@leing2021/super-pi 0.23.13 → 0.25.0

package/README.md

@@ -8,7 +8,7 @@
 
 **Turn your AI coding agent into a reliable engineer.**
 
-Super Pi is a Pi-native engineering workflow layer: it adds stage discipline, durable artifacts, TDD gates, checkpoints, review, and learning loops on top of your coding agent. It is not a general-purpose multi-agent executor; subagents are optional helpers for bounded leaf tasks.
+Super Pi is a Pi-native engineering workflow layer: it adds stage discipline, durable artifacts, TDD gates, checkpoints, review, and learning loops on top of your coding agent.
 
 Install, describe what you want to build, then keep saying "continue." Super Pi drives the full loop:
 
@@ -25,10 +25,9 @@ pi install npm:@leing2021/super-pi
 - **Five-step loop** — brainstorm → plan → work → review → learn, with automatic skill routing
 - **Checkpoint resume** — interrupted? Resume from the exact unit you left off
 - **TDD enforcement** — every unit follows RED → GREEN → REFACTOR with hard gates
-- **Controlled subagents** — inline execution by default; subagents are limited to bounded, non-interactive leaf tasks
 - **Evidence-first review** — auto-assigned reviewers across five axes, autofix loop
 - **Knowledge compounding** — solved problems become searchable solution artifacts
-- **Token-efficient** — ~2,600 tokens new-conversation overhead; progressive loading
+- **Token-efficient** — ~4,200 tokens new-conversation overhead; progressive loading
 
 ---
 
@@ -45,7 +44,7 @@ You: I want to build a CLI tool that helps indie devs find early users
 
 → 01-brainstorm: structured discovery → requirements artifact
 → 02-plan: TDD-gated implementation units → plan artifact
-→ 03-work: inline-first execution, bounded subagents, checkpoint resume
+→ 03-work: inline execution, checkpoint resume
 → 04-review: five-axis findings, autofix loop
 → 05-learn: knowledge compounding
 
@@ -73,18 +72,11 @@ You: /skill:03-work docs/plans/plan.md
 |-------|-------------|-----------|
 | **01-brainstorm** | Structured multi-round discovery, domain vocabulary persistence | `brainstorm_dialog` |
 | **02-plan** | TDD-gated implementation units, optional CEO Review | `plan_diff` |
-| **03-work** | Inline-first execution, bounded subagents, checkpoint resume, strict TDD, stop-the-line | `ce_subagent`, `ce_parallel_subagent` |
+| **03-work** | Inline execution, checkpoint resume, strict TDD, stop-the-line | `session_checkpoint`, `task_splitter` |
 | **04-review** | Auto-assigned reviewers, five-axis findings, autofix loop | `review_router` |
 | **05-learn** | Pattern extraction → searchable solution artifacts | `pattern_extractor` |
 | **06-next** | Next-step recommendation + workflow status | `workflow_state` |
 | **07-worktree** | Isolated git worktree development | `worktree_manager` |
-| **08-help** | Phase 1 skill explainer | — |
-
-### Subagent tool namespace
-
-Super Pi ships CE-specific tools named `ce_subagent` and `ce_parallel_subagent`. They are intentionally namespaced so they can coexist with the compatible third-party `pi-subagents` extension without tool-name collisions.
-
-These tools are helpers, not the core workflow. Use inline execution by default. Use CE subagents only for bounded, non-interactive, easily verifiable leaf tasks. Do not use them to invoke pipeline-stage skills (`01-brainstorm` through `05-learn`); run those stages directly with `/skill:<stage>`.
 
 ### Model & Thinking Routing
 
@@ -117,7 +109,7 @@ Super Pi is not a fork or wrapper. It extracts useful methods from the projects
 | Project | What Super Pi adopted |
 |---------|------------------------|
 | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | "Use when" skill trigger conditions, source-driven verification, stop-the-line hard gate, anti-rationalization, and the five-axis review baseline. Adopted as embedded micro-patterns only — no new skills, tools, commands, or agents. |
-| [everything-claude-code](https://github.com/affaan-m/everything-claude-code) | Parallel subagent orchestration, checkpoint resume, continuous learning loops, and token-conscious agent workflow design. |
+| [everything-claude-code](https://github.com/affaan-m/everything-claude-code) | Checkpoint resume, continuous learning loops, and token-conscious agent workflow design. |
 | [humanlayer/12-factor-agents](https://github.com/humanlayer/12-factor-agents) | Context window ownership, compacting resolved errors, retry caps, and pre-fetching obvious prerequisites. Adopted as lightweight context hygiene rules inside the existing Phase 1 pipeline. |
 | [superpowers](https://github.com/obra/superpowers) | Strict TDD gates, design checklists, review discipline, and the idea that agents need hard gates instead of gentle suggestions. |
 | [compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) | The five-step think → plan → build → review → learn loop and the knowledge-compounding backbone. |
@@ -153,13 +145,13 @@ All reviewers evaluate changes across: **correctness, readability, architecture,
 
 ## Token Cost
 
-New conversation overhead: **~2,600 tokens** (1.3% of 200K context).
+New conversation overhead: **~4,130 tokens** (2.1% of 200K context).
 
 | Component | Tokens |
 |-----------|--------|
-| 8 skill registrations | ~490 |
-| System prompt | ~1,400 |
-| Skill inlining (per invocation) | ~500-800 |
+| 17 skill registrations | ~1,710 |
+| 22 tool schemas | ~2,420 |
+| Skill inlining (per invocation) | ~300–1,200 |
 
 Progressive loading: only needed skills loaded on-demand.
 
@@ -191,11 +183,11 @@ Commit everything to git — these files are the project's traceable memory.
 
 | Component | Count |
 |-----------|------:|
-| Skills | 8 |
-| Tools | 19 |
-| Rules | 79 |
-| TypeScript lines | ~4,400 |
-| Tests | 209 (786 assertions) |
+| Skills | 7 |
+| Tools | 12 CE + 10 Pi built-in |
+| Rules | 78 |
+| TypeScript lines | ~4,100 |
+| Tests | 180 (727 assertions) |
 
 Rules in `rules/` cover 11 common topics + language-specific sets (TypeScript, Rust, Go, Python, Java, Kotlin, C++, C#, Dart, Swift, Perl, PHP). Project-level overrides take priority.
 

package/extensions/ce-core/index.ts

@@ -1,14 +1,13 @@
 import { readFile } from "node:fs/promises"
 import path from "node:path"
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
 import { Type } from "typebox"
 import { createArtifactHelperTool, type ArtifactType } from "./tools/artifact-helper"
-import { createAskUserQuestionTool } from "./tools/ask-user-question"
-import { createSubagentTool } from "./tools/subagent"
+import { createAskUserQuestionTool, CUSTOM_SENTINEL } from "./tools/ask-user-question"
+import { createAskUserQuestionCustomFactory } from "./tools/ask-user-question-ui"
 import { createWorkflowStateTool } from "./tools/workflow-state"
 import { createWorktreeManagerTool } from "./tools/worktree-manager"
 import { createReviewRouterTool } from "./tools/review-router"
-import { createParallelSubagentTool } from "./tools/parallel-subagent"
 import { createSessionCheckpointTool } from "./tools/session-checkpoint"
 import { createTaskSplitterTool } from "./tools/task-splitter"
 import { createBrainstormDialogTool } from "./tools/brainstorm-dialog"
@@ -19,11 +18,6 @@ import { createContextHandoffTool } from "./tools/context-handoff"
 import { filterBashOutput } from "./tools/bash-output-filter"
 import { filterReadOutput } from "./tools/read-output-filter"
 import { COMPACTION_FOCUS_INSTRUCTIONS } from "./tools/compaction-optimizer"
-import { createJsonRunner, type JsonRunConfig } from "./tools/subagent-json-runner"
-import { getFinalOutput, isFailedResult, type SingleResult } from "./tools/subagent-events"
-import { renderSubagentCall, renderSubagentResult } from "./tools/subagent-renderer"
-import type { SubagentLiveRunner, SubagentLiveExecOptions, SubagentLiveDetails } from "./tools/subagent"
-import type { ParallelSubagentLiveDetails } from "./tools/parallel-subagent"
 
 const PIPELINE_STAGE_KEYS = new Set([
   "01-brainstorm",
@@ -33,6 +27,70 @@ const PIPELINE_STAGE_KEYS = new Set([
   "05-learn",
 ])
 
+/**
+ * Module-level promise chain that serializes interactive `ask_user_question`
+ * UI calls within a single Pi process.
+ *
+ * Why: `@earendil-works/pi-coding-agent` renders extension selectors via a
+ * singleton field (`extensionSelector` / `extensionInput` in
+ * `interactive-mode.js`). When two selector calls overlap, the second
+ * overwrites the first, and the first promise never resolves — surfacing to
+ * the agent as a silent `No result provided`. See
+ * `docs/bug/ask-user-question-parallel-call-silent-failure.md`.
+ *
+ * This guard ensures at most one selector/input is on screen at a time.
+ */
+let askUserQuestionExclusiveChain: Promise<unknown> = Promise.resolve()
+
+function runAskUserQuestionExclusive<T>(task: () => Promise<T>): Promise<T> {
+  const run = askUserQuestionExclusiveChain.then(task, task)
+  // Keep the chain robust: a rejected run must not poison subsequent calls.
+  askUserQuestionExclusiveChain = run.then(
+    () => undefined,
+    () => undefined,
+  )
+  return run
+}
+
+/**
+ * Build the UI adapter for `ask_user_question`.
+ *
+ * In interactive TUI mode with `ctx.ui.custom` available, route `select`
+ * through the scrollable custom dialog so long questions/options stay readable
+ * (see `docs/bug/ask-user-question-long-text-not-scrollable.md`). Otherwise
+ * fall back to the built-in `ctx.ui.select()`.
+ */
+function buildAskUserQuestionUi(ctx: any): import("./tools/ask-user-question").AskUserQuestionUi {
+  const useCustom = ctx?.mode === "tui" && typeof ctx?.ui?.custom === "function"
+  const input = async (question: string) => (await ctx.ui.input(question)) ?? null
+  const selectFallback = async (question: string, options: string[]) =>
+    (await ctx.ui.select(question, options)) ?? null
+
+  if (!useCustom) {
+    return { input, select: selectFallback }
+  }
+
+  const select = async (question: string, options: string[]): Promise<string | null> => {
+    // The custom sentinel is appended last (if present) and matches
+    // `CUSTOM_SENTINEL` or a `CUSTOM_SENTINEL (#n)` disambiguation suffix.
+    const last = options.length > 0 ? options[options.length - 1] : null
+    const customLabel = last !== null
+      && (last === CUSTOM_SENTINEL || last.startsWith(`${CUSTOM_SENTINEL} (#`))
+      ? last
+      : null
+    const factory = createAskUserQuestionCustomFactory({
+      question,
+      displayOptions: options,
+      customLabel,
+    })
+    const selection = (await ctx.ui.custom(factory)) as
+      { selectedLabel: string | null } | null | undefined
+    return selection?.selectedLabel ?? null
+  }
+
+  return { input, select }
+}
+
 interface StrategySettings {
   modelStrategy?: Record<string, string>
   thinkingStrategy?: Record<string, string>
@@ -116,34 +174,6 @@ function parseModelRef(
   }
 }
 
-/**
- * Create a spawn-based subagent runner that uses pi --mode json
- * with per-process env (no global process.env mutation).
- */
-function createSubagentRunner(
-  pi: ExtensionAPI,
-  signal?: AbortSignal,
-): SubagentLiveRunner {
-  const jsonRunner = createJsonRunner()
-  return async (prompt: string, options?: SubagentLiveExecOptions) => {
-    const config: JsonRunConfig = {
-      prompt,
-      agent: "",
-      task: "",
-      cwd: (pi as any).cwd ?? process.cwd(),
-      extraFlags: options?.extraFlags,
-      extraEnv: options?.extraEnv,
-      signal,
-      onUpdate: options?.onUpdate,
-    }
-    const result = await jsonRunner.run(config)
-    if (isFailedResult(result) || result.exitCode !== 0) {
-      throw new Error(result.errorMessage || result.stderr || `Subagent failed for prompt: ${prompt}`)
-    }
-    return result
-  }
-}
-
 const artifactHelperParams = Type.Object({
   repoRoot: Type.String({ description: "Repository root where workflow artifacts should be created" }),
   artifactType: Type.Union([
@@ -166,18 +196,6 @@ const askUserQuestionParams = Type.Object({
   allowCustom: Type.Optional(Type.Boolean({ description: "Allow a custom answer when options are present" })),
 })
 
-const subagentTaskSchema = Type.Object({
-  agent: Type.String({ description: "Skill name to invoke via /skill:<name>" }),
-  task: Type.String({ description: "Task text passed to the subagent" }),
-})
-
-const subagentParams = Type.Object({
-  agent: Type.Optional(Type.String({ description: "Single subagent skill name" })),
-  task: Type.Optional(Type.String({ description: "Single subagent task" })),
-  chain: Type.Optional(Type.Array(subagentTaskSchema, { description: "Serial subagent chain with optional {previous} placeholder" })),
-  inheritSkills: Type.Optional(Type.Boolean({ description: "Whether the subagent should inherit skills. Default: true" })),
-})
-
 const workflowStateParams = Type.Object({
   repoRoot: Type.String({ description: "Repository root to scan for workflow artifacts" }),
 })
@@ -200,19 +218,6 @@ const reviewRouterParams = Type.Object({
   deletions: Type.Number({ description: "Number of lines removed" }),
 })
 
-const parallelSubagentTaskSchema = Type.Object({
-  agent: Type.String({ description: "Skill name to invoke via /skill:<name>" }),
-  task: Type.String({ description: "Task text passed to the subagent" }),
-})
-
-const parallelSubagentParams = Type.Object({
-  tasks: Type.Union([
-    Type.Array(parallelSubagentTaskSchema),
-    Type.String({ description: "JSON stringified array of tasks" }),
-  ], { description: "Array of independent tasks to run concurrently (can be a JSON string)" }),
-  inheritSkills: Type.Optional(Type.Boolean({ description: "Whether subagents should inherit skills. Default: true" })),
-})
-
 const sessionCheckpointParams = Type.Object({
   operation: Type.Union([
     Type.Literal("save"),
@@ -346,9 +351,18 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
       return { action: "continue" as const }
     }
 
+    // Skip model/thinking switching during streaming steers — these are
+    // mid-stream interrupts, not new pipeline invocations.
+    if (event.streamingBehavior === "steer") {
+      return { action: "continue" as const }
+    }
+
     const settings = await readSettings(ctx.cwd)
     const modelStrategy = settings?.modelStrategy
     const thinkingStrategy = settings?.thinkingStrategy
+    // Notification guard: only notify in interactive (TUI) or RPC modes.
+    // For interactive input capability checks (askUserQuestion), use ctx.hasUI directly.
+    const shouldNotify = ctx.mode === "tui" || ctx.mode === "rpc"
 
     // Model switching
     if (modelStrategy) {
@@ -362,19 +376,19 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
             if (model) {
               const switched = await pi.setModel(model)
               if (switched) {
-                if (ctx.hasUI) {
+                if (shouldNotify) {
                   ctx.ui.notify(`Switched model for ${stageKey}: ${model.provider}/${model.id}`, "info")
                 }
               } else {
-                if (ctx.hasUI) {
+                if (shouldNotify) {
                   ctx.ui.notify(`No API key for ${stageKey}: ${model.provider}/${model.id}`, "warning")
                 }
               }
-            } else if (ctx.hasUI) {
+            } else if (shouldNotify) {
               ctx.ui.notify(`Model not found for ${stageKey}: ${targetModelRef}`, "warning")
             }
           }
-        } else if (ctx.hasUI) {
+        } else if (shouldNotify) {
           ctx.ui.notify(`Invalid modelStrategy for ${stageKey}: ${targetModelRef}`, "warning")
         }
       }
@@ -399,7 +413,7 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
         const currentLevel = pi.getThinkingLevel()
         if (currentLevel !== normalized) {
           pi.setThinkingLevel(normalized)
-          if (ctx.hasUI) {
+          if (shouldNotify) {
             ctx.ui.notify(`Switched thinking level for ${stageKey}: ${normalized}`, "info")
           }
         }
@@ -411,11 +425,9 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
 
   const artifactHelper = createArtifactHelperTool()
   const askUserQuestion = createAskUserQuestionTool()
-  const subagent = createSubagentTool()
   const workflowState = createWorkflowStateTool()
   const worktreeManager = createWorktreeManagerTool()
   const reviewRouter = createReviewRouterTool()
-  const parallelSubagent = createParallelSubagentTool()
   const sessionCheckpoint = createSessionCheckpointTool()
   const taskSplitter = createTaskSplitterTool()
   const brainstormDialog = createBrainstormDialogTool()
@@ -452,6 +464,11 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     name: askUserQuestion.name,
     label: "Ask User Question",
     description: "Ask the user a structured question with optional choices and custom answers.",
+    promptSnippet: "Ask the user a structured question with optional choices and custom answers",
+    promptGuidelines: [
+      "Call ask_user_question one at a time, never two or more in the same assistant message: Pi renders selectors on a shared singleton, so parallel ask_user_question calls silently fail with 'No result provided'.",
+      "For ask_user_question, keep the question concise and put long analysis in prior text or a file first; ask_user_question normalizes long options to short labels but the full answer is still returned to you.",
+    ],
     parameters: askUserQuestionParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       if (!ctx.hasUI) {
@@ -462,17 +479,14 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
         }
       }
 
-      const result = await askUserQuestion.execute(
+      const result = await runAskUserQuestionExclusive(() => askUserQuestion.execute(
         {
           question: params.question,
           options: params.options,
           allowCustom: params.allowCustom,
         },
-        {
-          input: async (question) => (await ctx.ui.input(question)) ?? null,
-          select: async (question, options) => (await ctx.ui.select(question, options)) ?? null,
-        },
-      )
+        buildAskUserQuestionUi(ctx),
+      ))
 
       const contentText = result.answer === null
         ? "User cancelled."
@@ -489,45 +503,6 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     },
   })
 
-  pi.registerTool({
-    name: subagent.name,
-    label: "CE Subagent",
-    description: "Run a single CE skill-based subagent or a serial chain in an isolated Pi process.",
-    parameters: subagentParams,
-    async execute(_toolCallId, params, signal, onUpdate, ctx) {
-      const result = await subagent.execute(
-        {
-          agent: params.agent,
-          task: params.task,
-          chain: params.chain,
-          inheritSkills: params.inheritSkills,
-        },
-        createSubagentRunner(pi, signal),
-        { onUpdate: onUpdate ? (details) => onUpdate({ content: [], details }) : undefined },
-      )
-
-      // Build final content from results
-      const lastResult = result.results[result.results.length - 1]
-      const finalText = lastResult ? getFinalOutput(lastResult.messages) : ""
-      const isError = lastResult ? isFailedResult(lastResult) : false
-
-      return {
-        content: [{ type: "text", text: finalText || "(no output)" }],
-        details: result,
-        isError: isError || undefined,
-      }
-    },
-    renderCall(args, theme, _context) {
-      return renderSubagentCall(args, theme)
-    },
-    renderResult(result, renderContext, theme, _context) {
-      // Handle partial updates where data is at top level (from onUpdate)
-      // rather than nested in .details (from final result return value)
-      const data = (result.details || result) as SubagentLiveDetails
-      return renderSubagentResult(data, renderContext, theme)
-    },
-  })
-
   pi.registerTool({
     name: workflowState.name,
     label: "Workflow State",
@@ -599,73 +574,6 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     },
   })
 
-  pi.registerTool({
-    name: parallelSubagent.name,
-    label: "CE Parallel Subagent",
-    description: "Run multiple CE skill-based subagent tasks concurrently. IMPORTANT: Provide 'tasks' as a clean JSON array object. If the environment forces a string, provide a valid JSON array string.",
-    parameters: parallelSubagentParams,
-    async execute(_toolCallId, params, signal, onUpdate) {
-      let tasks: any[]
-      if (typeof params.tasks === "string") {
-        try {
-          const cleaned = params.tasks.replace(/^```json\s*|```$/g, "").trim()
-          tasks = JSON.parse(cleaned)
-        } catch (e) {
-          throw new Error(`Failed to parse tasks string as JSON: ${e instanceof Error ? e.message : String(e)}`)
-        }
-      } else {
-        tasks = params.tasks
-      }
-
-      const result = await parallelSubagent.execute(
-        {
-          tasks,
-          inheritSkills: params.inheritSkills,
-        },
-        createSubagentRunner(pi, signal),
-        { onUpdate: onUpdate ? (details) => onUpdate({ content: [], details }) : undefined },
-      )
-
-      // Build compact summary content for LLM consumption
-      const successCount = result.results.filter(r => r.exitCode === 0).length
-      const failCount = result.results.filter(r => isFailedResult(r)).length
-      const summaries = result.results.map((r, i) => {
-        const icon = isFailedResult(r) ? "✗" : "✓"
-        const output = getFinalOutput(r.messages) || r.errorMessage || r.stderr || "(no output)"
-        // Compact: first non-empty line, stripped of markdown formatting
-        const summaryLine = output.split("\n").find((l: string) => l.trim().length > 0) || ""
-        const cleaned = summaryLine.replace(/^#+\s*/, "").replace(/\*\*/g, "").trim()
-        const oneLine = cleaned.length > 200 ? cleaned.slice(0, 199) + "…" : cleaned
-        return `${i + 1}. ${icon} ${r.agent} — ${oneLine}`
-      })
-
-      // Full outputs available in details for expanded view
-      const fullOutputs = result.results.map(r => {
-        const output = getFinalOutput(r.messages) || ""
-        return output
-      })
-
-      return {
-        content: [{
-          type: "text",
-          text: `Parallel: ${successCount}/${result.results.length} succeeded${failCount > 0 ? `, ${failCount} failed` : ""}\n${summaries.join("\n")}`,
-        }],
-        details: result,
-      }
-    },
-    renderCall(args, theme, _context) {
-      return renderSubagentCall({
-        tasks: typeof args.tasks === "string" ? [] : args.tasks,
-      }, theme)
-    },
-    renderResult(result, renderContext, theme, _context) {
-      // Handle partial updates where data is at top level (from onUpdate)
-      // rather than nested in .details (from final result return value)
-      const data = (result.details || result) as ParallelSubagentLiveDetails
-      return renderSubagentResult(data, renderContext, theme)
-    },
-  })
-
   pi.registerTool({
     name: sessionCheckpoint.name,
     label: "Session Checkpoint",
@@ -909,31 +817,9 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
 
 export { createArtifactHelperTool } from "./tools/artifact-helper"
 export { createAskUserQuestionTool } from "./tools/ask-user-question"
-export { createSubagentTool } from "./tools/subagent"
-export { checkSubagentDepth, getChildDepthEnv, DEFAULT_MAX_SUBAGENT_DEPTH } from "./tools/subagent-depth-guard"
-export { AsyncMutex } from "./tools/async-mutex"
-export { createJsonRunner } from "./tools/subagent-json-runner"
-export {
-  parseJsonEvent,
-  applyEventToResult,
-  type SingleResult as SingleResultType,
-  type UsageStats,
-  type ParsedEvent,
-  isFailedResult as isFailedSingleResult,
-  formatUsageStats,
-  makeInitialResult,
-  getFinalOutput as getFinalOutputFromMessages,
-  getDisplayItems,
-} from "./tools/subagent-events"
-export {
-  formatToolCall,
-  renderSubagentCall,
-  renderSubagentResult,
-} from "./tools/subagent-renderer"
 export { createWorkflowStateTool } from "./tools/workflow-state"
 export { createWorktreeManagerTool } from "./tools/worktree-manager"
 export { createReviewRouterTool } from "./tools/review-router"
-export { createParallelSubagentTool } from "./tools/parallel-subagent"
 export { createSessionCheckpointTool } from "./tools/session-checkpoint"
 export { createTaskSplitterTool } from "./tools/task-splitter"
 export { createBrainstormDialogTool } from "./tools/brainstorm-dialog"

package/extensions/ce-core/tools/ask-user-question-ui.ts

@@ -0,0 +1,162 @@
+import {
+  Container,
+  Key,
+  matchesKey,
+  truncateToWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui"
+
+/**
+ * Result shape returned by the scrollable ask_user_question custom UI.
+ *
+ * - `selectedLabel`: the normalized display label the user picked (may be the
+ *   custom sentinel), or `null` when cancelled.
+ * - The caller maps `selectedLabel` back to the original full option string.
+ */
+export interface AskUserQuestionSelection {
+  selectedLabel: string | null
+}
+
+interface AskUserQuestionCustomOptions {
+  question: string
+  displayOptions: string[]
+  customLabel: string | null
+}
+
+/**
+ * Maximum number of option/question rows rendered before the viewport scrolls.
+ * Keeps the dialog inside typical terminal heights while still being readable.
+ */
+const MAX_VISIBLE_ROWS = 10
+
+/**
+ * Render the question body as wrapped lines so long questions stay readable
+ * inside the scrollable custom dialog.
+ */
+function renderQuestionLines(question: string, width: number, fg: (color: string, text: string) => string): string[] {
+  const lines = wrapTextWithAnsi(question, width)
+  return lines.map((line) => truncateToWidth(fg("text", line), width))
+}
+
+/**
+ * Scrollable selector component for `ask_user_question`.
+ *
+ * Renders a wrapped (multi-line) question and a list of single-line options.
+ * Handles:
+ * - up/down navigation with scroll offset
+ * - Enter to confirm
+ * - Escape / cancel keybinding to cancel
+ * - optional "Other" custom entry label
+ *
+ * Built to work inside Pi's `ctx.ui.custom()` factory contract:
+ * `(tui, theme, keybindings, done) => Component`.
+ */
+export class AskUserQuestionSelector extends Container {
+  private readonly options: string[]
+  private readonly question: string
+  private readonly customLabel: string | null
+  private readonly theme: { fg: (color: string, text: string) => string }
+  private readonly done: (result: AskUserQuestionSelection) => void
+  private selectedIndex = 0
+  private scrollOffset = 0
+  private resolved = false
+
+  constructor(
+    opts: AskUserQuestionCustomOptions,
+    theme: { fg: (color: string, text: string) => string },
+    done: (result: AskUserQuestionSelection) => void,
+  ) {
+    super()
+    this.options = opts.displayOptions
+    this.question = opts.question
+    this.customLabel = opts.customLabel
+    this.theme = theme
+    this.done = done
+  }
+
+  /** Resolve a selected display label into the result handed to `done()`. */
+  private commit(index: number): void {
+    if (this.resolved) return
+    this.resolved = true
+    const selected = this.options[index] ?? null
+    this.done({ selectedLabel: selected })
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.up) || data === "k") {
+      this.selectedIndex = Math.max(0, this.selectedIndex - 1)
+      this.scrollOffset = Math.min(this.scrollOffset, this.selectedIndex)
+    } else if (matchesKey(data, Key.down) || data === "j") {
+      this.selectedIndex = Math.min(this.options.length - 1, this.selectedIndex + 1)
+      const maxStart = Math.max(0, this.selectedIndex - MAX_VISIBLE_ROWS + 1)
+      this.scrollOffset = Math.max(this.scrollOffset, maxStart)
+    } else if (matchesKey(data, Key.enter) || data === "\n") {
+      this.commit(this.selectedIndex)
+    } else if (matchesKey(data, Key.escape)) {
+      if (this.resolved) return
+      this.resolved = true
+      this.done({ selectedLabel: null })
+    }
+  }
+
+  render(width: number): string[] {
+    const lines: string[] = []
+    const fg = this.theme.fg
+    const innerWidth = Math.max(20, width - 2)
+
+    lines.push(truncateToWidth(fg("accent", "─".repeat(width)), width))
+    for (const line of renderQuestionLines(this.question, innerWidth, fg)) {
+      lines.push(` ${line}`)
+    }
+    lines.push("")
+
+    const visible = this.options.slice(
+      this.scrollOffset,
+      this.scrollOffset + MAX_VISIBLE_ROWS,
+    )
+    for (let i = 0; i < visible.length; i++) {
+      const optionIndex = this.scrollOffset + i
+      const isSelected = optionIndex === this.selectedIndex
+      const isCustom = this.customLabel !== null && visible[i] === this.customLabel
+      const prefix = isSelected ? fg("accent", "→ ") : "  "
+      const marker = isCustom ? fg("muted", " ✎") : ""
+      lines.push(truncateToWidth(`${prefix}${fg(isSelected ? "accent" : "text", visible[i])}${marker}`, width))
+    }
+
+    if (this.options.length > MAX_VISIBLE_ROWS) {
+      lines.push(
+        truncateToWidth(
+          fg("muted", `  (${this.selectedIndex + 1}/${this.options.length})`),
+          width,
+        ),
+      )
+    }
+
+    lines.push("")
+    lines.push(
+      truncateToWidth(
+        fg("dim", " ↑↓ navigate · Enter select · Esc cancel"),
+        width,
+      ),
+    )
+    lines.push(truncateToWidth(fg("accent", "─".repeat(width)), width))
+    return lines
+  }
+}
+
+/**
+ * Build the factory passed to `ctx.ui.custom()`.
+ *
+ * Returns either a normalized display label (the user picked an option / custom
+ * sentinel) or `null` when the user cancelled.
+ */
+export function createAskUserQuestionCustomFactory(opts: AskUserQuestionCustomOptions) {
+  return (
+    _tui: unknown,
+    theme: { fg: (color: string, text: string) => string },
+    _keybindings: unknown,
+    done: (result: AskUserQuestionSelection) => void,
+  ): AskUserQuestionSelector => {
+    return new AskUserQuestionSelector(opts, theme, done)
+  }
+}