@nylorun/agents 0.9.0-beta → 0.11.0-beta

package/dist/a2a/handler.js

@@ -0,0 +1,178 @@
+import { createClient } from "../client.js";
+import { IncompatibleRuntimeError, RuntimeError } from "../http.js";
+/** The Host feature the handler forwards to. */
+const REQUIRED_FEATURE = "a2a-endpoint";
+/** A2A callers run tasks in their own sessions; nothing else. */
+const SCOPES = ["sessions:own"];
+const CARD_PATH = [".well-known", "agent-card.json"];
+class Problem extends Error {
+    status;
+    code;
+    headers;
+    constructor(status, message, code, headers = {}) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.headers = headers;
+    }
+}
+function problem(failure) {
+    return Response.json({ error: failure.message, ...(failure.code ? { code: failure.code } : {}) }, { status: failure.status, headers: failure.headers });
+}
+function problemOf(error) {
+    if (error instanceof Problem)
+        return error;
+    if (error instanceof IncompatibleRuntimeError)
+        return new Problem(502, error.message, "runtime_incompatible");
+    if (error instanceof RuntimeError && error.status === 404)
+        return new Problem(404, "Not found");
+    return new Problem(502, "The agent service failed", "runtime_error");
+}
+function normalizeBase(basePath = "/") {
+    const trimmed = basePath.replace(/\/+$/, "");
+    return trimmed === "" ? "" : trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+export function createA2aHandler(options) {
+    const allowed = new Set(options.agents.map((agent) => (typeof agent === "string" ? agent : agent.id)));
+    const base = normalizeBase(options.basePath);
+    const publicUrl = options.publicUrl?.replace(/\/+$/, "");
+    if (publicUrl !== undefined && !/^https?:\/\//.test(publicUrl))
+        throw new TypeError("createA2aHandler: publicUrl must be an http(s) URL");
+    let ready;
+    /** The client, once the Runtime is known to serve A2A. Retries after a failure. */
+    function connected() {
+        ready ??= (async () => {
+            const client = await (options.client ?? createClient());
+            const features = await client.hostFeatures();
+            if (!features.includes(REQUIRED_FEATURE))
+                throw new Problem(502, `The Runtime does not support ${REQUIRED_FEATURE}; upgrade the stack (nylorun up).`, "runtime_feature_missing");
+            return client;
+        })();
+        ready.catch(() => {
+            ready = undefined;
+        });
+        return ready;
+    }
+    const runtimePath = (agentId) => `/v1/a2a/agents/${encodeURIComponent(agentId)}`;
+    async function callerOf(request, agentId) {
+        const found = await options.subject(request);
+        if (!found)
+            throw new Problem(401, "Authentication required");
+        const caller = typeof found === "string" ? { subject: found } : found;
+        // An agent this partner may not use is the same 404 as one that does not exist.
+        if (caller.agents !== undefined && !caller.agents.includes(agentId))
+            throw new Problem(404, "Not found");
+        return caller.subject;
+    }
+    async function call(request, agentId) {
+        try {
+            if (!allowed.has(agentId))
+                throw new Problem(404, "Not found");
+            const subject = await callerOf(request, agentId);
+            const client = await connected();
+            let runtime;
+            try {
+                runtime = client.as(subject, { scopes: SCOPES });
+            }
+            catch (error) {
+                // The host's `subject` returned something the Runtime cannot name (see `as`).
+                throw new Problem(500, error.message, "subject_invalid");
+            }
+            const headers = {};
+            const version = request.headers.get("a2a-version") ??
+                new URL(request.url).searchParams.get("A2A-Version");
+            if (version !== null)
+                headers["A2A-Version"] = version;
+            const extensions = request.headers.get("a2a-extensions");
+            if (extensions !== null)
+                headers["A2A-Extensions"] = extensions;
+            const response = await runtime.transport.forward(runtimePath(agentId), {
+                method: "POST",
+                body: await request.text(),
+                headers,
+                signal: request.signal,
+            });
+            if (response.ok)
+                return new Response(response.body, {
+                    status: response.status,
+                    headers: { "content-type": response.headers.get("content-type") ?? "application/json" },
+                });
+            await response.body?.cancel().catch(() => { });
+            if (response.status === 404)
+                throw new Problem(404, "Not found");
+            if (response.status === 429)
+                throw new Problem(429, "Too many requests", "limit_exceeded", {
+                    ...(response.headers.get("retry-after")
+                        ? { "retry-after": response.headers.get("retry-after") }
+                        : {}),
+                });
+            if (response.status === 503)
+                throw new Problem(503, "The agent service is unavailable", "runtime_unavailable");
+            throw new Problem(502, "The agent service failed", "runtime_error");
+        }
+        catch (error) {
+            return problem(problemOf(error));
+        }
+    }
+    async function card(request, agentId) {
+        try {
+            if (!allowed.has(agentId))
+                throw new Problem(404, "Not found");
+            const client = await connected();
+            const template = await client.transport.json(`${runtimePath(agentId)}/card`);
+            const root = publicUrl ?? `${new URL(request.url).origin}${base}`;
+            const extra = options.card ?? {};
+            return Response.json({
+                ...template,
+                supportedInterfaces: [
+                    {
+                        url: `${root}/${encodeURIComponent(agentId)}`,
+                        protocolBinding: "JSONRPC",
+                        protocolVersion: "1.0",
+                    },
+                ],
+                ...(extra.provider ? { provider: extra.provider } : {}),
+                ...(extra.documentationUrl ? { documentationUrl: extra.documentationUrl } : {}),
+                ...(extra.iconUrl ? { iconUrl: extra.iconUrl } : {}),
+                ...(extra.securitySchemes ? { securitySchemes: extra.securitySchemes } : {}),
+                ...(extra.securityRequirements
+                    ? { securityRequirements: extra.securityRequirements }
+                    : {}),
+            }, { headers: { "cache-control": "public, max-age=300" } });
+        }
+        catch (error) {
+            return problem(problemOf(error));
+        }
+    }
+    async function route(request) {
+        const path = new URL(request.url).pathname;
+        if (path !== base && !path.startsWith(`${base}/`))
+            return problem(new Problem(404, "Not found"));
+        let segments;
+        try {
+            segments = path
+                .slice(base.length)
+                .split("/")
+                .slice(1)
+                .map((segment) => decodeURIComponent(segment));
+        }
+        catch {
+            return problem(new Problem(404, "Not found"));
+        }
+        if (segments.some((segment) => segment === ""))
+            return problem(new Problem(404, "Not found"));
+        const [agentId, ...rest] = segments;
+        if (!agentId || !allowed.has(agentId))
+            return problem(new Problem(404, "Not found"));
+        const method = request.method.toUpperCase();
+        const only = (allow, handle) => method === allow
+            ? handle()
+            : Promise.resolve(problem(new Problem(405, "Method not allowed", undefined, { allow })));
+        if (rest.length === 0)
+            return only("POST", () => call(request, agentId));
+        if (rest.length === 2 && rest[0] === CARD_PATH[0] && rest[1] === CARD_PATH[1])
+            return only("GET", () => card(request, agentId));
+        return problem(new Problem(404, "Not found"));
+    }
+    return { fetch: route, call, card };
+}

package/dist/a2a/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@nylorun/agents/a2a`: serve the Tenant's agents to A2A clients through the app's own server
+ * (gateway mode). The handler forwards A2A requests to the Runtime, which speaks the protocol;
+ * this entry point loads no A2A package.
+ */
+export { createA2aHandler } from "./handler.js";
+export type { A2aCaller, A2aCardOptions, A2aHandler, A2aHandlerOptions, } from "./handler.js";
+export { toNodeListener } from "../ag-ui/node.js";

package/dist/a2a/index.js

@@ -0,0 +1,7 @@
+/**
+ * `@nylorun/agents/a2a`: serve the Tenant's agents to A2A clients through the app's own server
+ * (gateway mode). The handler forwards A2A requests to the Runtime, which speaks the protocol;
+ * this entry point loads no A2A package.
+ */
+export { createA2aHandler } from "./handler.js";
+export { toNodeListener } from "../ag-ui/node.js";

package/dist/access.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Subject tokens and access management for app servers (Host feature `subject-tokens`), on the
+ * application key. `client.tokens.create` mints a short-lived token for one signed-in person;
+ * `client.access` manages the policy that decides what each role may do, the signing keys and
+ * revocations. Each call checks the Host feature before sending anything.
+ */
+import type { AccessPolicy, CreateTokenResponse, Jwks, PublishableKey, SigningKeyView, TokenScope } from "@nylorun/core/contracts";
+import { type Transport } from "./http.js";
+export interface CreateTokenOptions {
+    /** The person the token is for, e.g. `app:42`. */
+    subject: string;
+    /** A role of the Tenant's access policy. */
+    role: string;
+    /** Narrow the role's scopes. Default: all of the role's scopes. */
+    scopes?: readonly TokenScope[];
+    /** Narrow the role's agents. Default: all of the role's agents. */
+    agents?: readonly string[];
+    /** 60 to 900 seconds, at most the policy's `maxTtlSeconds`. Default: that maximum. */
+    ttlSeconds?: number;
+    signal?: AbortSignal;
+}
+export declare class TokensClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Mints a subject token. Only the application key may; never acting for a subject. */
+    create(options: CreateTokenOptions): Promise<CreateTokenResponse>;
+}
+export declare class SigningKeysClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<SigningKeyView[]>;
+    /**
+     * standby → current → previous → revoked, and a new standby. Refused while the previous key
+     * may still verify live tokens; `force` skips that and signs those tokens out.
+     */
+    rotate(options?: {
+        force?: boolean;
+        signal?: AbortSignal;
+    }): Promise<SigningKeyView[]>;
+    /** Revokes a previous or standby key; the current key must be rotated first. */
+    revoke(keyId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<SigningKeyView>;
+}
+/**
+ * Publishable keys (Host feature `browser-access`): shipped in a web page or an app, they name
+ * the Tenant and the app, and list the origins a browser may use them from.
+ */
+export declare class PublishableKeysClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<PublishableKey[]>;
+    /**
+     * A new key. `origins` are exact origins (`https://app.example.com`) or
+     * `http://localhost:*`; `[]` allows native apps only.
+     */
+    create(options: {
+        name: string;
+        origins: readonly string[];
+        signal?: AbortSignal;
+    }): Promise<PublishableKey>;
+    /** Replaces the key's origins. */
+    update(keyId: string, options: {
+        origins: readonly string[];
+        signal?: AbortSignal;
+    }): Promise<PublishableKey>;
+    /** Revokes the key: every request that sends it gets the opaque 404. */
+    revoke(keyId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<PublishableKey>;
+}
+export declare class AccessClient {
+    private readonly transport;
+    readonly signingKeys: SigningKeysClient;
+    readonly publishableKeys: PublishableKeysClient;
+    constructor(transport: Transport);
+    getPolicy(options?: {
+        signal?: AbortSignal;
+    }): Promise<AccessPolicy>;
+    putPolicy(policy: AccessPolicy, options?: {
+        signal?: AbortSignal;
+    }): Promise<AccessPolicy>;
+    /**
+     * Ends every token minted so far for `subject` and its open streams. Running turns continue;
+     * cancel them separately if they must stop.
+     */
+    revokeSubject(subject: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        subject: string;
+        epoch: number;
+    }>;
+    /** The public keys that verify the Tenant's subject tokens. */
+    jwks(options?: {
+        signal?: AbortSignal;
+    }): Promise<Jwks>;
+}

package/dist/access.js

@@ -0,0 +1,111 @@
+import { id, segment } from "./http.js";
+const FEATURE = "subject-tokens";
+export class TokensClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Mints a subject token. Only the application key may; never acting for a subject. */
+    async create(options) {
+        await this.transport.requireFeature(FEATURE, options.signal);
+        return this.transport.json("/v1/tokens", "POST", {
+            requestId: id(),
+            subject: options.subject,
+            role: options.role,
+            ...(options.scopes ? { scopes: [...options.scopes] } : {}),
+            ...(options.agents ? { agents: [...options.agents] } : {}),
+            ...(options.ttlSeconds === undefined ? {} : { ttlSeconds: options.ttlSeconds }),
+        }, options.signal);
+    }
+}
+export class SigningKeysClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async list(options = {}) {
+        await this.transport.requireFeature(FEATURE, options.signal);
+        const reply = await this.transport.json("/v1/access/signing-keys", "GET", undefined, options.signal);
+        return reply.keys;
+    }
+    /**
+     * standby → current → previous → revoked, and a new standby. Refused while the previous key
+     * may still verify live tokens; `force` skips that and signs those tokens out.
+     */
+    async rotate(options = {}) {
+        await this.transport.requireFeature(FEATURE, options.signal);
+        const reply = await this.transport.json("/v1/access/signing-keys/rotate", "POST", { requestId: id(), ...(options.force ? { force: true } : {}) }, options.signal);
+        return reply.keys;
+    }
+    /** Revokes a previous or standby key; the current key must be rotated first. */
+    async revoke(keyId, options = {}) {
+        await this.transport.requireFeature(FEATURE, options.signal);
+        return this.transport.json(`/v1/access/signing-keys/${segment(keyId)}/revoke`, "POST", { requestId: id() }, options.signal);
+    }
+}
+/**
+ * Publishable keys (Host feature `browser-access`): shipped in a web page or an app, they name
+ * the Tenant and the app, and list the origins a browser may use them from.
+ */
+export class PublishableKeysClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async list(options = {}) {
+        await this.transport.requireFeature("browser-access", options.signal);
+        const reply = await this.transport.json("/v1/access/publishable-keys", "GET", undefined, options.signal);
+        return reply.keys;
+    }
+    /**
+     * A new key. `origins` are exact origins (`https://app.example.com`) or
+     * `http://localhost:*`; `[]` allows native apps only.
+     */
+    async create(options) {
+        await this.transport.requireFeature("browser-access", options.signal);
+        return this.transport.json("/v1/access/publishable-keys", "POST", { requestId: id(), name: options.name, origins: [...options.origins] }, options.signal);
+    }
+    /** Replaces the key's origins. */
+    async update(keyId, options) {
+        await this.transport.requireFeature("browser-access", options.signal);
+        return this.transport.json(`/v1/access/publishable-keys/${segment(keyId)}`, "PUT", { requestId: id(), origins: [...options.origins] }, options.signal);
+    }
+    /** Revokes the key: every request that sends it gets the opaque 404. */
+    async revoke(keyId, options = {}) {
+        await this.transport.requireFeature("browser-access", options.signal);
+        return this.transport.json(`/v1/access/publishable-keys/${segment(keyId)}`, "DELETE", undefined, options.signal);
+    }
+}
+export class AccessClient {
+    transport;
+    signingKeys;
+    publishableKeys;
+    constructor(transport) {
+        this.transport = transport;
+        this.signingKeys = new SigningKeysClient(transport);
+        this.publishableKeys = new PublishableKeysClient(transport);
+    }
+    async getPolicy(options = {}) {
+        await this.transport.requireFeature(FEATURE, options.signal);
+        const reply = await this.transport.json("/v1/access/policy", "GET", undefined, options.signal);
+        return reply.policy;
+    }
+    async putPolicy(policy, options = {}) {
+        await this.transport.requireFeature(FEATURE, options.signal);
+        const reply = await this.transport.json("/v1/access/policy", "PUT", { requestId: id(), policy }, options.signal);
+        return reply.policy;
+    }
+    /**
+     * Ends every token minted so far for `subject` and its open streams. Running turns continue;
+     * cancel them separately if they must stop.
+     */
+    async revokeSubject(subject, options = {}) {
+        await this.transport.requireFeature(FEATURE, options.signal);
+        return this.transport.json("/v1/access/revocations", "POST", { requestId: id(), subject }, options.signal);
+    }
+    /** The public keys that verify the Tenant's subject tokens. */
+    async jwks(options = {}) {
+        await this.transport.requireFeature(FEATURE, options.signal);
+        return this.transport.json("/v1/access/jwks", "GET", undefined, options.signal);
+    }
+}

package/dist/action-handler.d.ts

@@ -0,0 +1,63 @@
+import { type EndpointPingResponse } from "@nylorun/core/contracts";
+import type { BuiltWorkflow } from "@nylorun/core/define";
+import { toNodeListener } from "./ag-ui/node.js";
+import { type AgentSource, type AgentsClient } from "./client.js";
+export interface ActionHandlerOptions {
+    /** The agents and workflows this endpoint serves. Agents they embed are served too. */
+    agents: readonly (AgentSource | BuiltWorkflow)[];
+    /**
+     * Application client, used by `register` (and, when `runtime` is not set, to read the
+     * Tenant's public keys). Default: `createClient()`, from the environment or the Project link.
+     */
+    client?: AgentsClient | Promise<AgentsClient>;
+    /**
+     * Where to read the Tenant's public keys without a key. Set it for a process that only
+     * serves Actions and holds no application key.
+     */
+    runtime?: {
+        url: string;
+        fetch?: typeof fetch;
+    };
+    /** The Tenant's public keys, instead of reading them from the Runtime. */
+    jwks?: {
+        keys: readonly JsonWebKey[];
+    };
+    /**
+     * The URL the Runtime calls, as registered. Every delivery token must name it. Default: the
+     * URL passed to `register` in this process; until then, any URL of the Tenant.
+     */
+    url?: string;
+    /** Registered with each endpoint. Default: `NYLORUN_IMPLEMENTATION_VERSION`, else `dev`. */
+    implementationVersion?: string;
+    /** Receives errors that are answered with a status instead of thrown. */
+    onError?: (error: unknown) => void;
+    /**
+     * Keeps the process alive for a background tool's work after its `202` answer, on platforms
+     * that end a request's work with its response (for example a serverless platform's
+     * `waitUntil`). A Node server needs nothing.
+     */
+    waitUntil?: (work: Promise<unknown>) => void;
+}
+export interface RegisterOptions {
+    /** The URL the Runtime calls, e.g. `http://localhost:3000/nylorun/actions`. */
+    url: string;
+    /** Save the definitions first. Default true. */
+    saveDefinitions?: boolean;
+    /** How long one inline delivery may take, in milliseconds. */
+    timeoutMs?: number;
+    /** In-flight deliveries per agent. */
+    maxConcurrent?: number;
+    signal?: AbortSignal;
+}
+export interface ActionHandler {
+    /** A web-standard handler: Hono, Next.js route handlers, Workers, Bun, Deno. */
+    fetch(request: Request): Promise<Response>;
+    /** The same handler for `node:http` and Express. */
+    readonly node: ReturnType<typeof toNodeListener>;
+    /**
+     * Saves the definitions, points the Runtime at `url` for every served agent and pings each
+     * one through the Runtime, so a wrong URL or a tunnel that is down fails here.
+     */
+    register(options: RegisterOptions): Promise<EndpointPingResponse[]>;
+}
+export declare function createActionHandler(options: ActionHandlerOptions): ActionHandler;