@nylorun/runtime 0.36.0-beta → 0.37.0-beta

package/dist/api/a2a/push.js

@@ -0,0 +1,305 @@
+import { signWebhook, webhookKeyOf } from "../../keys/webhooks.js";
+import { guardedFetch, OutboundRefused, refusal } from "../../tenant/outbound.js";
+import { traceKey } from "../../traces/key.js";
+import { traceIdOf } from "../../traces/ids.js";
+import { hostTuning } from "../../tuning.js";
+import { ALL_EXTENSIONS, keepExtensions } from "./extensions.js";
+import { a2aFail, } from "./protocol.js";
+import { ENDED, callerTraceId, updatesOf } from "./tasks.js";
+/** The most push configs one task keeps. A constant of the profile, not a setting. */
+export const MAX_PUSH_CONFIGS = 10;
+/** Events one pump reads at a time. */
+const PUMP_BATCH = 500;
+/** Sessions one sweep pass pumps. */
+const SWEEP_SESSIONS = 500;
+/** The most of a receiver's answer read: it is not used. */
+const ANSWER_BYTES = 64 * 1024;
+/** Whether this Runtime serves push notifications: it has a secret to sign them with. */
+export function pushEnabled(ctx) {
+    return ctx.config.a2a?.push?.secret !== undefined;
+}
+/** `host:port` of `url`, the way `a2a.push.allowHosts` names it. */
+function hostPort(url) {
+    const port = url.port || (url.protocol === "https:" ? "443" : "80");
+    return `${url.hostname.toLowerCase()}:${port}`;
+}
+/**
+ * The address policy a push, or a fetched file `url` part, is sent under: the Host's delivery
+ * policy, with private addresses refused unless `url`'s `host:port` is in `a2a.push.allowHosts`.
+ */
+export function pushPolicy(ctx, target) {
+    const url = new URL(target);
+    const hosts = ctx.config.a2a?.push?.allowHosts ?? [];
+    const allowed = hosts.includes(hostPort(url)) || hosts.includes(`${url.hostname.toLowerCase()}:*`);
+    return { ...(ctx.config.delivery ?? {}), privateAddresses: allowed ? "allow" : "refuse" };
+}
+/** Why the Runtime will not send to `target`, checked before a config is stored; else undefined. */
+export function pushRefusal(ctx, target) {
+    return refusal(new URL(target), pushPolicy(ctx, target));
+}
+/** A config as A2A answers it. */
+export function configView(row) {
+    return {
+        id: row.configId,
+        taskId: row.taskId,
+        url: row.url,
+        ...(row.token ? { token: row.token } : {}),
+        ...(row.authentication ? { authentication: row.authentication } : {}),
+    };
+}
+/**
+ * Stores `config` for a task (replacing one with its id), in `t`; the pump sends its updates.
+ * A URL the Runtime will not call is `InvalidParamsError`; past `MAX_PUSH_CONFIGS` too.
+ */
+export async function savePushConfig(ctx, t, start, config, configId) {
+    if (!pushEnabled(ctx))
+        a2aFail("pushNotSupported", "Push notifications are not configured on this Runtime (a2a.push.secret)");
+    const refused = pushRefusal(ctx, config.url);
+    if (refused)
+        a2aFail("invalidParams", `The push URL is refused: ${refused}`, {}, "url");
+    const existing = await t.pushConfigs(start.sessionId, start.taskId);
+    if (existing.length >= MAX_PUSH_CONFIGS && !existing.some((row) => row.configId === configId))
+        a2aFail("invalidParams", `A task keeps at most ${MAX_PUSH_CONFIGS} push configs`, {}, "id");
+    const row = {
+        sessionId: start.sessionId,
+        taskId: start.taskId,
+        configId,
+        contextId: start.contextId,
+        turnId: start.turnId,
+        url: config.url,
+        token: config.token ?? null,
+        authentication: config.authentication ?? null,
+        baseUrl: start.baseUrl,
+        extensions: [...(start.extensions.size === 0 ? ALL_EXTENSIONS : start.extensions)],
+        traceId: start.traceId ?? null,
+        nextSeq: start.nextSeq,
+        doneAt: start.done ? new Date() : null,
+    };
+    await t.putPushConfig(row);
+    return configView({ ...row, createdAt: new Date(), doneAt: row.doneAt });
+}
+const states = new WeakMap();
+function stateOf(ctx) {
+    let state = states.get(ctx);
+    if (!state) {
+        state = { active: new Set(), pumping: new Map(), again: new Set(), listening: false };
+        states.set(ctx, state);
+    }
+    return state;
+}
+/**
+ * Pumps session `sessionId` on this process: at once, or again after the pump running now, so
+ * one process never pumps a session twice at the same time. Never rejects.
+ */
+export function kickPushes(ctx, sessionId) {
+    const state = stateOf(ctx);
+    listen(ctx, state);
+    state.active.add(sessionId);
+    const running = state.pumping.get(sessionId);
+    if (running) {
+        state.again.add(sessionId);
+        return running;
+    }
+    const run = (async () => {
+        do {
+            state.again.delete(sessionId);
+            if (ctx.closing || ctx.closed)
+                return;
+            try {
+                await pumpSession(ctx, sessionId);
+            }
+            catch (error) {
+                ctx.config.logger.warn("a2a push pump failed; the sweep tries again", {
+                    sessionId,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+        } while (state.again.has(sessionId));
+    })().finally(() => state.pumping.delete(sessionId));
+    state.pumping.set(sessionId, run);
+    return run;
+}
+/** A commit on this process that wrote events of a session with a config pumps it. */
+function listen(ctx, state) {
+    if (state.listening)
+        return;
+    state.listening = true;
+    ctx.store.onCommit(({ events }) => {
+        const sessions = new Set(events.map((event) => event.sessionId));
+        for (const sessionId of sessions)
+            if (state.active.has(sessionId))
+                void kickPushes(ctx, sessionId);
+    });
+}
+/**
+ * Translates the events of session `sessionId` its configs have not read into push rows: reads
+ * the record from the lowest `nextSeq`, then, under the configs' locks, writes each config's
+ * updates and moves it on. A config stored behind what was read waits for the next pump.
+ */
+export async function pumpSession(ctx, sessionId) {
+    for (;;) {
+        const configs = await ctx.store.tx((t) => t.activePushConfigs(sessionId));
+        if (configs.length === 0) {
+            stateOf(ctx).active.delete(sessionId);
+            return;
+        }
+        const from = Math.min(...configs.map((config) => config.nextSeq));
+        const rows = await ctx.store.record().readRange(ctx.store.tenantId, sessionId, from, from + PUMP_BATCH);
+        if (rows.length === 0) {
+            // A deleted session's configs follow nothing any more.
+            await ctx.store.tx(async (t) => {
+                if (await t.get("sessions", sessionId))
+                    return;
+                for (const config of configs)
+                    await t.deletePushConfig(sessionId, config.taskId, config.configId);
+            });
+            return;
+        }
+        const events = rows.map((row) => row.body);
+        const key = configs.some((config) => config.traceId === null) ? await traceKey(ctx.store) : undefined;
+        await ctx.store.tx(async (t) => {
+            for (const config of await t.activePushConfigs(sessionId, { lock: true })) {
+                if (config.nextSeq < from)
+                    continue;
+                let { turnId, traceId } = config;
+                let next = config.nextSeq;
+                let done = false;
+                for (const event of events) {
+                    if (event.seq < config.nextSeq)
+                        continue;
+                    next = event.seq + 1;
+                    const payload = (event.payload ?? {});
+                    // A queued message's task follows the turn that takes it.
+                    if (event.type === "command.message" && event.turnId && payload.queuedMessageId === turnId)
+                        turnId = event.turnId;
+                    if (event.turnId !== turnId)
+                        continue;
+                    if (event.type === "command.message" && traceId === null)
+                        traceId =
+                            callerTraceId([event]) ??
+                                (key ? traceIdOf(key, ctx.store.tenantId, sessionId, turnId) : null);
+                    const view = {
+                        contextId: config.contextId,
+                        taskId: config.taskId,
+                        baseUrl: config.baseUrl,
+                        ...(traceId ? { traceId } : {}),
+                    };
+                    const active = new Set(config.extensions);
+                    for (const update of updatesOf(event, view))
+                        await t.enqueuePush({
+                            sessionId,
+                            taskId: config.taskId,
+                            configId: config.configId,
+                            body: JSON.stringify(keepExtensions(update, active)),
+                        });
+                    if (ENDED.has(event.type)) {
+                        done = true;
+                        break;
+                    }
+                }
+                if (next !== config.nextSeq || done || turnId !== config.turnId || traceId !== config.traceId)
+                    await t.advancePushConfig({ sessionId, taskId: config.taskId, configId: config.configId }, { turnId, nextSeq: next, traceId, done });
+            }
+        });
+        if (rows.length < PUMP_BATCH)
+            return;
+    }
+}
+/**
+ * The Tenant sweep's push step: pumps every session with a config still following its task
+ * (commits on other processes reach them here), and deletes configs done longer than the Host
+ * tuning's `a2a.pushConfigRetentionMs`.
+ */
+export async function pumpPushes(ctx) {
+    const state = stateOf(ctx);
+    listen(ctx, state);
+    const sessions = await ctx.store.tx((t) => t.pushSessions(SWEEP_SESSIONS));
+    state.active = new Set([...sessions, ...state.pumping.keys()]);
+    for (const sessionId of sessions) {
+        if (ctx.closing || ctx.closed)
+            return;
+        await kickPushes(ctx, sessionId);
+    }
+    const before = new Date(Date.now() - hostTuning().a2a.pushConfigRetentionMs);
+    await ctx.store.tx((t) => t.prunePushConfigs(before));
+}
+// ---------------------------------------------------------------------------
+// Delivery
+/** A push the receiver did not take: the sweep sends it again. */
+export class PushFailed extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PushFailed";
+    }
+}
+/** The headers of one push attempt: Standard Webhooks, the config's token and authentication. */
+export function pushHeaders(secret, push, config, now = Date.now()) {
+    const timestamp = String(Math.floor(now / 1000));
+    const key = webhookKeyOf(secret);
+    try {
+        const signature = signWebhook(key, push.id, timestamp, Buffer.from(push.body, "utf8"));
+        const authentication = config.authentication;
+        return {
+            "content-type": "application/json",
+            "webhook-id": push.id,
+            "webhook-timestamp": timestamp,
+            "webhook-signature": `v1,${signature}`,
+            ...(config.token ? { "x-a2a-notification-token": config.token } : {}),
+            ...(authentication ? { authorization: `${authentication.scheme} ${authentication.credentials}` } : {}),
+        };
+    }
+    finally {
+        key.fill(0);
+    }
+}
+/**
+ * Sends one push row (the Tenant's `send` for outbox kind `push`). Resolves `true` once it is
+ * done with: delivered (2xx), its config deleted, the receiver gone (`410`), or its URL refused
+ * by policy. Rejects with `PushFailed` (or the network's error) when it should be sent again.
+ */
+export async function deliverPush(ctx, push) {
+    if (ctx.closing || ctx.closed)
+        return false;
+    const secret = ctx.config.a2a?.push?.secret;
+    if (secret === undefined)
+        throw new PushFailed("Push notifications are not configured (a2a.push.secret)");
+    const config = await ctx.store.tx((t) => t.pushConfig(push.sessionId, push.taskId, push.configId));
+    if (!config)
+        return true;
+    const send = guardedFetch(pushPolicy(ctx, config.url), {
+        maxResponseBytes: ANSWER_BYTES,
+        timeoutMs: hostTuning().a2a.pushTimeoutMs,
+    });
+    let status;
+    try {
+        const response = await send(config.url, {
+            method: "POST",
+            headers: pushHeaders(secret, push, config),
+            body: push.body,
+        });
+        status = response.status;
+    }
+    catch (error) {
+        if (error instanceof OutboundRefused) {
+            ctx.config.logger.warn("a2a push dropped: its URL is refused", {
+                sessionId: push.sessionId,
+                taskId: push.taskId,
+                message: error.message,
+            });
+            return true;
+        }
+        throw error;
+    }
+    if ((status >= 200 && status < 300) || status === 410)
+        return true;
+    throw new PushFailed(`The push receiver answered ${status}`);
+}
+/**
+ * What the sweep does with a push that failed `attempts` times and was written at `createdAt`:
+ * try again after the backoff, or drop it once it would be past `a2a.pushMaxAgeMs`.
+ */
+export function pushRetry(attempts, createdAt, now = Date.now()) {
+    const { pushRetry: backoff, pushMaxAgeMs } = hostTuning().a2a;
+    const retryInMs = Math.min(backoff.minMs * 2 ** Math.max(0, attempts - 1), backoff.maxMs);
+    return now + retryInMs - Date.parse(createdAt) > pushMaxAgeMs ? "drop" : { retryInMs };
+}

package/dist/api/a2a/routes.d.ts

@@ -1,20 +1,26 @@
 import type { ServerResponse } from "node:http";
 import { type AuthScope, type TenantContext } from "../../tenant/context.js";
-import type { TraceContext } from "../../traces/ids.js";
+import { type TraceContext } from "../../traces/ids.js";
+/** The A2A endpoint's route for a published agent, from the Runtime's base URL. */
+export declare function agentEndpoint(baseUrl: string, agentId: string): string;
 /**
  * `GET /v1/a2a/agents/:agent/card`: the agent's card, for a caller who may use the agent. Its
  * input modes name the files the Tenant's model reads natively: a hint, since any file is
- * accepted and the agent's harness decides how its model sees it (protocol 15).
+ * accepted and the agent's harness decides how its model sees it (protocol 15). Its interface is
+ * this Runtime's JSON-RPC endpoint at `baseUrl` (a gateway lists its own instead).
  */
-export declare function a2aCard(ctx: TenantContext, scope: AuthScope, agentId: string): Promise<unknown>;
+export declare function a2aCard(ctx: TenantContext, scope: AuthScope, agentId: string, baseUrl: string): Promise<unknown>;
 /**
  * `POST /v1/a2a/agents/:agent`: one A2A JSON-RPC call, for a subject. JSON-RPC answers (errors
- * included) are the body to send with 200; HTTP-level refusals (unknown agent, no subject,
- * limits) are thrown as `HttpError` like any Tenant route. `body` is read once the agent is
- * known to be the caller's; closing `response` stops a blocking wait, never the task.
+ * included) are the body to send with 200, without the data of extensions the request did not
+ * activate; HTTP-level refusals (unknown agent, no subject, limits) are thrown as `HttpError`
+ * like any Tenant route. `body` is read once the agent is known to be the caller's; closing
+ * `response` stops a blocking wait, never the task.
  */
 export declare function a2aCall(ctx: TenantContext, scope: AuthScope, agentId: string, input: {
     body: () => Promise<string>;
     version: string | null;
     trace?: TraceContext;
+    extensions: ReadonlySet<string>;
+    baseUrl: string;
 }, response: ServerResponse): Promise<unknown>;