@north-light/sdk 0.0.0 → 0.3.415

package/dist/resources/request.js

@@ -0,0 +1,50 @@
+import { deadlineExceeded, MAX_TIMER_MS } from '@north-light/api';
+export function withQuery(path, query) {
+    if (query === undefined)
+        return path;
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined)
+            search.set(key, String(value));
+    }
+    const suffix = search.toString();
+    return suffix === '' ? path : `${path}?${suffix}`;
+}
+/** A held read's options: `wait` (an integer 1–25 s; anything else throws `RangeError` before sending) extends the
+ *  request timeout by the hold, so the timeout bounds the answer rather than the wait. Shared by `runs.get` and
+ *  `grant.get`. */
+export function heldReadOptions(wait, options) {
+    if (wait !== undefined && (!Number.isInteger(wait) || wait < 1 || wait > 25))
+        throw new RangeError('wait must be 1–25 seconds');
+    return wait ? { ...options, timeout: (options.timeout ?? 30_000) + wait * 1_000 } : options;
+}
+/** The call's one deadline, fixed at call start: `budgetMs` from now and/or `deadlineAt`, whichever is earlier, as
+ *  `deadlineAt` (so a retry after a 401 and every transport attempt share it). Options without either pass through. */
+export function deadline(options) {
+    if (options === undefined || (options.budgetMs === undefined && options.deadlineAt === undefined))
+        return options;
+    const { budgetMs, deadlineAt, ...rest } = options;
+    if (budgetMs !== undefined && (!Number.isFinite(budgetMs) || budgetMs <= 0 || budgetMs > MAX_TIMER_MS))
+        throw new RangeError(`budgetMs must be a positive finite number of at most ${MAX_TIMER_MS}`);
+    if (deadlineAt !== undefined && (!Number.isFinite(deadlineAt) || deadlineAt - Date.now() > MAX_TIMER_MS))
+        throw new RangeError(`deadlineAt must be a finite epoch-millisecond instant at most ${MAX_TIMER_MS} ms from now`);
+    return { ...rest, deadlineAt: Math.min(deadlineAt ?? Infinity, budgetMs === undefined ? Infinity : Date.now() + budgetMs) };
+}
+/** `promise`, or `deadline_exceeded` once `deadlineAt` passes first. */
+export async function withinDeadline(promise, deadlineAt) {
+    if (deadlineAt === undefined)
+        return promise;
+    const remaining = deadlineAt - Date.now();
+    if (remaining <= 0) {
+        promise.catch(() => { });
+        throw deadlineExceeded(deadlineAt);
+    }
+    let timer;
+    try {
+        return await Promise.race([promise, new Promise((_resolve, reject) => { timer = setTimeout(() => reject(deadlineExceeded(deadlineAt)), remaining); })]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}

package/dist/resources/run-notice.d.ts

@@ -0,0 +1,34 @@
+import { JwksCache } from '@north-light/identity';
+/** The scope a run-notice token carries. */
+export declare const RUN_NOTICE_SCOPE = "crtr:run_notice";
+/** A run notice that failed verification. An app maps it to HTTP 401 and stores nothing. */
+export declare class RunNoticeError extends Error {
+    readonly status = 401;
+    constructor(message: string);
+}
+export interface RunNotice {
+    /** The person the run belongs to, `user:<id>` (the token's `sub`). */
+    userId: string;
+    /** The runtime that sent it, from the token's `act.sub` (never the body). */
+    runtime: string;
+    runId: string;
+    latestSequence: number;
+}
+export interface VerifyRunNoticeOptions {
+    /** The app's registered `run_notice_url`, exactly; the token's `aud` must equal it. */
+    runNoticeUrl: string;
+    /** The directory issuer. */
+    issuer: string;
+    /** The app's own principal, `app:<id>`; the token's `grantee` must equal it. */
+    grantee: string;
+    /** Override the directory key cache (default: one per issuer, keys from `<issuer>/.well-known/jwks.json`). */
+    jwks?: JwksCache;
+    /** The `fetch` used for the directory's keys when `jwks` is absent (default: the global `fetch`), as
+     *  `OAuth2Options.fetch`. Keys are cached per `(issuer, fetch)`, so a test double such as
+     *  `@north-light/sdk/testing`'s `FakeCloud` is verified against its own keys. */
+    fetch?: typeof fetch;
+}
+/** Verify a runtime→app run notice: the bearer is a directory-signed outbound token for `runNoticeUrl`
+ *  (signature, `iss`, `aud`, `exp`), scope exactly `crtr:run_notice`, `grantee` the app's own principal;
+ *  the body is `{run_id, latest_sequence}`. Throws `RunNoticeError` (answer 401) on any failure. */
+export declare function verifyRunNotice(request: Request, options: VerifyRunNoticeOptions): Promise<RunNotice>;

package/dist/resources/run-notice.js

@@ -0,0 +1,67 @@
+import { JwksCache, verifyOutboundToken } from '@north-light/identity';
+/** The scope a run-notice token carries. */
+export const RUN_NOTICE_SCOPE = 'crtr:run_notice';
+/** A run notice that failed verification. An app maps it to HTTP 401 and stores nothing. */
+export class RunNoticeError extends Error {
+    status = 401;
+    constructor(message) { super(message); this.name = 'RunNoticeError'; }
+}
+const jwksUrl = (issuer) => `${issuer.replace(/\/+$/, '')}/.well-known/jwks.json`;
+// One cache per issuer for the global fetch, and one per (issuer, fetch) pair for a caller's fetch: a cache built on
+// one fetch must never answer for another (an unknown kid is re-fetched at most every 30 s).
+const caches = new Map();
+const fetchCaches = new Map();
+function cacheFor(issuer, fetcher) {
+    if (fetcher === undefined) {
+        let cache = caches.get(issuer);
+        if (!cache) {
+            cache = new JwksCache(issuer, (input, init) => fetch(input, init), jwksUrl(issuer));
+            caches.set(issuer, cache);
+        }
+        return cache;
+    }
+    let byFetch = fetchCaches.get(issuer);
+    if (!byFetch) {
+        byFetch = new WeakMap();
+        fetchCaches.set(issuer, byFetch);
+    }
+    let cache = byFetch.get(fetcher);
+    if (!cache) {
+        cache = new JwksCache(issuer, (input, init) => fetcher(input, init), jwksUrl(issuer));
+        byFetch.set(fetcher, cache);
+    }
+    return cache;
+}
+/** Verify a runtime→app run notice: the bearer is a directory-signed outbound token for `runNoticeUrl`
+ *  (signature, `iss`, `aud`, `exp`), scope exactly `crtr:run_notice`, `grantee` the app's own principal;
+ *  the body is `{run_id, latest_sequence}`. Throws `RunNoticeError` (answer 401) on any failure. */
+export async function verifyRunNotice(request, options) {
+    const match = /^Bearer ([^\s]+)$/.exec(request.headers.get('authorization') ?? '');
+    if (match === null)
+        throw new RunNoticeError('The request carries no bearer token.');
+    let claims;
+    try {
+        claims = await verifyOutboundToken({ token: match[1], jwks: options.jwks ?? cacheFor(options.issuer, options.fetch), issuer: options.issuer, audience: options.runNoticeUrl });
+    }
+    catch {
+        throw new RunNoticeError('The bearer token is not a valid directory token for this endpoint.');
+    }
+    if (claims.scope !== RUN_NOTICE_SCOPE)
+        throw new RunNoticeError('The token scope is not crtr:run_notice.');
+    if (claims.grantee !== options.grantee)
+        throw new RunNoticeError('The token was minted for another app.');
+    const runtime = claims.act.sub;
+    if (typeof runtime !== 'string' || !runtime.startsWith('runtime:'))
+        throw new RunNoticeError('The token names no runtime.');
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch {
+        throw new RunNoticeError('The notice body is not JSON.');
+    }
+    const { run_id: runId, latest_sequence: latest } = (body ?? {});
+    if (typeof runId !== 'string' || runId === '' || typeof latest !== 'number' || !Number.isSafeInteger(latest) || latest < 0)
+        throw new RunNoticeError('The notice body is not {run_id, latest_sequence}.');
+    return { userId: claims.sub, runtime, runId, latestSequence: latest };
+}

package/dist/resources/run-reply.d.ts

@@ -0,0 +1,79 @@
+import type { AssistantStopReasonDTO, RunOutcomeDTO, RunStatusDTO, TurnErrorDTO } from '@north-light/api';
+import type { RunStream } from './run-stream.js';
+/** What `runs.message` returns: the message a reply answers. */
+export interface SentRunMessage {
+    run_id: string;
+    message_id: string;
+    sequence_number: number;
+}
+/** One event of the reply to a message (`runs.reply`). */
+export type RunReplyEvent = 
+/** Streamed text of the turn's current assistant message. */
+{
+    type: 'text.delta';
+    delta: string;
+    sequence_number: number;
+}
+/** One assistant message ended; `text` is its whole text, possibly empty (a refused or failed call writes none). */
+ | {
+    type: 'message.done';
+    text: string;
+    stop_reason: AssistantStopReasonDTO;
+    sequence_number: number;
+}
+/** The turn ended; always the last event of a reply that reached its turn. `error` is set when the turn's last assistant message stopped with `error`. */
+ | {
+    type: 'turn.completed';
+    run_status: Exclude<RunStatusDTO, 'settled'>;
+    stop_reason: string;
+    error?: TurnErrorDTO;
+    message_ids: string[];
+    sequence_number: number;
+}
+/** The run settled before the turn completed; the reply ends here. */
+ | {
+    type: 'run.settled';
+    outcome: RunOutcomeDTO;
+    sequence_number: number;
+};
+/** How a reply ended (`RunReply.collect`):
+ *  - `completed`: the turn finished cleanly; `text` may still be empty when the model wrote nothing.
+ *  - `error`: the turn's last assistant message failed; `error` says why.
+ *  - `waiting_on_user`: the turn ended on a question to the person; the run waits for an answer.
+ *  - `settled`: the run settled before the turn completed; `outcome` says how. */
+export type RunReplyEnding = 'completed' | 'error' | 'waiting_on_user' | 'settled';
+/** The whole reply, from `RunReply.collect`. */
+export interface RunReplyResult {
+    /** Every assistant message's trimmed text in the turn, joined with a blank line; empty when the turn wrote none. */
+    text: string;
+    ended: RunReplyEnding;
+    /** Set when `ended` is `error`. */
+    error?: TurnErrorDTO;
+    /** Set when `ended` is `settled`. */
+    outcome?: RunOutcomeDTO;
+}
+/** `RunReply.collect` options. */
+export interface RunReplyCollectOptions {
+    /** Called with each streamed piece of text. When a turn speaks again after a tool call, the first piece
+     *  of the new message starts with a blank line, so the pieces concatenate to `text` (up to trimming). */
+    onDelta?: (delta: string) => void;
+}
+/**
+ * The reply to one message: the root's turn that delivers it. Consume it once:
+ * iterate it, or call `collect()` (text plus how it ended, with an optional
+ * `onDelta` while it streams) or `text()`. It ends after `turn.completed` (or `run.settled`) and
+ * closes its event stream; aborting the `signal` rejects with `APIUserAbortError`.
+ */
+export declare class RunReply implements AsyncIterable<RunReplyEvent> {
+    private readonly open;
+    private readonly sent;
+    private consumed;
+    constructor(open: (after: number) => RunStream, sent: SentRunMessage);
+    [Symbol.asyncIterator](): AsyncIterator<RunReplyEvent>;
+    /** Consume the reply: stream its text to `onDelta` and resolve to the whole text and how the turn ended.
+     *  A stream that closes before the turn ends throws, as iterating does. */
+    collect(options?: RunReplyCollectOptions): Promise<RunReplyResult>;
+    /** The reply's text: every assistant message's trimmed text in the turn, joined with a blank line. Empty when the turn wrote none.
+     *  `onDelta` receives the text as it streams, as in `collect`. */
+    text(options?: RunReplyCollectOptions): Promise<string>;
+}

package/dist/resources/run-reply.js

@@ -0,0 +1,93 @@
+import { APIError } from '../errors.js';
+/**
+ * The reply to one message: the root's turn that delivers it. Consume it once:
+ * iterate it, or call `collect()` (text plus how it ended, with an optional
+ * `onDelta` while it streams) or `text()`. It ends after `turn.completed` (or `run.settled`) and
+ * closes its event stream; aborting the `signal` rejects with `APIUserAbortError`.
+ */
+export class RunReply {
+    open;
+    sent;
+    consumed = false;
+    constructor(open, sent) {
+        this.open = open;
+        this.sent = sent;
+    }
+    async *[Symbol.asyncIterator]() {
+        if (this.consumed)
+            throw new Error('a RunReply can be consumed only once');
+        this.consumed = true;
+        let stream = this.open(this.sent.sequence_number);
+        let inTurn = false;
+        try {
+            for (;;) {
+                for await (const event of stream) {
+                    if (event.node_id !== this.sent.run_id)
+                        continue;
+                    if (event.type === 'node.settled') {
+                        yield { type: 'run.settled', outcome: event.outcome, sequence_number: event.sequence_number };
+                        return;
+                    }
+                    if (!inTurn) {
+                        inTurn = event.type === 'node.turn.started' && event.input.message_ids.includes(this.sent.message_id);
+                        continue;
+                    }
+                    if (event.type === 'node.output_text.delta')
+                        yield { type: 'text.delta', delta: event.delta, sequence_number: event.sequence_number };
+                    else if (event.type === 'node.output_text.done')
+                        yield { type: 'message.done', text: event.text, stop_reason: event.stop_reason, sequence_number: event.sequence_number };
+                    else if (event.type === 'node.turn.completed') {
+                        yield {
+                            type: 'turn.completed', run_status: event.run_status, stop_reason: event.stop_reason,
+                            ...(event.error ? { error: event.error } : {}), message_ids: event.message_ids, sequence_number: event.sequence_number,
+                        };
+                        return;
+                    }
+                }
+                // The runtime closed a quiet stream (`event: idle`) before the turn ended. A reply still waits for its turn, so it reopens from the cursor.
+                if (!stream.idle)
+                    return;
+                const next = stream.position;
+                stream.abort();
+                await new Promise((resolve) => setTimeout(resolve, 500));
+                stream = this.open(next);
+            }
+        }
+        finally {
+            stream.abort();
+        }
+    }
+    /** Consume the reply: stream its text to `onDelta` and resolve to the whole text and how the turn ended.
+     *  A stream that closes before the turn ends throws, as iterating does. */
+    async collect(options = {}) {
+        const texts = [];
+        let partial = false;
+        for await (const event of this) {
+            if (event.type === 'text.delta') {
+                if (!event.delta)
+                    continue;
+                options.onDelta?.(!partial && texts.length ? `\n\n${event.delta}` : event.delta);
+                partial = true;
+            }
+            else if (event.type === 'message.done') {
+                if (event.text.trim())
+                    texts.push(event.text.trim());
+                partial = false;
+            }
+            else {
+                const text = texts.join('\n\n');
+                if (event.type === 'run.settled')
+                    return { text, ended: 'settled', outcome: event.outcome };
+                if (event.error)
+                    return { text, ended: 'error', error: event.error };
+                return { text, ended: event.run_status === 'waiting_on_user' ? 'waiting_on_user' : 'completed' };
+            }
+        }
+        throw new APIError(0, 'stream_error', 'the run event stream ended before the reply did', undefined, undefined, { retryable: false, run_id: this.sent.run_id });
+    }
+    /** The reply's text: every assistant message's trimmed text in the turn, joined with a blank line. Empty when the turn wrote none.
+     *  `onDelta` receives the text as it streams, as in `collect`. */
+    async text(options = {}) {
+        return (await this.collect(options)).text;
+    }
+}

package/dist/resources/run-stream.d.ts

@@ -0,0 +1,65 @@
+import type { RunEvent, RunEventBaseDTO, RunEventOf, RunEventType } from '@north-light/api';
+/** Every run event, discriminated on `type`: the daemon declares the union once and the SDK re-exports it. */
+export type { RunEvent, RunEventOf, RunEventType };
+export type RunEventListener<T extends RunEventType = RunEventType> = (event: RunEventOf<T>) => void;
+/** An event under a type this SDK version does not declare (a newer daemon's), or read by field name. */
+export type UnknownRunEvent = RunEventBaseDTO & {
+    type: string;
+    [field: string]: unknown;
+};
+/** How a `RunStream` ended without an error: the run `settled`, or the runtime closed an `idle` stream
+ *  (no running turn and no new event for its quiet window) and `cursor` is where to reopen it. */
+export interface RunStreamEnd {
+    reason: 'settled' | 'idle';
+    cursor: number;
+}
+/** A resumable run event stream. Closing it does not stop the run.
+ *
+ *  Iteration ends normally in exactly two cases, told apart by `idle`: the run settled (`idle` is false) or the
+ *  runtime sent `event: idle` and closed (`idle` is true: the run is quiet, nothing is lost, and `cursor` is where to
+ *  reopen with `runs.events(runId, {after: cursor})` when there is something to read). After the idle frame the
+ *  stream does not reconnect on its own. A transport or protocol failure throws instead, as before. */
+export declare class RunStream implements AsyncIterable<RunEvent> {
+    private readonly open;
+    private readonly onReconnect?;
+    private readonly controller;
+    private readonly listeners;
+    private cursor;
+    private readonly outcome;
+    private resolveOutcome;
+    private rejectOutcome;
+    private finished;
+    private readonly events;
+    private wake?;
+    private failure;
+    private idled;
+    private readonly ended;
+    private resolveEnded;
+    private rejectEnded;
+    constructor(open: (after: number, signal: AbortSignal) => Promise<Response>, after?: number, signal?: AbortSignal, onReconnect?: ((state: "reconnecting" | "reconnected", error?: unknown) => void) | undefined);
+    on<T extends RunEventType>(type: T, listener: RunEventListener<T>): this;
+    on(type: string, listener: (event: RunEvent | UnknownRunEvent) => void): this;
+    off<T extends RunEventType>(type: T, listener: RunEventListener<T>): this;
+    off(type: string, listener: (event: RunEvent | UnknownRunEvent) => void): this;
+    abort(): void;
+    /** True once the runtime sent `event: idle` and closed the stream: the run has had no running turn and no new
+     *  event for the runtime's quiet window. The stream has ended and will not reconnect. */
+    get idle(): boolean;
+    /** The `sequence_number` of the last event delivered (the `after` this stream was given until one arrives).
+     *  After `idle`, reopen with `runs.events(runId, {after: stream.cursor})`. */
+    get position(): number;
+    /** Resolves when the stream ends without an error: `{reason: 'settled', cursor}` after `node.settled`, or
+     *  `{reason: 'idle', cursor}` after the runtime's idle close. Rejects with the transport or protocol failure, or
+     *  `APIUserAbortError` after `abort()`. */
+    whenEnded(): Promise<RunStreamEnd>;
+    /** Resolves to the run's `node.settled` event. */
+    finalOutcome(): Promise<RunEventOf<'node.settled'>>;
+    /** The run's `waiting_on_user` events: each carries a question (`question_id, initiating_app, title, subtitle?, steps, slots`). */
+    waitingOnUser(): AsyncIterable<RunEventOf<'waiting_on_user'>>;
+    [Symbol.asyncIterator](): AsyncIterator<RunEvent>;
+    private finish;
+    private deliver;
+    private consume;
+    private record;
+    private deliverPayload;
+}

package/dist/resources/run-stream.js

@@ -0,0 +1,243 @@
+import { APIError, APIUserAbortError, mapError } from '../errors.js';
+/** A resumable run event stream. Closing it does not stop the run.
+ *
+ *  Iteration ends normally in exactly two cases, told apart by `idle`: the run settled (`idle` is false) or the
+ *  runtime sent `event: idle` and closed (`idle` is true: the run is quiet, nothing is lost, and `cursor` is where to
+ *  reopen with `runs.events(runId, {after: cursor})` when there is something to read). After the idle frame the
+ *  stream does not reconnect on its own. A transport or protocol failure throws instead, as before. */
+export class RunStream {
+    open;
+    onReconnect;
+    controller = new AbortController();
+    listeners = new Map();
+    cursor;
+    outcome;
+    resolveOutcome;
+    rejectOutcome;
+    finished = false;
+    events = [];
+    wake;
+    failure;
+    idled = false;
+    ended;
+    resolveEnded;
+    rejectEnded;
+    constructor(open, after = 0, signal, onReconnect) {
+        this.open = open;
+        this.onReconnect = onReconnect;
+        if (!Number.isSafeInteger(after) || after < 0)
+            throw new RangeError('after must be a non-negative safe integer');
+        this.cursor = after;
+        this.outcome = new Promise((resolve, reject) => { this.resolveOutcome = resolve; this.rejectOutcome = reject; });
+        void this.outcome.catch(() => undefined);
+        this.ended = new Promise((resolve, reject) => { this.resolveEnded = resolve; this.rejectEnded = reject; });
+        void this.ended.catch(() => undefined);
+        if (signal?.aborted)
+            this.controller.abort(signal.reason);
+        else
+            signal?.addEventListener('abort', () => this.controller.abort(signal.reason), { once: true });
+        void this.consume();
+    }
+    on(type, listener) {
+        const set = this.listeners.get(type) ?? new Set();
+        set.add(listener);
+        this.listeners.set(type, set);
+        return this;
+    }
+    off(type, listener) { this.listeners.get(type)?.delete(listener); return this; }
+    abort() { this.controller.abort(); }
+    /** True once the runtime sent `event: idle` and closed the stream: the run has had no running turn and no new
+     *  event for the runtime's quiet window. The stream has ended and will not reconnect. */
+    get idle() { return this.idled; }
+    /** The `sequence_number` of the last event delivered (the `after` this stream was given until one arrives).
+     *  After `idle`, reopen with `runs.events(runId, {after: stream.cursor})`. */
+    get position() { return this.cursor; }
+    /** Resolves when the stream ends without an error: `{reason: 'settled', cursor}` after `node.settled`, or
+     *  `{reason: 'idle', cursor}` after the runtime's idle close. Rejects with the transport or protocol failure, or
+     *  `APIUserAbortError` after `abort()`. */
+    whenEnded() { return this.ended; }
+    /** Resolves to the run's `node.settled` event. */
+    finalOutcome() { return this.outcome; }
+    /** The run's `waiting_on_user` events: each carries a question (`question_id, initiating_app, title, subtitle?, steps, slots`). */
+    async *waitingOnUser() {
+        for await (const event of this)
+            if (event.type === 'waiting_on_user')
+                yield event;
+    }
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            if (this.events.length) {
+                yield this.events.shift();
+                continue;
+            }
+            if (this.finished) {
+                if (this.failure)
+                    throw this.failure;
+                return;
+            }
+            await new Promise((resolve) => { this.wake = resolve; });
+        }
+    }
+    finish(error) {
+        if (this.finished)
+            return;
+        this.finished = true;
+        this.failure = error;
+        if (error) {
+            this.rejectOutcome(error);
+            this.rejectEnded(error);
+        }
+        else
+            this.resolveEnded({ reason: this.idled ? 'idle' : 'settled', cursor: this.cursor });
+        this.wake?.();
+        this.wake = undefined;
+    }
+    deliver(event) {
+        if (!Number.isSafeInteger(event.sequence_number) || event.sequence_number <= this.cursor)
+            return;
+        this.cursor = event.sequence_number;
+        this.events.push(event);
+        for (const listener of this.listeners.get(event.type) ?? [])
+            listener(event);
+        this.wake?.();
+        this.wake = undefined;
+        if (event.type === 'node.settled') {
+            this.resolveOutcome(event);
+            this.finish();
+        }
+    }
+    async consume() {
+        let attempt = 0;
+        let failedReconnect = false;
+        while (!this.controller.signal.aborted && !this.finished) {
+            const connection = new AbortController();
+            const stop = () => connection.abort();
+            this.controller.signal.addEventListener('abort', stop, { once: true });
+            let idle;
+            let opened = false;
+            const resetIdle = () => { if (idle)
+                clearTimeout(idle); idle = setTimeout(() => connection.abort(), 45_000); };
+            try {
+                const response = await this.open(this.cursor, connection.signal);
+                opened = true;
+                if (!response.ok)
+                    throw await streamResponseError(response);
+                if (!response.body)
+                    throw new Error('Run event stream has no body');
+                if (failedReconnect) {
+                    this.onReconnect?.('reconnected');
+                    failedReconnect = false;
+                }
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                const ndjson = response.headers.get('content-type')?.includes('application/x-ndjson') ?? false;
+                let buffer = '';
+                if (!ndjson)
+                    resetIdle();
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (!ndjson)
+                        resetIdle();
+                    buffer += decoder.decode(value, { stream: true });
+                    const records = ndjson ? buffer.split(/\r?\n/) : buffer.split(/\r\n\r\n|\n\n|\r\r/);
+                    buffer = records.pop() ?? '';
+                    for (const record of records) {
+                        if (ndjson)
+                            this.deliverPayload(JSON.parse(record));
+                        else
+                            this.record(record);
+                        if (this.idled)
+                            this.finish();
+                        if (this.finished) {
+                            await reader.cancel();
+                            return;
+                        }
+                    }
+                }
+                if (buffer) {
+                    if (ndjson)
+                        this.deliverPayload(JSON.parse(buffer));
+                    else
+                        this.record(buffer);
+                    if (this.idled)
+                        this.finish();
+                    if (this.finished)
+                        return;
+                }
+                attempt = 0;
+            }
+            catch (error) {
+                if (this.controller.signal.aborted)
+                    break;
+                if ((!opened && !(error instanceof APIError)) ||
+                    (error instanceof APIError && (error.code === 'stream_dropped' || error.code === 'stream_error' || !error.retryable))) {
+                    this.finish(error);
+                    return;
+                }
+                if (attempt > 0) {
+                    failedReconnect = true;
+                    this.onReconnect?.('reconnecting', error);
+                }
+            }
+            finally {
+                if (idle)
+                    clearTimeout(idle);
+                this.controller.signal.removeEventListener('abort', stop);
+            }
+            if (this.finished || this.controller.signal.aborted)
+                break;
+            const delay = Math.min(30_000, 500 * 2 ** Math.min(attempt++, 6));
+            try {
+                await new Promise((resolve, reject) => {
+                    const timer = setTimeout(resolve, delay);
+                    this.controller.signal.addEventListener('abort', () => { clearTimeout(timer); reject(new Error('aborted')); }, { once: true });
+                });
+            }
+            catch {
+                break;
+            }
+        }
+        if (this.controller.signal.aborted)
+            this.finish(new APIUserAbortError(0, 'request_aborted', 'run stream aborted by caller'));
+    }
+    record(record) {
+        let type;
+        const data = [];
+        for (const line of record.split(/\r\n|\n|\r/)) {
+            if (line.startsWith(':'))
+                continue;
+            const separator = line.indexOf(':');
+            const field = separator === -1 ? line : line.slice(0, separator);
+            const value = separator === -1 ? '' : line.slice(separator + 1).replace(/^ /, '');
+            if (field === 'event')
+                type = value;
+            if (field === 'data')
+                data.push(value);
+        }
+        // The runtime's idle close: a quiet run, not an event. It carries no sequence number and is never delivered.
+        if (type === 'idle') {
+            if (!this.finished)
+                this.idled = true;
+            return;
+        }
+        if (!type || !data.length)
+            return;
+        const payload = JSON.parse(data.join('\n'));
+        this.deliverPayload({ ...payload, type });
+    }
+    deliverPayload(payload) {
+        if (payload.type === 'error') {
+            const envelope = (payload.error ?? payload);
+            throw new APIError(0, envelope.code ?? 'stream_error', envelope.message ?? 'Run stream error', envelope.details, undefined, envelope);
+        }
+        // A newer daemon may send an event type this SDK does not declare; it is delivered as-is.
+        this.deliver(payload);
+    }
+}
+async function streamResponseError(response) {
+    const payload = await response.json();
+    const error = payload.error;
+    return mapError(new APIError(response.status, error?.code ?? 'invalid_response', error?.message ?? `HTTP ${response.status}`, error?.details, response.headers, error));
+}