@north-light/sdk 0.0.0-stage → 0.3.414

package/dist/client.js

@@ -0,0 +1,543 @@
+import { APIError, CrtrClient, MINIMUM_RUNTIME_VERSION_HEADER, RUNTIME_VERSION_HEADER, compareReleaseVersions, routes, } from '@north-light/api';
+import { APIConnectionError, APIUserAbortError, AuthenticationError, CrouterError, mapError } from './errors.js';
+import { Bash } from './resources/bash.js';
+import { Canvas } from './resources/canvas.js';
+import { Crons } from './resources/crons.js';
+import { CustomObjects } from './resources/custom-objects.js';
+import { Attachments } from './resources/attachments.js';
+import { Files } from './resources/files.js';
+import { Human } from './resources/human.js';
+import { Models } from './resources/models.js';
+import { NodesResource } from './resources/nodes.js';
+import { nodeId, pathSegment } from './resources/identifiers.js';
+import { NodeStream } from './resources/node-stream.js';
+import { Questions } from './resources/questions.js';
+import { Providers } from './resources/providers.js';
+import { Runs } from './resources/runs.js';
+import { Shares } from './resources/shares.js';
+import { StructuredRequests } from './resources/structured-requests.js';
+import { Memory } from './resources/memory.js';
+import { Uploads } from './resources/uploads.js';
+import { heldReadOptions } from './resources/request.js';
+import { resolveJsonSchema } from './schema.js';
+import { SDK_VERSION } from './version.js';
+const LOCAL_SOCKET_FETCH = Symbol.for('@north-light/api/local-socket-fetch');
+const DEFAULT_TIMEOUT_MS = 30_000;
+const POLL_WAIT_SECONDS = 25;
+/**
+ * The client, and the only class an application constructs. Each namespace below wraps a
+ * family of daemon routes; `request` is the escape hatch for a route with no wrapper.
+ */
+export class Crouter {
+    /** Create, inspect, message, stream, and wait on nodes. */
+    nodes;
+    /** Run one command in an absolute working directory. */
+    bash;
+    /** Canvas-wide views: attention, snapshot, roster, dashboard, prune, and history. */
+    canvas;
+    /** Scheduled commands. */
+    crons;
+    /** Durable structured requests with deadlines and one settlement. */
+    structuredRequests;
+    /** Register, publish, receive, and acknowledge custom canvas objects. */
+    customObjects;
+    /** Human requests and the human inbox. */
+    human;
+    /** Model credentials and model configuration. */
+    models;
+    /** Agent profiles. */
+    profiles;
+    /** Daemon status and health. */
+    system;
+    /** Whether this client can reach a daemon that can run a model. */
+    auth;
+    /** Read, write, and list absolute host paths. */
+    files;
+    runs;
+    /** Uploads to runtime storage, for files a run prompt or message names (app listener only). */
+    uploads;
+    /** Signed links to files a run received as attachments (app listener only). */
+    attachments;
+    /** Public share links to files (app listener only). */
+    shares;
+    /** Questions agents in runs ask the user (app listener only). */
+    questions;
+    /** Read the documents the person owns (`store: 'user'`): an app sees their `public` documents, and every privacy level with a `crtr:memory:manage:user` grant. */
+    memory;
+    /** Scope-filtered provider tools and daemon-mediated calls. */
+    providers;
+    /** The caller's grant. With `wait` (1–25 s) and `since` (a `version` from an earlier answer), the runtime holds the
+     *  read until the grant's `version` differs from `since` or `wait` seconds pass; the request timeout is extended by
+     *  `wait`. To follow many people's grants, use `oauth.watchGrants`. */
+    grant;
+    health;
+    eventFetch;
+    bearerToken;
+    connectionToken;
+    tokenSource;
+    onUnauthorized;
+    client;
+    timeout;
+    baseURL;
+    socketPath;
+    constructor(options = {}) {
+        const env = nodeEnvironment();
+        const baseURL = options.baseURL ?? env['CRTR_BASE_URL'];
+        this.baseURL = baseURL;
+        this.socketPath = undefined;
+        if (options.baseURL !== undefined && options.socketPath !== undefined) {
+            throw new TypeError('Crouter accepts either baseURL or socketPath, not both');
+        }
+        if (baseURL !== undefined && options.autostart === true) {
+            throw new CrouterError('autostart is only valid for the local socket transport');
+        }
+        if (options.token !== undefined && options.tokenSource !== undefined)
+            throw new CrouterError('token and tokenSource are mutually exclusive');
+        if (options.tokenSource && baseURL === undefined)
+            throw new CrouterError('tokenSource requires baseURL');
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        const token = options.tokenSource ? undefined : options.token ?? env['CRTRD_TOKEN'];
+        this.bearerToken = token;
+        this.tokenSource = options.tokenSource;
+        this.onUnauthorized = options.onUnauthorized;
+        const headers = {
+            ...options.defaultHeaders,
+            ...options.headers,
+            ...(token === undefined ? {} : { Authorization: `Bearer ${token}` }),
+        };
+        const baseFetch = requireCurrentRuntime(options.fetch ?? (baseURL === undefined && isNodeRuntime() ? localSocketFetch(options.socketPath ?? env['CRTR_SOCKET']) : undefined));
+        this.eventFetch = options.tokenSource ? (input, init) => {
+            const url = new URL(input instanceof Request ? input.url : String(input));
+            if (url.pathname === '/v1/health')
+                return baseFetch(input, init);
+            return baseFetch(input, {
+                ...init, headers: { ...Object.fromEntries(new Headers(init?.headers)), Authorization: `Bearer ${this.connectionToken}` },
+            });
+        } : baseFetch;
+        if (baseURL !== undefined) {
+            this.client = new CrtrClient({
+                baseUrl: baseURL,
+                fetch: this.eventFetch,
+                headers,
+                timeoutMs: this.timeout,
+                maxRetries: options.maxRetries,
+            });
+        }
+        else {
+            if (!isNodeRuntime()) {
+                if (options.socketPath !== undefined)
+                    throw new CrouterError('socketPath is only available in Node');
+                this.socketPath = undefined;
+                this.client = new CrtrClient({
+                    baseUrl: 'http://localhost',
+                    fetch: baseFetch,
+                    headers,
+                    timeoutMs: this.timeout,
+                    maxRetries: options.maxRetries,
+                });
+            }
+            else {
+                const socketPath = options.socketPath ?? env['CRTR_SOCKET'];
+                this.socketPath = socketPath;
+                const autostart = options.autostart ?? true;
+                this.client = new CrtrClient({
+                    baseUrl: 'http://localhost',
+                    fetch: baseFetch,
+                    headers,
+                    timeoutMs: this.timeout,
+                    maxRetries: options.maxRetries,
+                    autostart,
+                    onColdSocket: autostart ? startDaemon : undefined,
+                });
+            }
+        }
+        const request = (method, path, body, options) => this.request(method, path, body, options);
+        const nodes = new NodesResource(request);
+        const phaseOneNodes = {
+            create: (params, options) => this.call(() => this.client.request('POST', routes.nodes(), serializeCreate(params), options)),
+            retrieve: async (id, options) => {
+                const validId = nodeId(id);
+                return this.call(() => this.client.request('GET', routes.node(validId), undefined, options));
+            },
+            list: (query, options) => this.call(() => this.client.request('GET', withQuery(routes.nodes(), query), undefined, options)),
+            outcome: (id, options) => this.outcome(id, options),
+            waitForOutcome: (id, options) => this.waitForOutcome(id, options),
+            createAndWait: (params, options) => this.createAndWait(params, options),
+            parse: (params, options) => this.parse(params, options),
+            message: async (id, body, options) => {
+                const validId = nodeId(id);
+                return this.call(() => this.client.request('POST', routes.nodeMessages(validId), messageBody(body), options));
+            },
+            cancel: async (id, body, options) => {
+                const validId = nodeId(id);
+                return this.call(() => this.client.request('POST', routes.nodeClose(validId), body ?? {}, options));
+            },
+            interrupt: async (id, options) => {
+                const validId = nodeId(id);
+                return this.call(() => this.client.request('POST', routes.nodeInterrupt(validId), {}, options));
+            },
+            stream: (params, options) => this.stream(params, options),
+            events: (id, options) => this.events(id, options),
+            reports: {
+                list: async (id, query, options) => {
+                    const validId = nodeId(id);
+                    return this.call(() => this.client.request('GET', withQuery(routes.nodeReports(validId), query), undefined, options));
+                },
+            },
+        };
+        this.nodes = Object.assign(nodes, phaseOneNodes);
+        this.bash = new Bash(request, this.timeout);
+        this.canvas = new Canvas(request);
+        this.crons = new Crons(request);
+        this.structuredRequests = new StructuredRequests(request);
+        this.customObjects = new CustomObjects(request, (path, options) => this.openCustomDeliveries(path, options));
+        this.human = new Human(request);
+        this.models = new Models(request);
+        this.profiles = {
+            ensure: async (name, params, options) => {
+                const validName = pathSegment(name, 'profile name');
+                return this.call(() => this.client.request('PUT', routes.profile(validName), params ?? {}, options));
+            },
+            retrieve: async (name, options) => {
+                const validName = pathSegment(name, 'profile name');
+                return this.call(() => this.client.request('GET', routes.profile(validName), undefined, options));
+            },
+            list: (options) => this.call(() => this.client.request('GET', routes.profiles(), undefined, options)),
+        };
+        this.system = {
+            status: (options) => this.call(() => this.client.request('GET', routes.status(), undefined, options)),
+            health: (options) => this.call(() => this.client.request('GET', routes.healthz(), undefined, options)),
+        };
+        this.auth = {
+            status: (params, options) => this.authStatus(params, options),
+        };
+        this.files = new Files(request, (path, options) => this.openDownload(path, options));
+        this.uploads = new Uploads(request);
+        this.attachments = new Attachments(request);
+        this.shares = new Shares(request);
+        this.questions = new Questions(request);
+        this.memory = new Memory(request);
+        this.runs = new Runs(request, (id, after, signal) => this.openRunEvents(id, after, signal), this.questions);
+        this.providers = new Providers(request);
+        this.grant = { get: (options = {}) => {
+                const { wait, since, ...rest } = options;
+                const held = heldReadOptions(wait, rest);
+                return this.request('GET', withQuery('/v1/grant', { wait, since }), undefined, held);
+            } };
+        this.health = { get: (options) => this.request('GET', '/v1/health', undefined, options) };
+    }
+    /** Establish NDJSON through the JSON client's cold-socket/retry transport; leave the live body unread. */
+    async openCustomDeliveries(path, options) {
+        const response = await this.call(() => this.client.rawResponse('GET', path, {
+            headers: { accept: 'application/x-ndjson', ...options.headers }, signal: options.signal,
+            timeout: 0, maxRetries: options.maxRetries,
+        }));
+        if (!response.ok)
+            throw mapError(await responseError(response));
+        return response;
+    }
+    openRunEvents(id, after, signal) {
+        const baseURL = this.baseURL;
+        if (!baseURL)
+            throw new CrouterError('Run events require an app listener baseURL');
+        return this.call(() => this.eventFetch(`${baseURL.replace(/\/$/, '')}/v1/runs/${encodeURIComponent(id)}/events?after=${after}`, {
+            headers: { 'accept': 'text/event-stream', ...(this.bearerToken ? { Authorization: `Bearer ${this.bearerToken}` } : {}),
+                ...(after ? { 'Last-Event-ID': String(after) } : {}) }, signal,
+        }));
+    }
+    /** `GET /v1/files/download` as a raw fetch: bytes are not JSON, so it bypasses the JSON client but
+     *  still goes through `call()`, which supplies the connection token and refreshes it once on a 401. */
+    async openDownload(path, options) {
+        const baseURL = this.baseURL;
+        if (!baseURL)
+            throw new CrouterError('File downloads require an app listener baseURL');
+        if (typeof path !== 'string' || path === '')
+            throw new TypeError('path is required');
+        const url = `${baseURL.replace(/\/$/, '')}/v1/files/download?${new URLSearchParams({ path })}`;
+        const response = await this.call(async () => {
+            try {
+                return await this.eventFetch(url, {
+                    headers: { ...(this.bearerToken ? { Authorization: `Bearer ${this.bearerToken}` } : {}), ...(options.range ? { Range: options.range } : {}) },
+                    ...(options.signal ? { signal: options.signal } : {}),
+                });
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw new APIUserAbortError(0, 'request_aborted', 'download aborted by caller');
+                throw new APIConnectionError(0, 'connection_error', error instanceof Error ? error.message : String(error));
+            }
+        });
+        if (response.ok)
+            return response;
+        throw mapError(await responseError(response));
+    }
+    /** Sends one request to any daemon route, for routes the namespaces above do not wrap. */
+    request(method, path, body, options) {
+        return this.call(() => this.client.request(method, path, body, options), path !== '/v1/health');
+    }
+    async authStatus(params = {}, options) {
+        if (this.baseURL === undefined && (!isNodeRuntime() || !await socketIsReachable(this.socketPath))) {
+            return connectStatus('Install crtr, run `crtr sys connect`, and paste the base URL and token it prints.');
+        }
+        let daemon;
+        try {
+            daemon = await this.call(() => this.client.request('GET', routes.status(), undefined, options));
+        }
+        catch (error) {
+            if (!(error instanceof APIError))
+                throw error;
+            const mapped = mapError(error);
+            if (mapped instanceof AuthenticationError) {
+                return connectStatus('The daemon rejected the saved token. Run `crtr sys connect` and paste the new base URL and token it prints.');
+            }
+            if (mapped instanceof APIConnectionError) {
+                const instruction = this.baseURL === undefined
+                    ? 'Run `crtr sys connect` and paste the base URL and token it prints.'
+                    : `The daemon at ${this.baseURL} could not be reached. Run \`crtr sys connect\` and paste the new base URL and token it prints.`;
+                return connectStatus(instruction);
+            }
+            throw mapped;
+        }
+        const daemonStatus = {
+            base_url: this.baseURL ?? daemon.listeners.socket_path,
+            runtime_version: daemon.runtime_version,
+            api_version: daemon.api_version,
+            startup_phase: daemon.startup_phase,
+            tcp: daemon.listeners.tcp,
+        };
+        if (daemon.startup_phase !== 'ready') {
+            return { connected: true, daemon: daemonStatus, model: null, next_step: null, instructions: null };
+        }
+        const model = await this.call(() => this.client.request('GET', withQuery(routes.modelAuthReadiness(), params), undefined, options));
+        if (model.credential !== 'ready') {
+            return {
+                connected: true,
+                daemon: daemonStatus,
+                model,
+                next_step: 'login',
+                instructions: `Run \`${connectCommand(params)}\` to log in to ${model.provider}.`,
+            };
+        }
+        return { connected: true, daemon: daemonStatus, model, next_step: null, instructions: null };
+    }
+    stream(params, options) {
+        const node = this.nodes.create(params, options);
+        const { timeout: _timeout, ...streamOptions } = options ?? {};
+        return new NodeStream(node, async (signal) => {
+            const created = await node;
+            return this.call(() => this.client.getNodeEvents(created.node_id, {}, { ...streamOptions, signal }));
+        }, options?.signal);
+    }
+    events(id, options = {}) {
+        const { after, ...streamOptions } = options;
+        const node = this.nodes.retrieve(id, streamOptions);
+        return new NodeStream(node, async (signal) => {
+            const existing = await node;
+            return this.call(() => this.client.getNodeEvents(existing.node_id, { after }, { ...streamOptions, signal }));
+        }, options.signal);
+    }
+    async outcome(id, options = {}) {
+        const validId = nodeId(id);
+        const { wait, ...requestOptions } = options;
+        if (wait !== undefined && (!Number.isInteger(wait) || wait < 0 || wait > POLL_WAIT_SECONDS)) {
+            throw new RangeError('wait must be an integer between 0 and 25');
+        }
+        const timeout = wait === undefined ? requestOptions.timeout : wait * 1_000 + (requestOptions.timeout ?? this.timeout);
+        return this.call(() => this.client.request('GET', withQuery(routes.nodeOutcome(validId), { wait }), undefined, { ...requestOptions, timeout }));
+    }
+    async waitForOutcome(id, options) {
+        for (;;) {
+            const response = await this.outcome(id, { ...options, wait: POLL_WAIT_SECONDS });
+            if (response.state === 'settled' && response.outcome !== null)
+                return response.outcome;
+        }
+    }
+    async createAndWait(params, options) {
+        const node = await this.nodes.create(params, options);
+        return this.waitForOutcome(node.node_id, options);
+    }
+    async parse(params, options) {
+        const outcome = await this.createAndWait({
+            ...params,
+            ...(params.parent == null && params.root_lifecycle === undefined ? { root_lifecycle: 'terminal' } : {}),
+        }, options);
+        if (outcome.kind === 'result') {
+            return { ...outcome, output_parsed: outcome.structured_result };
+        }
+        return { ...outcome, output_parsed: null };
+    }
+    async call(operation, authenticate = true) {
+        for (let attempt = 0;; attempt++) {
+            // A token refresh refused by the directory surfaces with its status class, like any other API error.
+            if (authenticate && this.tokenSource)
+                this.connectionToken = await this.tokenSource().catch(throwMapped);
+            let result;
+            try {
+                result = await operation();
+            }
+            catch (error) {
+                if (authenticate && attempt === 0 && error instanceof APIError && error.status === 401 && this.onUnauthorized) {
+                    await this.onUnauthorized().catch(throwMapped);
+                    continue;
+                }
+                throw mapError(error);
+            }
+            if (authenticate && attempt === 0 && result instanceof Response && result.status === 401 && this.onUnauthorized) {
+                await result.body?.cancel();
+                await this.onUnauthorized().catch(throwMapped);
+                continue;
+            }
+            return result;
+        }
+    }
+}
+/** Rethrow an `APIError` as its status class; any other error from caller-supplied token hooks passes through unchanged. */
+function throwMapped(error) {
+    throw error instanceof APIError ? mapError(error) : error;
+}
+/** A non-2xx answer's JSON envelope as an `APIError`; a body that is not the envelope keeps the status. */
+async function responseError(response) {
+    let error;
+    try {
+        error = (await response.json()).error;
+    }
+    catch {
+        error = undefined;
+    }
+    return new APIError(response.status, error?.code ?? 'invalid_response', error?.message ?? `HTTP ${response.status}`, error?.details, response.headers, error);
+}
+function serializeCreate(params) {
+    const { output_schema, ...rest } = params;
+    const independentRoot = rest.parent === undefined && rest.root === undefined ? { root: true } : {};
+    if (output_schema === undefined)
+        return { ...independentRoot, ...rest };
+    return {
+        ...independentRoot,
+        ...rest,
+        output_schema: typeof output_schema === 'string' ? output_schema : JSON.stringify(resolveJsonSchema(output_schema)),
+    };
+}
+function messageBody(body) {
+    if (typeof body === 'string')
+        return { body };
+    const { from: _from, ...request } = body;
+    return request;
+}
+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}`;
+}
+function connectStatus(instructions) {
+    return { connected: false, daemon: null, model: null, next_step: 'connect', instructions };
+}
+function connectCommand(params) {
+    const selectors = [
+        ['profile', params.profile],
+        ['cwd', params.cwd],
+        ['kind', params.kind],
+        ['model', params.model],
+    ].flatMap(([name, value]) => value === undefined ? [] : [`--${name}`, shellArgument(value)]);
+    return ['crtr', 'sys', 'connect', ...selectors].join(' ');
+}
+function shellArgument(value) {
+    if (/^[A-Za-z0-9_./:-]+$/.test(value))
+        return value;
+    return `'${value.replaceAll("'", String.fromCharCode(39, 34, 39, 34, 39))}'`;
+}
+async function socketIsReachable(socketPath) {
+    const load = new Function('specifier', 'return import(specifier)');
+    const [{ createConnection }, { defaultSocketPath }] = await Promise.all([
+        load('node:net'),
+        load('@north-light/api/node'),
+    ]);
+    const path = socketPath ?? defaultSocketPath();
+    return new Promise((resolve) => {
+        const socket = createConnection({ path });
+        const finish = (reachable) => {
+            socket.destroy();
+            resolve(reachable);
+        };
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+        socket.setTimeout(100, () => finish(false));
+    });
+}
+function nodeEnvironment() {
+    return isNodeRuntime() ? process.env : {};
+}
+function isNodeRuntime() {
+    return typeof process !== 'undefined' && process.versions?.node !== undefined;
+}
+/**
+ * Latest only (P2): the SDK accepts a runtime at or above its own release (`SDK_VERSION`) and nothing older, so its
+ * types never describe a field an older runtime does not send. Every runtime response names its release in
+ * `Crouter-Runtime-Version`; a successful answer from an older runtime, or one that names no release (every runtime
+ * before the header existed), is replaced by a 426 `runtime_version_unsupported` envelope before anything reads it,
+ * which the client raises as `RuntimeVersionError`. A refusal without the header passes through unchanged: it can come
+ * from a router or proxy in front of the runtime, and it carries no runtime data. `/healthz`, the unversioned
+ * substrate probe the cold-start wait polls, is exempt.
+ */
+function requireCurrentRuntime(inner) {
+    const checked = async (input, init) => {
+        const url = new URL(input instanceof Request ? input.url : String(input), 'http://localhost');
+        // Say which runtime this SDK accepts, so the router in front of a hosted runtime, or the runtime itself, refuses
+        // an older one before any handler runs. `/healthz` is exempt from both checks.
+        let sentInit = init;
+        if (url.pathname !== '/healthz') {
+            const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+            headers.set(MINIMUM_RUNTIME_VERSION_HEADER, SDK_VERSION);
+            sentInit = { ...init, headers };
+        }
+        const response = await (inner ?? globalThis.fetch)(input, sentInit);
+        if (url.pathname === '/healthz')
+            return response;
+        const runtimeVersion = response.headers.get(RUNTIME_VERSION_HEADER);
+        if (runtimeVersion === null ? !response.ok : compareReleaseVersions(runtimeVersion, SDK_VERSION) >= 0)
+            return response;
+        await response.body?.cancel();
+        const message = runtimeVersion === null
+            ? `The runtime did not name its version, so it predates the runtime version header; @north-light/sdk ${SDK_VERSION} requires a runtime at ${SDK_VERSION} or later. Upgrade the runtime, or pin @north-light/sdk to the runtime's release.`
+            : `The runtime is ${runtimeVersion}; @north-light/sdk ${SDK_VERSION} requires a runtime at ${SDK_VERSION} or later. Upgrade the runtime, or pin @north-light/sdk to ${runtimeVersion}.`;
+        return new Response(JSON.stringify({ error: {
+                code: 'runtime_version_unsupported', message, type: 'invalid_request_error', retryable: false,
+                details: { sdk_version: SDK_VERSION, runtime_version: runtimeVersion },
+            } }), { status: 426, headers: { 'content-type': 'application/json' } });
+    };
+    if (inner !== undefined && inner[LOCAL_SOCKET_FETCH] === true) {
+        checked[LOCAL_SOCKET_FETCH] = true;
+    }
+    return checked;
+}
+function localSocketFetch(socketPath) {
+    const load = new Function('specifier', 'return import(specifier)');
+    let fetchPromise;
+    const localFetch = (input, init) => {
+        fetchPromise ??= load('@north-light/api/node').then(({ socketFetch, defaultSocketPath }) => socketFetch(socketPath ?? defaultSocketPath()));
+        return fetchPromise.then((fetch) => fetch(input, init));
+    };
+    localFetch[LOCAL_SOCKET_FETCH] = true;
+    return localFetch;
+}
+async function startDaemon() {
+    const load = new Function('specifier', 'return import(specifier)');
+    const { spawn } = await load('node:child_process');
+    await new Promise((resolve, reject) => {
+        const child = spawn('crtr', ['sys', 'daemon', 'start'], { stdio: ['ignore', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+        child.once('error', (error) => reject(new CrouterError(`could not run \`crtr sys daemon start\`: ${error.message}`)));
+        child.once('exit', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new CrouterError(`\`crtr sys daemon start\` exited ${String(code)}${stderr === '' ? '' : `: ${stderr.trim()}`}`));
+        });
+    });
+}

package/dist/error-codes.d.ts

@@ -0,0 +1,7 @@
+export { errorCodes } from '@north-light/api';
+export type { ErrorCode, ErrorEnvelope, ErrorOrigin, ErrorType } from '@north-light/api';
+export { mapError } from './errors.js';
+/** Codes the SDK raises itself rather than reading from a daemon or directory response. */
+export declare const sdkErrorCodes: readonly ["crouter_error", "id_token_invalid", "oauth_nonce_missing", "oauth_state_mismatch", "oauth_exchange_mismatch", "not_connected", "refusal_handler_reentry", "run_idle", "waiting_on_user", "request_aborted", "request_timeout", "connection_error", "transport_error", "daemon_unavailable", "daemon_request_interrupted", "daemon_health_unavailable", "runtime_version_unsupported", "invalid_response", "stream_error", "stream_ended"];
+/** A code the SDK raises itself. An `APIError`'s `code` is one of these or an `ErrorCode` from the contract. */
+export type SdkErrorCode = typeof sdkErrorCodes[number];

package/dist/error-codes.js

@@ -0,0 +1,41 @@
+// The API contract owns the daemon's table; the SDK adds the codes it raises itself.
+export { errorCodes } from '@north-light/api';
+export { mapError } from './errors.js';
+/** Codes the SDK raises itself rather than reading from a daemon or directory response. */
+export const sdkErrorCodes = [
+    /** A `CrouterError` configuration or protocol failure with no more specific code. */
+    'crouter_error',
+    /** An ID token was missing, failed verification, or its nonce did not match. */
+    'id_token_invalid',
+    /** `exchangeIdentity` was called without the nonce `authorizeUrl` returned. */
+    'oauth_nonce_missing',
+    /** The callback's `state` was missing or differed from the saved one. */
+    'oauth_state_mismatch',
+    /** `exchangeCode` got a sign-in-only answer, or `exchangeIdentity` got one carrying a connection. */
+    'oauth_exchange_mismatch',
+    /** `oauth.client(userId)` or `refresh` found no stored connection for the person: they must sign in again. */
+    'not_connected',
+    /** `onRefusal` called `oauth.client` (or `refresh`) for the user whose dead connection it is handling. */
+    'refusal_handler_reentry',
+    /** `runs.parse`: the run stopped without settling. */
+    'run_idle',
+    /** `runs.parse`: the run waits on a question and no `onQuestion` was given. */
+    'waiting_on_user',
+    /** The caller's `AbortSignal` fired (`APIUserAbortError`). */
+    'request_aborted',
+    /** The request exceeded its timeout (`APIConnectionTimeoutError`). */
+    'request_timeout',
+    /** The daemon could not be reached, or the connection failed (`APIConnectionError`). */
+    'connection_error',
+    'transport_error',
+    'daemon_unavailable',
+    'daemon_request_interrupted',
+    'daemon_health_unavailable',
+    /** The runtime is older than this SDK, or sent no `Crouter-Runtime-Version` (`RuntimeVersionError`). */
+    'runtime_version_unsupported',
+    /** A response the SDK could not read as the API's JSON or error envelope. */
+    'invalid_response',
+    /** An event stream failed, or ended before the reply or node it carried did. */
+    'stream_error',
+    'stream_ended',
+];

package/dist/errors.d.ts

@@ -0,0 +1,57 @@
+import { APIError } from '@north-light/api';
+import type { SdkErrorCode } from './error-codes.js';
+export { APIError };
+/** An SDK configuration or protocol error, raised by the SDK itself. Its `code` is an `SdkErrorCode`. */
+export declare class CrouterError extends APIError {
+    readonly code: SdkErrorCode;
+    constructor(message: string, code?: SdkErrorCode);
+}
+/** The runtime is older than this SDK (or names no version at all), so the SDK's types do not describe what it
+ *  sends. Raised before the SDK reads the response; never retryable. Upgrade the runtime (or pin the SDK to the
+ *  runtime's release). `code` is `runtime_version_unsupported`, `status` 426. */
+export declare class RuntimeVersionError extends APIError {
+    /** The oldest runtime this SDK accepts: its own release version. */
+    get sdkVersion(): string;
+    /** The version the runtime named in `Crouter-Runtime-Version`, or `null` when it sent none (a runtime from before the header existed). */
+    get runtimeVersion(): string | null;
+}
+/** `RuntimeVersionError.details`. */
+export interface RuntimeVersionDetails {
+    sdk_version: string;
+    runtime_version: string | null;
+}
+/** The daemon rejected the request: HTTP 400. */
+export declare class BadRequestError extends APIError {
+}
+/** The token was missing or wrong: HTTP 401. */
+export declare class AuthenticationError extends APIError {
+}
+/** The caller is not allowed to do this: HTTP 403. */
+export declare class PermissionDeniedError extends APIError {
+}
+/** No such node, profile, cron, or other resource: HTTP 404. */
+export declare class NotFoundError extends APIError {
+}
+/** The resource is in a state that forbids the request: HTTP 409. */
+export declare class ConflictError extends APIError {
+}
+/** The request was well-formed but unusable, or too large: HTTP 413 and 422. */
+export declare class UnprocessableEntityError extends APIError {
+}
+/** Too many requests: HTTP 429. */
+export declare class RateLimitError extends APIError {
+}
+/** The daemon failed while handling the request: HTTP 500 and above. */
+export declare class InternalServerError extends APIError {
+}
+/** The daemon could not be reached, or the connection failed mid-request. */
+export declare class APIConnectionError extends APIError {
+}
+/** The request exceeded its timeout before the daemon answered. */
+export declare class APIConnectionTimeoutError extends APIConnectionError {
+}
+/** The caller's `AbortSignal` fired. */
+export declare class APIUserAbortError extends APIError {
+}
+/** Maps a transport failure or a plain `APIError` onto the specific class for its status and code. */
+export declare function mapError(error: unknown): APIError;