@vincemakes/kiso-server 0.41.1 → 0.41.2

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

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(/\/+$/, "");

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.41.2",
 	"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.41.2",
+		"@vincemakes/kiso-protocol": "0.41.2",
+		"@vincemakes/kiso-runtime": "0.41.2"
 	},
 	"devDependencies": {
-		"@vincemakes/kiso-evals": "0.41.1",
+		"@vincemakes/kiso-evals": "0.41.2",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"