@anuma/sdk 6.33.1 → 6.34.0

package/dist/telemetry/index.cjs

@@ -213,16 +213,7 @@ function createRecallDiagnosticsHandler(sink) {
       usedBudget: diagnostics.usedBudget,
       reranked: diagnostics.reranked,
       candidateCount: diagnostics.candidateCount,
-      // What the caller actually GOT. `candidateCount` is what was considered,
-      // and the two are routinely far apart — the fact lane pulls `limit * 2`
-      // when fusing — so a consumer reading candidateCount as "memories this
-      // turn received" overcounts.
       admittedCount: diagnostics.admittedCount,
-      // Both ends of the admitted range, and the lane counts, ride the EVENT as
-      // well as the metrics: a track-only sink is a supported configuration
-      // (the module's own PostHog example is exactly that shape), and it could
-      // otherwise see neither the bottom of the score range nor which side lane
-      // contributed.
       topScore: diagnostics.topScore,
       lowestAdmittedScore: diagnostics.lowestAdmittedScore,
       minScoreApplied: diagnostics.minScoreApplied,

package/dist/telemetry/index.d.mts

@@ -96,17 +96,6 @@ type LlmapiChatCompletionTool = {
     [key: string]: unknown;
 };
 
-/**
- * Lifecycle hooks for runToolLoop. All hooks are optional and observer
- * errors are swallowed (sync throws and async rejections both) so a buggy
- * hook can't crash the loop. Hook names match the Claude Agent SDK shape
- * (camelCase).
- *
- * Hooks are awaited synchronously at each fire site, so slow hooks
- * serialize into loop latency — keep them fast and do any heavy work
- * (network exports, file IO) asynchronously inside your own queue.
- */
-
 type LlmTokenUsage = {
     inputTokens?: number;
     outputTokens?: number;
@@ -228,156 +217,6 @@ type RunHooks = {
     afterToolUse?: (e: ToolUseEndEvent) => Promise<void> | void;
 };
 
-/**
- * Telemetry sink contract for the observability adapter.
- *
- * The SDK never talks to a vendor directly — it emits structured events and
- * metrics through this interface, and the app adapts it to PostHog, Datadog,
- * OpenTelemetry, etc. Both methods are optional so a sink that only cares
- * about events (or only about metrics) can implement half the surface.
- *
- * Implementations must be fast and must not throw: hooks are awaited
- * synchronously inside the tool loop (see `runHooks.ts`), so a slow or
- * throwing sink serializes into run latency or — worse — surfaces as a run
- * error. Queue network exports asynchronously inside your sink.
- *
- * @example
- * ```ts
- * import { createMetricsHooks, type TelemetrySink } from "@anuma/sdk/telemetry";
- *
- * // posthog-js: capture(event, properties)
- * const sink: TelemetrySink = {
- *   track: (event, properties) => posthog.capture(event, properties),
- *   metric: (name, value, tags) => statsd.histogram(name, value, tags),
- * };
- *
- * // posthog-node takes ONE object, so the arguments do not line up:
- * // track: (event, properties) => posthog.capture({ distinctId, event, properties })
- *
- * const hooks = createMetricsHooks(sink);
- * // pass `hooks` wherever RunHooks are accepted, or compose with your own:
- * // composeHooks([hooks, myTracingHooks])
- * ```
- */
-interface TelemetrySink {
-    /**
-     * Record a discrete event (run started, tool failed, recall degraded…).
-     * `properties` are flat, JSON-serializable, and free of message contents —
-     * only identifiers, counts, and timings.
-     */
-    track?: (event: string, properties: Record<string, unknown>) => void;
-    /**
-     * Record a numeric measurement (latency, duration, token count). `tags`
-     * are low-cardinality string dimensions (model, toolName, outcome, lane).
-     */
-    metric?: (name: string, value: number, tags: Record<string, string>) => void;
-}
-/**
- * Default sink that discards everything. Useful as a fallback when telemetry
- * is configured off, and as the base for sinks that override one method.
- *
- * Frozen. It is a published singleton, and `createMetricsHooks` closes over the
- * object rather than its methods, so one module assigning `noopTelemetrySink.track`
- * would reroute every already-constructed adapter that shares the reference — a
- * test stub that forgets to restore changes behaviour for the rest of the suite.
- * Freezing now rather than later: adding it later is the breaking direction,
- * because it turns a silent assignment into a strict-mode TypeError.
- */
-declare const noopTelemetrySink: TelemetrySink;
-
-/**
- * {@link RunHooks} adapter that turns tool-loop lifecycle hooks into
- * telemetry events and metrics on a {@link TelemetrySink}.
- *
- * Events emitted (all with `runId`; no message contents or tool arguments):
- *
- * - `run.started` — `{ runId, model }`
- * - `run.completed` — `{ runId, totalSteps, durationMs }`
- * - `run.failed` — `{ runId, durationMs, errorType, stage }`
- * - `model.call.completed` — `{ runId, stepIndex, latencyMs, model?, inputTokens?, outputTokens?, finishReason? }`
- * - `model.call.failed` — `{ runId, stepIndex, latencyMs, model? }`
- * - `tool.call.completed` — `{ runId, stepIndex, toolCallId, toolName, durationMs }`
- * - `tool.call.failed` — `{ runId, stepIndex, toolCallId, toolName, durationMs, errorType }`
- *
- * The raw `error` message string is NOT reported unless the caller opts in
- * with {@link MetricsHooksOptions.includeErrorMessages} — see that option for
- * why. `errorType` is always safe and always reported where the source event
- * carries one.
- *
- * Metrics emitted:
- *
- * - `run.duration` (ms, tags: model?, outcome)
- * - `model.call.latency` (ms, tags: model?, outcome)
- * - `model.call.tokens` (count, tags: direction: input|output) when usage is present
- * - `tool.call.duration` (ms, tags: toolName, outcome, errorType?)
- *
- * Pairing notes (mirrors the contract documented in `runHooks.ts`):
- *
- * - `onRunEnd` / `onRunError` are mutually exclusive and fire exactly once per
- *   run, so every started run resolves to exactly one terminal event.
- * - Server-side tools routed via `onToolCall` get `beforeToolUse` with no
- *   `afterToolUse`. The adapter therefore never emits a completion for a tool
- *   it saw only start; the pending timer is dropped when the run terminates.
- * - `afterToolUse` without a matching `beforeToolUse` (defensive — not a
- *   documented case) is still reported, with `durationMs` omitted.
- * - Per-run state is keyed by `runId` and cleared on the terminal hook, so
- *   concurrent runs and long-lived adapter instances do not leak timers. The
- *   `after*` hooks read that state without creating it, so a hook arriving
- *   after the terminal one cannot resurrect an entry nothing would delete
- *   again.
- */
-
-interface MetricsHooksOptions {
-    /**
-     * Override the clock used for every duration this adapter reports.
-     *
-     * The default is monotonic where the runtime has `performance.now()`
-     * (browser / RN / Node), falling back to `Date.now()`. That is about
-     * monotonicity, not precision: `Date.now()` steps BACKWARD on an NTP
-     * correction, a VM resume from snapshot, or a container host clock sync, and
-     * a step landing mid-run makes `now() - startedAt` negative. dogstatsd
-     * accepts a negative histogram sample, so it is ingested and corrupts the
-     * min/p50/p95 for that bucket — silently wrong data, which is the one thing
-     * this module exists to prevent.
-     *
-     * Supply your own only to make durations deterministic in a test.
-     */
-    now?: () => number;
-    /**
-     * Report the raw `error` message string on `run.failed`,
-     * `model.call.failed`, and `tool.call.failed`. Default `false`.
-     *
-     * Off by default because those strings are free text and routinely quote
-     * the input that caused the failure. `JSON.parse` echoes the offending tool
-     * arguments verbatim (`Unexpected token 'h', "hunter2pass"... is not valid
-     * JSON`), `executeToolCall` wraps whatever a host executor threw, and an
-     * executor with `deAnonymizeArgs` runs on de-redacted PII. Sending them to
-     * a sink contradicts {@link TelemetrySink}, which states that properties
-     * carry only identifiers, counts, and timings.
-     *
-     * Turn it on when the sink is infrastructure you own and you accept the
-     * exposure. Prefer `errorType`, which is always reported and always safe.
-     */
-    includeErrorMessages?: boolean;
-}
-/**
- * Build {@link RunHooks} that report run lifecycle, model calls, and tool
- * calls to `sink`. The returned hooks are synchronous and never throw — a
- * throwing sink method is swallowed with a console-free `noop` (the tool loop
- * already swallows hook errors; we avoid double-logging here).
- */
-declare function createMetricsHooks(sink: TelemetrySink, opts?: MetricsHooksOptions): RunHooks;
-
-/**
- * Unified memory layer types — the Recall / Retain API.
- *
- * This module defines the public surface for the new unified memory layer
- * that sits above `memoryVault` (curated facts) and `memoryEngine` (raw
- * conversation chunks). Callers should prefer these types over the legacy
- * `VaultSearchResult` / `ChunkSearchResult` shapes; the underlying stores
- * may converge later, the API will not.
- */
-
 /**
  * Budget controls retrieval depth/cost. Higher budgets enable more
  * candidate sources and the cross-encoder reranker.
@@ -594,51 +433,101 @@ interface RecallDiagnostics {
 }
 
 /**
- * Adapter that turns {@link RecallDiagnostics} (the `onDiagnostics` hook on
- * {@link RecallOptions}) into telemetry events and metrics on a
- * {@link TelemetrySink}.
+ * Telemetry sink contract for the observability adapter.
  *
- * Events emitted:
+ * The SDK never talks to a vendor directly — it emits structured events and
+ * metrics through this interface, and the app adapts it to PostHog, Datadog,
+ * OpenTelemetry, etc. Both methods are optional so a sink that only cares
+ * about events (or only about metrics) can implement half the surface.
  *
- * - `recall.completed` — once per `recall()` call with budget, lane counts,
- *   and whether the cross-encoder reranked.
- * - `recall.degraded` — once per entry in `diagnostics.degraded`, with the
- *   degradation reason. A clean recall emits none.
+ * Implementations must be fast and must not throw: hooks are awaited
+ * synchronously inside the tool loop (see `runHooks.ts`), so a slow or
+ * throwing sink serializes into run latency or — worse — surfaces as a run
+ * error. Queue network exports asynchronously inside your sink.
  *
- * Metrics emitted (all tagged `lane`):
+ * @example
+ * ```ts
+ * import { createMetricsHooks, type TelemetrySink } from "@anuma/sdk/telemetry";
  *
- * - `recall.duration` (ms) for each timing lane: `total`, `prep`, `factLane`,
- *   `rerank`, `queryEmbed`, `chunkLane`, `fuse`. `rerank` and `queryEmbed`
- *   are SUBSETS of `factLane` — do not sum the lanes.
- * - `recall.candidates` (count), `recall.facts` (count), `recall.chunks` (count)
- * - `recall.vault.size`, `recall.vault.rows_decrypted`,
- *   `recall.vault.rows_embedded` when the fact lane reported them.
+ * // posthog-js: capture(event, properties)
+ * const sink: TelemetrySink = {
+ *   track: (event, properties) => posthog.capture(event, properties),
+ *   metric: (name, value, tags) => statsd.histogram(name, value, tags),
+ * };
  *
- * COVERAGE — this handler only sees recalls the host starts itself: a direct
- * `recall()` call, or `reflect()` (`ReflectOptions extends RecallOptions`, and
- * reflect forwards the options object). It does NOT see recalls that happen
- * inside a tool-loop run. `RecallOptions.onDiagnostics` is a single slot, not a
- * composable hook list, and both in-run paths already occupy it to read
- * `degraded` for themselves — the recall tool (`lib/memory/recallTool.ts`) and
- * the vault search tool (`lib/memoryVault/searchTool.ts`). Neither forwards a
- * caller's callback, and neither exposes the slot on its own options.
+ * // posthog-node takes ONE object, so the arguments do not line up:
+ * // track: (event, properties) => posthog.capture({ distinctId, event, properties })
  *
- * Two consequences to plan for:
+ * const hooks = createMetricsHooks(sink);
+ * // pass `hooks` wherever RunHooks are accepted, or compose with your own:
+ * // composeHooks([hooks, myTracingHooks])
+ * ```
+ */
+interface TelemetrySink {
+    /**
+     * Record a discrete event (run started, tool failed, recall degraded…).
+     * `properties` are flat, JSON-serializable, and free of message contents —
+     * only identifiers, counts, and timings.
+     */
+    track?: (event: string, properties: Record<string, unknown>) => void;
+    /**
+     * Record a numeric measurement (latency, duration, token count). `tags`
+     * are low-cardinality string dimensions (model, toolName, outcome, lane).
+     */
+    metric?: (name: string, value: number, tags: Record<string, string>) => void;
+}
+/**
+ * Default sink that discards everything. Useful as a fallback when telemetry
+ * is configured off, and as the base for sinks that override one method.
  *
- * - Event volume reports host-initiated recall only. A near-empty
- *   `recall.completed` stream means the app recalls through the tools. It does
- *   not mean recall is broken or that the sink is misconfigured.
- * - These events carry no `runId`, so you cannot join them to `run.failed` from
- *   `createMetricsHooks`. That join needs two changes in the memory layer, not
- *   here: make `onDiagnostics` forwardable through both tools, and thread the
- *   loop's `runId` (minted in `lib/chat/toolLoop.ts`) across the executor
- *   boundary onto `RecallDiagnostics`.
+ * Frozen. It is a published singleton, and `createMetricsHooks` closes over the
+ * object rather than its methods, so one module assigning `noopTelemetrySink.track`
+ * would reroute every already-constructed adapter that shares the reference — a
+ * test stub that forgets to restore changes behaviour for the rest of the suite.
+ * Freezing now rather than later: adding it later is the breaking direction,
+ * because it turns a silent assignment into a strict-mode TypeError.
+ */
+declare const noopTelemetrySink: TelemetrySink;
+
+interface MetricsHooksOptions {
+    /**
+     * Override the clock used for every duration this adapter reports.
+     *
+     * The default is monotonic where the runtime has `performance.now()`
+     * (browser / RN / Node), falling back to `Date.now()`. That is about
+     * monotonicity, not precision: `Date.now()` steps BACKWARD on an NTP
+     * correction, a VM resume from snapshot, or a container host clock sync, and
+     * a step landing mid-run makes `now() - startedAt` negative. dogstatsd
+     * accepts a negative histogram sample, so it is ingested and corrupts the
+     * min/p50/p95 for that bucket — silently wrong data, which is the one thing
+     * this module exists to prevent.
+     *
+     * Supply your own only to make durations deterministic in a test.
+     */
+    now?: () => number;
+    /**
+     * Report the raw `error` message string on `run.failed`,
+     * `model.call.failed`, and `tool.call.failed`. Default `false`.
+     *
+     * Off by default because those strings are free text and routinely quote
+     * the input that caused the failure. `JSON.parse` echoes the offending tool
+     * arguments verbatim (`Unexpected token 'h', "hunter2pass"... is not valid
+     * JSON`), `executeToolCall` wraps whatever a host executor threw, and an
+     * executor with `deAnonymizeArgs` runs on de-redacted PII. Sending them to
+     * a sink contradicts {@link TelemetrySink}, which states that properties
+     * carry only identifiers, counts, and timings.
+     *
+     * Turn it on when the sink is infrastructure you own and you accept the
+     * exposure. Prefer `errorType`, which is always reported and always safe.
+     */
+    includeErrorMessages?: boolean;
+}
+/**
+ * Build {@link RunHooks} that report run lifecycle, model calls, and tool calls to `sink`; every run ends in exactly one `run.completed` or `run.failed`, and no message contents or tool arguments are emitted.
  *
- * A host that already holds a `runId` can stamp it today with no signature
- * change: wrap the sink rather than the handler, and put it on `track`
- * properties only. A metric tag of that cardinality is a problem for the
- * backend — see {@link TelemetrySink} on keeping tags low-cardinality.
+ * @see TELEMETRY.md for event payloads and metric names.
  */
+declare function createMetricsHooks(sink: TelemetrySink, opts?: MetricsHooksOptions): RunHooks;
 
 /**
  * Build an `onDiagnostics` callback that forwards recall diagnostics to

package/dist/telemetry/index.d.ts

@@ -96,17 +96,6 @@ type LlmapiChatCompletionTool = {
     [key: string]: unknown;
 };
 
-/**
- * Lifecycle hooks for runToolLoop. All hooks are optional and observer
- * errors are swallowed (sync throws and async rejections both) so a buggy
- * hook can't crash the loop. Hook names match the Claude Agent SDK shape
- * (camelCase).
- *
- * Hooks are awaited synchronously at each fire site, so slow hooks
- * serialize into loop latency — keep them fast and do any heavy work
- * (network exports, file IO) asynchronously inside your own queue.
- */
-
 type LlmTokenUsage = {
     inputTokens?: number;
     outputTokens?: number;
@@ -228,156 +217,6 @@ type RunHooks = {
     afterToolUse?: (e: ToolUseEndEvent) => Promise<void> | void;
 };
 
-/**
- * Telemetry sink contract for the observability adapter.
- *
- * The SDK never talks to a vendor directly — it emits structured events and
- * metrics through this interface, and the app adapts it to PostHog, Datadog,
- * OpenTelemetry, etc. Both methods are optional so a sink that only cares
- * about events (or only about metrics) can implement half the surface.
- *
- * Implementations must be fast and must not throw: hooks are awaited
- * synchronously inside the tool loop (see `runHooks.ts`), so a slow or
- * throwing sink serializes into run latency or — worse — surfaces as a run
- * error. Queue network exports asynchronously inside your sink.
- *
- * @example
- * ```ts
- * import { createMetricsHooks, type TelemetrySink } from "@anuma/sdk/telemetry";
- *
- * // posthog-js: capture(event, properties)
- * const sink: TelemetrySink = {
- *   track: (event, properties) => posthog.capture(event, properties),
- *   metric: (name, value, tags) => statsd.histogram(name, value, tags),
- * };
- *
- * // posthog-node takes ONE object, so the arguments do not line up:
- * // track: (event, properties) => posthog.capture({ distinctId, event, properties })
- *
- * const hooks = createMetricsHooks(sink);
- * // pass `hooks` wherever RunHooks are accepted, or compose with your own:
- * // composeHooks([hooks, myTracingHooks])
- * ```
- */
-interface TelemetrySink {
-    /**
-     * Record a discrete event (run started, tool failed, recall degraded…).
-     * `properties` are flat, JSON-serializable, and free of message contents —
-     * only identifiers, counts, and timings.
-     */
-    track?: (event: string, properties: Record<string, unknown>) => void;
-    /**
-     * Record a numeric measurement (latency, duration, token count). `tags`
-     * are low-cardinality string dimensions (model, toolName, outcome, lane).
-     */
-    metric?: (name: string, value: number, tags: Record<string, string>) => void;
-}
-/**
- * Default sink that discards everything. Useful as a fallback when telemetry
- * is configured off, and as the base for sinks that override one method.
- *
- * Frozen. It is a published singleton, and `createMetricsHooks` closes over the
- * object rather than its methods, so one module assigning `noopTelemetrySink.track`
- * would reroute every already-constructed adapter that shares the reference — a
- * test stub that forgets to restore changes behaviour for the rest of the suite.
- * Freezing now rather than later: adding it later is the breaking direction,
- * because it turns a silent assignment into a strict-mode TypeError.
- */
-declare const noopTelemetrySink: TelemetrySink;
-
-/**
- * {@link RunHooks} adapter that turns tool-loop lifecycle hooks into
- * telemetry events and metrics on a {@link TelemetrySink}.
- *
- * Events emitted (all with `runId`; no message contents or tool arguments):
- *
- * - `run.started` — `{ runId, model }`
- * - `run.completed` — `{ runId, totalSteps, durationMs }`
- * - `run.failed` — `{ runId, durationMs, errorType, stage }`
- * - `model.call.completed` — `{ runId, stepIndex, latencyMs, model?, inputTokens?, outputTokens?, finishReason? }`
- * - `model.call.failed` — `{ runId, stepIndex, latencyMs, model? }`
- * - `tool.call.completed` — `{ runId, stepIndex, toolCallId, toolName, durationMs }`
- * - `tool.call.failed` — `{ runId, stepIndex, toolCallId, toolName, durationMs, errorType }`
- *
- * The raw `error` message string is NOT reported unless the caller opts in
- * with {@link MetricsHooksOptions.includeErrorMessages} — see that option for
- * why. `errorType` is always safe and always reported where the source event
- * carries one.
- *
- * Metrics emitted:
- *
- * - `run.duration` (ms, tags: model?, outcome)
- * - `model.call.latency` (ms, tags: model?, outcome)
- * - `model.call.tokens` (count, tags: direction: input|output) when usage is present
- * - `tool.call.duration` (ms, tags: toolName, outcome, errorType?)
- *
- * Pairing notes (mirrors the contract documented in `runHooks.ts`):
- *
- * - `onRunEnd` / `onRunError` are mutually exclusive and fire exactly once per
- *   run, so every started run resolves to exactly one terminal event.
- * - Server-side tools routed via `onToolCall` get `beforeToolUse` with no
- *   `afterToolUse`. The adapter therefore never emits a completion for a tool
- *   it saw only start; the pending timer is dropped when the run terminates.
- * - `afterToolUse` without a matching `beforeToolUse` (defensive — not a
- *   documented case) is still reported, with `durationMs` omitted.
- * - Per-run state is keyed by `runId` and cleared on the terminal hook, so
- *   concurrent runs and long-lived adapter instances do not leak timers. The
- *   `after*` hooks read that state without creating it, so a hook arriving
- *   after the terminal one cannot resurrect an entry nothing would delete
- *   again.
- */
-
-interface MetricsHooksOptions {
-    /**
-     * Override the clock used for every duration this adapter reports.
-     *
-     * The default is monotonic where the runtime has `performance.now()`
-     * (browser / RN / Node), falling back to `Date.now()`. That is about
-     * monotonicity, not precision: `Date.now()` steps BACKWARD on an NTP
-     * correction, a VM resume from snapshot, or a container host clock sync, and
-     * a step landing mid-run makes `now() - startedAt` negative. dogstatsd
-     * accepts a negative histogram sample, so it is ingested and corrupts the
-     * min/p50/p95 for that bucket — silently wrong data, which is the one thing
-     * this module exists to prevent.
-     *
-     * Supply your own only to make durations deterministic in a test.
-     */
-    now?: () => number;
-    /**
-     * Report the raw `error` message string on `run.failed`,
-     * `model.call.failed`, and `tool.call.failed`. Default `false`.
-     *
-     * Off by default because those strings are free text and routinely quote
-     * the input that caused the failure. `JSON.parse` echoes the offending tool
-     * arguments verbatim (`Unexpected token 'h', "hunter2pass"... is not valid
-     * JSON`), `executeToolCall` wraps whatever a host executor threw, and an
-     * executor with `deAnonymizeArgs` runs on de-redacted PII. Sending them to
-     * a sink contradicts {@link TelemetrySink}, which states that properties
-     * carry only identifiers, counts, and timings.
-     *
-     * Turn it on when the sink is infrastructure you own and you accept the
-     * exposure. Prefer `errorType`, which is always reported and always safe.
-     */
-    includeErrorMessages?: boolean;
-}
-/**
- * Build {@link RunHooks} that report run lifecycle, model calls, and tool
- * calls to `sink`. The returned hooks are synchronous and never throw — a
- * throwing sink method is swallowed with a console-free `noop` (the tool loop
- * already swallows hook errors; we avoid double-logging here).
- */
-declare function createMetricsHooks(sink: TelemetrySink, opts?: MetricsHooksOptions): RunHooks;
-
-/**
- * Unified memory layer types — the Recall / Retain API.
- *
- * This module defines the public surface for the new unified memory layer
- * that sits above `memoryVault` (curated facts) and `memoryEngine` (raw
- * conversation chunks). Callers should prefer these types over the legacy
- * `VaultSearchResult` / `ChunkSearchResult` shapes; the underlying stores
- * may converge later, the API will not.
- */
-
 /**
  * Budget controls retrieval depth/cost. Higher budgets enable more
  * candidate sources and the cross-encoder reranker.
@@ -594,51 +433,101 @@ interface RecallDiagnostics {
 }
 
 /**
- * Adapter that turns {@link RecallDiagnostics} (the `onDiagnostics` hook on
- * {@link RecallOptions}) into telemetry events and metrics on a
- * {@link TelemetrySink}.
+ * Telemetry sink contract for the observability adapter.
  *
- * Events emitted:
+ * The SDK never talks to a vendor directly — it emits structured events and
+ * metrics through this interface, and the app adapts it to PostHog, Datadog,
+ * OpenTelemetry, etc. Both methods are optional so a sink that only cares
+ * about events (or only about metrics) can implement half the surface.
  *
- * - `recall.completed` — once per `recall()` call with budget, lane counts,
- *   and whether the cross-encoder reranked.
- * - `recall.degraded` — once per entry in `diagnostics.degraded`, with the
- *   degradation reason. A clean recall emits none.
+ * Implementations must be fast and must not throw: hooks are awaited
+ * synchronously inside the tool loop (see `runHooks.ts`), so a slow or
+ * throwing sink serializes into run latency or — worse — surfaces as a run
+ * error. Queue network exports asynchronously inside your sink.
  *
- * Metrics emitted (all tagged `lane`):
+ * @example
+ * ```ts
+ * import { createMetricsHooks, type TelemetrySink } from "@anuma/sdk/telemetry";
  *
- * - `recall.duration` (ms) for each timing lane: `total`, `prep`, `factLane`,
- *   `rerank`, `queryEmbed`, `chunkLane`, `fuse`. `rerank` and `queryEmbed`
- *   are SUBSETS of `factLane` — do not sum the lanes.
- * - `recall.candidates` (count), `recall.facts` (count), `recall.chunks` (count)
- * - `recall.vault.size`, `recall.vault.rows_decrypted`,
- *   `recall.vault.rows_embedded` when the fact lane reported them.
+ * // posthog-js: capture(event, properties)
+ * const sink: TelemetrySink = {
+ *   track: (event, properties) => posthog.capture(event, properties),
+ *   metric: (name, value, tags) => statsd.histogram(name, value, tags),
+ * };
  *
- * COVERAGE — this handler only sees recalls the host starts itself: a direct
- * `recall()` call, or `reflect()` (`ReflectOptions extends RecallOptions`, and
- * reflect forwards the options object). It does NOT see recalls that happen
- * inside a tool-loop run. `RecallOptions.onDiagnostics` is a single slot, not a
- * composable hook list, and both in-run paths already occupy it to read
- * `degraded` for themselves — the recall tool (`lib/memory/recallTool.ts`) and
- * the vault search tool (`lib/memoryVault/searchTool.ts`). Neither forwards a
- * caller's callback, and neither exposes the slot on its own options.
+ * // posthog-node takes ONE object, so the arguments do not line up:
+ * // track: (event, properties) => posthog.capture({ distinctId, event, properties })
  *
- * Two consequences to plan for:
+ * const hooks = createMetricsHooks(sink);
+ * // pass `hooks` wherever RunHooks are accepted, or compose with your own:
+ * // composeHooks([hooks, myTracingHooks])
+ * ```
+ */
+interface TelemetrySink {
+    /**
+     * Record a discrete event (run started, tool failed, recall degraded…).
+     * `properties` are flat, JSON-serializable, and free of message contents —
+     * only identifiers, counts, and timings.
+     */
+    track?: (event: string, properties: Record<string, unknown>) => void;
+    /**
+     * Record a numeric measurement (latency, duration, token count). `tags`
+     * are low-cardinality string dimensions (model, toolName, outcome, lane).
+     */
+    metric?: (name: string, value: number, tags: Record<string, string>) => void;
+}
+/**
+ * Default sink that discards everything. Useful as a fallback when telemetry
+ * is configured off, and as the base for sinks that override one method.
  *
- * - Event volume reports host-initiated recall only. A near-empty
- *   `recall.completed` stream means the app recalls through the tools. It does
- *   not mean recall is broken or that the sink is misconfigured.
- * - These events carry no `runId`, so you cannot join them to `run.failed` from
- *   `createMetricsHooks`. That join needs two changes in the memory layer, not
- *   here: make `onDiagnostics` forwardable through both tools, and thread the
- *   loop's `runId` (minted in `lib/chat/toolLoop.ts`) across the executor
- *   boundary onto `RecallDiagnostics`.
+ * Frozen. It is a published singleton, and `createMetricsHooks` closes over the
+ * object rather than its methods, so one module assigning `noopTelemetrySink.track`
+ * would reroute every already-constructed adapter that shares the reference — a
+ * test stub that forgets to restore changes behaviour for the rest of the suite.
+ * Freezing now rather than later: adding it later is the breaking direction,
+ * because it turns a silent assignment into a strict-mode TypeError.
+ */
+declare const noopTelemetrySink: TelemetrySink;
+
+interface MetricsHooksOptions {
+    /**
+     * Override the clock used for every duration this adapter reports.
+     *
+     * The default is monotonic where the runtime has `performance.now()`
+     * (browser / RN / Node), falling back to `Date.now()`. That is about
+     * monotonicity, not precision: `Date.now()` steps BACKWARD on an NTP
+     * correction, a VM resume from snapshot, or a container host clock sync, and
+     * a step landing mid-run makes `now() - startedAt` negative. dogstatsd
+     * accepts a negative histogram sample, so it is ingested and corrupts the
+     * min/p50/p95 for that bucket — silently wrong data, which is the one thing
+     * this module exists to prevent.
+     *
+     * Supply your own only to make durations deterministic in a test.
+     */
+    now?: () => number;
+    /**
+     * Report the raw `error` message string on `run.failed`,
+     * `model.call.failed`, and `tool.call.failed`. Default `false`.
+     *
+     * Off by default because those strings are free text and routinely quote
+     * the input that caused the failure. `JSON.parse` echoes the offending tool
+     * arguments verbatim (`Unexpected token 'h', "hunter2pass"... is not valid
+     * JSON`), `executeToolCall` wraps whatever a host executor threw, and an
+     * executor with `deAnonymizeArgs` runs on de-redacted PII. Sending them to
+     * a sink contradicts {@link TelemetrySink}, which states that properties
+     * carry only identifiers, counts, and timings.
+     *
+     * Turn it on when the sink is infrastructure you own and you accept the
+     * exposure. Prefer `errorType`, which is always reported and always safe.
+     */
+    includeErrorMessages?: boolean;
+}
+/**
+ * Build {@link RunHooks} that report run lifecycle, model calls, and tool calls to `sink`; every run ends in exactly one `run.completed` or `run.failed`, and no message contents or tool arguments are emitted.
  *
- * A host that already holds a `runId` can stamp it today with no signature
- * change: wrap the sink rather than the handler, and put it on `track`
- * properties only. A metric tag of that cardinality is a problem for the
- * backend — see {@link TelemetrySink} on keeping tags low-cardinality.
+ * @see TELEMETRY.md for event payloads and metric names.
  */
+declare function createMetricsHooks(sink: TelemetrySink, opts?: MetricsHooksOptions): RunHooks;
 
 /**
  * Build an `onDiagnostics` callback that forwards recall diagnostics to