@glubean/port 0.1.1 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glubean/port",
-  "version": "0.1.1",
+  "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"
   }