--- name: pull-remote-agent-context description: > Read a deployed Mesh agent's conversation history, artifacts, or workflow design from the `mesh` CLI. Activate when asked to pull/read/inspect a hosted agent's conversation transcript, list its conversations, fetch a workflow artifact/design it produced, or when the `agent_*` MCP tools (agent_list_conversations, agent_check_conversation, agent_get_artifacts, agent_get_workflow_design) are unavailable and the same read needs to happen via the CLI instead. metadata: version: '0.1' category: 'tooling' type: intent --- # Pull a deployed agent's conversation context `mesh conversations` (alias `mesh conv`) reads a deployed Mesh agent's conversations directly from its agent-api, over the same read surface the `agent_*` MCP tools use. This is the CLI-native path when those MCP tools aren't wired up, or when you're already in a shell. ## The recipe ```bash mesh conversations list --target <name> # discover conversation ids mesh conversations show <id> --target <name> # render the transcript mesh conversations artifacts <id> --target <name> # list its artifacts mesh artifacts get <id>:<artifactId> --target <name> # download artifact files ``` ## One-shot: `mesh conversations pull` (recommended) To pull a whole conversation + everything it produced into a session bundle in one command — the fast path when you're feeding a workflow-builder conversation into a coding session: ```bash mesh conversations pull <id> --target <name> -o <dir> ``` It writes: ``` <dir>/ index.json # conversation meta, artifact map, saveLocations, subagent tree, warnings[] conversation.md # the transcript (intent) designs/<slug>/ design-ir.json # the LIVE design IR (authoritative; resolved server-side) manifest.json # realized bindings (signals + service ops) — from the design's vcs folder README.md # + any other docs the design's folder holds, verbatim design-ir.saved.json # ONLY if the saved IR drifted from live (a warning is emitted) ui/<slug>.json # agent-built UI specs subagents/<childId>.md # recursive delegate transcripts (childId "/" → "__") ``` Key behaviors: - **Designs come from the agent-api**, which resolves the latest IR itself — no draft-branch guessing for the IR. - **Each design also pulls its OWN vcs folder verbatim** (a scoped shallow clone of just that design's repo, resolving the `drafts/*` ref that carries it), so docs/notes beyond the IR ride along. `--no-vcs` skips this (IR-only). - **Everything else the conversation referenced is cataloged, never cloned** — any tenant's knowledge-base / context repo (a `resource: vcs` drive-ref, whatever it's named) and any other artifact kind appears in `index.json.references[]` with a ready-to-run `pullHint`, but its content is not pulled. Pull a **specific** doc on demand (one path, not the whole repo) with `mesh vcs get <repo> <path> --target <name>` (CLI) or `agent_get_repo_doc` (MCP) — browse `conversation.md` to see which docs matter. - **Subagents recurse by default** (cycle-guarded); `--no-recursive` for direct delegates only. - **Best-effort**: nothing aborts the pull — per-unit failures land in `index.json.warnings[]`. Reach for the granular verbs below when you want just the transcript, just the artifact list, or a single artifact's files. `list`/`show`/`artifacts` all accept the same `--target <name>` / `--api-url <url>` / `--context <ctx>` / `--json` options (`mesh artifacts get` takes `--target`/`--api-url`/`--context` plus `-o/--output <dir>`, no `--json` — it always writes files). Start with `list` unless you already have a conversation id. ## The shared registry (`--target`) `--target <name>` resolves against `~/.config/mesh/agent-targets.json` (override with env `MESH_AGENT_TARGETS`) — **the exact same registry and names the MCP `agent_*` tools use** (`@mesh-tech/agent-targets`, consumed by both `mesh-cli` and `@mesh-tech/mesh-mcp`). `--target fub` on the CLI and `target: "fub"` on `agent_send_message` hit the same origin with the same identity. A registry entry looks like: ```json { "defaultTarget": "hub", "targets": { "fub": { "apiBaseUrl": "https://...", "conversationPathPrefix": "/c", "tenant": "fub", "env": "dev", "loginContext": "mesh.dev" } } } ``` **`mesh agent-targets add/refresh/list` (the SSM-backed generator) is NOT shipped yet.** Do not tell a user or agent to run it. Until it exists: - If the registry file already has the target you need, just pass `--target <name>`. - If it doesn't (or the file doesn't exist), either hand-author an entry in `~/.config/mesh/agent-targets.json` (schema above; see `packages/agent-remote/agent-targets.example.json` for a fuller example), or skip the registry entirely and pass `--api-url <url>` (+ `--context <ctx>`, default `mesh.dev`) ad hoc — no registry lookup happens in that case. Resolution precedence: `--api-url` (if given) > `--target` (if given, resolved from the registry) > the registry's `defaultTarget` > the `AGENT_API_URL`/`API_URL` env vars > `http://localhost:8787`. An unknown `--target` name errors listing the available names. ## Auth model Auth is a Zitadel bearer, the same one `mesh login <context>` already caches — no AWS role needed just to read. Each registry entry's `loginContext` picks which cached login to use (default `mesh.dev`); with `--api-url`, pass `--context <ctx>` to pick it explicitly. One `mesh login mesh.dev` (device flow works headless) reaches any deployed agent through its oauth2-proxy. A 401/403/redirect from an agent-api call means auth didn't reach it — re-run `mesh login <that context>`. ## MCP tools unavailable? Same registry, direct CLI path When the `agent_*` MCP tools (`agent_list_conversations`, `agent_check_conversation`, `agent_get_artifacts`, `agent_get_workflow_design`, `agent_list_targets`, ...) aren't reachable — no MCP server configured, or you're a plain shell/CLI agent — `mesh conversations` reaches the identical agent-api directly, with the same `--target` name and the same login. Nothing is lost by going CLI-only: list → show → artifacts covers list/read/artifacts; `mesh artifacts get` covers file export; workflow-design (the MCP's `agent_get_workflow_design`) has no direct CLI verb yet — get it via `mesh conversations artifacts <id>` (artifact index) plus `mesh artifacts get <id>:<artifactId>` for the IR/files. ## Transcript break-glass: `conversation_unavailable` `mesh conversations show <id>` reads the **live** worker (fast, decoded). If the worker can no longer replay that workflow (code drift), it 503s with `conversation_unavailable` and the CLI's error message already includes the next step: ```bash mesh temporal recover-conversation <id> ``` This reconstructs the transcript from durable Temporal history instead (needs the Temporal encoding key; see the `core` skill's `temporal` row). Add `--snapshot` for a structured, store-ready `{ messages, artifacts, focus }` blob instead of a markdown transcript. ## Output - Piped or redirected (non-TTY), or `--json` passed: compact JSON, one line, field names mirroring the agent-api payload — parse this. - A TTY without `--json`: an aligned table (`list`: double-space-padded columns, `ID TITLE UPDATED` — NOT `·`-separated; `artifacts`: `ARTIFACT-ID · KIND · TITLE` + a ready-to-copy `mesh artifacts get <id>:<artifactId>` download line; `show`: `role: content` blocks with `tool-calls:`/`artifacts:` notes). An agent scripting this should just pipe (`mesh conversations list --target fub | jq ...`) rather than pass `--json` — output auto-detects non-TTY. ## Errors, decoded | Symptom | Meaning | Fix | |---|---|---| | `auth did not reach the agent` | 401/403/redirect | `mesh login <loginContext>` (the target's, or `--context`) | | `conversation/artifact not found ... (<id>)` | 404, or not owned by this identity | `mesh conversations list --target <name>` to see valid ids | | `... conversation_unavailable ... try: mesh temporal recover-conversation <id>` | 503, worker can't replay | run the suggested `recover-conversation` | | `Unknown target "<name>". Available: ...` | `--target` not in the registry | pick a listed name, hand-author the entry, or use `--api-url` | | `No agent target given and no registry ...` | no `--target`/`--api-url` and no registry file | pass `--api-url <url>`, or hand-author `~/.config/mesh/agent-targets.json` | | `Registry at <path> is invalid: ...` | the JSON fails schema validation | fix the file, or pass `--api-url` | ## See also - `libs/mesh-cli/skills/core/SKILL.md` — full `mesh` command reference, including the `conversations`/`artifacts`/`temporal` rows this skill builds on. - `packages/agent-remote/agent-targets.example.json` — a worked registry file with `hub`/`fub`/`acme`/`local` entries.