@anuma/sdk 6.15.2 → 6.17.0

package/dist/telemetry/index.d.ts

@@ -0,0 +1,578 @@
+type LlmapiMessage = {
+    /**
+     * Content is the message content
+     */
+    content?: Array<LlmapiMessageContentPart>;
+    role?: LlmapiRole;
+    /**
+     * ToolCallID is the ID of the tool call this message is responding to (only for tool role)
+     */
+    tool_call_id?: string;
+    /**
+     * ToolCalls contains tool/function calls made by the assistant (only for assistant role)
+     */
+    tool_calls?: Array<LlmapiToolCall>;
+    /**
+     * Type is the message type (for Responses API: "message")
+     */
+    type?: string;
+};
+/**
+ * File is used when Type=input_file (for Responses API)
+ */
+type LlmapiMessageContentFile = {
+    /**
+     * FileData is the base64-encoded file content
+     */
+    file_data?: string;
+    /**
+     * FileID is the ID of an uploaded file
+     */
+    file_id?: string;
+    /**
+     * FileURL is the URL to the file
+     */
+    file_url?: string;
+    /**
+     * Filename is the name of the file
+     */
+    filename?: string;
+};
+/**
+ * ImageURL is used when Type=image_url or Type=input_image
+ */
+type LlmapiMessageContentImage = {
+    /**
+     * Detail is the OpenAI detail hint (auto|low|high)
+     */
+    detail?: string;
+    /**
+     * URL is the image URL or data URI
+     */
+    url?: string;
+};
+type LlmapiMessageContentPart = {
+    file?: LlmapiMessageContentFile;
+    image_url?: LlmapiMessageContentImage;
+    /**
+     * Text holds the text content when Type=text or Type=input_text
+     */
+    text?: string;
+    /**
+     * Type is the block type (`text`, `image_url`, or `input_file`)
+     */
+    type?: string;
+};
+/**
+ * Role is the message role (system, user, assistant, tool)
+ */
+type LlmapiRole = string;
+type LlmapiToolCall = {
+    function?: LlmapiToolCallFunction;
+    /**
+     * ID is the unique identifier for this tool call
+     */
+    id?: string;
+    /**
+     * Type is the type of tool call (always "function" for now)
+     */
+    type?: string;
+};
+/**
+ * Function contains the function call details
+ */
+type LlmapiToolCallFunction = {
+    /**
+     * Arguments is the JSON string of arguments to pass to the function
+     */
+    arguments?: string;
+    /**
+     * Name is the name of the function to call
+     */
+    name?: string;
+};
+
+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;
+};
+type ModelCallStartEvent = {
+    runId: string;
+    stepIndex: number;
+    model: string;
+    messages: Array<LlmapiMessage>;
+    tools: Array<LlmapiChatCompletionTool>;
+    requestBody: Record<string, unknown>;
+};
+type ModelCallEndEvent = {
+    runId: string;
+    stepIndex: number;
+    content: string;
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        arguments: string;
+    }>;
+    usage?: LlmTokenUsage;
+    finishReason?: string;
+    error?: string;
+};
+type ToolUseStartEvent = {
+    runId: string;
+    stepIndex: number;
+    toolCallId: string;
+    name: string;
+    rawArguments: string;
+    parsedArguments?: Record<string, unknown>;
+};
+type ToolUseEndEvent = {
+    runId: string;
+    stepIndex: number;
+    toolCallId: string;
+    name: string;
+    result?: unknown;
+    error?: string;
+    errorType?: "parse" | "timeout" | "execution";
+};
+type RunStartEvent = {
+    runId: string;
+    model: string;
+    messages: Array<LlmapiMessage>;
+    tools: Array<LlmapiChatCompletionTool>;
+};
+type RunEndEvent = {
+    runId: string;
+    finalContent: string;
+    /** Number of LLM rounds executed. */
+    totalSteps: number;
+};
+type RunErrorEvent = {
+    runId: string;
+    error: string;
+    /**
+     * Only `"model"` today. Tool failures surface on {@link RunHooks.afterToolUse}
+     * with `errorType`, not on `onRunError`, so a tool stage isn't needed yet.
+     * Left as a union to leave room for `"validation"` or `"tool"` later
+     * without a breaking change.
+     */
+    stage: "model";
+    /**
+     * The underlying `Error` when one is available. `RunErrorEvent` predates
+     * this field, so `error` (a string message) is kept for backwards
+     * compatibility; new consumers should prefer `errorObject` when present
+     * for stack traces and `cause`.
+     */
+    errorObject?: Error;
+};
+type RunHooks = {
+    /**
+     * Fires once per `runToolLoop` invocation, before any pre-processor or
+     * model call. The `messages` payload is the raw caller-supplied
+     * conversation — pre-processors that enrich it (e.g. web search context)
+     * run afterwards, so `beforeModelCall.messages` reflects the
+     * post-enrichment state.
+     */
+    onRunStart?: (e: RunStartEvent) => Promise<void> | void;
+    /**
+     * Fires exactly once per run on clean completion. Mutually exclusive
+     * with `onRunError` — a run that completes fires `onRunEnd`; a run that
+     * errors or is aborted fires `onRunError`. Consumers can rely on
+     * exactly one terminal hook per `onRunStart`.
+     */
+    onRunEnd?: (e: RunEndEvent) => Promise<void> | void;
+    /**
+     * Fires exactly once per run when the loop errors or is aborted.
+     * `stage` is `"model"` for stream/provider errors and for aborts;
+     * tool execution failures surface as structured `{ error, errorType }`
+     * results on `afterToolUse` rather than firing `onRunError`.
+     * Mutually exclusive with `onRunEnd`.
+     */
+    onRunError?: (e: RunErrorEvent) => Promise<void> | void;
+    beforeModelCall?: (e: ModelCallStartEvent) => Promise<void> | void;
+    afterModelCall?: (e: ModelCallEndEvent) => Promise<void> | void;
+    /**
+     * Fires before each tool the model invoked — including server-side
+     * tools that have no client executor. Today this is observe-only.
+     * TODO(follow-up PR): allow returning { args?, abort?: { reason } } to
+     * mutate arguments or short-circuit the tool call.
+     *
+     * Pairing with {@link afterToolUse} is asymmetric: server-side tools
+     * routed via `onToolCall` get `beforeToolUse` but no `afterToolUse`,
+     * because they don't execute in-process. Tools blocked by a failed
+     * dependency or a dependency cycle DO get `afterToolUse` with
+     * `errorType: "execution"` — consumers tallying matched pairs should
+     * filter on executor-backed tools to avoid spurious imbalances.
+     */
+    beforeToolUse?: (e: ToolUseStartEvent) => Promise<void> | void;
+    /**
+     * Fires after each executor-backed tool finishes (success or failure)
+     * and after each dependency-blocked tool is skipped (`errorType:
+     * "execution"`). Does NOT fire for server-side tools routed via
+     * `onToolCall`. See {@link beforeToolUse} for the pairing contract.
+     */
+    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.
+ *
+ * - `low`: cosine + BM25 + recency. No reranker. Mobile default.
+ * - `mid`: + cross-encoder rerank.
+ * - `high`: + multi-hop graph traversal. LLM-free — query decomposition
+ *   (when wanted) lives in the tool/agent layer ({@link createRecallTool}),
+ *   not inside `recall()` itself (719/B4).
+ */
+type Budget = "low" | "mid" | "high";
+/** Soft-degradation signals surfaced via {@link RecallDiagnostics.degraded}. */
+type RecallDegradation = 
+/** Rerank was requested (budget mid/high) but the cross-encoder didn't run
+ *  this call — unavailable (e.g. React Native) or a transient failure. */
+"rerank-unavailable"
+/**
+ * @deprecated 719/B4 moved query decomposition out of `recall()`. Budget
+ * `high` no longer requires `decomposeOptions` and this signal is never
+ * emitted. Prefer `"decompose-moved"` for the upgrade breadcrumb. Kept in
+ * the union so existing telemetry consumers stay typed.
+ */
+ | "decompose-unavailable"
+/**
+ * `budget: 'high'` with `decomposeOptions` set but no usable
+ * {@link RecallOptions.subQueries}. Pre-B4 this call shape triggered LLM
+ * rewrite inside `recall()`; post-B4 it stays on the single-query high
+ * path (rerank + graph) and callers must pass facets (or use
+ * {@link createRecallTool}). Surfaced so silent quality regressions show
+ * up in diagnostics instead of looking healthier than before.
+ */
+ | "decompose-moved"
+/** There was no usable cosine lane, so results were ranked on BM25 (lexical)
+ *  alone: either the query embedding failed (or came back empty), or no
+ *  candidate had a vector to score against it because the row (re)embed failed.
+ *  Also set when the chunk lane — cosine-only, with no lexical equivalent — was
+ *  skipped for the same reason. The embeddings provider is a single upstream
+ *  with no fallback, so this is a whole-provider outage rather than a per-item
+ *  miss — expect a quality drop, not a total loss.
+ *
+ *  NOT set for a partial failure that leaves cosine running (a sub-query embed
+ *  failing back to the single-query path, or a row batch failing while other
+ *  rows keep usable vectors) — those are logged, not reported, so this stays a
+ *  reliable outage signal rather than a general embedding-error counter. */
+ | "embeddings-unavailable";
+/**
+ * Per-call recall observability payload (see {@link RecallOptions.onDiagnostics}).
+ * All timings are wall-clock milliseconds. Lane counts are post-dedupe,
+ * pre-fusion. Intended to be forwarded to a metrics sink (e.g. PostHog).
+ */
+interface RecallDiagnostics {
+    /** Budget actually executed (may have downgraded from the requested one). */
+    usedBudget: Budget;
+    /** Whether the cross-encoder actually reranked the fact lane this call. */
+    reranked: boolean;
+    /** Total candidates considered before truncation. */
+    candidateCount: number;
+    /** Total vault size when the fact lane ran (absent if it didn't). */
+    vaultSize?: number;
+    /**
+     * Which vault read path the fact lane actually executed: `true` for the
+     * projected key scan that decrypts only the admission window, `false` for the
+     * legacy whole-vault load. Absent when the fact lane didn't run.
+     *
+     * Reported because "the option was passed" and "the branch ran" are different
+     * facts, and #845 needed the second one: the projected path was enabled in
+     * production and the p50 did not move, with no way to tell a flag that never
+     * reached the bundle from a projection that isn't cheaper at that vault size.
+     */
+    decryptLast?: boolean;
+    /**
+     * Rows the fact lane paid to decrypt. Absent when it didn't run.
+     *
+     * Read against {@link RecallDiagnostics.vaultSize} — that ratio is the whole
+     * point. `decryptLast` true with `vaultRowsDecrypted` ≈ `vaultSize` means the
+     * admission window is admitting the entire vault and the projection is buying
+     * nothing. Far below `vaultSize` with latency unchanged means the decrypt was
+     * never the cost.
+     */
+    vaultRowsDecrypted?: number;
+    /**
+     * Rows the fact lane had to re-embed through the portal because their stored
+     * vector was unusable — stale `embedding_model`, wrong dimension, or
+     * unparseable. Absent when the fact lane didn't run.
+     *
+     * Expected to be 0 on a healthy vault: rows are embedded at write time and the
+     * re-embed writes the current model back, so a persistently non-zero value
+     * means the writeback is not sticking and every turn is paying for it. On the
+     * LEGACY read path this batch is uncapped, so it can be the whole vault.
+     */
+    vaultRowsEmbedded?: number;
+    /** Facts the fact lane returned (post-dedupe, pre-fusion). */
+    factCount: number;
+    /** Chunks the chunk lane returned (post-dedupe, pre-fusion). */
+    chunkCount: number;
+    /** Wall-clock phase timings (ms). */
+    timings: {
+        /** Whole `recall()` call. */
+        total: number;
+        /** Parallel query-embed + graph/temporal side-lane build. */
+        prep: number;
+        /** Vault fact-lane search (`searchVaultMemoriesWithSize`). */
+        factLane: number;
+        /**
+         * The cross-encoder's share of {@link factLane} — wall-clock spent inside
+         * `rerankPairs`. Billed even when the CE threw partway through, because a
+         * rerank that burned three seconds and then failed still cost them.
+         *
+         * A SUBSET of `factLane`, not a sibling: read `factLane - rerank` for
+         * everything else the lane did (query embed, vault read, fused ranking).
+         * 0 when the CE did not run; `reranked` is what distinguishes that from a
+         * rerank that cost nothing.
+         *
+         * Exists because #845 spent three rounds arguing about which stage inside
+         * the fact lane dominated — whole-vault read, then admission window, then
+         * the CE — with one aggregate number for all of them. Every hypothesis was
+         * an inference; this makes the question a query.
+         */
+        rerank: number;
+        /**
+         * The query embed's share of {@link factLane} — one portal round trip.
+         *
+         * Also a SUBSET of `factLane`. Together with `rerank` this makes the lane
+         * decomposable: `factLane - queryEmbed - rerank` is the local work (vault
+         * read, decrypt, BM25/cosine fusion), and each of the three implies a
+         * completely different fix.
+         *
+         * 0 when the lane returned before embedding, which includes every empty
+         * vault — `prepareVaultCandidates` short-circuits first. That is why the
+         * fast `vault_size = 0` population never established a baseline for this
+         * cost, and why the ~850ms floor on the smallest NON-empty vaults had no
+         * attributable owner.
+         */
+        queryEmbed: number;
+        /** Chunk-lane search (`searchChunksOp`). */
+        chunkLane: number;
+        /** Cross-lane RRF fusion + provenance dedup after both lanes. */
+        fuse: number;
+    };
+    /** Soft-degradation signals that fired this call (empty when clean). */
+    degraded: RecallDegradation[];
+}
+
+/**
+ * Adapter that turns {@link RecallDiagnostics} (the `onDiagnostics` hook on
+ * {@link RecallOptions}) into telemetry events and metrics on a
+ * {@link TelemetrySink}.
+ *
+ * Events emitted:
+ *
+ * - `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.
+ *
+ * Metrics emitted (all tagged `lane`):
+ *
+ * - `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.
+ *
+ * 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.
+ *
+ * Two consequences to plan for:
+ *
+ * - 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`.
+ *
+ * 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.
+ */
+
+/**
+ * Build an `onDiagnostics` callback that forwards recall diagnostics to
+ * `sink`. Never throws — a throwing sink method is swallowed, matching the
+ * `recall()` contract that diagnostics must not break retrieval.
+ */
+declare function createRecallDiagnosticsHandler(sink: TelemetrySink): (diagnostics: RecallDiagnostics) => void;
+
+export { type MetricsHooksOptions, type RecallDiagnostics, type RunHooks, type TelemetrySink, createMetricsHooks, createRecallDiagnosticsHandler, noopTelemetrySink };