@prismer/runtime 2.0.7 → 2.2.55

package/built-in-skills/agent-coordination/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: agent-coordination
+scope: common
+description: Find other agents, list participants in a conversation, send routed messages, attach files, and recover earlier conversation context (history / resolve a fuzzy reference / read a quoted message / read compressed summaries). Use whenever you need to delegate to another agent, address a peer in a multi-agent conversation, send a message that carries a file, or pull context that scrolled out of your prompt window. Executes via `cloud discover`, `cloud im conversations`, `cloud send`, `cloud file send`, `cloud conversation history|resolve-identifier|summary`, and `cloud quote read` CLIs.
+---
+
+# Agent Coordination
+
+Multi-agent workspaces route messages between named agents. This skill bundles the four-step flow: **discover → list-in-conversation → send → (optional) attach file**. The platform enforces that messages are routed to **agents who are participants in the conversation**, so you can't shortcut steps 1–2 even when you "know" the username from chat text.
+
+## ⛔ Inline subagents are NOT delegation
+
+If you have an inline `Task` / `Subagent` / `ParallelAgents` / fan-out tool available (Anthropic Claude Code, Cursor, Cline, etc.), **never use it to fulfil a "delegate to <peer-agent>" request**. Inline subagents:
+
+- run in your own process, with your own context and credentials
+- never appear on the workspace Kanban
+- never @-mention the supposed assignee in the conversation
+- finish in seconds, which to the user looks like you did the work yourself (because you did)
+
+For peer-agent delegation, the canonical paths are **`cloud task create --assignee-name <peer>`** (tracked deliverable; see the `tasks` skill) and **`cloud send <peer-username> "<message>" --by-username --workspace-id "$PRISMER_WORKSPACE_ID"`** (ad-hoc message; see below). Anything else — including inline subagents — is the wrong tool, and the user will notice (the supposed assignee was never @-mentioned in chat, and your response came back too fast).
+
+### `cloud task create` vs `cloud send` — 选哪条 + 结果回流
+
+| 你想要的 | 用 | 结果怎么回来 |
+| --- | --- | --- |
+| **可追踪委派**（要交付物、要进度、要落看板） | `cloud task create --assignee-name <peer>` | **不自动回流**：peer 在独立 context 跑，产物落 task 卡；你须 `cloud task get <taskId>` 主动拉（`status=completed` 才算成）。详见 `tasks` skill 的「结果回流」段。 |
+| **即兴消息**（问一句、转一份、打个招呼） | `cloud send <peer-username> "<message>" --by-username --workspace-id "$PRISMER_WORKSPACE_ID"` | peer 若在**同一会话**，回复直接出现在这条会话里；不落看板、不可追踪。 |
+
+口诀：**要结果 / 要看板 → `cloud task create` 然后 `cloud task get` 取**；只是说句话 → `cloud send`。两者都不是 inline subagent。
+
+## When to use
+
+- The user asks to **delegate** something to another agent ("ask Bob to review this") — `cloud task create` for tracked work, `cloud send` for ad-hoc routing. **Never an inline subagent.**
+- You're in a multi-agent conversation and want to **address** a specific peer.
+- You need to **find an agent** with a specific capability (`code-review`, `data-analysis`, `repair`).
+- You need to **send a message** that carries an attached file (report, log, image).
+
+## CLI Reference
+
+### Discover (workspace-wide directory)
+
+```bash
+cloud discover --workspace-id "$PRISMER_WORKSPACE_ID"                                  # all agents in this workspace
+cloud discover --workspace-id "$PRISMER_WORKSPACE_ID" --capability code-review         # filter by capability
+cloud discover --workspace-id "$PRISMER_WORKSPACE_ID" --online-only                    # only online agents
+cloud im contacts                                 # your contact list
+```
+
+`cloud discover` is a workspace-scoped Agent Registry contract: every result
+is backed by an AgentCard in the requested workspace and carries its routing
+`userId`. Human accounts and agents from other workspaces are contract
+violations. When the target is already in the current conversation, prefer the
+conversation members listing below instead of searching the wider workspace.
+
+### List participants in a conversation (scoped)
+
+```bash
+cloud im conversations                            # all your conversations
+cloud im conversations --unread                   # unread only
+cloud im conversations <conversationId> --members --json # exact agent + human participant fields
+```
+
+### Send a message
+
+```bash
+# Direct message to an agent
+cloud send <to-username> "Please review the PR" --by-username --workspace-id "$PRISMER_WORKSPACE_ID"
+cloud send <to-username> "## Report" -t markdown --by-username --workspace-id "$PRISMER_WORKSPACE_ID"
+cloud send <to-username> "Acknowledged" --reply-to <messageId> --by-username --workspace-id "$PRISMER_WORKSPACE_ID"
+
+# Conversation-scoped (multi-agent group)
+cloud im groups send <groupId> "Team update: feature shipped"
+
+# With routing metadata
+cloud send <to-username> "Need approval" --conversation-id <convId> --by-username --workspace-id "$PRISMER_WORKSPACE_ID"
+```
+
+### Send with attached file
+
+> **决定怎么交付文件 — 先读这条:**
+>
+> - **用户明确要求随当前回复交付的文件** → 写入
+>   `${PRISMER_ARTIFACTS_DIR}`（当前 dispatch 的 `artifacts/` 目录），然后显式运行
+>   `cloud deliver <abs-path>`。auto-scan 默认 OFF；只写文件不算交付。
+> - **看板 task 的文件产物** → 显式运行 `cloud task attach <abs-path>`，并以
+>   命令返回的 assetId 为准。
+> - **`cloud file send` 会另起一条独立消息**（先于/晚于你的回复单独落），
+>   只适合「对话进行中临时丢个文件给对方看」这种 ad-hoc 分享，**不要**用它
+>   交付任务最终产物 —— 否则用户会看到「一条只有文件的消息」+「一条只有
+>   文字的消息」分裂开（release201/30 §4 + §7）。
+
+```bash
+# 当前回复的文件交付：写入 artifacts/ 后显式 deliver
+cp ./report.pdf "${PRISMER_ARTIFACTS_DIR}/"
+cloud deliver "${PRISMER_ARTIFACTS_DIR}/report.pdf"
+
+# 看板 task 文件产物：显式 attach
+cloud task attach "${PRISMER_ARTIFACTS_DIR}/report.pdf"
+
+# ad-hoc 临时分享（会另起独立消息 — 不要拿来交付最终产物）
+# 文字说明用 -c/--content（不是 --message —— 后者不存在，commander 会报
+# unknown option，逼 agent 试错）。`cloud file send <conversationId> <path>`
+# 之外仅 [-c|--content <text>] [--mime <type>] [--json] 三个旗标。
+cloud file send <conversationId> ./report.pdf
+cloud file send <conversationId> ./report.pdf --content "Latest numbers, please review"
+cloud file send <conversationId> ./image.png --mime image/png
+
+# 常态（含 hermes）：直接 `cloud file send <conversationId> <path>` 即可——daemon
+# (release203/15c) 按 agent 身份自动关联你当前的 dispatch。仅当你要对另一个
+# (非当前) dispatch 交付、或 daemon 报 409 歧义时，才从 <execution_context> 抄
+# --run-id "<run_id>" 传入。Spawn 适配器 (claude-code / codex) env 已注入。
+cloud file send <conversationId> ./report.pdf --run-id "<run_id>"  # 仅跨-dispatch / 409 时
+
+# Or upload first, then send by asset id
+cloud file upload ./report.pdf                    # → returns assetId / uploadId
+cloud send <to-username> "See attached" --asset-id <assetId> --by-username --workspace-id "$PRISMER_WORKSPACE_ID"
+```
+
+### Attach a file to a message you ALREADY sent (`cloud attach`)
+
+> **「我已经回了，现在想给那条消息补一个产物」** —— `cloud send` / `cloud
+> file send` 返回的 `messageId` 就是给这个用的。先发消息拿到 `messageId`，之后
+> 产出文件时用 `cloud attach <messageId> <abs-path>` 把它**补挂到那条已发出的
+> 消息上**（不会另起一条）。这跟 `cloud deliver`（随你**这一**回复一起发，回复
+> 还没落）是互补的两件事：`deliver` 管「这条回复带文件」，`attach` 管「补挂到
+> 已有消息」。
+
+```bash
+cloud attach <messageId> ./addendum.pdf
+
+# 常态（含 hermes）：直接 `cloud attach <messageId> <path>` 即可——daemon
+# (release203/15c) 按 agent 身份自动关联你当前的 dispatch（含 conversation）。
+# 仅当你要对另一个 (非当前) dispatch 操作、或 daemon 报 409 歧义时，才从
+# <execution_context> 抄 --run-id / --conversation-id 传入。
+cloud attach <messageId> ./addendum.pdf --run-id "<run_id>" --conversation-id "<conversation_id>"  # 仅跨-dispatch / 409 时
+```
+
+### Read earlier conversation context (on demand)
+
+```bash
+cloud conversation history <conversationId>             # recent messages (oldest→newest)
+cloud conversation history <conversationId> --limit 100 # pull more turns
+cloud conversation history <conversationId> --before <messageId>  # page further back
+```
+
+When you need context from **earlier in the conversation** than what you were handed — the user references "the layout we discussed", "that file from before", an earlier decision, or anything that isn't in the prompt you received — run `cloud conversation history <conversationId>` to fetch the prior turns yourself. Each message comes back as `{ id, role, sender, content, createdAt }`. Don't guess at what was said earlier; pull it. Don't assume the full history was pre-loaded into your prompt — it deliberately isn't (only a recent window is). Page backwards with `--before <messageId>` if you need still-older turns.
+
+## Memory & quoting
+
+A conversation is an unbounded sequence; only a recent window is in your prompt. Four CLIs let you recover anything that scrolled out — **pull it, never invent it**. None of this goes through MCP; it's all `cloud` CLI.
+
+```bash
+# 1. Earlier raw turns (verbatim messages, oldest→newest)
+cloud conversation history <conversationId> [--limit N] [--before <messageId>]
+
+# 2. Resolve a fuzzy reference ("上次那个 layout", "the auth doc") to a canonical id
+cloud conversation resolve-identifier <conversationId> "<alias>"
+
+# 3. Read the full text of a specific quoted/referenced message
+cloud quote read <conversationId> <messageId>
+
+# 4. Read compressed summaries of older segments (cheap recall of the whole arc)
+cloud conversation summary <conversationId>
+```
+
+**When to reach for which:**
+
+- **`history`** — you need the exact wording of recent-but-out-of-window turns, or to page back through a stretch of the conversation. Returns `{ id, role, sender, content, createdAt }` per message.
+- **`resolve-identifier`** — the user refers to something by an alias or vague phrase ("the layout we picked", "that PR", "the doc from yesterday") and you need the canonical id before acting on it. Output is `{ ambiguous, resolved, candidates[], note }`.
+- **`quote read`** — a message quotes/replies to an earlier one and you need that earlier message's full content (not just the snippet). Survives source deletion — if the original was deleted you get `deleted: true` + `sourceDeletedAt`, but still the snapshot content.
+- **`summary`** — you want the gist of the *whole* conversation arc without paging through every turn. Returns compressed-segment summaries (`{ segmentSeq, summary, coversFrom/To…, messageCount, tokenCount }`) for the current range. Use it to orient, then `history` / `quote read` to drill into the exact wording.
+
+### ⛔ Disambiguation rule (mandatory)
+
+`resolve-identifier` returns `ambiguous: true` (with `resolved: null` and **multiple `candidates`**) when the alias matched more than one identifier. When this happens you **MUST** present the candidates to the user and ask which one they meant. **Never guess a `canonicalId`, never silently pick the first/highest-scoring candidate, never proceed on a tie.** Picking wrong here corrupts every downstream action. The `note` field in the output restates this — honour it.
+
+When `resolved` is non-null (`ambiguous: false`), exactly one identifier matched and you may proceed. When `candidates` is empty, nothing matched — ask the user to clarify what they're referring to rather than inventing an id.
+
+### Run checkpoints (daemon-local)
+
+Long runs persist **phase-level** checkpoints on the daemon (one per phase transition, not per tool step). They drive automatic crash-resume; you normally never touch them. For manual save/restore of a run's checkpoint state (ops / before a risky reset), use the daemon-local `session` CLI — also `cloud`-family, never MCP:
+
+```bash
+prismer session checkpoint list <runId>      # show this run's live phase checkpoints
+prismer session checkpoint save <runId>      # snapshot them to a sidecar JSON
+prismer session checkpoint restore <runId>   # re-apply a saved snapshot
+```
+
+`<runId>` is the task/run id. These operate on local SQLite, so they work even when the daemon process is down.
+
+## Workflow (delegating to another agent)
+
+1. **List conversation participants first.** `cloud im conversations <convId> --members --json` returns a `participants` array. Each item has `{ id, role, user: { id, username, displayName, role, agentType } }`; it does not contain AgentCard capabilities or status. Don't `discover` if the intended target is already identifiable in this conversation.
+2. **Pick the target.** For an existing participant, select an agent by `user.role === "agent"` and use its exact `user.id` or `user.username`; exclude yourself. If the request instead requires capability/status-based selection, use the workspace-scoped Agent Registry with `cloud discover --workspace-id "$PRISMER_WORKSPACE_ID"`.
+3. **Compose a routed message** with: requested action, context, constraints, expected output. Don't bury the ask in pleasantries.
+4. **Send with the exact `username`** the listing returned via `cloud send <username> "<message>" --by-username --workspace-id "$PRISMER_WORKSPACE_ID"`. Don't transform "@Alice" → "alice" by yourself — use the exact string the service returned. Alternatively, pass the discovered `userId` directly and omit `--by-username`.
+5. **Check the return value.** `cloud send` may return `{ ok: false, error: 'agent_not_found' }` even when you got the username from listing (the agent may have left between calls). If `ok: false`, surface the error; don't pretend dispatch succeeded.
+
+## Workflow (file attachment)
+
+1. Confirm the file exists locally and is the artifact the user should receive.
+2. Follow the Runtime carrier directive first. An inline PKF is not a file attachment and must not create a parallel file.
+3. For an explicitly requested file, write new output under `PRISMER_ARTIFACTS_DIR`, then run `cloud deliver <abs-path>` for the current reply or `cloud task attach <abs-path>` for a task. Auto-scan is OFF.
+4. Use `cloud file send` for **ad-hoc conversation sharing**, or `cloud attach` to add a file to an existing message.
+5. Record the asset ID returned by the service and mention the attachment only after the command succeeded.
+
+## Operating Rules
+
+### Discover
+
+- Choose capability filters based on the **actual task**, not broad role guesses. "Code review" not "developer".
+- Use `--online-only` only when immediate response is required — otherwise async agents can pick up the task.
+- Compare `userId`, `username`, `name`, descriptions, capabilities, and status before picking. Identical names exist.
+- Use the returned `userId` directly, or resolve the returned `username` with `--by-username --workspace-id "$PRISMER_WORKSPACE_ID"` — never invent or guess identifiers from chat text.
+
+### List participants
+
+- This is **scoped to one conversation**, not a global directory. Don't use it to find agents you want to invite.
+- **Humans are not callable** through `send`/`im groups send` to a user-username; they participate as conversation members but aren't routed to. Use the conversation channel itself for human-facing messages.
+- If the list call fails, surface the error. Don't pretend a message can be routed when you don't know who's in the conversation.
+
+### Send
+
+- **Always use the skill** instead of just writing `@username` in plain prose when routing is intended. Plain text `@username` may or may not trigger routing depending on the channel — the CLI guarantees it.
+- **Never send to yourself.**
+- **Don't send to agents outside the conversation** unless this is a direct message (`cloud send <user-id>`).
+- Don't include secrets or **unrelated private context** in the routed message. The agent on the other end gets the full text.
+- For username routing, pass the exact username as the first argument with `--by-username --workspace-id "$PRISMER_WORKSPACE_ID"`; do not hand-write an `@username` mention in the message body.
+
+### File attach
+
+- Don't attach unrelated files or files containing secrets. The recipient gets full access to the asset.
+- Don't rely on **direct upload alone** to make a file visible — verify the response confirms attachment to the conversation/message.
+- Use `--mime` override only when auto-detection would be wrong (rare; usually unset).
+- If upload fails, report the failure and keep the local path available for retry.
+
+### Memory & quoting
+
+- **Pull, don't guess.** If the answer depends on something earlier in the conversation, fetch it (`history` / `quote read` / `summary`) instead of reconstructing it from memory or the user's paraphrase.
+- **`resolve-identifier` ambiguity is a hard stop.** `ambiguous: true` → ask the user; never auto-pick. No match → ask the user; never invent an id. See the disambiguation rule above.
+- **Quote content is authoritative over your recollection.** When a user quotes a message, `quote read` returns the exact text — defer to it even if it differs from what you remember.
+- **Use `summary` to orient, `history`/`quote read` to drill in.** Summaries are lossy by design; never quote a user back a "summary" as if it were their exact words.
+- These reads are membership-scoped — if you get a 403, you're not a participant in that conversation; don't retry against a different conversation id you weren't given.
+
+## Output reporting
+
+After discover: the default table exposes `User ID`, `Username`, `Name`, `Capabilities`, `Status`, and `Description`. Capability names may originate from either legacy strings or structured capability objects, but the table normalizes both to names.
+
+After listing participants: report `<user.id> · <user.username> · <user.displayName> · role=<user.role> · agentType=<user.agentType>`; participant rows do not contain AgentCard capabilities or status.
+
+After send: echo the returned `messageId` and `conversationId`. If the service returned a redacted version (signed/encrypted), surface that.
+
+After file send: echo the `messageId` + the asset's stable identifier (assetId or uploadId).
+
+## Backing capabilities (D22 mapping)
+
+Replaces these v1.x built-in skills: `agent-discover`, `conversation-list-agents`, `agent-send`, `message-send-file`.

package/built-in-skills/agent-meta/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: agent-meta
+scope: common
+description: Inspect, snapshot, publish, and fork Prismer long-running agents through the cloud agent lifecycle API.
+allowed-tools: cloud.agent.spec cloud.agent.snapshot cloud.agent.snapshots cloud.agent.restore cloud.agent.publish cloud.agent.packs cloud.agent.fork prismer.agent.snapshot prismer.agent.publish prismer.agent.fork
+metadata:
+  prismer:
+    category: workflow-core
+    version: "1.0.0"
+---
+
+# Agent Meta
+
+Use this skill when the user asks you to inspect, save, restore, publish, or fork a Prismer long-running agent.
+
+## Commands
+
+- Inspect your 4-tuple spec:
+  `cloud agent spec <agent-id>`
+
+- Save a private owner snapshot:
+  `cloud agent snapshot <agent-id> --label "<label>"`
+
+- Save a snapshot with memory reference:
+  `cloud agent snapshot <agent-id> --include-memory --label "<label>"`
+
+- List snapshots:
+  `cloud agent snapshots <agent-id>`
+
+- Restore from a snapshot:
+  `cloud agent restore <agent-id> <snapshot-id>`
+
+- Publish an agent pack without memory:
+  `cloud agent publish <agent-id> --slug <pack-slug> --version 1.0.0 --license proprietary`
+
+- List public agent packs:
+  `cloud agent packs`
+
+- Fork a pack into a workspace:
+  `cloud agent fork <pack-id-or-slug> --workspace-id <workspace-id> --display-name "<name>"`
+
+The runtime CLI has the same operational verbs for daemon environments:
+
+- `prismer agent snapshot <agent-id>`
+- `prismer agent publish <agent-id> --slug <pack-slug>`
+- `prismer agent fork <pack-id-or-slug> --workspace-id <workspace-id>`
+
+## Rules
+
+- Do not publish memory. The publish path strips memory by default; keep it that way unless a platform policy explicitly changes.
+- Use snapshots for owner backup and restore. Use publish only when the user asks to share or reuse the agent as an Agent Pack.
+- Fork creates a new identity and a clean memory partition in the target workspace.
+- If the user asks to "save your config", create a snapshot rather than publishing.

package/built-in-skills/assets/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: assets
+scope: common
+description: Locate, inspect, and read content-addressed workspace assets — search by filename/metadata, describe before reading bytes, then read bounded ranges. Use whenever the user references an uploaded file, when you need to cite file evidence, or when a task input/output is an asset URI. Executes via the `cloud asset` CLI and tools.
+---
+
+# Assets
+
+Workspace assets are **content-addressed** (SHA-256). Each asset has a stable URI, MIME type, size, and metadata. Treat assets as **opaque bytes you must search → describe → read** in that order. Don't claim you read a file unless a CLI call actually returned its content.
+
+## When to use
+
+- The user references a file by name, path, or `prismer://...` URI and you need its content.
+- A task description includes asset attachments — find them, inspect them, decide if you need to read bytes.
+- You're answering a question that requires citing file evidence (extract text, quote a paragraph, summarize a doc).
+- You need to find a file by hash, filename, or content keyword.
+
+## CLI Reference
+
+### Search
+
+```bash
+cloud asset list                                          # everything in current workspace
+cloud asset list --limit 20 --kind file
+cloud asset list --filename "design-doc*"                 # filename glob
+cloud asset list --mime "application/pdf"                 # by MIME
+cloud asset list --updated-after "2026-05-01"             # recency
+cloud asset by-hash <sha256>                              # exact content lookup
+```
+
+### Describe (metadata only, no bytes)
+
+```bash
+cloud asset get <assetId>                                 # full metadata, no content
+# OR for in-process MCP tools (when daemon exposes them):
+#   prismer.asset.describe { uri | assetId | contentHash }
+```
+
+### Read (bounded ranges only)
+
+```bash
+cloud asset download <assetId> --out ./local-copy         # whole file to disk
+cloud asset download <assetId> --offset 0 --length 4096   # first 4 KB
+# For LLM-friendly text extraction:
+cloud asset read <assetId> --offset 0 --length 4096       # text range read
+cloud asset read <assetId> --as-text                      # full text (for small text-like assets)
+```
+
+### Upload / Sync
+
+```bash
+cloud asset upload ./report.pdf                           # → asset record + content hash
+cloud asset upload ./report.pdf --conversation-id <id>    # pin to conversation
+cloud asset sync                                          # refresh local cache index
+```
+
+## Workflow
+
+1. **Search first** — use `cloud asset list` with filename / MIME / hash filters unless the user gave you an exact ID or URI.
+2. **Describe before reading bytes** — `cloud asset get <id>` to confirm MIME, size, and that this is the right file.
+3. **Read bounded ranges** — `--offset` + `--length`. Start with a small range (4 KB) to identify encoding/structure, then expand only if needed.
+4. **Preserve the locator** — record the asset ID, content hash, and URI in your reply so the user can follow up.
+
+## Operating Rules
+
+### Search
+
+- Don't guess asset identifiers when `asset list` can locate them. Filename + size + workspace = usually unique.
+- Prefer **exact** filters (hash, full filename, MIME) over broad terms.
+- Content search is **best-effort for text-like assets only**. PDFs, images, binaries won't match content queries — search by metadata.
+- Use a small `--limit` for targeted lookups; expand only when the first batch misses.
+
+### Describe
+
+- **Always describe before reading.** Metadata tells you whether reading is safe (text vs binary, size, encoding).
+- Don't treat metadata as proof of file contents — title and MIME can lie. The content hash is the only authoritative identity.
+- If multiple locators disagree (e.g. filename matches two assets with different hashes), **stop and re-search** rather than reading the wrong file.
+- Avoid reading binary or image-heavy assets directly. For images, use `cloud parse` (OCR) or a vision-capable downstream tool; for PDFs, use `cloud parse`.
+
+### Read
+
+- **Never load an entire large file** — `--length` caps reads. Start at 4 KB, expand only when the answer requires it.
+- Byte offsets don't align to line or character boundaries in multibyte text — handle the partial-token edge at the read boundary.
+- Watch the `truncated` flag in the response. If set, plan additional reads or tell the user the answer is based on a partial read.
+- Report partial reads explicitly when drawing conclusions from excerpts ("based on the first 8 KB of `<filename>`...").
+
+### Cite
+
+- When citing file evidence, **include the asset ID/URI and the locator** (offset + length, page number, or hash). The user needs to be able to follow up.
+- Never claim you read an asset unless a CLI/tool call **succeeded** with content in the response. Hallucinated reads are the #1 trust failure.
+
+## Output reporting
+
+After search: list matches with `<assetId> <filename> <mime> <sizeBytes>`. If 0 matches, say so and suggest broader filters.
+
+After describe: surface MIME, size, and any structured metadata fields relevant to the user's question (page count for PDFs, dimensions for images, etc.).
+
+After read: include the asset locator + range + content. If `truncated: true`, say "(partial — read X of Y bytes)".
+
+## ContentBlock output (v2.0 §4.6 / Gap E-⑤)
+
+When this skill resolves an **image** asset for downstream rendering, emit a
+ContentBlock pointing at the asset id rather than inlining bytes or a
+pre-signed URL into prose:
+
+```json
+{ "kind": "image", "assetId": "<assetId>", "mediaType": "image/png", "alt": "<one-line desc>" }
+```
+
+When it resolves an existing **file** asset (PDF, CSV, archive), do not copy it
+into `$PRISMER_ARTIFACTS_DIR` or create a duplicate upload. Return the existing
+asset through the structured ContentBlock attachment using its authoritative
+`assetId`:
+
+```json
+{ "kind": "file", "assetId": "<assetId>", "mediaType": "application/pdf", "filename": "<original>" }
+```
+
+Do NOT paste raw bytes or `data:` URIs into the reply body — they bypass the
+content-addressed store, defeat caching, and make follow-up retrieval
+impossible. The chat renderer reads ContentBlock attachments and surfaces
+them as previews. If the user explicitly requests a newly generated local
+file, that is a separate file carrier: write it under `artifacts/` and run
+`cloud deliver <abs-path>` or `cloud task attach <abs-path>` explicitly.
+
+## Backing capabilities (D22 mapping)
+
+Replaces these v1.x built-in skills: `asset-search`, `asset-describe`, `asset-read`.
+
+Implements Gap E-⑤ (built-in skill multimodal output) for the asset family —
+`assets.describe` / `assets.read` outputs flow through dispatch reply
+attachments (`AgentDispatchReplyPayload.attachments` typed as `{kind, assetId}`
+which maps to ContentBlock at chat-render time).

package/built-in-skills/browser-use/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: browser-use
+scope: common
+description: LLM-driven browser automation via the pre-installed browser-use library (chromium already in the image). Use whenever the task needs to interact with web pages beyond a single fetch — multi-step navigation, form filling, clicking, scrolling, structured data extraction, screenshots, or tasks the plain web tools can't complete. Runs as a Python script against the built-in chromium; LLM goes through the Prismer gateway (no external LLM key needed).
+---
+
+# Browser-Use (Web Automation)
+
+The sandbox image ships `browser-use` (installed in `/home/user/.venv`) and a full
+chromium build (playwright). This skill drives them: write a short Python script
+with `Agent(task=..., llm=..., browser=...)`, run it, report the result.
+
+## When to use
+
+- Multi-step web tasks: search → open → extract → compare → download
+- Form filling / login flows / clicking through pages
+- Structured extraction (tables, listings, prices) that a single fetch can't parse
+- Screenshots / visual confirmation of a page state
+- Anything needing JS-rendered content (SPA pages the fetch tools miss)
+
+For a single plain fetch, prefer the existing web tools (lighter). Reach for
+browser-use when they come back empty or the task is interactive.
+
+## How to run
+
+```bash
+# chromium executable (version dir may change — resolve dynamically):
+CHROME="$(find /home/user/.cache/ms-playwright -name chrome -type f | head -1)"
+
+# LLM = our gateway (OpenAI-compatible). PRISMER_BASE_URL / PRISMER_API_KEY
+# are already in the environment; never hardcode them in the script.
+cat > /tmp/bu_task.py <<'PY'
+import os, asyncio
+from browser_use import Agent, ChatOpenAI, Browser
+
+async def main():
+    llm = ChatOpenAI(
+        base_url=f"{os.environ['PRISMER_BASE_URL']}/api/v1",
+        api_key=os.environ['PRISMER_API_KEY'],
+        model=os.environ.get('PRISMER_MODEL', 'deepseek-v4-flash'),
+        temperature=0.0,
+        # REQUIRED for the Prismer gateway: browser-use defaults to forcing
+        # JSON-schema structured output (response_format=json_schema) which
+        # our upstream models reject with 400 "response_format type
+        # unavailable" (verified 2026-08-07). Disable it; the agent still
+        # extracts via its normal flow.
+        dont_force_structured_output=True,
+    )
+    browser = Browser(
+        headless=True,
+        executable_path=os.environ['CHROME'],
+    )
+    agent = Agent(
+        task="<TASK>",  # be specific: steps, URLs, what to extract, output format
+        llm=llm,
+        browser=browser,
+    )
+    history = await agent.run(max_steps=30)
+    print("RESULT:", history.final_result())
+    print("URLS:", history.urls())
+    print("ERRORS:", history.errors())
+    await browser.close()
+
+asyncio.run(main())
+PY
+CHROME="$CHROME" /home/user/.venv/bin/python /tmp/bu_task.py
+rm -f /tmp/bu_task.py
+```
+
+## Task-writing rules (from browser-use docs)
+
+- **Be specific**: `"Go to https://…, use extract with query 'first 3 quotes and their authors', save to quotes.csv via write_file"` — open-ended tasks fail.
+- **Name actions**: "use search action for …", "use click to open first result in a new tab", "use send_keys with 'Tab Tab Enter'" — the agent maps these to its built-in tools.
+- **Error recovery**: if navigation is blocked, fall back to a search engine; if a click fails, use keyboard navigation (`send_keys`).
+- **max_steps**: default 100; keep 30 for focused tasks, raise for long flows.
+- **Anti-bot**: if a page blocks automation, try `use_cloud=True` — NOT available here (no Browser-Use Cloud key). Fall back to search/cache.
+
+## Environment facts
+
+| Item | Value |
+| --- | --- |
+| Python | `/home/user/.venv/bin/python` (browser-use installed here) |
+| Chromium | `$(find /home/user/.cache/ms-playwright -name chrome -type f \| head -1)` |
+| LLM | Prismer gateway (`PRISMER_BASE_URL` + `PRISMER_API_KEY`, OpenAI-compatible) |
+| Model | `PRISMER_MODEL` env (default `deepseek-v4-flash`) — adjust for the task |
+| Telemetry | browser-use collects anonymous telemetry by default — set `ANONYMIZED_TELEMETRY=false` |
+
+## Output contract
+
+Report to the user: `history.final_result()` (the extracted answer), the URLs
+visited, and any errors. If `history.is_successful()` is False, say so plainly
+with `history.errors()` — do not invent a completion. Attach screenshots
+(`history.screenshot_paths()`) as task assets when they matter.