@bastani/atomic 0.8.22-0 → 0.8.23-0

package/dist/builtin/workflows/src/tui/stage-chat-view.ts

@@ -22,7 +22,7 @@
  *  - **Escape** mirrors the main coding-agent chat interrupt path for active
  *    live stages: it requests a controlled pause/abort while keeping the
  *    composer active. While paused, Enter calls `handle.resume(text)`.
- *  - **Ctrl+D** detaches (back to graph), or closes the popup while paused;
+ *  - **Ctrl+D** detaches (back to graph), including while paused;
  *    **Escape** closes the popup when idle.
  *  - **Blocked** stage: keystrokes absorbed; BLOCKED banner names the
  *    upstream awaiter.
@@ -69,7 +69,7 @@ import type { StageControlHandle } from "../runs/foreground/stage-control-regist
 import { isKeybindingsLike, type KeybindingsLike } from "./keybindings-adapter.js";
 import { BOLD, RESET, hexBg, hexToAnsi, lerpColor } from "./color-utils.js";
 import { renderWorkflowNoticeCard, type WorkflowNoticeTone } from "./workflow-notice-card.js";
-import { Key, matchesKey, visibleWidth } from "./text-helpers.js";
+import { Key, matchesKey, truncateToWidth, visibleWidth } from "./text-helpers.js";
 import {
   fitStageChatFrame,
   planStageChatFrame,
@@ -105,7 +105,7 @@ export interface StageChatViewOpts {
    * inspect-only (settled stage with no live handle).
    */
   handle?: StageControlHandle;
-  /** Called when the user presses Ctrl+D outside a paused stage (back to graph). */
+  /** Called when the user presses Ctrl+D (back to graph). */
   onDetach: (reason?: StageChatDetachReason, metadata?: StageChatDetachMetadata) => void;
   /** Called when the user presses Escape (close the whole popup). */
   onClose: () => void;
@@ -678,7 +678,9 @@ export class StageChatView implements Component, Focusable {
     const workingLines = chatChromeHidden ? [] : this.chatHost.renderWorkingStatus(w);
     const usageLines = chatChromeHidden ? [] : this.chatHost.renderUsage(w);
     const editorLines = chatChromeHidden ? [] : this.chatHost.renderEditor(w);
-    const footerLines = chatChromeHidden ? [] : this.chatHost.renderFooter(w);
+    const footerLines = chatChromeHidden
+      ? []
+      : this._renderFooterWithOrchestratorReturnHint(w, this.chatHost.renderFooter(w));
 
     const totalRows = this._viewLineCount();
     const plan = planStageChatFrame({
@@ -704,7 +706,9 @@ export class StageChatView implements Component, Focusable {
     if (blocked) this.chatHost.scrollToBottom();
 
     let bodyLines: string[];
-    if (promptActive) {
+    if (bodyBudget <= 0) {
+      bodyLines = [];
+    } else if (promptActive) {
       bodyLines = this._renderPromptBody(w, bodyBudget);
     } else if (blocked) {
       bodyLines = this._renderBlockedBody(w, bodyBudget, stage);
@@ -778,6 +782,67 @@ export class StageChatView implements Component, Focusable {
     return hexToAnsi(this.theme.borderDim) + "─".repeat(width) + RESET;
   }
 
+  private _renderFooterWithOrchestratorReturnHint(
+    width: number,
+    footerLines: readonly string[],
+  ): string[] {
+    if (footerLines.length === 0) {
+      return [this._mergeOrchestratorReturnHintIntoLine("", width)];
+    }
+    const lines = [...footerLines];
+    const lastIndex = lines.length - 1;
+    lines[lastIndex] = this._mergeOrchestratorReturnHintIntoLine(
+      lines[lastIndex] ?? "",
+      width,
+    );
+    return lines;
+  }
+
+  private _embedOrchestratorReturnHintInWidget(
+    widgetLines: readonly string[],
+    width: number,
+  ): string[] {
+    if (widgetLines.length === 0) {
+      return [this._mergeOrchestratorReturnHintIntoLine("", width)];
+    }
+    const lines = [...widgetLines];
+    const targetIndex = widgetHintTargetLineIndex(lines);
+    lines[targetIndex] = this._mergeOrchestratorReturnHintIntoLine(
+      lines[targetIndex] ?? "",
+      width,
+      { preserveTrailingBorder: true, rightMargin: 2 },
+    );
+    return lines;
+  }
+
+  private _mergeOrchestratorReturnHintIntoLine(
+    line: string,
+    width: number,
+    options: { preserveTrailingBorder?: boolean; rightMargin?: number } = {},
+  ): string {
+    const plain = "ctrl+d returns to orchestrator panel";
+    const styled =
+      paint("ctrl+d", this.theme.text, { bold: true }) +
+      paint(" returns to orchestrator panel", this.theme.textMuted);
+    const trailingBorder = options.preserveTrailingBorder === true
+      ? trailingWidgetBorderChar(line)
+      : "";
+    const suffixWidth = visibleWidth(trailingBorder);
+    const hintWidth = visibleWidth(plain);
+    const requestedRightMargin = Math.max(
+      0,
+      Math.floor(options.rightMargin ?? 0),
+    );
+    const rightMargin = Math.min(
+      requestedRightMargin,
+      Math.max(0, width - suffixWidth - hintWidth),
+    );
+    const hintStart = Math.max(0, width - suffixWidth - rightMargin - hintWidth);
+    const prefix = truncateToWidth(line, hintStart, "", true);
+    const gap = Math.max(0, hintStart - visibleWidth(prefix));
+    return prefix + " ".repeat(gap) + styled + " ".repeat(rightMargin) + trailingBorder;
+  }
+
   // -------------------------------------------------------------------------
   // Body — welcome panel / banner + transcript / blocked
   // -------------------------------------------------------------------------
@@ -913,7 +978,7 @@ export class StageChatView implements Component, Focusable {
         "warning",
         "❚❚",
         "PAUSED",
-        "enter resumes · ctrl+d close",
+        "enter resumes · ctrl+d graph",
       ),
     );
     callout.push(
@@ -981,12 +1046,18 @@ export class StageChatView implements Component, Focusable {
     const component = this.mountedCustomUi?.component;
     if (!component) return [];
     setComponentFocused(component, this.focused);
-    return component.render(width);
+    return this._embedOrchestratorReturnHintInWidget(component.render(width), width);
   }
 
   private _renderPromptBody(width: number, budget: number): string[] {
     const primitiveLines = this._renderPrimitivePromptBody(width);
-    if (primitiveLines) return this._fitPromptBodyLines(primitiveLines, width, budget);
+    if (primitiveLines) {
+      return this._fitPromptBodyLines(
+        this._embedOrchestratorReturnHintInWidget(primitiveLines, width),
+        width,
+        budget,
+      );
+    }
 
     const state = this.promptState;
     const lines = state
@@ -997,7 +1068,11 @@ export class StageChatView implements Component, Focusable {
         cursorOn: this.focused,
       })
       : [];
-    return this._fitPromptBodyLines(lines, width, budget);
+    return this._fitPromptBodyLines(
+      this._embedOrchestratorReturnHintInWidget(lines, width),
+      width,
+      budget,
+    );
   }
 
   private _renderPrimitivePromptBody(width: number): string[] | null {
@@ -1203,8 +1278,7 @@ export class StageChatView implements Component, Focusable {
         // stays pending (the stage remains awaiting_input) and is re-displayed
         // when the user re-attaches.
         this._releaseMountedCustomUi();
-        if (this._isPaused()) this.onClose();
-        else this.onDetach();
+        this.onDetach();
         return true;
       }
       if (matchesKey(data, Key.ctrl("c"))) {
@@ -1233,8 +1307,7 @@ export class StageChatView implements Component, Focusable {
     const readOnlyPromptArchive = readOnlyArchive && stage?.promptFootprint !== undefined;
     if (matchesKey(data, Key.ctrl("d"))) {
       if (!this.promptState && this.chatHost.hasInputText()) return this.chatHost.handleInput(data);
-      if (this._isPaused()) this.onClose();
-      else this.onDetach();
+      this.onDetach();
       return true;
     }
     if (this.promptState) {
@@ -1337,6 +1410,7 @@ export class StageChatView implements Component, Focusable {
   }
 
   invalidate(): void {
+    this.chatHost.invalidate();
     this._syncPromptState(this._currentStage()?.pendingPrompt);
   }
 
@@ -1699,6 +1773,29 @@ function takeRows(lines: readonly string[], rows: number): string[] {
   return lines.slice(0, rows);
 }
 
+function widgetHintTargetLineIndex(lines: readonly string[]): number {
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    if (!isWidgetBottomBorderLine(lines[index] ?? "")) return index;
+  }
+  return Math.max(0, lines.length - 1);
+}
+
+function isWidgetBottomBorderLine(line: string): boolean {
+  const plain = stripAnsi(line).trim();
+  const chars = Array.from(plain);
+  if (chars.length < 2) return false;
+  const first = chars[0] ?? "";
+  const last = chars.at(-1) ?? "";
+  if (!"╰└+".includes(first) || !"╯┘+".includes(last)) return false;
+  return chars.slice(1, -1).every((char) => "─═- ".includes(char));
+}
+
+function trailingWidgetBorderChar(line: string): string {
+  const plain = stripAnsi(line).trimEnd();
+  const last = Array.from(plain).at(-1) ?? "";
+  return "╯┘┤┴│|+".includes(last) ? last : "";
+}
+
 interface PaintOpts {
   bold?: boolean;
   italic?: boolean;

package/dist/builtin/workflows/src/tui/workflow-attach-pane.ts

@@ -5,8 +5,8 @@
  * between the orchestrator `GraphView` and a stage-scoped
  * `StageChatView`. Pressing Enter on a graph node attaches the popup
  * to that node's chat; Ctrl+D in chat mode swaps back to graph mode
- * with the same node still focused (see ui/attach-mockup.html), except
- * paused stage chats close the pane to mirror shell EOF semantics.
+ * with the same node still focused (see ui/attach-mockup.html), including
+ * paused stage chats.
  *
  * The shell never remounts the overlay — it only flips a `mode`
  * field and re-renders, so the popup stays in pi-tui's overlay layer

package/dist/core/system-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/core/system-prompt.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAyB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAWhE,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,wFAAwF;IACxF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,uCAAuC;IACvC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,+DAA+D;IAC/D,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gCAAgC;IAChC,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,yBAAyB;IACzB,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;CAClB;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CA0M3E","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.ts\";\nimport { formatSkillsForPrompt, type Skill } from \"./skills.ts\";\n\nconst DEFAULT_PROMPT_TOOLS = [\n  \"read\",\n  \"bash\",\n  \"edit\",\n  \"write\",\n  \"ask_user_question\",\n  \"todo\",\n] as const;\n\nexport interface SystemPromptModel {\n  /** Provider identifier for the selected model. */\n  provider: string;\n  /** Stable provider-specific model identifier. */\n  id: string;\n  /** Human-readable model name, when available. */\n  name?: string;\n}\n\nexport interface BuildSystemPromptOptions {\n  /** Custom system prompt (replaces default). */\n  customPrompt?: string;\n  /** Tools to include in prompt. Default: [read, bash, edit, write, ask_user_question, todo] */\n  selectedTools?: string[];\n  /** Tool names explicitly excluded by the caller and omitted from generated guidance. */\n  excludedTools?: string[];\n  /** Optional one-line tool snippets keyed by tool name. */\n  toolSnippets?: Record<string, string>;\n  /** Additional guideline bullets appended to the default system prompt guidelines. */\n  promptGuidelines?: string[];\n  /** Text to append to system prompt. */\n  appendSystemPrompt?: string;\n  /** Working directory. */\n  cwd: string;\n  /** Currently selected model, used for model-aware prompt metadata. */\n  selectedModel?: SystemPromptModel;\n  /** Current reasoning/thinking level for the selected model. */\n  selectedThinkingLevel?: string;\n  /** Pre-loaded context files. */\n  contextFiles?: Array<{ path: string; content: string }>;\n  /** Pre-loaded skills. */\n  skills?: Skill[];\n}\n\n/** Build the system prompt with tools, guidelines, and context */\nexport function buildSystemPrompt(options: BuildSystemPromptOptions): string {\n  const {\n    customPrompt,\n    selectedTools,\n    excludedTools,\n    toolSnippets,\n    promptGuidelines,\n    appendSystemPrompt,\n    cwd,\n    selectedModel,\n    selectedThinkingLevel,\n    contextFiles: providedContextFiles,\n    skills: providedSkills,\n  } = options;\n  const resolvedCwd = cwd;\n  const promptCwd = resolvedCwd.replace(/\\\\/g, \"/\");\n\n  const now = new Date();\n  const year = now.getFullYear();\n  const month = String(now.getMonth() + 1).padStart(2, \"0\");\n  const day = String(now.getDate()).padStart(2, \"0\");\n  const date = `${year}-${month}-${day}`;\n\n  const appendSection = appendSystemPrompt ? `\\n\\n${appendSystemPrompt}` : \"\";\n  const modelName =\n    selectedModel?.name?.trim() || selectedModel?.id || \"unknown\";\n  const modelReasoningLevel = selectedThinkingLevel?.trim() || \"off\";\n\n  const contextFiles = providedContextFiles ?? [];\n  const skills = providedSkills ?? [];\n  const explicitlyExcludedTools = new Set(excludedTools ?? []);\n  const isPromptToolAvailable = (name: string): boolean =>\n    (!selectedTools || selectedTools.includes(name)) &&\n    !explicitlyExcludedTools.has(name);\n\n  if (customPrompt) {\n    let prompt = customPrompt;\n\n    if (appendSection) {\n      prompt += appendSection;\n    }\n\n    // Append project context files\n    if (contextFiles.length > 0) {\n      prompt += \"\\n\\n# Project Context\\n\\n\";\n      prompt += \"Project-specific instructions and guidelines:\\n\\n\";\n      for (const { path: filePath, content } of contextFiles) {\n        prompt += `<context_file path=\\\"${filePath}\\\">\\n${content}\\n</context_file>\\n\\n`;\n      }\n    }\n\n    // Append skills section (only if read tool is available)\n    if (isPromptToolAvailable(\"read\") && skills.length > 0) {\n      prompt += formatSkillsForPrompt(skills);\n    }\n\n    // Add model metadata, date, and working directory last\n    prompt += `\\nModel name (used for commit attribution): ${modelName}`;\n    prompt += `\\nModel reasoning level: ${modelReasoningLevel}`;\n    prompt += `\\nCurrent date: ${date}`;\n    prompt += `\\nCurrent working directory: ${promptCwd}`;\n\n    return prompt;\n  }\n\n  // Get absolute paths to documentation and examples\n  const readmePath = getReadmePath();\n  const docsPath = getDocsPath();\n  const examplesPath = getExamplesPath();\n\n  // Build tools list based on selected tools.\n  // A tool appears in Available tools only when the caller provides a one-line snippet.\n  const tools = (selectedTools ?? DEFAULT_PROMPT_TOOLS).filter(\n    (name) => !explicitlyExcludedTools.has(name),\n  );\n  const visibleTools = tools.filter((name) => !!toolSnippets?.[name]);\n  const toolsList =\n    visibleTools.length > 0\n      ? visibleTools\n          .map((name) => `- ${name}: ${toolSnippets![name]}`)\n          .join(\"\\n\")\n      : \"(none)\";\n\n  // Build guidelines based on which tools are actually available\n  const guidelinesList: string[] = [];\n  const guidelinesSet = new Set<string>();\n  const addGuideline = (guideline: string): void => {\n    if (guidelinesSet.has(guideline)) {\n      return;\n    }\n    guidelinesSet.add(guideline);\n    guidelinesList.push(guideline);\n  };\n\n  const hasBash = tools.includes(\"bash\");\n  const hasGrep = tools.includes(\"grep\");\n  const hasFind = tools.includes(\"find\");\n  const hasLs = tools.includes(\"ls\");\n  const hasRead = tools.includes(\"read\");\n\n  // File exploration guidelines\n  if (hasBash && !hasGrep && !hasFind && !hasLs) {\n    addGuideline(\"Use bash for file operations like ls, rg, find\");\n  } else if (hasBash && (hasGrep || hasFind || hasLs)) {\n    addGuideline(\n      \"Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)\",\n    );\n  }\n\n  for (const guideline of promptGuidelines ?? []) {\n    const normalized = guideline.trim();\n    if (normalized.length > 0) {\n      addGuideline(normalized);\n    }\n  }\n\n  // Always include these\n  addGuideline(\"Be concise in your responses\");\n  addGuideline(\"Show file paths clearly when working with files\");\n\n  const guidelines = guidelinesList.map((g) => `- ${g}`).join(\"\\n\");\n\n  const askUserQuestionGuidance = explicitlyExcludedTools.has(\n    \"ask_user_question\",\n  )\n    ? \"\"\n    : \"- Always ask clarifying questions if the user's request is ambiguous or lacks necessary details. NEVER make assumptions about what the user wants. If you find yourself circling in thought and asking what the user \\\"really\\\" wants, stop and ask the user for clarification using the ask_user_question tool if available. It's better to clarify intent rather than to guess.\\n- **Asking the user is a strict requirement**: Whenever you need to ask the user anything — a clarification, a decision, a choice between options, a confirmation, or any yes/no question — you MUST ask it by calling the `ask_user_question` tool. Never pose a question to the user as plain assistant text. Every question you direct to the user goes through `ask_user_question`; writing the question in prose instead of calling the tool is not allowed.\";\n  const todoGuidance = explicitlyExcludedTools.has(\"todo\")\n    ? \"\"\n    : \"- **To-do management**: If the user has a complex task that can be broken down into actionable steps, use the `todo` tool to create a task list before proceeding. This ensures clarity and alignment with the user's goals and that you have a way to track your work and ensure you are meeting the user's expectations.\";\n\n  const subagentGuidance = explicitlyExcludedTools.has(\"subagent\")\n    ? \"\"\n    : `- **Subagent Orchestration**:\n  - To avoid draining your context window, prefer to use subagents for complex tasks all non-trivial operations should be delegated to subagents.\n  - You should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the \\`aws\\` CLI, using the \\`gh\\` CLI, digging through logs to \\`bash\\` subagents.\n  - You should use separate subagents for separate tasks, and you may launch them in parallel, but do not delegate multiple tasks that are likely to have significant overlap to separate subagents.\n  - Sometimes subagents will take a long time. DO NOT attempt to do the job yourself while waiting for the subagent to respond Instead, use the time to plan out your next steps.\n  - **Debugging**: When a user asks about debugging, spawn a debugger subagent first.\n    - Do not attempt to debug or analyze code yourself without first consulting the debugger subagent.\n    - Explain the debugger's insights to the user clearly and concisely.\n    - Once the user confirms, implement the necessary code changes based on those insights.\n    - If the user has follow-up questions, spawn additional debugger and research subagents as needed.`;\n\n  const workflowGuidance = explicitlyExcludedTools.has(\"workflow\")\n    ? \"\"\n    : `- **Workflows**: Use the \\`workflow\\` tool for existing named workflows and for repeatable, inspectable, resumable, or multi-stage processes; use direct \\`task\\`, \\`tasks\\`, or \\`chain\\` workflow calls for one-off tracked work when that is useful.\n  - For unfamiliar named workflows, discover with \\`action: \"list\"\\`, inspect with \\`action: \"get\"\\` or \\`action: \"inputs\"\\`, and run with \\`action: \"run\"\\`, \\`workflow\\`, and validated \\`inputs\\`; do not invent workflow names or input keys.\n  - Monitor long-running workflow runs through lifecycle notices and targeted \\`status\\`/\\`stages\\`/\\`stage\\` checks when you need new information; do not micro-manage every stage or create sleep/status polling loops.\n  - Use run-control and messaging actions (\\`send\\`, \\`pause\\`, \\`resume\\`, \\`interrupt\\`, \\`kill\\`) only when needed to answer prompts, steer a stage, resume or interrupt paused work, or respond to user requests/control signals.\n  - For transcripts, avoid reading whole session transcripts at once. Use \\`stages\\` or \\`stage\\` to get \\`sessionFile\\`/\\`transcriptPath\\`, quote the exact path without rewriting separators (preserve Windows backslashes), search it with \\`rg\\`/\\`grep\\`, and read small relevant ranges; use \\`transcript\\` with explicit \\`tail\\` or \\`limit\\` only for quick recent-context checks.\n  - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, and success criteria. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition.\n  - If you run \\`ralph\\` or \\`goal\\`, define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`;\n\n  let prompt = `You are an expert coding assistant operating named Atomic, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n${toolsList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelines}\n${askUserQuestionGuidance}\n${todoGuidance}\n${subagentGuidance}\n${workflowGuidance}\n\nAtomic documentation (read only when the user asks about customizing Atomic itself, its SDK, creating workflows, packages, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- Docs/examples references above must be resolved against these absolute roots; e.g. docs/foo.md means ${docsPath}/foo.md and examples/bar means ${examplesPath}/bar.\n- When asked about: atomic workflows (docs/workflows.md), extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), atomic packages (docs/packages.md)\n- When working on Atomic topics, read the docs and examples, and follow .md cross-references before implementing\n- Always read Atomic .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;\n\n  if (appendSection) {\n    prompt += appendSection;\n  }\n\n  // Append project context files\n  if (contextFiles.length > 0) {\n    prompt += \"\\n\\n# Project Context\\n\\n\";\n    prompt += \"Project-specific instructions and guidelines:\\n\\n\";\n    for (const { path: filePath, content } of contextFiles) {\n      prompt += `<context_file path=\\\"${filePath}\\\">\\n${content}\\n</context_file>\\n\\n`;\n    }\n  }\n\n  // Append skills section (only if read tool is available)\n  if (hasRead && skills.length > 0) {\n    prompt += formatSkillsForPrompt(skills);\n  }\n\n  // Add model metadata, date, and working directory last\n  prompt += `\\nModel name (used for commit attribution): ${modelName}`;\n  prompt += `\\nModel reasoning level: ${modelReasoningLevel}`;\n  prompt += `\\nCurrent date: ${date}`;\n  prompt += `\\nCurrent working directory: ${promptCwd}`;\n\n  return prompt;\n}\n"]}
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/core/system-prompt.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAyB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAWhE,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,wFAAwF;IACxF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,uCAAuC;IACvC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,+DAA+D;IAC/D,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gCAAgC;IAChC,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,yBAAyB;IACzB,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;CAClB;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CA8M3E","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.ts\";\nimport { formatSkillsForPrompt, type Skill } from \"./skills.ts\";\n\nconst DEFAULT_PROMPT_TOOLS = [\n  \"read\",\n  \"bash\",\n  \"edit\",\n  \"write\",\n  \"ask_user_question\",\n  \"todo\",\n] as const;\n\nexport interface SystemPromptModel {\n  /** Provider identifier for the selected model. */\n  provider: string;\n  /** Stable provider-specific model identifier. */\n  id: string;\n  /** Human-readable model name, when available. */\n  name?: string;\n}\n\nexport interface BuildSystemPromptOptions {\n  /** Custom system prompt (replaces default). */\n  customPrompt?: string;\n  /** Tools to include in prompt. Default: [read, bash, edit, write, ask_user_question, todo] */\n  selectedTools?: string[];\n  /** Tool names explicitly excluded by the caller and omitted from generated guidance. */\n  excludedTools?: string[];\n  /** Optional one-line tool snippets keyed by tool name. */\n  toolSnippets?: Record<string, string>;\n  /** Additional guideline bullets appended to the default system prompt guidelines. */\n  promptGuidelines?: string[];\n  /** Text to append to system prompt. */\n  appendSystemPrompt?: string;\n  /** Working directory. */\n  cwd: string;\n  /** Currently selected model, used for model-aware prompt metadata. */\n  selectedModel?: SystemPromptModel;\n  /** Current reasoning/thinking level for the selected model. */\n  selectedThinkingLevel?: string;\n  /** Pre-loaded context files. */\n  contextFiles?: Array<{ path: string; content: string }>;\n  /** Pre-loaded skills. */\n  skills?: Skill[];\n}\n\n/** Build the system prompt with tools, guidelines, and context */\nexport function buildSystemPrompt(options: BuildSystemPromptOptions): string {\n  const {\n    customPrompt,\n    selectedTools,\n    excludedTools,\n    toolSnippets,\n    promptGuidelines,\n    appendSystemPrompt,\n    cwd,\n    selectedModel,\n    selectedThinkingLevel,\n    contextFiles: providedContextFiles,\n    skills: providedSkills,\n  } = options;\n  const resolvedCwd = cwd;\n  const promptCwd = resolvedCwd.replace(/\\\\/g, \"/\");\n\n  const now = new Date();\n  const year = now.getFullYear();\n  const month = String(now.getMonth() + 1).padStart(2, \"0\");\n  const day = String(now.getDate()).padStart(2, \"0\");\n  const date = `${year}-${month}-${day}`;\n\n  const appendSection = appendSystemPrompt ? `\\n\\n${appendSystemPrompt}` : \"\";\n  const modelName =\n    selectedModel?.name?.trim() || selectedModel?.id || \"unknown\";\n  const modelReasoningLevel = selectedThinkingLevel?.trim() || \"off\";\n\n  const contextFiles = providedContextFiles ?? [];\n  const skills = providedSkills ?? [];\n  const explicitlyExcludedTools = new Set(excludedTools ?? []);\n  const isPromptToolAvailable = (name: string): boolean =>\n    (!selectedTools || selectedTools.includes(name)) &&\n    !explicitlyExcludedTools.has(name);\n\n  if (customPrompt) {\n    let prompt = customPrompt;\n\n    if (appendSection) {\n      prompt += appendSection;\n    }\n\n    // Append project context files\n    if (contextFiles.length > 0) {\n      prompt += \"\\n\\n# Project Context\\n\\n\";\n      prompt += \"Project-specific instructions and guidelines:\\n\\n\";\n      for (const { path: filePath, content } of contextFiles) {\n        prompt += `<context_file path=\\\"${filePath}\\\">\\n${content}\\n</context_file>\\n\\n`;\n      }\n    }\n\n    // Append skills section (only if read tool is available)\n    if (isPromptToolAvailable(\"read\") && skills.length > 0) {\n      prompt += formatSkillsForPrompt(skills);\n    }\n\n    // Add model metadata, date, and working directory last\n    prompt += `\\nModel name (used for commit attribution): ${modelName}`;\n    prompt += `\\nModel reasoning level: ${modelReasoningLevel}`;\n    prompt += `\\nCurrent date: ${date}`;\n    prompt += `\\nCurrent working directory: ${promptCwd}`;\n\n    return prompt;\n  }\n\n  // Get absolute paths to documentation and examples\n  const readmePath = getReadmePath();\n  const docsPath = getDocsPath();\n  const examplesPath = getExamplesPath();\n\n  // Build tools list based on selected tools.\n  // A tool appears in Available tools only when the caller provides a one-line snippet.\n  const tools = (selectedTools ?? DEFAULT_PROMPT_TOOLS).filter(\n    (name) => !explicitlyExcludedTools.has(name),\n  );\n  const visibleTools = tools.filter((name) => !!toolSnippets?.[name]);\n  const toolsList =\n    visibleTools.length > 0\n      ? visibleTools\n          .map((name) => `- ${name}: ${toolSnippets![name]}`)\n          .join(\"\\n\")\n      : \"(none)\";\n\n  // Build guidelines based on which tools are actually available\n  const guidelinesList: string[] = [];\n  const guidelinesSet = new Set<string>();\n  const addGuideline = (guideline: string): void => {\n    if (guidelinesSet.has(guideline)) {\n      return;\n    }\n    guidelinesSet.add(guideline);\n    guidelinesList.push(guideline);\n  };\n\n  const hasBash = tools.includes(\"bash\");\n  const hasGrep = tools.includes(\"grep\");\n  const hasFind = tools.includes(\"find\");\n  const hasLs = tools.includes(\"ls\");\n  const hasRead = tools.includes(\"read\");\n\n  // File exploration guidelines\n  if (hasBash && !hasGrep && !hasFind && !hasLs) {\n    addGuideline(\"Use bash for file operations like ls, rg, find\");\n  } else if (hasBash && (hasGrep || hasFind || hasLs)) {\n    addGuideline(\n      \"Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)\",\n    );\n  }\n\n  for (const guideline of promptGuidelines ?? []) {\n    const normalized = guideline.trim();\n    if (normalized.length > 0) {\n      addGuideline(normalized);\n    }\n  }\n\n  // Always include these\n  addGuideline(\"Be concise in your responses\");\n  addGuideline(\"Show file paths clearly when working with files\");\n\n  const guidelines = guidelinesList.map((g) => `- ${g}`).join(\"\\n\");\n\n  const askUserQuestionGuidance = explicitlyExcludedTools.has(\n    \"ask_user_question\",\n  )\n    ? \"\"\n    : \"- Always ask clarifying questions if the user's request is ambiguous or lacks necessary details. NEVER make assumptions about what the user wants. If you find yourself circling in thought and asking what the user \\\"really\\\" wants, stop and ask the user for clarification using the ask_user_question tool if available. It's better to clarify intent rather than to guess.\\n- **Asking the user is a strict requirement**: Whenever you need to ask the user anything — a clarification, a decision, a choice between options, a confirmation, or any yes/no question — you MUST ask it by calling the `ask_user_question` tool. Never pose a question to the user as plain assistant text. Every question you direct to the user goes through `ask_user_question`; writing the question in prose instead of calling the tool is not allowed.\";\n  const todoGuidance = explicitlyExcludedTools.has(\"todo\")\n    ? \"\"\n    : \"- **To-do management**: If the user has a complex task that can be broken down into actionable steps, use the `todo` tool to create a task list before proceeding. This ensures clarity and alignment with the user's goals and that you have a way to track your work and ensure you are meeting the user's expectations.\";\n\n  const subagentGuidance = explicitlyExcludedTools.has(\"subagent\")\n    ? \"\"\n    : `- **Subagent Orchestration**:\n  - To avoid draining your context window, prefer to use subagents for complex tasks all non-trivial operations should be delegated to subagents.\n  - You should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the \\`aws\\` CLI, using the \\`gh\\` CLI, digging through logs to \\`bash\\` subagents.\n  - You should use separate subagents for separate tasks, and you may launch them in parallel, but do not delegate multiple tasks that are likely to have significant overlap to separate subagents.\n  - Sometimes subagents will take a long time. DO NOT attempt to do the job yourself while waiting for the subagent to respond Instead, use the time to plan out your next steps.\n  - **Debugging**: When a user asks about debugging, spawn a debugger subagent first.\n    - Do not attempt to debug or analyze code yourself without first consulting the debugger subagent.\n    - Explain the debugger's insights to the user clearly and concisely.\n    - Once the user confirms, implement the necessary code changes based on those insights.\n    - If the user has follow-up questions, spawn additional debugger and research subagents as needed.`;\n\n  const workflowGuidance = explicitlyExcludedTools.has(\"workflow\")\n    ? \"\"\n    : `- **Workflows**: Use the \\`workflow\\` tool for existing named workflows and for repeatable, inspectable, resumable, or multi-stage processes; use direct \\`task\\`, \\`tasks\\`, or \\`chain\\` workflow calls for one-off tracked work when that is useful.\n  - For unfamiliar named workflows, discover with \\`action: \"list\"\\`, inspect with \\`action: \"get\"\\` or \\`action: \"inputs\"\\`, and run with \\`action: \"run\"\\`, \\`workflow\\`, and validated \\`inputs\\`; do not invent workflow names or input keys.\n  - Once you run a workflow with the workflow tool, end your current turn and wait for the next user input or lifecycle notice.\n    - You will automatically be alerted of key lifecycle events like start, finish, failure; do not attempt to track its progress yourself or read its logs or stages unless the user asks you to or you need to check in on it to get information for the next step.\n    - If the user needs information from the workflow run, use \\`status\\`, \\`stages\\`, or \\`stage\\` calls to get targeted information instead of trying to read everything.\n    - Offer to help the user on another task instead of anxiously polling or help the user run another workflow if they need.\n    - Use run-control and messaging actions (\\`send\\`, \\`pause\\`, \\`resume\\`, \\`interrupt\\`, \\`kill\\`) only when needed to answer prompts, steer a stage, resume or interrupt paused work, or respond to user requests/control signals.\n  - For transcripts, avoid reading whole session transcripts at once. Use \\`stages\\` or \\`stage\\` to get \\`sessionFile\\`/\\`transcriptPath\\`, quote the exact path without rewriting separators (preserve Windows backslashes), search it with \\`rg\\`/\\`grep\\`, and read small relevant ranges; use \\`transcript\\` with explicit \\`tail\\` or \\`limit\\` only for quick recent-context checks.\n  - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, and success criteria. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition. After you implement the workflow, reload it to access it and run it with test inputs to validate it works as intended before presenting it to the user.\n    - Tip: when designing workflows, implement it in a way that you pass information from stage to stage by writing it to a file or artifact (either deterministic or model-driven), pass the path with \\`reads\\`, and explicitly prompt the downstream agent with wording like \\`Read the file at <path>...\\`; do not inject large \\`previous\\` payloads or session history into the next prompt unless explicitly requested to.\n  - If you run \\`ralph\\` or \\`goal\\` workflow, define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`;\n\n  let prompt = `You are an expert coding assistant operating named Atomic, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n${toolsList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelines}\n${askUserQuestionGuidance}\n${todoGuidance}\n${subagentGuidance}\n${workflowGuidance}\n\nAtomic documentation (read only when the user asks about customizing Atomic itself, its SDK, creating workflows, packages, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- Docs/examples references above must be resolved against these absolute roots; e.g. docs/foo.md means ${docsPath}/foo.md and examples/bar means ${examplesPath}/bar.\n- When asked about: atomic workflows (docs/workflows.md), extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), atomic packages (docs/packages.md)\n- When working on Atomic topics, read the docs and examples, and follow .md cross-references before implementing\n- Always read Atomic .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;\n\n  if (appendSection) {\n    prompt += appendSection;\n  }\n\n  // Append project context files\n  if (contextFiles.length > 0) {\n    prompt += \"\\n\\n# Project Context\\n\\n\";\n    prompt += \"Project-specific instructions and guidelines:\\n\\n\";\n    for (const { path: filePath, content } of contextFiles) {\n      prompt += `<context_file path=\\\"${filePath}\\\">\\n${content}\\n</context_file>\\n\\n`;\n    }\n  }\n\n  // Append skills section (only if read tool is available)\n  if (hasRead && skills.length > 0) {\n    prompt += formatSkillsForPrompt(skills);\n  }\n\n  // Add model metadata, date, and working directory last\n  prompt += `\\nModel name (used for commit attribution): ${modelName}`;\n  prompt += `\\nModel reasoning level: ${modelReasoningLevel}`;\n  prompt += `\\nCurrent date: ${date}`;\n  prompt += `\\nCurrent working directory: ${promptCwd}`;\n\n  return prompt;\n}\n"]}

package/dist/core/system-prompt.js

@@ -120,11 +120,15 @@ export function buildSystemPrompt(options) {
         ? ""
         : `- **Workflows**: Use the \`workflow\` tool for existing named workflows and for repeatable, inspectable, resumable, or multi-stage processes; use direct \`task\`, \`tasks\`, or \`chain\` workflow calls for one-off tracked work when that is useful.
   - For unfamiliar named workflows, discover with \`action: "list"\`, inspect with \`action: "get"\` or \`action: "inputs"\`, and run with \`action: "run"\`, \`workflow\`, and validated \`inputs\`; do not invent workflow names or input keys.
-  - Monitor long-running workflow runs through lifecycle notices and targeted \`status\`/\`stages\`/\`stage\` checks when you need new information; do not micro-manage every stage or create sleep/status polling loops.
-  - Use run-control and messaging actions (\`send\`, \`pause\`, \`resume\`, \`interrupt\`, \`kill\`) only when needed to answer prompts, steer a stage, resume or interrupt paused work, or respond to user requests/control signals.
+  - Once you run a workflow with the workflow tool, end your current turn and wait for the next user input or lifecycle notice.
+    - You will automatically be alerted of key lifecycle events like start, finish, failure; do not attempt to track its progress yourself or read its logs or stages unless the user asks you to or you need to check in on it to get information for the next step.
+    - If the user needs information from the workflow run, use \`status\`, \`stages\`, or \`stage\` calls to get targeted information instead of trying to read everything.
+    - Offer to help the user on another task instead of anxiously polling or help the user run another workflow if they need.
+    - Use run-control and messaging actions (\`send\`, \`pause\`, \`resume\`, \`interrupt\`, \`kill\`) only when needed to answer prompts, steer a stage, resume or interrupt paused work, or respond to user requests/control signals.
   - For transcripts, avoid reading whole session transcripts at once. Use \`stages\` or \`stage\` to get \`sessionFile\`/\`transcriptPath\`, quote the exact path without rewriting separators (preserve Windows backslashes), search it with \`rg\`/\`grep\`, and read small relevant ranges; use \`transcript\` with explicit \`tail\` or \`limit\` only for quick recent-context checks.
-  - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, and success criteria. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition.
-  - If you run \`ralph\` or \`goal\`, define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`;
+  - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, and success criteria. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition. After you implement the workflow, reload it to access it and run it with test inputs to validate it works as intended before presenting it to the user.
+    - Tip: when designing workflows, implement it in a way that you pass information from stage to stage by writing it to a file or artifact (either deterministic or model-driven), pass the path with \`reads\`, and explicitly prompt the downstream agent with wording like \`Read the file at <path>...\`; do not inject large \`previous\` payloads or session history into the next prompt unless explicitly requested to.
+  - If you run \`ralph\` or \`goal\` workflow, define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`;
     let prompt = `You are an expert coding assistant operating named Atomic, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
 
 Available tools:

package/dist/core/system-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/core/system-prompt.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.ts\";\nimport { formatSkillsForPrompt, type Skill } from \"./skills.ts\";\n\nconst DEFAULT_PROMPT_TOOLS = [\n  \"read\",\n  \"bash\",\n  \"edit\",\n  \"write\",\n  \"ask_user_question\",\n  \"todo\",\n] as const;\n\nexport interface SystemPromptModel {\n  /** Provider identifier for the selected model. */\n  provider: string;\n  /** Stable provider-specific model identifier. */\n  id: string;\n  /** Human-readable model name, when available. */\n  name?: string;\n}\n\nexport interface BuildSystemPromptOptions {\n  /** Custom system prompt (replaces default). */\n  customPrompt?: string;\n  /** Tools to include in prompt. Default: [read, bash, edit, write, ask_user_question, todo] */\n  selectedTools?: string[];\n  /** Tool names explicitly excluded by the caller and omitted from generated guidance. */\n  excludedTools?: string[];\n  /** Optional one-line tool snippets keyed by tool name. */\n  toolSnippets?: Record<string, string>;\n  /** Additional guideline bullets appended to the default system prompt guidelines. */\n  promptGuidelines?: string[];\n  /** Text to append to system prompt. */\n  appendSystemPrompt?: string;\n  /** Working directory. */\n  cwd: string;\n  /** Currently selected model, used for model-aware prompt metadata. */\n  selectedModel?: SystemPromptModel;\n  /** Current reasoning/thinking level for the selected model. */\n  selectedThinkingLevel?: string;\n  /** Pre-loaded context files. */\n  contextFiles?: Array<{ path: string; content: string }>;\n  /** Pre-loaded skills. */\n  skills?: Skill[];\n}\n\n/** Build the system prompt with tools, guidelines, and context */\nexport function buildSystemPrompt(options: BuildSystemPromptOptions): string {\n  const {\n    customPrompt,\n    selectedTools,\n    excludedTools,\n    toolSnippets,\n    promptGuidelines,\n    appendSystemPrompt,\n    cwd,\n    selectedModel,\n    selectedThinkingLevel,\n    contextFiles: providedContextFiles,\n    skills: providedSkills,\n  } = options;\n  const resolvedCwd = cwd;\n  const promptCwd = resolvedCwd.replace(/\\\\/g, \"/\");\n\n  const now = new Date();\n  const year = now.getFullYear();\n  const month = String(now.getMonth() + 1).padStart(2, \"0\");\n  const day = String(now.getDate()).padStart(2, \"0\");\n  const date = `${year}-${month}-${day}`;\n\n  const appendSection = appendSystemPrompt ? `\\n\\n${appendSystemPrompt}` : \"\";\n  const modelName =\n    selectedModel?.name?.trim() || selectedModel?.id || \"unknown\";\n  const modelReasoningLevel = selectedThinkingLevel?.trim() || \"off\";\n\n  const contextFiles = providedContextFiles ?? [];\n  const skills = providedSkills ?? [];\n  const explicitlyExcludedTools = new Set(excludedTools ?? []);\n  const isPromptToolAvailable = (name: string): boolean =>\n    (!selectedTools || selectedTools.includes(name)) &&\n    !explicitlyExcludedTools.has(name);\n\n  if (customPrompt) {\n    let prompt = customPrompt;\n\n    if (appendSection) {\n      prompt += appendSection;\n    }\n\n    // Append project context files\n    if (contextFiles.length > 0) {\n      prompt += \"\\n\\n# Project Context\\n\\n\";\n      prompt += \"Project-specific instructions and guidelines:\\n\\n\";\n      for (const { path: filePath, content } of contextFiles) {\n        prompt += `<context_file path=\\\"${filePath}\\\">\\n${content}\\n</context_file>\\n\\n`;\n      }\n    }\n\n    // Append skills section (only if read tool is available)\n    if (isPromptToolAvailable(\"read\") && skills.length > 0) {\n      prompt += formatSkillsForPrompt(skills);\n    }\n\n    // Add model metadata, date, and working directory last\n    prompt += `\\nModel name (used for commit attribution): ${modelName}`;\n    prompt += `\\nModel reasoning level: ${modelReasoningLevel}`;\n    prompt += `\\nCurrent date: ${date}`;\n    prompt += `\\nCurrent working directory: ${promptCwd}`;\n\n    return prompt;\n  }\n\n  // Get absolute paths to documentation and examples\n  const readmePath = getReadmePath();\n  const docsPath = getDocsPath();\n  const examplesPath = getExamplesPath();\n\n  // Build tools list based on selected tools.\n  // A tool appears in Available tools only when the caller provides a one-line snippet.\n  const tools = (selectedTools ?? DEFAULT_PROMPT_TOOLS).filter(\n    (name) => !explicitlyExcludedTools.has(name),\n  );\n  const visibleTools = tools.filter((name) => !!toolSnippets?.[name]);\n  const toolsList =\n    visibleTools.length > 0\n      ? visibleTools\n          .map((name) => `- ${name}: ${toolSnippets![name]}`)\n          .join(\"\\n\")\n      : \"(none)\";\n\n  // Build guidelines based on which tools are actually available\n  const guidelinesList: string[] = [];\n  const guidelinesSet = new Set<string>();\n  const addGuideline = (guideline: string): void => {\n    if (guidelinesSet.has(guideline)) {\n      return;\n    }\n    guidelinesSet.add(guideline);\n    guidelinesList.push(guideline);\n  };\n\n  const hasBash = tools.includes(\"bash\");\n  const hasGrep = tools.includes(\"grep\");\n  const hasFind = tools.includes(\"find\");\n  const hasLs = tools.includes(\"ls\");\n  const hasRead = tools.includes(\"read\");\n\n  // File exploration guidelines\n  if (hasBash && !hasGrep && !hasFind && !hasLs) {\n    addGuideline(\"Use bash for file operations like ls, rg, find\");\n  } else if (hasBash && (hasGrep || hasFind || hasLs)) {\n    addGuideline(\n      \"Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)\",\n    );\n  }\n\n  for (const guideline of promptGuidelines ?? []) {\n    const normalized = guideline.trim();\n    if (normalized.length > 0) {\n      addGuideline(normalized);\n    }\n  }\n\n  // Always include these\n  addGuideline(\"Be concise in your responses\");\n  addGuideline(\"Show file paths clearly when working with files\");\n\n  const guidelines = guidelinesList.map((g) => `- ${g}`).join(\"\\n\");\n\n  const askUserQuestionGuidance = explicitlyExcludedTools.has(\n    \"ask_user_question\",\n  )\n    ? \"\"\n    : \"- Always ask clarifying questions if the user's request is ambiguous or lacks necessary details. NEVER make assumptions about what the user wants. If you find yourself circling in thought and asking what the user \\\"really\\\" wants, stop and ask the user for clarification using the ask_user_question tool if available. It's better to clarify intent rather than to guess.\\n- **Asking the user is a strict requirement**: Whenever you need to ask the user anything — a clarification, a decision, a choice between options, a confirmation, or any yes/no question — you MUST ask it by calling the `ask_user_question` tool. Never pose a question to the user as plain assistant text. Every question you direct to the user goes through `ask_user_question`; writing the question in prose instead of calling the tool is not allowed.\";\n  const todoGuidance = explicitlyExcludedTools.has(\"todo\")\n    ? \"\"\n    : \"- **To-do management**: If the user has a complex task that can be broken down into actionable steps, use the `todo` tool to create a task list before proceeding. This ensures clarity and alignment with the user's goals and that you have a way to track your work and ensure you are meeting the user's expectations.\";\n\n  const subagentGuidance = explicitlyExcludedTools.has(\"subagent\")\n    ? \"\"\n    : `- **Subagent Orchestration**:\n  - To avoid draining your context window, prefer to use subagents for complex tasks all non-trivial operations should be delegated to subagents.\n  - You should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the \\`aws\\` CLI, using the \\`gh\\` CLI, digging through logs to \\`bash\\` subagents.\n  - You should use separate subagents for separate tasks, and you may launch them in parallel, but do not delegate multiple tasks that are likely to have significant overlap to separate subagents.\n  - Sometimes subagents will take a long time. DO NOT attempt to do the job yourself while waiting for the subagent to respond Instead, use the time to plan out your next steps.\n  - **Debugging**: When a user asks about debugging, spawn a debugger subagent first.\n    - Do not attempt to debug or analyze code yourself without first consulting the debugger subagent.\n    - Explain the debugger's insights to the user clearly and concisely.\n    - Once the user confirms, implement the necessary code changes based on those insights.\n    - If the user has follow-up questions, spawn additional debugger and research subagents as needed.`;\n\n  const workflowGuidance = explicitlyExcludedTools.has(\"workflow\")\n    ? \"\"\n    : `- **Workflows**: Use the \\`workflow\\` tool for existing named workflows and for repeatable, inspectable, resumable, or multi-stage processes; use direct \\`task\\`, \\`tasks\\`, or \\`chain\\` workflow calls for one-off tracked work when that is useful.\n  - For unfamiliar named workflows, discover with \\`action: \"list\"\\`, inspect with \\`action: \"get\"\\` or \\`action: \"inputs\"\\`, and run with \\`action: \"run\"\\`, \\`workflow\\`, and validated \\`inputs\\`; do not invent workflow names or input keys.\n  - Monitor long-running workflow runs through lifecycle notices and targeted \\`status\\`/\\`stages\\`/\\`stage\\` checks when you need new information; do not micro-manage every stage or create sleep/status polling loops.\n  - Use run-control and messaging actions (\\`send\\`, \\`pause\\`, \\`resume\\`, \\`interrupt\\`, \\`kill\\`) only when needed to answer prompts, steer a stage, resume or interrupt paused work, or respond to user requests/control signals.\n  - For transcripts, avoid reading whole session transcripts at once. Use \\`stages\\` or \\`stage\\` to get \\`sessionFile\\`/\\`transcriptPath\\`, quote the exact path without rewriting separators (preserve Windows backslashes), search it with \\`rg\\`/\\`grep\\`, and read small relevant ranges; use \\`transcript\\` with explicit \\`tail\\` or \\`limit\\` only for quick recent-context checks.\n  - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, and success criteria. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition.\n  - If you run \\`ralph\\` or \\`goal\\`, define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`;\n\n  let prompt = `You are an expert coding assistant operating named Atomic, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n${toolsList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelines}\n${askUserQuestionGuidance}\n${todoGuidance}\n${subagentGuidance}\n${workflowGuidance}\n\nAtomic documentation (read only when the user asks about customizing Atomic itself, its SDK, creating workflows, packages, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- Docs/examples references above must be resolved against these absolute roots; e.g. docs/foo.md means ${docsPath}/foo.md and examples/bar means ${examplesPath}/bar.\n- When asked about: atomic workflows (docs/workflows.md), extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), atomic packages (docs/packages.md)\n- When working on Atomic topics, read the docs and examples, and follow .md cross-references before implementing\n- Always read Atomic .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;\n\n  if (appendSection) {\n    prompt += appendSection;\n  }\n\n  // Append project context files\n  if (contextFiles.length > 0) {\n    prompt += \"\\n\\n# Project Context\\n\\n\";\n    prompt += \"Project-specific instructions and guidelines:\\n\\n\";\n    for (const { path: filePath, content } of contextFiles) {\n      prompt += `<context_file path=\\\"${filePath}\\\">\\n${content}\\n</context_file>\\n\\n`;\n    }\n  }\n\n  // Append skills section (only if read tool is available)\n  if (hasRead && skills.length > 0) {\n    prompt += formatSkillsForPrompt(skills);\n  }\n\n  // Add model metadata, date, and working directory last\n  prompt += `\\nModel name (used for commit attribution): ${modelName}`;\n  prompt += `\\nModel reasoning level: ${modelReasoningLevel}`;\n  prompt += `\\nCurrent date: ${date}`;\n  prompt += `\\nCurrent working directory: ${promptCwd}`;\n\n  return prompt;\n}\n"]}
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/core/system-prompt.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.ts\";\nimport { formatSkillsForPrompt, type Skill } from \"./skills.ts\";\n\nconst DEFAULT_PROMPT_TOOLS = [\n  \"read\",\n  \"bash\",\n  \"edit\",\n  \"write\",\n  \"ask_user_question\",\n  \"todo\",\n] as const;\n\nexport interface SystemPromptModel {\n  /** Provider identifier for the selected model. */\n  provider: string;\n  /** Stable provider-specific model identifier. */\n  id: string;\n  /** Human-readable model name, when available. */\n  name?: string;\n}\n\nexport interface BuildSystemPromptOptions {\n  /** Custom system prompt (replaces default). */\n  customPrompt?: string;\n  /** Tools to include in prompt. Default: [read, bash, edit, write, ask_user_question, todo] */\n  selectedTools?: string[];\n  /** Tool names explicitly excluded by the caller and omitted from generated guidance. */\n  excludedTools?: string[];\n  /** Optional one-line tool snippets keyed by tool name. */\n  toolSnippets?: Record<string, string>;\n  /** Additional guideline bullets appended to the default system prompt guidelines. */\n  promptGuidelines?: string[];\n  /** Text to append to system prompt. */\n  appendSystemPrompt?: string;\n  /** Working directory. */\n  cwd: string;\n  /** Currently selected model, used for model-aware prompt metadata. */\n  selectedModel?: SystemPromptModel;\n  /** Current reasoning/thinking level for the selected model. */\n  selectedThinkingLevel?: string;\n  /** Pre-loaded context files. */\n  contextFiles?: Array<{ path: string; content: string }>;\n  /** Pre-loaded skills. */\n  skills?: Skill[];\n}\n\n/** Build the system prompt with tools, guidelines, and context */\nexport function buildSystemPrompt(options: BuildSystemPromptOptions): string {\n  const {\n    customPrompt,\n    selectedTools,\n    excludedTools,\n    toolSnippets,\n    promptGuidelines,\n    appendSystemPrompt,\n    cwd,\n    selectedModel,\n    selectedThinkingLevel,\n    contextFiles: providedContextFiles,\n    skills: providedSkills,\n  } = options;\n  const resolvedCwd = cwd;\n  const promptCwd = resolvedCwd.replace(/\\\\/g, \"/\");\n\n  const now = new Date();\n  const year = now.getFullYear();\n  const month = String(now.getMonth() + 1).padStart(2, \"0\");\n  const day = String(now.getDate()).padStart(2, \"0\");\n  const date = `${year}-${month}-${day}`;\n\n  const appendSection = appendSystemPrompt ? `\\n\\n${appendSystemPrompt}` : \"\";\n  const modelName =\n    selectedModel?.name?.trim() || selectedModel?.id || \"unknown\";\n  const modelReasoningLevel = selectedThinkingLevel?.trim() || \"off\";\n\n  const contextFiles = providedContextFiles ?? [];\n  const skills = providedSkills ?? [];\n  const explicitlyExcludedTools = new Set(excludedTools ?? []);\n  const isPromptToolAvailable = (name: string): boolean =>\n    (!selectedTools || selectedTools.includes(name)) &&\n    !explicitlyExcludedTools.has(name);\n\n  if (customPrompt) {\n    let prompt = customPrompt;\n\n    if (appendSection) {\n      prompt += appendSection;\n    }\n\n    // Append project context files\n    if (contextFiles.length > 0) {\n      prompt += \"\\n\\n# Project Context\\n\\n\";\n      prompt += \"Project-specific instructions and guidelines:\\n\\n\";\n      for (const { path: filePath, content } of contextFiles) {\n        prompt += `<context_file path=\\\"${filePath}\\\">\\n${content}\\n</context_file>\\n\\n`;\n      }\n    }\n\n    // Append skills section (only if read tool is available)\n    if (isPromptToolAvailable(\"read\") && skills.length > 0) {\n      prompt += formatSkillsForPrompt(skills);\n    }\n\n    // Add model metadata, date, and working directory last\n    prompt += `\\nModel name (used for commit attribution): ${modelName}`;\n    prompt += `\\nModel reasoning level: ${modelReasoningLevel}`;\n    prompt += `\\nCurrent date: ${date}`;\n    prompt += `\\nCurrent working directory: ${promptCwd}`;\n\n    return prompt;\n  }\n\n  // Get absolute paths to documentation and examples\n  const readmePath = getReadmePath();\n  const docsPath = getDocsPath();\n  const examplesPath = getExamplesPath();\n\n  // Build tools list based on selected tools.\n  // A tool appears in Available tools only when the caller provides a one-line snippet.\n  const tools = (selectedTools ?? DEFAULT_PROMPT_TOOLS).filter(\n    (name) => !explicitlyExcludedTools.has(name),\n  );\n  const visibleTools = tools.filter((name) => !!toolSnippets?.[name]);\n  const toolsList =\n    visibleTools.length > 0\n      ? visibleTools\n          .map((name) => `- ${name}: ${toolSnippets![name]}`)\n          .join(\"\\n\")\n      : \"(none)\";\n\n  // Build guidelines based on which tools are actually available\n  const guidelinesList: string[] = [];\n  const guidelinesSet = new Set<string>();\n  const addGuideline = (guideline: string): void => {\n    if (guidelinesSet.has(guideline)) {\n      return;\n    }\n    guidelinesSet.add(guideline);\n    guidelinesList.push(guideline);\n  };\n\n  const hasBash = tools.includes(\"bash\");\n  const hasGrep = tools.includes(\"grep\");\n  const hasFind = tools.includes(\"find\");\n  const hasLs = tools.includes(\"ls\");\n  const hasRead = tools.includes(\"read\");\n\n  // File exploration guidelines\n  if (hasBash && !hasGrep && !hasFind && !hasLs) {\n    addGuideline(\"Use bash for file operations like ls, rg, find\");\n  } else if (hasBash && (hasGrep || hasFind || hasLs)) {\n    addGuideline(\n      \"Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)\",\n    );\n  }\n\n  for (const guideline of promptGuidelines ?? []) {\n    const normalized = guideline.trim();\n    if (normalized.length > 0) {\n      addGuideline(normalized);\n    }\n  }\n\n  // Always include these\n  addGuideline(\"Be concise in your responses\");\n  addGuideline(\"Show file paths clearly when working with files\");\n\n  const guidelines = guidelinesList.map((g) => `- ${g}`).join(\"\\n\");\n\n  const askUserQuestionGuidance = explicitlyExcludedTools.has(\n    \"ask_user_question\",\n  )\n    ? \"\"\n    : \"- Always ask clarifying questions if the user's request is ambiguous or lacks necessary details. NEVER make assumptions about what the user wants. If you find yourself circling in thought and asking what the user \\\"really\\\" wants, stop and ask the user for clarification using the ask_user_question tool if available. It's better to clarify intent rather than to guess.\\n- **Asking the user is a strict requirement**: Whenever you need to ask the user anything — a clarification, a decision, a choice between options, a confirmation, or any yes/no question — you MUST ask it by calling the `ask_user_question` tool. Never pose a question to the user as plain assistant text. Every question you direct to the user goes through `ask_user_question`; writing the question in prose instead of calling the tool is not allowed.\";\n  const todoGuidance = explicitlyExcludedTools.has(\"todo\")\n    ? \"\"\n    : \"- **To-do management**: If the user has a complex task that can be broken down into actionable steps, use the `todo` tool to create a task list before proceeding. This ensures clarity and alignment with the user's goals and that you have a way to track your work and ensure you are meeting the user's expectations.\";\n\n  const subagentGuidance = explicitlyExcludedTools.has(\"subagent\")\n    ? \"\"\n    : `- **Subagent Orchestration**:\n  - To avoid draining your context window, prefer to use subagents for complex tasks all non-trivial operations should be delegated to subagents.\n  - You should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the \\`aws\\` CLI, using the \\`gh\\` CLI, digging through logs to \\`bash\\` subagents.\n  - You should use separate subagents for separate tasks, and you may launch them in parallel, but do not delegate multiple tasks that are likely to have significant overlap to separate subagents.\n  - Sometimes subagents will take a long time. DO NOT attempt to do the job yourself while waiting for the subagent to respond Instead, use the time to plan out your next steps.\n  - **Debugging**: When a user asks about debugging, spawn a debugger subagent first.\n    - Do not attempt to debug or analyze code yourself without first consulting the debugger subagent.\n    - Explain the debugger's insights to the user clearly and concisely.\n    - Once the user confirms, implement the necessary code changes based on those insights.\n    - If the user has follow-up questions, spawn additional debugger and research subagents as needed.`;\n\n  const workflowGuidance = explicitlyExcludedTools.has(\"workflow\")\n    ? \"\"\n    : `- **Workflows**: Use the \\`workflow\\` tool for existing named workflows and for repeatable, inspectable, resumable, or multi-stage processes; use direct \\`task\\`, \\`tasks\\`, or \\`chain\\` workflow calls for one-off tracked work when that is useful.\n  - For unfamiliar named workflows, discover with \\`action: \"list\"\\`, inspect with \\`action: \"get\"\\` or \\`action: \"inputs\"\\`, and run with \\`action: \"run\"\\`, \\`workflow\\`, and validated \\`inputs\\`; do not invent workflow names or input keys.\n  - Once you run a workflow with the workflow tool, end your current turn and wait for the next user input or lifecycle notice.\n    - You will automatically be alerted of key lifecycle events like start, finish, failure; do not attempt to track its progress yourself or read its logs or stages unless the user asks you to or you need to check in on it to get information for the next step.\n    - If the user needs information from the workflow run, use \\`status\\`, \\`stages\\`, or \\`stage\\` calls to get targeted information instead of trying to read everything.\n    - Offer to help the user on another task instead of anxiously polling or help the user run another workflow if they need.\n    - Use run-control and messaging actions (\\`send\\`, \\`pause\\`, \\`resume\\`, \\`interrupt\\`, \\`kill\\`) only when needed to answer prompts, steer a stage, resume or interrupt paused work, or respond to user requests/control signals.\n  - For transcripts, avoid reading whole session transcripts at once. Use \\`stages\\` or \\`stage\\` to get \\`sessionFile\\`/\\`transcriptPath\\`, quote the exact path without rewriting separators (preserve Windows backslashes), search it with \\`rg\\`/\\`grep\\`, and read small relevant ranges; use \\`transcript\\` with explicit \\`tail\\` or \\`limit\\` only for quick recent-context checks.\n  - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, and success criteria. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition. After you implement the workflow, reload it to access it and run it with test inputs to validate it works as intended before presenting it to the user.\n    - Tip: when designing workflows, implement it in a way that you pass information from stage to stage by writing it to a file or artifact (either deterministic or model-driven), pass the path with \\`reads\\`, and explicitly prompt the downstream agent with wording like \\`Read the file at <path>...\\`; do not inject large \\`previous\\` payloads or session history into the next prompt unless explicitly requested to.\n  - If you run \\`ralph\\` or \\`goal\\` workflow, define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`;\n\n  let prompt = `You are an expert coding assistant operating named Atomic, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n${toolsList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelines}\n${askUserQuestionGuidance}\n${todoGuidance}\n${subagentGuidance}\n${workflowGuidance}\n\nAtomic documentation (read only when the user asks about customizing Atomic itself, its SDK, creating workflows, packages, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- Docs/examples references above must be resolved against these absolute roots; e.g. docs/foo.md means ${docsPath}/foo.md and examples/bar means ${examplesPath}/bar.\n- When asked about: atomic workflows (docs/workflows.md), extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), atomic packages (docs/packages.md)\n- When working on Atomic topics, read the docs and examples, and follow .md cross-references before implementing\n- Always read Atomic .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;\n\n  if (appendSection) {\n    prompt += appendSection;\n  }\n\n  // Append project context files\n  if (contextFiles.length > 0) {\n    prompt += \"\\n\\n# Project Context\\n\\n\";\n    prompt += \"Project-specific instructions and guidelines:\\n\\n\";\n    for (const { path: filePath, content } of contextFiles) {\n      prompt += `<context_file path=\\\"${filePath}\\\">\\n${content}\\n</context_file>\\n\\n`;\n    }\n  }\n\n  // Append skills section (only if read tool is available)\n  if (hasRead && skills.length > 0) {\n    prompt += formatSkillsForPrompt(skills);\n  }\n\n  // Add model metadata, date, and working directory last\n  prompt += `\\nModel name (used for commit attribution): ${modelName}`;\n  prompt += `\\nModel reasoning level: ${modelReasoningLevel}`;\n  prompt += `\\nCurrent date: ${date}`;\n  prompt += `\\nCurrent working directory: ${promptCwd}`;\n\n  return prompt;\n}\n"]}

package/dist/core/tools/ask-user-question/ask-user-question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask-user-question.d.ts","sourceRoot":"","sources":["../../../../src/core/tools/ask-user-question/ask-user-question.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC1F,OAAO,EAIN,KAAK,YAAY,EAGjB,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAI/E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,kBAAkB,EAAE,CAWlF;AAED,eAAO,MAAM,sBAAsB,iGAA0I,CAAC;AAC9K,eAAO,MAAM,yBAAyB,EAAE,MAAM,EAK7C,CAAC;AAEF,wBAAgB,mCAAmC,IAAI,cAAc,CAAC,OAAO,oBAAoB,EAAE,OAAO,CAAC,CAyD1G;AAED,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,CAAC","sourcesContent":["import type { ToolDefinition } from \"../../extensions/types.ts\";\nimport { loadConfig, validateGuidanceFields } from \"./config.ts\";\nimport { QuestionnaireSession } from \"./state/questionnaire-session.ts\";\nimport { ROW_INTENT_META, sentinelsToAppend } from \"./state/row-intent.ts\";\nimport { buildQuestionnaireResponse, buildToolResult } from \"./tool/response-envelope.ts\";\nimport {\n\tMAX_OPTIONS,\n\tMAX_QUESTIONS,\n\tMIN_OPTIONS,\n\ttype QuestionData,\n\ttype QuestionnaireResult,\n\ttype QuestionParams,\n\tQuestionParamsSchema,\n} from \"./tool/types.ts\";\nimport { validateQuestionnaire } from \"./tool/validate-questionnaire.ts\";\nimport type { WrappingSelectItem } from \"./view/components/wrapping-select.ts\";\n\nconst ERROR_NO_UI = \"Error: UI not available (running in non-interactive mode)\";\n\nexport function buildItemsForQuestion(question: QuestionData): WrappingSelectItem[] {\n\tconst items: WrappingSelectItem[] = question.options.map((o) => ({\n\t\tkind: \"option\",\n\t\tlabel: o.label,\n\t\tdescription: o.description,\n\t}));\n\tconst hasAnyPreview = question.options.some((o) => typeof o.preview === \"string\" && o.preview.length > 0);\n\tfor (const kind of sentinelsToAppend(question, hasAnyPreview)) {\n\t\titems.push({ kind, label: ROW_INTENT_META[kind].label });\n\t}\n\treturn items;\n}\n\nexport const DEFAULT_PROMPT_SNIPPET = `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous`;\nexport const DEFAULT_PROMPT_GUIDELINES: string[] = [\n\t`Use ask_user_question whenever the user's request is underspecified and you cannot proceed without concrete decisions — you can ask up to ${MAX_QUESTIONS} questions per invocation.`,\n\t`Each question MUST have ${MIN_OPTIONS}-${MAX_OPTIONS} options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer (\"Type something.\" row is appended automatically to single-select questions) or pick \"Chat about this\" to abandon the questionnaire.`,\n\t`Set multiSelect: true when multiple answers are valid; this suppresses the \"Type something.\" row. Provide an options[].preview markdown string when an option benefits from richer side-by-side context (mockups, code snippets, diagrams, configs) — single-select only. NOTE: any non-empty preview on a single-select question ALSO suppresses the \"Type something.\" row (no room in the side-by-side layout); \"Chat about this\" remains the escape hatch. If you recommend a specific option, make it the first option and append \"(Recommended)\" to its label.`,\n\t\"Do not stack multiple ask_user_question calls back-to-back — group all clarifying questions into one invocation.\",\n];\n\nexport function createAskUserQuestionToolDefinition(): ToolDefinition<typeof QuestionParamsSchema, unknown> {\n\tconst guidance = validateGuidanceFields(loadConfig().guidance);\n\treturn {\n\t\tname: \"ask_user_question\",\n\t\tlabel: \"Ask User Question\",\n\t\tdescription: `Ask the user one or more structured questions during execution. Use when you need to:\n1. Gather user preferences or requirements\n2. Clarify ambiguous instructions\n3. Get decisions on implementation choices as you work\n4. Offer choices to the user about what direction to take\n\nUsage notes:\n- Users will always be able to type a custom answer (\"Type something.\" row is appended automatically to every single-select question) or pick \"Chat about this\" to abandon the questionnaire and continue in free-form conversation. Do NOT author \"Other\" / \"Type something.\" / \"Chat about this\" labels yourself — duplicates are rejected at runtime.\n- Use multiSelect: true to allow multiple answers to be selected for a question. The \"Type something.\" row is suppressed on multi-select questions, and is ALSO suppressed on single-select questions where any option carries a \\`preview\\` (the side-by-side layout has no room for inline custom text — \"Chat about this\" remains as the free-form escape hatch).\n- If you recommend a specific option, make that the first option in the list and add \"(Recommended)\" at the end of the label.\n\nPreview feature:\nUse the optional \\`preview\\` field on options when presenting concrete artifacts that users need to visually compare:\n- ASCII mockups of UI layouts or components\n- Code snippets showing different implementations\n- Diagram variations\n- Configuration examples\n\nPreview content is rendered as markdown in a monospace box. Multi-line text with newlines is supported. When any option has a preview, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).`,\n\t\tpromptSnippet: guidance.promptSnippet ?? DEFAULT_PROMPT_SNIPPET,\n\t\tpromptGuidelines: guidance.promptGuidelines ?? DEFAULT_PROMPT_GUIDELINES,\n\t\tparameters: QuestionParamsSchema,\n\n\t\tasync execute(_toolCallId, params, signal, _onUpdate, ctx) {\n\t\t\tconst typed = params as unknown as QuestionParams;\n\t\t\tif (!ctx.hasUI) return buildToolResult(ERROR_NO_UI, { answers: [], cancelled: true, error: \"no_ui\" });\n\n\t\t\tconst validation = validateQuestionnaire(typed);\n\t\t\tif (!validation.ok) {\n\t\t\t\treturn buildToolResult(validation.message, {\n\t\t\t\t\tanswers: [],\n\t\t\t\t\tcancelled: true,\n\t\t\t\t\terror: validation.error,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst itemsByTab: WrappingSelectItem[][] = typed.questions.map((q) => buildItemsForQuestion(q));\n\n\t\t\tconst result = await ctx.ui.custom<QuestionnaireResult>((tui, theme, _kb, done) => {\n\t\t\t\tconst session = new QuestionnaireSession({\n\t\t\t\t\ttui,\n\t\t\t\t\ttheme,\n\t\t\t\t\tparams: typed,\n\t\t\t\t\titemsByTab,\n\t\t\t\t\tdone,\n\t\t\t\t});\n\t\t\t\treturn session.component;\n\t\t\t}, { signal });\n\n\t\t\treturn buildQuestionnaireResponse(result, typed);\n\t\t},\n\t};\n}\n\nexport { buildQuestionnaireResponse, buildToolResult };\n"]}
+{"version":3,"file":"ask-user-question.d.ts","sourceRoot":"","sources":["../../../../src/core/tools/ask-user-question/ask-user-question.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC1F,OAAO,EAIN,KAAK,YAAY,EAGjB,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAI/E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,kBAAkB,EAAE,CAWlF;AAED,eAAO,MAAM,sBAAsB,iGAA0I,CAAC;AAC9K,eAAO,MAAM,yBAAyB,EAAE,MAAM,EAK7C,CAAC;AAEF,wBAAgB,mCAAmC,IAAI,cAAc,CAAC,OAAO,oBAAoB,EAAE,OAAO,CAAC,CA4E1G;AAED,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,CAAC","sourcesContent":["import type { ToolDefinition } from \"../../extensions/types.ts\";\nimport { loadConfig, validateGuidanceFields } from \"./config.ts\";\nimport { QuestionnaireSession } from \"./state/questionnaire-session.ts\";\nimport { ROW_INTENT_META, sentinelsToAppend } from \"./state/row-intent.ts\";\nimport { buildQuestionnaireResponse, buildToolResult } from \"./tool/response-envelope.ts\";\nimport {\n\tMAX_OPTIONS,\n\tMAX_QUESTIONS,\n\tMIN_OPTIONS,\n\ttype QuestionData,\n\ttype QuestionnaireResult,\n\ttype QuestionParams,\n\tQuestionParamsSchema,\n} from \"./tool/types.ts\";\nimport { validateQuestionnaire } from \"./tool/validate-questionnaire.ts\";\nimport type { WrappingSelectItem } from \"./view/components/wrapping-select.ts\";\n\nconst ERROR_NO_UI = \"Error: UI not available (running in non-interactive mode)\";\n\nexport function buildItemsForQuestion(question: QuestionData): WrappingSelectItem[] {\n\tconst items: WrappingSelectItem[] = question.options.map((o) => ({\n\t\tkind: \"option\",\n\t\tlabel: o.label,\n\t\tdescription: o.description,\n\t}));\n\tconst hasAnyPreview = question.options.some((o) => typeof o.preview === \"string\" && o.preview.length > 0);\n\tfor (const kind of sentinelsToAppend(question, hasAnyPreview)) {\n\t\titems.push({ kind, label: ROW_INTENT_META[kind].label });\n\t}\n\treturn items;\n}\n\nexport const DEFAULT_PROMPT_SNIPPET = `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous`;\nexport const DEFAULT_PROMPT_GUIDELINES: string[] = [\n\t`Use ask_user_question whenever the user's request is underspecified and you cannot proceed without concrete decisions — you can ask up to ${MAX_QUESTIONS} questions per invocation.`,\n\t`Each question MUST have ${MIN_OPTIONS}-${MAX_OPTIONS} options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer (\"Type something.\" row is appended automatically to single-select questions) or pick \"Chat about this\" to abandon the questionnaire.`,\n\t`Set multiSelect: true when multiple answers are valid; this suppresses the \"Type something.\" row. Provide an options[].preview markdown string when an option benefits from richer side-by-side context (mockups, code snippets, diagrams, configs) — single-select only. NOTE: any non-empty preview on a single-select question ALSO suppresses the \"Type something.\" row (no room in the side-by-side layout); \"Chat about this\" remains the escape hatch. If you recommend a specific option, make it the first option and append \"(Recommended)\" to its label.`,\n\t\"Do not stack multiple ask_user_question calls back-to-back — group all clarifying questions into one invocation.\",\n];\n\nexport function createAskUserQuestionToolDefinition(): ToolDefinition<typeof QuestionParamsSchema, unknown> {\n\tconst guidance = validateGuidanceFields(loadConfig().guidance);\n\treturn {\n\t\tname: \"ask_user_question\",\n\t\tlabel: \"Ask User Question\",\n\t\tdescription: `Ask the user one or more structured questions during execution. Use when you need to:\n1. Gather user preferences or requirements\n2. Clarify ambiguous instructions\n3. Get decisions on implementation choices as you work\n4. Offer choices to the user about what direction to take\n\nUsage notes:\n- Users will always be able to type a custom answer (\"Type something.\" row is appended automatically to every single-select question) or pick \"Chat about this\" to abandon the questionnaire and continue in free-form conversation. Do NOT author \"Other\" / \"Type something.\" / \"Chat about this\" labels yourself — duplicates are rejected at runtime.\n- Use multiSelect: true to allow multiple answers to be selected for a question. The \"Type something.\" row is suppressed on multi-select questions, and is ALSO suppressed on single-select questions where any option carries a \\`preview\\` (the side-by-side layout has no room for inline custom text — \"Chat about this\" remains as the free-form escape hatch).\n- If you recommend a specific option, make that the first option in the list and add \"(Recommended)\" at the end of the label.\n\nPreview feature:\nUse the optional \\`preview\\` field on options when presenting concrete artifacts that users need to visually compare:\n- ASCII mockups of UI layouts or components\n- Code snippets showing different implementations\n- Diagram variations\n- Configuration examples\n\nPreview content is rendered as markdown in a monospace box. Multi-line text with newlines is supported. When any option has a preview, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).`,\n\t\tpromptSnippet: guidance.promptSnippet ?? DEFAULT_PROMPT_SNIPPET,\n\t\tpromptGuidelines: guidance.promptGuidelines ?? DEFAULT_PROMPT_GUIDELINES,\n\t\tparameters: QuestionParamsSchema,\n\n\t\tasync execute(_toolCallId, params, signal, _onUpdate, ctx) {\n\t\t\tconst typed = params as unknown as QuestionParams;\n\t\t\tif (!ctx.hasUI) return buildToolResult(ERROR_NO_UI, { answers: [], cancelled: true, error: \"no_ui\" });\n\n\t\t\tconst validation = validateQuestionnaire(typed);\n\t\t\tif (!validation.ok) {\n\t\t\t\treturn buildToolResult(validation.message, {\n\t\t\t\t\tanswers: [],\n\t\t\t\t\tcancelled: true,\n\t\t\t\t\terror: validation.error,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst itemsByTab: WrappingSelectItem[][] = typed.questions.map((q) => buildItemsForQuestion(q));\n\n\t\t\t// Suspend the animated working loader for the lifetime of the blocking dialog.\n\t\t\t//\n\t\t\t// The questionnaire mounts inline, directly below the status/working-loader row.\n\t\t\t// That loader ticks every ~80ms and calls `requestRender()` on each frame. On a\n\t\t\t// short terminal the (tall) side-by-side dialog pushes the loader line above the\n\t\t\t// viewport top, so pi-tui's differential renderer sees `firstChanged < viewportTop`\n\t\t\t// and falls back to a full clear+replay (`\\x1b[2J\\x1b[H\\x1b[3J`) on every tick. The\n\t\t\t// transcript is replayed before the dialog each time, which is the flicker. The\n\t\t\t// loader conveys nothing while we're blocked on human input, so hide it for the\n\t\t\t// duration and restore it once the dialog closes (on every path).\n\t\t\t//\n\t\t\t// Guarded: some hosts (e.g. the workflow stage-UI broker) pass a minimal UI\n\t\t\t// context that only implements `custom`, so treat a missing loader control as a\n\t\t\t// no-op rather than throwing.\n\t\t\tctx.ui.setWorkingVisible?.(false);\n\t\t\ttry {\n\t\t\t\tconst result = await ctx.ui.custom<QuestionnaireResult>((tui, theme, _kb, done) => {\n\t\t\t\t\tconst session = new QuestionnaireSession({\n\t\t\t\t\t\ttui,\n\t\t\t\t\t\ttheme,\n\t\t\t\t\t\tparams: typed,\n\t\t\t\t\t\titemsByTab,\n\t\t\t\t\t\tdone,\n\t\t\t\t\t});\n\t\t\t\t\treturn session.component;\n\t\t\t\t}, { signal });\n\n\t\t\t\treturn buildQuestionnaireResponse(result, typed);\n\t\t\t} finally {\n\t\t\t\tctx.ui.setWorkingVisible?.(true);\n\t\t\t}\n\t\t},\n\t};\n}\n\nexport { buildQuestionnaireResponse, buildToolResult };\n"]}

package/dist/core/tools/ask-user-question/ask-user-question.js

@@ -64,17 +64,37 @@ Preview content is rendered as markdown in a monospace box. Multi-line text with
                 });
             }
             const itemsByTab = typed.questions.map((q) => buildItemsForQuestion(q));
-            const result = await ctx.ui.custom((tui, theme, _kb, done) => {
-                const session = new QuestionnaireSession({
-                    tui,
-                    theme,
-                    params: typed,
-                    itemsByTab,
-                    done,
-                });
-                return session.component;
-            }, { signal });
-            return buildQuestionnaireResponse(result, typed);
+            // Suspend the animated working loader for the lifetime of the blocking dialog.
+            //
+            // The questionnaire mounts inline, directly below the status/working-loader row.
+            // That loader ticks every ~80ms and calls `requestRender()` on each frame. On a
+            // short terminal the (tall) side-by-side dialog pushes the loader line above the
+            // viewport top, so pi-tui's differential renderer sees `firstChanged < viewportTop`
+            // and falls back to a full clear+replay (`\x1b[2J\x1b[H\x1b[3J`) on every tick. The
+            // transcript is replayed before the dialog each time, which is the flicker. The
+            // loader conveys nothing while we're blocked on human input, so hide it for the
+            // duration and restore it once the dialog closes (on every path).
+            //
+            // Guarded: some hosts (e.g. the workflow stage-UI broker) pass a minimal UI
+            // context that only implements `custom`, so treat a missing loader control as a
+            // no-op rather than throwing.
+            ctx.ui.setWorkingVisible?.(false);
+            try {
+                const result = await ctx.ui.custom((tui, theme, _kb, done) => {
+                    const session = new QuestionnaireSession({
+                        tui,
+                        theme,
+                        params: typed,
+                        itemsByTab,
+                        done,
+                    });
+                    return session.component;
+                }, { signal });
+                return buildQuestionnaireResponse(result, typed);
+            }
+            finally {
+                ctx.ui.setWorkingVisible?.(true);
+            }
         },
     };
 }

package/dist/core/tools/ask-user-question/ask-user-question.js.map

@@ -1 +1 @@
-{"version":3,"file":"ask-user-question.js","sourceRoot":"","sources":["../../../../src/core/tools/ask-user-question/ask-user-question.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ToolDefinition } from \"../../extensions/types.ts\";\nimport { loadConfig, validateGuidanceFields } from \"./config.ts\";\nimport { QuestionnaireSession } from \"./state/questionnaire-session.ts\";\nimport { ROW_INTENT_META, sentinelsToAppend } from \"./state/row-intent.ts\";\nimport { buildQuestionnaireResponse, buildToolResult } from \"./tool/response-envelope.ts\";\nimport {\n\tMAX_OPTIONS,\n\tMAX_QUESTIONS,\n\tMIN_OPTIONS,\n\ttype QuestionData,\n\ttype QuestionnaireResult,\n\ttype QuestionParams,\n\tQuestionParamsSchema,\n} from \"./tool/types.ts\";\nimport { validateQuestionnaire } from \"./tool/validate-questionnaire.ts\";\nimport type { WrappingSelectItem } from \"./view/components/wrapping-select.ts\";\n\nconst ERROR_NO_UI = \"Error: UI not available (running in non-interactive mode)\";\n\nexport function buildItemsForQuestion(question: QuestionData): WrappingSelectItem[] {\n\tconst items: WrappingSelectItem[] = question.options.map((o) => ({\n\t\tkind: \"option\",\n\t\tlabel: o.label,\n\t\tdescription: o.description,\n\t}));\n\tconst hasAnyPreview = question.options.some((o) => typeof o.preview === \"string\" && o.preview.length > 0);\n\tfor (const kind of sentinelsToAppend(question, hasAnyPreview)) {\n\t\titems.push({ kind, label: ROW_INTENT_META[kind].label });\n\t}\n\treturn items;\n}\n\nexport const DEFAULT_PROMPT_SNIPPET = `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous`;\nexport const DEFAULT_PROMPT_GUIDELINES: string[] = [\n\t`Use ask_user_question whenever the user's request is underspecified and you cannot proceed without concrete decisions — you can ask up to ${MAX_QUESTIONS} questions per invocation.`,\n\t`Each question MUST have ${MIN_OPTIONS}-${MAX_OPTIONS} options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer (\"Type something.\" row is appended automatically to single-select questions) or pick \"Chat about this\" to abandon the questionnaire.`,\n\t`Set multiSelect: true when multiple answers are valid; this suppresses the \"Type something.\" row. Provide an options[].preview markdown string when an option benefits from richer side-by-side context (mockups, code snippets, diagrams, configs) — single-select only. NOTE: any non-empty preview on a single-select question ALSO suppresses the \"Type something.\" row (no room in the side-by-side layout); \"Chat about this\" remains the escape hatch. If you recommend a specific option, make it the first option and append \"(Recommended)\" to its label.`,\n\t\"Do not stack multiple ask_user_question calls back-to-back — group all clarifying questions into one invocation.\",\n];\n\nexport function createAskUserQuestionToolDefinition(): ToolDefinition<typeof QuestionParamsSchema, unknown> {\n\tconst guidance = validateGuidanceFields(loadConfig().guidance);\n\treturn {\n\t\tname: \"ask_user_question\",\n\t\tlabel: \"Ask User Question\",\n\t\tdescription: `Ask the user one or more structured questions during execution. Use when you need to:\n1. Gather user preferences or requirements\n2. Clarify ambiguous instructions\n3. Get decisions on implementation choices as you work\n4. Offer choices to the user about what direction to take\n\nUsage notes:\n- Users will always be able to type a custom answer (\"Type something.\" row is appended automatically to every single-select question) or pick \"Chat about this\" to abandon the questionnaire and continue in free-form conversation. Do NOT author \"Other\" / \"Type something.\" / \"Chat about this\" labels yourself — duplicates are rejected at runtime.\n- Use multiSelect: true to allow multiple answers to be selected for a question. The \"Type something.\" row is suppressed on multi-select questions, and is ALSO suppressed on single-select questions where any option carries a \\`preview\\` (the side-by-side layout has no room for inline custom text — \"Chat about this\" remains as the free-form escape hatch).\n- If you recommend a specific option, make that the first option in the list and add \"(Recommended)\" at the end of the label.\n\nPreview feature:\nUse the optional \\`preview\\` field on options when presenting concrete artifacts that users need to visually compare:\n- ASCII mockups of UI layouts or components\n- Code snippets showing different implementations\n- Diagram variations\n- Configuration examples\n\nPreview content is rendered as markdown in a monospace box. Multi-line text with newlines is supported. When any option has a preview, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).`,\n\t\tpromptSnippet: guidance.promptSnippet ?? DEFAULT_PROMPT_SNIPPET,\n\t\tpromptGuidelines: guidance.promptGuidelines ?? DEFAULT_PROMPT_GUIDELINES,\n\t\tparameters: QuestionParamsSchema,\n\n\t\tasync execute(_toolCallId, params, signal, _onUpdate, ctx) {\n\t\t\tconst typed = params as unknown as QuestionParams;\n\t\t\tif (!ctx.hasUI) return buildToolResult(ERROR_NO_UI, { answers: [], cancelled: true, error: \"no_ui\" });\n\n\t\t\tconst validation = validateQuestionnaire(typed);\n\t\t\tif (!validation.ok) {\n\t\t\t\treturn buildToolResult(validation.message, {\n\t\t\t\t\tanswers: [],\n\t\t\t\t\tcancelled: true,\n\t\t\t\t\terror: validation.error,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst itemsByTab: WrappingSelectItem[][] = typed.questions.map((q) => buildItemsForQuestion(q));\n\n\t\t\tconst result = await ctx.ui.custom<QuestionnaireResult>((tui, theme, _kb, done) => {\n\t\t\t\tconst session = new QuestionnaireSession({\n\t\t\t\t\ttui,\n\t\t\t\t\ttheme,\n\t\t\t\t\tparams: typed,\n\t\t\t\t\titemsByTab,\n\t\t\t\t\tdone,\n\t\t\t\t});\n\t\t\t\treturn session.component;\n\t\t\t}, { signal });\n\n\t\t\treturn buildQuestionnaireResponse(result, typed);\n\t\t},\n\t};\n}\n\nexport { buildQuestionnaireResponse, buildToolResult };\n"]}
+{"version":3,"file":"ask-user-question.js","sourceRoot":"","sources":["../../../../src/core/tools/ask-user-question/ask-user-question.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ToolDefinition } from \"../../extensions/types.ts\";\nimport { loadConfig, validateGuidanceFields } from \"./config.ts\";\nimport { QuestionnaireSession } from \"./state/questionnaire-session.ts\";\nimport { ROW_INTENT_META, sentinelsToAppend } from \"./state/row-intent.ts\";\nimport { buildQuestionnaireResponse, buildToolResult } from \"./tool/response-envelope.ts\";\nimport {\n\tMAX_OPTIONS,\n\tMAX_QUESTIONS,\n\tMIN_OPTIONS,\n\ttype QuestionData,\n\ttype QuestionnaireResult,\n\ttype QuestionParams,\n\tQuestionParamsSchema,\n} from \"./tool/types.ts\";\nimport { validateQuestionnaire } from \"./tool/validate-questionnaire.ts\";\nimport type { WrappingSelectItem } from \"./view/components/wrapping-select.ts\";\n\nconst ERROR_NO_UI = \"Error: UI not available (running in non-interactive mode)\";\n\nexport function buildItemsForQuestion(question: QuestionData): WrappingSelectItem[] {\n\tconst items: WrappingSelectItem[] = question.options.map((o) => ({\n\t\tkind: \"option\",\n\t\tlabel: o.label,\n\t\tdescription: o.description,\n\t}));\n\tconst hasAnyPreview = question.options.some((o) => typeof o.preview === \"string\" && o.preview.length > 0);\n\tfor (const kind of sentinelsToAppend(question, hasAnyPreview)) {\n\t\titems.push({ kind, label: ROW_INTENT_META[kind].label });\n\t}\n\treturn items;\n}\n\nexport const DEFAULT_PROMPT_SNIPPET = `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous`;\nexport const DEFAULT_PROMPT_GUIDELINES: string[] = [\n\t`Use ask_user_question whenever the user's request is underspecified and you cannot proceed without concrete decisions — you can ask up to ${MAX_QUESTIONS} questions per invocation.`,\n\t`Each question MUST have ${MIN_OPTIONS}-${MAX_OPTIONS} options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer (\"Type something.\" row is appended automatically to single-select questions) or pick \"Chat about this\" to abandon the questionnaire.`,\n\t`Set multiSelect: true when multiple answers are valid; this suppresses the \"Type something.\" row. Provide an options[].preview markdown string when an option benefits from richer side-by-side context (mockups, code snippets, diagrams, configs) — single-select only. NOTE: any non-empty preview on a single-select question ALSO suppresses the \"Type something.\" row (no room in the side-by-side layout); \"Chat about this\" remains the escape hatch. If you recommend a specific option, make it the first option and append \"(Recommended)\" to its label.`,\n\t\"Do not stack multiple ask_user_question calls back-to-back — group all clarifying questions into one invocation.\",\n];\n\nexport function createAskUserQuestionToolDefinition(): ToolDefinition<typeof QuestionParamsSchema, unknown> {\n\tconst guidance = validateGuidanceFields(loadConfig().guidance);\n\treturn {\n\t\tname: \"ask_user_question\",\n\t\tlabel: \"Ask User Question\",\n\t\tdescription: `Ask the user one or more structured questions during execution. Use when you need to:\n1. Gather user preferences or requirements\n2. Clarify ambiguous instructions\n3. Get decisions on implementation choices as you work\n4. Offer choices to the user about what direction to take\n\nUsage notes:\n- Users will always be able to type a custom answer (\"Type something.\" row is appended automatically to every single-select question) or pick \"Chat about this\" to abandon the questionnaire and continue in free-form conversation. Do NOT author \"Other\" / \"Type something.\" / \"Chat about this\" labels yourself — duplicates are rejected at runtime.\n- Use multiSelect: true to allow multiple answers to be selected for a question. The \"Type something.\" row is suppressed on multi-select questions, and is ALSO suppressed on single-select questions where any option carries a \\`preview\\` (the side-by-side layout has no room for inline custom text — \"Chat about this\" remains as the free-form escape hatch).\n- If you recommend a specific option, make that the first option in the list and add \"(Recommended)\" at the end of the label.\n\nPreview feature:\nUse the optional \\`preview\\` field on options when presenting concrete artifacts that users need to visually compare:\n- ASCII mockups of UI layouts or components\n- Code snippets showing different implementations\n- Diagram variations\n- Configuration examples\n\nPreview content is rendered as markdown in a monospace box. Multi-line text with newlines is supported. When any option has a preview, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).`,\n\t\tpromptSnippet: guidance.promptSnippet ?? DEFAULT_PROMPT_SNIPPET,\n\t\tpromptGuidelines: guidance.promptGuidelines ?? DEFAULT_PROMPT_GUIDELINES,\n\t\tparameters: QuestionParamsSchema,\n\n\t\tasync execute(_toolCallId, params, signal, _onUpdate, ctx) {\n\t\t\tconst typed = params as unknown as QuestionParams;\n\t\t\tif (!ctx.hasUI) return buildToolResult(ERROR_NO_UI, { answers: [], cancelled: true, error: \"no_ui\" });\n\n\t\t\tconst validation = validateQuestionnaire(typed);\n\t\t\tif (!validation.ok) {\n\t\t\t\treturn buildToolResult(validation.message, {\n\t\t\t\t\tanswers: [],\n\t\t\t\t\tcancelled: true,\n\t\t\t\t\terror: validation.error,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst itemsByTab: WrappingSelectItem[][] = typed.questions.map((q) => buildItemsForQuestion(q));\n\n\t\t\t// Suspend the animated working loader for the lifetime of the blocking dialog.\n\t\t\t//\n\t\t\t// The questionnaire mounts inline, directly below the status/working-loader row.\n\t\t\t// That loader ticks every ~80ms and calls `requestRender()` on each frame. On a\n\t\t\t// short terminal the (tall) side-by-side dialog pushes the loader line above the\n\t\t\t// viewport top, so pi-tui's differential renderer sees `firstChanged < viewportTop`\n\t\t\t// and falls back to a full clear+replay (`\\x1b[2J\\x1b[H\\x1b[3J`) on every tick. The\n\t\t\t// transcript is replayed before the dialog each time, which is the flicker. The\n\t\t\t// loader conveys nothing while we're blocked on human input, so hide it for the\n\t\t\t// duration and restore it once the dialog closes (on every path).\n\t\t\t//\n\t\t\t// Guarded: some hosts (e.g. the workflow stage-UI broker) pass a minimal UI\n\t\t\t// context that only implements `custom`, so treat a missing loader control as a\n\t\t\t// no-op rather than throwing.\n\t\t\tctx.ui.setWorkingVisible?.(false);\n\t\t\ttry {\n\t\t\t\tconst result = await ctx.ui.custom<QuestionnaireResult>((tui, theme, _kb, done) => {\n\t\t\t\t\tconst session = new QuestionnaireSession({\n\t\t\t\t\t\ttui,\n\t\t\t\t\t\ttheme,\n\t\t\t\t\t\tparams: typed,\n\t\t\t\t\t\titemsByTab,\n\t\t\t\t\t\tdone,\n\t\t\t\t\t});\n\t\t\t\t\treturn session.component;\n\t\t\t\t}, { signal });\n\n\t\t\t\treturn buildQuestionnaireResponse(result, typed);\n\t\t\t} finally {\n\t\t\t\tctx.ui.setWorkingVisible?.(true);\n\t\t\t}\n\t\t},\n\t};\n}\n\nexport { buildQuestionnaireResponse, buildToolResult };\n"]}

package/dist/modes/interactive/components/chat-session-host.d.ts

@@ -94,6 +94,10 @@ export declare class ChatSessionHost<TExtraEntry extends ChatTranscriptEntryLike
     private animationTimer;
     private renderThrottleTimer;
     private bodyViewport;
+    private transcriptComponent;
+    private transcriptRenderSettingsKey;
+    private renderIdentityIds;
+    private nextRenderIdentityId;
     private liveChat;
     private editor;
     private optimisticUserSignatureCounts;
@@ -139,6 +143,10 @@ export declare class ChatSessionHost<TExtraEntry extends ChatTranscriptEntryLike
     private streamingWindowedEntry;
     private chatMessageRenderOptions;
     private toolTui;
+    private chatRenderSettingsCacheKey;
+    private transcriptCacheKey;
+    private entryContentCacheKey;
+    private renderIdentityKey;
     private pendingMessageLine;
     private abortCompaction;
     private abortBash;