antpath 0.10.13 → 0.10.15

package/README.md

@@ -8,23 +8,28 @@ antpath is a TypeScript-first SDK + CLI for running autonomous Claude Managed Ag
 
 ```ts
 import {
-  AntpathClient,        // the only public class — submits durable runs to a dashboard
-  defineTemplate,
-  string,
-  validateProxyAuth     // helper for per-run proxy endpoint auth
+  AntpathClient,        // the only client class — submits durable runs to a dashboard
+  Skill,                // workspace / provider / inline skill bundles
+  McpServer,            // MCP server declarations (headers split into secrets server-side)
+  ProxyEndpoint,        // per-run managed HTTP proxy endpoint
+  AgentsMd,             // AGENTS.md / CLAUDE.md uploads
+  File,                 // arbitrary workspace files mounted into the session
+  defineRun,            // type-safe wrapper around a credential-free `Blueprint`
+  validateProxyAuth     // helper that fails fast on policy/auth mismatch
 } from "antpath";
 ```
 
 ```bash
-antpath run ./template.json --api-token ant_… \
-  --anthropic-api-key sk-ant-… --follow
-antpath status   <run-id> --api-token …
-antpath events   <run-id> --api-token … --follow
-antpath outputs  <run-id> --api-token …
-antpath download <run-id> <output-id> --out ./local --api-token …
-antpath cancel   <run-id> --api-token …
-antpath delete   <run-id> --api-token …
-antpath whoami            --api-token …
+antpath run     --config ./blueprint.json --api-token ant_… \
+                --anthropic-api-key sk-ant-… --follow
+antpath status  <run-id>             --api-token …
+antpath events  <run-id> [--follow]  --api-token …
+antpath outputs <run-id>             --api-token …
+antpath download <run-id> [--out path] --api-token …
+antpath cancel  <run-id>             --api-token …
+antpath delete  <run-id>             --api-token …
+antpath whoami                       --api-token …
+antpath skills  <upload|list|get|delete> [flags] --api-token …
 ```
 
 The SDK class and the CLI are backed by the same `@antpath/shared` operations module — any read or write you can do through one, you can do through the other, against the same durable run records. The same npm package also ships the in-container `antpath` CLI as its `bin` entry; the worker mounts that CLI inside every run at `/mnt/session/uploads/antpath/antpath` (Anthropic Managed Agents rebases every session-resource mount under `/mnt/session/uploads/`, and mounted files have no execute permission so they are invoked through `node`), so skills can call `node /mnt/session/uploads/antpath/antpath proxy …` against the per-run manifest. See [Agent-first surface design](../../references/development-principles.md#agent-first-surface-design).
@@ -42,23 +47,17 @@ The dashboard URL defaults to `https://www.antpath.ai`. Self-hosted deployments
 ## Quickstart (SDK)
 
 ```ts
-import { AntpathClient, defineTemplate, string } from "antpath";
+import { AntpathClient } from "antpath";
 
 const client = new AntpathClient({
   apiToken: process.env.ANTPATH_API_TOKEN!
   // baseUrl defaults to https://www.antpath.ai — set it for self-hosted deployments.
 });
 
-const template = defineTemplate({
-  name: "hello",
+const ref = await client.submitRun({
   model: "claude-haiku-4-5",
   system: "You are a concise automation agent.",
-  messages: ["Write a short answer about {{topic}}."],
-  variables: { topic: string() }
-});
-
-const ref = await client.submitRun(template, {
-  variables: { topic: "agent-first SDK design" },
+  prompt: "Write a short answer about agent-first SDK design.",
   secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
 });
 
@@ -70,6 +69,23 @@ for (const output of await ref.outputs()) {
 }
 ```
 
+Reusable, credential-free configs use `defineRun`:
+
+```ts
+import { defineRun } from "antpath";
+
+const summarise = defineRun((topic: string) => ({
+  model: "claude-haiku-4-5",
+  system: "You are a concise automation agent.",
+  prompt: `Write a short answer about ${topic}.`
+}));
+
+const ref = await client.submitRun({
+  ...summarise("agent-first SDK design"),
+  secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
+});
+```
+
 Stream events live with `ref.stream()`:
 
 ```ts
@@ -80,16 +96,26 @@ for await (const event of ref.stream()) {
 }
 ```
 
-The same flow from the CLI:
+The same flow from the CLI (two equivalent forms):
 
 ```bash
-antpath run ./template.json \
+antpath run \
+  --api-token "$ANTPATH_API_TOKEN" \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --model claude-haiku-4-5 \
+  --system "You are a concise automation agent." \
+  --prompt "Write a short answer about agent-first SDK design." \
+  --follow
+
+antpath run \
   --api-token "$ANTPATH_API_TOKEN" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
-  --var topic="agent-first SDK design" \
+  --config ./blueprint.json \
   --follow
 ```
 
+`--config` accepts a JSON file matching the `Blueprint` shape: `{ model, system?, prompt, skills?, mcpServers?, environment?, cleanup?, proxyEndpoints?, metadata? }`. There is no template wrapper and no `{{var}}` DSL — interpolate at the call site.
+
 ## Test commands
 
 ```text
@@ -104,7 +130,7 @@ pnpm test:user:live      # live; same but hits the real platform
 ## Guides
 
 - [Quickstart](docs/quickstart.md)
-- [Templates](docs/templates.md)
+- [Blueprints](docs/templates.md)
 - [Credentials](docs/credentials.md)
 - [MCP](docs/mcp.md)
 - [Skills](docs/skills.md)

package/dist/_shared/config.d.ts

@@ -18,7 +18,16 @@ export interface PlatformProxyConfig {
     readonly sweeperIntervalMs: number;
 }
 export interface PlatformCaps {
-    readonly maxRunDurationMs: number;
+    /**
+     * Wall-clock ceiling on a single run before forced termination.
+     * `null` means no antpath-imposed cap, but this is **not unlimited
+     * overall**: the upstream provider (e.g. Anthropic Managed Agents)
+     * still enforces its own session-lifetime ceiling, and a run that
+     * exceeds it terminates regardless. Override via env var
+     * `ANTPATH_MAX_RUN_DURATION_MS` to layer an antpath-side cap below
+     * the provider's.
+     */
+    readonly maxRunDurationMs: number | null;
     readonly maxActiveRunsPerWorkspace: number;
     readonly maxActiveRunsPerUserOrToken: number;
     readonly pollingBaseIntervalMs: number;
@@ -44,4 +53,11 @@ export interface PlatformConfig extends PlatformRequiredConfig {
 type Env = Record<string, string | undefined>;
 export declare function parsePlatformConfig(env: Env): PlatformConfig;
 export declare function snapshotRunCaps(config: PlatformConfig): PlatformCaps;
+/**
+ * Single source of truth for the `ANTPATH_MAX_RUN_DURATION_MS` env override.
+ * Returns `null` when unset (= no antpath-imposed wall-clock cap). Used by
+ * `parsePlatformConfig` and by dashboard routes that mint proxy bearers and
+ * snapshot caps onto each run.
+ */
+export declare function parseMaxRunDurationMs(env: Env): number | null;
 export {};

package/dist/_shared/config.js

@@ -1,5 +1,5 @@
 const DEFAULT_CAPS = {
-    maxRunDurationMs: 5 * 60 * 1000,
+    maxRunDurationMs: null,
     maxActiveRunsPerWorkspace: 1,
     maxActiveRunsPerUserOrToken: 1,
     pollingBaseIntervalMs: 5_000,
@@ -41,7 +41,7 @@ export function parsePlatformConfig(env) {
         throw new Error(`Missing required environment variables: ${missing.join(", ")}`);
     }
     const caps = {
-        maxRunDurationMs: optionalPositiveInt(env, "ANTPATH_MAX_RUN_DURATION_MS", DEFAULT_CAPS.maxRunDurationMs),
+        maxRunDurationMs: parseMaxRunDurationMs(env),
         maxActiveRunsPerWorkspace: optionalPositiveInt(env, "ANTPATH_MAX_ACTIVE_RUNS_PER_WORKSPACE", DEFAULT_CAPS.maxActiveRunsPerWorkspace),
         maxActiveRunsPerUserOrToken: optionalPositiveInt(env, "ANTPATH_MAX_ACTIVE_RUNS_PER_USER_OR_TOKEN", DEFAULT_CAPS.maxActiveRunsPerUserOrToken),
         pollingBaseIntervalMs: optionalPositiveInt(env, "ANTPATH_POLLING_BASE_INTERVAL_MS", DEFAULT_CAPS.pollingBaseIntervalMs),
@@ -100,6 +100,23 @@ function optionalPositiveInt(env, name, fallback) {
 function optionalNonNegativeInt(env, name, fallback) {
     return optionalInt(env, name, fallback, 0);
 }
+/**
+ * Single source of truth for the `ANTPATH_MAX_RUN_DURATION_MS` env override.
+ * Returns `null` when unset (= no antpath-imposed wall-clock cap). Used by
+ * `parsePlatformConfig` and by dashboard routes that mint proxy bearers and
+ * snapshot caps onto each run.
+ */
+export function parseMaxRunDurationMs(env) {
+    const raw = env.ANTPATH_MAX_RUN_DURATION_MS;
+    if (raw === undefined || raw === "") {
+        return DEFAULT_CAPS.maxRunDurationMs;
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error("ANTPATH_MAX_RUN_DURATION_MS must be a safe integer greater than or equal to 1");
+    }
+    return value;
+}
 function optionalInt(env, name, fallback, minimum) {
     const raw = env[name];
     if (raw === undefined || raw === "") {

package/dist/_shared/index.d.ts

@@ -16,5 +16,7 @@ export * from "./runtime-types.js";
 export * from "./known-events.js";
 export * from "./http.js";
 export * as operations from "./operations.js";
+export type { SseStreamOptions, SseStreamOutcome } from "./operations.js";
 export * from "./proxy-validation.js";
+export * from "./sse.js";
 export * from "./telemetry.js";

package/dist/_shared/index.js

@@ -19,5 +19,6 @@ export * from "./known-events.js";
 export * from "./http.js";
 export * as operations from "./operations.js";
 export * from "./proxy-validation.js";
+export * from "./sse.js";
 export * from "./telemetry.js";
 //# sourceMappingURL=index.js.map

package/dist/_shared/operations.d.ts

@@ -1,6 +1,7 @@
 import type { HttpClient } from "./http.js";
 import type { RunUnit } from "./run-unit.js";
 import type { AgentsMdRecord, FileRecord, Output, Run, RunEvent, SignedOutputLink, Skill, WhoAmI } from "./runtime-types.js";
+import { type SseFrame } from "./sse.js";
 import type { PlatformFlatRunSubmissionInput, PlatformRunSubmissionInput } from "./submission.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
@@ -31,6 +32,53 @@ export declare function getRun(http: HttpClient, runId: string): Promise<Run>;
  */
 export declare function getRunUnit(http: HttpClient, runId: string): Promise<RunUnit>;
 export declare function listRunEvents(http: HttpClient, runId: string): Promise<readonly RunEvent[]>;
+/**
+ * Outcome of an SSE round — caller decides whether to reconnect.
+ *
+ *   - `terminal` — the server emitted `event: terminal` and closed.
+ *     The run reached a final state; the iterator drained any
+ *     events that landed alongside the transition.
+ *   - `disconnected` — the connection closed for any other reason
+ *     (network error, server-side error, server-side close without
+ *     a terminal frame). Callers may reconnect with the cursor.
+ *   - `aborted` — the caller's AbortSignal fired.
+ *
+ * `nextCursor` is the most recent cursor observed during the round
+ * — pass it back as `cursor` to resume.
+ */
+export interface SseStreamOutcome {
+    readonly kind: "terminal" | "disconnected" | "aborted";
+    readonly nextCursor: string | undefined;
+    readonly terminalStatus?: string;
+    readonly error?: string;
+}
+export interface SseStreamOptions {
+    readonly cursor?: string;
+    readonly signal?: AbortSignal;
+    /**
+     * Sink for non-event frames (`ready`, `ping`, `terminal`, `gone`,
+     * `error`). Optional — callers that only care about run events can
+     * leave this off and just read the iterator.
+     */
+    readonly onFrame?: (frame: SseFrame) => void;
+}
+/**
+ * Open the `GET /api/runs/:runId/events/stream` SSE endpoint and yield
+ * each `event: run_event` frame as a parsed `RunEvent`. The iterator
+ * completes when the server emits `event: terminal`, when the caller's
+ * AbortSignal fires, or when the underlying stream closes.
+ *
+ * The caller controls reconnection — this function deliberately does
+ * NOT auto-reconnect. The SDK wraps it with a backoff loop and falls
+ * back to polling when SSE is unavailable; the CLI tails events with
+ * the same reconnect contract.
+ *
+ * Cursor semantics: the dashboard sends each event frame with `id: <cursor>`
+ * which natively maps to `Last-Event-ID` on reconnect, AND embeds the
+ * cursor inside the JSON payload as `.cursor` so non-EventSource
+ * consumers can read it. We surface both.
+ */
+export declare function streamRunEventsSse(http: HttpClient, runId: string, options?: SseStreamOptions): AsyncGenerator<RunEvent, SseStreamOutcome, void>;
 export declare function listOutputs(http: HttpClient, runId: string): Promise<readonly Output[]>;
 export declare function createOutputLink(http: HttpClient, runId: string, outputId: string): Promise<SignedOutputLink>;
 export declare function cancelRun(http: HttpClient, runId: string): Promise<void>;

package/dist/_shared/operations.js

@@ -1,3 +1,4 @@
+import { iterateSse } from "./sse.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
  * AND the CLI subcommands both call these functions; neither
@@ -40,6 +41,154 @@ export async function listRunEvents(http, runId) {
     const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/events`);
     return result.events;
 }
+/**
+ * Open the `GET /api/runs/:runId/events/stream` SSE endpoint and yield
+ * each `event: run_event` frame as a parsed `RunEvent`. The iterator
+ * completes when the server emits `event: terminal`, when the caller's
+ * AbortSignal fires, or when the underlying stream closes.
+ *
+ * The caller controls reconnection — this function deliberately does
+ * NOT auto-reconnect. The SDK wraps it with a backoff loop and falls
+ * back to polling when SSE is unavailable; the CLI tails events with
+ * the same reconnect contract.
+ *
+ * Cursor semantics: the dashboard sends each event frame with `id: <cursor>`
+ * which natively maps to `Last-Event-ID` on reconnect, AND embeds the
+ * cursor inside the JSON payload as `.cursor` so non-EventSource
+ * consumers can read it. We surface both.
+ */
+export async function* streamRunEventsSse(http, runId, options = {}) {
+    const headers = {
+        accept: "text/event-stream"
+    };
+    if (options.cursor) {
+        // Both the header and the query-string carry the cursor — the
+        // header wins server-side, but some intermediaries strip
+        // `Last-Event-ID`, so we belt-and-braces it.
+        headers["last-event-id"] = options.cursor;
+    }
+    const query = {};
+    if (options.cursor)
+        query.cursor = options.cursor;
+    let outcome = {
+        kind: "disconnected",
+        nextCursor: options.cursor
+    };
+    let download;
+    try {
+        const init = { method: "GET", headers };
+        if (options.signal)
+            init.signal = options.signal;
+        download = await http.download(`/api/runs/${encodeURIComponent(runId)}/events/stream`, init, query);
+    }
+    catch (err) {
+        return {
+            kind: options.signal?.aborted ? "aborted" : "disconnected",
+            nextCursor: options.cursor,
+            error: err instanceof Error ? err.message : String(err)
+        };
+    }
+    const body = download.response.body;
+    if (!body) {
+        return {
+            kind: "disconnected",
+            nextCursor: options.cursor,
+            error: "SSE response body was empty"
+        };
+    }
+    let cursor = options.cursor;
+    try {
+        for await (const frame of iterateSse(body, options.signal)) {
+            options.onFrame?.(frame);
+            if (frame.id)
+                cursor = frame.id;
+            switch (frame.event) {
+                case "run_event": {
+                    const event = parseRunEventFrame(frame.data);
+                    if (event) {
+                        // The dashboard duplicates the cursor inside the data
+                        // payload — prefer it if present, since it survives proxies
+                        // that strip the `id:` line.
+                        const payloadCursor = readStringField(event, "cursor");
+                        if (payloadCursor)
+                            cursor = payloadCursor;
+                        yield event;
+                    }
+                    break;
+                }
+                case "terminal": {
+                    const status = readStringField(parseJsonObject(frame.data) ?? {}, "status");
+                    outcome = {
+                        kind: "terminal",
+                        nextCursor: cursor,
+                        ...(status ? { terminalStatus: status } : {})
+                    };
+                    return outcome;
+                }
+                case "gone": {
+                    outcome = {
+                        kind: "disconnected",
+                        nextCursor: cursor,
+                        error: "run no longer exists"
+                    };
+                    return outcome;
+                }
+                case "error": {
+                    const message = readStringField(parseJsonObject(frame.data) ?? {}, "message") ?? "SSE stream reported an error";
+                    outcome = {
+                        kind: "disconnected",
+                        nextCursor: cursor,
+                        error: message
+                    };
+                    return outcome;
+                }
+                // `ready` and `ping` are no-ops — they keep proxies alive and
+                // surface the initial cursor; consumers see them via `onFrame`.
+            }
+        }
+    }
+    catch (err) {
+        return {
+            kind: options.signal?.aborted ? "aborted" : "disconnected",
+            nextCursor: cursor,
+            error: err instanceof Error ? err.message : String(err)
+        };
+    }
+    // Stream ended without a terminal frame (server closed unexpectedly).
+    return {
+        kind: options.signal?.aborted ? "aborted" : "disconnected",
+        nextCursor: cursor
+    };
+}
+function parseRunEventFrame(data) {
+    const parsed = parseJsonObject(data);
+    if (!parsed)
+        return null;
+    // Run events always carry id + type; reject malformed frames.
+    const id = readStringField(parsed, "id");
+    const type = readStringField(parsed, "type");
+    if (!id || !type)
+        return null;
+    return parsed;
+}
+function parseJsonObject(data) {
+    if (data.length === 0)
+        return null;
+    try {
+        const value = JSON.parse(data);
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            return value;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function readStringField(obj, field) {
+    const value = obj[field];
+    return typeof value === "string" ? value : undefined;
+}
 export async function listOutputs(http, runId) {
     const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/outputs`);
     return result.outputs;

package/dist/_shared/proxy-protocol.d.ts

@@ -10,6 +10,21 @@
  */
 export declare const PROXY_PROTOCOL_VERSION: "1";
 export declare const PROXY_PROTOCOL_HEADER = "x-antpath-proxy-protocol";
+/**
+ * Default `User-Agent` the proxy attaches to every outbound request when
+ * the caller did not supply one via `allowHeaders`. Some upstreams reject
+ * requests that arrive without a meaningful UA — notably the Wikimedia
+ * family (Wikidata, Wikipedia, Wikimedia Commons), whose policy requires
+ * a contactable identifier and otherwise returns HTTP 403 with a
+ * `Please identify your user agent` body.
+ *
+ * Callers can override per request by listing `user-agent` in their
+ * endpoint's `allowHeaders` and setting it on the proxy call; the
+ * default only fires when nothing was forwarded.
+ *
+ * See <https://meta.wikimedia.org/wiki/User-Agent_policy>.
+ */
+export declare const PROXY_DEFAULT_USER_AGENT = "antpath-proxy/1.0 (+https://antpath.ai/contact)";
 export declare const PROXY_METHOD_HEADER = "x-antpath-method";
 export declare const PROXY_PATH_HEADER = "x-antpath-path";
 export declare const PROXY_QUERY_HEADER = "x-antpath-query";

package/dist/_shared/proxy-protocol.js

@@ -22,6 +22,21 @@
  */
 export const PROXY_PROTOCOL_VERSION = "1";
 export const PROXY_PROTOCOL_HEADER = "x-antpath-proxy-protocol";
+/**
+ * Default `User-Agent` the proxy attaches to every outbound request when
+ * the caller did not supply one via `allowHeaders`. Some upstreams reject
+ * requests that arrive without a meaningful UA — notably the Wikimedia
+ * family (Wikidata, Wikipedia, Wikimedia Commons), whose policy requires
+ * a contactable identifier and otherwise returns HTTP 403 with a
+ * `Please identify your user agent` body.
+ *
+ * Callers can override per request by listing `user-agent` in their
+ * endpoint's `allowHeaders` and setting it on the proxy call; the
+ * default only fires when nothing was forwarded.
+ *
+ * See <https://meta.wikimedia.org/wiki/User-Agent_policy>.
+ */
+export const PROXY_DEFAULT_USER_AGENT = "antpath-proxy/1.0 (+https://antpath.ai/contact)";
 export const PROXY_METHOD_HEADER = "x-antpath-method";
 export const PROXY_PATH_HEADER = "x-antpath-path";
 export const PROXY_QUERY_HEADER = "x-antpath-query";

package/dist/_shared/runtime-types.d.ts

@@ -87,8 +87,14 @@ export interface WhoAmI {
         readonly storageCapBytes?: number;
         /** Current captured-output usage in bytes. */
         readonly storageUsedBytes?: number;
-        /** Wall-clock ceiling on a single run before forced termination. */
-        readonly maxRunDurationMs?: number;
+        /**
+         * Wall-clock ceiling on a single run before forced termination.
+         * `null` means no antpath-imposed cap, but this is **not unlimited
+         * overall**: the upstream provider (e.g. Anthropic Managed Agents)
+         * still enforces its own session-lifetime ceiling, and a run that
+         * exceeds it terminates regardless.
+         */
+        readonly maxRunDurationMs?: number | null;
     };
     readonly [key: string]: unknown;
 }

package/dist/_shared/sse.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Tiny SSE (text/event-stream) parser used by the SDK / CLI to consume
+ * the dashboard's `/api/runs/:id/events/stream` endpoint without
+ * pulling in a DOM `EventSource` dependency. Node's `fetch` returns a
+ * web `ReadableStream<Uint8Array>` body; this parser turns that into
+ * an async iterable of `SseFrame`s.
+ *
+ * The wire grammar follows the WHATWG HTML spec § Server-sent events:
+ *
+ *   - Lines are separated by `\n`, `\r`, or `\r\n`.
+ *   - A `:` prefix marks a comment — ignored.
+ *   - `field: value` (or `field:value`, with no space) — leading space
+ *     after the colon is stripped.
+ *   - Recognised fields: `event`, `data`, `id`, `retry`.
+ *   - Multiple `data:` lines join with `\n`.
+ *   - A blank line dispatches the current frame and resets the buffer.
+ *   - `event:` defaults to `"message"` when absent.
+ *
+ * The parser is deliberately a free function so it can be unit-tested
+ * against synthesized chunk boundaries (one byte at a time, mid-frame,
+ * across UTF-8 multi-byte sequences) without spinning up a real
+ * connection.
+ */
+export interface SseFrame {
+    readonly id?: string;
+    readonly event: string;
+    readonly data: string;
+    readonly retry?: number;
+}
+/**
+ * Stateful parser: feed in chunks (in any size), pull out completed
+ * frames. Designed for `for await` consumption — see `iterateSse`.
+ */
+export declare class SseParser {
+    #private;
+    /**
+     * Push a chunk of raw bytes through the parser. Returns any frames
+     * that completed during this chunk. Chunks may contain zero, one,
+     * or many frame boundaries — the parser handles partial trailing
+     * data internally.
+     */
+    pushBytes(chunk: Uint8Array): readonly SseFrame[];
+    /**
+     * Push a text chunk directly. Used by the parser tests so they can
+     * exercise byte-boundary edge cases without manufacturing a
+     * `TextDecoder` round-trip.
+     */
+    pushText(text: string): readonly SseFrame[];
+    /**
+     * Indicate end-of-stream. Returns any final frame that the dispatcher
+     * was holding when the stream closed mid-frame (no trailing blank
+     * line). The dispatcher pattern is: blank line dispatches; if the
+     * remote closes after a partial frame, that frame is dropped per the
+     * spec.
+     */
+    flush(): void;
+    /**
+     * Current "last event id" — the cursor the SSE spec instructs the
+     * client to replay on automatic reconnection. Callers use this to
+     * resume after a disconnect.
+     */
+    get lastEventId(): string | undefined;
+}
+/**
+ * Convert a web `ReadableStream<Uint8Array>` (the body of a fetch
+ * Response) into an async iterable of SSE frames. The stream is
+ * consumed exactly once; the caller is responsible for cancelling
+ * the underlying reader on abort.
+ *
+ * The reader is raced against the abort signal so a long-blocked
+ * server (no chunks for many seconds) still releases the loop
+ * promptly when the consumer aborts.
+ */
+export declare function iterateSse(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncIterable<SseFrame>;