pi-advisor-flow 0.5.0 → 0.5.2

package/src/commands/manual-command.ts

@@ -0,0 +1,107 @@
+import {
+  getAdvisorMaxCallsPerSession,
+  getAdvisorSettings,
+  isSimpleMode,
+} from "../config/state.js";
+import type { GitContextLevel } from "../git.js";
+import { resolveAdvisorRequest } from "../tools/render-common.js";
+import { ManualAdvisorDialog } from "../ui/manual-dialog.js";
+import type { ManualAdvisorRequest } from "../ui/types.js";
+import { loadCommandConfig } from "./activation-preparation.js";
+import { startManualConsultation } from "./manual-consultation.js";
+import type { CommandRuntime, ManualAdvisorProgressState } from "./types.js";
+
+export const registerManualCommand = (runtime: CommandRuntime) => {
+  runtime.pi.registerCommand("advisor-manual", {
+    description:
+      "Consult the Advisor in parallel; accepts an optional focused question and fans its response out to the Executor",
+    handler: async (args, ctx) => {
+      if (!loadCommandConfig(ctx)) {
+        return;
+      }
+      if (
+        !(
+          isSimpleMode() ||
+          runtime.advisorSessionState.canConsult(getAdvisorMaxCallsPerSession())
+        )
+      ) {
+        runtime.reportManualBudgetExhausted(ctx);
+        return;
+      }
+
+      let gitContext: GitContextLevel | undefined;
+      let question: string | undefined;
+      if (ctx.mode === "tui") {
+        const request = await ctx.ui.custom<ManualAdvisorRequest | undefined>(
+          (tui, theme, keybindings, done) =>
+            new ManualAdvisorDialog({
+              gitContext: getAdvisorSettings().gitContext,
+              initialMessage: args,
+              keybindings,
+              onCancel: () => done(undefined),
+              onSubmit: done,
+              theme,
+              tui,
+            }),
+          {
+            overlay: true,
+            overlayOptions: {
+              anchor: "center",
+              margin: 2,
+              maxHeight: "80%",
+              minWidth: 56,
+              width: 76,
+            },
+          }
+        );
+        if (!request) {
+          return;
+        }
+        if (
+          !(
+            isSimpleMode() ||
+            runtime.advisorSessionState.canConsult(
+              getAdvisorMaxCallsPerSession()
+            )
+          )
+        ) {
+          runtime.reportManualBudgetExhausted(ctx);
+          return;
+        }
+        const { gitContext: selectedGitContext, message } = request;
+        gitContext = selectedGitContext;
+        question = resolveAdvisorRequest(message);
+      } else {
+        question = resolveAdvisorRequest(args);
+      }
+
+      if (!isSimpleMode()) {
+        runtime.advisorSessionState.consumeCall();
+      }
+      // A single visible progress surface avoids competing consultations overwriting
+      // each other's streamed state. A newer manual request replaces the previous one.
+      for (const [pending, token] of runtime.manualConsultations) {
+        pending.abort();
+        runtime.scoutStatus.release(ctx, token);
+      }
+      runtime.manualConsultations.clear();
+      const controller = new AbortController();
+      const scoutStatusToken = Symbol("manual-scout");
+      const progressId = runtime.nextManualProgressId();
+      const progress: ManualAdvisorProgressState = { phase: "preparing" };
+      runtime.manualProgress.set(progressId, progress);
+      runtime.scoutStatus.register(scoutStatusToken);
+      runtime.manualConsultations.set(controller, scoutStatusToken);
+      runtime.pi.appendEntry?.("advisor-manual-call", { progressId, question });
+      startManualConsultation(
+        runtime,
+        ctx,
+        question,
+        controller,
+        scoutStatusToken,
+        progress,
+        gitContext
+      );
+    },
+  });
+};

package/src/commands/manual-consultation.ts

@@ -0,0 +1,144 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { advisorRef } from "../config/state.js";
+import type { GitContextLevel } from "../git.js";
+import { herdrAdvisorActivity, notifyHerdrAdvisorFailure } from "../herdr.js";
+import { appendScoutLifecycleEntry } from "../tools/scout-status.js";
+import type { ScoutToolDetails } from "../tools/types.js";
+import { advisorUsageCost, snapshotAdvisorUsage } from "../usage.js";
+import { notify } from "./runtime.js";
+import type { CommandRuntime, ManualAdvisorProgressState } from "./types.js";
+
+export const startManualConsultation = (
+  runtime: CommandRuntime,
+  ctx: ExtensionContext,
+  question: string | undefined,
+  controller: AbortController,
+  scoutStatusToken: symbol,
+  progress: ManualAdvisorProgressState,
+  gitContext?: GitContextLevel
+) => {
+  herdrAdvisorActivity.start();
+  progress.phase = "preparing";
+  runtime.requestManualRender(ctx);
+  if (ctx.hasUI) {
+    const timer = setInterval(() => {
+      if (
+        controller.signal.aborted ||
+        runtime.manualConsultations.get(controller) !== scoutStatusToken
+      ) {
+        clearInterval(timer);
+        return;
+      }
+      runtime.requestManualRender(ctx);
+    }, 80);
+    runtime.manualProgressTimers.set(controller, timer);
+  }
+  let scoutDetails: ScoutToolDetails | undefined;
+  return 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";
+          runtime.requestManualRender(ctx);
+        }
+      },
+      gitContext
+    )
+    .then(({ markdown, usage }) => {
+      if (controller.signal.aborted) {
+        return;
+      }
+      progress.phase = "complete";
+      runtime.advisorSessionState.recordInvocation({
+        cost: advisorUsageCost(usage),
+        executionEffect: "continued",
+        kind: "markdown",
+        model: advisorRef,
+        trigger: "manual",
+        usage,
+      });
+      runtime.updateAdvisorUsageStatus(ctx);
+      const normalizedUsage = snapshotAdvisorUsage(usage);
+      runtime.pi.sendMessage(
+        {
+          content: `Manual Advisor consultation${question ? ` (${question})` : ""}:\n\n${markdown}`,
+          customType: "advisor-manual-result",
+          details: {
+            advisor: advisorRef,
+            question,
+            text: markdown,
+            ...(normalizedUsage ? { usage: normalizedUsage } : {}),
+          },
+          display: true,
+        },
+        {
+          // Steer lets the current turn finish its active work; the Executor sees
+          // the result before its next model call rather than being interrupted.
+          deliverAs: "steer",
+          triggerTurn: true,
+        }
+      );
+    })
+    .catch((error: unknown) => {
+      if (controller.signal.aborted) {
+        return;
+      }
+      progress.phase = "error";
+      const message = error instanceof Error ? error.message : String(error);
+      runtime.advisorSessionState.recordInvocation({
+        executionEffect: "continued",
+        failure: "provider-error",
+        kind: "markdown",
+        model: advisorRef,
+        trigger: "manual",
+      });
+      runtime.updateAdvisorUsageStatus(ctx);
+      runtime.pi.sendMessage(
+        {
+          content: `Manual Advisor consultation failed: ${message}`,
+          customType: "advisor-manual-result",
+          details: {
+            advisor: advisorRef,
+            text: `**Advisor consultation failed:** ${message}`,
+          },
+          display: true,
+        },
+        { deliverAs: "steer", triggerTurn: true }
+      );
+      notify(ctx, `Advisor consultation failed: ${message}`, "error");
+      notifyHerdrAdvisorFailure("Advisor consultation failed", message);
+    })
+    .finally(() => {
+      if (controller.signal.aborted) {
+        progress.phase = "cancelled";
+      }
+      const timer = runtime.manualProgressTimers.get(controller);
+      if (timer) {
+        clearInterval(timer);
+        runtime.manualProgressTimers.delete(controller);
+      }
+      runtime.requestManualRender(ctx);
+      runtime.scoutStatus.release(ctx, scoutStatusToken);
+      runtime.manualConsultations.delete(controller);
+      herdrAdvisorActivity.finish();
+    });
+};

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 };
+};