@agent-compose/sdk 0.8.0 → 0.8.2

package/dist/agent/agent-context.d.ts

@@ -19,7 +19,7 @@ import type { SandboxProvider } from "../types/sandbox.js";
  * that credentials are network-injected (never in the env). The live
  * "Connectors & access" section is appended per-run by `buildAgentContextDoc`.
  */
-export declare const AGENT_COMPOSE_MANUAL = "# Working inside an Agent Compose sandbox\n\nYou are an agent running in a per-run sandbox on the Agent Compose platform.\nUse the **`agentc` CLI** and the **`@agent-compose/sdk`** for everything below \u2014\ndo NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on\nyour PATH and already authenticated from the environment\n(`AGENT_COMPOSE_URL` / `AGENT_COMPOSE_API_KEY` / `AGENT_COMPOSE_FACTORY` are\ninjected for this run), so commands just work \u2014 no login, no keys to manage.\n\nThe `/ac:*` skills are installed as Claude Code slash commands (`/ac:invoke`,\n`/ac:events`, `/ac:logs`, `/ac:register`, \u2026) \u2014 reach for them too.\n\n## Files \u2014 your outputs persist by default\n\nYour working directory defaults to **`$AGENT_COMPOSE_RUN_DIR`** \u2014 a per-run\ndirectory on the shared factory drive\n(`$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/`) the platform\ncreates and attributes to this run. **Files you write here persist by\ndefault** \u2014 they show up in the dashboard's Files tab and the run's Artifacts\ncard, with no API calls to save them. The dir already exists and is writable.\n\nNeed throwaway scratch \u2014 heavy build output, package caches, temp files?\n`cd /tmp` (or any path outside `/factory`): anything off the factory drive is\nephemeral and discarded when the sandbox ends. In short: **stay in your working\ndir to keep something, `cd` out to throw it away.**\n\nThe whole shared drive is POSIX-mounted at `/factory`; the dashboard-visible\nroot is `$AGENT_COMPOSE_FACTORY_DIR` (`/factory/files`). Earlier versions and\nruns live in sibling dirs under\n`$AGENT_COMPOSE_FACTORY_DIR/$AGENT_COMPOSE_WORKFLOW/` \u2014 read them for prior\ncontext. Other workflows' dirs are present but not your concern.\n\n## Events \u2014 the factory timeline\n\nRecord something on the run/factory timeline (the dashboard renders these)\nwith the CLI \u2014 your run id is `$RUN_ID`:\n\n    agentc events send \"$RUN_ID\" <name> --summary \"<one line>\" [--body '<json>']\n\nNames like `note.created` / `brief.posted` surface in the Workbench;\n`agentc events list` reads them back. `/ac:events` is the skill equivalent.\n\n## Runs\n\n    agentc list                          # registered workflows  (/ac:list)\n    agentc logs \"$RUN_ID\"                # a run's logs           (/ac:logs)\n    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)\n\n## Writing workflow / agent code \u2014 the SDK\n\n`@agent-compose/sdk` is installed in `/workspace`. **To author a workflow,\nALWAYS run `/ac:generate-workflow`** (and `/ac:generate-agent` for an agent\nstep) instead of writing source from memory \u2014 the skill scaffolds the correct,\ncurrent shape. Then `agentc register <file.ts>` (or `/ac:register`).\n\nThe skill writes **step-form** (a builder of discrete, durable `.step()`s).\nThe legacy run-form (`defineWorkflow({ run(ctx, sandbox) { \u2026 } })`) has been\nREMOVED from the SDK \u2014 registering one fails with an error. Step-form is the\nonly shape: durable per-step replay, and pause only works there.\n\n## Pausing to ask the human\n\nTo ask a human and get an answer back, use the **`AskUserQuestion`** tool if\nyou have it; otherwise run **`agentc pause`**:\n\n    agentc pause --reason \"Notion returned 401 \u2014 connect Notion to continue\" \\\n                 --option retry --option skip\n\n**Both BLOCK and hand you the answer inline.** While you wait, the run is\nsuspended \u2014 your sandbox is frozen and compute stops, so a pause is free while\nthe human decides. When they answer, the call RETURNS with their decision: the\n`AskUserQuestion` tool result, or `agentc pause`'s output\n(`\u25B6 Resumed. The human answered: \u2026`), carries it.\n\n**Then USE that answer to finish your work \u2014 do NOT end your turn.** This is NOT\nfire-and-forget, and the answer does NOT arrive in a later message: it comes\nback right where you called it, on the SAME turn. The shape is: ask \u2192 the call\nblocks \u2192 it returns the human's answer \u2192 you act on it and produce your result.\nNever end your turn before the call returns, never guess an answer, and never\nproceed without one.\n\nReach for it the moment you hit \u2014 or foresee \u2014 any of these:\n- **A wall only a human can clear:** a 401/403, a missing credential, an\n  unconnected provider, a host the network refuses. Do NOT retry blindly or try\n  to work around it \u2014 pause and say what needs enabling.\n- **A durable or outward-facing action that needs sign-off:** registering a\n  workflow, deploying, sending email/messages, deleting or overwriting shared\n  data, spending money. Prepare everything, then pause for approval BEFORE you\n  commit it.\n- **A judgment call only the human can settle:** an under-specified request,\n  several valid paths, a conflict with existing state, missing input only they have.\n\nYou compose the `--reason` (the ask) yourself; pass `--option` choices when\nthere are clear ones, omit them for a free-form answer. Each agent pauses\nindependently \u2014 pausing doesn't stop the others.\n\n## Credentials\n\nConnector credentials (Google, GitHub, \u2026) are NEVER in your environment.\nThey're injected at the network layer when you call an allowed host \u2014 make the\nrequest **without** an Authorization header and the platform adds it. Don't try\nto read or exfiltrate tokens; they aren't here. The \"Connectors & access\"\nsection below (when present) lists exactly which providers this run can reach.\n\n## Computer Use \u2014 you have a real desktop, and it is already running\n\n**This machine has a graphical desktop.** Every session machine does \u2014 terminal\nsessions included \u2014 and the platform brings it UP AT BOOT, before your first\nturn: an X server on `DISPLAY=:0`, the openbox window manager, wallpaper and a\npanel. You do not start it, you do not wait for a human to open it, and you do\nnot need a viewer. Go straight to driving it.\n\n(The one exception, and it is rare: an image built without the GUI stack has no\ndisplay at all, and `DISPLAY=:0 xdotool getdisplaygeometry` errors outright.\nThat single case is the only one where this section does not apply \u2014 a\nscreenshot showing only wallpaper is NOT it, and neither is an app that failed\nto start.)\n\n**This is how you SEE anything.** Any question of the form \"does it render?\",\n\"is the page actually working?\", \"did the markers show up?\", \"what does it look\nlike?\" is answered by opening it on this desktop and screenshotting it \u2014 not by\nreasoning about the code, and not by a headless render (which proves the process\nstarts, not that the thing draws). Verify visually before you report visually.\n\n- **Input** \u2014 `xdotool` against `DISPLAY=:0`: `DISPLAY=:0 xdotool mousemove <x> <y>`,\n  `DISPLAY=:0 xdotool click 1` (1=left, 3=right), `DISPLAY=:0 xdotool type 'text'`,\n  `DISPLAY=:0 xdotool key Return` (also `ctrl+c`, `Tab`, `super`, \u2026).\n- **Screenshots** \u2014 `scrot` (or ImageMagick's `import`):\n  `DISPLAY=:0 scrot /tmp/screen.png`, then READ the PNG to see the screen,\n  before and after you act. A screenshot is your only eyes here.\n- **Apps + windows** \u2014 a plain X session. Launch in the background:\n  `DISPLAY=:0 <app> &`. Two things that trip agents up, both normal:\n  - a GUI app needs a **beat to map its window** \u2014 screenshot, and if you see\n    only wallpaper, wait a couple of seconds and screenshot again before\n    concluding anything;\n  - **Chromium needs `--no-sandbox`** in this environment (nested sandbox).\n    The whole recipe for looking at a local page:\n    `DISPLAY=:0 chromium --no-sandbox --disable-gpu --start-maximized <url> &`\n    then `sleep 5`, then `DISPLAY=:0 scrot /tmp/screen.png` and read it.\n  If a window still never appears, read the app's own log (`/tmp/*.log`) \u2014 the\n  desktop is not the thing that failed. Do NOT abandon it for a headless\n  screenshot: headless cannot tell you what the human will see.\n- **A human can watch** \u2014 the session header carries a **Desktop** button in the\n  dashboard, and what a teammate sees there is exactly this display. The desktop\n  runs whether or not anyone is looking; never wait for a viewer.\n\nNothing here changes the credentials rule above: tokens are injected at the\nnetwork layer, never present on the desktop or in any file you can read \u2014 so\nthere is nothing to type, paste, or screenshot a credential from.\n\n## Recording a demo \u2014 the desktop, captured to a video the human can play\n\n\"Record a demo of you using X\" is a normal ask, and this machine does it:\nstart a screen recording, drive the app with `xdotool` exactly as in Computer\nUse, stop the recording, and report the file. (For a LIVE view no recording is\nneeded \u2014 the session header's **Desktop** button already streams this display\nto any teammate watching; a recording is the durable, replayable artifact.\nBoth modes exist; say so when it matters.)\n\n**ffmpeg is NOT pre-installed** \u2014 install it first, once per machine:\n\n    sudo apt-get update -q && sudo apt-get install -y -q ffmpeg\n\n(drop `sudo` if you are already root). Then the whole recipe:\n\n    DISPLAY=:0 ffmpeg -f x11grab \\\n      -video_size \"$(DISPLAY=:0 xdotool getdisplaygeometry | tr ' ' x)\" \\\n      -framerate 10 -i :0 -c:v libvpx -b:v 1M -deadline realtime -cpu-used 8 \\\n      demo.webm &\n    FFMPEG_PID=$!\n    # ... drive the app with xdotool, screenshotting as you go ...\n    kill -INT \"$FFMPEG_PID\" && wait \"$FFMPEG_PID\"\n\nThe gotchas, each one earned:\n- **Stop with SIGINT (`kill -INT`), never SIGKILL** \u2014 ffmpeg finalizes the\n  file on SIGINT; a hard kill truncates the encode mid-write.\n- **Record WebM (matroska-family), not MP4** \u2014 mp4 writes its moov atom at the\n  END, so a killed or crashed encode leaves an UNPLAYABLE file; webm stays\n  playable up to the last written frame and plays natively in the browser.\n  MP4's only edge is compatibility with some external players \u2014 transcode\n  afterwards if you truly need it, never record straight to it.\n- **`-video_size` must match the real screen** \u2014 x11grab does not default to\n  it; read the geometry from `xdotool getdisplaygeometry` as above.\n- **10\u201312 fps is right for a screen demo** \u2014 small files, legible UI motion;\n  this is not video production.\n- **Write to the drive, not /tmp** \u2014 the recording must land in your working\n  directory to persist and show up in Files; a file in /tmp dies with the\n  sandbox.\n- When you stop, **TELL the human the exact drive path** of the video \u2014 a\n  recording they cannot find might as well not exist.\n\n## Previews \u2014 register every server you serve (cloud sessions)\n\nIn a cloud session, a dev server listening on a port becomes a hosted,\nmember-gated URL the human can open \u2014 but ONLY if you register it:\n\n    agentc preview open <port> [--name <label>] [--path </landing>]\n                                                 # hosted URL + an \"Open preview\" card\n    agentc preview list                          # the registry \u2014 what is live right now\n    agentc preview close <port>                  # take one down\n\n(`agentc preview announce` is the same verb as `open` \u2014 announce what you\nserve.) `--name` is the human-readable label; `--path` is where the app\nshould open (e.g. `/dashboard`) \u2014 the card and every chip land the human\nthere instead of a bare `/`.\n\nRegister EVERY server you start for a human, the moment it is listening, and\ntell them the URL the command printed. The registry is the only discoverable\nrecord of what this machine serves: an unregistered server keeps running, but\nnobody \u2014 not the human, not the assistant \u2014 can find its URL, and when the\nsandbox recycles it is gone without a trace. Never guess or hand out a raw\nport; the hosted URL from `agentc preview open` is the only address that\nworks outside this machine. (Outside a cloud session the command errors\nhonestly \u2014 there is no session sandbox to expose.)\n\nWhat registration buys you: the human sees each registered preview as a card\nin the conversation and a row in the session's Previews menu \u2014 MANY at once,\none per port \u2014 and the assistant resolves \"open the preview\" from this same\nregistry (its `list_previews` read), so what you register is exactly what\ngets opened. On deployments with subdomain previews the hosted URL is a real\norigin of its own \u2014 absolute asset paths and client-side routing work, the\nwhole app is navigable \u2014 so serve normally and let the platform address it;\nnever rewrite your app to a path prefix.\n\n## Tools in this environment\n\n- `agentc` \u2014 Agent Compose CLI (your primary interface; authed from env)\n- `@agent-compose/sdk` \u2014 installed in /workspace for writing workflows\n- `/ac:*` Claude Code skills \u2014 slash commands for the above\n- `archil` (factory drive), `rtk`, `bun`\n- `xdotool` / `scrot` \u2014 drive + screenshot the desktop (if this machine has one; see Computer Use)\n- A world-writable `/workspace` working directory";
+export declare const AGENT_COMPOSE_MANUAL = "# Working inside an Agent Compose sandbox\n\nYou are an agent running in a per-run sandbox on the Agent Compose platform.\nUse the **`agentc` CLI** and the **`@agent-compose/sdk`** for everything below \u2014\ndo NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on\nyour PATH and already authenticated from the environment\n(`AGENT_COMPOSE_URL` / `AGENT_COMPOSE_API_KEY` / `AGENT_COMPOSE_FACTORY` are\ninjected for this run), so commands just work \u2014 no login, no keys to manage.\n\nThe `/ac:*` skills are installed as Claude Code slash commands (`/ac:invoke`,\n`/ac:events`, `/ac:logs`, `/ac:register`, \u2026) \u2014 reach for them too.\n\n## Files \u2014 your outputs persist by default\n\nYour working directory defaults to **`$AGENT_COMPOSE_RUN_DIR`** \u2014 a per-run\ndirectory on the shared factory drive\n(`$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/`) the platform\ncreates and attributes to this run. **Files you write here persist by\ndefault** \u2014 they show up in the dashboard's Files tab and the run's Artifacts\ncard, with no API calls to save them. The dir already exists and is writable.\n\nNeed throwaway scratch \u2014 heavy build output, package caches, temp files?\n`cd /tmp` (or any path outside `/factory`): anything off the factory drive is\nephemeral and discarded when the sandbox ends. In short: **stay in your working\ndir to keep something, `cd` out to throw it away.**\n\nThe whole shared drive is POSIX-mounted at `/factory`; the dashboard-visible\nroot is `$AGENT_COMPOSE_FACTORY_DIR` (`/factory/files`). Earlier versions and\nruns live in sibling dirs under\n`$AGENT_COMPOSE_FACTORY_DIR/$AGENT_COMPOSE_WORKFLOW/` \u2014 read them for prior\ncontext. Other workflows' dirs are present but not your concern.\n\n## Events \u2014 the factory timeline\n\nRecord something on the run/factory timeline (the dashboard renders these)\nwith the CLI \u2014 your run id is `$RUN_ID`:\n\n    agentc events send \"$RUN_ID\" <name> --summary \"<one line>\" [--body '<json>']\n\nNames like `note.created` / `brief.posted` surface in the Workbench;\n`agentc events list` reads them back. `/ac:events` is the skill equivalent.\n\n## Runs\n\n    agentc list                          # registered workflows  (/ac:list)\n    agentc logs \"$RUN_ID\"                # a run's logs           (/ac:logs)\n    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)\n\n## Writing workflow / agent code \u2014 the SDK\n\n`@agent-compose/sdk` is installed in `/workspace`. **To author a workflow,\nALWAYS run `/ac:generate-workflow`** (and `/ac:generate-agent` for an agent\nstep) instead of writing source from memory \u2014 the skill scaffolds the correct,\ncurrent shape. Then `agentc register <file.ts>` (or `/ac:register`).\n\nThe skill writes **step-form** (a builder of discrete, durable `.step()`s).\nThe legacy run-form (`defineWorkflow({ run(ctx, sandbox) { \u2026 } })`) has been\nREMOVED from the SDK \u2014 registering one fails with an error. Step-form is the\nonly shape: durable per-step replay, and pause only works there.\n\n## Pausing to ask the human\n\nTo ask a human and get an answer back, use the **`AskUserQuestion`** tool if\nyou have it; otherwise run **`agentc pause`**:\n\n    agentc pause --reason \"Notion returned 401 \u2014 connect Notion to continue\" \\\n                 --option retry --option skip\n\n**Both BLOCK and hand you the answer inline.** While you wait, the run is\nsuspended \u2014 your sandbox is frozen and compute stops, so a pause is free while\nthe human decides. When they answer, the call RETURNS with their decision: the\n`AskUserQuestion` tool result, or `agentc pause`'s output\n(`\u25B6 Resumed. The human answered: \u2026`), carries it.\n\n**Then USE that answer to finish your work \u2014 do NOT end your turn.** This is NOT\nfire-and-forget, and the answer does NOT arrive in a later message: it comes\nback right where you called it, on the SAME turn. The shape is: ask \u2192 the call\nblocks \u2192 it returns the human's answer \u2192 you act on it and produce your result.\nNever end your turn before the call returns, never guess an answer, and never\nproceed without one.\n\nReach for it the moment you hit \u2014 or foresee \u2014 any of these:\n- **A wall only a human can clear:** a 401/403, a missing credential, an\n  unconnected provider, a host the network refuses. Do NOT retry blindly or try\n  to work around it \u2014 pause and say what needs enabling.\n- **A durable or outward-facing action that needs sign-off:** registering a\n  workflow, deploying, sending email/messages, deleting or overwriting shared\n  data, spending money. Prepare everything, then pause for approval BEFORE you\n  commit it.\n- **A judgment call only the human can settle:** an under-specified request,\n  several valid paths, a conflict with existing state, missing input only they have.\n\nYou compose the `--reason` (the ask) yourself; pass `--option` choices when\nthere are clear ones, omit them for a free-form answer. Each agent pauses\nindependently \u2014 pausing doesn't stop the others.\n\n## Credentials\n\nConnector credentials (Google, GitHub, \u2026) are NEVER in your environment.\nThey're injected at the network layer when you call an allowed host \u2014 make the\nrequest **without** an Authorization header and the platform adds it. Don't try\nto read or exfiltrate tokens; they aren't here. The \"Connectors & access\"\nsection below (when present) lists exactly which providers this run can reach.\n\n## Computer Use \u2014 you have a real desktop, and it is already running\n\n**This machine has a graphical desktop.** Every session machine does \u2014 terminal\nsessions included \u2014 and the platform brings it UP AT BOOT, before your first\nturn: an X server on `DISPLAY=:0`, the openbox window manager, wallpaper and a\npanel. You do not start it, you do not wait for a human to open it, and you do\nnot need a viewer. Go straight to driving it.\n\n(The one exception, and it is rare: an image built without the GUI stack has no\ndisplay at all, and `DISPLAY=:0 xdotool getdisplaygeometry` errors outright.\nThat single case is the only one where this section does not apply \u2014 a\nscreenshot showing only wallpaper is NOT it, and neither is an app that failed\nto start.)\n\n**This is how you SEE anything.** Any question of the form \"does it render?\",\n\"is the page actually working?\", \"did the markers show up?\", \"what does it look\nlike?\" is answered by opening it on this desktop and screenshotting it \u2014 not by\nreasoning about the code, and not by a headless render (which proves the process\nstarts, not that the thing draws). Verify visually before you report visually.\n\n- **Input** \u2014 `xdotool` against `DISPLAY=:0`: `DISPLAY=:0 xdotool mousemove <x> <y>`,\n  `DISPLAY=:0 xdotool click 1` (1=left, 3=right), `DISPLAY=:0 xdotool type 'text'`,\n  `DISPLAY=:0 xdotool key Return` (also `ctrl+c`, `Tab`, `super`, \u2026).\n- **Screenshots** \u2014 `scrot` (or ImageMagick's `import`):\n  `DISPLAY=:0 scrot /tmp/screen.png`, then READ the PNG to see the screen,\n  before and after you act. A screenshot is your only eyes here.\n- **Apps + windows** \u2014 a plain X session. Launch in the background:\n  `DISPLAY=:0 <app> &`. Two things that trip agents up, both normal:\n  - a GUI app needs a **beat to map its window** \u2014 screenshot, and if you see\n    only wallpaper, wait a couple of seconds and screenshot again before\n    concluding anything;\n  - **Chromium needs `--no-sandbox`** in this environment (nested sandbox).\n    The whole recipe for looking at a local page:\n    `DISPLAY=:0 chromium --no-sandbox --disable-gpu --start-maximized <url> &`\n    then `sleep 5`, then `DISPLAY=:0 scrot /tmp/screen.png` and read it.\n  If a window still never appears, read the app's own log (`/tmp/*.log`) \u2014 the\n  desktop is not the thing that failed. Do NOT abandon it for a headless\n  screenshot: headless cannot tell you what the human will see.\n- **A human can watch** \u2014 the session header carries a **Desktop** button in the\n  dashboard, and what a teammate sees there is exactly this display. The desktop\n  runs whether or not anyone is looking; never wait for a viewer.\n\nNothing here changes the credentials rule above: tokens are injected at the\nnetwork layer, never present on the desktop or in any file you can read \u2014 so\nthere is nothing to type, paste, or screenshot a credential from.\n\n## Recording a demo \u2014 the desktop, captured to a video the human can play\n\n\"Record a demo of you using X\" is a normal ask, and this machine does it.\n(For a LIVE view no recording is needed \u2014 the session header's **Desktop**\nbutton already streams this display to any teammate watching; a recording is\nthe durable, replayable artifact. Both modes exist; say so when it matters.)\n\n**Use `ac-record` \u2014 the platform recorder is already on PATH** (cloud\nsessions; `command -v ac-record` to confirm on older machines):\n\n    ac-record start     # begins capturing the desktop (display :0)\n    # ... drive the app with xdotool, screenshotting as you go ...\n    ac-record stop      # finishes + saves to recordings/ in your workspace\n    ac-record status    # one JSON line: {\"recording\":true,...}\n\nIt records the whole display (with desktop audio when the machine has a\nPulseAudio monitor), enforces sane caps (5 min / 200 MB \u2014 start a fresh\nrecording per scene rather than one long take), keeps the file playable even\nif the machine dies mid-take, and `stop` prints the saved path \u2014 the file\nlands ON THE DRIVE in `recordings/`, visible in Files and playable in the\ndashboard. A human watching the Desktop pane sees the recording indicator\nwhile you record.\n\nIf `ac-record` is missing (older machine), record by hand.\n**ffmpeg IS pre-installed** on platform images (`command -v ffmpeg`; only\nif absent: `sudo apt-get update -q && sudo apt-get install -y -q ffmpeg`):\n\n    DISPLAY=:0 ffmpeg -f x11grab \\\n      -video_size \"$(DISPLAY=:0 xdotool getdisplaygeometry | tr ' ' x)\" \\\n      -framerate 10 -i :0 -c:v libvpx -b:v 1M -deadline realtime -cpu-used 8 \\\n      demo.webm &\n    FFMPEG_PID=$!\n    # ... drive the app with xdotool ...\n    kill -INT \"$FFMPEG_PID\" && wait \"$FFMPEG_PID\"\n\nThe hand-rolled gotchas, each one earned:\n- **Stop with SIGINT (`kill -INT`), never SIGKILL** \u2014 ffmpeg finalizes the\n  file on SIGINT; a hard kill truncates the encode mid-write.\n- **Record WebM (matroska-family), not plain MP4** \u2014 mp4 writes its moov atom\n  at the END, so a killed or crashed encode leaves an UNPLAYABLE file; webm\n  stays playable up to the last written frame and plays natively in the\n  browser. (`ac-record` sidesteps this with fragmented mp4.)\n- **`-video_size` must match the real screen** \u2014 x11grab does not default to\n  it; read the geometry from `xdotool getdisplaygeometry` as above.\n- **10\u201315 fps is right for a screen demo** \u2014 small files, legible UI motion;\n  this is not video production.\n- **Write to the drive, not /tmp** \u2014 the recording must land in your working\n  directory to persist and show up in Files; a file in /tmp dies with the\n  sandbox.\n- When you stop, **TELL the human the exact drive path** of the video \u2014 a\n  recording they cannot find might as well not exist.\n\n## Previews \u2014 register every server you serve (cloud sessions)\n\nIn a cloud session, a dev server listening on a port becomes a hosted,\nmember-gated URL the human can open \u2014 but ONLY if you register it:\n\n    agentc preview open <port> [--name <label>] [--path </landing>]\n                                                 # hosted URL + an \"Open preview\" card\n    agentc preview list                          # the registry \u2014 what is live right now\n    agentc preview close <port>                  # take one down\n\n(`agentc preview announce` is the same verb as `open` \u2014 announce what you\nserve.) `--name` is the human-readable label; `--path` is where the app\nshould open (e.g. `/dashboard`) \u2014 the card and every chip land the human\nthere instead of a bare `/`.\n\nRegister EVERY server you start for a human, the moment it is listening, and\ntell them the URL the command printed. The registry is the only discoverable\nrecord of what this machine serves: an unregistered server keeps running, but\nnobody \u2014 not the human, not the assistant \u2014 can find its URL, and when the\nsandbox recycles it is gone without a trace. Never guess or hand out a raw\nport; the hosted URL from `agentc preview open` is the only address that\nworks outside this machine. (Outside a cloud session the command errors\nhonestly \u2014 there is no session sandbox to expose.)\n\nWhat registration buys you: the human sees each registered preview as a card\nin the conversation and a row in the session's Previews menu \u2014 MANY at once,\none per port \u2014 and the assistant resolves \"open the preview\" from this same\nregistry (its `list_previews` read), so what you register is exactly what\ngets opened. On deployments with subdomain previews the hosted URL is a real\norigin of its own \u2014 absolute asset paths and client-side routing work, the\nwhole app is navigable \u2014 so serve normally and let the platform address it;\nnever rewrite your app to a path prefix.\n\n## Tools in this environment\n\n- `agentc` \u2014 Agent Compose CLI (your primary interface; authed from env)\n- `@agent-compose/sdk` \u2014 installed in /workspace for writing workflows\n- `/ac:*` Claude Code skills \u2014 slash commands for the above\n- `archil` (factory drive), `rtk`, `bun`\n- `xdotool` / `scrot` \u2014 drive + screenshot the desktop (if this machine has one; see Computer Use)\n- A world-writable `/workspace` working directory";
 /** Parameters for the `agentc session add` education brief (ADR-0055 §8). */
 export interface AddedSessionBriefParams {
     conversationId: string;

package/dist/agent/agent-loop.d.ts

@@ -97,6 +97,11 @@ export type AgentLifecycleEvent = {
     /** Short runtime self-identifier (`claude`, `openai-desktop`, …).
      *  Drives the per-agent runtime icon on the dashboard. */
     runtimeKind?: string;
+    /** Authored plan-phase this agent belongs to (e.g. dynamic-task's
+     *  `phase.name`). Purely observability: the dashboard groups agents
+     *  under named phases without parsing the label prefix. Optional and
+     *  additive — absent for agents outside a phased plan. */
+    phase?: string;
 } | {
     event: "agent.message";
     at: number;
@@ -124,6 +129,9 @@ export type AgentLifecycleEvent = {
 export interface AgentLoopOpts<TResponse = unknown> {
     agentId?: string;
     label?: string;
+    /** Authored plan-phase name carried onto `agent.spawned` (see
+     *  AgentLifecycleEvent.phase). Optional, observability-only. */
+    phase?: string;
     onAgentLifecycleEvent?: (event: AgentLifecycleEvent) => void;
     onIteration?: (iteration: number, status: AgentStatus | null) => void;
     turnsPerIteration?: number;

package/dist/agent/run-agent.d.ts

@@ -48,6 +48,10 @@ export interface AgentOpts<T = unknown> {
     responseSchema?: z.ZodType<T>;
     /** Label prefix for runtime stderr ("[sbid][agent]" by default). */
     label?: string;
+    /** Authored plan-phase this agent belongs to. Rides `agent.spawned` so the
+     *  dashboard groups agents under named phases. Optional, additive,
+     *  observability-only — it never affects execution. */
+    phase?: string;
     /** Lifecycle event sink from workflow ctx. Emits agent.spawned / iteration / settled. */
     events?: {
         emit: (event: AgentLifecycleEvent) => void | Promise<void>;

package/dist/client.d.ts

@@ -12,17 +12,17 @@
  */
 import type { RunEvent } from "./types/events.js";
 import type { ConversationStreamEvent } from "./types/conversation-stream.js";
-import type { InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, StreamRunLogsOptions, RunStatus, ResumePauseOptions, ResumePauseResponse, AnswerSteerOptions, RequestAgentPauseOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, RunDetail, RunListEntry, ListRunsOptions, TimelineEvent, RunFundingResponse, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunArtifactRow, RunLogLine, ListRunLogsOptions, CancelRunResponse, ListSnapshotsOptions, SnapshotListResponse, SnapshotListEntry, RunSnapshotEntry } from "./types/api-runs.js";
-import type { TeamMember, Mention, CreateMentionsInput, ConversationsPage, SessionsPage, ConversationDetail, ConversationThread, CreateCloudSessionInput, CloudSessionCreated, SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, SessionChangeSet, SessionMergeReport, SessionDiscardReport, SendConversationMessageInput, SendConversationMessageResult, ChannelSessionRow, SessionChannelMessagePosted, ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow } from "./types/api-conversations.js";
+import type { InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, StreamRunLogsOptions, InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions, RunStatus, ResumePauseOptions, ResumePauseResponse, AnswerSteerOptions, RequestAgentPauseOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, RunDetail, RunListEntry, ListRunsOptions, TimelineEvent, RunFundingResponse, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunArtifactRow, RunLogLine, ListRunLogsOptions, CancelRunResponse, ListSnapshotsOptions, SnapshotListResponse, SnapshotListEntry, RunSnapshotEntry } from "./types/api-runs.js";
+import type { TeamMember, Mention, CreateMentionsInput, ConversationsPage, SessionsPage, ConversationDetail, ConversationThread, CreateCloudSessionInput, CloudSessionCreated, SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld, SessionChangeSet, SessionMergeGated, SessionMergeReport, SessionDiscardReport, SendConversationMessageInput, SendConversationMessageResult, ChannelSessionRow, SessionChannelMessagePosted, ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow } from "./types/api-conversations.js";
 import type { ConversationMemberRole, ConversationMember, ArtifactScope, SetScopeGrantsInput, SetTemplateScopeInput } from "./types/api-scopes.js";
 import type { Project, ProjectsPage, ProjectRole, ProjectMember, ProjectObjectsPage, ProjectAddPreview, AddProjectObjectInput, AddProjectObjectResult, RefreshProjectObjectResult } from "./types/api-projects.js";
-import type { RegisterResult, RegisterWorkflowInput, TemplateRow, TemplateDetail, ListTemplatesOptions, SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult, FactoryRow, CreateFactoryInput, UpdateFactoryInput, ScheduleRow, CreateScheduleInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, ApiKey, ApiKeyCreated, UsageResponse, DriveRepoLink, CreateDriveRepoLinkInput } from "./types/api-factory.js";
+import type { RegisterResult, RegisterWorkflowInput, TemplateRow, TemplateDetail, ListTemplatesOptions, SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult, FactoryRow, CreateFactoryInput, UpdateFactoryInput, ScheduleRow, CreateScheduleInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageResponse, DriveRepoLink, CreateDriveRepoLinkInput, DriveMountSession, CreateDriveMountSessionInput } from "./types/api-factory.js";
 import type { ComplianceSession, RequestComplianceSessionInput, ListComplianceSessionsOptions, ComplianceSessionsPage, ListComplianceAccessesOptions, ComplianceAccessesPage } from "./types/api-compliance.js";
-export type { RunState, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, StreamRunLogsOptions, RunStatus, ResumePauseActor, ResumePauseSuccess, ResumePausePending, ResumePauseResponse, ResumePauseOptions, RequestAgentPauseOptions, AnswerSteerOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, RunDetail, RunListEntry, ListRunsOptions, TimelineEvent, FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse, EventSubjectType, EventRow, RunArtifactRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, CancelRunResponse, ListSnapshotsOptions, SnapshotListEntry, SnapshotListResponse, RunSnapshotEntry, } from "./types/api-runs.js";
-export type { TeamMember, Mention, CreateMentionsInput, ConversationMessagePart, ConversationRow, ConversationMessageRow, ConversationsPage, SessionsPage, ConversationDetail, CreateCloudSessionInput, CloudSessionCreated, ConversationThread, SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, SessionFileChange, SessionChangeSet, SessionMergeReportDetail, SessionMergeReport, SessionDiscardReport, ConversationPageContext, SendConversationMessageInput, ConversationTurnState, SendConversationMessageResult, ConversationPresenceSnapshot, AgentListRow, StreamConversationOptions, ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted, } from "./types/api-conversations.js";
+export type { RunState, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, FundingChoice, StreamRunLogsOptions, InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions, RunStatus, ResumePauseActor, ResumePauseSuccess, ResumePausePending, ResumePauseResponse, ResumePauseOptions, RequestAgentPauseOptions, AnswerSteerOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, RunDetail, RunListEntry, ListRunsOptions, TimelineEvent, FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse, EventSubjectType, EventRow, RunArtifactRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, CancelRunResponse, ListSnapshotsOptions, SnapshotListEntry, SnapshotListResponse, RunSnapshotEntry, } from "./types/api-runs.js";
+export type { TeamMember, Mention, CreateMentionsInput, ConversationMessagePart, ConversationRow, ConversationMessageRow, ConversationsPage, SessionsPage, ConversationDetail, CreateCloudSessionInput, CloudSessionCreated, ConversationThread, SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld, SessionFileChange, SessionChangeSet, SessionChangeStats, SessionDiffReviewBound, ReviewSuggestion, ReviewSuggestionDecision, ReviewSuggestionDecisions, SessionMergeReportDetail, SessionMergeReport, SessionMergeGated, SessionDiscardReport, ConversationPageContext, SendConversationMessageInput, ConversationTurnState, SendConversationMessageResult, UnnotifiedMention, ConversationPresenceSnapshot, AgentListRow, StreamConversationOptions, ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted, } from "./types/api-conversations.js";
 export type { ConversationMemberRole, ConversationMember, DocumentCapability, TemplateCapability, ScopeGrant, ArtifactScope, RunContext, SetScopeGrantsInput, SetTemplateScopeInput, } from "./types/api-scopes.js";
 export type { Project, ProjectsPage, ProjectRole, ProjectMember, ProjectObject, ProjectObjectsPage, ProjectSkippedFile, ProjectPreviewFile, ProjectAddPreview, AddProjectObjectInput, AddProjectObjectResult, RefreshProjectObjectResult, } from "./types/api-projects.js";
-export type { RegisterResult, RegisteredRuntime, RuntimeSourceInput, TemplateSourceRef, RegisterWorkflowInput, TemplateRow, TemplateDetail, ListTemplatesOptions, FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult, PublicFileLinkState, FactoryRow, CreateFactoryInput, UpdateFactoryInput, ScheduleRow, CreateScheduleInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, ApiKey, ApiKeyCreated, UsageRollupRow, UsageResponse, DriveRepoLink, CreateDriveRepoLinkInput, } from "./types/api-factory.js";
+export type { RegisterResult, RegisteredRuntime, RuntimeSourceInput, TemplateSourceRef, RegisterWorkflowInput, TemplateRow, TemplateDetail, ListTemplatesOptions, FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult, PublicFileLinkState, FactoryRow, CreateFactoryInput, UpdateFactoryInput, ScheduleRow, CreateScheduleInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageRollupRow, UsageResponse, DriveRepoLink, CreateDriveRepoLinkInput, DriveMountSession, CreateDriveMountSessionInput, } from "./types/api-factory.js";
 export type { ComplianceScopeKind, ComplianceStatus, ComplianceSession, ComplianceAccess, RequestComplianceSessionInput, ListComplianceSessionsOptions, ComplianceSessionsPage, ListComplianceAccessesOptions, ComplianceAccessesPage, } from "./types/api-compliance.js";
 export interface AgentComposeClientOptions {
     /** Your team's API key — minted from the dashboard or `agentc keys create`.
@@ -65,6 +65,14 @@ export declare class AgentComposeClient {
      *
      *  `factorySlug`: defaults to `"default"`. */
     invoke(name: string, input?: Record<string, unknown>, opts?: InvokeWorkflowOptions): Promise<InvokeResult>;
+    /** Invoke an INLINE workflow — the exact payload `bundleWorkflow` produced
+     *  plus a `name` — WITHOUT registering it. The server validates it through
+     *  the same core as registration (manifest required + bound to the source
+     *  bytes) but writes no registry row: the run snapshots the source it
+     *  executes, and registration stays the door for named/versioned/scheduled
+     *  workflows. Same parent-child auto-detection and `Idempotency-Key`
+     *  semantics as `invoke()`. Requires the `invoke` scope. */
+    invokeInline(workflow: InlineWorkflowPayload, input?: Record<string, unknown>, opts?: InvokeInlineOptions): Promise<InvokeResult>;
     /** Invoke a workflow and wait for it to settle (success / failed / abandoned).
      *  Polls `getStatus` on a fixed interval. Rejects with `AgentComposeError`
      *  if the run settles non-success, or a plain `Error` on timeout.
@@ -73,6 +81,16 @@ export declare class AgentComposeClient {
      *  tests, tune up for long-running workflows. The parent-child auto-
      *  detection from `invoke()` applies here too. */
     invokeAndWait<TOutput = unknown>(name: string, input?: Record<string, unknown>, opts?: InvokeAndWaitOptions): Promise<RunStatus<TOutput>>;
+    /** `invokeInline` + block until the run settles — the "call blocks →
+     *  result returns on the same turn" contract for inline sub-workflows. */
+    invokeInlineAndWait<TOutput = unknown>(workflow: InlineWorkflowPayload, input?: Record<string, unknown>, opts?: InvokeInlineAndWaitOptions): Promise<RunStatus<TOutput>>;
+    /** Poll one run until it settles (success / failed / abandoned) and return
+     *  its final status. Shared tail of `invokeAndWait` / `invokeInlineAndWait`;
+     *  also useful to re-attach to a run you dispatched fire-and-forget. */
+    waitForRun<TOutput = unknown>(runId: string, opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<RunStatus<TOutput>>;
     /** List captured snapshots in a factory. */
     listSnapshots(opts?: ListSnapshotsOptions): Promise<SnapshotListEntry[]>;
     /** List one page of captured snapshots in a factory. */
@@ -183,6 +201,13 @@ export declare class AgentComposeClient {
     /** Files the run wrote on the factory drive — run-attributed revisions,
      *  latest write per path, paths the run later deleted excluded. */
     listRunArtifacts(runId: string): Promise<RunArtifactRow[]>;
+    /** One run artifact's bytes, resolved server-side through the DRIVE INDEX
+     *  (never the run's gone sandbox or branch) — a listed artifact with an
+     *  indexed path is always readable here, including after the run's branch
+     *  is merged/retired. The path is the listing's `path`, sent as a single
+     *  query parameter so slashes / spaces / unicode in agent-derived
+     *  filenames survive verbatim. */
+    getRunArtifactBytes(runId: string, path: string): Promise<Uint8Array>;
     /** Write (create or overwrite) one file on a factory's drive. */
     putFactoryFile(path: string, content: string | Uint8Array, opts?: {
         factorySlug?: string;
@@ -196,6 +221,7 @@ export declare class AgentComposeClient {
     getFactoryFileBytes(path: string, opts?: {
         factorySlug?: string;
         revision?: number;
+        branch?: string;
     }): Promise<Uint8Array>;
     /** Read one file's current content (or a specific revision) as text
      *  (UTF-8). For binary files use `getFactoryFileBytes` — decoding them to
@@ -203,7 +229,21 @@ export declare class AgentComposeClient {
     getFactoryFile(path: string, opts?: {
         factorySlug?: string;
         revision?: number;
+        branch?: string;
     }): Promise<string>;
+    /** Create a local drive mount (or re-mint an existing one's token by
+     *  passing its `conversationId`). */
+    createDriveMountSession(opts?: CreateDriveMountSessionInput & {
+        factorySlug?: string;
+    }): Promise<DriveMountSession>;
+    /** Release a local mount's gateway branch mount (clean unmount). The
+     *  branch and its review card survive — this only drops the gateway's
+     *  in-memory mount so the exclusive branch is not pinned. */
+    releaseDriveMountSession(conversationId: string, opts?: {
+        factorySlug?: string;
+    }): Promise<{
+        released: boolean;
+    }>;
     /** List conversations the caller can access, newest-activity first.
      *  Cursor-paginated: pass the previous page's `next_cursor`. */
     listConversations(opts?: {
@@ -215,8 +255,12 @@ export declare class AgentComposeClient {
     listSessions(factoryId: string, opts?: {
         cursor?: string;
     }): Promise<SessionsPage>;
-    /** One conversation with its latest page of messages. */
-    getConversation(id: string): Promise<ConversationDetail>;
+    /** One conversation with its latest page of messages. `limit` bounds the
+     *  page (newest N) — metadata-only consumers (e.g. resolving the
+     *  session's drive branch) pass 1 instead of pulling the full hydrate. */
+    getConversation(id: string, opts?: {
+        limit?: number;
+    }): Promise<ConversationDetail>;
     /** Provision a CLOUD-native session (ADR-0037 Phase 3b / ADR-0055 §9): a
      *  persistent server-side sandbox on the factory drive that keeps working
      *  after the caller's terminal (and laptop) closes. The session's TYPE is
@@ -268,6 +312,17 @@ export declare class AgentComposeClient {
     /** Take a dev preview down (write-tier). Idempotent — `closed` is false when
      *  no active row matched. */
     closePreview(conversationId: string, port: number): Promise<boolean>;
+    /** Hold (or extend — the stamp is monotone) a cloud session's
+     *  background-work busy lease: while it is live, the between-turns
+     *  park/suspend leaves the session's VM running so work the turn left
+     *  behind keeps executing. The lease lapses on its own — re-hold to
+     *  extend past `minutes` (server-capped). Write-tier. */
+    holdBackgroundWork(conversationId: string, input?: {
+        minutes?: number;
+    }): Promise<BackgroundWorkHeld>;
+    /** Release the session's background-work lease (the work finished).
+     *  Idempotent — `released` is false when no lease was held. */
+    releaseBackgroundWork(conversationId: string): Promise<boolean>;
     /** Fork a cloud session from HEAD: snapshot the VM + branch the drive + seed
      *  a new conversation from the transcript so far, booting from both. Returns
      *  the child conversation id to switch to. Write-tier; "Branch from here." */
@@ -286,6 +341,11 @@ export declare class AgentComposeClient {
      *  `main`. Write-tier + human caller. Pass `opts.branch` (the branch you
      *  reviewed) to fail 409 `branch_changed` if it moved since.
      *
+     *  On a merge-GATED session (merge-gate spec) a non-approver's call does
+     *  NOT merge: it answers 202 `SessionMergeGated` — the ask froze into (or
+     *  converged on) a kind='merge' approval routed to the session's
+     *  approvers. Discriminate on `object`.
+     *
      *  Failures: 403 `role_read_only` (read-only member) or a plain 403 for
      *  session toolbelt keys (agents cannot self-approve); 409 `turn_active`
      *  (a turn is running — retry when idle) | `branch_changed`; 400
@@ -294,7 +354,7 @@ export declare class AgentComposeClient {
      *  named in the body) | `rebranch_failed` (merge landed; retry safe). */
     mergeSessionChanges(conversationId: string, opts?: {
         branch?: string;
-    }): Promise<SessionMergeReport>;
+    }): Promise<SessionMergeReport | SessionMergeGated>;
     /** Reject the session's proposed changes: abandon its branch (retained
      *  dormant, never deleted — an admin re-merge can recover a mistaken
      *  discard) and continue the session on a fresh branch off `main`.
@@ -531,12 +591,13 @@ export declare class AgentComposeClient {
     listRepoLinks(opts?: {
         factorySlug?: string;
     }): Promise<DriveRepoLink[]>;
-    /** Link a drive directory to a GitHub repo + tracked branch (`manage`
-     *  scope). Requires the drive to be graph-authoritative — 409 names the
-     *  promotion prerequisite otherwise. */
+    /** Link a drive directory to a GitHub repo's tracked BRANCHES (`manage`
+     *  scope) — one link row per branch, created in one action. Requires the
+     *  drive to be graph-authoritative — 409 names the promotion
+     *  prerequisite otherwise. */
     createRepoLink(input: CreateDriveRepoLinkInput, opts?: {
         factorySlug?: string;
-    }): Promise<DriveRepoLink>;
+    }): Promise<DriveRepoLink[]>;
     /** Unlink (§6.3: the prefix's files and history stay on the drive). */
     deleteRepoLink(linkId: string, opts?: {
         factorySlug?: string;
@@ -554,8 +615,9 @@ export declare class AgentComposeClient {
      *  Factory-scoped keys can only mint other keys bound to the same factory. */
     createApiKey(input: CreateApiKeyInput): Promise<ApiKeyCreated>;
     /** List API keys on the caller's team (metadata only — plaintext keys are
-     *  never returned). */
-    listApiKeys(): Promise<ApiKey[]>;
+     *  never returned). Bounded + keyset-paginated: pass `cursor` from the
+     *  previous page's `nextCursor` to walk forward. */
+    listApiKeys(opts?: ListApiKeysOptions): Promise<ApiKeyPage>;
     /** Billable usage rollup for the caller's team over the [from, to) window. */
     getUsage(from: Date, to: Date): Promise<UsageResponse>;
     /** Cancel an in-progress run. Idempotent: cancelling an already-terminal

package/dist/display.d.ts

@@ -107,6 +107,22 @@ export declare function clampPlanEntries(raw: unknown): DisplayPlanEntry[];
 export declare const TABLE_MAX_COLUMNS = 12;
 export declare const TABLE_MAX_ROWS = 100;
 export declare const TABLE_CELL_MAX_CHARS = 200;
+/** Drive-path bound for promoted/marker paths (mirrors the directive cap). */
+export declare const DRIVE_PATH_MAX_CHARS = 512;
+/**
+ * Whether a string is a PLAUSIBLE factory-drive path — the gate every
+ * promoted document/image/preview/diff path and document/image marker
+ * passes before it can become a card. A malformed agent command can hand
+ * the promoter shell fragments instead of a path (live failure: a partial
+ * `agentc display document` call promoted the redirect word `2>&1` — and a
+ * bare `/` — into "Showed document" cards whose viewer link was dead), so
+ * anything that reads as a shell operator, flag, or empty reference is not
+ * a path: reject whitespace-only, over-long, flag-shaped (leading `-`),
+ * shell operators / substitution (`|`, `<`, `>`, `;`, backticks, `$(`,
+ * which covers `2>&1`), control characters, backslashes, bare/duplicate
+ * slashes, and `.`/`..` segments (the server rejects those anyway).
+ */
+export declare function isPlausibleDrivePath(raw: string): boolean;
 /**
  * Clamp raw table input to the marker/part bounds. Accepts an array of flat
  * objects (columns inferred from the key union, first-seen order) or a

package/dist/index.d.ts

@@ -27,7 +27,7 @@ export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, GatePause
 export type { AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking, AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone, AgentMessageError, AgentMessageUsage, AgentStatus, } from "./types/protocol.js";
 export type { SandboxProvider, DesktopSandboxProvider, SandboxPtyOpts, SandboxPtyHandle, } from "./types/sandbox.js";
 export { AgentComposeClient } from "./client.js";
-export type { RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, TemplateSourceRef, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, ListSnapshotsOptions, TemplateRow, ListTemplatesOptions, CreateFactoryInput, UpdateFactoryInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, StreamRunLogsOptions, TeamMember, Mention, CreateMentionsInput, EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, RunListEntry, ListRunsOptions, RunDetail, FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse, RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse, ApiKey, ApiKeyCreated, UsageRollupRow, UsageResponse, CancelRunResponse, RequestAgentPauseOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, AnswerSteerOptions, ResumePauseOptions, ResumePauseResponse, ResumePauseSuccess, ResumePausePending, ResumePauseActor, ConversationMessagePart, ConversationRow, ConversationMessageRow, ConversationsPage, ConversationDetail, ConversationThread, ConversationPageContext, SendConversationMessageInput, SendConversationMessageResult, ConversationTurnState, ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow, CreateCloudSessionInput, CloudSessionCreated, SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, SessionFileChange, SessionChangeSet, SessionMergeReportDetail, SessionMergeReport, SessionDiscardReport, ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted, FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, PublicFileLinkState, ConversationMemberRole, ConversationMember, DocumentCapability, TemplateCapability, ScopeGrant, ArtifactScope, RunContext, SetScopeGrantsInput, SetTemplateScopeInput, TemplateDetail, Project, ProjectsPage, ProjectRole, ProjectMember, ProjectObject, ProjectObjectsPage, ProjectSkippedFile, ProjectPreviewFile, ProjectAddPreview, AddProjectObjectInput, AddProjectObjectResult, RefreshProjectObjectResult, ComplianceScopeKind, ComplianceStatus, ComplianceSession, ComplianceAccess, RequestComplianceSessionInput, ListComplianceSessionsOptions, ComplianceSessionsPage, ListComplianceAccessesOptions, ComplianceAccessesPage, } from "./client.js";
+export type { RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, TemplateSourceRef, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, FundingChoice, InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions, ListSnapshotsOptions, TemplateRow, ListTemplatesOptions, CreateFactoryInput, UpdateFactoryInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, StreamRunLogsOptions, TeamMember, Mention, CreateMentionsInput, EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, RunListEntry, ListRunsOptions, RunDetail, FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse, RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageRollupRow, UsageResponse, CancelRunResponse, RequestAgentPauseOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, AnswerSteerOptions, ResumePauseOptions, ResumePauseResponse, ResumePauseSuccess, ResumePausePending, ResumePauseActor, ConversationMessagePart, ConversationRow, ConversationMessageRow, ConversationsPage, ConversationDetail, ConversationThread, ConversationPageContext, SendConversationMessageInput, SendConversationMessageResult, UnnotifiedMention, ConversationTurnState, ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow, CreateCloudSessionInput, CloudSessionCreated, SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld, SessionFileChange, SessionChangeSet, SessionChangeStats, SessionDiffReviewBound, ReviewSuggestion, ReviewSuggestionDecision, ReviewSuggestionDecisions, SessionMergeReportDetail, SessionMergeReport, SessionMergeGated, SessionDiscardReport, DriveMountSession, CreateDriveMountSessionInput, ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted, FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, PublicFileLinkState, ConversationMemberRole, ConversationMember, DocumentCapability, TemplateCapability, ScopeGrant, ArtifactScope, RunContext, SetScopeGrantsInput, SetTemplateScopeInput, TemplateDetail, Project, ProjectsPage, ProjectRole, ProjectMember, ProjectObject, ProjectObjectsPage, ProjectSkippedFile, ProjectPreviewFile, ProjectAddPreview, AddProjectObjectInput, AddProjectObjectResult, RefreshProjectObjectResult, ComplianceScopeKind, ComplianceStatus, ComplianceSession, ComplianceAccess, RequestComplianceSessionInput, ListComplianceSessionsOptions, ComplianceSessionsPage, ListComplianceAccessesOptions, ComplianceAccessesPage, } from "./client.js";
 export { parseSseStream } from "./sse.js";
 export { renderDirectiveMarker, parseDirectiveMarkers, DIRECTIVE_MARKER_PREFIX, DIRECTIVE_MARKER_SUFFIX, MAX_DIRECTIVES_PER_OUTPUT, REVISION_SELECTOR_RE, ASK_DIRECTIVE_PROMPT_MAX, ASK_DIRECTIVE_MAX_OPTIONS, ASK_DIRECTIVE_OPTION_ID_MAX, ASK_DIRECTIVE_OPTION_LABEL_MAX, ASK_APPROVER_MIN, ASK_APPROVER_MAX, } from "./directives.js";
 export type { CloudDirective } from "./directives.js";
@@ -38,7 +38,7 @@ export type { AcpAvailableCommand, AcpClientPeerDeps, AcpSessionCaps } from "./r
 export { AgentComposeError } from "./errors.js";
 export type { AuthzErrorCode } from "./errors.js";
 export { formatError } from "./utils/errors.js";
-export { bundleWorkflow, BUNDLER_VERSION, WorkflowSourceValidationError, assertDefaultExportIsDefineWorkflow, } from "./utils/bundler.js";
+export { bundleWorkflow, BUNDLER_VERSION, WorkflowSourceValidationError, assertDefaultExportIsDefineWorkflow, SDK_PACKAGE, SDK_SPECIFIER_ALIASES, resolveSdkAlias, explainBundleFailure, } from "./utils/bundler.js";
 export type { BundledWorkflow, WorkflowManifest } from "./utils/bundler.js";
 export { AgentStatusSchema } from "./utils/schemas.js";
 export { createClaudeRuntime, ClaudeRunner } from "./runtimes/claude.js";
@@ -48,7 +48,7 @@ export { createVercelRuntime, VercelRunner, listVercelRuntimeModels } from "./ru
 export type { VercelRuntimeConfig, VercelRuntimeModel } from "./runtimes/vercel.js";
 export type { GatewayModelId } from "ai";
 export { createCodexRuntime, codexSpec } from "./runtimes/codex.js";
-export type { CodexRuntimeConfig } from "./runtimes/codex.js";
+export type { CodexRuntimeConfig, CodexReasoningEffort } from "./runtimes/codex.js";
 export { default as codexRuntime } from "./runtimes/codex.js";
 export type { CliReasoningEffort } from "./runtimes/_cli-agent.js";
 export { createAmpRuntime } from "./runtimes/amp.js";
@@ -63,13 +63,13 @@ export { default as cursorRuntime } from "./runtimes/cursor.js";
 export { createDroidRuntime, droidSpec } from "./runtimes/droid.js";
 export type { DroidRuntimeConfig } from "./runtimes/droid.js";
 export { default as droidRuntime } from "./runtimes/droid.js";
-export { createClaudeCodeRuntime, claudeCodeSpec, CLAUDE_CODE_ACP_ADAPTER, CLAUDE_CODE_THINKING_TOKENS } from "./runtimes/claude-code.js";
+export { createClaudeCodeRuntime, claudeCodeSpec, CLAUDE_CODE_ACP_ADAPTER, CLAUDE_CODE_EFFORT_LEVELS } from "./runtimes/claude-code.js";
 export type { ClaudeCodeRuntimeConfig } from "./runtimes/claude-code.js";
 export { default as claudeCodeRuntime } from "./runtimes/claude-code.js";
 export { bashTool, codingTools, editTool, readTool, writeTool } from "./tools/index.js";
 export type { CodingTool } from "./tools/index.js";
 export type { RunEvent } from "./types/events.js";
-export { createSandbox, reconnectSandbox, killAllSandboxes, killSandboxById, getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot, snapshotResolves, makeSandboxProvider, makeDesktopSandboxProvider, parseSseExecStream, AGENT_COMPOSE_TAG, SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES, isE2bSupportedSize, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate, isPlatformE2bTemplateAlias, E2B_DEVBOX_TEMPLATE, E2B_DEVBOX_SPEC, E2B_DEVBOX_RECIPE_VERSION, e2bDevboxTemplateRef } from "./sandbox.js";
+export { createSandbox, reconnectSandbox, killAllSandboxes, killSandboxById, getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot, snapshotResolves, makeSandboxProvider, makeDesktopSandboxProvider, parseSseExecStream, AGENT_COMPOSE_TAG, SANDBOX_SIZES, SANDBOX_MACHINES, SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, SESSION_DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES, E2B_MAX_VCPUS, E2B_MAX_MEMORY_MB, VERCEL_MEMORY_MB_PER_VCPU, isE2bSupportedSize, isVercelSupportedSize, sandboxSizeLabel, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate, isPlatformE2bTemplateAlias, E2B_DEVBOX_TEMPLATE, E2B_DEVBOX_SPEC, E2B_DEVBOX_RECIPE_VERSION, e2bDevboxTemplateRef } from "./sandbox.js";
 export { SandboxUnavailableError, SANDBOX_UNAVAILABLE_PREFIX } from "./sandbox-errors.js";
 export type { SandboxCreateOpts, SandboxNetworkPolicy, SandboxNetworkHeaderTransform, SandboxNetworkAllowRule, SandboxNetworkSubnetPolicy, SandboxProviderName, SandboxQuotaResult, OwnedSandboxResult, OwnedSandbox, SandboxSize, ParseSseExecStreamOptions, SandboxCommandRunOptions, SandboxCommandResult, } from "./sandbox.js";
 export type { SandboxResources, DriveMergePolicy } from "./types/workflow-metadata.js";
@@ -94,5 +94,5 @@ export { AGENT_COMPOSE_MANUAL, buildAgentContextDoc, writeAgentContext, buildAdd
 export type { AgentConnectorInfo, AddedSessionBriefParams } from "./agent/agent-context.js";
 export { AgentMessageSchema, parseAgentResponse } from "./agent/protocol.js";
 export { importSourceModule, TMP_DIR, LATEST_VERSION } from "./utils/source-loader.js";
-export { DISPLAY_MARKER_KEY, DISPLAY_MARKER_VERSION, PLAN_MAX_ENTRIES, PLAN_ENTRY_MAX_CHARS, TABLE_MAX_COLUMNS, TABLE_MAX_ROWS, TABLE_CELL_MAX_CHARS, CHART_MAX_SERIES, CHART_MAX_POINTS_PER_SERIES, CHART_LABEL_MAX_CHARS, ASK_PROMPT_MAX_CHARS, ASK_MAX_OPTIONS, ASK_OPTION_ID_MAX_CHARS, ASK_OPTION_LABEL_MAX_CHARS, serializeDisplayMarker, parseDisplayMarker, findDisplayMarker, clampPlanEntries, clampTableData, clampChartSeries, clampChartAxisLabel, clampAskOptions, detectAgentcInvocation, shellWords, createDisplayPromoter, } from "./display.js";
+export { DISPLAY_MARKER_KEY, DISPLAY_MARKER_VERSION, PLAN_MAX_ENTRIES, PLAN_ENTRY_MAX_CHARS, TABLE_MAX_COLUMNS, TABLE_MAX_ROWS, TABLE_CELL_MAX_CHARS, CHART_MAX_SERIES, CHART_MAX_POINTS_PER_SERIES, CHART_LABEL_MAX_CHARS, ASK_PROMPT_MAX_CHARS, ASK_MAX_OPTIONS, ASK_OPTION_ID_MAX_CHARS, ASK_OPTION_LABEL_MAX_CHARS, DRIVE_PATH_MAX_CHARS, isPlausibleDrivePath, serializeDisplayMarker, parseDisplayMarker, findDisplayMarker, clampPlanEntries, clampTableData, clampChartSeries, clampChartAxisLabel, clampAskOptions, detectAgentcInvocation, shellWords, createDisplayPromoter, } from "./display.js";
 export type { DisplayMarker, DisplayPlanEntry, DisplayPlanStatus, DisplayTableCell, DisplayTableColumn, DisplayTableData, DisplayChartKind, DisplayChartPoint, DisplayChartSeries, DisplayAskOption, AgentcInvocation, PromotedPart, DisplayPromoter, DisplayPromoterContext, } from "./display.js";