@nylorun/agents 0.13.0-beta → 0.16.0-beta

package/dist/browser.js

@@ -1,281 +0,0 @@
-/**
- * `@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);
-    }
-    /** The person's file artifacts, in their own sessions (protocol 6). */
-    get artifacts() {
-        return this.client.artifacts;
-    }
-    /** 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/delivery-token.d.ts

@@ -1,62 +0,0 @@
-/** The claims of a verified delivery token. */
-export interface DeliveryClaims {
-    readonly iss: string;
-    readonly aud: string;
-    /** The Action id, or `ping`. */
-    readonly sub: string;
-    /** The agent or workflow the Action belongs to. */
-    readonly agt: string;
-    /** The delivery's generation; `0` for a ping. */
-    readonly gen: number;
-    /** base64url SHA-256 of the request body. */
-    readonly bdy: string;
-    readonly iat: number;
-    readonly exp: number;
-    readonly jti: string;
-}
-/** Why a delivery was refused; `code` is sent back to the Runtime. */
-export declare class DeliveryVerificationError extends Error {
-    readonly code: "signature_missing" | "signature_invalid" | "key_unknown" | "token_expired";
-    readonly name = "DeliveryVerificationError";
-    constructor(code: "signature_missing" | "signature_invalid" | "key_unknown" | "token_expired", message: string);
-}
-/** Finds the public key for a `kid`, or `undefined` when the Tenant has none. */
-export type KeyLookup = (kid: string) => Promise<CryptoKey | undefined>;
-/**
- * Verifies `token` against `body`. The keys are the installation's, so a valid signature already
- * binds the issuer to its one Tenant: any `urn:nylorun:tenant:<id>` issuer is accepted (and
- * returned in `iss`) unless `tenantId` names the one expected.
- */
-export declare function verifyDeliveryToken(token: string | null, options: {
-    keys: KeyLookup;
-    /** When set, `iss` must name this Tenant. */
-    tenantId?: string;
-    body: Uint8Array;
-    /** When set, `aud` must equal it: the URL this endpoint was registered with. */
-    audience?: string;
-    now?: number;
-}): Promise<DeliveryClaims>;
-/** base64url SHA-256 of `body`: the token's `bdy` claim. */
-export declare function bodyHash(body: Uint8Array): Promise<string>;
-/**
- * The Tenant's public keys, fetched from `GET /v1/access/jwks` and cached by `kid`. An
- * unknown `kid` refetches once, at most every `refetchMs`, so forged tokens cannot make the
- * endpoint call the Runtime on every request. Concurrent lookups share one in-flight fetch.
- */
-export declare class JwksCache {
-    private readonly source;
-    private readonly refetchMs;
-    private readonly keys;
-    private lastFetch;
-    private pending;
-    constructor(source: {
-        url: string;
-        key?: string;
-        fetch?: typeof fetch;
-    } | {
-        keys: readonly JsonWebKey[];
-    }, refetchMs?: number);
-    readonly lookup: KeyLookup;
-    private load;
-    private fetchKeys;
-}

package/dist/delivery-token.js

@@ -1,159 +0,0 @@
-/**
- * Verifies the delivery token on a request the Runtime sends to an Action endpoint: an ES256
- * JWT signed with the Tenant's current signing key (design: Action endpoints §8.1). WebCrypto
- * only, so the SDK takes no JWT dependency: a JWS ES256 signature is the raw `r || s` pair
- * WebCrypto's ECDSA verifies.
- */
-import { PROTOCOL_HEADER, PROTOCOL_VERSION, isTenantId } from "@nylorun/core/compatibility";
-import { DELIVERY_TOKEN_TYPE, subjectTokenIssuer } from "@nylorun/core/contracts";
-/** The issuer prefix of a Tenant's tokens: `urn:nylorun:tenant:<tenantId>`. */
-const ISSUER_PREFIX = subjectTokenIssuer("");
-/** Why a delivery was refused; `code` is sent back to the Runtime. */
-export class DeliveryVerificationError extends Error {
-    code;
-    name = "DeliveryVerificationError";
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-    }
-}
-/** Clock skew tolerated on `iat` and `exp`, in seconds. */
-const SKEW_SECONDS = 30;
-const FORBIDDEN_HEADERS = ["jku", "jwk", "x5u", "x5c", "x5t", "x5t#S256", "crit"];
-/** The largest token accepted: well above a real one, well below a request limit. */
-const MAX_TOKEN_LENGTH = 4096;
-/**
- * Verifies `token` against `body`. The keys are the installation's, so a valid signature already
- * binds the issuer to its one Tenant: any `urn:nylorun:tenant:<id>` issuer is accepted (and
- * returned in `iss`) unless `tenantId` names the one expected.
- */
-export async function verifyDeliveryToken(token, options) {
-    if (!token)
-        throw new DeliveryVerificationError("signature_missing", "No delivery token");
-    const parts = token.length <= MAX_TOKEN_LENGTH ? token.split(".") : [];
-    if (parts.length !== 3)
-        throw invalid("Not a compact JWS");
-    const [encodedHeader, encodedPayload, encodedSignature] = parts;
-    const header = json(encodedHeader);
-    if (header.alg !== "ES256" ||
-        header.typ !== DELIVERY_TOKEN_TYPE ||
-        typeof header.kid !== "string" ||
-        FORBIDDEN_HEADERS.some((name) => name in header))
-        throw invalid("Unexpected token header");
-    const key = await options.keys(header.kid);
-    if (!key)
-        throw new DeliveryVerificationError("key_unknown", `Unknown signing key ${header.kid}`);
-    const signed = await crypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, key, bytes(base64url(encodedSignature)), new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`));
-    if (!signed)
-        throw invalid("Bad signature");
-    const claims = json(encodedPayload);
-    if (typeof claims.iss !== "string" ||
-        typeof claims.aud !== "string" ||
-        typeof claims.sub !== "string" ||
-        typeof claims.agt !== "string" ||
-        !Number.isInteger(claims.gen) ||
-        typeof claims.bdy !== "string" ||
-        typeof claims.iat !== "number" ||
-        typeof claims.exp !== "number" ||
-        typeof claims.jti !== "string")
-        throw invalid("Missing claims");
-    if (!claims.iss.startsWith(ISSUER_PREFIX) ||
-        !isTenantId(claims.iss.slice(ISSUER_PREFIX.length)))
-        throw invalid("The token was not issued by a Tenant");
-    if (options.tenantId !== undefined && claims.iss !== subjectTokenIssuer(options.tenantId))
-        throw invalid("The token is for another Tenant");
-    if (options.audience !== undefined && claims.aud !== options.audience)
-        throw invalid(`The token is for ${claims.aud}, not ${options.audience}`);
-    const now = (options.now ?? Date.now()) / 1000;
-    if (claims.exp < now - SKEW_SECONDS || claims.iat > now + SKEW_SECONDS)
-        throw new DeliveryVerificationError("token_expired", "The delivery token has expired");
-    if (claims.bdy !== (await bodyHash(options.body)))
-        throw invalid("The body does not match the token");
-    return claims;
-}
-/** base64url SHA-256 of `body`: the token's `bdy` claim. */
-export async function bodyHash(body) {
-    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes(body)));
-    return Buffer.from(digest).toString("base64url");
-}
-/**
- * The Tenant's public keys, fetched from `GET /v1/access/jwks` and cached by `kid`. An
- * unknown `kid` refetches once, at most every `refetchMs`, so forged tokens cannot make the
- * endpoint call the Runtime on every request. Concurrent lookups share one in-flight fetch.
- */
-export class JwksCache {
-    source;
-    refetchMs;
-    keys = new Map();
-    lastFetch = 0;
-    pending;
-    constructor(source, refetchMs = 5000) {
-        this.source = source;
-        this.refetchMs = refetchMs;
-    }
-    lookup = async (kid) => {
-        const known = this.keys.get(kid);
-        if (known)
-            return known;
-        // Wait for an in-flight fetch: stamping the cooldown at the start of `load` used
-        // to make a concurrent ping (register + smoke, or tsx watch restart) answer
-        // `key_unknown` before the keys arrived.
-        if (this.pending) {
-            await this.pending;
-            return this.keys.get(kid);
-        }
-        if (Date.now() - this.lastFetch < this.refetchMs && this.lastFetch > 0)
-            return undefined;
-        await (this.pending ??= this.load().finally(() => (this.pending = undefined)));
-        return this.keys.get(kid);
-    };
-    async load() {
-        const keys = "keys" in this.source ? this.source.keys : await this.fetchKeys(this.source);
-        this.lastFetch = Date.now();
-        for (const jwk of keys) {
-            const kid = jwk.kid;
-            if (typeof kid !== "string" || jwk.kty !== "EC" || jwk.crv !== "P-256")
-                continue;
-            if (this.keys.has(kid))
-                continue;
-            this.keys.set(kid, await crypto.subtle.importKey("jwk", { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y }, { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"]));
-        }
-    }
-    async fetchKeys(source) {
-        const headers = {
-            [PROTOCOL_HEADER]: String(PROTOCOL_VERSION),
-        };
-        if (source.key)
-            headers.Authorization = `Bearer ${source.key}`;
-        const response = await (source.fetch ?? globalThis.fetch)(`${source.url.replace(/\/$/, "")}/v1/access/jwks`, { headers, redirect: "error", signal: AbortSignal.timeout(10_000) });
-        if (!response.ok) {
-            await response.body?.cancel();
-            throw new Error(`The Runtime answered ${response.status} for its public keys (GET /v1/access/jwks)`);
-        }
-        const body = (await response.json());
-        return Array.isArray(body.keys) ? body.keys : [];
-    }
-}
-function invalid(message) {
-    return new DeliveryVerificationError("signature_invalid", message);
-}
-function base64url(value) {
-    return new Uint8Array(Buffer.from(value, "base64url"));
-}
-/** A copy backed by a plain `ArrayBuffer`, which WebCrypto's types require. */
-function bytes(value) {
-    const copy = new Uint8Array(value.byteLength);
-    copy.set(value);
-    return copy;
-}
-function json(segment) {
-    try {
-        const value = JSON.parse(Buffer.from(segment, "base64url").toString("utf8"));
-        if (value && typeof value === "object" && !Array.isArray(value))
-            return value;
-    }
-    catch {
-        /* fall through */
-    }
-    throw invalid("Malformed token");
-}

package/dist/execute-action.d.ts

@@ -1,16 +0,0 @@
-import { type BuiltAgent, type BuiltWorkflow } from "@nylorun/core/define";
-import type { Action, ActionOutcome } from "@nylorun/core/contracts";
-import type { ActionSandbox } from "./sandbox/client.js";
-export type ExecutableDefinition = BuiltAgent | BuiltWorkflow;
-export type ExecuteActionOptions = {
-    /** Claim-scoped sandbox client; omitted when the session has no sandbox. */
-    readonly sandbox?: ActionSandbox;
-};
-/** Executes code only after a host-issued claim. No engine dependency. */
-export declare function executeAction(action: Action, root: ExecutableDefinition, signal: AbortSignal, options?: ExecuteActionOptions): Promise<ActionOutcome>;
-/**
- * True when `action` runs a tool marked `background` (`ToolDefinition.background`): an Action
- * endpoint answers its delivery at once and posts the outcome later. False for anything it
- * cannot find; `executeAction` reports those.
- */
-export declare function runsInBackground(action: Action, root: ExecutableDefinition): boolean;