@nylorun/agents 0.8.0-beta → 0.10.0-beta

package/dist/client.js

@@ -1,338 +1,6 @@
-import { SANDBOX_TOOL_NAMES, delegateOf, isBuiltWorkflow, isSandboxToolName, } from "@nylorun/core/define";
-import { SCOPES_HEADER, SUBJECT_HEADER } from "@nylorun/core/compatibility";
-import { LiveEventSchema, SessionItemsResponseSchema, parseSubjectHeaders, } from "@nylorun/core/contracts";
+export * from "./session-client.js";
+import { AgentsClient } from "./session-client.js";
 import { resolveConnection } from "./connection.js";
-import { Transport, id, segment } from "./http.js";
-import { observeSSE } from "./sse.js";
-function sessionSandboxOf(transport, sessionId) {
-    const call = (tool, args) => transport.json(`/v1/sessions/${segment(sessionId)}/sandbox/${segment(tool)}`, "POST", args);
-    const sandbox = {};
-    for (const tool of SANDBOX_TOOL_NAMES) {
-        if (!isSandboxToolName(tool))
-            continue;
-        sandbox[tool] = (args) => call(tool, args);
-    }
-    return sandbox;
-}
-function linkedSessionId(event) {
-    if (event.type !== "node.agent")
-        return undefined;
-    const payload = event.payload;
-    if (!payload || typeof payload !== "object" || Array.isArray(payload))
-        return undefined;
-    const sessionId = payload.sessionId;
-    return typeof sessionId === "string" && sessionId.length > 0
-        ? sessionId
-        : undefined;
-}
-const middlewareClosure = "Hosted definitions support declarative capabilities and before/after hooks, not middleware closures";
-/** The agent's declarations, then those of each agent it uses as a tool, keyed `<child>/<capability>`. */
-function declarationsOf(agent) {
-    if (isBuiltWorkflow(agent) || agent.manifest.kind === "workflow")
-        return [];
-    const built = agent.build?.() ?? agent;
-    if (isBuiltWorkflow(built))
-        return [];
-    const binding = built.getBinding?.();
-    if (!binding || !("declarations" in binding))
-        return [];
-    const found = (binding.declarations ?? []).map((item) => ({ key: item.id, item }));
-    for (const tool of binding.tools ?? []) {
-        const child = delegateOf(tool)?.agent;
-        for (const item of child?.getBinding().declarations ?? [])
-            found.push({ key: `${child.id}/${item.id}`, item });
-    }
-    return found;
-}
-function pluginRootsOf(agent) {
-    const roots = {};
-    for (const { key, item } of declarationsOf(agent))
-        if (item.pluginRoot)
-            roots[key] = item.pluginRoot;
-    return Object.keys(roots).length === 0 ? undefined : roots;
-}
-/** Closures stay on the live binding. The published manifest cannot name them. */
-export function assertNoMiddlewareClosures(agent) {
-    if (declarationsOf(agent).some(({ item }) => item.hasMiddleware))
-        throw new Error(middlewareClosure);
-}
-export class AgentsClient {
-    transport;
-    /** The subject this client acts for (`as`), or `undefined` for the principal itself. */
-    subject;
-    constructor(destination = {}) {
-        this.transport = new Transport(destination);
-        this.subject = undefined;
-    }
-    /**
-     * 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, options = {}) {
-        if (this.subject !== undefined)
-            throw new Error(`This client already acts for ${this.subject}`);
-        const scopes = [...(options.scopes ?? ["sessions:own"])].join(" ");
-        const parsed = parseSubjectHeaders(subject, scopes);
-        if (!parsed.ok)
-            throw new TypeError(parsed.message);
-        const client = Object.create(AgentsClient.prototype);
-        return Object.assign(client, {
-            transport: this.transport.withHeaders({
-                [SUBJECT_HEADER]: subject,
-                [SCOPES_HEADER]: [...parsed.scopes].join(" "),
-            }),
-            subject,
-        });
-    }
-    /** The Runtime's protocol features, including optional ones such as `transcript-events`. */
-    hostFeatures(options = {}) {
-        return this.transport.hostFeatures(options.signal);
-    }
-    listAgents(options = {}) {
-        return this.transport.json("/v1/agents", "GET", undefined, options.signal);
-    }
-    listSessions(options = {}) {
-        const query = options.agentId
-            ? `?agentId=${encodeURIComponent(options.agentId)}`
-            : "";
-        return this.transport.json(`/v1/sessions${query}`, "GET", undefined, options.signal);
-    }
-    async saveAgent(agent, options) {
-        if (isBuiltWorkflow(agent)) {
-            for (const binding of Object.values(agent.getBinding().agents)) {
-                await this.saveAgent({
-                    id: binding.manifest.id,
-                    manifest: binding.manifest,
-                    getBinding: () => binding,
-                }, options);
-            }
-            return this.transport.json(`/v1/agents/${segment(agent.id)}`, "PUT", {
-                requestId: options.requestId ?? id(),
-                manifest: agent.manifest,
-                implementationVersion: options.implementationVersion,
-            });
-        }
-        assertNoMiddlewareClosures(agent);
-        const pluginRoots = pluginRootsOf(agent);
-        return this.transport.json(`/v1/agents/${segment(agent.id)}`, "PUT", {
-            requestId: options.requestId ?? id(),
-            manifest: agent.manifest,
-            implementationVersion: options.implementationVersion,
-            ...(pluginRoots === undefined ? {} : { pluginRoots }),
-        });
-    }
-    async createSession(options) {
-        const sessionId = options.id ?? id();
-        await this.transport.json(`/v1/sessions/${segment(sessionId)}`, "PUT", {
-            requestId: options.requestId ?? id(),
-            agentId: options.agentId,
-            ownerUserId: options.ownerUserId,
-            ...(options.info ? { info: options.info } : {}),
-            ...(options.vaultIds ? { vaultIds: options.vaultIds } : {}),
-            ...(options.credentialSelections
-                ? { credentialSelections: options.credentialSelections }
-                : {}),
-            ...(options.sandbox ? { sandbox: options.sandbox } : {}),
-        });
-        return this.session(sessionId);
-    }
-    createVault(options) {
-        return this.transport.json("/v1/vaults", "POST", {
-            requestId: options.requestId ?? id(),
-            idempotencyKey: options.idempotencyKey,
-            name: options.name,
-            ownerUserId: options.ownerUserId,
-            ...(options.metadata ? { metadata: options.metadata } : {}),
-        });
-    }
-    listVaults(ownerUserId, signal) {
-        return this.transport.json(`/v1/vaults?ownerUserId=${encodeURIComponent(ownerUserId)}`, "GET", undefined, signal);
-    }
-    getVault(vaultId, signal) {
-        return this.transport.json(`/v1/vaults/${segment(vaultId)}`, "GET", undefined, signal);
-    }
-    deleteVault(vaultId) {
-        return this.transport.json(`/v1/vaults/${segment(vaultId)}`, "DELETE");
-    }
-    createCredential(vaultId, options) {
-        return this.transport.json(`/v1/vaults/${segment(vaultId)}/credentials`, "POST", {
-            requestId: options.requestId ?? id(),
-            idempotencyKey: options.idempotencyKey,
-            name: options.name,
-            auth: options.auth,
-        });
-    }
-    listCredentials(vaultId, signal) {
-        return this.transport.json(`/v1/vaults/${segment(vaultId)}/credentials`, "GET", undefined, signal);
-    }
-    getCredential(vaultId, credentialId, signal) {
-        return this.transport.json(`/v1/vaults/${segment(vaultId)}/credentials/${segment(credentialId)}`, "GET", undefined, signal);
-    }
-    rotateCredential(vaultId, credentialId, options) {
-        return this.transport.json(`/v1/vaults/${segment(vaultId)}/credentials/${segment(credentialId)}`, "POST", {
-            requestId: options.requestId ?? id(),
-            idempotencyKey: options.idempotencyKey,
-            auth: options.auth,
-        });
-    }
-    deleteCredential(vaultId, credentialId) {
-        return this.transport.json(`/v1/vaults/${segment(vaultId)}/credentials/${segment(credentialId)}`, "DELETE");
-    }
-    session(sessionId) {
-        return new SessionClient(this.transport, sessionId);
-    }
-}
-export class SessionClient {
-    transport;
-    id;
-    sandbox;
-    constructor(transport, id) {
-        this.transport = transport;
-        this.id = id;
-        this.sandbox = sessionSandboxOf(transport, id);
-    }
-    get path() {
-        return `/v1/sessions/${segment(this.id)}`;
-    }
-    inspect(signal) {
-        return this.transport.json(this.path, "GET", undefined, signal);
-    }
-    /** Pending waits / interactions from the session inspect view. */
-    async pending(signal) {
-        const view = await this.inspect(signal);
-        return view.waits ?? [];
-    }
-    command(command, signal) {
-        return this.transport.json(`${this.path}/commands`, "POST", command, signal);
-    }
-    /**
-     * Start a turn. Strings become `message.content`; any other JSON value becomes
-     * `message.data` (workflows.md §5).
-     */
-    input(value, options) {
-        const base = {
-            type: "message",
-            requestId: options.requestId ?? id(),
-            idempotencyKey: options.idempotencyKey,
-        };
-        return this.command(typeof value === "string"
-            ? { ...base, content: value }
-            : { ...base, data: value }, options.signal);
-    }
-    approve(interactionId, approved, options) {
-        return this.command({
-            type: "approve",
-            interactionId,
-            approved,
-            requestId: options.requestId ?? id(),
-            idempotencyKey: options.idempotencyKey,
-        }, options.signal);
-    }
-    respond(interactionId, value, options) {
-        return this.command({
-            type: "respond",
-            interactionId,
-            value,
-            requestId: options.requestId ?? id(),
-            idempotencyKey: options.idempotencyKey,
-        }, options.signal);
-    }
-    cancel(options) {
-        return this.command({
-            type: "cancel",
-            requestId: options.requestId ?? id(),
-            idempotencyKey: options.idempotencyKey,
-            ...(options.reason ? { reason: options.reason } : {}),
-        }, options.signal);
-    }
-    /** `agent` narrows to one agent used as a tool: its delegationId or its path. */
-    async history(options = {}) {
-        const query = new URLSearchParams();
-        if (options.cursor)
-            query.set("cursor", options.cursor);
-        if (options.agent)
-            query.set("agent", options.agent);
-        const search = query.toString();
-        return SessionItemsResponseSchema.parse(await this.transport.json(`${this.path}/items${search ? `?${search}` : ""}`, "GET", undefined, options.signal));
-    }
-    async *observe(options = {}) {
-        if (!options.follow) {
-            yield* this.observeOne(this.id, options);
-            return;
-        }
-        yield* this.observeFollowing(options);
-    }
-    async *observeOne(sessionId, options) {
-        for await (const frame of observeSSE(this.transport, `/v1/sessions/${segment(sessionId)}/events`, options)) {
-            if (frame.event === "heartbeat" || frame.event === "ready")
-                continue;
-            yield LiveEventSchema.parse(JSON.parse(frame.data));
-        }
-    }
-    /**
-     * Own session stream plus linked agent sessions announced in `node.agent`
-     * events, merged by `createdAt` then arrival order (workflows.md §11).
-     */
-    async *observeFollowing(options) {
-        const signal = options.signal;
-        const linked = new Set();
-        const queue = [];
-        let wait;
-        let open = 1;
-        let failed;
-        const wake = () => {
-            wait?.();
-            wait = undefined;
-        };
-        const push = (event) => {
-            queue.push(event);
-            queue.sort((a, b) => {
-                const byTime = a.createdAt.localeCompare(b.createdAt);
-                return byTime !== 0 ? byTime : a.cursor.localeCompare(b.cursor);
-            });
-            wake();
-        };
-        const pump = async (sessionId, cursor) => {
-            try {
-                for await (const event of this.observeOne(sessionId, { cursor, signal })) {
-                    push(event);
-                    const link = linkedSessionId(event);
-                    if (link && link !== this.id && !linked.has(link)) {
-                        linked.add(link);
-                        open += 1;
-                        void pump(link).finally(() => {
-                            open -= 1;
-                            wake();
-                        });
-                    }
-                }
-            }
-            catch (error) {
-                if (!signal?.aborted)
-                    failed = error;
-            }
-        };
-        void pump(this.id, options.cursor).finally(() => {
-            open -= 1;
-            wake();
-        });
-        while (!signal?.aborted) {
-            if (failed)
-                throw failed;
-            if (queue.length) {
-                yield queue.shift();
-                continue;
-            }
-            if (open <= 0)
-                return;
-            await new Promise((resolve) => {
-                wait = resolve;
-            });
-        }
-    }
-}
 export function createClient(destination = {}) {
     if (destination.url !== undefined ||
         destination.key !== undefined ||
@@ -346,4 +14,3 @@ export function createClient(destination = {}) {
         ...(destination.fetch ? { fetch: destination.fetch } : {}),
     }));
 }
-export { RuntimeError, IncompatibleRuntimeError } from "./http.js";

package/dist/connection.d.ts

@@ -3,7 +3,6 @@ export interface ResolvedConnection {
     url: string;
     tenant: string;
     key: string;
-    role: "application" | "executor";
     source: "options" | "environment" | "project-link";
 }
 export declare class ConnectionError extends Error {

package/dist/connection.js

@@ -42,7 +42,6 @@ async function readProjectLink(startDir) {
             url: stripTrailingSlash(link.hostUrl),
             tenant: link.tenantId,
             key: credentials.applicationKey,
-            role: "application",
             source: "project-link",
         };
     }
@@ -63,7 +62,6 @@ export async function resolveConnection(options) {
                 url: stripTrailingSlash(optionUrl),
                 tenant: optionTenant,
                 key: optionKey,
-                role: "application",
                 source: "options",
             };
         }
@@ -72,20 +70,16 @@ export async function resolveConnection(options) {
     const envUrl = env("NYLORUN_RUNTIME_URL");
     const envTenant = env("NYLORUN_TENANT");
     const envServerKey = env("NYLORUN_SERVER_KEY");
-    const envExecutorKey = env("NYLORUN_EXECUTOR_KEY");
     const anyEnv = envUrl !== undefined ||
         envTenant !== undefined ||
-        envServerKey !== undefined ||
-        envExecutorKey !== undefined;
+        envServerKey !== undefined;
     tried.push("environment");
     if (anyEnv) {
-        const key = envExecutorKey ?? envServerKey;
-        if (envUrl && envTenant && key) {
+        if (envUrl && envTenant && envServerKey) {
             return {
                 url: stripTrailingSlash(envUrl),
                 tenant: envTenant,
-                key,
-                role: envExecutorKey !== undefined ? "executor" : "application",
+                key: envServerKey,
                 source: "environment",
             };
         }

package/dist/delivery-token.d.ts

@@ -0,0 +1,57 @@
+/** 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>;
+export declare function verifyDeliveryToken(token: string | null, options: {
+    keys: KeyLookup;
+    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;
+        tenant: string;
+        key?: string;
+        fetch?: typeof fetch;
+    } | {
+        keys: readonly JsonWebKey[];
+    }, refetchMs?: number);
+    readonly lookup: KeyLookup;
+    private load;
+    private fetchKeys;
+}

package/dist/delivery-token.js

@@ -0,0 +1,150 @@
+/**
+ * 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, TENANT_HEADER, } from "@nylorun/core/compatibility";
+import { DELIVERY_TOKEN_TYPE, subjectTokenIssuer } from "@nylorun/core/contracts";
+/** 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;
+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 !== 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 = {
+            [TENANT_HEADER]: source.tenant,
+            [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

@@ -8,3 +8,9 @@ export type ExecuteActionOptions = {
 };
 /** 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;

package/dist/execute-action.js

@@ -42,6 +42,30 @@ export async function executeAction(action, root, signal, options = {}) {
     const tool = normalizeToolDefinition(raw);
     return runTool(action, tool, ref, signal, sandbox);
 }
+/**
+ * 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 function runsInBackground(action, root) {
+    if (action.kind !== "tool")
+        return false;
+    try {
+        if (isBuiltWorkflow(root)) {
+            const key = action.key;
+            const impl = typeof key === "string" ? root.getBinding().nodes[key] : undefined;
+            return impl?.kind === "tool" && impl.tool.background === true;
+        }
+        if (!("capabilityId" in action))
+            return false;
+        const agent = action.agent ? delegatedAgent(root, action.agent.id) : root;
+        const raw = implementationsFor(agent)[action.capabilityId]?.tools?.[action.toolName];
+        return raw !== undefined && normalizeToolDefinition(raw).background === true;
+    }
+    catch {
+        return false;
+    }
+}
 async function executeWorkflowTool(action, binding, signal, sandbox) {
     const impl = binding.nodes[action.key];
     if (!impl || impl.kind !== "tool")