pi-advisor-flow 0.5.1 → 0.5.2

package/src/ui/settings-formatting.ts

@@ -0,0 +1,133 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { ContextPreset } from "./types.js";
+
+export const DEFAULT_EFFORT_LEVEL = "Default (Model Default)";
+export const TOGGLE_VALUES = ["On", "Off"];
+export const SIMPLE_MODE_GRADIENT_INTERVAL_MS = 100;
+// Purple steps with a moving light highlight, retained from the original UI.
+const SIMPLE_MODE_GRADIENT_COLORS = [
+  [125, 79, 205],
+  [143, 96, 218],
+  [160, 114, 230],
+  [178, 135, 238],
+  [195, 157, 245],
+  [168, 120, 230],
+  [143, 89, 215],
+] as const;
+
+export const withCurrentValue = (current: string, values: string[]) =>
+  values.includes(current) ? values : [current, ...values];
+
+export const numericValues = (current: number, values: number[]) => {
+  const all = values.includes(current) ? values : [...values, current];
+  return all.sort((a, b) => a - b).map(String);
+};
+
+export const maxCallValues = (current: string) => {
+  const values = ["0", "1", "2", "3", "5", "10", "25", "50", "∞"];
+  if (values.includes(current)) {
+    return values;
+  }
+  const numeric = Number(current);
+  const insertionIndex = values.findIndex(
+    (value) => value !== "∞" && Number(value) > numeric
+  );
+  return insertionIndex === -1
+    ? [...values.slice(0, -1), current, "∞"]
+    : [
+        ...values.slice(0, insertionIndex),
+        current,
+        ...values.slice(insertionIndex),
+      ];
+};
+
+export const settingValue = (
+  value: boolean | undefined,
+  defaultValue: boolean
+) => ((value ?? defaultValue) ? "On" : "Off");
+
+export const currentContextLabel = (
+  presets: ContextPreset[],
+  contextMaxChars: number
+): string =>
+  presets.find((preset) => preset.value === contextMaxChars)?.label ??
+  String(contextMaxChars);
+
+export const contextDescription = (
+  presets: ContextPreset[],
+  contextMaxChars: number
+): string => {
+  const exactIndex = presets.findIndex(
+    (preset) => preset.value === contextMaxChars
+  );
+  const selectedIndex =
+    exactIndex >= 0
+      ? exactIndex
+      : presets.reduce(
+          (closestIndex, preset, index) =>
+            Math.abs(preset.value - contextMaxChars) <
+            Math.abs(presets[closestIndex].value - contextMaxChars)
+              ? index
+              : closestIndex,
+          0
+        );
+  const selectedPreset = presets[selectedIndex];
+  const isFullContext =
+    selectedPreset?.value === Number.MAX_SAFE_INTEGER ||
+    selectedPreset?.label.toUpperCase() === "FULL" ||
+    selectedPreset?.label.toUpperCase() === "ALL";
+  const progress = isFullContext
+    ? 1
+    : selectedIndex / Math.max(1, presets.length - 1);
+  const meterWidth = 20;
+  const marker = Math.round(progress * meterWidth);
+  const meter = Array.from({ length: meterWidth + 1 }, (_, index) => {
+    if (index === marker) {
+      return "●";
+    }
+    return index < marker ? "━" : "─";
+  }).join("");
+  const label = currentContextLabel(presets, contextMaxChars);
+  const labelWidth = visibleWidth(label);
+  const meterPrefix = "none    ";
+  const markerColumn = meterPrefix.length + marker;
+  const labelStart = Math.max(
+    0,
+    Math.min(
+      meterPrefix.length + meter.length + 2 - labelWidth,
+      markerColumn - Math.floor((labelWidth - 1) / 2)
+    )
+  );
+  const markerLabel = `${" ".repeat(labelStart)}${label}`;
+  const description =
+    exactIndex >= 0 ? selectedPreset?.description : "Custom context limit.";
+  return `${description ?? "Custom context limit."}\n${meterPrefix}${meter}  full\n${markerLabel}`;
+};
+
+export const currentEffort = (effort: string | undefined): string =>
+  effort || DEFAULT_EFFORT_LEVEL;
+
+export const rainbowGradient = (text: string, startedAt: number): string => {
+  const frame = Math.floor(
+    (Date.now() - startedAt) / SIMPLE_MODE_GRADIENT_INTERVAL_MS
+  );
+  const shinePosition = frame % (text.length * 2);
+  return [...text]
+    .map((character, index) => {
+      const [baseRed, baseGreen, baseBlue] =
+        SIMPLE_MODE_GRADIENT_COLORS[index % SIMPLE_MODE_GRADIENT_COLORS.length];
+      const distance = Math.abs(index - shinePosition);
+      let brightness = 0;
+      if (distance === 0) {
+        brightness = 0.7;
+      } else if (distance === 1) {
+        brightness = 0.35;
+      }
+      const red = Math.round(baseRed + (255 - baseRed) * brightness);
+      const green = Math.round(baseGreen + (255 - baseGreen) * brightness);
+      const blue = Math.round(baseBlue + (255 - baseBlue) * brightness);
+      return `\x1b[38;2;${red};${green};${blue}m${character}`;
+    })
+    .join("")
+    .concat("\x1b[0m");
+};

package/src/ui/settings-items.ts

@@ -0,0 +1,323 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { SettingItem } from "@earendil-works/pi-tui";
+import { isValidAdvisorToolPolicies } from "../config/validation.js";
+import {
+  contextDescription,
+  currentContextLabel,
+  currentEffort,
+  maxCallValues,
+  numericValues,
+  settingValue,
+  TOGGLE_VALUES,
+  withCurrentValue,
+} from "./settings-formatting.js";
+import { TextSettingSubmenu } from "./text-setting-submenu.js";
+import type {
+  AdvisorSettings,
+  ContextPreset,
+  RenderRequester,
+} from "./types.js";
+
+export interface SettingsItemsOptions {
+  effortLevels: string[];
+  presets: ContextPreset[];
+  settings: AdvisorSettings;
+  theme: Theme;
+  tui: RenderRequester;
+}
+
+const toggle = (
+  id: string,
+  label: string,
+  description: string,
+  value: boolean | undefined,
+  defaultValue: boolean
+): SettingItem => ({
+  currentValue: settingValue(value, defaultValue),
+  description,
+  id,
+  label,
+  values: TOGGLE_VALUES,
+});
+
+export const createSettingsItems = ({
+  effortLevels,
+  presets,
+  settings,
+  theme,
+  tui,
+}: SettingsItemsOptions): SettingItem[] => {
+  const items: SettingItem[] = [
+    {
+      currentValue: currentContextLabel(presets, settings.contextMaxChars),
+      description: contextDescription(presets, settings.contextMaxChars),
+      id: "context",
+      label: "Context window",
+      values: presets.map((preset) => preset.label),
+    },
+    {
+      currentValue: settingValue(settings.simpleMode, false),
+      description:
+        "Keep the Advisor available on demand without automatic gates or blocks.",
+      id: "simpleMode",
+      label: "Simple mode",
+      values: TOGGLE_VALUES,
+    },
+    {
+      currentValue: settingValue(settings.alwaysOn, false),
+      description:
+        "Run the Advisor flow automatically for supported agent turns.",
+      id: "alwaysOn",
+      label: "Always on",
+      values: TOGGLE_VALUES,
+    },
+  ];
+  if (settings.simpleMode) {
+    return items;
+  }
+
+  items.push(
+    {
+      currentValue: currentEffort(settings.effort),
+      description: "Reasoning level used for Advisor calls.",
+      id: "effort",
+      label: "Advisor reasoning",
+      values: withCurrentValue(currentEffort(settings.effort), effortLevels),
+    },
+    toggle(
+      "scoutEnabled",
+      "Experimental Advisor Scout",
+      "Enable the experimental Scout before Advisor calls.",
+      settings.scoutEnabled,
+      false
+    ),
+    toggle(
+      "showUsageDetails",
+      "Show usage and cost details",
+      "Show token usage and cost details in Advisor responses.",
+      settings.showUsageDetails,
+      true
+    ),
+    toggle(
+      "showUsageFooter",
+      "Show usage in footer",
+      "Show the current Advisor usage summary in the footer.",
+      settings.showUsageFooter,
+      false
+    ),
+    toggle(
+      "planGate",
+      "Plan gate",
+      "Ask the Advisor to review implementation plans.",
+      settings.planGate,
+      true
+    ),
+    toggle(
+      "failureGate",
+      "Failure gate",
+      "Ask the Advisor to review repeated failures.",
+      settings.failureGate,
+      true
+    ),
+    toggle(
+      "completionGate",
+      "Completion gate",
+      "Ask the Advisor to review work before declaring success.",
+      settings.completionGate,
+      true
+    ),
+    toggle(
+      "collapseResponses",
+      "Collapse long responses",
+      "Collapse long Advisor responses in the transcript.",
+      settings.collapseResponses,
+      false
+    ),
+    {
+      currentValue: settings.customRule || "None",
+      description: "Add a rule that triggers Advisor involvement.",
+      id: "customRule",
+      label: "Custom invocation",
+      submenu: (_currentValue, done) =>
+        new TextSettingSubmenu({
+          description: "Enter a custom invocation rule.",
+          initial: settings.customRule || "",
+          onCancel: done,
+          onSubmit: (value) => ({ value: value.trim() }),
+          theme,
+          title: "Custom invocation",
+          tui,
+        }),
+    },
+    toggle(
+      "blockOnBlocked",
+      "Block on critical advice",
+      "Block the agent when the Advisor returns a critical decision.",
+      settings.blockOnBlocked,
+      true
+    ),
+    toggle(
+      "autoLoopGate",
+      "Automatic loop gate",
+      "Ask the Advisor to review repeated equivalent attempts.",
+      settings.autoLoopGate,
+      true
+    ),
+    {
+      currentValue: `After ${settings.loopThreshold ?? 3} repeats`,
+      description: "Number of equivalent attempts before automatic review.",
+      id: "loopThreshold",
+      label: "Loop threshold",
+      values: numericValues(
+        settings.loopThreshold ?? 3,
+        Array.from({ length: 99 }, (_, index) => index + 2)
+      ).map((value) => `After ${value} repeats`),
+    },
+    {
+      currentValue:
+        settings.maxCallsPerSession === undefined
+          ? "∞"
+          : String(settings.maxCallsPerSession),
+      description: "Limit automatic Advisor calls in one session.",
+      id: "maxCallsPerSession",
+      label: "Max Advisor calls/session",
+      values: maxCallValues(
+        settings.maxCallsPerSession === undefined
+          ? "∞"
+          : String(settings.maxCallsPerSession)
+      ),
+    },
+    toggle(
+      "sessionSummary",
+      "Session Advisor Summary",
+      "Show a local summary when the session ends.",
+      settings.sessionSummary,
+      false
+    ),
+    {
+      currentValue: settings.failureMode ?? "block-session",
+      description: "Choose what happens when an Advisor gate fails.",
+      id: "failureMode",
+      label: "Gate failure mode",
+      values: withCurrentValue(settings.failureMode ?? "block-session", [
+        "block-session",
+        "block-tool",
+        "warn-and-continue",
+      ]),
+    },
+    toggle(
+      "herdrIntegration",
+      "Herdr integration",
+      "Send Advisor activity to the optional Herdr integration.",
+      settings.herdrIntegration,
+      true
+    ),
+    {
+      currentValue: String(settings.toolResultMaxLines ?? 2000),
+      description: "Maximum lines included from a tool result.",
+      id: "toolResultMaxLines",
+      label: "Tool result lines",
+      values: numericValues(
+        settings.toolResultMaxLines ?? 2000,
+        [0, 500, 1000, 2000, 5000, 10_000]
+      ),
+    },
+    {
+      currentValue: String(settings.toolResultMaxBytes ?? 50 * 1024),
+      description: "Maximum bytes included from a tool result.",
+      id: "toolResultMaxBytes",
+      label: "Tool result bytes",
+      values: numericValues(settings.toolResultMaxBytes ?? 50 * 1024, [
+        0,
+        10 * 1024,
+        50 * 1024,
+        100 * 1024,
+        500 * 1024,
+      ]),
+    },
+    toggle(
+      "redactSecrets",
+      "Redact common secrets",
+      "Redact common credential patterns before Advisor calls.",
+      settings.redactSecrets,
+      false
+    ),
+    {
+      currentValue: settings.gitContext ?? "summary",
+      description: "How much repository context is shared with the Advisor.",
+      id: "gitContext",
+      label: "Repository context",
+      values: withCurrentValue(settings.gitContext ?? "summary", [
+        "off",
+        "summary",
+        "full",
+      ]),
+    },
+    {
+      currentValue: String(settings.gitContextMaxChars ?? 20_000),
+      description: "Maximum repository context characters included.",
+      id: "gitContextMaxChars",
+      label: "Repository context chars",
+      values: numericValues(
+        settings.gitContextMaxChars ?? 20_000,
+        [0, 5000, 10_000, 20_000, 50_000, 100_000]
+      ),
+    },
+    {
+      currentValue: Object.keys(settings.toolPolicies ?? {}).length
+        ? "Configured"
+        : "All tools: full",
+      description:
+        "Choose which tools are shared in full, summarized, or excluded.",
+      id: "toolPolicies",
+      label: "Tool disclosure policies",
+      submenu: (_currentValue, done) =>
+        new TextSettingSubmenu({
+          description:
+            'Enter a JSON object with "full", "summary", or "exclude" values.',
+          initial: JSON.stringify(settings.toolPolicies ?? {}),
+          onCancel: done,
+          onSubmit: (value) => {
+            let parsed: unknown;
+            try {
+              parsed = JSON.parse(value || "{}");
+            } catch {
+              return { error: "Enter a valid JSON object." };
+            }
+            if (!isValidAdvisorToolPolicies(parsed)) {
+              return {
+                error:
+                  "Use non-empty tool names with full, summary, or exclude values.",
+              };
+            }
+            return { value: JSON.stringify(parsed) };
+          },
+          theme,
+          title: "Tool disclosure policies",
+          tui,
+        }),
+    },
+    toggle(
+      "trackedFileContent",
+      "Tracked file content",
+      "Allow tracked file contents to be sent with Advisor context.",
+      settings.trackedFileContent,
+      false
+    ),
+    toggle(
+      "untrackedContent",
+      "Untracked file content",
+      "Allow untracked file contents to be sent with Advisor context.",
+      settings.untrackedContent,
+      false
+    ),
+    toggle(
+      "outcomeLogging",
+      "Outcome logging (global)",
+      "Allow anonymized Advisor outcomes to be logged globally.",
+      settings.outcomeLogging,
+      false
+    )
+  );
+  return items;
+};

package/src/ui/settings-list-adapter.ts

@@ -0,0 +1,103 @@
+import {
+  type Component,
+  type Focusable,
+  type Input,
+  Key,
+  matchesKey,
+  type SettingItem,
+  type SettingsList,
+} from "@earendil-works/pi-tui";
+
+interface SettingsListPrivateFields {
+  filteredItems: SettingItem[];
+  searchInput?: Input;
+  selectedIndex: number;
+  submenuComponent?: Component | null;
+}
+
+/**
+ * Contains the narrow compatibility access needed for pi-tui's SettingsList.
+ * No other UI module should depend on its private fields.
+ */
+export class SettingsListAdapter {
+  private readonly list: SettingsList;
+
+  constructor(list: SettingsList) {
+    this.list = list;
+  }
+
+  invalidate(): void {
+    this.list.invalidate();
+  }
+
+  render(width: number): string[] {
+    return this.list.render(width);
+  }
+
+  handleInput(keyData: string): void {
+    this.list.handleInput(keyData);
+  }
+
+  /** Compatibility-only view for existing component integration seams. */
+  get submenuComponent(): Component | null | undefined {
+    return this.privateFields().submenuComponent;
+  }
+
+  setFocused(value: boolean): void {
+    const fields = this.privateFields();
+    const submenu = fields.submenuComponent as Focusable | undefined;
+    if (submenu) {
+      submenu.focused = value;
+    }
+  }
+
+  setSelectedId(items: SettingItem[], selectedId: string): void {
+    const selectedIndex = items.findIndex((item) => item.id === selectedId);
+    if (selectedIndex >= 0) {
+      this.privateFields().selectedIndex = selectedIndex;
+    }
+  }
+
+  changeWithArrow(
+    keyData: string,
+    onChange: (id: string, value: string) => void
+  ): boolean {
+    let direction = 0;
+    if (matchesKey(keyData, Key.left) || keyData === "\u001b[D") {
+      direction = -1;
+    } else if (matchesKey(keyData, Key.right) || keyData === "\u001b[C") {
+      direction = 1;
+    }
+    if (direction === 0) {
+      return false;
+    }
+
+    const fields = this.privateFields();
+    if (fields.submenuComponent || fields.searchInput?.getValue()) {
+      return false;
+    }
+    const item = fields.filteredItems[fields.selectedIndex];
+    if (!item?.values?.length) {
+      return false;
+    }
+    const currentIndex = item.values.indexOf(item.currentValue);
+    let nextIndex: number;
+    if (currentIndex === -1) {
+      nextIndex = direction > 0 ? 0 : item.values.length - 1;
+    } else {
+      nextIndex =
+        (currentIndex + direction + item.values.length) % item.values.length;
+    }
+    const nextValue = item.values[nextIndex];
+    if (nextValue === undefined) {
+      return false;
+    }
+    item.currentValue = nextValue;
+    onChange(item.id, nextValue);
+    return true;
+  }
+
+  private privateFields(): SettingsListPrivateFields {
+    return this.list as unknown as SettingsListPrivateFields;
+  }
+}

package/src/ui/settings-mutations.ts

@@ -0,0 +1,80 @@
+import type { AdvisorSettings, ContextPreset, SettingValue } from "./types.js";
+
+export const BOOLEAN_SETTING_IDS = new Set([
+  "scoutEnabled",
+  "showUsageDetails",
+  "showUsageFooter",
+  "planGate",
+  "failureGate",
+  "completionGate",
+  "collapseResponses",
+  "blockOnBlocked",
+  "autoLoopGate",
+  "sessionSummary",
+  "herdrIntegration",
+  "redactSecrets",
+  "trackedFileContent",
+  "untrackedContent",
+  "outcomeLogging",
+]);
+
+export const mutateAdvisorSettings = (
+  settings: AdvisorSettings,
+  id: string,
+  value: string,
+  presets: ContextPreset[]
+): void => {
+  switch (id) {
+    case "context":
+      settings.contextMaxChars =
+        presets.find((preset) => preset.label === value)?.value ??
+        settings.contextMaxChars;
+      break;
+    case "simpleMode":
+      settings.simpleMode = value === "On";
+      break;
+    case "alwaysOn":
+      settings.alwaysOn = value === "On";
+      break;
+    case "effort":
+      settings.effort = value;
+      break;
+    case "customRule":
+      settings.customRule = value.trim() || undefined;
+      break;
+    case "toolPolicies":
+      settings.toolPolicies = JSON.parse(
+        value
+      ) as AdvisorSettings["toolPolicies"];
+      break;
+    case "loopThreshold":
+      settings.loopThreshold = Number(
+        value.replace("After ", "").replace(" repeats", "")
+      );
+      break;
+    case "maxCallsPerSession":
+      settings.maxCallsPerSession = value === "∞" ? undefined : Number(value);
+      break;
+    case "failureMode":
+      settings.failureMode = value as AdvisorSettings["failureMode"];
+      break;
+    case "gitContext":
+      settings.gitContext = value as AdvisorSettings["gitContext"];
+      break;
+    case "toolResultMaxLines":
+      settings.toolResultMaxLines = Number(value);
+      break;
+    case "toolResultMaxBytes":
+      settings.toolResultMaxBytes = Number(value);
+      break;
+    case "gitContextMaxChars":
+      settings.gitContextMaxChars = Number(value);
+      break;
+    default:
+      if (BOOLEAN_SETTING_IDS.has(id)) {
+        (settings as unknown as Record<string, SettingValue | boolean>)[id] =
+          value === "On";
+      }
+      break;
+  }
+};