@nylorun/runtime 0.4.0-beta → 0.5.0-beta

package/dist/sessions/host.d.ts

@@ -0,0 +1,29 @@
+import type { BuiltAgent, ExecutionInput, ModelAdapter, RunResult } from "@nylorun/harness";
+import type { CanonicalEvent, SessionStore, StoredSession, SessionSummary } from "./store.js";
+export interface SubmitOptions {
+    readonly runId?: string;
+    readonly info?: unknown;
+    readonly signal?: AbortSignal;
+    readonly onModelCall: ModelAdapter;
+    readonly secrets?: readonly string[];
+    readonly onEvent?: (event: CanonicalEvent) => void;
+    readonly started?: Record<string, unknown>;
+}
+/** The built-in single-process coordinator. Storage adapters do not implement execution. */
+export declare class SessionHost {
+    readonly store: SessionStore;
+    private readonly queues;
+    private readonly generations;
+    private readonly active;
+    private readonly listeners;
+    private closed;
+    constructor(store: SessionStore);
+    private key;
+    read(agentId: string, sessionId: string): Promise<StoredSession | undefined>;
+    list(agentId: string): Promise<readonly SessionSummary[]>;
+    subscribe(agentId: string, sessionId: string, listener: (event: CanonicalEvent) => void): () => void;
+    submit(agent: BuiltAgent<any, any>, sessionId: string, input: ExecutionInput, options: SubmitOptions): Promise<RunResult<any>>;
+    cancel(agent: BuiltAgent<any, any>, sessionId: string): Promise<void>;
+    interrupt(agent: BuiltAgent<any, any>, sessionId: string, input: ExecutionInput, options: SubmitOptions): Promise<RunResult<any>>;
+    close(): Promise<void>;
+}

package/dist/sessions/host.js

@@ -0,0 +1,291 @@
+import { isHarnessError } from "@nylorun/harness";
+import { scrub } from "../redact.js";
+/** The built-in single-process coordinator. Storage adapters do not implement execution. */
+export class SessionHost {
+    store;
+    queues = new Map();
+    generations = new Map();
+    active = new Map();
+    listeners = new Map();
+    closed = false;
+    constructor(store) {
+        this.store = store;
+    }
+    key(agentId, sessionId) {
+        return JSON.stringify([agentId, sessionId]);
+    }
+    async read(agentId, sessionId) {
+        const document = await this.store.get(agentId, sessionId);
+        if (document?.active && !this.active.has(this.key(agentId, sessionId)))
+            return { ...document, status: "interrupted" };
+        return document;
+    }
+    async list(agentId) {
+        return (await this.store.list(agentId)).map((session) => session.status === "running" &&
+            !this.active.has(this.key(agentId, session.session))
+            ? { ...session, status: "interrupted" }
+            : session);
+    }
+    subscribe(agentId, sessionId, listener) {
+        const key = this.key(agentId, sessionId);
+        let listeners = this.listeners.get(key);
+        if (!listeners) {
+            listeners = new Set();
+            this.listeners.set(key, listeners);
+        }
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+            if (!listeners.size)
+                this.listeners.delete(key);
+        };
+    }
+    submit(agent, sessionId, input, options) {
+        const key = this.key(agent.id, sessionId);
+        const generation = this.generations.get(key) ?? 0;
+        const prior = this.queues.get(key) ?? Promise.resolve();
+        const work = prior
+            .catch(() => { })
+            .then(async () => {
+            if ((this.generations.get(key) ?? 0) !== generation)
+                throw new Error("Queued input cancelled by interruption");
+            if (this.closed)
+                throw new Error("Runtime is closed");
+            options.signal?.throwIfAborted();
+            const stored = await this.store.get(agent.id, sessionId);
+            // Cancellation/shutdown can arrive while an asynchronous store is loading.
+            if ((this.generations.get(key) ?? 0) !== generation)
+                throw new Error("Queued input cancelled by interruption");
+            if (this.closed)
+                throw new Error("Runtime is closed");
+            options.signal?.throwIfAborted();
+            if (stored?.active ||
+                stored?.status === "interrupted" ||
+                stored?.status === "archived")
+                throw new Error("This session is interrupted or archived. Reconcile external effects or start a new session.");
+            const controller = new AbortController();
+            this.active.set(key, controller);
+            const abort = () => controller.abort(options.signal?.reason);
+            options.signal?.addEventListener("abort", abort, { once: true });
+            if (options.signal?.aborted)
+                abort();
+            const now = Date.now();
+            const runId = options.runId ?? crypto.randomUUID();
+            let document = stored ?? {
+                version: 1,
+                id: sessionId,
+                agentId: agent.id,
+                status: "running",
+                startedAt: now,
+                updatedAt: now,
+                events: [],
+            };
+            const title = typeof input === "string"
+                ? input
+                : "text" in input
+                    ? input.text
+                    : "content" in input
+                        ? input.content
+                            .filter((part) => part.type === "text")
+                            .map((part) => part.text)
+                            .join(" ")
+                        : undefined;
+            const events = [...document.events];
+            let sequence = events.at(-1)?.seq ?? 0;
+            const add = (type, payload, publish = true) => {
+                const event = {
+                    session: sessionId,
+                    seq: ++sequence,
+                    ts: new Date().toISOString(),
+                    type,
+                    payload: scrub({ ...payload, runId }, options.secrets ?? []),
+                };
+                events.push(event);
+                if (publish)
+                    publishEvent(event);
+                return event;
+            };
+            const publishEvent = (event) => {
+                for (const listener of [
+                    options.onEvent,
+                    ...(this.listeners.get(key) ?? []),
+                ]) {
+                    try {
+                        listener?.(event);
+                    }
+                    catch {
+                        /* Delivery cannot acknowledge or block persistence. */
+                    }
+                }
+            };
+            const save = async () => {
+                document = {
+                    ...document,
+                    updatedAt: Date.now(),
+                    events: [...events],
+                };
+                await this.store.put(agent.id, sessionId, document);
+            };
+            try {
+                document = {
+                    ...document,
+                    status: "running",
+                    active: { runId, input },
+                    ...(document.title === undefined && title
+                        ? { title: title.slice(0, 120) }
+                        : {}),
+                };
+                add("session.run.started", options.started ?? {
+                    input_kind: typeof input === "string"
+                        ? "user-message"
+                        : "kind" in input
+                            ? input.kind
+                            : "user-message",
+                    ...(typeof input === "string" ? { input } : {}),
+                });
+                await save();
+                const result = await agent.run({
+                    state: document.state,
+                    input,
+                    info: options.info,
+                    signal: controller.signal,
+                    onModelCall: options.onModelCall,
+                    onEvent: (event) => {
+                        add(event.type, event);
+                    },
+                    record: async (state) => {
+                        document = { ...document, state };
+                        await save();
+                    },
+                });
+                const { active: _, ...rest } = document;
+                document = {
+                    ...rest,
+                    state: result.state,
+                    status: result.status === "paused" ? "waiting" : result.status,
+                };
+                const terminal = result.status === "completed"
+                    ? add("final", { output: result.output }, false)
+                    : result.status === "paused"
+                        ? add("interaction.required", {
+                            pending: result.pending,
+                            ...(result.pending.find((item) => item.interaction)
+                                ?.interaction
+                                ? {
+                                    interaction: result.pending.find((item) => item.interaction).interaction,
+                                }
+                                : {}),
+                        }, false)
+                        : add(result.status === "failed" ? "error" : "cancelled", result.status === "failed" ? { ...result.error } : {}, false);
+                await save();
+                publishEvent(terminal);
+                return result;
+            }
+            catch (error) {
+                if (isHarnessError(error) &&
+                    [
+                        "execution.invalid-input",
+                        "execution.invalid-state",
+                        "execution.incompatible",
+                    ].includes(error.code)) {
+                    // Keep the prior continuation, but commit the rejected attempt so event
+                    // sequence numbers already observed by subscribers are never reused.
+                    const rejected = add("error", {
+                        message: error instanceof Error ? error.message : String(error),
+                    }, false);
+                    const { active: _, ...rest } = document;
+                    await this.store.put(agent.id, sessionId, {
+                        ...(stored ?? { ...rest, status: "failed" }),
+                        updatedAt: Date.now(),
+                        events: [...events],
+                    });
+                    publishEvent(rejected);
+                    throw error;
+                }
+                // A failed commit must leave the durable active marker intact. Never replay it.
+                add("error", {
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+            finally {
+                options.signal?.removeEventListener("abort", abort);
+                this.active.delete(key);
+            }
+        });
+        this.queues.set(key, work);
+        void work
+            .finally(() => {
+            if (this.queues.get(key) === work)
+                this.queues.delete(key);
+        })
+            .catch(() => { });
+        return work;
+    }
+    async cancel(agent, sessionId) {
+        const key = this.key(agent.id, sessionId);
+        this.generations.set(key, (this.generations.get(key) ?? 0) + 1);
+        this.active.get(key)?.abort(new Error("Run cancelled"));
+        const prior = this.queues.get(key) ?? Promise.resolve();
+        const work = prior
+            .catch(() => { })
+            .then(async () => {
+            const stored = await this.store.get(agent.id, sessionId);
+            if (stored?.active || stored?.status === "interrupted")
+                throw new Error("This session was interrupted; reconcile its external effects before cancellation.");
+            if (stored?.state?.status !== "paused")
+                return;
+            const result = await agent.run({
+                state: stored.state,
+                input: { kind: "continue" },
+                signal: AbortSignal.abort(new Error("Paused execution cancelled")),
+                onModelCall: async () => {
+                    throw new Error("Cancelled execution cannot call a model");
+                },
+            });
+            const event = {
+                session: sessionId,
+                seq: (stored.events.at(-1)?.seq ?? 0) + 1,
+                ts: new Date().toISOString(),
+                type: "cancelled",
+                payload: { executionId: result.state.executionId },
+            };
+            await this.store.put(agent.id, sessionId, {
+                ...stored,
+                state: result.state,
+                status: "cancelled",
+                updatedAt: Date.now(),
+                events: [...stored.events, event],
+            });
+            for (const listener of this.listeners.get(key) ?? []) {
+                try {
+                    listener(event);
+                }
+                catch {
+                    /* Observation cannot change committed cancellation. */
+                }
+            }
+        });
+        this.queues.set(key, work);
+        try {
+            await work;
+        }
+        finally {
+            if (this.queues.get(key) === work)
+                this.queues.delete(key);
+        }
+    }
+    async interrupt(agent, sessionId, input, options) {
+        await this.cancel(agent, sessionId);
+        return this.submit(agent, sessionId, input, options);
+    }
+    async close() {
+        this.closed = true;
+        for (const controller of this.active.values())
+            controller.abort(new Error("Runtime closing"));
+        await Promise.allSettled(this.queues.values());
+        this.listeners.clear();
+        if ("close" in this.store && typeof this.store.close === "function")
+            await this.store.close();
+    }
+}

package/dist/sessions/store.d.ts

@@ -0,0 +1,40 @@
+import type { ExecutionInput, ExecutionState } from "@nylorun/harness";
+export interface CanonicalEvent {
+    readonly session: string;
+    readonly seq: number;
+    readonly ts: string;
+    readonly type: string;
+    readonly payload: Record<string, unknown>;
+}
+export interface SessionSummary {
+    readonly session: string;
+    readonly title?: string;
+    readonly status: StoredSession["status"];
+    readonly startedAt: number;
+    readonly endedAt?: number;
+}
+export interface StoredSession {
+    readonly version: 1;
+    readonly id: string;
+    readonly agentId: string;
+    readonly state?: ExecutionState;
+    readonly status: "running" | "waiting" | "completed" | "cancelled" | "failed" | "interrupted" | "archived";
+    readonly startedAt: number;
+    readonly updatedAt: number;
+    readonly title?: string;
+    readonly active?: {
+        readonly runId: string;
+        readonly input: ExecutionInput;
+    };
+    readonly events: readonly CanonicalEvent[];
+}
+export interface SessionStore {
+    get(agentId: string, sessionId: string): Promise<StoredSession | undefined>;
+    put(agentId: string, sessionId: string, session: StoredSession): Promise<void>;
+    list(agentId: string): Promise<readonly SessionSummary[]>;
+}
+export interface ManagedSessionStore extends SessionStore {
+    close(): Promise<void>;
+}
+export declare function sessionSummary(session: StoredSession): SessionSummary;
+export declare function memorySessions(): SessionStore;

package/dist/sessions/store.js

@@ -0,0 +1,30 @@
+export function sessionSummary(session) {
+    return {
+        session: session.id,
+        status: session.status,
+        startedAt: session.startedAt,
+        ...(session.title === undefined ? {} : { title: session.title }),
+        ...(session.status === "completed" ? { endedAt: session.updatedAt } : {}),
+    };
+}
+export function memorySessions() {
+    const documents = new Map();
+    const key = (agentId, sessionId) => JSON.stringify([agentId, sessionId]);
+    return {
+        async get(agentId, sessionId) {
+            const found = documents.get(key(agentId, sessionId));
+            return found === undefined ? undefined : structuredClone(found);
+        },
+        async put(agentId, sessionId, session) {
+            if (session.id !== sessionId || session.agentId !== agentId)
+                throw new Error("Session identity mismatch");
+            documents.set(key(agentId, sessionId), structuredClone(session));
+        },
+        async list(agentId) {
+            return [...documents.values()]
+                .filter((session) => session.agentId === agentId)
+                .map(sessionSummary)
+                .sort((a, b) => b.startedAt - a.startedAt);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/runtime",
-  "version": "0.4.0-beta",
+  "version": "0.5.0-beta",
   "description": "Portable agent runtime, Hono protocol router, model providers, and the Nylorun CLI.",
   "type": "module",
   "license": "Apache-2.0",
@@ -19,6 +19,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js"
     }
   },
   "files": [
@@ -32,15 +36,17 @@
     "provenance": true
   },
   "scripts": {
-    "build": "node ../scripts/check-typescript-version.mjs && tsc -p tsconfig.json",
+    "build": "npm run clean && node ../scripts/check-typescript-version.mjs && tsc -p tsconfig.json",
     "check": "npm run build && npm test && node scripts/check-package.mjs",
     "typecheck": "node ../scripts/check-typescript-version.mjs && tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "clean": "node -e \"import('node:fs').then(({rmSync})=>rmSync('dist',{recursive:true,force:true}))\""
   },
   "dependencies": {
     "@earendil-works/pi-ai": "0.85.1",
-    "@hono/node-server": "^2.1.1"
+    "@hono/node-server": "^2.1.1",
+    "@nylorun/harness": "0.13.0-beta"
   },
   "peerDependencies": {
     "hono": "^4.13.7"

package/dist/adapters/journal.d.ts

@@ -1,35 +0,0 @@
-export type CanonicalEvent = Readonly<{
-    session: string;
-    seq: number;
-    ts: string;
-    type: string;
-    payload: Record<string, unknown>;
-}>;
-export type SessionSummary = Readonly<{
-    session: string;
-    title?: string;
-    status: "idle" | "waiting";
-    startedAt: number;
-    endedAt?: number;
-}>;
-/** Explicit local-only JSONL durability. Raw provider payloads never enter this service. */
-export declare class JsonlJournal {
-    private readonly root;
-    private readonly secrets;
-    constructor(root: string, secrets: readonly string[]);
-    append(agentId: string, event: CanonicalEvent): Promise<void>;
-    events(agentId: string, sessionId: string): Promise<readonly CanonicalEvent[]>;
-    list(agentId: string): Promise<readonly SessionSummary[]>;
-    private file;
-}
-export declare function scrub(value: unknown, secrets: readonly string[]): unknown;
-export interface RuntimeDurability {
-    append(agentId: string, event: CanonicalEvent): Promise<void>;
-    events(agentId: string, sessionId: string): Promise<readonly CanonicalEvent[]>;
-    list(agentId: string): Promise<readonly SessionSummary[]>;
-}
-export declare function localJsonl(options?: {
-    root?: string;
-    secrets?: readonly string[];
-}): RuntimeDurability;
-export declare function memoryHistory(): RuntimeDurability;

package/dist/adapters/journal.js

@@ -1,130 +0,0 @@
-import { appendFile, mkdir, readFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
-/** Explicit local-only JSONL durability. Raw provider payloads never enter this service. */
-export class JsonlJournal {
-    root;
-    secrets;
-    constructor(root, secrets) {
-        this.root = root;
-        this.secrets = secrets;
-    }
-    async append(agentId, event) {
-        const file = this.file(agentId, event.session);
-        await mkdir(join(this.root, agentId, event.session), { recursive: true });
-        await appendFile(file, `${JSON.stringify(scrub(event, this.secrets))}\n`);
-    }
-    async events(agentId, sessionId) {
-        try {
-            return Object.freeze((await readFile(this.file(agentId, sessionId), "utf8"))
-                .split("\n")
-                .filter(Boolean)
-                .flatMap((line) => {
-                try {
-                    return [JSON.parse(line)];
-                }
-                catch {
-                    return [];
-                }
-            }));
-        }
-        catch {
-            return Object.freeze([]);
-        }
-    }
-    async list(agentId) {
-        try {
-            const ids = await readdir(join(this.root, agentId));
-            const summaries = await Promise.all(ids.map(async (sessionId) => {
-                const events = await this.events(agentId, sessionId);
-                const final = events.findLast((event) => event.type === "final");
-                const title = sessionTitle(events);
-                return {
-                    session: sessionId,
-                    ...(title === undefined ? {} : { title }),
-                    status: sessionStatus(events),
-                    startedAt: events[0] ? Date.parse(events[0].ts) : 0,
-                    ...(final === undefined ? {} : { endedAt: Date.parse(final.ts) }),
-                };
-            }));
-            return Object.freeze(summaries.sort((a, b) => b.startedAt - a.startedAt));
-        }
-        catch {
-            return Object.freeze([]);
-        }
-    }
-    file(agentId, sessionId) {
-        return join(this.root, safe(agentId), safe(sessionId), "events.jsonl");
-    }
-}
-function sessionTitle(events) {
-    for (const event of events) {
-        if (event.type !== "session.run.started" ||
-            typeof event.payload.input !== "string")
-            continue;
-        const title = event.payload.input.replace(/\s+/gu, " ").trim();
-        if (title)
-            return title;
-    }
-    return undefined;
-}
-function sessionStatus(events) {
-    for (let index = events.length - 1; index >= 0; index -= 1) {
-        const event = events[index];
-        if (event.type === "final")
-            return "idle";
-        if (event.type === "interaction.required")
-            return "waiting";
-        if (event.type === "session.run.started" &&
-            typeof event.payload.approved === "boolean")
-            return "idle";
-    }
-    return "idle";
-}
-function safe(value) {
-    if (value === "." || value === ".." || !/^[a-zA-Z0-9._-]+$/u.test(value)) {
-        throw new Error("Refusing a path-shaped ID.");
-    }
-    return value;
-}
-export function scrub(value, secrets) {
-    if (typeof value === "string")
-        return secrets.reduce((text, secret) => secret.length >= 8 ? text.split(secret).join("[redacted]") : text, value.replace(/data:image\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+/giu, "[inline image data redacted]"));
-    if (Array.isArray(value))
-        return value.map((item) => scrub(item, secrets));
-    if (value && typeof value === "object")
-        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
-            key,
-            /^(authorization|api[_-]?key|(?:access|refresh|id|auth)[_-]?token|token|secret|password|cookie|credentials?)$/iu.test(key)
-                ? "[redacted]"
-                : scrub(item, secrets),
-        ]));
-    return value;
-}
-export function localJsonl(options = {}) {
-    return new JsonlJournal(options.root ?? join(process.cwd(), ".data", "sessions"), options.secrets ?? []);
-}
-export function memoryHistory() {
-    const agents = new Map();
-    return {
-        async append(agentId, event) {
-            const sessions = agents.get(agentId) ?? new Map();
-            agents.set(agentId, sessions);
-            const events = sessions.get(event.session) ?? [];
-            events.push(event);
-            sessions.set(event.session, events);
-        },
-        async events(agentId, sessionId) {
-            return agents.get(agentId)?.get(sessionId) ?? [];
-        },
-        async list(agentId) {
-            return [...(agents.get(agentId) ?? [])]
-                .map(([session, events]) => ({
-                session,
-                title: sessionTitle(events),
-                status: sessionStatus(events),
-                startedAt: Date.parse(events[0].ts),
-            }))
-                .sort((a, b) => b.startedAt - a.startedAt);
-        },
-    };
-}