@vincemakes/kiso-server 0.41.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kiso contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @vincemakes/kiso-server
+
+The hosted-session service: many durable kiso sessions in one long-lived
+process, each with observers, one run at a time. It is the layer a product
+backend puts between its HTTP (or socket, or stdio) handlers and the
+runtime — the layer two products wrote independently before this package
+existed.
+
+It is not a transport, and it is not a second agent. Every session here is
+`runtime.createAgent(...).session({ id })`; every run is that session's
+`run()` / `resume()`. The product supplies the agent factory; the service
+never learns what the agent is for.
+
+```ts
+import { createSessionService } from "@vincemakes/kiso-server";
+import { createAgent, SessionStore } from "@vincemakes/kiso-runtime";
+
+const store = new SessionStore("./sessions");
+const service = createSessionService({
+  store,
+  open: async (sessionId) => createAgent({ /* the product's definition */ store, model, tools, extensions }),
+});
+
+const { runId, done } = await service.run("s1", "hello");     // InFlightError | OpenRunError | DrainingError
+const off = await service.subscribe("s1", lastSeqSeen, (ev) => send(ev)); // replay, then live, exactly once
+await service.approve("s1", decisionId, true);                 // → { needsResume }
+await service.abort("s1");                                     // → idle | parked (who is waited for) | stopped
+await service.drain(20_000);                                   // → { waitedFor, parked, interrupted, timedOut }
+await service.close(5_000);                              // abort what is live, wait up to the grace
+```
+
+## What it decides, and what it leaves to the host
+
+- **One run per session.** A second `run()` while one is live refuses
+  with `InFlightError`.
+- **An open run in the log** (a previous process died inside it) refuses
+  with `OpenRunError`; `run(input, { resumeFirst: true })` resumes it to its
+  terminal first. Silent resume is the one option not offered.
+- **Abort while parked.** A run waiting for a person — a kernel approval,
+  or whatever `hooks.parkedBy` names (the ask extension's questions) —
+  is parked, not running. `abort()` returns `{ kind: "parked", ... }` and
+  does nothing; `{ force: true }` aborts anyway. "stopped" carries a
+  `settled` promise: the kernel does not kill a tool, so a tool that
+  ignores the abort keeps its run open until it returns.
+- **After the last uncertain verdict** the service does not resume;
+  `resolveUncertain` returns `{ remaining }` and the host resumes at zero.
+- **Executing tools** are counted from `tool_execution_started` and the
+  three ending events (succeeded, failed, resolved) — `EXECUTION_ENDED`,
+  stated once.
+- **Product frames on the stream** (billing, estimates, couriers) are the
+  transport's business; the service delivers the durable events only.
+
+## What a host still writes
+
+The transport (routes, SSE framing, `Last-Event-ID`, keepalive, status
+codes), the agent factory, and any per-session product state it feeds the
+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? })`
+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
+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.
+

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The service's typed refusals. A transport maps each to its own status
+ * (409 / 409 / 503 in the two products that wrote these by hand); the
+ * service itself knows no status code.
+ */
+/** A run is already in flight for this session — one run per session. */
+export declare class InFlightError extends Error {
+    readonly sessionId: string;
+    readonly runId: string;
+    constructor(sessionId: string, runId: string);
+}
+/** The log holds a run that never reached its terminal — a previous
+ *  process died inside it. It must be resumed (recovery drives ONE run to
+ *  its terminal) before a new turn starts; `run(..., { resumeFirst: true })`
+ *  does that in one call. The one thing the service never does is resume
+ *  silently. */
+export declare class OpenRunError extends Error {
+    readonly sessionId: string;
+    readonly runId: string;
+    constructor(sessionId: string, runId: string);
+}
+/** drain() was called: no new run or resume starts in this process. */
+export declare class DrainingError extends Error {
+    constructor();
+}

package/dist/errors.js

@@ -0,0 +1,38 @@
+/**
+ * The service's typed refusals. A transport maps each to its own status
+ * (409 / 409 / 503 in the two products that wrote these by hand); the
+ * service itself knows no status code.
+ */
+/** A run is already in flight for this session — one run per session. */
+export class InFlightError extends Error {
+    sessionId;
+    runId;
+    constructor(sessionId, runId) {
+        super(`session ${sessionId} already has a run in flight (${runId})`);
+        this.name = "InFlightError";
+        this.sessionId = sessionId;
+        this.runId = runId;
+    }
+}
+/** The log holds a run that never reached its terminal — a previous
+ *  process died inside it. It must be resumed (recovery drives ONE run to
+ *  its terminal) before a new turn starts; `run(..., { resumeFirst: true })`
+ *  does that in one call. The one thing the service never does is resume
+ *  silently. */
+export class OpenRunError extends Error {
+    sessionId;
+    runId;
+    constructor(sessionId, runId) {
+        super(`session ${sessionId} still has an open run (${runId}) — resume it before starting a new turn`);
+        this.name = "OpenRunError";
+        this.sessionId = sessionId;
+        this.runId = runId;
+    }
+}
+/** drain() was called: no new run or resume starts in this process. */
+export class DrainingError extends Error {
+    constructor() {
+        super("the service is draining — no new run starts in this process");
+        this.name = "DrainingError";
+    }
+}

package/dist/execution.d.ts

@@ -0,0 +1,12 @@
+import type { Event } from "@vincemakes/kiso-core";
+/**
+ * The events that end a tool execution, stated ONCE.
+ *
+ * The two products that counted executing tools by hand disagreed on this
+ * set: one stopped at succeeded / failed, the other also counted resolved.
+ * Resolved belongs here — an uncertain execution that received its verdict
+ * is no longer executing, whichever verdict it got.
+ */
+export declare const EXECUTION_ENDED: ReadonlySet<Event["type"]>;
+/** +1 when a tool starts executing, −1 when one ends, 0 otherwise. */
+export declare function executionDelta(event: Event): -1 | 0 | 1;

package/dist/execution.js

@@ -0,0 +1,19 @@
+/**
+ * The events that end a tool execution, stated ONCE.
+ *
+ * The two products that counted executing tools by hand disagreed on this
+ * set: one stopped at succeeded / failed, the other also counted resolved.
+ * Resolved belongs here — an uncertain execution that received its verdict
+ * is no longer executing, whichever verdict it got.
+ */
+export const EXECUTION_ENDED = new Set([
+    "tool_execution_succeeded",
+    "tool_execution_failed",
+    "tool_execution_resolved",
+]);
+/** +1 when a tool starts executing, −1 when one ends, 0 otherwise. */
+export function executionDelta(event) {
+    if (event.type === "tool_execution_started")
+        return 1;
+    return EXECUTION_ENDED.has(event.type) ? -1 : 0;
+}

package/dist/http.d.ts

@@ -0,0 +1,48 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Event } from "@vincemakes/kiso-core";
+import type { WireFrame, WireInput } from "@vincemakes/kiso-protocol";
+import type { SessionService } from "./service.js";
+import { type ProjectionOptions } from "./wire.js";
+/**
+ * The HTTP + SSE transport over the hosted-session service.
+ *
+ * A host mounts `handle` in front of its own routes: it answers the agent
+ * routes under `prefix` and returns false for everything else. Status codes
+ * and framing are decided here, once — the two hosting products had each
+ * chosen their own (409 for in-flight in one, an exception in the other;
+ * `event:` on every frame in one, none in the other; a keepalive in one).
+ *
+ *   GET  {prefix}/:id/events     the stream, from ?after or Last-Event-ID
+ *   GET  {prefix}/:id            the session snapshot (also /state)
+ *   GET  {prefix}/:id/replay     every wire event on the log + the snapshot
+ *   POST {prefix}/:id/run        202 { runId } — or the run's own stream with ?stream=1
+ *   POST {prefix}/:id/resume     202 { runId } — or the stream with ?stream=1
+ *   POST {prefix}/:id/abort      200 idle | stopped — 409 parked (who is waited for)
+ *   POST {prefix}/:id/approve    200 { needsResume }
+ *   POST {prefix}/:id/uncertain  200 { remaining }
+ *
+ * What the host supplies: `authorize` (REQUIRED — session ownership; there
+ * is no default that allows), and optionally `augment` (frames beside a
+ * wire event: billing, estimates), `prepareInput` (the product's turn
+ * preparation), the projection options and the keepalive period.
+ */
+export interface HttpHandlerOptions {
+    /** The mount point; the session id and the action follow it. Default `/v1/sessions`. */
+    readonly prefix?: string;
+    /** Session ownership, per request. False → 403, and nothing is opened. */
+    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>;
+    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;
+}
+export interface HttpHandler {
+    /** True when the request was an agent route and has been answered. */
+    readonly handle: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+}
+export declare function createHttpHandler(service: SessionService, options: HttpHandlerOptions): HttpHandler;

package/dist/http.js

@@ -0,0 +1,249 @@
+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}$/;
+const ACTIONS = new Set(["", "state", "events", "replay", "run", "resume", "abort", "approve", "uncertain"]);
+export function createHttpHandler(service, options) {
+    const prefix = (options.prefix ?? "/v1/sessions").replace(/\/+$/, "");
+    const keepaliveMs = options.keepaliveMs ?? 15_000;
+    const bodyLimit = options.bodyLimit ?? 1024 * 1024;
+    const projection = options.projection ?? {};
+    const json = (res, status, body) => {
+        res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify(body));
+    };
+    const fail = (res, status, code, message, runId) => {
+        const error = { code, message, ...(runId !== undefined ? { runId } : {}) };
+        json(res, status, error);
+    };
+    /** The service's refusals → the wire's codes. */
+    const refuse = (res, err) => {
+        if (err instanceof InFlightError)
+            return fail(res, 409, "in_flight", err.message, err.runId);
+        if (err instanceof OpenRunError)
+            return fail(res, 409, "open_run", err.message, err.runId);
+        if (err instanceof DrainingError)
+            return fail(res, 503, "draining", err.message);
+        if (err instanceof BadRequest)
+            return fail(res, 400, "bad_request", err.message);
+        fail(res, 500, "internal", err instanceof Error ? err.message : String(err));
+    };
+    const readBody = async (req) => {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of req) {
+            const buf = chunk;
+            size += buf.length;
+            if (size > bodyLimit)
+                throw new BadRequest(`body exceeds ${bodyLimit} bytes`);
+            chunks.push(buf);
+        }
+        if (chunks.length === 0)
+            return {};
+        let parsed;
+        try {
+            parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        }
+        catch {
+            throw new BadRequest("body is not JSON");
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            throw new BadRequest("body must be a JSON object");
+        return parsed;
+    };
+    const inputOf = async (body, req, sessionId) => {
+        if (options.prepareInput !== undefined)
+            return options.prepareInput(body, req, sessionId);
+        const input = body["input"];
+        if (typeof input === "string") {
+            if (input.trim() === "")
+                throw new BadRequest("input must be a non-empty string");
+            return input;
+        }
+        if (Array.isArray(input) && input.length > 0)
+            return input;
+        throw new BadRequest("input must be a non-empty string or a non-empty array of content blocks");
+    };
+    const state = async (sessionId) => {
+        const events = service.events(sessionId);
+        return {
+            sessionId,
+            running: service.isRunning(sessionId),
+            highWater: events.at(-1)?.seq ?? -1,
+            openRun: service.openRun(sessionId),
+            pendingApprovals: await service.pendingApprovals(sessionId),
+            uncertain: (await service.uncertainExecutions(sessionId)).map((u) => ({ executionId: u.executionId, callId: u.callId, name: u.name })),
+        };
+    };
+    /** One durable event → its frames: the wire event (if any) under its seq, then the product's. */
+    const framesOf = async (event, sessionId) => {
+        let out = "";
+        const wire = toWireEvent(event, projection);
+        if (wire !== null)
+            out += `id: ${wire.seq}\nevent: ${wire.type}\ndata: ${JSON.stringify(wire)}\n\n`;
+        if (options.augment !== undefined) {
+            for (const frame of await options.augment(event, sessionId))
+                out += `event: ${frame.event}\ndata: ${JSON.stringify(frame.data)}\n\n`;
+        }
+        return out;
+    };
+    /** Open an SSE response and pump the session's events after `after`
+     *  into it until the client leaves or `until` settles. */
+    const stream = async (res, req, sessionId, after, until) => {
+        res.writeHead(200, {
+            "content-type": "text/event-stream; charset=utf-8",
+            "cache-control": "no-cache, no-transform",
+            connection: "keep-alive",
+            "x-accel-buffering": "no",
+        });
+        res.write(": open\n\n");
+        // frames are written in event order even though augment is async:
+        // a chain serialises them
+        let chain = Promise.resolve();
+        let closed = false;
+        const unsubscribe = await service.subscribe(sessionId, after, (event) => {
+            chain = chain.then(async () => {
+                if (closed)
+                    return;
+                const text = await framesOf(event, sessionId);
+                if (!closed && text !== "")
+                    res.write(text);
+            });
+        });
+        const keepalive = keepaliveMs > 0 ? setInterval(() => res.write(": keepalive\n\n"), keepaliveMs) : undefined;
+        keepalive?.unref();
+        const end = () => {
+            if (closed)
+                return;
+            closed = true;
+            if (keepalive !== undefined)
+                clearInterval(keepalive);
+            unsubscribe();
+        };
+        req.on("close", end);
+        res.on("close", end);
+        if (until !== undefined) {
+            await until.catch(() => { });
+            await chain; // every frame of the run has been written
+            end();
+            res.end();
+        }
+    };
+    const afterOf = (req, url, body) => {
+        const header = req.headers["last-event-id"];
+        const fromHeader = typeof header === "string" ? Number(header) : NaN;
+        if (Number.isFinite(fromHeader))
+            return fromHeader;
+        const fromBody = body !== undefined && typeof body["after"] === "number" ? body["after"] : NaN;
+        if (Number.isFinite(fromBody))
+            return fromBody;
+        const fromQuery = Number(url.searchParams.get("after") ?? NaN);
+        return Number.isFinite(fromQuery) ? fromQuery : -1;
+    };
+    const handle = async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (url.pathname !== prefix && !url.pathname.startsWith(`${prefix}/`))
+            return false;
+        const rest = url.pathname.slice(prefix.length + 1);
+        const slash = rest.indexOf("/");
+        const rawId = slash === -1 ? rest : rest.slice(0, slash);
+        const action = slash === -1 ? "" : rest.slice(slash + 1);
+        let sessionId;
+        try {
+            sessionId = decodeURIComponent(rawId);
+        }
+        catch {
+            fail(res, 400, "bad_request", "malformed session id");
+            return true;
+        }
+        if (!SESSION_ID.test(sessionId) || !ACTIONS.has(action)) {
+            fail(res, 404, "not_found", "no such route");
+            return true;
+        }
+        try {
+            if (!(await options.authorize(req, sessionId))) {
+                fail(res, 403, "forbidden", "this session is not yours");
+                return true;
+            }
+            const method = req.method ?? "GET";
+            if (method === "GET" && action === "events") {
+                await stream(res, req, sessionId, afterOf(req, url));
+                return true;
+            }
+            if (method === "GET" && (action === "" || action === "state")) {
+                json(res, 200, await state(sessionId));
+                return true;
+            }
+            if (method === "GET" && action === "replay") {
+                const events = service.events(sessionId).map((e) => toWireEvent(e, projection)).filter((w) => w !== null);
+                json(res, 200, { sessionId, events, state: await state(sessionId) });
+                return true;
+            }
+            if (method !== "POST") {
+                fail(res, 405, "bad_request", `${method} is not allowed on ${action || "the session"}`);
+                return true;
+            }
+            const body = await readBody(req);
+            const wantsStream = url.searchParams.get("stream") === "1";
+            if (action === "run" || action === "resume") {
+                let handle;
+                if (action === "run") {
+                    const input = await inputOf(body, req, sessionId);
+                    const source = body["source"];
+                    handle = await service.run(sessionId, input, {
+                        ...(source === "user" || source === "suggestion" || source === "tool_result" ? { source: source } : {}),
+                        ...(body["resumeFirst"] === true ? { resumeFirst: true } : {}),
+                    });
+                }
+                else {
+                    handle = await service.resume(sessionId);
+                }
+                if (wantsStream)
+                    await stream(res, req, sessionId, afterOf(req, url, body), handle.done);
+                else
+                    json(res, 202, { runId: handle.runId });
+                return true;
+            }
+            if (action === "abort") {
+                const outcome = await service.abort(sessionId, body["force"] === true ? { force: true } : {});
+                const reply = outcome.kind === "stopped" ? { kind: "stopped", runId: outcome.runId } : outcome;
+                json(res, outcome.kind === "parked" ? 409 : 200, reply);
+                return true;
+            }
+            if (action === "approve") {
+                const decisionId = body["decisionId"];
+                const allow = body["allow"];
+                if (typeof decisionId !== "string" || decisionId === "" || typeof allow !== "boolean")
+                    throw new BadRequest("decisionId (string) and allow (boolean) are required");
+                const reason = body["reason"];
+                json(res, 200, await service.approve(sessionId, decisionId, allow, typeof reason === "string" ? reason : undefined));
+                return true;
+            }
+            if (action === "uncertain") {
+                const executionId = body["executionId"];
+                const resolution = body["resolution"];
+                if (typeof executionId !== "string" || executionId === "" || (resolution !== "rerun" && resolution !== "abandoned")) {
+                    throw new BadRequest('executionId (string) and resolution ("rerun" | "abandoned") are required');
+                }
+                json(res, 200, await service.resolveUncertain(sessionId, executionId, resolution));
+                return true;
+            }
+            fail(res, 404, "not_found", "no such route");
+            return true;
+        }
+        catch (err) {
+            if (res.headersSent) {
+                res.end();
+                return true;
+            }
+            refuse(res, err);
+            return true;
+        }
+    };
+    return { handle };
+}
+class BadRequest extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BadRequest";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @vincemakes/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, no product noun: the product supplies
+ * 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 { 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 type { ProjectionOptions } from "./wire.js";
+export type { Listener } from "./tail.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * @vincemakes/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, no product noun: the product supplies
+ * 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 { EXECUTION_ENDED, executionDelta } from "./execution.js";
+export { tail } from "./tail.js";
+export { MAX_ARG_VALUE_CHARS, STRIPPED_ARG_KEYS, sanitizeToolArgs, toWireEvent } from "./wire.js";

package/dist/service.d.ts

@@ -0,0 +1,150 @@
+import type { ContentBlock, Event, MessageSource } from "@vincemakes/kiso-core";
+import type { Agent, ApprovalRequest, Session, SessionStore } from "@vincemakes/kiso-runtime";
+import { type Listener } from "./tail.js";
+/**
+ * The hosted-session service — many durable sessions in one long-lived
+ * process, each with observers, one run at a time.
+ *
+ * What it is: the layer two products wrote independently on top of the
+ * runtime (a session registry, the one-run rule, a pump that fans a run's
+ * events out to listeners and counts executing tools, replay-from-seq for
+ * reconnecting observers, approve / abort / resume routed to the right
+ * run, drain before exit). It names no product noun: the product hands
+ * in an agent FACTORY (control inversion) and the service never learns
+ * what the agent is for.
+ *
+ * What it is not: a transport. HTTP, SSE, sockets and their status codes
+ * live above it. It is also not a second Agent — every session here is
+ * `runtime.createAgent(...).session({ id })`, and every run is that
+ * session's `run()` / `resume()`; the service adds bookkeeping, never a
+ * 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. */
+    readonly store: SessionStore;
+    /** The product's agent factory, called once per session id (and again by
+     *  `reopen`). Everything product-specific — prompt, tools, extensions,
+     *  permission policy — is decided in here. */
+    readonly open: (sessionId: string) => Promise<Agent>;
+    readonly hooks?: {
+        /** Product-level parking beyond the kernel's own approvals — the ask
+         *  extension's pending questions are the known case. A non-empty
+         *  list means the run is waiting for a person, so `abort()` refuses
+         *  (a voided draft is not what "stop" means when someone is being
+         *  asked) unless forced. */
+        readonly parkedBy?: (sessionId: string) => readonly string[];
+        /** 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;
+    };
+}
+export interface RunHandle {
+    readonly runId: string;
+    /** Settles when the run has reached its terminal and the last event has
+     *  been delivered to every listener. Rejects only if the runtime threw
+     *  (a poisoned session); a run that fails still SETTLES — its failure is
+     *  a terminal event, not an exception. */
+    readonly done: Promise<void>;
+}
+export interface RunOptions {
+    readonly source?: MessageSource;
+    /** The log holds an open run from a previous process: resume it to its
+     *  terminal first, then start this turn. Without this the call refuses
+     *  with `OpenRunError` — the service never resumes silently. */
+    readonly resumeFirst?: boolean;
+}
+export type AbortOutcome = {
+    readonly kind: "idle";
+} | {
+    readonly kind: "parked";
+    readonly runId: string;
+    readonly approvals: readonly ApprovalRequest[];
+    readonly reasons: readonly string[];
+} | {
+    readonly kind: "stopped";
+    readonly runId: string;
+    readonly settled: Promise<void>;
+};
+export interface DrainReport {
+    /** Sessions with a tool executing when drain began; waited for, up to the grace. */
+    readonly waitedFor: readonly string[];
+    /** Sessions whose run is waiting for a person — untouched, resumable. */
+    readonly parked: readonly string[];
+    /** Sessions streaming (no tool executing) — cut when the process exits, resumable. */
+    readonly interrupted: readonly string[];
+    /** The subset of `waitedFor` still executing when the grace ran out. */
+    readonly timedOut: readonly string[];
+}
+export interface OpenRun {
+    readonly sessionId: string;
+    readonly runId: string;
+}
+export declare class SessionService {
+    #private;
+    constructor(options: SessionServiceOptions);
+    /** Rebuild an IDLE session from the factory — the product's definition
+     *  changed (its tool set, its prompt) and the next run should see it.
+     *  Observers are carried over. Refuses while a run is in flight. */
+    reopen(sessionId: string): Promise<void>;
+    /** Start a turn. Refuses with `InFlightError` (one run per session),
+     *  `OpenRunError` (a previous process died inside a run — see
+     *  `resumeFirst`) or `DrainingError`. */
+    run(sessionId: string, input: string | readonly ContentBlock[], options?: RunOptions): Promise<RunHandle>;
+    /** Drive the open run (one a previous process left, or one parked at an
+     *  approval that has since been answered) to its terminal. */
+    resume(sessionId: string): Promise<RunHandle>;
+    /** Stop the run in flight. A run waiting for a person (a kernel approval,
+     *  or whatever `hooks.parkedBy` names) is PARKED, not running: aborting
+     *  it would void the draft the answer is meant to continue, so the
+     *  service refuses and says who is being waited for — `force` overrides.
+     *  "stopped" means the abort was delivered; `settled` resolves when the
+     *  run's terminal is written (a tool that ignores the abort signal keeps
+     *  the run open until it returns — the kernel does not kill tools). The
+     *  `onAbort` hook runs on the abort, not on the settle. */
+    abort(sessionId: string, options?: {
+        readonly force?: boolean;
+    }): Promise<AbortOutcome>;
+    /** Answer a kernel approval. `needsResume` is true when no run was live
+     *  to consume the answer (the process that asked is gone): the decision
+     *  is durable, and `resume()` is what makes the run continue. */
+    approve(sessionId: string, decisionId: string, allow: boolean, reason?: string): Promise<{
+        readonly needsResume: boolean;
+    }>;
+    pendingApprovals(sessionId: string): Promise<readonly ApprovalRequest[]>;
+    uncertainExecutions(sessionId: string): Promise<ReturnType<Session["uncertainExecutions"]>>;
+    /** Record a verdict on an uncertain execution. `remaining` is how many
+     *  still await one; the host resumes when it reaches zero — the service
+     *  does not start runs on its own. */
+    resolveUncertain(sessionId: string, executionId: string, resolution: "rerun" | "abandoned"): Promise<{
+        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. */
+    subscribe(sessionId: string, after: number, listener: Listener): Promise<() => void>;
+    /** The durable log after `after` — a plain read, no session opened. */
+    events(sessionId: string, after?: number): Event[];
+    isRunning(sessionId: string): boolean;
+    /** The highest seq this process has delivered for the session, −1 before any. */
+    highWater(sessionId: string): number;
+    executingCount(): number;
+    get draining(): boolean;
+    /** 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;
+    /** 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). */
+    openRuns(): OpenRun[];
+    /** Stop accepting runs; wait up to `graceMs` for executing tools; report.
+     *  Nothing is aborted here — a run cut by the process exiting is
+     *  resumable, and the report says which sessions those are. */
+    drain(graceMs: number): Promise<DrainReport>;
+    /** 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. */
+    close(graceMs?: number): Promise<void>;
+}
+export declare function createSessionService(options: SessionServiceOptions): SessionService;

package/dist/service.js

@@ -0,0 +1,263 @@
+import { openRunId } from "@vincemakes/kiso-runtime/internal";
+import { DrainingError, InFlightError, OpenRunError } from "./errors.js";
+import { executionDelta } from "./execution.js";
+import { tail } from "./tail.js";
+export class SessionService {
+    #store;
+    #open;
+    #hooks;
+    /** id → the opening (memoized, so two concurrent callers share one open). */
+    #opening = new Map();
+    /** id → the held session, once open. */
+    #held = new Map();
+    #draining = false;
+    constructor(options) {
+        this.#store = options.store;
+        this.#open = options.open;
+        this.#hooks = options.hooks ?? {};
+    }
+    // ---- the registry -------------------------------------------------------
+    async #hold(sessionId) {
+        const existing = this.#opening.get(sessionId);
+        if (existing !== undefined)
+            return existing;
+        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 };
+            this.#held.set(sessionId, held);
+            return held;
+        })();
+        this.#opening.set(sessionId, opening);
+        try {
+            return await opening;
+        }
+        catch (err) {
+            this.#opening.delete(sessionId);
+            throw err;
+        }
+    }
+    /** Rebuild an IDLE session from the factory — the product's definition
+     *  changed (its tool set, its prompt) and the next run should see it.
+     *  Observers are carried over. Refuses while a run is in flight. */
+    async reopen(sessionId) {
+        const held = await this.#hold(sessionId);
+        if (held.live !== null)
+            throw new InFlightError(sessionId, held.live.runId);
+        const agent = await this.#open(sessionId);
+        held.agent = agent;
+        held.session = await agent.session({ id: sessionId });
+    }
+    // ---- runs -----------------------------------------------------------------
+    #pump(held, run) {
+        held.live = run;
+        const pumping = (async () => {
+            try {
+                for await (const event of run) {
+                    held.executing = Math.max(0, held.executing + executionDelta(event));
+                    held.highWater = Math.max(held.highWater, event.seq);
+                    for (const listener of [...held.listeners]) {
+                        try {
+                            listener(event);
+                        }
+                        catch {
+                            held.listeners.delete(listener); // a throwing observer leaves; the run does not
+                        }
+                    }
+                }
+            }
+            finally {
+                if (held.live === run) {
+                    held.live = null;
+                    held.pumping = null;
+                    held.executing = 0;
+                }
+            }
+        })();
+        held.pumping = pumping;
+        void pumping.catch(() => { }); // a host that does not await `done` gets no unhandled rejection
+        return { runId: run.runId, done: pumping };
+    }
+    /** Start a turn. Refuses with `InFlightError` (one run per session),
+     *  `OpenRunError` (a previous process died inside a run — see
+     *  `resumeFirst`) or `DrainingError`. */
+    async run(sessionId, input, options = {}) {
+        if (this.#draining)
+            throw new DrainingError();
+        const held = await this.#hold(sessionId);
+        if (held.live !== null)
+            throw new InFlightError(sessionId, held.live.runId);
+        const open = openRunId(this.#store.load(sessionId));
+        if (open !== undefined) {
+            if (options.resumeFirst !== true)
+                throw new OpenRunError(sessionId, open);
+            await this.#pump(held, held.session.resume()).done;
+        }
+        const run = held.session.run(input, options.source !== undefined ? { source: options.source } : {});
+        return this.#pump(held, run);
+    }
+    /** Drive the open run (one a previous process left, or one parked at an
+     *  approval that has since been answered) to its terminal. */
+    async resume(sessionId) {
+        if (this.#draining)
+            throw new DrainingError();
+        const held = await this.#hold(sessionId);
+        if (held.live !== null)
+            throw new InFlightError(sessionId, held.live.runId);
+        return this.#pump(held, held.session.resume());
+    }
+    /** Stop the run in flight. A run waiting for a person (a kernel approval,
+     *  or whatever `hooks.parkedBy` names) is PARKED, not running: aborting
+     *  it would void the draft the answer is meant to continue, so the
+     *  service refuses and says who is being waited for — `force` overrides.
+     *  "stopped" means the abort was delivered; `settled` resolves when the
+     *  run's terminal is written (a tool that ignores the abort signal keeps
+     *  the run open until it returns — the kernel does not kill tools). The
+     *  `onAbort` hook runs on the abort, not on the settle. */
+    async abort(sessionId, options = {}) {
+        const held = await this.#hold(sessionId);
+        const run = held.live;
+        if (run === null)
+            return { kind: "idle" };
+        const approvals = held.session.pendingApprovals();
+        const reasons = this.#hooks.parkedBy?.(sessionId) ?? [];
+        if ((approvals.length > 0 || reasons.length > 0) && options.force !== true) {
+            return { kind: "parked", runId: run.runId, approvals, reasons };
+        }
+        run.abort();
+        const settled = held.pumping?.catch(() => { }) ?? Promise.resolve();
+        await this.#hooks.onAbort?.(sessionId, run.runId);
+        return { kind: "stopped", runId: run.runId, settled };
+    }
+    // ---- decisions ------------------------------------------------------------
+    /** Answer a kernel approval. `needsResume` is true when no run was live
+     *  to consume the answer (the process that asked is gone): the decision
+     *  is durable, and `resume()` is what makes the run continue. */
+    async approve(sessionId, decisionId, allow, reason) {
+        const held = await this.#hold(sessionId);
+        const wasLive = held.live !== null;
+        await held.session.approve(decisionId, allow, reason);
+        return { needsResume: !wasLive };
+    }
+    async pendingApprovals(sessionId) {
+        return (await this.#hold(sessionId)).session.pendingApprovals();
+    }
+    async uncertainExecutions(sessionId) {
+        return (await this.#hold(sessionId)).session.uncertainExecutions();
+    }
+    /** Record a verdict on an uncertain execution. `remaining` is how many
+     *  still await one; the host resumes when it reaches zero — the service
+     *  does not start runs on its own. */
+    async resolveUncertain(sessionId, executionId, resolution) {
+        const held = await this.#hold(sessionId);
+        await held.session.resolveUncertain(executionId, resolution);
+        return { remaining: held.session.uncertainExecutions().length };
+    }
+    // ---- 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. */
+    async subscribe(sessionId, after, listener) {
+        const held = await this.#hold(sessionId);
+        return tail(() => this.events(sessionId, after), held.listeners, after, listener);
+    }
+    /** The durable log after `after` — a plain read, no session opened. */
+    events(sessionId, after = -1) {
+        return this.#store
+            .load(sessionId)
+            .map((r) => r.event)
+            .filter((e) => e.seq > after);
+    }
+    isRunning(sessionId) {
+        return this.#held.get(sessionId)?.live !== null && this.#held.get(sessionId)?.live !== undefined;
+    }
+    /** The highest seq this process has delivered for the session, −1 before any. */
+    highWater(sessionId) {
+        return this.#held.get(sessionId)?.highWater ?? -1;
+    }
+    executingCount() {
+        let n = 0;
+        for (const held of this.#held.values())
+            n += held.executing;
+        return n;
+    }
+    get draining() {
+        return this.#draining;
+    }
+    /** The run a previous process left without a terminal on this session,
+     *  or null. The plain read the transport's snapshot needs. */
+    openRun(sessionId) {
+        return openRunId(this.#store.load(sessionId)) ?? null;
+    }
+    /** 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). */
+    openRuns() {
+        const out = [];
+        for (const sessionId of this.#store.ids()) {
+            const runId = openRunId(this.#store.load(sessionId));
+            if (runId !== undefined)
+                out.push({ sessionId, runId });
+        }
+        return out;
+    }
+    // ---- process lifecycle -------------------------------------------------
+    /** Stop accepting runs; wait up to `graceMs` for executing tools; report.
+     *  Nothing is aborted here — a run cut by the process exiting is
+     *  resumable, and the report says which sessions those are. */
+    async drain(graceMs) {
+        this.#draining = true;
+        const waitedFor = [];
+        const parked = [];
+        const interrupted = [];
+        const waits = [];
+        for (const held of this.#held.values()) {
+            if (held.live === null)
+                continue;
+            if (held.executing > 0) {
+                waitedFor.push(held.id);
+                if (held.pumping !== null)
+                    waits.push(held.pumping.catch(() => { }));
+                continue;
+            }
+            const askedFor = held.session.pendingApprovals().length > 0 || (this.#hooks.parkedBy?.(held.id) ?? []).length > 0;
+            (askedFor ? parked : interrupted).push(held.id);
+        }
+        if (waits.length === 0)
+            return { waitedFor, parked, interrupted, timedOut: [] };
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(() => resolve("timeout"), graceMs);
+        });
+        const outcome = await Promise.race([Promise.allSettled(waits).then(() => "done"), deadline]);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        const timedOut = outcome === "timeout" ? waitedFor.filter((id) => (this.#held.get(id)?.executing ?? 0) > 0) : [];
+        return { waitedFor, parked, interrupted, timedOut };
+    }
+    /** 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. */
+    async close(graceMs = 0) {
+        this.#draining = true;
+        const settling = [];
+        for (const held of this.#held.values()) {
+            held.live?.abort();
+            if (held.pumping !== null)
+                settling.push(held.pumping.catch(() => { }));
+        }
+        if (settling.length > 0 && graceMs > 0) {
+            let timer;
+            await Promise.race([Promise.all(settling), new Promise((resolve) => {
+                    timer = setTimeout(resolve, graceMs);
+                })]);
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+        this.#held.clear();
+        this.#opening.clear();
+    }
+}
+export function createSessionService(options) {
+    return new SessionService(options);
+}

package/dist/tail.d.ts

@@ -0,0 +1,18 @@
+import type { Event } from "@vincemakes/kiso-core";
+export type Listener = (event: Event) => void;
+/**
+ * Replay-then-live, exact by sequence number.
+ *
+ * The reconnect guarantee: a subscriber that names the last seq it saw
+ * receives every event after it exactly once — the ones already on disk
+ * (persist-first: every event is written before a run yields it) and the
+ * ones the live run emits from now on, in order, with no duplicate at the
+ * seam. The seam is the only hard part: an event the run emits WHILE the
+ * replay is being read must neither be lost nor sent twice. It is
+ * buffered until the replay ends, then sent only if its seq is beyond
+ * what the replay covered.
+ *
+ * Both hosting products wrote this function independently, flag names
+ * included. It is one function now.
+ */
+export declare function tail(replay: () => Iterable<Event>, listeners: Set<Listener>, after: number, send: Listener): () => void;

package/dist/tail.js

@@ -0,0 +1,47 @@
+/**
+ * Replay-then-live, exact by sequence number.
+ *
+ * The reconnect guarantee: a subscriber that names the last seq it saw
+ * receives every event after it exactly once — the ones already on disk
+ * (persist-first: every event is written before a run yields it) and the
+ * ones the live run emits from now on, in order, with no duplicate at the
+ * seam. The seam is the only hard part: an event the run emits WHILE the
+ * replay is being read must neither be lost nor sent twice. It is
+ * buffered until the replay ends, then sent only if its seq is beyond
+ * what the replay covered.
+ *
+ * Both hosting products wrote this function independently, flag names
+ * included. It is one function now.
+ */
+export function tail(replay, listeners, after, send) {
+    let sentUpTo = after;
+    const buffered = [];
+    let replaying = true;
+    const listener = (event) => {
+        if (replaying) {
+            buffered.push(event);
+            return;
+        }
+        if (event.seq <= sentUpTo)
+            return;
+        sentUpTo = event.seq;
+        send(event);
+    };
+    listeners.add(listener);
+    for (const event of replay()) {
+        if (event.seq <= sentUpTo)
+            continue;
+        sentUpTo = event.seq;
+        send(event);
+    }
+    replaying = false;
+    for (const event of buffered) {
+        if (event.seq <= sentUpTo)
+            continue;
+        sentUpTo = event.seq;
+        send(event);
+    }
+    return () => {
+        listeners.delete(listener);
+    };
+}

package/dist/wire.d.ts

@@ -0,0 +1,29 @@
+import type { Event } from "@vincemakes/kiso-core";
+import { type WireEvent } from "@vincemakes/kiso-protocol";
+/**
+ * The projection: durable Event → WireEvent | null.
+ *
+ * Pure, total over the union: a type not in DURABLE_TO_WIRE yields null; a
+ * type on the wire yields exactly the allowlisted fields that are present
+ * (never undefined), with tool arguments passed through `sanitize`. The
+ * allowlist is data in the protocol package; nothing here can add a field
+ * the protocol did not name.
+ */
+export interface ProjectionOptions {
+    /** Reasoning text on the wire — OFF unless a product asks (every hosting
+     *  product shipped a "thinking leaks" fix once). */
+    readonly exposeThinking?: boolean;
+    /** Replaces the default tool-argument sanitizer. */
+    readonly sanitize?: (input: unknown) => unknown;
+}
+/** Argument keys that carry prose the client has no business seeing in a
+ *  tool card (the model's own prompt to a generator, a document body).
+ *  uooki's list, verbatim. */
+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;
+export declare function toWireEvent(event: Event, options?: ProjectionOptions): WireEvent | null;

package/dist/wire.js

@@ -0,0 +1,40 @@
+import { DURABLE_TO_WIRE, SANITIZED_FIELDS, WIRE_FIELDS } from "@vincemakes/kiso-protocol";
+/** Argument keys that carry prose the client has no business seeing in a
+ *  tool card (the model's own prompt to a generator, a document body).
+ *  uooki's list, verbatim. */
+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))
+        return input;
+    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;
+    }
+    return out;
+}
+export function toWireEvent(event, options = {}) {
+    const wireType = DURABLE_TO_WIRE[event.type];
+    if (wireType === undefined)
+        return null;
+    if (wireType === "thinking" && options.exposeThinking !== true)
+        return null;
+    const sanitize = options.sanitize ?? sanitizeToolArgs;
+    const source = event;
+    const projected = { seq: event.seq, type: wireType };
+    for (const field of WIRE_FIELDS[wireType]) {
+        if (!(field in source))
+            continue;
+        const value = source[field];
+        if (value === undefined)
+            continue;
+        projected[field] = SANITIZED_FIELDS.has(field) ? sanitize(value) : value;
+    }
+    return projected;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@vincemakes/kiso-server",
+	"version": "0.41.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",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./http": {
+			"types": "./dist/http.d.ts",
+			"default": "./dist/http.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"typecheck": "tsc -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@vincemakes/kiso-core": "0.41.0",
+		"@vincemakes/kiso-protocol": "0.41.0",
+		"@vincemakes/kiso-runtime": "0.41.0"
+	},
+	"devDependencies": {
+		"@vincemakes/kiso-evals": "0.41.0",
+		"@types/node": "^26.1.2",
+		"typescript": "^5.7.2",
+		"vitest": "^3.0.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/vincemakes/kiso.git",
+		"directory": "packages/server"
+	},
+	"bugs": {
+		"url": "https://github.com/vincemakes/kiso/issues"
+	},
+	"homepage": "https://github.com/vincemakes/kiso/tree/main/packages/server#readme"
+}