@agent-compose/sdk 0.5.7 → 0.5.9

package/src/agent/agent-context.ts

@@ -0,0 +1,220 @@
+/**
+ * Harness-agnostic agent context delivery.
+ *
+ * Every coding-agent harness we drive (Claude Code, Codex, Amp, Gemini, …)
+ * looks for an instruction file in its working directory — but they disagree
+ * on the NAME (Codex/Amp read `AGENTS.md`; Claude reads `CLAUDE.md`; Gemini
+ * reads `GEMINI.md`). So `agent()` writes the SAME platform manual under all
+ * three names at the agent's working dir, and every harness finds the one it
+ * knows. The manual is the single source of truth here; `base-env` bakes a
+ * static copy at `/workspace/AGENTS.md` for plain shell sessions, but the
+ * per-run copy `agent()` writes is the authoritative one — it carries the
+ * live connector list and lands at the run's working dir.
+ */
+
+import type { SandboxProvider } from "../types/sandbox.js";
+
+/**
+ * The platform manual delivered to every agent, regardless of harness.
+ * Covers the three things an agent must know: where files go (the factory
+ * drive + the persist-by-default working dir), how to pause for a human, and
+ * that credentials are network-injected (never in the env). The live
+ * "Connectors & access" section is appended per-run by `buildAgentContextDoc`.
+ */
+export const AGENT_COMPOSE_MANUAL = `# Working inside an Agent Compose sandbox
+
+You are an agent running in a per-run sandbox on the Agent Compose platform.
+Use the **\`agentc\` CLI** and the **\`@agent-compose/sdk\`** for everything below —
+do NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on
+your PATH and already authenticated from the environment
+(\`AGENT_COMPOSE_URL\` / \`AGENT_COMPOSE_API_KEY\` / \`AGENT_COMPOSE_FACTORY\` are
+injected for this run), so commands just work — no login, no keys to manage.
+
+The \`/ac:*\` skills are installed as Claude Code slash commands (\`/ac:invoke\`,
+\`/ac:events\`, \`/ac:logs\`, \`/ac:register\`, …) — reach for them too.
+
+## Files — your outputs persist by default
+
+Your working directory defaults to **\`\$AGENT_COMPOSE_RUN_DIR\`** — a per-run
+directory on the shared factory drive
+(\`\$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/\`) the platform
+creates and attributes to this run. **Files you write here persist by
+default** — they show up in the dashboard's Files tab and the run's Artifacts
+card, with no API calls to save them. The dir already exists and is writable.
+
+Need throwaway scratch — heavy build output, package caches, temp files?
+\`cd /tmp\` (or any path outside \`/factory\`): anything off the factory drive is
+ephemeral and discarded when the sandbox ends. In short: **stay in your working
+dir to keep something, \`cd\` out to throw it away.**
+
+The whole shared drive is POSIX-mounted at \`/factory\`; the dashboard-visible
+root is \`\$AGENT_COMPOSE_FACTORY_DIR\` (\`/factory/files\`). Earlier versions and
+runs live in sibling dirs under
+\`\$AGENT_COMPOSE_FACTORY_DIR/\$AGENT_COMPOSE_WORKFLOW/\` — read them for prior
+context. Other workflows' dirs are present but not your concern.
+
+## Events — the factory timeline
+
+Record something on the run/factory timeline (the dashboard renders these)
+with the CLI — your run id is \`$RUN_ID\`:
+
+    agentc events send "$RUN_ID" <name> --summary "<one line>" [--body '<json>']
+
+Names like \`note.created\` / \`brief.posted\` surface in the Workbench;
+\`agentc events list\` reads them back. \`/ac:events\` is the skill equivalent.
+
+## Runs
+
+    agentc list                          # registered workflows  (/ac:list)
+    agentc logs "$RUN_ID"                # a run's logs           (/ac:logs)
+    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)
+
+## Writing workflow / agent code — the SDK
+
+\`@agent-compose/sdk\` is installed in \`/workspace\` — import it from any script
+you write there:
+
+    import { defineWorkflow, agent, AgentComposeClient } from "@agent-compose/sdk";
+
+Use \`/ac:generate-workflow\` / \`/ac:generate-agent\` to scaffold, then
+\`agentc register <file.ts>\` (or \`/ac:register\`).
+
+## Pausing to ask the human — \`agentc pause\`
+
+When you can't or shouldn't proceed without a human, run \`agentc pause\`, then
+**END YOUR TURN**:
+
+    agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
+                 --option retry --option skip
+
+\`agentc pause\` does NOT block and does NOT print the answer. It records your
+question and returns immediately. The moment you end your turn, the run pauses
+(your sandbox is snapshotted and compute stops while the human decides) and the
+human's answer is delivered to you as your **next message** — you pick up
+exactly where you left off, with the answer in hand. So: ask, end your turn,
+and wait. Do NOT keep working, do NOT call more tools, and do NOT mark the task
+complete after pausing.
+
+Reach for it the moment you hit — or foresee — any of these:
+- **A wall only a human can clear:** a 401/403, a missing credential, an
+  unconnected provider, a host the network refuses. Do NOT retry blindly or try
+  to work around it — pause and say what needs enabling.
+- **A durable or outward-facing action that needs sign-off:** registering a
+  workflow, deploying, sending email/messages, deleting or overwriting shared
+  data, spending money. Prepare everything, then pause for approval BEFORE you
+  commit it.
+- **A judgment call only the human can settle:** an under-specified request,
+  several valid paths, a conflict with existing state, missing input only they have.
+
+You compose the \`--reason\` (the ask) yourself; pass \`--option\` choices when
+there are clear ones, omit them for a free-form answer. Each agent pauses
+independently — pausing doesn't stop the others.
+
+## Credentials
+
+Connector credentials (Google, GitHub, …) are NEVER in your environment.
+They're injected at the network layer when you call an allowed host — make the
+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.
+
+## 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\`
+- A world-writable \`/workspace\` working directory`;
+
+/**
+ * One connector this run can reach, as the agent should see it. Strictly
+ * NON-SECRET — hosts, methods, paths, identity only. The access token is
+ * injected at the network layer and never appears here. The server builds
+ * this list at dispatch from the run's connector grants × the provider
+ * catalogue and delivers it as the `AGENT_COMPOSE_CONNECTORS` env (JSON array).
+ */
+export interface AgentConnectorInfo {
+  /** Provider key (`github`, `notion`, …). */
+  provider: string;
+  /** Human label ("GitHub", "Notion"). */
+  name?: string;
+  /** API hosts the credential is injected for. */
+  hosts?: string[];
+  /** Allowed HTTP methods (Tier-2 narrowing). Empty/absent = any. */
+  methods?: string[];
+  /** Allowed path prefixes (Tier-2 narrowing). Empty/absent = any. */
+  pathPrefixes?: string[];
+  /** GitHub: the repository the minted token is scoped to. */
+  repository?: string;
+  /** Coarse capability the token was minted with. */
+  access?: string;
+  /** Human scope descriptions, when the provider declares them. */
+  scopes?: string[];
+}
+
+/** Render the per-run "Connectors & access" markdown section, or "" when the
+ *  run brokers no connectors. */
+function renderConnectorsSection(connectors: AgentConnectorInfo[]): string {
+  if (connectors.length === 0) return "";
+  const rows = connectors.map((c) => {
+    const host  = c.hosts?.length ? c.hosts.join(", ") : "(host set by the platform)";
+    const verbs = c.methods?.length ? c.methods.join("/") : "any method";
+    const paths = c.pathPrefixes?.length ? ` under ${c.pathPrefixes.join(", ")}` : "";
+    const repo  = c.repository ? ` — repo \`${c.repository}\` (${c.access ?? "read"})` : "";
+    const why   = c.scopes?.length ? `  \n  _scopes: ${c.scopes.join(", ")}_` : "";
+    return `- **${c.name ?? c.provider}** → \`${host}\` — ${verbs}${paths}${repo}${why}`;
+  });
+  return `
+
+## Connectors & access — what this run can reach
+
+These providers are connected for this run. Call their APIs with plain
+fetch/SDKs and **no Authorization header** — the platform injects the
+credential at the network layer. Requests outside the listed method/path are
+refused (403) and the token withheld. Anything NOT listed is unreachable; if
+you need it, \`agentc pause\` and ask for it to be connected.
+
+${rows.join("\n")}
+`;
+}
+
+/** Compose the full per-run agent doc: the static manual + the live
+ *  connectors section read from `AGENT_COMPOSE_CONNECTORS` (a JSON array;
+ *  malformed/absent → no section). */
+export function buildAgentContextDoc(env: Record<string, string | undefined>): string {
+  let connectors: AgentConnectorInfo[] = [];
+  const raw = env.AGENT_COMPOSE_CONNECTORS;
+  if (raw) {
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (Array.isArray(parsed)) connectors = parsed as AgentConnectorInfo[];
+    } catch { /* malformed manifest — render the manual without a connectors section */ }
+  }
+  return AGENT_COMPOSE_MANUAL + renderConnectorsSection(connectors);
+}
+
+/**
+ * Write the platform context at the agent's working dir under every harness's
+ * instruction-file name, so whichever CLI runs finds the one it reads. Codex
+ * and Amp read `AGENTS.md` natively; Claude reads `CLAUDE.md`; Gemini reads
+ * `GEMINI.md` — we write identical content to all three rather than detect the
+ * harness (the runtime's `kind` isn't known until after spawn, and a few extra
+ * small files in our own run dir are harmless).
+ *
+ * Best-effort: a write failure logs and is swallowed — never fail an agent
+ * because its context file couldn't be written.
+ */
+export async function writeAgentContext(args: {
+  sandbox: Pick<SandboxProvider, "files">;
+  cwd: string;
+  env: Record<string, string | undefined>;
+}): Promise<void> {
+  const doc = buildAgentContextDoc(args.env);
+  const dir = args.cwd.replace(/\/+$/, "") || "/workspace";
+  // AGENTS.md is the cross-harness standard; CLAUDE.md / GEMINI.md are the
+  // per-harness names. Same content under each — the harness that doesn't read
+  // a given name simply ignores it.
+  for (const name of ["AGENTS.md", "CLAUDE.md", "GEMINI.md"]) {
+    await args.sandbox.files.write(`${dir}/${name}`, doc);
+  }
+}

package/src/agent/agent-loop.ts

@@ -9,16 +9,24 @@ import { AgentStatusSchema, parseAgentResponse } from "./protocol.js";
 import type { AgentStatus, AgentMessage } from "./protocol.js";
 import { randomUUID } from "node:crypto";
 import type { Processor, ProcessorContext } from "../processors/processor.js";
+import { boundProcessorPause, type BoundaryPauseFn } from "../pause/pause-core.js";
 import { runProcessorChain } from "../processors/runner.js";
 import { RequestContext } from "../request-context/request-context.js";
 import { PauseManager } from "../pause/manager.js";
 import { PauseSignal, isPauseSignal } from "../pause/pause-core.js";
 import { SteerDecisionSchema, type SteerDecision, type SteerPayload } from "./steer-control.js";
+import { type LocalPauseRequest } from "./local-pause-request.js";
 
 export const DEFAULT_CLAUDE_MODEL = "claude-fable-5";
 
 const SAME_BLOCKER_ITERATIONS = 3;
-const STALL_ITERATIONS        = 3;
+// Consecutive turns with NEITHER a <status> NOR a <response> before the loop
+// declares the agent wedged. Kept generous because the most common benign
+// cause is an agent that launched a useful BACKGROUND job and is waiting to be
+// "notified" — the corrective re-prompt (below) tells it to poll synchronously,
+// and these extra turns give that nudge (and the job) time to land before we
+// give up.
+const STALL_ITERATIONS        = 6;
 const MESSAGE_PREVIEW_CHARS   = 400;
 
 export function parseAgentStatus(text: string): AgentStatus | null {
@@ -47,9 +55,10 @@ export type AgentMessageSummary =
   | { type: "thinking"; text: string }
   | { type: "tool_use"; toolName: string; toolUseId: string; toolInput: Record<string, unknown>; toolInputPreview: string }
   | { type: "tool_result"; toolUseId: string; output: string; isError: boolean }
-  | { type: "usage"; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheCreationTokens: number; durationMs: number; numTurns: number }
+  | { type: "usage"; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheCreationTokens: number; durationMs: number; numTurns: number; model?: string }
   | { type: "done"; sessionId: string }
-  | { type: "error"; text: string };
+  | { type: "error"; text: string }
+  | { type: "plan"; entries: { content: string; priority: "high" | "medium" | "low"; status: "pending" | "in_progress" | "completed" }[] };
 
 function truncate(value: string): string {
   return value.length > MESSAGE_PREVIEW_CHARS ? `${value.slice(0, MESSAGE_PREVIEW_CHARS)}…` : value;
@@ -77,6 +86,11 @@ export function summarizeAgentMessage(msg: AgentMessage): AgentMessageSummary {
     };
     case "done": return { type: "done", sessionId: msg.sessionId };
     case "error": return { type: "error", text: truncate(msg.text) };
+    // ACP `plan` (WS-C / ADR-0020 Q2). Pure observability — forwarded to
+    // onAgentEvent / agent.message; it is NOT an AgentStatus and never feeds
+    // self-pause. Pass the entries straight through (the dashboard renders the
+    // structured plan; no preview truncation needed — entries are short).
+    case "plan": return { type: "plan", entries: msg.entries };
   }
 }
 
@@ -129,19 +143,24 @@ export interface AgentLoopOpts<TResponse = unknown> {
    * streaming input (ignored otherwise — handled at the runtime).
    */
   inbox?: import("./async-queue.js").AsyncQueue<{ text: string; senderName?: string | null }>;
-  /** PR 7 steer-pause: the boundary calls this to pause the workflow for a
-   *  human steer. agent() builds it (a corePause closed over runId/stepIndex);
-   *  the loop supplies the agentScope so the pauseId is stable across resume.
-   *  Absent ⇒ no steer pause (local tests, non-sandbox callers). */
-  pause?: <T = unknown>(
-    req: { reason: string; correlationKey?: string; schema?: z.ZodType<T> },
-    agentScope: { agentId: string; iteration: number },
-  ) => Promise<T>;
+  /** The run's pause boundary. agent() builds it (a corePause closed over
+   *  runId/stepIndex); the loop supplies the agentScope so the pauseId is
+   *  stable across resume. Drives both PR-7 steer-pause AND a processor's
+   *  `ctx.pause` (human-approval gate). Absent ⇒ no pause (local tests,
+   *  non-sandbox callers). */
+  pause?: BoundaryPauseFn;
   /** PR 7: take-once read of this agent's pending steer (set by the control
    *  poller). Returns the steer's payload (reason / correlationKey) or null.
    *  The boundary consumes it once per check, and only when no steer is
    *  already staged. */
   consumeSteerPending?: () => SteerPayload | null;
+  /** Take-once read of a local `agentc pause` request this agent dropped in the
+   *  state dir during its turn (the CLI writes it; see local-pause-request.ts).
+   *  Returns the request (reason + offered options) or null. The loop turns it
+   *  into a staged self-pause the next boundary takes — the same snapshot-release
+   *  path as `needs_input`, but triggered by an explicit `agentc pause` call so
+   *  it is honored regardless of `mode`. */
+  consumeLocalPauseRequest?: () => LocalPauseRequest | null;
   /** PR 7: `auto` (autonomous, default) or `hitl` (can be steer-paused). The
    *  boundary is inert unless `hitl`. */
   mode?: "auto" | "hitl";
@@ -174,6 +193,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     retryCount:  0,
     agentId,
     iteration,
+    pause: boundProcessorPause(opts.pause, { agentId, iteration }),
   });
 
   if (!opts.runtime) throw new Error("agentLoop: opts.runtime is required");
@@ -185,6 +205,10 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     processors,
     requestContext,
     agentId,
+    // Thread the pause boundary so a runtime-driven pre-tool gate (e.g. the ACP
+    // `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> } } : {}),
   });
 
@@ -216,7 +240,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
   let resumed = false;
   // PR 7: a pending human steer-pause intent. Persisted in loop state so it
   // survives a resume and the boundary re-issues the pause on re-entry.
-  let pendingSteerPause: { reason: string; correlationKey: string | null; at: number } | null = null;
+  let pendingSteerPause: { reason: string; correlationKey: string | null; at: number; payload?: Record<string, unknown> } | null = null;
 
   const pauseManager = new PauseManager(agentId);
   const restore = await pauseManager.restoreAgentLoop<TResponse>(client);
@@ -336,6 +360,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
           {
             reason: pendingSteerPause.reason,
             ...(pendingSteerPause.correlationKey !== null ? { correlationKey: pendingSteerPause.correlationKey } : {}),
+            ...(pendingSteerPause.payload !== undefined ? { payload: pendingSteerPause.payload } : {}),
             schema: SteerDecisionSchema,
           },
           { agentId, iteration },
@@ -397,6 +422,11 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       // (otherwise it restarts the task in a fresh session and repeats side effects).
       sessionId: lastSessionId ?? undefined,
       iteration: iteration + 1,
+      // Thread the loop's abort signal so a runtime that owns a cancellable
+      // transport (the ACP path's `session/cancel`, ADR-0020) actually unwinds
+      // when the loop aborts — input/output processor `abort`, or any external
+      // cancel. Without this the cancel/session-cancel wiring is dead.
+      signal: loopAbort.signal,
       ...(opts.inbox ? { inboxStream: opts.inbox } : {}),
     })) {
       // processOutput chain — deny drops the message from accumulation;
@@ -413,7 +443,13 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       }
       const msg = outputVerdict.value;
       opts.onAgentEvent?.(iteration, msg);
-      opts.onAgentLifecycleEvent?.({ event: "agent.message", at: Date.now(), agentId, label, iteration: iteration + 1, message: summarizeAgentMessage(msg) });
+      // Usage summaries carry the resolved model so the server can price
+      // token rows per model without correlating back to agent.spawned.
+      const summary = summarizeAgentMessage(msg);
+      opts.onAgentLifecycleEvent?.({
+        event: "agent.message", at: Date.now(), agentId, label, iteration: iteration + 1,
+        message: summary.type === "usage" && client.model != null ? { ...summary, model: client.model } : summary,
+      });
       if (msg.type === "init")  lastSessionId = msg.sessionId;
       if (msg.type === "text")  responseText += msg.text;
       if (msg.type === "error") throw new Error(`Agent error: ${msg.text}`);
@@ -425,6 +461,31 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     lastResponseText = responseText;
 
     let status = parseAgentStatus(responseText);
+
+    // `agentc pause` — the agent shelled out to the CLI during this turn, which
+    // dropped a durable pause-request marker in the state dir. Honor it like a
+    // self-pause: stage the pause the NEXT boundary takes, carrying the agent's
+    // question as the reason and any offered choices as the pause payload (the
+    // dashboard renders them as buttons). Checked BEFORE the settle / needs_input
+    // paths and independent of the <status> block — the common case is an agent
+    // that called the tool and ended its turn with no status at all, which would
+    // otherwise fall through to the empty-output re-prompt below. UNGATED by
+    // `mode`: an explicit `agentc pause` is a deliberate ask, not the `needs_input`
+    // heuristic that only `hitl` agents may trigger.
+    if (opts.pause && pendingSteerPause === null) {
+      const localPause = opts.consumeLocalPauseRequest?.() ?? null;
+      if (localPause) {
+        pendingSteerPause = {
+          reason:         localPause.reason,
+          correlationKey: null,
+          ...(localPause.options && localPause.options.length > 0 ? { payload: { options: localPause.options } } : {}),
+          at:             Date.now(),
+        };
+        blockerStreak = null;   // an explicit ask is not a stuck loop
+        continue;               // pause fires at the next boundary
+      }
+    }
+
     // Inline safeParse (instead of letting parseAgentResponse validate)
     // so a schema failure surfaces via lastResponseValidationError on
     // the next iteration — the model needs that feedback to fix its
@@ -511,15 +572,22 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     if (!status && rawResponse === null) {
       if (++iterationsWithoutStatus >= STALL_ITERATIONS)
         throw new Error(`${logLabel} stalled: no <status> block after ${iterationsWithoutStatus} iterations`);
-      // EMPTY-OUTPUT RE-PROMPT: under the unbudgeted default (maxIterations 1)
-      // a single turn that emits neither <status> nor <response> would
-      // otherwise exhaust the budget with ZERO corrective feedback. Treat it
-      // like the contract-violation branches — refund the iteration and
-      // re-prompt with explicit feedback, bounded by the shared retry pool.
-      // The stall counter above still hard-bounds consecutive empty turns.
-      if (opts.responseSchema && schemaRetriesLeft-- > 0) {
-        lastResponseValidationError = "no <response> block found — the turn ended with neither a <status> nor a <response> block; emit the complete <response> JSON";
-        process.stdout.write(`${logLabel} no <status>/<response> emitted — corrective re-prompt (${schemaRetriesLeft} retries left)\n`);
+      // EMPTY-OUTPUT RE-PROMPT: a turn that emits neither <status> nor
+      // <response>. Refund the iteration and re-prompt with explicit feedback
+      // (bounded by the shared retry pool); the stall counter above still
+      // hard-bounds genuinely wedged agents. The directive call-out about
+      // BACKGROUND jobs is load-bearing: the dominant benign cause is an agent
+      // that ran `cmd &` and parked itself "waiting to be notified" — the loop
+      // delivers no such notification, so it must poll synchronously instead.
+      // Fires with or without a responseSchema (an agent with no schema still
+      // owes a <status>).
+      if (schemaRetriesLeft-- > 0) {
+        lastResponseValidationError =
+          "Your turn ended with no <status> block" + (opts.responseSchema ? " (and no <response> block)" : "") + ". " +
+          "If you launched a background job (`… &`) and are waiting to be notified when it finishes — STOP: nothing will notify you here. " +
+          "Poll it NOW (read its output / wait for it synchronously to completion), then emit your <status>" +
+          (opts.responseSchema ? " and the complete <response> JSON." : ".");
+        process.stdout.write(`${logLabel} empty turn (no <status>) — corrective re-prompt (${schemaRetriesLeft} retries left)\n`);
         iteration--;
         continue;
       }

package/src/agent/local-pause-request.ts

@@ -0,0 +1,90 @@
+/**
+ * Local pause-request marker — the in-sandbox bridge from `agentc pause` to
+ * the agent loop's snapshot-release pause boundary.
+ *
+ * `agentc pause` runs as a grandchild subprocess of the runner (the agent CLI
+ * shells out to it). It cannot throw a `PauseSignal` into the loop and the
+ * in-memory steer flag (`signalSteerPending`) lives in a different process, so
+ * the only reliable channel is the shared sandbox filesystem. The CLI writes a
+ * durable marker here; the agent loop consumes it at the end of the turn
+ * (alongside the `needs_input` self-pause) and stages a real `ctx.pause` the
+ * next boundary takes — which snapshots the sandbox, releases the activity
+ * (compute stops), and parks the workflow. On resume the human's answer is
+ * delivered as the agent's next user turn.
+ *
+ * This is the ONLY place the marker path + shape are defined — both the CLI
+ * (writer) and the SDK loop (reader) import it, so the two halves can never
+ * drift. Like the rest of the state-dir, the layout is a wire protocol between
+ * the runner and the next subprocess invocation (ADR-0006). The marker is
+ * consumed BEFORE the snapshot, so it never needs to survive a pause.
+ *
+ * Scoped by `agentId` so concurrent `agent()` calls sharing one sandbox each
+ * see only their own request. When the id is unavailable (older agent env that
+ * doesn't inject `AGENT_COMPOSE_AGENT_ID`) both sides fall back to a single
+ * unscoped slot — correct for the common single-agent step, and the only case
+ * where an unscoped marker can be ambiguous (two anonymous agents) is one the
+ * old block-poll CLI couldn't handle either.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+import { getStateDir } from "../pause/state-dir.js";
+
+/** A choice offered to the human. A bare string is shorthand for
+ *  `{ label, value }` with both equal — exactly what the dashboard's
+ *  `readOptions` accepts. */
+export type PauseOption = string | { label: string; value: string };
+
+/** What `agentc pause` records for the loop to turn into a `ctx.pause`. */
+export interface LocalPauseRequest {
+  /** The question shown to the human (becomes the pause `reason`). */
+  reason:   string;
+  /** Optional offered choices, rendered as buttons in the dashboard. */
+  options?: PauseOption[];
+}
+
+const UNSCOPED = "_unscoped";
+
+const requestsDir = () => join(getStateDir(), "pause-requests");
+const markerPath  = (agentId: string | undefined | null) =>
+  join(requestsDir(), `${slug(agentId) || UNSCOPED}.json`);
+
+/** Keep the agentId filename-safe. Agent ids are `step<idx>-agent-<n>` shaped,
+ *  but defend against anything exotic so the marker can never escape the dir. */
+function slug(agentId: string | undefined | null): string {
+  return (agentId ?? "").replace(/[^a-zA-Z0-9_.-]/g, "_");
+}
+
+/** Write the marker atomically (tmp → rename) so the loop never reads a
+ *  partial file mid-write. Called by `agentc pause`. */
+export function writeLocalPauseRequest(agentId: string | undefined | null, req: LocalPauseRequest): void {
+  mkdirSync(requestsDir(), { recursive: true });
+  const final = markerPath(agentId);
+  const tmp   = `${final}.${randomBytes(6).toString("hex")}.tmp`;
+  writeFileSync(tmp, JSON.stringify(req), "utf8");
+  renameSync(tmp, final);
+}
+
+/** Take-once read: returns + deletes this agent's pending pause request, else
+ *  null. Checks the agent-scoped slot first, then the unscoped fallback. The
+ *  loop calls this once per turn; a malformed marker is dropped (deleted +
+ *  null) rather than wedging the loop. */
+export function consumeLocalPauseRequest(agentId: string | undefined | null): LocalPauseRequest | null {
+  const paths = [...new Set([markerPath(agentId), markerPath(null)])]; // dedupe when agentId is absent
+  for (const path of paths) {
+    if (!existsSync(path)) continue;
+    try {
+      const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
+      rmSync(path, { force: true });
+      if (raw && typeof raw === "object" && typeof (raw as LocalPauseRequest).reason === "string" && (raw as LocalPauseRequest).reason.trim().length > 0) {
+        const r = raw as LocalPauseRequest;
+        return { reason: r.reason.trim(), ...(Array.isArray(r.options) && r.options.length > 0 ? { options: r.options } : {}) };
+      }
+    } catch {
+      rmSync(path, { force: true }); // unreadable / partial → drop it
+    }
+  }
+  return null;
+}

package/src/agent/run-agent.ts

@@ -13,14 +13,16 @@
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { getActiveStep, nextAgentCallInActiveStep } from "../active-step.js";
-import { corePause } from "../pause/pause-core.js";
+import { corePause, type PauseRequest } from "../pause/pause-core.js";
 import { agentLoop } from "./agent-loop.js";
 import { consumeSteerPending, runControlPoller } from "./steer-control.js";
+import { consumeLocalPauseRequest } from "./local-pause-request.js";
 import type { AgentLifecycleEvent, AgentLoopResult } from "./agent-loop.js";
 import { AsyncQueue } from "./async-queue.js";
 import type { AgentMessage, AgentStatus } from "../types/protocol.js";
 import type { AgentRuntime, RuntimeOptions } from "../types/runtime.js";
 import type { SandboxProvider } from "../types/sandbox.js";
+import { writeAgentContext } from "./agent-context.js";
 import type { AgentBudget } from "../types/workflow.js";
 import type { Processor } from "../processors/processor.js";
 import { RequestContext } from "../request-context/request-context.js";
@@ -232,7 +234,42 @@ export function resolveAgentId(explicitId?: string): string {
 }
 
 export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopResult<T>> {
-  const workingDir = opts.workingDir ?? "";
+  // Persist-by-default: an agent's working dir is the run dir on the factory
+  // drive (the mount step creates it ahead of the run), so everything it
+  // writes is kept and attributed to this run; `cd /tmp` for throwaway
+  // scratch. Falls back to /workspace when this run has no factory drive.
+  // Never "" — an empty cwd is the one case the harnesses' instruction-file
+  // upward-walk can't resolve, and it left codex/amp without their AGENTS.md.
+  let workingDir = opts.workingDir || process.env.AGENT_COMPOSE_RUN_DIR || "/workspace";
+
+  // Deliver the platform context (file conventions, connectors & access, how to
+  // pause) as AGENTS.md / CLAUDE.md / GEMINI.md at the working dir — and use the
+  // write as a LIVENESS PROBE of the working dir. AGENT_COMPOSE_RUN_DIR points at
+  // the /factory FUSE drive, whose writes HANG (uninterruptible, no timeout) when
+  // the mount degraded — launching the agent there wedges it silently with zero
+  // output (no logs). Bound the write; on timeout/failure fall back to /workspace
+  // (always present + writable) so a degraded drive can never sink an agent.
+  const CONTEXT_WRITE_DEADLINE_MS = 15_000;
+  const tryWriteContext = (cwd: string): Promise<boolean> => {
+    // Capture the deadline timer so the fast path (write resolves first) can
+    // clear it in finally — otherwise each probe leaks a dangling 15s timer.
+    // Mirrors sandbox.ts's clear-in-finally pattern.
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    return Promise.race([
+      writeAgentContext({ sandbox: opts.sandbox, cwd, env: process.env }).then(() => true),
+      new Promise<boolean>((resolve) => { timer = setTimeout(() => resolve(false), CONTEXT_WRITE_DEADLINE_MS); }),
+    ]).catch((err: unknown) => {
+      console.error(`[agent] writeAgentContext(${cwd}) failed: ${err instanceof Error ? err.message : String(err)}`);
+      return false;
+    }).finally(() => { if (timer) clearTimeout(timer); });
+  };
+  if (!(await tryWriteContext(workingDir)) && workingDir !== "/workspace") {
+    console.error(
+      `[agent] working dir ${workingDir} not writable within ${CONTEXT_WRITE_DEADLINE_MS}ms ` +
+      `(factory drive degraded?) — falling back to /workspace so the agent can run`);
+    workingDir = "/workspace";
+    await tryWriteContext(workingDir);
+  }
 
   // Stable agentId for this invocation. Used by the inbox URL (server
   // scopes pending messages by agentId), the agentLoop (which would
@@ -279,7 +316,7 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
   const activeStepForPause = getActiveStep();
   const steerPause = activeStepForPause && runId
     ? function steerPauseFn<T>(
-        req: { reason: string; correlationKey?: string; schema?: z.ZodType<T> },
+        req: PauseRequest<T>,
         agentScope: { agentId: string; iteration: number },
       ): Promise<T> {
         return corePause<T>(req, {
@@ -329,6 +366,9 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
     // PR 7 steer-pause wiring.
     mode,
     consumeSteerPending: () => consumeSteerPending(agentId),
+    // `agentc pause` self-pause: the loop reads the marker this agent's CLI
+    // dropped in the state dir and stages a snapshot-release pause from it.
+    consumeLocalPauseRequest: () => consumeLocalPauseRequest(agentId),
     ...(steerPause ? { pause: steerPause } : {}),
   });
   } finally {

package/src/agent/steer-control.ts

@@ -17,13 +17,27 @@
 import { z } from "zod";
 
 /** What a steer/resume answer carries. Used as the boundary pause's `schema`
- *  so it is validated client-side in the re-spawned runner — a null/empty
- *  message is rejected (PauseSchemaError) so an agent never resumes on an
- *  empty steer. `message` becomes the agent's next user turn. */
-export const SteerDecisionSchema = z.object({
-  message: z.string().min(1),
-  actor:   z.string().nullish(),
-});
+ *  so it is validated client-side in the re-spawned runner — an empty answer
+ *  is rejected (PauseSchemaError) so an agent never resumes on nothing. The
+ *  normalised `message` becomes the agent's next user turn.
+ *
+ *  Accepts BOTH resume-payload conventions and normalises to `{ message }`:
+ *    - `{ message }` — the SDK / API steer convention (`answerSteer`).
+ *    - `{ decision }` — what the dashboard's RunPausePanel universally sends
+ *      for every pause (option click or free text). Without this, resuming an
+ *      agent steer / `needs_input` / `agentc pause` pause from the dashboard
+ *      failed schema validation in the re-spawned runner and the agent never
+ *      got the answer — the resume looked like it did nothing. */
+export const SteerDecisionSchema = z
+  .object({
+    message:  z.string().min(1).optional(),
+    decision: z.string().min(1).optional(),
+    actor:    z.string().nullish(),
+  })
+  .transform((d) => ({ message: (d.message ?? d.decision ?? "").trim(), actor: d.actor ?? null }))
+  .refine((d) => d.message.length > 0, {
+    message: "a steer/resume answer needs a non-empty `message` or `decision`",
+  });
 export type SteerDecision = z.infer<typeof SteerDecisionSchema>;
 
 /** Metadata a pending steer carries from the control message to the boundary