@spunto/build 0.21.1 → 0.23.0

package/README.md

@@ -166,8 +166,34 @@ JSON columns at them with `$type<…>()`, instead of a generator having to impor
 `SetupStatus` is what a shell script writes into a container and a control plane reads back minutes
 later: changing it is a migration, not an edit.
 
+### `@spunto/build/agent-contract` — the Spunto agent contract
+
+What an agent app's runner reads on stdin (`user`, `interrupt`, `title`) and prints on stdout:
+**our** vocabulary, one JSON object per line, each event with the harness message it was read from
+as `source`. The runner normalises; the platform has one strict reader for every app:
+
+```ts
+import { readContractLine, runConformance, agentContractSchema } from "@spunto/build/agent-contract"
+
+readContractLine('{"type":"message","role":"assistant","text":"done"}') // → [{ type, payload, source }]
+// closed schemas: an unknown field or type is kept as `raw`, with the reason — never half-read
+
+const results = await runConformance(start) // start: ({ resume }) => a process you spawned
+```
+
+The JSON Schema is shipped as `@spunto/build/agent-contract/schema.json`, generated from the very
+table the reader validates with. The conformance suite drives a runner like the platform does and
+checks every line and the order of events (simple turn, tool, interrupt, resume, limit, title,
+files). `@spunto/build/agent-contract/fake-agent.mjs` is a whole runner in 46 lines with no SDK
+that passes it. The Claude and Codex runners (`./agent-runners`) carry their adapters next to them
+and are meant to be **bundled** (esbuild, `platform: node`, `format: esm`) before being run.
+
 ### `@spunto/build/agent-stream` — reading an agent session as it happens
 
+Since the contract (`agent-v1`), what is left here is the writing side of a session and the
+**legacy dialects** — the CLI's `claude-stream`, the runners' former `claude-runner` /
+`codex-runner` — for sessions that began on them.
+
 One adapter per harness dialect, one vocabulary out. A CLI's JSON output is an output format, not
 an API; adapters normalise into a small set of event types so stored history doesn't date the first
 time a vendor reshuffles a field.
@@ -175,6 +201,12 @@ time a vendor reshuffles a field.
 Here for the reason that inverts the rest of the package: **nothing has forked this yet.** Putting
 it in the shared package now costs nothing and means the second product never writes its own.
 
+Tokens of a message still being written (Claude's `stream_event` lines, from
+`includePartialMessages`) are **not** events: `parseStreamLine` reads them as nothing, and
+`foldDraft(protocol, lines, previous)` folds them into the one transient text block in flight —
+closed by the finished message, never stored. Where the draft lives between two reads is the
+caller's business.
+
 ### `@spunto/build/terminal` — the half of a persistent terminal that is a string
 
 A worker's terminal is an exec attached to a session that outlives it, so closing a browser tab

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.21.1",
+  "version": "0.23.0",
   "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",
@@ -63,6 +63,12 @@
       "types": "./src/agent-stream/index.ts",
       "import": "./src/agent-stream/index.ts"
     },
+    "./agent-contract": {
+      "types": "./src/agent-contract/index.ts",
+      "import": "./src/agent-contract/index.ts"
+    },
+    "./agent-contract/schema.json": "./src/agent-contract/agent-contract.v1.schema.json",
+    "./agent-contract/fake-agent.mjs": "./src/agent-contract/examples/fake-agent.mjs",
     "./agent-protocol": {
       "types": "./src/agent-protocol/index.ts",
       "import": "./src/agent-protocol/index.ts"
@@ -104,7 +110,8 @@
     "typescript": "^5",
     "vitest": "^4.1.10",
     "ws": "^8.22.0",
-    "zod": "^4.6.5"
+    "zod": "^4.6.5",
+    "esbuild": "^0.25.12"
   },
   "peerDependencies": {
     "zod": "^4"