@agent-compose/sdk 0.5.6 → 0.5.8

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 } 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
@@ -52,13 +52,6 @@ export interface RegisterResult {
   name: string;
   version: string;
   runtimes?: RegisteredRuntime[];
-  /** Non-fatal advisories from the server. Surfaced at register time so the
-   *  operator sees them while still in front of the terminal — currently
-   *  covers "memory extraction is configured but its workflow is not
-   *  registered in this factory". Empty/undefined when registration was
-   *  cleanly resolved against everything the workflow declares it
-   *  depends on. */
-  warnings?: string[];
 }
 
 export interface RegisteredRuntime {
@@ -72,6 +65,19 @@ export interface RuntimeSourceInput {
   source: string;
 }
 
+/** GitHub provenance for a registered template's source file — stored as
+ *  `metadata.source` on the registration. `cloud-build` stamps the built
+ *  commit's sha; the dashboard's manual link path writes `sha: "manual"`. */
+export interface TemplateSourceRef {
+  owner:  string;
+  repo:   string;
+  branch: string;
+  /** Repo-relative file path, e.g. `.agentc/workflows/workflow-deploy.ts`. */
+  path:   string;
+  /** Commit sha the version was built from, or `"manual"` for hand-links. */
+  sha:    string;
+}
+
 export interface RegisterWorkflowInput {
   name: string;
   source: string;
@@ -83,6 +89,9 @@ export interface RegisterWorkflowInput {
    *  executed on the server. */
   manifest: WorkflowManifest;
   version?: string;
+  /** Where the source file lives on GitHub — stored as `metadata.source`.
+   *  Named `sourceRef` because `source` is the bundled code itself. */
+  sourceRef?: TemplateSourceRef;
   schedule?: string;
   runtimes?: RuntimeSourceInput[];
   /** Human-readable description declared via
@@ -94,15 +103,20 @@ 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;
-  /** Run the built-in memory extractor after this workflow completes.
-   *  Opt-in; defaults to false when omitted. */
-  memory?: boolean;
-  /** Ordered list of workflow names that run as post-hooks after this
-   *  workflow completes. The memory extractor (when `memory: true`)
-   *  runs as an additional hook alongside these. */
-  postRunHooks?: readonly string[];
+  /** Connector requirements declared via `defineWorkflow({ connectors })`
+   *  (ADR-0007). Validated against the server's provider registry at
+   *  registration; tokens are injected at the network layer at dispatch. */
+  connectors?: ConnectorRequirements;
+  /** Connector-catalogue operation tag — see `ConnectorOperationTag`. */
+  connectorOperation?: ConnectorOperationTag;
+  /** Tier-1 invoke ACL declared via `defineWorkflow({ invokePolicy })`.
+   *  Only meaningful when the workflow also declares `connectors` — the
+   *  server gates dispatch on it before binding any grant. */
+  invokePolicy?: InvokePolicy;
   /** Input schema extracted from the workflow's `input` zod schema. */
   inputSchema?: IOSchema;
   /** Output schema extracted from the workflow's `output` zod schema. */
@@ -127,19 +141,20 @@ 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 memory-extractor override — `false` skips the
-   *  built-in memory hook for this run; omitting leaves the registered
-   *  default in place. */
-  memory?:       boolean;
-  /** Per-invocation post-hook override — replaces the registered
-   *  `postRunHooks` array for this run only. */
-  postRunHooks?:    readonly 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. */
   agentId?:      string | null;
   /** Factory slug. Defaults to `"default"`. */
   factorySlug?:  string;
+  /** Idempotency key — sent as the `Idempotency-Key` header. A repeat invoke
+   *  with the same key inside the server's dedup window returns the original
+   *  run instead of starting a new one (matches `resumePause`'s pattern). */
+  idempotencyKey?: string;
 }
 
 export interface InvokeAndWaitOptions extends InvokeWorkflowOptions {
@@ -170,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;
@@ -234,6 +299,13 @@ export interface RunStatus<TOutput = unknown> {
   id: string;
   status: RunState;
   output?: TOutput;
+  /** The run's latest (`saveLatest`) snapshot id, populated once the run has
+   *  succeeded — the boot source to fork this run's evolved filesystem from
+   *  (pass as `snapshots.bootFrom` on a follow-up invoke). `null` while the run
+   *  is still in flight or when it captured no snapshot. Lets an orchestrator
+   *  fork a child straight off the `invokeChild` result without a separate
+   *  `listRunSnapshots` call. */
+  latestSnapshotId?: string | null;
 }
 
 /** ADR-0006 step 10 — actor record returned on a successful resume.
@@ -380,6 +452,41 @@ export interface EventRow {
   createdAt: string;
 }
 
+// The server emits these rows in snake_case; the client maps them to
+// camelCase at the fetch boundary so the SDK surface stays uniform
+// (`EventRow.createdAt`, `RunStatus.latestSnapshotId`, …).
+export interface RunArtifactRow {
+  path: string;
+  factorySlug: string | null;
+  sizeBytes: number | null;
+  lastWriteAt: string;
+  /** Opening text of the file (≤320 chars) — null for binary/empty. */
+  preview: string | null;
+}
+
+export interface FactoryFileWriteResult {
+  path: string;
+  contentHash: string;
+  sizeBytes: number;
+  created: boolean;
+}
+
+/** Wire shapes — what the server actually emits (snake_case). */
+interface RunArtifactWire {
+  path: string;
+  factory_slug: string | null;
+  size_bytes: number | null;
+  last_write_at: string;
+  preview: string | null;
+}
+
+interface FactoryFileWriteWire {
+  path: string;
+  content_hash: string;
+  size_bytes: number;
+  created: boolean;
+}
+
 export interface ReportEventInput {
   name: string;
   body: unknown;
@@ -395,7 +502,7 @@ export interface ListEventsOptions {
   factorySlug?: string;
   limit?: number;
   /** Case-insensitive substring match. Server uses `ILIKE %name%`, so
-   *  `"mem"` matches `memory.fact`, `memory.usage`, etc. Pass the
+   *  `"site"` matches `site.created`, `site.failed`, etc. Pass the
    *  full event name for an effectively-exact filter (any string is a
    *  substring of itself). */
   name?: string;
@@ -600,15 +707,17 @@ export class AgentComposeClient {
       ? detectAmbientParentRunId()
       : opts.parentRunId;
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const headers: Record<string, string> = {};
+    if (opts?.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
     return this.fetch(templatePath(factorySlug, name, "invoke"), {
       method: "POST",
+      ...(opts?.idempotencyKey ? { headers } : {}),
       body: {
         input,
         ...(opts?.snapshots     !== undefined ? { snapshots:     opts.snapshots }     : {}),
         ...(opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {}),
         ...(opts?.placeholders  !== undefined ? { placeholders:  opts.placeholders }  : {}),
-        ...(opts?.memory        !== undefined ? { memory:        opts.memory }        : {}),
-        ...(opts?.postRunHooks     !== undefined ? { postRunHooks:     opts.postRunHooks }     : {}),
+        ...(opts?.size          !== undefined ? { size:          opts.size }          : {}),
         ...(parentRunId                       ? { parentRunId }                       : {}),
         ...(opts?.agentId                     ? { agentId: opts.agentId }             : {}),
       },
@@ -895,6 +1004,103 @@ export class AgentComposeClient {
     return body.events;
   }
 
+  /** Files the run wrote on the factory drive — run-attributed revisions,
+   *  latest write per path, paths the run later deleted excluded. */
+  async listRunArtifacts(runId: string): Promise<RunArtifactRow[]> {
+    const body = await this.fetch<{ artifacts: RunArtifactWire[] }>(
+      `/api/v1/workflows/${encodeURIComponent(runId)}/artifacts`,
+    );
+    return body.artifacts.map((a) => ({
+      path:        a.path,
+      factorySlug: a.factory_slug,
+      sizeBytes:   a.size_bytes,
+      lastWriteAt: a.last_write_at,
+      preview:     a.preview,
+    }));
+  }
+
+  // ── Factory files ──────────────────────────────────────────────────────────
+  // The factory drive: documents surfaced in the dashboard's Files tab.
+  // Writes from inside a sandbox automatically carry the run-callback token
+  // (AGENT_COMPOSE_RUN_TOKEN), so the revision is attributed to the run —
+  // that's what surfaces the doc in the Workbench docs section and the
+  // editor-avatar run hover.
+
+  /** Write (create or overwrite) one file on a factory's drive. */
+  async putFactoryFile(
+    path: string,
+    content: string | Uint8Array,
+    opts?: { factorySlug?: string; contentType?: string },
+  ): Promise<FactoryFileWriteResult> {
+    const factorySlug = opts?.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 wire = await this.fetch<FactoryFileWriteWire>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/content?path=${encodeURIComponent(path)}`,
+      {
+        method: "PUT",
+        body: content,
+        headers: {
+          "content-type": opts?.contentType ?? "text/plain; charset=utf-8",
+          ...(runToken ? { "x-run-token": runToken } : {}),
+        },
+      },
+    );
+    return {
+      path:        wire.path,
+      contentHash: wire.content_hash,
+      sizeBytes:   wire.size_bytes,
+      created:     wire.created,
+    };
+  }
+
+  /** Read one file's current content (or a specific revision) as text. */
+  async getFactoryFile(
+    path: string,
+    opts?: { factorySlug?: string; revision?: number },
+  ): Promise<string> {
+    const factorySlug = opts?.factorySlug
+      ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined)
+      ?? DEFAULT_FACTORY;
+    const q = new URLSearchParams({ path });
+    if (opts?.revision !== undefined) q.set("revision", String(opts.revision));
+    return this.fetch(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/content?${q}`,
+      { responseType: "text" },
+    );
+  }
+
+  /** 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

@@ -41,8 +41,8 @@ export type {
   ReuseSnapshot,
   IOSchema,
   OutputSchema,
-  WorkflowMemoryConfig,
 } from "./types/workflow.js";
+export type { ConnectorRequestRules } from "./types/workflow-metadata.js";
 
 // Snapshot entry type re-exported for consumers (dashboard, CLI).
 export type { RunSnapshotEntry } from "./client.js";
@@ -106,12 +106,13 @@ export type {
 // HTTP client
 export { AgentComposeClient } from "./client.js";
 export type {
-  RegisterResult, RegisterWorkflowInput, RuntimeSourceInput,
+  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,
   RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse,
@@ -181,12 +182,14 @@ export { createSandbox, reconnectSandbox, killAllSandboxes, killSandboxById,
   getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot,
   makeSandboxProvider, makeDesktopSandboxProvider,
   parseSseExecStream, AGENT_COMPOSE_TAG } from "./sandbox.js";
+export { SandboxUnavailableError, SANDBOX_UNAVAILABLE_PREFIX } from "./sandbox-errors.js";
 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";
@@ -248,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,
@@ -264,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> {

package/src/runtimes/claude.ts

@@ -62,8 +62,20 @@ function translateMessage(message: Record<string, unknown>): AgentMessage[] {
       numTurns: Number(message.num_turns ?? 0),
       timestamp: ts,
     });
-    if (message.is_error || message.subtype === "error_during_execution") {
-      msgs.push({ type: "error", text: formatError(message.error ?? message.result ?? message.message), timestamp: ts });
+    if (message.subtype === "error_max_turns") {
+      // Running out of turns is NOT a failure — the agent did real work and the
+      // files it wrote are on disk. End the iteration cleanly (don't throw) so the
+      // workflow keeps the partial result and moves on.
+      msgs.push({ type: "done", sessionId: String(message.session_id ?? ""), timestamp: ts });
+    } else if (message.is_error || message.subtype === "error_during_execution") {
+      // Error results sometimes carry NO error/result/message fields (e.g.
+      // the binary died early) — fall back to subtype + the raw envelope so
+      // the failure is diagnosable instead of "Agent error: undefined".
+      const detail = message.error ?? message.result ?? message.message;
+      const text = detail !== undefined
+        ? formatError(detail)
+        : `${String(message.subtype ?? "unknown_error")} — raw result: ${JSON.stringify({ ...message, usage: undefined }).slice(0, 600)}`;
+      msgs.push({ type: "error", text, timestamp: ts });
     } else {
       msgs.push({ type: "done", sessionId: String(message.session_id ?? ""), timestamp: ts });
     }
@@ -77,7 +89,11 @@ export interface ClaudeRuntimeConfig {
   claudeMdContent?: string;
   /** Env overrides for Agent SDK provider routing. */
   env?: Record<string, string>;
-  /** Model to use. Defaults to DEFAULT_CLAUDE_MODEL. */
+  /** Model to use. Accepts a caliber shorthand — "fable" (most capable),
+   *  "opus", "sonnet", "haiku" (fastest/cheapest) — or an exact model id.
+   *  Defaults to DEFAULT_CLAUDE_MODEL (Fable). Orchestrators pick a caliber
+   *  per agent: fable/opus for planning + implementation, sonnet for focused
+   *  single-responsibility work, haiku for mechanical tasks. */
   model?: string;
   /** MCP servers to configure for the Agent SDK. */
   mcpServers?: Record<string, { command: string; args?: string[]; env?: Record<string, string> }>;
@@ -87,6 +103,31 @@ export interface ClaudeRuntimeConfig {
   thinking?: ThinkingConfig;
   /** Reasoning effort hint for models that support adaptive thinking. */
   effort?: "low" | "medium" | "high" | "xhigh" | "max";
+  /** Skills to enable for the agent (the Agent SDK's `skills` option — also
+   *  auto-adds the `Skill` tool). The agent-env bakes the `/ac:*` skills via
+   *  `agentc init`; default `"all"` makes them usable. Pass `[]` to disable. */
+  skills?: string[] | "all";
+}
+
+/** Caliber shorthand → exact model id. Full ids pass through untouched. */
+const MODEL_TIERS: Record<string, string> = {
+  fable: "claude-fable-5",
+  opus: "claude-opus-4-8",
+  sonnet: "claude-sonnet-4-6",
+  haiku: "claude-haiku-4-5",
+};
+function resolveClaudeModel(model: string | undefined): string {
+  if (!model) return DEFAULT_CLAUDE_MODEL;
+  return MODEL_TIERS[model.toLowerCase()] ?? model;
+}
+
+/** Fable rejects an explicit `thinking: {type: "disabled"}` with a 400 (the only
+ *  off-mode on Fable is omitting the param). Other models accept it. Resolve the
+ *  thinking config against the chosen model so callers can keep passing
+ *  `thinking: {type: "disabled"}` for cheap/fast agents regardless of tier. */
+function resolveThinking(model: string, thinking: ThinkingConfig | undefined): ThinkingConfig | undefined {
+  if (model.startsWith("claude-fable") && thinking && (thinking as { type?: string }).type === "disabled") return undefined;
+  return thinking;
 }
 
 /** Canonical install path for Claude Code inside a Vercel sandbox.
@@ -130,7 +171,7 @@ export class ClaudeRunner implements ModelExecutionContract {
   ) {}
 
   get model(): string {
-    return this.config.model ?? this.options.model ?? DEFAULT_CLAUDE_MODEL;
+    return resolveClaudeModel(this.config.model ?? this.options.model);
   }
 
   async gateToolCall(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult> {
@@ -179,7 +220,7 @@ export class ClaudeRunner implements ModelExecutionContract {
     //
     //   Without an inboxStream we keep the simple string-prompt path —
     //   no queue, same behaviour as before. This keeps non-interactive
-    //   workflows (memory extractor, etc.) on the original code path.
+    //   workflows on the original code path.
     //
     //   The queue is closed when the SDK's `result` message indicates
     //   the iteration's assistant turns are done; without close() the
@@ -216,9 +257,9 @@ export class ClaudeRunner implements ModelExecutionContract {
           tools: this.options.allowedTools,
           allowedTools: this.options.allowedTools,
           maxTurns: this.options.maxTurns,
-          model: this.config.model ?? this.options.model ?? DEFAULT_CLAUDE_MODEL,
+          model: this.model,
           outputFormat: this.options.outputFormat,
-          thinking: this.config.thinking,
+          thinking: resolveThinking(this.model, this.config.thinking),
           effort: this.config.effort,
           cwd: this.options.cwd,
           env: { ...process.env, ...(this.config.env ?? {}) },
@@ -226,6 +267,10 @@ export class ClaudeRunner implements ModelExecutionContract {
             ?? process.env.CLAUDE_CODE_EXECUTABLE
             ?? DEFAULT_CLAUDE_PATH,
           ...(this.config.claudeMdContent ? { systemPrompt: { type: "preset" as const, preset: "claude_code" as const, append: this.config.claudeMdContent } } : {}),
+          // Turn skills ON (and auto-add the `Skill` tool). The agent-env
+          // bakes the `/ac:*` skills; without this the Agent SDK leaves
+          // them un-enabled and the agent can't invoke them.
+          skills: this.config.skills ?? "all",
           resume: opts.sessionId,
           mcpServers: this.config.mcpServers,
           permissionMode: "acceptEdits",
@@ -251,7 +296,20 @@ export class ClaudeRunner implements ModelExecutionContract {
         if (raw.type === "result" && inboxQueue) inboxQueue.close();
       }
     } catch (err) {
-      yield { type: "error", text: formatError(err), timestamp: now() };
+      // The SDK ALSO signals "out of turns" by THROWING (separately from the
+      // result-message `error_max_turns` subtype handled in translateMessage — that
+      // typed path is the primary signal; this catch covers the SDK's separate
+      // throw, which is prose-only). Treat it the same: NOT a failure — end the
+      // iteration cleanly so the loop continues, keeping the work it did.
+      // Match ONLY the specific exhaustion phrase, NOT a loose "maxTurns" token: the
+      // latter would also swallow a genuine error like "maxTurns must be a positive
+      // integer" and silently report it as a clean finish.
+      const text = formatError(err);
+      if (/maximum number of turns/i.test(text)) {
+        yield { type: "done", sessionId: opts.sessionId ?? "", timestamp: now() };
+      } else {
+        yield { type: "error", text, timestamp: now() };
+      }
     } finally {
       // Belt-and-braces — close on error/abort too so the dangling
       // iterable doesn't leak the inboxStream consumer.

package/src/sandbox-errors.ts

@@ -0,0 +1,53 @@
+/**
+ * Sandbox-infrastructure error.
+ *
+ * Distinct from `StepExecutionError` (the user/runner step-failure wrapper):
+ * that's the workflow author's problem. A `SandboxUnavailableError` means the
+ * sandbox itself couldn't carry the step — the provider refused a command, the
+ * sandbox was reclaimed (idle/lifetime timeout, eviction), an API blip, or the
+ * connection dropped mid-stream. None of these are a fault in the customer's
+ * code, so they're surfaced as "infrastructure issue, retry" rather than
+ * blaming the user.
+ *
+ * ## Retryability is about *when*, not *which error*
+ *
+ * The Vercel provider (`sandbox.ts`) decides `retryable` purely from *where* it
+ * caught the error — not by inspecting status codes or error vocabularies:
+ *   - `retryable: true`  — caught before the runner launched the step (file
+ *     write / command launch / reconnect refused). No user code ran, so
+ *     re-provisioning a fresh sandbox and re-running the step is safe. ANY
+ *     error here qualifies (sandbox reclaimed, 429, 5xx, network blip).
+ *   - `retryable: false` — caught while/after the runner streamed, so user code
+ *     may already have executed side effects. Surfaced honestly as an infra
+ *     failure, but NOT auto-retried.
+ *
+ * ## Cross-process contract
+ *
+ * The thrown error crosses the Temporal activity→workflow serialisation
+ * boundary, which preserves the error **message** but discards custom instance
+ * fields. So the retryability signal is encoded IN the message via a stable
+ * prefix — `[sandbox-unavailable:retryable]` or `[sandbox-unavailable:terminal]`
+ * — following the same `[kind] …` convention `StepExecutionError` uses. The
+ * server (`utils/transient-errors.ts`) matches this prefix with a pure regex to
+ * classify the failure and decide whether the workflow re-provisions and
+ * retries. A unit test pins the SDK-produced string against the server matcher
+ * so the two can't drift.
+ */
+
+/** Stable message prefix. Both variants share this leading token so a single
+ *  server-side regex recognises the class; the `:retryable` / `:terminal`
+ *  suffix carries the recovery decision. */
+export const SANDBOX_UNAVAILABLE_PREFIX = "[sandbox-unavailable";
+
+export class SandboxUnavailableError extends Error {
+  /** True when caught before any user code ran (safe to re-provision + retry);
+   *  false when the sandbox died mid/after execution. */
+  readonly retryable: boolean;
+  readonly sandboxId: string | undefined;
+  constructor(detail: string, opts: { retryable: boolean; sandboxId?: string }) {
+    super(`${SANDBOX_UNAVAILABLE_PREFIX}:${opts.retryable ? "retryable" : "terminal"}] ${detail}`);
+    this.name      = "SandboxUnavailableError";
+    this.retryable = opts.retryable;
+    this.sandboxId = opts.sandboxId;
+  }
+}