@columenlabs/lumen-ops 0.1.35 → 0.1.37

package/README.md

@@ -1,6 +1,6 @@
 # @columenlabs/lumen-ops
 
-Lumen's ops meters for Cloudflare Workers: every data query your app runs becomes one Analytics Engine point, so you can find slow and heavy queries and fix them. The meter wraps your bindings once, so new code is metered without opting in. It writes only each query's shape, never a value.
+Lumen's ops parts for Cloudflare Workers: every data query your app runs becomes one Analytics Engine point, so you can find slow and heavy queries and fix them. The meter wraps your bindings once, so new code is metered without opting in. It writes only each query's shape, never a value. It also meters tool calls (`/tools`) and sends signed webhooks (`/webhooks`).
 
 - Docs: https://lumen.columenlabs.com/docs/
 - For agents: https://lumen.columenlabs.com/llms.txt
@@ -93,6 +93,63 @@ GROUP BY fingerprint ORDER BY p95_ms DESC LIMIT 20
 | `queryShape(sql)` | The shape, fingerprint and op of a query |
 | `foldRoute(path)` | A path with id-like segments as `:id` |
 
+## Tool calls
+
+`@columenlabs/lumen-ops/tools` meters each call an assistant or agent makes: one point per call with its latency, outcome and a hash of the code it ran, so slow or failing tools show up and the same script is grouped across runs.
+
+```ts
+import { meteredCall, meterToolCall, setToolSink } from '@columenlabs/lumen-ops/tools';
+
+setToolSink(env.TOOL_CALLS); // an Analytics Engine dataset binding
+
+// Wrap a call: latency and outcome are taken for you.
+const rows = await meteredCall({ app: 'trade', tool: 'portfolio_list', kind: 'call' }, () => run(args));
+
+// Or write one by hand, with the code a script ran.
+meterToolCall({ app: 'trade', tool: 'script', kind: 'script', ok: true, ms: 840, code: source, rows: 120 });
+```
+
+| Column | Holds |
+|---|---|
+| `index1` | app |
+| `blob1`…`blob9` | app, tool, kind, outcome (`ok` or `error`), error kind, code hash, source, tier, run id |
+| `double1`…`double6` | ms, rows, bytes in, bytes out, tokens in, tokens out |
+
+Arguments and results are never written; only their sizes.
+
+| Export | What it does |
+|---|---|
+| `setToolSink(binding)` | The dataset tool points go to; nothing is written until it is set |
+| `meterToolCall(point)` | One point by hand |
+| `meteredCall(point, fn, errorKind?)` | Runs `fn`, timing it and writing its outcome |
+| `codeHash(code)` | A short hash of a script, whitespace folded |
+
+## Webhooks out
+
+`@columenlabs/lumen-ops/webhooks` sends one delivery, signed per the [Standard Webhooks](https://www.standardwebhooks.com) spec when a secret is given, so the receiver can verify it with any Standard Webhooks library. It never throws: the result says how it went, for the app's own delivery log and retries.
+
+```ts
+import { newWebhookSecret, sendWebhook } from '@columenlabs/lumen-ops/webhooks';
+
+const secret = newWebhookSecret(); // whsec_…, shown to its owner once, kept sealed
+const r = await sendWebhook({
+  url: endpoint.url,
+  secret,
+  id: event.id, // the same id on a retry
+  body: JSON.stringify(event.payload),
+  headers: { authorization: `Bearer ${endpoint.token}` },
+  userAgent: 'MyApp-Webhooks/1',
+});
+if (!r.ok) scheduleRetry(event, r.status, r.error);
+```
+
+| Export | What it does |
+|---|---|
+| `sendWebhook(send)` | One POST: `{ ok, status, ms, id, error? }`; status 0 when the endpoint never answered |
+| `newWebhookSecret()` | A new `whsec_` secret, 32 random bytes |
+
+The endpoint's own headers go first, so they can never replace the signature headers. Redirects count as failures unless `redirect` says otherwise; the timeout is 10 s by default.
+
 ## Versions
 
 0.x: any minor may break things until 1.0. Every merge to Lumen's `main` publishes the next patch of every Lumen package; see the [releases](https://github.com/columenlabs/lumen/releases).

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export * from './points.js';
 export * from './queries.js';
+export * from './tools.js';
+export * from './webhooks.js';

package/dist/index.js

@@ -1,2 +1,4 @@
 export * from './points.js';
 export * from './queries.js';
+export * from './tools.js';
+export * from './webhooks.js';

package/dist/tools.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The tool-call meter: every tool an assistant or an agent calls (an MCP tool, a function, a script
+ * in a sandbox, a web read) is one Analytics Engine point, with how long it took, how it ended and
+ * a hash of the code it ran, so slow, failing and repeated calls can be found and made first class.
+ *
+ * A point holds names, numbers and hashes only: never the arguments, the result or the person.
+ */
+import type { PointSink } from './points.js';
+export interface ToolCallPoint {
+    /** The app, or the part of it, the call ran in. */
+    app: string;
+    /** The tool or function called (`trade.portfolio_list`), or a name for the script. */
+    tool: string;
+    /** How it was called: call, script, sql, web, or your own. */
+    kind: string;
+    ok: boolean;
+    /** Wall time of the call, ms. */
+    ms: number;
+    /** A short error kind when it failed (`bad_args`, `timeout`), never the message. */
+    error?: string;
+    /** The code the call ran (a script's source, a query); only its hash is written. */
+    code?: string;
+    /** Who started it: chat, brief, job, or your own. */
+    source?: string;
+    /** The model size or tier that made the call, never a model's name if the app keeps it private. */
+    tier?: string;
+    /** The turn or run the call belongs to, an id the app makes (not a person's). */
+    run?: string;
+    /** Rows the call returned. */
+    rows?: number;
+    /** Bytes of the call's input and output. */
+    bytesIn?: number;
+    bytesOut?: number;
+    /** Tokens, when the call itself ran a model. */
+    tokensIn?: number;
+    tokensOut?: number;
+}
+/** The entry point sets the dataset once per isolate. */
+export declare function setToolSink(s: PointSink | undefined): void;
+/** A 64-bit hash of the code with its whitespace folded: the same script hashes the same. */
+export declare function codeHash(code: string): string;
+/**
+ * Column order is the contract with whoever reads the dataset back: index1 app; blobs app, tool,
+ * kind, outcome, error, code hash, source, tier, run; doubles ms, rows, bytes in, bytes out,
+ * tokens in, tokens out.
+ */
+export declare function meterToolCall(p: ToolCallPoint): void;
+/** Runs one tool call and meters it: the wall time, and `error` as the kind when it throws. */
+export declare function meteredCall<T>(p: Omit<ToolCallPoint, 'ok' | 'ms'>, fn: () => Promise<T>, errorKind?: (err: unknown) => string): Promise<T>;

package/dist/tools.js

@@ -0,0 +1,67 @@
+let sink;
+/** The entry point sets the dataset once per isolate. */
+export function setToolSink(s) {
+    sink = s;
+}
+const fnv = (s, seed) => {
+    let h = seed >>> 0;
+    for (let i = 0; i < s.length; i++)
+        h = Math.imul(h ^ s.charCodeAt(i), 16777619) >>> 0;
+    return h.toString(16).padStart(8, '0');
+};
+/** A 64-bit hash of the code with its whitespace folded: the same script hashes the same. */
+export function codeHash(code) {
+    const s = code.replace(/\s+/g, ' ').trim();
+    return fnv(s, 2166136261) + fnv(s, 0x9e3779b9);
+}
+const cap = (s, n = 96) => (s.length > n ? s.slice(0, n) : s);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+/**
+ * Column order is the contract with whoever reads the dataset back: index1 app; blobs app, tool,
+ * kind, outcome, error, code hash, source, tier, run; doubles ms, rows, bytes in, bytes out,
+ * tokens in, tokens out.
+ */
+export function meterToolCall(p) {
+    if (!sink)
+        return;
+    try {
+        sink.writeDataPoint({
+            indexes: [cap(p.app)],
+            blobs: [
+                cap(p.app),
+                cap(p.tool, 128),
+                cap(p.kind),
+                p.ok ? 'ok' : 'error',
+                cap(p.error ?? ''),
+                p.code ? codeHash(p.code) : '',
+                cap(p.source ?? ''),
+                cap(p.tier ?? ''),
+                cap(p.run ?? ''),
+            ],
+            doubles: [
+                num(p.ms),
+                num(p.rows),
+                num(p.bytesIn),
+                num(p.bytesOut),
+                num(p.tokensIn),
+                num(p.tokensOut),
+            ],
+        });
+    }
+    catch (err) {
+        console.error('meterToolCall', err);
+    }
+}
+/** Runs one tool call and meters it: the wall time, and `error` as the kind when it throws. */
+export async function meteredCall(p, fn, errorKind = () => 'error') {
+    const t0 = performance.now();
+    try {
+        const out = await fn();
+        meterToolCall({ ...p, ok: true, ms: performance.now() - t0 });
+        return out;
+    }
+    catch (err) {
+        meterToolCall({ ...p, ok: false, ms: performance.now() - t0, error: errorKind(err) });
+        throw err;
+    }
+}

package/dist/webhooks.d.ts

@@ -0,0 +1,34 @@
+export interface WebhookSend {
+    url: string;
+    /** The body as sent and signed, usually JSON. */
+    body: string;
+    /** Signs the delivery: `whsec_…` (see `newWebhookSecret`). Left out, nothing is signed. */
+    secret?: string;
+    /** The message id the signature covers; the same id on a retry. Made up when left out. */
+    id?: string;
+    /** The endpoint's own headers (its auth). They can never replace the signature headers. */
+    headers?: Record<string, string>;
+    /** Default `application/json`. */
+    contentType?: string;
+    userAgent?: string;
+    /** Default 10 s. */
+    timeoutMs?: number;
+    /** Default `manual`: a redirect counts as a failed delivery, never followed. */
+    redirect?: RequestRedirect;
+    /** For tests or a service binding; default the global fetch. */
+    fetch?: typeof fetch;
+}
+export interface WebhookResult {
+    ok: boolean;
+    /** The endpoint's HTTP status; 0 when it never answered (timeout, DNS, refused). */
+    status: number;
+    ms: number;
+    /** The message id sent. */
+    id: string;
+    /** On a failure: the first 200 characters of the answer, or why there was none. */
+    error?: string;
+}
+/** A new signing secret, `whsec_` and 32 random bytes in base64. Show it to its owner once. */
+export declare function newWebhookSecret(): string;
+/** Sends one delivery. */
+export declare function sendWebhook(send: WebhookSend): Promise<WebhookResult>;

package/dist/webhooks.js

@@ -0,0 +1,49 @@
+/**
+ * Webhooks out: one POST to an endpoint, signed per the Standard Webhooks spec
+ * (https://www.standardwebhooks.com) when a secret is given, so any of its libraries verifies it.
+ * The send never throws: it returns how it went, for the app's own delivery log and retries.
+ */
+import { Webhook } from 'standardwebhooks';
+/** A new signing secret, `whsec_` and 32 random bytes in base64. Show it to its owner once. */
+export function newWebhookSecret() {
+    const bytes = crypto.getRandomValues(new Uint8Array(32));
+    return `whsec_${btoa(String.fromCharCode(...bytes))}`;
+}
+/** Sends one delivery. */
+export async function sendWebhook(send) {
+    const id = send.id ?? `msg_${crypto.randomUUID().replaceAll('-', '')}`;
+    const at = new Date();
+    const signed = send.secret
+        ? {
+            'webhook-id': id,
+            'webhook-timestamp': String(Math.floor(at.getTime() / 1000)),
+            'webhook-signature': new Webhook(send.secret).sign(id, at, send.body),
+        }
+        : {};
+    const started = Date.now();
+    try {
+        const res = await (send.fetch ?? fetch)(send.url, {
+            method: 'POST',
+            redirect: send.redirect ?? 'manual',
+            signal: AbortSignal.timeout(send.timeoutMs ?? 10_000),
+            headers: {
+                ...send.headers,
+                'content-type': send.contentType ?? 'application/json',
+                ...(send.userAgent ? { 'user-agent': send.userAgent } : {}),
+                ...signed,
+            },
+            body: send.body,
+        });
+        const ok = res.status >= 200 && res.status < 300;
+        let error;
+        if (ok)
+            await res.body?.cancel();
+        else
+            error = (await res.text().catch(() => '')).slice(0, 200) || `HTTP ${res.status}`;
+        return { ok, status: res.status, ms: Date.now() - started, id, ...(error ? { error } : {}) };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 0, ms: Date.now() - started, id, error: error.slice(0, 200) };
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@columenlabs/lumen-ops",
-  "version": "0.1.35",
-  "description": "Lumen's ops meters: every data query an app runs as one Analytics Engine point, by its shape only.",
+  "version": "0.1.37",
+  "description": "Lumen's ops parts: every data query and tool call an app runs as one Analytics Engine point (shapes and hashes only), and signed webhooks out.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,6 +18,14 @@
     "./queries": {
       "types": "./dist/queries.d.ts",
       "default": "./dist/queries.js"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "default": "./dist/tools.js"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks.d.ts",
+      "default": "./dist/webhooks.js"
     }
   },
   "files": [
@@ -39,5 +47,7 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "dependencies": {}
+  "dependencies": {
+    "standardwebhooks": "1.1.1"
+  }
 }