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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-advisor-flow",
-  "version": "0.9.2-dev.5",
+  "version": "0.10.1-dev.1",
   "description": "Advanced Executor/Advisor flow for Pi, fully configurable and extendable.",
   "keywords": [
     "advisor",
@@ -55,7 +55,7 @@
     "@earendil-works/pi-coding-agent": "1.0.0",
     "@earendil-works/pi-tui": "1.0.0",
     "@oxlint/plugins": "1.86.0",
-    "@types/node": "^26.6.3",
+    "@types/node": "^26.6.4",
     "@typesafe-ai/sdk": "^0.6.0",
     "bun-types": "1.4.2",
     "husky": "^9.1.7",

package/src/commands/activation-preparation.ts

@@ -2,11 +2,13 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import {
   advisorEffortRef,
+  advisorFallbackModelRef,
   advisorRef,
   executorEffortRef,
   executorRef,
   getPersistedModelRefs,
   setAdvisorEffortRef,
+  setAdvisorFallbackModelRef,
   setAdvisorRef,
   setExecutorEffortRef,
   setExecutorRef,
@@ -99,6 +101,7 @@ export const prepareActivationModels = async (
   const selection = await selectAdvisorModels(ctx, {
     advisor: advisorOverride || persisted.advisor ? advisorRef : "",
     advisorEffort: advisorEffortRef,
+    advisorFallbackModel: advisorFallbackModelRef,
     executor:
       executorOverride || plan.pendingExecutor || persisted.executor
         ? executorRef
@@ -111,6 +114,7 @@ export const prepareActivationModels = async (
     return;
   }
   setAdvisorRef(selection.advisor);
+  setAdvisorFallbackModelRef(selection.advisorFallbackModel);
   setAdvisorEffortRef(selection.advisorEffort);
   setExecutorRef(selection.executor);
   setExecutorEffortRef(selection.executorEffort);

package/src/commands/manual-consultation.ts

@@ -14,8 +14,10 @@ import { notify } from "./runtime.ts";
 import type { CommandRuntime, ManualAdvisorProgressState } from "./types.ts";
 
 interface ManualResultDetails {
+  adviceId?: string;
   advisor: string;
   agentRulesBytes?: number;
+  followUp?: boolean;
   preferenceBytes?: number;
   question?: string;
   text: string;
@@ -50,35 +52,42 @@ export const startManualConsultation = async (
   const finishHerdrActivity = runtime.herdrActivity.start();
   let scoutDetails: ScoutToolDetails | undefined;
   try {
-    const { adviceId, agentRulesBytes, markdown, preferenceBytes, usage } =
-      await runtime.requestAdvisor(
-        ctx,
-        question,
-        controller.signal,
-        (thinking, text) => {
-          if (controller.signal.aborted) {
-            return;
-          }
+    const {
+      adviceId,
+      agentRulesBytes,
+      followUp,
+      markdown,
+      model,
+      preferenceBytes,
+      usage,
+    } = await runtime.requestAdvisor(
+      ctx,
+      question,
+      controller.signal,
+      (thinking, text) => {
+        if (controller.signal.aborted) {
+          return;
+        }
+        progress.phase = "active";
+        progress.thinking = thinking;
+        progress.text = text;
+        runtime.requestManualRender(ctx);
+      },
+      (event) => {
+        if (!controller.signal.aborted) {
+          runtime.scoutStatus.update(ctx, scoutStatusToken, event);
+          scoutDetails = appendScoutLifecycleEntry(
+            runtime.pi,
+            event,
+            scoutDetails
+          );
+          progress.scout = scoutDetails;
           progress.phase = "active";
-          progress.thinking = thinking;
-          progress.text = text;
           runtime.requestManualRender(ctx);
-        },
-        (event) => {
-          if (!controller.signal.aborted) {
-            runtime.scoutStatus.update(ctx, scoutStatusToken, event);
-            scoutDetails = appendScoutLifecycleEntry(
-              runtime.pi,
-              event,
-              scoutDetails
-            );
-            progress.scout = scoutDetails;
-            progress.phase = "active";
-            runtime.requestManualRender(ctx);
-          }
-        },
-        gitContext
-      );
+        }
+      },
+      gitContext
+    );
     if (controller.signal.aborted) {
       return;
     }
@@ -87,8 +96,9 @@ export const startManualConsultation = async (
     runtime.advisorSessionState.recordInvocation({
       cost: advisorUsageCost(usage),
       executionEffect: "continued",
+      followUp,
       kind: "markdown",
-      model: advisorRef,
+      model: model ?? advisorRef,
       trigger: "manual",
       usage,
     });
@@ -105,8 +115,10 @@ export const startManualConsultation = async (
     }
     runtime.updateAdvisorUsageStatus(ctx);
     const details: ManualResultDetails = {
-      advisor: advisorRef,
+      adviceId,
+      advisor: model ?? advisorRef,
       agentRulesBytes,
+      followUp,
       preferenceBytes,
       question,
       text: markdown,

package/src/commands/model-commands.ts

@@ -1,10 +1,12 @@
 import {
   advisorEffortRef,
+  advisorFallbackModelRef,
   advisorRef,
   executorEffortRef,
   executorRef,
   getPersistedModelRefs,
   setAdvisorEffortRef,
+  setAdvisorFallbackModelRef,
   setAdvisorRef,
   setExecutorEffortRef,
   setExecutorRef,
@@ -24,7 +26,7 @@ export const registerModelCommands = (runtime: CommandRuntime) => {
 
   runtime.pi.registerCommand("advisor-models", {
     description:
-      "Select and persist the Executor and Advisor models with reasoning levels",
+      "Select and persist the Executor, Advisor, and optional fallback models with reasoning levels",
     handler: async (_args, ctx) => {
       if (!(loadCommandConfig(ctx) && ctx.hasUI)) {
         return;
@@ -36,6 +38,7 @@ export const registerModelCommands = (runtime: CommandRuntime) => {
       const selection = await selectAdvisorModels(ctx, {
         advisor: persisted.advisor ? advisorRef : "",
         advisorEffort: advisorEffortRef,
+        advisorFallbackModel: advisorFallbackModelRef,
         executor:
           runtime.pendingExecutorModelRef ??
           (persisted.executor ? executorRef : ""),
@@ -49,6 +52,7 @@ export const registerModelCommands = (runtime: CommandRuntime) => {
 
       setExecutorRef(selection.executor);
       setAdvisorRef(selection.advisor);
+      setAdvisorFallbackModelRef(selection.advisorFallbackModel);
       setExecutorEffortRef(selection.executorEffort);
       setAdvisorEffortRef(selection.advisorEffort);
 

package/src/commands/model-picker.ts

@@ -1,6 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { SearchableModelSelector } from "../ui/model-selector.ts";
+import { FALLBACK_ADVISOR_MODEL_DISABLED } from "../ui/types.ts";
 import {
   effortChoices,
   getAvailableModelRefs,
@@ -10,6 +11,7 @@ import {
 export interface AdvisorModelSelection {
   advisor: string;
   advisorEffort: string | undefined;
+  advisorFallbackModel: string | undefined;
   executor: string;
   executorEffort: string | undefined;
 }
@@ -17,6 +19,7 @@ export interface AdvisorModelSelection {
 export interface AdvisorModelPickerOptions {
   advisor: string | undefined;
   advisorEffort: string | undefined;
+  advisorFallbackModel: string | undefined;
   executor: string | undefined;
   executorEffort: string | undefined;
   selectAdvisor: boolean;
@@ -46,7 +49,13 @@ export const selectAdvisorModels = async (
         )
     ),
   ];
-  let { advisor, advisorEffort, executor, executorEffort } = options;
+  let {
+    advisor,
+    advisorEffort,
+    advisorFallbackModel,
+    executor,
+    executorEffort,
+  } = options;
 
   if (options.selectExecutor) {
     const selectedExecutor = await ctx.ui.custom<string | undefined>(
@@ -104,8 +113,41 @@ export const selectAdvisorModels = async (
     advisorEffort = selectedEffort(selectedAdvisorEffort);
   }
 
+  const selectedFallback = await ctx.ui.custom<string | undefined>(
+    (tui, theme, keybindings, done) =>
+      new SearchableModelSelector({
+        allOptions: [
+          FALLBACK_ADVISOR_MODEL_DISABLED,
+          ...new Set([
+            ...allOptions,
+            ...(refs || !advisorFallbackModel ? [] : [advisorFallbackModel]),
+          ]),
+        ],
+        currentOption: advisorFallbackModel ?? FALLBACK_ADVISOR_MODEL_DISABLED,
+        keybindings,
+        onCancel: () => done(undefined),
+        onSelect: done,
+        theme,
+        title: "Select Fallback Advisor Model (optional)",
+        tui,
+      })
+  );
+  if (selectedFallback === undefined) {
+    return undefined;
+  }
+  advisorFallbackModel =
+    selectedFallback === FALLBACK_ADVISOR_MODEL_DISABLED
+      ? undefined
+      : selectedFallback;
+
   if (!(advisor && executor)) {
     return undefined;
   }
-  return { advisor, advisorEffort, executor, executorEffort };
+  return {
+    advisor,
+    advisorEffort,
+    advisorFallbackModel,
+    executor,
+    executorEffort,
+  };
 };

package/src/commands/runtime.ts

@@ -77,7 +77,15 @@ class CommandRuntime implements CommandRuntimeContract {
           undefined,
           undefined,
           undefined,
-          onScout
+          onScout,
+          undefined,
+          undefined,
+          (adviceId, payload, replacesAdviceId) =>
+            this.advisorSessionState.captureFollowUp(
+              adviceId,
+              payload,
+              replacesAdviceId
+            )
         ));
   }
 

package/src/commands/settings-persistence.ts

@@ -11,6 +11,7 @@ import {
   setAdvisorCustomInvocationRef,
   setAdvisorDisableSameModelRef,
   setAdvisorEffortRef,
+  setAdvisorFallbackModelRef,
   setAdvisorFailureGateRef,
   setAdvisorFailureModeRef,
   setAdvisorGitContextMaxCharsRef,
@@ -69,6 +70,7 @@ const applySessionSettings = (settings: AdvisorSettings) => {
   );
   setContextMaxCharsRef(settings.contextMaxChars);
   setAdvisorPlanGateRef(settings.planGate);
+  setAdvisorFallbackModelRef(settings.fallbackModel);
   setAdvisorFailureGateRef(settings.failureGate);
   setAdvisorCompletionGateRef(settings.completionGate);
   setAdvisorDisableSameModelRef(settings.disableSameModel ?? true);

package/src/commands/types.ts

@@ -21,7 +21,9 @@ export type ManualConsult = (
   adviceId?: string;
   agentRulesBytes?: number;
   draftBytes?: number;
+  followUp?: boolean;
   markdown: string;
+  model?: string;
   preferenceBytes?: number;
   thinkingText: string;
   usage?: unknown;

package/src/config/defaults.ts

@@ -30,6 +30,7 @@ import {
   setAdvisorPlanGateRef,
   setAdvisorRedactSecretsRef,
   setAdvisorRef,
+  setAdvisorFallbackModelRef,
   setAdvisorScoutEnabledRef,
   setAdvisorScoutTimeoutMsRef,
   setAdvisorSessionSummaryRef,
@@ -69,6 +70,7 @@ import {
 export const resetDefaults = () => {
   setExecutorRef("");
   setAdvisorRef("");
+  setAdvisorFallbackModelRef(undefined);
   setAdvisorAgentsMdContextRef(true);
   setPersistedModelRefs(undefined, undefined);
   setExecutorEffortRef(undefined);
@@ -139,6 +141,10 @@ const applyNonEmptyStringConfig = (
 export const applyConfig = (config: AdvisorConfig) => {
   applyNonEmptyStringConfig(config.executor, setExecutorRef);
   applyNonEmptyStringConfig(config.advisor, setAdvisorRef);
+  applyNonEmptyStringConfig(
+    config.advisorFallbackModel,
+    setAdvisorFallbackModelRef
+  );
   applyNonEmptyStringConfig(config.executorEffort, setExecutorEffortRef);
   applyNonEmptyStringConfig(config.advisorEffort, setAdvisorEffortRef);
   applyOptionalConfig(

package/src/config/schema.ts

@@ -10,6 +10,7 @@ import {
   advisorCustomInvocationRef,
   advisorDisableSameModelRef,
   advisorEffortRef,
+  advisorFallbackModelRef,
   advisorFailureGateRef,
   advisorFailureModeRef,
   advisorGitContextMaxCharsRef,
@@ -226,6 +227,12 @@ export const CONFIG_SCHEMA = {
     persisted: true,
     type: "boolean",
   },
+  advisorFallbackModel: {
+    accepted: "a provider/model string",
+    current: () => configuredModelRef(advisorFallbackModelRef),
+    persisted: true,
+    type: "string",
+  },
   advisorGitContext: {
     accepted: GIT_CONTEXT_LEVELS.join(", "),
     current: () => advisorGitContextRef,

package/src/config/state.ts

@@ -25,6 +25,7 @@ import type {
 // An empty ref means no model has been selected yet.
 export let executorRef = "";
 export let advisorRef = "";
+export let advisorFallbackModelRef: string | undefined;
 export let advisorAgentsMdContextRef = true;
 let persistedExecutorRef: string | undefined;
 let persistedAdvisorRef: string | undefined;
@@ -81,6 +82,9 @@ export const setExecutorRef = (ref: string) => {
 export const setAdvisorRef = (ref: string) => {
   advisorRef = ref;
 };
+export const setAdvisorFallbackModelRef = (ref: string | undefined) => {
+  advisorFallbackModelRef = ref?.trim() || undefined;
+};
 export const setAdvisorAgentsMdContextRef = (enabled: boolean) => {
   advisorAgentsMdContextRef = enabled;
 };
@@ -250,6 +254,7 @@ export const getAdvisorSettings = () => ({
   effort: advisorEffortRef,
   failureGate: advisorFailureGateRef,
   failureMode: advisorFailureModeRef,
+  fallbackModel: advisorFallbackModelRef,
   gitContext: advisorGitContextRef,
   gitContextMaxChars: advisorGitContextMaxCharsRef,
   herdrIntegration: advisorHerdrIntegrationRef,

package/src/config/types.ts

@@ -60,6 +60,7 @@ export const GATE_FAILURE_MODES: GateFailureMode[] = [
 
 export interface AdvisorConfig {
   advisor?: string;
+  advisorFallbackModel?: string;
   advisorAgentsMdContext?: boolean;
   advisorAutoLoopGate?: boolean;
   advisorBlockOnBlocked?: boolean;

package/src/config.ts

@@ -8,6 +8,7 @@ export {
   advisorCompletionGateRef,
   advisorCustomInvocationRef,
   advisorEffortRef,
+  advisorFallbackModelRef,
   advisorFailureGateRef,
   advisorFailureModeRef,
   advisorGitContextMaxCharsRef,
@@ -42,6 +43,7 @@ export {
   setAdvisorCompletionGateRef,
   setAdvisorCustomInvocationRef,
   setAdvisorEffortRef,
+  setAdvisorFallbackModelRef,
   setAdvisorFailureGateRef,
   setAdvisorFailureModeRef,
   setAdvisorGitContextMaxCharsRef,

package/src/follow-up.ts

@@ -0,0 +1,85 @@
+import type { Message } from "@earendil-works/pi-ai/compat";
+
+export const FOLLOW_UP_TTL_MS = 5 * 60 * 1000;
+export const FOLLOW_UP_MAX_DEPTH = 3;
+export const FOLLOW_UP_MAX_TOOL_CALLS = 3;
+
+export interface AdvisorFollowUpPayload {
+  depth: number;
+  messages: Message[];
+  model: string;
+  privacyKey: string;
+  redacted: boolean;
+  systemPrompt: string;
+}
+
+export interface AdvisorFollowUpLookup {
+  payload?: AdvisorFollowUpPayload;
+  reason?: string;
+}
+
+interface StoredFollowUpPayload extends AdvisorFollowUpPayload {
+  expiresAt: number;
+  toolCallsSince: number;
+}
+
+const copy = <Value>(value: Value): Value => structuredClone(value);
+
+export class AdvisorFollowUpCache {
+  readonly #entries = new Map<string, StoredFollowUpPayload>();
+  readonly #now: () => number;
+
+  constructor(now: () => number = Date.now) {
+    this.#now = now;
+  }
+
+  clear() {
+    this.#entries.clear();
+  }
+
+  advanceToolCall() {
+    const now = this.#now();
+    for (const [adviceId, entry] of this.#entries) {
+      if (
+        now >= entry.expiresAt ||
+        entry.toolCallsSince + 1 >= FOLLOW_UP_MAX_TOOL_CALLS
+      ) {
+        this.#entries.delete(adviceId);
+        continue;
+      }
+      entry.toolCallsSince += 1;
+    }
+  }
+
+  capture(
+    adviceId: string,
+    payload: AdvisorFollowUpPayload,
+    replacesAdviceId?: string
+  ) {
+    if (replacesAdviceId) {
+      this.#entries.delete(replacesAdviceId);
+    }
+    this.#entries.set(adviceId, {
+      ...copy(payload),
+      expiresAt: this.#now() + FOLLOW_UP_TTL_MS,
+      toolCallsSince: 0,
+    });
+  }
+
+  get(adviceId: string): AdvisorFollowUpLookup {
+    const entry = this.#entries.get(adviceId);
+    if (!entry) {
+      return { reason: "the adviceId is unknown or no longer cached" };
+    }
+    if (this.#now() >= entry.expiresAt) {
+      this.#entries.delete(adviceId);
+      return { reason: "the cached payload has expired" };
+    }
+    if (entry.depth >= FOLLOW_UP_MAX_DEPTH) {
+      return {
+        reason: `the follow-up chain is limited to ${FOLLOW_UP_MAX_DEPTH} follow-ups`,
+      };
+    }
+    return { payload: copy(entry) };
+  }
+}

package/src/session-state.ts

@@ -1,5 +1,10 @@
 import { isRecordOf, isString } from "./content-utils.ts";
 import type { JsonValue } from "./content-utils.ts";
+import { AdvisorFollowUpCache } from "./follow-up.ts";
+import type {
+  AdvisorFollowUpLookup,
+  AdvisorFollowUpPayload,
+} from "./follow-up.ts";
 import { AdvisorJevLedgerState } from "./jev/ledger.ts";
 import type { AdvisorJevUsage } from "./jev/ledger.ts";
 import {
@@ -22,6 +27,7 @@ type ExecutionEffect = "continued" | "tool-blocked" | "session-blocked";
 export interface AdvisorInvocationRecord {
   cost?: number;
   decision?: GateDecision;
+  followUp?: boolean;
   executionEffect: ExecutionEffect;
   failure?: string;
   kind: "markdown" | "gate";
@@ -179,9 +185,14 @@ export class AdvisorSessionState {
   #consumedCalls = 0;
   #callReservations = new Set<string>();
   readonly #jev = new AdvisorJevLedgerState();
+  readonly #followUps: AdvisorFollowUpCache;
   #sessionTurnOrdinal = 0;
   #turnsSinceConsultation = 0;
 
+  constructor(now?: () => number) {
+    this.#followUps = new AdvisorFollowUpCache(now);
+  }
+
   resetTask() {
     this.#repetition = freshRepetition();
     this.#blockedReason = undefined;
@@ -190,6 +201,7 @@ export class AdvisorSessionState {
     this.#consumedCalls = 0;
     this.#callReservations.clear();
     this.#jev.reset();
+    this.#followUps.clear();
     this.#sessionTurnOrdinal = 0;
     this.#turnsSinceConsultation = 0;
   }
@@ -268,6 +280,26 @@ export class AdvisorSessionState {
     return this.#consumedCalls;
   }
 
+  advanceFollowUpToolCall() {
+    this.#followUps.advanceToolCall();
+  }
+
+  clearFollowUps() {
+    this.#followUps.clear();
+  }
+
+  followUpFor(adviceId: string): AdvisorFollowUpLookup {
+    return this.#followUps.get(adviceId);
+  }
+
+  captureFollowUp(
+    adviceId: string,
+    payload: AdvisorFollowUpPayload,
+    replacesAdviceId?: string
+  ) {
+    this.#followUps.capture(adviceId, payload, replacesAdviceId);
+  }
+
   /** Counts one completed executor turn on both turn counters. The ordinal
    * feeds the filter override window and summary positions and is never reset
    * by anything; turnsSinceConsultation resets on every consultation. */
@@ -495,6 +527,7 @@ export class AdvisorSessionState {
       `Budget: ${budget}`,
       `Usage: ${formatAdvisorUsageTotals(totals)}`,
       `Markdown advice: ${markdown.length} responses (${this.#ledger.draftConsultations} with drafts)`,
+      `Follow-ups: ${markdown.filter((item) => item.followUp).length}`,
       `Outcome reports: ${this.#ledger.outcomes}`,
       `Gate decisions: ${this.#decisionsLine()}`,
       `Loop matching: normalized tool signatures; ${this.#repetition.interventions} gate intervention${this.#repetition.interventions === 1 ? "" : "s"}`,

package/src/tools/advisor-output.ts

@@ -0,0 +1,28 @@
+import { Type } from "typebox";
+
+export const advisorOutputSchema = Type.Object({
+  adviceId: Type.Optional(Type.String()),
+  advisor: Type.Optional(Type.String()),
+  followUp: Type.Optional(Type.Boolean()),
+  jev: Type.Optional(
+    Type.Object({
+      kind: Type.Union([Type.Literal("screened"), Type.Literal("repeat")]),
+      reason: Type.String(),
+      skipped: Type.Boolean(),
+    })
+  ),
+  skipReason: Type.Optional(Type.String()),
+  text: Type.String({
+    description: "Advisor Markdown or consultation skip notice.",
+  }),
+  usage: Type.Optional(
+    Type.Object({
+      cacheRead: Type.Optional(Type.Number()),
+      cacheWrite: Type.Optional(Type.Number()),
+      cost: Type.Optional(Type.Number()),
+      input: Type.Optional(Type.Number()),
+      output: Type.Optional(Type.Number()),
+      totalTokens: Type.Optional(Type.Number()),
+    })
+  ),
+});