@north-light/sdk 0.0.0 → 0.3.415

package/dist/testing/wire.d.ts

@@ -0,0 +1,62 @@
+import type { GrantGetDTO } from '@north-light/api';
+/** An error the fake answers with: status plus the contract-2 envelope fields. */
+export interface FakeError {
+    readonly kind: 'fake-error';
+    status: number;
+    code: string;
+    message: string;
+    origin: string;
+    retryable: boolean;
+    details?: unknown;
+    param?: string;
+    scope?: string;
+}
+/** Build a `FakeError`. `retryable` defaults to the daemon's rule: true exactly for a 503. */
+export declare function fakeError(input: {
+    status: number;
+    code: string;
+    message?: string;
+    origin?: string;
+    retryable?: boolean;
+    details?: unknown;
+    param?: string;
+    scope?: string;
+}): FakeError;
+export declare function isFakeError(value: unknown): value is FakeError;
+/** Thrown inside the fake's handlers; the router answers it as an envelope. */
+export declare class FakeRefused extends Error {
+    readonly error: FakeError;
+    constructor(error: FakeError);
+}
+export declare const refuse: (status: number, code: string, message: string, extra?: {
+    param?: string;
+    details?: unknown;
+    scope?: string;
+    origin?: string;
+    retryable?: boolean;
+}) => FakeRefused;
+export declare const invalid: (message: string, param?: string) => FakeRefused;
+export declare const notFound: (message?: string) => FakeRefused;
+/** The envelope body the app listener writes (`app-listener.ts` `envelope`). */
+export declare function envelopeBody(error: FakeError, runId?: string): {
+    error: Record<string, unknown>;
+};
+export declare function jsonAnswer(body: unknown, status: number, headers: Record<string, string>): Response;
+/** Keys sorted, `undefined` dropped, arrays in order: the daemon's `canonicalJson`. */
+export declare function canonicalJson(value: unknown): string;
+/** `grant.get` `version`: changes exactly when rev, resolved_scopes, spend_cap, payer or dependencies does. */
+export declare function grantVersion(grant: Pick<GrantGetDTO, 'rev' | 'resolved_scopes' | 'spend_cap' | 'payer' | 'dependencies'>): string;
+export declare const sha256Hex: (text: string) => string;
+/** The daemon's `requestedScopes`: the run's scope list, or null when the request names none. */
+export declare function requestedScopes(held: readonly string[], value: unknown, grantee: string): string[] | null;
+/** `wait` query: absent → 0; else an integer 1–25. */
+export declare function waitSeconds(query: URLSearchParams): number;
+/** An integer query parameter in [min, max], default when absent. */
+export declare function integerParam(raw: string | null, param: string, min: number, max: number, fallback: number): number;
+export declare function objectBody(body: unknown): Record<string, unknown>;
+/** Unsigned JWT the SDK decodes (`decodeJwt`), as a directory access token. */
+export declare function unsignedJwt(claims: Record<string, unknown>): string;
+export declare function decodeUnsigned(token: string): Record<string, unknown> | null;
+/** Resolve after `ms`, or reject when `signal` aborts. */
+export declare function abortable<T>(signal: AbortSignal | null | undefined, register: (resolve: (value: T) => void) => () => void): Promise<T>;
+export declare const nowIso: (ms?: number) => string;

package/dist/testing/wire.js

@@ -0,0 +1,148 @@
+// Wire helpers shared by the fake directory and runtime: the error envelope, JSON answers carrying the runtime
+// version, the daemon's hashes, and request parsing.
+import { createHash } from 'node:crypto';
+import { errorCodes } from '@north-light/api';
+import { covers, parseScope } from '@north-light/identity';
+/** Build a `FakeError`. `retryable` defaults to the daemon's rule: true exactly for a 503. */
+export function fakeError(input) {
+    return {
+        kind: 'fake-error', status: input.status, code: input.code, message: input.message ?? input.code,
+        origin: input.origin ?? 'runtime', retryable: input.retryable ?? input.status === 503,
+        ...(input.details === undefined ? {} : { details: input.details }),
+        ...(input.param === undefined ? {} : { param: input.param }),
+        ...(input.scope === undefined ? {} : { scope: input.scope }),
+    };
+}
+export function isFakeError(value) {
+    return typeof value === 'object' && value !== null && value.kind === 'fake-error';
+}
+/** Thrown inside the fake's handlers; the router answers it as an envelope. */
+export class FakeRefused extends Error {
+    error;
+    constructor(error) {
+        super(error.message);
+        this.error = error;
+    }
+}
+export const refuse = (status, code, message, extra = {}) => new FakeRefused(fakeError({ status, code, message, ...extra }));
+export const invalid = (message, param) => refuse(400, 'invalid_request', message, param === undefined ? {} : { param });
+export const notFound = (message = 'run not found') => refuse(404, 'not_found', message);
+const STREAM_TYPES = new Set(['stream_gap', 'provider_error', 'runtime_version_unsupported']);
+function typeOf(code) {
+    const row = errorCodes[code];
+    if (row)
+        return row.type;
+    return STREAM_TYPES.has(code) ? 'invalid_request_error' : 'server_error';
+}
+let requestSerial = 0;
+/** The envelope body the app listener writes (`app-listener.ts` `envelope`). */
+export function envelopeBody(error, runId) {
+    return {
+        error: {
+            code: error.code, message: error.message,
+            ...(error.details === undefined ? {} : { details: error.details }),
+            type: typeOf(error.code),
+            ...(error.param ? { param: error.param } : {}),
+            origin: error.origin, retryable: error.retryable,
+            request_id: `req-fake-${++requestSerial}`,
+            ...(runId ? { run_id: runId } : {}),
+            ...(error.scope ? { scope: error.scope } : {}),
+            ...(error.code === 'unauthorized' ? { user_action: 'reconnect' } : {}),
+        },
+    };
+}
+export function jsonAnswer(body, status, headers) {
+    return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', ...headers } });
+}
+/** Keys sorted, `undefined` dropped, arrays in order: the daemon's `canonicalJson`. */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalJson(item === undefined ? null : item)).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value).filter(([, v]) => v !== undefined).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/** `grant.get` `version`: changes exactly when rev, resolved_scopes, spend_cap, payer or dependencies does. */
+export function grantVersion(grant) {
+    const input = { rev: grant.rev, resolved_scopes: grant.resolved_scopes, spend_cap: grant.spend_cap, payer: grant.payer, dependencies: grant.dependencies ?? {} };
+    return createHash('sha256').update(canonicalJson(input)).digest('base64url').slice(0, 22);
+}
+export const sha256Hex = (text) => createHash('sha256').update(text).digest('hex');
+/** The daemon's `requestedScopes`: the run's scope list, or null when the request names none. */
+export function requestedScopes(held, value, grantee) {
+    const missing = (scope) => refuse(403, 'scope_missing', `missing scope ${scope}`, { scope });
+    if (value === undefined) {
+        if (!held.some((scope) => covers(scope, 'crtr:llm')))
+            throw missing('crtr:llm');
+        return null;
+    }
+    if (!Array.isArray(value) || value.some((scope) => typeof scope !== 'string'))
+        throw invalid('scopes must be a list of scope strings', 'scopes');
+    for (const scope of value) {
+        try {
+            parseScope(scope);
+        }
+        catch {
+            throw invalid(`invalid scope ${scope}`, 'scopes');
+        }
+        if (/^crtr:files:(?:read|rw):app:/.test(scope) && scope.split(':')[4] === grantee.slice(4))
+            throw invalid(`own-app files cannot narrow a run: ${scope}`, 'scopes');
+        const ownSpace = /^crtr:memory:(?:read|rw):app:/.test(scope) && scope.split(':')[4] === grantee.slice(4);
+        if (!ownSpace && !held.some((h) => covers(h, scope)))
+            throw missing(scope);
+    }
+    if (!value.includes('crtr:llm'))
+        throw missing('crtr:llm');
+    return value;
+}
+/** `wait` query: absent → 0; else an integer 1–25. */
+export function waitSeconds(query) {
+    const raw = query.get('wait');
+    if (raw === null || raw === '')
+        return 0;
+    if (!/^(0|[1-9]\d?)$/.test(raw) || Number(raw) < 1 || Number(raw) > 25)
+        throw invalid('wait must be an integer from 1 through 25', 'wait');
+    return Number(raw);
+}
+/** An integer query parameter in [min, max], default when absent. */
+export function integerParam(raw, param, min, max, fallback) {
+    if (raw === null)
+        return fallback;
+    if (!/^(0|[1-9]\d*)$/.test(raw) || Number(raw) < min || Number(raw) > max)
+        throw invalid(`invalid ${param}`, param);
+    return Number(raw);
+}
+export function objectBody(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        throw invalid('a JSON object is required');
+    return body;
+}
+/** Unsigned JWT the SDK decodes (`decodeJwt`), as a directory access token. */
+export function unsignedJwt(claims) {
+    const part = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
+    return `${part({ alg: 'none', typ: 'at+jwt' })}.${part(claims)}.fake`;
+}
+export function decodeUnsigned(token) {
+    try {
+        return JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString());
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve after `ms`, or reject when `signal` aborts. */
+export function abortable(signal, register) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new DOMException('aborted', 'AbortError'));
+            return;
+        }
+        let unregister = () => { };
+        const onAbort = () => { unregister(); reject(signal.reason ?? new DOMException('aborted', 'AbortError')); };
+        unregister = register((value) => { signal?.removeEventListener('abort', onAbort); unregister(); resolve(value); });
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+export const nowIso = (ms = Date.now()) => new Date(ms).toISOString();

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+import type { CloseRequest, CreateNodeRequest, EnsureProfileRequest, NodeEventsQuery, ModelAuthReadinessDTO, ModelAuthReadinessQuery, NodeOutcomeDTO, SendMessageRequest, StartupPhaseDTO } from '@north-light/api';
+/** A JSON Schema object. The daemon validates structured results against it. */
+export type JsonSchema = Record<string, unknown>;
+/**
+ * A structured-result schema: a JSON string, a JSON Schema object, or anything exposing
+ * `toJSONSchema()` — which a Zod v4 object does.
+ */
+export type OutputSchema = string | JsonSchema | {
+    toJSONSchema(): JsonSchema;
+};
+/** The daemon's create request, widening `output_schema` to accept schema objects. */
+export type NodeCreateParams = Omit<CreateNodeRequest, 'output_schema'> & {
+    output_schema?: OutputSchema;
+};
+/** The final argument of every request-capable method. */
+export interface RequestOptions {
+    /** Merged into this request's headers. */
+    headers?: Record<string, string>;
+    /** Aborts the request, rejecting with `APIUserAbortError`. */
+    signal?: AbortSignal;
+    /** Wall clock in milliseconds for this request, overriding the client's default. */
+    timeout?: number;
+    /** Transient-failure retries for this request. Never applied to `POST` or `PATCH`. */
+    maxRetries?: number;
+    /** One overall deadline for this call, in milliseconds from now: it covers every attempt, every retry wait
+     *  (including a server's `Retry-After`) and the response body. `timeout` still bounds each attempt but never
+     *  past the deadline. When the deadline passes, or a retry wait would pass it, the call rejects with
+     *  `DeadlineExceededError` at once instead of sleeping on. */
+    budgetMs?: number;
+    /** The same deadline as an absolute instant (epoch milliseconds), for passing one deadline to several calls.
+     *  With `budgetMs` too, the earlier wins. */
+    deadlineAt?: number;
+}
+/** Options for one outcome poll. */
+export interface NodeOutcomeOptions extends RequestOptions {
+    /** One daemon long poll in seconds, from 0 through 25. */
+    wait?: number;
+}
+/** Options for an existing node's event stream. Streams have no wall-clock timeout. */
+export interface NodeEventsOptions extends Omit<RequestOptions, 'timeout'>, NodeEventsQuery {
+}
+/** A message to a running node. The sender is filled in by the client. */
+export type MessageParams = Omit<SendMessageRequest, 'from'>;
+/** What `nodes.cancel` closes, including whether to cascade to descendants. */
+export type CancelParams = CloseRequest;
+/** The outcome of a `parse` run, with the structured result typed from the schema. */
+export type ParsedOutcome<T> = (Extract<NodeOutcomeDTO, {
+    kind: 'result';
+}> & {
+    output_parsed: T;
+}) | (Exclude<NodeOutcomeDTO, {
+    kind: 'result';
+}> & {
+    output_parsed: null;
+});
+/** The value type an `OutputSchema` describes, inferred from a Zod or Standard Schema object. */
+export type SchemaOutput<T> = T extends {
+    _output: infer Output;
+} ? Output : T extends {
+    '~standard': {
+        types?: {
+            output: infer Output;
+        };
+    };
+} ? Output : unknown;
+/** The profile settings `profiles.ensure` creates or updates. */
+export type EnsureProfileParams = EnsureProfileRequest;
+/** The launch-selecting fields used to resolve the provider readiness check. */
+export type AuthStatusParams = ModelAuthReadinessQuery;
+/** Whether this client can reach a daemon that can run a model, and what to do if it cannot. */
+export interface AuthStatus {
+    /** The client holds a transport and the daemon answered. */
+    connected: boolean;
+    /** Present only when connected. */
+    daemon: {
+        base_url: string;
+        runtime_version: string;
+        api_version: string;
+        startup_phase: StartupPhaseDTO;
+        tcp: string | null;
+    } | null;
+    /** Present only when connected. */
+    model: ModelAuthReadinessDTO | null;
+    /** The one thing the application should do next, or null when ready. */
+    next_step: 'connect' | 'login' | null;
+    /** Literal text the application shows the user for `next_step`. */
+    instructions: string | null;
+}

package/dist/types.js

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

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** This SDK's release version. It is also the oldest runtime the SDK accepts: one release is one version set. */
+export declare const SDK_VERSION = "0.3.415";

package/dist/version.js

@@ -0,0 +1,3 @@
+// Written by scripts/release-version.mjs on every release; do not edit by hand.
+/** This SDK's release version. It is also the oldest runtime the SDK accepts: one release is one version set. */
+export const SDK_VERSION = '0.3.415';

package/package.json

@@ -1,8 +1,63 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.0.0",
-  "description": "Placeholder. The release of this package is published from Northlight-Systems/crouter by CI.",
-  "license": "UNLICENSED",
-  "repository": { "type": "git", "url": "git+https://github.com/Northlight-Systems/crouter.git" },
-  "publishConfig": { "access": "public" }
+  "version": "0.3.415",
+  "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "crouter-sdk": "./dist/keygen-cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./errors": {
+      "types": "./dist/error-codes.d.ts",
+      "import": "./dist/error-codes.js"
+    },
+    "./stores/postgres": {
+      "types": "./dist/stores/postgres.d.ts",
+      "import": "./dist/stores/postgres.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./testing/conformance": {
+      "types": "./dist/testing/conformance/index.d.ts",
+      "import": "./dist/testing/conformance/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod 755 dist/keygen-cli.js"
+  },
+  "dependencies": {
+    "@north-light/api": "0.3.415",
+    "@north-light/identity": "0.3.415",
+    "jose": "^6.2.1"
+  },
+  "peerDependencies": {
+    "pg": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Northlight-Systems/crouter.git",
+    "directory": "packages/crouter-sdk"
+  },
+  "license": "UNLICENSED"
 }