[ymote]

Docs only. I read everything from the code at f52620c5, which pins octos ae230ce0. Each file's English and Chinese versions carry the same content.

Changes, and why

README.md / README.zh-CN.md

• New section, "The system agent and the app agents":
  • The system agent's session, its pane, and its exact kernel tools (crates/kernel/src/system_tools.rs, session/tool_list/set, Kernel: the system agent's exact tool list on every start (ADR 0004 §12 step 4) #245).
  • The host tools on its session: agents.list and agents.ask (crates/shell/src/agents.rs), plus terminal.run.
  • A table of the apps that have an agent today (Rinx, News, Mail, Calendar), how each is declared, its tools, and its cards (crates/shell/src/apps.rs agent_apps, apps/*/bundle/tools.json).
  • A Mermaid sequence: system agent → peer/input → Mail's agent → mail.notify → relay → host service → glance.publish → notification → in-card chat (Mail and Calendar agents put cards on the glance screen; assistant pane and glance panel polish #267, L0 in-card chat (sys.chat) host side; AI-written text in the mail card #263).
  • What is not built yet: AGENT.md, skills, triggers.
• "Every path into octos" table: script apps are behind first-use consent, not "off". This matches contained_gate_from in crates/ai-host/src/lib.rs and docs(ai-services): contained apps' assistant is behind consent, not off #268.
• "Cards and questions":
  • The glance service: methods, caller identity, limits, and the toast → card window → panel flow (crates/shell/src/glance*.rs).
  • The in-card chat (sys.chat, crates/l0-chat).
• Layout: rows for crates/l0-chat and crates/toolbox, which was missing, plus Calendar and the calendar/news services. The ai-host, kernel and app-peers rows are made accurate.

AGENTS.md

• New "Where things live" rows: the system chat and agents.rs; agent_apps and host_tools; approvals; glance and l0-chat; an app agent's tools.json.
• The host services row now includes calendar, news and model.
• The app-peers row now has a real test command.
• Every new check command was run (results below).

Crate READMEs

• ai-host:
  • The model service and the octos host service for script apps are now covered: card.<app id>, the gate, the declared names (src/contained.rs).
  • Removed: "broker omits / does not set generic_tools" (broker.rs:1721 sets them).
  • Toolbox: the App Hub pin already includes mobile: native-feeling frame pacing on the phone #26, but the code keeps the os.* gate. toolbox-peers is on by default on the phone.
• app-peers:
  • The person's share_history lane is on main, no longer "in progress".
  • Script-app peers are covered.
  • The namespace id is the broker id (app/card.os.mail/…, FNV tag).
  • The approvals routing is corrected.
• kernel (en/zh):
  • The consumers are the system chat, every app-peers broker and AppCard. Removed: the stale "Rinx mini-app host uses rinx-mini-… sessions" paragraph.
  • The toolbox and cross-app grants are not wired outside tests.
  • agents.* host tools are covered.
  • Host tools need no peer token (octos#2657).
• toolbox:
  • Removed "The shells do not link it yet".
  • The pin has octos-research, so no override is needed. The test count is 83, the dossier template is added, and the fixture count is 23.
  • "How an app agent uses it" now matches peer::catalog.
• crates/l0-chat/README.md (new): ownership, roles, limits, storage, responders, tests.
• apps/README (en/zh) and apps/AGENTS.md:
  • Calendar (row, status, calendar service section).
  • Mail's mail.notify, contacts.rs and secrets folder.
  • An "App agents" section on declaring an agent, running it, its tools and its cards.
  • Layout, packing step, and the test table.
• apps/mail plan: the status line, which said "not started", now lists what feat(mail): email action card MVP on the desktop (fake data) #261/L0 in-card chat (sys.chat) host side; AI-written text in the mail card #263/Mail and Calendar agents put cards on the glance screen; assistant pane and glance panel polish #267 landed.

Checks run

• cargo test --locked -p octosense-l0-chat passed (8); its clippy is clean.
• -p octosense-mail-service -p octosense-calendar-service -p octosense-news-service -p octosense-llm-service passed.
• -p octosense-app-peers --features octos-core,ws passed.
• -p octosense-ai-host --features octos-core,llm passed.
• -p octosense-kernel passed.
• -p octosense-toolbox passed (83).
• From phone/: cargo test --locked --features mobile-apps -p octosense-shell with each of system_chat (63), host_tools (60), approvals (58) and glance (31) passed.
• From rom/: python3 -m unittest tests.test_no_local_paths is OK, and the tools/ unittests are OK. Every relative link resolves.
• Not run: tools/ci-local.sh.
• Unverified (marked as such in the docs): the "Trying it" desktop recipe for app agents.

Overlaps with open PRs

• Desktop: find the packaged octos kernel and refuse one of another revision #256 and Desktop release packages; a release workflow that keeps signing out of the build #257 (README*, kernel and ai-host READMEs): I left their hunks alone. That covers the kernel bullet, the octos dependency row, the "AI services (octos)" paragraph, the build lines, the CI table, kernel launch lines 40–49, and the ai-host Host fields. The paragraph at README "AI services (octos)" still says "each granted native app" and "approvals answered in that app". It is stale, but Desktop: find the packaged octos kernel and refuse one of another revision #256 edits the same line, so it is left for a follow-up.
• Photos: add AI-curated Memories and slideshows #266 and Maps: the search and route map draws makepad's pre-baked world map #165 (apps/README*): the News, Photos and Maps rows, the capability paragraph, the App Hub pin line and the "no CI" bullet are untouched. Photos: add AI-curated Memories and slideshows #266 already fixes the last two. I edited the Mail row and added a Calendar row. One unchanged line separates each of them from those PRs' lines.
• docs(ai-services): contained apps' assistant is behind consent, not off #268 (ai-services): not touched. This PR agrees with its consent wording.
• Not touched: docs/architecture.md, which Desktop: find the packaged octos kernel and refuse one of another revision #256 edits. Its "Worked example" still says there is no Calendar app and Mail has no tools.

Inconsistencies in the code (not fixed here)

• crates/shell/src/glance_chat.rs says Mail has no agent or tools.json. That is stale since Mail and Calendar agents put cards on the glance screen; assistant pane and glance panel polish #267.
• The MAX_QUEUED_INPUTS doc in crates/app-peers/src/host_tools.rs still says person messages share the queue.
• toolbox_peers.rs keeps an os.* gate marked "until App Hub mobile: native-feeling frame pacing on the phone #26", but mobile: native-feeling frame pacing on the phone #26 is in the pin.
• phone/Cargo.toml and desktop/Cargo.toml comment toolbox-peers as "off by default", yet the phone's default includes it.
• Script peers pass the peer id as the broker's app id. As a result the namespace is app/card.os.mail/… and the brief reads "the os.mail app".
• The manifest's agent.profile and model.needs are not read by the shell.
• SystemAgentTools::grant_toolbox and grant_cross_app are used only in tests.
• octosense-calendar-service tests are not in apps.yml.

Second commit: the person talks to an app's agent directly

• New README section (English and Chinese) "Talking to an app's agent yourself": the shell's "Ask " panel for every app with an agent (crates/shell/src/app_chat/), opened from the bar's button, Shift+F8 or the menu row "Ask this app's agent"; a card's in-card chat; the app's own UI. It covers consent, both lanes labelled, Send running in parallel with the system agent's lane, where questions go, and close/reopen.
• Stop: the panel's Stop stops only the person's own turn (interrupt_agent_lane). A running system agent turn has its own "Stop the system agent's task". The approval and question sheets' "Stop 's agent" stops both lanes (approvals::stop_agent). The README had said every Stop ends both lanes.
• Phone: the pane is drawn as a full-screen sheet, but no touch control opens it on main yet. All callers of ask_focused_app are the desktop bar, the menu row and Shift+F8.
• The two-lanes PNG still said "Two lanes: in progress" and "app UI or its cards". The Mermaid diagram is now shown inline and the PNG is removed.
• apps/README (English and Chinese): the same in short.

Checks: python3 -m unittest discover -s tools -p 'test_*.py' (90 OK), rom/tests/test_no_local_paths OK, and every relative link and anchor in the four edited files resolves.

Third commit: the README's drawings, redrawn (gpt-image-2)

Drawing	What changed
agents-processes.png	Adds the "Ask " panel, the person's turns from it and from in-card chat to the broker, and the app host services (mail, calendar, news) that the relay sends app tools to and that publish glance cards. The Mermaid text version gains the same nodes.
agents-two-lanes.png	Back, without the "Two lanes: in progress" badge. The person's arrow is now labelled "the shell's Ask panel, a card's chat or the app's own UI".
agents-tool-call.png	Checks inside each branch and the confirm: app hand-off through the router, as in the Mermaid. The example is calendar.remove_event (destructive, confirm: host) instead of mail.send, which no app has.
agents-card-flow.png (new)	The system agent → Mail's agent → mail.notify → glance card → in-card chat sequence. Its Mermaid is now a collapsed text version, like the others.

Every label was checked against the Mermaid and the code. One processes draft had wrong arrows and was redrawn. The images are quantized to 128 colours, about 460 KB each.

🤖 Generated with Claude Code