@agent-compose/sdk 0.7.0 → 0.8.1

package/src/agent/agent-context.ts

@@ -77,9 +77,9 @@ step) instead of writing source from memory — the skill scaffolds the correct,
 current shape. Then \`agentc register <file.ts>\` (or \`/ac:register\`).
 
 The skill writes **step-form** (a builder of discrete, durable \`.step()\`s).
-Never write the legacy run-form (\`defineWorkflow({ run(ctx, sandbox) { … } })\`):
-it is one opaque step, so any failure or resume re-runs the whole body — and
-**pause does not work in run-form**.
+The legacy run-form (\`defineWorkflow({ run(ctx, sandbox) { … } })\`) has been
+REMOVED from the SDK — registering one fails with an error. Step-form is the
+only shape: durable per-step replay, and pause only works there.
 
 ## Pausing to ask the human
 
@@ -125,14 +125,197 @@ request **without** an Authorization header and the platform adds it. Don't try
 to read or exfiltrate tokens; they aren't here. The "Connectors & access"
 section below (when present) lists exactly which providers this run can reach.
 
+## Computer Use — you have a real desktop, and it is already running
+
+**This machine has a graphical desktop.** Every session machine does — terminal
+sessions included — and the platform brings it UP AT BOOT, before your first
+turn: an X server on \`DISPLAY=:0\`, the openbox window manager, wallpaper and a
+panel. You do not start it, you do not wait for a human to open it, and you do
+not need a viewer. Go straight to driving it.
+
+(The one exception, and it is rare: an image built without the GUI stack has no
+display at all, and \`DISPLAY=:0 xdotool getdisplaygeometry\` errors outright.
+That single case is the only one where this section does not apply — a
+screenshot showing only wallpaper is NOT it, and neither is an app that failed
+to start.)
+
+**This is how you SEE anything.** Any question of the form "does it render?",
+"is the page actually working?", "did the markers show up?", "what does it look
+like?" is answered by opening it on this desktop and screenshotting it — not by
+reasoning about the code, and not by a headless render (which proves the process
+starts, not that the thing draws). Verify visually before you report visually.
+
+- **Input** — \`xdotool\` against \`DISPLAY=:0\`: \`DISPLAY=:0 xdotool mousemove <x> <y>\`,
+  \`DISPLAY=:0 xdotool click 1\` (1=left, 3=right), \`DISPLAY=:0 xdotool type 'text'\`,
+  \`DISPLAY=:0 xdotool key Return\` (also \`ctrl+c\`, \`Tab\`, \`super\`, …).
+- **Screenshots** — \`scrot\` (or ImageMagick's \`import\`):
+  \`DISPLAY=:0 scrot /tmp/screen.png\`, then READ the PNG to see the screen,
+  before and after you act. A screenshot is your only eyes here.
+- **Apps + windows** — a plain X session. Launch in the background:
+  \`DISPLAY=:0 <app> &\`. Two things that trip agents up, both normal:
+  - a GUI app needs a **beat to map its window** — screenshot, and if you see
+    only wallpaper, wait a couple of seconds and screenshot again before
+    concluding anything;
+  - **Chromium needs \`--no-sandbox\`** in this environment (nested sandbox).
+    The whole recipe for looking at a local page:
+    \`DISPLAY=:0 chromium --no-sandbox --disable-gpu --start-maximized <url> &\`
+    then \`sleep 5\`, then \`DISPLAY=:0 scrot /tmp/screen.png\` and read it.
+  If a window still never appears, read the app's own log (\`/tmp/*.log\`) — the
+  desktop is not the thing that failed. Do NOT abandon it for a headless
+  screenshot: headless cannot tell you what the human will see.
+- **A human can watch** — the session header carries a **Desktop** button in the
+  dashboard, and what a teammate sees there is exactly this display. The desktop
+  runs whether or not anyone is looking; never wait for a viewer.
+
+Nothing here changes the credentials rule above: tokens are injected at the
+network layer, never present on the desktop or in any file you can read — so
+there is nothing to type, paste, or screenshot a credential from.
+
+## Recording a demo — the desktop, captured to a video the human can play
+
+"Record a demo of you using X" is a normal ask, and this machine does it:
+start a screen recording, drive the app with \`xdotool\` exactly as in Computer
+Use, stop the recording, and report the file. (For a LIVE view no recording is
+needed — the session header's **Desktop** button already streams this display
+to any teammate watching; a recording is the durable, replayable artifact.
+Both modes exist; say so when it matters.)
+
+**ffmpeg is NOT pre-installed** — install it first, once per machine:
+
+    sudo apt-get update -q && sudo apt-get install -y -q ffmpeg
+
+(drop \`sudo\` if you are already root). Then the whole recipe:
+
+    DISPLAY=:0 ffmpeg -f x11grab \\
+      -video_size "$(DISPLAY=:0 xdotool getdisplaygeometry | tr ' ' x)" \\
+      -framerate 10 -i :0 -c:v libvpx -b:v 1M -deadline realtime -cpu-used 8 \\
+      demo.webm &
+    FFMPEG_PID=$!
+    # ... drive the app with xdotool, screenshotting as you go ...
+    kill -INT "$FFMPEG_PID" && wait "$FFMPEG_PID"
+
+The gotchas, each one earned:
+- **Stop with SIGINT (\`kill -INT\`), never SIGKILL** — ffmpeg finalizes the
+  file on SIGINT; a hard kill truncates the encode mid-write.
+- **Record WebM (matroska-family), not MP4** — mp4 writes its moov atom at the
+  END, so a killed or crashed encode leaves an UNPLAYABLE file; webm stays
+  playable up to the last written frame and plays natively in the browser.
+  MP4's only edge is compatibility with some external players — transcode
+  afterwards if you truly need it, never record straight to it.
+- **\`-video_size\` must match the real screen** — x11grab does not default to
+  it; read the geometry from \`xdotool getdisplaygeometry\` as above.
+- **10–12 fps is right for a screen demo** — small files, legible UI motion;
+  this is not video production.
+- **Write to the drive, not /tmp** — the recording must land in your working
+  directory to persist and show up in Files; a file in /tmp dies with the
+  sandbox.
+- When you stop, **TELL the human the exact drive path** of the video — a
+  recording they cannot find might as well not exist.
+
+## Previews — register every server you serve (cloud sessions)
+
+In a cloud session, a dev server listening on a port becomes a hosted,
+member-gated URL the human can open — but ONLY if you register it:
+
+    agentc preview open <port> [--name <label>] [--path </landing>]
+                                                 # hosted URL + an "Open preview" card
+    agentc preview list                          # the registry — what is live right now
+    agentc preview close <port>                  # take one down
+
+(\`agentc preview announce\` is the same verb as \`open\` — announce what you
+serve.) \`--name\` is the human-readable label; \`--path\` is where the app
+should open (e.g. \`/dashboard\`) — the card and every chip land the human
+there instead of a bare \`/\`.
+
+Register EVERY server you start for a human, the moment it is listening, and
+tell them the URL the command printed. The registry is the only discoverable
+record of what this machine serves: an unregistered server keeps running, but
+nobody — not the human, not the assistant — can find its URL, and when the
+sandbox recycles it is gone without a trace. Never guess or hand out a raw
+port; the hosted URL from \`agentc preview open\` is the only address that
+works outside this machine. (Outside a cloud session the command errors
+honestly — there is no session sandbox to expose.)
+
+What registration buys you: the human sees each registered preview as a card
+in the conversation and a row in the session's Previews menu — MANY at once,
+one per port — and the assistant resolves "open the preview" from this same
+registry (its \`list_previews\` read), so what you register is exactly what
+gets opened. On deployments with subdomain previews the hosted URL is a real
+origin of its own — absolute asset paths and client-side routing work, the
+whole app is navigable — so serve normally and let the platform address it;
+never rewrite your app to a path prefix.
+
 ## Tools in this environment
 
 - \`agentc\` — Agent Compose CLI (your primary interface; authed from env)
 - \`@agent-compose/sdk\` — installed in /workspace for writing workflows
 - \`/ac:*\` Claude Code skills — slash commands for the above
 - \`archil\` (factory drive), \`rtk\`, \`bun\`
+- \`xdotool\` / \`scrot\` — drive + screenshot the desktop (if this machine has one; see Computer Use)
 - A world-writable \`/workspace\` working directory`;
 
+/** Parameters for the `agentc session add` education brief (ADR-0055 §8). */
+export interface AddedSessionBriefParams {
+  conversationId: string;
+  serverUrl: string;
+  dashboardUrl: string | null;
+}
+
+/**
+ * The education brief `agentc session add` writes into a connected LOCAL
+ * session's CLAUDE.md/AGENTS.md — the same content family as
+ * `AGENT_COMPOSE_MANUAL`, rendered for the local context (one source,
+ * rendered per context). The manual above must stay BYTE-IDENTICAL (the
+ * server and base-env bake static copies of it); this function renders a
+ * sibling document and never touches it. The local context differs from the
+ * sandbox in exactly the ways stated here: auth rides the bridge credential
+ * fallback instead of injected run env; no factory drive is mounted — the
+ * files on this machine belong to the human; and the bound conversation is
+ * MIRROR-ONLY (ADR-0055 §8.6) — teammates read along but can never message
+ * the session through it, so the brief must not promise an inbound channel.
+ */
+export function buildAddedSessionBrief(p: AddedSessionBriefParams): string {
+  const dashboardSection = p.dashboardUrl === null ? "" : `
+
+## Dashboard
+
+Teammates follow this conversation (and the rest of the factory) in the
+Agent Compose dashboard: ${p.dashboardUrl}`;
+
+  return `# Connected to Agent Compose
+
+Agent Compose is your team's agent platform: durable conversations,
+workflow runs, and shared factory drives where humans and agents work
+together. THIS terminal's claude-code session is connected to Agent
+Compose conversation \`${p.conversationId}\` on ${p.serverUrl}.
+
+That conversation is a LIVE, READ-ONLY MIRROR of this terminal session:
+teammates read along in the dashboard as the work happens, but they cannot
+message you through it — anything posted there is answered by the server
+with a notice and never reaches this terminal. Everything you do here is
+mirrored automatically; you have an audience, not a channel.
+
+## The \`agentc\` toolbelt
+
+The \`agentc\` CLI works from this shell. It is already authenticated on
+this machine via the bridge credential fallback — no keys to manage,
+commands just work:
+
+    agentc list                          # registered workflows
+    agentc logs <run-id>                 # a run's logs
+    agentc invoke <workflow> -i '<json>' # dispatch a workflow
+    agentc events list                   # read the factory timeline
+
+## Scope — this is your LOCAL machine
+
+The files here are YOURS: no factory drive is mounted in this session,
+and nothing you write locally lands on a shared drive by itself. Cloud
+drive/branch semantics (per-run directories on the factory drive, drive
+branches, persist-by-default outputs) apply only to cloud sessions —
+not here.${dashboardSection}
+`;
+}
+
 /**
  * One connector this run can reach, as the agent should see it. Strictly
  * NON-SECRET — hosts, methods, paths, identity only. The access token is

package/src/agent/agent-loop.ts

@@ -39,6 +39,24 @@ export function parseAgentStatus(text: string): AgentStatus | null {
 
 const DEFAULT_ALLOWED_TOOLS = ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "WebFetch"];
 
+/**
+ * A `responseSchema` rendered for the runtime's structured-output surface.
+ *
+ * zod v4's `toJSONSchema` stamps `$schema: "…/draft/2020-12/schema"` on the
+ * result. Claude Code validates `--json-schema` with a validator that has no
+ * 2020-12 meta-schema registered, so any schema CARRYING that header is
+ * rejected at CLI startup — the process exits 1 before its first API call
+ * and every agent with a responseSchema dies on spawn (observed live on
+ * claude 2.1.212: `--json-schema is not a valid JSON Schema: no schema with
+ * key or ref "https://json-schema.org/draft/2020-12/schema"`). The header is
+ * pure metadata — drop it; the schema body is draft-07-compatible for every
+ * shape zod emits from our workflow schemas.
+ */
+export function runtimeJsonSchema(schema: z.ZodType<unknown>): Record<string, unknown> {
+  const { $schema: _$schema, ...rest } = z.toJSONSchema(schema) as Record<string, unknown>;
+  return rest;
+}
+
 export interface AgentLoopResult<TResponse = unknown> {
   agentId:     string;
   label:       string;
@@ -71,7 +89,12 @@ function preview(value: unknown): string {
   }
 }
 
-export function summarizeAgentMessage(msg: AgentMessage): AgentMessageSummary {
+/** Everything but the live-only streaming chunk: `text_delta` never becomes
+ *  an agent.message event (the terminating `text` carries the whole block) —
+ *  the loop filters it before summarizing. */
+type DurableAgentMessage = Exclude<AgentMessage, { type: "text_delta" } | { type: "usage_delta" }>;
+
+export function summarizeAgentMessage(msg: DurableAgentMessage): AgentMessageSummary {
   switch (msg.type) {
     case "init": return { type: "init", sessionId: msg.sessionId };
     case "text": return { type: "text", text: msg.text };
@@ -103,6 +126,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; agentId: string; label: string; iteration: number; message: AgentMessageSummary }
   | { event: "agent.iteration"; at: number; agentId: string; label: string; iteration: number; status: AgentStatus | null }
@@ -111,6 +139,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;
@@ -208,7 +239,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     // `session/request_permission` path through CliAgentRunner.gateToolCall) can
     // raise a human-approval `ctx.pause`, not just on the loop's own hooks.
     ...(opts.pause ? { pause: opts.pause } : {}),
-    ...(opts.responseSchema ? { outputFormat: { type: "json_schema" as const, schema: z.toJSONSchema(opts.responseSchema) as Record<string, unknown> } } : {}),
+    ...(opts.responseSchema ? { outputFormat: { type: "json_schema" as const, schema: runtimeJsonSchema(opts.responseSchema) } } : {}),
   });
 
   // Heads-up when a caller registers tool-call gating on a runtime that
@@ -284,6 +315,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
       ...(client.model       != null ? { model:       client.model       } : {}),
       ...(client.kind        != null ? { runtimeKind: client.kind        } : {}),
+      ...(opts.phase         != null ? { phase:       opts.phase         } : {}),
     });
   }
 
@@ -428,6 +460,11 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       signal: loopAbort.signal,
       ...(opts.inbox ? { inboxStream: opts.inbox } : {}),
     })) {
+      // Live-only streaming chunk: the terminating `text` message carries
+      // the complete block, so the loop (accumulation, events, processors)
+      // ignores deltas — they exist for progressive-rendering consumers
+      // (the conversation cloud executor), not the workflow event stream.
+      if (rawMsg.type === "text_delta" || rawMsg.type === "usage_delta") continue;
       // processOutput chain — deny drops the message from accumulation;
       // abort ends the loop. Continue carries the (possibly mutated)
       // message forward.
@@ -441,6 +478,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
         continue;
       }
       const msg = outputVerdict.value;
+      if (msg.type === "text_delta" || msg.type === "usage_delta") continue; // a processor cannot re-introduce a live-only chunk
       opts.onAgentEvent?.(iteration, msg);
       // Usage summaries carry the resolved model so the server can price
       // token rows per model without correlating back to agent.spawned.

package/src/agent/run-agent.ts

@@ -183,6 +183,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> };
   /** Per-message event callback — wire this to your workflow's event
@@ -349,6 +353,7 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
     runtime: (runtimeOpts: RuntimeOptions) => opts.runtime.create(opts.sandbox, { ...runtimeOpts, agentManual: buildAgentContextDoc(process.env) }),
     agentId,
     ...(opts.label !== undefined ? { label: opts.label } : {}),
+    ...(opts.phase !== undefined ? { phase: opts.phase } : {}),
     ...(opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {}),
     ...(opts.budget?.maxIterations     !== undefined ? { maxIterations:     opts.budget.maxIterations }     : {}),
     ...(opts.tools                      !== undefined ? { allowedTools:      opts.tools }                    : {}),