@getrift/rift 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/src/observability/tool-usage-stats.d.ts

@@ -3,14 +3,86 @@
  *
  * No filesystem reads, no parsing — callers pass an already-decoded
  * `ToolUsageEntry[]` (typically via `readToolUsageEntriesTolerant`).
- * Buckets calls into today/week/month/all-time and applies a fixed
- * per-tool tokens-saved heuristic so historical entries (which were
- * never instrumented for size) yield a usable estimate.
+ * Buckets calls into today/week/month/all-time. The headline retrieval
+ * metric is `context_tokens_delivered_estimate` — the measured size of
+ * the text channel actually returned on context hits, divided by 4 for
+ * a rough tokens estimate.
  */
 import type { ToolUsageEntry } from "./tool-usage.js";
 export interface UsageWindow {
     calls: number;
-    tokens_saved: number;
+    /**
+     * Successful retrieval calls that returned at least one item and were not
+     * marked `degraded`. Captures rift_search, rift_conversations_search, and
+     * rift_context_pack — the tools whose job is to surface relevant context.
+     * Non-retrieval calls (rift_save, rift_status) are excluded.
+     */
+    context_hits: number;
+    /**
+     * Subset of `context_hits` whose rows included `response_text_bytes`, meaning
+     * they actually contributed to `context_tokens_delivered_estimate`. Legacy
+     * rows written before byte measurement still count as context hits, but not
+     * as measured hits. SwiftBar renders this as "3/115 hits measured" so equal
+     * token totals across wider windows are understandable instead of suspicious.
+     */
+    context_tokens_measured_hits: number;
+    /**
+     * Cheap tokens estimate (`ceil(bytes / 4)`) over the MCP text channel of
+     * every call that counts toward `context_hits`. Measured from the response
+     * we actually returned — not a per-tool flat constant. Empty results,
+     * degraded retrievals, failures, and non-retrieval tools contribute 0.
+     * Legacy log rows written before response size was recorded contribute 0
+     * (no fabricated number) and naturally age out as fresh rows accumulate.
+     */
+    context_tokens_delivered_estimate: number;
+}
+/**
+ * Precise-lookup health: aggregates over rift_search calls whose
+ * `search_mode` was recorded as `"exact_id"`. Surfaces the leading
+ * indicators that the strict direct-lookup gate on `/search` is or
+ * isn't earning agent trust — high success ratio + rare typed failures
+ * is healthy; rising `typed_failures` (`id_not_found`/`ambiguous_id`)
+ * or large `max_content_tokens_estimate` paired with low success is
+ * the shape of a flow where an agent may stop trusting Rift for precise
+ * lookup. Trust risk is named precisely:
+ * we cannot tell from Rift alone that the agent went on to read JSONL
+ * from disk, only that the lookup it asked for here failed.
+ */
+export interface PreciseLookupStats {
+    /** Total rift_search calls with search_mode = exact_id (success or not). */
+    total: number;
+    /** Subset of `total` where success = true. */
+    successes: number;
+    /**
+     * Failures bucketed by the typed `error` field parsed from the response
+     * body (e.g. `id_not_found`, `ambiguous_id`). Transport / untyped
+     * failures do not appear here — they only count toward `total - successes`.
+     */
+    typed_failures: Record<string, number>;
+    /**
+     * Detail-level split among exact-id calls. `summary` is impossible by
+     * definition (exact-id requires middle|full), so only `middle` and
+     * `full` appear. Useful for seeing whether agents prefer the bounded
+     * middle path or still default to full-body expansion.
+     */
+    by_detail: {
+        middle: number;
+        full: number;
+    };
+    /**
+     * Count of successful exact-id calls that returned at least one hit
+     * with `content_truncated === true` — a leading indicator that the
+     * agent received a bounded excerpt and may decide to escalate to
+     * `detail=full`. Bounded to successful calls because truncation only
+     * makes sense for returned content.
+     */
+    truncated_count: number;
+    /**
+     * Maximum `content_tokens_estimate` observed across all exact-id
+     * calls (successful or not, when the field was present). Captures the
+     * worst-case "this row would blow context if expanded" signal.
+     */
+    max_content_tokens_estimate: number;
 }
 export interface UsageSummary {
     today: UsageWindow;
@@ -18,6 +90,7 @@ export interface UsageSummary {
     month: UsageWindow;
     all_time: UsageWindow;
     by_tool: Record<string, number>;
+    precise_lookup: PreciseLookupStats;
 }
 export declare function aggregateUsage(entries: ToolUsageEntry[], now?: Date): UsageSummary;
 //# sourceMappingURL=tool-usage-stats.d.ts.map

package/dist/src/observability/tool-usage-stats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-usage-stats.d.ts","sourceRoot":"","sources":["../../../src/observability/tool-usage-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAyCtD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAkBD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EAAE,EACzB,GAAG,GAAE,IAAiB,GACrB,YAAY,CA4Cd"}
+{"version":3,"file":"tool-usage-stats.d.ts","sourceRoot":"","sources":["../../../src/observability/tool-usage-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAsBtD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,4BAA4B,EAAE,MAAM,CAAC;IACrC;;;;;;;OAOG;IACH,iCAAiC,EAAE,MAAM,CAAC;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC;;;;;OAKG;IACH,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,2BAA2B,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,cAAc,EAAE,kBAAkB,CAAC;CACpC;AA8ED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EAAE,EACzB,GAAG,GAAE,IAAiB,GACrB,YAAY,CA2Fd"}

package/dist/src/observability/tool-usage-stats.js

@@ -1,24 +1,7 @@
-/**
- * Tokens-saved estimates per MCP tool call. The numbers are the
- * approximate tokens an agent would have to spend stuffing equivalent
- * context into a system prompt or doing the same query without the
- * compact, bucketed retrieval the MCP server provides.
- *
- * Unknown tools fall back to `DEFAULT_TOKENS_SAVED` so future tools
- * report a non-zero baseline.
- */
-const TOKENS_SAVED_PER_TOOL = {
-    rift_context_pack: 12_000,
-    rift_conversations_search: 8_000,
-    rift_search: 6_000,
-    rift_save: 2_000,
-    rift_status: 1_000,
-};
-const DEFAULT_TOKENS_SAVED = 1_000;
 /**
  * Map legacy tool names from JSONL rows written before the rename onto
- * their canonical `rift_*` equivalents so SwiftBar tokens-saved counters
- * stay continuous on a machine that upgrades. Hidden migration only —
+ * their canonical `rift_*` equivalents so SwiftBar counters stay
+ * continuous on a machine that upgrades. Hidden migration only —
  * never surfaces in user-visible output.
  */
 const LEGACY_TOOL_RENAMES = {
@@ -33,49 +16,146 @@ function canonicalToolName(tool) {
 }
 const DAY_MS = 24 * 60 * 60 * 1000;
 function emptyWindow() {
-    return { calls: 0, tokens_saved: 0 };
+    return {
+        calls: 0,
+        context_hits: 0,
+        context_tokens_measured_hits: 0,
+        context_tokens_delivered_estimate: 0,
+    };
+}
+/**
+ * Cheap tokens estimate from a UTF-8 byte count. `bytes / 4` is the standard
+ * back-of-envelope for English text — good enough for a glanceable menu-bar
+ * counter without pulling a real tokenizer into the daemon.
+ */
+function tokensFromBytes(bytes) {
+    return bytes > 0 ? Math.ceil(bytes / 4) : 0;
+}
+/**
+ * Local-time start-of-day. The menu-bar "today" counter is a glanceable
+ * Mac-local metric, so the boundary follows the machine's wall clock — not
+ * UTC, which would reset mid-evening in Asia/early-morning in Europe.
+ */
+function startOfLocalDay(date) {
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
 }
-function tokensSavedFor(tool) {
-    return TOKENS_SAVED_PER_TOOL[tool] ?? DEFAULT_TOKENS_SAVED;
+/**
+ * Local-time start of the following day. Built via the local-time Date
+ * constructor (not `startOfLocalDay + DAY_MS`) so DST-fallback days, which
+ * have 25 hours, still capture their final hour as "today".
+ */
+function startOfNextLocalDay(date) {
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate() + 1).getTime();
 }
-function startOfUtcDay(date) {
-    return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+/**
+ * Local-time start of the current calendar month. The menu labels this window
+ * "This month", and a friend reads that as "since the 1st" — not a rolling
+ * 30-day trailing window. Anchoring on the calendar boundary keeps the label
+ * honest (on June 4 it means June 1→now, never May 5→now).
+ */
+function startOfLocalMonth(date) {
+    return new Date(date.getFullYear(), date.getMonth(), 1).getTime();
+}
+/**
+ * Tools whose `result_count` counts toward `context_hits`. Belt-and-suspenders
+ * with the logger's own whitelist in [extractRetrievalSignal] — if a future
+ * code path ever writes `result_count` for a non-retrieval tool, this gate
+ * still keeps it out of the metric.
+ */
+const RETRIEVAL_TOOLS_FOR_HITS = new Set([
+    "rift_search",
+    "rift_conversations_search",
+    "rift_context_pack",
+]);
+function isContextHit(tool, entry) {
+    return (RETRIEVAL_TOOLS_FOR_HITS.has(tool) &&
+        entry.success === true &&
+        entry.degraded !== true &&
+        typeof entry.result_count === "number" &&
+        entry.result_count > 0);
 }
 export function aggregateUsage(entries, now = new Date()) {
-    const todayStartMs = startOfUtcDay(now);
+    const todayStartMs = startOfLocalDay(now);
+    const todayEndMs = startOfNextLocalDay(now);
     const nowMs = now.getTime();
+    // `week` stays a rolling 7-day window — it is an internal metric, never
+    // surfaced in the menu, so it carries no calendar-label honesty obligation.
+    // `month` is a calendar-month boundary because the menu labels it "This
+    // month" (see startOfLocalMonth).
     const weekStartMs = nowMs - 7 * DAY_MS;
-    const monthStartMs = nowMs - 30 * DAY_MS;
+    const monthStartMs = startOfLocalMonth(now);
     const summary = {
         today: emptyWindow(),
         week: emptyWindow(),
         month: emptyWindow(),
         all_time: emptyWindow(),
         by_tool: {},
+        precise_lookup: {
+            total: 0,
+            successes: 0,
+            typed_failures: {},
+            by_detail: { middle: 0, full: 0 },
+            truncated_count: 0,
+            max_content_tokens_estimate: 0,
+        },
     };
-    const todayEndMs = todayStartMs + DAY_MS;
     for (const entry of entries) {
         const ts = Date.parse(entry.timestamp);
         if (Number.isNaN(ts))
             continue;
         const tool = canonicalToolName(entry.tool);
-        const tokens = entry.success ? tokensSavedFor(tool) : 0;
+        const hit = isContextHit(tool, entry) ? 1 : 0;
+        // Only count delivered tokens on context hits — empty/degraded/non-retrieval
+        // calls all contribute 0. `response_text_bytes` is absent on legacy rows
+        // written before the field existed; those naturally contribute 0 too.
+        const delivered = hit && typeof entry.response_text_bytes === "number"
+            ? tokensFromBytes(entry.response_text_bytes)
+            : 0;
+        const measuredHit = hit && typeof entry.response_text_bytes === "number" ? 1 : 0;
         summary.all_time.calls += 1;
-        summary.all_time.tokens_saved += tokens;
+        summary.all_time.context_tokens_delivered_estimate += delivered;
+        summary.all_time.context_tokens_measured_hits += measuredHit;
+        summary.all_time.context_hits += hit;
         summary.by_tool[tool] = (summary.by_tool[tool] ?? 0) + 1;
+        if (tool === "rift_search" && entry.search_mode === "exact_id") {
+            const pl = summary.precise_lookup;
+            pl.total += 1;
+            if (entry.success === true)
+                pl.successes += 1;
+            else if (typeof entry.typed_error === "string") {
+                pl.typed_failures[entry.typed_error] =
+                    (pl.typed_failures[entry.typed_error] ?? 0) + 1;
+            }
+            if (entry.detail === "middle")
+                pl.by_detail.middle += 1;
+            else if (entry.detail === "full")
+                pl.by_detail.full += 1;
+            if (entry.has_truncated_content === true)
+                pl.truncated_count += 1;
+            if (typeof entry.max_content_tokens_estimate === "number" &&
+                entry.max_content_tokens_estimate > pl.max_content_tokens_estimate) {
+                pl.max_content_tokens_estimate = entry.max_content_tokens_estimate;
+            }
+        }
         if (ts > nowMs)
             continue;
         if (ts >= monthStartMs) {
             summary.month.calls += 1;
-            summary.month.tokens_saved += tokens;
+            summary.month.context_tokens_delivered_estimate += delivered;
+            summary.month.context_tokens_measured_hits += measuredHit;
+            summary.month.context_hits += hit;
         }
         if (ts >= weekStartMs) {
             summary.week.calls += 1;
-            summary.week.tokens_saved += tokens;
+            summary.week.context_tokens_delivered_estimate += delivered;
+            summary.week.context_tokens_measured_hits += measuredHit;
+            summary.week.context_hits += hit;
         }
         if (ts >= todayStartMs && ts < todayEndMs) {
             summary.today.calls += 1;
-            summary.today.tokens_saved += tokens;
+            summary.today.context_tokens_delivered_estimate += delivered;
+            summary.today.context_tokens_measured_hits += measuredHit;
+            summary.today.context_hits += hit;
         }
     }
     return summary;

package/dist/src/observability/tool-usage-stats.js.map

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

package/dist/src/observability/tool-usage.d.ts

@@ -1,3 +1,5 @@
+export type SearchMode = "exact_id" | "ranked";
+export type DetailLevel = "summary" | "middle" | "full";
 export interface ToolUsageEntry {
     timestamp: string;
     type: "mcp_tool_call";
@@ -8,15 +10,64 @@ export interface ToolUsageEntry {
     result_count?: number;
     degraded?: boolean;
     error?: string;
+    /**
+     * rift_search only: "exact_id" when `args.id` is present AND
+     * `detail` is "middle" or "full" (the strict direct-lookup gate on
+     * `/search`); "ranked" otherwise. Recorded as a leading indicator for
+     * precise-lookup trust: a healthy exact-ID flow has a high success
+     * ratio and rare typed failures; failures are trust-loss risk signals
+     * that may push an agent to seek evidence outside Rift.
+     * Trust risk is named precisely — we cannot tell from Rift alone that
+     * the agent went on to read JSONL from disk, only that the precise
+     * lookup it asked for here failed.
+     */
+    search_mode?: SearchMode;
+    /** rift_search only: the detail level argued by the caller. */
+    detail?: DetailLevel;
+    /** rift_search only: whether the caller supplied an `id`. */
+    id_present?: boolean;
+    /** rift_search only: whether the caller supplied a `tier`. */
+    tier_present?: boolean;
+    /** rift_search only: whether the caller supplied a `source_table`. */
+    source_table_present?: boolean;
+    /**
+     * rift_search only: the typed error code parsed from the response
+     * body when the call failed with a structured error (e.g.
+     * `id_not_found`, `ambiguous_id`). Absent for generic transport
+     * failures or untyped 4xx/5xx.
+     */
+    typed_error?: string;
+    /**
+     * rift_search only: true when any returned hit carries
+     * `content_truncated === true`. Signals that the agent received a
+     * bounded middle-detail excerpt rather than the full row body — a
+     * useful leading indicator that the agent may decide to escalate to
+     * `detail=full` next.
+     */
+    has_truncated_content?: boolean;
+    /**
+     * rift_search only: the maximum `content_tokens_estimate` observed
+     * across returned hits. Cheap to compute (the size advisory is
+     * already on each hit) and lets us see whether agents are routinely
+     * being shown rows that would blow context if expanded.
+     */
+    max_content_tokens_estimate?: number;
+    /**
+     * Total UTF-8 byte length of `content[].text` on the MCP response we
+     * hand back to the caller. The text channel is the user/model-visible
+     * answer; we count it (rather than `structuredContent`, which often
+     * duplicates the same data) so the resulting tokens-delivered estimate
+     * isn't double-counted. Recorded on every successful call so it can
+     * survive retrieval-tool / non-retrieval-tool reclassifications later.
+     */
+    response_text_bytes?: number;
 }
 export declare function sanitizeArgs(raw: Record<string, unknown>): Record<string, unknown>;
 /**
- * Try to extract result_count from search-tool responses.
- *
- * Slice 1: search tools now emit markdown on the text channel and put the
- * compact DTO in `structuredContent`. We read from structuredContent first
- * and fall back to JSON-parsing the text channel for backwards compatibility
- * with tools that still return JSON there.
+ * Try to extract `result_count` from a retrieval-tool response. For search
+ * tools this is `results.length`; for `rift_context_pack` it is the sum of
+ * all four bucket sizes (decisions + constraints + examples + rules).
+ * Returns `undefined` for non-retrieval tools.
  */
 export declare function extractResultCount(tool: string, mcpResult: {
     content: Array<{
@@ -26,7 +77,9 @@ export declare function extractResultCount(tool: string, mcpResult: {
     structuredContent?: Record<string, unknown>;
 }): number | undefined;
 /**
- * Try to extract degraded flag from search-tool responses.
+ * Try to extract the `degraded` flag from a retrieval-tool response.
+ * Returns `undefined` for non-retrieval tools and for retrieval tools whose
+ * response did not carry the flag.
  */
 export declare function extractDegraded(tool: string, mcpResult: {
     content: Array<{
@@ -35,6 +88,46 @@ export declare function extractDegraded(tool: string, mcpResult: {
     }>;
     structuredContent?: Record<string, unknown>;
 }): boolean | undefined;
+/**
+ * Derive search-mode metadata from the raw rift_search args. Mirrors the
+ * direct-lookup gate on `/search`: `id` + (`middle` | `full`) → exact_id;
+ * anything else is ranked retrieval, even if `id` is present alongside
+ * `detail="summary"` (which doesn't trigger the strict path).
+ */
+export declare function deriveSearchModeMeta(args: Record<string, unknown>): {
+    search_mode: SearchMode;
+    detail: DetailLevel;
+    id_present: boolean;
+    tier_present: boolean;
+    source_table_present: boolean;
+};
+/**
+ * Derive result-side metadata for a successful rift_search call:
+ *   - has_truncated_content: any returned hit with content_truncated=true
+ *   - max_content_tokens_estimate: max content_tokens_estimate across hits
+ *
+ * Reads from `structuredContent.results` (the canonical compact DTO).
+ * Returns `{}` when the result shape is unknown — never throws.
+ */
+export declare function extractSearchResultMeta(mcpResult: {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}): {
+    has_truncated_content?: boolean;
+    max_content_tokens_estimate?: number;
+};
+/**
+ * Try to parse the typed error code (`id_not_found`, `ambiguous_id`, …)
+ * out of a failure response's text channel. `formatError` formats typed
+ * 404/409 bodies as `"<Prefix>: { "error": "id_not_found", … }"`, so we
+ * locate the first `{`, JSON.parse to end, and return the `error` field
+ * when it's a string. Returns `undefined` for transport-only failures
+ * (no body), untyped responses, or unparseable text.
+ */
+export declare function parseTypedError(text: string | undefined): string | undefined;
 export declare class ToolUsageLogger {
     private readonly logPath;
     constructor(dataDir: string);

package/dist/src/observability/tool-usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-usage.d.ts","sourceRoot":"","sources":["../../../src/observability/tool-usage.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzB;AAID;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C,GACA,MAAM,GAAG,SAAS,CAapB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C,GACA,OAAO,GAAG,SAAS,CAarB;AAID,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,MAAM;IAK3B,2CAA2C;IAC3C,GAAG,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAWhC;;;OAGG;IACH,IAAI,CACF,CAAC,SAAS;QACR,OAAO,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC7C,EAED,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC;IAwCb,sCAAsC;IACtC,OAAO,IAAI,cAAc,EAAE;IAa3B,IAAI,QAAQ,IAAI,MAAM,CAErB;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,GACf,cAAc,EAAE,CA4BlB"}
+{"version":3,"file":"tool-usage.d.ts","sourceRoot":"","sources":["../../../src/observability/tool-usage.ts"],"names":[],"mappings":"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"}