@nylorun/agents 0.9.0-beta → 0.10.0-beta

package/dist/action-handler.js

@@ -0,0 +1,283 @@
+/**
+ * An Action endpoint (design: Action endpoints): the application mounts this handler at a URL
+ * and registers the URL; the Runtime POSTs each Action for the served agents to it and records
+ * the answer as the Action's outcome. No stream, no claim, no key needed to serve.
+ *
+ * Each request is checked before any code runs: the delivery token must be signed by the
+ * Tenant's signing key, be for this Tenant, this URL (once known), this Action and this
+ * generation, and cover the exact body. The Action then runs through `executeAction`, with the
+ * request's signal as `ctx.signal`.
+ */
+import { OUTCOME_HEADER, SIGNATURE_HEADER, } from "@nylorun/core/compatibility";
+import { ActionDeliverySchema, DeliveryHeartbeatResponseSchema, EndpointPingResponseSchema, PutEndpointsRequestSchema, } from "@nylorun/core/contracts";
+import { toNodeListener } from "./ag-ui/node.js";
+import { createClient } from "./client.js";
+import { DeliveryVerificationError, JwksCache, verifyDeliveryToken, } from "./delivery-token.js";
+import { executeAction, runsInBackground, } from "./execute-action.js";
+import { RuntimeError, Transport, delay, segment } from "./http.js";
+import { createActionSandbox } from "./sandbox/client.js";
+import { buildAgents, embeddedIn, flowManifestHash, implementationVersionOf, } from "./served-definitions.js";
+/** The Host feature `register` needs. */
+const REQUIRED_FEATURE = "action-endpoints";
+export function createActionHandler(options) {
+    const agents = buildAgents(options.agents, "createActionHandler");
+    const version = implementationVersionOf(options);
+    let client;
+    const clientOf = () => (client ??= Promise.resolve(options.client ?? createClient()));
+    let audience = options.url;
+    let verification;
+    const verificationOf = () => (verification ??= resolveVerification(options, clientOf)).catch((error) => {
+        verification = undefined;
+        throw error;
+    });
+    let callbacks;
+    const report = (error) => {
+        try {
+            options.onError?.(error);
+        }
+        catch { }
+    };
+    const handle = async (request) => {
+        if (request.method !== "POST")
+            return answer(405, "method_not_allowed", "An Action endpoint accepts POST only");
+        const body = new Uint8Array(await request.arrayBuffer());
+        const { tenant, url, fetch, keys } = await verificationOf();
+        const token = request.headers.get(SIGNATURE_HEADER);
+        let claims;
+        try {
+            claims = await verifyDeliveryToken(token, {
+                keys: keys.lookup,
+                tenantId: tenant,
+                body,
+                ...(audience === undefined ? {} : { audience }),
+            });
+        }
+        catch (error) {
+            if (!(error instanceof DeliveryVerificationError))
+                throw error;
+            // A key this endpoint has not seen yet (a rotation within the refetch interval) is not
+            // a refusal: the Runtime retries a 503, while a 401 would fail the Action.
+            return answer(error.code === "key_unknown" ? 503 : 401, error.code, error.message);
+        }
+        let delivery;
+        try {
+            delivery = ActionDeliverySchema.parse(JSON.parse(new TextDecoder().decode(body)));
+        }
+        catch {
+            return answer(400, "invalid_delivery", "The body is not an Action delivery");
+        }
+        if (delivery.type === "ping") {
+            if (claims.sub !== "ping" || claims.agt !== delivery.agentId)
+                return answer(401, "signature_invalid", "The token is for another delivery");
+            const agent = agents.get(delivery.agentId);
+            if (!agent)
+                return notServed(delivery.agentId);
+            const manifestHash = flowManifestHash(agent);
+            return Response.json({
+                agentId: agent.id,
+                implementationVersion: version,
+                ...(manifestHash === undefined ? {} : { manifestHash }),
+            });
+        }
+        const { action } = delivery;
+        if (claims.sub !== action.actionId ||
+            claims.gen !== action.generation ||
+            claims.agt !== action.agentId)
+            return answer(401, "signature_invalid", "The token is for another delivery");
+        const agent = agents.get(action.agentId);
+        if (!agent)
+            return notServed(action.agentId);
+        const served = flowManifestHash(agent);
+        if (served !== undefined && "key" in action && action.manifestHash !== served)
+            return answer(409, "version_mismatch", `Action ${action.actionId} belongs to manifest ${action.manifestHash} of '${action.agentId}'; this endpoint serves ${served}`);
+        if (runsInBackground(action, agent)) {
+            const work = runInBackground({
+                action,
+                agent,
+                token: token,
+                sandbox: delivery.sandbox,
+                runtime: { url, tenant, ...(fetch ? { fetch } : {}) },
+                report,
+            });
+            options.waitUntil?.(work);
+            return new Response(null, { status: 202 });
+        }
+        const sandbox = delivery.sandbox
+            ? createActionSandbox({
+                transport: (callbacks = callbacks
+                    ? callbacks.withKey(token)
+                    : new Transport({ url, tenant, key: token, ...(fetch ? { fetch } : {}) })),
+                actionId: action.actionId,
+                signal: request.signal,
+            })
+            : undefined;
+        try {
+            const outcome = await executeAction(action, agent, request.signal, {
+                ...(sandbox ? { sandbox } : {}),
+            });
+            return Response.json(outcome, { headers: { [OUTCOME_HEADER]: "1" } });
+        }
+        catch (error) {
+            if (request.signal.aborted)
+                return answer(503, "aborted", "The Runtime closed the delivery");
+            // Tool errors are outcomes; a throw means this endpoint cannot run the Action at all.
+            report(error);
+            return answer(404, "action_not_served", error instanceof Error ? error.message : String(error));
+        }
+    };
+    const fetchHandler = async (request) => {
+        try {
+            return await handle(request);
+        }
+        catch (error) {
+            report(error);
+            // Not run: the Runtime retries a 503 whatever the Action's kind.
+            return answer(503, "endpoint_unavailable", error instanceof Error ? error.message : String(error));
+        }
+    };
+    return {
+        fetch: fetchHandler,
+        node: toNodeListener({ fetch: fetchHandler }),
+        async register(register) {
+            const application = await clientOf();
+            const { transport } = application;
+            await transport.requireFeature(REQUIRED_FEATURE, register.signal);
+            if (register.saveDefinitions ?? true) {
+                const embedded = embeddedIn(agents);
+                for (const agent of agents.values())
+                    if (!embedded.has(agent.id))
+                        await application.saveAgent(agent, { implementationVersion: version });
+            }
+            const endpoints = [...agents.values()].map((agent) => {
+                const manifestHash = flowManifestHash(agent);
+                return {
+                    agentId: agent.id,
+                    url: register.url,
+                    implementationVersion: version,
+                    ...(manifestHash === undefined ? {} : { manifestHash }),
+                    ...(register.timeoutMs === undefined ? {} : { timeoutMs: register.timeoutMs }),
+                    ...(register.maxConcurrent === undefined
+                        ? {}
+                        : { maxConcurrent: register.maxConcurrent }),
+                };
+            });
+            await transport.json("/v1/endpoints", "PUT", PutEndpointsRequestSchema.parse({ endpoints }), register.signal);
+            audience = register.url;
+            const answers = [];
+            for (const agent of agents.values())
+                answers.push(EndpointPingResponseSchema.parse(await transport.json(`/v1/endpoints/${segment(agent.id)}/ping`, "POST", {}, register.signal)));
+            return answers;
+        },
+    };
+}
+/** How long a background tool waits before its first heartbeat, and after a failed one. */
+const HEARTBEAT_RETRY_MS = 1_000;
+/**
+ * A background tool (`ToolDefinition.background`): runs after the `202` answer, heartbeats on
+ * the deadline the Runtime returns, stops when a heartbeat answers `409` (cancelled, lost or
+ * sent again), and posts its outcome. Every callback uses the newest delivery token.
+ */
+async function runInBackground(input) {
+    const { action, report } = input;
+    let current = new Transport({ ...input.runtime, key: input.token });
+    const live = {
+        json: (...args) => current.json(...args),
+    };
+    const path = `/v1/actions/${segment(action.actionId)}`;
+    const stop = new AbortController();
+    const done = new AbortController();
+    const heartbeats = (async () => {
+        let wait = HEARTBEAT_RETRY_MS;
+        while (!done.signal.aborted && !stop.signal.aborted) {
+            try {
+                await delay(wait, done.signal);
+            }
+            catch {
+                return;
+            }
+            try {
+                const renewed = DeliveryHeartbeatResponseSchema.parse(await current.json(`${path}/heartbeat`, "POST", undefined, done.signal));
+                current = current.withKey(renewed.token);
+                wait = Math.max(HEARTBEAT_RETRY_MS, Math.floor((Date.parse(renewed.deadlineAt) - Date.now()) / 3));
+            }
+            catch (error) {
+                if (done.signal.aborted)
+                    return;
+                if (error instanceof RuntimeError && error.status === 409) {
+                    stop.abort(error);
+                    return;
+                }
+                report(error);
+                wait = HEARTBEAT_RETRY_MS;
+            }
+        }
+    })();
+    let outcome;
+    try {
+        outcome = await executeAction(action, input.agent, stop.signal, {
+            ...(input.sandbox
+                ? { sandbox: createActionSandbox({ transport: live, actionId: action.actionId, signal: stop.signal }) }
+                : {}),
+        });
+    }
+    catch (error) {
+        // Not served here: say so rather than leave the Runtime waiting for the deadline.
+        report(error);
+        outcome = {
+            value: {
+                kind: "failed",
+                code: "action_not_served",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+    finally {
+        done.abort();
+    }
+    await heartbeats;
+    if (stop.signal.aborted)
+        return;
+    for (let attempt = 0;; attempt++) {
+        try {
+            await current.json(`${path}/result`, "POST", outcome);
+            return;
+        }
+        catch (error) {
+            if (attempt >= 4 ||
+                (error instanceof RuntimeError && error.status < 500 && error.status !== 429)) {
+                report(error);
+                return;
+            }
+            await delay(Math.min(4_000, 250 * 2 ** attempt), new AbortController().signal);
+        }
+    }
+}
+async function resolveVerification(options, clientOf) {
+    if (options.runtime) {
+        const { url, tenant, fetch } = options.runtime;
+        return {
+            tenant,
+            url,
+            ...(fetch ? { fetch } : {}),
+            keys: new JwksCache(options.jwks ?? { url, tenant, ...(fetch ? { fetch } : {}) }),
+        };
+    }
+    const { transport } = await clientOf();
+    return {
+        tenant: transport.tenant,
+        url: transport.url,
+        fetch: transport.fetcher,
+        keys: new JwksCache(options.jwks ?? {
+            url: transport.url,
+            tenant: transport.tenant,
+            key: transport.key,
+            fetch: transport.fetcher,
+        }),
+    };
+}
+function notServed(agentId) {
+    return answer(404, "agent_not_served", `This endpoint does not serve '${agentId}'`);
+}
+function answer(status, code, message) {
+    return Response.json({ code, message }, { status });
+}

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

@@ -1,9 +1,19 @@
-import type { BuiltWorkflow } from "@nylorun/core/define";
+/**
+ * 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 { type SubjectScope } from "@nylorun/core/contracts";
+import type { BuiltWorkflow } from "@nylorun/core/define";
 import { type AgentSource, type AgentsClient } from "../client.js";
 /** Per-session parameters the host may add, such as the person's vault for MCP servers. */
 export interface AgUiSessionOptions {
-    /** Part of the session's identity: keep it stable for a subject and agent, or runs get 409. */
+    /** Set when the thread's session is created, on its first run; later runs keep them. */
     info?: Record<string, unknown>;
     vaultIds?: readonly string[];
     credentialSelections?: Parameters<AgentsClient["createSession"]>[0]["credentialSelections"];
@@ -37,6 +47,4 @@ export interface AgUiHandler {
     /** `POST`: cancels the thread's running turn. */
     cancel(request: Request, agentId: string, threadId: string): Promise<Response>;
 }
-/** A session per subject, agent and thread; one subject can never name another's session. */
-export declare function sessionIdFor(subject: string, agentId: string, threadId: string): string;
 export declare function createAgUiHandler(options: AgUiHandlerOptions): AgUiHandler;