@crouter/sdk 0.3.377

package/dist/resources/models.d.ts

@@ -0,0 +1,8 @@
+import { ModelConfig } from './models/config.js';
+import { ModelCredentials } from './models/credentials.js';
+import type { Request } from './request.js';
+export declare class Models {
+    readonly credentials: ModelCredentials;
+    readonly config: ModelConfig;
+    constructor(request: Request);
+}

package/dist/resources/models.js

@@ -0,0 +1,10 @@
+import { ModelConfig } from './models/config.js';
+import { ModelCredentials } from './models/credentials.js';
+export class Models {
+    credentials;
+    config;
+    constructor(request) {
+        this.credentials = new ModelCredentials(request);
+        this.config = new ModelConfig(request);
+    }
+}

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

@@ -0,0 +1,34 @@
+import { type NodeDetailDTO, type NodeEventDTO, type NodeOutcomeDTO } from '@crouter/api';
+/** One event from a node's stream. */
+export type NodeStreamEvent = NodeEventDTO;
+/** The `type` discriminant of a stream event, and the name `on` and `off` take. */
+export type NodeStreamEventType = NodeStreamEvent['type'];
+/** A listener for one event type, receiving only that type's event. */
+export type NodeStreamEventListener<T extends NodeStreamEventType> = (event: Extract<NodeStreamEvent, {
+    type: T;
+}>) => void;
+/** A parsed node event stream. Aborting it disconnects this observer, not the node. */
+export declare class NodeStream implements AsyncIterable<NodeStreamEvent> {
+    /** The node this stream follows; resolves once the daemon has created it. */
+    readonly node: Promise<NodeDetailDTO>;
+    private readonly controller;
+    private readonly listeners;
+    private readonly settled;
+    private resolveOutcome;
+    private rejectOutcome;
+    private finished;
+    constructor(node: Promise<NodeDetailDTO>, open: (signal: AbortSignal) => Promise<Response>, signal?: AbortSignal);
+    /** Adds a listener for one event type. */
+    on<T extends NodeStreamEventType>(type: T, listener: NodeStreamEventListener<T>): this;
+    /** Removes a listener added with `on`. */
+    off<T extends NodeStreamEventType>(type: T, listener: NodeStreamEventListener<T>): this;
+    /** Disconnects this observer. The node keeps running. */
+    abort(): void;
+    /** The node's settled outcome. Rejects with `APIError` on a terminal stream error. */
+    finalOutcome(): Promise<NodeOutcomeDTO>;
+    [Symbol.asyncIterator](): AsyncIterator<NodeStreamEvent>;
+    private consume;
+    private handleRecord;
+    private emit;
+    private fail;
+}

package/dist/resources/node-stream.js

@@ -0,0 +1,176 @@
+import { isErrorBody } from '@crouter/api';
+import { ResourceIdentifierError } from './identifiers.js';
+import { APIConnectionError, APIError, APIUserAbortError, mapError } from '../errors.js';
+/** A parsed node event stream. Aborting it disconnects this observer, not the node. */
+export class NodeStream {
+    /** The node this stream follows; resolves once the daemon has created it. */
+    node;
+    controller = new AbortController();
+    listeners = new Map();
+    settled;
+    resolveOutcome;
+    rejectOutcome;
+    finished = false;
+    constructor(node, open, signal) {
+        this.node = node;
+        this.settled = new Promise((resolve, reject) => {
+            this.resolveOutcome = resolve;
+            this.rejectOutcome = reject;
+        });
+        void this.settled.catch(() => undefined);
+        if (signal !== undefined) {
+            if (signal.aborted)
+                this.controller.abort(signal.reason);
+            else
+                signal.addEventListener('abort', () => this.controller.abort(signal.reason), { once: true });
+        }
+        void this.consume(open);
+    }
+    /** Adds a listener for one event type. */
+    on(type, listener) {
+        const listeners = this.listeners.get(type) ?? new Set();
+        listeners.add(listener);
+        this.listeners.set(type, listeners);
+        return this;
+    }
+    /** Removes a listener added with `on`. */
+    off(type, listener) {
+        this.listeners.get(type)?.delete(listener);
+        return this;
+    }
+    /** Disconnects this observer. The node keeps running. */
+    abort() {
+        this.controller.abort();
+    }
+    /** The node's settled outcome. Rejects with `APIError` on a terminal stream error. */
+    finalOutcome() {
+        return this.settled;
+    }
+    async *[Symbol.asyncIterator]() {
+        const events = [];
+        let wake;
+        const listener = (event) => {
+            events.push(event);
+            wake?.();
+            wake = undefined;
+        };
+        void this.settled.then(() => { wake?.(); wake = undefined; }, () => { wake?.(); wake = undefined; });
+        for (const type of eventTypes)
+            this.on(type, listener);
+        try {
+            for (;;) {
+                const event = events.shift();
+                if (event !== undefined) {
+                    yield event;
+                    continue;
+                }
+                if (this.finished) {
+                    await this.settled;
+                    return;
+                }
+                await new Promise((resolve) => { wake = resolve; });
+            }
+        }
+        finally {
+            for (const type of eventTypes)
+                this.off(type, listener);
+        }
+    }
+    async consume(open) {
+        try {
+            const response = await open(this.controller.signal);
+            if (!response.ok)
+                throw await responseError(response);
+            if (response.body === null)
+                throw new APIConnectionError(0, 'stream_ended', 'node event stream had no response body');
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            for (;;) {
+                const { done, value } = await reader.read();
+                buffer += decoder.decode(value, { stream: !done });
+                const records = buffer.split(/\r\n\r\n|\n\n|\r\r/);
+                buffer = records.pop() ?? '';
+                for (const record of records)
+                    this.handleRecord(record);
+                if (done) {
+                    if (buffer !== '')
+                        this.handleRecord(buffer);
+                    break;
+                }
+            }
+            if (!this.finished)
+                this.fail(new APIConnectionError(0, 'stream_ended', 'node event stream ended before node.settled'));
+        }
+        catch (error) {
+            this.fail(this.controller.signal.aborted
+                ? new APIUserAbortError(0, 'request_aborted', 'request aborted by caller signal')
+                : error instanceof ResourceIdentifierError
+                    ? error
+                    : error instanceof APIError ? mapError(error) : error);
+        }
+    }
+    handleRecord(record) {
+        let type;
+        const data = [];
+        for (const line of record.split(/\r\n|\r|\n/)) {
+            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 === undefined || data.length === 0)
+            return;
+        const parsed = JSON.parse(data.join('\n'));
+        const event = { ...parsed, type };
+        this.emit(event);
+        if (event.type === 'node.settled') {
+            this.finished = true;
+            this.resolveOutcome(event.outcome);
+        }
+        else if (event.type === 'error' && event.error.code !== 'stream_gap') {
+            this.fail(new APIError(0, event.error.code, event.error.message, event.error.details));
+        }
+    }
+    emit(event) {
+        for (const listener of this.listeners.get(event.type) ?? [])
+            listener(event);
+    }
+    fail(error) {
+        if (this.finished)
+            return;
+        this.finished = true;
+        this.rejectOutcome(error);
+    }
+}
+async function responseError(response) {
+    const text = (await response.text()).trim();
+    let body;
+    try {
+        body = text === '' ? undefined : JSON.parse(text);
+    }
+    catch {
+        return new APIError(response.status, 'invalid_response', text.slice(0, 500), undefined, response.headers);
+    }
+    if (isErrorBody(body)) {
+        return new APIError(response.status, body.error.code, body.error.message, body.error.details, response.headers);
+    }
+    return new APIError(response.status, 'internal', `request failed with status ${response.status}`, undefined, response.headers);
+}
+const eventTypes = [
+    'node.output_text.delta',
+    'node.output_text.done',
+    'node.tool_call.started',
+    'node.tool_call.completed',
+    'node.turn.started',
+    'node.turn.completed',
+    'node.report.pushed',
+    'node.status.changed',
+    'node.settled',
+    'error',
+];

package/dist/resources/nodes/jobs.d.ts

@@ -0,0 +1,9 @@
+import { type BashJobStatusDTO, type BashJobStopResultDTO } from '@crouter/api';
+import type { RequestOptions } from '../../types.js';
+import type { Request } from '../request.js';
+export declare class NodeJobs {
+    private readonly request;
+    constructor(request: Request);
+    list(id: string, options?: RequestOptions): Promise<BashJobStatusDTO[]>;
+    cancel(id: string, jobId: string, options?: RequestOptions): Promise<BashJobStopResultDTO>;
+}

package/dist/resources/nodes/jobs.js

@@ -0,0 +1,14 @@
+import { routes } from '@crouter/api';
+import { jobId as validatedJobId, nodeId } from '../identifiers.js';
+export class NodeJobs {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    async list(id, options) {
+        return this.request('GET', routes.nodeJobs(nodeId(id)), undefined, options);
+    }
+    async cancel(id, jobId, options) {
+        return this.request('DELETE', routes.nodeJob(nodeId(id), validatedJobId(jobId)), undefined, options);
+    }
+}

package/dist/resources/nodes/result.d.ts

@@ -0,0 +1,8 @@
+import { type SubmitResultDTO, type SubmitResultRequest } from '@crouter/api';
+import type { RequestOptions } from '../../types.js';
+import type { Request } from '../request.js';
+export declare class NodeResult {
+    private readonly request;
+    constructor(request: Request);
+    submit(id: string, body: SubmitResultRequest, options?: RequestOptions): Promise<SubmitResultDTO>;
+}

package/dist/resources/nodes/result.js

@@ -0,0 +1,11 @@
+import { routes } from '@crouter/api';
+import { nodeId } from '../identifiers.js';
+export class NodeResult {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    async submit(id, body, options) {
+        return this.request('POST', routes.nodeResult(nodeId(id)), body, options);
+    }
+}

package/dist/resources/nodes/worktree.d.ts

@@ -0,0 +1,9 @@
+import { type AbandonWorktreeRequest, type AbandonWorktreeResultDTO, type CloseWorktreeResultDTO } from '@crouter/api';
+import type { RequestOptions } from '../../types.js';
+import type { Request } from '../request.js';
+export declare class NodeWorktree {
+    private readonly request;
+    constructor(request: Request);
+    close(id: string, options?: RequestOptions): Promise<CloseWorktreeResultDTO>;
+    abandon(id: string, body: AbandonWorktreeRequest, options?: RequestOptions): Promise<AbandonWorktreeResultDTO>;
+}

package/dist/resources/nodes/worktree.js

@@ -0,0 +1,14 @@
+import { routes, } from '@crouter/api';
+import { nodeId } from '../identifiers.js';
+export class NodeWorktree {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    async close(id, options) {
+        return this.request('POST', routes.nodeWorktreeClose(nodeId(id)), {}, options);
+    }
+    async abandon(id, body, options) {
+        return this.request('POST', routes.nodeWorktreeAbandon(nodeId(id)), body, options);
+    }
+}

package/dist/resources/nodes.d.ts

@@ -0,0 +1,23 @@
+import { type NodeConfigPatch, type NodeDetailDTO, type RelaunchRootResultDTO, type ReviveAllResultDTO, type ReviveRequest, type ReviveResultDTO, type PromoteRequest, type WaitRequest, type YieldRequest } from '@crouter/api';
+import type { RequestOptions } from '../types.js';
+import { NodeJobs } from './nodes/jobs.js';
+import { NodeResult } from './nodes/result.js';
+import { NodeWorktree } from './nodes/worktree.js';
+import type { Request } from './request.js';
+export declare class NodesResource {
+    private readonly request;
+    readonly jobs: NodeJobs;
+    readonly worktree: NodeWorktree;
+    readonly result: NodeResult;
+    constructor(request: Request);
+    update(id: string, patch: NodeConfigPatch, options?: RequestOptions): Promise<NodeDetailDTO>;
+    fork(id: string, options?: RequestOptions): Promise<NodeDetailDTO>;
+    revive(id: string, body?: ReviveRequest, options?: RequestOptions): Promise<ReviveResultDTO>;
+    reviveAll(options?: RequestOptions): Promise<ReviveAllResultDTO>;
+    promote(id: string, body?: PromoteRequest, options?: RequestOptions): Promise<NodeDetailDTO>;
+    demote(id: string, options?: RequestOptions): Promise<NodeDetailDTO>;
+    recycle(id: string, options?: RequestOptions): Promise<NodeDetailDTO>;
+    yield(id: string, body?: YieldRequest, options?: RequestOptions): Promise<NodeDetailDTO>;
+    wait(id: string, body: WaitRequest, options?: RequestOptions): Promise<NodeDetailDTO>;
+    relaunchRoot(id: string, options?: RequestOptions): Promise<RelaunchRootResultDTO>;
+}

package/dist/resources/nodes.js

@@ -0,0 +1,47 @@
+import { routes, } from '@crouter/api';
+import { nodeId } from './identifiers.js';
+import { NodeJobs } from './nodes/jobs.js';
+import { NodeResult } from './nodes/result.js';
+import { NodeWorktree } from './nodes/worktree.js';
+export class NodesResource {
+    request;
+    jobs;
+    worktree;
+    result;
+    constructor(request) {
+        this.request = request;
+        this.jobs = new NodeJobs(request);
+        this.worktree = new NodeWorktree(request);
+        this.result = new NodeResult(request);
+    }
+    async update(id, patch, options) {
+        return this.request('PATCH', routes.nodeConfig(nodeId(id)), patch, options);
+    }
+    async fork(id, options) {
+        return this.request('POST', routes.nodeFork(nodeId(id)), {}, options);
+    }
+    async revive(id, body, options) {
+        return this.request('POST', routes.nodeRevive(nodeId(id)), body ?? {}, options);
+    }
+    reviveAll(options) {
+        return this.request('POST', routes.reviveAll(), {}, options);
+    }
+    async promote(id, body, options) {
+        return this.request('POST', routes.nodePromote(nodeId(id)), body ?? {}, options);
+    }
+    async demote(id, options) {
+        return this.request('POST', routes.nodeDemote(nodeId(id)), {}, options);
+    }
+    async recycle(id, options) {
+        return this.request('POST', routes.nodeRecycle(nodeId(id)), {}, options);
+    }
+    async yield(id, body, options) {
+        return this.request('POST', routes.nodeYield(nodeId(id)), body ?? {}, options);
+    }
+    async wait(id, body, options) {
+        return this.request('POST', routes.nodeWait(nodeId(id)), body, options);
+    }
+    async relaunchRoot(id, options) {
+        return this.request('POST', routes.nodeRelaunchRoot(nodeId(id)), {}, options);
+    }
+}

package/dist/resources/providers.d.ts

@@ -0,0 +1,51 @@
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+/** Help-only provider manifest: granted leaves, never transport or credentials. */
+export type ProviderToolEntry = {
+    provider: string;
+    display_name: string;
+    status: 'available';
+    major: number;
+    groups: Array<{
+        group: string;
+        leaves: Array<{
+            tool: string;
+            description: string;
+            summary: string;
+            params: unknown[];
+            output: unknown[];
+        }>;
+    }>;
+    commands: Array<{
+        kind: 'branch';
+        name: string;
+        description: string;
+        whenToUse: string;
+        summary: string;
+        children: unknown[];
+    }>;
+} | {
+    provider: string;
+    display_name: string;
+    status: 'installing' | 'install_failed';
+    error?: string;
+    groups: [];
+    commands: [];
+};
+export declare class Providers {
+    private readonly request;
+    constructor(request: Request);
+    /** Omit provider to list every reachable provider; name one to inspect it. */
+    tools(provider: string, options?: RequestOptions): Promise<ProviderToolEntry>;
+    tools(provider?: undefined, options?: RequestOptions): Promise<{
+        providers: ProviderToolEntry[];
+    }>;
+    /** The daemon checks scope, mints an outbound token and calls the provider. */
+    call(input: {
+        provider: string;
+        tool: string;
+        arguments: Record<string, unknown>;
+        version?: number;
+        approval?: string;
+    }, options?: RequestOptions): Promise<unknown>;
+}

package/dist/resources/providers.js

@@ -0,0 +1,15 @@
+import { pathSegment } from './identifiers.js';
+export class Providers {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    tools(provider, options) {
+        const path = provider === undefined ? '/v1/providers/tools' : `/v1/providers/${pathSegment(provider, 'provider')}/tools`;
+        return this.request('GET', path, undefined, options);
+    }
+    /** The daemon checks scope, mints an outbound token and calls the provider. */
+    call(input, options) {
+        return this.request('POST', '/v1/provider/call', input, options);
+    }
+}

package/dist/resources/questions.d.ts

@@ -0,0 +1,49 @@
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+/** One input or display element of a question. `id` is absent on a slot that takes no response. */
+export interface QuestionSlot {
+    id?: string;
+    kind: string;
+    /** Zero-based step the slot appears on. */
+    step: number;
+    config: Record<string, unknown>;
+}
+/** The fields a `waiting_on_user` run event and `questions.get` share. */
+export interface QuestionFields {
+    question_id: string;
+    /** The app whose run asked. */
+    initiating_app: string;
+    title: string;
+    subtitle?: string;
+    /** Number of steps. */
+    steps: number;
+    slots: QuestionSlot[];
+}
+export type QuestionStatus = 'open' | 'answered' | 'canceled';
+/** Responses keyed by slot id. */
+export type QuestionResponses = Record<string, unknown>;
+/** A question an agent in a run asked the user. */
+export interface Question extends QuestionFields {
+    run_id: string;
+    /** The asking node. */
+    node_id: string;
+    status: QuestionStatus;
+    /** Present once answered. */
+    answer?: QuestionResponses;
+}
+export interface QuestionAnswered {
+    question_id: string;
+    status: 'answered';
+    answer: QuestionResponses;
+}
+/** Questions from agents in runs (app listener only). */
+export declare class Questions {
+    private readonly request;
+    constructor(request: Request);
+    /** Read a question of a run the caller can read; anything else is `not_found`. */
+    get(questionId: string, options?: RequestOptions): Promise<Question>;
+    /** Answer an open question of the caller's own run. An answer that does not match a slot is
+     *  `invalid_request` with `param` naming the slot, and records nothing. A question already answered or
+     *  canceled — including the loser of a race — is 409 `run_settled` with `details.state` and `details.result`. */
+    answer(questionId: string, responses: QuestionResponses, options?: RequestOptions): Promise<QuestionAnswered>;
+}

package/dist/resources/questions.js

@@ -0,0 +1,21 @@
+import { pathSegment } from './identifiers.js';
+/** Questions from agents in runs (app listener only). */
+export class Questions {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    /** Read a question of a run the caller can read; anything else is `not_found`. */
+    get(questionId, options) {
+        return this.request('GET', questionPath(questionId), undefined, options);
+    }
+    /** Answer an open question of the caller's own run. An answer that does not match a slot is
+     *  `invalid_request` with `param` naming the slot, and records nothing. A question already answered or
+     *  canceled — including the loser of a race — is 409 `run_settled` with `details.state` and `details.result`. */
+    answer(questionId, responses, options = {}) {
+        return this.request('POST', `${questionPath(questionId)}/answer`, { responses }, { ...options, maxRetries: 0 });
+    }
+}
+function questionPath(id) {
+    return `/v1/questions/${encodeURIComponent(pathSegment(id, 'question id'))}`;
+}

package/dist/resources/request.d.ts

@@ -0,0 +1,3 @@
+import type { RequestOptions } from '../types.js';
+export type Request = <T>(method: string, path: string, body?: unknown, options?: RequestOptions) => Promise<T>;
+export declare function withQuery(path: string, query: object | undefined): string;

package/dist/resources/request.js

@@ -0,0 +1,11 @@
+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}`;
+}

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

@@ -0,0 +1,79 @@
+import type { AssistantStopReasonDTO, RunOutcomeDTO, RunStatusDTO, TurnErrorDTO } from '@crouter/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: () => 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>;
+}