@north-light/sdk 0.3.550 → 0.3.552

package/dist/client.d.ts

@@ -3,6 +3,8 @@ import { Bash } from './resources/bash.js';
 import { Canvas } from './resources/canvas.js';
 import { Crons } from './resources/crons.js';
 import { Docs } from './resources/docs.js';
+import { Charges } from './resources/charges.js';
+import { SpendLimits } from './resources/spend-limits.js';
 import { Relations } from './resources/relations.js';
 import { Schemas } from './resources/schemas.js';
 import { CustomObjects } from './resources/custom-objects.js';
@@ -61,13 +63,17 @@ export interface CrouterOptions {
     defaultHeaders?: Record<string, string>;
     /** Merged after `defaultHeaders`; the `Authorization` generated from `token` still wins. */
     headers?: Record<string, string>;
+    /** Sent as the `Crtr-Caused-By` header on every request of this client: `message:<id>`, `request:<id>` or `cron_run:<id>`.
+     *  The runtime records it on the charges and runs the request causes. A provider handler passes the inbound `request:<id>`. The runtime
+     *  ignores any other form. `RunStartParams.causedBy` overrides it for one `runs.start`. */
+    causedBy?: 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 namespaces of `Crouter` that only the owner's own daemon serves. A person's app listener answers them `404 unknown operation`. */
-export type OwnerOnly = 'nodes' | 'bash' | 'canvas' | 'crons' | 'structuredRequests' | 'customObjects' | 'human' | 'models' | 'system' | 'auth';
+export type OwnerOnly = 'spendLimits' | 'nodes' | 'bash' | 'canvas' | 'crons' | 'structuredRequests' | 'customObjects' | 'human' | 'models' | 'system' | 'auth';
 /** What an app reaches on a person's runtime (the app listener): `Crouter` without the owner-daemon namespaces, `files.download`
  *  only, `profiles.list` only, `customObjects` register/publish/unregister and `canvas` watch/unwatch. `Crouter` is assignable to it, so a function that takes `AppClient` takes either. */
 export type AppClient = Omit<Crouter, OwnerOnly | 'files' | 'profiles'> & {
@@ -140,6 +146,10 @@ export declare class Crouter {
     readonly schemas: Schemas;
     /** Write, replace and list the relation facts of the app's own schema (app listener only). */
     readonly relations: Relations;
+    /** The runtime's money ledger: month charge rows and the rows under a reference (`GET /v1/charges`). */
+    readonly charges: Charges;
+    /** Dollar limits (`GET`/`PUT`/`DELETE /v1/spend-limits`); the person's own client only. */
+    readonly spendLimits: SpendLimits;
     /** 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
@@ -157,9 +167,10 @@ export declare class Crouter {
             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). */
+    /** @deprecated Use `charges.list`. The caller's month-to-date spend (`usage.get`): user-paid model and priced tool usage, app-paid usage,
+     *  the grant's `spend_cap`, and `reset_at`. The cap counts priced tool calls as well as model calls. Once user-paid spend reaches
+     *  `spend_cap`, calls billed to the user answer `cap_exhausted` (a `RateLimitError`, status 402, `userAction: 'raise_cap'`,
+     *  `error.capExhausted` holds the limit) until `reset_at`. `month` is `YYYY-MM` (UTC; default: current). */
     readonly usage: {
         get: (params?: {
             month?: string;

package/dist/client.js

@@ -4,6 +4,8 @@ import { Bash } from './resources/bash.js';
 import { Canvas } from './resources/canvas.js';
 import { Crons } from './resources/crons.js';
 import { Docs } from './resources/docs.js';
+import { Charges } from './resources/charges.js';
+import { SpendLimits } from './resources/spend-limits.js';
 import { Relations } from './resources/relations.js';
 import { Schemas } from './resources/schemas.js';
 import { CustomObjects } from './resources/custom-objects.js';
@@ -16,7 +18,7 @@ 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 { CAUSED_BY_HEADER, Runs } from './resources/runs.js';
 import { Shares } from './resources/shares.js';
 import { StructuredRequests } from './resources/structured-requests.js';
 import { Memory } from './resources/memory.js';
@@ -75,6 +77,10 @@ export class Crouter {
     schemas;
     /** Write, replace and list the relation facts of the app's own schema (app listener only). */
     relations;
+    /** The runtime's money ledger: month charge rows and the rows under a reference (`GET /v1/charges`). */
+    charges;
+    /** Dollar limits (`GET`/`PUT`/`DELETE /v1/spend-limits`); the person's own client only. */
+    spendLimits;
     /** 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
@@ -82,9 +88,10 @@ export class Crouter {
      *  `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). */
+    /** @deprecated Use `charges.list`. The caller's month-to-date spend (`usage.get`): user-paid model and priced tool usage, app-paid usage,
+     *  the grant's `spend_cap`, and `reset_at`. The cap counts priced tool calls as well as model calls. Once user-paid spend reaches
+     *  `spend_cap`, calls billed to the user answer `cap_exhausted` (a `RateLimitError`, status 402, `userAction: 'raise_cap'`,
+     *  `error.capExhausted` holds the limit) until `reset_at`. `month` is `YYYY-MM` (UTC; default: current). */
     usage;
     eventFetch;
     bearerToken;
@@ -118,6 +125,7 @@ export class Crouter {
         const headers = {
             ...options.defaultHeaders,
             ...options.headers,
+            ...(options.causedBy === undefined ? {} : { [CAUSED_BY_HEADER]: options.causedBy }),
             ...(token === undefined ? {} : { Authorization: `Bearer ${token}` }),
         };
         const baseFetch = requireCurrentRuntime(options.fetch ?? (baseURL === undefined && isNodeRuntime() ? localSocketFetch(options.socketPath ?? env['CRTR_SOCKET']) : undefined));
@@ -235,6 +243,8 @@ export class Crouter {
         this.docs = new Docs(request);
         this.schemas = new Schemas(request);
         this.relations = new Relations(request);
+        this.charges = new Charges(request);
+        this.spendLimits = new SpendLimits(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 = {}) => {

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import { APIError } from '@north-light/api';
+import { APIError, type CapExhaustedDetails } from '@north-light/api';
 import type { SdkErrorCode } from './error-codes.js';
 export { APIError };
 /** An SDK configuration or protocol error, raised by the SDK itself. Its `code` is an `SdkErrorCode`. */
@@ -50,8 +50,11 @@ export declare class ConflictError extends APIError {
 /** The request was well-formed but unusable, or too large: HTTP 413 and 422. */
 export declare class UnprocessableEntityError extends APIError {
 }
-/** Too many requests: HTTP 429. */
+/** Too many requests (HTTP 429) or a refused spend (HTTP 402 `cap_exhausted`). */
 export declare class RateLimitError extends APIError {
+    /** For `cap_exhausted`: the limit that refused the call, the dollars counted against it, `reset_at`, and what the person can do
+     *  (`raise_cap` or `clear_limit`; none for an operator limit). `null` for any other code. */
+    get capExhausted(): CapExhaustedDetails | null;
 }
 /** The daemon failed while handling the request: HTTP 500 and above. */
 export declare class InternalServerError extends APIError {

package/dist/errors.js

@@ -44,8 +44,13 @@ export class ConflictError extends APIError {
 /** The request was well-formed but unusable, or too large: HTTP 413 and 422. */
 export class UnprocessableEntityError extends APIError {
 }
-/** Too many requests: HTTP 429. */
+/** Too many requests (HTTP 429) or a refused spend (HTTP 402 `cap_exhausted`). */
 export class RateLimitError extends APIError {
+    /** For `cap_exhausted`: the limit that refused the call, the dollars counted against it, `reset_at`, and what the person can do
+     *  (`raise_cap` or `clear_limit`; none for an operator limit). `null` for any other code. */
+    get capExhausted() {
+        return this.code === 'cap_exhausted' && this.details !== null && typeof this.details === 'object' ? this.details : null;
+    }
 }
 /** The daemon failed while handling the request: HTTP 500 and above. */
 export class InternalServerError extends APIError {

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export type { Share, ShareCreated, ShareCreateParams } from './resources/shares.
 export type { Doc, DocEditParams, DocListParams, DocWriteParams } from './resources/docs.js';
 export type { Schemas } from './resources/schemas.js';
 export type { Relations } from './resources/relations.js';
+export type { Charges, ChargeListParams } from './resources/charges.js';
+export type { SpendLimits } from './resources/spend-limits.js';
 export type { MemoryDocument, MemoryGetParams, MemoryListItem, MemoryListPage, MemoryListParams } from './resources/memory.js';
 export type { Question, QuestionAnswered, QuestionCanceled, QuestionFields, QuestionKind, QuestionResponses, QuestionSlot, QuestionStatus } from './resources/questions.js';
 export type { ProviderToolEntry } from './resources/providers.js';
@@ -39,6 +41,7 @@ export { describeToolDefault, followActivity } from './resources/activity.js';
 export type { ActivityStep, DescribeTool } 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';
 export type { DeadlineDetails, RuntimeVersionDetails } from './errors.js';
+export type { CapExhaustedDetails } from '@north-light/api';
 export { SDK_VERSION } from './version.js';
 export { setupLink } from './setup-link.js';
 export { sdkErrorCodes } from './error-codes.js';

package/dist/oauth/index.js

@@ -64,7 +64,7 @@ function httpsUrl(value) {
     }
 }
 /** The owner-daemon namespaces a person's runtime does not serve to an app. `canvas` and `customObjects` are narrowed below, not absent. */
-const OWNER_ONLY = ['nodes', 'bash', 'crons', 'structuredRequests', 'human', 'models', 'system', 'auth'];
+const OWNER_ONLY = ['spendLimits', 'nodes', 'bash', 'crons', 'structuredRequests', 'human', 'models', 'system', 'auth'];
 /** The class `ConnectedCrouter` extends: `Crouter`'s implementation under the type of what a person's app listener serves. */
 const AppCrouter = Crouter;
 /** A runtime client on one person's stored connection (`oauth.client(userId)`): an `AppClient` that refreshes its

package/dist/resources/charges.d.ts

@@ -0,0 +1,23 @@
+import { type ChargeListDTO } from '@north-light/api';
+import type { RequestOptions } from '../types.js';
+import { type Request } from './request.js';
+/** `charges.list` input. */
+export interface ChargeListParams {
+    /** UTC `YYYY-MM`; default the current month. With `under`, no default: the chain spans every month unless one is named. */
+    month?: string;
+    /** A reference (`message:<id>`, `request:<id>`, `cron_run:<id>`, `run:<id>`) or a charge id: only the rows under it. */
+    under?: string;
+    /** Page size, 1 to 10,000; default 1,000. */
+    limit?: number;
+    /** The `next` of the previous page. */
+    after?: string;
+}
+/** The runtime's money ledger, read-only. */
+export declare class Charges {
+    private readonly request;
+    constructor(request: Request);
+    /** One page of the month's charge rows on this runtime, or of the rows under a reference, in time order; while `next` is not null,
+     *  call again with it as `after` to read the rest. An app sees only rows it is the grantee of; the person also gets the month's
+     *  totals by payer and funding with the limits (over every row of the month, not the page). Replaces `usage.get`. */
+    list(params?: ChargeListParams, options?: RequestOptions): Promise<ChargeListDTO>;
+}

package/dist/resources/charges.js

@@ -0,0 +1,15 @@
+import { routes } from '@north-light/api';
+import { withQuery } from './request.js';
+/** The runtime's money ledger, read-only. */
+export class Charges {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    /** One page of the month's charge rows on this runtime, or of the rows under a reference, in time order; while `next` is not null,
+     *  call again with it as `after` to read the rest. An app sees only rows it is the grantee of; the person also gets the month's
+     *  totals by payer and funding with the limits (over every row of the month, not the page). Replaces `usage.get`. */
+    list(params = {}, options) {
+        return this.request('GET', withQuery(routes.charges(), params), undefined, options);
+    }
+}

package/dist/resources/runs.d.ts

@@ -3,6 +3,8 @@ import { RunReply, type SentRunMessage } from './run-reply.js';
 import type { Questions, Question, QuestionResponses } from './questions.js';
 import type { JsonSchema, OutputSchema, RequestOptions, SchemaOutput } from '../types.js';
 import type { RunActivityDTO, RunOutcomeDTO, RunTraceDTO, TurnErrorDTO } from '@north-light/api';
+/** The request header that names what caused a call; the runtime reads it on `/v1`. */
+export declare const CAUSED_BY_HEADER = "Crtr-Caused-By";
 export interface RunStartParams {
     prompt: string;
     scopes?: string[];
@@ -25,6 +27,11 @@ export interface RunStartParams {
     /** A first message, stored with the run as a `start_turn: false` message: it always joins the first turn
      *  as context ahead of `prompt`. The result's `message` is what `runs.reply` takes to follow that turn. */
     message?: string;
+    /** What caused this run, sent as the `Crtr-Caused-By` request header (not in the body): `message:<id>`, `request:<id>` or `cron_run:<id>`.
+     *  The runtime records it on the run's root node and its charges, so spend traces back to the call that started the run.
+     *  A call from inside a provider's handler passes the inbound `request:<id>`. It overrides a client-wide `CrouterOptions.causedBy`
+     *  for this call. A value in any other form is ignored by the runtime. */
+    causedBy?: string;
 }
 export interface RunStartResult {
     run_id: string;

package/dist/resources/runs.js

@@ -4,6 +4,8 @@ import { RunStream } from './run-stream.js';
 import { RunReply } from './run-reply.js';
 import { resolveJsonSchema } from '../schema.js';
 import { deadline, heldReadOptions } from './request.js';
+/** The request header that names what caused a call; the runtime reads it on `/v1`. */
+export const CAUSED_BY_HEADER = 'Crtr-Caused-By';
 export class Runs {
     request;
     openEvents;
@@ -15,8 +17,10 @@ export class Runs {
     }
     async start(params, options = {}) {
         const { idempotencyKey = crypto.randomUUID(), maxRetries = 2, ...rest } = options;
-        const body = params.output_schema === undefined ? params : { ...params, output_schema: resolveJsonSchema(params.output_schema) };
-        return this.keyedSend('/v1/runs', body, idempotencyKey, maxRetries, rest);
+        const { causedBy, ...fields } = params;
+        const body = fields.output_schema === undefined ? fields : { ...fields, output_schema: resolveJsonSchema(fields.output_schema) };
+        const headers = causedBy === undefined ? rest.headers : { ...rest.headers, [CAUSED_BY_HEADER]: causedBy };
+        return this.keyedSend('/v1/runs', body, idempotencyKey, maxRetries, headers === undefined ? rest : { ...rest, headers });
     }
     get(runId, options = {}) {
         const { wait, ...rest } = options;

package/dist/resources/spend-limits.d.ts

@@ -0,0 +1,14 @@
+import { type LimitDTO, type SpendLimitListDTO, type SpendLimitRemovedDTO, type SpendLimitSetRequest } from '@north-light/api';
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+/** The runtime's dollar limits. The person's own client only: an app is refused `403 owner_only` (`limits.*` is the unrelated per-app memory and disk cap). */
+export declare class SpendLimits {
+    private readonly request;
+    constructor(request: Request);
+    /** Every limit row: grant caps, the person's own limits and operator limits. */
+    list(options?: RequestOptions): Promise<SpendLimitListDTO>;
+    /** Write the limit row `id` (it must start `person:`), replacing any row with that id. `usd_per_month: 0` is an emergency stop. */
+    set(id: string, params: SpendLimitSetRequest, options?: RequestOptions): Promise<LimitDTO>;
+    /** Clear a `person:` limit row. `404 not_found` when there is none. */
+    remove(id: string, options?: RequestOptions): Promise<SpendLimitRemovedDTO>;
+}

package/dist/resources/spend-limits.js

@@ -0,0 +1,20 @@
+import { routes } from '@north-light/api';
+/** The runtime's dollar limits. The person's own client only: an app is refused `403 owner_only` (`limits.*` is the unrelated per-app memory and disk cap). */
+export class SpendLimits {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    /** Every limit row: grant caps, the person's own limits and operator limits. */
+    list(options) {
+        return this.request('GET', routes.spendLimits(), undefined, options);
+    }
+    /** Write the limit row `id` (it must start `person:`), replacing any row with that id. `usd_per_month: 0` is an emergency stop. */
+    set(id, params, options) {
+        return this.request('PUT', routes.spendLimit(id), params, options);
+    }
+    /** Clear a `person:` limit row. `404 not_found` when there is none. */
+    remove(id, options) {
+        return this.request('DELETE', routes.spendLimit(id), undefined, options);
+    }
+}

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.550"
+  sdk-version: "0.3.552"
 ---
 
 # Building a Northlight app
@@ -27,7 +27,7 @@ Never text a person first: Comms refuses a send to anyone who has not texted you
 
 ## First: check this skill matches the SDK
 
-This skill is for SDK version `0.3.550`. 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. It needs no account. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
+This skill is for SDK version `0.3.552`. 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. It needs no account. 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.550";
+export declare const SDK_VERSION = "0.3.552";
 /** 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.550';
+export const SDK_VERSION = '0.3.552';
 // 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.550",
-  "crouterContract": "1.31",
+  "version": "0.3.552",
+  "crouterContract": "1.32",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,9 +44,9 @@
     "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.550",
-    "@north-light/identity": "0.3.550",
-    "@north-light/plugin": "0.3.550",
+    "@north-light/api": "0.3.552",
+    "@north-light/identity": "0.3.552",
+    "@north-light/plugin": "0.3.552",
     "jose": "^6.2.1"
   },
   "peerDependencies": {