@north-light/sdk 0.0.0 → 0.3.415

package/dist/client.js

@@ -0,0 +1,582 @@
+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 { 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');
+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;
+    /** 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;
+    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(deadline(options), (options) => this.client.request('POST', routes.nodes(), serializeCreate(params), options)),
+            retrieve: async (id, options) => {
+                const validId = nodeId(id);
+                return this.call(deadline(options), (options) => this.client.request('GET', routes.node(validId), 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(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(deadline(options), (options) => this.client.request('POST', routes.nodeClose(validId), body ?? {}, options));
+            },
+            interrupt: async (id, options) => {
+                const validId = nodeId(id);
+                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(deadline(options), (options) => 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(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(deadline(options), (options) => this.client.request('GET', routes.profile(validName), undefined, options));
+            },
+            list: (options) => this.call(deadline(options), (options) => this.client.request('GET', routes.profiles(), undefined, options)),
+        };
+        this.system = {
+            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),
+        };
+        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) };
+        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(undefined, () => 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(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,
+        }));
+    }
+    /** `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(undefined, 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(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))) {
+            return connectStatus('Install crtr, run `crtr sys connect`, and paste the base URL and token it prints.');
+        }
+        let daemon;
+        try {
+            daemon = await this.call(deadline(options), (options) => 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(deadline(options), (options) => 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, budgetMs, deadlineAt, ...streamOptions } = options ?? {};
+        const opening = deadline({ budgetMs, deadlineAt })?.deadlineAt;
+        return new NodeStream(node, async (signal) => {
+            const created = await node;
+            return this.openWithin(opening, signal, (signal) => this.call(undefined, () => this.client.getNodeEvents(created.node_id, {}, { ...streamOptions, signal })));
+        }, options?.signal);
+    }
+    events(id, options = {}) {
+        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.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;
+        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(deadline({ ...requestOptions, timeout }), (options) => this.client.request('GET', withQuery(routes.nodeOutcome(validId), { wait }), undefined, 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, unbounded) {
+        const options = deadline(unbounded);
+        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 };
+    }
+    /** 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 withinDeadline(this.tokenSource(), deadlineAt).catch(throwMapped);
+            let result;
+            try {
+                result = await operation(options ?? {});
+            }
+            catch (error) {
+                if (authenticate && attempt === 0 && error instanceof APIError && error.status === 401 && this.onUnauthorized) {
+                    await withinDeadline(this.onUnauthorized(), deadlineAt).catch(throwMapped);
+                    continue;
+                }
+                throw mapError(error);
+            }
+            if (authenticate && attempt === 0 && result instanceof Response && result.status === 401 && this.onUnauthorized) {
+                await withinDeadline((async () => { try {
+                    await result.body?.cancel();
+                }
+                catch { /* discarded */ } })(), deadlineAt).catch(() => { });
+                await withinDeadline(this.onUnauthorized(), deadlineAt).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/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'));