pi-subagents-lite 1.4.1 → 1.4.3

package/src/ui/menu/menu-model-settings.ts

@@ -10,10 +10,11 @@
  */
 
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { SettingsList, SelectList, type SettingItem } from "@earendil-works/pi-tui";
+import { SettingsList, type SettingItem } from "@earendil-works/pi-tui";
 import { getAgentConfig, getAllTypes } from "../../agents/agent-types.js";
+import type { Theme } from "../types.js";
 import { CONFIG_AGENT_NON_MODEL_KEYS } from "../../config/types.js";
-import { buildSettingsListTheme, buildSelectListTheme, createDelegatingComponent } from "./helpers.js";
+import { buildSettingsListTheme, createSearchableSelect } from "./helpers.js";
 import { createModelSelectSubmenu } from "./submenus/model-select.js";
 import { createConfirmSubmenu } from "./submenus/confirm.js";
 import { SettingsListWrapper } from "./wrappers/settings-list.js";
@@ -24,7 +25,7 @@ export async function showModelSettingsMenu(
   modelOptions: string[],
 ): Promise<void> {
   // Build menu items from current store state.
-  const buildItems = (store: ReturnType<typeof getStore>, theme: any): SettingItem[] => {
+  const buildItems = (store: ReturnType<typeof getStore>, theme: Theme): SettingItem[] => {
     const items: SettingItem[] = [];
     
     // Shared onSelect for model override submenus: applies session/permanent/clear
@@ -71,6 +72,7 @@ export async function showModelSettingsMenu(
       id: "defaultModel",
       label: "Global default model",
       currentValue: globalDisplayValue,
+      description: "Model used when no per-type override or frontmatter model applies.",
       submenu: createModelSelectSubmenu({
         modelOptions,
         showClear: false,
@@ -105,6 +107,7 @@ export async function showModelSettingsMenu(
         id: `type:${typeName}`,
         label: typeName,
         currentValue: `${frontmatterHint}${displayModel}`,
+        description: `Per-type model override for the ${typeName} agent type.`,
         submenu: createModelSelectSubmenu({
           modelOptions,
           showClear: hasPerm,
@@ -121,26 +124,26 @@ export async function showModelSettingsMenu(
         id: "overrideType",
         label: "Override another type...",
         currentValue: "",
-        submenu: (_currentValue, subDone) => {
-          const typeNames = nonOverridden.map(e => ({ value: e.typeName, label: e.typeName }));
-          const typeList = new SelectList(typeNames, 10, buildSelectListTheme(theme));
-          const delegator = createDelegatingComponent(typeList);
-
-          typeList.onSelect = (item) => {
-            const entry = nonOverridden.find(e => e.typeName === item.value)!;
-            // Delegate to createModelSelectSubmenu for the 2-step model flow
-            const modelSubmenu = createModelSelectSubmenu({
-              modelOptions,
-              showClear: false,
-              theme,
-              onSelect: modelOverrideOnSelect(entry.typeName, entry.typeName),
-            });
-            delegator.setActive(modelSubmenu(entry.effectiveModel, subDone));
-          };
-          typeList.onCancel = () => subDone();
-
-          return delegator;
-        },
+        description: "Add a model override for an agent type that currently inherits.",
+        submenu: (_currentValue, subDone) =>
+          createSearchableSelect(
+            nonOverridden.map(e => ({ value: e.typeName, label: e.typeName })),
+            {
+              onSelect: (typeName) => {
+                const entry = nonOverridden.find(e => e.typeName === typeName)!;
+                // Delegate to createModelSelectSubmenu for the 2-step model flow
+                const modelSubmenu = createModelSelectSubmenu({
+                  modelOptions,
+                  showClear: false,
+                  theme,
+                  onSelect: modelOverrideOnSelect(entry.typeName, entry.typeName),
+                });
+                return modelSubmenu(entry.effectiveModel, subDone);
+              },
+              onCancel: () => subDone(),
+            },
+            theme,
+          ),
       });
     }
 
@@ -153,6 +156,7 @@ export async function showModelSettingsMenu(
         id: "clearSession",
         label: "Clear session overrides",
         currentValue: "",
+        description: "Discard model overrides set only for this session.",
         submenu: createConfirmSubmenu({
           message: "Clear all session overrides?",
           theme,
@@ -169,6 +173,7 @@ export async function showModelSettingsMenu(
       id: "clearAll",
       label: "Clear all overrides",
       currentValue: "",
+      description: "Discard all model overrides (config and session).",
       submenu: createConfirmSubmenu({
         message: "Clear all model overrides?",
         theme,

package/src/ui/menu/menu-running-agents.ts

@@ -22,6 +22,7 @@ import { getDisplayName, truncateDesc } from "../format.js";
 import { buildSnapshotMarkdown } from "../../prompt/context.js";
 import { buildSelectListTheme, createDelegatingComponent } from "./helpers.js";
 import { getManager, getStore } from "../../shell.js";
+import type { Theme } from "../types.js";
 
 /**
  * Show a ResultViewer for an agent's result, error, or snapshot.
@@ -73,7 +74,7 @@ async function showResultViewer(
 export function buildAgentActionsList(
   ctx: ExtensionCommandContext,
   record: AgentRecord,
-  theme: any,
+  theme: Theme,
   done: () => void,
   setActive: (c: import("@earendil-works/pi-tui").Component) => void,
   onClose: () => void,

package/src/ui/menu/menu-spawn-options.ts

@@ -27,6 +27,7 @@ export async function showSpawnOptionsMenu(ctx: ExtensionCommandContext): Promis
       label: "Force background",
       currentValue: store.agent.forceBackground ? "ON" : "OFF",
       values: ["ON", "OFF"],
+      description: "Spawn every agent in the background by default (no foreground wait).",
     },
     {
       id: "graceTurns",
@@ -36,6 +37,7 @@ export async function showSpawnOptionsMenu(ctx: ExtensionCommandContext): Promis
         store.mutate.agent.setGraceTurns(parsed);
         ctx.ui.notify(`Grace turns set to ${parsed}`, "info");
       }),
+      description: "Extra turns after the soft turn limit before a hard abort.",
     },
     {
       id: "defaultMaxTurns",
@@ -48,18 +50,21 @@ export async function showSpawnOptionsMenu(ctx: ExtensionCommandContext): Promis
         store.mutate.agent.setDefaultMaxTurns(undefined);
         ctx.ui.notify("Default max turns cleared", "info");
       }),
+      description: "Soft turn limit; agent is steered here, then hard-aborts after grace turns. Blank = unlimited.",
     },
     {
       id: "defaultThinking",
       label: "Default thinking level",
       currentValue: store.agent.defaultThinking ?? "inherit",
       values: ["off", "minimal", "low", "medium", "high", "xhigh", "inherit"],
+      description: "Thinking level applied when agent frontmatter omits one.",
     },
     {
       id: "disableDefaultAgents",
       label: "Disable default agents",
       currentValue: store.agent.disableDefaultAgents ? "ON" : "OFF",
       values: ["ON", "OFF"],
+      description: "Skip auto-loading built-in agent types next session; only .pi/agents types load.",
     },
   ];
 

package/src/ui/menu/menu-spawn-wizard.ts

@@ -11,9 +11,10 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { SettingsList, SelectList, type SettingItem } from "@earendil-works/pi-tui";
 import type { ThinkingLevel } from "../../types.js";
+import type { Theme } from "../types.js";
 import { getAgentConfig, getAvailableTypes, resolveType, discoverNewAgents } from "../../agents/agent-types.js";
-import { findModelInRegistry } from "../../utils.js";
-import { buildSettingsListTheme, buildSelectListTheme } from "./helpers.js";
+import { findModelInRegistry, VALID_THINKING_LEVELS } from "../../utils.js";
+import { buildSettingsListTheme, buildSelectListTheme, createSearchableSelect } from "./helpers.js";
 import { DEFAULT_GRACE_TURNS } from "../../config/config-io.js";
 import { createModelSelectSubmenu } from "./submenus/model-select.js";
 import { createNumericSubmenu, createInputSubmenu } from "./submenus/numeric-input.js";
@@ -120,7 +121,6 @@ async function isInGitRepo(cwd: string): Promise<boolean> {
 // Spawn agent wizard
 // ============================================================================
 
-const THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"];
 
 /**
  * Show the spawn agent flow as a multi-step wizard:
@@ -146,6 +146,7 @@ export async function showSpawnAgentMenu(
         id: t,
         label: t,
         currentValue: t,
+        description: getAgentConfig(t)?.description ?? "Agent type",
         submenu: (_v: string, _subDone: (value?: string) => void) => {
           done(t);
           return undefined as any;
@@ -214,6 +215,7 @@ export async function showSpawnAgentMenu(
         id: "spawn",
         label: "Spawn",
         currentValue: "",
+        description: "Spawn the agent with current settings",
         submenu: (_v, done) => {
           const gtItem = items.find(i => i.id === "graceTurns");
           const bgItem = items.find(i => i.id === "background");
@@ -304,6 +306,7 @@ export async function showSpawnAgentMenu(
         id: "model",
         label: "Model",
         currentValue: displayModel,
+        description: "Override the default model for this agent",
         submenu: createModelSelectSubmenu({
           modelOptions,
           showClear: false,
@@ -317,6 +320,7 @@ export async function showSpawnAgentMenu(
         id: "background",
         label: "Background",
         currentValue: currentBackground ? "ON" : "OFF",
+        description: "Run the agent in the background",
         values: ["ON", "OFF"],
       },
       ...(inGitRepo
@@ -324,28 +328,33 @@ export async function showSpawnAgentMenu(
             id: "worktree",
             label: "Worktree",
             currentValue: currentWorktreeLabel,
+            description: "Run in a linked git worktree instead of parent cwd",
             submenu: (_v: string, done: (v?: string) => void) => {
               const pickerItems = [
                 { value: "Inherits parent cwd", label: "Inherits parent cwd" },
                 ...worktrees.map(wt => {
                   const branchLabel = wt.isDetached ? "detached" : (wt.branch ?? "detached");
                   const truncPath = truncatePath(wt.path);
-                  return { value: wt.path, label: `${branchLabel}  ·  ${truncPath}` };
+                  return { value: wt.path, label: truncPath, provider: branchLabel };
                 }),
               ];
-              const list = new SelectList(pickerItems, 10, buildSelectListTheme(theme));
-              list.onSelect = (item) => {
-                if (item.value === "Inherits parent cwd") {
-                  currentWorktreePath = undefined;
-                  done("Inherits parent cwd");
-                } else {
-                  const wt = worktrees.find(w => w.path === item.value);
-                  currentWorktreePath = wt?.path;
-                  done(wt?.branch ?? "detached");
-                }
-              };
-              list.onCancel = () => done();
-              return list;
+              return createSearchableSelect(
+                pickerItems,
+                {
+                  onSelect: (value) => {
+                    if (value === "Inherits parent cwd") {
+                      currentWorktreePath = undefined;
+                      done("Inherits parent cwd");
+                    } else {
+                      const wt = worktrees.find(w => w.path === value);
+                      currentWorktreePath = wt?.path;
+                      done(wt?.branch ?? "detached");
+                    }
+                  },
+                  onCancel: () => done(),
+                },
+                theme,
+              );
             },
           } as SettingItem]
         : []),
@@ -353,24 +362,28 @@ export async function showSpawnAgentMenu(
         id: "thinkingLevel",
         label: "Thinking level",
         currentValue: currentThinking ?? "inherit",
-        values: [...THINKING_LEVELS, "inherit"],
+        description: "Set the reasoning effort level",
+        values: [...VALID_THINKING_LEVELS, "inherit"],
       },
       {
         id: "maxTokens",
         label: "Max tokens",
         currentValue: fmtNum(currentMaxTokens),
+        description: "Maximum tokens the agent can consume",
         submenu: createNumericSubmenu(ctx, (parsed) => { currentMaxTokens = parsed; }, () => { currentMaxTokens = undefined; }),
       },
       {
         id: "maxTurns",
         label: "Max turns",
         currentValue: fmtNum(currentMaxTurns),
+        description: "Maximum conversation turns before hard stop",
         submenu: createNumericSubmenu(ctx, (parsed) => { currentMaxTurns = parsed; }, () => { currentMaxTurns = undefined; }),
       },
       {
         id: "graceTurns",
         label: "Grace turns",
         currentValue: String(currentGraceTurns),
+        description: "Extra turns after soft limit before abort",
         submenu: createNumericSubmenu(ctx, { min: 0, default: DEFAULT_GRACE_TURNS }, (parsed) => { currentGraceTurns = parsed; }),
       },
       { id: "__sep__", label: " ", currentValue: "" },
@@ -378,12 +391,14 @@ export async function showSpawnAgentMenu(
         id: "description",
         label: "Description",
         currentValue: currentDescription,
+        description: "Short label shown in the agents list",
         submenu: createInputSubmenu(ctx),
       },
       {
         id: "prompt",
         label: "Prompt",
         currentValue: prompt,
+        description: "The user message sent to the agent",
         submenu: createInputSubmenu(ctx, { required: true }),
       }
     ];
@@ -391,7 +406,7 @@ export async function showSpawnAgentMenu(
     return items;
   };
 
-  let theme: any;
+  let theme: Theme;
   let doneRef: () => void;
 
   await ctx.ui.custom((_tui, t, _kb, done) => {

package/src/ui/menu/menu-system-prompt.ts

@@ -17,7 +17,7 @@ import { buildSettingsListTheme } from "./helpers.js";
 import { SettingsListWrapper } from "./wrappers/settings-list.js";
 import type { SystemPromptMode } from "../../agents/types.js";
 import { getStore } from "../../shell.js";
-import { CUSTOM_PROMPT_PATH } from "../../agents/agent-runner.js";
+import { CUSTOM_PROMPT_PATH } from "../../config/config-io.js";
 
 export async function showSystemPromptMenu(ctx: ExtensionCommandContext): Promise<void> {
   const store = getStore();
@@ -29,6 +29,7 @@ export async function showSystemPromptMenu(ctx: ExtensionCommandContext): Promis
         label: "System prompt mode",
         currentValue: store.agent.systemPromptMode,
         values: ["replace", "inherit", "custom"],
+        description: "How the subagent system prompt is built: replace, inherit, or custom.",
       },
     ];
 
@@ -39,6 +40,7 @@ export async function showSystemPromptMenu(ctx: ExtensionCommandContext): Promis
         label: "Create prompt file",
         currentValue: CUSTOM_PROMPT_PATH,
         values: ["Create"],
+        description: `Create ${CUSTOM_PROMPT_PATH} with a starter template for custom mode.`,
       });
     }
 
@@ -48,24 +50,26 @@ export async function showSystemPromptMenu(ctx: ExtensionCommandContext): Promis
         label: "Include AGENTS.md",
         currentValue: store.agent.includeContextFiles ? "ON" : "OFF",
         values: ["ON", "OFF"],
+        description: "Load project and ~/.pi/agent AGENTS.md as shared <project_context>.",
       },
       {
         id: "loadSkillsImplicitly",
         label: "Load skills implicitly",
         currentValue: store.agent.loadSkillsImplicitly ? "ON" : "OFF",
         values: ["ON", "OFF"],
+        description: "Give new agents all skills when frontmatter omits the field.",
       },
       {
         id: "loadExtensionsImplicitly",
         label: "Load extensions implicitly",
         currentValue: store.agent.loadExtensionsImplicitly ? "ON" : "OFF",
         values: ["ON", "OFF"],
+        description: "Give new agents all extensions when frontmatter omits the field.",
       },
     );
 
     return items;
   };
-
   let items = buildItems();
   let rebuild: ((newItems: SettingItem[]) => void) | null = null;
 

package/src/ui/menu/menu-widget-settings.ts

@@ -54,15 +54,29 @@ export async function showWidgetSettingsMenu(ctx: ExtensionCommandContext): Prom
         store.mutate.widget.setShortcut(newValue === "ON");
         ctx.ui.notify(`Ctrl+o shortcut ${newValue}`, "info");
         break;
+      case "thinkingBuffer":
+        store.mutate.agent.setOutputThinkingBufferSize(newValue === "OFF" ? 0 : Number(newValue));
+        ctx.ui.notify(`Thinking buffer ${newValue}`, "info");
+        break;
     }
   };
 
   await ctx.ui.custom((_tui, theme, _kb, done) => {
+    const statDescriptions: Record<string, string> = {
+      showTools: "Show tool count (🛠 ) in the widget.",
+      showTurns: "Show turn count (⟳ ) in the widget.",
+      showInput: "Show input tokens (↑) in the widget.",
+      showOutput: "Show output tokens (↓) in the widget.",
+      showContext: "Show context-fill percent (%) in the widget.",
+      showCost: "Show dollar cost ($) in the widget.",
+      showTime: "Show elapsed time in the widget.",
+    };
     const statItems: SettingItem[] = [...statConfig.entries()].map(([id, cfg]) => ({
       id,
       label: cfg.label,
       currentValue: cfg.get() ? "ON" : "OFF",
       values: ["ON", "OFF"],
+      description: statDescriptions[id],
     }));
 
     const items: SettingItem[] = [
@@ -71,6 +85,7 @@ export async function showWidgetSettingsMenu(ctx: ExtensionCommandContext): Prom
         label: "Force compact mode",
         currentValue: store.agent.widgetCompact ? "ON" : "OFF",
         values: ["ON", "OFF"],
+        description: "Force compact widget mode regardless of ctrl+o state.",
       },
       {
         id: "maxLines",
@@ -80,6 +95,7 @@ export async function showWidgetSettingsMenu(ctx: ExtensionCommandContext): Prom
           store.mutate.widget.setMaxLines(parsed);
           ctx.ui.notify(`Max lines (full) set to ${parsed}`, "info");
         }),
+        description: "Max body lines in full widget mode (excluding heading).",
       },
       {
         id: "descLengthFull",
@@ -89,6 +105,7 @@ export async function showWidgetSettingsMenu(ctx: ExtensionCommandContext): Prom
           store.mutate.widget.setDescLengthFull(parsed);
           ctx.ui.notify(`Description length (full) set to ${parsed}`, "info");
         }),
+        description: "Max description length shown in full widget mode.",
       },
       {
         id: "maxLinesCompact",
@@ -98,6 +115,7 @@ export async function showWidgetSettingsMenu(ctx: ExtensionCommandContext): Prom
           store.mutate.widget.setMaxLinesCompact(parsed);
           ctx.ui.notify(`Max lines (compact) set to ${parsed}`, "info");
         }),
+        description: "Max body lines in compact widget mode.",
       },
       {
         id: "descLengthCompact",
@@ -107,12 +125,21 @@ export async function showWidgetSettingsMenu(ctx: ExtensionCommandContext): Prom
           store.mutate.widget.setDescLengthCompact(parsed);
           ctx.ui.notify(`Description length (compact) set to ${parsed}`, "info");
         }),
+        description: "Max description length shown in compact widget mode.",
       },
       {
         id: "shortcut",
         label: "Ctrl+o shortcut",
         currentValue: store.agent.widgetShortcut ? "ON" : "OFF",
         values: ["ON", "OFF"],
+        description: "When ON, ctrl+o toggles compact mode; when OFF, compact is set manually.",
+      },
+      {
+        id: "thinkingBuffer",
+        label: "Log file thinking buffer",
+        currentValue: store.agent.outputThinkingBufferSize === 0 ? "OFF" : String(store.agent.outputThinkingBufferSize),
+        values: ["OFF", "80", "200", "500", "1000"],
+        description: "Controls log file thinking buffering in chars. OFF = only at turn end, 80 = flush after 80 chars.",
       },
       { id: "__sep__", label: " ", currentValue: "" },
       {
@@ -121,6 +148,7 @@ export async function showWidgetSettingsMenu(ctx: ExtensionCommandContext): Prom
         currentValue: "→",
         submenu: (_currentValue, done2) =>
           new SettingsList(statItems, 7, buildSettingsListTheme(theme), onChange, () => done2()),
+        description: "Toggle which usage stats appear in the widget.",
       },
     ];
 

package/src/ui/menu/submenus/confirm.ts

@@ -6,13 +6,14 @@
  */
 
 import { SelectList, type Component } from "@earendil-works/pi-tui";
+import type { Theme } from "../../types.js";
 import { buildSelectListTheme } from "../helpers.js";
 
 export interface ConfirmSubmenuOptions {
   /** Message shown to the user */
   message: string;
   /** Theme from pi-coding-agent (fg, bold, italic) */
-  theme: any;
+  theme: Theme;
   /** Called when user confirms (selects Yes) */
   onConfirm: () => void;
 }

package/src/ui/menu/submenus/model-select.ts

@@ -2,19 +2,20 @@
  * model-select-submenu.ts — 2-step model override submenu.
  *
  * Step 1: SelectList with override mode (session/permanent/clear)
- * Step 2 (if session/permanent): ModelSelectorDialog for model selection
+ * Step 2 (if session/permanent): SearchableSelectDialog for model selection
  *
  * The submenu factory must be created inside ctx.ui.custom to capture the theme.
  */
 
 import { SelectList, type Component } from "@earendil-works/pi-tui";
-import { ModelSelectorDialog, type ModelOption } from "../../../models/model-selector.js";
+import type { Theme } from "../../types.js";
+import { SearchableSelectDialog, type SelectOption } from "../../../ui/searchable-select.js";
 import { buildModelOptions, buildSelectListTheme, createDelegatingComponent } from "../helpers.js";
 
 export interface ModelSelectSubmenuOptions {
   modelOptions: string[];
   showClear: boolean;
-  theme: any; // Theme from pi-coding-agent (fg, bold, italic)
+  theme: Theme;
   onSelect: (mode: "session" | "permanent" | "clear", model: string | null) => void;
 }
 
@@ -52,7 +53,7 @@ export function createModelSelectSubmenu(
     modeList.onCancel = () => done();
 
     const modelOpts = buildModelOptions(options.modelOptions);
-    const modelSelector = new ModelSelectorDialog(
+    const modelSelector = new SearchableSelectDialog(
       modelOpts,
       _currentValue === "(inherits parent)" ? null : _currentValue,
       {