pi-advisor-flow 0.5.0 → 0.5.2

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);

package/src/commands/settings-commands.ts

@@ -0,0 +1,80 @@
+import {
+  alwaysOnRef,
+  getAdvisorSettings,
+  getPersistedModelRefs,
+  setAlwaysOnRef,
+} from "../config/state.js";
+import { saveConfig } from "../config/storage.js";
+import { AdvisorSettingsSelector } from "../ui/settings-selector.js";
+import { loadCommandConfig } from "./activation-preparation.js";
+import { CONTEXT_PRESETS, EFFORT_LEVELS } from "./model-options.js";
+import { notify } from "./runtime.js";
+import { saveAdvisorSettings } from "./settings-persistence.js";
+import type { CommandRuntime } from "./types.js";
+
+export const registerSettingsCommands = (runtime: CommandRuntime) => {
+  runtime.pi.registerCommand("advisor-settings", {
+    description: "Configure Advisor settings",
+    handler: async (_args, ctx) => {
+      if (!(loadCommandConfig(ctx) && ctx.hasUI)) {
+        return;
+      }
+
+      const initial = getAdvisorSettings();
+      await ctx.ui.custom<void>(
+        (tui, theme, _keybindings, done) =>
+          new AdvisorSettingsSelector({
+            effortLevels: EFFORT_LEVELS,
+            initial,
+            onCancel: () => done(),
+            onChange: (settings) => {
+              try {
+                saveAdvisorSettings(ctx, settings);
+                runtime.updateAdvisorUsageStatus(ctx);
+              } catch (error) {
+                const message =
+                  error instanceof Error ? error.message : String(error);
+                ctx.ui.notify(
+                  `Could not save Advisor settings: ${message}`,
+                  "error"
+                );
+              }
+            },
+            presets: CONTEXT_PRESETS,
+            theme,
+            tui,
+          })
+      );
+    },
+  });
+
+  runtime.pi.registerCommand("advisor-off", {
+    description: "Disable on-demand Advisor calls; keep the current model",
+    handler: (_args, ctx) => {
+      runtime.pi.setActiveTools(
+        runtime.pi
+          .getActiveTools()
+          .filter(
+            (name) =>
+              name !== "ask_advisor" && name !== "record_advisor_outcome"
+          )
+      );
+      // Leaving alwaysOn set would silently reactivate the flow next session.
+      const wasAlwaysOn = alwaysOnRef;
+      if (wasAlwaysOn) {
+        const persisted = getPersistedModelRefs();
+        setAlwaysOnRef(false);
+        saveConfig(ctx, {
+          persistAdvisor: Boolean(persisted.advisor),
+          persistExecutor: Boolean(persisted.executor),
+        });
+      }
+      notify(
+        ctx,
+        `Advisor flow disabled. Current model unchanged.${wasAlwaysOn ? " Always on turned off." : ""}`,
+        "info"
+      );
+      return Promise.resolve();
+    },
+  });
+};

package/src/commands/settings-persistence.ts

@@ -0,0 +1,81 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  getPersistedModelRefs,
+  setAdvisorAutoLoopGateRef,
+  setAdvisorBlockOnBlockedRef,
+  setAdvisorCollapseResponsesRef,
+  setAdvisorCompletionGateRef,
+  setAdvisorCustomInvocationRef,
+  setAdvisorEffortRef,
+  setAdvisorFailureGateRef,
+  setAdvisorFailureModeRef,
+  setAdvisorGitContextMaxCharsRef,
+  setAdvisorGitContextRef,
+  setAdvisorHerdrIntegrationRef,
+  setAdvisorLoopThresholdRef,
+  setAdvisorMaxCallsPerSessionRef,
+  setAdvisorOutcomeLoggingRef,
+  setAdvisorPlanGateRef,
+  setAdvisorRedactSecretsRef,
+  setAdvisorScoutEnabledRef,
+  setAdvisorSessionSummaryRef,
+  setAdvisorToolPoliciesRef,
+  setAdvisorToolResultMaxBytesRef,
+  setAdvisorToolResultMaxLinesRef,
+  setAdvisorTrackedFileContentRef,
+  setAdvisorUntrackedContentRef,
+  setAlwaysOnRef,
+  setContextMaxCharsRef,
+  setShowUsageDetailsRef,
+  setShowUsageFooterRef,
+  setSimpleModeRef,
+} from "../config/state.js";
+import { saveConfig, saveGlobalOutcomeLogging } from "../config/storage.js";
+import type { AdvisorSettings } from "../ui/types.js";
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one settings form maps every persisted control.
+export const applyAdvisorSettings = (settings: AdvisorSettings) => {
+  setAdvisorEffortRef(
+    settings.effort === "Default (Model Default)" ? undefined : settings.effort
+  );
+  setContextMaxCharsRef(settings.contextMaxChars);
+  setAdvisorPlanGateRef(settings.planGate);
+  setAdvisorFailureGateRef(settings.failureGate);
+  setAdvisorCompletionGateRef(settings.completionGate);
+  setAdvisorCollapseResponsesRef(settings.collapseResponses);
+  setAdvisorCustomInvocationRef(settings.customRule);
+  setAdvisorBlockOnBlockedRef(settings.blockOnBlocked ?? true);
+  setAdvisorAutoLoopGateRef(settings.autoLoopGate ?? true);
+  setAdvisorLoopThresholdRef(settings.loopThreshold ?? 3);
+  setAdvisorMaxCallsPerSessionRef(settings.maxCallsPerSession);
+  setAdvisorSessionSummaryRef(settings.sessionSummary ?? false);
+  setAdvisorScoutEnabledRef(settings.scoutEnabled ?? false);
+  setShowUsageDetailsRef(settings.showUsageDetails ?? true);
+  setShowUsageFooterRef(settings.showUsageFooter ?? false);
+  setSimpleModeRef(settings.simpleMode ?? false);
+  setAlwaysOnRef(settings.alwaysOn ?? false);
+  setAdvisorFailureModeRef(settings.failureMode ?? "block-session");
+  setAdvisorHerdrIntegrationRef(settings.herdrIntegration ?? true);
+  setAdvisorToolResultMaxLinesRef(settings.toolResultMaxLines ?? 2000);
+  setAdvisorToolResultMaxBytesRef(settings.toolResultMaxBytes ?? 50 * 1024);
+  setAdvisorRedactSecretsRef(settings.redactSecrets ?? false);
+  setAdvisorGitContextRef(settings.gitContext ?? "summary");
+  setAdvisorGitContextMaxCharsRef(settings.gitContextMaxChars ?? 20_000);
+  setAdvisorToolPoliciesRef(settings.toolPolicies ?? {});
+  setAdvisorTrackedFileContentRef(settings.trackedFileContent ?? false);
+  setAdvisorUntrackedContentRef(settings.untrackedContent ?? false);
+  setAdvisorOutcomeLoggingRef(settings.outcomeLogging ?? false);
+};
+
+export const saveAdvisorSettings = (
+  ctx: ExtensionContext,
+  settings: AdvisorSettings
+) => {
+  applyAdvisorSettings(settings);
+  const persisted = getPersistedModelRefs();
+  saveConfig(ctx, {
+    persistAdvisor: Boolean(persisted.advisor),
+    persistExecutor: Boolean(persisted.executor),
+  });
+  saveGlobalOutcomeLogging(settings.outcomeLogging ?? false);
+};

package/src/commands/types.ts

@@ -0,0 +1,78 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import type { GitContextLevel } from "../git.js";
+import type { ScoutLifecycleEvent } from "../scout.js";
+import type { AdvisorSessionState } from "../session-state.js";
+import type { ScoutStatusManager } from "../tools/scout-status.js";
+import type { ScoutToolDetails } from "../tools/types.js";
+
+export type ManualConsult = (
+  ctx: ExtensionContext,
+  question?: string,
+  signal?: AbortSignal,
+  onChunk?: (thinking: string, text: string) => void,
+  onScout?: (event: ScoutLifecycleEvent) => void,
+  gitContext?: GitContextLevel
+) => Promise<{
+  markdown: string;
+  thinkingText: string;
+  draftBytes?: number;
+  preferenceBytes?: number;
+  usage?: unknown;
+}>;
+
+export type ThinkingLevel = Parameters<ExtensionAPI["setThinkingLevel"]>[0];
+
+export type ManualAdvisorProgressPhase =
+  | "preparing"
+  | "active"
+  | "complete"
+  | "cancelled"
+  | "error";
+
+export interface ManualAdvisorProgressState {
+  phase: ManualAdvisorProgressPhase;
+  scout?: ScoutToolDetails;
+  text?: string;
+  thinking?: string;
+}
+
+export interface CommandDependencies {
+  consult?: ManualConsult;
+  sessionState?: AdvisorSessionState;
+  statusManager?: ScoutStatusManager;
+}
+
+export interface CommandRuntime {
+  readonly advisorSessionState: AdvisorSessionState;
+  flowEnabled: () => boolean;
+  readonly manualConsultations: Map<AbortController, symbol>;
+  readonly manualProgress: Map<string, ManualAdvisorProgressState>;
+  manualProgressSequence: number;
+  readonly manualProgressTimers: Map<
+    AbortController,
+    ReturnType<typeof setInterval>
+  >;
+  nextManualProgressId: () => string;
+  pendingExecutorModelRef: string | undefined;
+  readonly pi: ExtensionAPI;
+  reportManualBudgetExhausted: (ctx: ExtensionContext) => void;
+  readonly requestAdvisor: ManualConsult;
+  requestManualRender: (ctx: ExtensionContext) => void;
+  readonly scoutStatus: ScoutStatusManager;
+  setExecutorModel: (
+    model: Parameters<ExtensionAPI["setModel"]>[0]
+  ) => ReturnType<ExtensionAPI["setModel"]>;
+  suppressModelSelectionSync: boolean;
+  updateAdvisorUsageStatus: (ctx: ExtensionContext) => void;
+}
+
+export interface ManualAdvisorProgressView {
+  expanded: boolean;
+  question: string | undefined;
+  state: ManualAdvisorProgressState;
+  theme: Theme;
+}