@open-everywhere/core 0.1.0

package/dist/agent/observability/ship.d.ts

@@ -0,0 +1,87 @@
+export type LogLevel = "info" | "warn" | "error";
+export type LogFields = Record<string, unknown>;
+/** One shipped record. Flat on purpose — every backend can index flat JSON. */
+export interface LogRecord {
+    [key: string]: unknown;
+    ts: string;
+    level: LogLevel;
+    service: string;
+    env: string;
+    component: string;
+    message: string;
+    surfaceKey?: string;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+/** Whether shipping is enabled (OE_LOG_SHIP_URL set). */
+export declare function logShipEnabled(): boolean;
+/** Shape an unknown caught value into the record's error field. Never throws. */
+export declare function shapeError(err: unknown): {
+    name: string;
+    message: string;
+    stack?: string;
+};
+/**
+ * Build one record (pure given its inputs — exported for tests). Reserved keys win
+ * over caller fields; surfaceKey falls back to the routing surface hint.
+ */
+export declare function buildRecord(level: LogLevel, component: string, message: string, opts?: {
+    fields?: LogFields;
+    err?: unknown;
+    service?: string;
+}): LogRecord;
+/**
+ * Parse a console call's arguments: pull the `[open-everywhere:x]` component off the
+ * first string argument (else component "console"), keep the first Error argument as
+ * the structured error, stringify the rest. Pure — exported for tests.
+ */
+export declare function parseConsoleArgs(args: unknown[]): {
+    component: string;
+    message: string;
+    err?: unknown;
+};
+/** Queue a record for shipping. No-op when unconfigured. Never throws. */
+export declare function enqueue(record: LogRecord): void;
+/**
+ * Flush the queue now — fire-and-forget POST of a JSON array. All failures are
+ * swallowed (batch dropped, one warning per distinct reason): shipping is best-effort
+ * by contract and must never block or fail a turn. Await-able so the turn-end hook
+ * (and `beforeExit`) can give the POST a chance to complete before instance freeze.
+ */
+export declare function flushLogShip(): Promise<void>;
+export interface OeLogger {
+    info(msg: string, fields?: LogFields): void;
+    warn(msg: string, fields?: LogFields): void;
+    error(msg: string, err?: unknown, fields?: LogFields): void;
+}
+/**
+ * The structured logging API for new code and error paths. Prints the classic
+ * `[open-everywhere:component] msg` line via the RAW console (readable in `vercel
+ * logs`, and invisible to the console capture so it can't double-ship) and enqueues
+ * a structured record with typed fields + error stack.
+ */
+export declare function oeLogger(component: string): OeLogger;
+/**
+ * Wrap console.log/warn/error so every existing `[open-everywhere:x]` line also
+ * ships as a structured record — zero call-site churn across the ~60 existing
+ * sites. Console output is byte-identical (the original fn runs with the original
+ * args). Idempotent; no-op when shipping is unconfigured.
+ */
+export declare function installConsoleCapture(): void;
+/** The one-call install used by the instrumentation setup seam. */
+export declare function installLogShipping(): void;
+/** Records dropped so far (queue overflow / failed flushes) — for tests/diagnostics. */
+export declare function droppedRecordCount(): number;
+/**
+ * TEST SEAM — reset module state and optionally inject a fetch. Restores wrapped
+ * console fns. Not for production use.
+ */
+export declare function __resetLogShipForTest(overrides?: {
+    fetchImpl?: typeof fetch;
+}): void;
+/** TEST SEAM — current queue length. */
+export declare function __queueLengthForTest(): number;
+//# sourceMappingURL=ship.d.ts.map

package/dist/agent/observability/ship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ship.d.ts","sourceRoot":"","sources":["../../../agent/observability/ship.ts"],"names":[],"mappings":"AA4DA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AACjD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3D;AA6DD,yDAAyD;AACzD,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAK1F;AAYD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,QAAQ,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,SAAS,CAeX;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,CAmBvG;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAqB/C;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAyBlD;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CAC7D;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAiBpD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAkB5C;AAgCD,mEAAmE;AACnE,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GAAG,IAAI,CAmBxF;AAED,wCAAwC;AACxC,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/agent/observability/ship.js

@@ -0,0 +1,354 @@
+// Structured log shipping — the vendor-neutral durable-logs seam.
+//
+// WHY: Vercel Hobby retains runtime logs for ~1 HOUR and has no Drains, so the only
+// durable path for "what happened live" is app-level push. This module turns every
+// `[open-everywhere:component]` console line (and any explicitly structured record)
+// into a JSON record and POSTs batches to an env-configured HTTP ingest endpoint —
+// any backend that accepts a JSON array of objects (Axiom, Better Stack, a local
+// collector…). No vendor SDK, no dependency: plain `fetch`.
+//
+// FAIL-OPEN, ZERO-COST WHEN UNCONFIGURED (matching the OTel instrumentation seam):
+//   - No `OE_LOG_SHIP_URL` → everything here is a no-op; console behaviour unchanged.
+//   - Shipping NEVER blocks a turn: records are queued, flushed fire-and-forget on a
+//     size threshold / short unref'd timer / turn-end hook, and ALL transport
+//     failures are swallowed (one raw-console warning per distinct reason).
+//   - The queue is bounded (drop-oldest) so a dead endpoint can't grow memory.
+//
+// Env (see docs/deploy/observability.md):
+//   OE_LOG_SHIP_URL           full ingest URL — presence enables shipping
+//   OE_LOG_SHIP_TOKEN         auth header VALUE (e.g. "Bearer xaat-…") — optional
+//   OE_LOG_SHIP_TOKEN_HEADER  auth header NAME (default "authorization")
+//   OE_LOG_SERVICE            `service` stamp (default "open-everywhere")
+//   OE_LOG_SHIP_BATCH_MAX     flush when the queue reaches this size (default 20)
+//   OE_LOG_SHIP_FLUSH_MS      time-based flush interval in ms (default 1000)
+//
+// Three capture paths feed the same queue:
+//   1. `oeLogger(component)` — the structured API for new/error-path code: prints the
+//      classic `[open-everywhere:component] msg` line via the RAW console (so the
+//      console capture below can't double-ship it) and enqueues a typed record.
+//   2. `installConsoleCapture()` — wraps console.log/warn/error so EVERY existing
+//      log line ships too, with the `[open-everywhere:x]` component parsed out and
+//      any Error argument's stack preserved. Zero call-site churn.
+//   3. `installProcessCapture()` — `uncaughtExceptionMonitor` (observe-only: unlike
+//      an `uncaughtException` listener it does NOT alter Node's crash behaviour; in
+//      Node's default throw-mode it also sees unhandled rejections) + a best-effort
+//      `beforeExit` flush.
+// `installLogShipping()` = 2 + 3, called once from the instrumentation setup seam.
+//
+// surfaceKey: best-effort from the per-session binding bridge (identity/binding-bridge.ts,
+// which the binding-bridge hook stamps from ctx at session/turn start). Fine for
+// observability labels; a log emitted outside a session simply carries no surfaceKey. (This
+// used to read model/surface-hint.ts's module-global — retired with the ALS/hint routing
+// hack; the binding bridge is the surviving per-session identity source.)
+import { readBindingBridge, bridgedContext } from "../identity/binding-bridge.js";
+import { domainKeyOf, resolvePartition } from "../memory/partition.js";
+import { emitTelemetry } from "./telemetry.js";
+/** Best-effort surface key for a log record: the current session's bound surface (domain
+ *  grain, matching what the routing surface stamp used), or undefined outside a session or
+ *  when the context carried no platform identity. Never throws. */
+function surfaceKeyForLog() {
+    try {
+        const bridged = readBindingBridge();
+        if (!bridged)
+            return undefined;
+        return domainKeyOf(resolvePartition(bridgedContext(bridged)));
+    }
+    catch {
+        return undefined;
+    }
+}
+// The console functions as they were BEFORE installConsoleCapture wrapped them.
+// Everything this module prints goes through these — the wrapper must never see
+// its own output (re-entrancy → duplicate/looping records).
+const rawConsole = {
+    log: console.log.bind(console),
+    warn: console.warn.bind(console),
+    error: console.error.bind(console),
+};
+const QUEUE_HARD_CAP = 500; // drop-oldest bound — a dead endpoint must not grow memory
+let config; // undefined = not read yet; null = disabled
+let queue = [];
+let flushTimer;
+let fetchImpl = (...args) => fetch(...args);
+// The console fns as they were AT INSTALL time (composes with any earlier wrapper);
+// null = capture not installed. The test seam restores these.
+let capturedConsole = null;
+let processCaptured = false;
+let droppedRecords = 0;
+const warnedReasons = new Set();
+function warnOnce(reason) {
+    if (warnedReasons.has(reason))
+        return;
+    warnedReasons.add(reason);
+    rawConsole.warn(`[open-everywhere:log-ship] ${reason}`);
+}
+function readConfig() {
+    if (config !== undefined)
+        return config;
+    const url = process.env.OE_LOG_SHIP_URL?.trim();
+    if (!url) {
+        config = null;
+        return config;
+    }
+    const num = (raw, fallback) => {
+        const n = Number(raw);
+        return Number.isFinite(n) && n > 0 ? n : fallback;
+    };
+    config = {
+        url,
+        tokenHeader: process.env.OE_LOG_SHIP_TOKEN_HEADER?.trim() || "authorization",
+        token: process.env.OE_LOG_SHIP_TOKEN || undefined,
+        service: process.env.OE_LOG_SERVICE?.trim() || "open-everywhere",
+        batchMax: num(process.env.OE_LOG_SHIP_BATCH_MAX, 20),
+        flushMs: num(process.env.OE_LOG_SHIP_FLUSH_MS, 1000),
+    };
+    return config;
+}
+/** Whether shipping is enabled (OE_LOG_SHIP_URL set). */
+export function logShipEnabled() {
+    return readConfig() !== null;
+}
+/** Shape an unknown caught value into the record's error field. Never throws. */
+export function shapeError(err) {
+    if (err instanceof Error) {
+        return { name: err.name, message: err.message, stack: err.stack };
+    }
+    return { name: "NonError", message: safeString(err) };
+}
+function safeString(value) {
+    if (typeof value === "string")
+        return value;
+    try {
+        const json = JSON.stringify(value);
+        return json === undefined ? String(value) : json;
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Build one record (pure given its inputs — exported for tests). Reserved keys win
+ * over caller fields; surfaceKey falls back to the routing surface hint.
+ */
+export function buildRecord(level, component, message, opts = {}) {
+    const surfaceKey = typeof opts.fields?.surfaceKey === "string" ? opts.fields.surfaceKey : surfaceKeyForLog();
+    const record = {
+        ...opts.fields,
+        ts: new Date().toISOString(),
+        level,
+        service: opts.service ?? readConfig()?.service ?? "open-everywhere",
+        env: process.env.VERCEL_ENV ?? process.env.NODE_ENV ?? "local",
+        component,
+        message,
+    };
+    if (surfaceKey)
+        record.surfaceKey = surfaceKey;
+    if (opts.err !== undefined)
+        record.error = shapeError(opts.err);
+    return record;
+}
+/**
+ * Parse a console call's arguments: pull the `[open-everywhere:x]` component off the
+ * first string argument (else component "console"), keep the first Error argument as
+ * the structured error, stringify the rest. Pure — exported for tests.
+ */
+export function parseConsoleArgs(args) {
+    let component = "console";
+    let err;
+    const parts = [];
+    for (const arg of args) {
+        if (err === undefined && arg instanceof Error) {
+            err = arg;
+            parts.push(arg.message);
+            continue;
+        }
+        parts.push(safeString(arg));
+    }
+    let message = parts.join(" ");
+    const match = /^\[open-everywhere:([^\]]+)\]\s*/.exec(message);
+    if (match) {
+        component = match[1];
+        message = message.slice(match[0].length);
+    }
+    return err === undefined ? { component, message } : { component, message, err };
+}
+/** Queue a record for shipping. No-op when unconfigured. Never throws. */
+export function enqueue(record) {
+    const cfg = readConfig();
+    if (!cfg)
+        return;
+    try {
+        queue.push(record);
+        if (queue.length > QUEUE_HARD_CAP) {
+            queue.splice(0, queue.length - QUEUE_HARD_CAP);
+            droppedRecords++;
+        }
+        if (queue.length >= cfg.batchMax) {
+            void flushLogShip();
+            return;
+        }
+        if (!flushTimer) {
+            flushTimer = setTimeout(() => void flushLogShip(), cfg.flushMs);
+            // unref so a pending flush never holds the process open (scripts, tests).
+            flushTimer.unref?.();
+        }
+    }
+    catch {
+        // Observability must never throw into the caller.
+    }
+}
+/**
+ * Flush the queue now — fire-and-forget POST of a JSON array. All failures are
+ * swallowed (batch dropped, one warning per distinct reason): shipping is best-effort
+ * by contract and must never block or fail a turn. Await-able so the turn-end hook
+ * (and `beforeExit`) can give the POST a chance to complete before instance freeze.
+ */
+export async function flushLogShip() {
+    const cfg = readConfig();
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = undefined;
+    }
+    if (!cfg || queue.length === 0)
+        return;
+    const batch = queue;
+    queue = [];
+    try {
+        const headers = { "content-type": "application/json" };
+        if (cfg.token)
+            headers[cfg.tokenHeader] = cfg.token;
+        const res = await fetchImpl(cfg.url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(batch),
+        });
+        if (!res.ok) {
+            droppedRecords += batch.length;
+            warnOnce(`ingest rejected ${res.status} — dropping batches with this status until it recovers`);
+        }
+    }
+    catch (err) {
+        droppedRecords += batch.length;
+        warnOnce(`ingest unreachable (${err instanceof Error ? err.message : String(err)}) — dropping batches`);
+    }
+}
+/**
+ * The structured logging API for new code and error paths. Prints the classic
+ * `[open-everywhere:component] msg` line via the RAW console (readable in `vercel
+ * logs`, and invisible to the console capture so it can't double-ship) and enqueues
+ * a structured record with typed fields + error stack.
+ */
+export function oeLogger(component) {
+    const prefix = `[open-everywhere:${component}]`;
+    return {
+        info(msg, fields) {
+            rawConsole.log(`${prefix} ${msg}`);
+            enqueue(buildRecord("info", component, msg, { fields }));
+        },
+        warn(msg, fields) {
+            rawConsole.warn(`${prefix} ${msg}`);
+            enqueue(buildRecord("warn", component, msg, { fields }));
+        },
+        error(msg, err, fields) {
+            if (err === undefined)
+                rawConsole.error(`${prefix} ${msg}`);
+            else
+                rawConsole.error(`${prefix} ${msg}`, err);
+            enqueue(buildRecord("error", component, msg, { fields, err }));
+        },
+    };
+}
+/**
+ * Wrap console.log/warn/error so every existing `[open-everywhere:x]` line also
+ * ships as a structured record — zero call-site churn across the ~60 existing
+ * sites. Console output is byte-identical (the original fn runs with the original
+ * args). Idempotent; no-op when shipping is unconfigured.
+ */
+export function installConsoleCapture() {
+    if (capturedConsole || !logShipEnabled())
+        return;
+    // Wrap the fns AS THEY ARE NOW — composing with any wrapper installed before us —
+    // and remember them so the test seam can unwrap.
+    capturedConsole = { log: console.log, warn: console.warn, error: console.error };
+    const wrap = (level, original) => ((...args) => {
+        try {
+            const { component, message, err } = parseConsoleArgs(args);
+            enqueue(buildRecord(level, component, message, err === undefined ? {} : { err }));
+        }
+        catch {
+            // Capture must never break console output.
+        }
+        original(...args);
+    });
+    console.log = wrap("info", capturedConsole.log);
+    console.warn = wrap("warn", capturedConsole.warn);
+    console.error = wrap("error", capturedConsole.error);
+}
+/**
+ * Ship fatal errors and flush on exit. `uncaughtExceptionMonitor` is observe-only —
+ * it does NOT change Node's crash semantics (unlike an `uncaughtException` listener),
+ * and under Node's default unhandled-rejection mode (throw) it sees unhandled
+ * rejections too. Idempotent.
+ *
+ * INSTALLED UNCONDITIONALLY (not gated on `logShipEnabled()`): `enqueue`/
+ * `flushLogShip` already no-op internally when `OE_LOG_SHIP_URL` is unset, so
+ * gating the LISTENER itself here bought nothing — and it was load-bearing for
+ * telemetry/hooks/telemetry.ts's `oe.error.uncaught` event, which needs this exact
+ * process-capture path independent of whether log shipping happens to be
+ * configured (telemetry defaults ON; log shipping defaults OFF). Fixed inline
+ * rather than adding a second, parallel `uncaughtExceptionMonitor` listener.
+ */
+function installProcessCapture() {
+    if (processCaptured)
+        return;
+    processCaptured = true;
+    process.on("uncaughtExceptionMonitor", (err, origin) => {
+        enqueue(buildRecord("error", "process", `uncaught (${origin})`, { err }));
+        void flushLogShip(); // best-effort — the process may die before the POST lands
+        // Telemetry's oe.error.uncaught: component + error CLASS name only, never the
+        // message or stack (both can embed org content) — see observability/telemetry.ts.
+        emitTelemetry("oe.error.uncaught", {
+            "oe.component": "process",
+            "oe.error.name": err instanceof Error ? err.name : "NonError",
+        });
+    });
+    process.on("beforeExit", () => void flushLogShip());
+}
+/** The one-call install used by the instrumentation setup seam. */
+export function installLogShipping() {
+    installConsoleCapture();
+    installProcessCapture();
+}
+/** Records dropped so far (queue overflow / failed flushes) — for tests/diagnostics. */
+export function droppedRecordCount() {
+    return droppedRecords;
+}
+/**
+ * TEST SEAM — reset module state and optionally inject a fetch. Restores wrapped
+ * console fns. Not for production use.
+ */
+export function __resetLogShipForTest(overrides = {}) {
+    config = undefined;
+    queue = [];
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = undefined;
+    }
+    droppedRecords = 0;
+    warnedReasons.clear();
+    fetchImpl = overrides.fetchImpl ?? ((...args) => fetch(...args));
+    if (capturedConsole) {
+        console.log = capturedConsole.log;
+        console.warn = capturedConsole.warn;
+        console.error = capturedConsole.error;
+        capturedConsole = null;
+    }
+    // process listeners: uncaughtExceptionMonitor/beforeExit are additive and harmless
+    // across tests; we only reset the flag so install can be re-exercised.
+    processCaptured = false;
+}
+/** TEST SEAM — current queue length. */
+export function __queueLengthForTest() {
+    return queue.length;
+}
+//# sourceMappingURL=ship.js.map

package/dist/agent/observability/ship.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ship.js","sourceRoot":"","sources":["../../../agent/observability/ship.ts"],"names":[],"mappings":"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"}

package/dist/agent/observability/telemetry.d.ts

@@ -0,0 +1,154 @@
+/** Every attribute key an event is allowed to carry. Anything else is dropped at
+ *  `emitTelemetry` (warn-once) — this table IS the contract, not a suggestion. */
+export declare const EVENT_SCHEMA: Readonly<Record<string, readonly string[]>>;
+/** Resource attribute keys this module will ever stamp — the never-collected list's
+ *  positive counterpart (docs/deploy/telemetry.md quotes both verbatim). */
+export declare const RESOURCE_ATTR_KEYS: readonly string[];
+/**
+ * THE CLOSED VOCABULARY for `oe.feature` and `oe.outcome` — every value any call site in the tree
+ * emits, and nothing else.
+ *
+ * 🔴 THESE LISTS ARE GATED IN BOTH DIRECTIONS (OPE-1365). `emitTelemetry` itself enforces attribute
+ * KEYS only, so for a while these lists were a comment: the OPE-1290 diff added the wait feature and
+ * its four outcomes, ten other features and seven other outcomes were already being emitted without
+ * ever being declared, and nothing anywhere noticed. `packages/core/scripts/telemetry-test.ts` now
+ * scans every real `emitTelemetry(...)` call site and fails BOTH ways — a literal value outside
+ * these lists, and a value declared here that no call site emits. A vocabulary nothing checks
+ * describes the code it was written against, not the code that ships.
+ *
+ * 🔴 THE SCAN READS LITERALS, AND `emitTelemetry` CLOSES THE REST (OPE-1371). A call site that
+ * passes a hoisted variable is invisible to the scan, and five real emits do exactly that — so for a
+ * while nothing kept those variables inside these lists. The emitter now checks the VALUE of
+ * `oe.feature` and `oe.outcome` against {@link CLOSED_ATTR_VALUES} and drops an undeclared one
+ * before the record is queued, naming it in the deploy log. Both halves stay: the scan catches the
+ * mistake at review time, the emitter at run time. Values only a variable can carry are listed in
+ * the test's `DYNAMIC_ONLY_OUTCOMES`, each against the file that produces it, and the test verifies
+ * that file still contains the value. Prefer a literal at the call site wherever the shape allows
+ * one; a variable there buys nothing and keeps the scan blind.
+ *
+ * `docs/deploy/telemetry.md`'s operator-facing "what we send" table quotes both lists, and the same
+ * test pins the table to them — the doc under-declared what an approve click sends for months. Keep
+ * the two honest together.
+ */
+export declare const FEATURE_VALUES: readonly ["agent_created", "approval_requested", "approval_decided", "approval_judge_contradicted", "bash_hang_guard", "pr_opened", "routine_cancelled", "routine_fired", "routine_permission_card", "routine_permission_card_wait", "skill_created", "skill_deleted", "spend_cap_hit", "spend_checkpoint", "stall_guard", "webhook_declared", "webhook_received", "webhook_rotated"];
+export declare const OUTCOME_VALUES: readonly ["ok", "failed", "noop", "declined", "denied", "withheld", "deduped", "approved", "autoapproved", "rejected", "granted", "continued", "tripped", "expired", "unverified", "deadline", "stale", "gone", "unreadable", "unknown", "not-judge-lift", "already-recorded", "recorded", "halted"];
+/** Turn-total token bucket (log-scale, never a precise count). */
+export declare function tokensBucket(total: number): string;
+/** Step-count bucket for one turn. */
+export declare function stepsBucket(steps: number): string;
+/** Wall-clock latency bucket (ms) for one turn. */
+export declare function latencyBucket(ms: number): string;
+/** Configured-domain-count bucket (never the exact count — can't fingerprint an org's structure). */
+export declare function domainsBucket(count: number): string;
+/** Pre-launch placeholder collector project (a tiny separate Vercel project + Neon
+ *  free tier — a design note "Collector architecture"). May move to
+ *  a custom domain before launch; keep this the ONE named constant callers/docs cite,
+ *  never inlined elsewhere, so that move is a one-line change. */
+export declare const DEFAULT_TELEMETRY_URL = "https://oe-telemetry.vercel.app/v1/logs";
+/**
+ * Drop the memoized config so the NEXT read re-derives it from the current env.
+ * Config is memoized once per process (like ship.ts) because in the normal boot
+ * path env vars never change mid-process. The install wizard is the one legitimate
+ * exception: its interactive "redirect to your own collector" answer mutates
+ * `process.env.OE_TELEMETRY_OTLP_URL` mid-process and must take effect on the very
+ * next emit — call this right after that mutation, before any further telemetry
+ * call. (Distinct from `__resetTelemetryForTest`, which also clears the queue/
+ * instance/dedupe state for a full test reset.)
+ */
+export declare function resetTelemetryConfigCache(): void;
+/** Whether telemetry is enabled right now (config precedence applied). Exported for
+ *  the `/oe status` line and for tests. */
+export declare function telemetryEnabled(): boolean;
+/** `/oe status`'s `telemetry:` line — "off" / "on (default collector)" / "on (custom endpoint)". */
+export declare function telemetryStatusLine(): string;
+interface InstanceInfo {
+    readonly id: string;
+    readonly ephemeral: boolean;
+}
+export interface ResolvedInstance {
+    readonly id: string;
+    readonly ephemeral: boolean;
+    /** True only when THIS call minted a brand-new id — nothing durable existed
+     *  before it. Callers that don't own the app's own first-boot/heartbeat
+     *  lifecycle (the install wizard, below) use this to stay silent on a true
+     *  first-ever resolution without having to know the internal pending flag. */
+    readonly justMinted: boolean;
+}
+/**
+ * Resolve (minting if necessary) this deployment's durable anonymous instance id
+ * — the SAME id the app's own boot lifecycle (`oe.instance.first_boot`/heartbeat,
+ * below) and the install wizard (`packages/create`) both key off, so there is
+ * exactly one id per install, never one per caller. Sets `cachedInstance` as a
+ * side effect (so a subsequent `emitTelemetry` can send). Deliberately does NOT
+ * decide any first-boot/heartbeat emission itself — that stays
+ * `resolveInstanceAndMaybeEmitFirstBoot`'s job below, so a caller like the wizard
+ * can resolve the id under its OWN consent gate without silently triggering the
+ * app's own lifecycle events (which are gated only by `OE_TELEMETRY`/
+ * `DO_NOT_TRACK`, not by the wizard's explicit accept/decline prompt). Never
+ * throws — falls back to an ephemeral per-process id when the operational store
+ * is unreachable.
+ */
+export declare function resolveInstanceId(): Promise<ResolvedInstance>;
+/**
+ * The one-call install used by the instrumentation setup seam (every boot). Prints
+ * the disclosure line BEFORE anything is transmitted, then resolves the instance id
+ * and (respecting the grace window) fires first_boot/heartbeat. Idempotent per
+ * process (a second call in the same boot/warm instance is a no-op). Returns a
+ * Promise so tests can await it deterministically; the instrumentation setup seam
+ * calls it WITHOUT awaiting (`defineInstrumentation`'s `setup` is synchronous —
+ * this must never block boot; resolution proceeds in the background).
+ */
+export declare function initTelemetry(): Promise<void>;
+/** Register (or replace) one EXTRACTED provider's credential-presence probe for the heartbeat's
+ *  `surfacesWithCreds` diagnostic. Exported so a provider bundle (slack, linear, teams, discord,
+ *  github all ride it today) reports its own configured-ness without core hardcoding its vendor
+ *  env-var name. */
+export declare function registerSurfaceCredentialProbe(platform: string, probe: () => boolean): void;
+/**
+ * Emit `oe.instance.heartbeat` if the last one was ≥6h ago (in-memory only — no
+ * store write on this hot path; serverless cold-boot storms are handled by
+ * COLLECTOR-SIDE dedupe on (instance_id, 6h window), not here). Safe to call on
+ * every turn and on cold boot; no-ops silently when the instance isn't resolved yet.
+ */
+export declare function maybeHeartbeat(now?: number): void;
+export type TelemetryAttrValue = string | number | boolean | readonly string[];
+export type TelemetryAttrs = Readonly<Record<string, TelemetryAttrValue>>;
+interface QueuedTelemetryRecord {
+    readonly eventName: string;
+    readonly attributes: TelemetryAttrs;
+    readonly timeUnixNano: string;
+}
+/** Records dropped so far (queue overflow / failed flushes) — self-reported in the
+ *  heartbeat's `oe.telemetry.dropped` field, and for tests/diagnostics. */
+export declare function droppedTelemetryCount(): number;
+/** Build the OTLP/JSON logs payload for a batch of records (pure — exported for
+ *  tests). Resource attributes are stamped ONCE per batch, per the OTLP shape. */
+export declare function buildOtlpPayload(records: readonly QueuedTelemetryRecord[]): Record<string, unknown>;
+/**
+ * Emit one telemetry event. NEVER throws. Enforces the CLOSED vocabulary:
+ * an unregistered `eventName` is dropped whole (warn-once); an attribute key
+ * outside that event's own allow-list is dropped individually (warn-once) —
+ * the rest of the event still sends. No-ops when disabled, when the instance
+ * id isn't resolved yet, or (in debug mode) after logging the would-be payload
+ * instead of queuing it.
+ */
+export declare function emitTelemetry(eventName: string, attrs?: TelemetryAttrs): void;
+/**
+ * Flush the queue now — fire-and-forget POST of the OTLP/JSON payload. All
+ * transport failures are swallowed (batch dropped, one warning per distinct
+ * reason); await-able so a turn-end hook can give the POST a chance to land
+ * before serverless suspend.
+ */
+export declare function flushTelemetry(): Promise<void>;
+/** TEST SEAM — reset every module-level state slot and optionally inject a fetch. */
+export declare function __resetTelemetryForTest(overrides?: {
+    fetchImpl?: typeof fetch;
+}): void;
+/** TEST SEAM — current queue length. */
+export declare function __queueLengthForTest(): number;
+/** TEST SEAM — inject a resolved instance directly (skip the store round-trip). */
+export declare function __setInstanceForTest(info: InstanceInfo | null): void;
+/** TEST SEAM — force the heartbeat throttle open/closed. */
+export declare function __setLastHeartbeatForTest(at: number): void;
+export {};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/agent/observability/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../../agent/observability/telemetry.ts"],"names":[],"mappings":"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"}