@north-light/sdk 0.0.0-stage → 0.3.414

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

@@ -0,0 +1,98 @@
+import type { Crouter } from '../client.js';
+import type { RunActivity, RunObject } from './runs.js';
+/** A run the app is still waiting on: whose runtime holds it, and its id. `pending()` returns these from the app's own rows. */
+export interface PendingRun {
+    userId: string;
+    runId: string;
+}
+/** How a watched run came to rest. `gone`: the runtime answered 404 `not_found` for it (the run was deleted). */
+export type RunEnding = 'settled' | 'idle' | 'waiting_on_user' | 'gone';
+/** One ending `RunWatcher` hands to `onEnded`. `run` is the `runs.get` answer that came to rest, or `null` when `gone`. */
+export type RunEnded = {
+    userId: string;
+    runId: string;
+    ended: Exclude<RunEnding, 'gone'>;
+    run: RunObject;
+} | {
+    userId: string;
+    runId: string;
+    ended: 'gone';
+    run: null;
+};
+/** One live-progress reading `RunWatcher` hands to `onActivity`: a `running` run's `activity` and the `runs.get` answer it came from. */
+export interface RunActivityEvent {
+    userId: string;
+    runId: string;
+    activity: RunActivity | null;
+    run: RunObject;
+}
+export interface RunWatchOptions {
+    /** Every run the app still waits on, read from its own rows (the durable record). Called at `start()`, every
+     *  `sweepMs`, after each delivery, and on `nudge()`. Stop returning a run once `onEnded` has landed it. */
+    pending: () => Promise<PendingRun[]> | PendingRun[];
+    /** Land one ending. At least once per `(runId, status, latest_sequence)`: make it idempotent (guard the write on
+     *  the row still waiting on that run). If it throws, the same ending is retried after 5 s, doubling to 5 min. */
+    onEnded: (event: RunEnded) => Promise<void> | void;
+    /** Told about every failure the watcher recovers from itself: a throwing `pending()` or `onEnded`, a transient
+     *  runtime error, a missing (`not_connected`) or refused connection. Defaults to ignoring them. */
+    onError?: (error: unknown, run: PendingRun | null) => void;
+    /** Live progress, best effort: called with each read of a run that is still `running` whose `activity` differs from
+     *  the last one handed over for that run (compared as JSON: `phase`, plus `tool.name` and `tool.summary`). Never
+     *  awaited by the watcher: at most one call per run runs at a time, and a newer reading taken meanwhile replaces any
+     *  still waiting, so the next call gets the newest. A call may finish after `onEnded` for that run: guard the write on
+     *  the row still waiting on the run. A throw goes to `onError` and is not retried; it never delays or changes
+     *  `onEnded`. When set, running runs are read with `wait: activityWait` instead of 25 s. */
+    onActivity?: (event: RunActivityEvent) => Promise<void> | void;
+    /** Seconds each read of a running run waits while `onActivity` is set: an integer 1–25, default 2. A run that comes
+     *  to rest still answers at once. A followed run is read at least this often; a run waiting for a `concurrency` slot
+     *  or backing off after a failure is not read. */
+    activityWait?: number;
+    /** Milliseconds between sweeps of `pending()`. Default 30 000. */
+    sweepMs?: number;
+    /** Most runs followed with an open long-poll at once. Default 50; the rest wait their turn. */
+    concurrency?: number;
+}
+/**
+ * Follows an app's background runs until each comes to rest (`settled`, `idle`, `waiting_on_user`, or deleted),
+ * and hands each ending to `onEnded` at least once. Build it with `oauth.watchRuns(...)`, then `start()`.
+ *
+ * Delivery is keyed in memory on `(runId, status, latest_sequence)`: a run still in `pending()` after delivery is
+ * re-read once per sweep without `wait` and delivered again only when that key changes (it worked again, or an
+ * `idle` run was later canceled to `settled`); a sweep that reads `running` goes back to the long-poll. The app's
+ * rows are the durable record, so a restarted watcher re-derives everything from `pending()`.
+ *
+ * With `onActivity`, each running read whose `activity` (as JSON) differs from the last handed over is reported,
+ * and running runs are read with a short `wait` (`activityWait`), since the runtime's long-poll answers early only at rest.
+ */
+export declare class RunWatcher {
+    private readonly open;
+    private readonly options;
+    /** The `wait` of each read of a running run: 25, or `activityWait` while `onActivity` is set. */
+    private readonly runningWait;
+    /** The last key delivered per runId: `${status}:${latest_sequence}`, or `gone`. */
+    private readonly delivered;
+    /** The last `activity` handed to `onActivity` per runId, as JSON. Cleared when the run rests. */
+    private readonly activitySeen;
+    /** Runs with an `onActivity` call in flight, each with the newest reading taken meanwhile (null: none). */
+    private readonly activityCalls;
+    /** Runs that rested and were delivered: re-read only on sweeps. */
+    private readonly resting;
+    private readonly follower;
+    constructor(open: (userId: string) => Promise<Crouter>, options: RunWatchOptions);
+    private get running();
+    /** Read `pending()` and begin following; sweeps repeat every `sweepMs` until `stop()`. Resolves after the first sweep. */
+    start(): Promise<void>;
+    /** Sweep now instead of waiting for `sweepMs`, for example right after the app starts a run it will watch. */
+    nudge(): void;
+    /** Stop sweeping, abort every open long-poll, and resolve once every loop has ended. No handler starts afterwards;
+     *  an `onActivity` call already running is not waited for. */
+    stop(): Promise<void>;
+    private forget;
+    /** One loop: read the run until it rests, deliver once per key, then leave it to the sweeps (`park`). */
+    private follow;
+    /** Hand a running run's activity to `onActivity` once per distinct value, without blocking the follow loop. */
+    private progress;
+    /** Run `onActivity` for one run, then for the newest reading taken meanwhile, until none waits or the watcher stops. */
+    private callActivity;
+    private deliver;
+}

package/dist/resources/run-watcher.js

@@ -0,0 +1,162 @@
+import { APIError, CrouterError } from '../errors.js';
+import { Follower, troubleResult } from './follower.js';
+const defaultActivityWait = 2;
+const restingStatuses = new Set(['settled', 'idle', 'waiting_on_user']);
+/**
+ * Follows an app's background runs until each comes to rest (`settled`, `idle`, `waiting_on_user`, or deleted),
+ * and hands each ending to `onEnded` at least once. Build it with `oauth.watchRuns(...)`, then `start()`.
+ *
+ * Delivery is keyed in memory on `(runId, status, latest_sequence)`: a run still in `pending()` after delivery is
+ * re-read once per sweep without `wait` and delivered again only when that key changes (it worked again, or an
+ * `idle` run was later canceled to `settled`); a sweep that reads `running` goes back to the long-poll. The app's
+ * rows are the durable record, so a restarted watcher re-derives everything from `pending()`.
+ *
+ * With `onActivity`, each running read whose `activity` (as JSON) differs from the last handed over is reported,
+ * and running runs are read with a short `wait` (`activityWait`), since the runtime's long-poll answers early only at rest.
+ */
+export class RunWatcher {
+    open;
+    options;
+    /** The `wait` of each read of a running run: 25, or `activityWait` while `onActivity` is set. */
+    runningWait;
+    /** The last key delivered per runId: `${status}:${latest_sequence}`, or `gone`. */
+    delivered = new Map();
+    /** The last `activity` handed to `onActivity` per runId, as JSON. Cleared when the run rests. */
+    activitySeen = new Map();
+    /** Runs with an `onActivity` call in flight, each with the newest reading taken meanwhile (null: none). */
+    activityCalls = new Map();
+    /** Runs that rested and were delivered: re-read only on sweeps. */
+    resting = new Set();
+    follower;
+    constructor(open, options) {
+        this.open = open;
+        this.options = options;
+        const activityWait = options.activityWait ?? defaultActivityWait;
+        this.follower = new Follower({
+            name: 'RunWatcher',
+            items: () => options.pending(),
+            key: (run) => run.runId,
+            turn: (run, signal) => this.follow(run, signal),
+            // A deleted run cannot come back: once `gone` is delivered it is not read again while pending() returns it.
+            admit: (runId) => this.delivered.get(runId) !== 'gone',
+            onForget: (runId) => this.forget(runId),
+            onError: options.onError,
+            sweepMs: options.sweepMs ?? 30_000,
+            concurrency: options.concurrency ?? 50,
+        });
+        if (!Number.isInteger(activityWait) || activityWait < 1 || activityWait > 25)
+            throw new CrouterError('activityWait must be an integer from 1 to 25');
+        this.runningWait = options.onActivity ? activityWait : 25;
+    }
+    get running() { return this.follower.isRunning; }
+    /** Read `pending()` and begin following; sweeps repeat every `sweepMs` until `stop()`. Resolves after the first sweep. */
+    start() { return this.follower.start(); }
+    /** Sweep now instead of waiting for `sweepMs`, for example right after the app starts a run it will watch. */
+    nudge() { this.follower.nudge(); }
+    /** Stop sweeping, abort every open long-poll, and resolve once every loop has ended. No handler starts afterwards;
+     *  an `onActivity` call already running is not waited for. */
+    stop() { return this.follower.stop(); }
+    forget(runId) {
+        this.delivered.delete(runId);
+        this.resting.delete(runId);
+        this.activitySeen.delete(runId);
+        if (this.activityCalls.has(runId))
+            this.activityCalls.set(runId, null);
+    }
+    /** One loop: read the run until it rests, deliver once per key, then leave it to the sweeps (`park`). */
+    async follow(run, signal) {
+        let client;
+        try {
+            client = await this.open(run.userId);
+        }
+        catch (error) {
+            return troubleResult(this.follower, error, run);
+        }
+        // A run delivered before is re-read once without waiting: waitRun answers a resting run at once, so a
+        // long-poll would spin. Only a run seen running (or never delivered) long-polls.
+        let plain = this.resting.has(run.runId);
+        for (;;) {
+            if (signal.aborted || !this.running)
+                return 'park';
+            let current;
+            try {
+                current = await client.runs.get(run.runId, plain ? { signal } : { signal, wait: this.runningWait });
+            }
+            catch (error) {
+                if (signal.aborted || !this.running)
+                    return 'park';
+                if (error instanceof APIError && error.status === 404 && error.code === 'not_found' && error.origin === 'runtime') {
+                    return this.deliver(run, 'gone', { userId: run.userId, runId: run.runId, ended: 'gone', run: null });
+                }
+                return troubleResult(this.follower, error, run);
+            }
+            if (!restingStatuses.has(current.status)) {
+                plain = false;
+                this.resting.delete(run.runId);
+                this.progress(run, current);
+                continue;
+            }
+            // At rest: a later run of the same id reports its first phase again, and no reading still waiting is handed over.
+            this.activitySeen.delete(run.runId);
+            if (this.activityCalls.has(run.runId))
+                this.activityCalls.set(run.runId, null);
+            const key = `${current.status}:${current.latest_sequence}`;
+            if (this.delivered.get(run.runId) === key) {
+                this.resting.add(run.runId);
+                return 'park';
+            }
+            return this.deliver(run, key, { userId: run.userId, runId: run.runId, ended: current.status, run: current });
+        }
+    }
+    /** Hand a running run's activity to `onActivity` once per distinct value, without blocking the follow loop. */
+    progress(run, current) {
+        if (!this.options.onActivity || !this.running)
+            return;
+        const activity = current.activity ?? null;
+        const key = JSON.stringify(activity);
+        if (this.activitySeen.get(run.runId) === key)
+            return;
+        this.activitySeen.set(run.runId, key);
+        const event = { userId: run.userId, runId: run.runId, activity, run: current };
+        // One call per run at a time: a reading taken while one runs replaces any still waiting.
+        if (this.activityCalls.has(run.runId)) {
+            this.activityCalls.set(run.runId, event);
+            return;
+        }
+        this.activityCalls.set(run.runId, null);
+        void this.callActivity(run, event);
+    }
+    /** Run `onActivity` for one run, then for the newest reading taken meanwhile, until none waits or the watcher stops. */
+    async callActivity(run, first) {
+        let event = first;
+        while (event && this.running) {
+            try {
+                await this.options.onActivity(event);
+            }
+            catch (error) {
+                this.follower.report(error, run);
+            }
+            event = this.activityCalls.get(run.runId) ?? null;
+            this.activityCalls.set(run.runId, null);
+        }
+        this.activityCalls.delete(run.runId);
+    }
+    async deliver(run, key, event) {
+        if (!this.running)
+            return 'park';
+        try {
+            await this.options.onEnded(event);
+        }
+        catch (error) {
+            this.follower.report(error, run);
+            return 'fail';
+        }
+        this.delivered.set(run.runId, key);
+        this.resting.add(run.runId);
+        this.follower.succeeded(run.runId);
+        // The app has likely landed it; re-read pending() so the set shrinks (and the next run gets a slot) promptly.
+        if (this.running)
+            void this.follower.sweep();
+        return 'park';
+    }
+}

package/dist/resources/runs.d.ts

@@ -0,0 +1,192 @@
+import { RunStream } from './run-stream.js';
+import { RunReply, type SentRunMessage } from './run-reply.js';
+import type { Questions, Question, QuestionResponses } from './questions.js';
+import type { JsonSchema, OutputSchema, RequestOptions, SchemaOutput } from '../types.js';
+import type { RunActivityDTO, RunOutcomeDTO, RunTraceDTO, TurnErrorDTO } from '@north-light/api';
+export interface RunStartParams {
+    prompt: string;
+    scopes?: string[];
+    metadata?: Record<string, unknown>;
+    /** Launch every node without network or the app's files mount. Descendants cannot disable it. */
+    isolated?: boolean;
+    /** Profile id (`profile_id` from `profiles.list()`) the run's agent uses; absent uses the app's default profile. */
+    profile?: string;
+    /** A JSON Schema, or an object with `toJSONSchema()` (a Zod v4 object), the run's result must satisfy.
+     *  Sent as a JSON object; the daemon refuses one that is not an object or is over 256 KB serialized
+     *  (`invalid_request`, `param: output_schema`), which is raised without a resend. The SDK does not
+     *  validate results against it. */
+    output_schema?: JsonSchema | {
+        toJSONSchema(): JsonSchema;
+    };
+    /** A first message, stored with the run as a `start_turn: false` message: it always joins the first turn
+     *  as context ahead of `prompt`. The result's `message` is what `runs.reply` takes to follow that turn. */
+    message?: string;
+}
+export interface RunStartResult {
+    run_id: string;
+    node_id: string;
+    grantee: string;
+    grant: string;
+    rev: number;
+    scopes: string[] | null;
+    payer: 'user';
+    status: 'running';
+    created_at: string;
+    metadata: Record<string, unknown>;
+    sequence_number: number;
+    /** Present when `RunStartParams.message` was sent: pass it to `runs.reply(run.run_id, run.message)`. */
+    message?: SentRunMessage;
+}
+export type RunStatus = 'running' | 'waiting_on_user' | 'idle' | 'settled';
+export interface RunObject {
+    run_id: string;
+    name: string;
+    status: RunStatus;
+    /** Present once the run settled: `finalized`; `declined` with `details: {reason, code, retryable}`;
+     *  `canceled`; `deadline_exceeded`; `runtime_error` with `details.crouter_reason`. */
+    outcome?: RunOutcomeDTO;
+    /** The validated `output_schema` result, exactly as the daemon sent it; present when `outcome.kind` is `result` and one was submitted. */
+    result?: unknown;
+    last_report?: string;
+    /** Present when the root's latest completed turn ended in error; the next turn that completes without one clears it. */
+    last_turn_error?: TurnErrorDTO;
+    pending_question_ids: string[];
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens: number;
+        cache_write_tokens: number;
+        cost_usd: number;
+    };
+    payer: 'user';
+    scopes: string[] | null;
+    metadata: Record<string, unknown>;
+    created_at: string;
+    settled_at?: string;
+    latest_sequence: number;
+    last_activity_at: string;
+    /** What the root is doing while the run is `running`, else null: `starting`, `thinking`, `tool` (with `tool.name`
+     *  and a one-line `tool.summary`), `writing`, `submitting_result` (writing or recording the `output_schema` result), or
+     *  `between_turns`. Poll `runs.get` for a progress badge instead of
+     *  reading `runs.trace`. */
+    activity: RunActivity | null;
+}
+/** `RunObject.activity` while the run is `running`. */
+export type RunActivity = RunActivityDTO;
+/** A profile an app may start runs with (`profiles.list()`). Pass `profile_id` as `RunStartParams.profile`. */
+export interface AppProfile {
+    profile_id: string;
+    name: string;
+    grantee: string;
+    default_kind: string;
+    default: boolean;
+}
+export interface RunDeleteResult {
+    run_id: string;
+    uploads_pending: number;
+}
+/** `runs.trace` in its rendered form; message `content` narrows on `type` and role fields on `role`. */
+export type RunTrace = RunTraceDTO;
+/** A settled `runs.parse` run: the run outcome plus `output_parsed`, typed to the schema and non-null exactly when `kind` is `result`. */
+export type RunParsedOutcome<T> = (Extract<RunOutcomeDTO, {
+    kind: 'result';
+}> & {
+    output_parsed: T;
+}) | (Exclude<RunOutcomeDTO, {
+    kind: 'result';
+}> & {
+    output_parsed: null;
+});
+/** `runs.parse` params: `runs.start`'s, with `output_schema` required. */
+export type RunParseParams<TSchema> = Omit<RunStartParams, 'output_schema'> & {
+    output_schema: TSchema;
+};
+export interface RunParseOptions extends RequestOptions {
+    /** Answers each open question once, by id, with one response per slot. Without it `parse` rejects `waiting_on_user`. */
+    onQuestion?: (question: Question) => QuestionResponses | Promise<QuestionResponses>;
+    idempotencyKey?: string;
+}
+export type RunRequest = <T>(method: string, path: string, body?: unknown, options?: RequestOptions) => Promise<T>;
+export declare class Runs {
+    private readonly request;
+    private readonly openEvents;
+    private readonly questions?;
+    constructor(request: RunRequest, openEvents: (runId: string, after: number, signal: AbortSignal) => Promise<Response>, questions?: Questions | undefined);
+    start(params: RunStartParams, options?: RequestOptions & {
+        idempotencyKey?: string;
+    }): Promise<RunStartResult>;
+    get(runId: string, options?: RequestOptions & {
+        wait?: number;
+    }): Promise<RunObject>;
+    list(filters?: {
+        status?: RunStatus;
+        after?: string;
+        limit?: number;
+    }, options?: RequestOptions): Promise<{
+        runs: RunObject[];
+        next: string | null;
+    }>;
+    /** Every run across pages, most recently active first: `for await (const run of runs.listAll())`. Fetches
+     *  the next page (`limit` per page) only as you iterate; `break` stops fetching. */
+    listAll(filters?: {
+        status?: RunStatus;
+        limit?: number;
+    }, options?: RequestOptions): AsyncGenerator<RunObject, void, undefined>;
+    /** Send a message to a run. `start_turn: true` (the default) answers it in its
+     *  own turn: a running run receives it when its current turn ends, and a
+     *  message sent before the first turn has started queues behind that turn,
+     *  because a run's `runs.start` prompt is always its first turn's input.
+     *  `start_turn: false` stores it without starting a turn; it is delivered as
+     *  context at the start of the next turn, ahead of that turn's input. For a
+     *  new run that is the first turn only if it is stored before the run claims
+     *  its first turn's messages; to guarantee it, pass `message` to `runs.start`.
+     *
+     *  The send carries an `Idempotency-Key`: `idempotencyKey` when given, otherwise a UUID generated for this
+     *  call and reused on every retry of it. The daemon keeps the key for 24 hours; a repeat with the same key
+     *  and the same message returns the first send's result without delivering again, and the same key with a
+     *  different message or `start_turn` throws `ConflictError` `idempotency_conflict`. To make a send safe
+     *  across your own restarts, derive the key from your own record of the send (a batch or row id). */
+    message(runId: string, message: string, options?: RequestOptions & {
+        start_turn?: boolean;
+        idempotencyKey?: string;
+    }): Promise<SentRunMessage>;
+    interrupt(runId: string, options?: RequestOptions & {
+        children?: 'stop' | 'continue';
+    }): Promise<RunObject>;
+    cancel(runId: string, options?: RequestOptions & {
+        keepSchedules?: boolean;
+    }): Promise<RunObject>;
+    /** Delete the run, running or not: the runtime stops its turns and sandboxes itself, so there is no need to
+     *  `cancel` first. Deleting a run that is already gone throws `NotFoundError` (404).
+     *  `uploads_pending` counts the run's released uploads storage has not yet confirmed deleted; the runtime retries those. */
+    delete(runId: string, options?: RequestOptions): Promise<RunDeleteResult>;
+    /** Rename the caller's own run. The name is trimmed, must not be empty, and is at most 200 characters. */
+    rename(runId: string, name: string, options?: RequestOptions): Promise<RunObject>;
+    trace(runId: string, options?: RequestOptions & {
+        format?: 'entries';
+    }): Promise<RunTrace>;
+    events(runId: string, options?: {
+        after?: number;
+        signal?: AbortSignal;
+        onReconnect?: (state: 'reconnecting' | 'reconnected', error?: unknown) => void;
+    }): RunStream;
+    /** Follow the reply to one message: `sent` is what `runs.message` returned, or `runs.start`'s `message`. Reads the run's events after
+     *  `sent.sequence_number`, keeps the root's, starts at the turn that delivers the message and ends after that
+     *  turn's `turn.completed` (or the run's settlement). Several messages delivered in one turn share that turn's reply.
+     *  An expired cursor throws `stream_gap`. */
+    reply(runId: string, sent: SentRunMessage, options?: {
+        signal?: AbortSignal;
+    }): RunReply;
+    stream(params: RunStartParams, options?: RequestOptions & {
+        idempotencyKey?: string;
+    }): RunStream;
+    /** Long-polls `runs.get` until the run is `settled`, `waiting_on_user`, or `idle`, and returns that response
+     *  unchanged (`result` is not parsed). Aborting `signal` rejects with its reason and leaves the run as it is. */
+    wait(runId: string, options?: RequestOptions): Promise<RunObject>;
+    /** Start a run with `output_schema` and wait for it to settle; resolves with the outcome and `output_parsed`
+     *  typed to the schema. `onQuestion` answers each open question once; without it, a question rejects with
+     *  `APIError` code `waiting_on_user`. A run that stops without settling rejects `run_idle` (untouched:
+     *  send `runs.message` or `runs.cancel`). Aborting `signal` rejects with its reason; the run is never canceled. */
+    parse<TSchema extends OutputSchema>(params: RunParseParams<TSchema>, options?: RunParseOptions): Promise<RunParsedOutcome<SchemaOutput<TSchema>>>;
+    private parseRun;
+}

package/dist/resources/runs.js

@@ -0,0 +1,208 @@
+import { APIError } from '../errors.js';
+import { RunStream } from './run-stream.js';
+import { RunReply } from './run-reply.js';
+import { resolveJsonSchema } from '../schema.js';
+import { heldReadOptions } from './request.js';
+export class Runs {
+    request;
+    openEvents;
+    questions;
+    constructor(request, openEvents, questions) {
+        this.request = request;
+        this.openEvents = openEvents;
+        this.questions = questions;
+    }
+    async start(params, options = {}) {
+        const { idempotencyKey = crypto.randomUUID(), maxRetries = 2, ...rest } = options;
+        const body = params.output_schema === undefined ? params : { ...params, output_schema: resolveJsonSchema(params.output_schema) };
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.request('POST', '/v1/runs', body, { ...rest, maxRetries: 0, headers: { ...rest.headers, 'Idempotency-Key': idempotencyKey } });
+            }
+            catch (error) {
+                if (attempt >= maxRetries || !(error instanceof APIError) || !retryableSend(error))
+                    throw error;
+                await pause(error.retryAfterS ? error.retryAfterS * 1_000 : 500 * 2 ** attempt, rest.signal);
+            }
+        }
+    }
+    get(runId, options = {}) {
+        const { wait, ...rest } = options;
+        return this.request('GET', `${runPath(runId)}${query({ wait })}`, undefined, heldReadOptions(wait, rest));
+    }
+    list(filters = {}, options) {
+        return this.request('GET', `/v1/runs${query(filters)}`, undefined, options);
+    }
+    /** Every run across pages, most recently active first: `for await (const run of runs.listAll())`. Fetches
+     *  the next page (`limit` per page) only as you iterate; `break` stops fetching. */
+    async *listAll(filters = {}, options) {
+        for (let after;;) {
+            const page = await this.list({ ...filters, ...(after === undefined ? {} : { after }) }, options);
+            yield* page.runs;
+            if (!page.next)
+                return;
+            after = page.next;
+        }
+    }
+    /** Send a message to a run. `start_turn: true` (the default) answers it in its
+     *  own turn: a running run receives it when its current turn ends, and a
+     *  message sent before the first turn has started queues behind that turn,
+     *  because a run's `runs.start` prompt is always its first turn's input.
+     *  `start_turn: false` stores it without starting a turn; it is delivered as
+     *  context at the start of the next turn, ahead of that turn's input. For a
+     *  new run that is the first turn only if it is stored before the run claims
+     *  its first turn's messages; to guarantee it, pass `message` to `runs.start`.
+     *
+     *  The send carries an `Idempotency-Key`: `idempotencyKey` when given, otherwise a UUID generated for this
+     *  call and reused on every retry of it. The daemon keeps the key for 24 hours; a repeat with the same key
+     *  and the same message returns the first send's result without delivering again, and the same key with a
+     *  different message or `start_turn` throws `ConflictError` `idempotency_conflict`. To make a send safe
+     *  across your own restarts, derive the key from your own record of the send (a batch or row id). */
+    async message(runId, message, options = {}) {
+        const { idempotencyKey = crypto.randomUUID(), maxRetries = 2, start_turn, ...rest } = options;
+        const body = { message, ...(start_turn === undefined ? {} : { start_turn }) };
+        // One key per logical send, reused on every retry: the daemon answers a repeat with the first send's
+        // result, so a retry after a lost response cannot deliver the message twice.
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.request('POST', `${runPath(runId)}/messages`, body, { ...rest, maxRetries: 0, headers: { ...rest.headers, 'Idempotency-Key': idempotencyKey } });
+            }
+            catch (error) {
+                if (attempt >= maxRetries || !(error instanceof APIError) || !retryableSend(error))
+                    throw error;
+                await pause(error.retryAfterS ? error.retryAfterS * 1_000 : 500 * 2 ** attempt, rest.signal);
+            }
+        }
+    }
+    interrupt(runId, options = {}) {
+        const { children, ...rest } = options;
+        return this.request('POST', `${runPath(runId)}/interrupt`, children === undefined ? {} : { children }, rest);
+    }
+    cancel(runId, options = {}) {
+        const { keepSchedules, ...rest } = options;
+        return this.request('POST', `${runPath(runId)}/cancel`, keepSchedules === undefined ? {} : { keep_schedules: keepSchedules }, rest);
+    }
+    /** Delete the run, running or not: the runtime stops its turns and sandboxes itself, so there is no need to
+     *  `cancel` first. Deleting a run that is already gone throws `NotFoundError` (404).
+     *  `uploads_pending` counts the run's released uploads storage has not yet confirmed deleted; the runtime retries those. */
+    delete(runId, options) {
+        return this.request('DELETE', runPath(runId), undefined, options);
+    }
+    /** Rename the caller's own run. The name is trimmed, must not be empty, and is at most 200 characters. */
+    rename(runId, name, options) {
+        return this.request('POST', `${runPath(runId)}/rename`, { name }, options);
+    }
+    trace(runId, options = {}) {
+        const { format, ...rest } = options;
+        return this.request('GET', `${runPath(runId)}/trace${query({ format })}`, undefined, rest);
+    }
+    events(runId, options = {}) {
+        return new RunStream((after, signal) => this.openEvents(runId, after, signal), options.after, options.signal, options.onReconnect);
+    }
+    /** Follow the reply to one message: `sent` is what `runs.message` returned, or `runs.start`'s `message`. Reads the run's events after
+     *  `sent.sequence_number`, keeps the root's, starts at the turn that delivers the message and ends after that
+     *  turn's `turn.completed` (or the run's settlement). Several messages delivered in one turn share that turn's reply.
+     *  An expired cursor throws `stream_gap`. */
+    reply(runId, sent, options = {}) {
+        if (sent.run_id !== runId)
+            throw new TypeError('sent belongs to a different run');
+        return new RunReply((after) => this.events(runId, { after, signal: options.signal }), sent);
+    }
+    stream(params, options = {}) {
+        const controller = new AbortController();
+        options.signal?.addEventListener('abort', () => controller.abort(), { once: true });
+        const started = this.start(params, options);
+        return new RunStream(async (after, signal) => {
+            const run = await started;
+            return this.openEvents(run.run_id, after, signal);
+        }, 0, controller.signal);
+    }
+    /** Long-polls `runs.get` until the run is `settled`, `waiting_on_user`, or `idle`, and returns that response
+     *  unchanged (`result` is not parsed). Aborting `signal` rejects with its reason and leaves the run as it is. */
+    async wait(runId, options = {}) {
+        return abortable(options.signal, async () => {
+            for (;;) {
+                const result = await this.get(runId, { ...options, wait: 25 });
+                if (result.status === 'settled' || result.status === 'waiting_on_user' || result.status === 'idle')
+                    return result;
+            }
+        });
+    }
+    /** Start a run with `output_schema` and wait for it to settle; resolves with the outcome and `output_parsed`
+     *  typed to the schema. `onQuestion` answers each open question once; without it, a question rejects with
+     *  `APIError` code `waiting_on_user`. A run that stops without settling rejects `run_idle` (untouched:
+     *  send `runs.message` or `runs.cancel`). Aborting `signal` rejects with its reason; the run is never canceled. */
+    async parse(params, options = {}) {
+        const { onQuestion, idempotencyKey, ...rest } = options;
+        return abortable(rest.signal, () => this.parseRun(params, onQuestion, idempotencyKey, rest));
+    }
+    async parseRun(params, onQuestion, idempotencyKey, rest) {
+        const run = await this.start(params, { ...rest, ...(idempotencyKey === undefined ? {} : { idempotencyKey }) });
+        const answered = new Set();
+        for (;;) {
+            const current = await this.wait(run.run_id, rest);
+            if (current.status === 'settled' && current.outcome) {
+                const outcome = current.outcome;
+                if (outcome.kind === 'result')
+                    return { ...outcome, output_parsed: current.result };
+                return { ...outcome, output_parsed: null };
+            }
+            if (current.status === 'idle') {
+                throw new APIError(0, 'run_idle', 'the run stopped without settling; send runs.message or runs.cancel', undefined, undefined, { retryable: false, run_id: run.run_id });
+            }
+            const open = current.pending_question_ids.filter((id) => !answered.has(id));
+            if (!onQuestion) {
+                const questionId = open[0] ?? current.pending_question_ids[0];
+                throw new APIError(0, 'waiting_on_user', 'the run is waiting on a question and no onQuestion was given', undefined, undefined, { retryable: false, run_id: run.run_id, ...(questionId === undefined ? {} : { question_id: questionId }) });
+            }
+            if (!this.questions)
+                throw new TypeError('runs.parse needs the client questions resource to answer a question');
+            for (const id of open) {
+                const question = await this.questions.get(id, rest);
+                const responses = await onQuestion(question);
+                answered.add(id);
+                await this.questions.answer(id, responses, rest);
+            }
+            // Every listed question already answered: the run has not moved on yet, so poll again after a pause.
+            if (open.length === 0)
+                await pause(500, rest.signal);
+        }
+    }
+}
+/** A keyed send is safe to repeat after a refusal the daemon marked retryable or a transport failure. */
+function retryableSend(error) {
+    return error.retryable === true || error.code === 'transport_error' || error.code === 'daemon_request_interrupted' || error.code === 'connection_error' || error.code === 'request_timeout';
+}
+function runPath(id) {
+    if (!/^[A-Za-z0-9_-]+$/.test(id))
+        throw new TypeError('Invalid run id');
+    return `/v1/runs/${encodeURIComponent(id)}`;
+}
+function query(fields) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(fields))
+        if (value !== undefined)
+            params.set(key, String(value));
+    return params.size ? `?${params}` : '';
+}
+/** SDK-RUN-27: an aborted helper rejects with the signal's own reason, whatever the in-flight request raised. */
+async function abortable(signal, run) {
+    if (signal?.aborted)
+        throw signal.reason;
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw signal.reason;
+        throw error;
+    }
+}
+async function pause(ms, signal) {
+    if (signal?.aborted)
+        throw signal.reason;
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason); }, { once: true });
+    });
+}