@agent-compose/sdk 0.5.5 → 0.5.7

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/runtimes/codex.ts

@@ -4,12 +4,13 @@
  * Built on the shared CLI-agent base; Codex brings its own loop + tools, so we
  * only stream-parse what it prints.
  *
- * Auth: set `CODEX_API_KEY` (or `OPENAI_API_KEY`) in the sandbox env via a
- * workflow secret. Requires the `codex` CLI installed in the sandbox image.
+ * Auth: set `OPENAI_API_KEY` (or `CODEX_API_KEY`) in the sandbox env via a
+ * workflow secret. The runtime installs the `codex` CLI (`@openai/codex`) on
+ * demand — no image baking needed; pair with `snapshots: { bootFrom: "reuse" }`
+ * to install once and boot from the captured snapshot on every run after.
  *
- * ⚠️ NOT verified against a live `codex` run — the resume flag and the exact
- * item shapes (command_execution / reasoning fields) are mapped from the docs
- * (developers.openai.com/codex/noninteractive). Verify before production use.
+ * Verified against codex-cli 0.124.0: `codex exec --json` + resume-by-thread,
+ * with the command_execution / reasoning / agent_message item shapes below.
  */
 
 import type { AgentMessage } from "../index.js";
@@ -21,6 +22,10 @@ function now(): string { return new Date().toISOString(); }
 const codexSpec: CliAgentSpec = {
   kind: "codex",
   authEnv: "CODEX_API_KEY",
+  bin: "codex",
+  // Global npm install; symlink onto PATH only if the global bin dir isn't
+  // already there (so a non-login `sh -c` can find it).
+  install: 'sudo npm install -g @openai/codex && (command -v codex >/dev/null 2>&1 || sudo ln -sf "$(npm prefix -g)/bin/codex" /usr/local/bin/codex)',
   // Codex reads the prompt from stdin when invoked as `codex exec ... -`.
   promptPayload: (prompt) => prompt,
   buildCommand: ({ promptPath, sessionId, model, cwd }) => {

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