@vincemakes/kiso-server 0.42.3 → 0.43.0

package/README.md

@@ -88,7 +88,7 @@ factory. The service is the part that was the same in every host.
 
 ## The HTTP + SSE transport — `@vincemakes/kiso-server/http`
 
-`createHttpHandler(service, { authorize, augment?, prepareInput?, projection?, keepaliveMs? })`
+`createHttpHandler(service, { authorize, augment?, frames?, prepareInput?, projection?, keepaliveMs? })`
 returns a `handle(req, res)` a host mounts in front of its own routes; it
 answers the agent routes under `prefix` (default `/v1/sessions`) and
 returns false for everything else. Status codes and framing are decided
@@ -96,8 +96,18 @@ here once: `id: <seq>` / `event: <type>` / `data: <WireEvent>`, an `: open`
 preamble, `Last-Event-ID` and `?after`, a keepalive; `in_flight` and
 `open_run` are 409, `draining` 503, `forbidden` 403. Wire events are the
 projection in `@vincemakes/kiso-protocol` — never the durable event.
-`authorize` is required: there is no default that allows. `prepareInput`
+`authorize` is required: there is no default that allows. `openRun`, `openRuns`, and `events()` on a session the service has not opened read the durable store and THROW when its log is unreadable; they never disguise corruption as an empty result — call them inside a try/catch in a host callback. `highWater()` is process-local and does not read the store. `prepareInput`
 may answer a request itself — write the product's own status and body to
 the response it receives and return `{ handled: true }`; nothing is opened
 and no run starts (a gate, a quota, an attachment check, in the product's
 own shape).
+
+`frames` (0.43.0) is the host's own frame source: called once per open
+stream with a `push`, and whatever the host pushes — a long tool's
+progress, a retry banner — is written on the same ordered chain as the
+wire events, on `/run?stream=1` and on `GET /events` alike, so a frame
+pushed between two events lands between them. `augment` fires only
+beside a durable event; `frames` is for the minutes in which nothing
+durable happens. The function it returns is called when the stream
+ends. Nothing pushed is durable: a client that reconnects sees the
+events again, never these frames.

package/dist/http.d.ts

@@ -33,6 +33,15 @@ export interface HttpHandlerOptions {
     readonly authorize: (req: IncomingMessage, sessionId: string) => Promise<boolean> | boolean;
     /** Frames a product adds beside a wire event on the same connection. */
     readonly augment?: (event: Event, sessionId: string) => readonly WireFrame[] | Promise<readonly WireFrame[]>;
+    /** 0.43.0 (#4): the host's own frame source. Called once per open
+     *  stream with a `push`; whatever the host pushes — a tool's progress,
+     *  a retry banner — is written on the SAME ordered chain as the wire
+     *  events, so a frame pushed between two events lands between them,
+     *  on `/run?stream=1` and on `GET /events` alike. The returned function
+     *  is called when the stream ends; a push after that is dropped.
+     *  Nothing here is durable: a reconnecting client sees events again,
+     *  never these frames. */
+    readonly frames?: (sessionId: string, push: (frame: WireFrame) => void) => (() => void) | void;
     /** The product's turn preparation; default: `body.input` as given.
      *  0.42.0: it may instead ANSWER the request itself — write the
      *  product's own status and body to `res` and return `{ handled: true }`;

package/dist/http.js

@@ -113,6 +113,15 @@ export function createHttpHandler(service, options) {
                     res.write(text);
             });
         });
+        // 0.43.0 (#4): the host's frames ride the same chain — ordered with
+        // the events, dropped once the stream has ended.
+        const push = (frame) => {
+            chain = chain.then(() => {
+                if (!closed)
+                    res.write(`event: ${frame.event}\ndata: ${JSON.stringify(frame.data)}\n\n`);
+            });
+        };
+        const stopFrames = options.frames?.(sessionId, push) ?? undefined;
         const keepalive = keepaliveMs > 0 ? setInterval(() => res.write(": keepalive\n\n"), keepaliveMs) : undefined;
         keepalive?.unref();
         const end = () => {
@@ -121,6 +130,7 @@ export function createHttpHandler(service, options) {
             closed = true;
             if (keepalive !== undefined)
                 clearInterval(keepalive);
+            stopFrames?.();
             unsubscribe();
         };
         req.on("close", end);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-server",
-	"version": "0.42.3",
+	"version": "0.43.0",
 	"description": "kiso server — the hosted-session service: many durable sessions in one process, observers with exact replay from a sequence number, approve / abort / resume routed to the right run, drain and close. No transport; a product supplies the agent factory.",
 	"type": "module",
 	"license": "MIT",
@@ -25,12 +25,12 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-core": "0.42.3",
-		"@vincemakes/kiso-protocol": "0.42.3",
-		"@vincemakes/kiso-runtime": "0.42.3"
+		"@vincemakes/kiso-core": "0.43.0",
+		"@vincemakes/kiso-protocol": "0.43.0",
+		"@vincemakes/kiso-runtime": "0.43.0"
 	},
 	"devDependencies": {
-		"@vincemakes/kiso-evals": "0.42.3",
+		"@vincemakes/kiso-evals": "0.43.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"