@north-light/sdk 0.0.0 → 0.3.415

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,188 @@
-# @north-light/sdk
+# @north-light/sdk — a typed Node and browser client for running crouter agents from your application
 
-Placeholder that reserves the name so trusted publishing can be configured. Real releases are published by CI from Northlight-Systems/crouter.
+![crouter](https://raw.githubusercontent.com/Northlight-Systems/crouter/main/assets/banner.svg)
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@north-light/sdk"><img alt="npm" src="https://img.shields.io/npm/v/@north-light/sdk?label=npm"></a>
+</p>
+
+`@north-light/sdk` is the application-facing client for a crouter daemon (`crtrd`). Create an agent run, wait for a result checked against a Zod or Standard Schema, stream the run's text and tool calls to a UI, and use the daemon's other APIs: files, bash, documents ("memory"), crons, human requests, and the OAuth connection flow for apps whose users each have their own runtime. It is ESM-only.
+
+It is a client, not a runtime. It never runs an agent itself, and it does not bundle a model: the daemon it talks to does, using the provider that daemon is signed in to. In Node, `new Crouter()` connects to the local daemon over its unix socket and starts it on the first request if it is not running. In a browser or from another machine it needs the daemon's TCP URL and a bearer token. The lower-level contract it is built on is [`@north-light/api`](https://www.npmjs.com/package/@north-light/api); most applications should install this package instead.
+
+[Docs](https://docs.crouter.ai/docs/sdk) · [Client construction](https://docs.crouter.ai/docs/sdk/client) · [Resource map](https://docs.crouter.ai/docs/sdk/resources) · [Recipes](https://docs.crouter.ai/docs/sdk/guides) · [crouter repository](https://github.com/Northlight-Systems/crouter)
+
+## Install
+
+```bash
+npm install @north-light/sdk zod   # zod is optional; any Standard Schema works for output_schema
+npm install -g @north-light/cli         # the daemon and the crtr CLI
+crtr                           # first run: the installer signs you in to a model provider
+```
+
+## Connect
+
+In Node, `new Crouter()` uses the local unix socket and starts the daemon on the first request when the socket is cold. In a browser or a remote process, pass the TCP URL and bearer token returned by `crtr sys connect` — the owner token, or a scoped token from `crtr sys connect --scopes` whose list caps what the application and its runs may do. Call `client.auth.status()` before enabling a run button: its `instructions` tells the user what to do when `next_step` is not `null`.
+
+```ts
+import Crouter from '@north-light/sdk';
+
+const client = new Crouter();
+const status = await client.auth.status();
+
+if (status.next_step !== null) {
+  console.log(status.instructions);
+} else {
+  console.log('The daemon and selected provider are ready.');
+}
+```
+
+```ts
+const client = new Crouter({
+  baseURL: 'http://127.0.0.1:8787',
+  token: 'the-token-from-crtr-sys-connect',
+});
+```
+
+## Runtime version
+
+The SDK talks only to a runtime at or above its own version (`SDK_VERSION`), and has no compatibility mode for older ones: its types, such as `RunObject.activity`, describe what a runtime at its release sends. Every runtime answer carries a `Crouter-Runtime-Version` header. When that version is older than the SDK, or the header is missing (every runtime released before this rule shipped), the call throws `RuntimeVersionError` before the SDK reads the response: `code` is `runtime_version_unsupported`, `status` is 426, `retryable` is false, and `sdkVersion` and `runtimeVersion` name both versions. The SDK also sends its own version on every request except `/healthz` as `Crouter-Minimum-Runtime-Version`; the hosting router and a runtime at this release or later refuse an older runtime with the same 426 *before* any handler runs, so nothing is accepted and no `Idempotency-Key` is recorded (a retry after the roll is a first send). Upgrade the runtime first, then the SDK.
+
+Pin `@north-light/sdk` to an exact version. One release is one version set: `@north-light/sdk@X` depends on exactly `@north-light/api@X` and `@north-light/identity@X`, so the pin fixes all three.
+
+```ts
+import { RuntimeVersionError } from '@north-light/sdk';
+
+try {
+  await client.runs.get(runId);
+} catch (error) {
+  if (error instanceof RuntimeVersionError) console.error(`runtime ${error.runtimeVersion ?? '(unnamed)'} is older than SDK ${error.sdkVersion}`);
+  else throw error;
+}
+```
+
+## Run and parse a result
+
+`parse()` creates a root run, waits for its outcome, and types `output_parsed` from a Zod or Standard Schema. Pass `scopes` to give a run a per-run allow-list; under a scoped token the list must stay inside the token's ceiling, and omitting it gives the run the ceiling.
+
+```ts
+import Crouter from '@north-light/sdk';
+import { z } from 'zod';
+
+const client = new Crouter();
+const run = await client.nodes.parse({
+  prompt: 'Read package.json and return its name and version.',
+  cwd: '/absolute/path/to/project',
+  scopes: ['crtr:llm', 'crtr:files:read:user:.'],
+  output_schema: z.object({ name: z.string(), version: z.string() }),
+});
+
+if (run.kind === 'result') console.log(run.output_parsed.name, run.output_parsed.version);
+else if (run.reason === 'declined') console.warn(run.declined?.reason);
+else console.error(run.reason, run.detail);
+```
+
+## Stream a run
+
+`nodes.stream()` creates a run and opens its event stream. `followActivity()` turns tool-call events into snapshots for an activity view. Disconnecting or calling `stream.abort()` stops the stream, not the run.
+
+```ts
+import { followActivity } from '@north-light/sdk';
+
+const stream = client.nodes.stream({
+  prompt: 'Inspect the repository and report the failing tests.',
+  cwd: '/absolute/path/to/project',
+});
+
+for await (const steps of followActivity(stream)) {
+  renderActivity(steps);
+}
+
+const outcome = await stream.finalOutcome();
+console.log(outcome.kind);
+```
+
+## Follow the reply to a message
+
+On a run, `runs.reply(runId, sent)` follows the turn that answers one `runs.message` and ends when that turn completes. `turn.completed.error` reports a refused (`content_refused`) or failed (`model_error`) model call.
+
+```ts
+const sent = await client.runs.message(runId, 'Hello');
+const text = await client.runs.reply(runId, sent).text();
+```
+
+To answer a first message in the run's first turn, pass it to `runs.start`: `message` is stored with the run and always joins the first turn as context ahead of `prompt`, and the result's `message` is what `runs.reply` takes. (A `runs.message(id, text, {start_turn: false})` sent after `runs.start` joins the first turn only if it is stored before the run claims that turn's messages.)
+
+`runs.message(id, text, {idempotencyKey})` sends an `Idempotency-Key` (a fresh `crypto.randomUUID()` per call, reused across the SDK's own retries). The daemon delivers a key once for 24 hours and returns the original result on replay; the same key with a different body fails with `409 idempotency_conflict`. Pass your own key, derived from your message id, to dedupe across process restarts.
+
+```ts
+const run = await client.runs.start({prompt: instructions, message: 'Hello'});
+const {text, ended, error} = await client.runs.reply(run.run_id, run.message!).collect({onDelta: (delta) => send(delta)});
+// ended: 'completed' | 'error' (see error) | 'waiting_on_user' | 'settled' (see outcome)
+```
+
+`collect` (and `text({onDelta})`) passes each streamed piece to `onDelta`, starting a later assistant message with a blank line, and resolves to the trimmed messages joined by a blank line. The raw `RunReplyEvent` iterator stays available.
+
+A run working in the background reports what it is doing on `runs.get(runId).activity` (`starting`, `thinking`, `tool` with `tool.name` and `tool.summary`, `writing`, or `between_turns`; `null` once it is no longer `running`), so a polling page shows progress without reading `runs.trace`.
+
+`runs.listAll(filters)` and `memory.listAll(params)` (the person's knowledge and preference documents the caller can read: `public` by default, every privacy level with `crtr:memory:manage:user`) iterate every item across pages with `for await`, fetching the next page only as you go. `runs.delete(runId)` deletes a running run too — it stops the run's turns and sandboxes itself, so there is no need to `cancel` first; deleting a run that is already gone throws `NotFoundError`.
+
+## Read files and run bash
+
+File paths and the bash working directory are absolute. `bash.run()` returns non-zero exits as values.
+
+```ts
+const source = await client.files.read('/absolute/path/to/project/package.json');
+const command = await client.bash.run({
+  command: 'npm test',
+  cwd: '/absolute/path/to/project',
+  timeout_s: 60,
+});
+
+console.log(source.content, command.exit_code);
+```
+
+## PostgreSQL connection store (Node)
+
+For a multi-process OAuth app, install `pg` in the app (`npm install pg`) and import the optional `@north-light/sdk/stores/postgres` subpath; the SDK's main entry never loads `pg`. `new PostgresConnectionStore(pool, { table: 'connection' })` implements `load`, `save`, `lock`, `remove(userId, refreshToken)`, and `listStale(before: Date)`. Pass it as `new OAuth2Client({..., store})`. Use one shared database and the same table for all workers. The lock keeps one PostgreSQL transaction and client open across the entire refresh callback (including the token request), so provision the pool for concurrent refreshes and avoid a transaction timeout shorter than the request. The table name accepts one or two lowercase SQL identifiers (schema.table), never SQL fragments.
+
+Create the table before using the store (or adapt this schema in your migration):
+
+```sql
+CREATE TABLE connection (
+  user_id text PRIMARY KEY,
+  runtime_url text NOT NULL,
+  refresh_token text NOT NULL,
+  grant_id text NOT NULL,
+  access_token text NOT NULL,
+  access_token_expires_at timestamptz NOT NULL,
+  id_token text,
+  updated_at timestamptz NOT NULL DEFAULT clock_timestamp()
+);
+CREATE INDEX connection_updated_at_idx ON connection (updated_at, user_id);
+```
+
+`save` upserts all fields and sets `updated_at` to the database clock. `listStale(before)` selects connections with `updated_at < before`, oldest first; it is a **last save** timestamp, not necessarily last successful refresh if an app also calls `save` for another reason. For idle-token maintenance, schedule `oauth.refreshIdleConnections({olderThanMs: 30 * 24 * 60 * 60 * 1000})` (for example, daily). It selects stale connections, refreshes under the store lock, reloads there to avoid rotating an already-used token, saves a rotated connection, and reports `{refreshed, refused, failures}`. A connection the directory refuses goes to the client's `onRefusal(refusal)` and is then removed (`remove` deletes the row only while it still holds the refused token); `refusal.kind` is `'removed'` (`grant_removed`: the runtime deleted the app's runs; delete what you store for the person), `'paused'` (`grant_suspended`: nothing was deleted; keep the data until they sign in again), or `'reconnect'` (`refresh_token_expired`, `refresh_token_reused`, `grant_revoked`: nothing was deleted; ask them to sign in again). `refusalOf(error)` returns the same `Refusal` from a refused call's error. Load the signing key `crouter-sdk keygen` wrote with `privateKey: await privateKeyFromFile('local/app-key.json')` (Node), or check one from an environment variable with `parsePrivateJwk(text)`; both refuse anything but a private JWK with a `kid`. The SDK does not start a timer. `listStale` returns connections, not timestamps, so a worker needing a strict cutoff recheck must maintain that policy separately. The table contains credentials: restrict database access, encrypt backups, and delete a row when its user disconnects. PostgreSQL `timestamptz` must be returned as a JavaScript `Date` (the `pg` default parser).
+
+## Example application
+
+See the complete [localhost SDK demo](https://github.com/Northlight-Systems/crouter/tree/main/examples/localhost-demo) for streaming, structured output, and an HTTP plugin in one local page.
+
+## Reference
+
+The [SDK guide](https://docs.crouter.ai/docs/sdk) covers [client construction](https://docs.crouter.ai/docs/sdk/client), [nodes and scopes](https://docs.crouter.ai/docs/sdk/nodes), [streaming](https://docs.crouter.ai/docs/sdk/streaming), [files](https://docs.crouter.ai/docs/sdk/files), [bash](https://docs.crouter.ai/docs/sdk/bash), [Docker](https://docs.crouter.ai/docs/sdk/docker), [errors](https://docs.crouter.ai/docs/sdk/errors), and the complete [resource map](https://docs.crouter.ai/docs/sdk/resources).
+
+`@north-light/sdk/errors` exports `errorCodes`/`ErrorCode` (the daemon's codes), `sdkErrorCodes`/`SdkErrorCode` (the codes the SDK raises itself, such as `oauth_state_mismatch`; `CrouterError.code` is typed with them), and `mapError`, which turns a plain `APIError` into its status class (`NotFoundError`, …) for app tests.
+
+The SDK re-exports its public DTO types, so you do not also install `@north-light/api`.
+
+## Related
+
+- [`@north-light/api`](https://www.npmjs.com/package/@north-light/api): the `/v1` contract this client is built on.
+- [`@north-light/env-docker`](https://www.npmjs.com/package/@north-light/env-docker): start a `crtrd` container and get a `Connection` to pass to `new Crouter(...)`.
+- [`@north-light/plugin`](https://www.npmjs.com/package/@north-light/plugin): expose your own commands to agents as `crtr` commands.
+- [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/client.d.ts

@@ -0,0 +1,176 @@
+import { type HealthDTO, type MessageResultDTO, type NodeDetailDTO, type ListNodesQuery, type NodeOutcomeDTO, type NodeOutcomeResponseDTO, type NodeSummaryDTO, type ProfileDTO, type ReportDTO, type ReportsQuery, type StatusDTO } from '@north-light/api';
+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 { 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 type { AuthStatus, AuthStatusParams, CancelParams, EnsureProfileParams, MessageParams, NodeCreateParams, NodeEventsOptions, NodeOutcomeOptions, OutputSchema, ParsedOutcome, RequestOptions, SchemaOutput } from './types.js';
+import type { AppProfile } from './resources/runs.js';
+type CoreNodes = {
+    create: (params: NodeCreateParams, options?: RequestOptions) => Promise<NodeDetailDTO>;
+    retrieve: (id: string, options?: RequestOptions) => Promise<NodeDetailDTO>;
+    list: (query?: ListNodesQuery, options?: RequestOptions) => Promise<NodeSummaryDTO[]>;
+    outcome: (id: string, options?: NodeOutcomeOptions) => Promise<NodeOutcomeResponseDTO>;
+    waitForOutcome: (id: string, options?: RequestOptions) => Promise<NodeOutcomeDTO>;
+    createAndWait: (params: NodeCreateParams, options?: RequestOptions) => Promise<NodeOutcomeDTO>;
+    parse: <TSchema extends OutputSchema>(params: NodeCreateParams & {
+        output_schema: TSchema;
+    }, options?: RequestOptions) => Promise<ParsedOutcome<SchemaOutput<TSchema>>>;
+    message: (id: string, body: string | MessageParams, options?: RequestOptions) => Promise<MessageResultDTO>;
+    cancel: (id: string, body?: CancelParams, options?: RequestOptions) => Promise<unknown>;
+    interrupt: (id: string, options?: RequestOptions) => Promise<unknown>;
+    stream: (params: NodeCreateParams, options?: RequestOptions) => NodeStream;
+    events: (id: string, options?: NodeEventsOptions) => NodeStream;
+    reports: {
+        list: (id: string, query?: ReportsQuery, options?: RequestOptions) => Promise<ReportDTO[]>;
+    };
+};
+/** Connection settings for a Crouter daemon. `headers` lets a Docker environment's
+ * `connection()` result pass directly to this constructor. */
+export interface CrouterOptions {
+    /** `http(s)://host:port` of a daemon TCP listener. Defaults to `CRTR_BASE_URL`. */
+    baseURL?: string;
+    /** Unix socket path. Node only. Defaults to `CRTR_SOCKET`, else `$CRTR_HOME/crtrd.sock`, else `~/.crouter/canvas/crtrd.sock`. */
+    socketPath?: string;
+    /** Sent as `Authorization: Bearer <token>`. Defaults to `CRTRD_TOKEN`. A unix-socket daemon ignores it. */
+    token?: string;
+    /** Supplies a directory token per request, including reconnects. Mutually exclusive with token. */
+    tokenSource?: () => Promise<string>;
+    /** Refreshes a connection-backed token once after a 401. */
+    onUnauthorized?: () => Promise<void>;
+    /** Per-request wall clock in milliseconds. Defaults to 30000. Does not apply to a stream. */
+    timeout?: number;
+    /** Transient-failure retries. Defaults to 2. Never applied to `POST` or `PATCH`. */
+    maxRetries?: number;
+    /** Merged into every request. */
+    defaultHeaders?: Record<string, string>;
+    /** Merged after `defaultHeaders`; the `Authorization` generated from `token` still wins. */
+    headers?: Record<string, string>;
+    /** Transport override, for proxies and instrumentation. */
+    fetch?: typeof fetch;
+    /** On a cold socket, run `crtr sys daemon start` and retry once. Node only. Defaults to true for a socket, false for `baseURL`. */
+    autostart?: boolean;
+}
+/**
+ * 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 declare class Crouter {
+    /** Create, inspect, message, stream, and wait on nodes. */
+    readonly nodes: NodesResource & CoreNodes;
+    /** Run one command in an absolute working directory. */
+    readonly bash: Bash;
+    /** Canvas-wide views: attention, snapshot, roster, dashboard, prune, and history. */
+    readonly canvas: Canvas;
+    /** Scheduled commands. */
+    readonly crons: Crons;
+    /** Durable structured requests with deadlines and one settlement. */
+    readonly structuredRequests: StructuredRequests;
+    /** Register, publish, receive, and acknowledge custom canvas objects. */
+    readonly customObjects: CustomObjects;
+    /** Human requests and the human inbox. */
+    readonly human: Human;
+    /** Model credentials and model configuration. */
+    readonly models: Models;
+    /** Agent profiles. */
+    readonly profiles: {
+        ensure: (name: string, params?: EnsureProfileParams, options?: RequestOptions) => Promise<ProfileDTO>;
+        retrieve: (name: string, options?: RequestOptions) => Promise<ProfileDTO>;
+        /** The profiles an app may start runs with (app listener only): its own, and those of other apps its grant covers. `default` marks its default profile. */
+        list: (options?: RequestOptions) => Promise<{
+            profiles: AppProfile[];
+        }>;
+    };
+    /** Daemon status and health. */
+    readonly system: {
+        status: (options?: RequestOptions) => Promise<StatusDTO>;
+        health: (options?: RequestOptions) => Promise<HealthDTO>;
+    };
+    /** Whether this client can reach a daemon that can run a model. */
+    readonly auth: {
+        status: (params?: AuthStatusParams, options?: RequestOptions) => Promise<AuthStatus>;
+    };
+    /** Read, write, and list absolute host paths. */
+    readonly files: Files;
+    readonly runs: Runs;
+    /** Uploads to runtime storage, for files a run prompt or message names (app listener only). */
+    readonly uploads: Uploads;
+    /** Signed links to files a run received as attachments (app listener only). */
+    readonly attachments: Attachments;
+    /** Public share links to files (app listener only). */
+    readonly shares: Shares;
+    /** Questions agents in runs ask the user (app listener only). */
+    readonly questions: 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. */
+    readonly memory: Memory;
+    /** Scope-filtered provider tools and daemon-mediated calls. */
+    readonly providers: 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`. */
+    readonly grant: {
+        get: (options?: RequestOptions & {
+            wait?: number;
+            since?: string;
+        }) => Promise<import('@north-light/api').GrantGetDTO>;
+    };
+    readonly health: {
+        get: (options?: RequestOptions) => Promise<{
+            status: 'ok';
+            api_version: string;
+        }>;
+    };
+    /** The caller's month-to-date spend (`usage.get`): user-paid model and provider usage, app-paid usage, the grant's
+     *  `spend_cap`, and `reset_at`. Once user-paid spend reaches `spend_cap`, user-paid model calls answer `cap_exhausted`
+     *  (a `RateLimitError`, status 402, `userAction: 'raise_cap'`) until `reset_at`. `month` is `YYYY-MM` (UTC; default: current). */
+    readonly usage: {
+        get: (params?: {
+            month?: string;
+        }, options?: RequestOptions) => Promise<import('@north-light/api').SpendUsageDTO>;
+    };
+    private readonly eventFetch;
+    private readonly bearerToken;
+    private connectionToken;
+    private readonly tokenSource;
+    private readonly onUnauthorized;
+    private readonly client;
+    private readonly timeout;
+    private readonly baseURL;
+    private readonly socketPath;
+    constructor(options?: CrouterOptions);
+    /** Establish NDJSON through the JSON client's cold-socket/retry transport; leave the live body unread. */
+    private openCustomDeliveries;
+    private openRunEvents;
+    /** `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. */
+    private openDownload;
+    /** Sends one request to any daemon route, for routes the namespaces above do not wrap. */
+    request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    private authStatus;
+    private stream;
+    private events;
+    /** Opening a stream under the call's deadline: the open (token hook included) is abandoned and aborted at
+     *  `deadlineAt`. Once open, a stream has no deadline: it lives until it ends or `signal` aborts. */
+    private openWithin;
+    private outcome;
+    private waitForOutcome;
+    private createAndWait;
+    private parse;
+    /** Runs `operation` with the connection token, refreshing it once after a 401. `options` carries the call's one
+     *  deadline (resolved by `deadline`): the token fetch, the refresh and every attempt share it, and `operation`
+     *  receives the options with the deadline resolved. */
+    private call;
+}
+export {};