@columenlabs/lumen-ops 0.1.34 → 0.1.36

package/README.md

@@ -93,6 +93,37 @@ 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 |
+
 ## 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,3 @@
 export * from './points.js';
 export * from './queries.js';
+export * from './tools.js';

package/dist/index.js

@@ -1,2 +1,3 @@
 export * from './points.js';
 export * from './queries.js';
+export * from './tools.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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@columenlabs/lumen-ops",
-  "version": "0.1.34",
-  "description": "Lumen's ops meters: every data query an app runs as one Analytics Engine point, by its shape only.",
+  "version": "0.1.36",
+  "description": "Lumen's ops meters: every data query and every tool call an app runs as one Analytics Engine point, by shape and hash only.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,6 +18,10 @@
     "./queries": {
       "types": "./dist/queries.d.ts",
       "default": "./dist/queries.js"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "default": "./dist/tools.js"
     }
   },
   "files": [