gencode-ai 0.1.2 → 0.1.3

package/src/prompts/system/base.txt

@@ -61,6 +61,48 @@ When making changes to files, first understand the file's code conventions. Mimi
 - Do not add docstrings, type annotations, or comments to code you didn't change
 - Keep solutions simple and focused. Only make changes directly requested or clearly necessary.
 
+# Asking Questions
+
+You have access to the AskUserQuestion tool to ask the user questions during execution.
+
+CRITICAL: You MUST use the AskUserQuestion tool for ALL questions with choices. NEVER write numbered lists, bullet points, or "which do you prefer" questions as plain text.
+
+## Wrong - Plain Text Questions (DO NOT DO THIS)
+
+<bad-example>
+user: Set up a new database
+assistant: I can set up a database for you. Which one would you prefer?
+1. PostgreSQL - relational database
+2. MongoDB - document database
+3. SQLite - embedded database
+</bad-example>
+
+<bad-example>
+user: Create a new project
+assistant: What type of project?
+- Web app
+- CLI tool
+- API server
+</bad-example>
+
+## Correct - Use AskUserQuestion Tool
+
+<example>
+user: Set up a new database
+assistant: [uses AskUserQuestion tool with questions: [{question: "Which database?", header: "Database", options: [{label: "PostgreSQL", description: "Relational DB"}, {label: "MongoDB", description: "Document DB"}], multiSelect: false}]]
+</example>
+
+<example>
+user: Create a new project
+assistant: [uses AskUserQuestion tool to ask about project type, framework preferences, etc.]
+</example>
+
+Use AskUserQuestion when you need to:
+- Gather user preferences (database choice, framework, etc.)
+- Clarify ambiguous instructions with specific options
+- Get decisions on implementation approaches
+- Offer choices about direction to take
+
 # Task Management
 
 You have access to the TodoWrite tool to manage tasks.

package/src/prompts/tools/ask-user.txt

@@ -0,0 +1,110 @@
+Use this tool when you need to ask the user questions during execution.
+
+CRITICAL: You MUST use this tool for ANY question with 2+ choices. NEVER present options as plain text, numbered lists, or bullet points.
+
+WRONG (never do this):
+- "Which do you prefer? 1. Option A 2. Option B"
+- "What type? - Web - CLI - API"
+- Writing any numbered or bulleted choices in your response
+
+CORRECT: Call this tool with structured questions and options.
+
+This allows you to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take
+
+## When to Use This Tool
+
+Use when you encounter:
+- Ambiguous requirements that could be interpreted multiple ways
+- Technology choices where user preference matters (database, framework, etc.)
+- Implementation approaches with different trade-offs
+- Features or options that should be user-selected
+
+## When NOT to Use This Tool
+
+Don't use for:
+- Asking "Is my plan ready?" or "Should I proceed?" - just proceed or use planning tools
+- Simple yes/no confirmations - just make a reasonable choice
+- Questions you can answer by reading the codebase
+- Trivial implementation details
+
+## Usage Guidelines
+
+- Keep headers short (max 12 chars): "Database", "Auth", "Features"
+- Provide 2-4 options per question
+- Put recommended option FIRST and add "(Recommended)" to its label
+- Use multiSelect: true for non-mutually-exclusive options
+- "Other" option is automatically added - don't include it manually
+- Keep option labels concise (1-5 words)
+- Descriptions should explain trade-offs or implications
+
+## Examples
+
+### Single Choice - Technology Selection
+```json
+{
+  "questions": [{
+    "question": "Which database should we use?",
+    "header": "Database",
+    "options": [
+      { "label": "PostgreSQL (Recommended)", "description": "Robust relational DB" },
+      { "label": "MongoDB", "description": "Document-based NoSQL" },
+      { "label": "SQLite", "description": "Lightweight embedded DB" }
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+### Multi-Select - Feature Selection
+```json
+{
+  "questions": [{
+    "question": "Which features should we enable?",
+    "header": "Features",
+    "options": [
+      { "label": "TypeScript", "description": "Type safety" },
+      { "label": "ESLint", "description": "Code linting" },
+      { "label": "Testing", "description": "Unit tests" },
+      { "label": "Tailwind", "description": "CSS framework" }
+    ],
+    "multiSelect": true
+  }]
+}
+```
+
+### Multiple Questions
+```json
+{
+  "questions": [
+    {
+      "question": "Which auth method?",
+      "header": "Auth",
+      "options": [
+        { "label": "OAuth 2.0 (Recommended)", "description": "Industry standard" },
+        { "label": "JWT", "description": "Stateless tokens" }
+      ],
+      "multiSelect": false
+    },
+    {
+      "question": "Which providers to support?",
+      "header": "Providers",
+      "options": [
+        { "label": "Google", "description": "Most common" },
+        { "label": "GitHub", "description": "Developer-focused" }
+      ],
+      "multiSelect": true
+    }
+  ]
+}
+```
+
+## Constraints
+
+- Maximum 4 questions per call
+- Maximum 4 options per question
+- Header: max 12 characters
+- multiSelect must be explicitly set (required, not optional)

package/src/tools/builtin/ask-user.ts

@@ -0,0 +1,185 @@
+/**
+ * AskUserQuestion Tool - Structured user questioning
+ *
+ * Allows the agent to pause execution and present structured questions
+ * to the user with predefined options. Supports single-select, multi-select,
+ * and custom "Other" input.
+ */
+
+import { z } from 'zod';
+import type { Tool, ToolResult, ToolContext } from '../types.js';
+import { loadToolDescription } from '../../prompts/index.js';
+
+// ============================================================================
+// Zod Schemas
+// ============================================================================
+
+export const QuestionOptionSchema = z.object({
+  label: z
+    .string()
+    .min(1)
+    .max(50)
+    .describe('Display text for this option (1-5 words, concise)'),
+  description: z
+    .string()
+    .min(1)
+    .max(200)
+    .describe('Explanation of what this option means or implications'),
+});
+
+export const QuestionSchema = z.object({
+  question: z
+    .string()
+    .min(1)
+    .describe('The complete question to ask the user, ending with a question mark'),
+  header: z
+    .string()
+    .min(1)
+    .max(12)
+    .describe('Very short label displayed as a chip/tag (max 12 chars)'),
+  options: z
+    .array(QuestionOptionSchema)
+    .min(2)
+    .max(4)
+    .describe('2-4 options for the user to choose from'),
+  multiSelect: z
+    .boolean()
+    .describe('Set to true to allow multiple selections, false for single choice'),
+});
+
+export const AskUserQuestionInputSchema = z.object({
+  questions: z
+    .array(QuestionSchema)
+    .min(1)
+    .max(4)
+    .describe('1-4 questions to ask the user'),
+});
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type QuestionOption = z.infer<typeof QuestionOptionSchema>;
+export type Question = z.infer<typeof QuestionSchema>;
+export type AskUserQuestionInput = z.infer<typeof AskUserQuestionInputSchema>;
+
+export interface QuestionAnswer {
+  question: string;
+  header: string;
+  selectedOptions: string[];
+  customInput?: string;
+}
+
+export interface AskUserQuestionResult {
+  answers: QuestionAnswer[];
+}
+
+// ============================================================================
+// Answer Formatting
+// ============================================================================
+
+/**
+ * Format answers for display to the agent
+ */
+export function formatAnswersForAgent(answers: QuestionAnswer[]): string {
+  const lines: string[] = ['User answered the following questions:', ''];
+
+  answers.forEach((answer, index) => {
+    lines.push(`${index + 1}. ${answer.header} (${answer.question})`);
+
+    if (answer.selectedOptions.length > 0) {
+      lines.push(`   Selected: ${answer.selectedOptions.join(', ')}`);
+    }
+
+    if (answer.customInput) {
+      lines.push(`   Custom input: ${answer.customInput}`);
+    }
+
+    lines.push('');
+  });
+
+  lines.push('Proceeding with user selections.');
+
+  return lines.join('\n');
+}
+
+/**
+ * Format answers for CLI confirmation display
+ */
+export function formatAnswersForDisplay(answers: QuestionAnswer[]): string {
+  return answers
+    .map((answer) => {
+      const selections = answer.customInput
+        ? [...answer.selectedOptions, answer.customInput].join(', ')
+        : answer.selectedOptions.join(', ');
+      return `✔ ${answer.header}: ${selections}`;
+    })
+    .join('\n');
+}
+
+// ============================================================================
+// Tool Implementation
+// ============================================================================
+
+/**
+ * AskUserQuestion tool
+ *
+ * This tool is special - it doesn't execute immediately but signals
+ * the agent loop to pause and wait for user input via the CLI.
+ *
+ * The actual questioning is handled by the CLI layer (QuestionPrompt component).
+ * This tool just validates the input and returns a marker for the agent loop.
+ */
+export const askUserQuestionTool: Tool<AskUserQuestionInput> = {
+  name: 'AskUserQuestion',
+  description: loadToolDescription('ask-user'),
+  parameters: AskUserQuestionInputSchema,
+
+  async execute(input: AskUserQuestionInput, context: ToolContext): Promise<ToolResult> {
+    // Validation is handled by Zod schema
+    // Additional validation for recommended options format
+    for (const question of input.questions) {
+      // Check if first option has (Recommended) - this is just a hint, not enforced
+      const firstOption = question.options[0];
+      if (firstOption && !firstOption.label.includes('(Recommended)')) {
+        // This is fine - recommended suffix is optional
+      }
+    }
+
+    // Check if context has askUser callback
+    if (context.askUser) {
+      try {
+        const answers = await context.askUser(input.questions);
+        return {
+          success: true,
+          output: formatAnswersForAgent(answers),
+          metadata: {
+            title: 'AskUserQuestion',
+            subtitle: `${answers.length} answer(s) received`,
+          },
+        };
+      } catch (error) {
+        return {
+          success: false,
+          output: '',
+          error: `Failed to get user response: ${error instanceof Error ? error.message : String(error)}`,
+        };
+      }
+    }
+
+    // If no askUser callback, return a special marker
+    // The agent loop should detect this and handle it specially
+    return {
+      success: true,
+      output: JSON.stringify({
+        type: 'ask_user_question',
+        questions: input.questions,
+        requiresUserInput: true,
+      }),
+      metadata: {
+        title: 'AskUserQuestion',
+        subtitle: `${input.questions.length} question(s) pending`,
+      },
+    };
+  },
+};

package/src/tools/index.ts

@@ -15,6 +15,18 @@ export { grepTool } from './builtin/grep.js';
 export { webfetchTool } from './builtin/webfetch.js';
 export { websearchTool } from './builtin/websearch.js';
 export { todowriteTool, getTodos, clearTodos } from './builtin/todowrite.js';
+export {
+  askUserQuestionTool,
+  formatAnswersForAgent,
+  formatAnswersForDisplay,
+} from './builtin/ask-user.js';
+export type {
+  Question as AskUserQuestion,
+  QuestionOption as AskUserQuestionOption,
+  QuestionAnswer as AskUserQuestionAnswer,
+  AskUserQuestionInput,
+  AskUserQuestionResult,
+} from './builtin/ask-user.js';
 
 import { ToolRegistry } from './registry.js';
 import { readTool } from './builtin/read.js';
@@ -26,6 +38,7 @@ import { grepTool } from './builtin/grep.js';
 import { webfetchTool } from './builtin/webfetch.js';
 import { websearchTool } from './builtin/websearch.js';
 import { todowriteTool } from './builtin/todowrite.js';
+import { askUserQuestionTool } from './builtin/ask-user.js';
 
 /**
  * Create a registry with all built-in tools
@@ -42,6 +55,7 @@ export function createDefaultRegistry(): ToolRegistry {
     webfetchTool,
     websearchTool,
     todowriteTool,
+    askUserQuestionTool,
   ]);
   return registry;
 }
@@ -59,4 +73,5 @@ export const builtinTools = [
   webfetchTool,
   websearchTool,
   todowriteTool,
+  askUserQuestionTool,
 ];

package/src/tools/types.ts

@@ -9,9 +9,27 @@ import { z } from 'zod';
 // Tool Definition Types
 // ============================================================================
 
+// Forward declaration for Question type (used by AskUserQuestion tool)
+export interface Question {
+  question: string;
+  header: string;
+  options: Array<{ label: string; description: string }>;
+  multiSelect: boolean;
+}
+
+// Forward declaration for QuestionAnswer type (used by AskUserQuestion tool)
+export interface QuestionAnswer {
+  question: string;
+  header: string;
+  selectedOptions: string[];
+  customInput?: string;
+}
+
 export interface ToolContext {
   cwd: string;
   abortSignal?: AbortSignal;
+  /** Callback for AskUserQuestion tool to interact with user */
+  askUser?: (questions: Question[]) => Promise<QuestionAnswer[]>;
 }
 
 export interface ToolResultMetadata {