pi-advisor-flow 0.9.2-dev.4 → 0.10.0

package/src/tools/register-ask-advisor.ts

@@ -11,6 +11,7 @@ import {
   isSimpleMode,
 } from "../config/state.ts";
 import { loadConfig } from "../config/storage.ts";
+import type { AdvisorFollowUpPayload } from "../follow-up.ts";
 import { notifyHerdrAdvisorFailure } from "../herdr.ts";
 import {
   ADVISOR_STREAM_UPDATE_INTERVAL_MS,
@@ -21,10 +22,12 @@ import {
   advisorUsageForPi,
   snapshotAdvisorUsage,
 } from "../usage.ts";
+import { assertAdvisorFollowUpPrivacy } from "./consultation.ts";
 import { notifyLocalFailure, updateAdvisorUsageStatus } from "./gate-policy.ts";
 import { normalizeScreeningQuestion, screeningSkipText } from "./jev-filter.ts";
 import {
   advisorModelAccessReason,
+  fallbackSameModelAdvisorNotice,
   sameModelAdvisorDisabled,
   sameModelAdvisorNotice,
 } from "./model-access.ts";
@@ -47,6 +50,65 @@ const assertAdvisorModelAccess = (ctx: ExtensionContext) => {
   }
 };
 
+interface AskAdvisorParams {
+  draft?: string;
+  followUpTo?: string;
+  force?: boolean;
+  gitContext?: "none" | "summary" | "full";
+  includeTrackedFiles?: string[];
+  includeUntracked?: string[];
+  question?: string;
+}
+
+const resolveFollowUp = (
+  params: AskAdvisorParams,
+  session: ToolRegistrationContext["session"]
+): { adviceId: string; payload: AdvisorFollowUpPayload } | undefined => {
+  if (!params.followUpTo) {
+    return undefined;
+  }
+  if (
+    !params.question?.trim() ||
+    params.draft !== undefined ||
+    params.gitContext !== undefined ||
+    params.includeTrackedFiles?.length ||
+    params.includeUntracked?.length
+  ) {
+    throw new Error(
+      "Follow-up consultations accept only followUpTo and a non-empty question. Issue a fresh consultation for new context or attachments."
+    );
+  }
+  const cached = session.followUpFor(params.followUpTo);
+  if (!cached.payload) {
+    throw new Error(
+      `Follow-up unavailable for adviceId ${params.followUpTo}: ${cached.reason ?? "the cached payload is unavailable"}. Issue a fresh consultation.`
+    );
+  }
+  return { adviceId: params.followUpTo, payload: cached.payload };
+};
+
+const sameModelNoticeFor = (modelRef: string | undefined) =>
+  (modelRef ?? advisorRef) === advisorRef
+    ? sameModelAdvisorNotice
+    : fallbackSameModelAdvisorNotice;
+
+const skippedSameModelResult = (
+  id: string,
+  notice: string,
+  reservedCalls: Set<string>,
+  session: ToolRegistrationContext["session"]
+) => {
+  session.releaseCall(id);
+  reservedCalls.delete(id);
+  return {
+    content: [{ text: notice, type: "text" as const }],
+    details: {
+      skipReason: notice,
+      text: notice,
+    },
+  };
+};
+
 const claimTrackedHandoff = (
   session: ToolRegistrationContext["session"],
   includeTrackedFiles: string[] | undefined
@@ -76,23 +138,25 @@ export const registerAskAdvisorTool = ({
 }: ToolRegistrationContext): void => {
   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.",
+      "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. Use followUpTo with a new question to continue one cached consultation without rebuilding its redacted context. If the Advisor explicitly names a missing file, you may make a sequential fresh consultation with includeTrackedFiles when enabled and relevant.",
     async execute(_id, params, signal, onUpdate, ctx) {
-      const skipSameModel = () => {
-        session.releaseCall(_id);
-        reservedCalls.delete(_id);
-        return {
-          content: [{ text: sameModelAdvisorNotice, type: "text" as const }],
-          details: {
-            skipReason: sameModelAdvisorNotice,
-            text: sameModelAdvisorNotice,
-          },
-        };
-      };
+      let followUp:
+        | { adviceId: string; payload: AdvisorFollowUpPayload }
+        | undefined;
       try {
         loadConfig(ctx);
-        if (sameModelAdvisorDisabled(ctx)) {
-          return skipSameModel();
+        followUp = resolveFollowUp(params, session);
+        if (followUp) {
+          assertAdvisorFollowUpPrivacy(followUp.payload, ctx);
+        }
+        const modelRef = followUp?.payload.model;
+        if (sameModelAdvisorDisabled(ctx, ctx.model, modelRef)) {
+          return skippedSameModelResult(
+            _id,
+            sameModelNoticeFor(modelRef),
+            reservedCalls,
+            session
+          );
         }
         assertAdvisorModelAccess(ctx);
       } catch (error) {
@@ -148,8 +212,13 @@ export const registerAskAdvisorTool = ({
             },
           };
         }
-        if (sameModelAdvisorDisabled(ctx)) {
-          return skipSameModel();
+        if (sameModelAdvisorDisabled(ctx, ctx.model, followUp?.payload.model)) {
+          return skippedSameModelResult(
+            _id,
+            sameModelNoticeFor(followUp?.payload.model),
+            reservedCalls,
+            session
+          );
         }
         if (
           !simpleMode &&
@@ -191,7 +260,8 @@ export const registerAskAdvisorTool = ({
               coalescedUpdate.update({
                 content: [{ text: tx, type: "text" }],
                 details: {
-                  advisor: advisorRef,
+                  advisor: followUp?.payload.model ?? advisorRef,
+                  followUp: Boolean(followUp),
                   question: resolveAdvisorRequest(params.question),
                   scout: scoutDetails,
                   text: tx,
@@ -209,13 +279,17 @@ export const registerAskAdvisorTool = ({
               coalescedUpdate.update({
                 content: [{ text: scoutDetails.text ?? "", type: "text" }],
                 details: {
-                  advisor: advisorRef,
+                  advisor: followUp?.payload.model ?? advisorRef,
+                  followUp: Boolean(followUp),
                   question: resolveAdvisorRequest(params.question),
                   scout: scoutDetails,
                 },
               });
             },
-            _id
+            _id,
+            followUp,
+            (adviceId, payload, replacesAdviceId) =>
+              session.captureFollowUp(adviceId, payload, replacesAdviceId)
           );
           flushUpdate();
           session.issueAdvice(
@@ -228,6 +302,7 @@ export const registerAskAdvisorTool = ({
           session.recordInvocation({
             cost: advisorUsageCost(result.usage),
             executionEffect: "continued",
+            followUp: result.followUp,
             kind: "markdown",
             model: result.model,
             trigger: "executor-requested",
@@ -239,7 +314,9 @@ export const registerAskAdvisorTool = ({
           const details: AdvisorToolDetails = {
             adviceId: result.adviceId,
             advisor: result.model,
+            agentRulesBytes: result.agentRulesBytes,
             draftBytes: result.draftBytes,
+            followUp: result.followUp,
             imageBytes: result.imageBytes,
             imageCount: result.imageCount,
             imageOmissions: result.imageOmissions,
@@ -258,7 +335,7 @@ export const registerAskAdvisorTool = ({
           const response: AgentToolResult<AdvisorToolDetails> = {
             content: [
               {
-                text: `Advisor (${result.model})\n\n${result.markdown}`,
+                text: `${result.followUp ? "Advisor follow-up" : "Advisor"} (${result.model})\n\n${result.markdown}`,
                 type: "text",
               },
             ],
@@ -279,7 +356,7 @@ export const registerAskAdvisorTool = ({
             executionEffect: "continued",
             failure: "provider-error",
             kind: "markdown",
-            model: advisorRef,
+            model: followUp?.payload.model ?? advisorRef,
             trigger: "executor-requested",
           });
           updateAdvisorUsageStatus(ctx, session);
@@ -302,6 +379,12 @@ export const registerAskAdvisorTool = ({
             "Concise untrusted draft for plan or completion review; claims are not verification evidence.",
         })
       ),
+      followUpTo: Type.Optional(
+        Type.String({
+          description:
+            "Opaque adviceId from a prior successful consultation. Requires a new non-empty question and reuses that consultation's redacted payload; do not combine with draft, Git context, or file attachments.",
+        })
+      ),
       force: Type.Optional(
         Type.Boolean({
           description:
@@ -341,12 +424,16 @@ export const registerAskAdvisorTool = ({
       ),
     }),
     promptGuidelines: [
-      "Call ask_advisor with an empty object for general consultation. For a plan or completion review, include a concise draft naming work, validation, and remaining risks; its claims are not evidence. If the Advisor explicitly says it cannot review a specifically named file, you may make a sequential follow-up call with includeTrackedFiles when the file is relevant, permitted, and worth the shared call budget; do not infer paths or retry automatically.",
+      "Call ask_advisor with an empty object for general consultation. For a plan or completion review, include a concise draft naming work, validation, and remaining risks; its claims are not evidence. To drill into an existing answer, pass its adviceId as followUpTo with a new question and no draft, Git context, or attachments. If the Advisor explicitly says it cannot review a specifically named file, you may make a sequential follow-up call with includeTrackedFiles when the file is relevant, permitted, and worth the shared call budget; do not infer paths or retry automatically.",
     ],
     promptSnippet:
       "Consult the Advisor using its existing context; attach a draft for plan or completion review",
     renderCall(args, theme) {
-      return renderAdvisorCallBox(args.question?.trim(), theme);
+      return renderAdvisorCallBox(
+        args.question?.trim(),
+        theme,
+        Boolean(args.followUpTo)
+      );
     },
     renderResult(result, options, theme, context) {
       // SAFETY: this tool's execute() only returns AdvisorToolDetails-shaped details.

package/src/tools/register-lifecycle.ts

@@ -95,6 +95,16 @@ export const registerToolLifecycle = ({
       : undefined;
   });
 
+  pi.on("input", () => {
+    session.clearFollowUps();
+  });
+
+  pi.on("tool_result", (event) => {
+    if (event.toolName !== "ask_advisor") {
+      session.advanceFollowUpToolCall();
+    }
+  });
+
   pi.on("tool_call", (event, ctx) => {
     if (session.blocked) {
       return {
@@ -149,6 +159,7 @@ export const registerToolLifecycle = ({
 
   pi.on("session_shutdown", (_event, ctx) => {
     reservedCalls.clear();
+    session.clearFollowUps();
     session.clearCallReservations();
     scoutStatus.clear(ctx);
     herdrBlock.clear();

package/src/tools/register-renderers.ts

@@ -20,29 +20,63 @@ interface CallMessageDetails {
 
 interface TurnGateResultDetails {
   advisor?: string;
+  agentRulesBytes?: number;
   text?: string;
   usage?: unknown;
 }
 
 interface LoopResultDetails {
   advisor?: string;
+  agentRulesBytes?: number;
   decision?: GateDecision;
   text?: string;
   usage?: unknown;
 }
 
-const addUsageLine = (
+const formatByteSize = (bytes: number) => {
+  if (bytes >= 1024 ** 3) {
+    return `${(bytes / 1024 ** 3).toFixed(1)} GiB`;
+  }
+  if (bytes >= 1024 ** 2) {
+    return `${(bytes / 1024 ** 2).toFixed(1)} MiB`;
+  }
+  if (bytes >= 1024) {
+    return `${Math.round(bytes / 1024)} KiB`;
+  }
+  return `${bytes} B`;
+};
+
+const addAttachmentLine = (
   box: Box,
   details: TurnGateResultDetails | LoopResultDetails | undefined,
   theme: Theme
 ) => {
-  if (!getAdvisorSettings().showUsageDetails) {
-    return;
+  if (details?.agentRulesBytes) {
+    box.addChild(
+      new Text(
+        theme.fg(
+          "dim",
+          `  AGENTS.md rules attached · ${formatByteSize(details.agentRulesBytes)}`
+        ),
+        0,
+        0
+      )
+    );
   }
-  const usageText = formatAdvisorUsage(details?.usage);
-  if (usageText) {
-    box.addChild(new Text(theme.fg("dim", `  Usage: ${usageText}`), 0, 0));
+};
+
+const addUsageLine = (
+  box: Box,
+  details: TurnGateResultDetails | LoopResultDetails | undefined,
+  theme: Theme
+) => {
+  if (getAdvisorSettings().showUsageDetails) {
+    const usageText = formatAdvisorUsage(details?.usage);
+    if (usageText) {
+      box.addChild(new Text(theme.fg("dim", `  Usage: ${usageText}`), 0, 0));
+    }
   }
+  addAttachmentLine(box, details, theme);
 };
 
 const callQuestionRenderer: MessageRenderer<CallMessageDetails> = (

package/src/tools/render-advisor-result.ts

@@ -60,6 +60,9 @@ const formatByteSize = (bytes: number): string => {
 
 const attachmentLabels = (details: AdvisorToolDetails | undefined) =>
   [
+    details?.agentRulesBytes
+      ? `AGENTS.md rules attached · ${formatByteSize(details.agentRulesBytes)}`
+      : undefined,
     details?.draftBytes
       ? `Draft attached · ${formatByteSize(details.draftBytes)}`
       : undefined,
@@ -159,6 +162,9 @@ const finalResultLines = (
   theme: Theme
 ): string[] => {
   const lines = [renderAdvisorResponseHeader(hasSoundVerdict(advice), theme)];
+  if (details?.followUp) {
+    lines.push(theme.fg("dim", "  Follow-up consultation"));
+  }
   if (details?.advisor) {
     lines.push(theme.fg("dim", `  ${details.advisor}`));
   }

package/src/tools/render-common.ts

@@ -85,11 +85,15 @@ export const resolveAdvisorRequest = (question?: string) =>
 
 export const renderAdvisorCallBox = (
   question: string | undefined,
-  theme: Theme
+  theme: Theme,
+  followUp = false
 ) => {
   const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
   const label = theme.fg("customMessageLabel", theme.bold("[advisor]"));
-  const title = theme.fg("customMessageText", "Executor → Advisor");
+  const title = theme.fg(
+    "customMessageText",
+    followUp ? "Executor → Advisor · Follow-up" : "Executor → Advisor"
+  );
   box.addChild(
     new Text(
       question

package/src/tools/types.ts

@@ -46,7 +46,9 @@ export interface AdvisorGateFailure {
 
 export interface AdvisorConsultationResult {
   adviceId: string;
+  agentRulesBytes?: number;
   draftBytes?: number;
+  followUp?: boolean;
   imageBytes?: number;
   imageCount?: number;
   imageOmissions?: number;
@@ -63,6 +65,7 @@ export interface AdvisorConsultationResult {
 }
 
 export interface AdvisorGateResult {
+  agentRulesBytes?: number;
   decision: GateDecision;
   markdown: string;
   model: string;
@@ -86,6 +89,8 @@ export type GateFailureCategory =
 export interface AdvisorToolDetails {
   adviceId?: string;
   advisor?: string;
+  agentRulesBytes?: number;
+  followUp?: boolean;
   draftBytes?: number;
   imageBytes?: number;
   imageCount?: number;

package/src/ui/settings-items.ts

@@ -17,6 +17,7 @@ import {
 import { isValidAdvisorToolPolicies } from "../config/validation.ts";
 import { JevSetupSubmenu } from "./jev-setup-submenu.ts";
 import { SearchableModelMultiSelector } from "./model-multi-selector.ts";
+import { SearchableModelSelector } from "./model-selector.ts";
 import {
   contextDescription,
   currentContextLabel,
@@ -28,6 +29,7 @@ import {
   withCurrentValue,
 } from "./settings-formatting.ts";
 import { TextSettingSubmenu } from "./text-setting-submenu.ts";
+import { FALLBACK_ADVISOR_MODEL_DISABLED } from "./types.ts";
 import type {
   AdvisorSettings,
   ContextPreset,
@@ -36,6 +38,7 @@ import type {
 
 export interface SettingsItemsOptions {
   effortLevels: string[];
+  fallbackModel: SettingItem;
   modelWhitelist: SettingItem;
   presets: ContextPreset[];
   settings: AdvisorSettings;
@@ -220,6 +223,37 @@ const jevItems = (
   },
 ];
 
+export const advisorFallbackModelItem = (
+  settings: AdvisorSettings,
+  modelRefs: string[] | undefined,
+  keybindings: KeybindingsManager | undefined,
+  theme: Theme,
+  tui: RenderRequester
+): SettingItem => ({
+  currentValue: settings.fallbackModel ?? FALLBACK_ADVISOR_MODEL_DISABLED,
+  description:
+    "Retry a failed Advisor request once with this optional model; the primary model remains unchanged.",
+  id: "fallbackModel",
+  label: "Fallback Advisor model",
+  submenu: (_currentValue, done) =>
+    new SearchableModelSelector({
+      allOptions: [
+        FALLBACK_ADVISOR_MODEL_DISABLED,
+        ...new Set(
+          modelRefs ?? (settings.fallbackModel ? [settings.fallbackModel] : [])
+        ),
+      ],
+      currentOption: settings.fallbackModel ?? FALLBACK_ADVISOR_MODEL_DISABLED,
+      keybindings: keybindings ?? getKeybindings(),
+      onCancel: done,
+      onSelect: (value) =>
+        done(value === FALLBACK_ADVISOR_MODEL_DISABLED ? "" : value),
+      theme,
+      title: "Fallback Advisor model",
+      tui,
+    }),
+});
+
 export const advisorModelWhitelistItem = (
   settings: AdvisorSettings,
   modelRefs: string[] | undefined,
@@ -252,6 +286,7 @@ export const advisorModelWhitelistItem = (
 
 export const createSettingsItems = ({
   effortLevels,
+  fallbackModel,
   modelWhitelist,
   presets,
   settings,
@@ -282,6 +317,7 @@ export const createSettingsItems = ({
       label: "Always on",
       values: TOGGLE_VALUES,
     },
+    fallbackModel,
   ];
   if (settings.simpleMode) {
     items.push(
@@ -472,6 +508,13 @@ export const createSettingsItems = ({
       settings.redactSecrets,
       false
     ),
+    toggle(
+      "agentsMdContext",
+      "AGENTS.md context",
+      "Include trusted project and global AGENTS.md rules in Advisor calls.",
+      settings.agentsMdContext,
+      true
+    ),
     {
       currentValue: settings.gitContext ?? "summary",
       description: "How much repository context is shared with the Advisor.",

package/src/ui/settings-mutations.ts

@@ -1,7 +1,9 @@
 import { DEFAULT_JEV_MODEL } from "../config/types.ts";
+import { FALLBACK_ADVISOR_MODEL_DISABLED } from "./types.ts";
 import type { AdvisorSettings, ContextPreset } from "./types.ts";
 
 const BOOLEAN_SETTING_FIELDS = [
+  "agentsMdContext",
   "autoLoopGate",
   "blockOnBlocked",
   "collapseResponses",
@@ -54,6 +56,13 @@ const applyCoreMutation = (
       settings.alwaysOn = value === "On";
       return true;
     }
+    case "fallbackModel": {
+      settings.fallbackModel =
+        value === FALLBACK_ADVISOR_MODEL_DISABLED
+          ? undefined
+          : value.trim() || undefined;
+      return true;
+    }
     case "effort": {
       settings.effort = value;
       return true;

package/src/ui/settings-selector.ts

@@ -7,6 +7,7 @@ import {
   SIMPLE_MODE_GRADIENT_INTERVAL_MS,
 } from "./settings-formatting.ts";
 import {
+  advisorFallbackModelItem,
   advisorModelWhitelistItem,
   createSettingsItems,
 } from "./settings-items.ts";
@@ -96,6 +97,13 @@ export class AdvisorSettingsSelector implements Component, Focusable {
       }
       return defaultLabel(text, selected);
     };
+    const fallbackModel = advisorFallbackModelItem(
+      this.settings,
+      this.options.modelRefs,
+      this.options.keybindings,
+      this.options.theme,
+      this.options.tui
+    );
     const modelWhitelist = advisorModelWhitelistItem(
       this.settings,
       this.options.modelRefs,
@@ -105,6 +113,7 @@ export class AdvisorSettingsSelector implements Component, Focusable {
     );
     const items = createSettingsItems({
       effortLevels: this.options.effortLevels,
+      fallbackModel,
       modelWhitelist,
       presets: this.presets,
       settings: this.settings,

package/src/ui/types.ts

@@ -66,7 +66,11 @@ export interface ContextPreset {
   value: number;
 }
 
+export const FALLBACK_ADVISOR_MODEL_DISABLED = "Disabled (no fallback)";
+
 export interface AdvisorSettings {
+  agentsMdContext?: boolean;
+  fallbackModel?: string;
   alwaysOn?: boolean;
   autoLoopGate?: boolean;
   blockOnBlocked?: boolean;