[ymote]

ADR 0002 §6 (the system toolbox) as app peers' host-registered tools, for octos#2567 (UPCR-2026-035). Issue #62 records the registration rules. Everything is behind features that are off by default, so the shells, Rinx and CI's existing lines behave exactly as before.

Features

• octosense-app-peers/peer-tools: registration and routing in the broker.
• octosense-ai-host/toolbox-peers: turns that on and adds the toolbox (octos engine, model service, grants, host folder).

Both compile on main's octos pin (e6223efc after merging main, which brought #98 and serve --host-managed). The wire is JSON, so nothing needs #2567's types. CI now also tests and lints both features against the scripted kernel.

Registration (issue #62 rules)

• After every successful peer/prepare, the broker calls peer/tools/register. It does so on the same link that later opens contexts and starts turns. It sends the empty set when the app has no tools (Rinx).
• A lost link unbinds the peer, so the next request prepares and registers again before any turn.
• If registration fails, the peer stays unbound: no context opens, no turn starts, and availability() reports Failed with the reason.

Grant	Registered (risk)
none	empty set
research	workflow.run (read), workflow.fork (act), toolbox.search (read), toolbox.web_read (read)
crawl, with max_depth/max_pages > 0	toolbox.deep_crawl (read)

• octos deep_research, workflow.list and workflow.evaluate are not offered.
• Every tool is background: true, outward: false, confirm: host, so the kernel gates none of them.
• call_timeout_ms is 300 000 and max_result_bytes is 1 MiB.
• Names are toolbox.* because octos requires <app>.<tool>.

Calls

• Deduplication: a call runs once per (session, turn, tool_call_id, args_digest). A repeat gets the first result.
• Unregistered tools are refused as not_registered. The toolbox also checks the grant itself (not_granted).
• Cancel: peer/tool/cancel, the call's deadline, release or link loss fire the call's Cancel, then drop its future. A cancelled call is never answered.
• Routing:
  • workflow.* goes to Toolbox::handle_json.
  • search and web_read go to the same ResearchBackend (OctosResearch), narrowed by the octos Scope.
  • deep_crawl is a bounded same-site crawl over the new ResearchBackend::read_links. The octos reader keeps HTML for this.
• Worker thread: the toolbox's futures are not Send, so each app gets its own worker thread.
• Model calls: ModelHostClient runs the toolbox's ModelClient through ModelHost::complete. It uses the person's providers and the app's daily budget, in the same ledger at <apps root>/.host/model/ledger.json. Host callers may now send up to 256 KiB of input, because digests carry their articles' evidence. model.complete from an app stays at 32 KiB.
• Results: written to <apps root>/.host/toolbox/<app>/…, outside the app's jail. octosense_ai_host::{TOOLBOX_HOST_DIR, toolbox_root, toolbox_folder} is always compiled, so glance: resolve sys.digest sources from host-held digests (ADR 0002 M4) #87's digest_root can adopt it.
• Grants: read from the manifest's capabilities (research/crawl), with the scope in the top-level research object. This is App Hub mobile: native-feeling frame pacing on the phone #26's shape (merged). Temporary: only os.* apps get what they declare until the shells' App Hub pin includes mobile: native-feeling frame pacing on the phone #26 and the host reads its verified grant.

Tests

• Scripted kernel:
  • app-peers tests/peer_tools.rs (6): register right after prepare and before any turn, and again after a reconnect; a failed registration starts no turns; routing and deduplication; an unregistered tool is refused; cancel and timeout; release.
  • ai-host tests/toolbox_peers.rs (7): registration per grant; the os.*-only rule; workflow.run/fork/search/web_read with FakeModel and fixture research, with results in .host; scope refusals; a forged deep_crawl without crawl (not registered and refused); cancel; the budget through ModelHost.
• Toolbox: tests/peer.rs covers the crawl bounds. There are unit tests for the declarations and narrow_crawl. A parity test now covers octos's crawl_args too.
• Real octos kernel, built from #2567 at e270d039 and again at 31c51064:
  • app-peers real_kernel without the feature: 6/6 pass.
  • With peer-tools: 4 pass. They include a new real-turn host-tool call and "empty set means no tools", both over stdio and over the host-managed server (host-token WebSocket, after merging main). 4 are ignored, see below.
  • ai-host toolbox_real_kernel: the real kernel accepts the toolbox's declarations, a real turn calls toolbox_search and workflow_run (the result lands in .host), and deep_crawl is not offered without crawl.
• Checks run: cargo check --locked -p octosense with and without --features mobile-apps, check-shell-graph.sh -p octosense, and from phone/: cargo check --locked -p octosense-home --features mobile-apps. Tests pass for app-peers (plain, octos-core,ws, +peer-tools), toolbox (plain, live, octos-engine), ai-host (plain, octos-core,llm, toolbox-peers), the llm-service and the mail service. Clippy -D warnings is clean on the changed crates. Toolbox fmt passes.

Finding: a registered peer loses the system agent → peer flows

Under #2567, once a peer registers, kernel-internal continuations get no tools. With the empty set, even the peer's own turns get none: no ask_user_question, no shell.

So with the feature on, four ADR 0007 real-kernel flows fail (question/answer, second input, interrupt on close, approval refusal). The peer just echoes. These tests are #[ignore]d under peer-tools with that reason.

This is #2567's stated design, but it affects Rinx's assistant as soon as the feature is enabled. It needs a decision before the pin moves. Options include generic tools for Rinx's set, or the host driving those runs itself.

Unverified

• No shell run with the feature on: no hidden-window Rinx run (News M3: triggers (data events, digest times) and an unattended run #62 item 5) and no device.
• The live octos engine was not exercised through a peer. Only fixtures and the real kernel with fixture research were.

To turn it on

1. Merge octos#2567 and move the octos pin to include it (one pin move; Android liboctos.so from the same rev).
2. Resolve the finding above for Rinx, then run News M3: triggers (data events, digest times) and an unattended run #62's manual Rinx check.
3. Move the shells' App Hub pin to include App Hub mobile: native-feeling frame pacing on the phone #26 (research/crawl). Then read its verified AppPolicy::research and drop system_app_only.
4. glance: resolve sys.digest sources from host-held digests (ADR 0002 M4) #87 adopts octosense_ai_host::toolbox_root for digest_root.
5. Enable octosense-ai-host/toolbox-peers in the shells. ai-host: the octos host service for contained apps (Card runner) #106 can pass toolbox_peers::tools_for_manifest to hosted::launch_with_tools for contained apps.

No pin moved. Rinx is untouched. No local override was needed: #2567's kernel was built in a separate octos worktree only for the real-kernel tests.

🤖 Generated with Claude Code

[ymote]

Superseded by #151: #108's toolbox parts are ported onto main's octos#2567 shell side (#145's broker registration and host-tool relay), with the deep_research exclusion dropped and the toolbox gated on the #120 first-use consent. Leaving this open for reference; not closing it here.

🤖 Generated with Claude Code

[ymote]

Superseded by #151 (merged as 8855326), which rebuilt this on main's #145 registration and relay.