@north-light/api 0.0.0-stage → 0.3.414

package/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 Northlight Systems. All rights reserved.
+
+This software and its associated documentation files (the "Software") are the
+proprietary and confidential property of Northlight Systems. No licence or
+right to use, copy, modify, merge, publish, distribute, sublicense, sell,
+reverse engineer, decompile or create derivative works of the Software is
+granted except under a separate written agreement with Northlight Systems.
+
+The Software is made available as compiled and minified packages through the
+npm registry solely so that it can be installed and run by those authorised by
+Northlight Systems. Installing a package from the registry does not grant any
+licence to the Software's source code.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+NORTHLIGHT SYSTEMS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @north-light/api — the typed client and contract for the crtrd `/v1` API
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![crouter](https://raw.githubusercontent.com/Northlight-Systems/crouter/main/assets/banner.svg)
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@north-light/api"><img alt="npm" src="https://img.shields.io/npm/v/@north-light/api?label=npm"></a>
+</p>
+
+`@north-light/api` is the low-level contract for the crouter daemon's `/v1` HTTP API: the `CrtrClient` class, route builders, the API error type, request and response types (DTOs), and the schema for command-plugin manifests. It has no runtime dependencies and no install scripts.
+
+It is not the package most applications want. [`@north-light/sdk`](https://www.npmjs.com/package/@north-light/sdk) is built on it and adds run management, streaming, typed results and OAuth. Use `@north-light/api` when you need the wire contract itself — a thin client, a proxy, or tooling that validates plugin manifests.
+
+[Docs](https://docs.crouter.ai/docs/sdk) · [SDK resource map](https://docs.crouter.ai/docs/sdk/resources) · [crouter repository](https://github.com/Northlight-Systems/crouter) · [Source](https://github.com/Northlight-Systems/crouter/tree/main/src/api)
+
+## Install
+
+```bash
+npm install @north-light/api
+```
+
+The package is ESM-only. Import it from an ES module, or use dynamic `import()` from CommonJS. A crouter daemon (`npm install -g @north-light/cli`) must be reachable for any request.
+
+## Connect to a daemon
+
+`CrtrClient` is the typed HTTP client. Give it a TCP base URL and any required bearer header. `crtr sys connect` prints both for a local daemon.
+
+```ts
+import { CrtrClient } from '@north-light/api';
+
+const client = new CrtrClient({
+  baseUrl: 'https://my-crtrd.example.com',
+  headers: { authorization: 'Bearer a-daemon-token' },
+});
+
+const nodes = await client.listNodes();
+console.log(nodes.map((node) => node.node_id));
+```
+
+For the local Unix socket, import the Node-only entry point:
+
+```ts
+import { localClient } from '@north-light/api/node';
+
+const client = localClient();
+console.log(await client.healthz());
+```
+
+## Exports
+
+- `CrtrClient` and `waitForDaemonAvailability` for typed `/v1` requests.
+- `routes` and `API_VERSION` for route construction.
+- `LONG_POLL_ROUTES`, `longPollRoute` and `longPollHoldSeconds` — which daemon routes hold a request open (`?wait=`) and for how long, for a proxy that must not cut a held request off.
+- `ApiError`, `APIError`, `ErrorBody` and `isErrorBody` for the API error contract.
+- DTOs for canvas, nodes, reports, lifecycle, files, bash, memory, models, human requests, crons, reviews and related routes.
+- `@north-light/api/node` — `defaultSocketPath`, `socketFetch` and `localClient`.
+- `@north-light/api/plugin-manifest` and `@north-light/api/command-manifest` — the plugin command-manifest schema and validation types.
+- `@north-light/api/cards` — generated context types.
+
+## Related
+
+- [`@north-light/sdk`](https://www.npmjs.com/package/@north-light/sdk) — the client most applications should use.
+- [`@north-light/plugin`](https://www.npmjs.com/package/@north-light/plugin) — author plugins whose manifests use this package's types.
+- [Main repository](https://github.com/Northlight-Systems/crouter) — the `crtr` CLI, the `crtrd` daemon.
+
+## License
+
+Proprietary. Copyright (c) 2026 Northlight Systems. All rights reserved. See `LICENSE`.

package/dist/api/__tests__/error-codes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/__tests__/error-codes.test.js

@@ -0,0 +1,79 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+import { errorCodes } from '../error-codes.js';
+test('SDK and API expose one fixed code table with contract 2 tuples', () => {
+    assert.deepEqual(errorCodes.server_error, { type: 'server_error', status: 500, retryable: true });
+    assert.deepEqual(errorCodes.runtime_starting, { type: 'server_error', status: 503, retryable: true });
+    assert.deepEqual(errorCodes.payer_not_app, { type: 'permission_error', status: 403, retryable: false });
+    assert.deepEqual(errorCodes.cap_exhausted, { type: 'rate_limit_error', status: 402, retryable: false });
+    assert.deepEqual(errorCodes.concurrency_limit, { type: 'rate_limit_error', status: 429, retryable: true });
+    for (const code of ['grant_revoked', 'grant_removed', 'grant_suspended', 'refresh_token_expired', 'refresh_token_reused']) {
+        assert.deepEqual(errorCodes[code], { type: 'authentication_error', status: 401, retryable: false }, code);
+    }
+    assert.deepEqual(errorCodes.provider_setup_pending, { type: 'permission_error', status: 403, retryable: false });
+    assert.equal('provider_error' in errorCodes, false); // provider's 4xx status varies
+    assert.equal('usage' in errorCodes, false); // legacy socket-only code
+    assert.equal('stream_gap' in errorCodes, false); // stream protocol, not a fixed HTTP row
+});
+test('every statically named RunError and ProviderError agrees with the fixed table', () => {
+    const src = fileURLToPath(new URL('../..', import.meta.url));
+    const files = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(dir, entry.name);
+        return entry.isDirectory() ? files(path) : entry.name.endsWith('.ts') && !path.includes('/__tests__/') ? [path] : [];
+    });
+    const literals = (expr) => {
+        if (ts.isStringLiteral(expr) || ts.isNumericLiteral(expr))
+            return [ts.isNumericLiteral(expr) ? Number(expr.text) : expr.text];
+        if (ts.isConditionalExpression(expr))
+            return [...literals(expr.whenTrue), ...literals(expr.whenFalse)];
+        return [];
+    };
+    let checked = 0;
+    for (const path of files(src)) {
+        const source = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true);
+        const visit = (node) => {
+            if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && ['RunError', 'ProviderError'].includes(node.expression.text)) {
+                const args = node.arguments ?? [];
+                const run = node.expression.text === 'RunError';
+                const codes = args[run ? 1 : 0] ? literals(args[run ? 1 : 0]) : [];
+                const statuses = run && args[0] ? literals(args[0]) : [];
+                const options = !run && args[2] && ts.isObjectLiteralExpression(args[2]) ? args[2] : undefined;
+                const override = options?.properties.find((prop) => ts.isPropertyAssignment(prop) && prop.name.getText(source) === 'status');
+                const providerStatuses = override && ts.isPropertyAssignment(override) ? literals(override.initializer) : [];
+                for (const code of codes) {
+                    if (typeof code !== 'string' || ['provider_error', 'usage', 'stream_gap', 'stream_dropped', 'stream_error'].includes(code))
+                        continue;
+                    const row = errorCodes[code];
+                    assert.ok(row, `${path}:${source.getLineAndCharacterOfPosition(node.pos).line + 1}: ${code} missing from errorCodes`);
+                    for (const status of run ? statuses : providerStatuses)
+                        assert.equal(status, row.status, `${path}: ${code} status`);
+                    if (run && args[6] && args[6].kind !== ts.SyntaxKind.UndefinedKeyword && args[6].kind !== ts.SyntaxKind.NullKeyword) {
+                        const retry = args[6].kind === ts.SyntaxKind.TrueKeyword ? true : args[6].kind === ts.SyntaxKind.FalseKeyword ? false : undefined;
+                        if (retry !== undefined)
+                            assert.equal(retry, row.retryable, `${path}: ${code} retryable`);
+                    }
+                    else if (run && statuses.length) {
+                        for (const status of statuses)
+                            assert.equal(status === 503, row.retryable, `${path}: ${code} default retryable`);
+                    }
+                    checked++;
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    assert.ok(checked > 100, `checked only ${checked} throw sites`);
+});
+test('app origin belongs to the full HTTP envelope without a body status', () => {
+    const row = errorCodes.invalid_request;
+    const body = { error: { code: 'invalid_request', message: 'Missing prompt',
+            type: row.type, origin: 'app', retryable: row.retryable, request_id: 'request-1', param: 'prompt' } };
+    assert.equal(body.error.origin, 'app');
+    assert.equal('status' in body.error, false);
+    assert.equal(row.status, 400);
+});

package/dist/api/__tests__/integration/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/__tests__/integration/client.test.js

@@ -0,0 +1,276 @@
+// Client availability recovery regressions.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CrtrClient, safeColdStartDiagnostic } from '../../client.js';
+import { localClient } from '../../node-transport.js';
+import { ApiError } from '../../errors.js';
+import { DaemonExitedBeforeReadyError, daemonAutostartStartupFailure, ensureDaemon, resetDaemonAutostart, } from '../../../daemon/manage.js';
+function startDelayedHealthzServer(socketPath, delayMs) {
+    const server = createServer((_req, res) => {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+    });
+    const timer = setTimeout(() => server.listen(socketPath), delayMs);
+    return { server, cancel: () => clearTimeout(timer) };
+}
+// A dropped response is distinct from a refused connect. Its cause is unknown, so reads may wait and retry but mutations never replay.
+function startHandoverServer(socketPath) {
+    let dropped = false;
+    const server = createServer((req, res) => {
+        if (!dropped) {
+            dropped = true; // model the old server dying mid-request
+            req.socket.destroy();
+            return;
+        }
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, method: req.method }));
+    });
+    return {
+        server,
+        ready: new Promise((resolvePromise) => server.listen(socketPath, resolvePromise)),
+    };
+}
+test('a hang-up mid-request rides out the daemon handover and replays the idempotent call', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-handover-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, ready } = startHandoverServer(socketPath);
+    try {
+        await ready;
+        const client = localClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
+        assert.deepEqual(await client.request('GET', '/v1/nodes'), { ok: true, method: 'GET' });
+    }
+    finally {
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('an interrupted mutation is not replayed or labelled a daemon handover', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-handover-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, ready } = startHandoverServer(socketPath);
+    try {
+        await ready;
+        const client = localClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
+        await assert.rejects(() => client.request('POST', '/v1/nodes', {}), 
+        // Replaying is unsafe (the daemon may have applied it), so this one is the
+        // caller's call — but it must not be reported as a daemon that is down.
+        (err) => err instanceof ApiError && err.code === 'daemon_request_interrupted');
+    }
+    finally {
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a non-socket cold-start path surfaces its diagnostic after autostart times out', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-nonsocket-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    mkdirSync(socketPath);
+    const diagnostic = 'crtrd.log (tail):\napi.server.failed: EADDRINUSE';
+    const client = localClient({
+        socketPath,
+        autostart: true,
+        onColdSocket: async () => { },
+        coldStartPollWindowMs: 50,
+        coldStartDiagnostic: () => diagnostic,
+    });
+    try {
+        await assert.rejects(() => client.healthz(), (error) => error instanceof ApiError
+            && error.code === 'daemon_unavailable'
+            && error.message.includes(diagnostic));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('cliClient-style cold start fails loud when the injected poll window is shorter than the (valid) startup delay', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 300);
+    try {
+        const client = localClient({
+            socketPath,
+            autostart: true,
+            onColdSocket: async () => {
+                /* fire-and-forget: the delayed listen() above models ensureDaemon() */
+            },
+            coldStartPollWindowMs: 100, // shorter than the 300ms the daemon actually needs
+        });
+        await assert.rejects(() => client.healthz(), (err) => err instanceof ApiError && err.code === 'daemon_unavailable');
+    }
+    finally {
+        cancel(); // the client already timed out at 100ms; never let listen() fire at 300ms
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a disabled-autostart client waits for an externally managed listener without invoking its spawn hook', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 100);
+    let spawnAttempts = 0;
+    try {
+        const client = localClient({
+            socketPath,
+            autostart: false,
+            onColdSocket: async () => { spawnAttempts += 1; },
+            coldStartPollWindowMs: 1_000,
+        });
+        assert.deepEqual(await client.request('GET', '/v1/nodes'), { ok: true });
+        assert.equal(spawnAttempts, 0, 'disabled autostart only waits; it never invokes the spawn hook');
+    }
+    finally {
+        cancel();
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('availability expiry keeps the final transport failure inside one wall-clock budget', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const server = createServer((_req, _res) => { });
+    let listenTimer;
+    try {
+        const client = localClient({
+            socketPath,
+            autostart: true,
+            timeoutMs: 5_000,
+            coldStartPollWindowMs: 250,
+            onColdSocket: async () => { listenTimer = setTimeout(() => server.listen(socketPath), 10); },
+        });
+        const started = Date.now();
+        await assert.rejects(() => client.healthz(), (error) => error instanceof ApiError && error.code === 'request_timeout' && error.message.includes('request timed out'));
+        assert.ok(Date.now() - started < 500, 'a probe cannot extend the 250ms availability budget');
+    }
+    finally {
+        if (listenTimer !== undefined)
+            clearTimeout(listenTimer);
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a caller abort with a custom reason is request_aborted', async () => {
+    const controller = new AbortController();
+    const client = new CrtrClient({
+        baseUrl: 'http://fixture.test',
+        fetch: async (_input, init) => await new Promise((_resolve, reject) => {
+            const signal = init?.signal;
+            if (signal === null || signal === undefined)
+                throw new Error('request signal is required');
+            signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+        }),
+    });
+    const request = client.request('GET', '/healthz', undefined, { signal: controller.signal });
+    controller.abort(new Error('caller custom abort'));
+    await assert.rejects(request, (error) => error instanceof ApiError && error.code === 'request_aborted');
+});
+test('safeColdStartDiagnostic returns undefined for an absent hook', () => {
+    assert.equal(safeColdStartDiagnostic(undefined), undefined);
+});
+test('safeColdStartDiagnostic returns the hook result when it succeeds', () => {
+    assert.equal(safeColdStartDiagnostic(() => 'crtrd.log (tail):\nboom'), 'crtrd.log (tail):\nboom');
+});
+test('safeColdStartDiagnostic treats a THROWING hook as absent, not a propagated error', () => {
+    assert.equal(safeColdStartDiagnostic(() => {
+        throw new Error('custom hook blew up');
+    }), undefined);
+});
+test('a daemon this client started that fails terminally ends the cold-start wait at once with its reason', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-startup-failed-'));
+    const socketPath = join(dir, 'crtrd.sock'); // nothing ever listens
+    let failure;
+    const client = localClient({
+        socketPath,
+        autostart: true,
+        onColdSocket: async () => { setTimeout(() => { failure = 'daemon 7 exited before becoming ready (with exit code 1)\n[crtrd] claim lost: own_identity_indeterminate'; }, 150); },
+        coldStartPollWindowMs: 60_000,
+        coldStartFailure: () => failure,
+        coldStartDiagnostic: () => 'crtrd.log (tail): must not be appended to a reason that already explains itself',
+    });
+    const started = Date.now();
+    try {
+        await assert.rejects(() => client.healthz(), (error) => error instanceof ApiError
+            && error.code === 'daemon_unavailable'
+            && error.message.includes('crtrd failed to start')
+            && error.message.includes('own_identity_indeterminate')
+            && !error.message.includes('crtrd.log (tail)'));
+        assert.ok(Date.now() - started < 5_000, 'must not poll out the 60s window');
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a first spawn that failed does not end the wait of a later healthy spawn: failure → backoff → new in-flight attempt', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-stale-failure-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const savedEnv = process.env['CRTR_NO_DAEMON_AUTOSTART'];
+    delete process.env['CRTR_NO_DAEMON_AUTOSTART'];
+    resetDaemonAutostart();
+    let now = 1_000_000;
+    let spawns = 0;
+    let server;
+    let timer;
+    const deps = {
+        isDaemonRunning: () => false,
+        now: () => now,
+        spawnDaemon: () => {
+            spawns += 1;
+            if (spawns === 1)
+                return Promise.reject(new DaemonExitedBeforeReadyError('daemon 1 exited before becoming ready (with exit code 1)', 'FIRST SPAWN EXITED'));
+            // Attempt 2: stays in flight, and its daemon starts listening a moment later.
+            return new Promise((resolve) => {
+                server = createServer((_q, r) => { r.writeHead(200, { 'content-type': 'application/json' }); r.end('{"ok":true}'); });
+                timer = setTimeout(() => { server?.listen(socketPath); resolve({}); }, 400);
+            });
+        },
+    };
+    try {
+        ensureDaemon(deps); // attempt 1 — fails terminally
+        await new Promise((resolve) => setImmediate(resolve));
+        assert.match(daemonAutostartStartupFailure() ?? '', /FIRST SPAWN EXITED/);
+        now += 120_000; // backoff elapsed
+        const client = localClient({
+            socketPath,
+            autostart: true,
+            onColdSocket: async () => { ensureDaemon(deps); }, // attempt 2 starts as this client goes cold
+            coldStartPollWindowMs: 5_000,
+            coldStartFailure: daemonAutostartStartupFailure,
+        });
+        assert.ok((await client.healthz()) !== undefined);
+        assert.equal(spawns, 2);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        server?.close();
+        resetDaemonAutostart();
+        if (savedEnv === undefined)
+            delete process.env['CRTR_NO_DAEMON_AUTOSTART'];
+        else
+            process.env['CRTR_NO_DAEMON_AUTOSTART'] = savedEnv;
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('with no reported startup failure the cold-start wait keeps its full window', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-startup-slow-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 400);
+    try {
+        const client = localClient({
+            socketPath,
+            autostart: true,
+            onColdSocket: async () => { },
+            coldStartPollWindowMs: 5_000,
+            coldStartFailure: () => undefined, // a migration still making progress reports nothing
+        });
+        assert.ok((await client.healthz()) !== undefined);
+    }
+    finally {
+        cancel();
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});