@spunto/build 0.22.0 → 0.23.0

package/src/agent-runners/claude.mjs

@@ -1,16 +1,17 @@
 #!/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 Claude runner (RFC 0048): written into the machine by the platform when a session starts —
+// one file, **bundled** with its adapter by the platform (esbuild) so there is nothing to install —
+// 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`):
+// The Spunto agent contract, the same for every agent app (docs/agent-contract.md, `../agent-contract`):
 //
 //   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`)
+//   stdout  **our** vocabulary, one JSON object per line (`agent-v1`): each SDK message is read
+//           here (`./claude/adapter.ts`) and printed as the events it means, with the message
+//           itself as `source` — the platform has no Claude reader for it
 //   env     SPUNTO_AGENT_OPTIONS — the task's parameters, as declared by the app's catalog
 //           (`./catalogs.ts`): `{"effort":"high"}`
 //           SPUNTO_AGENT_MCP — the org's MCP servers (RFC 0049), in the platform's words:
@@ -21,10 +22,14 @@
 //   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.
+// `ANTHROPIC_API_KEY`) reaches the SDK's binary through the environment, untouched. The one thing
+// the runner does with that key itself is ask the Models API how large the session's window is
+// (`resolveContextWindow`) — an API key only, never a subscription token, which is the rule the
+// platform followed when it asked on the session's behalf.
 
 import { createInterface } from "node:readline"
+import { claudeTranslator } from "./claude/adapter"
+import { resolveContextWindow } from "../agent-stream/model-window"
 
 const SDK = process.env.SPUNTO_CLAUDE_SDK || "/opt/spunto/agents/claude/node_modules/@anthropic-ai/claude-agent-sdk/sdk.mjs"
 
@@ -32,12 +37,32 @@ 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`. */
+/** A failure the platform can read: the turn ends, failed, saying why — then a non-zero exit. */
 function fail(message) {
-  out({ type: "result", subtype: "error_during_execution", is_error: true, result: message })
+  out({ type: "session.ended", status: "failed", stopReason: null, summary: message })
   process.exit(1)
 }
 
+/** How the window is asked about: an API key, the only credential the platform ever used for it. */
+const apiKey = process.env.ANTHROPIC_API_KEY?.trim()
+const credential = apiKey ? { kind: "api-key", value: apiKey } : null
+
+/**
+ * Print one SDK message as the contract. The line that opens the session carries the model's own
+ * window when the Models API answers (the adapter only knows a table), so it is measured here, once
+ * per session, before the line goes out — the platform no longer asks anyone on a session's behalf.
+ */
+const translate = claudeTranslator()
+async function emit(message) {
+  for (const line of translate(message)) {
+    if (line.type === "session.started" && typeof line.model === "string") {
+      const measured = await resolveContextWindow(line.model, credential).catch(() => null)
+      if (measured !== null) line.contextWindow = measured
+    }
+    out(line)
+  }
+}
+
 function parseArgs(argv) {
   const [verb, ...rest] = argv
   if (verb !== "run") fail(`claude runner: unknown verb "${verb ?? ""}" (expected "run")`)
@@ -165,15 +190,13 @@ createInterface({ input: process.stdin, crlfDelay: Infinity })
     } 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.
+      // Asked of the SDK (Claude names the conversation from the human's words), and said in band.
       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 } } })
-          }
+          const clean = typeof title === "string" ? title.replace(/\s+/g, " ").trim().slice(0, 200) : ""
+          if (clean) out({ type: "session.title", title: clean })
         })
         .catch((err) => process.stderr.write(`claude runner: title failed: ${err?.message ?? err}\n`))
     }
@@ -185,7 +208,7 @@ createInterface({ input: process.stdin, crlfDelay: Infinity })
 let lastType = null
 try {
   for await (const message of session) {
-    out(message)
+    await emit(message)
     lastType = message?.type ?? null
   }
 } catch (err) {

package/src/agent-runners/codex/adapter.ts

@@ -0,0 +1,135 @@
+/**
+ * Codex's dialect, read into our vocabulary — the events of `@openai/codex-sdk`'s `runStreamed()`
+ * (`ThreadEvent`). Written against the SDK's own types (0.164.0).
+ *
+ * Lives with the Codex runner (RFC 0048 § 9): the runner bundles it and prints the contract
+ * (`codexContractLines`). The platform's legacy reader still imports `adaptCodex` for sessions
+ * started on the runner's old dialect, until they end.
+ *
+ * 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.
+ */
+
+import { clip, type NormalizedEvent } from "../../agent-contract/vocabulary"
+
+function num(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null
+}
+
+export 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 } }]
+}
+
+/**
+ * An `agent_message` item being written, as the contract's transient `message.delta`. Codex hands
+ * the whole text so far on `item.started` / `item.updated`, not a delta, so every one opens the
+ * draft afresh with it (`start`); the completed item, stored as the `message`, closes it.
+ */
+export function codexDelta(obj: Record<string, unknown>): Record<string, unknown>[] {
+  if (obj.type !== "item.started" && obj.type !== "item.updated") return []
+  const item = (obj.item ?? {}) as Record<string, unknown>
+  if (item.type !== "agent_message" || typeof item.text !== "string" || !item.text) return []
+  return [{ type: "message.delta", start: true, text: item.text }]
+}
+
+/** One `ThreadEvent`, as the lines of the contract the Codex runner prints, each with the event as `source`. */
+export function codexContractLines(event: Record<string, unknown>): Record<string, unknown>[] {
+  return [...codexDelta(event), ...adaptCodex(event).map((e) => ({ type: e.type, ...e.payload, source: event }))]
+}

package/src/agent-runners/codex.mjs

@@ -1,11 +1,13 @@
 #!/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.
+// with the `codex` binary it drives by the `spunto-agent-codex` feature. Bundled with its adapter
+// by the platform, like every runner.
 //
 //   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)
+//   stdout  **our** vocabulary (`agent-v1`): each `ThreadEvent` read here (`./codex/adapter.ts`),
+//           with the event itself as `source`
 //   env     SPUNTO_AGENT_MCP — the org's MCP servers, through the platform's gateway (RFC 0049)
 //   env     SPUNTO_AGENT_OPTIONS — the task's parameters (`./catalogs.ts`):
 //           `{"reasoningEffort":"high","webSearch":"live"}`
@@ -19,6 +21,7 @@
 // the machine's terminal (`~/.codex/auth.json`), which the binary reads on its own.
 
 import { createInterface } from "node:readline"
+import { codexContractLines } from "./codex/adapter"
 
 const SDK = process.env.SPUNTO_CODEX_SDK || "/opt/spunto/agents/codex/node_modules/@openai/codex-sdk/dist/index.js"
 
@@ -26,8 +29,13 @@ function out(obj) {
   process.stdout.write(`${JSON.stringify(obj)}\n`)
 }
 
+/** One `ThreadEvent` (or one the runner stands in for the SDK), as the contract. */
+function emit(event) {
+  for (const line of codexContractLines(event)) out(line)
+}
+
 function fail(message) {
-  out({ type: "turn.failed", error: { message } })
+  emit({ type: "turn.failed", error: { message } })
   process.exit(1)
 }
 
@@ -110,7 +118,7 @@ const threadOptions = {
 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 })
+if (args.resume) emit({ type: "thread.started", thread_id: args.resume })
 
 const pending = []
 let closed = false
@@ -154,14 +162,14 @@ for (;;) {
   try {
     const { events } = await thread.runStreamed(text, { signal: current.signal })
     for await (const event of events) {
-      out(event)
+      emit(event)
       lastType = event?.type ?? null
     }
   } catch (err) {
     if (current.signal.aborted) {
-      out({ type: "turn.failed", error: { message: "Interrupted." } })
+      emit({ type: "turn.failed", error: { message: "Interrupted." } })
     } else if (lastType !== "turn.failed") {
-      out({ type: "turn.failed", error: { message: `codex runner: ${err?.message ?? err}` } })
+      emit({ type: "turn.failed", error: { message: `codex runner: ${err?.message ?? err}` } })
       failed = true
     }
   }

package/src/agent-runners/index.ts

@@ -7,23 +7,25 @@
  *    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.
+ *  - a **runner**, a `.mjs` entry of ours (`claude.mjs`, `codex.mjs`) with its harness's adapter
+ *    next to it (`claude/adapter.ts`, `codex/adapter.ts`). The caller **bundles** the two into one
+ *    file (esbuild, `platform: node`, `format: esm`) and writes it into the machine at the moment a
+ *    session starts. Not baked: a runner fix reaches the next session, not the next rebuild;
+ *  - the **Spunto agent contract** (`agent-v1`, `../agent-contract`), which is how the platform
+ *    writes the runner's stdin and reads its stdout — the same for every app.
  *
- * The runner contract, identical for every app:
+ * The runner contract, identical for every app (docs/agent-contract.md):
  *
  *   <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
+ *   stdout  our vocabulary, one JSON object per line, each event with its harness message as `source`
+ *   exit    0 = the input closed and the last turn ended; ≠ 0 = the session could not run, and its
+ *           last line is a failed `session.ended` saying why
  *
- * 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.
+ * Pure like the rest of the package: what a caller gets is *where* a runner entry is, and the shell
+ * that starts it. Bundling and reading the file are the caller's I/O.
  */
 
 import type { AgentProtocol } from "../agent-stream/agent-stream"
@@ -39,9 +41,14 @@ 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. */
+  /** How the platform talks to the runner — the contract, for every app. */
   protocol: AgentProtocol
-  /** The runner, a file of this package. */
+  /**
+   * What this app's runner printed before the contract, and so how a session it started then is
+   * still read, until it ends (RFC 0048 § 9: a session keeps the dialect it began on).
+   */
+  legacyProtocol: AgentProtocol
+  /** The runner's entry, a file of this package — to be bundled with what it imports. */
   runnerFile: URL
   /** Where the harness looks for user-level skills (RFC 0033), as shell evaluated in the machine. */
   skillDirs: string[]
@@ -51,14 +58,16 @@ export const AGENT_HARNESSES: Record<AgentHarnessId, AgentHarness> = {
   claude: {
     id: "claude",
     featureId: "spunto-agent-claude",
-    protocol: "claude-runner",
+    protocol: "agent-v1",
+    legacyProtocol: "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",
+    protocol: "agent-v1",
+    legacyProtocol: "codex-runner",
     runnerFile: new URL("./codex.mjs", import.meta.url),
     skillDirs: ["${CODEX_HOME:-$HOME/.codex}/skills"],
   },