pi-advisor-flow 0.9.2-dev.5 → 0.10.1-dev.1

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

@@ -3,6 +3,7 @@ import type {
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import type { Static } from "typebox";
 
 import {
   advisorRef,
@@ -11,6 +12,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 +23,13 @@ import {
   advisorUsageForPi,
   snapshotAdvisorUsage,
 } from "../usage.ts";
+import { advisorOutputSchema } from "./advisor-output.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 +52,66 @@ 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,
+    },
+    structuredContent: { skipReason: notice, text: notice },
+  };
+};
+
 const claimTrackedHandoff = (
   session: ToolRegistrationContext["session"],
   includeTrackedFiles: string[] | undefined
@@ -76,23 +141,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. In Pi Codemode, gather and filter deterministic tool results first, then call tools.ask_advisor. Nested results are not automatically reconstructed: pass only permitted, concise summaries in draft (untrusted, capped at 8 KiB, not independently verified). Draft does not inherit source-tool disclosure policies; use gitContext for patches within the user's allowance.",
     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) {
@@ -136,20 +203,27 @@ export const registerAskAdvisorTool = ({
           const skipText = screeningSkipText(screening);
           session.releaseCall(_id);
           reservedCalls.delete(_id);
+          const skipped = {
+            jev: {
+              kind: screening.kind,
+              reason: screening.reason,
+              skipped: true,
+            },
+            text: skipText,
+          };
           return {
             content: [{ text: skipText, type: "text" }],
-            details: {
-              jev: {
-                kind: screening.kind,
-                reason: screening.reason,
-                skipped: true,
-              },
-              text: skipText,
-            },
+            details: skipped,
+            structuredContent: skipped,
           };
         }
-        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 +265,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 +284,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 +307,7 @@ export const registerAskAdvisorTool = ({
           session.recordInvocation({
             cost: advisorUsageCost(result.usage),
             executionEffect: "continued",
+            followUp: result.followUp,
             kind: "markdown",
             model: result.model,
             trigger: "executor-requested",
@@ -241,6 +321,7 @@ export const registerAskAdvisorTool = ({
             advisor: result.model,
             agentRulesBytes: result.agentRulesBytes,
             draftBytes: result.draftBytes,
+            followUp: result.followUp,
             imageBytes: result.imageBytes,
             imageCount: result.imageCount,
             imageOmissions: result.imageOmissions,
@@ -256,14 +337,24 @@ export const registerAskAdvisorTool = ({
           if (usage) {
             details.usage = usage;
           }
+          const structuredContent: Static<typeof advisorOutputSchema> = {
+            adviceId: result.adviceId,
+            advisor: result.model,
+            followUp: Boolean(result.followUp),
+            text: result.markdown,
+          };
+          if (usage) {
+            structuredContent.usage = usage;
+          }
           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",
               },
             ],
             details,
+            structuredContent,
           };
           if (piUsage) {
             response.usage = piUsage;
@@ -280,7 +371,7 @@ export const registerAskAdvisorTool = ({
             executionEffect: "continued",
             failure: "provider-error",
             kind: "markdown",
-            model: advisorRef,
+            model: followUp?.payload.model ?? advisorRef,
             trigger: "executor-requested",
           });
           updateAdvisorUsageStatus(ctx, session);
@@ -296,6 +387,7 @@ export const registerAskAdvisorTool = ({
     },
     label: "Ask Advisor",
     name: "ask_advisor",
+    outputSchema: advisorOutputSchema,
     parameters: Type.Object({
       draft: Type.Optional(
         Type.String({
@@ -303,6 +395,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:
@@ -342,12 +440,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/render-advisor-result.ts

@@ -162,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

@@ -48,6 +48,7 @@ export interface AdvisorConsultationResult {
   adviceId: string;
   agentRulesBytes?: number;
   draftBytes?: number;
+  followUp?: boolean;
   imageBytes?: number;
   imageCount?: number;
   imageOmissions?: number;
@@ -89,6 +90,7 @@ 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(

package/src/ui/settings-mutations.ts

@@ -1,4 +1,5 @@
 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 = [
@@ -55,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,8 +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;