@prismer/runtime 2.0.7 → 2.0.8

package/CHANGELOG.md

@@ -2,6 +2,207 @@
 
 ## Unreleased
 
+### Added
+
+- **`mode:'message-attach'` for `POST /local/deliver`** (release202/09 P5#3, 动作
+  A2). Appends a freshly-uploaded asset to an ALREADY-SENT message. Body adds
+  `messageId` (and requires `conversationId`); the daemon uploads with its own
+  credential (same `deliverFile` upload path + agent-output-policy +
+  magic-bytes as the other modes) then POSTs the resulting `assetId` to the
+  cloud conversation-scoped attach route
+  `POST /api/im/messages/:conversationId/:messageId/attach` (X-IM-Agent stamped
+  so the cloud sender-check resolves the same agent that authored the message).
+  Unlike `mode:'send'` it does not start a new message; unlike `mode:'attach'`
+  it does not ride the reply. Wired from the in-container `cloud attach` SDK
+  command. Complements `mode:'attach'` (reply does not exist yet) — A2 is for a
+  reply that already exists.
+- **`mode:'task-attach'` for `POST /local/deliver`** (release202/09 P5#2, 动作
+  ③). The daemon uploads the file as a **task-bound** asset (`deliverFile`
+  already stamps `sourceTaskId = taskId`), which the cloud `POST /assets`
+  handler auto-rolls onto the kanban task card
+  (`appendOutputAssetIdToTask` + `reemitTerminalDigestForAssetArrival`) plus the
+  asset library. Unlike `mode:'attach'` it does **not** call
+  `recordDeliveredAsset` (a kanban task may run without a chat reply — its
+  products belong on the card, not a turn reply) and unlike `mode:'send'` it
+  posts no message. No new cloud HTTP call is needed: the existing
+  `sourceTaskId`-driven rollup is the kanban + library landing. Wired from the
+  in-container `cloud task attach` SDK command.
+- **Explicit agent-driven file delivery** (release202/09 P2). New daemon
+  local-server route `POST /local/deliver` (`local-server.ts` `onDeliver` +
+  `daemon/asset/deliver.ts` `attachDeliver`): the in-container agent's
+  `cloud deliver` / `cloud file send` proxy here so the daemon (which holds a
+  usable IM credential the agent lacks) performs the upload + delivery. Body
+  `{ taskId, path, mode:'attach'|'send', conversationId?, agentUsername? }`.
+  `mode:'attach'` (动作 A) records the assetId onto `ArtifactsWatcher`'s
+  existing `pendingByTask` so dispatch-end `flushPending` rides it on
+  `reply.assetIds`; `mode:'send'` (动作 B) posts a standalone message with the
+  asset attachment, stamped as the agent (`X-IM-Agent`). New public
+  `ArtifactsWatcher.recordDeliveredAsset(taskId, assetId)` +
+  `ArtifactsWatcher.deliverFile(...)`. `PRISMER_CONVERSATION_ID` is now
+  injected into the agent env for 动作 B targeting.
+
+### Changed
+
+- **ArtifactsWatcher directory auto-scan is now flag-gated OFF by default**
+  (release202/09 P2). New `ArtifactsWatcherOptions.autoScan` (default
+  **false**): when off, the polling scan / `scanNow()` are no-ops (no implicit
+  directory-magic), but `pendingByTask` / `flushPending` /
+  `recordDeliveredAsset` / `upload` all still work. The legacy scan code is
+  retained behind the flag and re-enablable via `PRISMER_ARTIFACTS_AUTOSCAN=1`.
+  File delivery is now EXPLICIT (`cloud deliver` / `cloud file send`).
+
+- **Hermes one-shot task-run dispatch via `/v1/runs`** (release202/08 Phase 1,
+  flag-gated **default OFF**). New `HERMES_TASK_RUNS_DISPATCH` env flag. When ON
+  and a dispatch is classified as a one-shot **run** (execution context
+  `task-run` AND no triggering chat sender — pure kanban / scheduled fire /
+  programmatic orchestration), the hermes adapter routes through the new
+  `runs-dispatcher.ts` (`POST /v1/runs` → 202 + run_id, then `GET
+  /v1/runs/{id}/events` SSE) instead of the stateful Sessions API. The run is
+  **stateless** — no hermes session, no `local_run_sessions` mapping; its input
+  is the bare task prompt (+ inline asset blocks) and `system_prompt` embeds a
+  standalone `<execution_context type="task-run">` block (no SEED/THIN
+  envelope, no participants/current_turn_sender). Multimodal image_url parts and
+  the `/events` SSE parser (`consumeSessionsSse`) are reused verbatim. Chat
+  turns (group/dm with a triggering sender) keep going through
+  `dispatchViaSessions` unchanged. With the flag OFF the router is inert —
+  `deriveDispatchKind` returns `'turn'` unconditionally, so 100% of traffic
+  stays on Sessions (release201/25 §16.4 A3 behaviour, byte-for-byte).
+  `adapters/hermes/{flag.ts,runs-dispatcher.ts,index.ts}`,
+  `daemon/conversation-context.ts` (`renderExecutionContextXml`).
+
+- **Role templates declare `taskDispatchScope`** (release202/08 §3.2 P3 —
+  config-driven, role-agnostic task-dispatch permission). A role's template /
+  agent-profile `config.taskDispatchScope` (`'any' | 'agents' | 'self' |
+  'none'`) is the middle layer of cloud's three-layer dispatch resolver
+  (`workspace.metadata.dispatchPolicy` > role/profile config >
+  `DEFAULT_DISPATCH_POLICY`), so a NEW role gets its dispatch capability by
+  declaring this field — the cloud resolver needs zero code changes. Declared:
+  `ceo` → `any` (orchestrator, sibling of `taskAuthority`), `product-manager`
+  → `agents` (delegates to engineer/verifier, never a human peer), `engineer`
+  / `researcher` / `verifier` → `none` (executors, no peer delegation).
+  `templates/roles/*.json`.
+
+### Fixed
+
+- **Model reasoning trace restored in agent messages on the hermes sessions
+  stream** (regression from `2cdd2cad`, 2026-05-29). When dispatch migrated from
+  `/v1/runs` (legacy `consumeSse`) to the sessions stream (`consumeSessionsSse`),
+  the deleted `reasoning.available` handler was the only path feeding the model's
+  thinking trace into `recorder.recordReasoningChunk(...)`, so reasoning stopped
+  becoming `reasoning_chunk` steps and the expandable reasoning block vanished
+  (tool-call steps still showed — separate handlers). Root cause of the shape
+  mismatch: the sessions endpoint (`api_server.py:1585-1590 _tool_progress`)
+  does **not** emit `reasoning.available`; it **remaps** reasoning into a
+  `tool.progress` event with `tool_name: '_thinking'` and the text in `delta`
+  (not `preview`), which the old `tool.progress` handler — reading only
+  `preview` — silently dropped. Fix: `tool.progress` now reads `delta` first and
+  routes reasoning through `recordReasoningChunk` + a `kind:'reasoning'`
+  onProgress hint (no `lastProgress` bump — reasoning is not a progress unit for
+  the reaper, mirroring the deleted handler). Also added a defensive top-level
+  `reasoning.available` case (accepts `text`/`reasoning_content`/`delta`/
+  `content`) for the `/v1/runs`-style direct event in case a hermes build
+  surfaces it on the sessions stream. Guarded against empty strings. Covered by
+  `test/reasoning-sse.test.ts`.
+- **Hermes adapter no longer reuses a stale/foreign gateway squatting on the
+  port** (release202/07 robustness). `ensureService` decided reuse-vs-respawn
+  with the UNAUTHENTICATED `/health` check, which an old-version (pre-sessions,
+  404 on `/v1/capabilities`) or wrong-`API_SERVER_KEY` (401) gateway — e.g. an
+  orphan we spawned in a PRIOR daemon session — answers `200` to. Reusing such a
+  squatter made the capability gate later trip with the misleading "Hermes does
+  not advertise session_chat_streaming", failing every dispatch after a daemon
+  restart until the orphans were manually `pkill`ed. Now the reuse decision is
+  AUTHENTICATED: a hermes counts as reusable only if it answers
+  `GET /v1/capabilities` as ours; otherwise the adapter frees the port
+  (`stopStaleHermesGateways`, matches `-p <profile>` / `API_SERVER_PORT`) and
+  spawns a fresh gateway with our key — self-healing on restart. The capability
+  probe result is reused as the pinned `HermesService.capabilities` (no extra
+  fetch on the happy path). `adapters/hermes/index.ts` `ensureService`.
+
+### Changed
+
+- **Provider chain routing — `proxyProvider` widened from `'newapi'|'deepseek'`
+  enum to any chain id** (release202/07). The codex adapter previously hardcoded
+  the gateway base_url to `<PRISMER_BASE_URL>/api/v1` "regardless of
+  proxyProvider" — silently dropping a `deepseek` selection so every Codex
+  request landed on newapi (and 500'd for deepseek-only models). Now both the
+  codex and hermes adapters resolve `base_url` by the configured chain:
+  `newapi`/`default` → `/api/v1`; any other chain → `/api/v1/proxy/<chain>`
+  (codex appends `/responses`, hermes `/chat/completions`). The cloud walks the
+  chain (source1 → source2 → …) with per-source fallback.
+  - `adapters/codex/index.ts` — `proxyProvider` schema `z.enum` → `z.string`;
+    `resolveCodexPrismerProvider` honors the chain in base_url.
+  - `adapters/hermes/index.ts` — same schema widening; `resolvePrismerProviderBaseUrl`
+    generalized from the `deepseek`-only branch to any chain id.
+
+- **Document-deliverable SOP — markdown files, not chat prose** (B-line,
+  release201/3x). Codified the rule that document-type deliverables
+  (research memos, PRDs, reports, reviews, summaries) MUST be written as
+  markdown files into `${PRISMER_OUTBOX_DIR}/` (physically
+  `${TASK_WORKDIR}/result/`) so the daemon outbox-watcher auto-registers
+  them as task-bound IMAssets; the chat reply is a summary/teaser, not the
+  deliverable itself.
+  - `built-in-skills/tasks/SKILL.md` §产物输出 — added §文档型交付物 (= markdown
+    文件) sub-section referencing the real `${PRISMER_OUTBOX_DIR}` /
+    `result/` auto-archival wiring (`dispatch.ts` `appendArtifactsInstruction`,
+    `PRISMER_ARTIFACTS_DIR` env). Filenames/structure are skill-defined
+    (no hardcoded schema).
+  - `templates/roles/{researcher,product-manager,engineer}.json`
+    `systemPrompt` — replaced the old "upload as workspace file +
+    prismer://file URI" convention with the markdown-to-`result/` SOP and a
+    summary-vs-deliverable distinction; each points at the tasks skill SOP.
+  - `templates/roles/verifier.json` `systemPrompt` + `operatingPrinciples` —
+    extended the same SOP to the verifier: the full acceptance record
+    (per-criterion method / params / observed result / repro steps) is now a
+    markdown file in `${PRISMER_OUTBOX_DIR}/` (e.g. `verification-report.md`),
+    auto-archived as a task-bound IMAsset. Binary evidence (screenshots /
+    benchmark output / logs) still goes via `cloud task attach` +
+    `evidenceRefs`; the `verify-criterion --note` stays a summary. The two
+    paths are complementary.
+  - Audit (cross-referenced docs): `templates/roles/ceo.json` left unchanged —
+    it already routes all file deliverables through `office-artifacts` /
+    `image-generate` / `canvas-design` / `web-artifacts-builder` skills (no
+    legacy "upload as workspace file" anti-pattern), so it needs no SOP
+    backfill. `templates/roles/skill-author.json` left unchanged — its
+    deliverable is a structured `status=draft` IMSkill submitted via
+    `cloud skill draft create`, not a chat-bound markdown document, so the
+    `result/` SOP does not apply.
+
+### Added
+
+- **Adapter version probe with KNOWN_GOOD pinning** (Release 201 v2.0.7
+  post-release P1). All four adapters (hermes / codex / claude-code /
+  openclaw) now run `<binary> --version` on startup, parse the result,
+  warn when the detected version drifts below the per-adapter
+  `MIN_VERSION`, and warn when it diverges from `KNOWN_GOOD`. Pins are
+  declared in the new `sdk/prismer-cloud/runtime/src/adapters/known-versions.ts`
+  manifest:
+
+  - hermes: MIN=`0.0.0` (soft-pass), KNOWN_GOOD=`unknown` — TODO(v2.0.8):
+    pin after cookbook run exercises a real hermes binary
+  - codex: MIN=`0.0.0` (soft-pass), KNOWN_GOOD=`unknown` — TODO(v2.0.8):
+    pin after cookbook run against `@openai/codex`
+  - claude-code: MIN=`2.0.0` (Wave-4 flag set requires 2.x), KNOWN_GOOD=
+    `unknown` — TODO(v2.0.8): pin knownGood after cookbook run
+  - openclaw: MIN=`2026.4.0`, KNOWN_GOOD=`2026.4.0` — wrapper carries a
+    2026.4.x stderr-bleed workaround, revisit once upstream fixes
+
+  Honesty note: three of the four pins are intentionally unpinned at
+  the floor — this is the governance scaffold, not a claim that we've
+  validated specific upstream revs. Bumping the pins is a v2.0.8 task
+  blocked on real cookbook runs.
+
+- New `sdk/prismer-cloud/runtime/src/adapters/version-check.ts` —
+  `compareSemver`, `isVersionInRange`, `parseVersionFromStdout` shared
+  helpers so the four adapters do not redefine their own semver math.
+
+- `/healthz` `adapters[]` entries now carry `minVersion` + `knownGood`
+  alongside the existing `name` / `ready` / `version` fields so cloud
+  debug-pipeline can flag drift between detected and tested versions.
+
+- `test/adapters-version-check.test.ts` — vitest regression covering
+  compareSemver, range checks, pre-release stripping, parseVersionFromStdout,
+  and the `ADAPTER_KNOWN_VERSIONS` manifest shape.
+
 ## v2.0.1 — 2026-05-21 — Skill multi-file manifest protocol (§A.7 Phase 1) + URL asset fetch
 
 Coordinated v2.0.1 patch release. `/VERSION` → 2.0.1. Internal preview only;

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

@@ -0,0 +1,235 @@
+---
+name: agent-coordination
+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>`** (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).
+
+## 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                                    # all visible agents
+cloud discover --capability code-review           # filter by capability
+cloud discover --online-only                      # only online agents
+cloud im contacts                                 # your contact list
+```
+
+### List participants in a conversation (scoped)
+
+```bash
+cloud im conversations                            # all your conversations
+cloud im conversations --unread                   # unread only
+cloud im conversations <conversationId> --members # agents + humans in this conversation
+```
+
+### Send a message
+
+```bash
+# Direct message to an agent
+cloud send <to-username> "Please review the PR"
+cloud send <to-username> "## Report" -t markdown
+cloud send <to-username> --reply-to <messageId> "Acknowledged"
+
+# 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>
+```
+
+### Send with attached file
+
+> **决定怎么交付文件 — 先读这条:**
+>
+> - **你这次任务的最终交付物（要跟你的回复一起出现的产物）** → 写进
+>   `${PRISMER_ARTIFACTS_DIR}`（当前 dispatch 的 `artifacts/` 目录）。
+>   daemon artifacts-watcher 会自动归档并把 assetId **挂到你这条 dispatch
+>   回复上**，于是「文件 + 你的总结文字」是**同一条消息**。这是默认路径。
+> - **`cloud file send` 会另起一条独立消息**（先于/晚于你的回复单独落），
+>   只适合「对话进行中临时丢个文件给对方看」这种 ad-hoc 分享，**不要**用它
+>   交付任务最终产物 —— 否则用户会看到「一条只有文件的消息」+「一条只有
+>   文字的消息」分裂开（release201/30 §4 + §7）。
+
+```bash
+# 默认：最终交付物写进 artifacts/，随你的回复单条附带（无需任何 send 命令）
+cp ./report.pdf "${PRISMER_ARTIFACTS_DIR}/"     # 然后正常回复即可（平台自动收尾）
+
+# 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
+
+# On hermes (no per-dispatch env): also pass --run-id "<run_id>" (copied from
+# <execution_context>) so the daemon proxy activates. Spawn adapters
+# (claude-code / codex) have the env set and don't need it.
+cloud file send <conversationId> ./report.pdf --run-id "<run_id>"
+
+# 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>
+```
+
+### 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
+
+# On hermes (no per-dispatch env): also pass --run-id "<run_id>" and
+# --conversation-id "<conversation_id>" (both copied from <execution_context>)
+# so the daemon proxy activates + the attach route knows which thread the
+# message lives in. Spawn adapters (claude-code / codex) have the env set.
+cloud attach <messageId> ./addendum.pdf --run-id "<run_id>" --conversation-id "<conversation_id>"
+```
+
+### 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` returns the `agents` array with `username`, `id`, `displayName`, `agentType`, `capabilities`. Don't `discover` if the target is already in the conversation — it leaks agents outside the routing scope into your candidate set.
+2. **Pick the target.** Match on capability + status. Exclude your own username. If multiple match, pick the most specific capability and surface the choice to the user if unclear.
+3. **Compose a routed message** with: requested action, context, constraints, expected output. Don't bury the ask in pleasantries.
+4. **Send with the exact `to-username`** the listing returned. Don't transform "@Alice" → "alice" by yourself — use the exact string the service returned.
+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. Prefer writing new outputs under `PRISMER_ARTIFACTS_DIR` (the current dispatch's `artifacts/` dir) — the daemon artifacts-watcher auto-archives every file there as an IMAsset and attaches the IDs to your dispatch reply. See release201/30 §4 for the full pipeline.
+3. Use this skill for **existing files elsewhere** or when you need an explicit message title alongside the attachment.
+4. Record the uploaded asset ID returned by the service.
+5. Mention the attachment in the user-facing reply **only after** the send/queue 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 names, IDs, descriptions, capabilities, and status before picking. Identical display names exist.
+- Use returned IDs/usernames for routing — 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.
+- If routing involves `@username` shorthand in the message body, prefer letting the CLI add it via `--to-username` over hand-writing the mention.
+
+### 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: list each candidate as `<username> · <displayName> · capabilities=[a,b,c] · status=<online|offline>`.
+
+After listing participants: same format, scoped to the conversation.
+
+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,52 @@
+---
+name: agent-meta
+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,131 @@
+---
+name: assets
+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 a **file** asset (PDF, CSV, archive) the reply should include
+the asset as an attachment (auto-handled by writing into
+`$PRISMER_ARTIFACTS_DIR` — daemon's artifacts-watcher scans the dispatch's
+`artifacts/` dir and auto-archives + attaches per release201/30 §4 — or
+explicitly as):
+
+```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 automatically.
+
+## 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).