@spunto/build 0.19.1 → 0.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.19.1",
+  "version": "0.20.1",
   "description": "Spunto's shared Build engine — the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
   "type": "module",
   "license": "MIT",
@@ -81,7 +81,13 @@
     },
     "./sandbox-agent/agent.mjs": "./src/sandbox-agent/agent.mjs",
     "./sandbox-agent/bootstrap.sh": "./src/sandbox-agent/bootstrap.sh",
-    "./sandbox-agent/runner.sh": "./src/sandbox-agent/runner.sh"
+    "./sandbox-agent/runner.sh": "./src/sandbox-agent/runner.sh",
+    "./agent-runners": {
+      "types": "./src/agent-runners/index.ts",
+      "import": "./src/agent-runners/index.ts"
+    },
+    "./agent-runners/claude.mjs": "./src/agent-runners/claude.mjs",
+    "./agent-runners/codex.mjs": "./src/agent-runners/codex.mjs"
   },
   "files": [
     "src",

package/src/agent-runners/catalogs.ts

@@ -0,0 +1,140 @@
+/**
+ * What each agent app (RFC 0048) lets a task choose: its models, and **its own parameters** —
+ * effort, reasoning, web search… The platform knows none of them by name. It shows what an app
+ * declares, checks a task's choice against it (`validateAgentOptions`), and hands the choice to the
+ * runner (`OPTIONS_ENV`), which is the only code that knows what a parameter means to its SDK.
+ *
+ * **Measured, not remembered.** Each catalog is what the SDK pinned by its feature
+ * (`./features.ts`) answers, and it changes when that pin moves:
+ *
+ *  - Claude: `query().supportedModels()` of `@anthropic-ai/claude-agent-sdk` 0.3.310, on
+ *    2026-10-26. Each model comes back with `supportedEffortLevels`;
+ *  - Codex: `codex debug models` of `@openai/codex` 0.164.0 — the catalog bundled in the binary,
+ *    offline, on 2026-10-26 — the `visibility: "list"` models, with their
+ *    `supported_reasoning_levels` and `default_reasoning_level`.
+ *
+ * `packages/build/scripts/agent-catalogs.mjs` prints both again, to diff against this file when a
+ * pin is bumped.
+ */
+
+export type AgentParamValue = { value: string; label: string; description?: string }
+
+/** A parameter an app defines. A choice among values — the one shape both SDKs need today. */
+export type AgentParam = {
+  id: string
+  label: string
+  description?: string
+  values: AgentParamValue[]
+}
+
+export type AgentModel = {
+  value: string
+  label: string
+  description?: string
+  /** What the harness runs when no model is picked. */
+  default?: boolean
+  /** Values of a parameter this model allows, when it does not take all of them. */
+  params?: Record<string, string[]>
+  /** What this model runs with when the parameter is left unset — shown as the chip's placeholder. */
+  paramDefaults?: Record<string, string>
+}
+
+export type AgentCatalog = {
+  models: AgentModel[]
+  params: AgentParam[]
+}
+
+/** The variable a task's chosen parameters reach the runner in, as one JSON object. */
+export const OPTIONS_ENV = "SPUNTO_AGENT_OPTIONS"
+
+const CLAUDE_EFFORT: AgentParamValue[] = [
+  { value: "low", label: "Low" },
+  { value: "medium", label: "Medium" },
+  { value: "high", label: "High" },
+  { value: "xhigh", label: "Extra high" },
+  { value: "max", label: "Max" },
+]
+
+const CODEX_REASONING: AgentParamValue[] = [
+  { value: "low", label: "Low", description: "Fast responses with lighter reasoning" },
+  { value: "medium", label: "Medium", description: "Balances speed and reasoning depth for everyday tasks" },
+  { value: "high", label: "High", description: "Greater reasoning depth for complex problems" },
+  { value: "xhigh", label: "Extra high", description: "Extra high reasoning depth for complex problems" },
+  { value: "max", label: "Max", description: "Maximum reasoning depth for the hardest problems" },
+  { value: "ultra", label: "Ultra", description: "Maximum reasoning with automatic task delegation" },
+]
+
+const ALL_BUT_ULTRA = ["low", "medium", "high", "xhigh", "max"]
+
+export const AGENT_CATALOGS: Record<"claude" | "codex", AgentCatalog> = {
+  claude: {
+    // The SDK's aliases (`default`, `sonnet`, `opus`, `fable`, `haiku`) resolved to the ids they
+    // stand for: a task records the model it ran, not a name whose meaning moves.
+    models: [
+      { value: "claude-sonnet-5-5", label: "Claude Sonnet 5.5", description: "Default (recommended)", default: true },
+      { value: "claude-opus-5-5", label: "Claude Opus 5.5" },
+      { value: "claude-fable-5-1", label: "Claude Fable 5.1" },
+      { value: "claude-haiku-5-5", label: "Claude Haiku 5.5" },
+    ],
+    params: [
+      {
+        id: "effort",
+        label: "Effort",
+        description: "How much Claude thinks before it acts. Unset = the model's own default.",
+        values: CLAUDE_EFFORT,
+      },
+    ],
+  },
+  codex: {
+    models: [
+      { value: "gpt-6-astra", label: "GPT-6-Astra", description: "Frontier intelligence for the most demanding work.", paramDefaults: { reasoningEffort: "low" } },
+      { value: "gpt-6.1-sol", label: "GPT-6.1-Sol", description: "Latest workhorse model for coding and everyday work.", paramDefaults: { reasoningEffort: "low" } },
+      { value: "gpt-6-sol", label: "GPT-6-Sol", description: "Previous generation workhorse model.", paramDefaults: { reasoningEffort: "medium" } },
+      { value: "gpt-6-luna", label: "GPT-6-Luna", description: "Fast and affordable model for easier tasks.", params: { reasoningEffort: ALL_BUT_ULTRA }, paramDefaults: { reasoningEffort: "medium" } },
+      { value: "gpt-5.6-sol", label: "GPT-5.6-Sol", description: "Older generation workhorse model.", paramDefaults: { reasoningEffort: "low" } },
+      { value: "gpt-5.6-terra", label: "GPT-5.6-Terra", description: "Older balanced model for straightforward work.", paramDefaults: { reasoningEffort: "medium" } },
+      { value: "gpt-5.6-luna", label: "GPT-5.6-Luna", description: "Older fast and efficient model.", params: { reasoningEffort: ALL_BUT_ULTRA }, paramDefaults: { reasoningEffort: "medium" } },
+      { value: "gpt-5.5", label: "GPT-5.5", description: "Legacy coding model.", params: { reasoningEffort: ["low", "medium", "high", "xhigh"] }, paramDefaults: { reasoningEffort: "medium" } },
+    ],
+    params: [
+      {
+        id: "reasoningEffort",
+        label: "Reasoning",
+        description: "How deeply Codex reasons. Unset = the model's own default.",
+        values: CODEX_REASONING,
+      },
+      {
+        id: "webSearch",
+        label: "Web search",
+        description: "Whether Codex may search the web: from a cache, live, or not at all. Unset = Codex's default.",
+        values: [
+          { value: "disabled", label: "Off" },
+          { value: "cached", label: "Cached" },
+          { value: "live", label: "Live" },
+        ],
+      },
+    ],
+  },
+}
+
+/**
+ * Why these options cannot run under this catalog and model — or null when they can. An unknown
+ * parameter, a value the parameter does not have, or one the model does not take. A model the
+ * catalog does not list (typed by hand) is held to the parameter's values only: the catalog cannot
+ * speak for it.
+ */
+export function agentOptionsError(catalog: AgentCatalog, model: string | null | undefined, options: Record<string, string>): string | null {
+  const known = model ? catalog.models.find((m) => m.value === model) : undefined
+  for (const [id, value] of Object.entries(options)) {
+    const param = catalog.params.find((p) => p.id === id)
+    if (!param) return `Unknown parameter "${id}" — this harness takes ${catalog.params.map((p) => p.id).join(", ") || "none"}.`
+    if (!param.values.some((v) => v.value === value)) {
+      return `"${value}" is not a value of ${param.label} — one of ${param.values.map((v) => v.value).join(", ")}.`
+    }
+    const allowed = known?.params?.[id]
+    if (allowed && !allowed.includes(value)) {
+      return `${known!.label} does not take ${param.label} "${value}" — one of ${allowed.join(", ")}.`
+    }
+  }
+  return null
+}

package/src/agent-runners/claude.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// The Claude runner (RFC 0048): one file, no dependency of its own, written into the machine by
+// the platform when a session starts and run with the Node the `spunto-agent-claude` feature put
+// in the image. It drives Claude through the official Agent SDK the same feature installed.
+//
+// The contract, the same for every agent app (`../agent-runners/index.ts`):
+//
+//   node claude.mjs run [--model <id>] [--resume <session id>]
+//   stdin   one JSON object per line — {"type":"user","text"} · {"type":"interrupt","id"} ·
+//           {"type":"title","id","description"} ; closed = the session ends after its turn
+//   stdout  the harness's own dialect, one JSON object per line — here the SDK's messages, which
+//           are exactly the CLI's `stream-json` shapes, so the platform reads them with the
+//           adapter it already had (`claude-runner`)
+//   env     SPUNTO_AGENT_OPTIONS — the task's parameters, as declared by the app's catalog
+//           (`./catalogs.ts`): `{"effort":"high"}`
+//   exit    0 once the input is closed and the last turn is over, 1 when the session could not run
+//
+// Credentials are not this file's business: whatever the member set as secrets (an
+// `ANTHROPIC_API_KEY`) reaches the SDK's binary through the environment, untouched — this runner
+// reads no credential itself.
+
+import { createInterface } from "node:readline"
+
+const SDK = process.env.SPUNTO_CLAUDE_SDK || "/opt/spunto/agents/claude/node_modules/@anthropic-ai/claude-agent-sdk/sdk.mjs"
+
+function out(obj) {
+  process.stdout.write(`${JSON.stringify(obj)}\n`)
+}
+
+/** A failure the platform can read: the shape of the CLI's own failed `result`. */
+function fail(message) {
+  out({ type: "result", subtype: "error_during_execution", is_error: true, result: message })
+  process.exit(1)
+}
+
+function parseArgs(argv) {
+  const [verb, ...rest] = argv
+  if (verb !== "run") fail(`claude runner: unknown verb "${verb ?? ""}" (expected "run")`)
+  const args = {}
+  for (let i = 0; i < rest.length; i++) {
+    const flag = rest[i]
+    if (flag === "--model" || flag === "--resume") {
+      const value = rest[++i]
+      if (value) args[flag.slice(2)] = value
+    } else {
+      fail(`claude runner: unknown flag "${flag}"`)
+    }
+  }
+  return args
+}
+
+/** The human's turns, as the async iterable the SDK reads its prompt from. Ends when stdin does. */
+function inputQueue() {
+  const pending = []
+  let wake = null
+  let closed = false
+  return {
+    push(message) {
+      pending.push(message)
+      wake?.()
+    },
+    close() {
+      closed = true
+      wake?.()
+    },
+    async *[Symbol.asyncIterator]() {
+      for (;;) {
+        if (pending.length > 0) {
+          yield pending.shift()
+          continue
+        }
+        if (closed) return
+        await new Promise((resolve) => (wake = resolve))
+        wake = null
+      }
+    },
+  }
+}
+
+const args = parseArgs(process.argv.slice(2))
+
+/** The task's parameters. Checked by the platform against the catalog; read defensively all the same. */
+function readOptions() {
+  try {
+    const parsed = JSON.parse(process.env.SPUNTO_AGENT_OPTIONS || "{}")
+    return parsed && typeof parsed === "object" ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+const params = readOptions()
+
+let sdk
+try {
+  sdk = await import(SDK)
+} catch (err) {
+  fail(`claude runner: the Agent SDK is not installed at ${SDK} — is the project's image built with the Claude app's feature? (${err?.message ?? err})`)
+}
+
+const input = inputQueue()
+const session = sdk.query({
+  prompt: input,
+  options: {
+    cwd: process.cwd(),
+    ...(args.model ? { model: args.model } : {}),
+    ...(args.resume ? { resume: args.resume } : {}),
+    ...(typeof params.effort === "string" ? { effort: params.effort } : {}),
+    // A task runs unattended in a disposable machine — what `--dangerously-skip-permissions` did.
+    permissionMode: "bypassPermissions",
+    allowDangerouslySkipPermissions: true,
+    // Claude Code's own system prompt, CLAUDE.md, settings and skills: the session must behave
+    // exactly like the CLI it replaces, not like a bare SDK agent.
+    systemPrompt: { type: "preset", preset: "claude_code" },
+    settingSources: ["user", "project", "local"],
+    stderr: (line) => process.stderr.write(line),
+  },
+})
+
+createInterface({ input: process.stdin, crlfDelay: Infinity })
+  .on("line", (line) => {
+    let msg
+    try {
+      msg = JSON.parse(line)
+    } catch {
+      return
+    }
+    if (!msg || typeof msg !== "object") return
+    if (msg.type === "user" && typeof msg.text === "string") {
+      input.push({ type: "user", message: { role: "user", content: [{ type: "text", text: msg.text }] }, parent_tool_use_id: null })
+    } else if (msg.type === "interrupt") {
+      session.interrupt().catch((err) => process.stderr.write(`claude runner: interrupt failed: ${err?.message ?? err}\n`))
+    } else if (msg.type === "title" && typeof msg.description === "string") {
+      // Answered with the `control_response` the CLI would have printed, so the platform reads
+      // a title one way whichever side of the SDK the session runs on.
+      if (typeof session.generateSessionTitle !== "function") return
+      session
+        .generateSessionTitle(msg.description, { persist: true })
+        .then((title) => {
+          if (typeof title === "string" && title) {
+            out({ type: "control_response", response: { subtype: "success", request_id: msg.id, response: { title } } })
+          }
+        })
+        .catch((err) => process.stderr.write(`claude runner: title failed: ${err?.message ?? err}\n`))
+    }
+  })
+  .on("close", () => input.close())
+
+// The SDK also throws after a failed `result` it has just yielded; that result already said why,
+// and a second one would end the turn twice in the timeline.
+let lastType = null
+try {
+  for await (const message of session) {
+    out(message)
+    lastType = message?.type ?? null
+  }
+} catch (err) {
+  if (lastType === "result") process.exit(1)
+  fail(`claude runner: ${err?.message ?? err}`)
+}
+process.exit(0)

package/src/agent-runners/codex.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// The Codex runner (RFC 0048): same contract as `claude.mjs`, over `@openai/codex-sdk`, installed
+// with the `codex` binary it drives by the `spunto-agent-codex` feature.
+//
+//   node codex.mjs run [--model <id>] [--resume <thread id>]
+//   stdin   {"type":"user","text"} · {"type":"interrupt","id"} · {"type":"title",…} (ignored: Codex
+//           does not name its threads) ; closed = the session ends after its turn
+//   stdout  the SDK's `ThreadEvent`s, one per line (`codex-runner` in the platform's adapters)
+//   env     SPUNTO_AGENT_OPTIONS — the task's parameters (`./catalogs.ts`):
+//           `{"reasoningEffort":"high","webSearch":"live"}`
+//   exit    0 once the input is closed and the last turn is over, 1 when the session could not run
+//
+// Codex works turn by turn: a message that arrives while a turn runs waits for it to end, then
+// starts the next one in the same thread — what a "queued message" already means on the platform.
+// An interrupt aborts the turn in flight, and the runner says so with a `turn.failed`.
+//
+// Credentials: `OPENAI_API_KEY` (or `CODEX_API_KEY`) as a secret, or a `codex login` done by hand in
+// the machine's terminal (`~/.codex/auth.json`), which the binary reads on its own.
+
+import { createInterface } from "node:readline"
+
+const SDK = process.env.SPUNTO_CODEX_SDK || "/opt/spunto/agents/codex/node_modules/@openai/codex-sdk/dist/index.js"
+
+function out(obj) {
+  process.stdout.write(`${JSON.stringify(obj)}\n`)
+}
+
+function fail(message) {
+  out({ type: "turn.failed", error: { message } })
+  process.exit(1)
+}
+
+function parseArgs(argv) {
+  const [verb, ...rest] = argv
+  if (verb !== "run") fail(`codex runner: unknown verb "${verb ?? ""}" (expected "run")`)
+  const args = {}
+  for (let i = 0; i < rest.length; i++) {
+    const flag = rest[i]
+    if (flag === "--model" || flag === "--resume") {
+      const value = rest[++i]
+      if (value) args[flag.slice(2)] = value
+    } else {
+      fail(`codex runner: unknown flag "${flag}"`)
+    }
+  }
+  return args
+}
+
+const args = parseArgs(process.argv.slice(2))
+
+/** The task's parameters. Checked by the platform against the catalog; read defensively all the same. */
+function readOptions() {
+  try {
+    const parsed = JSON.parse(process.env.SPUNTO_AGENT_OPTIONS || "{}")
+    return parsed && typeof parsed === "object" ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+const params = readOptions()
+
+let sdk
+try {
+  sdk = await import(SDK)
+} catch (err) {
+  fail(`codex runner: the Codex SDK is not installed at ${SDK} — is the project's image built with the Codex app's feature? (${err?.message ?? err})`)
+}
+
+const apiKey = process.env.OPENAI_API_KEY || process.env.CODEX_API_KEY
+const codex = new sdk.Codex(apiKey ? { apiKey } : {})
+const threadOptions = {
+  workingDirectory: process.cwd(),
+  ...(args.model ? { model: args.model } : {}),
+  ...(typeof params.reasoningEffort === "string" ? { modelReasoningEffort: params.reasoningEffort } : {}),
+  ...(typeof params.webSearch === "string" ? { webSearchMode: params.webSearch } : {}),
+  // A task runs unattended in a disposable machine: no approval prompt nobody would answer, and
+  // no sandbox of Codex's own inside the one the machine already is (it needs kernel features a
+  // container rarely has).
+  approvalPolicy: "never",
+  sandboxMode: "danger-full-access",
+  networkAccessEnabled: true,
+}
+const thread = args.resume ? codex.resumeThread(args.resume, threadOptions) : codex.startThread(threadOptions)
+// A resumed thread is not announced by the SDK (`thread.started` only comes with a new one), and
+// the platform learns the session id from that line — so the runner says it.
+if (args.resume) out({ type: "thread.started", thread_id: args.resume })
+
+const pending = []
+let closed = false
+let current = null // AbortController of the turn in flight
+let wake = null
+
+createInterface({ input: process.stdin, crlfDelay: Infinity })
+  .on("line", (line) => {
+    let msg
+    try {
+      msg = JSON.parse(line)
+    } catch {
+      return
+    }
+    if (!msg || typeof msg !== "object") return
+    if (msg.type === "user" && typeof msg.text === "string") {
+      pending.push(msg.text)
+      wake?.()
+    } else if (msg.type === "interrupt") {
+      current?.abort()
+    }
+  })
+  .on("close", () => {
+    closed = true
+    wake?.()
+  })
+
+let failed = false
+for (;;) {
+  if (pending.length === 0) {
+    if (closed) break
+    await new Promise((resolve) => (wake = resolve))
+    wake = null
+    continue
+  }
+  const text = pending.shift()
+  current = new AbortController()
+  // The SDK also throws once the binary exits after a `turn.failed` it has just yielded; that line
+  // already said why, and a second one would end the turn twice in the timeline.
+  let lastType = null
+  try {
+    const { events } = await thread.runStreamed(text, { signal: current.signal })
+    for await (const event of events) {
+      out(event)
+      lastType = event?.type ?? null
+    }
+  } catch (err) {
+    if (current.signal.aborted) {
+      out({ type: "turn.failed", error: { message: "Interrupted." } })
+    } else if (lastType !== "turn.failed") {
+      out({ type: "turn.failed", error: { message: `codex runner: ${err?.message ?? err}` } })
+      failed = true
+    }
+  }
+  current = null
+}
+process.exit(failed ? 1 : 0)

package/src/agent-runners/features.ts

@@ -0,0 +1,77 @@
+// The install scripts of the agent apps' features (RFC 0048), shipped by the platform itself like
+// `google-cloud-cli.sh` (`../script/local-features.ts`). Root, at image build time.
+//
+// Each one lays down, under /opt/spunto/agents:
+//   node/            a private Node — the runner must not depend on the project's (absent from a
+//                    Python image, swapped by an nvm feature that installs after this one)
+//   <id>/            the harness's official SDK, pinned, with the native binary it drives
+//   /usr/local/bin/  the harness's CLI for the humans in the terminal, unless the image has one
+
+/** Where every agent feature installs. */
+export const AGENT_HOME = "/opt/spunto/agents"
+/** The private Node the features fetch — the release the sandbox bootstrap fetches too. */
+export const AGENT_NODE_VERSION = "v24.11.1"
+const NODE_VERSION = AGENT_NODE_VERSION
+
+function featureScript(p: { id: string; label: string; packages: string; cli: string }): string {
+  return `#!/bin/sh
+set -e
+echo "[feature] ${p.id}: installing ${p.label}..."
+
+HOME_DIR=${AGENT_HOME}
+NODE_DIR=$HOME_DIR/node
+mkdir -p "$HOME_DIR"
+
+fetch() {
+  if command -v curl >/dev/null 2>&1; then curl -fsSL --retry 5 --retry-delay 2 "$1" -o "$2"
+  elif command -v wget >/dev/null 2>&1; then wget -qO "$2" "$1"
+  else echo "[feature] ${p.id}: neither curl nor wget in this image" >&2; exit 1
+  fi
+}
+
+if ! "$NODE_DIR/bin/node" -e 'process.exit(0)' 2>/dev/null; then
+  case "$(uname -m)" in
+    x86_64|amd64) ARCH=x64 ;;
+    aarch64|arm64) ARCH=arm64 ;;
+    *) echo "[feature] ${p.id}: unsupported arch $(uname -m)" >&2; exit 1 ;;
+  esac
+  echo "[feature] ${p.id}: fetching node ${NODE_VERSION} ($ARCH)"
+  fetch "https://nodejs.org/dist/${NODE_VERSION}/node-${NODE_VERSION}-linux-$ARCH.tar.gz" /tmp/_spunto_node.tgz
+  rm -rf "$NODE_DIR" && mkdir -p "$NODE_DIR"
+  tar -xzf /tmp/_spunto_node.tgz -C "$NODE_DIR" --strip-components=1
+  rm -f /tmp/_spunto_node.tgz
+fi
+
+mkdir -p "$HOME_DIR/${p.id}"
+PATH="$NODE_DIR/bin:$PATH" "$NODE_DIR/bin/npm" install --prefix "$HOME_DIR/${p.id}" \\
+  --omit=dev --no-audit --no-fund --no-update-notifier --loglevel=error ${p.packages}
+chmod -R a+rX "$HOME_DIR"
+
+${p.cli}
+
+echo "[feature] ${p.id}: done"
+`
+}
+
+export const AGENT_FEATURE_SCRIPTS: Record<string, string> = {
+  "spunto-agent-claude.sh": featureScript({
+    id: "claude",
+    label: "the Claude Agent SDK",
+    packages: "@anthropic-ai/claude-agent-sdk@0.3.310",
+    // The SDK drives a native \`claude\` binary from a platform package; the same binary is the CLI.
+    cli: `if ! command -v claude >/dev/null 2>&1; then
+  for b in "$HOME_DIR"/claude/node_modules/@anthropic-ai/claude-agent-sdk-linux-*/claude; do
+    if [ -x "$b" ]; then ln -sf "$b" /usr/local/bin/claude; break; fi
+  done
+fi`,
+  }),
+  "spunto-agent-codex.sh": featureScript({
+    id: "codex",
+    label: "the Codex SDK",
+    packages: "@openai/codex-sdk@0.164.0",
+    cli: `if ! command -v codex >/dev/null 2>&1; then
+  printf '#!/bin/sh\\nexec %s %s "$@"\\n' "$NODE_DIR/bin/node" "$HOME_DIR/codex/node_modules/@openai/codex/bin/codex.js" > /usr/local/bin/codex
+  chmod 755 /usr/local/bin/codex
+fi`,
+  }),
+}

package/src/agent-runners/index.ts

@@ -0,0 +1,95 @@
+/**
+ * Agent apps (RFC 0048): what it takes to run a harness in a machine, on both sides of the seam.
+ *
+ * An agent app is three things, and this module is where they meet:
+ *
+ *  - a **feature** the platform injects into the image of every project that picks the app — it
+ *    installs a private Node and the harness's **official SDK** (with the binary the SDK drives)
+ *    under `/opt/spunto/agents/<id>`. Shipped by the platform itself (`localScript`), so an app
+ *    never waits on a registry release;
+ *  - a **runner**, one dependency-free `.mjs` file of ours (`claude.mjs`, `codex.mjs`), written into
+ *    the machine at the moment a session starts. Not baked: a runner fix reaches the next session,
+ *    not the next rebuild;
+ *  - a **dialect** (`claude-runner`, `codex-runner` in `../agent-stream`), which is how the platform
+ *    writes the runner's stdin and reads its stdout.
+ *
+ * The runner contract, identical for every app:
+ *
+ *   <node> <runner>.mjs run [--model <id>] [--resume <session id>]
+ *   stdin   one JSON object per line: {"type":"user","text"} · {"type":"interrupt","id"} ·
+ *           {"type":"title","id","description"} (`RunnerInput`); closed ⇒ end after the turn
+ *   env     SPUNTO_AGENT_OPTIONS — the task's parameters (`./catalogs.ts`), one JSON object
+ *   stdout  the harness's own events, one JSON object per line — normalised by the platform
+ *   exit    0 = the input closed and the last turn ended; 1 = the session could not run
+ *
+ * Pure like the rest of the package: what a caller gets is *where* a runner file is, and the shell
+ * that starts it. Reading the file is the caller's I/O.
+ */
+
+import type { AgentProtocol } from "../agent-stream/agent-stream"
+
+import { AGENT_HOME } from "./features"
+
+/** The Node every runner runs on — the private one the features install. */
+export const AGENT_NODE = `${AGENT_HOME}/node/bin/node`
+
+export type AgentHarnessId = "claude" | "codex"
+
+export type AgentHarness = {
+  id: AgentHarnessId
+  /** The catalog id of the feature the platform injects (`AVAILABLE_FEATURES`, `localScript`). */
+  featureId: string
+  /** How the platform talks to the runner. */
+  protocol: AgentProtocol
+  /** The runner, a file of this package. */
+  runnerFile: URL
+  /** Where the harness looks for user-level skills (RFC 0033), as shell evaluated in the machine. */
+  skillDirs: string[]
+}
+
+export const AGENT_HARNESSES: Record<AgentHarnessId, AgentHarness> = {
+  claude: {
+    id: "claude",
+    featureId: "spunto-agent-claude",
+    protocol: "claude-runner",
+    runnerFile: new URL("./claude.mjs", import.meta.url),
+    skillDirs: ["${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills"],
+  },
+  codex: {
+    id: "codex",
+    featureId: "spunto-agent-codex",
+    protocol: "codex-runner",
+    runnerFile: new URL("./codex.mjs", import.meta.url),
+    skillDirs: ["${CODEX_HOME:-$HOME/.codex}/skills"],
+  },
+}
+
+/** The variable a runner's text travels in, base64 — see `runnerCommand`. */
+export const RUNNER_ENV = "SPUNTO_AGENT_RUNNER"
+
+/**
+ * The shell that starts a session: write the runner out of `$SPUNTO_AGENT_RUNNER` (base64, set by
+ * the caller in the command's environment), then `exec` it on the feature's Node so the session
+ * *is* the runner — stdin, signals and exit code included.
+ *
+ * The text rides in the environment rather than in the command because the command is what the
+ * platform shows ("what the platform ran"): eight kilobytes of base64 there would bury the one line
+ * worth reading. `--model` is appended by the platform like for any harness; `resume` adds the
+ * session the platform read off the stream, passed as `$SPUNTO_TASK_SESSION_ID`.
+ */
+export function runnerCommand(harness: AgentHarness, opts: { resume?: boolean } = {}): string {
+  const file = `"$HOME/.spunto/agents/${harness.id}.mjs"`
+  return [
+    `mkdir -p "$HOME/.spunto/agents" && printf %s "$${RUNNER_ENV}" | base64 -d > ${file} && unset ${RUNNER_ENV} &&`,
+    `exec ${AGENT_NODE} ${file} run${opts.resume ? ` --resume "$SPUNTO_TASK_SESSION_ID"` : ""}`,
+  ].join(" ")
+}
+
+/** The harness an injected feature id belongs to, if any. */
+export function harnessOfFeature(featureId: string): AgentHarness | null {
+  return Object.values(AGENT_HARNESSES).find((h) => h.featureId === featureId) ?? null
+}
+
+export { AGENT_FEATURE_SCRIPTS, AGENT_HOME, AGENT_NODE_VERSION } from "./features"
+export { AGENT_CATALOGS, OPTIONS_ENV, agentOptionsError } from "./catalogs"
+export type { AgentCatalog, AgentModel, AgentParam, AgentParamValue } from "./catalogs"

package/src/agent-stream/agent-stream.ts

@@ -22,9 +22,43 @@
 import { contextWindowOf } from "./model-window"
 import { claudeTurnLimit } from "./turn-limit"
 
-export const AGENT_PROTOCOLS = ["none", "claude-json", "claude-stream", "jsonl"] as const
+export const AGENT_PROTOCOLS = ["none", "claude-json", "claude-stream", "jsonl", "claude-runner", "codex-runner"] as const
 export type AgentProtocol = (typeof AGENT_PROTOCOLS)[number]
 
+/**
+ * What a **project** can be set to by hand (`projects.taskAgentProtocol`). The `*-runner` dialects
+ * are not in it: they belong to an agent app (RFC 0048) and come with the app's runner, never with
+ * a command someone typed.
+ */
+export const PROJECT_AGENT_PROTOCOLS = ["none", "claude-json", "claude-stream", "jsonl"] as const
+
+/**
+ * A runner of an agent app (RFC 0048, `../agent-runners`): our own process in the machine, driving a
+ * harness through its official SDK. Its stdin speaks **our** contract (`RunnerInput`), whatever the
+ * harness; its stdout is the harness's own dialect, normalised here like any other.
+ */
+export function isRunner(protocol: AgentProtocol): boolean {
+  return protocol === "claude-runner" || protocol === "codex-runner"
+}
+
+/**
+ * One line of a runner's stdin. The whole input side of the contract — three verbs, the same for
+ * every harness, so the platform never writes a harness's own shape into a runner.
+ */
+export type RunnerInput =
+  | { type: "user"; text: string }
+  | { type: "interrupt"; id: string }
+  | { type: "title"; id: string; description: string }
+
+function runnerLine(input: RunnerInput): string {
+  return `${JSON.stringify(input)}\n`
+}
+
+/** Claude's dialect, whichever way it reaches us — the CLI's `stream-json` or the SDK's messages (the same shapes). */
+function speaksClaude(protocol: AgentProtocol): boolean {
+  return protocol === "claude-json" || protocol === "claude-stream" || protocol === "claude-runner"
+}
+
 /**
  * The normalized vocabulary. Deliberately short — it has to be translatable *from* several
  * harnesses, so anything specific to one of them does not belong in it.
@@ -100,7 +134,7 @@ export function applyProtocol(command: string, protocol: AgentProtocol): string
 
 /** Does this protocol keep the harness alive, listening on stdin, between turns? */
 export function isInteractive(protocol: AgentProtocol): boolean {
-  return protocol === "claude-stream"
+  return protocol === "claude-stream" || isRunner(protocol)
 }
 
 /**
@@ -110,6 +144,7 @@ export function isInteractive(protocol: AgentProtocol): boolean {
  * stops two messages from interleaving into one unparseable line.
  */
 export function userTurnLine(protocol: AgentProtocol, text: string): string {
+  if (isRunner(protocol)) return runnerLine({ type: "user", text })
   if (protocol !== "claude-stream") return `${text}\n`
   return `${JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text }] } })}\n`
 }
@@ -122,6 +157,7 @@ export function userTurnLine(protocol: AgentProtocol, text: string): string {
  * message is a normal turn rather than a resume.
  */
 export function interruptLine(protocol: AgentProtocol, requestId: string): string | null {
+  if (isRunner(protocol)) return runnerLine({ type: "interrupt", id: requestId })
   if (protocol !== "claude-stream") return null
   return `${JSON.stringify({ type: "control_request", request_id: requestId, request: { subtype: "interrupt" } })}\n`
 }
@@ -144,9 +180,12 @@ export function interruptLine(protocol: AgentProtocol, requestId: string): strin
  * `control_response` (an interrupt's, say) without keeping state between write and read.
  */
 export function sessionTitleRequestLine(protocol: AgentProtocol, requestId: string, description: string): string | null {
-  if (protocol !== "claude-stream") return null
+  if (protocol !== "claude-stream" && protocol !== "claude-runner") return null
   const text = description.trim()
   if (!text) return null
+  // The Claude runner asks the SDK (`generateSessionTitle`), and answers with the very
+  // `control_response` the CLI would have printed — so the reading side below is one path.
+  if (protocol === "claude-runner") return runnerLine({ type: "title", id: `${TITLE_REQUEST_PREFIX}${requestId}`, description: text })
   return `${JSON.stringify({
     type: "control_request",
     request_id: `${TITLE_REQUEST_PREFIX}${requestId}`,
@@ -207,7 +246,7 @@ export function sessionTitleProbe(protocol: AgentProtocol, sessionId: string): s
  * session id is looked up, so a harness that says its name in band pays nothing for the question.
  */
 export function readsTitleOutOfBand(protocol: AgentProtocol): boolean {
-  return protocol === "claude-json" || protocol === "claude-stream"
+  return speaksClaude(protocol)
 }
 
 /** Longest name we keep. The column allows 200; a harness that writes an essay gets cut. */
@@ -262,7 +301,9 @@ export function parseStreamLine(protocol: AgentProtocol, line: string): Normaliz
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return []
   const obj = parsed as Record<string, unknown>
-  return protocol === "claude-json" || protocol === "claude-stream" ? adaptClaudeJson(obj) : adaptPassthrough(obj)
+  if (speaksClaude(protocol)) return adaptClaudeJson(obj)
+  if (protocol === "codex-runner") return adaptCodex(obj)
+  return adaptPassthrough(obj)
 }
 
 /**
@@ -280,6 +321,117 @@ function adaptPassthrough(obj: Record<string, unknown>): NormalizedEvent[] {
   return [{ type: type as TaskEventType, payload }]
 }
 
+/**
+ * `codex-runner` — the events of `@openai/codex-sdk`'s `runStreamed()` (`ThreadEvent`), printed one
+ * per line by the Codex runner (RFC 0048). Written against the SDK's own types (0.164.0); the
+ * runner adds nothing of its own beyond a `thread.started` for a resumed thread (the SDK only
+ * announces new ones) and a `turn.failed` when a turn is interrupted. Not yet run against a real
+ * OpenAI account: the shapes below were measured on a failing turn (401) only.
+ *
+ * Codex works per **turn**, not per session: `turn.completed` is a hand-back the way Claude's
+ * `result` is, so it ends the turn here too. Its usage is the turn's sum, which is why it is filed
+ * as a `call` (summed over the task) without a `contextTokens`: no single number of it is the
+ * size of the prompt last sent.
+ */
+function adaptCodex(obj: Record<string, unknown>): NormalizedEvent[] {
+  const type = obj.type
+  if (type === "thread.started") {
+    return [{ type: "session.started", payload: { harness: "codex", model: null, sessionId: typeof obj.thread_id === "string" ? obj.thread_id : null } }]
+  }
+  if (type === "turn.started") return []
+  if (type === "turn.completed") {
+    const u = (obj.usage ?? {}) as Record<string, unknown>
+    return [
+      {
+        type: "usage",
+        payload: {
+          scope: "call",
+          model: null,
+          inputTokens: num(u.input_tokens) ?? 0,
+          outputTokens: (num(u.output_tokens) ?? 0) + (num(u.reasoning_output_tokens) ?? 0),
+          cacheReadTokens: num(u.cached_input_tokens) ?? 0,
+          cacheCreationTokens: num(u.cache_write_input_tokens) ?? 0,
+        },
+      },
+      { type: "session.ended", payload: { status: "succeeded", stopReason: null, summary: "" } },
+    ]
+  }
+  if (type === "turn.failed") {
+    const error = (obj.error ?? {}) as Record<string, unknown>
+    return [{ type: "session.ended", payload: { status: "failed", stopReason: null, summary: clip(error.message).text } }]
+  }
+  // Not an end: measured, Codex emits `error` for every retry ("Reconnecting... 2/5 (401 …)") and
+  // only the `turn.failed` that follows the last one ends the turn. Kept visible, not fatal.
+  if (type === "error") return [{ type: "raw", payload: { json: obj } }]
+  if (type !== "item.started" && type !== "item.updated" && type !== "item.completed") {
+    return [{ type: "raw", payload: { json: obj } }]
+  }
+  const item = (obj.item ?? {}) as Record<string, unknown>
+  const callId = typeof item.id === "string" ? item.id : null
+  const started = type === "item.started"
+  const completed = type === "item.completed"
+  switch (item.type) {
+    case "agent_message": {
+      if (!completed) return []
+      const { text, truncated } = clip(item.text)
+      return text ? [{ type: "message", payload: { role: "assistant", text, truncated } }] : []
+    }
+    case "reasoning": {
+      if (!completed) return []
+      const { text, truncated } = clip(item.text)
+      return text ? [{ type: "thinking", payload: { text, truncated } }] : []
+    }
+    case "command_execution": {
+      if (started) {
+        const { text: input, truncated } = clip({ command: item.command })
+        return [{ type: "tool.call", payload: { callId, name: "Bash", input, truncated } }]
+      }
+      if (!completed) return []
+      const { text: output, truncated } = clip(item.aggregated_output)
+      const failed = item.status === "failed" || (typeof item.exit_code === "number" && item.exit_code !== 0)
+      return [{ type: "tool.result", payload: { callId, isError: failed, output, truncated } }]
+    }
+    case "file_change": {
+      // Reported once, applied: the call and its outcome arrive together.
+      if (!completed) return []
+      const changes = Array.isArray(item.changes) ? item.changes : []
+      const { text: input, truncated } = clip({ changes })
+      const output = changes
+        .filter((c): c is Record<string, unknown> => !!c && typeof c === "object")
+        .map((c) => `${c.kind} ${c.path}`)
+        .join("\n")
+      return [
+        { type: "tool.call", payload: { callId, name: "Edit", input, truncated } },
+        { type: "tool.result", payload: { callId, isError: item.status === "failed", output, truncated: false } },
+      ]
+    }
+    case "mcp_tool_call": {
+      const name = `${typeof item.server === "string" ? item.server : "mcp"}.${typeof item.tool === "string" ? item.tool : "tool"}`
+      if (started) {
+        const { text: input, truncated } = clip(item.arguments)
+        return [{ type: "tool.call", payload: { callId, name, input, truncated } }]
+      }
+      if (!completed) return []
+      const error = (item.error ?? null) as Record<string, unknown> | null
+      const { text: output, truncated } = clip(error ? error.message : (item.result as Record<string, unknown> | undefined)?.content ?? "")
+      return [{ type: "tool.result", payload: { callId, isError: !!error || item.status === "failed", output, truncated } }]
+    }
+    case "web_search": {
+      if (!started) return []
+      const { text: input, truncated } = clip({ query: item.query })
+      return [{ type: "tool.call", payload: { callId, name: "WebSearch", input, truncated } }]
+    }
+    case "todo_list": {
+      const steps = (Array.isArray(item.items) ? item.items : [])
+        .filter((t): t is Record<string, unknown> => !!t && typeof t === "object")
+        .map((t) => ({ text: clip(t.text).text, status: t.completed === true ? "completed" : "pending" }))
+        .filter((s) => s.text)
+      return steps.length > 0 ? [{ type: "plan", payload: { steps } }] : []
+    }
+  }
+  return [{ type: "raw", payload: { json: obj } }]
+}
+
 /**
  * `claude-json` — Claude Code's `--output-format stream-json --verbose`.
  *

package/src/agent-stream/index.ts

@@ -20,9 +20,11 @@ export {
   cleanTitle,
   interruptLine,
   isInteractive,
+  isRunner,
   parseLines,
   parseSessionTitle,
   parseStreamLine,
+  PROJECT_AGENT_PROTOCOLS,
   readsTitleOutOfBand,
   sessionTitleProbe,
   sessionTitleRequestLine,
@@ -38,6 +40,7 @@ export type { TurnLimit, TurnLimitKind } from "./turn-limit"
 export type {
   AgentProtocol,
   NormalizedEvent,
+  RunnerInput,
   SessionUsage,
   SourcedEvent,
   TaskEventType,

package/src/catalogs/index.ts

@@ -40,6 +40,11 @@ export type DevFeature = {
   options?: DevFeatureOption[]
   /** Options always passed to the install script. A user's choice is merged over these. */
   defaultOptions?: Record<string, string>
+  /**
+   * Never picked by hand: the platform injects it into the image of a project whose agent app
+   * (RFC 0048) asks for it. Left out of the feature picker, but still resolved here like any other.
+   */
+  injected?: boolean
 }
 
 /**
@@ -205,6 +210,21 @@ export const AVAILABLE_FEATURES: DevFeature[] = [
     localScript: "google-cloud-cli.sh",
     description: "gcloud, gsutil, bq (local install script)",
   },
+  {
+    // The agent apps' features (RFC 0048, `../agent-runners`): injected, never picked.
+    id: "spunto-agent-claude",
+    label: "Claude (agent app)",
+    localScript: "spunto-agent-claude.sh",
+    description: "The Claude Agent SDK and the Node its runner uses — injected by the Claude app",
+    injected: true,
+  },
+  {
+    id: "spunto-agent-codex",
+    label: "Codex (agent app)",
+    localScript: "spunto-agent-codex.sh",
+    description: "The Codex SDK and the Node its runner uses — injected by the Codex app",
+    injected: true,
+  },
   {
     // Always installed, whether or not it's picked here (lib/setup-script.ts § the two features
     // every worker image is made of): it's what creates the `vscode` user. Listed anyway so a

package/src/script/local-features.ts

@@ -2,13 +2,17 @@
 //
 // Embedded as strings rather than read from disk: the package does no I/O (see the README), and a
 // build script that inlines its own payload is also a build script that cannot fail on a missing
-// file. There is one today, and one is the right number — a local script is a maintenance burden
+// file. There is one of those today, and one is the right number — a local script is a maintenance burden
 // the devcontainer ecosystem is supposed to carry, so the bar for adding another is "the upstream
 // feature does not exist or is broken", not "this was quicker".
 //
 // Keyed by the catalog's `localScript` filename so the two stay legible together.
 
+import { AGENT_FEATURE_SCRIPTS } from "../agent-runners/features"
+
 export const LOCAL_FEATURE_SCRIPTS: Record<string, string> = {
+  // The agent apps' features (RFC 0048): ours by definition — nobody upstream installs our runner's SDK.
+  ...AGENT_FEATURE_SCRIPTS,
   // Google's own apt repository; the upstream devcontainer feature pins a gcloud version and
   // breaks whenever Google retires it.
   "google-cloud-cli.sh": `#!/bin/sh