pi-advisor-flow 0.3.6 → 0.4.0

package/src/tools.ts

@@ -24,7 +24,6 @@ import {
   advisorGitContextMaxCharsRef,
   advisorGitContextRef,
   advisorLoopThresholdRef,
-  advisorMaxCallsPerSessionRef,
   advisorOutcomeLoggingRef,
   advisorPlanGateRef,
   advisorRedactSecretsRef,
@@ -35,6 +34,7 @@ import {
   advisorUntrackedContentRef,
   contextMaxCharsRef,
   executorRef,
+  getAdvisorMaxCallsPerSession,
   isSimpleMode,
   loadConfig,
 } from "./config.js";
@@ -68,6 +68,7 @@ import {
 import {
   buildScoutManifest,
   reconstructScoutConversation,
+  SCOUT_MANIFEST_MAX_BYTES,
 } from "./scout-context.js";
 import {
   AdvisorSessionState,
@@ -75,8 +76,13 @@ import {
   type GateDecision,
   type GateTrigger,
 } from "./session-state.js";
-import type { BenchmarkTelemetry } from "./telemetry.js";
 import { readTrackedFiles, readUntrackedFiles } from "./untracked.js";
+import {
+  advisorUsageCost,
+  advisorUsageForPi,
+  formatAdvisorUsage,
+  snapshotAdvisorUsage,
+} from "./usage.js";
 
 export type {
   AdvisorInvocationRecord,
@@ -302,6 +308,7 @@ export interface AdvisorGateFailure {
   markdown?: string;
   message: string;
   ok: false;
+  usage?: unknown;
 }
 export interface AdvisorConsultationResult {
   adviceId: string;
@@ -327,14 +334,6 @@ export interface AdvisorGateResult {
 }
 export type AdvisorGateOutcome = AdvisorGateResult | AdvisorGateFailure;
 
-export const advisorUsageCost = (usage: unknown): number | undefined => {
-  const value = usage as
-    | { cost?: { total?: unknown }; totalCost?: unknown }
-    | undefined;
-  const cost = value?.cost?.total ?? value?.totalCost;
-  return typeof cost === "number" ? cost : undefined;
-};
-
 const DECISION_LINE = /^Decision\s*:\s*(proceed|revise|blocked)\s*$/i;
 const CODE_FENCE = /^(?:```|~~~)/;
 const LINE_BREAK = /\r?\n/;
@@ -431,8 +430,7 @@ export const curateAdvisorConversation = async (
   enabled = advisorScoutEnabledRef,
   runScout: typeof runAdvisorScout = runAdvisorScout,
   currentInvocationId?: string,
-  maxChars?: number,
-  telemetry?: BenchmarkTelemetry
+  maxChars?: number
 ): Promise<{
   conversation: string;
   scout?: Exclude<ScoutOutcome, { cancelled: true }>;
@@ -445,7 +443,8 @@ export const curateAdvisorConversation = async (
   }
   const built = buildScoutManifest(ctx, {
     currentInvocationId,
-    maxBytes: maxChars,
+    maxConversationChars: maxChars,
+    maxManifestBytes: SCOUT_MANIFEST_MAX_BYTES,
   });
   if (!built.ok) {
     const scout: Exclude<ScoutOutcome, { cancelled: true }> = {
@@ -470,8 +469,7 @@ export const curateAdvisorConversation = async (
     signal,
     onScout,
     undefined,
-    undefined,
-    telemetry
+    undefined
   );
   if (!outcome.ok && outcome.cancelled) {
     throw signal?.reason instanceof Error
@@ -504,8 +502,7 @@ const collectAdvisorResponse = async (
   includeUntracked?: string[],
   includeTracked?: string[],
   onScout?: (event: ScoutLifecycleEvent) => void,
-  currentInvocationId?: string,
-  telemetry?: BenchmarkTelemetry
+  currentInvocationId?: string
 ) => {
   loadConfig(ctx);
   const resolved = await resolveConfiguredModel(ctx, advisorRef, "Advisor");
@@ -551,8 +548,7 @@ const collectAdvisorResponse = async (
     advisorScoutEnabledRef,
     runAdvisorScout,
     currentInvocationId,
-    conversationBudget,
-    telemetry
+    conversationBudget
   );
   const { conversation, scout } = curated;
   const preferences = await readProjectPreferences(
@@ -643,43 +639,22 @@ export const consultAdvisor = async (
   includeUntracked?: string[],
   includeTracked?: string[],
   onScout?: (event: ScoutLifecycleEvent) => void,
-  currentInvocationId?: string,
-  telemetry?: BenchmarkTelemetry
+  currentInvocationId?: string
 ): Promise<AdvisorConsultationResult> => {
-  telemetry?.advisorStart({ model: advisorRef, question, trigger });
-  try {
-    const result = await collectAdvisorResponse(
-      ctx,
-      ADVISOR_SYSTEM,
-      question,
-      signal,
-      onChunk,
-      gitContext,
-      draft,
-      includeUntracked,
-      includeTracked,
-      onScout,
-      currentInvocationId,
-      telemetry
-    );
-    telemetry?.advisorEnd({
-      model: result.model,
-      outcome: "completed",
-      question,
-      response: result.markdown,
-      trigger,
-      usage: result.usage,
-    });
-    return { ...result, adviceId: randomUUID(), trigger };
-  } catch (error) {
-    telemetry?.advisorError({
-      category: signal?.aborted ? "cancelled" : "provider-error",
-      model: advisorRef,
-      question,
-      trigger,
-    });
-    throw error;
-  }
+  const result = await collectAdvisorResponse(
+    ctx,
+    ADVISOR_SYSTEM,
+    question,
+    signal,
+    onChunk,
+    gitContext,
+    draft,
+    includeUntracked,
+    includeTracked,
+    onScout,
+    currentInvocationId
+  );
+  return { ...result, adviceId: randomUUID(), trigger };
 };
 
 export const runAdvisorGate = async (
@@ -689,10 +664,8 @@ export const runAdvisorGate = async (
   signal?: AbortSignal,
   onChunk?: (thinking: string, text: string) => void,
   onScout?: (event: ScoutLifecycleEvent) => void,
-  currentInvocationId?: string,
-  telemetry?: BenchmarkTelemetry
+  currentInvocationId?: string
 ): Promise<AdvisorGateOutcome> => {
-  telemetry?.advisorStart({ model: advisorRef, question, trigger });
   try {
     const result = await collectAdvisorResponse(
       ctx,
@@ -705,20 +678,11 @@ export const runAdvisorGate = async (
       undefined,
       undefined,
       onScout,
-      currentInvocationId,
-      telemetry
+      currentInvocationId
     );
     const parsed = parseAutomaticDecision(result.markdown);
-    telemetry?.advisorEnd({
-      model: result.model,
-      outcome: parsed.ok ? `decision:${parsed.decision}` : parsed.category,
-      question,
-      response: result.markdown,
-      trigger,
-      usage: result.usage,
-    });
     if (!parsed.ok) {
-      return parsed;
+      return { ...parsed, usage: result.usage };
     }
     return {
       ...parsed,
@@ -728,12 +692,6 @@ export const runAdvisorGate = async (
       usage: result.usage,
     };
   } catch (error) {
-    telemetry?.advisorError({
-      category: signal?.aborted ? "cancelled" : "provider-error",
-      model: advisorRef,
-      question,
-      trigger,
-    });
     if (signal?.aborted) {
       throw error;
     }
@@ -749,6 +707,15 @@ export const runAdvisorGate = async (
   }
 };
 
+const updateAdvisorUsageStatus = (
+  ctx: ExtensionContext,
+  session: AdvisorSessionState
+) => {
+  if (ctx.hasUI) {
+    ctx.ui.setStatus("advisor-usage", session.usageStatus());
+  }
+};
+
 const notifyLocalFailure = (
   ctx: ExtensionContext,
   message: string,
@@ -814,7 +781,7 @@ const reserveAdvisorCall = (
   if (event.toolName !== "ask_advisor" || isSimpleMode()) {
     return;
   }
-  if (!session.canConsult(advisorMaxCallsPerSessionRef)) {
+  if (!session.canConsult(getAdvisorMaxCallsPerSession())) {
     const message = "Advisor call budget exhausted for this session.";
     if (ctx.hasUI) {
       ctx.ui.notify(message, "warning");
@@ -840,12 +807,20 @@ const sendAutomaticGateCall = (pi: ExtensionAPI, event: ToolCallEvent) => {
   );
 };
 
-const sendAutomaticGateFailure = (pi: ExtensionAPI, markdown: string) => {
+const sendAutomaticGateFailure = (
+  pi: ExtensionAPI,
+  markdown: string,
+  usage?: unknown
+) => {
+  const normalizedUsage = snapshotAdvisorUsage(usage);
   pi.sendMessage(
     {
       content: markdown,
       customType: "advisor-loop-result",
-      details: { text: markdown },
+      details: {
+        text: markdown,
+        ...(normalizedUsage ? { usage: normalizedUsage } : {}),
+      },
       display: true,
     },
     { deliverAs: "steer" }
@@ -864,6 +839,9 @@ const sendAutomaticGateResult = (
         advisor: result.model,
         decision: result.decision,
         text: result.markdown,
+        ...(snapshotAdvisorUsage(result.usage)
+          ? { usage: snapshotAdvisorUsage(result.usage) }
+          : {}),
       },
       display: true,
     },
@@ -877,8 +855,7 @@ const handleAutomaticGate = async (
   ctx: ExtensionContext,
   session: AdvisorSessionState,
   runGate: typeof runAdvisorGate,
-  scoutStatus: ScoutStatusManager,
-  telemetry?: BenchmarkTelemetry
+  scoutStatus: ScoutStatusManager
 ): Promise<ToolCallEventResult | undefined> => {
   if (
     isSimpleMode() ||
@@ -893,7 +870,7 @@ const handleAutomaticGate = async (
     return;
   }
   const reason = `Advisor loop gate: normalized signature for ${event.toolName} repeated ${advisorLoopThresholdRef} times without a materially different tool action.`;
-  if (!session.canConsult(advisorMaxCallsPerSessionRef)) {
+  if (!session.canConsult(getAdvisorMaxCallsPerSession())) {
     const failure = failureEffect(
       "budget-exhausted",
       "Advisor gate call budget is exhausted.",
@@ -931,8 +908,7 @@ const handleAutomaticGate = async (
           ensureGateCall();
         }
       },
-      event.toolCallId,
-      telemetry
+      event.toolCallId
     );
     ensureGateCall();
     if (!result.ok) {
@@ -942,7 +918,9 @@ const handleAutomaticGate = async (
         kind: "gate",
         model: advisorRef,
         trigger: "repeated-tool-call",
+        usage: result.usage,
       });
+      updateAdvisorUsageStatus(ctx, session);
       const failure = failureEffect(
         result.category,
         result.message,
@@ -951,7 +929,8 @@ const handleAutomaticGate = async (
       );
       sendAutomaticGateFailure(
         pi,
-        `**Advisor gate failure (${result.category}):** ${result.message}`
+        `**Advisor gate failure (${result.category}):** ${result.message}`,
+        result.usage
       );
       return failure.block
         ? { block: true, reason: `${reason}\n${failure.reason}` }
@@ -966,6 +945,7 @@ const handleAutomaticGate = async (
       trigger: result.trigger,
       usage: result.usage,
     });
+    updateAdvisorUsageStatus(ctx, session);
     sendAutomaticGateResult(pi, result);
     if (result.decision === "proceed") {
       session.resetRepetition();
@@ -1011,6 +991,7 @@ interface AdvisorToolDetails {
   thinking?: string;
   trackedBytes?: number;
   untrackedBytes?: number;
+  usage?: unknown;
 }
 interface AdvisorRenderState {
   phase?: string;
@@ -1059,7 +1040,7 @@ export const scoutDetailsFromEvent = (
         selectedLabels: outcome.selectedLabels,
         status: "curated",
         synthesis: outcome.selection.synthesis,
-        usage: outcome.metrics.usage,
+        usage: snapshotAdvisorUsage(outcome.metrics.usage),
       }
     : {
         availableCount: outcome.metrics.availableCount,
@@ -1069,7 +1050,7 @@ export const scoutDetailsFromEvent = (
         omittedBeforeScout: outcome.metrics.omittedBeforeScout,
         selectedCount: 0,
         status: "fallback",
-        usage: outcome.metrics.usage,
+        usage: snapshotAdvisorUsage(outcome.metrics.usage),
       };
 };
 
@@ -1173,6 +1154,10 @@ export const renderScoutDetails = (
       `  ${scout.model}${scout.selectedCount === undefined ? "" : ` · ${scout.selectedCount} kept / ${Math.max(0, (scout.availableCount ?? 0) - scout.selectedCount)} omitted`}${scout.latencyMs === undefined ? "" : ` · ${(scout.latencyMs / 1000).toFixed(1)}s`}`
     ),
   ];
+  const usage = formatAdvisorUsage(scout.usage);
+  if (usage) {
+    lines.push(theme.fg("dim", `  Usage: ${usage}`));
+  }
   if (scout.fallbackReason) {
     lines.push(theme.fg("warning", `  ${scout.fallbackReason}`));
   }
@@ -1293,6 +1278,10 @@ const renderFinalAdvisorResult = (
   if (details?.advisor) {
     lines.push(theme.fg("dim", `  ${details.advisor}`));
   }
+  const usage = formatAdvisorUsage(details?.usage);
+  if (usage) {
+    lines.push(theme.fg("dim", `  Usage: ${usage}`));
+  }
   const attachments = [
     details?.draftBytes
       ? `Draft attached · ${details.draftBytes} B`
@@ -1357,7 +1346,6 @@ export const registerAdvisorTool = (
   dependencies: {
     runGate?: typeof runAdvisorGate;
     statusManager?: ScoutStatusManager;
-    telemetry?: BenchmarkTelemetry;
   } = {}
 ) => {
   const reservedCalls = new Set<string>();
@@ -1385,7 +1373,12 @@ export const registerAdvisorTool = (
     "advisor-loop-result",
     (message, { expanded }, theme) => {
       const details = message.details as
-        | { decision?: GateDecision; text?: string; advisor?: string }
+        | {
+            advisor?: string;
+            decision?: GateDecision;
+            text?: string;
+            usage?: unknown;
+          }
         | undefined;
       const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
       box.addChild(
@@ -1401,6 +1394,10 @@ export const registerAdvisorTool = (
       if (details?.advisor) {
         box.addChild(new Text(theme.fg("dim", `  ${details.advisor}`), 0, 0));
       }
+      const usage = formatAdvisorUsage(details?.usage);
+      if (usage) {
+        box.addChild(new Text(theme.fg("dim", `  Usage: ${usage}`), 0, 0));
+      }
       if (details?.text) {
         box.addChild(
           new Markdown(
@@ -1428,10 +1425,13 @@ export const registerAdvisorTool = (
     }
   );
 
-  pi.on("session_start", () => {
+  pi.on("session_start", (_event, ctx) => {
     session.resetTask();
     reservedCalls.clear();
     herdrAdvisorBlock.clear();
+    if (ctx?.hasUI) {
+      ctx.ui.setStatus("advisor-usage", undefined);
+    }
   });
 
   pi.on("before_agent_start", (_event, ctx) => {
@@ -1442,7 +1442,7 @@ export const registerAdvisorTool = (
     const guidelines = advisorInvocationGuidelines();
     const budget = isSimpleMode()
       ? undefined
-      : session.remainingCalls(advisorMaxCallsPerSessionRef);
+      : session.remainingCalls(getAdvisorMaxCallsPerSession());
     if (budget !== undefined) {
       guidelines.push(
         `Advisor calls remaining this session: ${budget}.\nReserve calls for material decisions, repeated failures, or final review.`
@@ -1476,8 +1476,7 @@ export const registerAdvisorTool = (
       ctx,
       session,
       dependencies.runGate ?? runAdvisorGate,
-      scoutStatus,
-      dependencies.telemetry
+      scoutStatus
     );
   });
 
@@ -1488,7 +1487,7 @@ export const registerAdvisorTool = (
     if (isSimpleMode() || session.blocked || !advisorSessionSummaryRef) {
       return;
     }
-    const summary = session.summary(advisorMaxCallsPerSessionRef);
+    const summary = session.summary(getAdvisorMaxCallsPerSession());
     if (summary && ctx.hasUI) {
       ctx.ui.notify(summary, "info");
     }
@@ -1498,11 +1497,15 @@ export const registerAdvisorTool = (
     reservedCalls.clear();
     scoutStatus.clear(ctx);
     herdrAdvisorBlock.clear();
+    if (ctx?.hasUI) {
+      ctx.ui.setStatus("advisor-usage", undefined);
+    }
   });
 
   pi.registerTool({
     description:
       "Consult the on-demand Advisor model for strategic guidance. Call with an empty object for a contextual review; attach an optional draft for concrete plan or completion review. If the Advisor explicitly names a missing file, you may make a sequential follow-up call with includeTrackedFiles when enabled and relevant.",
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: usage and consent paths remain explicit at the tool boundary.
     async execute(_id, params, signal, onUpdate, ctx) {
       reservedCalls.delete(_id);
       if (
@@ -1514,7 +1517,7 @@ export const registerAdvisorTool = (
         );
       }
       if (!isSimpleMode()) {
-        if (!session.canConsult(advisorMaxCallsPerSessionRef)) {
+        if (!session.canConsult(getAdvisorMaxCallsPerSession())) {
           throw new Error("Advisor call budget exhausted for this session.");
         }
         session.consumeCall();
@@ -1554,8 +1557,7 @@ export const registerAdvisorTool = (
               },
             });
           },
-          _id,
-          dependencies.telemetry
+          _id
         );
         session.issueAdvice(
           result.adviceId,
@@ -1571,6 +1573,11 @@ export const registerAdvisorTool = (
           trigger: "executor-requested",
           usage: result.usage,
         });
+        const usage = snapshotAdvisorUsage(result.usage);
+        const piUsage = advisorUsageForPi(result.usage);
+        if (ctx.hasUI) {
+          ctx.ui.setStatus("advisor-usage", session.usageStatus());
+        }
         return {
           content: [
             {
@@ -1589,7 +1596,9 @@ export const registerAdvisorTool = (
             thinking: result.thinkingText,
             trackedBytes: result.trackedBytes,
             untrackedBytes: result.untrackedBytes,
+            ...(usage ? { usage } : {}),
           },
+          ...(piUsage ? { usage: piUsage } : {}),
         };
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -1600,6 +1609,9 @@ export const registerAdvisorTool = (
           model: advisorRef,
           trigger: "executor-requested",
         });
+        if (ctx.hasUI) {
+          ctx.ui.setStatus("advisor-usage", session.usageStatus());
+        }
         notifyLocalFailure(ctx, message);
         notifyHerdrAdvisorFailure("Advisor consultation failed", message);
         throw error;

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)}`;
+};