pi-advisor-flow 0.4.0 → 0.5.0

package/src/config.ts

@@ -66,6 +66,8 @@ export let advisorOutcomeLoggingRef = false;
 export let advisorUntrackedContentRef = false;
 export let advisorTrackedFileContentRef = false;
 export let advisorScoutEnabledRef = false;
+export let showUsageDetailsRef = true;
+export let showUsageFooterRef = false;
 
 export const setExecutorRef = (ref: string) => {
   executorRef = ref;
@@ -174,6 +176,12 @@ export const setAdvisorTrackedFileContentRef = (enabled: boolean) => {
 export const setAdvisorScoutEnabledRef = (enabled: boolean) => {
   advisorScoutEnabledRef = enabled;
 };
+export const setShowUsageDetailsRef = (enabled: boolean) => {
+  showUsageDetailsRef = enabled;
+};
+export const setShowUsageFooterRef = (enabled: boolean) => {
+  showUsageFooterRef = enabled;
+};
 
 /**
  * Returns the current live settings state. Use this at UI boundaries instead of
@@ -200,6 +208,8 @@ export const getAdvisorSettings = () => ({
   redactSecrets: advisorRedactSecretsRef,
   scoutEnabled: advisorScoutEnabledRef,
   sessionSummary: advisorSessionSummaryRef,
+  showUsageDetails: showUsageDetailsRef,
+  showUsageFooter: showUsageFooterRef,
   simpleMode: simpleModeRef,
   toolPolicies: { ...advisorToolPoliciesRef },
   toolResultMaxBytes: advisorToolResultMaxBytesRef,
@@ -253,6 +263,8 @@ export interface AdvisorConfig {
   executor?: string;
   executorEffort?: string;
   gateFailureMode?: GateFailureMode;
+  showUsageDetails?: boolean;
+  showUsageFooter?: boolean;
   simpleMode?: boolean;
 }
 
@@ -273,6 +285,7 @@ const CONFIG_KEYS = new Set<keyof AdvisorConfig>([
   "advisorPlanGate",
   "advisorSessionSummary",
   "advisorScoutEnabled",
+  "showUsageDetails",
   "simpleMode",
   "alwaysOn",
   "advisorToolResultMaxBytes",
@@ -286,6 +299,7 @@ const CONFIG_KEYS = new Set<keyof AdvisorConfig>([
   "executor",
   "executorEffort",
   "gateFailureMode",
+  "showUsageFooter",
 ]);
 const BOOLEAN_CONFIG_KEYS = [
   "advisorPlanGate",
@@ -296,6 +310,8 @@ const BOOLEAN_CONFIG_KEYS = [
   "advisorAutoLoopGate",
   "advisorSessionSummary",
   "advisorScoutEnabled",
+  "showUsageDetails",
+  "showUsageFooter",
   "simpleMode",
   "alwaysOn",
   "advisorHerdrIntegration",
@@ -482,6 +498,8 @@ const resetDefaults = () => {
   advisorUntrackedContentRef = false;
   advisorTrackedFileContentRef = false;
   advisorScoutEnabledRef = false;
+  showUsageDetailsRef = true;
+  showUsageFooterRef = false;
 };
 
 const applyOptionalConfig = <Key extends keyof AdvisorConfig>(
@@ -549,6 +567,8 @@ const applyConfig = (config: AdvisorConfig) => {
     setAdvisorSessionSummaryRef
   );
   applyOptionalConfig(config, "advisorScoutEnabled", setAdvisorScoutEnabledRef);
+  applyOptionalConfig(config, "showUsageDetails", setShowUsageDetailsRef);
+  applyOptionalConfig(config, "showUsageFooter", setShowUsageFooterRef);
   applyOptionalConfig(config, "simpleMode", setSimpleModeRef);
   applyOptionalConfig(config, "alwaysOn", setAlwaysOnRef);
   applyOptionalConfig(config, "gateFailureMode", setAdvisorFailureModeRef);
@@ -716,6 +736,8 @@ export const saveConfig = (_ctx: ExtensionContext) => {
     advisorUntrackedContent: advisorUntrackedContentRef,
     alwaysOn: alwaysOnRef,
     gateFailureMode: advisorFailureModeRef,
+    showUsageDetails: showUsageDetailsRef,
+    showUsageFooter: showUsageFooterRef,
     simpleMode: simpleModeRef,
   };
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);

package/src/model-stream.ts

@@ -56,6 +56,129 @@ export interface CollectedTextStream {
   usage?: unknown;
 }
 
+export const ADVISOR_STREAM_UPDATE_INTERVAL_MS = 90;
+
+export interface CoalescedUpdateResult {
+  error?: unknown;
+  failed: boolean;
+}
+
+export interface CoalescedUpdate<T> {
+  cancel: () => void;
+  flush: () => CoalescedUpdateResult;
+  update: (value: T) => void;
+}
+
+export interface CoalescedUpdateScheduler {
+  clearTimeout: (timer: ReturnType<typeof setTimeout>) => void;
+  now: () => number;
+  setTimeout: (
+    callback: () => void,
+    delay: number
+  ) => ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Keep stream updates responsive without forwarding every provider delta to
+ * the UI. The first update in a burst is immediate; later updates are kept as
+ * the latest value and published at most once per interval. `flush()` closes
+ * the publisher and is intended for terminal success/error paths.
+ */
+export const createCoalescedUpdate = <T>(
+  publish: (value: T) => void,
+  intervalMs = ADVISOR_STREAM_UPDATE_INTERVAL_MS,
+  scheduler: CoalescedUpdateScheduler = {
+    clearTimeout,
+    now: Date.now,
+    setTimeout: (callback, delay) => setTimeout(callback, delay),
+  }
+): CoalescedUpdate<T> => {
+  if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+    throw new Error("Coalesced update interval must be positive and finite.");
+  }
+
+  let closed = false;
+  let hasPending = false;
+  let pending: T | undefined;
+  let lastPublishedAt: number | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let publishError: unknown;
+  let publishFailed = false;
+
+  const clearTimer = () => {
+    if (timer !== undefined) {
+      scheduler.clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  const publishPending = () => {
+    timer = undefined;
+    if (!hasPending) {
+      return;
+    }
+    const value = pending as T;
+    pending = undefined;
+    hasPending = false;
+    lastPublishedAt = scheduler.now();
+    try {
+      publish(value);
+    } catch (error) {
+      publishFailed = true;
+      publishError = error;
+      closed = true;
+      clearTimer();
+    }
+  };
+
+  const schedule = () => {
+    const elapsed =
+      lastPublishedAt === undefined
+        ? intervalMs
+        : scheduler.now() - lastPublishedAt;
+    const delay = Math.max(0, intervalMs - elapsed);
+    if (delay === 0) {
+      publishPending();
+      return;
+    }
+    timer = scheduler.setTimeout(publishPending, delay);
+    timer.unref?.();
+  };
+
+  return {
+    cancel: () => {
+      closed = true;
+      clearTimer();
+      pending = undefined;
+      hasPending = false;
+    },
+    flush: () => {
+      if (!closed) {
+        closed = true;
+        clearTimer();
+        publishPending();
+      }
+      return { error: publishError, failed: publishFailed };
+    },
+    update: (value) => {
+      if (closed) {
+        return;
+      }
+      if (publishFailed) {
+        throw publishError;
+      }
+      pending = value;
+      hasPending = true;
+      if (timer === undefined) {
+        schedule();
+      }
+      if (publishFailed) {
+        throw publishError;
+      }
+    },
+  };
+};
+
 export const collectTextStream = async (
   resolved: ResolvedConfiguredModel,
   options: CollectTextStreamOptions,

package/src/session-state.ts

@@ -124,6 +124,7 @@ export class AdvisorSessionState {
     string,
     { advice: string; trigger: ConsultationTrigger }
   >();
+  readonly #pendingAdvice = new Set<string>();
   readonly #reportedAdvice = new Set<string>();
   #draftConsultations = 0;
   #outcomes = 0;
@@ -138,6 +139,7 @@ export class AdvisorSessionState {
     this.#loopInterventions = 0;
     this.#consumedCalls = 0;
     this.#issuedAdvice.clear();
+    this.#pendingAdvice.clear();
     this.#reportedAdvice.clear();
     this.#draftConsultations = 0;
     this.#outcomes = 0;
@@ -237,16 +239,38 @@ export class AdvisorSessionState {
     return true;
   }
 
-  claimAdvice(id: string) {
-    if (this.#reportedAdvice.has(id)) {
+  reserveAdvice(id: string) {
+    if (this.#reportedAdvice.has(id) || this.#pendingAdvice.has(id)) {
       return;
     }
     const advice = this.#issuedAdvice.get(id);
     if (!advice) {
       return;
     }
+    this.#pendingAdvice.add(id);
+    return advice;
+  }
+
+  commitAdvice(id: string) {
+    if (!this.#pendingAdvice.delete(id)) {
+      return false;
+    }
     this.#reportedAdvice.add(id);
     this.#outcomes += 1;
+    return true;
+  }
+
+  releaseAdvice(id: string) {
+    this.#pendingAdvice.delete(id);
+  }
+
+  /** Compatibility helper for synchronous callers that can commit immediately. */
+  claimAdvice(id: string) {
+    const advice = this.reserveAdvice(id);
+    if (!advice) {
+      return;
+    }
+    this.commitAdvice(id);
     return advice;
   }
 

package/src/tools.ts

@@ -35,6 +35,7 @@ import {
   contextMaxCharsRef,
   executorRef,
   getAdvisorMaxCallsPerSession,
+  getAdvisorSettings,
   isSimpleMode,
   loadConfig,
 } from "./config.js";
@@ -57,7 +58,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 {
@@ -712,7 +718,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 +749,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 +765,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 +909,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 +954,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 +966,8 @@ const handleAutomaticGate = async (
         result.category,
         result.message,
         ctx,
-        session
+        session,
+        failureMode
       );
       sendAutomaticGateFailure(
         pi,
@@ -939,7 +981,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 +995,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 +1118,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 +1137,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 +1149,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 +1164,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,9 +1205,11 @@ 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}`));
@@ -1278,9 +1331,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
@@ -1344,10 +1399,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 +1453,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 +1566,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 +1584,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 +1619,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 +1630,7 @@ export const registerAdvisorTool = (
           },
           _id
         );
+        flushUpdate();
         session.issueAdvice(
           result.adviceId,
           result.markdown,
@@ -1575,9 +1647,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 +1671,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 +1683,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 +1765,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 +1785,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.",