@a5c-ai/agent-runtime 5.0.1-staging.04ca6ab00d21 → 5.0.1-staging.40a93c240e7b

package/README.md

@@ -4,6 +4,12 @@ Agent runtime layer (L5) for the Babysitter monorepo.
 
 Provides daemon lifecycle, session management, resource management, and telemetry infrastructure.
 
+The runtime observability surface includes compatible daemon JSONL logging policy
+helpers, run-health latency percentiles, pure diagnostics renderers for health,
+metrics, config, and queue state, and optional telemetry trace/export helpers.
+Remote telemetry exporters are opt-in; local and no-op behavior remains the
+default.
+
 ## Install
 
 ```bash

package/dist/background/state.d.ts

@@ -4,11 +4,17 @@ import { BackgroundProcessRegistry } from "../backgroundProcessRegistry";
  * that state.ts actually consumes.  Defined locally to avoid a circular
  * dependency between agent-runtime and agent-core.
  */
-interface BackgroundRegistryOwner {
+export interface BackgroundRegistryOwner {
     backgroundRegistry?: BackgroundProcessRegistry;
     maxBackgroundProcesses?: number;
+    /**
+     * Stable identifier for the owner.  When provided, the registry is stored
+     * in a string-keyed Map in addition to the WeakMap.  This prevents orphaning
+     * when the caller recreates the options object (new object identity) but
+     * logically refers to the same owner.
+     */
+    registryId?: string;
 }
 export declare function getBackgroundRegistry(options: BackgroundRegistryOwner): BackgroundProcessRegistry;
 export declare function disposeBackgroundRegistry(options: BackgroundRegistryOwner): void;
-export {};
 //# sourceMappingURL=state.d.ts.map

package/dist/background/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/background/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAEzE;;;;GAIG;AACH,UAAU,uBAAuB;IAC/B,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;IAC/C,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAID,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,uBAAuB,GAAG,yBAAyB,CAWjG;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAOhF"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/background/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;IAC/C,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAcD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,uBAAuB,GAAG,yBAAyB,CA8BjG;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAWhF"}

package/dist/background/state.js

@@ -3,15 +3,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getBackgroundRegistry = getBackgroundRegistry;
 exports.disposeBackgroundRegistry = disposeBackgroundRegistry;
 const backgroundProcessRegistry_1 = require("../backgroundProcessRegistry");
+/**
+ * Primary store — keyed by object identity (auto-collected when owner is GC'd).
+ */
 const scopedRegistries = new WeakMap();
+/**
+ * Secondary store — keyed by `registryId` string so that a new options object
+ * with the same registryId finds the existing registry instead of creating a
+ * new one (which would orphan any background processes tracked by the old one).
+ */
+const namedRegistries = new Map();
 function getBackgroundRegistry(options) {
     if (options.backgroundRegistry) {
         return options.backgroundRegistry;
     }
+    // Try the WeakMap first (cheapest path for stable object references).
     let registry = scopedRegistries.get(options);
-    if (!registry) {
-        registry = new backgroundProcessRegistry_1.BackgroundProcessRegistry({ maxConcurrent: options.maxBackgroundProcesses });
-        scopedRegistries.set(options, registry);
+    if (registry) {
+        return registry;
+    }
+    // Try the string-keyed secondary map when a registryId is provided.
+    if (options.registryId) {
+        registry = namedRegistries.get(options.registryId);
+        if (registry) {
+            // Re-attach to the WeakMap so subsequent lookups with this object are fast.
+            scopedRegistries.set(options, registry);
+            return registry;
+        }
+    }
+    // No existing registry found — create a new one.
+    registry = new backgroundProcessRegistry_1.BackgroundProcessRegistry({ maxConcurrent: options.maxBackgroundProcesses });
+    scopedRegistries.set(options, registry);
+    if (options.registryId) {
+        namedRegistries.set(options.registryId, registry);
     }
     return registry;
 }
@@ -22,4 +46,7 @@ function disposeBackgroundRegistry(options) {
     }
     registry.dispose();
     scopedRegistries.delete(options);
+    if (options.registryId) {
+        namedRegistries.delete(options.registryId);
+    }
 }

package/dist/backgroundProcessRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backgroundProcessRegistry.d.ts","sourceRoot":"","sources":["../src/backgroundProcessRegistry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAC;AAOnD,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,mDAAmD;AACnD,MAAM,WAAW,yBAAyB;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,IAAI,CAAC;CACzD;AA4BD,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,YAAY,CAAC,KAAK,CAAA;KAAE;IAKrF;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,oBAAoB;IAuF/C,+DAA+D;IAC/D,GAAG,CAAC,gBAAgB,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAM/D,+CAA+C;IAC/C,IAAI,IAAI,oBAAoB,EAAE;IAI9B,4EAA4E;IAC5E,MAAM,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO;IAczC,kCAAkC;IAClC,OAAO,IAAI,IAAI;IAcf,mDAAmD;IACnD,OAAO,IAAI,IAAI;IASf,OAAO,CAAC,QAAQ;CAcjB"}
+{"version":3,"file":"backgroundProcessRegistry.d.ts","sourceRoot":"","sources":["../src/backgroundProcessRegistry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAC;AAOnD,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,mDAAmD;AACnD,MAAM,WAAW,yBAAyB;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,IAAI,CAAC;CACzD;AA4BD,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,YAAY,CAAC,KAAK,CAAA;KAAE;IAKrF;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,oBAAoB;IA0F/C,+DAA+D;IAC/D,GAAG,CAAC,gBAAgB,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAM/D,+CAA+C;IAC/C,IAAI,IAAI,oBAAoB,EAAE;IAI9B,4EAA4E;IAC5E,MAAM,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO;IAczC,kCAAkC;IAClC,OAAO,IAAI,IAAI;IAcf,mDAAmD;IACnD,OAAO,IAAI,IAAI;IASf,OAAO,CAAC,QAAQ;CAcjB"}

package/dist/backgroundProcessRegistry.js

@@ -66,6 +66,9 @@ class BackgroundProcessRegistry {
         }
         const backgroundTaskId = (0, babysitter_sdk_1.nextUlid)();
         const startMs = Date.now();
+        // HERE BE DRAGONS: Shell invocation is duplicated in 5 files. All must use the same flags.
+        // See also: agent-core/session.ts, agent-core/tools/execution.ts,
+        // agent-platform/tools/execution.ts, agent-platform/backgroundProcessRegistry.ts
         const shell = process.platform === "win32" ? "cmd.exe" : "/bin/bash";
         const shellArgs = process.platform === "win32"
             ? ["/c", opts.command]

package/dist/daemon/daemonLog.d.ts

@@ -3,11 +3,28 @@
  *
  * Appends structured JSON lines to a daemon activation log file.
  */
+export type DaemonLogLevel = "debug" | "info" | "warn" | "error" | "fatal";
 export interface DaemonLogEntry {
     timestamp: string;
     event: string;
+    level?: DaemonLogLevel;
+    schemaVersion?: string;
+    sampled?: boolean;
+    sequence?: number;
+    correlationId?: string;
+    traceId?: string;
+    spanId?: string;
     data?: Record<string, unknown>;
 }
-export declare function appendDaemonLog(logDir: string, entry: DaemonLogEntry): Promise<void>;
+export interface DaemonLogPolicy {
+    minLevel?: DaemonLogLevel;
+    eventAllowList?: readonly string[];
+    eventDenyList?: readonly string[];
+    sampleRate?: number;
+    maxBytes?: number;
+    maxFiles?: number;
+    schemaVersion?: string;
+}
+export declare function appendDaemonLog(logDir: string, entry: DaemonLogEntry, policy?: DaemonLogPolicy): Promise<void>;
 export declare function readDaemonLog(logDir: string): Promise<DaemonLogEntry[]>;
 //# sourceMappingURL=daemonLog.d.ts.map

package/dist/daemon/daemonLog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daemonLog.d.ts","sourceRoot":"","sources":["../../src/daemon/daemonLog.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,cAAc,EAAE,CAAC,CAY3B"}
+{"version":3,"file":"daemonLog.d.ts","sourceRoot":"","sources":["../../src/daemon/daemonLog.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAE3E,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAsED,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,EACrB,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,cAAc,EAAE,CAAC,CAY3B"}

package/dist/daemon/daemonLog.js

@@ -42,10 +42,86 @@ exports.appendDaemonLog = appendDaemonLog;
 exports.readDaemonLog = readDaemonLog;
 const node_fs_1 = require("node:fs");
 const path = __importStar(require("node:path"));
-async function appendDaemonLog(logDir, entry) {
+const DEFAULT_SCHEMA_VERSION = "2026.05.daemon-log-v1";
+const LEVEL_RANK = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    fatal: 50,
+};
+function shouldWriteEntry(entry, policy) {
+    if (!policy)
+        return true;
+    if (policy.eventAllowList && !policy.eventAllowList.includes(entry.event)) {
+        return false;
+    }
+    if (policy.eventDenyList?.includes(entry.event)) {
+        return false;
+    }
+    const minLevel = policy.minLevel;
+    if (minLevel) {
+        const entryLevel = entry.level ?? "info";
+        if (LEVEL_RANK[entryLevel] < LEVEL_RANK[minLevel]) {
+            return false;
+        }
+    }
+    const sampleRate = policy.sampleRate;
+    if (sampleRate !== undefined) {
+        if (sampleRate <= 0)
+            return false;
+        if (sampleRate < 1 && deterministicSample(entry, sampleRate) === false) {
+            return false;
+        }
+    }
+    return true;
+}
+function deterministicSample(entry, sampleRate) {
+    const key = `${entry.timestamp}:${entry.event}:${entry.correlationId ?? ""}:${entry.traceId ?? ""}`;
+    let hash = 0;
+    for (let i = 0; i < key.length; i++) {
+        hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
+    }
+    return hash / 0xffffffff < sampleRate;
+}
+async function rotateIfNeeded(logPath, nextLineBytes, policy) {
+    const maxBytes = policy?.maxBytes ?? 0;
+    if (maxBytes <= 0)
+        return;
+    let currentSize = 0;
+    try {
+        currentSize = (await node_fs_1.promises.stat(logPath)).size;
+    }
+    catch {
+        return;
+    }
+    if (currentSize + nextLineBytes <= maxBytes)
+        return;
+    const maxFiles = Math.max(1, policy?.maxFiles ?? 1);
+    for (let index = maxFiles - 1; index >= 1; index--) {
+        const from = `${logPath}.${index}`;
+        const to = `${logPath}.${index + 1}`;
+        await node_fs_1.promises.rename(from, to).catch(() => { });
+    }
+    await node_fs_1.promises.rename(logPath, `${logPath}.1`).catch(() => { });
+}
+async function appendDaemonLog(logDir, entry, policy) {
+    if (!shouldWriteEntry(entry, policy))
+        return;
     await node_fs_1.promises.mkdir(logDir, { recursive: true });
     const logPath = path.join(logDir, "daemon.jsonl");
-    const line = JSON.stringify(entry) + "\n";
+    const serializedEntry = {
+        ...entry,
+        ...(policy?.schemaVersion && !entry.schemaVersion
+            ? { schemaVersion: policy.schemaVersion }
+            : {}),
+        ...(policy?.sampleRate !== undefined ? { sampled: true } : {}),
+    };
+    if (policy && !serializedEntry.schemaVersion) {
+        serializedEntry.schemaVersion = DEFAULT_SCHEMA_VERSION;
+    }
+    const line = JSON.stringify(serializedEntry) + "\n";
+    await rotateIfNeeded(logPath, Buffer.byteLength(line), policy);
     await node_fs_1.promises.appendFile(logPath, line, "utf-8");
 }
 async function readDaemonLog(logDir) {

package/dist/daemon/index.d.ts

@@ -8,6 +8,6 @@ export { appendDaemonLog, readDaemonLog } from "./daemonLog";
 export type { DaemonConfig, DaemonStartOptions, DaemonStartOutput, DaemonStopOptions, DaemonStopOutput, DaemonStatusOptions, DaemonStatusOutput, DaemonMetadata, TriggerConfig, TriggerEvent, FileTriggerEvent, AutomationTriggerEvent, FileTriggerConfig, FileWatcherHandle, WebhookListenerOptions, WebhookListenerHandle, TriggerCallback, } from "./types";
 export type { TimerSchedulerHandle } from "./timerScheduler";
 export type { DaemonLoopOptions, DaemonLoopStatus } from "./loop";
-export type { DaemonLogEntry } from "./daemonLog";
+export type { DaemonLogEntry, DaemonLogLevel, DaemonLogPolicy } from "./daemonLog";
 export type { ApiResult } from "../apiResult";
 //# sourceMappingURL=index.d.ts.map

package/dist/daemon/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/daemon/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7D,YAAY,EACV,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,GAChB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAClE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/daemon/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7D,YAAY,EACV,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,GAChB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAClE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnF,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}

package/dist/observability/diagnostics.d.ts

@@ -0,0 +1,25 @@
+import type { DaemonConfig } from "../daemon/types";
+import type { DaemonLoopStatus } from "../daemon/loop";
+import type { RunHealthSnapshot } from "./types";
+export type DiagnosticsRequestPath = "/health" | "/metrics" | "/config" | "/queue";
+export interface DiagnosticsContext {
+    health: RunHealthSnapshot;
+    queue?: DaemonLoopStatus | null;
+    config?: DaemonConfig | Record<string, unknown> | null;
+}
+export interface DiagnosticsSnapshot {
+    health: RunHealthSnapshot;
+    metrics: string;
+    config: unknown;
+    queue: DaemonLoopStatus | null;
+}
+export interface DiagnosticsResponse {
+    status: number;
+    contentType: string;
+    body: unknown;
+}
+export declare function redactDiagnosticsConfig(value: unknown): unknown;
+export declare function buildDiagnosticsSnapshot(context: DiagnosticsContext): DiagnosticsSnapshot;
+export declare function renderPrometheusMetrics(context: Pick<DiagnosticsContext, "health" | "queue">): string;
+export declare function handleDiagnosticsRequest(requestPath: DiagnosticsRequestPath, context: DiagnosticsContext): DiagnosticsResponse;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/observability/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/observability/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEnF,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACxD;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;CACf;AAID,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AAmBD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,kBAAkB,GAAG,mBAAmB,CAQzF;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,MAAM,CA0BrG;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,sBAAsB,EACnC,OAAO,EAAE,kBAAkB,GAC1B,mBAAmB,CAuBrB"}

package/dist/observability/diagnostics.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactDiagnosticsConfig = redactDiagnosticsConfig;
+exports.buildDiagnosticsSnapshot = buildDiagnosticsSnapshot;
+exports.renderPrometheusMetrics = renderPrometheusMetrics;
+exports.handleDiagnosticsRequest = handleDiagnosticsRequest;
+const SECRET_KEY_PATTERN = /(secret|token|api[-_]?key|authorization|password|credential|private[-_]?key)/i;
+function redactDiagnosticsConfig(value) {
+    return redactValue(value, "");
+}
+function redactValue(value, key) {
+    if (SECRET_KEY_PATTERN.test(key)) {
+        return "[REDACTED]";
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redactValue(item, ""));
+    }
+    if (value && typeof value === "object") {
+        const result = {};
+        for (const [childKey, childValue] of Object.entries(value)) {
+            result[childKey] = redactValue(childValue, childKey);
+        }
+        return result;
+    }
+    return value;
+}
+function buildDiagnosticsSnapshot(context) {
+    const queue = context.queue ?? null;
+    return {
+        health: context.health,
+        queue,
+        config: redactDiagnosticsConfig(context.config ?? null),
+        metrics: renderPrometheusMetrics({ health: context.health, queue }),
+    };
+}
+function renderPrometheusMetrics(context) {
+    const metrics = context.health.metrics;
+    const lines = [
+        "# HELP babysitter_run_effect_latency_ms Run effect latency in milliseconds.",
+        "# TYPE babysitter_run_effect_latency_ms gauge",
+        `babysitter_run_effect_latency_ms{quantile="avg"} ${metrics.avgEffectLatencyMs}`,
+        `babysitter_run_effect_latency_ms{quantile="0.5"} ${metrics.p50EffectLatencyMs}`,
+        `babysitter_run_effect_latency_ms{quantile="0.95"} ${metrics.p95EffectLatencyMs}`,
+        `babysitter_run_effect_latency_ms{quantile="0.99"} ${metrics.p99EffectLatencyMs}`,
+        "# HELP babysitter_run_effects_total Run effects by state.",
+        "# TYPE babysitter_run_effects_total gauge",
+        `babysitter_run_effects_total{state="total"} ${metrics.totalEffects}`,
+        `babysitter_run_effects_total{state="resolved"} ${metrics.resolvedEffects}`,
+        `babysitter_run_effects_total{state="failed"} ${metrics.failedEffects}`,
+        `babysitter_run_effects_total{state="pending"} ${metrics.pendingCount}`,
+        "# HELP babysitter_run_error_rate Run effect error rate.",
+        "# TYPE babysitter_run_error_rate gauge",
+        `babysitter_run_error_rate ${metrics.errorRate}`,
+        "# HELP babysitter_daemon_queue_active_runs Active daemon runs.",
+        "# TYPE babysitter_daemon_queue_active_runs gauge",
+        `babysitter_daemon_queue_active_runs ${context.queue?.activeRuns ?? 0}`,
+        "# HELP babysitter_daemon_queue_pending_runs Pending daemon runs.",
+        "# TYPE babysitter_daemon_queue_pending_runs gauge",
+        `babysitter_daemon_queue_pending_runs ${context.queue?.pendingRuns ?? 0}`,
+    ];
+    return `${lines.join("\n")}\n`;
+}
+function handleDiagnosticsRequest(requestPath, context) {
+    switch (requestPath) {
+        case "/health":
+            return { status: 200, contentType: "application/json", body: context.health };
+        case "/metrics":
+            return {
+                status: 200,
+                contentType: "text/plain; version=0.0.4",
+                body: renderPrometheusMetrics({ health: context.health, queue: context.queue }),
+            };
+        case "/config":
+            return {
+                status: 200,
+                contentType: "application/json",
+                body: redactDiagnosticsConfig(context.config ?? null),
+            };
+        case "/queue":
+            return {
+                status: 200,
+                contentType: "application/json",
+                body: context.queue ?? null,
+            };
+    }
+}

package/dist/observability/health.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/observability/health.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EACV,iBAAiB,EAGjB,YAAY,EACb,MAAM,SAAS,CAAC;AAiBjB,UAAU,aAAa;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/B,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,YAAY,EAAE,EACtB,OAAO,CAAC,EAAE,aAAa,GACtB,iBAAiB,CAiInB"}
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/observability/health.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EACV,iBAAiB,EAGjB,YAAY,EACb,MAAM,SAAS,CAAC;AAiBjB,UAAU,aAAa;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/B,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,YAAY,EAAE,EACtB,OAAO,CAAC,EAAE,aAAa,GACtB,iBAAiB,CA0InB"}

package/dist/observability/health.js

@@ -28,6 +28,7 @@ function computeRunHealthFromEvents(events, options) {
     let failedEffects = 0;
     let totalLatency = 0;
     let latencyCount = 0;
+    const latencies = [];
     let lastActivityAt = null;
     let hasRunFailed = false;
     const iterations = new Set();
@@ -53,8 +54,10 @@ function computeRunHealthFromEvents(events, options) {
                 resolvedEffects.add(effectId);
                 const reqTs = requestedAt.get(effectId);
                 if (reqTs != null) {
-                    totalLatency += ts - reqTs;
+                    const latency = ts - reqTs;
+                    totalLatency += latency;
                     latencyCount++;
+                    latencies.push(latency);
                 }
                 const status = typeof event.data.status === "string" ? event.data.status : undefined;
                 if (status === "error") {
@@ -69,6 +72,9 @@ function computeRunHealthFromEvents(events, options) {
     const pendingCount = totalEffects - resolvedCount;
     const errorRate = resolvedCount > 0 ? failedEffects / resolvedCount : 0;
     const avgEffectLatencyMs = latencyCount > 0 ? Math.round(totalLatency / latencyCount) : 0;
+    const p50EffectLatencyMs = percentile(latencies, 0.5);
+    const p95EffectLatencyMs = percentile(latencies, 0.95);
+    const p99EffectLatencyMs = percentile(latencies, 0.99);
     // Oldest pending effect age
     let oldestPendingAgeMs = 0;
     for (const [effectId, reqTs] of requestedAt) {
@@ -82,6 +88,9 @@ function computeRunHealthFromEvents(events, options) {
     const metrics = {
         errorRate,
         avgEffectLatencyMs,
+        p50EffectLatencyMs,
+        p95EffectLatencyMs,
+        p99EffectLatencyMs,
         pendingCount,
         oldestPendingAgeMs,
         iterationCount: iterations.size,
@@ -127,3 +136,10 @@ function computeRunHealthFromEvents(events, options) {
         computedAt: new Date(now).toISOString(),
     };
 }
+function percentile(values, quantile) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const rank = Math.max(1, Math.ceil(quantile * sorted.length));
+    return Math.round(sorted[rank - 1]);
+}

package/dist/observability/index.d.ts

@@ -3,4 +3,5 @@ export { computeRunHealthFromEvents } from "./health";
 export { getRunHealthSnapshot, getOrchestrationStatus, getPendingWorkItems, type OrchestrationStatus, type OrchestrationPhase, type PendingWorkItem, } from "./runStatus";
 export type { PhaseTimeline, PhaseEntry, PhaseName, Milestone, IterationTimeline, RunHealthSnapshot, RunHealthStatus, RunHealthMetrics, HealthConfig, } from "./types";
 export { registerWebhook, unregisterWebhook, listWebhooks, buildWebhookEvent, evaluateAlertLevel, filterRegistrations, type AlertLevel, type WebhookEventType, type WebhookRegistration, type WebhookEvent, type WebhookDeliveryResult, type WebhookRegistry, type WebhookRegistrationInput, WEBHOOK_SCHEMA_VERSION, } from "./webhooks";
+export { buildDiagnosticsSnapshot, handleDiagnosticsRequest, redactDiagnosticsConfig, renderPrometheusMetrics, type DiagnosticsContext, type DiagnosticsRequestPath, type DiagnosticsResponse, type DiagnosticsSnapshot, } from "./diagnostics";
 //# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,aAAa,EACb,UAAU,EACV,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,sBAAsB,GACvB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,aAAa,EACb,UAAU,EACV,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAC"}

package/dist/observability/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WEBHOOK_SCHEMA_VERSION = exports.filterRegistrations = exports.evaluateAlertLevel = exports.buildWebhookEvent = exports.listWebhooks = exports.unregisterWebhook = exports.registerWebhook = exports.getPendingWorkItems = exports.getOrchestrationStatus = exports.getRunHealthSnapshot = exports.computeRunHealthFromEvents = exports.buildPhaseTimelineFromEvents = exports.buildPhaseTimeline = void 0;
+exports.renderPrometheusMetrics = exports.redactDiagnosticsConfig = exports.handleDiagnosticsRequest = exports.buildDiagnosticsSnapshot = exports.WEBHOOK_SCHEMA_VERSION = exports.filterRegistrations = exports.evaluateAlertLevel = exports.buildWebhookEvent = exports.listWebhooks = exports.unregisterWebhook = exports.registerWebhook = exports.getPendingWorkItems = exports.getOrchestrationStatus = exports.getRunHealthSnapshot = exports.computeRunHealthFromEvents = exports.buildPhaseTimelineFromEvents = exports.buildPhaseTimeline = void 0;
 var timeline_1 = require("./timeline");
 Object.defineProperty(exports, "buildPhaseTimeline", { enumerable: true, get: function () { return timeline_1.buildPhaseTimeline; } });
 Object.defineProperty(exports, "buildPhaseTimelineFromEvents", { enumerable: true, get: function () { return timeline_1.buildPhaseTimelineFromEvents; } });
@@ -18,3 +18,8 @@ Object.defineProperty(exports, "buildWebhookEvent", { enumerable: true, get: fun
 Object.defineProperty(exports, "evaluateAlertLevel", { enumerable: true, get: function () { return webhooks_1.evaluateAlertLevel; } });
 Object.defineProperty(exports, "filterRegistrations", { enumerable: true, get: function () { return webhooks_1.filterRegistrations; } });
 Object.defineProperty(exports, "WEBHOOK_SCHEMA_VERSION", { enumerable: true, get: function () { return webhooks_1.WEBHOOK_SCHEMA_VERSION; } });
+var diagnostics_1 = require("./diagnostics");
+Object.defineProperty(exports, "buildDiagnosticsSnapshot", { enumerable: true, get: function () { return diagnostics_1.buildDiagnosticsSnapshot; } });
+Object.defineProperty(exports, "handleDiagnosticsRequest", { enumerable: true, get: function () { return diagnostics_1.handleDiagnosticsRequest; } });
+Object.defineProperty(exports, "redactDiagnosticsConfig", { enumerable: true, get: function () { return diagnostics_1.redactDiagnosticsConfig; } });
+Object.defineProperty(exports, "renderPrometheusMetrics", { enumerable: true, get: function () { return diagnostics_1.renderPrometheusMetrics; } });

package/dist/observability/types.d.ts

@@ -8,6 +8,9 @@ export type RunHealthStatus = "healthy" | "degraded" | "stuck" | "failed";
 export interface RunHealthMetrics {
     errorRate: number;
     avgEffectLatencyMs: number;
+    p50EffectLatencyMs: number;
+    p95EffectLatencyMs: number;
+    p99EffectLatencyMs: number;
     pendingCount: number;
     oldestPendingAgeMs: number;
     iterationCount: number;

package/dist/observability/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/observability/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC;IACxB,uFAAuF;IACvF,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,YAAY,CAAC;AAEjF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,YAAY,GAAG,cAAc,GAAG,eAAe,GAAG,YAAY,CAAC;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,YAAY,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACjD,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/observability/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC;IACxB,uFAAuF;IACvF,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,YAAY,CAAC;AAEjF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,YAAY,GAAG,cAAc,GAAG,eAAe,GAAG,YAAY,CAAC;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,YAAY,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACjD,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC"}

package/dist/telemetry/exporters.d.ts

@@ -0,0 +1,35 @@
+import type { TelemetryExporter, TelemetryExportResult, TelemetrySpan } from "./types";
+export declare class NoopTelemetryExporter implements TelemetryExporter {
+    export(spans: readonly TelemetrySpan[]): Promise<TelemetryExportResult>;
+    flush(): Promise<TelemetryExportResult>;
+}
+export declare class InMemoryTelemetryExporter implements TelemetryExporter {
+    private readonly spans;
+    export(spans: readonly TelemetrySpan[]): Promise<TelemetryExportResult>;
+    getSpans(): TelemetrySpan[];
+    clear(): void;
+}
+export declare class FileTelemetryExporter implements TelemetryExporter {
+    private readonly filePath;
+    constructor(filePath: string);
+    export(spans: readonly TelemetrySpan[]): Promise<TelemetryExportResult>;
+}
+export interface OtlpHttpTraceExporterOptions {
+    endpoint: string;
+    headers?: Record<string, string>;
+    fetch?: (input: string, init: {
+        method: string;
+        headers: Record<string, string>;
+        body: string;
+    }) => Promise<{
+        ok: boolean;
+        status: number;
+        text?: () => Promise<string>;
+    }>;
+}
+export declare class OtlpHttpTraceExporter implements TelemetryExporter {
+    private readonly options;
+    constructor(options: OtlpHttpTraceExporterOptions);
+    export(spans: readonly TelemetrySpan[]): Promise<TelemetryExportResult>;
+}
+//# sourceMappingURL=exporters.d.ts.map

package/dist/telemetry/exporters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporters.d.ts","sourceRoot":"","sources":["../../src/telemetry/exporters.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,qBAAa,qBAAsB,YAAW,iBAAiB;IACvD,MAAM,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIvE,KAAK,IAAI,OAAO,CAAC,qBAAqB,CAAC;CAG9C;AAED,qBAAa,yBAA0B,YAAW,iBAAiB;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAEvC,MAAM,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAK7E,QAAQ,IAAI,aAAa,EAAE;IAI3B,KAAK,IAAI,IAAI;CAGd;AAED,qBAAa,qBAAsB,YAAW,iBAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,MAAM;IAEvC,MAAM,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAQ9E;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE;QAC5B,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,IAAI,EAAE,MAAM,CAAC;KACd,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC,CAAC;CAC9E;AAED,qBAAa,qBAAsB,YAAW,iBAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,4BAA4B;IAE5D,MAAM,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAgC9E"}

package/dist/telemetry/exporters.js

@@ -0,0 +1,141 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OtlpHttpTraceExporter = exports.FileTelemetryExporter = exports.InMemoryTelemetryExporter = exports.NoopTelemetryExporter = void 0;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+class NoopTelemetryExporter {
+    async export(spans) {
+        return { ok: true, exported: spans.length };
+    }
+    async flush() {
+        return { ok: true, exported: 0 };
+    }
+}
+exports.NoopTelemetryExporter = NoopTelemetryExporter;
+class InMemoryTelemetryExporter {
+    spans = [];
+    async export(spans) {
+        this.spans.push(...spans.map(cloneSpan));
+        return { ok: true, exported: spans.length };
+    }
+    getSpans() {
+        return this.spans.map(cloneSpan);
+    }
+    clear() {
+        this.spans.length = 0;
+    }
+}
+exports.InMemoryTelemetryExporter = InMemoryTelemetryExporter;
+class FileTelemetryExporter {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async export(spans) {
+        await node_fs_1.promises.mkdir(path.dirname(this.filePath), { recursive: true });
+        const lines = spans.map((span) => JSON.stringify(span)).join("\n");
+        if (lines) {
+            await node_fs_1.promises.appendFile(this.filePath, `${lines}\n`, "utf-8");
+        }
+        return { ok: true, exported: spans.length };
+    }
+}
+exports.FileTelemetryExporter = FileTelemetryExporter;
+class OtlpHttpTraceExporter {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async export(spans) {
+        const fetchImpl = this.options.fetch ?? globalThis.fetch;
+        if (!fetchImpl) {
+            return { ok: false, exported: 0, error: "fetch is not available" };
+        }
+        try {
+            const response = await fetchImpl(this.options.endpoint, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...this.options.headers,
+                },
+                body: JSON.stringify({ resourceSpans: spans.map(toOtlpSpan) }),
+            });
+            if (!response.ok) {
+                const text = response.text ? await response.text() : "";
+                return {
+                    ok: false,
+                    exported: 0,
+                    error: `OTLP HTTP export failed with status ${response.status}${text ? `: ${text}` : ""}`,
+                };
+            }
+            return { ok: true, exported: spans.length };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                exported: 0,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+}
+exports.OtlpHttpTraceExporter = OtlpHttpTraceExporter;
+function cloneSpan(span) {
+    return {
+        ...span,
+        attributes: { ...span.attributes },
+        events: span.events.map((event) => ({
+            ...event,
+            attributes: event.attributes ? { ...event.attributes } : undefined,
+        })),
+    };
+}
+function toOtlpSpan(span) {
+    return {
+        traceId: span.traceId,
+        spanId: span.spanId,
+        parentSpanId: span.parentSpanId,
+        name: span.name,
+        startTimeUnixNano: Date.parse(span.startTime) * 1_000_000,
+        endTimeUnixNano: span.endTime ? Date.parse(span.endTime) * 1_000_000 : undefined,
+        status: { code: span.status },
+        attributes: Object.entries(span.attributes).map(([key, value]) => ({
+            key,
+            value,
+        })),
+        events: span.events,
+    };
+}

package/dist/telemetry/index.d.ts

@@ -2,8 +2,10 @@
  * Telemetry module — OpenTelemetry-aligned structured telemetry interfaces
  * and in-memory implementations.
  */
-export { TelemetrySpanStatus, type TelemetryEvent, type TelemetrySpan, type TelemetryProvider, type TelemetryConfig, } from "./types";
+export { TelemetrySpanStatus, type TelemetryEvent, type TelemetrySpan, type TelemetryProvider, type TelemetryConfig, type TraceContext, type TelemetrySpanStartOptions, type TelemetryExporter, type TelemetryExportResult, } from "./types";
 export { InMemoryTelemetryProvider } from "./provider";
 export { AuditLog, type AuditEntry, type AuditFilter, } from "./audit-log";
 export { SpanTree, type SpanTreeNode, type SerializedSpanTreeNode, } from "./span-tree";
+export { createTraceContext, parseTraceParent, serializeTraceParent, type CreateTraceContextOptions, } from "./traceContext";
+export { FileTelemetryExporter, InMemoryTelemetryExporter, NoopTelemetryExporter, OtlpHttpTraceExporter, type OtlpHttpTraceExporterOptions, } from "./exporters";
 //# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,EACL,QAAQ,EACR,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,GAC3B,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,EACL,QAAQ,EACR,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,yBAAyB,GAC/B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,aAAa,CAAC"}

package/dist/telemetry/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SpanTree = exports.AuditLog = exports.InMemoryTelemetryProvider = exports.TelemetrySpanStatus = void 0;
+exports.OtlpHttpTraceExporter = exports.NoopTelemetryExporter = exports.InMemoryTelemetryExporter = exports.FileTelemetryExporter = exports.serializeTraceParent = exports.parseTraceParent = exports.createTraceContext = exports.SpanTree = exports.AuditLog = exports.InMemoryTelemetryProvider = exports.TelemetrySpanStatus = void 0;
 /**
  * Telemetry module — OpenTelemetry-aligned structured telemetry interfaces
  * and in-memory implementations.
@@ -13,3 +13,12 @@ var audit_log_1 = require("./audit-log");
 Object.defineProperty(exports, "AuditLog", { enumerable: true, get: function () { return audit_log_1.AuditLog; } });
 var span_tree_1 = require("./span-tree");
 Object.defineProperty(exports, "SpanTree", { enumerable: true, get: function () { return span_tree_1.SpanTree; } });
+var traceContext_1 = require("./traceContext");
+Object.defineProperty(exports, "createTraceContext", { enumerable: true, get: function () { return traceContext_1.createTraceContext; } });
+Object.defineProperty(exports, "parseTraceParent", { enumerable: true, get: function () { return traceContext_1.parseTraceParent; } });
+Object.defineProperty(exports, "serializeTraceParent", { enumerable: true, get: function () { return traceContext_1.serializeTraceParent; } });
+var exporters_1 = require("./exporters");
+Object.defineProperty(exports, "FileTelemetryExporter", { enumerable: true, get: function () { return exporters_1.FileTelemetryExporter; } });
+Object.defineProperty(exports, "InMemoryTelemetryExporter", { enumerable: true, get: function () { return exporters_1.InMemoryTelemetryExporter; } });
+Object.defineProperty(exports, "NoopTelemetryExporter", { enumerable: true, get: function () { return exporters_1.NoopTelemetryExporter; } });
+Object.defineProperty(exports, "OtlpHttpTraceExporter", { enumerable: true, get: function () { return exporters_1.OtlpHttpTraceExporter; } });

package/dist/telemetry/provider.d.ts

@@ -4,7 +4,7 @@
  *
  * Stores spans in memory and supports flush/drain for export pipelines.
  */
-import type { TelemetryProvider, TelemetrySpan, TelemetryEvent } from "./types";
+import type { TelemetryProvider, TelemetrySpan, TelemetryEvent, TelemetrySpanStartOptions } from "./types";
 import { TelemetrySpanStatus } from "./types";
 /**
  * In-memory telemetry provider that satisfies the TelemetryProvider interface.
@@ -23,6 +23,7 @@ export declare class InMemoryTelemetryProvider implements TelemetryProvider {
     /** Maps spanId -> traceId so child spans inherit the parent's trace. */
     private readonly traceIndex;
     startSpan(name: string, parentSpanId?: string): Promise<TelemetrySpan>;
+    startSpan(name: string, options?: TelemetrySpanStartOptions): Promise<TelemetrySpan>;
     endSpan(spanId: string, status?: TelemetrySpanStatus): Promise<void>;
     recordEvent(spanId: string, event: TelemetryEvent): Promise<void>;
     flush(): Promise<void>;

package/dist/telemetry/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/telemetry/provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACf,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAwB9C;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,YAAW,iBAAiB;IACjE,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IAIlD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA4BtE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAapE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IASjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAMvC,gEAAgE;IAChE,cAAc,IAAI,aAAa,EAAE;CAGlC"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/telemetry/provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAwB9C;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,YAAW,iBAAiB;IACjE,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IAIlD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IACtE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,aAAa,CAAC;IA2CpF,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAapE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IASjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAMvC,gEAAgE;IAChE,cAAc,IAAI,aAAa,EAAE;CAGlC"}

package/dist/telemetry/provider.js

@@ -28,11 +28,17 @@ class InMemoryTelemetryProvider {
     completed = [];
     /** Maps spanId -> traceId so child spans inherit the parent's trace. */
     traceIndex = new Map();
-    // ---------- TelemetryProvider interface ----------
-    async startSpan(name, parentSpanId) {
+    async startSpan(name, optionsOrParentSpanId) {
         const spanId = (0, node_crypto_1.randomUUID)();
+        const options = typeof optionsOrParentSpanId === "string"
+            ? { parentSpanId: optionsOrParentSpanId }
+            : optionsOrParentSpanId;
+        const parentSpanId = options?.traceContext?.spanId ?? options?.parentSpanId;
         let traceId;
-        if (parentSpanId) {
+        if (options?.traceContext) {
+            traceId = options.traceContext.traceId;
+        }
+        else if (parentSpanId) {
             // Inherit traceId from the parent span.
             traceId = this.traceIndex.get(parentSpanId) ?? (0, node_crypto_1.randomUUID)();
         }
@@ -46,7 +52,15 @@ class InMemoryTelemetryProvider {
             parentSpanId,
             startTime: new Date().toISOString(),
             status: types_1.TelemetrySpanStatus.Unset,
-            attributes: {},
+            attributes: {
+                ...options?.attributes,
+                ...(options?.correlationId
+                    ? { "babysitter.correlation_id": options.correlationId }
+                    : {}),
+                ...(options?.traceContext?.correlationId && !options?.correlationId
+                    ? { "babysitter.correlation_id": options.traceContext.correlationId }
+                    : {}),
+            },
             events: [],
         };
         this.active.set(spanId, span);

package/dist/telemetry/traceContext.d.ts

@@ -0,0 +1,10 @@
+import type { TraceContext } from "./types";
+export declare function parseTraceParent(header: string): TraceContext | null;
+export declare function serializeTraceParent(context: TraceContext): string;
+export interface CreateTraceContextOptions {
+    parent?: TraceContext;
+    correlationId?: string;
+    sampled?: boolean;
+}
+export declare function createTraceContext(options?: CreateTraceContextOptions): TraceContext;
+//# sourceMappingURL=traceContext.d.ts.map

package/dist/telemetry/traceContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceContext.d.ts","sourceRoot":"","sources":["../../src/telemetry/traceContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAQ5C,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAQpE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAElE;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,yBAAyB,GAAG,YAAY,CAYpF"}

package/dist/telemetry/traceContext.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTraceParent = parseTraceParent;
+exports.serializeTraceParent = serializeTraceParent;
+exports.createTraceContext = createTraceContext;
+const node_crypto_1 = require("node:crypto");
+const TRACEPARENT_PATTERN = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+function allZero(value) {
+    return /^0+$/.test(value);
+}
+function parseTraceParent(header) {
+    const match = TRACEPARENT_PATTERN.exec(header.trim());
+    if (!match)
+        return null;
+    const [, version, traceId, spanId, traceFlags] = match;
+    if (version !== "00" || allZero(traceId) || allZero(spanId)) {
+        return null;
+    }
+    return { version, traceId, spanId, traceFlags };
+}
+function serializeTraceParent(context) {
+    return `${context.version}-${context.traceId}-${context.spanId}-${context.traceFlags}`;
+}
+function createTraceContext(options) {
+    const traceId = options?.parent?.traceId ?? randomHex(16);
+    const spanId = randomHex(8);
+    const traceFlags = options?.sampled === false ? "00" : options?.parent?.traceFlags ?? "01";
+    return {
+        version: "00",
+        traceId,
+        spanId,
+        traceFlags,
+        parentSpanId: options?.parent?.spanId,
+        correlationId: options?.correlationId ?? options?.parent?.correlationId,
+    };
+}
+function randomHex(bytes) {
+    let value = (0, node_crypto_1.randomBytes)(bytes).toString("hex");
+    while (allZero(value)) {
+        value = (0, node_crypto_1.randomBytes)(bytes).toString("hex");
+    }
+    return value;
+}

package/dist/telemetry/types.d.ts

@@ -42,6 +42,20 @@ export interface TelemetrySpan {
     /** Discrete events recorded during the span's lifetime. */
     readonly events: TelemetryEvent[];
 }
+export interface TraceContext {
+    readonly version: "00";
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly traceFlags: string;
+    readonly parentSpanId?: string;
+    readonly correlationId?: string;
+}
+export interface TelemetrySpanStartOptions {
+    readonly parentSpanId?: string;
+    readonly traceContext?: TraceContext;
+    readonly correlationId?: string;
+    readonly attributes?: Record<string, string | number | boolean>;
+}
 /** Abstraction over a telemetry backend (e.g. OTLP exporter, console, no-op). */
 export interface TelemetryProvider {
     /**
@@ -52,6 +66,7 @@ export interface TelemetryProvider {
      * @returns The newly created span.
      */
     startSpan(name: string, parentSpanId?: string): Promise<TelemetrySpan>;
+    startSpan(name: string, options?: TelemetrySpanStartOptions): Promise<TelemetrySpan>;
     /**
      * End an in-flight span.
      *
@@ -82,4 +97,13 @@ export interface TelemetryConfig {
     /** Named exporters to send telemetry data to (e.g. "otlp", "console", "file"). */
     readonly exporters?: string[];
 }
+export interface TelemetryExportResult {
+    readonly ok: boolean;
+    readonly exported: number;
+    readonly error?: string;
+}
+export interface TelemetryExporter {
+    export(spans: readonly TelemetrySpan[]): Promise<TelemetryExportResult>;
+    flush?(): Promise<TelemetryExportResult>;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/telemetry/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/telemetry/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,yEAAyE;AACzE,oBAAY,mBAAmB;IAC7B,wCAAwC;IACxC,EAAE,OAAO;IACT,oCAAoC;IACpC,KAAK,UAAU;IACf,oDAAoD;IACpD,KAAK,UAAU;CAChB;AAMD,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACjE;AAMD,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAC/D,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;CACnC;AAMD,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAEvE;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IACtC,yDAAyD;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/telemetry/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,yEAAyE;AACzE,oBAAY,mBAAmB;IAC7B,wCAAwC;IACxC,EAAE,OAAO;IACT,oCAAoC;IACpC,KAAK,UAAU;IACf,oDAAoD;IACpD,KAAK,UAAU;CAChB;AAMD,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACjE;AAMD,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAC/D,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACjE;AAMD,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACvE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAErF;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IACtC,yDAAyD;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACxE,KAAK,CAAC,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC1C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a5c-ai/agent-runtime",
-  "version": "5.0.1-staging.04ca6ab00d21",
+  "version": "5.0.1-staging.40a93c240e7b",
   "description": "Agent runtime layer (L5) — daemon, session, resource management, telemetry",
   "license": "MIT",
   "type": "commonjs",
@@ -32,6 +32,11 @@
       "require": "./dist/observability/index.js",
       "default": "./dist/observability/index.js"
     },
+    "./telemetry": {
+      "types": "./dist/telemetry/index.d.ts",
+      "require": "./dist/telemetry/index.js",
+      "default": "./dist/telemetry/index.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {
@@ -47,6 +52,9 @@
       ],
       "observability": [
         "dist/observability/index.d.ts"
+      ],
+      "telemetry": [
+        "dist/telemetry/index.d.ts"
       ]
     }
   },
@@ -63,8 +71,8 @@
     "test": "vitest run --config vitest.config.ts"
   },
   "dependencies": {
-    "@a5c-ai/agent-comm-mux": "5.0.1-staging.04ca6ab00d21",
-    "@a5c-ai/babysitter-sdk": "5.0.1-staging.04ca6ab00d21"
+    "@a5c-ai/agent-comm-mux": "5.0.1-staging.40a93c240e7b",
+    "@a5c-ai/babysitter-sdk": "5.0.1-staging.40a93c240e7b"
   },
   "devDependencies": {
     "@types/node": "^20.11.30",