pi-advisor-flow 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project are documented here.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.3.3
+
+### Added
+
+- Added **EXPERIMENTAL** Advisor Scout, an opt-in conversation curator that uses the configured Executor model before every Advisor invocation. It keeps selected evidence verbatim, labels its synthesis as untrusted inference, reports separate usage and latency, and falls back to the original context without changing Advisor or gate safety behavior. The experiment adapts the context-boundary idea from the [FastContext paper](https://arxiv.org/html/2606.14066v1); it is not the paper's repository explorer and does not claim its reported effect size.
+
+### Fixed
+
+- Kept Scout history within the Advisor's remaining context budget, including zero-budget behavior, and kept pending Advisor drafts and attachment paths outside Scout's input.
+- Included the current repeated tool invocation in automatic-gate Scout context.
+
 ## 0.3.1
 
 ### Changed

package/README.md

@@ -20,10 +20,11 @@ The idea is simple: keep implementation on a fast model and borrow frontier reas
 - **Separate model and reasoning controls** for the Executor and Advisor.
 - **Privacy controls** for conversation history, repository context, explicit tracked/untracked file handoff, tool results, secret redaction, and outcome logging.
 - **Optional persistent activation, Simple mode, session summaries, and Herdr integration.**
+- **EXPERIMENTAL Advisor Scout** that uses the configured Executor model to curate conversation evidence before every Advisor call.
 
 ## Install
 
-Current release: **0.3.1**. Requires Pi 0.84.1 or later and is compatible with Herdr 0.8.0. The extension installs no dependencies of its own; Pi supplies its runtime modules.
+Current release: **0.3.2**. Requires Pi 0.84.1 or later and is compatible with Herdr 0.8.0. The extension installs no dependencies of its own; Pi supplies its runtime modules.
 
 ```bash
 # npm
@@ -56,13 +57,26 @@ You can also enable the flow and select both models at once:
 
 1. The Executor investigates the task and forms its own candidate direction.
 2. For a consequential decision, stalled attempt, or final review, it calls `ask_advisor` with the reconstructed conversation and allowed repository context.
-3. The Advisor returns a concise review. It may challenge assumptions, identify risks, or recommend the next verification step.
-4. The Executor decides what to adopt, performs the work, and validates the result.
+3. When Experimental Advisor Scout is enabled, the configured Executor model selects relevant conversation groups and writes a short, explicitly untrusted synthesis.
+4. The Advisor receives selected verbatim evidence, required current-request context, and the unchanged deterministic repository, preference, draft, and attachment regions.
+5. The Executor decides what to adopt, performs the work, and validates the result.
 
 A normal consultation never blocks execution. The optional automatic loop gate is different: it evaluates repeated tool calls and applies the configured failure policy when the Advisor says to revise, reports a block, is unavailable, or returns an invalid decision.
 
 Successful calls return an opaque `adviceId`. If global outcome logging is enabled, the Executor can call `record_advisor_outcome` once to record whether the advice was adopted and whether final validation passed.
 
+### Experimental Advisor Scout
+
+Experimental Advisor Scout is off by default. Enable `Experimental Advisor Scout` in the advanced `/advisor-settings` screen or set `"advisorScoutEnabled": true` in the global `advisor.json`.
+
+Scout runs before `ask_advisor`, `/advisor-manual`, and automatic Advisor gates. It uses the configured Executor model and Executor reasoning effort in a separate model call. This adds cost and latency. The compact result shows the model, selection counts, and elapsed time; `Ctrl+O` shows bounded selected labels and the synthesis.
+
+Scout receives a bounded manifest of conversation and tool-history groups after the normal tool disclosure, result-cap, and redaction policies are applied. The manifest and reconstructed Scout conversation share the Advisor's remaining context budget after repository context; a zero remaining budget produces no history groups. For a pending `ask_advisor` call, Scout receives only the allowlisted question and Git-context preference, never the draft or explicit attachment paths. Scout does not receive the deterministic Git context, draft, project preferences, or explicit tracked and untracked attachments. Those regions are appended later through their existing consent and cap rules.
+
+A Scout timeout, provider error, missing model or authentication, or invalid response produces a visible fallback. The Advisor then receives the original uncurated conversation. Cancelling the parent operation stops both Scout and Advisor work and does not start fallback. Scout usage is displayed separately and does not spend an Advisor call from the session budget.
+
+This experiment adapts the context-boundary idea from Zhang et al., ["FastContext: Training Efficient Repository Explorer for Coding Agents"](https://arxiv.org/html/2606.14066v1). It is not a reproduction of FastContext. The paper describes an on-demand repository explorer with read, glob, and grep tools. pi-advisor Scout curates conversation history only, and the paper's reported effect sizes do not apply to this feature.
+
 ## Commands
 
 | Command | Purpose |
@@ -79,6 +93,8 @@ The Executor calls `ask_advisor({})` for a general review. It can pass a targete
 
 Advisor context can include user messages, tool calls, tool results, and repository information. Secret redaction is off by default, and tools without an explicit disclosure policy default to full context. Review the privacy settings before using the extension with sensitive work.
 
+When Experimental Advisor Scout is enabled, the Executor model provider also receives bounded Advisor-eligible conversation history. Scout does not receive the deterministic repository, draft, preference, or explicit-file regions described below.
+
 Repository context is configurable from no access through changed-file summaries to a capped patch. When context is disabled or its budget is zero, the Advisor is told it was withheld rather than shown an apparently clean tree. Explicit tracked and untracked file contents require separate global opt-ins; attachments are capped, redacted when configured, and sent as untrusted data.
 
 ## Documentation

package/extensions/index.ts

@@ -7,6 +7,7 @@ import {
   parseAutomaticDecision as parseAutomaticDecisionImplementation,
   registerAdvisorTool,
   runAdvisorGate as runAdvisorGateImplementation,
+  ScoutStatusManager,
 } from "../src/tools.js";
 
 export type { AdvisorConfig, GateFailureMode } from "../src/config.js";
@@ -31,9 +32,10 @@ export const runAdvisorGate = (
 
 export default function (pi: ExtensionAPI) {
   const sessionState = new AdvisorSessionState();
+  const scoutStatus = new ScoutStatusManager();
   setHerdrBlockedEmitter((active, label) =>
     pi.events.emit("herdr:blocked", { active, label })
   );
-  registerAdvisorTool(pi, sessionState);
-  registerCommands(pi, { sessionState });
+  registerAdvisorTool(pi, sessionState, { statusManager: scoutStatus });
+  registerCommands(pi, { sessionState, statusManager: scoutStatus });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-advisor-flow",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "author": "Philip Brembeck",
   "repository": {
     "type": "git",

package/src/commands.ts

@@ -35,6 +35,7 @@ import {
   setAdvisorPlanGateRef,
   setAdvisorRedactSecretsRef,
   setAdvisorRef,
+  setAdvisorScoutEnabledRef,
   setAdvisorSessionSummaryRef,
   setAdvisorToolPoliciesRef,
   setAdvisorToolResultMaxBytesRef,
@@ -49,15 +50,18 @@ import {
   splitRef,
 } from "./config.js";
 import { herdrAdvisorActivity, notifyHerdrAdvisorFailure } from "./herdr.js";
+import type { ScoutLifecycleEvent } from "./scout.js";
 import type { AdvisorSessionState } from "./session-state.js";
 import {
   adviceForDisplay,
+  appendScoutLifecycleEntry,
   consultAdvisor,
   advisorSessionState as defaultAdvisorSessionState,
   hasSoundVerdict,
   renderAdvisorCallBox,
   renderAdvisorResponseHeader,
   resolveAdvisorRequest,
+  ScoutStatusManager,
 } from "./tools.js";
 import {
   type AdvisorSettings,
@@ -132,7 +136,9 @@ const CONTEXT_PRESETS: ContextPreset[] = [
 type ManualConsult = (
   ctx: ExtensionContext,
   question?: string,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  onChunk?: (thinking: string, text: string) => void,
+  onScout?: (event: ScoutLifecycleEvent) => void
 ) => Promise<{
   markdown: string;
   thinkingText: string;
@@ -161,24 +167,50 @@ export const registerCommands = (
   dependencies: {
     consult?: ManualConsult;
     sessionState?: AdvisorSessionState;
+    statusManager?: ScoutStatusManager;
   } = {}
 ) => {
   const advisorSessionState =
     dependencies.sessionState ?? defaultAdvisorSessionState;
+  const scoutStatus = dependencies.statusManager ?? new ScoutStatusManager();
   const flowEnabled = () => pi.getActiveTools().includes("ask_advisor");
   const requestAdvisor =
     dependencies.consult ??
-    ((ctx, question, signal) =>
-      consultAdvisor(ctx, question, signal, undefined, "manual"));
-  const manualConsultations = new Set<AbortController>();
+    ((ctx, question, signal, onChunk, onScout) =>
+      consultAdvisor(
+        ctx,
+        question,
+        signal,
+        onChunk,
+        "manual",
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        onScout
+      ));
+  const manualConsultations = new Map<AbortController, symbol>();
 
   const startManualConsultation = (
     ctx: ExtensionContext,
     question: string | undefined,
-    controller: AbortController
+    controller: AbortController,
+    scoutStatusToken: symbol
   ) => {
     herdrAdvisorActivity.start();
-    return requestAdvisor(ctx, question, controller.signal)
+    let scoutDetails: Parameters<typeof appendScoutLifecycleEntry>[2];
+    return requestAdvisor(
+      ctx,
+      question,
+      controller.signal,
+      undefined,
+      (event) => {
+        if (!controller.signal.aborted) {
+          scoutStatus.update(ctx, scoutStatusToken, event);
+          scoutDetails = appendScoutLifecycleEntry(pi, event, scoutDetails);
+        }
+      }
+    )
       .then(({ markdown }) => {
         if (controller.signal.aborted) {
           return;
@@ -232,6 +264,7 @@ export const registerCommands = (
         notifyHerdrAdvisorFailure("Advisor consultation failed", message);
       })
       .finally(() => {
+        scoutStatus.release(ctx, scoutStatusToken);
         manualConsultations.delete(controller);
         herdrAdvisorActivity.finish();
       });
@@ -398,10 +431,12 @@ export const registerCommands = (
     saveConfig(ctx);
   });
 
-  pi.on("session_shutdown", () => {
-    for (const controller of manualConsultations) {
+  pi.on("session_shutdown", (_event, ctx) => {
+    for (const [controller, token] of manualConsultations) {
       controller.abort();
+      scoutStatus.release(ctx, token);
     }
+    scoutStatus.clear(ctx);
     manualConsultations.clear();
     herdrAdvisorActivity.clear();
   });
@@ -430,14 +465,17 @@ export const registerCommands = (
       const question = resolveAdvisorRequest(args);
       // A single visible progress surface avoids competing consultations overwriting
       // each other's streamed state. A newer manual request replaces the previous one.
-      for (const pending of manualConsultations) {
+      for (const [pending, token] of manualConsultations) {
         pending.abort();
+        scoutStatus.release(ctx, token);
       }
       manualConsultations.clear();
       const controller = new AbortController();
-      manualConsultations.add(controller);
+      const scoutStatusToken = Symbol("manual-scout");
+      scoutStatus.register(scoutStatusToken);
+      manualConsultations.set(controller, scoutStatusToken);
       pi.appendEntry?.("advisor-manual-call", { question });
-      startManualConsultation(ctx, question, controller);
+      startManualConsultation(ctx, question, controller, scoutStatusToken);
       return Promise.resolve();
     },
   });
@@ -563,6 +601,7 @@ export const registerCommands = (
       setAdvisorLoopThresholdRef(settings.loopThreshold ?? 3);
       setAdvisorMaxCallsPerSessionRef(settings.maxCallsPerSession);
       setAdvisorSessionSummaryRef(settings.sessionSummary ?? false);
+      setAdvisorScoutEnabledRef(settings.scoutEnabled ?? false);
       setSimpleModeRef(settings.simpleMode ?? false);
       setAlwaysOnRef(settings.alwaysOn ?? false);
       setAdvisorFailureModeRef(settings.failureMode ?? "block-session");

package/src/config.ts

@@ -65,6 +65,7 @@ export let advisorToolPoliciesRef: AdvisorToolPolicies = {};
 export let advisorOutcomeLoggingRef = false;
 export let advisorUntrackedContentRef = false;
 export let advisorTrackedFileContentRef = false;
+export let advisorScoutEnabledRef = false;
 
 export const setExecutorRef = (ref: string) => {
   executorRef = ref;
@@ -170,6 +171,9 @@ export const setAdvisorUntrackedContentRef = (enabled: boolean) => {
 export const setAdvisorTrackedFileContentRef = (enabled: boolean) => {
   advisorTrackedFileContentRef = enabled;
 };
+export const setAdvisorScoutEnabledRef = (enabled: boolean) => {
+  advisorScoutEnabledRef = enabled;
+};
 
 /**
  * Returns the current live settings state. Use this at UI boundaries instead of
@@ -194,6 +198,7 @@ export const getAdvisorSettings = () => ({
   outcomeLogging: advisorOutcomeLoggingRef,
   planGate: advisorPlanGateRef,
   redactSecrets: advisorRedactSecretsRef,
+  scoutEnabled: advisorScoutEnabledRef,
   sessionSummary: advisorSessionSummaryRef,
   simpleMode: simpleModeRef,
   toolPolicies: { ...advisorToolPoliciesRef },
@@ -232,6 +237,7 @@ export interface AdvisorConfig {
   advisorOutcomeLogging?: boolean;
   advisorPlanGate?: boolean;
   advisorRedactSecrets?: boolean;
+  advisorScoutEnabled?: boolean;
   advisorSessionSummary?: boolean;
   advisorToolPolicies?: AdvisorToolPolicies;
   advisorToolResultMaxBytes?: number;
@@ -262,6 +268,7 @@ const CONFIG_KEYS = new Set<keyof AdvisorConfig>([
   "advisorMaxCallsPerSession",
   "advisorPlanGate",
   "advisorSessionSummary",
+  "advisorScoutEnabled",
   "simpleMode",
   "alwaysOn",
   "advisorToolResultMaxBytes",
@@ -284,6 +291,7 @@ const BOOLEAN_CONFIG_KEYS = [
   "advisorBlockOnBlocked",
   "advisorAutoLoopGate",
   "advisorSessionSummary",
+  "advisorScoutEnabled",
   "simpleMode",
   "alwaysOn",
   "advisorHerdrIntegration",
@@ -469,6 +477,7 @@ const resetDefaults = () => {
   advisorOutcomeLoggingRef = false;
   advisorUntrackedContentRef = false;
   advisorTrackedFileContentRef = false;
+  advisorScoutEnabledRef = false;
 };
 
 const applyOptionalConfig = <Key extends keyof AdvisorConfig>(
@@ -535,6 +544,7 @@ const applyConfig = (config: AdvisorConfig) => {
     "advisorSessionSummary",
     setAdvisorSessionSummaryRef
   );
+  applyOptionalConfig(config, "advisorScoutEnabled", setAdvisorScoutEnabledRef);
   applyOptionalConfig(config, "simpleMode", setSimpleModeRef);
   applyOptionalConfig(config, "alwaysOn", setAlwaysOnRef);
   applyOptionalConfig(config, "gateFailureMode", setAdvisorFailureModeRef);
@@ -693,6 +703,7 @@ export const saveConfig = (_ctx: ExtensionContext) => {
     advisorGitContextMaxChars: advisorGitContextMaxCharsRef,
     advisorHerdrIntegration: advisorHerdrIntegrationRef,
     advisorRedactSecrets: advisorRedactSecretsRef,
+    advisorScoutEnabled: advisorScoutEnabledRef,
     advisorSessionSummary: advisorSessionSummaryRef,
     advisorToolPolicies: advisorToolPoliciesRef,
     advisorToolResultMaxBytes: advisorToolResultMaxBytesRef,

package/src/conversation.ts

@@ -247,7 +247,7 @@ const toolResultEntry = (
   return `[Tool Result for ${toolName}] (${message.isError ? "Error " : ""}output):\n${capped.content}`;
 };
 
-const conversationEntry = (
+export const conversationEntry = (
   entry: unknown,
   toolResultMaxLines: number,
   toolResultMaxBytes: number,

package/src/model-stream.ts

@@ -0,0 +1,106 @@
+import {
+  type Api,
+  type AssistantMessage,
+  type Message,
+  type Model,
+  stream,
+} from "@earendil-works/pi-ai/compat";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { splitRef } from "./config.js";
+
+export interface ResolvedConfiguredModel {
+  apiKey: string;
+  env?: Record<string, string>;
+  headers?: Record<string, string | null>;
+  model: Model<Api>;
+  ref: string;
+}
+
+export const resolveConfiguredModel = async (
+  ctx: ExtensionContext,
+  ref: string,
+  label: string
+): Promise<ResolvedConfiguredModel> => {
+  const [provider, modelId] = splitRef(ref);
+  const model = ctx.modelRegistry.find(provider, modelId);
+  if (!model) {
+    throw new Error(`${label} model not found: ${ref}`);
+  }
+  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 ${ref}`);
+  }
+  return {
+    apiKey: auth.apiKey,
+    env: auth.env,
+    headers: auth.headers,
+    model,
+    ref,
+  };
+};
+
+export interface CollectTextStreamOptions {
+  messages: Message[];
+  onChunk?: (thinking: string, text: string) => void;
+  reasoning?: string;
+  signal?: AbortSignal;
+  systemPrompt: string;
+}
+
+export interface CollectedTextStream {
+  text: string;
+  thinking: string;
+  usage?: unknown;
+}
+
+export const collectTextStream = async (
+  resolved: ResolvedConfiguredModel,
+  options: CollectTextStreamOptions,
+  streamModel: typeof stream = stream
+): Promise<CollectedTextStream> => {
+  let thinking = "";
+  let text = "";
+  const eventStream = streamModel(
+    resolved.model,
+    { messages: options.messages, systemPrompt: options.systemPrompt },
+    {
+      apiKey: resolved.apiKey,
+      env: resolved.env,
+      headers: resolved.headers,
+      reasoning: options.reasoning as never,
+      signal: options.signal,
+    }
+  );
+
+  for await (const event of eventStream) {
+    if (event.type === "thinking_delta") {
+      thinking += event.delta;
+      options.onChunk?.(thinking, text);
+    } else if (event.type === "text_delta") {
+      text += event.delta;
+      options.onChunk?.(thinking, text);
+    }
+  }
+
+  const response = await eventStream.result();
+  const lastAssistant = [response].find(
+    (message): message is AssistantMessage => message.role === "assistant"
+  );
+  const finalText =
+    lastAssistant?.content
+      .filter(
+        (part): part is { type: "text"; text: string } => part.type === "text"
+      )
+      .map((part) => part.text)
+      .join("\n") || text;
+  return {
+    text: finalText,
+    thinking,
+    usage: (
+      lastAssistant as (AssistantMessage & { usage?: unknown }) | undefined
+    )?.usage,
+  };
+};