@nylorun/agents 0.30.0-beta → 0.31.1-beta

package/dist/a2a/index.js

@@ -1,7 +1,9 @@
 /**
  * `@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.
+ * (gateway mode), and call A2A agents with the Nylorun profile v2 (the client, push
+ * verification, the extensions' readers and the change feed). 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";
+export * from "./client-api.js";

package/dist/a2a/profile.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The Nylorun A2A profile, v2: the five extensions' URIs, the data each carries, and readers
+ * that find it in whatever a client holds (a task, a push's `StreamResponse`, a status update, a
+ * message, an artifact). A reader answers `undefined` (or `[]`) when the data is missing or not
+ * the profile's shape, so a core-tier agent outside Nylorun reads as plain A2A.
+ */
+import type { Artifact } from "./types.js";
+/** The profile's extension URIs, exactly as agents declare them on the card. */
+export declare const A2A_EXTENSIONS: {
+    /** An open interaction on a status message; the caller's answer on its reply. */
+    readonly interactions: "https://docs.nylorun.com/a2a/interactions/v1";
+    /** `uncertain`: the effect whose outcome was lost. */
+    readonly effects: "https://docs.nylorun.com/a2a/effects/v1";
+    /** The agent's plan, whole each time. */
+    readonly progress: "https://docs.nylorun.com/a2a/progress/v1";
+    /** Totals and the trace id, on the terminal status update. */
+    readonly telemetry: "https://docs.nylorun.com/a2a/telemetry/v1";
+    /** Each file artifact's kind, path, version, size and digest. */
+    readonly files: "https://docs.nylorun.com/a2a/files/v1";
+};
+export type A2aExtensionUri = (typeof A2A_EXTENSIONS)[keyof typeof A2A_EXTENSIONS];
+/** Every profile v2 extension: what a client activates by default. */
+export declare const A2A_PROFILE_EXTENSIONS: readonly A2aExtensionUri[];
+export type A2aPlanStepState = "pending" | "active" | "done" | "blocked" | "skipped";
+export interface A2aPlanStep {
+    label: string;
+    state: A2aPlanStepState;
+    note?: string;
+}
+/** `progress/v1`: the whole plan, never a diff. */
+export interface A2aProgress {
+    steps: A2aPlanStep[];
+}
+/** `telemetry/v1`, on the terminal status update. */
+export interface A2aTelemetry {
+    totals?: {
+        steps: number;
+        tokens: number;
+        costUsd: number;
+    };
+    /** The caller's `traceparent` trace id when one was sent, else the Runtime's own. */
+    traceId?: string;
+}
+/** `interactions/v1`: what the agent waits for. `approval` and `connection` pause as `AUTH_REQUIRED`. */
+export interface A2aInteraction {
+    interactionId: string;
+    kind: "approval" | "question" | "connection" | (string & {});
+    prompt?: string;
+    detail?: unknown;
+}
+/** `effects/v1`. */
+export interface A2aEffects {
+    /** The effect id whose outcome was lost; the task stays `WORKING`. */
+    uncertain?: string;
+}
+/** `files/v1`, on an artifact that comes from a file the agent wrote. */
+export interface A2aFile {
+    kind: string;
+    /** Its path in the agent's outputs. */
+    path?: string;
+    version?: number;
+    size?: number;
+    sha256?: string;
+}
+/** An artifact with its `files/v1` data. */
+export interface A2aFileArtifact {
+    artifact: Artifact;
+    file: A2aFile;
+}
+/**
+ * The data under extension `uri` in `source`'s metadata: an update event's own first, then its
+ * status message's. `source` may be a `StreamResponse`, a task, a status update, a status, a
+ * message or an artifact.
+ */
+export declare function readExtension(source: unknown, uri: string): unknown;
+/** `progress/v1`'s plan; steps that are not the profile's shape are left out. */
+export declare function readProgress(source: unknown): A2aProgress | undefined;
+/** `telemetry/v1`'s totals and trace id. */
+export declare function readTelemetry(source: unknown): A2aTelemetry | undefined;
+/** `interactions/v1`'s open interaction, from a status (update) or its message. */
+export declare function readInteraction(source: unknown): A2aInteraction | undefined;
+/** `effects/v1`: the effect whose outcome was lost. */
+export declare function readEffects(source: unknown): A2aEffects | undefined;
+/**
+ * The artifacts with `files/v1` data: a task's, an artifact update's, or one artifact. Others
+ * (the turn's `output`, a core-tier agent's) are left out.
+ */
+export declare function readFiles(source: unknown): A2aFileArtifact[];

package/dist/a2a/profile.js

@@ -0,0 +1,133 @@
+/** The profile's extension URIs, exactly as agents declare them on the card. */
+export const A2A_EXTENSIONS = {
+    /** An open interaction on a status message; the caller's answer on its reply. */
+    interactions: "https://docs.nylorun.com/a2a/interactions/v1",
+    /** `uncertain`: the effect whose outcome was lost. */
+    effects: "https://docs.nylorun.com/a2a/effects/v1",
+    /** The agent's plan, whole each time. */
+    progress: "https://docs.nylorun.com/a2a/progress/v1",
+    /** Totals and the trace id, on the terminal status update. */
+    telemetry: "https://docs.nylorun.com/a2a/telemetry/v1",
+    /** Each file artifact's kind, path, version, size and digest. */
+    files: "https://docs.nylorun.com/a2a/files/v1",
+};
+/** Every profile v2 extension: what a client activates by default. */
+export const A2A_PROFILE_EXTENSIONS = Object.values(A2A_EXTENSIONS);
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The objects whose `metadata` may hold extension data, most specific first. */
+function holders(source) {
+    if (!isObject(source))
+        return [];
+    for (const key of ["statusUpdate", "artifactUpdate", "task", "message"])
+        if (isObject(source[key]))
+            return holders(source[key]);
+    const found = [source];
+    const status = isObject(source.status) ? source.status : undefined;
+    if (status && isObject(status.message))
+        found.push(status.message);
+    if (isObject(source.artifact))
+        found.push(source.artifact);
+    return found;
+}
+/**
+ * The data under extension `uri` in `source`'s metadata: an update event's own first, then its
+ * status message's. `source` may be a `StreamResponse`, a task, a status update, a status, a
+ * message or an artifact.
+ */
+export function readExtension(source, uri) {
+    for (const holder of holders(source)) {
+        const metadata = holder.metadata;
+        if (isObject(metadata) && metadata[uri] !== undefined)
+            return metadata[uri];
+    }
+    return undefined;
+}
+const STEP_STATES = new Set(["pending", "active", "done", "blocked", "skipped"]);
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+/** `progress/v1`'s plan; steps that are not the profile's shape are left out. */
+export function readProgress(source) {
+    const data = readExtension(source, A2A_EXTENSIONS.progress);
+    if (!isObject(data) || !Array.isArray(data.steps))
+        return undefined;
+    const steps = [];
+    for (const step of data.steps) {
+        if (!isObject(step) || typeof step.label !== "string" || typeof step.state !== "string")
+            continue;
+        if (!STEP_STATES.has(step.state))
+            continue;
+        steps.push({
+            label: step.label,
+            state: step.state,
+            ...(typeof step.note === "string" ? { note: step.note } : {}),
+        });
+    }
+    return { steps };
+}
+/** `telemetry/v1`'s totals and trace id. */
+export function readTelemetry(source) {
+    const data = readExtension(source, A2A_EXTENSIONS.telemetry);
+    if (!isObject(data))
+        return undefined;
+    const totals = isObject(data.totals) ? data.totals : undefined;
+    const result = {};
+    if (totals && finite(totals.steps) && finite(totals.tokens) && finite(totals.costUsd))
+        result.totals = { steps: totals.steps, tokens: totals.tokens, costUsd: totals.costUsd };
+    if (typeof data.traceId === "string")
+        result.traceId = data.traceId;
+    return result.totals || result.traceId ? result : undefined;
+}
+/** `interactions/v1`'s open interaction, from a status (update) or its message. */
+export function readInteraction(source) {
+    const data = readExtension(source, A2A_EXTENSIONS.interactions);
+    if (!isObject(data) || typeof data.interactionId !== "string" || data.interactionId === "")
+        return undefined;
+    return {
+        interactionId: data.interactionId,
+        kind: typeof data.kind === "string" ? data.kind : "question",
+        ...(typeof data.prompt === "string" ? { prompt: data.prompt } : {}),
+        ...(data.detail !== undefined ? { detail: data.detail } : {}),
+    };
+}
+/** `effects/v1`: the effect whose outcome was lost. */
+export function readEffects(source) {
+    const data = readExtension(source, A2A_EXTENSIONS.effects);
+    if (!isObject(data))
+        return undefined;
+    return typeof data.uncertain === "string" ? { uncertain: data.uncertain } : {};
+}
+function fileOf(artifact) {
+    if (!isObject(artifact) || typeof artifact.artifactId !== "string")
+        return undefined;
+    const metadata = artifact.metadata;
+    const data = isObject(metadata) ? metadata[A2A_EXTENSIONS.files] : undefined;
+    if (!isObject(data) || typeof data.kind !== "string")
+        return undefined;
+    return {
+        artifact: artifact,
+        file: {
+            kind: data.kind,
+            ...(typeof data.path === "string" ? { path: data.path } : {}),
+            ...(finite(data.version) ? { version: data.version } : {}),
+            ...(finite(data.size) ? { size: data.size } : {}),
+            ...(typeof data.sha256 === "string" ? { sha256: data.sha256 } : {}),
+        },
+    };
+}
+/**
+ * The artifacts with `files/v1` data: a task's, an artifact update's, or one artifact. Others
+ * (the turn's `output`, a core-tier agent's) are left out.
+ */
+export function readFiles(source) {
+    if (!isObject(source))
+        return [];
+    if (isObject(source.task))
+        return readFiles(source.task);
+    if (isObject(source.artifactUpdate))
+        return readFiles(source.artifactUpdate);
+    const artifacts = Array.isArray(source.artifacts)
+        ? source.artifacts
+        : isObject(source.artifact)
+            ? [source.artifact]
+            : [source];
+    return artifacts.flatMap((artifact) => fileOf(artifact) ?? []);
+}

package/dist/a2a/push.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Verifying a push delivery from a Nylorun agent (profile v2): Standard Webhooks signatures over
+ * the raw body with the installation's `whsec_` secret. Web Crypto only, so it runs wherever
+ * `fetch` does; HMAC comparison is `crypto.subtle.verify`'s, in constant time.
+ */
+import type { StreamResponse } from "./types.js";
+export type A2aPushFailure = "missing_headers" | "invalid_secret" | "invalid_timestamp" | "timestamp_out_of_range" | "invalid_signature" | "invalid_token" | "invalid_body";
+/** A delivery that is not provably from the agent: answer it `400` or `401` and drop it. */
+export declare class A2aPushVerificationError extends Error {
+    readonly reason: A2aPushFailure;
+    constructor(reason: A2aPushFailure, message: string);
+}
+/** Request headers as `Headers`, a `node:http` `IncomingHttpHeaders`, or a plain record. */
+export type PushHeaders = Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+export interface VerifyA2aPushOptions {
+    /** The installation's webhook secret, `whsec_<base64>`. */
+    secret: string;
+    headers: PushHeaders;
+    /** The request body exactly as received: verify before parsing. */
+    body: string | Uint8Array;
+    /** How far `webhook-timestamp` may be from now, either way. Default 300. */
+    toleranceSeconds?: number;
+    /**
+     * The push config's `token`, when the client gave one: the delivery's
+     * `X-A2A-Notification-Token` must match it.
+     */
+    token?: string;
+}
+/**
+ * Checks one push delivery and returns its body, an A2A `StreamResponse`. Throws
+ * `A2aPushVerificationError` when a header is missing, the timestamp is more than
+ * `toleranceSeconds` from now, no `v1` signature matches, or the token differs. Several
+ * signatures (space-separated) are allowed, as during a secret's rotation.
+ */
+export declare function verifyA2aPush(options: VerifyA2aPushOptions): Promise<StreamResponse>;

package/dist/a2a/push.js

@@ -0,0 +1,96 @@
+/** A delivery that is not provably from the agent: answer it `400` or `401` and drop it. */
+export class A2aPushVerificationError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "A2aPushVerificationError";
+    }
+}
+function header(headers, name) {
+    if (typeof headers.get === "function")
+        return headers.get(name) ?? undefined;
+    const record = headers;
+    const key = Object.keys(record).find((candidate) => candidate.toLowerCase() === name);
+    const value = key === undefined ? undefined : record[key];
+    return Array.isArray(value) ? value.join(" ") : value;
+}
+function base64Bytes(value) {
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value) || value.length % 4 === 1)
+        return undefined;
+    try {
+        const binary = atob(value);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++)
+            bytes[i] = binary.charCodeAt(i);
+        return bytes;
+    }
+    catch {
+        return undefined;
+    }
+}
+const encoder = new TextEncoder();
+/** Equal strings, compared without stopping at the first difference. */
+function sameText(a, b) {
+    const left = encoder.encode(a);
+    const right = encoder.encode(b);
+    let diff = left.length ^ right.length;
+    for (let i = 0; i < Math.max(left.length, right.length); i++)
+        diff |= (left[i] ?? 0) ^ (right[i] ?? 0);
+    return diff === 0;
+}
+/**
+ * Checks one push delivery and returns its body, an A2A `StreamResponse`. Throws
+ * `A2aPushVerificationError` when a header is missing, the timestamp is more than
+ * `toleranceSeconds` from now, no `v1` signature matches, or the token differs. Several
+ * signatures (space-separated) are allowed, as during a secret's rotation.
+ */
+export async function verifyA2aPush(options) {
+    const id = header(options.headers, "webhook-id");
+    const timestamp = header(options.headers, "webhook-timestamp");
+    const signatures = header(options.headers, "webhook-signature");
+    if (!id || !timestamp || !signatures)
+        throw new A2aPushVerificationError("missing_headers", "webhook-id, webhook-timestamp and webhook-signature are required");
+    const secret = base64Bytes(options.secret.replace(/^whsec_/, ""));
+    if (!secret || secret.length === 0)
+        throw new A2aPushVerificationError("invalid_secret", "The secret must be whsec_<base64>");
+    if (!/^\d{1,15}$/.test(timestamp))
+        throw new A2aPushVerificationError("invalid_timestamp", "webhook-timestamp must be unix seconds");
+    const tolerance = options.toleranceSeconds ?? 300;
+    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > tolerance)
+        throw new A2aPushVerificationError("timestamp_out_of_range", `webhook-timestamp is more than ${tolerance} seconds from now`);
+    const body = typeof options.body === "string" ? options.body : new TextDecoder().decode(options.body);
+    const key = await crypto.subtle.importKey("raw", secret, { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+    const signed = encoder.encode(`${id}.${timestamp}.${body}`);
+    let verified = false;
+    for (const entry of signatures.split(" ")) {
+        const comma = entry.indexOf(",");
+        if (comma < 0 || entry.slice(0, comma) !== "v1")
+            continue;
+        const signature = base64Bytes(entry.slice(comma + 1));
+        if (!signature)
+            continue;
+        // Every candidate is checked, so the time taken says nothing about which one matched.
+        if (await crypto.subtle.verify("HMAC", key, signature, signed))
+            verified = true;
+    }
+    if (!verified)
+        throw new A2aPushVerificationError("invalid_signature", "No webhook-signature matches");
+    if (options.token !== undefined) {
+        const token = header(options.headers, "x-a2a-notification-token");
+        if (token === undefined || !sameText(token, options.token))
+            throw new A2aPushVerificationError("invalid_token", "X-A2A-Notification-Token does not match the push config's token");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        throw new A2aPushVerificationError("invalid_body", "The body is not JSON");
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        !["task", "message", "statusUpdate", "artifactUpdate"].some((key) => key in parsed))
+        throw new A2aPushVerificationError("invalid_body", "The body is not an A2A StreamResponse");
+    return parsed;
+}

package/dist/a2a/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The A2A 1.0 wire types the client reads and sends, as ProtoJSON (camelCase fields, enum
+ * values such as `TASK_STATE_WORKING`). They follow the Runtime's own (`api/a2a/protocol.ts`)
+ * and add what profile v2 serves: metadata on tasks and artifacts, the update events a push
+ * carries, `ListTasks` and the card's extensions. Only types: nothing here runs.
+ */
+export type TaskState = "TASK_STATE_SUBMITTED" | "TASK_STATE_WORKING" | "TASK_STATE_INPUT_REQUIRED" | "TASK_STATE_AUTH_REQUIRED" | "TASK_STATE_COMPLETED" | "TASK_STATE_FAILED" | "TASK_STATE_CANCELED" | "TASK_STATE_REJECTED";
+export type Metadata = Record<string, unknown>;
+/** Exactly one of `text`, `data`, `raw` (base64 bytes) or `url` (A2A §4.1.6). */
+export type Part = {
+    text: string;
+    mediaType?: string;
+    metadata?: Metadata;
+} | {
+    data: unknown;
+    mediaType?: string;
+    metadata?: Metadata;
+} | {
+    raw: string;
+    mediaType?: string;
+    filename?: string;
+    metadata?: Metadata;
+} | {
+    url: string;
+    mediaType?: string;
+    filename?: string;
+    metadata?: Metadata;
+};
+export type Role = "ROLE_USER" | "ROLE_AGENT";
+export interface Message {
+    messageId: string;
+    role: Role;
+    parts: Part[];
+    contextId?: string;
+    taskId?: string;
+    /** The extension URIs whose data this message carries in `metadata`. */
+    extensions?: string[];
+    metadata?: Metadata;
+    referenceTaskIds?: string[];
+}
+export interface Artifact {
+    artifactId: string;
+    name?: string;
+    description?: string;
+    parts: Part[];
+    extensions?: string[];
+    metadata?: Metadata;
+}
+export interface TaskStatus {
+    state: TaskState;
+    message?: Message;
+    /** ISO 8601. Order updates by it. */
+    timestamp?: string;
+}
+export interface Task {
+    id: string;
+    contextId: string;
+    status: TaskStatus;
+    artifacts?: Artifact[];
+    history?: Message[];
+    metadata?: Metadata;
+}
+export interface TaskStatusUpdateEvent {
+    taskId: string;
+    contextId: string;
+    status: TaskStatus;
+    metadata?: Metadata;
+}
+export interface TaskArtifactUpdateEvent {
+    taskId: string;
+    contextId: string;
+    artifact: Artifact;
+    append?: boolean;
+    lastChunk?: boolean;
+    metadata?: Metadata;
+}
+/** One update: the body of a push delivery, or one frame of a stream. Exactly one field is set. */
+export type StreamResponse = {
+    task: Task;
+} | {
+    message: Message;
+} | {
+    statusUpdate: TaskStatusUpdateEvent;
+} | {
+    artifactUpdate: TaskArtifactUpdateEvent;
+};
+/** Where an agent sends push deliveries for a task. */
+export interface PushNotificationConfig {
+    url: string;
+    /** Sent back on every delivery as `X-A2A-Notification-Token`. */
+    token?: string;
+    id?: string;
+}
+export interface ListTasksResult {
+    tasks: Task[];
+    /** Empty when this is the last page. */
+    nextPageToken: string;
+    pageSize: number;
+    totalSize: number;
+}
+export interface AgentExtension {
+    uri: string;
+    description?: string;
+    required?: boolean;
+    params?: Metadata;
+}
+export interface AgentInterface {
+    url: string;
+    protocolBinding: string;
+    protocolVersion?: string;
+}
+export interface AgentCapabilities {
+    streaming?: boolean;
+    pushNotifications?: boolean;
+    extendedAgentCard?: boolean;
+    extensions?: AgentExtension[];
+}
+export interface AgentSkill {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    examples?: string[];
+    inputModes?: string[];
+    outputModes?: string[];
+}
+export interface AgentCard {
+    name: string;
+    description: string;
+    supportedInterfaces: AgentInterface[];
+    version: string;
+    capabilities: AgentCapabilities;
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    skills: AgentSkill[];
+    provider?: {
+        organization: string;
+        url: string;
+    };
+    documentationUrl?: string;
+    iconUrl?: string;
+    securitySchemes?: Record<string, unknown>;
+    securityRequirements?: unknown[];
+    [field: string]: unknown;
+}

package/dist/a2a/types.js

@@ -0,0 +1,7 @@
+/**
+ * The A2A 1.0 wire types the client reads and sends, as ProtoJSON (camelCase fields, enum
+ * values such as `TASK_STATE_WORKING`). They follow the Runtime's own (`api/a2a/protocol.ts`)
+ * and add what profile v2 serves: metadata on tasks and artifacts, the update events a push
+ * carries, `ListTasks` and the card's extensions. Only types: nothing here runs.
+ */
+export {};

package/dist/compose.js

@@ -199,6 +199,7 @@ function agentHarness(file, base, where, files, warnings) {
         ...(file.outputSchema === undefined ? {} : { outputSchema: file.outputSchema }),
         ...(file.loop === undefined ? {} : { loop: file.loop }),
         ...(file.memory === undefined ? {} : { memory: file.memory }),
+        ...(file.model === undefined ? {} : { model: file.model }),
     };
 }
 /**

package/dist/index.d.ts

@@ -33,3 +33,5 @@ export type { SkillDiagnostic } from "./skills/index.js";
 export { McpError } from "./mcp/index.js";
 export type { McpServerSpec } from "./mcp/index.js";
 export type { SessionPageOptions } from "./reads.js";
+export * from "./a2a/client-api.js";
+export type * as A2a from "./a2a/types.js";

package/dist/index.js

@@ -23,3 +23,5 @@ export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
 export { loadMcpServers, loadPlugin, PluginError } from "./plugins/load.js";
 export { hashFolder, loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, } from "./skills/index.js";
 export { McpError } from "./mcp/index.js";
+// The A2A client (`@nylorun/agents/a2a` also has the gateway handler).
+export * from "./a2a/client-api.js";

package/dist/session-client.d.ts

@@ -439,10 +439,15 @@ export declare class SessionClient {
         agent?: string;
         signal?: AbortSignal;
     }): Promise<SessionItemsResponse>;
+    /**
+     * The session's events from `cursor` on, reconnecting from the last one when the connection
+     * drops or sends nothing, keepalives included, for `idleTimeoutMs` (default 45 s; `0` never).
+     */
     observe(options?: {
         cursor?: string;
         signal?: AbortSignal;
         follow?: boolean;
+        idleTimeoutMs?: number;
     }): AsyncGenerator<{
         schema: "nylorun.event/2";
         eventId: string;

package/dist/session-client.js

@@ -279,6 +279,10 @@ export class SessionClient {
             ...("tail" in page ? { tail: page.tail } : {}),
         };
     }
+    /**
+     * The session's events from `cursor` on, reconnecting from the last one when the connection
+     * drops or sends nothing, keepalives included, for `idleTimeoutMs` (default 45 s; `0` never).
+     */
     async *observe(options = {}) {
         if (!options.follow) {
             yield* this.observeOne(this.id, options);
@@ -318,7 +322,11 @@ export class SessionClient {
         };
         const pump = async (sessionId, cursor) => {
             try {
-                for await (const event of this.observeOne(sessionId, { cursor, signal })) {
+                for await (const event of this.observeOne(sessionId, {
+                    cursor,
+                    signal,
+                    ...(options.idleTimeoutMs !== undefined ? { idleTimeoutMs: options.idleTimeoutMs } : {}),
+                })) {
                     push(event);
                     const link = linkedSessionId(event);
                     if (link && link !== this.id && !linked.has(link)) {

package/dist/sse.d.ts

@@ -4,9 +4,26 @@ export interface SSEEvent {
     data: string;
     id?: string;
 }
-/** Fetch-based SSE supports Authorization headers and works in browsers and Node. */
-export declare function readSSE(response: Response, signal: AbortSignal): AsyncGenerator<SSEEvent>;
+/**
+ * How long a stream may send nothing before the client takes it for dead: the Runtime sends a
+ * `: keepalive` comment every 15 s, so three missed ones.
+ */
+export declare const SSE_IDLE_TIMEOUT_MS = 45000;
+/** A stream sent no byte, not even a keepalive, for `idleTimeoutMs`. */
+export declare class SSEIdleTimeoutError extends Error {
+    readonly idleTimeoutMs: number;
+    constructor(idleTimeoutMs: number);
+}
+/**
+ * Fetch-based SSE supports Authorization headers and works in browsers and Node. Any byte,
+ * keepalive comments included, counts as liveness; after `idleTimeoutMs` without one the read
+ * stops with `SSEIdleTimeoutError` (`0` waits forever).
+ */
+export declare function readSSE(response: Response, signal: AbortSignal, options?: {
+    idleTimeoutMs?: number;
+}): AsyncGenerator<SSEEvent>;
 export declare function observeSSE(transport: Transport, path: string, options?: {
     signal?: AbortSignal;
     cursor?: string;
+    idleTimeoutMs?: number;
 }): AsyncGenerator<SSEEvent>;