@agent-compose/sdk 0.5.6 → 0.5.7

package/src/agent/agent-loop.ts

@@ -15,7 +15,7 @@ import { PauseManager } from "../pause/manager.js";
 import { PauseSignal, isPauseSignal } from "../pause/pause-core.js";
 import { SteerDecisionSchema, type SteerDecision, type SteerPayload } from "./steer-control.js";
 
-export const DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
+export const DEFAULT_CLAUDE_MODEL = "claude-fable-5";
 
 const SAME_BLOCKER_ITERATIONS = 3;
 const STALL_ITERATIONS        = 3;
@@ -152,8 +152,15 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
   const label              = opts.label ?? "agent";
   const logLabel           = opts.label ?? "[Agent Loop]";
   const startedAt          = Date.now();
-  const turnsPerIteration  = opts.turnsPerIteration ?? 40;
-  const maxIterations      = opts.maxIterations ?? 8;
+  // No budget ⇒ no turn cap: the harness runtime (Claude Code) decides when it's
+  // done. A numeric budget is an explicit caller choice, not a default we impose.
+  const turnsPerIteration  = opts.turnsPerIteration;
+  const maxIterations      = opts.maxIterations ?? (turnsPerIteration === undefined ? 1 : 8);
+  // A responseSchema is a CONTRACT, not a hope: when the agent's <response> fails
+  // validation, the loop re-prompts with the exact errors until it conforms —
+  // without consuming the caller's iteration budget. The backstop below only
+  // guards against a truly wedged agent (never reached in normal operation).
+  let schemaRetriesLeft    = 10;
   const processors         = opts.processors ?? [];
   const requestContext     = opts.requestContext ?? RequestContext.fromReserved({
     teamId: "", runId: "", workflowId: "",
@@ -171,7 +178,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
 
   if (!opts.runtime) throw new Error("agentLoop: opts.runtime is required");
   const client = opts.runtime({
-    maxTurns:     turnsPerIteration,
+    ...(turnsPerIteration !== undefined ? { maxTurns: turnsPerIteration } : {}),
     allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
     label: logLabel,
     cwd:          opts.cwd,
@@ -342,6 +349,14 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
 
     const procCtx = buildProcCtx(iteration + 1);
     let initialPrompt = opts.buildPrompt(lastStatus, iteration);
+    // CONTRACT FEEDBACK: when the previous turn's <response> failed schema
+    // validation, the violation goes BACK TO THE MODEL as its next turn (the
+    // session carries the prior context). Without this, contract retries
+    // re-run the identical prompt and the model repeats the identical mistake.
+    if (lastResponseValidationError) {
+      initialPrompt = `${initialPrompt}\n\n[response contract violation — fix and re-emit]\nYour previous <response> failed schema validation with these errors:\n${lastResponseValidationError.slice(0, 2000)}\nRe-emit the COMPLETE corrected <response> JSON now: every required field present, correctly named and typed (no omissions, no renames).`;
+      lastResponseValidationError = "";
+    }
     if (steerDecision) {
       // Deliver the human's answer as the agent's next user turn by appending
       // it to the iteration prompt. `sendMessage({ prompt })` is the one input
@@ -364,7 +379,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
 
     // Progress, not an error — write to stdout so dashboards and
     // log viewers don't visually flag it as a warning.
-    process.stdout.write(`${logLabel} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration} turns\n`);
+    process.stdout.write(`${logLabel} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration !== undefined ? `${turnsPerIteration} turns` : "harness-decided turns"}\n`);
 
     let responseText = "";
     // The single `opts.inbox` is shared across iterations, but the
@@ -376,7 +391,11 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     // semantics — buffered until consumed).
     for await (const rawMsg of client.sendMessage({
       prompt,
-      sessionId: iteration > 0 ? lastSessionId : undefined,
+      // Resume whenever a session exists — NOT keyed on `iteration > 0`, because a
+      // contract retry rolls `iteration` back to 0 while a session already exists;
+      // keying on the session id keeps the corrective re-prompt in the same session
+      // (otherwise it restarts the task in a fresh session and repeats side effects).
+      sessionId: lastSessionId ?? undefined,
       iteration: iteration + 1,
       ...(opts.inbox ? { inboxStream: opts.inbox } : {}),
     })) {
@@ -447,6 +466,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
           process.stderr.write(`${logLabel} NO <response> BLOCK — response tail: ${responseText.slice(-400)}\n`);
           status = { ...status!, exit_signal: false, blockers: ["No <response> block found — emit a <response> block with the required JSON fields before setting exit_signal: true"] };
           opts.onIteration?.(iteration + 1, status);
+          if (schemaRetriesLeft-- > 0) iteration--; // contract enforcement — free, not billed to the iteration budget
           continue;
         }
         // Status-merged validation — the schema may reference status
@@ -458,6 +478,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
           process.stderr.write(`${logLabel} <response> SCHEMA FAILED: ${parsed.error.message}\nraw: ${JSON.stringify(rawResponse).slice(0, 400)}\n`);
           status = { ...status!, exit_signal: false, blockers: [`<response> schema validation failed: ${parsed.error.message}`] };
           opts.onIteration?.(iteration + 1, status);
+          if (schemaRetriesLeft-- > 0) iteration--; // contract enforcement — free, not billed to the iteration budget
           continue;
         }
         response = parsed.data;
@@ -487,10 +508,24 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       continue;
     }
 
-    if (!status) {
+    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`);
+        iteration--;
+        continue;
+      }
     } else {
+      // A parsed structured response (even one that failed schema validation)
+      // is real output, not a stall — the contract retry below handles it.
       iterationsWithoutStatus = 0;
     }
 
@@ -506,6 +541,20 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       blockerStreak = null;
     }
 
+    // CONTRACT RETRY (catch-all): the agent EMITTED a <response> block this turn,
+    // it failed schema validation, and it didn't go through the <status> branches
+    // above (structured-only output, no <status>). Re-prompt with the validation
+    // errors as feedback, FREE of the iteration budget. Gated on an actual
+    // validation failure this turn AND on the agent not signalling it's still
+    // working (`exit_signal: false`) — an in-progress turn that happens to carry
+    // a draft <response> consumes its budget normally instead of draining the
+    // shared retry pool that genuine contract violations rely on.
+    if (opts.responseSchema && rawResponse !== null && lastResponseValidationError !== "" && status?.exit_signal !== false && schemaRetriesLeft-- > 0) {
+      process.stdout.write(`${logLabel} response contract not yet satisfied — corrective re-prompt (${schemaRetriesLeft} retries left)\n`);
+      iteration--;
+      continue;
+    }
+
     if (iteration + 1 < maxIterations)
       // Loop continuation — progress.
       process.stdout.write(`${logLabel} continuing to iteration ${iteration + 2}/${maxIterations}\n`);

package/src/client.ts

@@ -17,7 +17,7 @@ import { parseSseStream } from "./sse.js";
 import type { SandboxNetworkPolicy } 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 } 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
@@ -96,13 +105,16 @@ export interface RegisterWorkflowInput {
   snapshots?: SnapshotConfig;
   /** 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 +139,16 @@ 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[];
   /** 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 {
@@ -234,6 +243,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 +396,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 +446,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 +651,16 @@ 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 }     : {}),
         ...(parentRunId                       ? { parentRunId }                       : {}),
         ...(opts?.agentId                     ? { agentId: opts.agentId }             : {}),
       },
@@ -895,6 +947,73 @@ 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 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,7 +106,7 @@ 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,
@@ -181,6 +181,7 @@ 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,

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;
+  }
+}