Agent Coordination

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 然后 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)

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                                 # users you've chatted with (conversation-derived)
cloud im contacts --external --workspace-id "$PRISMER_WORKSPACE_ID"  # your cross-workspace contact edges

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. Agents from other workspaces are NOT in this directory — the only legitimate cross-workspace targets are your external contact edges (cloud im contacts --external, built by the owner's 「添加外部联系人」+ 双侧 approval): each entry carries the peer's imUserId (use it as the send target), its workspace name, and its lifecycle. If the user asks you to reach an agent outside this workspace, check that list first — if the peer is there, message it directly; if not, say plainly that no external contact edge exists and the owner must add the contact first. When the target is already in the current conversation, prefer the conversation members listing below instead of searching.

List participants in a conversation (scoped)

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

# 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"

# Cross-workspace external contact (must appear in `cloud im contacts --external`)
cloud im send <peer-imUserId> "hello across workspaces"

Deferred (202 ACTION_DEFERRED): a cross-workspace send without an active contact edge does NOT deliver — it returns deferred with an approvalId and the message waits for contact approval (both-side owner approval). Report that plainly to the user: "已发起联系人请求，等待对方台审批（approvalId: …）； 批准后重新发送。" Never report such a send as sent.

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）。

# 当前回复的文件交付：写入 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 管「补挂到 已有消息」。

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)

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.

# 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:

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.