@vincemakes/kiso-client 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,30 @@
+# @vincemakes/kiso-client
+
+The typed client for a hosted kiso session, over the wire protocol. Run,
+resume, abort, approve, the snapshot, and a stream that reconnects with
+`Last-Event-ID` and never yields an event twice. Browser and Node: global
+`fetch`, no EventSource (it cannot send headers), and nothing from the
+runtime — this package depends on `@vincemakes/kiso-protocol` alone.
+
+```ts
+import { createClient } from "@vincemakes/kiso-client";
+
+const client = createClient({ baseUrl: "https://api.example.com/v1/sessions", headers: () => ({ authorization: `Bearer ${token}` }) });
+const session = client.session("s1");
+
+const { runId } = await session.run("hello");            // ClientError on in_flight / open_run / draining / forbidden
+for await (const ev of session.events({ after: -1, until: (e) => e.kind === "event" && e.event.type === "terminal" })) {
+  if (ev.kind === "event") render(ev.event);              // a WireEvent under its seq
+  else if (ev.event === "billing") bill(ev.data);         // a product frame beside it
+}
+const outcome = await session.abort();                    // idle | parked (a reply, not an error) | stopped
+await session.approve(decisionId, true);                  // → { needsResume }
+```
+
+`events()` keeps the stream alive: a dropped connection reconnects with
+the last seq it delivered, with exponential backoff, and the seam is
+deduplicated by seq — the transport's replay-from-seq guarantee,
+consumed. `runStream()` is one turn on one response (`/run?stream=1`)
+with no reconnect; a dropped connection there is the cue to `events()`.
+
+See the repository README for the framework overview.

package/dist/client.d.ts

@@ -0,0 +1,90 @@
+import type { AbortReply, ApproveReply, ResolveUncertainReply, RunReply, SessionState, WireError, WireErrorCode, WireEvent, WireInput, WireSource } from "@vincemakes/kiso-protocol";
+/**
+ * The typed client for a hosted kiso session, over the wire protocol.
+ *
+ * It knows the routes the transport answers under a prefix, the one error
+ * shape, and how to keep a stream alive: `events()` reconnects with the
+ * last seq it delivered as `Last-Event-ID`, so a client that loses its
+ * connection mid-run picks up exactly where it was — the transport's
+ * replay-from-seq guarantee, consumed. Browser and Node: global `fetch`,
+ * no EventSource, nothing from the runtime.
+ */
+export interface ClientOptions {
+    /** The mount point, e.g. `https://api.example.com/v1/sessions`. */
+    readonly baseUrl: string;
+    /** Per-request headers — the host's auth. Called on every request. */
+    readonly headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Injected for tests or non-global environments. Default: globalThis.fetch. */
+    readonly fetch?: typeof fetch;
+    /** Reconnect backoff for `events()`: first wait and cap, in ms. */
+    readonly reconnect?: {
+        readonly initialMs?: number;
+        readonly maxMs?: number;
+    };
+}
+/** A non-2xx reply, carrying the wire's error shape. */
+export declare class ClientError extends Error {
+    readonly status: number;
+    readonly code: WireErrorCode;
+    readonly runId: string | undefined;
+    constructor(status: number, error: WireError);
+}
+/** What `events()` yields: a wire event under its seq, or a product frame beside one. */
+export type ClientEvent = {
+    readonly kind: "event";
+    readonly event: WireEvent;
+} | {
+    readonly kind: "frame";
+    readonly event: string;
+    readonly data: unknown;
+};
+export interface EventsOptions {
+    /** The last seq already seen; −1 (the default) for everything. */
+    readonly after?: number;
+    /** Stop the stream. */
+    readonly signal?: AbortSignal;
+    /** End the stream after this event (e.g. the terminal) — otherwise it
+     *  stays open, reconnecting, until the signal fires. */
+    readonly until?: (event: ClientEvent) => boolean;
+    /** Called before each reconnect with the attempt number and the wait. */
+    readonly onReconnect?: (attempt: number, waitMs: number) => void;
+}
+export interface RunStreamOptions extends Omit<EventsOptions, "until"> {
+    readonly source?: WireSource;
+    readonly resumeFirst?: boolean;
+}
+export declare class SessionClient {
+    #private;
+    readonly id: string;
+    constructor(options: ClientOptions, sessionId: string);
+    /** Start a turn; refusals arrive as ClientError (in_flight, open_run, draining, forbidden). */
+    run(input: WireInput, options?: {
+        source?: WireSource;
+        resumeFirst?: boolean;
+    }): Promise<RunReply>;
+    resume(): Promise<RunReply>;
+    /** Stop the run in flight. A parked run is a REPLY (kind "parked"), not an error. */
+    abort(options?: {
+        force?: boolean;
+    }): Promise<AbortReply>;
+    approve(decisionId: string, allow: boolean, reason?: string): Promise<ApproveReply>;
+    resolveUncertain(executionId: string, resolution: "rerun" | "abandoned"): Promise<ResolveUncertainReply>;
+    state(): Promise<SessionState>;
+    replay(): Promise<{
+        readonly events: readonly WireEvent[];
+        readonly state: SessionState;
+    }>;
+    /** One turn on one response (`/run?stream=1`): its events, then the end.
+     *  No reconnect — a dropped connection is the caller's cue to `events()`. */
+    runStream(input: WireInput, options?: RunStreamOptions): AsyncGenerator<ClientEvent, void, undefined>;
+    /** Every event after `after`, live, reconnecting with `Last-Event-ID` on
+     *  a dropped connection and never yielding a seq twice. Runs until the
+     *  signal fires or `until` says so. */
+    events(options?: EventsOptions): AsyncGenerator<ClientEvent, void, undefined>;
+}
+export declare class KisoClient {
+    #private;
+    constructor(options: ClientOptions);
+    session(sessionId: string): SessionClient;
+}
+export declare function createClient(options: ClientOptions): KisoClient;

package/dist/client.js

@@ -0,0 +1,189 @@
+import { readSse } from "./sse.js";
+/** A non-2xx reply, carrying the wire's error shape. */
+export class ClientError extends Error {
+    status;
+    code;
+    runId;
+    constructor(status, error) {
+        super(error.message);
+        this.name = "ClientError";
+        this.status = status;
+        this.code = error.code;
+        this.runId = error.runId;
+    }
+}
+export class SessionClient {
+    #options;
+    id;
+    constructor(options, sessionId) {
+        this.#options = options;
+        this.id = sessionId;
+    }
+    #url(action, query) {
+        const base = `${this.#options.baseUrl.replace(/\/+$/, "")}/${encodeURIComponent(this.id)}${action === "" ? "" : `/${action}`}`;
+        if (query === undefined || Object.keys(query).length === 0)
+            return base;
+        return `${base}?${new URLSearchParams(query).toString()}`;
+    }
+    async #request(method, action, body, extra = {}) {
+        const doFetch = this.#options.fetch ?? globalThis.fetch;
+        const headers = { ...(await this.#options.headers?.()), ...extra.headers };
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        return doFetch(this.#url(action, extra.query), {
+            method,
+            headers,
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            ...(extra.signal !== undefined ? { signal: extra.signal } : {}),
+        });
+    }
+    async #json(res, okStatuses = [200, 202]) {
+        const text = await res.text();
+        let parsed = null;
+        try {
+            parsed = text === "" ? null : JSON.parse(text);
+        }
+        catch {
+            parsed = null;
+        }
+        if (okStatuses.includes(res.status))
+            return parsed;
+        const error = isWireError(parsed) ? parsed : { code: "internal", message: text || `HTTP ${res.status}` };
+        throw new ClientError(res.status, error);
+    }
+    /** Start a turn; refusals arrive as ClientError (in_flight, open_run, draining, forbidden). */
+    async run(input, options = {}) {
+        return this.#json(await this.#request("POST", "run", { input, ...options }));
+    }
+    async resume() {
+        return this.#json(await this.#request("POST", "resume", {}));
+    }
+    /** Stop the run in flight. A parked run is a REPLY (kind "parked"), not an error. */
+    async abort(options = {}) {
+        return this.#json(await this.#request("POST", "abort", options), [200, 409]);
+    }
+    async approve(decisionId, allow, reason) {
+        return this.#json(await this.#request("POST", "approve", { decisionId, allow, ...(reason !== undefined ? { reason } : {}) }));
+    }
+    async resolveUncertain(executionId, resolution) {
+        return this.#json(await this.#request("POST", "uncertain", { executionId, resolution }));
+    }
+    async state() {
+        return this.#json(await this.#request("GET", "state"));
+    }
+    async replay() {
+        return this.#json(await this.#request("GET", "replay"));
+    }
+    /** One turn on one response (`/run?stream=1`): its events, then the end.
+     *  No reconnect — a dropped connection is the caller's cue to `events()`. */
+    async *runStream(input, options = {}) {
+        const { source, resumeFirst, after, signal } = options;
+        const res = await this.#request("POST", "run", { input, ...(source !== undefined ? { source } : {}), ...(resumeFirst !== undefined ? { resumeFirst } : {}), after: after ?? -1 }, { query: { stream: "1" }, ...(signal !== undefined ? { signal } : {}) });
+        if (res.status !== 200 || res.body === null)
+            await this.#json(res, []); // throws the wire error
+        for await (const frame of readSse(res.body)) {
+            const ev = toClientEvent(frame);
+            if (ev !== null)
+                yield ev;
+        }
+    }
+    /** Every event after `after`, live, reconnecting with `Last-Event-ID` on
+     *  a dropped connection and never yielding a seq twice. Runs until the
+     *  signal fires or `until` says so. */
+    async *events(options = {}) {
+        let lastSeq = options.after ?? -1;
+        let attempt = 0;
+        const initial = this.#options.reconnect?.initialMs ?? 250;
+        const cap = this.#options.reconnect?.maxMs ?? 5_000;
+        for (;;) {
+            if (options.signal?.aborted)
+                return;
+            let res;
+            try {
+                res = await this.#request("GET", "events", undefined, {
+                    headers: { accept: "text/event-stream", "last-event-id": String(lastSeq) },
+                    ...(options.signal !== undefined ? { signal: options.signal } : {}),
+                });
+            }
+            catch (err) {
+                if (options.signal?.aborted)
+                    return;
+                res = null;
+                void err;
+            }
+            if (res !== null) {
+                if (res.status !== 200 || res.body === null)
+                    await this.#json(res, []); // a refusal is final: forbidden, not_found
+                attempt = 0;
+                try {
+                    for await (const frame of readSse(res.body)) {
+                        if (options.signal?.aborted)
+                            return;
+                        const ev = toClientEvent(frame);
+                        if (ev === null)
+                            continue;
+                        if (ev.kind === "event") {
+                            if (ev.event.seq <= lastSeq)
+                                continue; // the seam: never twice
+                            lastSeq = ev.event.seq;
+                        }
+                        yield ev;
+                        if (options.until?.(ev) === true)
+                            return;
+                    }
+                }
+                catch {
+                    // the connection dropped mid-stream — fall through to reconnect
+                }
+            }
+            if (options.signal?.aborted)
+                return;
+            attempt += 1;
+            const wait = Math.min(cap, initial * 2 ** (attempt - 1));
+            options.onReconnect?.(attempt, wait);
+            await sleep(wait, options.signal);
+        }
+    }
+}
+export class KisoClient {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    session(sessionId) {
+        return new SessionClient(this.#options, sessionId);
+    }
+}
+export function createClient(options) {
+    return new KisoClient(options);
+}
+function toClientEvent(frame) {
+    if (frame.data === undefined)
+        return null; // a comment: open / keepalive
+    let data;
+    try {
+        data = JSON.parse(frame.data);
+    }
+    catch {
+        return null;
+    }
+    if (frame.id !== undefined)
+        return { kind: "event", event: data };
+    return { kind: "frame", event: frame.event ?? "message", data };
+}
+function isWireError(value) {
+    return typeof value === "object" && value !== null && typeof value.code === "string" && typeof value.message === "string";
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @vincemakes/kiso-client — the typed client for a hosted kiso session.
+ *
+ * Over the wire protocol only: run, resume, abort, approve, the snapshot,
+ * and a stream that reconnects with Last-Event-ID and never repeats an
+ * event. Browser and Node; depends on `@vincemakes/kiso-protocol` alone.
+ */
+export { ClientError, createClient, KisoClient, SessionClient } from "./client.js";
+export type { ClientEvent, ClientOptions, EventsOptions, RunStreamOptions } from "./client.js";
+export { parseSseBlock, readSse } from "./sse.js";
+export type { SseFrame } from "./sse.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @vincemakes/kiso-client — the typed client for a hosted kiso session.
+ *
+ * Over the wire protocol only: run, resume, abort, approve, the snapshot,
+ * and a stream that reconnects with Last-Event-ID and never repeats an
+ * event. Browser and Node; depends on `@vincemakes/kiso-protocol` alone.
+ */
+export { ClientError, createClient, KisoClient, SessionClient } from "./client.js";
+export { parseSseBlock, readSse } from "./sse.js";

package/dist/sse.d.ts

@@ -0,0 +1,19 @@
+/**
+ * An incremental Server-Sent Events parser over a byte stream.
+ *
+ * Standards-shaped and small: frames are separated by a blank line; `id:`,
+ * `event:` and `data:` lines are read (multi-line data joins with "\n");
+ * comment lines (`:`) are reported as keepalives so a consumer can tell a
+ * quiet stream from a dead one. No EventSource: a fetch-based reader can
+ * send `Last-Event-ID` as a header, which the browser API cannot.
+ */
+export interface SseFrame {
+    readonly id?: string;
+    readonly event?: string;
+    readonly data?: string;
+    /** A comment line — the transport's `: open` / `: keepalive`. */
+    readonly comment?: string;
+}
+export declare function parseSseBlock(block: string): SseFrame | null;
+/** Read a body as SSE frames, as they complete. Ends when the body ends. */
+export declare function readSse(body: ReadableStream<Uint8Array>): AsyncGenerator<SseFrame, void, undefined>;

package/dist/sse.js

@@ -0,0 +1,74 @@
+/**
+ * An incremental Server-Sent Events parser over a byte stream.
+ *
+ * Standards-shaped and small: frames are separated by a blank line; `id:`,
+ * `event:` and `data:` lines are read (multi-line data joins with "\n");
+ * comment lines (`:`) are reported as keepalives so a consumer can tell a
+ * quiet stream from a dead one. No EventSource: a fetch-based reader can
+ * send `Last-Event-ID` as a header, which the browser API cannot.
+ */
+export function parseSseBlock(block) {
+    let id;
+    let event;
+    const data = [];
+    let comment;
+    for (const raw of block.split("\n")) {
+        const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (line === "")
+            continue;
+        if (line.startsWith(":")) {
+            comment = line.slice(1).trim();
+            continue;
+        }
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "id")
+            id = value;
+        else if (field === "event")
+            event = value;
+        else if (field === "data")
+            data.push(value);
+    }
+    if (id === undefined && event === undefined && data.length === 0 && comment === undefined)
+        return null;
+    return {
+        ...(id !== undefined ? { id } : {}),
+        ...(event !== undefined ? { event } : {}),
+        ...(data.length > 0 ? { data: data.join("\n") } : {}),
+        ...(comment !== undefined ? { comment } : {}),
+    };
+}
+/** Read a body as SSE frames, as they complete. Ends when the body ends. */
+export async function* readSse(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            // CRLF is normalised on the whole buffer so a "\r" that ends one
+            // chunk meets its "\n" from the next before the split
+            buffer = (buffer + decoder.decode(value, { stream: true })).replace(/\r\n/g, "\n");
+            let boundary = buffer.indexOf("\n\n");
+            while (boundary !== -1) {
+                const block = buffer.slice(0, boundary);
+                buffer = buffer.slice(boundary + 2);
+                const frame = parseSseBlock(block);
+                if (frame !== null)
+                    yield frame;
+                boundary = buffer.indexOf("\n\n");
+            }
+        }
+        const last = parseSseBlock(buffer);
+        if (last !== null)
+            yield last;
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@vincemakes/kiso-client",
+	"version": "0.41.0",
+	"description": "kiso client — the typed client for a hosted kiso session over the wire protocol: run, resume, abort, approve, the snapshot, and a stream that reconnects with Last-Event-ID and never repeats an event. Browser and Node; depends on the protocol package only.",
+	"type": "module",
+	"license": "MIT",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"typecheck": "tsc -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@vincemakes/kiso-protocol": "0.41.0"
+	},
+	"devDependencies": {
+		"@vincemakes/kiso-core": "0.41.0",
+		"@vincemakes/kiso-evals": "0.41.0",
+		"@vincemakes/kiso-runtime": "0.41.0",
+		"@vincemakes/kiso-server": "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/client"
+	},
+	"bugs": {
+		"url": "https://github.com/vincemakes/kiso/issues"
+	},
+	"homepage": "https://github.com/vincemakes/kiso/tree/main/packages/client#readme"
+}