pi-subagents-lite 1.2.0 → 1.4.0

package/src/types.ts

@@ -2,50 +2,32 @@
  * Type definitions for the subagent system.
  */
 
+import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
-import type { LifetimeUsage } from "./usage.js";
+import type { AgentOutputLog } from "./agents/output-file.js";
+import type { LifetimeUsage } from "./agents/usage.js";
+import type { SubagentType, AgentInvocation } from "./agents/types.js";
 
 /** Thinking level for agent models. */
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
-/** Agent type: any string name (built-in defaults or user-defined). */
-export type SubagentType = string;
+/** Tool activity event: start/end of a tool invocation. */
+export interface ToolActivity {
+  type: "start" | "end";
+  toolName: string;
+}
 
-/** Unified agent configuration — used for both default and user-defined agents. */
-export interface AgentConfig {
-  name: string;
-  displayName?: string;
-  description: string;
-  /** Tools to register with the session (controls availability, not LLM visibility). */
-  registeredTools?: string[];
-  /**
-   * Controls which tool schemas the LLM sees. Can reference built-in tools
-   * and extension tools. true = all, string[] = listed, false = none.
-   * Supports ext/* syntax to include all tools from an extension.
-   * Mutually exclusive with excludeTools.
-   */
-  tools?: true | string[] | false;
-  /** Tool blacklist — all tools except these are visible. Mutually exclusive with tools (when tools is string[]). */
-  excludeTools?: string[];
-  /** true = inherit all, string[] = only listed, false = none. Mutually exclusive with excludeExtensions. */
-  extensions: true | string[] | false;
-  /** Extension blacklist — all extensions except these load. Mutually exclusive with extensions (when extensions is string[]). */
-  excludeExtensions?: string[];
-  /** Whitelist of allowed skills (metadata only in system prompt). true = all, string[] = listed, false = none */
-  skills: true | string[] | false;
-  /** Skills to preload with full content into system prompt. string[] = listed, false/undefined = none */
-  preloadSkills?: string[] | false;
-  model?: string;
-  thinking?: ThinkingLevel;
+/**
+ * Resolved model + run-limit tunables shared by every spawn/run shape
+ * (RunOptions, SpawnOptions, SpawnIntent). Add a tunable here once and it
+ * flows through the whole chain.
+ */
+export interface RunTunables {
+  model?: Model<any>;
   maxTurns?: number;
-  systemPrompt: string;
-
-  /** true = this is an embedded default agent (informational) */
-  isDefault?: boolean;
-  /** true = agent is hidden from the schema enum but can still be called by name. */
-  hidden?: boolean;
-  /** Where this agent was loaded from */
-  source?: "project" | "global";
+  maxTokens?: number;
+  thinkingLevel?: ThinkingLevel;
+  graceTurns?: number;
 }
 
 export interface AgentRecord {
@@ -62,46 +44,40 @@ export interface AgentRecord {
   stats: AgentAccumulatedStats;
 }
 
-export interface AgentInvocation {
-  /** Short display name, e.g. "haiku" — only set when different from parent. */
-  modelName?: string;
-  thinking?: ThinkingLevel;
-  maxTurns?: number;
-  runInBackground?: boolean;
-}
-
 export interface EnvInfo {
   isGitRepo: boolean;
   branch: string | null;
   platform: string;
 }
 
-/** How many characters of agent ID to show in display. */
-export const SHORT_ID_LENGTH = 8;
+/**
+ * Streaming/callback surface shared by RunOptions and SpawnOptions.
+ * Bridges agent-runner events to record tracking and live-view updates.
+ */
+export interface RunCallbacks {
+  onToolActivity?: (activity: ToolActivity) => void;
+  onTextDelta?: (delta: string, fullText: string) => void;
+  onSessionCreated?: (session: AgentSession) => void;
+  onTurnEnd?: (turnCount: number) => void;
+  onAssistantUsage?: (usage: LifetimeUsage) => void;
+  onCompaction?: (info: CompactionInfo) => void;
+}
 
 /**
- * Theme for terminal rendering — used by format.ts, renderer.ts, and UI widgets.
- * Defined here (not in ui/agent-widget.ts) so non-UI modules can import it
- * without depending on the UI layer.
+ * Coordinator-side spawn config shared by SpawnOptions and SpawnIntent.
+ * The resolved run params that both the manager and coordinator agree on;
+ * extends RunTunables with display/identity fields.
  */
-export type Theme = {
-  fg(color: string, text: string): string;
-  bg(color: string, text: string): string;
-  bold(text: string): string;
-  italic?: (text: string) => string;
-};
-
-/** Non-model keys in config.agent — preserved when clearing all overrides. */
-export const CONFIG_AGENT_NON_MODEL_KEYS = [
-  "default",
-  "forceBackground",
-  "graceTurns",
-  "showCost",
-  "widgetMaxLines",
-  "widgetMaxLinesCompact",
-  "widgetCompact",
-  "widgetShortcut",
-];
+export interface SpawnConfig extends RunTunables {
+  description: string;
+  modelKey?: string;
+  worktreePath?: string;
+  worktreeLabel?: string;
+  invocation?: AgentInvocation;
+}
+
+/** How many characters of agent ID to show in display. */
+export const SHORT_ID_LENGTH = 8;
 
 /** Reason for a context compaction event. */
 export type CompactionReason = "manual" | "threshold" | "overflow";
@@ -117,7 +93,7 @@ export interface CompactionInfo {
 // ---------------------------------------------------------------------------
 
 /** Possible agent lifecycle statuses. */
-export type AgentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+export type AgentStatus = "queued" | "running" | "completed" | "turn_limited" | "aborted" | "stopped" | "error";
 
 /**
  * Lifecycle state: when the agent started, completed, and its current status.
@@ -158,8 +134,8 @@ export interface AgentExecutionState {
   promise?: Promise<string>;
   /** Steering messages queued before the session was ready. */
   pendingSteers?: string[];
-  /** Cleanup function for the output file stream subscription. */
-  outputCleanup?: () => void;
+  /** Lifecycle wrapper for the output file stream. */
+  outputLog?: AgentOutputLog;
 }
 
 /**

package/src/ui/agent-widget.ts

@@ -3,19 +3,19 @@
  */
 
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import type { AgentManager } from "../agent-manager.js";
-import type { AgentRecord, Theme } from "../types.js";
+import type { AgentManager } from "../agents/agent-manager.js";
+import type { AgentRecord } from "../types.js";
+import type { Theme } from "./types.js";
 import {
   formatCost,
   getLifetimeTotal,
   getSessionContextPercent,
-  type LifetimeUsage,
-  type SessionLike,
-} from "../usage.js";
-import { formatMs, buildStatsParts, getDisplayName } from "../format.js";
+} from "../agents/usage.js";
+import { formatMs, buildStatsParts, getDisplayName, truncateDesc, type StatsVisibility } from "./format.js";
+import type { LiveView } from "../spawn/spawn-coordinator.js";
 
 // Re-export Theme so existing consumers (model-selector, result-viewer) don't break
-export type { Theme } from "../types.js";
+export type { Theme } from "./types.js";
 
 // ---- Constants ----
 
@@ -26,7 +26,7 @@ const DEFAULT_MAX_WIDGET_LINES = 12;
 const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
 /** Non-success statuses — used for linger behavior and icon rendering. */
-const ERROR_STATUSES = new Set(["error", "aborted", "steered", "stopped"]);
+const ERROR_STATUSES = new Set(["error", "aborted", "turn_limited", "stopped"]);
 
 /** Tree-drawing connectors used in the widget header/continuation lines. */
 const BRANCH = "├─";
@@ -83,22 +83,9 @@ interface RenderBlock {
   continuations: string[];
 }
 
-/** Per-agent live activity state. */
-export interface AgentActivity {
-  activeTools: Map<string, string>;
-  toolUses: number;
-  responseText: string;
-  session?: SessionLike;
-  /** Current turn count. */
-  turnCount: number;
-  /** Effective max turns for this agent (undefined = unlimited). */
-  maxTurns?: number;
-  /** Lifetime usage breakdown — see LifetimeUsage docs. */
-  lifetimeUsage: LifetimeUsage;
-}
-
 // ---- Re-exports from format.ts (backward compatibility) ----
-export { formatMs, buildStatsParts, getDisplayName } from "../format.js";
+export { formatMs, buildStatsParts, getDisplayName, type StatsVisibility } from "./format.js";
+export type { LiveView as AgentActivity } from "../spawn/spawn-coordinator.js";
 
 // ---- Widget-internal helpers ----
 
@@ -161,6 +148,9 @@ export class AgentWidget {
   /** Whether to show cost in stats and status bar. */
   private showCost = false;
 
+  /** Stats visibility flags. Controls which stats appear in the stats line. */
+  private statsVisibility: StatsVisibility = {};
+
   /** Whether the widget callback is currently registered with the TUI. */
   private widgetRegistered = false;
   /** Cached TUI reference from widget factory callback, used for requestRender(). */
@@ -185,9 +175,15 @@ export class AgentWidget {
   /** Maximum lines for compact mode. */
   private maxLinesCompact = Math.floor(DEFAULT_MAX_WIDGET_LINES / 2);
 
+  /** Max description length in full mode. */
+  private descLengthFull = 50;
+
+  /** Max description length in compact mode. */
+  private descLengthCompact = 30;
+
   constructor(
     private manager: AgentManager,
-    private agentActivity: Map<string, AgentActivity>,
+    private getLiveView: (id: string) => LiveView | undefined,
   ) {}
 
   /** Set whether to show cost in stats and status bar. */
@@ -195,6 +191,11 @@ export class AgentWidget {
     this.showCost = enabled;
   }
 
+  /** Set stats visibility flags. */
+  setStatsVisibility(visible: StatsVisibility) {
+    this.statsVisibility = visible;
+  }
+
   /** Set compact mode (internal, for sync from ctrl+o). */
   setCompactMode(enabled: boolean) {
     if (this.compactMode === enabled) return;
@@ -228,6 +229,16 @@ export class AgentWidget {
     this.maxLinesCompact = lines;
   }
 
+  /** Set max description length for full mode. */
+  setDescLengthFull(len: number) {
+    this.descLengthFull = len;
+  }
+
+  /** Set max description length for compact mode. */
+  setDescLengthCompact(len: number) {
+    this.descLengthCompact = len;
+  }
+
   /** Set the UI context (grabbed from first tool execution). */
   setUICtx(ctx: UICtx) {
     if (ctx !== this.uiCtx) {
@@ -297,7 +308,7 @@ export class AgentWidget {
     switch (status) {
       case "completed":
         return { icon: theme.fg("success", "✓"), statusText: "" };
-      case "steered":
+      case "turn_limited":
         return { icon: theme.fg("warning", "✓"), statusText: theme.fg("warning", " (turn limit)") };
       case "stopped":
         return { icon: theme.fg("dim", "■"), statusText: theme.fg("dim", " stopped") };
@@ -314,42 +325,42 @@ export class AgentWidget {
   /** Render a finished agent line. */
   private renderFinishedLine(a: AgentRecord, theme: Theme): string {
     const name = getDisplayName(a.display.type);
-    const duration = formatMs((a.lifecycle.completedAt ?? Date.now()) - a.lifecycle.startedAt);
+    const fullDesc = truncateDesc(a.display.description, this.descLengthFull);
     const { icon, statusText } = this.finishedIconAndStatus(a.lifecycle.status, a.error, theme);
 
-    const activity = this.agentActivity.get(a.id);
-    const usage = activity?.lifetimeUsage ?? a.stats.lifetimeUsage;
+    const durationMs = (a.lifecycle.completedAt ?? Date.now()) - a.lifecycle.startedAt;
     const statsParts = buildStatsParts({
       toolUses: a.stats.toolUses,
-      turnCount: activity?.turnCount ?? a.stats.turnCount,
-      maxTurns: activity?.maxTurns ?? a.stats.maxTurns,
-      tokens: getLifetimeTotal(usage),
-      contextPercent: activity?.session ? getSessionContextPercent(activity.session) : a.stats.contextPercent ?? null,
+      turnCount: a.stats.turnCount,
+      maxTurns: a.stats.maxTurns,
+      input: a.stats.lifetimeUsage.input,
+      output: a.stats.lifetimeUsage.output,
+      contextPercent: a.stats.contextPercent ?? null,
       compactions: a.stats.compactionCount,
-      cost: this.showCost ? usage.cost : undefined,
-    }, theme);
-    statsParts.push(duration);
+      cost: a.stats.lifetimeUsage.cost,
+      durationMs,
+    }, theme, this.statsVisibility);
 
     const statsLine = statsParts.join("·");
-    return `${icon} ${theme.fg("dim", name)}  ${theme.fg("dim", a.display.description)}  ${wrapInDim(theme, statsLine)}${statusText}`;
+    return `${icon} ${theme.fg("dim", name)}  ${theme.fg("dim", fullDesc)}  ${wrapInDim(theme, statsLine)}${statusText}`;
   }
 
   /** Build the stats line (toolUses · turns · tokens · cost · elapsed) for a running agent. */
   private buildStatsLine(
     agent: AgentRecord,
-    activity: AgentActivity | undefined,
     theme: Theme,
   ): string {
     const parts = buildStatsParts({
-      toolUses: activity?.toolUses ?? agent.stats.toolUses,
-      turnCount: activity?.turnCount,
-      maxTurns: activity?.maxTurns,
-      tokens: getLifetimeTotal(activity?.lifetimeUsage),
-      contextPercent: getSessionContextPercent(activity?.session),
+      toolUses: agent.stats.toolUses,
+      turnCount: agent.stats.turnCount,
+      maxTurns: agent.stats.maxTurns,
+      input: agent.stats.lifetimeUsage.input,
+      output: agent.stats.lifetimeUsage.output,
+      contextPercent: agent.execution.session ? getSessionContextPercent(agent.execution.session) : agent.stats.contextPercent ?? null,
       compactions: agent.stats.compactionCount,
-      cost: this.showCost ? activity?.lifetimeUsage?.cost : undefined,
-    }, theme);
-    parts.push(formatMs(Date.now() - agent.lifecycle.startedAt));
+      cost: agent.stats.lifetimeUsage.cost,
+      durationMs: Date.now() - agent.lifecycle.startedAt,
+    }, theme, this.statsVisibility);
     return parts.join("·");
   }
 
@@ -390,13 +401,13 @@ export class AgentWidget {
     const blocks: RenderBlock[] = [];
     for (const a of running) {
       const name = getDisplayName(a.display.type);
-      const bg = this.agentActivity.get(a.id);
-      const statsLine = this.buildStatsLine(a, bg, theme);
+      const bg = this.getLiveView(a.id);
+      const statsLine = this.buildStatsLine(a, theme);
       const activity = bg ? describeActivity(bg.activeTools, bg.responseText) : THINKING_TEXT;
 
       if (this.isCompact()) {
         // Compact: single line with activity inline, truncated description
-        const desc = a.display.description.length > 30 ? a.display.description.slice(0, 27) + "..." : a.display.description;
+        const desc = truncateDesc(a.display.description, this.descLengthCompact);
         const headerLine = `${BRANCH} ${theme.fg("accent", frame)} ${theme.bold(name)}  ${desc}  ${statsLine}  ${theme.fg("dim", activity)}`;
         blocks.push({
           header: truncate(headerLine),
@@ -404,7 +415,8 @@ export class AgentWidget {
         });
       } else {
         // Full: header + continuation lines
-        const headerLine = `${BRANCH} ${theme.fg("accent", frame)} ${theme.bold(name)}  ${a.display.description}  ${statsLine}`;
+        const fullDesc = truncateDesc(a.display.description, this.descLengthFull);
+        const headerLine = `${BRANCH} ${theme.fg("accent", frame)} ${theme.bold(name)}  ${fullDesc}  ${statsLine}`;
         const continuations: string[] = [];
         if (a.display.outputFile || a.display.worktreeLabel) {
           const parts: string[] = [];

package/src/{format.ts → ui/format.ts}

@@ -8,9 +8,15 @@
  * Pure functions — no module-level state, no side effects.
  */
 
-import { getConfig } from "./agent-types.js";
-import type { SubagentType, Theme } from "./types.js";
-import { formatTokens, formatCost } from "./usage.js";
+import { getConfig } from "../agents/agent-types.js";
+import type { SubagentType } from "../agents/types.js";
+import type { Theme } from "./types.js";
+import { formatTokens, formatTokensCompact, formatCost } from "../agents/usage.js";
+
+/** Truncate a description string to `maxLen` characters, appending "..." if truncated. */
+export function truncateDesc(text: string, maxLen: number): string {
+  return text.length > maxLen ? text.slice(0, maxLen - 3) + "..." : text;
+}
 
 /** Max length for a truncated command in tool arg summaries. */
 const MAX_COMMAND_DISPLAY_LENGTH = 100;
@@ -25,18 +31,22 @@ const MAX_DEFAULT_STRING_DISPLAY_LENGTH = 200;
  * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
  * Compaction count rendered as `↻ N` in dim.
  *
- *   "12.3k"                     — no annotations
- *   "12.3k(45%)"                — percent only
- *   "12.3k(↻ 2)"                 — compactions only (e.g. right after compact)
- *   "12.3k(45%·↻ 2)"             — both
+ *   "↑12k↓8k"                    — no annotations
+ *   "↑12k↓8k 45%"                — percent only
+ *   "↑12k↓8k ↻ 2"                 — compactions only (e.g. right after compact)
+ *   "↑12k↓8k 45% ↻ 2"             — both
  */
 function formatSessionTokens(
-  tokens: number,
+  inputTokens: number,
+  outputTokens: number,
   percent: number | null,
   theme: Theme,
   compactions = 0,
 ): string {
-  const tokenStr = formatTokens(tokens);
+  const tokenParts: string[] = [];
+  if (inputTokens > 0) tokenParts.push(`↑${formatTokensCompact(inputTokens)}`);
+  if (outputTokens > 0) tokenParts.push(`↓${formatTokensCompact(outputTokens)}`);
+  const tokenStr = tokenParts.join("");
   const annot: string[] = [];
   if (percent !== null) {
     const color = percent >= 85 ? "error" : percent >= 70 ? "warning" : "dim";
@@ -46,16 +56,17 @@ function formatSessionTokens(
     annot.push(theme.fg("dim", `↻ ${compactions}`));
   }
   if (annot.length === 0) return tokenStr;
-  // Include closing paren in the last annotation's color span to prevent
-  // ANSI reset from leaving `)` in default color when wrapped in outer dim.
-  const lastIdx = annot.length - 1;
-  annot[lastIdx] += ")";
-  return `${tokenStr}(${annot.join("·")}`;
+  return `${tokenStr} ${annot.join(" ")}`;
 }
 
-/** Format turn count with optional max limit: "5≤30⟳" or "5⟳". */
-function formatTurns(turnCount: number, maxTurns?: number | null): string {
-  return maxTurns != null ? `${turnCount}≤${maxTurns}⟳ ` : `${turnCount}⟳ `;
+/** Format turn count with optional max limit. Shows max when >= 80% of limit. */
+function formatTurns(turnCount: number, maxTurns: number | null | undefined, theme: Theme): string {
+  if (maxTurns == null) return `${turnCount}⟳ `;
+  const ratio = turnCount / maxTurns;
+  const text = ratio >= 0.8 ? `${turnCount}≤${maxTurns}⟳ ` : `${turnCount}⟳ `;
+  if (ratio >= 1) return theme.fg("error", text);
+  if (ratio >= 0.8) return theme.fg("warning", text);
+  return text;
 }
 
 // ---- Exported formatting functions ----
@@ -77,31 +88,58 @@ export function formatMs(ms: number): string {
   return parts.join(" ");
 }
 
+/** Visibility flags for stats parts. All default to true. */
+export interface StatsVisibility {
+  showTools?: boolean;
+  showTurns?: boolean;
+  showInput?: boolean;
+  showOutput?: boolean;
+  showContext?: boolean;
+  showCost?: boolean;
+  showTime?: boolean;
+}
+
 /**
- * Build common stats parts: toolUses · turns · tokens with context % · cost.
+ * Build common stats parts: toolUses · turns · input↓ output with context % · cost · time.
  * Shared by AgentWidget and index.ts for consistent stats display.
+ *
+ * @param visible - Optional visibility flags. All default to true for backward compatibility.
+ * @param durationMs - Optional duration in ms. When provided and showTime is not false, appends formatted time.
  */
 export function buildStatsParts(
   args: {
     toolUses: number;
     turnCount?: number;
     maxTurns?: number;
-    tokens: number;
+    input: number;
+    output: number;
     contextPercent: number | null;
     compactions: number;
     cost?: number;
+    durationMs?: number;
   },
   theme: Theme,
+  visible?: StatsVisibility,
 ): string[] {
   const parts: string[] = [];
-  if (args.toolUses > 0) parts.push(`${args.toolUses}🛠 `);
-  if (args.turnCount != null) parts.push(formatTurns(args.turnCount, args.maxTurns));
-  if (args.tokens > 0) {
-    parts.push(formatSessionTokens(
-      args.tokens, args.contextPercent, theme, args.compactions,
-    ));
+  if (visible?.showTools !== false && args.toolUses > 0) parts.push(`${args.toolUses}🛠 `);
+  if (visible?.showTurns !== false && args.turnCount != null) parts.push(formatTurns(args.turnCount, args.maxTurns, theme));
+  if (visible?.showInput !== false || visible?.showOutput !== false) {
+    const showIn = visible?.showInput !== false;
+    const showOut = visible?.showOutput !== false;
+    const inputTokens = showIn ? args.input : 0;
+    const outputTokens = showOut ? args.output : 0;
+    if (inputTokens > 0 || outputTokens > 0) {
+      parts.push(formatSessionTokens(
+        inputTokens, outputTokens,
+        visible?.showContext !== false ? args.contextPercent : null,
+        theme,
+        visible?.showContext !== false ? args.compactions : 0,
+      ));
+    }
   }
-  if (args.cost != null && args.cost > 0) parts.push(formatCost(args.cost));
+  if (visible?.showCost !== false && args.cost != null && args.cost > 0) parts.push(formatCost(args.cost));
+  if (visible?.showTime !== false && args.durationMs != null) parts.push(formatMs(args.durationMs));
   return parts;
 }
 

package/src/ui/menu/helpers.ts

@@ -0,0 +1,93 @@
+/**
+ * helpers.ts — Shared helpers for menu modules:
+ * theme builders for SettingsList/SelectList, numeric validation,
+ * model-option building, and a swappable delegating component.
+ */
+
+import type { Component, SettingsListTheme } from "@earendil-works/pi-tui";
+import type { ModelOption } from "../../models/model-selector.js";
+import { parseModelKey } from "../../utils.js";
+
+/**
+ * Build ModelOption[] from raw "provider/model-id" strings.
+ * Includes "(inherits parent)" as the first option.
+ */
+export function buildModelOptions(rawOptions: string[]): ModelOption[] {
+  const items: ModelOption[] = [
+    { value: "(inherits parent)", label: "(inherits parent)", provider: "" },
+  ];
+
+  for (const opt of rawOptions) {
+    const parsed = parseModelKey(opt);
+    if (!parsed) continue;
+    items.push({ value: opt, label: parsed.modelId, provider: parsed.provider });
+  }
+  return items;
+}
+
+/**
+ * Build a SettingsListTheme from a pi-coding-agent Theme.
+ * Shared by widget settings and future SettingsList-based menus.
+ */
+export function buildSettingsListTheme(theme: { fg(color: string, text: string): string; bold(text: string): string }): SettingsListTheme {
+  return {
+    label: (text, selected) => selected ? theme.fg("accent", text) : text,
+    value: (text, selected) => selected ? theme.fg("accent", text) : theme.fg("muted", text),
+    description: (text) => theme.fg("muted", text),
+    // Use "→ " (2 chars) to match non-selected prefix "  " (2 spaces)
+    // This prevents menu items from shifting left/right when cursor moves
+    cursor: theme.fg("accent", "→ "),
+    hint: (text) => theme.fg("dim", text),
+  };
+}
+
+/**
+ * Pure numeric validation. Returns parsed integer ≥ min, or undefined.
+ * Extracted from parseNumericInput for use in submenu Components.
+ */
+export function validateNumeric(value: string, min: number): number | undefined {
+  const parsed = parseInt(value.trim(), 10);
+  if (isNaN(parsed) || parsed < min) return undefined;
+  return parsed;
+}
+
+/**
+ * Create a Component that delegates to a swappable inner component.
+ * Use in submenus that switch between SelectList → Input (or similar).
+ */
+export function createDelegatingComponent(initial: Component): Component & { setActive(c: Component): void; focused?: boolean; items?: any; onSelect?: any; onCancel?: any } {
+  let active = initial;
+  return {
+    invalidate() { active.invalidate?.(); },
+    render(width: number) { return active.render(width); },
+    handleInput(data: string) { active.handleInput?.(data); },
+    setActive(c: Component) { active = c; },
+    // Propagate focused to the active child so isFocusable() returns true,
+    // which tells SettingsListWrapper to passthrough keys instead of converting them.
+    get focused() { return (active as any)?.focused ?? false; },
+    set focused(value: boolean) { if ((active as any)?.focused != null) (active as any).focused = value; },
+    // Proxy SelectList properties so SettingsListWrapper can add "Back" button.
+    get items() { return (active as any)?.items; },
+    set items(v: any) { (active as any).items = v; },
+    get onSelect() { return (active as any)?.onSelect; },
+    set onSelect(v: any) { (active as any).onSelect = v; },
+    get onCancel() { return (active as any)?.onCancel; },
+    set onCancel(v: any) { (active as any).onCancel = v; },
+  };
+}
+
+/**
+ * Build a SelectListTheme from a pi-coding-agent Theme.
+ * Produces identical visual style to buildSettingsListTheme:
+ *   → cursor, accent colors, muted descriptions.
+ */
+export function buildSelectListTheme(theme: { fg(color: string, text: string): string; bold(text: string): string }): import("@earendil-works/pi-tui").SelectListTheme {
+  return {
+    selectedPrefix: () => theme.fg("accent", "→ "),
+    selectedText: (text) => theme.fg("accent", text),
+    description: (text) => theme.fg("muted", text),
+    scrollInfo: (text) => theme.fg("dim", text),
+    noMatch: (text) => theme.fg("dim", text),
+  };
+}
+