@north-light/api 0.3.580 → 0.3.588

package/dist/core/providers/device-libs.js

@@ -0,0 +1,202 @@
+import { ProviderError } from './errors.js';
+import { deviceDeps, deviceFailure, deviceUnreachable } from './device.js';
+/** Wire contract §9.1. */
+export const LIBS_SEARCH_PATH = '/v1/libs/search';
+export const LIBS_BUNDLE_PATH = '/v1/libs/bundle';
+export const LIBS_REPORT_PATH = '/v1/libs/report';
+/** The device wire version libs routes and bundled execs are served at. */
+export const LIBS_MAJOR = 2;
+/** The report is never awaited; this only keeps a hung one from living forever. */
+const REPORT_TIMEOUT_MS = 10_000;
+const LIB_IMPORT = /@(northlight|vallum)\//;
+const MAX_CALLS = 1000;
+const MAX_TEXT = 2000;
+const DEFAULT_RETRY_AFTER_S = 300;
+export const isLibsSearch = (major, tool) => major === LIBS_MAJOR && tool === 'browser libs';
+/** An exec whose code may import a library. The relay does the exact leading-import parse; a false positive costs one round trip. */
+export function wantsBundling(major, tool, args) {
+    return major === LIBS_MAJOR && tool === 'browser executor exec' && typeof args['code'] === 'string' && LIB_IMPORT.test(args['code']);
+}
+function retryAfterSeconds(headers) {
+    const raw = headers['retry-after'];
+    const first = Array.isArray(raw) ? raw[0] : raw;
+    const seconds = first === undefined ? NaN : Number(first);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
+}
+/** A relay libs answer that is not 2xx, as the error the agent sees. A 503 that names a wait carries it as `retry_after_s`. */
+function libsFailure(ctx, peer) {
+    const error = peer.body?.error;
+    const code = error && typeof error === 'object' && typeof error.code === 'string' ? error.code : undefined;
+    const message = error && typeof error === 'object' && typeof error.message === 'string' ? error.message : undefined;
+    const device = deviceFailure(ctx.machine, peer.status, code, message, peer.body);
+    if (device !== null)
+        return device;
+    const mapped = ctx.mapFailure(peer.status, peer.body, peer.headers);
+    const wait = peer.status === 503 ? retryAfterSeconds(peer.headers) : undefined;
+    if (wait === undefined || mapped.retry_after_s !== undefined)
+        return mapped;
+    return new ProviderError('provider_unavailable', mapped.message, { origin: mapped.origin, details: mapped.details, ...(mapped.param ? { param: mapped.param } : {}), retry_after_s: wait });
+}
+const budgetSpent = (ctx) => deviceUnreachable(ctx.machine, 'timeout', '');
+/** One libs request on the selected Desktop's relay host; returns the unwrapped `result` object. */
+async function libsRequest(ctx, path, body, version) {
+    const remaining = ctx.deadlineAt - Date.now();
+    if (remaining <= 0)
+        throw budgetSpent(ctx);
+    const peer = await deviceDeps.current.call(ctx.machine.machine_id, { method: 'POST', path, body: { ...body, version, deadline_at: ctx.deadlineAt } }, { envelope: ctx.envelope, device: true, signal: AbortSignal.any([ctx.signal, AbortSignal.timeout(remaining)]) });
+    if (ctx.signal.aborted)
+        throw ctx.signal.reason ?? new Error('provider call aborted');
+    if ('unreachable' in peer)
+        throw deviceUnreachable(ctx.machine, peer.unreachable.reason, peer.unreachable.message);
+    if (peer.status < 200 || peer.status >= 300)
+        throw libsFailure(ctx, peer);
+    const answer = peer.body && typeof peer.body === 'object' && !Array.isArray(peer.body) ? peer.body['result'] : undefined;
+    if (!answer || typeof answer !== 'object' || Array.isArray(answer)) {
+        throw new ProviderError('provider_bad_response', 'the libraries result is not a JSON object', { origin: 'provider', details: { status: peer.status, message: 'the libraries result is not a JSON object' } });
+    }
+    return answer;
+}
+/** `browser libs`: the relay's catalog search. The caller validates the result against the leaf's output. */
+export function callLibsSearch(ctx, args, version) {
+    return libsRequest(ctx, LIBS_SEARCH_PATH, { arguments: args }, version);
+}
+const strings = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : null;
+function parseServices(value) {
+    if (!Array.isArray(value))
+        return null;
+    const services = [];
+    for (const raw of value) {
+        const item = raw;
+        const domains = strings(item?.['domains']);
+        const writes = strings(item?.['writes']);
+        if (!item || typeof item['id'] !== 'string' || typeof item['name'] !== 'string' || domains === null || writes === null)
+            return null;
+        services.push({ id: item['id'], name: item['name'], domains, writes });
+    }
+    return services;
+}
+/** Bundle an exec's code. `null` when the relay found no library import (`bundled: false`): the arguments go to Desktop unchanged. */
+export async function bundleExec(ctx, args, version) {
+    const answer = await libsRequest(ctx, LIBS_BUNDLE_PATH, { code: args['code'] }, version);
+    if (answer['bundled'] === false)
+        return null;
+    const domains = strings(answer['domains']);
+    const services = parseServices(answer['services']);
+    if (answer['bundled'] !== true || typeof answer['bundle'] !== 'string' || domains === null || services === null || typeof answer['release'] !== 'string') {
+        throw new ProviderError('provider_bad_response', 'the libraries bundle answer is malformed', { origin: 'provider', details: { status: 200, message: 'the libraries bundle answer is malformed' } });
+    }
+    const { code: _code, ...rest } = args;
+    return { arguments: { ...rest, bundle: answer['bundle'], domains }, release: answer['release'], services };
+}
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+const text = (value) => typeof value === 'string' ? value.slice(0, MAX_TEXT) : undefined;
+const finite = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+/** The envelope comes from a web page's JavaScript, so it is rebuilt field by field: only the documented metadata survives, bounded,
+ *  and nothing a lib call received or returned can ride along in a record. */
+export function sanitizeCalls(value) {
+    if (!Array.isArray(value))
+        return [];
+    const calls = [];
+    for (const raw of value.slice(0, MAX_CALLS)) {
+        const record = object(raw);
+        const service = text(record?.['service']);
+        const fn = text(record?.['fn']);
+        if (!record || service === undefined || fn === undefined)
+            continue;
+        const errorClass = text(record['errorClass']);
+        const status = finite(record['status']);
+        const upstreamCode = text(record['upstreamCode']);
+        calls.push({
+            service, fn, ok: record['ok'] === true, durationMs: Math.max(0, Math.round(finite(record['durationMs']) ?? 0)),
+            ...(errorClass !== undefined && { errorClass }),
+            ...(status !== undefined && { status }),
+            ...(upstreamCode !== undefined && { upstreamCode }),
+            ...(typeof record['wasDispatched'] === 'boolean' && { wasDispatched: record['wasDispatched'] }),
+        });
+    }
+    return calls;
+}
+/** True when `url`'s host is, or is a subdomain of, any of `domains`. */
+function hostMatches(url, domains) {
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    return domains.some((raw) => {
+        const domain = raw.toLowerCase().replace(/^\*\./, '').replace(/^\./, '');
+        return host === domain || host.endsWith(`.${domain}`);
+    });
+}
+/** The first failed `Unauthenticated` call whose own service is not on `url`'s host, as "<Service> (on <host>)". Desktop warns only when
+ *  the page matches none of the imported libraries, so with several imports a call to a service on another site is found here. */
+function offSiteCall(calls, services, url) {
+    for (const call of calls) {
+        if (call.ok || call.errorClass !== 'Unauthenticated')
+            continue;
+        const service = services.find((candidate) => candidate.id === call.service);
+        if (!service || service.domains.length === 0 || hostMatches(url, service.domains))
+            continue;
+        let host = url;
+        try {
+            host = new URL(url).hostname || url;
+        }
+        catch { /* keep the raw url */ }
+        return `${service.name} is not on ${host} (it runs on ${service.domains.join(', ')})`;
+    }
+    return undefined;
+}
+/** The old top-level code, status and `next`, raised by crtrd itself. `details.status` makes the CLI print this code, not the status default. */
+function outcomeError(code, status, message, next, retryAfterS) {
+    return new ProviderError(code, message, { status, origin: 'provider', details: { code, message, next, status }, ...(retryAfterS === undefined ? {} : { retry_after_s: retryAfterS }) });
+}
+/** Turns Desktop's `{envelope, url, warning?}` into the leaf's answer or the design's error. Rules run top to bottom; the first match wins.
+ *  `calls` is always returned, so a failed record can be reported whichever way the exec ended. */
+export function mapLibOutcome(desktop, services) {
+    const envelope = object(desktop['envelope']);
+    if (!envelope || typeof desktop['url'] !== 'string') {
+        return { calls: [], error: outcomeError('js_exception', 409, 'The page returned a result that could not be read', 'Run the code again; if it keeps happening, report it') };
+    }
+    const url = desktop['url'];
+    const calls = sanitizeCalls(envelope['calls']);
+    const warning = text(desktop['warning']);
+    if (!('error' in envelope)) {
+        return { calls, result: { result: envelope['result'] === undefined ? null : envelope['result'], url, calls, ...(warning !== undefined && { warning }) } };
+    }
+    const message = text(envelope['error']) ?? 'The script threw';
+    // Off the libraries' domains: keep the host hint with any other failure.
+    const hint = warning === undefined ? '' : ` ${warning}`;
+    const errorClass = text(envelope['errorClass']);
+    const fail = (error) => ({ calls, error });
+    const dispatched = calls.filter((call) => call.wasDispatched === true && services.find((service) => service.id === call.service)?.writes.includes(call.fn) === true);
+    if (dispatched.length > 0) {
+        return fail(outcomeError('outcome_unknown', 409, `The script threw after ${dispatched.map((call) => `${call.service}.${call.fn}`).join(', ')} was sent, so it may have taken effect: ${message}`, `Check the site before repeating this action; do not retry blindly.${hint}`));
+    }
+    if (errorClass === 'Unauthenticated') {
+        const offSite = offSiteCall(calls, services, url);
+        if ((offSite ?? warning) !== undefined) {
+            return fail(outcomeError('wrong_site', 409, `The executor is on the wrong site, not signed out: ${offSite ?? warning} (${message})`, "Create the executor on the service's own site (browser executor create --url https://…) or navigate it there, then run the code again"));
+        }
+        return fail(outcomeError('site_signed_out', 409, `The site is signed out in this Chrome profile: ${message}`, "Sign in to the service in Chrome through the Northlight Desktop menu's Open Chrome profile, then run the code again"));
+    }
+    if (errorClass === 'RateLimited') {
+        const retryAfterS = finite(envelope['retryAfterS']);
+        const wait = retryAfterS !== undefined && retryAfterS >= 1 ? Math.ceil(retryAfterS) : DEFAULT_RETRY_AFTER_S;
+        return fail(outcomeError('rate_limited', 429, message, `Wait for Retry-After seconds, then run the code again.${hint}`, wait));
+    }
+    if (errorClass === 'ContractDrift') {
+        return fail(outcomeError('lib_broken', 502, `The library no longer matches the site: ${message}`, `Do not retry; the library needs a fix. Use a different approach for now.${hint}`));
+    }
+    return fail(outcomeError('js_exception', 409, errorClass && errorClass !== 'Unknown' ? `${errorClass}: ${message}` : message, `Fix the code or its arguments and run it again.${hint}`));
+}
+/** Fire-and-forget: tell the relay which lib calls failed so it can report them (metadata only). Nothing here can fail the call. */
+export function reportLibCalls(machine, envelope, release, calls) {
+    if (!calls.some((call) => !call.ok))
+        return;
+    try {
+        void deviceDeps.current.call(machine.machine_id, { method: 'POST', path: LIBS_REPORT_PATH, body: { release, calls } }, { envelope, device: true, signal: AbortSignal.timeout(REPORT_TIMEOUT_MS) }).catch(() => undefined);
+    }
+    catch { /* a report is best effort */ }
+}

package/dist/core/providers/device.d.ts

@@ -0,0 +1,42 @@
+import { type Machine } from '../peer/directory.js';
+import { type PeerResult, type PeerRequest, type PeerOptions } from '../peer/client.js';
+import type { Envelope } from '../peer/envelope.js';
+import { ProviderError } from './errors.js';
+export interface DeviceDeps {
+    list(): Promise<Machine[]>;
+    /** The last list the directory answered, however old; null before the first. Used only when the directory cannot be reached now. */
+    lastList(): Machine[] | null;
+    call(machineId: string, request: PeerRequest, options: PeerOptions): Promise<PeerResult>;
+}
+/** Tests replace `current`. */
+export declare const deviceDeps: {
+    current: DeviceDeps;
+};
+/** The device call's path on the Desktop (wire contract §5). */
+export declare const DEVICE_CALL_PATH = "/v1/device/call";
+/** The bundle's `timeouts.requestMs` when it declares none (device spec "Per-call deadline"). */
+export declare const DEFAULT_DEVICE_REQUEST_MS = 60000;
+/** The §2.1 selection table. `named` is the caller's `machine`, prefix optional. `newest`: an unnamed choice among several devices takes
+ *  the one seen last instead of refusing (browser libs: the answer is the same on every machine, so the agent need not choose). */
+export declare function selectDevice(named: string | undefined, deps?: DeviceDeps, options?: {
+    newest?: boolean;
+}): Promise<Machine>;
+export interface DeviceRequest {
+    tool: string;
+    arguments: Record<string, unknown>;
+    version: number;
+    requestId: string;
+    runId: string | null;
+    deadlineAt: number;
+    upload: {
+        id: string;
+        link: string;
+    } | null;
+}
+/** Wire contract §5 body. The upload link travels here, never in a header. */
+export declare function deviceBody(request: DeviceRequest): Record<string, unknown>;
+export declare function sendDeviceCall(machine: Machine, request: DeviceRequest, envelope: Envelope, signal: AbortSignal, deps?: DeviceDeps): Promise<PeerResult>;
+/** What a peer that never answered means for a device call. */
+export declare function deviceUnreachable(machine: Machine, reason: string, message: string): ProviderError;
+/** The device's (or relay's) non-2xx answer as the error `provider.call` returns, or null when the generic provider mapping should handle it. */
+export declare function deviceFailure(machine: Machine, status: number, code: string | undefined, message: string | undefined, body: unknown): ProviderError | null;

package/dist/core/providers/device.js

@@ -0,0 +1,95 @@
+// A provider served by a machine (`bundle.transport.kind === "machine"`, today `app:device`): the call is a peer call to one of the
+// account's `kind = device` machines over the relay, not an outbound-token HTTP call. This module owns machine selection, the
+// request, and the mapping of what the device (or the relay in front of it) answered.
+import { directory, normalizeMachineId } from '../peer/directory.js';
+import { peerCall } from '../peer/client.js';
+import { ProviderError } from './errors.js';
+/** Tests replace `current`. */
+export const deviceDeps = {
+    current: { list: () => directory.list(), lastList: () => directory.lastList(), call: (machineId, request, options) => peerCall(machineId, request, options) },
+};
+/** The device call's path on the Desktop (wire contract §5). */
+export const DEVICE_CALL_PATH = '/v1/device/call';
+/** The bundle's `timeouts.requestMs` when it declares none (device spec "Per-call deadline"). */
+export const DEFAULT_DEVICE_REQUEST_MS = 60_000;
+const candidateView = (machine) => ({ machine_id: machine.machine_id, name: machine.name, last_seen: machine.last_seen });
+function machineRequired(candidates, named) {
+    const list = candidates.map((machine) => `${machine.name} (${machine.machine_id})`).join(', ');
+    return new ProviderError('machine_required', named === undefined
+        ? `This account has ${candidates.length} devices: ${list}. Pick one with --machine <machine_id>.`
+        : `${named} is not one of this account's devices. Devices: ${list}. Pick one with --machine <machine_id>.`, { param: 'machine', details: { candidates: candidates.map(candidateView) } });
+}
+const seenAt = (machine) => { const at = machine.last_seen === null ? NaN : Date.parse(machine.last_seen); return Number.isFinite(at) ? at : -Infinity; };
+/** The §2.1 selection table. `named` is the caller's `machine`, prefix optional. `newest`: an unnamed choice among several devices takes
+ *  the one seen last instead of refusing (browser libs: the answer is the same on every machine, so the agent need not choose). */
+export async function selectDevice(named, deps = deviceDeps.current, options = {}) {
+    let machines;
+    try {
+        machines = await deps.list();
+    }
+    catch (error) {
+        const held = deps.lastList();
+        if (held === null)
+            throw new ProviderError('provider_unavailable', `The directory could not be reached to find your devices: ${error instanceof Error ? error.message : String(error)}`, { origin: 'directory' });
+        machines = held;
+    }
+    const candidates = machines.filter((machine) => machine.kind === 'device');
+    if (candidates.length === 0) {
+        const message = 'This needs the Northlight app on your Mac, and none is signed in to this account. Install Northlight Desktop on the Mac (on that Mac, `crtr sys desktop install`; otherwise https://account.northlight.ai/desktop), then sign in inside Desktop with the same Northlight account: its window shows a code and one Allow click.';
+        const next = 'Tell the person in one or two sentences what the Northlight app gives them for this task (their own signed-in browser, Messages, files and shell on this Mac) and ask once whether to install it. On yes: if you are running on their Mac, run `crtr sys desktop install` yourself; otherwise give them https://account.northlight.ai/desktop (or the download steps you already have) to install Desktop on their Mac. Then they sign in inside Desktop with the same Northlight account; do not ask them to sign crtr in. If they already said no to it in this conversation, do not ask again: say it needs the app and carry on without it.';
+        throw new ProviderError('provider_not_connected', message, { origin: 'provider', details: { code: 'provider_not_connected', message, next, status: 403 } });
+    }
+    if (named !== undefined) {
+        const id = normalizeMachineId(named);
+        const found = candidates.find((machine) => machine.machine_id === id);
+        if (!found)
+            throw machineRequired(candidates, named);
+        return found;
+    }
+    if (candidates.length > 1 && options.newest === true)
+        return candidates.reduce((best, machine) => seenAt(machine) > seenAt(best) ? machine : best);
+    if (candidates.length > 1)
+        throw machineRequired(candidates, undefined);
+    return candidates[0];
+}
+/** Wire contract §5 body. The upload link travels here, never in a header. */
+export function deviceBody(request) {
+    return { tool: request.tool, arguments: request.arguments, version: request.version, request_id: request.requestId,
+        ...(request.runId === null ? {} : { run_id: request.runId }), deadline_at: request.deadlineAt,
+        ...(request.upload === null ? {} : { upload: request.upload }) };
+}
+export async function sendDeviceCall(machine, request, envelope, signal, deps = deviceDeps.current) {
+    const remaining = Math.max(1, request.deadlineAt - Date.now());
+    return deps.call(machine.machine_id, { method: 'POST', path: DEVICE_CALL_PATH, body: deviceBody(request) }, { envelope, device: true, signal: AbortSignal.any([signal, AbortSignal.timeout(remaining)]) });
+}
+/** What a peer that never answered means for a device call. */
+export function deviceUnreachable(machine, reason, message) {
+    switch (reason) {
+        case 'timeout': return new ProviderError('device_timeout', `${machine.name} did not answer in time.`, { origin: 'runtime', details: { machine_id: machine.machine_id } });
+        case 'directory_unreachable':
+        case 'no_directory':
+            return new ProviderError('provider_unavailable', message, { origin: 'directory' });
+        case 'unknown_machine':
+            return new ProviderError('provider_not_connected', `${machine.name} is no longer on this account.`, { origin: 'directory' });
+        case 'not_a_crtr_peer':
+            return new ProviderError('server_error', message);
+        default: // machine_offline, network, runtime_starting: the peer message already names the machine and the cause
+            return new ProviderError('device_offline', message.trim() === '' ? `${machine.name} is offline.` : message, { origin: 'runtime', details: { machine_id: machine.machine_id } });
+    }
+}
+/** The device's (or relay's) non-2xx answer as the error `provider.call` returns, or null when the generic provider mapping should handle it. */
+export function deviceFailure(machine, status, code, message, body) {
+    if (status === 401)
+        return new ProviderError('device_offline', `${machine.name}: Desktop is signed out. Sign in to Northlight Desktop again.`, { origin: 'runtime', details: { machine_id: machine.machine_id } });
+    if (status === 426) {
+        const supported = (body?.error?.details?.supported);
+        return new ProviderError('peer_version_too_old', message ?? `${machine.name} does not serve this device major. Update Northlight Desktop.`, { origin: 'runtime', details: { machine_id: machine.machine_id, ...(Array.isArray(supported) ? { supported } : {}) } });
+    }
+    if (status === 502 && code === 'machine_disconnected') {
+        return new ProviderError('device_disconnected', `${machine.name} disconnected during the call; the action may have run.`, { origin: 'runtime', details: { machine_id: machine.machine_id } });
+    }
+    if (code === 'payload_too_large' || code === 'response_too_large') {
+        return new ProviderError('provider_error', message ?? `The call or its answer was too large for the relay (16 MiB).`, { origin: 'runtime', status: 413, details: { code, message: message ?? null, status } });
+    }
+    return null;
+}

package/dist/core/providers/errors.d.ts

@@ -0,0 +1,99 @@
+import { RunError } from '../runs/operations.js';
+export type ErrorType = 'invalid_request_error' | 'authentication_error' | 'permission_error' | 'rate_limit_error' | 'server_error';
+export type ErrorOrigin = 'directory' | 'router' | 'runtime' | 'provider';
+export interface CodeRow {
+    type: ErrorType;
+    status: number;
+    retryable: boolean;
+    user_action?: string;
+}
+/** The provider rows of the daemon-operations code table. `provider_error`'s
+ *  status is the provider's own 4xx; 400 is its default (a provider `scope_missing`). */
+export declare const PROVIDER_CODES: {
+    readonly provider_error: {
+        readonly type: "invalid_request_error";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly provider_rate_limited: {
+        readonly type: "rate_limit_error";
+        readonly status: 429;
+        readonly retryable: true;
+    };
+    readonly provider_unavailable: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly provider_refused: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly provider_not_connected: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly provider_version_retired: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly storage_unavailable: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly approval_pending: {
+        readonly user_action: "answer_question";
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly user_denied: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+};
+export type ProviderCode = keyof typeof PROVIDER_CODES;
+/** The non-provider codes a provider call also returns (the rest of the table
+ *  rows it reaches). Anything absent falls back by status. */
+declare const OTHER_CODES: Record<string, CodeRow>;
+export declare function codeRow(code: string, status: number): CodeRow;
+export interface ProviderErrorOptions {
+    /** Overrides the table status (`provider_error` carries the provider's 4xx). */
+    status?: number;
+    param?: string;
+    details?: unknown;
+    scope?: string;
+    origin?: ErrorOrigin;
+    retry_after_s?: number;
+    question_id?: string;
+    run_id?: string;
+    /** The error behind this one, kept for the log. */
+    cause?: unknown;
+}
+export declare class ProviderError extends RunError {
+    readonly origin: ErrorOrigin;
+    readonly type: ErrorType;
+    readonly retry_after_s?: number;
+    readonly question_id?: string;
+    readonly user_action?: string;
+    readonly run_id?: string;
+    constructor(code: ProviderCode | keyof typeof OTHER_CODES, message: string, options?: ProviderErrorOptions);
+}
+/** `scope_missing` naming the `<provider>:<group>` string. */
+export declare function scopeMissing(scope: string): ProviderError;
+/** The contract-2 error envelope for any value a provider operation throws.
+ *  A value that is not a `RunError` is a 500 `server_error` (its cause is logged by the caller).
+ *  `directoryCaller`: the caller holds a directory token (app listener). */
+export declare function providerErrorBody(thrown: unknown, requestId: string, directoryCaller: boolean, runId?: string): {
+    status: number;
+    body: {
+        error: Record<string, unknown>;
+    };
+    headers: Record<string, string>;
+};
+export {};

package/dist/core/providers/errors.js

@@ -0,0 +1,136 @@
+// Provider call error codes (contract 3; daemon-operations "Code table").
+//
+// Every refusal `provider.tools` / `provider.call` returns is a `ProviderError`:
+// a `RunError` (so every existing mapper still reads status/code/param/details)
+// that also carries the envelope fields a provider call sets — `origin`,
+// `retry_after_s`, `question_id`, `user_action`. `providerErrorBody` renders the
+// contract-2 envelope for any thrown value on both listeners.
+import { RunError } from '../runs/operations.js';
+import { errorCodes } from '../../api/error-codes.js';
+/** The provider rows of the daemon-operations code table. `provider_error`'s
+ *  status is the provider's own 4xx; 400 is its default (a provider `scope_missing`). */
+export const PROVIDER_CODES = {
+    provider_error: { type: 'invalid_request_error', status: 400, retryable: false },
+    provider_rate_limited: errorCodes.provider_rate_limited,
+    provider_unavailable: errorCodes.provider_unavailable,
+    provider_refused: errorCodes.provider_refused,
+    provider_not_connected: errorCodes.provider_not_connected,
+    provider_version_retired: errorCodes.provider_version_retired,
+    storage_unavailable: errorCodes.storage_unavailable,
+    approval_pending: { ...errorCodes.approval_pending, user_action: 'answer_question' },
+    user_denied: errorCodes.user_denied,
+};
+/** The non-provider codes a provider call also returns (the rest of the table
+ *  rows it reaches). Anything absent falls back by status. */
+const OTHER_CODES = {
+    unauthorized: errorCodes.unauthorized,
+    grant_revoked: errorCodes.grant_revoked,
+    machine_revoked: errorCodes.machine_revoked,
+    scope_missing: errorCodes.scope_missing,
+    permission_error: errorCodes.permission_error,
+    invalid_request: errorCodes.invalid_request,
+    not_found: errorCodes.not_found,
+    not_implemented: errorCodes.not_implemented,
+    runtime_starting: errorCodes.runtime_starting,
+    server_error: errorCodes.server_error,
+    provider_bad_response: errorCodes.provider_bad_response,
+    invalid_argument: errorCodes.invalid_argument,
+    machine_required: errorCodes.machine_required,
+    device_offline: errorCodes.device_offline,
+    device_timeout: errorCodes.device_timeout,
+    device_disconnected: errorCodes.device_disconnected,
+    peer_version_too_old: errorCodes.peer_version_too_old,
+    // Browser-library exec outcomes (device-libs.ts), raised with their own status. None is retryable: a write may have run, the site is
+    // signed out or the wrong one, the script is wrong, or the library needs a fix.
+    outcome_unknown: { type: 'invalid_request_error', status: 409, retryable: false },
+    wrong_site: { type: 'invalid_request_error', status: 409, retryable: false },
+    site_signed_out: { type: 'invalid_request_error', status: 409, retryable: false },
+    js_exception: { type: 'invalid_request_error', status: 409, retryable: false },
+    lib_broken: { type: 'server_error', status: 502, retryable: false },
+};
+export function codeRow(code, status) {
+    return PROVIDER_CODES[code] ?? OTHER_CODES[code]
+        ?? (Object.prototype.hasOwnProperty.call(errorCodes, code) ? errorCodes[code] : undefined) ?? {
+        type: status === 401 ? 'authentication_error' : status === 403 ? 'permission_error' : status === 429 ? 'rate_limit_error' : status >= 500 ? 'server_error' : 'invalid_request_error',
+        status, retryable: status >= 500,
+    };
+}
+export class ProviderError extends RunError {
+    origin;
+    type;
+    retry_after_s;
+    question_id;
+    user_action;
+    run_id;
+    constructor(code, message, options = {}) {
+        const row = codeRow(code, options.status ?? 500);
+        super(options.status ?? row.status, code, message, options.param, options.details, options.scope, row.retryable);
+        this.type = row.type;
+        this.origin = options.origin ?? 'runtime';
+        if (options.cause !== undefined)
+            this.cause = options.cause;
+        if (options.retry_after_s !== undefined)
+            this.retry_after_s = options.retry_after_s;
+        if (options.question_id !== undefined)
+            this.question_id = options.question_id;
+        if (options.run_id !== undefined)
+            this.run_id = options.run_id;
+        if (row.user_action !== undefined)
+            this.user_action = row.user_action;
+    }
+}
+/** `scope_missing` naming the `<provider>:<group>` string. */
+export function scopeMissing(scope) {
+    return new ProviderError('scope_missing', `missing scope ${scope}`, { scope });
+}
+/** An `ApiError`-shaped throw (numeric `status`, string `code`) from shared router code. */
+function shaped(thrown) {
+    if (!(thrown instanceof Error))
+        return null;
+    const { status, code, details, retryable } = thrown;
+    if (typeof status !== 'number' || typeof code !== 'string' || status < 400 || status > 599)
+        return null;
+    // The thrower's own retry decision wins; the code table only fills one it did not make.
+    return new RunError(status, code, thrown.message, undefined, details, undefined, typeof retryable === 'boolean' ? retryable : codeRow(code, status).retryable);
+}
+/** `reconnect` and `grant_scope:<scope>` only a directory can act on, so only a
+ *  directory-token caller (the app listener) gets them. */
+function directoryAction(err) {
+    if (err.code === 'unauthorized' || err.code === 'grant_revoked')
+        return 'reconnect';
+    if (err.code === 'scope_missing' && err.scope)
+        return `grant_scope:${err.scope}`;
+    return undefined;
+}
+/** The contract-2 error envelope for any value a provider operation throws.
+ *  A value that is not a `RunError` is a 500 `server_error` (its cause is logged by the caller).
+ *  `directoryCaller`: the caller holds a directory token (app listener). */
+export function providerErrorBody(thrown, requestId, directoryCaller, runId) {
+    const err = thrown instanceof RunError ? thrown : shaped(thrown) ?? new ProviderError('server_error', 'provider request failed');
+    const provider = err instanceof ProviderError ? err : null;
+    const row = codeRow(err.code, err.status);
+    const run = provider?.run_id ?? runId;
+    // A `cap_exhausted` refusal names its own `user_action` in its details (absent for an operator limit).
+    const capAction = err.details?.user_action;
+    const userAction = provider?.user_action ?? (err.code === 'cap_exhausted' ? (typeof capAction === 'string' ? capAction : undefined) : directoryCaller ? directoryAction(err) : undefined);
+    const resetAt = err.code === 'cap_exhausted' ? err.details?.reset_at : undefined;
+    const error = {
+        code: err.code, message: err.message,
+        ...(err.details === undefined ? {} : { details: err.details }),
+        type: provider?.type ?? row.type,
+        ...(err.param ? { param: err.param } : {}),
+        origin: provider?.origin ?? 'runtime',
+        retryable: err.retryable,
+        ...(provider?.retry_after_s === undefined ? {} : { retry_after_s: provider.retry_after_s }),
+        ...(typeof resetAt === 'string' ? { reset_at: resetAt } : {}),
+        request_id: requestId,
+        ...(run ? { run_id: run } : {}),
+        ...(provider?.question_id ? { question_id: provider.question_id } : {}),
+        ...(userAction ? { user_action: userAction } : {}),
+        ...(err.scope ? { scope: err.scope } : {}),
+    };
+    const headers = { 'Request-Id': requestId };
+    if (provider?.retry_after_s !== undefined)
+        headers['Retry-After'] = String(provider.retry_after_s);
+    return { status: err.status, body: { error }, headers };
+}