docs: app agents, the system agent and in-card chat as on 2026-10-01

AGENTS.md

@@ -54,7 +54,15 @@ patch around it here.
   answers `no service answers "…" on this device`. `llm` is for system apps
   only. Never put a model key in an app. Read
   [docs/AI-SERVICES.md](docs/AI-SERVICES.md) before adding one, and report
-  such a feature as not verified on a device.
+  such a feature as not verified on a device. An app's own agent
+  (`"agent": {…, "tools": ["ask_user_question"]}`) is checked here only by
+  `hub check`. In the shells the person talks to it directly in the
+  "Ask <app>" panel the shell draws for every app with an agent, so the app
+  need not draw a chat of its own (desktop; the phone has no entry to the
+  panel yet). A store app's `tools.json` tools do not run in any shell yet,
+  so no screen may depend on its agent calling them. L0 cards that use
+  `sys.chat`, `sys.digest` or `model-copy` text need a newer runtime than
+  this repository pins: report them as not verified here.
 - **Only needed capabilities.** Each capability maps to something a screen
   does ([docs/CAPABILITIES.md](docs/CAPABILITIES.md)). Remove what is unused.
 - **No dummy screenshots.** Screenshots are captures of the real app in a real
@@ -64,8 +72,10 @@ patch around it here.
   for you; after signing, any edit needs stamp and sign again (human).
 - **Keep the bundle clean.** Only `manifest.json`, `listing.json`, the entry,
   artwork and screenshots go in `bundle/` (plus `tools.json`, `AGENT.md` and
-  `skills/` for an app that declares its own agent; the shells give it a peer
-  and its tools, but do not install `AGENT.md` or skills yet:
+  `skills/` for an app that declares its own agent; the shells give it a peer,
+  `ask_user_question` and read access to its account folder, and register
+  its tools (which run only for system apps today), but do not install
+  `AGENT.md` or skills yet:
   [docs/AI-SERVICES.md](docs/AI-SERVICES.md#an-apps-own-agent)). Notes, keys, logs, review packets
   and `.local-state/` stay out.
 - **Run headless.** Start apps with `tools/octo run … --hidden` (Makepad's

README.md

@@ -240,18 +240,22 @@ release), `capabilities` (the permissions it asks for), `network.hosts`
 (bare host names, with `net`), and `integrity.bundle_blake3`, written by
 `hub stamp` (plus a signature after `hub sign-manifest`). Optional requests
 (`storage.max_bytes`, `compute.*`, `agent`) are clamped to the host's
-ceilings; `hub check` prints the resulting `grants:` line.
+ceilings; `hub check` prints the resulting `grants:` line. `storage` may
+also say whether the app keeps accounts and what its agent may read
+(`storage.accounts`, `storage.agent_workspace`). The id may not be, or end
+in, a name the host reserves (`terminal`, `rinx`, `system`, `toolbox`, …).
 
 **Capabilities** form a closed list defined by the App Hub: `storage`, `net`,
 `images`, `web`, `camera`, `microphone`, `library`, `location`, `mail`,
-`llm`, `news`, `glance`, `model`, `prompt`, `ledger.read`, `clipboard`, plus 49 exact
+`llm`, `news`, `glance`, `model`, `research`, `crawl`, `prompt`, `ledger.read`, `clipboard`, plus 49 exact
 host-service names (four `octos.*` for the device's assistant, 45 `matrix.*`
 for Rinx). Not requested means not granted,
 and the store shows the person one plain-language line per capability before
 install. Ask for the least the app needs. What each unlocks, which have no
 working path yet (`prompt`, `ledger.read`, `clipboard`) and which only a
-system app can use (`llm`): [docs/CAPABILITIES.md](docs/CAPABILITIES.md).
-What the assistant capabilities do today (nothing yet, in OctoSense):
+system app can use (`llm`, `news`, and for now `research` and `crawl`):
+[docs/CAPABILITIES.md](docs/CAPABILITIES.md). What the assistant
+capabilities and an app's own agent do today in OctoSense:
 [docs/AI-SERVICES.md](docs/AI-SERVICES.md).
 
 **`listing.json`**: subtitle, description, category, keywords, icon,
@@ -304,16 +308,27 @@ lists every check.
 ## AI in your app
 
 OctoSense runs one octos agent kernel per shell, configured by the person in
-the AI providers system app; keys never reach an app. **A contained app
-cannot use it yet**: the gate accepts the four `octos.*` capabilities, but no
-OctoSense shell serves them to apps, and `card-host` serves no host services.
-`llm` is provider management for system apps only, and the one-shot `model`
-capability (App Hub #24) has no service in any shell yet. An app's own agent
-(`tools.json`, `AGENT.md`, skills, triggers) is admitted by App Hub `main` and
-planned in OctoSense's ADR 0002, but nothing runs it yet. Build apps that are
-complete without AI, and read [docs/AI-SERVICES.md](docs/AI-SERVICES.md)
-before adding an AI feature: the exact names, a verified call that handles
-"unavailable", what the person sees, the errors, and the planned route.
+the AI providers system app; keys never reach an app. On it run the
+**system agent** (the shell's own assistant, which the person talks to in
+the system chat) and one **app agent** per app that declares one, each on
+its own host-owned peer. As of 2026-10-01, on OctoSense `main`
+([docs/AI-SERVICES.md](docs/AI-SERVICES.md) has the details and sources):
+
+| An app can | How | In `card-host` |
+| --- | --- | --- |
+| Make a one-shot, schema-checked model call | `model` capability, `host.request("model.complete", …)`, within a daily budget | `no service answers "model"` |
+| Talk to the assistant from its own screens | the four `octos.*` capabilities, once the person allows the app's agent on a first-use sheet | `no service answers "octos"` |
+| Have its own agent, which the person talks to directly (the shell's "Ask <app>" panel, drawn for every app with an agent; an in-card chat; the app's own screens) and the system agent can hand work to | an `agent` block (`"tools": ["ask_user_question"]`), optional `tools.json`; the agent reads the app's account folder (`accounts/device/`) | checked by `hub check` only |
+| Publish cards to the glance screen, with an in-card chat its agent answers and model-written text marked AI-written | `glance` capability, `glance.publish` (L0 `sys.chat`, `model-copy`) | `no service answers "glance"`; this repository's runtime predates `sys.chat` |
+
+Still **coming**: a store app's own `tools.json` tools running (today only
+system apps' host-service tools run), the host choosing the agent's model
+from `needs`, triggers and background runs, installing `AGENT.md` and
+skills, and the system toolbox for store apps. `llm` is provider management
+for system apps only. Build apps that are complete without AI, and read
+[docs/AI-SERVICES.md](docs/AI-SERVICES.md) before adding an AI feature: the
+exact names, a verified call that handles "unavailable", what the person
+sees, the errors, and what is planned.
 
 ## Running an app
 
@@ -452,7 +467,7 @@ Limits, stated plainly:
 | [docs/SCRIPT-API.md](docs/SCRIPT-API.md) | The Splash language and every API a contained app may call |
 | [docs/CAPABILITIES.md](docs/CAPABILITIES.md) | Each capability: what it unlocks, what the person sees, the rules |
 | [docs/HOST-SERVICES.md](docs/HOST-SERVICES.md) | `host.request`, sheets, "secrets are the host's", adding a service |
-| [docs/AI-SERVICES.md](docs/AI-SERVICES.md) ([简体中文](docs/AI-SERVICES.zh-CN.md)) | OctoSense's assistant (octos): what an app can use today, a verified example, what is planned (an app's own agent, its tools, the system toolbox, glance cards, `sys.digest`), with a dated status table |
+| [docs/AI-SERVICES.md](docs/AI-SERVICES.md) ([简体中文](docs/AI-SERVICES.zh-CN.md)) | OctoSense's assistant (octos): the system agent and app agents, what an app can use today, a verified example, an app's own agent and its tools, the system toolbox, glance cards, `sys.digest`, AI-written text and in-card chat (`sys.chat`), with a dated status table |
 | [docs/PUBLISHING.md](docs/PUBLISHING.md) | Publishing to the App Hub, with verified outputs and the checklist |
 | [docs/GLOSSARY.md](docs/GLOSSARY.md) | One meaning per term |
 | [docs/NATIVE-WORKSPACE.md](docs/NATIVE-WORKSPACE.md), [docs/l0/](docs/l0/) | Sibling-source setup for the native runtime; L0 card examples |

README.zh-CN.md

@@ -221,14 +221,16 @@ my-app/                     the app's own git repository
 `capabilities`（申请的权限）、`network.hosts`（纯主机名，需配合 `net`），以及由
 `hub stamp` 写入的 `integrity.bundle_blake3`（`hub sign-manifest` 之后还有签名）。可选的
 申请项（`storage.max_bytes`、`compute.*`、`agent`）会被限制在宿主的上限以内；
-`hub check` 输出的 `grants:` 行就是实际授予的结果。
+`hub check` 输出的 `grants:` 行就是实际授予的结果。`storage` 还可以声明应用是否按账户
+保存数据、它的 Agent 能读什么（`storage.accounts`、`storage.agent_workspace`）。应用 id
+不能是、也不能以宿主保留的名字结尾（`terminal`、`rinx`、`system`、`toolbox` 等）。
 
 **Capabilities（权限）** 是 App Hub 定义的封闭列表：`storage`、`net`、`images`、`web`、
-`camera`、`microphone`、`library`、`location`、`mail`、`llm`、`news`、`glance`、`model`、`prompt`、`ledger.read`、
+`camera`、`microphone`、`library`、`location`、`mail`、`llm`、`news`、`glance`、`model`、`research`、`crawl`、`prompt`、`ledger.read`、
 `clipboard`，另有 49 个精确的宿主服务名（设备助手的 4 个 `octos.*`，Rinx 的 45 个 `matrix.*`）。未申请即不授予；安装前商店会为每项权限向用户显示一行通俗说明。只申请应用真正
 需要的。每项权限解锁什么、哪些目前还没有可用路径（`prompt`、`ledger.read`、`clipboard`）、
-哪些只有系统应用能用（`llm`）：[docs/CAPABILITIES.md](docs/CAPABILITIES.md)。
-助手相关权限目前能做什么（在 OctoSense 中暂时什么也做不了）：
+哪些只有系统应用能用（`llm`、`news`，以及暂时的 `research` 和 `crawl`）：[docs/CAPABILITIES.md](docs/CAPABILITIES.md)。
+助手相关权限和应用自己的 Agent 目前在 OctoSense 中能做什么：
 [docs/AI-SERVICES.zh-CN.md](docs/AI-SERVICES.zh-CN.md)。
 
 **`listing.json`**：副标题、描述、类别、关键词、图标、截图、实际测试过的平台、年龄分级，
@@ -269,14 +271,24 @@ my-app/                     the app's own git repository
 ## 应用中的 AI
 
 OctoSense 每个 Shell 运行一个 octos Agent 内核，由用户在系统应用 AI providers 中配置；
-密钥永远不会到达应用。**隔离运行的应用目前还不能使用它**：准入检查接受 4 个 `octos.*`
-权限，但没有任何 OctoSense Shell 向应用提供这些服务，`card-host` 也不提供任何宿主服务。
-`llm` 是只供系统应用使用的模型提供方管理服务，一次性调用模型的 `model` 权限（App Hub #24）
-目前也还没有任何 Shell 提供服务。应用自己的 Agent（`tools.json`、`AGENT.md`、
-skills、触发器）已被 App Hub `main` 接受，并在 OctoSense ADR 0002 中规划，但目前没有任何
-地方运行它。请把应用做成不依赖 AI 也完整可用；添加 AI 功能之前先读
+密钥永远不会到达应用。内核上运行着**系统 Agent**（Shell 自己的助手，用户在系统对话中与它交谈），
+以及每个声明了 Agent 的应用各自的**应用 Agent**，每个都在宿主持有的独立 peer 上。
+截至 2026-10-01，在 OctoSense `main` 上（细节与出处见
+[docs/AI-SERVICES.zh-CN.md](docs/AI-SERVICES.zh-CN.md)）：
+
+| 应用可以 | 方式 | 在 `card-host` 中 |
+| --- | --- | --- |
+| 进行一次性、按 schema 校验的模型调用 | `model` 权限，`host.request("model.complete", …)`，受每日预算限制 | `no service answers "model"` |
+| 在自己的界面上与助手对话 | 4 个 `octos.*` 权限，用户在首次使用的确认页上允许该应用的 Agent 之后 | `no service answers "octos"` |
+| 拥有自己的 Agent：用户可以直接与它对话（Shell 为每个有 Agent 的应用绘制的“Ask <app>”面板、卡片内对话、应用自己的界面），系统 Agent 也可以把任务交给它 | `agent` 块（`"tools": ["ask_user_question"]`），可选 `tools.json`；该 Agent 可以读取应用的账户文件夹（`accounts/device/`） | 只能用 `hub check` 检查 |
+| 向 glance 屏幕发布卡片，卡片内可与应用 Agent 对话，模型写的文字标为 AI 撰写 | `glance` 权限，`glance.publish`（L0 `sys.chat`、`model-copy`） | `no service answers "glance"`；本仓库锁定的运行时早于 `sys.chat` |
+
+仍在**规划中**：商店应用自己的 `tools.json` 工具真正运行（目前只有系统应用的 host-service
+工具能运行）、宿主根据 `needs` 为 Agent 选择模型、触发器与后台运行、安装 `AGENT.md` 和
+skills，以及面向商店应用的系统工具箱。`llm` 是只供系统应用使用的模型提供方管理服务。
+请把应用做成不依赖 AI 也完整可用；添加 AI 功能之前先读
 [docs/AI-SERVICES.zh-CN.md](docs/AI-SERVICES.zh-CN.md)：准确的名称、一个经过验证并处理
-“不可用”状态的调用、用户看到什么、错误信息，以及规划中的路线。
+“不可用”状态的调用、用户看到什么、错误信息，以及规划中的内容。
 
 ## 运行应用
 
@@ -388,7 +400,7 @@ curl -s 127.0.0.1:8161/quit; curl -s 127.0.0.1:8162/quit
 | [docs/SCRIPT-API.md](docs/SCRIPT-API.md) | Splash 语言及隔离应用可调用的全部 API |
 | [docs/CAPABILITIES.md](docs/CAPABILITIES.md) | 每项权限：解锁什么、用户看到什么、规则 |
 | [docs/HOST-SERVICES.md](docs/HOST-SERVICES.md) | `host.request`、面板、“密钥归宿主所有”、新增宿主服务 |
-| [docs/AI-SERVICES.zh-CN.md](docs/AI-SERVICES.zh-CN.md)（[English](docs/AI-SERVICES.md)） | OctoSense 的助手（octos）：应用目前能用什么、经过验证的示例、规划中的内容（应用自己的 Agent、它的工具、系统工具箱、glance 卡片、`sys.digest`），附带日期的状态表 |
+| [docs/AI-SERVICES.zh-CN.md](docs/AI-SERVICES.zh-CN.md)（[English](docs/AI-SERVICES.md)） | OctoSense 的助手（octos）：系统 Agent 与应用 Agent、应用目前能用什么、经过验证的示例、应用自己的 Agent 及其工具、系统工具箱、glance 卡片、`sys.digest`、AI 撰写的文字与卡片内对话（`sys.chat`），附带日期的状态表 |
 | [docs/PUBLISHING.md](docs/PUBLISHING.md) | 发布到 App Hub，附经过验证的输出和检查清单 |
 | [docs/GLOSSARY.md](docs/GLOSSARY.md) | 每个术语只有一个含义 |
 | [docs/NATIVE-WORKSPACE.md](docs/NATIVE-WORKSPACE.md)、[docs/l0/](docs/l0/) | 原生运行时的兄弟仓库配置；L0 卡片示例 |