@north-light/cli 0.3.550 → 0.3.552

package/dist/types.d.ts

@@ -402,6 +402,10 @@ export interface ScopeConfig {
     paths?: {
         user_files?: string;
     };
+    /** The money ledger. `take_pct` (0-100, default 0) is Northlight's take on each priced model or tool charge; at 0 no take rows are written. */
+    ledger?: {
+        take_pct?: number;
+    };
     /** Conversation store configuration for the daemon. */
     store?: {
         root?: string;

package/docs/sdk/release-notes.md

@@ -7,6 +7,16 @@ description: Behavior changes in @north-light/sdk that an app must act on, newes
 
 Changes to `@north-light/sdk` that can change what an existing app sees. Newest first.
 
+## 0.3.552
+
+One ledger records every charge. Additive, except that the per-app cap now counts more.
+
+- **Charges.** `client.charges.list({ month?, under?, after?, limit? })` (`GET /v1/charges`) returns a page of the month's charge rows on this runtime, in time order; while `next` is not null, pass it back as `after` for the rest (`limit` is 1 to 10,000, default 1,000). Each row has: payer, funding, `caused_by`, `request` and the vendor's `vendor_ref`. `under` takes `run:<id>`, `message:<id>`, `request:<id>`, `cron_run:<id>` or a charge id, and lists the rows of every month unless `month` is also given; the answer carries a `month` only when you filtered. An app sees only the rows it is the grantee of. `usage.get` is deprecated in favour of it and keeps its shape.
+- **The per-app cap counts priced tool calls.** The cap a user sets on an app (`spend_cap` in `usage.get`) used to count only model calls on the person's subscription or key. It now counts every charge the app makes on the person, including priced tool calls, so an app can reach its cap sooner than before.
+- **`cap_exhausted` details.** The `402` carries `details.limit` (`id`, `payer`, `filters`, `usd_per_month`, `source`), `details.usd` and `details.reset_at`. `userAction` is `raise_cap` for an app's cap on the person, `clear_limit` for a limit the person set, and absent for an operator limit. `details.spend_cap` and `details.usd_equivalent` are still sent, with the same numbers as `details.limit.usd_per_month` and `details.usd`, but are deprecated: read the new keys. `RateLimitError.capExhausted` returns them typed (`CapExhaustedDetails`). A new run, node or job can now be refused with it too, when a limit covers every charge of its payer, such as a `$0` stop or the app's cap.
+- **Spend limits.** `client.spendLimits.list | set | remove` (`/v1/spend-limits`) reads and writes dollar limits, for the person's own client only; an app is refused `403 owner_only`, and `spendLimits` is not on `AppClient`. These are not `/v1/limits`, which stays the per-app memory and disk cap. `crtr sys spend show | chain | limit` is the command line for all of it.
+- **`Crtr-Caused-By`.** `runs.start({ causedBy })` and the client option `causedBy` send one reference (`message:<id>`, `request:<id>` or `cron_run:<id>`) that the runtime stores on the run's charges. A runtime older than this release ignores it.
+
 ## 0.3.550
 
 An app registers a permission schema for its own object types and decides who may read each object with relations. Additive, except that `friends` leaves the privacy levels and nodes move under their profile.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.550",
+  "version": "0.3.552",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -140,7 +140,7 @@
   },
   "license": "UNLICENSED",
   "dependencies": {
-    "@north-light/identity": "0.3.550",
+    "@north-light/identity": "0.3.552",
     "@earendil-works/pi-agent-core": "1.1.0",
     "@earendil-works/pi-ai": "1.1.0",
     "@earendil-works/pi-coding-agent": "1.1.0",

package/packages/crouter-identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/identity",
-  "version": "0.3.550",
+  "version": "0.3.552",
   "description": "Northlight access-token verification and scope rules",
   "type": "module",
   "main": "./dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.550",
+  "version": "0.3.552",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/cli",
-      "version": "0.3.550",
+      "version": "0.3.552",
       "hasInstallScript": true,
       "license": "UNLICENSED",
       "workspaces": [
@@ -24,7 +24,7 @@
         "@milkdown/preset-gfm": "^7.22.3",
         "@milkdown/prose": "^7.22.3",
         "@milkdown/utils": "^7.22.3",
-        "@north-light/identity": "0.3.550",
+        "@north-light/identity": "0.3.552",
         "cron-parser": "^5.6.0",
         "esbuild": "^0.27.7",
         "jose": "^6.2.12",
@@ -12455,17 +12455,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/api",
-      "version": "0.3.550",
+      "version": "0.3.552",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/env-docker",
-      "version": "0.3.550",
+      "version": "0.3.552",
       "license": "UNLICENSED"
     },
     "packages/crouter-identity": {
       "name": "@north-light/identity",
-      "version": "0.3.550",
+      "version": "0.3.552",
       "license": "UNLICENSED",
       "dependencies": {
         "jose": "^6.2.1"
@@ -12473,21 +12473,21 @@
     },
     "packages/crouter-plugin": {
       "name": "@north-light/plugin",
-      "version": "0.3.550",
+      "version": "0.3.552",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.550",
-        "@north-light/identity": "0.3.550"
+        "@north-light/api": "0.3.552",
+        "@north-light/identity": "0.3.552"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/sdk",
-      "version": "0.3.550",
+      "version": "0.3.552",
       "license": "UNLICENSED",
       "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"
       },
       "bin": {

package/dist/core/usage/ledger.d.ts

@@ -1,49 +0,0 @@
-import { type CanvasDb } from '../canvas/db.js';
-import type { SpendUsageDTO } from '../../api/dto/usage.js';
-/** The person's own agent. Its grant carries the directory's default cap, but the
- *  cap bounds what an app spends of the person's subscription, never the person's
- *  own work, so `app:terminal` is never stopped. */
-export declare const UNCAPPED_GRANTEE = "app:terminal";
-export type Payer = 'user' | 'app';
-/** The UTC calendar month `YYYY-MM` of `at`. */
-export declare function usageMonth(at?: Date): string;
-/** 00:00Z on the first day of the UTC month after `month`. */
-export declare function resetAt(month: string): string;
-export interface UsageRecord {
-    grantee: string;
-    payer: Payer;
-    /** `model` for a completion, `provider:<id>` for a provider receipt. */
-    source: string;
-    /** The model that answered; `''` for a provider receipt. */
-    served_model: string;
-    input_tokens: number;
-    output_tokens: number;
-    cached_tokens: number;
-    /** List-price cost; null when the served model has no list price (it adds nothing to the total). */
-    usd_equivalent: number | null;
-}
-/** Add one completion's or receipt's usage to its grantee's month, inside the caller's write. */
-export declare function addUsage(db: CanvasDb, record: UsageRecord, at?: Date): Promise<void>;
-/** Record one model completion for `grantee`. */
-export declare function recordModelUsage(grantee: string, payer: Payer, servedModel: string, usage: {
-    input: number;
-    output: number;
-    cacheRead: number;
-}, usdEquivalent: number | null): Promise<void>;
-/** The grantee's user-paid month-to-date model spend; provider receipts are not in it. */
-export declare function monthSpend(grantee: string, month?: string): Promise<number>;
-/** Who a user-paid call bills, and the cap that bounds it (`null` = uncapped). */
-export interface SpendTarget {
-    grantee: string;
-    spend_cap: number | null;
-}
-/** The cap that applies to `target`: none for the person's own agent or a grant with no cap. */
-export declare function effectiveCap(target: SpendTarget): number | null;
-/** Refuse a user-paid call once the grantee's month spend reached its cap (SPD-2).
- *  The check runs before the call; one response may overshoot the cap (no
- *  reserve-then-settle), and the next call is refused. */
-export declare function assertUnderCap(target: SpendTarget | undefined, at?: Date): Promise<void>;
-/** `usage.get` for one grantee and month. */
-export declare function usageFor(grantee: string, spendCap: number | null, month?: string): Promise<SpendUsageDTO>;
-/** A `month` query value: `YYYY-MM` with a real month, years 1000-9999; absent means the current month. */
-export declare function parseUsageMonth(value: string | null): string;

package/dist/core/usage/ledger.js

@@ -1,10 +0,0 @@
-var f=Object.defineProperty;var a=(e,t)=>f(e,"name",{value:t,configurable:!0});import{withCanvasWrite as h,openDb as d}from"../canvas/db.js";import{RunError as _}from"../runs/operations.js";const q="app:terminal";function r(e=new Date){return e.toISOString().slice(0,7)}a(r,"usageMonth");function l(e){const[t,n]=e.split("-").map(Number);return new Date(Date.UTC(t,n,1)).toISOString()}a(l,"resetAt");async function w(e,t,n=new Date){const u=r(n);await e.prepare(`INSERT INTO usage (grantee, month, payer, source, served_model, input_tokens, output_tokens, cached_tokens, usd_equivalent)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(grantee, month, payer, source, served_model) DO UPDATE SET
-      input_tokens = usage.input_tokens + excluded.input_tokens,
-      output_tokens = usage.output_tokens + excluded.output_tokens,
-      cached_tokens = usage.cached_tokens + excluded.cached_tokens,
-      usd_equivalent = CASE WHEN usage.usd_equivalent IS NULL AND excluded.usd_equivalent IS NULL THEN NULL
-        ELSE COALESCE(usage.usd_equivalent, 0) + COALESCE(excluded.usd_equivalent, 0) END`).run(t.grantee,u,t.payer,t.source,t.served_model,t.input_tokens,t.output_tokens,t.cached_tokens,t.usd_equivalent),t.payer==="user"&&t.source==="model"&&t.usd_equivalent!==null&&t.usd_equivalent>0&&await e.prepare(`INSERT INTO grantee_usage (grantee, month, usd_equivalent) VALUES (?, ?, ?)
-      ON CONFLICT(grantee, month) DO UPDATE SET usd_equivalent = grantee_usage.usd_equivalent + excluded.usd_equivalent`).run(t.grantee,u,t.usd_equivalent)}a(w,"addUsage");async function y(e,t,n,u,s){await h(async p=>await w(p,{grantee:e,payer:t,source:"model",served_model:n,input_tokens:u.input,output_tokens:u.output,cached_tokens:u.cacheRead,usd_equivalent:s}))}a(y,"recordModelUsage");async function c(e,t=r()){return(await(await d()).prepare("SELECT usd_equivalent FROM grantee_usage WHERE grantee = ? AND month = ?").get(e,t))?.usd_equivalent??0}a(c,"monthSpend");function m(e){return e.grantee===q?null:e.spend_cap}a(m,"effectiveCap");async function x(e,t=new Date){if(!e)return;const n=m(e);if(n===null)return;const u=r(t),s=await c(e.grantee,u);if(!(s<n))throw new _(402,"cap_exhausted",`${e.grantee} reached its monthly usage limit`,void 0,{spend_cap:n,usd_equivalent:s,reset_at:l(u)})}a(x,"assertUnderCap");async function C(e,t,n=r()){const u=await(await d()).prepare(`SELECT payer, source, served_model, input_tokens, output_tokens, usd_equivalent
-    FROM usage WHERE grantee = ? AND month = ? ORDER BY served_model`).all(e,n),s=a(i=>u.filter(o=>o.payer===i&&o.source==="model").map(({served_model:o,input_tokens:E,output_tokens:v,usd_equivalent:g})=>({served_model:o,input_tokens:E,output_tokens:v,usd_equivalent:g})),"byModel"),p=u.filter(i=>i.payer==="app").reduce((i,o)=>i+(o.usd_equivalent??0),0);return{grantee:e,month:n,usd_equivalent:await c(e,n),by_model:s("user"),app_paid:{usd_equivalent:p,by_model:s("app")},spend_cap:m({grantee:e,spend_cap:t}),reset_at:l(n)}}a(C,"usageFor");function D(e){if(e===null)return r();if(!/^[1-9]\d{3}-(0[1-9]|1[0-2])$/.test(e))throw new _(400,"invalid_request","month must be YYYY-MM","month");return e}a(D,"parseUsageMonth");export{q as UNCAPPED_GRANTEE,w as addUsage,x as assertUnderCap,m as effectiveCap,c as monthSpend,D as parseUsageMonth,y as recordModelUsage,l as resetAt,C as usageFor,r as usageMonth};