@turmind/halo 1.5.9 → 1.5.11

package/bundled-docs/dev/desktop-packaging.md

@@ -431,6 +431,20 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
     busy (recording) or unsaved, so it doesn't fire on an ordinary close or a
     workspace switch.
 
+- **Chat screenshot button (`window.haloCapture.screenshot` → IPC
+  `halo:capture-screenshot`) — ⚠ not yet verified on a real Mac / Windows**
+  (only the main-side handler was exercised, under Electron on Linux/Xvfb).
+  mac / win only (`CAPTURE_SUPPORTED`; else `null`). Grabs the display the
+  requesting window is on (`screen.getDisplayMatching(win.getBounds())`) via
+  `desktopCapturer` `types: ['screen']` at `size × scaleFactor`, matched on
+  `display_id` (single source → used as is); returns base64 JPEG 92, `{ error:
+  'permission' }` on an empty thumbnail (macOS Screen Recording not granted),
+  `null` after 3 mostly-black tries (`isMostlyBlack`, so a near-black desktop
+  also fails). The crop UI lives in the admin, not the shell. An older shell
+  without `screenshot` makes the admin fall back to `getDisplayMedia` (the
+  picker above). Worth checking on real hardware: the permission path, Retina
+  (`scaleFactor` > 1), multi-monitor.
+
 - **Cross-staging needs a full restage — auto-fast skips the native fixup.**
   After editing `stage-runtime.mjs`, or any time you cross-stage a target whose
   `node_modules` differs from what's on disk, run with `HALO_STAGE_FULL=1`. The

package/bundled-docs/dev/env.md

@@ -84,7 +84,7 @@ Three config file types, precedence **env vars > config.yaml / settings.yaml > c
 
 `init.ts` seeds these on first run with a per-category policy. Refresh trigger: `halo setup` always re-runs the seed, and the startup check re-runs it automatically when `~/.halo/global/.template-version` is behind the bundled `TEMPLATE_VERSION` — on server start and at the start of `halo cli` / `halo tui` (`init.ts` `refreshTemplatesIfOutdated`, called from `index.ts` and the CLI's `harness.ts` `initRuntime`; a never-seeded home is left to `halo setup`).
 
-- **Always overwritten** (platform-owned, refreshed when the template version moves): `~/.halo/global/{prompts,models,docs}/`, `INSTRUCTIONS.md`, the built-in agent ids (`default`, `executor`, `deep-executor`, `goal`, `__evo_agent__`, `__score__`, `__apply_agent__`), built-in skill ids (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `aws-knowledge`, `web-search`, `self`, `halo`, `extension`).
+- **Always overwritten** (platform-owned, refreshed when the template version moves): `~/.halo/global/{prompts,models,docs}/`, `INSTRUCTIONS.md`, the built-in agent ids (`default`, `executor`, `deep-executor`, `goal`, `__evo_agent__`, `__score__`, `__apply_agent__`), built-in skill ids (`agent`, `skill`, `workspace`, `cron`, `send-file`, `aws-knowledge`, `web-search`, `self`, `halo`, `extension`).
 - **Built-in agents** keep the user's `model:` and `context:` blocks on overwrite — the admin UI lets users change which model an agent uses and its context limits, and that choice survives upgrades.
 - **Optional skills** (`tavily-web-search`) install only when picked via `halo setup`; the opt-in list is `~/.halo/global/.installed-optional-skills`. Picked skills are force-overwritten alongside the always-overwritten set.
 - **Skill params in `halo setup`**: a newly picked optional skill walks all its declared params; for built-in skills setup asks only the `secret: true` ones (`listRequiredSkillsWithSecrets`, `setup-providers.ts`) — plain params such as `extension.params.hub_repo` / `web-search.params.fast_region` are set in Settings → Skills only.
@@ -99,7 +99,7 @@ Source: `packages/server/src/config.ts`
 |---|---|---|---|
 | `HALO_PORT` | `9527` | `config.yaml server.port` | Hono listen port |
 | `HALO_PASSWORD` | (none) | `config.yaml server.password` (scrypt hash) | Plaintext login password. When set, takes precedence over the stored hash and bypasses scrypt entirely — intended for Docker / systemd / CI. It also satisfies the **startup gate**: the server refuses to boot with no password configured, and env plaintext counts as a first-class credential there, so an env-only deployment (`halo setup -y && HALO_PASSWORD=... halo server start`, no stored hash) boots fine. The hash is set by `halo setup` for interactive installs. |
-| `HALO_CORS_ORIGINS` | empty (reflect any origin) | `config.yaml server.cors_origins` | CORS allowlist (comma-separated). Empty = reflect any incoming Origin so credentials work cross-origin. Set explicit list to enforce strict CORS. |
+| `HALO_CORS_ORIGINS` | empty (reflect any origin) | `config.yaml server.cors_origins` | CORS allowlist (comma-separated, exact origins). Empty = reflect any incoming Origin **without** `Allow-Credentials` (header-token callers like `x-token` work; cookie-carrying cross-origin requests don't). A non-empty list = only those origins get CORS, with `Allow-Credentials` (e.g. a frontend behind an SSO that must send its cookie). Read at startup — a change needs a restart. Prefer a same-origin reverse proxy over listing origins (see `halo-city/README.md`). |
 | `HALO_FRONTEND_DIR` | auto (bundled `admin-out`, else `packages/admin/out`) | — | Static frontend dir; resolved against the current working directory |
 | `HALO_MAX_CONTEXT_TOKENS` | `272000` | — | Model max context |
 | `HALO_SHELL_TIMEOUT` | `120000` | `config.yaml timeout.shell_exec` | Shell command timeout (ms) |

package/bundled-docs/dev/tools.md

@@ -202,7 +202,7 @@ Per-channel defaults: every channel session (Web, Telegram, Slack, Feishu, WeCom
 `grep` reads the first 512 bytes of each file looking for a null byte and skips binaries (`glob` matches paths only and never opens files).
 
 ### Tool result budget
-The orchestrator truncates tool results over 8000 chars and appends a `[Content truncated]` hint telling the agent to use `grep` for a targeted search. `activate_skill` results are exempt — a SKILL.md body is instructions, not data, and the built-in acp / cron / self skills exceed 8K.
+The orchestrator truncates tool results over 8000 chars and appends a `[Content truncated]` hint telling the agent to use `grep` for a targeted search. `activate_skill` results are exempt — a SKILL.md body is instructions, not data, and the built-in cron / self skills exceed 8K.
 
 ## Session tools
 
@@ -284,13 +284,13 @@ Send a message to another session. Idle = immediate run, busy = queued + soft in
 | `target_session_id` | string | yes | Target session ID |
 | `message` | string | yes | Message content |
 
-**Busy = soft interrupt (merge-answer parity)**: when the target is busy, `query_session` enqueues the message **and** requests a soft interrupt (same as a user message arriving mid-turn) — the in-flight turn unwinds after its current tool, then every message that landed alongside it drains as **one merged turn**. So a sub-agent asked two questions while busy answers them **together**, not one-by-one — matching how root folds two user messages. No message is dropped. (Before 0.1.4 a busy `query_session` was pure no-interrupt enqueue, which made sub-agents reply one question at a time.)
+**Busy = soft interrupt (merge-answer parity)**: when the target is busy, `query_session` enqueues the message **and** requests a soft interrupt (same as a user message arriving mid-turn) — the in-flight turn finishes its current batch of tool calls and unwinds before its next model call, then every message that landed alongside it drains as **one merged turn**. So a sub-agent asked two questions while busy answers them **together**, not one-by-one — matching how root folds two user messages. No message is dropped. (Before 0.1.4 a busy `query_session` was pure no-interrupt enqueue, which made sub-agents reply one question at a time.)
 
 **Queue cap (backpressure)**: when the target is busy, `query_session` is rejected with `{"code": 1, "error": "...message queue is full (N/max)..."}` once the target's queued **agent-sourced** messages reach `session.maxQueueSize` (default 256, settings `general.session.max_queue_size`). The cap counts **only agent→agent entries** — user messages share the same queue but are immune to backpressure (a human can't hand-type up to the cap, and counting them would let user chatter consume the agents' budget). `interrupt_session` is a deliberate action and bypasses the cap entirely.
 
 ### interrupt_session
 
-Equivalent to `query_session` **plus an immediate abort** of the in-flight turn. The message is enqueued and traced right away (exactly like `query_session`); aborting then makes the queue drain **now** rather than after the current turn finishes, so the enqueued message is folded into the very next merged turn. The abort is hard — it propagates to `shell_exec` and SIGTERMs a command mid-execution (contrast the soft interrupt `query_session` and a busy user message trigger, which wait for the current `tool_result`). For a **compound** command (`sleep 60 && …`) under `full` access, the kill reaches the real worker because the command runs as a **process-group leader** and the whole group is signalled — before 0.1.4 the abort only hit the wrapping `/bin/sh`, leaving the worker to orphan and run to completion (which made `interrupt_session` look like it didn't interrupt). See [session.md → Process-group kill on abort](../design/session.md#process-group-kill-on-abort). Conversation history is preserved (repaired, not discarded), and `interrupt_session` bypasses the `query_session` queue cap.
+Equivalent to `query_session` **plus an immediate abort** of the in-flight turn. The message is enqueued and traced right away (exactly like `query_session`); aborting then makes the queue drain **now** rather than after the current turn finishes, so the enqueued message is folded into the very next merged turn. The abort is hard — it propagates to `shell_exec` and SIGTERMs a command mid-execution (contrast the soft interrupt `query_session` and a busy user message trigger, which wait for the current tool batch to finish). Of a cut parallel batch, the call that was running gets the do-not-retry `[tool execution interrupted …]` result and the calls that never started get a "was not run … safe to re-issue" result. For a **compound** command (`sleep 60 && …`) under `full` access, the kill reaches the real worker because the command runs as a **process-group leader** and the whole group is signalled — before 0.1.4 the abort only hit the wrapping `/bin/sh`, leaving the worker to orphan and run to completion (which made `interrupt_session` look like it didn't interrupt). See [session.md → Process-group kill on abort](../design/session.md#process-group-kill-on-abort). Conversation history is preserved (repaired, not discarded), and `interrupt_session` bypasses the `query_session` queue cap.
 
 | Arg | Type | Required | Description |
 |---|---|---|---|
@@ -299,7 +299,7 @@ Equivalent to `query_session` **plus an immediate abort** of the in-flight turn.
 
 ### stop_session
 
-Abort the current task of a running session. Any queued messages are **not** dropped — they are folded into the conversation history before the abort, so nothing said while the session was busy is lost. The session stays usable — later `query_session` calls continue the conversation.
+Abort the current task of a running session. Any queued messages are **not** dropped — they are folded into the conversation history before the abort, so nothing said while the session was busy is lost. The session stays usable — later `query_session` calls continue the conversation. Refused with `{"code": 1}` (no stop) when `session_id` is the caller's own session or one of its ancestors — the stop would wait on the very turn making the call; to end its own work an agent just finishes its turn.
 
 | Arg | Type | Required | Description |
 |---|---|---|---|
@@ -307,7 +307,7 @@ Abort the current task of a running session. Any queued messages are **not** dro
 
 ### archive_session
 
-**Cascade** archive a session and every descendant. Aborts running work, clears queued messages. Archived sessions disappear from `session_list` and cannot be reached by `query_session`. Only use it when the whole subtree is done.
+**Cascade** archive a session and every descendant. Aborts running work, clears queued messages. Archived sessions disappear from `session_list` and cannot be reached by `query_session`. Only use it when the whole subtree is done. Refused with `{"code": 1}` (nothing archived) when `session_id` is the caller's own session or one of its ancestors, for the same reason as `stop_session`.
 
 | Arg | Type | Required | Description |
 |---|---|---|---|
@@ -372,7 +372,7 @@ Cross-**workspace** dispatch on the same server: a "secretary" agent in workspac
 
 ### relay_send
 
-Dispatch a message to a session in another workspace. Creates the session if `session_id` does not exist there (root session, agent `agent_id` or the target workspace's default agent, description `Relay: <first 60 chars>`), stamps the target row's `reply_to` with `{ workspace: <caller ws>, sessionId: <caller session> }`, appends the raw message to the target's UI transcript and sends it prefixed `[channel: relay | from: <caller ws>]\n\n<message>` — so the target agent knows the message came from another workspace's agent, not the admin UI, and doesn't echo the tag. Busy target → the message is **queued + soft interrupt** (same as `query_session` / a user message mid-turn: the current tool finishes, then the queue drains as one merged turn), so follow-ups and corrections ride the same tool. Returns immediately.
+Dispatch a message to a session in another workspace. Creates the session if `session_id` does not exist there (root session, agent `agent_id` or the target workspace's default agent, description `Relay: <first 60 chars>`), stamps the target row's `reply_to` with `{ workspace: <caller ws>, sessionId: <caller session> }`, appends the raw message to the target's UI transcript and sends it prefixed `[channel: relay | from: <caller ws>]\n\n<message>` — so the target agent knows the message came from another workspace's agent, not the admin UI, and doesn't echo the tag. Busy target → the message is **queued + soft interrupt** (same as `query_session` / a user message mid-turn: the current batch of tool calls finishes, then the queue drains as one merged turn), so follow-ups and corrections ride the same tool. Returns immediately. When `workspace` is the caller's own workspace, a `session_id` naming the caller itself or one of its ancestors is refused (`{"code": 1}`, nothing sent, `reply_to` untouched) — its report would come back into the caller's own tree; other sessions in the same workspace are fine.
 
 | Arg | Type | Required | Description |
 |---|---|---|---|
@@ -405,7 +405,7 @@ Body capped at `limits.autoReportMax` (head-kept) with a `[Report truncated: N c
 
 ### relay_interrupt
 
-`relay_send` **plus a hard abort** of the target's in-flight turn — `interrupt_session` semantics across workspaces: the message is enqueued first, and if the target was busy (`state === 'queued'`) its turn is aborted immediately (propagates to `shell_exec`, SIGTERMs the process group) so the drain picks the message up now instead of after the current step. Enqueue-then-abort order matters: the finally never sees an empty queue and so never fires a spurious relay report. Idle target → behaves exactly like `relay_send` (`interrupted: false`). Unlike `relay_send` it does **not** create a missing session (`{"code": 1, "error": "session not found"}`) — there is nothing to interrupt. Use it when the target is heading the wrong way and waiting for its current step is not acceptable; for ordinary follow-ups prefer `relay_send`.
+`relay_send` **plus a hard abort** of the target's in-flight turn — `interrupt_session` semantics across workspaces: the message is enqueued first, and if the target was busy (`state === 'queued'`) its turn is aborted immediately (propagates to `shell_exec`, SIGTERMs the process group) so the drain picks the message up now instead of after the current step. Enqueue-then-abort order matters: the finally never sees an empty queue and so never fires a spurious relay report. Idle target → behaves exactly like `relay_send` (`interrupted: false`). Unlike `relay_send` it does **not** create a missing session (`{"code": 1, "error": "session not found"}`) — there is nothing to interrupt. Use it when the target is heading the wrong way and waiting for its current step is not acceptable; for ordinary follow-ups prefer `relay_send`. Same own-workspace self / ancestor refusal as `relay_send`.
 
 | Arg | Type | Required | Description |
 |---|---|---|---|
@@ -417,7 +417,7 @@ Returns `{ "code": 0, "workspace", "session_id", "state": "running" | "queued",
 
 ### relay_stop
 
-Cascades `stopSession` on the target session and its sub-agents. If the target was mid-turn the caller still receives a relay report describing where it was cut off (the stop ends the turn → finally → `deliverRelayReport`, with the partial trace as body).
+Cascades `stopSession` on the target session and its sub-agents. If the target was mid-turn the caller still receives a relay report describing where it was cut off (the stop ends the turn → finally → `deliverRelayReport`, with the partial trace as body). When `workspace` is the caller's own workspace, a `session_id` naming the caller itself or one of its ancestors is refused (`{"code": 1}`, no stop) — same rule as `stop_session`; the same id in another workspace is a different session and stops normally.
 
 | Arg | Type | Required | Description |
 |---|---|---|---|

package/bundled-docs/guide/README.md

@@ -22,7 +22,7 @@ Aimed at Halo end-users. Pick the doc that matches your situation.
 - [Feishu / Lark](channels/feishu.md) — long-connect with appId + appSecret
 - [WeCom](channels/wecom.md) — 企业微信 intelligent bot, long-connect with Bot ID + Secret
 - [WeChat](channels/wechat.md) — QR-scan iLink bot
-- [ACP](channels/acp.md) — Claude Code or other ACP clients driving a remote halo
+- [ACP](channels/acp.md) — Zed / JetBrains or other ACP clients driving a remote halo
 
 ## Related docs
 

package/bundled-docs/guide/channels/README.md

@@ -12,7 +12,7 @@ This folder has one onboarding guide per channel. Pick the one you want and foll
 | [Feishu / Lark](feishu.md) | Chinese enterprise teams | Feishu open-platform App (`appId` + `appSecret`) + long connection | WebSocket (long-connect) |
 | [WeCom](wecom.md) | Chinese enterprise teams on 企业微信 (single chat + groups) | 智能机器人 (Bot ID + Secret) + long connection | WebSocket (long-connect) |
 | [WeChat](wechat.md) | China-side personal use; mobile-first | iLink-style bot, login by scanning a QR | Long-poll |
-| [ACP](acp.md) | Claude Code (or other ACP clients) driving a remote halo | Web token + adapter CLI | JSON-RPC over stdio |
+| [ACP](acp.md) | An ACP-speaking IDE (Zed / JetBrains / …) driving a remote halo | Web token + adapter CLI | JSON-RPC over stdio |
 
 ## How channels are wired
 
@@ -28,7 +28,7 @@ This folder has one onboarding guide per channel. Pick the one you want and foll
                           SessionManager (per workspace)
 ```
 
-Each channel handler is a thin adapter between its native protocol and halo's `SessionManager`. Slash commands (`/session` `/agent` `/skill` `/workspace` `/cron` `/acp` `/evo` `/extension` `/help`) are shared across all of them — see `channels/shared/commands.ts`.
+Each channel handler is a thin adapter between its native protocol and halo's `SessionManager`. Slash commands (`/session` `/agent` `/skill` `/workspace` `/cron` `/evo` `/extension` `/help`) are shared across all of them — see `channels/shared/commands.ts`.
 
 The ACP adapter is **not** a channel — it's a stdio bridge that translates ACP JSON-RPC into the web channel's HTTP+SSE. Counted here only because users go through the same "set up an account, get a token" flow.
 
@@ -62,7 +62,7 @@ When in doubt start at `readonly` and raise it later. The setting is on the **ac
 
 - Already know which channel you want → click the row above
 - New to halo and just want to chat in a browser → [Web](web.md)
-- Want to run halo from your IDE (Claude Code etc.) → [ACP](acp.md)
+- Want to run halo from your IDE (Zed / JetBrains) → [ACP](acp.md)
 - Setting up a team workspace → [Slack](slack.md), [Feishu](feishu.md) or [WeCom](wecom.md)
 
 For the design rationale and protocol details (not user-facing), see [docs/design/](../../design/) — one file per channel: `web.md`, `telegram.md`, `slack.md`, `feishu.md`, `wecom.md`, `wechat.md`.

package/bundled-docs/guide/channels/acp.md

@@ -1,6 +1,6 @@
 # ACP (Agent Client Protocol)
 
-Drive a halo server from any [ACP](https://github.com/zed-industries/agent-client-protocol)-speaking client. The most common use is **Claude Code on a developer's laptop, talking to a halo agent on EC2** — but any ACP client works.
+Drive a halo server from any [ACP](https://github.com/zed-industries/agent-client-protocol)-speaking client. The most common use is **an ACP-capable editor (Zed, a JetBrains IDE) on a developer's laptop, talking to a halo agent on EC2** — but any ACP client works.
 
 ACP isn't a channel of its own. The `halo acp` command is a **stdio bridge** that translates ACP JSON-RPC into the Web channel's HTTP+SSE. So setup = "create a Web account, then point an adapter at it."
 
@@ -8,7 +8,7 @@ ACP isn't a channel of its own. The `halo acp` command is a **stdio bridge** tha
 
 ```
 [Mac]                                    [EC2]
-Claude Code                                  halo server (port 9527)
+Zed / JetBrains IDE                          halo server (port 9527)
    │   ACP / JSON-RPC over stdio                │
    ▼                                            │
 halo acp adapter ────HTTP/SSE────────────────▶│
@@ -19,8 +19,7 @@ halo acp adapter ────HTTP/SSE──────────────
 ```
 
 Use ACP when:
-- You want to use Claude Code locally as the chat UI but the agent's tools / workspace live on a remote machine
-- You want one halo server to delegate to **another** halo server on a different host (the `/acp add` flow below)
+- You want to use your editor (Zed, a JetBrains IDE) locally as the chat UI but the agent's tools / workspace live on a remote machine
 - You're integrating with any tool that already speaks ACP
 
 If you just want a browser UI, use the [Web](web.md) channel directly — ACP is overkill.
@@ -61,58 +60,82 @@ Each adapter process binds to **one** workspace. To drive multiple workspaces co
 
 The adapter reads/writes JSON-RPC frames on **stdin / stdout** (one message per line, no LSP-style framing). **Stderr** is reserved for human-readable diagnostics — never parse it.
 
-### Wiring into Claude Code
-
-Claude Code lets you register a custom agent. Use its `claude-code config agent add` command (see Claude Code's own docs for the exact incantation) and point it at the `halo acp …` invocation above.
-
-After registration, you can launch a session in Claude Code that streams to the remote halo server transparently — Claude Code thinks it's talking to a local agent, halo thinks it's talking to a Web-channel client.
-
-## Step 3 — (Halo-to-halo) bind a remote with `/acp add`
-
-The most common use of this adapter isn't a third-party ACP client — it's **another halo agent** delegating out to a remote halo workspace. Halo ships a builtin `acp` skill for this (slash command `/acp`, full access). Type `/acp add` — or just ask in chat (e.g. "add an ACP binding to my other halo").
-
-It walks you through `(label, host, port, workspace, token)` and **stamps out a new skill** named `ask-<label>` containing:
-
-- `SKILL.md` — slash command `/ask-<label>`, instructions tailored to this remote
-- `config.yaml` — declares the binding's params so admin Settings shows a form
-- `ask.py` — bundled JSON-RPC ↔ stdio helper (one copy per binding, intentional — keeps `/workspace share` bundles self-contained)
-
-It also writes the connection values into `settings.yaml` (workspace or global, you pick).
-
-After install, the local agent can do `shell_exec: python3 .../ask-<label>/ask.py "<question>"` and halo's runtime substitutes the configured values. **Multiple bindings coexist** — each gets its own slash command, settings namespace, and Admin Settings page. `/acp list` shows the bindings you've generated.
-
-To remove a binding: `/acp remove` (deletes the skill directory and points out the leftover `ask-<label>:` block in `settings.yaml`).
-
-This is the **only** supported way to set up a halo-to-halo binding — there's no generic single-target `ask-acp-agent` skill, because per-binding namespaces (one token-host-workspace triple per skill id) are required for multi-remote use.
-
-### Direct asks — `/acp kiro` / `/acp claude`
+### Wiring into Zed
+
+Register the adapter as a custom agent in Zed's `settings.json` (Agent Settings → External Agents → Add Agent → Add Custom Agent opens it for you). See [Zed's External Agents docs](https://zed.dev/docs/ai/external-agents):
+
+```json
+{
+  "agent_servers": {
+    "halo": {
+      "type": "custom",
+      "command": "halo",
+      "args": [
+        "acp",
+        "--host", "my-ec2-or-localhost",
+        "--port", "9527",
+        "--token", "<web-token-from-step-1>",
+        "--workspace", "/abs/path/on/server"
+      ],
+      "env": {}
+    }
+  }
+}
+```
 
-Bindings are for **remote halo servers**. For agents on the **same machine** no binding is needed — the `acp` skill talks to them directly, zero config:
+### Wiring into JetBrains IDEs
+
+In the AI Chat tool window click the menu button in the upper-right corner and choose **Add Custom Agent**; the IDE creates and opens `~/.jetbrains/acp.json`. See [JetBrains' ACP docs](https://www.jetbrains.com/help/ai-assistant/acp.html):
+
+```json
+{
+  "agent_servers": {
+    "halo": {
+      "command": "halo",
+      "args": [
+        "acp",
+        "--host", "my-ec2-or-localhost",
+        "--port", "9527",
+        "--token", "<web-token-from-step-1>",
+        "--workspace", "/abs/path/on/server"
+      ],
+      "env": {}
+    }
+  }
+}
+```
 
-- `/acp claude <question>` — local Claude Code (via npm `@agentclientprotocol/claude-agent-acp`)
-- `/acp kiro <question>` — local Kiro (via `kiro-cli acp`)
+If the IDE can't find `halo` on its `PATH`, use the absolute path to the binary as `command`.
 
-The question is passed verbatim — including the other agent's own slash commands (e.g. `/acp kiro /model <full-model-id>` switches Kiro's model). Both coexist with `/ask-<label>` bindings.
+After registration, pick the agent in the editor's agent panel and chat — the editor thinks it's talking to a local agent, halo thinks it's talking to a Web-channel client.
 
 ## ACP method coverage
 
+The adapter speaks ACP protocol v1 and passes the [ACP TCK](https://github.com/agentclientprotocol/acp-tck) v1 suite (verdict CONFORMANT).
+
 | Method | Implemented | Notes |
 |---|---|---|
-| `initialize` | ✅ | Declares `protocolVersion: 1`, `loadSession: true`, no auth methods |
+| `initialize` | ✅ | Declares `protocolVersion: 1`, `loadSession: true`, `sessionCapabilities.list`, image + embedded-context prompts, no auth methods, and `agentInfo` (`halo` + adapter version) |
 | `authenticate` | ✅ (no-op) | Token is passed via launch flags; ACP-side auth has nothing to do |
 | `session/new` | ✅ | Calls `POST /api/web/sessions`; halo mints `web_<accountId>_<ts>_<rand>` and creates the row immediately |
-| `session/load` | ✅ | Verifies the supplied id still exists on the halo server, then registers it locally |
-| `session/prompt` | ✅ | Forwards text + image content blocks. Resource / embedded-context blocks log a stderr warning and are dropped (see "Reverse fs" below) |
-| `session/cancel` | ✅ | Aborts the in-flight HTTP/SSE stream and POSTs `/web/stop` |
+| `session/load` | ✅ | Replays the session's active log into the editor (your messages, the agent's thinking, tool calls with their output, replies), then resumes it. That's the whole conversation until the session is archived; after archiving only the newest part |
+| `session/list` | ✅ | Lists this token's own conversations, newest first — what an editor's session history / resume picker shows |
+| `session/prompt` | ✅ | Text and images go through as-is. A file the editor attaches with its content (an @-mention) is inlined into the message as `[resource: <uri>]` plus the content in a code block; a binary attachment becomes `[binary resource omitted: <uri>]`; a file *link* becomes `[resource link: <name> <uri>]` — only a pointer, since the server can't open a path on your laptop. Audio is not supported (dropped with a stderr warning) |
+| `session/cancel` | ✅ | Stops the turn server-side; the interrupted tool calls still show up before the prompt ends as `cancelled` |
+| `session/resume`, modes, config options, `session/delete` / `close`, `logout` | ❌ | Not advertised in `initialize`; calling them anyway gets "method not found" |
 | Reverse `fs/*` | ❌ | See "Reverse fs" below |
 | Reverse `terminal/*` | ❌ | Same reasoning |
 | `requestPermission` | ❌ | Halo has its own access-level system at the channel-account level |
 
+Tool calls show in the editor with a kind (read / edit / execute / search / fetch / other) and a one-line title such as `shell_exec: ls -la`. They carry no file locations — the paths are on the server, the editor couldn't open them. Your editor's own MCP servers are not connected to the halo agent.
+
+If the connection drops mid-turn (proxy timeout, network blip, server restart), the adapter re-attaches on its own and fills in whatever text it missed; after 5 failed attempts it ends the turn with `[adapter error] connection lost`. Sending a prompt while the session is already busy (another client is mid-turn on it) queues it on the server; the adapter waits for that run and returns the reply to your message when it finishes.
+
 ### Session id model
 
-ACP `sessionId` **is** the halo session id — there's no extra mapping layer. `session/new` asks the server to mint one (`POST /api/web/sessions`); it lands in the token's own `web_<accountId>_` namespace and the `agent_sessions` row exists immediately, so readonly / workspace tokens can drive it too. The ACP client persists ids itself; the adapter holds no on-disk state. Losing the adapter's in-memory map on restart is harmless because the conversation lives on the halo server.
+ACP `sessionId` **is** the halo session id — there's no extra mapping layer. `session/new` asks the server to mint one (`POST /api/web/sessions`); it lands in the token's own `web_<accountId>_` namespace and the `agent_sessions` row exists immediately, so readonly / workspace tokens can drive it too. The adapter holds no on-disk state; losing its in-memory map on restart is harmless because the conversation lives on the halo server.
 
-The ACP client is the source of truth for "which sessions are mine" — a Mac-side Claude Code knows about *its* sessions, the EC2-side halo agent doesn't need to enumerate them.
+`session/list` asks the server for the token's own root conversations (every session under its `web_<accountId>_` prefix — including ones a browser client made with the same token; sub-agent sessions excluded). It's scoped to the token even for a `full` token. Each entry's `cwd` is the server-side workspace path, so if your editor filters the list by its local project directory it gets an empty list — that's expected.
 
 ## Multi-workspace
 
@@ -131,7 +154,7 @@ ACP optionally lets the agent (running on the server) request files from the cli
 1. The Web channel is HTTP + SSE — a one-way stream. Reverse fs would need WebSocket or long-poll
 2. Halo agents currently use `file_read` / `file_write` against the **server's** workspace; supporting reverse fs would need a parallel toolset
 
-For now: if you want the agent to see a Mac-side file, paste it into the prompt. The adapter logs a stderr warning when it sees a `resource` content block in `session/prompt`, so the failure mode is obvious.
+What works instead: attach the file with its content (e.g. an @-mention in your editor) — the adapter inlines it into the prompt, so the agent reads it. A plain file link only tells the agent the name and path; it can't open it. Or paste the content into the prompt.
 
 ## Common problems
 
@@ -140,8 +163,10 @@ For now: if you want the agent to see a Mac-side file, paste it into the prompt.
 | Adapter exits immediately on launch | Missing required flag, or the token / host are wrong. Check stderr |
 | `401` on first prompt | Token typo, or token was deleted from admin |
 | `403` when launching with `--workspace /some/other/path` | Token is `readonly` / `workspace` access — use a `full` token or omit `--workspace` |
-| Tool calls don't appear in Claude Code | Expected — halo doesn't translate every event back as ACP `tool_call`. See [docs/dev/acp-adapter.md](../../dev/acp-adapter.md) for the full mapping |
-| Two `session/prompt` calls on the same id, second hangs | Halo queues messages when a session is busy; ACP adapter ends the response with `[queued — session busy]`. Wait for the first to finish |
+| Tool call shows no file link / can't jump to the file | Expected — tool paths are on the server, so the adapter sends no `locations`. See [docs/dev/acp-adapter.md](../../dev/acp-adapter.md) for the full mapping |
+| Second prompt rejected while the first is still running | ACP allows one prompt per session at a time — cancel the first, or wait for it |
+| Reply text appears again behind `[reconnected — full reply]` | The stream dropped mid-reply and the missed part couldn't be appended cleanly, so the adapter resent the whole reply. A proxy cutting long streams is the usual cause |
+| Session history picker is empty | If the editor filters by its local project directory, the list comes back empty: halo sessions live under the **server** workspace path |
 | `/workspace switch <path>` worked but other tokens broke | You changed the db-level default. Switch back with another `/workspace switch`, or stop using slash commands from the adapter |
 
 ## Reference

package/bundled-docs/guide/channels/feishu.md

@@ -130,7 +130,7 @@ Same set as the other channels — type as plain text, **in a 1:1 DM only** (in
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
-| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
+| `/cron` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 ## Cron jobs targeting Feishu

package/bundled-docs/guide/channels/slack.md

@@ -132,7 +132,7 @@ Same set as the other channels, but **only in a DM with the bot** — in a chann
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
-| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
+| `/cron` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 ## Cron jobs targeting Slack

package/bundled-docs/guide/channels/telegram.md

@@ -78,7 +78,7 @@ If nothing happens, check halo server logs for `[Telegram]` lines.
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
-| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
+| `/cron` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 ## Cron jobs targeting Telegram

package/bundled-docs/guide/channels/web.md

@@ -36,19 +36,20 @@ curl -N -H "x-token: $TOKEN" -H "Content-Type: application/json" \
   http://localhost:9527/api/web/chat
 ```
 
-Response is a stream of `data: {json}\n\n` SSE frames:
+Response is a standard SSE stream: `data: {json}` event lines, plus a `: keepalive` comment line every 15 s so an idle proxy doesn't cut the connection during a long tool call:
 
 ```
 data: {"type":"session","sessionId":"web_abc123_m1xyz"}
 data: {"type":"thinking","text":"..."}
-data: {"type":"tool_call","toolName":"file_read","toolInput":{...}}
-data: {"type":"tool_result","toolName":"file_read","result":"..."}
+data: {"type":"tool_call","toolName":"file_read","toolUseId":"toolu_01…","toolInput":{...}}
+: keepalive
+data: {"type":"tool_result","toolName":"file_read","toolUseId":"toolu_01…","result":"..."}
 data: {"type":"stream","text":"Hello! "}
 data: {"type":"stream","text":"How can I help?"}
 data: {"type":"complete"}
 ```
 
-Parse the `type` field on each event to render text vs tool calls vs completion.
+Parse the `type` field on each event to render text vs tool calls vs completion. **Only lines starting with `data:` are events** — skip everything else (the keepalive comment, blank separators). `EventSource` does this for you; a hand-rolled parser that splits on `\n\n` and slices off `data: ` will break on the keepalive. `toolUseId` pairs a `tool_result` with its `tool_call` when several run at once (it can be empty for some model providers — then pair with the most recent call).
 
 ### Other endpoints
 
@@ -56,12 +57,13 @@ Parse the `type` field on each event to render text vs tool calls vs completion.
 |---|---|---|
 | `POST /api/web/chat` | Send a message; SSE response |
 | `POST /api/web/sessions` | Mint a new root session in the token's namespace; returns `{sessionId}` |
+| `GET /api/web/sessions?cursor=…` | List the token's own conversations, newest first, 50 per page → `{workspace, sessions: [{sessionId, title, updatedAt}], nextCursor}`; pass `nextCursor` back as `cursor` for the next page (`null` = last page) |
 | `POST /api/web/stop` | Cancel the running task |
-| `GET /api/web/history` | Fetch session message history |
-| `GET /api/web/subscribe` | Reconnect to a running session's SSE stream |
+| `GET /api/web/history` | Fetch session message history (optional `since=<epoch ms>`: only rows from then on) |
+| `GET /api/web/subscribe` | Reconnect to a running session's SSE stream (an idle session answers with one `complete` straight away) |
 | `GET /api/web/file?path=…` | Fetch a file from the bound workspace (path relative to it; `.halo` runtime state is refused) |
 
-All six accept the same auth header.
+All seven accept the same auth header.
 
 ### Per-request overrides
 
@@ -102,7 +104,7 @@ Slash commands are intercepted before they reach the agent — same set as every
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
-| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
+| `/cron` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 Send a slash command exactly like a normal message — the server detects the leading `/`.

package/bundled-docs/guide/channels/wechat.md

@@ -77,7 +77,7 @@ Same set as the other channels — type as plain text in your WeChat DM with the
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
-| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
+| `/cron` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 | `/qr [level]` | Generate an invite QR (`full`-access bot only; `level` = `readonly` (default) / `workspace` / `full`) |
 

package/bundled-docs/guide/channels/wecom.md

@@ -105,7 +105,7 @@ Same set as the other channels — type as plain text in a **single chat** (comm
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
-| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
+| `/cron` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 ## Cron jobs targeting WeCom

package/bundled-docs/guide/chat.md

@@ -68,7 +68,6 @@ Most commands are noun-verb **object commands**: `/<obj> <verb> [args]`. Bare `/
 | `/skill <verb>` | Manage skills — `list` / `desc` (built-in, open to all) · `disable` / `enable` (built-in, workspace access) · `delete` (built-in, full access) · `create` / `update` (handled by the `skill` skill, full access) |
 | `/workspace <verb>` | Manage the workspace — `info` (built-in, open to all) · `switch <path>` (built-in, full access) · `setup` / `tidy` (workspace skill, workspace access; init / reorganize `.halo/` INDEX.md / INSTRUCTIONS.md / memory/) · `share` (workspace skill, full access; export a shareable bundle) |
 | `/cron <verb>` | Scheduled agent runs — `create` / `list` / `update` / `enable` / `disable` / `delete` (cron skill, full access) |
-| `/acp <verb>` | Talk to other agents over ACP — `kiro <q>` / `claude <q>` ask a local agent directly; `add` / `list` / `remove` manage generated `ask-<label>` bindings (acp skill, full access) |
 | `/extension <verb>` | Canvas preview extensions — `install <id\|zip\|url>` / `list` / `remove <id>` (extension skill, full access) |
 | `/evo [hint]` | Queue a self-evolution run on this session (full access only) |
 | `/help` | List every command — object commands only show the verbs you can run |

package/bundled-docs/guide/cli.md

@@ -143,7 +143,6 @@ Multi-turn conversation. Supports all standard Halo slash commands:
 | `/workspace switch <path>` | Switch workspace (full access only) |
 | `/workspace setup` / `/workspace tidy` / `/workspace share` | Set up / tidy the `.halo/` knowledge files, or export a shareable bundle (workspace skill) |
 | `/cron <verb>` | Manage scheduled agent runs: `create` / `list` / `update` / `enable` / `disable` / `delete` |
-| `/acp <verb>` | Ask other agents over ACP (`kiro <q>` / `claude <q>`) and manage `ask-*` bindings (`add` / `list` / `remove`) |
 | `/extension <verb>` | Canvas preview extensions: `install` / `list` / `remove`; `models` updates the model provider list from the hub (full access only) |
 | `/evo [hint]` | Queue a self-evolution run on this session (full access only) |
 | `/quit` | Exit |
@@ -181,7 +180,7 @@ The line under the input box:
 | `Ctrl+W` / `Alt+Backspace` | Delete the word before the cursor |
 | `Ctrl+U` / `Ctrl+K` | Delete to start / to end of input |
 
-On resume (`-s <id>`, or the default latest session), the TUI replays the session's prior conversation on screen so you see where you left off. `shell_exec` output is shown inline by default (other tools' output needs `-v`). Tool lines show a short argument summary and duration, e.g. `⚙ file_read hello.txt 4ms`.
+On resume (`-s <id>`, or the default latest session), the TUI replays the session's prior conversation on screen so you see where you left off — only the last 100 messages; anything older collapses into a first line `── N earlier messages hidden · ctrl+o for the full log ──`. `shell_exec` output is shown inline by default (other tools' output needs `-v`). Tool lines show a short argument summary and duration, e.g. `⚙ file_read hello.txt 4ms`.
 
 **Multi-line paste**: pasting text with newlines (or >800 chars) collapses into a compact placeholder like `[#1 pasted 3 lines]` in the input; you can keep typing around it, and the original text is expanded back in full on submit. Pasted content is inserted at the cursor position.
 

package/bundled-docs/guide/getting-started.md

@@ -79,7 +79,7 @@ After `halo setup`:
 
 **When does "refreshed on upgrade" actually run?** `halo setup` always re-runs the seed; the server's startup check — and the same check at the start of `halo cli` / `halo tui` — also re-runs it automatically when `~/.halo/global/.template-version` is behind the bundled `TEMPLATE_VERSION`. So the routine flow `halo upgrade && halo server restart` is enough — no need to remember `halo setup` — and a CLI-only user just runs `halo cli` / `halo tui` after `halo upgrade`.
 
-**Server-refreshed**: `INSTRUCTIONS.md`, `prompts/`, `models/`, `docs/`, the built-in agent ids (`default`, `executor`, `deep-executor`, `goal`, `__evo_agent__`, `__score__`, `__apply_agent__`), and the built-in skill ids (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `self`, `aws-knowledge`, `web-search`, `halo`, `extension`). To customize one, copy it into the workspace scope (`<project>/.halo/...`) — workspace replaces global at runtime.
+**Server-refreshed**: `INSTRUCTIONS.md`, `prompts/`, `models/`, `docs/`, the built-in agent ids (`default`, `executor`, `deep-executor`, `goal`, `__evo_agent__`, `__score__`, `__apply_agent__`), and the built-in skill ids (`agent`, `skill`, `workspace`, `cron`, `send-file`, `self`, `aws-knowledge`, `web-search`, `halo`, `extension`). To customize one, copy it into the workspace scope (`<project>/.halo/...`) — workspace replaces global at runtime.
 
 **Never overwritten**: anything else under `agents/` or `skills/` (your own creations), and everything under `secrets/`.
 

package/bundled-docs/guide/skills.md

@@ -30,7 +30,7 @@ Putting those in AGENT.md would bloat the system prompt. Skills use **progressiv
 
 Workspace overrides global (same id).
 
-**Built-in skills** (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `self`, `aws-knowledge`, `web-search`, `halo`, `extension`) are server-shipped and **force-overwritten on every server startup**. Local edits to these directories under `~/.halo/global/skills/` will be lost. To customize one, copy it into `<project>/.halo/skills/<id>/` (workspace replaces global) and edit there. Other skills under `~/.halo/global/skills/` — including any the user created via the admin UI — are untouched by the seeder.
+**Built-in skills** (`agent`, `skill`, `workspace`, `cron`, `send-file`, `self`, `aws-knowledge`, `web-search`, `halo`, `extension`) are server-shipped and **force-overwritten on every server startup**. Local edits to these directories under `~/.halo/global/skills/` will be lost. To customize one, copy it into `<project>/.halo/skills/<id>/` (workspace replaces global) and edit there. Other skills under `~/.halo/global/skills/` — including any the user created via the admin UI — are untouched by the seeder.
 
 ## SKILL.md format
 
@@ -154,7 +154,6 @@ Halo seeds these skills on every startup (the ids in `BUILTIN_SKILL_IDS`, `packa
 | skill | Create / update skills — backs the `create` / `update` verbs of `/skill` |
 | workspace | Workspace maintenance — backs `/workspace setup` / `tidy` (init / reorganize `.halo/` INDEX.md / INSTRUCTIONS.md / memory/) and `/workspace share` (export a shareable bundle) |
 | cron | Create / list / update / enable / disable / delete scheduled agent runs — backs `/cron` |
-| acp | Talk to other agents over ACP (`/acp kiro\|claude <q>`) and manage `ask-<label>` bindings for halo-to-halo delegation (`/acp add\|list\|remove`) |
 | send-file | Deliver an image/video/file as a channel attachment by emitting `MEDIA:<absolute_path>` — works on Web / WeChat / Telegram / Slack / Feishu (no command; model-activated, workspace access) |
 | self | The agent's own visual space (`.halo/canvas/self.html`) for self-expression (no command; model-activated, full access) |
 | aws-knowledge | Query the official AWS Knowledge MCP server for up-to-date AWS docs (no command, `user-invocable: false`; model auto-activates) |

package/bundled-docs/requirements/chat.md

@@ -8,6 +8,7 @@ The primary surface for talking to an agent.
 - Dropdown in the composer's left control cluster (after the Debug button) selects which agent to use; hidden when only one agent is usable
 - Lists every available agent (from `GET /api/agent-configs`; overridden, disabled and internal agents are hidden), highest priority first. A new session starts on the top one
 - **Locked during an active session** (and while a response is streaming) — the agent is bound to the session; to change, start a new session (/session new)
+- While it can be changed, the Bot icon is primary-coloured (same "active" colour as the other toolbar toggles); locked, it stays muted grey and dimmed, and hovering it explains that the agent can't change once the conversation has started — start a new session to use another (`chat.agent.locked`)
 - The Agents panel's "Test" button can also preselect an agent
 
 ### Access level
@@ -96,26 +97,45 @@ When `contextEnabled` is on (default), user messages are auto-prepended with:
 - Drag to chat input
 - Clipboard paste
 - File-picker button
+- Screenshot button (below)
 
 Images ride along as base64; multimodal supported. Before sending, every attachment is downscaled (long edge ≤ 1568) and re-encoded as JPEG; an SVG is rasterized the same way (long edge 1024, on white), since vision input only takes jpeg / png / gif / webp. An image the browser can't decode (e.g. HEIC / TIFF in Chrome) and that isn't one of those four is refused when attached, with an inline notice naming the file — it is never sent only to be dropped server-side. Pasted images are also persisted to `<workspace>/.halo/assets/web/inbound/web/<date>/` so a `[图片已保存: /abs/path]` marker survives page reload and renders as a click-to-preview chip (shared with the WeChat channel's inbound media flow).
 
+### Screenshot (drag-select a region)
+A Scissors button in the toolbar's input group (upload · **screenshot** · screen · camera) takes one still of the screen and lets the user crop it into an image attachment:
+- Click → a frozen frame opens in a full-window crop layer over the admin (dark backdrop, area outside the selection dimmed). Drag a box (dragging again redraws it); **Enter**, double-click or ✓ confirms, **Esc** or ✕ cancels. Confirming with no box (or one under 8 px) attaches the whole frame. Enter here never sends the message.
+- The crop is cut from the full-resolution frame and attached as `screenshot-YYYYMMDD-HHMMSS.png` — from then on it's an ordinary attachment (chip, X to remove, downscaled to JPEG on send like any upload).
+- Grey at rest, primary colour while the picker / crop layer is open; clicking it then cancels.
+- Frame source differs by client:
+  - **Desktop client** (mac / win): no picker — grabs the display the Halo window is on (only that one on multi-monitor), Halo itself visible in the shot. Needs macOS **Screen Recording**; without it the permission hint shows in the attachment-notice row.
+  - **Browser**: the browser's own `getDisplayMedia` picker every time (a page can't read the screen otherwise), one frame, stream stopped right away. Picking "Entire screen" includes the browser's own "sharing" bar — crop it out. Cancelling the picker does nothing.
+  - An older desktop client without the screenshot bridge falls back to the browser path (Halo's own source picker).
+- Independent of live capture: never reads or changes a bound screen share.
+- Shown only when a frame source exists and the selected agent's model accepts images — same gate as live capture (no button on mobile browsers).
+
 ### Inline media chips
 Any message containing `[图片/视频/语音/文件 已保存: /path]` markers (WeChat + web) or a leading `MEDIA: /path` line (agent-emitted, e.g. from `wechat-send`) renders a compact chip with filename + icon. Clicking opens a full-size preview modal (image/video/audio inline, file → download link). The modal has a Download button (top-right, next to close) for image/video/audio; the media URL carries a per-open cache-buster (`&t=<timestamp>`) so overwritten files (same path, new bytes) always show current content. Paths inside the active workspace or under the OS temp dir (`/tmp/`) are previewable; everything else degrades to a non-clickable chip.
 
 Images in chat (the modal's full-size image, a user message's screenshot strip and its zoom, markdown images in replies) never show the browser's broken-image icon: a themed pulsing box while loading, the image once loaded, and an `ImageOff` icon + "Image unavailable" / 「图片无法加载」 box if it fails (`shared/components/safe-image.tsx`).
 
-### Live capture (desktop only)
-Lets the agent *see something live* on demand. Desktop client (Electron) only — the entry points never render in a plain browser. Borrows the meeting-app "share" model: the user binds one source, then the agent requests a frame when it actually needs to look.
+### Live capture (screen share + camera)
+Lets the agent *see something live* on demand. Works in the desktop client (Electron) **and** a plain browser. Borrows the meeting-app "share" model: the user binds a source, then the agent requests a frame when it actually needs to look.
+
+Two source kinds in the chat-input toolbar, **independent** — either one alone, or both at once:
+- **Screen / window share** (MonitorUp button). Desktop: opens a picker grid of screens + app windows; a bound window can be grabbed even while it sits in the background. Browser: the browser's own `getDisplayMedia` picker; the share is kept live while bound (frames drawn from it on demand). No screen button where `getDisplayMedia` is missing (mobile browsers) — the camera button stays.
+- **Camera** (Camera button) — opens a picker with a live preview (even for a single webcam), then binds the chosen device. Hidden entirely on a machine with no camera. In the browser the camera stream is held open while bound (so a request that lands while the page has no focus doesn't re-prompt or stall) and released on unbind.
+
+Each button is a toggle: grey when off, primary-coloured icon when on. **Clicking an active button again turns that source off** — no picker; in the browser the share / camera stream stops. To switch screen source or camera device, turn it off and on again. Each bound source also shows as a chip right after the agent selector (icon + name, primary colour, X to unbind just that one). In the browser, the browser's own "Stop sharing" bar unbinds the screen (the camera stays).
 
-Two source kinds in the chat-input toolbar, **mutually exclusive** (only one bound at a time):
-- **Screen / window share** (MonitorUp button) — opens a picker grid of screens + app windows. A bound window can be grabbed even while it sits in the background.
-- **Camera** (Camera button) — toggles the webcam on. Hidden entirely on a machine with no camera.
+Once bound, a frame is **not** attached to every message. Instead a one-line instruction is injected into the next send telling the model how to ask for a look:
+- Only one source bound — "the user is sharing the «X» window" / "sharing «X» from the browser" / "the user has turned the camera on", and the model outputs a line containing exactly `<<<CAPTURE>>>` when it needs the current view.
+- Both bound — one combined instruction ("the user is sharing «X» and has the camera on"): `<<<CAPTURE:screen>>>` for the screen only, `<<<CAPTURE:camera>>>` for the camera only, bare `<<<CAPTURE>>>` for both.
 
-Once bound, a frame is **not** attached to every message. Instead a one-line instruction is injected into the next send ("the user is sharing the «X» window" / "the user has turned the camera on") telling the model to output a line containing exactly `<<<CAPTURE>>>` when it needs to see the current view. On turn completion the frontend detects the marker in any of the turn's replies, grabs one frame, and sends it back as a **visible image message** — the model sees it on its following turn. So it's a cross-turn round-trip: model asks → frame is sent back → model answers next turn. The returned frame is also shown inline on the user bubble so you can see exactly what was sent.
+On turn completion the frontend collects every capture marker in the turn's replies (union; a bare marker = every bound source; a request for a source that isn't on falls back to every bound one, so a request never goes unanswered), grabs each requested source and sends them back as **one visible image message** (screen first) — the model sees them on its following turn. So it's a cross-turn round-trip: model asks → frame(s) sent back → model answers next turn. The returned frames are shown inline on the user bubble so you can see exactly what was sent; a source that failed contributes a short failure note instead of its image. Markers are hidden from the rendered reply.
 
 Constraints:
-- Shown only when the selected agent's model accepts image input (capture is pointless on a text-only model); switching to a text-only model auto-unbinds.
-- Screen share needs macOS **Screen Recording** permission; the camera prompts for **Camera** permission on first use, with an "Open Settings" path if previously denied.
+- Shown only when the selected agent's model accepts image input (capture is pointless on a text-only model); switching to a text-only model auto-unbinds both.
+- Desktop: screen share needs macOS **Screen Recording** permission; the camera prompts for **Camera** permission on first use, with an "Open Settings" path if previously denied. Browser: the page must be served over HTTPS or from localhost (`getDisplayMedia` / `getUserMedia` are absent elsewhere, so the buttons don't render); a denied camera shows a hint pointing at the address bar's site settings.
 - Binding is **in-memory only** and shared by all chat tabs — a page reload or restart requires re-selecting.
 
 ### The agent's face (`self.html`)