pi-advisor-flow 0.5.1 → 0.5.3

package/src/commands/manual-progress.ts

@@ -0,0 +1,93 @@
+import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, Markdown, Text } from "@earendil-works/pi-tui";
+import {
+  adviceForDisplay,
+  renderAdvisorCallBox,
+  renderThinkingMarkdown,
+  SPINNER_FRAMES,
+} from "../tools/render-common.js";
+import { renderScoutDetails } from "../tools/scout-status.js";
+import type { ManualAdvisorProgressState } from "./types.js";
+
+export class ManualAdvisorProgressComponent implements Component {
+  private readonly question: string | undefined;
+  private readonly state: ManualAdvisorProgressState;
+  private readonly expanded: boolean;
+  private readonly theme: Theme;
+
+  constructor(
+    question: string | undefined,
+    state: ManualAdvisorProgressState,
+    expanded: boolean,
+    theme: Theme
+  ) {
+    this.question = question;
+    this.state = state;
+    this.expanded = expanded;
+    this.theme = theme;
+  }
+
+  render(width: number): string[] {
+    const box = renderAdvisorCallBox(this.question, this.theme);
+    if (this.state.phase === "complete" || this.state.phase === "cancelled") {
+      return box.render(width);
+    }
+
+    const { scout } = this.state;
+    const scoutActive =
+      scout?.status === "calling" || scout?.status === "streaming";
+    if (scoutActive) {
+      renderScoutDetails(box, scout, this.expanded, this.theme);
+      return box.render(width);
+    }
+    if (scout?.status === "cancelled") {
+      return box.render(width);
+    }
+    if (this.state.phase === "error") {
+      box.addChild(
+        new Text(
+          this.theme.fg("error", this.theme.bold("◆ ADVISOR · FAILED")),
+          0,
+          0
+        )
+      );
+      return box.render(width);
+    }
+
+    const frame =
+      SPINNER_FRAMES[Math.floor(Date.now() / 80) % SPINNER_FRAMES.length];
+    let status = "Working…";
+    if (this.state.phase === "preparing") {
+      status = "Preparing…";
+    } else if (this.state.text?.trim()) {
+      status = "Responding…";
+    }
+    box.addChild(
+      new Text(
+        `${this.theme.fg("warning", this.theme.bold(`◆ ADVISOR ${frame}`))} ${this.theme.fg("dim", `· ${status}`)}`,
+        0,
+        0
+      )
+    );
+    if (this.state.thinking?.trim()) {
+      box.addChild(
+        renderThinkingMarkdown(this.state.thinking.slice(-200), this.theme)
+      );
+    }
+    if (this.state.text) {
+      box.addChild(
+        new Markdown(
+          adviceForDisplay(this.state.text, this.expanded),
+          0,
+          0,
+          getMarkdownTheme()
+        )
+      );
+    }
+    return box.render(width);
+  }
+
+  invalidate(): void {
+    // The live progress state is read during each render.
+  }
+}

package/src/commands/model-commands.ts

@@ -0,0 +1,66 @@
+import {
+  advisorEffortRef,
+  advisorRef,
+  executorEffortRef,
+  executorRef,
+  getPersistedModelRefs,
+  setAdvisorEffortRef,
+  setAdvisorRef,
+  setExecutorEffortRef,
+  setExecutorRef,
+} from "../config/state.js";
+import { saveConfig } from "../config/storage.js";
+import { activateAdvisor } from "./activation.js";
+import { loadCommandConfig } from "./activation-preparation.js";
+import { selectAdvisorModels } from "./model-picker.js";
+import type { CommandRuntime } from "./types.js";
+
+export const registerModelCommands = (runtime: CommandRuntime) => {
+  runtime.pi.registerCommand("advisor", {
+    description:
+      "Enable the Executor/Advisor flow and switch to the configured or explicitly selected Executor model; accepts contextMaxChars=N",
+    handler: (args, ctx) => activateAdvisor(runtime, args, ctx),
+  });
+
+  runtime.pi.registerCommand("advisor-models", {
+    description:
+      "Select and persist the Executor and Advisor models with reasoning levels",
+    handler: async (_args, ctx) => {
+      if (!(loadCommandConfig(ctx) && ctx.hasUI)) {
+        return;
+      }
+      // When `/model` was used before activation, show that session choice as
+      // the Executor's current option instead of making the persisted Executor
+      // look like the active selection.
+      const persisted = getPersistedModelRefs();
+      const selection = await selectAdvisorModels(ctx, {
+        advisor: persisted.advisor ? advisorRef : "",
+        advisorEffort: advisorEffortRef,
+        executor:
+          runtime.pendingExecutorModelRef ??
+          (persisted.executor ? executorRef : ""),
+        executorEffort: executorEffortRef,
+        selectAdvisor: true,
+        selectExecutor: true,
+      });
+      if (!selection) {
+        return;
+      }
+
+      setExecutorRef(selection.executor);
+      setAdvisorRef(selection.advisor);
+      setExecutorEffortRef(selection.executorEffort);
+      setAdvisorEffortRef(selection.advisorEffort);
+
+      const path = saveConfig(ctx, {
+        persistAdvisor: true,
+        persistExecutor: true,
+      });
+      runtime.pendingExecutorModelRef = undefined;
+      ctx.ui.notify(
+        `Saved Executor + Advisor configurations to ${path}`,
+        "info"
+      );
+    },
+  });
+};

package/src/commands/model-options.ts

@@ -0,0 +1,181 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type getPersistedModelRefs, splitRef } from "../config/state.js";
+import type { ContextPreset } from "../ui/types.js";
+
+export const DEFAULT_EFFORT_LEVEL = "Default (Model Default)";
+export const SELECTED_PREFIX = "✓ ";
+export const EFFORT_LEVELS = [
+  DEFAULT_EFFORT_LEVEL,
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+];
+
+export const effortChoices = (configured: string | undefined): string[] => {
+  const current = configured ?? DEFAULT_EFFORT_LEVEL;
+  return [
+    `${SELECTED_PREFIX}${current}`,
+    ...EFFORT_LEVELS.filter((level) => level !== current),
+  ];
+};
+
+export const selectedEffort = (choice: string): string | undefined => {
+  const effort = choice.startsWith(SELECTED_PREFIX)
+    ? choice.slice(SELECTED_PREFIX.length)
+    : choice;
+  return effort === DEFAULT_EFFORT_LEVEL ? undefined : effort;
+};
+
+export const ADVISOR_ACTIVATION_EXPLANATION =
+  "The Advisor is a second-opinion model that reviews the Executor's context and returns risks, alternatives, and verification steps without changing files or running tools.";
+
+const ARGUMENT_WHITESPACE = /\s+/;
+const hasModelOverride = (args: string, key: "advisor" | "executor") =>
+  args
+    .trim()
+    .split(ARGUMENT_WHITESPACE)
+    .some((token) => {
+      const [tokenKey, value] = token.split("=");
+      return tokenKey === key && Boolean(value);
+    });
+
+export const hasExecutorOverride = (args: string) =>
+  hasModelOverride(args, "executor");
+export const hasAdvisorOverride = (args: string) =>
+  hasModelOverride(args, "advisor");
+
+export const CONTEXT_PRESETS: ContextPreset[] = [
+  {
+    description:
+      "No conversation history. The Advisor receives only its standing instructions.",
+    label: "0",
+    value: 0,
+  },
+  {
+    description: "The most recent 10,000 characters of the current branch.",
+    label: "10k",
+    value: 10_000,
+  },
+  {
+    description: "The most recent 25,000 characters of the current branch.",
+    label: "25k",
+    value: 25_000,
+  },
+  {
+    description: "The most recent 100,000 characters of the current branch.",
+    label: "100k",
+    value: 100_000,
+  },
+  {
+    description: "The most recent 200,000 characters of the current branch.",
+    label: "200k",
+    value: 200_000,
+  },
+  {
+    description:
+      "The complete reconstructed conversation branch. Cost and model context limits apply.",
+    label: "ALL",
+    value: Number.MAX_SAFE_INTEGER,
+  },
+];
+
+export const findConfiguredModel = (
+  ctx: ExtensionContext,
+  ref: string | undefined
+) => {
+  if (!ref) {
+    return;
+  }
+  const [provider, modelId] = splitRef(ref);
+  return ctx.modelRegistry.find(provider, modelId);
+};
+
+export const getAvailableModelRefs = (
+  ctx: ExtensionContext
+): string[] | undefined => {
+  if (typeof ctx.modelRegistry.getAvailable !== "function") {
+    return undefined;
+  }
+  return ctx.modelRegistry
+    .getAvailable()
+    .map((model) => `${model.provider}/${model.id}`);
+};
+
+export const isSelectableModel = (
+  ctx: ExtensionContext,
+  ref: string | undefined,
+  availableRefs: Set<string> | undefined
+) => {
+  if (!ref) {
+    return false;
+  }
+  if (availableRefs) {
+    const [provider, modelId] = splitRef(ref);
+    return availableRefs.has(`${provider}/${modelId}`);
+  }
+  return Boolean(findConfiguredModel(ctx, ref));
+};
+
+export const getExplicitModelError = (
+  ctx: ExtensionContext,
+  ref: string | undefined,
+  label: "Advisor" | "Executor",
+  overridden: boolean,
+  availableRefs: Set<string> | undefined
+) => {
+  if (overridden) {
+    if (!ref) {
+      return `${label} model not configured`;
+    }
+    if (!findConfiguredModel(ctx, ref)) {
+      return `${label} model not found: ${ref}`;
+    }
+    if (availableRefs && !isSelectableModel(ctx, ref, availableRefs)) {
+      return `${label} model unavailable: ${ref}`;
+    }
+  }
+};
+
+export interface ActivationModelPlan {
+  pendingExecutor: string | undefined;
+  selectAdvisor: boolean;
+  selectExecutor: boolean;
+}
+
+export const planActivationModels = (
+  ctx: ExtensionContext,
+  executor: string | undefined,
+  advisor: string | undefined,
+  pendingExecutorRef: string | undefined,
+  persisted: ReturnType<typeof getPersistedModelRefs>,
+  executorOverride: boolean,
+  advisorOverride: boolean,
+  availableRefs: Set<string> | undefined
+): ActivationModelPlan => {
+  const pendingExecutor =
+    !executorOverride &&
+    pendingExecutorRef &&
+    isSelectableModel(ctx, pendingExecutorRef, availableRefs)
+      ? pendingExecutorRef
+      : undefined;
+  const executorConfigured =
+    executorOverride ||
+    Boolean(pendingExecutor) ||
+    Boolean(
+      persisted.executor && isSelectableModel(ctx, executor, availableRefs)
+    );
+  const advisorConfigured =
+    advisorOverride ||
+    Boolean(
+      persisted.advisor && isSelectableModel(ctx, advisor, availableRefs)
+    );
+  return {
+    pendingExecutor,
+    selectAdvisor: !advisorConfigured,
+    selectExecutor: !executorConfigured,
+  };
+};

package/src/commands/model-picker.ts

@@ -0,0 +1,110 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { SearchableModelSelector } from "../ui/model-selector.js";
+import {
+  effortChoices,
+  getAvailableModelRefs,
+  selectedEffort,
+} from "./model-options.js";
+
+export interface AdvisorModelSelection {
+  advisor: string;
+  advisorEffort: string | undefined;
+  executor: string;
+  executorEffort: string | undefined;
+}
+
+export interface AdvisorModelPickerOptions {
+  advisor: string | undefined;
+  advisorEffort: string | undefined;
+  executor: string | undefined;
+  executorEffort: string | undefined;
+  selectAdvisor: boolean;
+  selectExecutor: boolean;
+}
+
+export const selectAdvisorModels = async (
+  ctx: ExtensionContext,
+  options: AdvisorModelPickerOptions
+): Promise<AdvisorModelSelection | undefined> => {
+  if (!ctx.hasUI) {
+    return undefined;
+  }
+  const refs = getAvailableModelRefs(ctx);
+  if (refs && refs.length === 0) {
+    ctx.ui.notify(
+      "No selectable models are available. Configure a provider with /login or models.json, then retry.",
+      "error"
+    );
+    return undefined;
+  }
+  const allOptions = [
+    ...new Set(
+      refs ??
+        [options.executor, options.advisor].filter((ref): ref is string =>
+          Boolean(ref)
+        )
+    ),
+  ];
+  let { advisor, advisorEffort, executor, executorEffort } = options;
+
+  if (options.selectExecutor) {
+    const selectedExecutor = await ctx.ui.custom<string | undefined>(
+      (tui, theme, keybindings, done) =>
+        new SearchableModelSelector({
+          allOptions,
+          currentOption: executor || undefined,
+          keybindings,
+          onCancel: () => done(undefined),
+          onSelect: done,
+          theme,
+          title: "Select Executor Model",
+          tui,
+        })
+    );
+    if (!selectedExecutor) {
+      return undefined;
+    }
+    const selectedExecutorEffort = await ctx.ui.select(
+      "Select Executor Reasoning/Thinking Level",
+      effortChoices(executorEffort)
+    );
+    if (!selectedExecutorEffort) {
+      return undefined;
+    }
+    executor = selectedExecutor;
+    executorEffort = selectedEffort(selectedExecutorEffort);
+  }
+
+  if (options.selectAdvisor) {
+    const selectedAdvisor = await ctx.ui.custom<string | undefined>(
+      (tui, theme, keybindings, done) =>
+        new SearchableModelSelector({
+          allOptions,
+          currentOption: advisor || undefined,
+          keybindings,
+          onCancel: () => done(undefined),
+          onSelect: done,
+          theme,
+          title: "Select Advisor Model",
+          tui,
+        })
+    );
+    if (!selectedAdvisor) {
+      return undefined;
+    }
+    const selectedAdvisorEffort = await ctx.ui.select(
+      "Select Advisor Reasoning/Thinking Level",
+      effortChoices(advisorEffort)
+    );
+    if (!selectedAdvisorEffort) {
+      return undefined;
+    }
+    advisor = selectedAdvisor;
+    advisorEffort = selectedEffort(selectedAdvisorEffort);
+  }
+
+  if (!(advisor && executor)) {
+    return undefined;
+  }
+  return { advisor, advisorEffort, executor, executorEffort };
+};

package/src/commands/registration.ts

@@ -0,0 +1,27 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { activateAdvisor } from "./activation.js";
+import { registerCommandLifecycle } from "./lifecycle.js";
+import { registerManualCommand } from "./manual-command.js";
+import { registerModelCommands } from "./model-commands.js";
+import { registerCommandRenderers } from "./renderers.js";
+import { createCommandRuntime } from "./runtime.js";
+import { registerSettingsCommands } from "./settings-commands.js";
+import type { CommandDependencies } from "./types.js";
+
+export const registerCommands = (
+  pi: ExtensionAPI,
+  dependencies: CommandDependencies = {}
+) => {
+  const runtime = createCommandRuntime(pi, dependencies);
+  const activate = (args: string, ctx: ExtensionContext, announce = true) =>
+    activateAdvisor(runtime, args, ctx, announce);
+
+  registerCommandRenderers(runtime);
+  registerCommandLifecycle(runtime, activate);
+  registerManualCommand(runtime);
+  registerModelCommands(runtime);
+  registerSettingsCommands(runtime);
+};

package/src/commands/renderers.ts

@@ -0,0 +1,76 @@
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Box, Markdown, Text } from "@earendil-works/pi-tui";
+import { getAdvisorSettings } from "../config/state.js";
+import {
+  adviceForDisplay,
+  hasSoundVerdict,
+  renderAdvisorCallBox,
+  renderAdvisorResponseHeader,
+} from "../tools/render-common.js";
+import { formatAdvisorUsage } from "../usage.js";
+import { ManualAdvisorProgressComponent } from "./manual-progress.js";
+import type { CommandRuntime } from "./types.js";
+
+export const registerCommandRenderers = (runtime: CommandRuntime) => {
+  runtime.pi.registerEntryRenderer?.(
+    "advisor-manual-call",
+    (entry, { expanded }, theme) => {
+      const { progressId, question } = (entry.data ?? {}) as {
+        progressId?: string;
+        question?: string;
+      };
+      const progress = progressId
+        ? runtime.manualProgress.get(progressId)
+        : undefined;
+      return progress
+        ? new ManualAdvisorProgressComponent(
+            question,
+            progress,
+            Boolean(expanded),
+            theme
+          )
+        : renderAdvisorCallBox(question, theme);
+    }
+  );
+
+  runtime.pi.registerMessageRenderer?.(
+    "advisor-manual-result",
+    (message, { expanded }, theme) => {
+      const details = message.details as
+        | { advisor?: string; text?: string; usage?: unknown }
+        | undefined;
+      const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+      const advice =
+        details?.text ??
+        (typeof message.content === "string"
+          ? message.content
+          : "(Advisor returned no advice.)");
+      // Manual consultations must render exactly like an Executor ask_advisor call.
+      box.addChild(
+        new Text(
+          renderAdvisorResponseHeader(hasSoundVerdict(advice), theme),
+          0,
+          0
+        )
+      );
+      if (details?.advisor) {
+        box.addChild(new Text(theme.fg("dim", `  ${details.advisor}`), 0, 0));
+      }
+      if (getAdvisorSettings().showUsageDetails) {
+        const usage = formatAdvisorUsage(details?.usage);
+        if (usage) {
+          box.addChild(new Text(theme.fg("dim", `  Usage: ${usage}`), 0, 0));
+        }
+      }
+      box.addChild(
+        new Markdown(
+          adviceForDisplay(advice, expanded),
+          0,
+          0,
+          getMarkdownTheme()
+        )
+      );
+      return box;
+    }
+  );
+};

package/src/commands/runtime.ts

@@ -0,0 +1,114 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { getAdvisorSettings } from "../config/state.js";
+import { notifyHerdrAdvisorFailure } from "../herdr.js";
+import type { AdvisorSessionState } from "../session-state.js";
+import { consultAdvisor } from "../tools/consultation.js";
+import { ScoutStatusManager } from "../tools/scout-status.js";
+import { advisorSessionState as defaultAdvisorSessionState } from "../tools/session.js";
+import type {
+  CommandDependencies,
+  CommandRuntime as CommandRuntimeContract,
+  ManualAdvisorProgressState,
+  ManualConsult,
+} from "./types.js";
+
+export const notify = (
+  ctx: ExtensionContext,
+  message: string,
+  level: "error" | "info" | "warning"
+) => {
+  if (ctx.hasUI) {
+    ctx.ui.notify(message, level);
+  }
+};
+
+export class CommandRuntime implements CommandRuntimeContract {
+  readonly advisorSessionState: AdvisorSessionState;
+  readonly manualConsultations = new Map<AbortController, symbol>();
+  readonly manualProgress = new Map<string, ManualAdvisorProgressState>();
+  readonly manualProgressTimers = new Map<
+    AbortController,
+    ReturnType<typeof setInterval>
+  >();
+  readonly pi: ExtensionAPI;
+  readonly requestAdvisor: ManualConsult;
+  readonly scoutStatus: ScoutStatusManager;
+  manualProgressSequence = 0;
+  pendingExecutorModelRef: string | undefined;
+  suppressModelSelectionSync = false;
+
+  constructor(pi: ExtensionAPI, dependencies: CommandDependencies = {}) {
+    this.pi = pi;
+    this.advisorSessionState =
+      dependencies.sessionState ?? defaultAdvisorSessionState;
+    this.scoutStatus =
+      dependencies.statusManager ?? new ScoutStatusManager(false);
+    this.requestAdvisor =
+      dependencies.consult ??
+      ((ctx, question, signal, onChunk, onScout, gitContext) =>
+        consultAdvisor(
+          ctx,
+          question,
+          signal,
+          onChunk,
+          "manual",
+          gitContext,
+          undefined,
+          undefined,
+          undefined,
+          onScout,
+          undefined
+        ));
+  }
+
+  flowEnabled() {
+    return this.pi.getActiveTools().includes("ask_advisor");
+  }
+
+  nextManualProgressId() {
+    this.manualProgressSequence += 1;
+    return `manual-${this.manualProgressSequence}`;
+  }
+
+  async setExecutorModel(
+    model: Parameters<ExtensionAPI["setModel"]>[0]
+  ): Promise<boolean> {
+    this.suppressModelSelectionSync = true;
+    try {
+      return await this.pi.setModel(model);
+    } finally {
+      this.suppressModelSelectionSync = false;
+    }
+  }
+
+  updateAdvisorUsageStatus(ctx: ExtensionContext) {
+    if (ctx.hasUI) {
+      ctx.ui.setStatus(
+        "advisor-usage",
+        getAdvisorSettings().showUsageFooter
+          ? this.advisorSessionState.usageStatus()
+          : undefined
+      );
+    }
+  }
+
+  reportManualBudgetExhausted(ctx: ExtensionContext) {
+    const message = "Advisor call budget exhausted for this session.";
+    notify(ctx, message, "warning");
+    notifyHerdrAdvisorFailure("Advisor budget exhausted", message);
+  }
+
+  requestManualRender(ctx: ExtensionContext) {
+    if (ctx.hasUI) {
+      ctx.ui.setStatus("advisor-manual", undefined);
+    }
+  }
+}
+
+export const createCommandRuntime = (
+  pi: ExtensionAPI,
+  dependencies: CommandDependencies = {}
+) => new CommandRuntime(pi, dependencies);