@vincemakes/kiso-server 0.41.1 → 0.42.0

package/README.md

@@ -66,6 +66,20 @@ await service.close(5_000);                              // abort what is live,
   product that must guarantee no prose reaches a client supplies its own
   `sanitize` in the projection options.
 
+## Shutting down, and one thing not to call
+
+The order that keeps every run resumable: `service.drain(graceMs)` (no
+new runs; wait for executing tools; the report says what was parked or
+cut), then stop the listener, then `store.closeAll()`, then exit. Do not
+call `service.close()` for that — it ABORTS what is live, including a
+run parked at an approval, which voids the draft its answer would have
+continued. And do not call `agent.close()` on a factory's agent when the
+store is shared: in the runtime it closes the whole store.
+
+`hooks.onSettled` is the product's "what next" after a run: a follow-up
+turn, a resume when `uncertainRemaining` reaches zero, a notification.
+The service never starts a run on its own.
+
 ## What a host still writes
 
 The transport (routes, SSE framing, `Last-Event-ID`, keepalive, status
@@ -82,5 +96,8 @@ 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.
-
+`authorize` is required: there is no default that allows. `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).

package/dist/http.d.ts

@@ -33,14 +33,23 @@ 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[]>;
-    /** The product's turn preparation; default: `body.input` as given. */
-    readonly prepareInput?: (body: Readonly<Record<string, unknown>>, req: IncomingMessage, sessionId: string) => WireInput | Promise<WireInput>;
+    /** 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 }`;
+     *  the handler then returns without opening a run, a session, or a 400
+     *  (a gate, a quota, an attachment check, an empty message — the
+     *  product's refusals in the product's shape). */
+    readonly prepareInput?: (body: Readonly<Record<string, unknown>>, req: IncomingMessage, sessionId: string, res: ServerResponse) => WireInput | Handled | Promise<WireInput | Handled>;
     readonly projection?: ProjectionOptions;
     /** `: keepalive` comments on an idle stream. Default 15 s; 0 disables. */
     readonly keepaliveMs?: number;
     /** Request-body cap in bytes. Default 1 MiB. */
     readonly bodyLimit?: number;
 }
+/** What `prepareInput` returns when it answered the request itself. */
+export interface Handled {
+    readonly handled: true;
+}
 export interface HttpHandler {
     /** True when the request was an agent route and has been answered. */
     readonly handle: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;

package/dist/http.js

@@ -1,6 +1,10 @@
 import { DrainingError, InFlightError, OpenRunError } from "./errors.js";
 import { toWireEvent } from "./wire.js";
-const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** The store's own rule (`^[A-Za-z0-9._-]+$`), with a length cap. 0.41.2:
+ *  the first version also required a leading letter or digit, which the
+ *  store never did — a nanoid can start with `_` or `-` (about 1 in 32 do)
+ *  and every such session answered 404. */
+const SESSION_ID = /^[A-Za-z0-9._-]{1,128}$/;
 const ACTIONS = new Set(["", "state", "events", "replay", "run", "resume", "abort", "approve", "uncertain"]);
 export function createHttpHandler(service, options) {
     const prefix = (options.prefix ?? "/v1/sessions").replace(/\/+$/, "");
@@ -50,9 +54,9 @@ export function createHttpHandler(service, options) {
             throw new BadRequest("body must be a JSON object");
         return parsed;
     };
-    const inputOf = async (body, req, sessionId) => {
+    const inputOf = async (body, req, sessionId, res) => {
         if (options.prepareInput !== undefined)
-            return options.prepareInput(body, req, sessionId);
+            return options.prepareInput(body, req, sessionId, res);
         const input = body["input"];
         if (typeof input === "string") {
             if (input.trim() === "")
@@ -187,7 +191,9 @@ export function createHttpHandler(service, options) {
             if (action === "run" || action === "resume") {
                 let handle;
                 if (action === "run") {
-                    const input = await inputOf(body, req, sessionId);
+                    const input = await inputOf(body, req, sessionId, res);
+                    if (isHandled(input))
+                        return true; // the product answered; nothing opened
                     const source = body["source"];
                     handle = await service.run(sessionId, input, {
                         ...(source === "user" || source === "suggestion" || source === "tool_result" ? { source: source } : {}),
@@ -241,6 +247,9 @@ export function createHttpHandler(service, options) {
     };
     return { handle };
 }
+function isHandled(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v) && v.handled === true;
+}
 class BadRequest extends Error {
     constructor(message) {
         super(message);

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  * the agent factory, and every run is the runtime's own `Session.run()`.
  */
 export { createSessionService, SessionService } from "./service.js";
-export type { AbortOutcome, DrainReport, OpenRun, RunHandle, RunOptions, SessionServiceOptions } from "./service.js";
+export type { AbortOutcome, DrainReport, OpenRun, RunHandle, RunOptions, SessionServiceOptions, SettledRun } from "./service.js";
 export { DrainingError, InFlightError, OpenRunError, StoreMismatchError } from "./errors.js";
 export { EXECUTION_ENDED, executionDelta } from "./execution.js";
 export { tail } from "./tail.js";

package/dist/service.d.ts

@@ -48,8 +48,26 @@ export interface SessionServiceOptions {
         /** After `abort()` has aborted a run: the product's cleanup, e.g.
          *  finishing paid jobs the run left in flight. */
         readonly onAbort?: (sessionId: string, runId: string) => Promise<void> | void;
+        /** After a run has settled — its terminal delivered to every
+         *  listener, the session idle again. The product's "what next": a
+         *  follow-up turn (`service.run`), a resume when the last uncertain
+         *  verdict is in (`uncertainRemaining === 0`), a notification. The
+         *  service itself never starts a run on its own. Runs after the
+         *  store check, so a mismatched session never reaches it. */
+        readonly onSettled?: (settled: SettledRun) => Promise<void> | void;
     };
 }
+/** What `hooks.onSettled` receives. */
+export interface SettledRun {
+    readonly sessionId: string;
+    readonly runId: string;
+    /** The terminal's outcome kind: completed | aborted | error | max_turns | max_tokens | hook_stopped. */
+    readonly outcome: string;
+    /** Executions still awaiting a human verdict after this run. */
+    readonly uncertainRemaining: number;
+    /** The highest seq this run delivered. */
+    readonly highWater: number;
+}
 export interface RunHandle {
     readonly runId: string;
     /** Settles when the run has reached its terminal and the last event has

package/dist/service.js

@@ -81,6 +81,16 @@ export class SessionService {
                 held.mismatch = new StoreMismatchError(held.id, run.runId, held.highWater);
                 throw held.mismatch;
             }
+            if (this.#hooks.onSettled !== undefined) {
+                const terminal = [...held.session.log.all].reverse().find((e) => e.type === "terminal");
+                await this.#hooks.onSettled({
+                    sessionId: held.id,
+                    runId: run.runId,
+                    outcome: terminal !== undefined && terminal.type === "terminal" ? terminal.outcome.kind : "unknown",
+                    uncertainRemaining: held.session.uncertainExecutions().length,
+                    highWater: held.highWater,
+                });
+            }
         })();
         held.pumping = pumping;
         void pumping.catch(() => { }); // a host that does not await `done` gets no unhandled rejection

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-server",
-	"version": "0.41.1",
+	"version": "0.42.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.41.1",
-		"@vincemakes/kiso-protocol": "0.41.1",
-		"@vincemakes/kiso-runtime": "0.41.1"
+		"@vincemakes/kiso-core": "0.42.0",
+		"@vincemakes/kiso-protocol": "0.42.0",
+		"@vincemakes/kiso-runtime": "0.42.0"
 	},
 	"devDependencies": {
-		"@vincemakes/kiso-evals": "0.41.1",
+		"@vincemakes/kiso-evals": "0.42.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"