@north-light/sdk 0.3.499 → 0.3.501

package/dist/index.d.ts

@@ -28,6 +28,8 @@ export { parsePrivateJwk, privateKeyFromFile } from './oauth/keygen.js';
 export type { AuthorizeNonce, Connection, ConnectionStore, Identity, OAuth2Options } from './oauth/index.js';
 export type { IdTokenClaims } from '@north-light/identity';
 export { cursorFromRequest, forwardRunEvents } from './resources/forward.js';
+export { INFERENCE_SCOPE, inferenceEndpoint } from './resources/inference-endpoint.js';
+export type { InferenceEndpointOptions, InferenceProvider, InferenceRung, InferenceUsage } from './resources/inference-endpoint.js';
 export { RUN_NOTICE_SCOPE, RunNoticeError, verifyRunNotice } from './resources/run-notice.js';
 export type { RunNotice, VerifyRunNoticeOptions } from './resources/run-notice.js';
 export type { NodeStreamEvent, NodeStreamEventListener, NodeStreamEventType } from './resources/node-stream.js';

package/dist/index.js

@@ -10,6 +10,7 @@ export { GrantWatcher } from './resources/grant-watcher.js';
 export { generateKeyPair } from './oauth/keygen.js';
 export { parsePrivateJwk, privateKeyFromFile } from './oauth/keygen.js';
 export { cursorFromRequest, forwardRunEvents } from './resources/forward.js';
+export { INFERENCE_SCOPE, inferenceEndpoint } from './resources/inference-endpoint.js';
 export { RUN_NOTICE_SCOPE, RunNoticeError, verifyRunNotice } from './resources/run-notice.js';
 export { describeToolDefault, followActivity } from './resources/activity.js';
 export { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, DeadlineExceededError, InternalServerError, NoHostedRuntimeError, NotGrantedError, NotFoundError, PermissionDeniedError, RateLimitError, RuntimeVersionError, UnprocessableEntityError, mapError, } from './errors.js';

package/dist/resources/inference-endpoint.d.ts

@@ -0,0 +1,50 @@
+/** The scope an inference token carries. */
+export declare const INFERENCE_SCOPE = "crtr:llm";
+export type InferenceRung = 'ultra' | 'strong' | 'medium' | 'light';
+export interface InferenceProvider {
+    /** The vendor's own API base URL, for example `https://api.anthropic.com`. */
+    baseURL: string;
+    /** The app's key for that vendor. It replaces the token on the way upstream and is never logged or returned. */
+    apiKey: string;
+    /** The header the vendor's API carries its key in: `x-api-key` or `Authorization: Bearer`. Defaults to `x-api-key` for the provider id `anthropic` and to `bearer` for every other id. */
+    keyHeader?: 'x-api-key' | 'bearer';
+}
+export interface InferenceUsage {
+    /** The person the call ran for, `user:<id>` (the token's `sub`). */
+    sub: string;
+    /** The provider id, the first path segment after the mount. */
+    provider: string;
+    /** The model the request named. */
+    model: string;
+    /** The vendor's status code (always 2xx; a refused or failed request does not report). */
+    status: number;
+    /** The vendor's own `usage` object, merged across stream events; `undefined` when the answer carried none. */
+    usage: Record<string, unknown> | undefined;
+}
+export interface InferenceEndpointOptions {
+    /** The directory issuer. */
+    issuer: string;
+    /** The endpoint base URL the app registered, for example `https://context.northlight.ai/v1/inference`. The token's `aud` must equal it exactly; its path is where the handler is mounted. */
+    baseURL: string;
+    /** The app's own principal, `app:<id>`; the token's grantee must be it. */
+    app: string;
+    /** Upstream base URL and key per provider id (a model catalog provider id such as `anthropic`). */
+    providers: Record<string, InferenceProvider>;
+    /** Strength to model: the catalog model ids (`<provider id>/<model>`) the endpoint serves. A request naming any other model is refused. */
+    rungs: Partial<Record<InferenceRung, string>>;
+    /** Called once per completed request, after its answer has been streamed to the caller. A throw is written to `console.error`. */
+    onUsage?: (usage: InferenceUsage) => void | Promise<void>;
+    /** The `fetch` used for the upstream call and the directory's keys (default: the global `fetch`). */
+    fetch?: typeof fetch;
+}
+/**
+ * The server side of an app-paid app: a Fetch handler that serves a person's runtime the vendors' own APIs with the
+ * app's keys. Mount it at the path of `baseURL`. A request to `<baseURL>/<provider id>/<vendor path>` carries a
+ * directory token in the header that vendor's API carries its key in; the handler verifies it (issuer, `aud` =
+ * `baseURL`, expiry, scope `crtr:llm`, the app itself as grantee) and answers 401, sending nothing upstream, when it
+ * does not hold. A provider id the app did not configure is 404. A request whose JSON body names a model outside
+ * `rungs` is refused. Otherwise the request goes upstream unchanged with the app's key in place of the token, and the
+ * vendor's answer comes back unchanged, status codes and `retry-after` included. The handler keeps no state, counts
+ * no spend and applies no limit.
+ */
+export declare function inferenceEndpoint(options: InferenceEndpointOptions): (request: Request) => Promise<Response>;

package/dist/resources/inference-endpoint.js

@@ -0,0 +1,149 @@
+import { JwksCache, verifyCallToken } from '@north-light/identity';
+/** The scope an inference token carries. */
+export const INFERENCE_SCOPE = 'crtr:llm';
+const jwksUrl = (issuer) => `${issuer.replace(/\/+$/, '')}/.well-known/jwks.json`;
+const STRIPPED_REQUEST_HEADERS = ['host', 'connection', 'keep-alive', 'transfer-encoding', 'te', 'upgrade', 'content-length', 'authorization', 'x-api-key', 'cookie', 'proxy-authorization'];
+// The body is decoded and re-streamed, so these describe the upstream wire form, not what we send.
+const STRIPPED_RESPONSE_HEADERS = ['connection', 'keep-alive', 'transfer-encoding', 'content-encoding', 'content-length'];
+function refuse(status, code, message) {
+    return new Response(JSON.stringify({ type: 'error', error: { type: code, code, message } }), { status, headers: { 'content-type': 'application/json' } });
+}
+function keyHeaderOf(id, provider) {
+    return provider?.keyHeader ?? (id === 'anthropic' ? 'x-api-key' : 'bearer');
+}
+function tokenOf(request, header) {
+    if (header === 'x-api-key')
+        return request.headers.get('x-api-key') ?? undefined;
+    return /^Bearer ([^\s]+)$/.exec(request.headers.get('authorization') ?? '')?.[1];
+}
+/** The vendor's `usage` of a completed answer: the body's for JSON, the events' merged for a server-sent stream. */
+async function usageOf(body, contentType) {
+    const object = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    if (contentType.includes('text/event-stream')) {
+        let merged;
+        let pending = '';
+        const take = (line) => {
+            if (!line.startsWith('data:'))
+                return;
+            let event;
+            try {
+                event = JSON.parse(line.slice(5).trim());
+            }
+            catch {
+                return;
+            }
+            const found = object(object(event)?.usage) ?? object(object(object(event)?.message)?.usage);
+            if (found !== undefined)
+                merged = { ...merged, ...found };
+        };
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            pending += decoder.decode(value, { stream: true });
+            const lines = pending.split('\n');
+            pending = lines.pop();
+            lines.forEach(take);
+        }
+        take(pending);
+        return merged;
+    }
+    let text = '';
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        text += decoder.decode(value, { stream: true });
+    }
+    if (!contentType.includes('json'))
+        return undefined;
+    try {
+        return object(object(JSON.parse(text))?.usage);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The server side of an app-paid app: a Fetch handler that serves a person's runtime the vendors' own APIs with the
+ * app's keys. Mount it at the path of `baseURL`. A request to `<baseURL>/<provider id>/<vendor path>` carries a
+ * directory token in the header that vendor's API carries its key in; the handler verifies it (issuer, `aud` =
+ * `baseURL`, expiry, scope `crtr:llm`, the app itself as grantee) and answers 401, sending nothing upstream, when it
+ * does not hold. A provider id the app did not configure is 404. A request whose JSON body names a model outside
+ * `rungs` is refused. Otherwise the request goes upstream unchanged with the app's key in place of the token, and the
+ * vendor's answer comes back unchanged, status codes and `retry-after` included. The handler keeps no state, counts
+ * no spend and applies no limit.
+ */
+export function inferenceEndpoint(options) {
+    const upstreamFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    const mount = new URL(options.baseURL).pathname.replace(/\/+$/, '');
+    const served = new Set(Object.values(options.rungs));
+    if (served.size === 0)
+        throw new Error('inferenceEndpoint: rungs must name at least one model');
+    for (const model of served) {
+        const provider = model.split('/')[0];
+        if (!model.includes('/') || options.providers[provider] === undefined)
+            throw new Error(`inferenceEndpoint: rung model ${model} must be <provider id>/<model> for a configured provider`);
+    }
+    const jwks = new JwksCache(options.issuer, (input, init) => upstreamFetch(input, init), jwksUrl(options.issuer));
+    return async (request) => {
+        const url = new URL(request.url);
+        if (!url.pathname.startsWith(`${mount}/`))
+            return refuse(404, 'not_found', 'No such path.');
+        const [providerId, ...restSegments] = url.pathname.slice(mount.length + 1).split('/');
+        const provider = Object.hasOwn(options.providers, providerId) ? options.providers[providerId] : undefined;
+        const token = tokenOf(request, keyHeaderOf(providerId, provider));
+        if (token === undefined)
+            return refuse(401, 'unauthorized', 'The request carries no directory token.');
+        let verified;
+        try {
+            verified = await verifyCallToken({ token, jwks, issuer: options.issuer, audience: options.baseURL });
+        }
+        catch {
+            return refuse(401, 'unauthorized', 'The token is not a valid directory token for this endpoint.');
+        }
+        if (!(verified.scope ?? '').split(' ').includes(INFERENCE_SCOPE) || !verified.chain.some((link) => link.sub === options.app)) {
+            return refuse(401, 'unauthorized', 'The token was not minted for this app to serve inference.');
+        }
+        if (provider === undefined)
+            return refuse(404, 'not_found', `This endpoint serves no provider ${providerId}.`);
+        const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
+        let model;
+        try {
+            model = body === undefined ? undefined : JSON.parse(new TextDecoder().decode(body)).model;
+        }
+        catch {
+            model = undefined;
+        }
+        if (typeof model !== 'string')
+            return refuse(400, 'invalid_request', 'The request body must be JSON naming a model.');
+        if (!served.has(`${providerId}/${model}`))
+            return refuse(404, 'model_unavailable', `This endpoint does not serve ${providerId}/${model}.`);
+        const headers = new Headers(request.headers);
+        for (const name of STRIPPED_REQUEST_HEADERS)
+            headers.delete(name);
+        if (keyHeaderOf(providerId, provider) === 'x-api-key')
+            headers.set('x-api-key', provider.apiKey);
+        else
+            headers.set('authorization', `Bearer ${provider.apiKey}`);
+        let upstream;
+        try {
+            upstream = await upstreamFetch(`${provider.baseURL.replace(/\/+$/, '')}/${restSegments.join('/')}${url.search}`, { method: request.method, headers, body, redirect: 'manual', signal: request.signal });
+        }
+        catch {
+            return refuse(502, 'upstream_unreachable', `${providerId} could not be reached.`);
+        }
+        const responseHeaders = new Headers(upstream.headers);
+        for (const name of STRIPPED_RESPONSE_HEADERS)
+            responseHeaders.delete(name);
+        if (upstream.body === null || options.onUsage === undefined || !upstream.ok) {
+            return new Response(upstream.body, { status: upstream.status, statusText: upstream.statusText, headers: responseHeaders });
+        }
+        const [toCaller, toUsage] = upstream.body.tee();
+        const report = options.onUsage;
+        void usageOf(toUsage, upstream.headers.get('content-type') ?? '').then((usage) => report({ sub: verified.sub, provider: providerId, model, status: upstream.status, usage }), () => undefined).catch((error) => { console.error('inferenceEndpoint onUsage failed:', error); });
+        return new Response(toCaller, { status: upstream.status, statusText: upstream.statusText, headers: responseHeaders });
+    };
+}

package/dist/skill/northlight/SKILL.md

@@ -2,7 +2,7 @@
 name: northlight
 description: "Use when building, debugging or shipping an app that signs people in with Northlight, starts runs on their Northlight runtime, or calls Northlight providers (sms, search, integrations, context, device) with @north-light/sdk."
 metadata:
-  sdk-version: "0.3.499"
+  sdk-version: "0.3.501"
 ---
 
 # Building a Northlight app
@@ -11,7 +11,7 @@ An app on Northlight signs people in with their Northlight account, then starts
 
 ## First: check this skill matches the SDK
 
-This skill is for SDK version `0.3.499`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. That command needs no account and no crtr. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
+This skill is for SDK version `0.3.501`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. That command needs no account and no crtr. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
 
 ## Where things run
 

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export declare const SDK_VERSION = "0.3.499";
+export declare const SDK_VERSION = "0.3.501";
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the
  *  contract level existed (which only knows this header) refuses this SDK, while every later runtime accepts it. */
 export declare const LEGACY_FLOOR = "0.3.423";

package/dist/version.js

@@ -1,6 +1,6 @@
 // SDK_VERSION is written by scripts/release-version.mjs on every release; do not edit by hand.
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export const SDK_VERSION = '0.3.499';
+export const SDK_VERSION = '0.3.501';
 // LEGACY_FLOOR is written once by `scripts/contract.mjs release`, at the first release that carries the contract level
 // (the `0.0.0` placeholder is replaced there and never again); do not edit by hand.
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.3.499",
-  "crouterContract": "1.15",
+  "version": "0.3.501",
+  "crouterContract": "1.16",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,8 +44,8 @@
     "prepublishOnly": "node -e \"if (process.env.npm_config_tag !== 'next') { console.error('@north-light/sdk publishes only with --tag next; scripts/promote-sdk.mjs is the only mover of latest.'); process.exit(1); }\""
   },
   "dependencies": {
-    "@north-light/api": "0.3.499",
-    "@north-light/identity": "0.3.499",
+    "@north-light/api": "0.3.501",
+    "@north-light/identity": "0.3.501",
     "jose": "^6.2.1"
   },
   "peerDependencies": {