pi-advisor-flow 0.4.0 → 0.5.1

package/src/tools.ts

@@ -10,7 +10,14 @@ import {
   type ToolCallEventResult,
   type ToolRenderResultOptions,
 } from "@earendil-works/pi-coding-agent";
-import { Box, Markdown, Text } from "@earendil-works/pi-tui";
+import {
+  Box,
+  type Component,
+  Markdown,
+  Text,
+  truncateToWidth,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import {
   advisorAutoLoopGateRef,
@@ -35,6 +42,7 @@ import {
   contextMaxCharsRef,
   executorRef,
   getAdvisorMaxCallsPerSession,
+  getAdvisorSettings,
   isSimpleMode,
   loadConfig,
 } from "./config.js";
@@ -57,7 +65,12 @@ import {
   herdrAdvisorBlock,
   notifyHerdrAdvisorFailure,
 } from "./herdr.js";
-import { collectTextStream, resolveConfiguredModel } from "./model-stream.js";
+import {
+  ADVISOR_STREAM_UPDATE_INTERVAL_MS,
+  collectTextStream,
+  createCoalescedUpdate,
+  resolveConfiguredModel,
+} from "./model-stream.js";
 import { ADOPTIONS, appendOutcome, VALIDATIONS } from "./outcomes.js";
 import { readProjectPreferences } from "./preferences.js";
 import {
@@ -105,6 +118,56 @@ export const SPINNER_FRAMES = [
   "⠇",
   "⠏",
 ];
+
+const THINKING_PREFIX = "  💭 ";
+const THINKING_PREFIX_WIDTH = visibleWidth(THINKING_PREFIX);
+type ThinkingTheme = Pick<Theme, "fg">;
+
+/**
+ * Renders visible nested-model thinking with the same Markdown semantics as
+ * Pi's assistant thinking blocks while keeping the compact speech-bubble cue.
+ * The prefix is added after Markdown parsing so it cannot change block syntax.
+ *
+ * Note: During streaming, incomplete Markdown (e.g., `**text` without closing `**`)
+ * displays raw markers transiently until delimiters arrive. This mirrors expected
+ * behavior when typing Markdown incrementally and is acceptable in the context
+ * of brief thinking previews. When thinking is complete, all markers render.
+ */
+class ThinkingMarkdown implements Component {
+  private readonly markdown: Markdown;
+  private readonly prefix: string;
+
+  constructor(thinking: string, theme: ThinkingTheme) {
+    this.markdown = new Markdown(thinking.trim(), 0, 0, getMarkdownTheme(), {
+      color: (text) => theme.fg("thinkingText", text),
+      italic: true,
+    });
+    this.prefix = theme.fg("thinkingText", THINKING_PREFIX);
+  }
+
+  render(width: number): string[] {
+    const renderWidth = Math.max(1, Math.floor(width));
+    const contentWidth = Math.max(1, renderWidth - THINKING_PREFIX_WIDTH);
+    const lines = this.markdown.render(contentWidth);
+    return lines.map((line, index) =>
+      truncateToWidth(
+        index === 0 ? `${this.prefix}${line}` : line,
+        renderWidth,
+        ""
+      )
+    );
+  }
+
+  invalidate(): void {
+    this.markdown.invalidate();
+  }
+}
+
+export const renderThinkingMarkdown = (
+  thinking: string,
+  theme: ThinkingTheme
+): Component => new ThinkingMarkdown(thinking, theme);
+
 export const resolveAdvisorRequest = (question?: string) =>
   question?.trim() || undefined;
 export const advisorMessageText = (
@@ -712,7 +775,10 @@ const updateAdvisorUsageStatus = (
   session: AdvisorSessionState
 ) => {
   if (ctx.hasUI) {
-    ctx.ui.setStatus("advisor-usage", session.usageStatus());
+    ctx.ui.setStatus(
+      "advisor-usage",
+      getAdvisorSettings().showUsageFooter ? session.usageStatus() : undefined
+    );
   }
 };
 
@@ -740,12 +806,15 @@ export const gateFailureEffectForMode = (
     : ("session-blocked" as const);
 };
 
-const gateDecisionEffect = (decision: GateDecision) => {
+const gateDecisionEffect = (
+  decision: GateDecision,
+  failureMode: "block-session" | "block-tool" | "warn-and-continue"
+) => {
   if (decision === "proceed") {
     return "continued" as const;
   }
   return decision === "blocked"
-    ? ("session-blocked" as const)
+    ? gateFailureEffectForMode(failureMode)
     : ("tool-blocked" as const);
 };
 
@@ -753,15 +822,42 @@ const failureEffect = (
   category: GateFailureCategory,
   message: string,
   ctx: ExtensionContext,
-  session: AdvisorSessionState
+  session: AdvisorSessionState,
+  failureMode: "block-session" | "block-tool" | "warn-and-continue"
 ) => {
   const reason = `Advisor gate ${category}: ${message}`;
-  notifyLocalFailure(ctx, message, advisorFailureModeRef === "block-session");
+  notifyLocalFailure(ctx, message, failureMode === "block-session");
   notifyHerdrAdvisorFailure("Advisor gate failure", reason);
-  if (advisorFailureModeRef === "warn-and-continue") {
+  if (failureMode === "warn-and-continue") {
+    return { block: false, effect: "continued" as const, reason };
+  }
+  if (failureMode === "block-tool") {
+    return { block: true, effect: "tool-blocked" as const, reason };
+  }
+  session.block(reason);
+  herdrAdvisorBlock.set(reason);
+  if (advisorBlockOnBlockedRef) {
+    ctx.abort();
+  }
+  return { block: true, effect: "session-blocked" as const, reason };
+};
+
+const blockedDecisionEffect = (
+  reason: string,
+  ctx: ExtensionContext,
+  session: AdvisorSessionState,
+  failureMode: "block-session" | "block-tool" | "warn-and-continue"
+) => {
+  if (failureMode === "warn-and-continue") {
+    if (ctx.hasUI) {
+      ctx.ui.notify(
+        "Advisor gate returned blocked; continuing by configuration.",
+        "warning"
+      );
+    }
     return { block: false, effect: "continued" as const, reason };
   }
-  if (advisorFailureModeRef === "block-tool") {
+  if (failureMode === "block-tool") {
     return { block: true, effect: "tool-blocked" as const, reason };
   }
   session.block(reason);
@@ -870,12 +966,14 @@ const handleAutomaticGate = async (
     return;
   }
   const reason = `Advisor loop gate: normalized signature for ${event.toolName} repeated ${advisorLoopThresholdRef} times without a materially different tool action.`;
+  const failureMode = advisorFailureModeRef;
   if (!session.canConsult(getAdvisorMaxCallsPerSession())) {
     const failure = failureEffect(
       "budget-exhausted",
       "Advisor gate call budget is exhausted.",
       ctx,
-      session
+      session,
+      failureMode
     );
     return failure.block ? { block: true, reason: failure.reason } : undefined;
   }
@@ -913,7 +1011,7 @@ const handleAutomaticGate = async (
     ensureGateCall();
     if (!result.ok) {
       session.recordInvocation({
-        executionEffect: gateFailureEffectForMode(advisorFailureModeRef),
+        executionEffect: gateFailureEffectForMode(failureMode),
         failure: result.category,
         kind: "gate",
         model: advisorRef,
@@ -925,7 +1023,8 @@ const handleAutomaticGate = async (
         result.category,
         result.message,
         ctx,
-        session
+        session,
+        failureMode
       );
       sendAutomaticGateFailure(
         pi,
@@ -939,7 +1038,7 @@ const handleAutomaticGate = async (
     session.recordInvocation({
       cost: advisorUsageCost(result.usage),
       decision: result.decision,
-      executionEffect: gateDecisionEffect(result.decision),
+      executionEffect: gateDecisionEffect(result.decision, failureMode),
       kind: "gate",
       model: result.model,
       trigger: result.trigger,
@@ -953,11 +1052,13 @@ const handleAutomaticGate = async (
     }
     const gateReason = `Advisor loop review: ${result.markdown}`;
     if (result.decision === "blocked") {
-      session.block(gateReason);
-      herdrAdvisorBlock.set(gateReason);
-      if (advisorBlockOnBlockedRef) {
-        ctx.abort();
-      }
+      const effect = blockedDecisionEffect(
+        gateReason,
+        ctx,
+        session,
+        failureMode
+      );
+      return effect.block ? { block: true, reason: effect.reason } : undefined;
     }
     return { block: true, reason: gateReason };
   } finally {
@@ -1074,6 +1175,11 @@ export class ScoutStatusManager {
   readonly #active = new Set<symbol>();
   readonly #known = new Set<symbol>();
   readonly #retired = new Set<symbol>();
+  private readonly showStatus: boolean;
+
+  constructor(showStatus = true) {
+    this.showStatus = showStatus;
+  }
 
   register(token: symbol) {
     if (!this.#retired.has(token)) {
@@ -1088,7 +1194,9 @@ export class ScoutStatusManager {
     this.#known.add(token);
     if (event.type === "call" || event.type === "chunk") {
       this.#active.add(token);
-      ctx.ui.setStatus("advisor-scout", "Scout curating…");
+      if (this.showStatus) {
+        ctx.ui.setStatus("advisor-scout", "Scout curating…");
+      }
       return;
     }
     this.release(ctx, token);
@@ -1098,7 +1206,7 @@ export class ScoutStatusManager {
     this.#active.delete(token);
     this.#known.delete(token);
     this.#retired.add(token);
-    if (!ctx.hasUI) {
+    if (!(ctx.hasUI && this.showStatus)) {
       return;
     }
     ctx.ui.setStatus(
@@ -1113,7 +1221,7 @@ export class ScoutStatusManager {
     }
     this.#known.clear();
     this.#active.clear();
-    if (ctx.hasUI) {
+    if (ctx.hasUI && this.showStatus) {
       ctx.ui.setStatus("advisor-scout", undefined);
     }
   }
@@ -1154,28 +1262,28 @@ 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 (getAdvisorSettings().showUsageDetails) {
+    const usage = formatAdvisorUsage(scout.usage);
+    if (usage) {
+      lines.push(theme.fg("dim", `  Usage: ${usage}`));
+    }
   }
   if (scout.fallbackReason) {
     lines.push(theme.fg("warning", `  ${scout.fallbackReason}`));
   }
-  if (scout.thinking && active) {
-    lines.push(
-      theme.fg(
-        "thinkingText",
-        `  💭 ${scout.thinking.replace(/\n/g, " ").slice(-200)}`
-      )
-    );
+  const thinking = scout.thinking && active ? scout.thinking.slice(-200) : "";
+  box.addChild(new Text(lines.join("\n"), 0, 0));
+  if (thinking.trim()) {
+    box.addChild(renderThinkingMarkdown(thinking, theme));
   }
+  const expandedLines: string[] = [];
   if (expanded && scout.selectedLabels?.length) {
-    lines.push(
+    expandedLines.push(
       theme.fg("dim", `  Selected: ${scout.selectedLabels.join("; ")}`)
     );
   }
   if (expanded && scout.synthesis) {
-    lines.push(
+    expandedLines.push(
       theme.fg(
         "dim",
         `  Scout synthesis (untrusted inference): ${scout.synthesis}`
@@ -1183,14 +1291,16 @@ export const renderScoutDetails = (
     );
   }
   if (expanded && scout.omittedBeforeScout) {
-    lines.push(
+    expandedLines.push(
       theme.fg(
         "dim",
         `  ${scout.omittedBeforeScout} group(s) omitted before Scout`
       )
     );
   }
-  box.addChild(new Text(lines.join("\n"), 0, 0));
+  if (expandedLines.length > 0) {
+    box.addChild(new Text(expandedLines.join("\n"), 0, 0));
+  }
 };
 
 const syncRenderPhase = (context: AdvisorToolContext, phase: string) => {
@@ -1230,14 +1340,14 @@ const renderPartialAdvisorResult = (
   const lines = [
     `${theme.fg("warning", theme.bold(`◆ ADVISOR ${frame}`))} ${theme.fg("dim", "· Working…")}`,
   ];
-  if (details?.thinking) {
+  box.addChild(new Text(lines.join("\n"), 0, 0));
+  if (details?.thinking?.trim()) {
     const thought =
       details.thinking.length > 200
         ? details.thinking.slice(-200)
         : details.thinking;
-    lines.push(theme.fg("thinkingText", `  💭 ${thought.replace(/\n/g, " ")}`));
+    box.addChild(renderThinkingMarkdown(thought, theme));
   }
-  box.addChild(new Text(lines.join("\n"), 0, 0));
   if (details?.text) {
     box.addChild(
       new Markdown(
@@ -1278,9 +1388,11 @@ 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}`));
+  if (getAdvisorSettings().showUsageDetails) {
+    const usage = formatAdvisorUsage(details?.usage);
+    if (usage) {
+      lines.push(theme.fg("dim", `  Usage: ${usage}`));
+    }
   }
   const attachments = [
     details?.draftBytes
@@ -1299,17 +1411,14 @@ const renderFinalAdvisorResult = (
   if (attachments.length) {
     lines.push(theme.fg("dim", `  ${attachments.join(" · ")}`));
   }
-  if (details?.thinking) {
-    const thought = details.thinking.replace(/\n/g, " ").slice(0, 300);
-    lines.push(
-      theme.fg(
-        "thinkingText",
-        `  💭 ${thought}${details.thinking.length > 300 ? "…" : ""}`
-      )
-    );
-  }
+  const thinking = details?.thinking?.trim()
+    ? `${details.thinking.slice(0, 300)}${details.thinking.length > 300 ? "…" : ""}`
+    : "";
   const displayAdvice = advice || "(Advisor returned no advice.)";
   box.addChild(new Text(lines.join("\n"), 0, 0));
+  if (thinking) {
+    box.addChild(renderThinkingMarkdown(thinking, theme));
+  }
   box.addChild(
     new Markdown(
       adviceForDisplay(displayAdvice, expanded),
@@ -1344,10 +1453,14 @@ export const registerAdvisorTool = (
   pi: ExtensionAPI,
   session: AdvisorSessionState = advisorSessionState,
   dependencies: {
+    appendOutcome?: typeof appendOutcome;
+    consult?: typeof consultAdvisor;
     runGate?: typeof runAdvisorGate;
     statusManager?: ScoutStatusManager;
   } = {}
 ) => {
+  const appendAdvisorOutcome = dependencies.appendOutcome ?? appendOutcome;
+  const requestAdvisor = dependencies.consult ?? consultAdvisor;
   const reservedCalls = new Set<string>();
   const scoutStatus = dependencies.statusManager ?? new ScoutStatusManager();
 
@@ -1394,9 +1507,11 @@ 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 (getAdvisorSettings().showUsageDetails) {
+        const usage = formatAdvisorUsage(details?.usage);
+        if (usage) {
+          box.addChild(new Text(theme.fg("dim", `  Usage: ${usage}`), 0, 0));
+        }
       }
       if (details?.text) {
         box.addChild(
@@ -1505,7 +1620,6 @@ export const registerAdvisorTool = (
   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 (
@@ -1524,13 +1638,24 @@ export const registerAdvisorTool = (
       }
       herdrAdvisorActivity.start();
       let scoutDetails: ScoutToolDetails | undefined;
+      const coalescedUpdate = createCoalescedUpdate(
+        (update: Parameters<NonNullable<typeof onUpdate>>[0]) =>
+          onUpdate?.(update),
+        ADVISOR_STREAM_UPDATE_INTERVAL_MS
+      );
+      const flushUpdate = () => {
+        const result = coalescedUpdate.flush();
+        if (result.failed) {
+          throw result.error;
+        }
+      };
       try {
-        const result = await consultAdvisor(
+        const result = await requestAdvisor(
           ctx,
           resolveAdvisorRequest(params.question),
           signal,
           (t, tx) =>
-            onUpdate?.({
+            coalescedUpdate.update({
               content: [{ text: tx, type: "text" }],
               details: {
                 advisor: advisorRef,
@@ -1548,7 +1673,7 @@ export const registerAdvisorTool = (
           params.includeTrackedFiles,
           (event) => {
             scoutDetails = scoutDetailsFromEvent(event, scoutDetails);
-            onUpdate?.({
+            coalescedUpdate.update({
               content: [{ text: scoutDetails.text ?? "", type: "text" }],
               details: {
                 advisor: advisorRef,
@@ -1559,6 +1684,7 @@ export const registerAdvisorTool = (
           },
           _id
         );
+        flushUpdate();
         session.issueAdvice(
           result.adviceId,
           result.markdown,
@@ -1575,9 +1701,7 @@ export const registerAdvisorTool = (
         });
         const usage = snapshotAdvisorUsage(result.usage);
         const piUsage = advisorUsageForPi(result.usage);
-        if (ctx.hasUI) {
-          ctx.ui.setStatus("advisor-usage", session.usageStatus());
-        }
+        updateAdvisorUsageStatus(ctx, session);
         return {
           content: [
             {
@@ -1601,6 +1725,10 @@ export const registerAdvisorTool = (
           ...(piUsage ? { usage: piUsage } : {}),
         };
       } catch (error) {
+        // Publish the latest partial state before surfacing a provider or
+        // execution error. A failure from the UI sink must not replace the
+        // original error because this path is also used for provider failures.
+        coalescedUpdate.flush();
         const message = error instanceof Error ? error.message : String(error);
         session.recordInvocation({
           executionEffect: "continued",
@@ -1609,13 +1737,12 @@ export const registerAdvisorTool = (
           model: advisorRef,
           trigger: "executor-requested",
         });
-        if (ctx.hasUI) {
-          ctx.ui.setStatus("advisor-usage", session.usageStatus());
-        }
+        updateAdvisorUsageStatus(ctx, session);
         notifyLocalFailure(ctx, message);
         notifyHerdrAdvisorFailure("Advisor consultation failed", message);
         throw error;
       } finally {
+        coalescedUpdate.cancel();
         herdrAdvisorActivity.finish();
       }
     },
@@ -1692,18 +1819,19 @@ export const registerAdvisorTool = (
           details: { recorded: false },
         };
       }
-      const advice = session.claimAdvice(params.adviceId);
+      const advice = session.reserveAdvice(params.adviceId);
       if (!advice) {
-        throw new Error("Unknown or already recorded adviceId.");
+        throw new Error("Unknown, already recorded, or pending adviceId.");
       }
       try {
-        await appendOutcome({
+        await appendAdvisorOutcome({
           adoption: params.adoption as (typeof ADOPTIONS)[number],
           advice: advice.advice,
           trigger: advice.trigger,
           validationStatus:
             params.validationStatus as (typeof VALIDATIONS)[number],
         });
+        session.commitAdvice(params.adviceId);
         return {
           content: [
             { text: "Advisor outcome recorded locally.", type: "text" },
@@ -1711,6 +1839,7 @@ export const registerAdvisorTool = (
           details: { recorded: true },
         };
       } catch {
+        session.releaseAdvice(params.adviceId);
         if (ctx.hasUI) {
           ctx.ui.notify(
             "Advisor outcome could not be recorded locally.",