@vincemakes/kiso-server 0.41.0 → 0.41.2

package/README.md

@@ -50,6 +50,36 @@ await service.close(5_000);                              // abort what is live,
 - **Product frames on the stream** (billing, estimates, couriers) are the
   transport's business; the service delivers the durable events only.
 
+## What the host owns
+
+- **The store.** `createSessionService({ store })` takes the store the
+  factory's agents write to; the service never closes it — `close()`
+  aborts runs and forgets sessions, and the host calls `store.closeAll()`
+  when its process ends. Everything about an open session is read from
+  that session's own log (the object the run writes), so replay and run
+  share one truth by construction; a factory that binds its agents to a
+  DIFFERENT store is detected — the first run to settle on such a session
+  ends with `StoreMismatchError` and the session is refused from then on.
+- **The sanitizer's guarantee.** The default `sanitizeToolArgs` strips
+  prose keys and truncates long strings at every depth. It is a UI-noise
+  and casual-leak filter for a tool card, not a privacy boundary: a
+  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/errors.d.ts

@@ -19,6 +19,15 @@ export declare class OpenRunError extends Error {
     readonly runId: string;
     constructor(sessionId: string, runId: string);
 }
+/** The factory's agent writes to a different store than the service was
+ *  given: a run settled and its terminal is not on the service's store.
+ *  Two stores are two truths, which kiso does not allow — the session is
+ *  refused from here on (the host's wiring is wrong, not the run). */
+export declare class StoreMismatchError extends Error {
+    readonly sessionId: string;
+    readonly runId: string;
+    constructor(sessionId: string, runId: string, expectedSeq: number);
+}
 /** drain() was called: no new run or resume starts in this process. */
 export declare class DrainingError extends Error {
     constructor();

package/dist/errors.js

@@ -29,6 +29,20 @@ export class OpenRunError extends Error {
         this.runId = runId;
     }
 }
+/** The factory's agent writes to a different store than the service was
+ *  given: a run settled and its terminal is not on the service's store.
+ *  Two stores are two truths, which kiso does not allow — the session is
+ *  refused from here on (the host's wiring is wrong, not the run). */
+export class StoreMismatchError extends Error {
+    sessionId;
+    runId;
+    constructor(sessionId, runId, expectedSeq) {
+        super(`session ${sessionId}: run ${runId} settled at seq ${expectedSeq} but the service's store does not hold it — the agent factory's store is not the service's store`);
+        this.name = "StoreMismatchError";
+        this.sessionId = sessionId;
+        this.runId = runId;
+    }
+}
 /** drain() was called: no new run or resume starts in this process. */
 export class DrainingError extends Error {
     constructor() {

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,10 +7,10 @@
  * 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 { DrainingError, InFlightError, OpenRunError } from "./errors.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";
-export { MAX_ARG_VALUE_CHARS, STRIPPED_ARG_KEYS, sanitizeToolArgs, toWireEvent } from "./wire.js";
+export { MAX_ARG_DEPTH, MAX_ARG_VALUE_CHARS, STRIPPED_ARG_KEYS, sanitizeToolArgs, toWireEvent } from "./wire.js";
 export type { ProjectionOptions } from "./wire.js";
 export type { Listener } from "./tail.js";

package/dist/index.js

@@ -7,7 +7,7 @@
  * the agent factory, and every run is the runtime's own `Session.run()`.
  */
 export { createSessionService, SessionService } from "./service.js";
-export { DrainingError, InFlightError, OpenRunError } from "./errors.js";
+export { DrainingError, InFlightError, OpenRunError, StoreMismatchError } from "./errors.js";
 export { EXECUTION_ENDED, executionDelta } from "./execution.js";
 export { tail } from "./tail.js";
-export { MAX_ARG_VALUE_CHARS, STRIPPED_ARG_KEYS, sanitizeToolArgs, toWireEvent } from "./wire.js";
+export { MAX_ARG_DEPTH, MAX_ARG_VALUE_CHARS, STRIPPED_ARG_KEYS, sanitizeToolArgs, toWireEvent } from "./wire.js";

package/dist/service.d.ts

@@ -20,9 +20,19 @@ import { type Listener } from "./tail.js";
  * loop of its own.
  */
 export interface SessionServiceOptions {
-    /** The store every session in this process lives on — the same one the
-     *  factory's agents write to. The service reads it for replay and for
-     *  the open-run check. */
+    /** The store every session in this process lives on — the SAME one the
+     *  factory's agents write to. The service reads it for boot recovery
+     *  (`openRuns()`) and for cold reads of sessions it has not opened;
+     *  everything about an open session is read from that session's own
+     *  log, so the run that writes and the replay that reads share one
+     *  object by construction. The remaining way to get two stores — a
+     *  factory that binds its agents to another store — is DETECTED: the
+     *  first run to settle on such a session ends with StoreMismatchError
+     *  and the session is refused from then on.
+     *
+     *  Ownership: the host owns the store. `close()` aborts runs and
+     *  forgets sessions; it never closes the store — the host calls
+     *  `store.closeAll()` when its process ends. */
     readonly store: SessionStore;
     /** The product's agent factory, called once per session id (and again by
      *  `reopen`). Everything product-specific — prompt, tools, extensions,
@@ -38,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
@@ -121,9 +149,12 @@ export declare class SessionService {
         readonly remaining: number;
     }>;
     /** Every event after `after` — the ones on disk now, then the live ones
-     *  as they land — exactly once each, in order. Returns the unsubscribe. */
+     *  as they land — exactly once each, in order. Returns the unsubscribe.
+     *  The replay reads the OPEN session's own log, never a second copy. */
     subscribe(sessionId: string, after: number, listener: Listener): Promise<() => void>;
-    /** The durable log after `after` — a plain read, no session opened. */
+    /** The durable log after `after`. An open session answers from its own
+     *  log; a session this process has not opened is read from the store
+     *  (a cold read, nothing opened). */
     events(sessionId: string, after?: number): Event[];
     isRunning(sessionId: string): boolean;
     /** The highest seq this process has delivered for the session, −1 before any. */
@@ -133,6 +164,8 @@ export declare class SessionService {
     /** The run a previous process left without a terminal on this session,
      *  or null. The plain read the transport's snapshot needs. */
     openRun(sessionId: string): string | null;
+    /** True once a settled run proved the factory's store is not this one. */
+    mismatched(sessionId: string): boolean;
     /** Boot recovery: every session on the store whose last run has no
      *  terminal. The host decides what to do with them (resume, or leave
      *  for the next request to find). */
@@ -144,7 +177,9 @@ export declare class SessionService {
     /** Abort every live run, wait up to `graceMs` for each to settle (a
      *  tool that ignores the abort keeps its run open until it returns),
      *  then forget every session. Whatever did not settle is resumable by
-     *  the next process — persist-first means nothing delivered is lost. */
+     *  the next process — persist-first means nothing delivered is lost.
+     *  The STORE is not closed here: the host owns it and calls
+     *  `store.closeAll()` when its process ends. */
     close(graceMs?: number): Promise<void>;
 }
 export declare function createSessionService(options: SessionServiceOptions): SessionService;

package/dist/service.js

@@ -1,5 +1,5 @@
 import { openRunId } from "@vincemakes/kiso-runtime/internal";
-import { DrainingError, InFlightError, OpenRunError } from "./errors.js";
+import { DrainingError, InFlightError, OpenRunError, StoreMismatchError } from "./errors.js";
 import { executionDelta } from "./execution.js";
 import { tail } from "./tail.js";
 export class SessionService {
@@ -24,7 +24,7 @@ export class SessionService {
         const opening = (async () => {
             const agent = await this.#open(sessionId);
             const session = await agent.session({ id: sessionId });
-            const held = { id: sessionId, agent, session, listeners: new Set(), live: null, pumping: null, executing: 0, highWater: -1 };
+            const held = { id: sessionId, agent, session, listeners: new Set(), live: null, pumping: null, executing: 0, highWater: -1, mismatch: null };
             this.#held.set(sessionId, held);
             return held;
         })();
@@ -73,6 +73,24 @@ export class SessionService {
                     held.executing = 0;
                 }
             }
+            // the one-truth check: what this run wrote must be on the store the
+            // service was given. Persist-first means the terminal is on disk
+            // before it was yielded above; a store that does not hold it is a
+            // different store.
+            if (held.highWater >= 0 && !this.#store.load(held.id).some((r) => r.event.seq === held.highWater)) {
+                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
@@ -85,6 +103,8 @@ export class SessionService {
         if (this.#draining)
             throw new DrainingError();
         const held = await this.#hold(sessionId);
+        if (held.mismatch !== null)
+            throw held.mismatch;
         if (held.live !== null)
             throw new InFlightError(sessionId, held.live.runId);
         const open = openRunId(this.#store.load(sessionId));
@@ -102,6 +122,8 @@ export class SessionService {
         if (this.#draining)
             throw new DrainingError();
         const held = await this.#hold(sessionId);
+        if (held.mismatch !== null)
+            throw held.mismatch;
         if (held.live !== null)
             throw new InFlightError(sessionId, held.live.runId);
         return this.#pump(held, held.session.resume());
@@ -155,17 +177,19 @@ export class SessionService {
     }
     // ---- observation ----------------------------------------------------------
     /** Every event after `after` — the ones on disk now, then the live ones
-     *  as they land — exactly once each, in order. Returns the unsubscribe. */
+     *  as they land — exactly once each, in order. Returns the unsubscribe.
+     *  The replay reads the OPEN session's own log, never a second copy. */
     async subscribe(sessionId, after, listener) {
         const held = await this.#hold(sessionId);
-        return tail(() => this.events(sessionId, after), held.listeners, after, listener);
+        return tail(() => held.session.log.all.filter((e) => e.seq > after), held.listeners, after, listener);
     }
-    /** The durable log after `after` — a plain read, no session opened. */
+    /** The durable log after `after`. An open session answers from its own
+     *  log; a session this process has not opened is read from the store
+     *  (a cold read, nothing opened). */
     events(sessionId, after = -1) {
-        return this.#store
-            .load(sessionId)
-            .map((r) => r.event)
-            .filter((e) => e.seq > after);
+        const held = this.#held.get(sessionId);
+        const events = held !== undefined ? held.session.log.all : this.#store.load(sessionId).map((r) => r.event);
+        return events.filter((e) => e.seq > after);
     }
     isRunning(sessionId) {
         return this.#held.get(sessionId)?.live !== null && this.#held.get(sessionId)?.live !== undefined;
@@ -188,6 +212,10 @@ export class SessionService {
     openRun(sessionId) {
         return openRunId(this.#store.load(sessionId)) ?? null;
     }
+    /** True once a settled run proved the factory's store is not this one. */
+    mismatched(sessionId) {
+        return this.#held.get(sessionId)?.mismatch !== null && this.#held.get(sessionId)?.mismatch !== undefined;
+    }
     /** Boot recovery: every session on the store whose last run has no
      *  terminal. The host decides what to do with them (resume, or leave
      *  for the next request to find). */
@@ -237,7 +265,9 @@ export class SessionService {
     /** Abort every live run, wait up to `graceMs` for each to settle (a
      *  tool that ignores the abort keeps its run open until it returns),
      *  then forget every session. Whatever did not settle is resumable by
-     *  the next process — persist-first means nothing delivered is lost. */
+     *  the next process — persist-first means nothing delivered is lost.
+     *  The STORE is not closed here: the host owns it and calls
+     *  `store.closeAll()` when its process ends. */
     async close(graceMs = 0) {
         this.#draining = true;
         const settling = [];

package/dist/wire.d.ts

@@ -22,8 +22,13 @@ export interface ProjectionOptions {
 export declare const STRIPPED_ARG_KEYS: ReadonlySet<string>;
 /** Longer string values are cut here; the card shows a prefix. */
 export declare const MAX_ARG_VALUE_CHARS = 200;
-/** The default sanitizer: drops the prose keys, truncates long strings,
- *  leaves non-objects alone. Shallow — an argument's nested object is
- *  passed through as is. */
-export declare function sanitizeToolArgs(input: unknown): unknown;
+/** Nesting beyond this is replaced by a marker rather than walked. */
+export declare const MAX_ARG_DEPTH = 8;
+/** The default sanitizer: drops the prose keys and truncates long strings
+ *  AT EVERY DEPTH — objects and arrays are walked (0.41.1; the 0.41.0
+ *  version was shallow, so `{ options: { prompt } }` passed the prompt
+ *  through). What it is: a UI-noise and casual-leak filter for a tool
+ *  card. What it is not: a privacy boundary — a product that must
+ *  guarantee no prose reaches a client supplies its own `sanitize`. */
+export declare function sanitizeToolArgs(input: unknown, depth?: number): unknown;
 export declare function toWireEvent(event: Event, options?: ProjectionOptions): WireEvent | null;

package/dist/wire.js

@@ -5,17 +5,28 @@ import { DURABLE_TO_WIRE, SANITIZED_FIELDS, WIRE_FIELDS } from "@vincemakes/kiso
 export const STRIPPED_ARG_KEYS = new Set(["prompt", "description", "text", "body", "content", "instructions", "system_prompt", "input_text"]);
 /** Longer string values are cut here; the card shows a prefix. */
 export const MAX_ARG_VALUE_CHARS = 200;
-/** The default sanitizer: drops the prose keys, truncates long strings,
- *  leaves non-objects alone. Shallow — an argument's nested object is
- *  passed through as is. */
-export function sanitizeToolArgs(input) {
-    if (input === null || typeof input !== "object" || Array.isArray(input))
+/** Nesting beyond this is replaced by a marker rather than walked. */
+export const MAX_ARG_DEPTH = 8;
+/** The default sanitizer: drops the prose keys and truncates long strings
+ *  AT EVERY DEPTH — objects and arrays are walked (0.41.1; the 0.41.0
+ *  version was shallow, so `{ options: { prompt } }` passed the prompt
+ *  through). What it is: a UI-noise and casual-leak filter for a tool
+ *  card. What it is not: a privacy boundary — a product that must
+ *  guarantee no prose reaches a client supplies its own `sanitize`. */
+export function sanitizeToolArgs(input, depth = 0) {
+    if (typeof input === "string")
+        return input.length > MAX_ARG_VALUE_CHARS ? `${input.slice(0, MAX_ARG_VALUE_CHARS)}…` : input;
+    if (input === null || typeof input !== "object")
         return input;
+    if (depth >= MAX_ARG_DEPTH)
+        return Array.isArray(input) ? "[…]" : "{…}";
+    if (Array.isArray(input))
+        return input.map((v) => sanitizeToolArgs(v, depth + 1));
     const out = {};
     for (const [key, value] of Object.entries(input)) {
         if (STRIPPED_ARG_KEYS.has(key))
             continue;
-        out[key] = typeof value === "string" && value.length > MAX_ARG_VALUE_CHARS ? `${value.slice(0, MAX_ARG_VALUE_CHARS)}…` : value;
+        out[key] = sanitizeToolArgs(value, depth + 1);
     }
     return out;
 }

package/package.json

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