@north-light/sdk 0.3.414 → 0.3.416

package/dist/client.d.ts

@@ -132,6 +132,14 @@ export declare class Crouter {
             api_version: string;
         }>;
     };
+    /** The caller's month-to-date spend (`usage.get`): user-paid model and provider usage, app-paid usage, the grant's
+     *  `spend_cap`, and `reset_at`. Once user-paid spend reaches `spend_cap`, user-paid model calls answer `cap_exhausted`
+     *  (a `RateLimitError`, status 402, `userAction: 'raise_cap'`) until `reset_at`. `month` is `YYYY-MM` (UTC; default: current). */
+    readonly usage: {
+        get: (params?: {
+            month?: string;
+        }, options?: RequestOptions) => Promise<import('@north-light/api').SpendUsageDTO>;
+    };
     private readonly eventFetch;
     private readonly bearerToken;
     private connectionToken;
@@ -153,10 +161,16 @@ export declare class Crouter {
     private authStatus;
     private stream;
     private events;
+    /** Opening a stream under the call's deadline: the open (token hook included) is abandoned and aborted at
+     *  `deadlineAt`. Once open, a stream has no deadline: it lives until it ends or `signal` aborts. */
+    private openWithin;
     private outcome;
     private waitForOutcome;
     private createAndWait;
     private parse;
+    /** Runs `operation` with the connection token, refreshing it once after a 401. `options` carries the call's one
+     *  deadline (resolved by `deadline`): the token fetch, the refresh and every attempt share it, and `operation`
+     *  receives the options with the deadline resolved. */
     private call;
 }
 export {};

package/dist/client.js

@@ -18,7 +18,7 @@ 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 { deadline, heldReadOptions, withinDeadline } 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');
@@ -71,6 +71,10 @@ export class Crouter {
      *  `wait`. To follow many people's grants, use `oauth.watchGrants`. */
     grant;
     health;
+    /** The caller's month-to-date spend (`usage.get`): user-paid model and provider usage, app-paid usage, the grant's
+     *  `spend_cap`, and `reset_at`. Once user-paid spend reaches `spend_cap`, user-paid model calls answer `cap_exhausted`
+     *  (a `RateLimitError`, status 402, `userAction: 'raise_cap'`) until `reset_at`. `month` is `YYYY-MM` (UTC; default: current). */
+    usage;
     eventFetch;
     bearerToken;
     connectionToken;
@@ -154,34 +158,34 @@ export class Crouter {
         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)),
+            create: (params, options) => this.call(deadline(options), (options) => 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));
+                return this.call(deadline(options), (options) => this.client.request('GET', routes.node(validId), undefined, options));
             },
-            list: (query, options) => this.call(() => this.client.request('GET', withQuery(routes.nodes(), query), undefined, options)),
+            list: (query, options) => this.call(deadline(options), (options) => 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));
+                return this.call(deadline(options), (options) => 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));
+                return this.call(deadline(options), (options) => 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));
+                return this.call(deadline(options), (options) => 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));
+                    return this.call(deadline(options), (options) => this.client.request('GET', withQuery(routes.nodeReports(validId), query), undefined, options));
                 },
             },
         };
@@ -196,17 +200,17 @@ export class Crouter {
         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));
+                return this.call(deadline(options), (options) => 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));
+                return this.call(deadline(options), (options) => this.client.request('GET', routes.profile(validName), undefined, options));
             },
-            list: (options) => this.call(() => this.client.request('GET', routes.profiles(), undefined, options)),
+            list: (options) => this.call(deadline(options), (options) => 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)),
+            status: (options) => this.call(deadline(options), (options) => this.client.request('GET', routes.status(), undefined, options)),
+            health: (options) => this.call(deadline(options), (options) => this.client.request('GET', routes.healthz(), undefined, options)),
         };
         this.auth = {
             status: (params, options) => this.authStatus(params, options),
@@ -225,10 +229,11 @@ export class Crouter {
                 return this.request('GET', withQuery('/v1/grant', { wait, since }), undefined, held);
             } };
         this.health = { get: (options) => this.request('GET', '/v1/health', undefined, options) };
+        this.usage = { get: (params = {}, options) => this.request('GET', withQuery('/v1/usage', { month: params.month }), 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, {
+        const response = await this.call(undefined, () => this.client.rawResponse('GET', path, {
             headers: { accept: 'application/x-ndjson', ...options.headers }, signal: options.signal,
             timeout: 0, maxRetries: options.maxRetries,
         }));
@@ -240,7 +245,7 @@ export class Crouter {
         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}`, {
+        return this.call(undefined, () => 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,
         }));
@@ -254,7 +259,7 @@ export class Crouter {
         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 () => {
+        const response = await this.call(undefined, async () => {
             try {
                 return await this.eventFetch(url, {
                     headers: { ...(this.bearerToken ? { Authorization: `Bearer ${this.bearerToken}` } : {}), ...(options.range ? { Range: options.range } : {}) },
@@ -273,7 +278,7 @@ export class Crouter {
     }
     /** 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');
+        return this.call(deadline(options), (options) => this.client.request(method, path, body, options), path !== '/v1/health');
     }
     async authStatus(params = {}, options) {
         if (this.baseURL === undefined && (!isNodeRuntime() || !await socketIsReachable(this.socketPath))) {
@@ -281,7 +286,7 @@ export class Crouter {
         }
         let daemon;
         try {
-            daemon = await this.call(() => this.client.request('GET', routes.status(), undefined, options));
+            daemon = await this.call(deadline(options), (options) => this.client.request('GET', routes.status(), undefined, options));
         }
         catch (error) {
             if (!(error instanceof APIError))
@@ -308,7 +313,7 @@ export class Crouter {
         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));
+        const model = await this.call(deadline(options), (options) => this.client.request('GET', withQuery(routes.modelAuthReadiness(), params), undefined, options));
         if (model.credential !== 'ready') {
             return {
                 connected: true,
@@ -322,20 +327,44 @@ export class Crouter {
     }
     stream(params, options) {
         const node = this.nodes.create(params, options);
-        const { timeout: _timeout, ...streamOptions } = options ?? {};
+        const { timeout: _timeout, budgetMs, deadlineAt, ...streamOptions } = options ?? {};
+        const opening = deadline({ budgetMs, deadlineAt })?.deadlineAt;
         return new NodeStream(node, async (signal) => {
             const created = await node;
-            return this.call(() => this.client.getNodeEvents(created.node_id, {}, { ...streamOptions, signal }));
+            return this.openWithin(opening, signal, (signal) => this.call(undefined, () => this.client.getNodeEvents(created.node_id, {}, { ...streamOptions, signal })));
         }, options?.signal);
     }
     events(id, options = {}) {
-        const { after, ...streamOptions } = options;
-        const node = this.nodes.retrieve(id, streamOptions);
+        const { after, budgetMs, deadlineAt, ...streamOptions } = options;
+        const opening = deadline({ budgetMs, deadlineAt })?.deadlineAt;
+        const node = this.nodes.retrieve(id, { ...streamOptions, ...(opening === undefined ? {} : { deadlineAt: opening }) });
         return new NodeStream(node, async (signal) => {
             const existing = await node;
-            return this.call(() => this.client.getNodeEvents(existing.node_id, { after }, { ...streamOptions, signal }));
+            return this.openWithin(opening, signal, (signal) => this.call(undefined, () => this.client.getNodeEvents(existing.node_id, { after }, { ...streamOptions, signal })));
         }, options.signal);
     }
+    /** Opening a stream under the call's deadline: the open (token hook included) is abandoned and aborted at
+     *  `deadlineAt`. Once open, a stream has no deadline: it lives until it ends or `signal` aborts. */
+    async openWithin(deadlineAt, signal, open) {
+        if (deadlineAt === undefined)
+            return open(signal);
+        const controller = new AbortController();
+        const onAbort = () => controller.abort(signal.reason);
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            return await withinDeadline(open(controller.signal), deadlineAt);
+        }
+        catch (error) {
+            controller.abort(error);
+            throw error instanceof APIError ? mapError(error) : error;
+        }
+        finally {
+            signal.removeEventListener('abort', onAbort);
+        }
+    }
     async outcome(id, options = {}) {
         const validId = nodeId(id);
         const { wait, ...requestOptions } = options;
@@ -343,16 +372,19 @@ export class Crouter {
             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 }));
+        return this.call(deadline({ ...requestOptions, timeout }), (options) => this.client.request('GET', withQuery(routes.nodeOutcome(validId), { wait }), undefined, options));
     }
-    async waitForOutcome(id, options) {
+    async waitForOutcome(id, unbounded) {
+        // One deadline for the whole wait: every poll shares it instead of restarting `budgetMs`.
+        const options = deadline(unbounded);
         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) {
+    async createAndWait(params, unbounded) {
+        const options = deadline(unbounded);
         const node = await this.nodes.create(params, options);
         return this.waitForOutcome(node.node_id, options);
     }
@@ -366,25 +398,32 @@ export class Crouter {
         }
         return { ...outcome, output_parsed: null };
     }
-    async call(operation, authenticate = true) {
+    /** Runs `operation` with the connection token, refreshing it once after a 401. `options` carries the call's one
+     *  deadline (resolved by `deadline`): the token fetch, the refresh and every attempt share it, and `operation`
+     *  receives the options with the deadline resolved. */
+    async call(options, operation, authenticate = true) {
+        const deadlineAt = options?.deadlineAt;
         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);
+                this.connectionToken = await withinDeadline(this.tokenSource(), deadlineAt).catch(throwMapped);
             let result;
             try {
-                result = await operation();
+                result = await operation(options ?? {});
             }
             catch (error) {
                 if (authenticate && attempt === 0 && error instanceof APIError && error.status === 401 && this.onUnauthorized) {
-                    await this.onUnauthorized().catch(throwMapped);
+                    await withinDeadline(this.onUnauthorized(), deadlineAt).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);
+                await withinDeadline((async () => { try {
+                    await result.body?.cancel();
+                }
+                catch { /* discarded */ } })(), deadlineAt).catch(() => { });
+                await withinDeadline(this.onUnauthorized(), deadlineAt).catch(throwMapped);
                 continue;
             }
             return result;

package/dist/crtr.d.ts

@@ -0,0 +1,24 @@
+/** How long a `crtr` call from an SDK command may run before the command gives up. */
+export declare const CRTR_TIMEOUT_MS = 60000;
+/** The join step crtr's `not_joined` answer names when it carries none of its own. */
+export declare const DEFAULT_JOIN_STEP = "Open https://account.northlight.ai/account/machines, choose Create join token, then run `crtr sys join --directory https://account.northlight.ai --token <token>`.";
+export type CrtrOutcome = {
+    kind: 'ok';
+    stdout: string;
+} | {
+    kind: 'missing';
+}
+/** crtr answered `not_joined`: this machine was never joined to an account, so no `cloud` leaf exists. */
+ | {
+    kind: 'not_joined';
+    joinStep: string;
+} | {
+    kind: 'failed';
+    message: string;
+};
+export declare const parseJson: (text: string) => unknown;
+/** Runs `crtr <argv>` once: execFile, no shell, the caller's environment. */
+export declare function runCrtr(argv: string[], timeoutMs: number): Promise<CrtrOutcome>;
+/** "This machine's crtr isn't joined …, so <what>." then the join step. */
+export declare const notJoinedLines: (what: string, joinStep: string) => string[];
+export declare const say: (lines: string[]) => void;

package/dist/crtr.js

@@ -0,0 +1,50 @@
+import { execFile } from 'node:child_process';
+/** How long a `crtr` call from an SDK command may run before the command gives up. */
+export const CRTR_TIMEOUT_MS = 60_000;
+/** The join step crtr's `not_joined` answer names when it carries none of its own. */
+export const DEFAULT_JOIN_STEP = 'Open https://account.northlight.ai/account/machines, choose Create join token, then run `crtr sys join --directory https://account.northlight.ai --token <token>`.';
+const seconds = (ms) => {
+    const n = Math.max(1, Math.round(ms / 1000));
+    return `${n} second${n === 1 ? '' : 's'}`;
+};
+export const parseJson = (text) => {
+    try {
+        return JSON.parse(text.trim());
+    }
+    catch {
+        return undefined;
+    }
+};
+const lastLine = (text) => text.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
+/** The JSON error that ends `text`, even when other lines (a warning, a notice) precede it. */
+const errorBody = (text) => {
+    const body = parseJson(text.slice(text.lastIndexOf('\n{') + 1));
+    return body && typeof body === 'object' && !Array.isArray(body) ? body : undefined;
+};
+const text = (value) => (typeof value === 'string' && value ? value : undefined);
+/** Runs `crtr <argv>` once: execFile, no shell, the caller's environment. */
+export function runCrtr(argv, timeoutMs) {
+    return new Promise((resolve) => {
+        execFile('crtr', argv, { timeout: timeoutMs, env: process.env, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+            const err = error;
+            if (err?.code === 'ENOENT')
+                return resolve({ kind: 'missing' });
+            if (!err)
+                return resolve({ kind: 'ok', stdout });
+            if (err.killed)
+                return resolve({ kind: 'failed', message: `crtr did not answer within ${seconds(timeoutMs)}.` });
+            const bodies = [errorBody(stdout), errorBody(stderr)];
+            const notJoined = bodies.find((body) => (text(body?.error) ?? text(body?.code)) === 'not_joined');
+            if (notJoined)
+                return resolve({ kind: 'not_joined', joinStep: text(notJoined.next) ?? DEFAULT_JOIN_STEP });
+            const message = bodies.map((body) => text(body?.message)).find(Boolean);
+            resolve({ kind: 'failed', message: message ?? lastLine(stderr) ?? lastLine(stdout) ?? err.message });
+        });
+    });
+}
+/** "This machine's crtr isn't joined …, so <what>." then the join step. */
+export const notJoinedLines = (what, joinStep) => [
+    `This machine's crtr isn't joined to your crouter cloud account, so ${what}.`,
+    joinStep,
+];
+export const say = (lines) => console.error(lines.join('\n'));

package/dist/env-command.d.ts

@@ -0,0 +1,15 @@
+export declare const ENV_USAGE = "Usage: crouter-sdk env --app <client id> [--out <path>]";
+/** The variables `env` owns, in the order it writes them. `CROUTER_KEY_FILE` is never one. */
+declare const NAMES: readonly ["CROUTER_ISSUER", "CROUTER_CLIENT_ID", "APP_ORIGIN"];
+type Name = typeof NAMES[number];
+export interface EnvOptions {
+    /** How long `crtr cloud apps get` may run before env gives up. */
+    crtrTimeoutMs?: number;
+}
+/** Rewrites each assignment to a name in `values`, appends the names it had none for, and keeps every other line. */
+export declare function updateEnvText(text: string, values: Record<Name, string>): string;
+/** The last `CROUTER_KEY_FILE` the file assigns, or undefined. */
+export declare function keyFileOf(text: string): string | undefined;
+/** The `crouter-sdk env` command. Returns the process exit code. */
+export declare function runEnv(argv: string[], options?: EnvOptions): Promise<number>;
+export {};

package/dist/env-command.js

@@ -0,0 +1,138 @@
+import { mkdir, open, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { CRTR_TIMEOUT_MS, notJoinedLines, parseJson, runCrtr, say } from './crtr.js';
+export const ENV_USAGE = 'Usage: crouter-sdk env --app <client id> [--out <path>]';
+const DEFAULT_KEY_FILE = 'local/app-key.json';
+/** The variables `env` owns, in the order it writes them. `CROUTER_KEY_FILE` is never one. */
+const NAMES = ['CROUTER_ISSUER', 'CROUTER_CLIENT_ID', 'APP_ORIGIN'];
+function parseArgs(args) {
+    if (args[0] !== 'env')
+        throw new Error(ENV_USAGE);
+    let path = 'local/app.env';
+    let app;
+    const seen = new Set();
+    for (let i = 1; i < args.length; i++) {
+        const flag = args[i];
+        const value = args[++i];
+        if (seen.has(flag) || (flag !== '--out' && flag !== '--app') || !value || value.startsWith('--'))
+            throw new Error(ENV_USAGE);
+        seen.add(flag);
+        if (flag === '--out')
+            path = value;
+        else
+            app = value;
+    }
+    if (!app)
+        throw new Error(ENV_USAGE);
+    return { path, app };
+}
+/** One `NAME=value` assignment line, with an optional `export ` prefix. */
+const ASSIGNMENT = /^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)(\s*=)(.*)$/;
+/** A value is written bare when a dotenv reader and a shell both read it back unchanged. */
+const formatValue = (value) => (/^[A-Za-z0-9_\-.:/@%+,~]*$/.test(value) ? value : JSON.stringify(value));
+/** The value of a dotenv assignment's right-hand side: quotes removed, a trailing comment dropped. */
+function readValue(raw) {
+    const text = raw.trim();
+    const quote = text[0];
+    if ((quote === '"' || quote === "'") && text.indexOf(quote, 1) > 0) {
+        const inner = text.slice(1, text.indexOf(quote, 1));
+        if (quote === "'")
+            return inner;
+        try {
+            return JSON.parse(`"${inner}"`);
+        }
+        catch {
+            return inner;
+        }
+    }
+    return text.replace(/\s+#.*$/, '');
+}
+/** Rewrites each assignment to a name in `values`, appends the names it had none for, and keeps every other line. */
+export function updateEnvText(text, values) {
+    const lines = text === '' ? [] : text.replace(/\n$/, '').split('\n');
+    const written = new Set();
+    const out = lines.map((line) => {
+        const match = ASSIGNMENT.exec(line);
+        const name = match?.[2];
+        if (!match || !name || !NAMES.includes(name))
+            return line;
+        written.add(name);
+        return `${match[1]}${name}${match[3]}${formatValue(values[name])}`;
+    });
+    for (const name of NAMES)
+        if (!written.has(name))
+            out.push(`${name}=${formatValue(values[name])}`);
+    return `${out.join('\n')}\n`;
+}
+/** The last `CROUTER_KEY_FILE` the file assigns, or undefined. */
+export function keyFileOf(text) {
+    let found;
+    for (const line of text.split('\n')) {
+        const match = ASSIGNMENT.exec(line);
+        if (match?.[2] === 'CROUTER_KEY_FILE')
+            found = readValue(match[4] ?? '');
+    }
+    return found || undefined;
+}
+function envOf(answer) {
+    const env = answer?.env;
+    if (!env || typeof env !== 'object')
+        return undefined;
+    const values = {};
+    for (const name of NAMES) {
+        const value = env[name];
+        if (typeof value !== 'string' || !value)
+            return undefined;
+        values[name] = value;
+    }
+    return values;
+}
+const byHand = (path) => `Set ${NAMES.join(', ')} in ${path} by hand: \`crtr cloud apps get --app-id <client id>\` shows them under env.`;
+/** The `crouter-sdk env` command. Returns the process exit code. */
+export async function runEnv(argv, options = {}) {
+    const { path, app } = parseArgs(argv);
+    const outcome = await runCrtr(['cloud', 'apps', 'get', '--app-id', app, '--json'], options.crtrTimeoutMs ?? CRTR_TIMEOUT_MS);
+    if (outcome.kind === 'missing') {
+        say(["Couldn't find crtr, so nothing was written.", byHand(path)]);
+        return 2;
+    }
+    if (outcome.kind === 'not_joined') {
+        say(notJoinedLines('nothing was written', outcome.joinStep));
+        return 2;
+    }
+    if (outcome.kind === 'failed') {
+        say([`Couldn't read ${app}: ${outcome.message}`, 'Nothing was written.']);
+        return 2;
+    }
+    const values = envOf(parseJson(outcome.stdout));
+    if (!values) {
+        const last = outcome.stdout.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
+        say([`crtr answered without the app's env: ${last ?? '(no output)'}`, 'Nothing was written.']);
+        return 2;
+    }
+    const existing = await readFile(path, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    const next = updateEnvText(existing ?? '', values);
+    if (existing === undefined) {
+        await mkdir(dirname(path), { recursive: true });
+        const file = await open(path, 'wx', 0o600);
+        try {
+            await file.writeFile(next);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    else if (next !== existing) {
+        await writeFile(path, next);
+    }
+    say([
+        `Set in ${path}:`,
+        ...NAMES.map((name) => `  ${name}=${values[name]}`),
+        `Key file: ${keyFileOf(next) ?? DEFAULT_KEY_FILE} (set CROUTER_KEY_FILE to change it).`,
+    ]);
+    return 0;
+}

package/dist/error-codes.d.ts

@@ -2,6 +2,6 @@ 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"];
+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", "deadline_exceeded", "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

@@ -25,6 +25,8 @@ export const sdkErrorCodes = [
     'request_aborted',
     /** The request exceeded its timeout (`APIConnectionTimeoutError`). */
     'request_timeout',
+    /** The call's overall deadline passed, or a retry wait would have passed it (`DeadlineExceededError`). */
+    'deadline_exceeded',
     /** The daemon could not be reached, or the connection failed (`APIConnectionError`). */
     'connection_error',
     'transport_error',

package/dist/errors.d.ts

@@ -50,6 +50,21 @@ export declare class APIConnectionError extends APIError {
 /** The request exceeded its timeout before the daemon answered. */
 export declare class APIConnectionTimeoutError extends APIConnectionError {
 }
+/** The call's overall deadline (`budgetMs` / `deadlineAt`) passed, or the next retry wait would have passed it.
+ *  `status` 504, `code` `deadline_exceeded`. `deadlineAt` is the instant (epoch ms); `reason` is `elapsed` (time ran out)
+ *  or `retry_after` (the server asked for a wait longer than the time left, so the call stopped without sleeping;
+ *  `retryAfterS` is that request). `cause` is the last failure, when there was one. */
+export declare class DeadlineExceededError extends APIConnectionTimeoutError {
+    get deadlineAt(): number;
+    get reason(): 'elapsed' | 'retry_after';
+    get retryAfterRequestS(): number | undefined;
+}
+/** `DeadlineExceededError.details`. */
+export interface DeadlineDetails {
+    deadline_at: number;
+    reason: 'elapsed' | 'retry_after';
+    retry_after_s?: number;
+}
 /** The caller's `AbortSignal` fired. */
 export declare class APIUserAbortError extends APIError {
 }

package/dist/errors.js

@@ -46,6 +46,15 @@ export class APIConnectionError extends APIError {
 /** The request exceeded its timeout before the daemon answered. */
 export class APIConnectionTimeoutError extends APIConnectionError {
 }
+/** The call's overall deadline (`budgetMs` / `deadlineAt`) passed, or the next retry wait would have passed it.
+ *  `status` 504, `code` `deadline_exceeded`. `deadlineAt` is the instant (epoch ms); `reason` is `elapsed` (time ran out)
+ *  or `retry_after` (the server asked for a wait longer than the time left, so the call stopped without sleeping;
+ *  `retryAfterS` is that request). `cause` is the last failure, when there was one. */
+export class DeadlineExceededError extends APIConnectionTimeoutError {
+    get deadlineAt() { return this.details.deadline_at; }
+    get reason() { return this.details.reason; }
+    get retryAfterRequestS() { return this.details.retry_after_s; }
+}
 /** The caller's `AbortSignal` fired. */
 export class APIUserAbortError extends APIError {
 }
@@ -56,32 +65,37 @@ export function mapError(error) {
     }
     const Constructor = error.code === 'runtime_version_unsupported'
         ? RuntimeVersionError
-        : error.code === 'request_aborted'
-            ? APIUserAbortError
-            : error.status === 504 || error.code === 'request_timeout'
-                ? APIConnectionTimeoutError
-                : error.code === 'daemon_unavailable' || error.code === 'transport_error' || error.code === 'daemon_request_interrupted' || error.code === 'daemon_health_unavailable'
-                    ? APIConnectionError
-                    : error.status === 400
-                        ? BadRequestError
-                        : error.status === 401
-                            ? AuthenticationError
-                            : error.status === 403
-                                ? PermissionDeniedError
-                                : error.status === 404
-                                    ? NotFoundError
-                                    : error.status === 409
-                                        ? ConflictError
-                                        : error.status === 413 || error.status === 422
-                                            ? UnprocessableEntityError
-                                            : error.status === 402 || error.status === 429
-                                                ? RateLimitError
-                                                : error.status >= 500
-                                                    ? InternalServerError
-                                                    : APIError;
-    return new Constructor(error.status, error.code, error.message, error.details, error.headers, {
+        : error.code === 'deadline_exceeded'
+            ? DeadlineExceededError
+            : error.code === 'request_aborted'
+                ? APIUserAbortError
+                : error.status === 504 || error.code === 'request_timeout'
+                    ? APIConnectionTimeoutError
+                    : error.code === 'daemon_unavailable' || error.code === 'transport_error' || error.code === 'daemon_request_interrupted' || error.code === 'daemon_health_unavailable'
+                        ? APIConnectionError
+                        : error.status === 400
+                            ? BadRequestError
+                            : error.status === 401
+                                ? AuthenticationError
+                                : error.status === 403
+                                    ? PermissionDeniedError
+                                    : error.status === 404
+                                        ? NotFoundError
+                                        : error.status === 409
+                                            ? ConflictError
+                                            : error.status === 413 || error.status === 422
+                                                ? UnprocessableEntityError
+                                                : error.status === 402 || error.status === 429
+                                                    ? RateLimitError
+                                                    : error.status >= 500
+                                                        ? InternalServerError
+                                                        : APIError;
+    const mapped = new Constructor(error.status, error.code, error.message, error.details, error.headers, {
         type: error.type, param: error.param, origin: error.origin, retryable: error.retryable,
         retry_after_s: error.retryAfterS, reset_at: error.resetAt, request_id: error.requestId, run_id: error.runId,
         question_id: error.questionId, scope: error.scope, user_action: error.userAction,
     });
+    if (error.cause !== undefined)
+        Object.defineProperty(mapped, 'cause', { value: error.cause, configurable: true, writable: true });
+    return mapped;
 }