@agent-compose/sdk 0.5.7 → 0.5.8

package/src/agent/agent-context.ts

@@ -0,0 +1,212 @@
+/**
+ * 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\`. It
+blocks until they answer on the dashboard, then prints their answer to stdout:
+
+    ANSWER=$(agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
+                          --option retry --option skip)
+
+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. Read the printed answer
+and act on it. 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

@@ -18,7 +18,13 @@ import { SteerDecisionSchema, type SteerDecision, type SteerPayload } from "./st
 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,7 +53,7 @@ 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 };
 
@@ -413,7 +419,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}`);
@@ -511,15 +523,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/run-agent.ts

@@ -21,6 +21,7 @@ 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 +233,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

package/src/client.ts

@@ -14,10 +14,10 @@
 import { ofetch } from "ofetch";
 import { AgentComposeError } from "./errors.js";
 import { parseSseStream } from "./sse.js";
-import type { SandboxNetworkPolicy } from "./sandbox.js";
+import type { SandboxNetworkPolicy, SandboxSize } from "./sandbox.js";
 import type { RunEvent } from "./types/events.js";
 import type { WorkflowPlan } from "./types/workflow-plan.js";
-import type { SnapshotConfig, IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy } from "./types/workflow-metadata.js";
+import type { SnapshotConfig, IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources } from "./types/workflow-metadata.js";
 import type { WorkflowManifest } from "./utils/bundler.js";
 
 /** UUID-v4-ish — matches the server-side predicate. Used to auto-detect
@@ -103,6 +103,8 @@ export interface RegisterWorkflowInput {
   /** All snapshot config — `bootFrom` (where to restore at run start),
    *  `save`, `retain`. See `WorkflowMetadata.snapshots`. */
   snapshots?: SnapshotConfig;
+  /** Sandbox machine size (template default). See `WorkflowMetadata.resources`. */
+  resources?: SandboxResources;
   /** Provider-neutral execution plan detected by the CLI bundler. */
   workflowPlan?: WorkflowPlan;
   /** Connector requirements declared via `defineWorkflow({ connectors })`
@@ -139,6 +141,10 @@ export interface InvokeWorkflowOptions {
    *  vars after brokering. Replaces the template-level placeholders for
    *  this run only — registered metadata is not mutated. */
   placeholders?: Record<string, string>;
+  /** Per-invocation machine-size override of the template's `resources.size`.
+   *  `small` (default) | `medium` | `large`; omit → the template default,
+   *  else `small`. Honoured on Vercel (→ vCPUs); E2B ignores it. */
+  size?: SandboxSize;
   /** Explicit parent run id. Pass `null` to suppress ambient RUN_ID auto-detection. */
   parentRunId?:  string | null;
   /** Agent loop inside the parent run that caused this invoke, when applicable. */
@@ -179,6 +185,56 @@ export interface ListTemplatesOptions {
   factorySlug?: string;
 }
 
+/** A human member of your team — the people an agent (or you) can @-flag. */
+export interface TeamMember {
+  /** Membership row id. */
+  id: string;
+  /** The user id — what you pass to `createMentions({ mentionedUserIds })`. */
+  userId: string;
+  role: string;
+  email: string;
+  name: string;
+  joinedAt: string;
+}
+
+/** A "you were flagged" ping, persisted server-side so it reaches the
+ *  mentioned teammate in their Workbench. */
+export interface Mention {
+  id: string;
+  factoryId: string;
+  mentionedUserId: string;
+  /** Who flagged: 'user' | 'api_key' | 'run' | 'system'. */
+  actorKind: string;
+  actorId: string | null;
+  actorLabel: string | null;
+  /** Where it lives: 'doc' | 'comment' | 'plan' | 'run'. */
+  contextKind: string;
+  contextPath: string | null;
+  /** Ready-made relative dashboard URL the Workbench card links to. */
+  contextUrl: string | null;
+  text: string;
+  runId: string | null;
+  seenAt: string | null;
+  resolvedAt: string | null;
+  createdAt: string;
+}
+
+export interface CreateMentionsInput {
+  /** Team-member user ids to flag (1–20). Discover them via `listMembers()`.
+   *  Non-members are dropped server-side. */
+  mentionedUserIds: string[];
+  /** The flag message shown in the teammate's Workbench. */
+  text: string;
+  contextKind: "doc" | "comment" | "plan" | "run";
+  /** Factory-relative file path or comment thread id, when applicable. */
+  contextPath?: string;
+  /** Ready-made relative dashboard URL the Workbench card links to (e.g.
+   *  `/factories/<slug>/files/view?path=<plan>`). */
+  contextUrl?: string;
+  runId?: string;
+  factorySlug?: string;
+}
+
 export interface CreateFactoryInput {
   slug: string;
   name: string;
@@ -661,6 +717,7 @@ export class AgentComposeClient {
         ...(opts?.snapshots     !== undefined ? { snapshots:     opts.snapshots }     : {}),
         ...(opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {}),
         ...(opts?.placeholders  !== undefined ? { placeholders:  opts.placeholders }  : {}),
+        ...(opts?.size          !== undefined ? { size:          opts.size }          : {}),
         ...(parentRunId                       ? { parentRunId }                       : {}),
         ...(opts?.agentId                     ? { agentId: opts.agentId }             : {}),
       },
@@ -1014,6 +1071,36 @@ export class AgentComposeClient {
     );
   }
 
+  /** List the human members of your team — the people you (or an agent) can
+   *  @-flag with `createMentions`. Each row's `userId` is what
+   *  `mentionedUserIds` expects. */
+  async listMembers(): Promise<TeamMember[]> {
+    const body = await this.fetch<{ members: TeamMember[] }>("/api/v1/team/members");
+    return body.members;
+  }
+
+  /** Flag one or more teammates — a durable ping that lands in their factory
+   *  Workbench. Use from an agent (e.g. a remediation plan that needs a human
+   *  to rotate a secret) or any team automation. Resolve `mentionedUserIds`
+   *  via `listMembers()`. When run inside a sandbox the run-callback token is
+   *  forwarded so the ping is attributed to the run ("flagged by <workflow>"). */
+  async createMentions(input: CreateMentionsInput): Promise<Mention[]> {
+    const factorySlug = input.factorySlug
+      ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined)
+      ?? DEFAULT_FACTORY;
+    const runToken = typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_RUN_TOKEN : undefined;
+    const { factorySlug: _omit, ...payload } = input;
+    const body = await this.fetch<{ mentions: Mention[] }>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/mentions`,
+      {
+        method: "POST",
+        body: payload,
+        ...(runToken ? { headers: { "x-run-token": runToken } } : {}),
+      },
+    );
+    return body.mentions;
+  }
+
   /** List events ingested into a factory, newest first. Supports
    *  case-insensitive substring filter (`name`) and timestamp-cursor
    *  pagination (`before`). Returns `{ events, has_more }` — the

package/src/index.ts

@@ -112,6 +112,7 @@ export type {
   CreateFactoryInput, UpdateFactoryInput,
   SecretOptions, SetSecretResult, SecretListEntry,
   CreateApiKeyInput, StreamRunLogsOptions,
+  TeamMember, Mention, CreateMentionsInput,
   EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult,
   RunLogLine, ListRunLogsOptions,
   RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse,
@@ -185,9 +186,10 @@ export { SandboxUnavailableError, SANDBOX_UNAVAILABLE_PREFIX } from "./sandbox-e
 export type {
   SandboxCreateOpts, SandboxNetworkPolicy, SandboxNetworkHeaderTransform,
   SandboxNetworkAllowRule, SandboxNetworkSubnetPolicy, SandboxProviderName,
-  SandboxQuotaResult, OwnedSandboxResult, OwnedSandbox,
+  SandboxQuotaResult, OwnedSandboxResult, OwnedSandbox, SandboxSize,
   ParseSseExecStreamOptions, SandboxCommandRunOptions, SandboxCommandResult,
 } from "./sandbox.js";
+export type { SandboxResources } from "./types/workflow-metadata.js";
 
 // Workflow engine
 export { runWorkflow, WorkflowError, EngineError, classifyError, parseNameVersion } from "./workflows/engine.js";
@@ -249,7 +251,7 @@ export {
 } from "./pause/errors.js";
 export type { PauseErrorCode } from "./pause/errors.js";
 export type { PauseRequest } from "./pause/pause-core.js";
-export type { RequestDecisionRequest, WaitForEventRequest } from "./pause/wrappers.js";
+export type { WaitForEventRequest } from "./pause/wrappers.js";
 export type {
   StepRequest,
   StepResult,
@@ -265,5 +267,7 @@ export { agentLoop, parseAgentStatus, DEFAULT_CLAUDE_MODEL } from "./agent/agent
 export type { AgentLifecycleEvent, AgentLoopOpts, AgentLoopResult } from "./agent/agent-loop.js";
 export { agent } from "./agent/run-agent.js";
 export type { AgentOpts } from "./agent/run-agent.js";
+export { AGENT_COMPOSE_MANUAL, buildAgentContextDoc, writeAgentContext } from "./agent/agent-context.js";
+export type { AgentConnectorInfo } from "./agent/agent-context.js";
 export { AgentMessageSchema, parseAgentResponse } from "./agent/protocol.js";
 export { importSourceModule, TMP_DIR, LATEST_VERSION } from "./utils/source-loader.js";

package/src/pause/wrappers.ts

@@ -1,12 +1,16 @@
 /**
- * The three opinionated pause wrappers (ADR-0006 §"SDK surface"), each a thin
+ * The two opinionated pause wrappers (ADR-0006 §"SDK surface"), each a thin
  * closure over `ctx.pause`:
  *
- *   - `requestDecision` — pause for a typed human/agent decision (schema required).
  *   - `sleep`           — a lightweight timed pause; resolves on its own TTL,
  *                         skips the snapshot, returns void.
  *   - `waitForEvent`    — pause until an event resumes by correlation key.
  *
+ * A typed human/agent decision is NOT a wrapper — it's a plain `ctx.pause`
+ * with a `schema` (and `payload.options` for the dashboard's answer UI). The
+ * pause primitive carries the reason (the ask) and the resume value (the
+ * resolution); there is no separate `requestDecision`.
+ *
  * Built from a `PauseFn` so the wrapper logic lives in one place and the step
  * runner just spreads them onto the context next to `pause`.
  */
@@ -19,18 +23,10 @@ import type { PauseRequest } from "./pause-core.js";
 export type PauseFn = <T = unknown>(req: PauseRequest<T>) => Promise<T>;
 
 /** Internal: pause with an explicit wire `kind`. The wrappers stamp
- *  `decision`/`sleep`/`event` through this; the public `ctx.pause` is always
+ *  `sleep`/`event` through this; the public `ctx.pause` is always
  *  `custom` and never exposes it. */
 export type KindedPauseFn = <T = unknown>(req: PauseRequest<T>, kind: StepPauseRequest["kind"]) => Promise<T>;
 
-export interface RequestDecisionRequest<T> {
-  reason:   string;
-  payload?: Record<string, unknown>;
-  /** Required — a decision is always validated against a shape. */
-  schema:   z.ZodType<T>;
-  ttlMs?:   number;
-}
-
 export interface WaitForEventRequest<T> {
   reason:         string;
   /** Required — the by-key resume route targets this. */
@@ -40,22 +36,12 @@ export interface WaitForEventRequest<T> {
 }
 
 export interface PauseWrappers {
-  requestDecision<T>(req: RequestDecisionRequest<T>): Promise<T>;
   sleep(durationMs: number): Promise<void>;
   waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T>;
 }
 
 export function buildPauseWrappers(pause: KindedPauseFn): PauseWrappers {
   return {
-    requestDecision<T>(req: RequestDecisionRequest<T>): Promise<T> {
-      return pause<T>({
-        reason: req.reason,
-        schema: req.schema,
-        ...(req.payload !== undefined ? { payload: req.payload } : {}),
-        ...(req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {}),
-      }, "decision");
-    },
-
     // Resolves on its OWN ttl — there is no external resumer for a sleep, so
     // onExpiry resolves (not throws) with void. snapshot:false keeps it cheap.
     sleep(durationMs: number): Promise<void> {