@nylorun/agents 0.9.0-beta → 0.10.0-beta

package/dist/ag-ui/handler.js

@@ -1,29 +1,21 @@
 /**
- * An AG-UI endpoint over the Tenant's agents, as web-standard `Request` → `Response`
- * handlers. The host authenticates people (`subject`); the handler maps each AG-UI thread to
- * one session per subject, agent and thread, and streams the session's transcript events as
- * AG-UI events. It never trusts a session id from the client, and it calls the Runtime as the
- * subject (`client.as`), so the Runtime itself keeps one subject out of another's sessions.
+ * AG-UI for the Tenant's agents, served from the app's own server as web-standard
+ * `Request` → `Response` handlers. The host signs people in (`subject`); the handler forwards
+ * each request to the Runtime's AG-UI endpoint (Host feature `ag-ui-endpoint`) acting for that
+ * person, so the Runtime keeps one person out of another's threads and does all the protocol
+ * work. The browser never sees the Tenant key, the Runtime's URL or the Tenant id.
+ *
+ * The same threads are reachable directly from a browser with a subject token: each thread is
+ * one session per subject, agent and thread on both paths.
  */
-import { createHash, randomUUID } from "node:crypto";
-import { EventType } from "@ag-ui/core";
-import { RunAgentInputSchema } from "@ag-ui/core/schemas";
-import { parseSubjectHeaders, } from "@nylorun/core/contracts";
+import { parseSubjectHeaders } from "@nylorun/core/contracts";
 import { createClient, } from "../client.js";
-import { IncompatibleRuntimeError, RuntimeError } from "../http.js";
-import { messagesFromEvents } from "./history.js";
-import { SSE_CONTENT_TYPE, SSE_HEARTBEAT, sseFrame } from "./sse.js";
-import { RunTranslator } from "./translate.js";
-const HEARTBEAT_MS = 15_000;
-/** Host features the handler needs: the chat transcript, and acting for each subject. */
-const REQUIRED_FEATURES = ["transcript-events", "subject-headers"];
+import { IncompatibleRuntimeError } from "../http.js";
+/** The Host feature the handler forwards to. */
+const REQUIRED_FEATURES = ["ag-ui-endpoint"];
 const DEFAULT_SCOPES = ["sessions:own"];
-const TERMINAL = new Set([
-    "turn.completed",
-    "turn.paused",
-    "turn.failed",
-    "turn.cancelled",
-]);
+/** Response headers passed back to the browser; nothing else of the Runtime's. */
+const PASSED_HEADERS = ["content-type", "cache-control", "x-accel-buffering"];
 class Problem extends Error {
     status;
     code;
@@ -36,49 +28,28 @@ class Problem extends Error {
 function problem(status, message, code) {
     return Response.json({ error: message, ...(code ? { code } : {}) }, { status });
 }
+/** The Runtime's refusal, as the browser may see it: no Runtime details. */
+function refusal(status) {
+    if (status === 404)
+        return new Problem(404, "Not found");
+    if (status === 400)
+        return new Problem(400, "The request was rejected", "invalid_request");
+    if (status === 409)
+        return new Problem(409, "The agent is busy or waiting for an answer to an open interrupt", "session_busy");
+    return new Problem(502, "The agent service failed", "runtime_error");
+}
 function problemOf(error) {
     if (error instanceof Problem)
         return error;
-    if (error instanceof RuntimeError) {
-        if (error.status === 404)
-            return new Problem(404, "Not found");
-        // The Runtime refused what the client sent (e.g. a cursor it cannot read).
-        if (error.status === 400)
-            return new Problem(400, "The request was rejected", "invalid_request");
-        if (error.status === 409)
-            return new Problem(409, "The agent is busy or waiting for an answer to an open interrupt", "session_busy");
-        return new Problem(502, "The agent service failed", "runtime_error");
-    }
     if (error instanceof IncompatibleRuntimeError)
         return new Problem(502, error.message, "runtime_incompatible");
-    return new Problem(500, "Internal error");
-}
-/** A session per subject, agent and thread; one subject can never name another's session. */
-export function sessionIdFor(subject, agentId, threadId) {
-    return createHash("sha256")
-        .update(`${subject}\u0000${agentId}\u0000${threadId}`)
-        .digest("hex")
-        .slice(0, 32);
-}
-/** The trailing user message: the Runtime keeps the transcript, AG-UI resends all of it. */
-function lastUserMessage(messages) {
-    const last = messages.at(-1);
-    if (!last || last.role !== "user")
-        throw new Problem(400, "The run's last message must be a user message");
-    const text = typeof last.content === "string"
-        ? last.content
-        : last.content
-            .filter((part) => part.type === "text")
-            .map((part) => part.text)
-            .join("\n");
-    if (!text.trim())
-        throw new Problem(400, "The user message has no text");
-    return { id: last.id, text };
+    return new Problem(502, "The agent service failed", "runtime_error");
 }
 function normalizeBase(basePath = "/") {
     const trimmed = basePath.replace(/\/+$/, "");
     return trimmed === "" ? "" : trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
 }
+const segment = (value) => encodeURIComponent(value);
 export function createAgUiHandler(options) {
     const allowed = new Set(options.agents.map((agent) => (typeof agent === "string" ? agent : agent.id)));
     const base = normalizeBase(options.basePath);
@@ -87,7 +58,7 @@ export function createAgUiHandler(options) {
     if (!checked.ok)
         throw new TypeError(`createAgUiHandler: ${checked.message}`);
     let ready;
-    /** The client, once the Runtime is known to have every required feature. Retries after a failure. */
+    /** The client, once the Runtime is known to serve AG-UI. Retries after a failure. */
     function connected() {
         ready ??= (async () => {
             const client = await (options.client ?? createClient());
@@ -102,253 +73,91 @@ export function createAgUiHandler(options) {
         });
         return ready;
     }
-    /** The client acting for `subject`: the Runtime limits it to the subject's own sessions. */
-    async function clientFor(subject) {
-        const client = await connected();
-        try {
-            return client.as(subject, { scopes });
-        }
-        catch (error) {
-            // The host's `subject` returned something the Runtime cannot name (see `as`).
-            throw new Problem(500, error.message, "subject_invalid");
-        }
-    }
     async function subjectOf(request) {
         const subject = await options.subject(request);
         if (!subject)
             throw new Problem(401, "Sign in required");
         return subject;
     }
-    function assertAgent(agentId) {
-        if (!allowed.has(agentId))
-            throw new Problem(404, "Not found");
-    }
-    async function sessionFor(request, agentId, threadId) {
-        assertAgent(agentId);
-        const subject = await subjectOf(request);
-        const client = await clientFor(subject);
-        return {
-            client,
-            subject,
-            session: client.session(sessionIdFor(subject, agentId, threadId)),
-        };
-    }
-    async function submit(session, input) {
-        if (input.resume?.length) {
-            let cursor = null;
-            // The interaction's kind is on the pending view, not in its id.
-            const pending = await session.pending();
-            const waits = Array.isArray(pending) ? pending : [];
-            for (const entry of input.resume) {
-                const wait = waits.find((w) => w?.interaction?.id === entry.interruptId);
-                const key = `${input.runId}:${entry.interruptId}`;
-                const payload = entry.payload;
-                const accepted = (wait?.interaction?.kind ?? "approval") === "approval"
-                    ? await session.approve(entry.interruptId, entry.status === "resolved" &&
-                        (payload === true ||
-                            (typeof payload === "object" && payload?.approved === true)), { idempotencyKey: key })
-                    : entry.status === "cancelled"
-                        ? await session.cancel({ idempotencyKey: key, reason: "interrupt cancelled" })
-                        : await session.respond(entry.interruptId, (entry.payload ?? null), {
-                            idempotencyKey: key,
-                        });
-                cursor ??= accepted.cursor;
-            }
-            return cursor;
-        }
-        const message = lastUserMessage(input.messages);
-        // The AG-UI message id is the idempotency key: a retried run replays the same turn,
-        // and history gives the message back its client id.
-        const accepted = await session.input(message.text, {
-            idempotencyKey: message.id,
-        });
-        return accepted.cursor;
-    }
-    /** Streams translated events until the run ends. Closing the response stops the read only. */
-    function stream(request, translator, source, preface = []) {
-        const reading = new AbortController();
-        request.signal.addEventListener("abort", () => reading.abort(), { once: true });
-        const bytes = new TextEncoder();
-        const body = new ReadableStream({
-            async start(controller) {
-                const write = (text) => {
-                    try {
-                        controller.enqueue(bytes.encode(text));
-                    }
-                    catch {
-                        reading.abort();
-                    }
-                };
-                const heartbeat = setInterval(() => write(SSE_HEARTBEAT), HEARTBEAT_MS);
-                try {
-                    write(sseFrame(translator.started()));
-                    for (const event of preface)
-                        write(sseFrame(event));
-                    if (source)
-                        for await (const event of source(reading.signal)) {
-                            const step = translator.translate(event);
-                            step.events.forEach((out, index) => write(sseFrame(out, index === step.events.length - 1 ? event.cursor : undefined)));
-                            if (step.finished || reading.signal.aborted)
-                                break;
-                        }
-                }
-                catch (error) {
-                    if (!reading.signal.aborted) {
-                        const failure = problemOf(error);
-                        write(sseFrame({
-                            type: EventType.RUN_ERROR,
-                            message: failure.message,
-                            ...(failure.code ? { code: failure.code } : {}),
-                        }));
-                    }
-                }
-                finally {
-                    clearInterval(heartbeat);
-                    reading.abort();
-                    try {
-                        controller.close();
-                    }
-                    catch {
-                        /* the client is gone */
-                    }
-                }
-            },
-            cancel() {
-                reading.abort();
-            },
-        });
-        return new Response(body, {
-            headers: {
-                "content-type": SSE_CONTENT_TYPE,
-                "cache-control": "no-cache, no-transform",
-                "x-accel-buffering": "no",
-            },
-        });
-    }
-    async function run(request, agentId) {
+    /** Forwards to the Runtime acting for `subject`, and passes the answer back. */
+    async function forward(request, subject, path, init) {
+        const client = await connected();
+        let person;
         try {
-            assertAgent(agentId);
-            const subject = await subjectOf(request);
-            const parsed = RunAgentInputSchema.safeParse(await request.json().catch(() => undefined));
-            if (!parsed.success)
-                throw new Problem(400, "Invalid RunAgentInput");
-            const input = parsed.data;
-            // Nylorun tools run in the Runtime or the app's executor; the browser runs none.
-            if (input.tools?.length)
-                throw new Problem(400, "Frontend tools are not supported");
-            const client = await clientFor(subject);
-            const extra = (await options.session?.(subject, agentId)) ?? {};
-            const translator = new RunTranslator(input.threadId, input.runId);
-            let session;
-            try {
-                // The host's parameters first: they never replace the session's identity.
-                session = await client.createSession({
-                    ...extra,
-                    id: sessionIdFor(subject, agentId, input.threadId),
-                    agentId,
-                    ownerUserId: subject,
-                });
-            }
-            catch (error) {
-                if (error instanceof RuntimeError && error.status === 409)
-                    throw new Problem(409, "The thread's session was opened with other parameters", "session_conflict");
-                throw error;
-            }
-            let cursor;
-            try {
-                cursor = await submit(session, input);
-            }
-            catch (error) {
-                const failure = problemOf(error);
-                // A busy or paused session is a run that could not start, not a transport failure.
-                if (failure.status !== 409)
-                    throw failure;
-                return stream(request, translator, undefined, [
-                    {
-                        type: EventType.RUN_ERROR,
-                        message: failure.message,
-                        code: failure.code,
-                    },
-                ]);
-            }
-            return stream(request, translator, (signal) => session.observe({ ...(cursor ? { cursor } : {}), signal }));
+            person = client.as(subject, { scopes });
         }
         catch (error) {
-            const failure = problemOf(error);
-            return problem(failure.status, failure.message, failure.code);
+            // The host's `subject` returned something the Runtime cannot name (see `as`).
+            throw new Problem(500, error.message, "subject_invalid");
         }
-    }
-    async function history(request, agentId, threadId) {
-        try {
-            const { session } = await sessionFor(request, agentId, threadId);
-            const items = [];
-            let cursor;
-            try {
-                for (;;) {
-                    const page = await session.history({ ...(cursor ? { cursor } : {}) });
-                    items.push(...page.items);
-                    if (!page.cursor || page.cursor === cursor || page.items.length === 0)
-                        break;
-                    cursor = page.cursor;
-                }
-            }
-            catch (error) {
-                // A thread that never ran has no session yet.
-                if (error instanceof RuntimeError && error.status === 404)
-                    return Response.json([]);
-                throw error;
-            }
-            return Response.json(messagesFromEvents(items));
+        const response = await person.transport.forward(`/v1/ag-ui/agents${path}`, {
+            ...init,
+            signal: request.signal,
+        });
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => { });
+            throw refusal(response.status);
         }
-        catch (error) {
-            const failure = problemOf(error);
-            return problem(failure.status, failure.message, failure.code);
+        const headers = new Headers();
+        for (const name of PASSED_HEADERS) {
+            const value = response.headers.get(name);
+            if (value !== null)
+                headers.set(name, value);
         }
+        return new Response(response.body, { status: response.status, headers });
     }
-    async function reattach(request, agentId, threadId) {
+    async function run(request, agentId) {
         try {
-            const { session } = await sessionFor(request, agentId, threadId);
-            const url = new URL(request.url);
-            const cursor = request.headers.get("last-event-id") ?? url.searchParams.get("cursor");
-            if (!cursor)
-                throw new Problem(400, "Last-Event-ID or ?cursor= is required");
-            const view = await session.inspect();
-            const runId = url.searchParams.get("runId") ??
-                view.activeTurnId ??
-                (typeof view.lastTurnId === "string" ? view.lastTurnId : randomUUID());
-            const translator = new RunTranslator(threadId, runId, { reattached: true });
-            if (view.activeTurnId)
-                return stream(request, translator, (signal) => session.observe({ cursor, signal }));
-            // No turn is running: send what the client missed, if the run ended after the cursor.
-            const missed = [];
-            let from = cursor;
-            for (;;) {
-                const page = await session.history({ cursor: from });
-                missed.push(...page.items);
-                if (!page.cursor || page.cursor === from || page.items.length === 0)
-                    break;
-                from = page.cursor;
-            }
-            if (!missed.some((event) => TERMINAL.has(event.type)))
-                return new Response(null, { status: 204 });
-            return stream(request, translator, () => iterate(missed));
+            if (!allowed.has(agentId))
+                throw new Problem(404, "Not found");
+            const subject = await subjectOf(request);
+            const body = (await request.json().catch(() => undefined));
+            if (!body || typeof body !== "object" || Array.isArray(body))
+                throw new Problem(400, "Invalid RunAgentInput", "invalid_request");
+            // Only the host names the session's options; whatever the browser sent is replaced.
+            const forwarded = body.forwardedProps && typeof body.forwardedProps === "object"
+                ? { ...body.forwardedProps }
+                : {};
+            delete forwarded.nylorun;
+            const extra = (await options.session?.(subject, agentId)) ?? {};
+            if (Object.keys(extra).length > 0)
+                forwarded.nylorun = { session: extra };
+            return await forward(request, subject, `/${segment(agentId)}`, {
+                method: "POST",
+                headers: { accept: "text/event-stream" },
+                body: JSON.stringify({ ...body, forwardedProps: forwarded }),
+            });
         }
         catch (error) {
             const failure = problemOf(error);
             return problem(failure.status, failure.message, failure.code);
         }
     }
-    async function cancel(request, agentId, threadId) {
+    async function thread(request, agentId, threadId, action, init) {
         try {
-            const { session } = await sessionFor(request, agentId, threadId);
-            await session.cancel({ idempotencyKey: `cancel:${randomUUID()}` });
-            return new Response(null, { status: 204 });
+            if (!allowed.has(agentId))
+                throw new Problem(404, "Not found");
+            const subject = await subjectOf(request);
+            const query = new URL(request.url).search;
+            return await forward(request, subject, `/${segment(agentId)}/threads/${segment(threadId)}/${action}${query}`, init);
         }
         catch (error) {
             const failure = problemOf(error);
             return problem(failure.status, failure.message, failure.code);
         }
     }
+    const history = (request, agentId, threadId) => thread(request, agentId, threadId, "messages", { method: "GET" });
+    const reattach = (request, agentId, threadId) => {
+        const cursor = request.headers.get("last-event-id");
+        return thread(request, agentId, threadId, "events", {
+            method: "GET",
+            headers: {
+                accept: "text/event-stream",
+                ...(cursor ? { "last-event-id": cursor } : {}),
+            },
+        });
+    };
+    const cancel = (request, agentId, threadId) => thread(request, agentId, threadId, "cancel", { method: "POST" });
     async function route(request) {
         const path = new URL(request.url).pathname;
         if (path !== base && !path.startsWith(`${base}/`))
@@ -359,12 +168,12 @@ export function createAgUiHandler(options) {
                 .slice(base.length)
                 .split("/")
                 .slice(1)
-                .map((segment) => decodeURIComponent(segment));
+                .map((part) => decodeURIComponent(part));
         }
         catch {
             return problem(404, "Not found");
         }
-        if (segments.some((segment) => segment === ""))
+        if (segments.some((part) => part === ""))
             return problem(404, "Not found");
         const [agentId, threads, threadId, action] = segments;
         const method = request.method.toUpperCase();
@@ -392,6 +201,3 @@ export function createAgUiHandler(options) {
     }
     return { fetch: route, run, history, reattach, cancel };
 }
-async function* iterate(items) {
-    yield* items;
-}

package/dist/ag-ui/index.d.ts

@@ -1,6 +1,7 @@
 /**
  * `@nylorun/agents/ag-ui`: serve the Tenant's agents to AG-UI clients from the app's own
- * server. The only entry point that loads `@ag-ui/core`.
+ * server. The handler forwards to the Runtime's AG-UI endpoint for each signed-in person; it
+ * loads no AG-UI package itself.
  */
 export { createAgUiHandler } from "./handler.js";
 export type { AgUiHandler, AgUiHandlerOptions, AgUiSessionOptions, } from "./handler.js";

package/dist/ag-ui/index.js

@@ -1,6 +1,7 @@
 /**
  * `@nylorun/agents/ag-ui`: serve the Tenant's agents to AG-UI clients from the app's own
- * server. The only entry point that loads `@ag-ui/core`.
+ * server. The handler forwards to the Runtime's AG-UI endpoint for each signed-in person; it
+ * loads no AG-UI package itself.
  */
 export { createAgUiHandler } from "./handler.js";
 export { toNodeListener } from "./node.js";

package/dist/browser.d.ts

@@ -0,0 +1,97 @@
+import type { CredentialSelection, VaultInfo } from "@nylorun/core/contracts";
+import type { TokenSource } from "./http.js";
+import { AgentsClient, type SessionClient } from "./session-client.js";
+/** What the token callback returns: the token, or the app server's `{ token, expiresAt }`. */
+export type TokenReply = string | {
+    token: string;
+    expiresAt?: string;
+};
+export interface BrowserClientOptions {
+    /** The Runtime's URL, as the page reaches it. */
+    url: string;
+    /** The Tenant's publishable key for this app (`nr_pub_…`). */
+    publishableKey: string;
+    /** Returns a subject token for the signed-in person, usually from your app server. */
+    token(signal?: AbortSignal): Promise<TokenReply>;
+    fetch?: typeof fetch;
+}
+interface Claims {
+    sub?: string;
+    exp?: number;
+}
+/** The token's claims, read without verifying (the Runtime verifies). */
+export declare function readClaims(token: string): Claims;
+/** A token kept in memory, fetched on demand, one fetch at a time. */
+export declare class CachedToken implements TokenSource {
+    private readonly fetchToken;
+    private readonly now;
+    private current;
+    private pending;
+    constructor(fetchToken: (signal?: AbortSignal) => Promise<TokenReply>, now?: () => number);
+    get(signal?: AbortSignal): Promise<string>;
+    invalidate(): void;
+    /** The subject of the current token, fetching one if needed. */
+    subject(signal?: AbortSignal): Promise<string>;
+}
+/** The signed-in person's view of the Runtime: their sessions and vaults, the agents they may use. */
+export declare class BrowserClient {
+    /** The underlying Tenant API client, for anything this class does not wrap. */
+    readonly client: AgentsClient;
+    readonly url: string;
+    readonly publishableKey: string;
+    private readonly tokens;
+    private readonly fetcher;
+    constructor(options: BrowserClientOptions);
+    /** The person the tokens are for. */
+    subject(signal?: AbortSignal): Promise<string>;
+    /** A current token, e.g. for a request this client does not make itself. */
+    token(signal?: AbortSignal): Promise<string>;
+    /** The agents the person may use: id, name and description. */
+    listAgents(signal?: AbortSignal): Promise<{
+        agents: {
+            agentId: string;
+            name?: string;
+            description?: string;
+        }[];
+    }>;
+    listSessions(agentId?: string, signal?: AbortSignal): Promise<{
+        sessions: import("./session-client.js").SessionView[];
+    }>;
+    session(sessionId: string): SessionClient;
+    /** A session of the person's own; the owner is always the token's subject. */
+    createSession(options: {
+        id?: string;
+        agentId: string;
+        vaultIds?: readonly string[];
+        credentialSelections?: readonly CredentialSelection[];
+    }): Promise<SessionClient>;
+    createVault(options: {
+        name: string;
+        idempotencyKey: string;
+        metadata?: Record<string, string>;
+    }): Promise<VaultInfo>;
+    listVaults(signal?: AbortSignal): Promise<{
+        vaults: VaultInfo[];
+    }>;
+    /** `fetch` with this client's credentials, retrying once after `401 token_expired`. */
+    private send;
+    /**
+     * For `@ag-ui/client`'s `HttpAgent`: `new HttpAgent({ url, fetch })`. The `fetch` adds the
+     * publishable key and a current token, and when the Runtime ends a run's stream because the
+     * token expired or was revoked, it reattaches with a new token from the last event, so the
+     * agent sees one run.
+     */
+    agUi(agentId: string): {
+        url: string;
+        fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    };
+    /** The thread's messages, for `HttpAgent`'s `initialMessages`. */
+    agUiHistory(agentId: string, threadId: string, signal?: AbortSignal): Promise<unknown[]>;
+    /**
+     * Passes a run's frames through; on `nylorun.stream_closed` before the run finished, fetches
+     * the rest from the last event id and continues without repeating `RUN_STARTED`.
+     */
+    private stitch;
+}
+export declare function createBrowserClient(options: BrowserClientOptions): BrowserClient;
+export {};