@nylorun/runtime 0.13.0-beta → 0.14.0-beta

package/dist/tenant/session-streams.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Live delivery over Durable Streams (architecture §12.4, "Reading"): session history
+ * (`GET /v1/sessions/:id/items`) and session SSE (`GET /v1/sessions/:id/events`).
+ *
+ * - **Streams.** A session's events are in `sessions/<id>` in the Tenant's current basin
+ *   generation (`currentBasin`); cursors carry only the session id and sequence.
+ * - **History** reads the session's stream from the cursor up to the tail seen when the read
+ *   starts. The `agent` filter runs here, and the response cursor is the last record read. If
+ *   the streams fail, history answers `503`.
+ * - **SSE** shares one stream read per observed session in this process (a `SessionStream`)
+ *   among that session's observers. Each observer keeps the next sequence it needs and skips
+ *   what it already has, so a client resuming from `Last-Event-ID` sees no gap and no
+ *   duplicate. An observer behind the feed restarts the shared read from its own position.
+ *   A feed follows one basin generation: it ends once its session is gone or the Tenant moved
+ *   to a new generation (a reset, possibly on another node), checked when a client joins, when
+ *   its read fails, on a `sessions.reset` signal, and periodically (`checkSessionStreams`).
+ *
+ * Business code never writes here: events reach streams only through the stream relay, from
+ * the record, after commit.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LiveEvent } from "@nylorun/core/contracts";
+import type { TenantContext } from "./context.js";
+import type { StreamsWiring } from "./streams.js";
+/** Why the Runtime ended a stream a subject token opened. */
+export type StreamEndReason = "token_expired" | "revoked";
+/** Where an observer's events go: an SSE response, or an in-process reader. */
+export interface ObserverSink {
+    write(event: LiveEvent): void;
+    /** Ends the stream; with a reason, the client is told why before it ends. */
+    end(reason?: StreamEndReason): void;
+}
+/** The subject token a stream was opened with: it ends at expiry or revocation. */
+export interface StreamHolder {
+    readonly subject: string;
+    readonly epoch: number;
+    /** Epoch ms when the token expires. */
+    readonly expiresAt: number;
+}
+/** One client of a session: the next sequence it needs. */
+interface Observer {
+    readonly sink: ObserverSink;
+    next: number;
+    readonly holder?: StreamHolder;
+    /** Ends the observer when its token expires. */
+    deadline?: NodeJS.Timeout;
+}
+/** The shared stream read of one observed session. */
+interface SessionStream {
+    readonly sessionId: string;
+    /** The basin the feed reads (the Tenant's generation when it started). */
+    readonly basin: string;
+    readonly stream: string;
+    /** The sequence the shared read yields next. Every observer's `next` is at or past it. */
+    next: number;
+    readonly observers: Set<Observer>;
+    /** Aborts the current read; replaced when the read restarts from an earlier sequence. */
+    read: AbortController;
+}
+export interface SessionStreams {
+    /** Set once by `wireStreams`. */
+    wiring: StreamsWiring | undefined;
+    /** The Tenant's basin generation as this process last saw it (`wireStreams` keeps it). */
+    generation: number;
+    /** Session id → its shared read and observers. */
+    readonly sessions: Map<string, SessionStream>;
+}
+export declare function createSessionStreams(): SessionStreams;
+export declare function send(response: ServerResponse, data: string): void;
+/** Start an SSE response with keepalives; `onClose` runs once the client goes away. */
+export declare function openSse(request: IncomingMessage, response: ServerResponse, onClose: () => void): void;
+/** The resume cursor: `?cursor=` wins over `Last-Event-ID`. */
+export declare function requestCursor(request: IncomingMessage, url: URL): string | undefined;
+/** The basin the Tenant's session streams are in now. */
+export declare function currentBasin(ctx: TenantContext): string;
+/**
+ * `GET /v1/sessions/:id/items`: the session stream after the cursor, up to its tail when the
+ * read starts. The cursor returned is the last record read (the request's cursor when none
+ * was), whatever the `agent` filter kept.
+ */
+export declare function readHistory(ctx: TenantContext, sessionId: string, cursor: string | undefined, agent: string | undefined): Promise<{
+    items: LiveEvent[];
+    cursor: string | null;
+}>;
+/**
+ * `GET /v1/sessions/:id/events`: joins the session's shared read at the client's cursor and
+ * follows it until the client leaves, the session is reset or deleted, or the Tenant closes.
+ */
+export declare function streamSessionEvents(ctx: TenantContext, request: IncomingMessage, response: ServerResponse, sessionId: string, cursor: string | undefined, holder?: StreamHolder): Promise<void>;
+/** Thrown by `observeSession` when the Runtime ended the stream for its token. */
+export declare class StreamClosed extends Error {
+    readonly reason: StreamEndReason;
+    /** The cursor of the last event delivered, if any. */
+    readonly cursor: string | undefined;
+    constructor(reason: StreamEndReason, 
+    /** The cursor of the last event delivered, if any. */
+    cursor: string | undefined);
+}
+/**
+ * A session's events from `cursor`, in process: the same shared read and deadlines as an SSE
+ * client (`streamSessionEvents`). Ends when `signal` aborts or the feed ends; throws
+ * `StreamClosed` when the Runtime ends it for its token (expiry or revocation).
+ */
+export declare function observeSession(ctx: TenantContext, sessionId: string, cursor: string | undefined, options: {
+    holder?: StreamHolder;
+    signal: AbortSignal;
+}): AsyncGenerator<LiveEvent>;
+/**
+ * Ends every feed in this process whose session is gone or whose Tenant moved to a new basin
+ * generation, and moves this process to the Tenant's current generation. Run on a
+ * `sessions.reset` signal and periodically, so feeds on nodes other than the one that reset
+ * the Tenant end too.
+ */
+export declare function checkSessionStreams(ctx: TenantContext): Promise<void>;
+/**
+ * Ends the streams of `subject` opened with a token older than `epoch` (a revocation), on
+ * this process. Other processes do the same on the `subject.revoked` signal.
+ */
+export declare function endSubjectStreams(hub: SessionStreams, subject: string, epoch: number): void;
+/** Reset or close: end every session observer and stop every shared read. */
+export declare function clearObservers(hub: SessionStreams): void;
+/** Close: end every session observer. */
+export declare function endAllStreams(hub: SessionStreams): void;
+export declare function sleep(ms: number, signal: AbortSignal): Promise<void>;
+export {};

package/dist/tenant/session-streams.js

@@ -0,0 +1,399 @@
+import { decodeCursor, encodeCursor } from "../store/cursor.js";
+import { basinOf } from "../streams/basin.js";
+import { sessionStream, } from "../streams/types.js";
+import { fail } from "./http.js";
+export function createSessionStreams() {
+    return { wiring: undefined, generation: 0, sessions: new Map() };
+}
+const RETRY_MIN_MS = 100;
+const RETRY_MAX_MS = 2000;
+function frame(event) {
+    return `id: ${event.cursor}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+export function send(response, data) {
+    if (!response.write(data))
+        response.destroy();
+}
+/** The frame that tells a client why the Runtime ended its stream (no `id:`: not an event). */
+function closedFrame(reason) {
+    return `event: nylorun.closed\ndata: ${JSON.stringify({ reason })}\n\n`;
+}
+/** An observer sink writing SSE frames to `response`. */
+function sseSink(response) {
+    return {
+        write: (event) => send(response, frame(event)),
+        end: (reason) => {
+            if (reason && !response.writableEnded)
+                send(response, closedFrame(reason));
+            response.end();
+        },
+    };
+}
+/** Start an SSE response with keepalives; `onClose` runs once the client goes away. */
+export function openSse(request, response, onClose) {
+    response.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+        "x-accel-buffering": "no",
+    });
+    response.flushHeaders();
+    const timer = setInterval(() => send(response, ": keepalive\n\n"), 15000);
+    timer.unref();
+    request.on("close", () => {
+        clearInterval(timer);
+        onClose();
+    });
+}
+/** The resume cursor: `?cursor=` wins over `Last-Event-ID`. */
+export function requestCursor(request, url) {
+    return (url.searchParams.get("cursor") ??
+        (typeof request.headers["last-event-id"] === "string"
+            ? request.headers["last-event-id"]
+            : undefined));
+}
+/** The first sequence to read: after the cursor's, or the session's first event. */
+function startSeq(sessionId, cursor) {
+    return cursor ? decodeCursor(sessionId, cursor) + 1 : 0;
+}
+/** `agent` keeps only events of one agent used as a tool, by delegationId or path. */
+function belongsTo(event, agent) {
+    const ref = event.payload?.agent;
+    return ref?.delegationId === agent || ref?.path === agent;
+}
+/** The basin the Tenant's session streams are in now. */
+export function currentBasin(ctx) {
+    return basinOf(ctx.config.tenantId, ctx.sessionStreams.generation);
+}
+/** The session's stream now, or undefined when the session is gone. */
+async function currentStream(ctx, sessionId) {
+    const session = await ctx.store.tx((t) => t.get("sessions", sessionId));
+    return session && { basin: currentBasin(ctx), stream: sessionStream(sessionId) };
+}
+const sameStream = (feed, ref) => ref !== undefined && ref.basin === feed.basin && ref.stream === feed.stream;
+function streamsOf(ctx) {
+    return (ctx.sessionStreams.wiring?.streams ?? fail(503, "Session streams are unavailable"));
+}
+/**
+ * `GET /v1/sessions/:id/items`: the session stream after the cursor, up to its tail when the
+ * read starts. The cursor returned is the last record read (the request's cursor when none
+ * was), whatever the `agent` filter kept.
+ */
+export async function readHistory(ctx, sessionId, cursor, agent) {
+    const from = startSeq(sessionId, cursor);
+    const streams = streamsOf(ctx);
+    const ref = (await currentStream(ctx, sessionId)) ?? fail(404, "Session not found");
+    const items = [];
+    let last;
+    try {
+        for await (const record of streams.read(ref.basin, ref.stream, from, { follow: false })) {
+            last = record.seq;
+            if (agent === undefined || belongsTo(record.body, agent))
+                items.push(record.body);
+        }
+    }
+    catch (error) {
+        ctx.config.logger.warn("session history read failed", {
+            sessionId,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        fail(503, "Session history is unavailable");
+    }
+    return {
+        items,
+        cursor: last !== undefined ? encodeCursor(sessionId, last) : cursor ?? null,
+    };
+}
+/**
+ * `GET /v1/sessions/:id/events`: joins the session's shared read at the client's cursor and
+ * follows it until the client leaves, the session is reset or deleted, or the Tenant closes.
+ */
+export async function streamSessionEvents(ctx, request, response, sessionId, cursor, holder) {
+    const observer = {
+        sink: sseSink(response),
+        next: startSeq(sessionId, cursor),
+        ...(holder ? { holder } : {}),
+    };
+    const joined = await join(ctx, sessionId, observer);
+    openSse(request, response, () => leave(ctx.sessionStreams, joined, observer));
+    armDeadline(ctx.sessionStreams, joined, observer);
+}
+/** Thrown by `observeSession` when the Runtime ended the stream for its token. */
+export class StreamClosed extends Error {
+    reason;
+    cursor;
+    constructor(reason, 
+    /** The cursor of the last event delivered, if any. */
+    cursor) {
+        super(`The stream ended: ${reason}`);
+        this.reason = reason;
+        this.cursor = cursor;
+        this.name = "StreamClosed";
+    }
+}
+/**
+ * A session's events from `cursor`, in process: the same shared read and deadlines as an SSE
+ * client (`streamSessionEvents`). Ends when `signal` aborts or the feed ends; throws
+ * `StreamClosed` when the Runtime ends it for its token (expiry or revocation).
+ */
+export async function* observeSession(ctx, sessionId, cursor, options) {
+    const queue = [];
+    let ended;
+    let wake;
+    const notify = () => {
+        const resolve = wake;
+        wake = undefined;
+        resolve?.();
+    };
+    const observer = {
+        sink: {
+            write: (event) => {
+                queue.push(event);
+                notify();
+            },
+            end: (reason) => {
+                ended = reason ? { reason } : {};
+                notify();
+            },
+        },
+        next: startSeq(sessionId, cursor),
+        ...(options.holder ? { holder: options.holder } : {}),
+    };
+    const joined = await join(ctx, sessionId, observer);
+    armDeadline(ctx.sessionStreams, joined, observer);
+    const stop = () => {
+        leave(ctx.sessionStreams, joined, observer);
+        notify();
+    };
+    options.signal.addEventListener("abort", stop, { once: true });
+    let last = cursor;
+    try {
+        for (;;) {
+            while (queue.length > 0) {
+                const event = queue.shift();
+                last = event.cursor;
+                yield event;
+            }
+            if (options.signal.aborted)
+                return;
+            if (ended) {
+                if (ended.reason)
+                    throw new StreamClosed(ended.reason, last);
+                return;
+            }
+            await new Promise((resolve) => (wake = resolve));
+        }
+    }
+    finally {
+        options.signal.removeEventListener("abort", stop);
+        leave(ctx.sessionStreams, joined, observer);
+    }
+}
+/** Ends the observer when its token expires. */
+function armDeadline(hub, feed, observer) {
+    if (!observer.holder)
+        return;
+    observer.deadline = setTimeout(() => endObserver(hub, feed, observer, "token_expired"), Math.max(0, observer.holder.expiresAt - Date.now()));
+    observer.deadline.unref();
+}
+/**
+ * Adds `observer` to the session's shared read, starting or restarting it from the
+ * observer's position when needed. 404 when the session has no stream.
+ */
+async function join(ctx, sessionId, observer) {
+    const from = observer.next;
+    streamsOf(ctx);
+    const ref = (await currentStream(ctx, sessionId)) ?? fail(404, "Session not found");
+    const hub = ctx.sessionStreams;
+    let feed = hub.sessions.get(sessionId);
+    if (feed && !sameStream(feed, ref)) {
+        // The Tenant moved to a new basin since that feed started: it follows an abandoned stream.
+        endFeed(hub, feed);
+        feed = undefined;
+    }
+    if (!feed) {
+        feed = {
+            sessionId,
+            basin: ref.basin,
+            stream: ref.stream,
+            next: from,
+            observers: new Set(),
+            read: new AbortController(),
+        };
+        hub.sessions.set(sessionId, feed);
+        runFeed(ctx, feed);
+    }
+    else if (from < feed.next) {
+        // Behind the shared read: restart it here; observers ahead skip what they have.
+        feed.read.abort();
+        feed.read = new AbortController();
+        feed.next = from;
+        runFeed(ctx, feed);
+    }
+    feed.observers.add(observer);
+    return feed;
+}
+/** Ends one observer early (its token expired or was revoked). */
+function endObserver(hub, feed, observer, reason) {
+    if (!feed.observers.has(observer))
+        return;
+    leave(hub, feed, observer);
+    observer.sink.end(reason);
+}
+function leave(hub, feed, observer) {
+    if (observer.deadline)
+        clearTimeout(observer.deadline);
+    if (!feed.observers.delete(observer))
+        return;
+    if (feed.observers.size > 0)
+        return;
+    feed.read.abort();
+    if (hub.sessions.get(feed.sessionId) === feed)
+        hub.sessions.delete(feed.sessionId);
+}
+function deliver(observer, record) {
+    if (record.seq < observer.next)
+        return;
+    observer.next = record.seq + 1;
+    observer.sink.write(record.body);
+}
+/**
+ * Follows the feed's stream from `feed.next` for the current `feed.read`, retrying failed
+ * reads from where it stopped while the session still has that stream. A read that ends by
+ * itself (the stream's Tenant is gone or the streams closed), or a session that is gone or
+ * whose Tenant moved to a new basin, ends the observers.
+ */
+function runFeed(ctx, feed) {
+    const read = feed.read;
+    const signal = read.signal;
+    void (async () => {
+        let delay = RETRY_MIN_MS;
+        while (!signal.aborted) {
+            const streams = ctx.sessionStreams.wiring?.streams;
+            if (!streams)
+                break;
+            try {
+                for await (const record of streams.read(feed.basin, feed.stream, feed.next, { signal })) {
+                    // A restart replaced this read: the new one owns `feed.next`.
+                    if (signal.aborted || feed.read !== read)
+                        return;
+                    if (record.seq < feed.next)
+                        continue;
+                    feed.next = record.seq + 1;
+                    delay = RETRY_MIN_MS;
+                    for (const observer of feed.observers)
+                        deliver(observer, record);
+                }
+                if (signal.aborted)
+                    return;
+                break;
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return;
+                ctx.config.logger.warn("session stream read failed; retrying", {
+                    sessionId: feed.sessionId,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+            if (!(await stillCurrent(ctx, feed)))
+                break;
+            await sleep(delay, signal);
+            delay = Math.min(delay * 2, RETRY_MAX_MS);
+        }
+        if (signal.aborted || feed.read !== read)
+            return;
+        endFeed(ctx.sessionStreams, feed);
+    })();
+}
+/** False when the feed's session is gone or the Tenant moved to a new basin. True when unsure. */
+async function stillCurrent(ctx, feed) {
+    try {
+        return sameStream(feed, await currentStream(ctx, feed.sessionId));
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Ends every feed in this process whose session is gone or whose Tenant moved to a new basin
+ * generation, and moves this process to the Tenant's current generation. Run on a
+ * `sessions.reset` signal and periodically, so feeds on nodes other than the one that reset
+ * the Tenant end too.
+ */
+export async function checkSessionStreams(ctx) {
+    const feeds = [...ctx.sessionStreams.sessions.values()];
+    // Also a backstop for lost `subject.revoked` signals: the holders' current epochs.
+    const subjects = new Set();
+    for (const feed of feeds)
+        for (const observer of feed.observers)
+            if (observer.holder)
+                subjects.add(observer.holder.subject);
+    const { exists, epochs, generation } = await ctx.store.tx(async (t) => {
+        const exists = new Set();
+        for (const feed of feeds)
+            if (await t.get("sessions", feed.sessionId))
+                exists.add(feed.sessionId);
+        return {
+            exists,
+            generation: (await t.basinGenerations()).current,
+            epochs: subjects.size === 0
+                ? new Map()
+                : await t.subjectEpochs([...subjects]),
+        };
+    });
+    if (generation !== ctx.sessionStreams.generation)
+        ctx.sessionStreams.wiring?.moveTo(generation);
+    for (const feed of feeds)
+        if (ctx.sessionStreams.sessions.get(feed.sessionId) === feed &&
+            !sameStream(feed, exists.has(feed.sessionId)
+                ? { basin: currentBasin(ctx), stream: sessionStream(feed.sessionId) }
+                : undefined))
+            endFeed(ctx.sessionStreams, feed);
+    for (const [subject, epoch] of epochs)
+        endSubjectStreams(ctx.sessionStreams, subject, epoch);
+}
+/**
+ * Ends the streams of `subject` opened with a token older than `epoch` (a revocation), on
+ * this process. Other processes do the same on the `subject.revoked` signal.
+ */
+export function endSubjectStreams(hub, subject, epoch) {
+    for (const feed of [...hub.sessions.values()])
+        for (const observer of [...feed.observers])
+            if (observer.holder?.subject === subject && observer.holder.epoch < epoch)
+                endObserver(hub, feed, observer, "revoked");
+}
+function endFeed(hub, feed) {
+    feed.read.abort();
+    if (hub.sessions.get(feed.sessionId) === feed)
+        hub.sessions.delete(feed.sessionId);
+    for (const observer of feed.observers) {
+        if (observer.deadline)
+            clearTimeout(observer.deadline);
+        observer.sink.end();
+    }
+    feed.observers.clear();
+}
+/** Reset or close: end every session observer and stop every shared read. */
+export function clearObservers(hub) {
+    for (const feed of [...hub.sessions.values()])
+        endFeed(hub, feed);
+    hub.sessions.clear();
+}
+/** Close: end every session observer. */
+export function endAllStreams(hub) {
+    clearObservers(hub);
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+    });
+}

package/dist/tenant/sessions.d.ts

@@ -5,7 +5,7 @@
  */
 import { type PutAgentRequest, type PutSessionRequest } from "@nylorun/core/contracts";
 import type { Tx } from "../store/types.js";
-import { type Session, type TenantContext } from "./context.js";
+import { type Session, type SessionAccess, type TenantContext } from "./context.js";
 export declare function listDefinitions(ctx: TenantContext): Promise<{
     agents: {
         agentId: any;
@@ -14,13 +14,27 @@ export declare function listDefinitions(ctx: TenantContext): Promise<{
         implementationVersion: string;
     }[];
 }>;
+/**
+ * The agents a subject token or publishable key may see: id, name and description only, never
+ * instructions, tools or MCP servers, and only the agents allowed.
+ */
+export declare function listAgentsPublic(ctx: TenantContext, agents: ReadonlySet<string> | "*"): Promise<{
+    agents: {
+        agentId: string;
+        name?: any;
+        description?: any;
+    }[];
+}>;
 export declare function putDefinition(ctx: TenantContext, agentId: string, body: PutAgentRequest): Promise<{
     agentId: string;
     manifestHash: string;
     implementationVersion: string;
 }>;
-/** `owner`, when the request acts for a subject, limits the list to that subject's sessions. */
-export declare function listSessions(ctx: TenantContext, agentId: string | null, owner?: string): Promise<{
+/**
+ * `access`, when the request acts for a person, limits the list to that person's sessions of
+ * the agents they may use.
+ */
+export declare function listSessions(ctx: TenantContext, agentId: string | null, access?: SessionAccess): Promise<{
     sessions: {
         id: string;
         agentId: string;
@@ -34,7 +48,17 @@ export declare function listSessions(ctx: TenantContext, agentId: string | null,
  * the request acts for a subject, must be the session's owner: another owner's session id is
  * the 404 of a missing one (not the 409 of a mismatch), and so are another owner's vaults and
  * sandboxes.
+ *
+ * The session's sandbox is decided here and fixed for its life (§5 of Sandboxes v3): shared
+ * with `{ session }`, none with `false`, inline, or the Tenant default when omitted. A definition
+ * that declares its own sandbox (`.sandbox()`) keeps it and takes no sandbox request.
  */
-export declare function putSession(ctx: TenantContext, id: string, body: PutSessionRequest, owner?: string): Promise<Session>;
+export declare function putSession(ctx: TenantContext, id: string, body: PutSessionRequest, access?: SessionAccess, options?: {
+    /**
+     * Create the session if it is missing and otherwise leave it as it is (an AG-UI thread's
+     * session): an existing one must have the same owner and agent, or it is a 404.
+     */
+    createOnly?: boolean;
+}): Promise<Session>;
 /** The session resource returned by `GET`/`PUT /v1/sessions/:id`. */
 export declare function sessionView(t: Tx, s: Session): Promise<unknown>;