pi-advisor-flow 0.3.0 → 0.3.3

package/src/tools.ts

@@ -1,9 +1,5 @@
 import { randomUUID } from "node:crypto";
-import {
-  type AssistantMessage,
-  type Message,
-  stream,
-} from "@earendil-works/pi-ai/compat";
+import type { Message } from "@earendil-works/pi-ai/compat";
 import {
   type AgentToolResult,
   type ExtensionAPI,
@@ -33,13 +29,14 @@ import {
   advisorPlanGateRef,
   advisorRedactSecretsRef,
   advisorRef,
+  advisorScoutEnabledRef,
   advisorSessionSummaryRef,
   advisorTrackedFileContentRef,
   advisorUntrackedContentRef,
   contextMaxCharsRef,
+  executorRef,
   isSimpleMode,
   loadConfig,
-  splitRef,
 } from "./config.js";
 import {
   recentConversation,
@@ -60,8 +57,18 @@ import {
   herdrAdvisorBlock,
   notifyHerdrAdvisorFailure,
 } from "./herdr.js";
+import { collectTextStream, resolveConfiguredModel } from "./model-stream.js";
 import { ADOPTIONS, appendOutcome, VALIDATIONS } from "./outcomes.js";
 import { readProjectPreferences } from "./preferences.js";
+import {
+  runAdvisorScout,
+  type ScoutLifecycleEvent,
+  type ScoutOutcome,
+} from "./scout.js";
+import {
+  buildScoutManifest,
+  reconstructScoutConversation,
+} from "./scout-context.js";
 import {
   AdvisorSessionState,
   type ConsultationTrigger,
@@ -301,6 +308,7 @@ export interface AdvisorConsultationResult {
   markdown: string;
   model: string;
   preferenceBytes?: number;
+  scout?: Exclude<ScoutOutcome, { cancelled: true }>;
   thinkingText: string;
   trackedBytes?: number;
   trigger: ConsultationTrigger;
@@ -414,6 +422,67 @@ export const parseAutomaticDecision = (
 const adviceForText = (result: AdvisorGateResult) =>
   `**Decision: ${result.decision}**\n\n${result.markdown}`;
 
+export const curateAdvisorConversation = async (
+  ctx: ExtensionContext,
+  legacyConversation: string,
+  signal?: AbortSignal,
+  onScout?: (event: ScoutLifecycleEvent) => void,
+  enabled = advisorScoutEnabledRef,
+  runScout: typeof runAdvisorScout = runAdvisorScout,
+  currentInvocationId?: string,
+  maxChars?: number
+): Promise<{
+  conversation: string;
+  scout?: Exclude<ScoutOutcome, { cancelled: true }>;
+}> => {
+  if (!enabled) {
+    return { conversation: legacyConversation };
+  }
+  if (maxChars !== undefined && maxChars <= 0) {
+    return { conversation: "" };
+  }
+  const built = buildScoutManifest(ctx, {
+    currentInvocationId,
+    maxBytes: maxChars,
+  });
+  if (!built.ok) {
+    const scout: Exclude<ScoutOutcome, { cancelled: true }> = {
+      category: built.reason,
+      message: built.message,
+      metrics: {
+        availableCount: 0,
+        inputBytes: 0,
+        latencyMs: 0,
+        omittedBeforeScout: 0,
+        selectedCount: 0,
+      },
+      model: executorRef,
+      ok: false,
+    };
+    onScout?.({ outcome: scout, type: "fallback" });
+    return { conversation: legacyConversation, scout };
+  }
+  const outcome = await runScout(ctx, built.manifest, signal, onScout);
+  if (!outcome.ok && outcome.cancelled) {
+    throw signal?.reason instanceof Error
+      ? signal.reason
+      : new Error("Advisor operation cancelled during Scout.");
+  }
+  let conversation = legacyConversation;
+  if (outcome.ok) {
+    conversation =
+      maxChars === undefined
+        ? outcome.conversation
+        : reconstructScoutConversation(
+            built.manifest,
+            outcome.selection.selectedIds,
+            outcome.selection.synthesis,
+            maxChars
+          );
+  }
+  return { conversation, scout: outcome };
+};
+
 const collectAdvisorResponse = async (
   ctx: ExtensionContext,
   systemPrompt: string,
@@ -423,21 +492,12 @@ const collectAdvisorResponse = async (
   gitContext?: GitContextLevel,
   draft?: string,
   includeUntracked?: string[],
-  includeTracked?: string[]
+  includeTracked?: string[],
+  onScout?: (event: ScoutLifecycleEvent) => void,
+  currentInvocationId?: string
 ) => {
   loadConfig(ctx);
-  const [provider, modelId] = splitRef(advisorRef);
-  const model = ctx.modelRegistry.find(provider, modelId);
-  if (!model) {
-    throw new Error(`Advisor model not found: ${advisorRef}`);
-  }
-  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-  if (!auth.ok) {
-    throw new Error((auth as { error: string }).error);
-  }
-  if (!auth.apiKey) {
-    throw new Error(`No API key for ${advisorRef}`);
-  }
+  const resolved = await resolveConfiguredModel(ctx, advisorRef, "Advisor");
 
   // The user setting is the ceiling; the Executor may only narrow it.
   const allowed = advisorGitContextRef;
@@ -464,10 +524,25 @@ const collectAdvisorResponse = async (
   );
   // Repository context spends part of the shared budget, so a large patch
   // cannot silently push the conversation past the model's context window.
-  const conversation = advisorRequestConversation(
+  const conversationBudget = Math.max(
+    0,
+    contextMaxCharsRef - changeText.length
+  );
+  const legacyConversation = advisorRequestConversation(
     ctx,
-    Math.max(0, contextMaxCharsRef - changeText.length)
+    conversationBudget
   );
+  const curated = await curateAdvisorConversation(
+    ctx,
+    legacyConversation,
+    signal,
+    onScout,
+    advisorScoutEnabledRef,
+    runAdvisorScout,
+    currentInvocationId,
+    conversationBudget
+  );
+  const { conversation, scout } = curated;
   const preferences = await readProjectPreferences(
     ctx,
     8 * 1024,
@@ -519,41 +594,14 @@ const collectAdvisorResponse = async (
     },
   ];
 
-  let thinkingText = "";
-  let responseText = "";
-  const eventStream = stream(
-    model,
-    { messages, systemPrompt },
-    {
-      apiKey: auth.apiKey,
-      env: auth.env,
-      headers: auth.headers,
-      reasoning: advisorEffortRef as never,
-      signal,
-    }
-  );
-
-  for await (const event of eventStream) {
-    if (event.type === "thinking_delta") {
-      thinkingText += event.delta;
-      onChunk?.(thinkingText, responseText);
-    } else if (event.type === "text_delta") {
-      responseText += event.delta;
-      onChunk?.(thinkingText, responseText);
-    }
-  }
-
-  const response = await eventStream.result();
-  const lastAssistant = [response].find(
-    (m): m is AssistantMessage => m.role === "assistant"
-  );
-  const markdown =
-    lastAssistant?.content
-      .filter(
-        (part): part is { type: "text"; text: string } => part.type === "text"
-      )
-      .map((part) => part.text)
-      .join("\n") || responseText;
+  const streamed = await collectTextStream(resolved, {
+    messages,
+    onChunk,
+    reasoning: advisorEffortRef,
+    signal,
+    systemPrompt,
+  });
+  const markdown = streamed.text;
   if (!markdown.trim()) {
     throw new Error("Advisor returned no advice.");
   }
@@ -562,14 +610,13 @@ const collectAdvisorResponse = async (
     markdown,
     model: advisorRef,
     preferenceBytes: preferences?.bytes,
-    thinkingText,
+    thinkingText: streamed.thinking,
     trackedBytes:
       tracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
     untrackedBytes:
       untracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
-    usage: (
-      lastAssistant as (AssistantMessage & { usage?: unknown }) | undefined
-    )?.usage,
+    usage: streamed.usage,
+    ...(scout ? { scout } : {}),
   };
 };
 
@@ -582,7 +629,9 @@ export const consultAdvisor = async (
   gitContext?: GitContextLevel,
   draft?: string,
   includeUntracked?: string[],
-  includeTracked?: string[]
+  includeTracked?: string[],
+  onScout?: (event: ScoutLifecycleEvent) => void,
+  currentInvocationId?: string
 ): Promise<AdvisorConsultationResult> => {
   const result = await collectAdvisorResponse(
     ctx,
@@ -593,7 +642,9 @@ export const consultAdvisor = async (
     gitContext,
     draft,
     includeUntracked,
-    includeTracked
+    includeTracked,
+    onScout,
+    currentInvocationId
   );
   return { ...result, adviceId: randomUUID(), trigger };
 };
@@ -603,7 +654,9 @@ export const runAdvisorGate = async (
   question: string,
   trigger: GateTrigger = "repeated-tool-call",
   signal?: AbortSignal,
-  onChunk?: (thinking: string, text: string) => void
+  onChunk?: (thinking: string, text: string) => void,
+  onScout?: (event: ScoutLifecycleEvent) => void,
+  currentInvocationId?: string
 ): Promise<AdvisorGateOutcome> => {
   try {
     const result = await collectAdvisorResponse(
@@ -611,7 +664,13 @@ export const runAdvisorGate = async (
       ADVISOR_DECISION_SYSTEM,
       question,
       signal,
-      onChunk
+      onChunk,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      onScout,
+      currentInvocationId
     );
     const parsed = parseAutomaticDecision(result.markdown);
     if (!parsed.ok) {
@@ -625,6 +684,9 @@ export const runAdvisorGate = async (
       usage: result.usage,
     };
   } catch (error) {
+    if (signal?.aborted) {
+      throw error;
+    }
     const message = error instanceof Error ? error.message : String(error);
     return {
       category:
@@ -763,7 +825,9 @@ const handleAutomaticGate = async (
   pi: ExtensionAPI,
   event: ToolCallEvent,
   ctx: ExtensionContext,
-  session: AdvisorSessionState
+  session: AdvisorSessionState,
+  runGate: typeof runAdvisorGate,
+  scoutStatus: ScoutStatusManager
 ): Promise<ToolCallEventResult | undefined> => {
   if (
     isSimpleMode() ||
@@ -789,12 +853,36 @@ const handleAutomaticGate = async (
   }
   session.consumeCall();
   herdrAdvisorActivity.start();
-  sendAutomaticGateCall(pi, event);
+  let scoutDetails: ScoutToolDetails | undefined;
+  const scoutStatusToken = Symbol("automatic-gate-scout");
+  scoutStatus.register(scoutStatusToken);
+  let gateCallSent = false;
+  const ensureGateCall = () => {
+    if (!gateCallSent) {
+      sendAutomaticGateCall(pi, event);
+      gateCallSent = true;
+    }
+  };
+  if (!advisorScoutEnabledRef) {
+    ensureGateCall();
+  }
   try {
-    const result = await runAdvisorGate(
+    const result = await runGate(
       ctx,
-      `${reason} Review the repeated actions and recommend the smallest safe next step.`
+      `${reason} Review the repeated actions and recommend the smallest safe next step.`,
+      "repeated-tool-call",
+      ctx.signal,
+      undefined,
+      (scoutEvent) => {
+        scoutStatus.update(ctx, scoutStatusToken, scoutEvent);
+        scoutDetails = appendScoutLifecycleEntry(pi, scoutEvent, scoutDetails);
+        if (scoutEvent.type === "success" || scoutEvent.type === "fallback") {
+          ensureGateCall();
+        }
+      },
+      event.toolCallId
     );
+    ensureGateCall();
     if (!result.ok) {
       session.recordInvocation({
         executionEffect: gateFailureEffectForMode(advisorFailureModeRef),
@@ -841,22 +929,40 @@ const handleAutomaticGate = async (
     }
     return { block: true, reason: gateReason };
   } finally {
+    scoutStatus.release(ctx, scoutStatusToken);
     herdrAdvisorActivity.finish();
   }
 };
 
+export interface ScoutToolDetails {
+  availableCount?: number;
+  fallbackReason?: string;
+  latencyMs?: number;
+  model: string;
+  omittedBeforeScout?: number;
+  selectedCount?: number;
+  selectedLabels?: string[];
+  status: "calling" | "streaming" | "curated" | "fallback" | "cancelled";
+  synthesis?: string;
+  text?: string;
+  thinking?: string;
+  usage?: unknown;
+}
 interface AdvisorToolDetails {
   adviceId?: string;
   advisor?: string;
   draftBytes?: number;
   preferenceBytes?: number;
   question?: string;
+  scout?: ScoutToolDetails;
   text?: string;
   thinking?: string;
   trackedBytes?: number;
   untrackedBytes?: number;
 }
 interface AdvisorRenderState {
+  phase?: string;
+  scout?: ScoutToolDetails;
   timerId?: ReturnType<typeof setInterval>;
 }
 interface AdvisorToolContext {
@@ -868,6 +974,196 @@ interface AdvisorToolContext {
 const advisorResultDetails = (result: AgentToolResult<AdvisorToolDetails>) =>
   result.details;
 
+export const scoutDetailsFromEvent = (
+  event: ScoutLifecycleEvent,
+  previous?: ScoutToolDetails
+): ScoutToolDetails => {
+  if (event.type === "call") {
+    return { model: event.model, status: "calling" };
+  }
+  if (event.type === "chunk") {
+    return {
+      ...previous,
+      model: event.model,
+      status: "streaming",
+      text: event.text,
+      thinking: event.thinking,
+    };
+  }
+  if (event.type === "cancelled") {
+    return {
+      model: previous ? previous.model : executorRef,
+      status: "cancelled",
+    };
+  }
+  const { outcome } = event;
+  return outcome.ok
+    ? {
+        availableCount: outcome.metrics.availableCount,
+        latencyMs: outcome.metrics.latencyMs,
+        model: outcome.model,
+        omittedBeforeScout: outcome.metrics.omittedBeforeScout,
+        selectedCount: outcome.metrics.selectedCount,
+        selectedLabels: outcome.selectedLabels,
+        status: "curated",
+        synthesis: outcome.selection.synthesis,
+        usage: outcome.metrics.usage,
+      }
+    : {
+        availableCount: outcome.metrics.availableCount,
+        fallbackReason: `${outcome.category}: ${outcome.message}`,
+        latencyMs: outcome.metrics.latencyMs,
+        model: outcome.model,
+        omittedBeforeScout: outcome.metrics.omittedBeforeScout,
+        selectedCount: 0,
+        status: "fallback",
+        usage: outcome.metrics.usage,
+      };
+};
+
+export const appendScoutLifecycleEntry = (
+  pi: ExtensionAPI,
+  event: ScoutLifecycleEvent,
+  previous?: ScoutToolDetails
+) => {
+  const scout = scoutDetailsFromEvent(event, previous);
+  if (
+    event.type === "success" ||
+    event.type === "fallback" ||
+    event.type === "cancelled"
+  ) {
+    pi.appendEntry?.("advisor-scout-result", scout);
+  }
+  return scout;
+};
+
+export class ScoutStatusManager {
+  readonly #active = new Set<symbol>();
+  readonly #known = new Set<symbol>();
+  readonly #retired = new Set<symbol>();
+
+  register(token: symbol) {
+    if (!this.#retired.has(token)) {
+      this.#known.add(token);
+    }
+  }
+
+  update(ctx: ExtensionContext, token: symbol, event: ScoutLifecycleEvent) {
+    if (this.#retired.has(token) || !ctx.hasUI) {
+      return;
+    }
+    this.#known.add(token);
+    if (event.type === "call" || event.type === "chunk") {
+      this.#active.add(token);
+      ctx.ui.setStatus("advisor-scout", "Scout curating…");
+      return;
+    }
+    this.release(ctx, token);
+  }
+
+  release(ctx: ExtensionContext, token: symbol) {
+    this.#active.delete(token);
+    this.#known.delete(token);
+    this.#retired.add(token);
+    if (!ctx.hasUI) {
+      return;
+    }
+    ctx.ui.setStatus(
+      "advisor-scout",
+      this.#active.size > 0 ? "Scout curating…" : undefined
+    );
+  }
+
+  clear(ctx: ExtensionContext) {
+    for (const token of this.#known) {
+      this.#retired.add(token);
+    }
+    this.#known.clear();
+    this.#active.clear();
+    if (ctx.hasUI) {
+      ctx.ui.setStatus("advisor-scout", undefined);
+    }
+  }
+}
+
+const scoutTitle = (scout: ScoutToolDetails, frame: string) => {
+  if (scout.status === "calling" || scout.status === "streaming") {
+    return `◆ SCOUT ${frame} · CURATING…`;
+  }
+  if (scout.status === "curated") {
+    return "◆ SCOUT · CURATED";
+  }
+  if (scout.status === "cancelled") {
+    return "◆ SCOUT · CANCELLED";
+  }
+  return "◆ SCOUT · FALLBACK";
+};
+
+export const renderScoutDetails = (
+  box: Box,
+  scout: ScoutToolDetails,
+  expanded: boolean,
+  theme: Theme
+) => {
+  const active = scout.status === "calling" || scout.status === "streaming";
+  const frame =
+    SPINNER_FRAMES[Math.floor(Date.now() / 80) % SPINNER_FRAMES.length];
+  const title = scoutTitle(scout, frame);
+  const lines = [
+    theme.fg(
+      scout.status === "fallback" || scout.status === "cancelled"
+        ? "warning"
+        : "accent",
+      theme.bold(title)
+    ),
+    theme.fg(
+      "dim",
+      `  ${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`}`
+    ),
+  ];
+  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)}`
+      )
+    );
+  }
+  if (expanded && scout.selectedLabels?.length) {
+    lines.push(
+      theme.fg("dim", `  Selected: ${scout.selectedLabels.join("; ")}`)
+    );
+  }
+  if (expanded && scout.synthesis) {
+    lines.push(
+      theme.fg(
+        "dim",
+        `  Scout synthesis (untrusted inference): ${scout.synthesis}`
+      )
+    );
+  }
+  if (expanded && scout.omittedBeforeScout) {
+    lines.push(
+      theme.fg(
+        "dim",
+        `  ${scout.omittedBeforeScout} group(s) omitted before Scout`
+      )
+    );
+  }
+  box.addChild(new Text(lines.join("\n"), 0, 0));
+};
+
+const syncRenderPhase = (context: AdvisorToolContext, phase: string) => {
+  if (context.state.phase !== phase && context.state.timerId) {
+    clearInterval(context.state.timerId);
+    context.state.timerId = undefined;
+  }
+  context.state.phase = phase;
+};
+
 const renderPartialAdvisorResult = (
   box: Box,
   result: AgentToolResult<AdvisorToolDetails>,
@@ -875,12 +1171,25 @@ const renderPartialAdvisorResult = (
   theme: Theme,
   context: AdvisorToolContext
 ) => {
+  const details = advisorResultDetails(result);
+  if (details?.scout) {
+    context.state.scout = details.scout;
+  }
+  const scout = details?.scout ?? context.state.scout;
+  const scoutActive =
+    scout?.status === "calling" || scout?.status === "streaming";
+  syncRenderPhase(context, scoutActive ? "scout" : "advisor");
   if (!context.state.timerId) {
     context.state.timerId = setInterval(() => context.invalidate(), 80);
   }
+  if (scout) {
+    renderScoutDetails(box, scout, expanded, theme);
+  }
+  if (scoutActive || scout?.status === "cancelled") {
+    return;
+  }
   const frame =
     SPINNER_FRAMES[Math.floor(Date.now() / 80) % SPINNER_FRAMES.length];
-  const details = advisorResultDetails(result);
   const lines = [
     `${theme.fg("warning", theme.bold(`◆ ADVISOR ${frame}`))} ${theme.fg("dim", "· Working…")}`,
   ];
@@ -911,11 +1220,22 @@ const renderFinalAdvisorResult = (
   theme: Theme,
   context: AdvisorToolContext
 ) => {
+  syncRenderPhase(context, "final");
   if (context.state.timerId) {
     clearInterval(context.state.timerId);
     context.state.timerId = undefined;
   }
   const details = advisorResultDetails(result);
+  if (details?.scout) {
+    context.state.scout = details.scout;
+  }
+  const scout = details?.scout ?? context.state.scout;
+  if (scout) {
+    renderScoutDetails(box, scout, expanded, theme);
+  }
+  if (scout?.status === "cancelled") {
+    return;
+  }
   const advice = details?.text || textFrom(result.content);
   const lines = [renderAdvisorResponseHeader(hasSoundVerdict(advice), theme)];
   if (details?.advisor) {
@@ -981,9 +1301,24 @@ const renderAdvisorResult = (
 
 export const registerAdvisorTool = (
   pi: ExtensionAPI,
-  session: AdvisorSessionState = advisorSessionState
+  session: AdvisorSessionState = advisorSessionState,
+  dependencies: {
+    runGate?: typeof runAdvisorGate;
+    statusManager?: ScoutStatusManager;
+  } = {}
 ) => {
   const reservedCalls = new Set<string>();
+  const scoutStatus = dependencies.statusManager ?? new ScoutStatusManager();
+
+  pi.registerEntryRenderer?.(
+    "advisor-scout-result",
+    (entry, { expanded }, theme) => {
+      const scout = entry.data as ScoutToolDetails;
+      const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+      renderScoutDetails(box, scout, Boolean(expanded), theme);
+      return box;
+    }
+  );
 
   pi.registerMessageRenderer?.(
     "advisor-loop-call",
@@ -1082,7 +1417,14 @@ export const registerAdvisorTool = (
     if (event.toolName === "ask_advisor") {
       return reservation;
     }
-    return handleAutomaticGate(pi, event, ctx, session);
+    return handleAutomaticGate(
+      pi,
+      event,
+      ctx,
+      session,
+      dependencies.runGate ?? runAdvisorGate,
+      scoutStatus
+    );
   });
 
   pi.on("agent_settled", (_event, ctx) => {
@@ -1098,8 +1440,9 @@ export const registerAdvisorTool = (
     }
   });
 
-  pi.on("session_shutdown", () => {
+  pi.on("session_shutdown", (_event, ctx) => {
     reservedCalls.clear();
+    scoutStatus.clear(ctx);
     herdrAdvisorBlock.clear();
   });
 
@@ -1123,6 +1466,7 @@ export const registerAdvisorTool = (
         session.consumeCall();
       }
       herdrAdvisorActivity.start();
+      let scoutDetails: ScoutToolDetails | undefined;
       try {
         const result = await consultAdvisor(
           ctx,
@@ -1134,6 +1478,7 @@ export const registerAdvisorTool = (
               details: {
                 advisor: advisorRef,
                 question: resolveAdvisorRequest(params.question),
+                scout: scoutDetails,
                 text: tx,
                 thinking: t,
               },
@@ -1143,7 +1488,19 @@ export const registerAdvisorTool = (
           params.gitContext === "none" ? "off" : params.gitContext,
           params.draft,
           params.includeUntracked,
-          params.includeTrackedFiles
+          params.includeTrackedFiles,
+          (event) => {
+            scoutDetails = scoutDetailsFromEvent(event, scoutDetails);
+            onUpdate?.({
+              content: [{ text: scoutDetails.text ?? "", type: "text" }],
+              details: {
+                advisor: advisorRef,
+                question: resolveAdvisorRequest(params.question),
+                scout: scoutDetails,
+              },
+            });
+          },
+          _id
         );
         session.issueAdvice(
           result.adviceId,
@@ -1172,6 +1529,7 @@ export const registerAdvisorTool = (
             draftBytes: result.draftBytes,
             preferenceBytes: result.preferenceBytes,
             question: resolveAdvisorRequest(params.question),
+            scout: scoutDetails,
             text: result.markdown,
             thinking: result.thinkingText,
             trackedBytes: result.trackedBytes,