@nylorun/agents 0.9.0-beta → 0.10.0-beta

package/dist/browser.js

@@ -0,0 +1,277 @@
+/**
+ * `@nylorun/agents/browser`: a Runtime client for browsers and apps that hold no Tenant key
+ * (Host features `subject-tokens` and `browser-access`). The page ships a publishable key; the
+ * app server's token route returns a subject token for the signed-in person; the client keeps
+ * it in memory, fetches a new one a minute before it expires or when the Runtime answers
+ * `401 token_expired`, and never asks for two at once.
+ *
+ * No Node-only module is imported here or below.
+ */
+import { PROTOCOL_HEADER, PROTOCOL_VERSION, PUBLISHABLE_KEY_HEADER, } from "@nylorun/core/compatibility";
+import { AgentsClient } from "./session-client.js";
+/** Fetch a new token this long before the current one expires. */
+const REFRESH_EARLY_MS = 60_000;
+/** The token's claims, read without verifying (the Runtime verifies). */
+export function readClaims(token) {
+    const payload = token.split(".")[1];
+    if (!payload)
+        return {};
+    try {
+        const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+        const json = new TextDecoder().decode(Uint8Array.from(atob(padded), (c) => c.charCodeAt(0)));
+        return JSON.parse(json);
+    }
+    catch {
+        return {};
+    }
+}
+/** A token kept in memory, fetched on demand, one fetch at a time. */
+export class CachedToken {
+    fetchToken;
+    now;
+    current;
+    pending;
+    constructor(fetchToken, now = Date.now) {
+        this.fetchToken = fetchToken;
+        this.now = now;
+    }
+    get(signal) {
+        if (this.current && this.current.expiresAt - REFRESH_EARLY_MS > this.now())
+            return Promise.resolve(this.current.token);
+        this.pending ??= this.fetchToken(signal)
+            .then((reply) => {
+            const token = typeof reply === "string" ? reply : reply.token;
+            if (typeof token !== "string" || token === "")
+                throw new Error("The token callback returned no token");
+            const expiresAt = typeof reply !== "string" && reply.expiresAt
+                ? Date.parse(reply.expiresAt)
+                : (readClaims(token).exp ?? 0) * 1000;
+            this.current = { token, expiresAt };
+            return token;
+        })
+            .finally(() => {
+            this.pending = undefined;
+        });
+        return this.pending;
+    }
+    invalidate() {
+        this.current = undefined;
+    }
+    /** The subject of the current token, fetching one if needed. */
+    async subject(signal) {
+        const sub = readClaims(await this.get(signal)).sub;
+        if (!sub)
+            throw new Error("The subject token names no subject");
+        return sub;
+    }
+}
+/** Reattaching a run the Runtime ended for its token, at most this many times in a row. */
+const MAX_REATTACH = 5;
+function parseFrame(text) {
+    let id;
+    let data;
+    for (const line of text.split("\n")) {
+        if (line.startsWith("id: "))
+            id = line.slice(4);
+        else if (line.startsWith("data: "))
+            data = line.slice(6);
+    }
+    let event;
+    try {
+        event = data === undefined ? undefined : JSON.parse(data);
+    }
+    catch {
+        event = undefined;
+    }
+    return { text, ...(id ? { id } : {}), ...(event ? { event } : {}) };
+}
+/** The frames of an SSE body, as they arrive. */
+async function* frames(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
+            let end;
+            while ((end = buffer.indexOf("\n\n")) >= 0) {
+                const text = buffer.slice(0, end);
+                buffer = buffer.slice(end + 2);
+                if (text.trim() !== "")
+                    yield parseFrame(text);
+            }
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+}
+/** The signed-in person's view of the Runtime: their sessions and vaults, the agents they may use. */
+export class BrowserClient {
+    /** The underlying Tenant API client, for anything this class does not wrap. */
+    client;
+    url;
+    publishableKey;
+    tokens;
+    fetcher;
+    constructor(options) {
+        this.url = options.url.replace(/\/$/, "");
+        this.publishableKey = options.publishableKey;
+        this.tokens = new CachedToken((signal) => options.token(signal));
+        const base = options.fetch ?? globalThis.fetch;
+        // Called as a method, a page's window.fetch would lose its receiver.
+        this.fetcher = options.fetch ? base : (input, init) => base(input, init);
+        this.client = new AgentsClient({
+            url: this.url,
+            publishableKey: options.publishableKey,
+            token: this.tokens,
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+        });
+    }
+    /** The person the tokens are for. */
+    subject(signal) {
+        return this.tokens.subject(signal);
+    }
+    /** A current token, e.g. for a request this client does not make itself. */
+    token(signal) {
+        return this.tokens.get(signal);
+    }
+    /** The agents the person may use: id, name and description. */
+    listAgents(signal) {
+        return this.client.listAgents({ ...(signal ? { signal } : {}) });
+    }
+    listSessions(agentId, signal) {
+        return this.client.listSessions({
+            ...(agentId ? { agentId } : {}),
+            ...(signal ? { signal } : {}),
+        });
+    }
+    session(sessionId) {
+        return this.client.session(sessionId);
+    }
+    /** A session of the person's own; the owner is always the token's subject. */
+    async createSession(options) {
+        return this.client.createSession({
+            ...options,
+            ownerUserId: await this.subject(),
+        });
+    }
+    async createVault(options) {
+        return this.client.createVault({ ...options, ownerUserId: await this.subject() });
+    }
+    async listVaults(signal) {
+        return this.client.listVaults(await this.subject(signal), signal);
+    }
+    /** `fetch` with this client's credentials, retrying once after `401 token_expired`. */
+    async send(input, init = {}, retried = false) {
+        const headers = new Headers(init.headers);
+        headers.set("authorization", `Bearer ${await this.tokens.get(init.signal ?? undefined)}`);
+        headers.set(PUBLISHABLE_KEY_HEADER, this.publishableKey);
+        headers.set(PROTOCOL_HEADER, String(PROTOCOL_VERSION));
+        const response = await this.fetcher(input, { ...init, headers });
+        if (response.status !== 401 || retried)
+            return response;
+        const body = (await response.clone().json().catch(() => undefined));
+        if (body?.code !== "token_expired")
+            return response;
+        await response.body?.cancel().catch(() => { });
+        this.tokens.invalidate();
+        return this.send(input, init, true);
+    }
+    /**
+     * 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) {
+        const url = `${this.url}/v1/ag-ui/agents/${encodeURIComponent(agentId)}`;
+        const fetchRun = async (input, init = {}) => {
+            const target = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+            const response = await this.send(target, init);
+            const isStream = response.headers.get("content-type")?.includes("text/event-stream");
+            const method = (init.method ?? "GET").toUpperCase();
+            if (!response.ok || !isStream || !response.body || method !== "POST" || target !== url)
+                return response;
+            let run = {};
+            try {
+                run = JSON.parse(String(init.body ?? "{}"));
+            }
+            catch {
+                /* not a RunAgentInput: pass the stream through as it is */
+            }
+            if (!run.threadId)
+                return response;
+            return new Response(this.stitch(response.body, url, run.threadId, run.runId, init.signal ?? undefined), {
+                status: response.status,
+                headers: response.headers,
+            });
+        };
+        return { url, fetch: fetchRun };
+    }
+    /** The thread's messages, for `HttpAgent`'s `initialMessages`. */
+    async agUiHistory(agentId, threadId, signal) {
+        const response = await this.send(`${this.url}/v1/ag-ui/agents/${encodeURIComponent(agentId)}/threads/${encodeURIComponent(threadId)}/messages`, { method: "GET", ...(signal ? { signal } : {}) });
+        if (!response.ok)
+            throw new Error(`Runtime HTTP ${response.status}`);
+        return (await response.json());
+    }
+    /**
+     * 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`.
+     */
+    stitch(body, url, threadId, runId, signal) {
+        const encoder = new TextEncoder();
+        const self = this;
+        return new ReadableStream({
+            async start(controller) {
+                let lastId;
+                let source = body;
+                let reattaching = false;
+                try {
+                    for (let attempt = 0; source && attempt <= MAX_REATTACH; attempt += 1) {
+                        let closed = false;
+                        for await (const frame of frames(source)) {
+                            if (frame.event?.type === "CUSTOM" && frame.event.name === "nylorun.stream_closed") {
+                                if (frame.id)
+                                    lastId = frame.id;
+                                closed = true;
+                                break;
+                            }
+                            // The reattached stream starts its run again; the agent already has it.
+                            if (reattaching && frame.event?.type === "RUN_STARTED")
+                                continue;
+                            if (frame.id)
+                                lastId = frame.id;
+                            controller.enqueue(encoder.encode(`${frame.text}\n\n`));
+                        }
+                        source = null;
+                        if (!closed || !lastId || signal?.aborted)
+                            break;
+                        reattaching = true;
+                        const query = runId ? `?runId=${encodeURIComponent(runId)}` : "";
+                        const next = await self.send(`${url}/threads/${encodeURIComponent(threadId)}/events${query}`, {
+                            method: "GET",
+                            headers: { accept: "text/event-stream", "last-event-id": lastId },
+                            ...(signal ? { signal } : {}),
+                        });
+                        // 204: the run ended with nothing after the last event; there is no more to send.
+                        if (next.ok && next.status !== 204 && next.body)
+                            source = next.body;
+                    }
+                    controller.close();
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+        });
+    }
+}
+export function createBrowserClient(options) {
+    return new BrowserClient(options);
+}

package/dist/client.d.ts

@@ -1,230 +1,6 @@
-import type { AgentManifest, BuiltAgent, BuiltWorkflow, JsonValue, SandboxToolName, WorkflowManifest } from "@nylorun/core/define";
-import { type SubjectScope, type CredentialInfo, type CredentialSelection, type SessionCommand, type VaultInfo } from "@nylorun/core/contracts";
-import { Transport, type Destination } from "./http.js";
-/** Application-principal access to a session's sandbox built-ins (workflows.md §8). */
-export type SessionSandbox = {
-    readonly [K in SandboxToolName]: (args: Record<string, unknown>) => Promise<unknown>;
-};
-export interface AgentSource {
-    readonly id: string;
-    readonly manifest: AgentManifest | WorkflowManifest;
-    build?(): BuiltAgent | BuiltWorkflow;
-    getBinding?: BuiltAgent["getBinding"] | BuiltWorkflow["getBinding"];
-}
-/** Closures stay on the live binding. The published manifest cannot name them. */
-export declare function assertNoMiddlewareClosures(agent: AgentSource): void;
-export interface SessionView {
-    id: string;
-    agentId: string;
-    ownerUserId: string;
-    status: string;
-    activeTurnId: string | null;
-    waits?: unknown;
-    [key: string]: unknown;
-}
-export interface ActAsOptions {
-    /** What the subject may do; the Runtime grants nothing else. Default `["sessions:own"]`. */
-    scopes?: readonly SubjectScope[];
-}
-export declare class AgentsClient {
-    readonly transport: Transport;
-    /** The subject this client acts for (`as`), or `undefined` for the principal itself. */
-    readonly subject: string | undefined;
-    constructor(destination?: Destination);
-    /**
-     * A client that acts for `subject`: every call sends `Nylorun-Subject` and
-     * `Nylorun-Scopes`, and the Runtime limits it to the scopes and to the subject's own sessions
-     * and vaults (Host feature `subject-headers`). For app servers, which authenticate the person
-     * themselves and hold the key; nothing is minted, cached or refreshed.
-     */
-    as(subject: string, options?: ActAsOptions): AgentsClient;
-    /** The Runtime's protocol features, including optional ones such as `transcript-events`. */
-    hostFeatures(options?: {
-        signal?: AbortSignal;
-    }): Promise<readonly string[]>;
-    listAgents(options?: {
-        signal?: AbortSignal;
-    }): Promise<{
-        agents: {
-            manifest: AgentManifest;
-        }[];
-    }>;
-    listSessions(options?: {
-        agentId?: string;
-        signal?: AbortSignal;
-    }): Promise<{
-        sessions: SessionView[];
-    }>;
-    saveAgent(agent: AgentSource | BuiltWorkflow, options: {
-        implementationVersion: string;
-        requestId?: string;
-    }): Promise<unknown>;
-    createSession(options: {
-        id?: string;
-        agentId: string;
-        ownerUserId: string;
-        info?: Record<string, unknown>;
-        requestId?: string;
-        vaultIds?: readonly string[];
-        credentialSelections?: readonly CredentialSelection[];
-        /** Share another session's sandbox (public PutSession.sandbox). */
-        sandbox?: {
-            session: string;
-        };
-    }): Promise<SessionClient>;
-    createVault(options: {
-        name: string;
-        ownerUserId: string;
-        metadata?: Record<string, string>;
-        idempotencyKey: string;
-        requestId?: string;
-    }): Promise<VaultInfo>;
-    listVaults(ownerUserId: string, signal?: AbortSignal): Promise<{
-        vaults: VaultInfo[];
-    }>;
-    getVault(vaultId: string, signal?: AbortSignal): Promise<VaultInfo>;
-    deleteVault(vaultId: string): Promise<{
-        id: string;
-    }>;
-    createCredential(vaultId: string, options: {
-        name: string;
-        idempotencyKey: string;
-        requestId?: string;
-        auth: {
-            type: "bearer";
-            url: string;
-            token: string;
-        } | {
-            type: "oauth";
-            url: string;
-            accessToken: string;
-            expiresAt?: string | null;
-            refresh?: {
-                tokenEndpoint: string;
-                clientId: string;
-                refreshToken: string;
-                tokenEndpointAuth: {
-                    type: "none";
-                } | {
-                    type: "client_secret_basic";
-                    clientSecret: string;
-                } | {
-                    type: "client_secret_post";
-                    clientSecret: string;
-                };
-            };
-        };
-    }): Promise<CredentialInfo>;
-    listCredentials(vaultId: string, signal?: AbortSignal): Promise<{
-        credentials: CredentialInfo[];
-    }>;
-    getCredential(vaultId: string, credentialId: string, signal?: AbortSignal): Promise<CredentialInfo>;
-    rotateCredential(vaultId: string, credentialId: string, options: {
-        idempotencyKey: string;
-        requestId?: string;
-        auth: {
-            type: "bearer";
-            token: string;
-        } | {
-            type: "oauth";
-            accessToken: string;
-            expiresAt?: string | null;
-        };
-    }): Promise<CredentialInfo>;
-    deleteCredential(vaultId: string, credentialId: string): Promise<{
-        id: string;
-    }>;
-    session(sessionId: string): SessionClient;
-}
-export type CommandOptions = {
-    idempotencyKey: string;
-    requestId?: string;
-    signal?: AbortSignal;
-};
-export declare class SessionClient {
-    private readonly transport;
-    readonly id: string;
-    readonly sandbox: SessionSandbox;
-    constructor(transport: Transport, id: string);
-    private get path();
-    inspect(signal?: AbortSignal): Promise<SessionView>;
-    /** Pending waits / interactions from the session inspect view. */
-    pending(signal?: AbortSignal): Promise<{}>;
-    command(command: SessionCommand, signal?: AbortSignal): Promise<{
-        status: "accepted";
-        turnId: string | null;
-        cursor: string | null;
-        requestId: string;
-    }>;
-    /**
-     * Start a turn. Strings become `message.content`; any other JSON value becomes
-     * `message.data` (workflows.md §5).
-     */
-    input(value: string | JsonValue, options: CommandOptions): Promise<{
-        status: "accepted";
-        turnId: string | null;
-        cursor: string | null;
-        requestId: string;
-    }>;
-    approve(interactionId: string, approved: boolean, options: CommandOptions): Promise<{
-        status: "accepted";
-        turnId: string | null;
-        cursor: string | null;
-        requestId: string;
-    }>;
-    respond(interactionId: string, value: JsonValue, options: CommandOptions): Promise<{
-        status: "accepted";
-        turnId: string | null;
-        cursor: string | null;
-        requestId: string;
-    }>;
-    cancel(options: CommandOptions & {
-        reason?: string;
-    }): Promise<{
-        status: "accepted";
-        turnId: string | null;
-        cursor: string | null;
-        requestId: string;
-    }>;
-    /** `agent` narrows to one agent used as a tool: its delegationId or its path. */
-    history(options?: {
-        cursor?: string;
-        agent?: string;
-        signal?: AbortSignal;
-    }): Promise<{
-        items: {
-            eventId: string;
-            sessionId: string;
-            tenantId: string;
-            turnId: string | null;
-            cursor: string;
-            createdAt: string;
-            type: string;
-            payload: unknown;
-        }[];
-        cursor: string | null;
-    }>;
-    observe(options?: {
-        cursor?: string;
-        signal?: AbortSignal;
-        follow?: boolean;
-    }): AsyncGenerator<{
-        eventId: string;
-        sessionId: string;
-        tenantId: string;
-        turnId: string | null;
-        cursor: string;
-        createdAt: string;
-        type: string;
-        payload: unknown;
-    }, void, unknown>;
-    private observeOne;
-    /**
-     * Own session stream plus linked agent sessions announced in `node.agent`
-     * events, merged by `createdAt` then arrival order (workflows.md §11).
-     */
-    private observeFollowing;
-}
+export * from "./session-client.js";
+import { AgentsClient } from "./session-client.js";
+import type { Destination } from "./http.js";
 /**
  * Build a Tenant API client.
  * Explicit connection fields keep today's sync Transport resolution (including
@@ -233,6 +9,3 @@ export declare class SessionClient {
  */
 export declare function createClient(destination: Destination): AgentsClient;
 export declare function createClient(destination?: undefined): Promise<AgentsClient>;
-export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
-export type { Destination, IncompatibleReason } from "./http.js";
-export type { LiveEvent } from "@nylorun/core/contracts";