@vincemakes/kiso-server 0.44.0 → 0.45.1

package/README.md

@@ -23,6 +23,7 @@ const service = createSessionService({
 
 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
+service.steer("s1", "only the editor tests");                 // → { runId } — NotRunningError | RunClosedError: run() it instead
 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 }
@@ -42,6 +43,13 @@ await service.close(5_000);                              // abort what is live,
   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.
+- **Steer, and what never landed** (ADR-0057). `steer()` hands the live
+  run a person's input; the run admits it at its next quiescent boundary.
+  With no run live it refuses (`NotRunningError`); once the run has
+  decided to end, the runtime refuses (`RunClosedError`). Input accepted
+  and never admitted is on `SettledRun.unadmitted`, and the HTTP stream
+  names it in an `unadmitted` frame after the terminal; the service never
+  starts the follow-up run itself — the host does, usually with it.
 - **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

package/dist/errors.d.ts

@@ -32,3 +32,9 @@ export declare class StoreMismatchError extends Error {
 export declare class DrainingError extends Error {
     constructor();
 }
+/** ADR-0057: a steer for a session with no run in flight. The host starts a
+ *  run with the input instead. */
+export declare class NotRunningError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}

package/dist/errors.js

@@ -50,3 +50,13 @@ export class DrainingError extends Error {
         this.name = "DrainingError";
     }
 }
+/** ADR-0057: a steer for a session with no run in flight. The host starts a
+ *  run with the input instead. */
+export class NotRunningError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`session ${sessionId} has no run in flight — start a run with this input`);
+        this.name = "NotRunningError";
+        this.sessionId = sessionId;
+    }
+}

package/dist/http.d.ts

@@ -17,6 +17,7 @@ import { type ProjectionOptions } from "./wire.js";
  *   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/steer      202 { runId } — 409 idle | closed (ADR-0057)
  *   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 }

package/dist/http.js

@@ -1,11 +1,12 @@
-import { DrainingError, InFlightError, OpenRunError } from "./errors.js";
+import { RunClosedError } from "@vincemakes/kiso-runtime";
+import { DrainingError, InFlightError, NotRunningError, OpenRunError } from "./errors.js";
 import { toWireEvent } from "./wire.js";
 /** 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"]);
+const ACTIONS = new Set(["", "state", "events", "replay", "run", "resume", "steer", "abort", "approve", "uncertain"]);
 export function createHttpHandler(service, options) {
     const prefix = (options.prefix ?? "/v1/sessions").replace(/\/+$/, "");
     const keepaliveMs = options.keepaliveMs ?? 15_000;
@@ -27,6 +28,10 @@ export function createHttpHandler(service, options) {
             return fail(res, 409, "open_run", err.message, err.runId);
         if (err instanceof DrainingError)
             return fail(res, 503, "draining", err.message);
+        if (err instanceof NotRunningError)
+            return fail(res, 409, "idle", err.message);
+        if (err instanceof RunClosedError)
+            return fail(res, 409, "closed", err.message, err.runId);
         if (err instanceof BadRequest)
             return fail(res, 400, "bad_request", err.message);
         fail(res, 500, "internal", err instanceof Error ? err.message : String(err));
@@ -84,6 +89,13 @@ export function createHttpHandler(service, options) {
         const wire = toWireEvent(event, projection);
         if (wire !== null)
             out += `id: ${wire.seq}\nevent: ${wire.type}\ndata: ${JSON.stringify(wire)}\n\n`;
+        // ADR-0057: a 202 steer always has a visible fate — admitted (its
+        // user_input is on the stream) or named here, right after the terminal.
+        if (event.type === "terminal") {
+            const left = service.unadmittedAt(sessionId, event.seq);
+            if (left !== null)
+                out += `event: unadmitted\ndata: ${JSON.stringify(left)}\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`;
@@ -219,6 +231,13 @@ export function createHttpHandler(service, options) {
                     json(res, 202, { runId: handle.runId });
                 return true;
             }
+            if (action === "steer") {
+                const input = await inputOf(body, req, sessionId, res);
+                if (isHandled(input))
+                    return true; // the product answered; nothing steered
+                json(res, 202, service.steer(sessionId, input));
+                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;

package/dist/index.d.ts

@@ -8,7 +8,7 @@
  */
 export { createSessionService, SessionService } from "./service.js";
 export type { AbortOutcome, DrainReport, OpenRun, RunHandle, RunOptions, SessionServiceOptions, SettledRun } from "./service.js";
-export { DrainingError, InFlightError, OpenRunError, StoreMismatchError } from "./errors.js";
+export { DrainingError, InFlightError, NotRunningError, OpenRunError, StoreMismatchError } from "./errors.js";
 export { EXECUTION_ENDED, executionDelta } from "./execution.js";
 export { tail } from "./tail.js";
 export { MAX_ARG_DEPTH, MAX_ARG_VALUE_CHARS, STRIPPED_ARG_KEYS, sanitizeToolArgs, toWireEvent } from "./wire.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, StoreMismatchError } from "./errors.js";
+export { DrainingError, InFlightError, NotRunningError, OpenRunError, StoreMismatchError } from "./errors.js";
 export { EXECUTION_ENDED, executionDelta } from "./execution.js";
 export { tail } from "./tail.js";
 export { MAX_ARG_DEPTH, MAX_ARG_VALUE_CHARS, STRIPPED_ARG_KEYS, sanitizeToolArgs, toWireEvent } from "./wire.js";

package/dist/service.d.ts

@@ -67,6 +67,9 @@ export interface SettledRun {
     readonly uncertainRemaining: number;
     /** The highest seq this run delivered. */
     readonly highWater: number;
+    /** ADR-0057: input a steer handed this run that it never admitted — the
+     *  run sealed first. The host's "what next" is usually a new run with it. */
+    readonly unadmitted: readonly (string | readonly ContentBlock[])[];
 }
 export interface RunHandle {
     readonly runId: string;
@@ -116,6 +119,20 @@ export declare class SessionService {
      *  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>;
+    /** ADR-0057 — hand the session's live run a person's input; it is
+     *  admitted at the run's next Safe Admission boundary. Refuses with
+     *  `NotRunningError` when no run is live, and with the runtime's
+     *  `RunClosedError` once the run's ingress has sealed — either way the
+     *  host starts a new run with the input. */
+    steer(sessionId: string, input: string | readonly ContentBlock[]): {
+        readonly runId: string;
+    };
+    /** ADR-0057 — what the run that ended at `terminalSeq` accepted and never
+     *  admitted; null when nothing, or when that is not the latest terminal. */
+    unadmittedAt(sessionId: string, terminalSeq: number): {
+        readonly runId: string;
+        readonly items: readonly (string | readonly ContentBlock[])[];
+    } | null;
     /** Start a turn. Refuses with `InFlightError` (one run per session),
      *  `OpenRunError` (a previous process died inside a run — see
      *  `resumeFirst`) or `DrainingError`. */

package/dist/service.js

@@ -1,5 +1,5 @@
 import { openRunId } from "@vincemakes/kiso-runtime/internal";
-import { DrainingError, InFlightError, OpenRunError, StoreMismatchError } from "./errors.js";
+import { DrainingError, InFlightError, NotRunningError, 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, mismatch: null };
+            const held = { id: sessionId, agent, session, listeners: new Set(), live: null, pumping: null, executing: 0, highWater: -1, mismatch: null, unadmitted: null };
             this.#held.set(sessionId, held);
             return held;
         })();
@@ -54,6 +54,10 @@ export class SessionService {
         const pumping = (async () => {
             try {
                 for await (const event of run) {
+                    // ADR-0057: the ingress sealed before the terminal was appended,
+                    // so what never landed is known by the time it is delivered.
+                    if (event.type === "terminal")
+                        held.unadmitted = { runId: run.runId, terminalSeq: event.seq, items: run.unadmitted() };
                     held.executing = Math.max(0, held.executing + executionDelta(event));
                     held.highWater = Math.max(held.highWater, event.seq);
                     for (const listener of [...held.listeners]) {
@@ -89,6 +93,7 @@ export class SessionService {
                     outcome: terminal !== undefined && terminal.type === "terminal" ? terminal.outcome.kind : "unknown",
                     uncertainRemaining: held.session.uncertainExecutions().length,
                     highWater: held.highWater,
+                    unadmitted: run.unadmitted(),
                 });
             }
         })();
@@ -96,6 +101,24 @@ export class SessionService {
         void pumping.catch(() => { }); // a host that does not await `done` gets no unhandled rejection
         return { runId: run.runId, done: pumping };
     }
+    /** ADR-0057 — hand the session's live run a person's input; it is
+     *  admitted at the run's next Safe Admission boundary. Refuses with
+     *  `NotRunningError` when no run is live, and with the runtime's
+     *  `RunClosedError` once the run's ingress has sealed — either way the
+     *  host starts a new run with the input. */
+    steer(sessionId, input) {
+        const live = this.#held.get(sessionId)?.live ?? null;
+        if (live === null)
+            throw new NotRunningError(sessionId);
+        live.steer(input);
+        return { runId: live.runId };
+    }
+    /** ADR-0057 — what the run that ended at `terminalSeq` accepted and never
+     *  admitted; null when nothing, or when that is not the latest terminal. */
+    unadmittedAt(sessionId, terminalSeq) {
+        const u = this.#held.get(sessionId)?.unadmitted ?? null;
+        return u !== null && u.terminalSeq === terminalSeq && u.items.length > 0 ? { runId: u.runId, items: u.items } : null;
+    }
     /** Start a turn. Refuses with `InFlightError` (one run per session),
      *  `OpenRunError` (a previous process died inside a run — see
      *  `resumeFirst`) or `DrainingError`. */

package/package.json

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