pi-advisor-flow 0.3.6 → 0.5.0

package/src/usage.ts

@@ -0,0 +1,199 @@
+import type { Usage } from "@earendil-works/pi-ai/compat";
+
+/** Normalized usage returned by an Advisor or Scout provider response. */
+export interface AdvisorUsageSnapshot {
+  cacheRead?: number;
+  cacheWrite?: number;
+  cost?: number;
+  input?: number;
+  output?: number;
+  totalTokens?: number;
+}
+
+/** Session-local totals for direct Advisor model requests. */
+export interface AdvisorUsageTotals {
+  cacheRead?: number;
+  cacheWrite?: number;
+  calls: number;
+  cost?: number;
+  costCalls: number;
+  input?: number;
+  knownCalls: number;
+  output?: number;
+  totalTokens?: number;
+}
+
+const finite = (value: unknown) =>
+  typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? value
+    : undefined;
+
+const add = (left: number | undefined, right: number | undefined) =>
+  left === undefined || right === undefined ? (left ?? right) : left + right;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+const costFields = ["input", "output", "cacheRead", "cacheWrite", "total"];
+
+/** Extracts provider-agnostic usage fields without trusting provider metadata. */
+export const snapshotAdvisorUsage = (
+  usage: unknown
+): AdvisorUsageSnapshot | undefined => {
+  if (!isRecord(usage)) {
+    return undefined;
+  }
+  const cost = isRecord(usage.cost) ? usage.cost : undefined;
+  const snapshot = {
+    cacheRead: finite(usage.cacheRead),
+    cacheWrite: finite(usage.cacheWrite),
+    cost: finite(cost?.total) ?? finite(usage.totalCost) ?? finite(usage.cost),
+    input: finite(usage.input),
+    output: finite(usage.output),
+    totalTokens: finite(usage.totalTokens),
+  } satisfies AdvisorUsageSnapshot;
+  const hasCostField = costFields.some(
+    (field) => finite(cost?.[field]) !== undefined
+  );
+  return Object.values(snapshot).some((value) => value !== undefined) ||
+    hasCostField
+    ? snapshot
+    : undefined;
+};
+
+/** Returns the reported provider cost, when the response includes one. */
+export const advisorUsageCost = (usage: unknown): number | undefined =>
+  snapshotAdvisorUsage(usage)?.cost;
+
+/**
+ * Converts supported provider usage to Pi's complete nested-tool usage shape.
+ * Missing fields become zero only at this Pi API boundary; absent usage remains
+ * undefined so an unavailable request is never presented as a zero-cost call.
+ */
+export const advisorUsageForPi = (usage: unknown): Usage | undefined => {
+  const snapshot = snapshotAdvisorUsage(usage);
+  if (!(snapshot && isRecord(usage))) {
+    return undefined;
+  }
+  const cost = isRecord(usage.cost) ? usage.cost : undefined;
+  const input = snapshot.input ?? 0;
+  const output = snapshot.output ?? 0;
+  const cacheRead = snapshot.cacheRead ?? 0;
+  const cacheWrite = snapshot.cacheWrite ?? 0;
+  const cacheWrite1h = finite(usage.cacheWrite1h);
+  const reasoning = finite(usage.reasoning);
+  return {
+    cacheRead,
+    cacheWrite,
+    ...(cacheWrite1h === undefined ? {} : { cacheWrite1h }),
+    ...(reasoning === undefined ? {} : { reasoning }),
+    cost: {
+      cacheRead: finite(cost?.cacheRead) ?? 0,
+      cacheWrite: finite(cost?.cacheWrite) ?? 0,
+      input: finite(cost?.input) ?? 0,
+      output: finite(cost?.output) ?? 0,
+      total: snapshot.cost ?? 0,
+    },
+    input,
+    output,
+    totalTokens:
+      snapshot.totalTokens ?? input + output + cacheRead + cacheWrite,
+  };
+};
+
+/** Creates empty totals without treating absent usage as zero usage. */
+export const emptyAdvisorUsageTotals = (): AdvisorUsageTotals => ({
+  calls: 0,
+  costCalls: 0,
+  knownCalls: 0,
+});
+
+/** Adds one direct Advisor response to session-local usage totals. */
+export const addAdvisorUsage = (totals: AdvisorUsageTotals, usage: unknown) => {
+  totals.calls += 1;
+  const snapshot = snapshotAdvisorUsage(usage);
+  if (!snapshot) {
+    return;
+  }
+  totals.knownCalls += 1;
+  totals.cacheRead = add(totals.cacheRead, snapshot.cacheRead);
+  totals.cacheWrite = add(totals.cacheWrite, snapshot.cacheWrite);
+  totals.input = add(totals.input, snapshot.input);
+  totals.output = add(totals.output, snapshot.output);
+  totals.totalTokens = add(totals.totalTokens, snapshot.totalTokens);
+  if (snapshot.cost !== undefined) {
+    totals.cost = add(totals.cost, snapshot.cost);
+    totals.costCalls += 1;
+  }
+};
+
+const formatTokens = (value: number) => {
+  if (value < 1000) {
+    return String(value);
+  }
+  if (value < 10_000) {
+    return `${(value / 1000).toFixed(1)}k`;
+  }
+  if (value < 1_000_000) {
+    return `${Math.round(value / 1000)}k`;
+  }
+  if (value < 10_000_000) {
+    return `${(value / 1_000_000).toFixed(1)}M`;
+  }
+  return `${Math.round(value / 1_000_000)}M`;
+};
+
+const formatCost = (value: number) => `$${value.toFixed(4)}`;
+
+const formatUsageFields = (usage: AdvisorUsageSnapshot): string | undefined => {
+  const tokens = [
+    usage.input === undefined ? undefined : `↑${formatTokens(usage.input)}`,
+    usage.output === undefined ? undefined : `↓${formatTokens(usage.output)}`,
+    usage.cacheRead === undefined
+      ? undefined
+      : `cr:${formatTokens(usage.cacheRead)}`,
+    usage.cacheWrite === undefined
+      ? undefined
+      : `cw:${formatTokens(usage.cacheWrite)}`,
+  ].filter((value): value is string => value !== undefined);
+  if (tokens.length === 0 && usage.totalTokens !== undefined) {
+    tokens.push(`tokens:${formatTokens(usage.totalTokens)}`);
+  }
+  if (usage.cost !== undefined) {
+    tokens.push(formatCost(usage.cost));
+  }
+  return tokens.join(" · ") || undefined;
+};
+
+/** Formats one response for an Advisor or Scout result renderer. */
+export const formatAdvisorUsage = (usage: unknown): string | undefined => {
+  const snapshot = snapshotAdvisorUsage(usage);
+  return snapshot ? formatUsageFields(snapshot) : undefined;
+};
+
+/** Formats cumulative direct Advisor usage for a footer or session summary. */
+export const formatAdvisorUsageTotals = (
+  totals: AdvisorUsageTotals
+): string => {
+  const usage = formatUsageFields(totals);
+  const missing = totals.calls - totals.knownCalls;
+  const parts = [
+    usage,
+    missing > 0 ? `${missing} without usage data` : undefined,
+  ];
+  return (
+    parts.filter((value): value is string => value !== undefined).join(" · ") ||
+    "unavailable"
+  );
+};
+
+/** Formats the current direct Advisor usage status for the Pi footer. */
+export const formatAdvisorUsageStatus = (
+  totals: AdvisorUsageTotals
+): string | undefined => {
+  if (totals.calls === 0) {
+    return undefined;
+  }
+  const label = `Advisor: ${totals.calls} call${totals.calls === 1 ? "" : "s"}`;
+  return `${label} · ${formatAdvisorUsageTotals(totals)}`;
+};

package/src/telemetry.ts

@@ -1,270 +0,0 @@
-import type { EventBus } from "@earendil-works/pi-coding-agent";
-import { redactAndCapText } from "./conversation.js";
-
-export const BENCHMARK_TELEMETRY_CHANNEL = "pi-advisor:benchmark";
-const BENCHMARK_CONTEXT = "PI_ADVISOR_BENCHMARK_CONTEXT";
-const BENCHMARK_RUN_ID = "PI_ADVISOR_BENCHMARK_RUN_ID";
-const BENCHMARK_TOKEN = "PI_ADVISOR_BENCHMARK_TOKEN";
-const MAX_TEXT_BYTES = 2000;
-const MAX_LABELS = 32;
-const MAX_LABEL_BYTES = 160;
-
-export interface BenchmarkAdvisorStart {
-  model: string;
-  question?: string;
-  trigger?: string;
-}
-
-export interface BenchmarkAdvisorEnd extends BenchmarkAdvisorStart {
-  outcome?: string;
-  response?: string;
-  usage?: unknown;
-}
-
-export interface BenchmarkAdvisorError extends BenchmarkAdvisorStart {
-  category: "provider-error" | "empty-response" | "cancelled" | "unknown";
-}
-
-export type BenchmarkScoutEvent =
-  | { model: string; type: "call" }
-  | {
-      availableCount?: number;
-      latencyMs?: number;
-      model: string;
-      omittedBeforeScout?: number;
-      selectedCount?: number;
-      selectedLabels?: string[];
-      synthesis?: string;
-      type: "success";
-      usage?: unknown;
-    }
-  | {
-      availableCount?: number;
-      fallback?: string;
-      latencyMs?: number;
-      model: string;
-      omittedBeforeScout?: number;
-      selectedCount?: number;
-      type: "fallback";
-      usage?: unknown;
-    }
-  | { type: "cancelled" };
-
-export type BenchmarkTelemetryEvent =
-  | {
-      type: "advisor:start";
-      runId: string;
-      model: string;
-      question?: string;
-      trigger?: string;
-      timestamp: string;
-    }
-  | {
-      type: "advisor:end";
-      runId: string;
-      model: string;
-      outcome?: string;
-      response?: string;
-      timestamp: string;
-      usage?: Record<string, unknown>;
-    }
-  | {
-      type: "advisor:error";
-      category: BenchmarkAdvisorError["category"];
-      runId: string;
-      model: string;
-      timestamp: string;
-    }
-  | {
-      event: BenchmarkScoutEvent;
-      runId: string;
-      timestamp: string;
-      type: "scout";
-    }
-  | {
-      fields: Record<string, unknown>;
-      runId: string;
-      timestamp: string;
-      type: "provider-request";
-    };
-
-type BenchmarkTelemetryPayload = {
-  [K in BenchmarkTelemetryEvent["type"]]: Omit<
-    Extract<BenchmarkTelemetryEvent, { type: K }>,
-    "runId" | "timestamp"
-  >;
-}[BenchmarkTelemetryEvent["type"]];
-
-export interface BenchmarkTelemetry {
-  advisorEnd: (event: BenchmarkAdvisorEnd) => void;
-  advisorError: (event: BenchmarkAdvisorError) => void;
-  advisorStart: (event: BenchmarkAdvisorStart) => void;
-  providerRequest: (payload: unknown) => void;
-  scout: (event: BenchmarkScoutEvent) => void;
-}
-
-const finite = (value: unknown) =>
-  typeof value === "number" && Number.isFinite(value) ? value : undefined;
-
-const usageSnapshot = (usage: unknown): Record<string, unknown> | undefined => {
-  if (!usage || typeof usage !== "object") {
-    return undefined;
-  }
-  const source = usage as Record<string, unknown>;
-  const { cost } = source;
-  const costSource =
-    cost && typeof cost === "object"
-      ? (cost as Record<string, unknown>)
-      : undefined;
-  const result = Object.fromEntries(
-    ["input", "output", "cacheRead", "cacheWrite", "totalTokens"]
-      .map((key) => [key, finite(source[key])] as const)
-      .filter(([, value]) => value !== undefined)
-  ) as Record<string, unknown>;
-  const providerCost = finite(costSource?.total);
-  if (providerCost !== undefined) {
-    result.cost = { total: providerCost };
-  }
-  return Object.keys(result).length > 0 ? result : undefined;
-};
-
-const text = (value: string | undefined, maxBytes = MAX_TEXT_BYTES) =>
-  value ? redactAndCapText(value, maxBytes, true) : undefined;
-
-const labels = (values: string[] | undefined) =>
-  values
-    ?.slice(0, MAX_LABELS)
-    .map((value) => text(value, MAX_LABEL_BYTES))
-    .filter((value): value is string => Boolean(value));
-
-const PROVIDER_SENSITIVE_KEY = /message|prompt|content|input|system/i;
-const SAFE_PROVIDER_FIELDS = new Set([
-  "max_completion_tokens",
-  "max_tokens",
-  "parallel_tool_calls",
-  "reasoning_effort",
-  "temperature",
-  "top_p",
-  "tool_choice",
-]);
-const sanitizeProviderValue = (value: unknown, depth = 0): unknown => {
-  if (depth > 3 || value === null) {
-    return value;
-  }
-  if (
-    typeof value === "string" ||
-    typeof value === "number" ||
-    typeof value === "boolean"
-  ) {
-    return typeof value === "string" ? text(value, 320) : value;
-  }
-  if (Array.isArray(value)) {
-    return value
-      .slice(0, 16)
-      .map((item) => sanitizeProviderValue(item, depth + 1));
-  }
-  if (typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value as Record<string, unknown>)
-        .filter(([key]) => !PROVIDER_SENSITIVE_KEY.test(key))
-        .slice(0, 32)
-        .map(([key, item]) => [key, sanitizeProviderValue(item, depth + 1)])
-    );
-  }
-  return undefined;
-};
-
-const providerFields = (payload: unknown): Record<string, unknown> => {
-  const value =
-    payload && typeof payload === "object"
-      ? (payload as Record<string, unknown>)
-      : {};
-  return Object.fromEntries(
-    [...SAFE_PROVIDER_FIELDS]
-      .filter((key) => key in value)
-      .map((key) => [key, sanitizeProviderValue(value[key])])
-  );
-};
-
-const enabledCapability = () => {
-  const context = process.env[BENCHMARK_CONTEXT] === "1";
-  const runId = process.env[BENCHMARK_RUN_ID];
-  const token = process.env[BENCHMARK_TOKEN];
-  if (!(context && runId && token && token.length >= 32)) {
-    return;
-  }
-  return { runId, token };
-};
-
-export const createBenchmarkTelemetry = (
-  events: EventBus
-): BenchmarkTelemetry | undefined => {
-  const capability = enabledCapability();
-  if (!capability) {
-    return undefined;
-  }
-  const emit = (event: BenchmarkTelemetryPayload) => {
-    try {
-      events.emit(BENCHMARK_TELEMETRY_CHANNEL, {
-        ...event,
-        runId: capability.runId,
-        timestamp: new Date().toISOString(),
-      } satisfies BenchmarkTelemetryEvent);
-    } catch {
-      // Benchmark diagnostics must never change Advisor/Scout behavior.
-    }
-  };
-  return {
-    advisorEnd: (event) =>
-      emit({
-        model: event.model,
-        outcome: text(event.outcome, 160),
-        response: text(event.response),
-        type: "advisor:end",
-        usage: usageSnapshot(event.usage),
-      }),
-    advisorError: (event) =>
-      emit({
-        category: event.category,
-        model: event.model,
-        type: "advisor:error",
-      }),
-    advisorStart: (event) =>
-      emit({
-        model: event.model,
-        question: text(event.question),
-        trigger: text(event.trigger, 160),
-        type: "advisor:start",
-      }),
-    providerRequest: (payload) => {
-      emit({
-        fields: providerFields(payload),
-        type: "provider-request",
-      });
-    },
-    scout: (event) => {
-      if (event.type === "call" || event.type === "cancelled") {
-        emit({ event, type: "scout" });
-        return;
-      }
-      emit({
-        event: {
-          ...(event.type === "success"
-            ? {
-                selectedLabels: labels(event.selectedLabels),
-                synthesis: text(event.synthesis),
-              }
-            : { fallback: text(event.fallback, 320) }),
-          availableCount: finite(event.availableCount),
-          latencyMs: finite(event.latencyMs),
-          model: event.model,
-          omittedBeforeScout: finite(event.omittedBeforeScout),
-          selectedCount: finite(event.selectedCount),
-          type: event.type,
-          usage: usageSnapshot(event.usage),
-        },
-        type: "scout",
-      });
-    },
-  };
-};