@crouter/sdk 0.3.377

package/dist/resources/run-reply.js

@@ -0,0 +1,84 @@
+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;
+        const stream = this.open();
+        let inTurn = false;
+        try {
+            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;
+                }
+            }
+        }
+        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,40 @@
+import type { RunEvent, RunEventBaseDTO, RunEventOf, RunEventType } from '@crouter/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;
+};
+/** A resumable run event stream. Closing it does not stop the run. */
+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;
+    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;
+    /** 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,206 @@
+import { APIError, APIUserAbortError } from '../errors.js';
+/** A resumable run event stream. Closing it does not stop the run. */
+export class RunStream {
+    open;
+    onReconnect;
+    controller = new AbortController();
+    listeners = new Map();
+    cursor;
+    outcome;
+    resolveOutcome;
+    rejectOutcome;
+    finished = false;
+    events = [];
+    wake;
+    failure;
+    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);
+        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(); }
+    /** 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.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.finished) {
+                            await reader.cancel();
+                            return;
+                        }
+                    }
+                }
+                if (buffer) {
+                    if (ndjson)
+                        this.deliverPayload(JSON.parse(buffer));
+                    else
+                        this.record(buffer);
+                }
+                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);
+        }
+        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 new APIError(response.status, error?.code ?? 'invalid_response', error?.message ?? `HTTP ${response.status}`, error?.details, response.headers, error);
+}

package/dist/resources/runs.d.ts

@@ -0,0 +1,184 @@
+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 '@crouter/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`, 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`. */
+    message(runId: string, message: string, options?: RequestOptions & {
+        start_turn?: boolean;
+    }): 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;
+}