---
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.