@glubean/port 0.1.0 → 0.2.0

package/README.md

@@ -86,6 +86,26 @@ const result = await port.turns.startStructured({
 console.log(result.data)
 ```
 
+Streaming partial JSON: when callers want progressive structure (rather than
+the all-or-nothing `startStructured` contract), accumulate `message.delta.text`
+and feed it to a partial-JSON parser. [`partial-json`](https://www.npmjs.com/package/partial-json)
+is a zero-dependency option designed for LLM streaming:
+
+```ts
+import { parse, Allow } from "partial-json"
+
+let accumulated = ""
+for await (const event of port.turns.start({ sessionId: session.id, input })) {
+  if (event.type !== "message.delta") continue
+  accumulated += event.text
+  const partial = parse(accumulated, Allow.ALL)
+  // push `partial` to the UI as it grows
+}
+```
+
+Use `startStructured` when you need final-shape validation or retry on malformed
+output; use the partial-JSON pattern when you need to render incrementally.
+
 ## Local Development
 
 Node 24 can run the TypeScript sources directly.

package/dist/lifecycle.js

@@ -104,6 +104,10 @@ class LifecycleRuntime {
                         const ref = eventToRef(runtime.#adapter.id, event, input.sessionId);
                         if (ref && !currentTurnId)
                             currentTurnId = ref.turnId;
+                        // Set terminalSeen BEFORE yielding so that if the consumer
+                        // breaks on the terminal event, the finally below does not
+                        // append a spurious cancellation. Same reasoning applies to
+                        // the synthesized terminals further down.
                         if (event.type === "turn.completed")
                             terminalSeen = true;
                         runtime.#record(event, input);
@@ -111,6 +115,7 @@ class LifecycleRuntime {
                     }
                     if (currentTurnId && !terminalSeen) {
                         const completed = completedEvent(input.sessionId, currentTurnId, "completed");
+                        terminalSeen = true;
                         runtime.#record(completed, input);
                         yield completed;
                     }
@@ -120,6 +125,7 @@ class LifecycleRuntime {
                     if (currentTurnId) {
                         const errorEvent = { type: "error", sessionId: input.sessionId, turnId: currentTurnId, message };
                         const completed = completedEvent(input.sessionId, currentTurnId, "failed", message);
+                        terminalSeen = true;
                         runtime.#record(errorEvent, input);
                         runtime.#record(completed, input);
                         yield errorEvent;
@@ -127,6 +133,26 @@ class LifecycleRuntime {
                     }
                     throw error;
                 }
+                finally {
+                    // If the consumer abandons the iterator after the turn was accepted
+                    // but before a terminal event, synthesize a cancellation so
+                    // turns.status / turns.wait don't report "running" forever, and
+                    // ALWAYS poke the adapter to stop work for that turn. We can't
+                    // tell from inside lifecycle whether a previously-recorded error
+                    // event was a terminal failure (claude spawn ENOENT) or a benign
+                    // diagnostic (codex/gemini stderr surfaced as error) — so we
+                    // treat the consumer's break as the authoritative termination
+                    // signal, preserving the recorded error in the snapshot for
+                    // informational purposes.
+                    if (currentTurnId && !terminalSeen) {
+                        const recorded = runtime.#turns.get(turnKey(input.sessionId, currentTurnId));
+                        if (!recorded || !isTerminalStatus(recorded.status)) {
+                            const cancelled = completedEvent(input.sessionId, currentTurnId, "cancelled", recorded?.error);
+                            runtime.#record(cancelled, input);
+                            void runtime.#adapter.cancelTurn({ sessionId: input.sessionId, turnId: currentTurnId }).catch(() => undefined);
+                        }
+                    }
+                }
             },
         };
     }

package/dist/providers/claude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/providers/claude.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAGV,aAAa,EACb,kBAAkB,EAGlB,IAAI,EACJ,cAAc,EAEd,cAAc,EAEf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,KAAK,iBAAiB,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;AAEtD,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,QAAQ,CAwCtD,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAE1F;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAGxG;AA0ID,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,CAe9G"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/providers/claude.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAGV,aAAa,EACb,kBAAkB,EAGlB,IAAI,EACJ,cAAc,EAEd,cAAc,EAEf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,KAAK,iBAAiB,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;AAEtD,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,QAAQ,CAwCtD,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAE1F;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAGxG;AA2KD,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,CAe9G"}

package/dist/providers/claude.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import process from "node:process";
+import { AsyncQueue } from "../async-queue.js";
 import { createPortFromAdapter } from "../port.js";
 import { providerRuntimeOptions, resolveRuntimeOptions } from "../options.js";
 import { normalizeTokenUsage } from "../token-usage.js";
@@ -93,14 +94,23 @@ class ClaudeRuntime {
         });
         this.#processes.set(turnId, child);
         child.stdin.end(inputToPrompt(input.input));
+        const queue = new AsyncQueue();
         let buffered = "";
         let sawMessage = false;
         const stderr = [];
-        const events = [];
-        const push = (event) => {
-            events.push(event);
+        let exitInfo = { code: null, signal: null };
+        let spawnError;
+        const emit = (event) => {
+            queue.push(event);
             this.#events.emit("event", event);
         };
+        const drainLine = (line) => {
+            for (const event of normalizeClaudeLine(line, input.sessionId, turnId, sawMessage)) {
+                if (event.type === "message.delta")
+                    sawMessage = true;
+                emit(event);
+            }
+        };
         child.stdout.setEncoding("utf8");
         child.stdout.on("data", (chunk) => {
             buffered += chunk;
@@ -112,34 +122,57 @@ class ClaudeRuntime {
                 buffered = buffered.slice(newlineIndex + 1);
                 if (!line)
                     continue;
-                for (const event of normalizeClaudeLine(line, input.sessionId, turnId, sawMessage)) {
-                    if (event.type === "message.delta")
-                        sawMessage = true;
-                    push(event);
-                }
+                drainLine(line);
             }
         });
         child.stderr.setEncoding("utf8");
         child.stderr.on("data", (chunk) => stderr.push(chunk));
-        const exit = await waitForExit(child);
-        this.#processes.delete(turnId);
-        const trailing = buffered.trim();
-        if (trailing) {
-            for (const event of normalizeClaudeLine(trailing, input.sessionId, turnId, sawMessage)) {
-                if (event.type === "message.delta")
-                    sawMessage = true;
-                push(event);
+        // Delete from #processes only once the OS reports the child is gone
+        // (close fires after stdio is drained; error covers spawn failures).
+        // Doing this in handlers keeps the map entry reachable for
+        // adapter.close() / cancelTurn() during the gap between SIGTERM and
+        // actual exit, in case the binary ignores or delays the signal.
+        child.on("error", (err) => {
+            spawnError = err;
+            this.#processes.delete(turnId);
+            queue.close();
+        });
+        child.on("close", (code, signal) => {
+            exitInfo = { code, signal };
+            const trailing = buffered.trim();
+            buffered = "";
+            if (trailing)
+                drainLine(trailing);
+            this.#processes.delete(turnId);
+            queue.close();
+        });
+        try {
+            for await (const event of queue)
+                yield event;
+            if (spawnError) {
+                const message = spawnError.message;
+                yield { type: "error", sessionId: input.sessionId, turnId, message };
+                yield completedTurn(input.sessionId, turnId, "failed", message);
+                return;
+            }
+            if (exitInfo.code === 0) {
+                yield completedTurn(input.sessionId, turnId, "completed");
+                return;
             }
+            const message = stderr.join("").trim() || `Claude Code exited with code ${exitInfo.code ?? "null"} signal=${exitInfo.signal ?? "null"}`;
+            yield { type: "error", sessionId: input.sessionId, turnId, message };
+            yield completedTurn(input.sessionId, turnId, "failed", message);
         }
-        for (const event of events)
-            yield event;
-        if (exit.code === 0) {
-            yield completedTurn(input.sessionId, turnId, "completed");
-            return;
+        finally {
+            // If the consumer aborts the iterator while the child is still
+            // alive, send SIGTERM. The close handler above is the single owner
+            // of the #processes entry and will delete it once the kernel
+            // confirms exit — so callers retain a working handle for graceful
+            // shutdown (close()) or escalation (cancelTurn → repeat kill).
+            if (child.exitCode === null && child.signalCode === null) {
+                child.kill();
+            }
         }
-        const message = stderr.join("").trim() || `Claude Code exited with code ${exit.code ?? "null"} signal=${exit.signal ?? "null"}`;
-        yield { type: "error", sessionId: input.sessionId, turnId, message };
-        yield completedTurn(input.sessionId, turnId, "failed", message);
     }
     async #cancelTurn(input) {
         this.#processes.get(input.turnId)?.kill();
@@ -284,9 +317,6 @@ function textFromClaudeMessage(value) {
         return text ? [text] : [];
     });
 }
-function waitForExit(child) {
-    return new Promise((resolve) => child.on("exit", (code, signal) => resolve({ code, signal })));
-}
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }

package/dist/providers/codex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/providers/codex.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAGV,cAAc,EAEd,aAAa,EAEb,kBAAkB,EAElB,SAAS,EACT,IAAI,EACJ,WAAW,EAGZ,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,KAAK,gBAAgB,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAEpD,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC,OAAO,CAwCpD,CAAC;AAEF,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAEvF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAIrG;AAiPD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACpC,GAAG,SAAS,CAYZ"}
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/providers/codex.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAGV,cAAc,EAEd,aAAa,EAEb,kBAAkB,EAElB,SAAS,EACT,IAAI,EACJ,WAAW,EAGZ,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,KAAK,gBAAgB,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAEpD,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC,OAAO,CAwCpD,CAAC;AAEF,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAEvF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAIrG;AAuUD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACpC,GAAG,SAAS,CAYZ"}

package/dist/providers/codex.js

@@ -55,6 +55,13 @@ export async function createCodexAdapter(options) {
     await runtime.start();
     return runtime.adapter;
 }
+/**
+ * Cap stderr buffer to a bounded number of lines so a chatty codex
+ * process cannot grow memory unbounded over a long-lived session. The
+ * tail (most recent N lines) is what we surface in error messages —
+ * head lines from a healthy startup are rarely useful for diagnosis.
+ */
+const STDERR_BUFFER_MAX_LINES = 200;
 class CodexRuntime {
     #options;
     #process;
@@ -62,6 +69,17 @@ class CodexRuntime {
     #normalizer = new CodexEventNormalizer();
     #events = new EventEmitter();
     #closed = false;
+    /**
+     * Bounded ring buffer of recent codex stderr lines, surfaced in
+     * augmented error messages so a 30ms "JSON-RPC input closed" failure
+     * carries the actual codex stderr (auth error, bad flag, missing
+     * config, etc.) instead of disappearing into the void.
+     */
+    #stderrBuffer = [];
+    /** Captured at process 'exit' so subsequent rpc.request rejections can cite it. */
+    #exitInfo = null;
+    /** Captured at process 'error' (e.g. spawn ENOENT) for the same reason. */
+    #spawnError = null;
     constructor(options) {
         this.#options = options;
     }
@@ -104,27 +122,84 @@ class CodexRuntime {
             shell: false,
         });
         this.#process.stderr.on("data", (chunk) => {
-            const message = chunk.toString("utf8").trim();
-            if (message)
-                this.#emit({ type: "error", message });
+            const text = chunk.toString("utf8");
+            // Buffer stderr line-by-line so #augmentError can surface a
+            // bounded tail. We still emit the chunk as an error event so
+            // existing event-stream consumers aren't broken.
+            for (const line of text.split(/\r?\n/)) {
+                if (!line)
+                    continue;
+                this.#stderrBuffer.push(line);
+                if (this.#stderrBuffer.length > STDERR_BUFFER_MAX_LINES) {
+                    this.#stderrBuffer.splice(0, this.#stderrBuffer.length - STDERR_BUFFER_MAX_LINES);
+                }
+            }
+            const trimmed = text.trim();
+            if (trimmed)
+                this.#emit({ type: "error", message: trimmed });
         });
         this.#process.on("exit", (code, signal) => {
+            this.#exitInfo = { code, signal };
             if (!this.#closed) {
                 this.#emit({ type: "error", message: `Codex app-server exited: code=${code ?? "null"} signal=${signal ?? "null"}` });
             }
         });
+        // 'error' fires on spawn failures (e.g. ENOENT when codex binary is
+        // missing from PATH). Without a listener Node would crash the
+        // process on the unhandled emit; instead capture and let the
+        // pending rpc.request rejection surface the spawn error.
+        this.#process.on("error", (err) => {
+            this.#spawnError = err;
+            if (!this.#closed) {
+                this.#emit({ type: "error", message: `Codex app-server spawn error: ${err.message}` });
+            }
+        });
         this.#rpc = new JsonRpcLineConnection(this.#process.stdout, this.#process.stdin);
         this.#rpc.onNotification((notification) => {
             for (const event of this.#normalizer.normalize(notification)) {
                 this.#emit(event);
             }
         });
-        await this.#rpc.request("initialize", {
-            clientInfo: { name: "glubean-port", version: "0.0.0" },
-            capabilities: { experimentalApi: true },
-        });
+        try {
+            await this.#rpc.request("initialize", {
+                clientInfo: { name: "glubean-port", version: "0.0.0" },
+                capabilities: { experimentalApi: true },
+            });
+        }
+        catch (err) {
+            throw await this.#augmentError(err);
+        }
         this.#rpc.notify("initialized", {});
     }
+    /**
+     * Wrap an rpc rejection with codex process diagnostics so callers see
+     * (a) why the process closed if it did, (b) any spawn 'error' (e.g.
+     * ENOENT), and (c) the most recent stderr lines. The original error
+     * is preserved as `cause` for callers that introspect it.
+     *
+     * Awaits a microtask so any racing `process.on("exit")` fires before
+     * we read `#exitInfo` — JsonRpcLineConnection rejects synchronously
+     * from `input.on("close")`, but Node may fire stream 'close' before
+     * the matching process 'exit' on some versions.
+     */
+    async #augmentError(err) {
+        await new Promise((resolve) => setImmediate(resolve));
+        const original = err instanceof Error ? err : new Error(String(err));
+        const parts = [original.message];
+        if (this.#spawnError) {
+            parts.push(`(codex spawn error: ${this.#spawnError.message})`);
+        }
+        if (this.#exitInfo) {
+            parts.push(`(codex process exited: code=${this.#exitInfo.code ?? "null"} signal=${this.#exitInfo.signal ?? "null"})`);
+        }
+        if (this.#stderrBuffer.length > 0) {
+            const tail = this.#stderrBuffer.slice(-20).join("\n");
+            parts.push(`(codex stderr tail:\n${tail})`);
+        }
+        const augmented = new Error(parts.join(" "));
+        augmented.cause = original;
+        return augmented;
+    }
     async close() {
         this.#closed = true;
         this.#rpc?.close();
@@ -152,7 +227,14 @@ class CodexRuntime {
         });
         if (method === "thread/resume")
             params.threadId = input.id ?? "";
-        const result = asRecord(await rpc.request(method, params));
+        let rawResult;
+        try {
+            rawResult = await rpc.request(method, params);
+        }
+        catch (err) {
+            throw await this.#augmentError(err);
+        }
+        const result = asRecord(rawResult);
         const thread = asRecord(result.thread);
         const id = asString(thread.id) ?? input.id;
         if (!id)
@@ -183,18 +265,25 @@ class CodexRuntime {
             const runtimeOptions = resolveRuntimeOptions(input, this.#options.options);
             const codexOptions = providerRuntimeOptions(runtimeOptions);
             const effort = toCodexReasoningEffort(codexOptions.effort);
-            const result = asRecord(await rpc.request("turn/start", {
-                threadId: input.sessionId,
-                input: normalizeInput(input.input),
-                ...(runtimeOptions.cwd ? { cwd: runtimeOptions.cwd } : {}),
-                ...(runtimeOptions.model ? { model: runtimeOptions.model } : {}),
-                ...(runtimeOptions.approvalPolicy ? { approvalPolicy: runtimeOptions.approvalPolicy } : {}),
-                ...(runtimeOptions.sandbox ? { sandboxPolicy: toCodexSandboxPolicy(runtimeOptions.sandbox) } : {}),
-                ...(effort ? { effort } : {}),
-                ...(codexOptions?.reasoningSummary ? { summary: codexOptions.reasoningSummary } : {}),
-                ...(codexOptions?.serviceTier ? { serviceTier: codexOptions.serviceTier } : {}),
-                ...(input.outputSchema ? { outputSchema: input.outputSchema } : {}),
-            }));
+            let rawResult;
+            try {
+                rawResult = await rpc.request("turn/start", {
+                    threadId: input.sessionId,
+                    input: normalizeInput(input.input),
+                    ...(runtimeOptions.cwd ? { cwd: runtimeOptions.cwd } : {}),
+                    ...(runtimeOptions.model ? { model: runtimeOptions.model } : {}),
+                    ...(runtimeOptions.approvalPolicy ? { approvalPolicy: runtimeOptions.approvalPolicy } : {}),
+                    ...(runtimeOptions.sandbox ? { sandboxPolicy: toCodexSandboxPolicy(runtimeOptions.sandbox) } : {}),
+                    ...(effort ? { effort } : {}),
+                    ...(codexOptions?.reasoningSummary ? { summary: codexOptions.reasoningSummary } : {}),
+                    ...(codexOptions?.serviceTier ? { serviceTier: codexOptions.serviceTier } : {}),
+                    ...(input.outputSchema ? { outputSchema: input.outputSchema } : {}),
+                });
+            }
+            catch (err) {
+                throw await this.#augmentError(err);
+            }
+            const result = asRecord(rawResult);
             expectedTurnId = readTurnId(result);
             for await (const event of queue) {
                 yield event;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glubean/port",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Neutral runtime adapter for local coding agents.",
   "type": "module",
   "exports": {
@@ -29,6 +29,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
+    "partial-json": "^0.1.7",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   }