@cat-factory/server 0.185.2 → 0.188.0

package/dist/telemetry/machineTelemetry.js

@@ -0,0 +1,89 @@
+// Mothership-mode telemetry INGEST (docs/initiatives/mothership-mode.md, PR 5 — the UPSTREAM half).
+//
+// Telemetry is the local-first bucket: a mothership-mode node writes every LLM call, dispatch
+// context and performed search to a `node:sqlite` store on the laptop, because routing them
+// through the per-call persistence RPC would put a network round trip on the hot path of every
+// model call. That capture half landed with the store and its retention prune.
+//
+// What it left open is that the rows never go anywhere. A hosted teammate opening the run a
+// laptop drove sees an empty observability panel, zero token rollups and no web-search log — and
+// once the local retention window passes, so does the node that produced them. This module is the
+// runtime-neutral spine of the sync UP: the wire envelope, the fetch client the laptop posts
+// through, and nothing else. It is deliberately a DEDICATED `/internal/*` endpoint rather than a
+// hole in the persistence proxy (ADR 0009): the whole reason telemetry is local-first is that its
+// writes must not be per-row RPCs, so re-admitting them one at a time would undo the bucket.
+//
+// The batch is APPEND-ONLY and idempotent by row id, which is what lets the node retry a chunk
+// whose ack was lost without corrupting a stored prompt delta (see the ports' `recordMany`).
+/** Per-request row caps. A batch above these is refused (413) rather than silently truncated. */
+export const TELEMETRY_INGEST_LIMITS = {
+    /** Per-call rows: the lightest of the three, though each carries prompt + response bodies. */
+    metrics: 200,
+    /** Dispatch snapshots: one row is routinely megabytes (composed prompt + injected files). */
+    snapshots: 20,
+    /** Performed searches: no unbounded body, so the cap is purely on row count. */
+    searchQueries: 500,
+};
+/**
+ * Upper bound on a whole ingest request body (characters), checked before parsing costs anything
+ * meaningful. The row caps above bound COUNT; this bounds BYTES, which is the axis a single
+ * pathological snapshot moves. Generous enough for a full chunk of real rows.
+ */
+export const MAX_TELEMETRY_INGEST_CHARS = 8_000_000;
+/**
+ * Thrown when the node holds no machine token yet (booted before the mothership login), so
+ * nothing was uploaded and nothing COULD have been.
+ *
+ * It is an error rather than an empty-but-successful result because the caller's success path
+ * advances a high-water mark: a zeroed `TelemetryIngestResult` is indistinguishable from "the run
+ * had no rows", which would mark the run uploaded and let the local prune delete rows the
+ * mothership never saw. Distinct from a transport failure only so the sweep can log it as the
+ * benign, self-healing condition it is — both dispositions leave the mark alone and retry.
+ */
+export class MachineTokenUnavailableError extends Error {
+    constructor() {
+        super('no machine token: node has not completed the mothership login yet');
+        this.name = 'MachineTokenUnavailableError';
+    }
+}
+const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * A fetch-based {@link MachineTelemetryClient} posting to a mothership's
+ * `POST /internal/telemetry/ingest` with the node's machine token. Mirrors
+ * `HttpMachineNotificationClient`'s auth contract (a fixed token OR a per-request provider, so a
+ * token cached after boot by the mothership login flow is picked up without a restart).
+ */
+export class HttpMachineTelemetryClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async ingest(batch) {
+        const token = typeof this.opts.token === 'function' ? this.opts.token() : this.opts.token;
+        // No token yet (a node booted before the mothership login): there is nothing to sync to, and a
+        // guaranteed-403 upload of megabytes is pure waste — so the upload is SKIPPED, but it is
+        // skipped by THROWING. Returning a zeroed result here would read to the sweep as "the range is
+        // stored", advancing the run's high-water mark over rows that never left the laptop and
+        // handing them to the retention prune. The rows stay local and the run stays a candidate, so
+        // the sweep picks it up once the SPA login completes.
+        if (!token)
+            throw new MachineTokenUnavailableError();
+        const fetchImpl = this.opts.fetchImpl ?? fetch;
+        const res = await fetchImpl(`${this.opts.baseUrl.replace(/\/$/, '')}/internal/telemetry/ingest`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+            body: JSON.stringify(batch),
+            signal: AbortSignal.timeout(this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            throw new Error(`mothership telemetry ingest failed with HTTP ${res.status}`);
+        }
+        const body = (await res.json());
+        return {
+            metrics: body.stored?.metrics ?? 0,
+            snapshots: body.stored?.snapshots ?? 0,
+            searchQueries: body.stored?.searchQueries ?? 0,
+        };
+    }
+}
+//# sourceMappingURL=machineTelemetry.js.map

package/dist/telemetry/machineTelemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machineTelemetry.js","sourceRoot":"","sources":["../../src/telemetry/machineTelemetry.ts"],"names":[],"mappings":"AAEA,oGAAoG;AACpG,EAAE;AACF,8FAA8F;AAC9F,4FAA4F;AAC5F,+FAA+F;AAC/F,+EAA+E;AAC/E,EAAE;AACF,4FAA4F;AAC5F,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,EAAE;AACF,+FAA+F;AAC/F,6FAA6F;AAE7F,iGAAiG;AACjG,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,8FAA8F;IAC9F,OAAO,EAAE,GAAG;IACZ,6FAA6F;IAC7F,SAAS,EAAE,EAAE;IACb,gFAAgF;IAChF,aAAa,EAAE,GAAG;CACV,CAAA;AAEV;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,SAAS,CAAA;AA4BnD;;;;;;;;;GASG;AACH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACrD;QACE,KAAK,CAAC,mEAAmE,CAAC,CAAA;QAC1E,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAA;IAC5C,CAAC;CACF;AA2BD,MAAM,kBAAkB,GAAG,MAAM,CAAA;AAEjC;;;;;GAKG;AACH,MAAM,OAAO,0BAA0B;IACR,IAAI;IAAjC,YAA6B,IAAuC;oBAAvC,IAAI;IAAsC,CAAC;IAExE,KAAK,CAAC,MAAM,CAAC,KAA6B;QACxC,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAA;QACzF,+FAA+F;QAC/F,yFAAyF;QACzF,+FAA+F;QAC/F,wFAAwF;QACxF,6FAA6F;QAC7F,sDAAsD;QACtD,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,4BAA4B,EAAE,CAAA;QACpD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,KAAK,CAAA;QAC9C,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,4BAA4B,EACnE;YACE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE;YACjF,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YAC3B,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC;SACvE,CACF,CAAA;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,gDAAgD,GAAG,CAAC,MAAM,EAAE,CAAC,CAAA;QAC/E,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAgD,CAAA;QAC9E,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC;YAClC,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,IAAI,CAAC;YACtC,aAAa,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,IAAI,CAAC;SAC/C,CAAA;IACH,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/server",
-  "version": "0.185.2",
+  "version": "0.188.0",
   "description": "Runtime-neutral HTTP layer for the Agent Architecture Board: the Hono controllers, middleware (auth/authz/CORS/error), request helpers and the gateway seams shared by every deployment facade (Cloudflare Worker, Node service).",
   "repository": {
     "type": "git",
@@ -30,13 +30,13 @@
     "hono": "^4.12.32",
     "pino": "^10.3.1",
     "valibot": "^1.4.2",
-    "@cat-factory/agents": "0.94.0",
-    "@cat-factory/contracts": "0.202.0",
-    "@cat-factory/integrations": "0.113.5",
-    "@cat-factory/kernel": "0.201.0",
-    "@cat-factory/orchestration": "0.177.1",
-    "@cat-factory/prompt-fragments": "0.15.25",
-    "@cat-factory/spend": "0.12.131"
+    "@cat-factory/agents": "0.96.0",
+    "@cat-factory/contracts": "0.204.0",
+    "@cat-factory/integrations": "0.113.8",
+    "@cat-factory/kernel": "0.203.0",
+    "@cat-factory/orchestration": "0.179.0",
+    "@cat-factory/prompt-fragments": "0.15.27",
+    "@cat-factory/spend": "0.12.134"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",