gencode-ai 0.1.2 → 0.2.0

package/src/planning/tools/enter-plan-mode.ts

@@ -0,0 +1,111 @@
+/**
+ * EnterPlanMode Tool
+ *
+ * Transitions the agent into plan mode for designing implementation
+ * approaches before writing code. In plan mode, only read-only tools
+ * are available.
+ */
+
+import { z } from 'zod';
+import type { Tool, ToolResult, ToolContext } from '../../tools/types.js';
+import { getPlanModeManager } from '../state.js';
+import { createPlanFile, getDisplayPath } from '../plan-file.js';
+import { PLAN_MODE_ALLOWED_TOOLS, PLAN_MODE_BLOCKED_TOOLS } from '../types.js';
+
+// ============================================================================
+// Tool Definition
+// ============================================================================
+
+const EnterPlanModeInputSchema = z.object({});
+
+export type EnterPlanModeInput = z.infer<typeof EnterPlanModeInputSchema>;
+
+/**
+ * EnterPlanMode Tool
+ *
+ * Use this tool when you need to plan an implementation before writing code.
+ * This is recommended for:
+ * - New feature implementations
+ * - Tasks with multiple valid approaches
+ * - Architectural decisions
+ * - Multi-file changes
+ * - Unclear requirements
+ */
+export const enterPlanModeTool: Tool<EnterPlanModeInput> = {
+  name: 'EnterPlanMode',
+
+  description: `Transition into plan mode to design an implementation approach before writing code.
+
+Use this tool when:
+- Implementing new features that require design decisions
+- Tasks with multiple valid approaches
+- Changes that affect existing behavior or structure
+- Architectural decisions between patterns or technologies
+- Multi-file changes (more than 2-3 files)
+- Unclear requirements that need exploration
+
+In plan mode:
+- Only read-only tools are available (Read, Glob, Grep, WebFetch, WebSearch, TodoWrite, AskUserQuestion)
+- Write, Edit, and Bash tools are blocked
+- You can explore the codebase and design an approach
+- Use ExitPlanMode when ready to request user approval
+
+This tool REQUIRES user approval before entering plan mode.`,
+
+  parameters: EnterPlanModeInputSchema,
+
+  async execute(_input: EnterPlanModeInput, context: ToolContext): Promise<ToolResult> {
+    const manager = getPlanModeManager();
+
+    // Check if already in plan mode
+    if (manager.isActive()) {
+      return {
+        success: false,
+        output: '',
+        error: 'Already in plan mode. Use ExitPlanMode to exit first.',
+      };
+    }
+
+    try {
+      // Create plan file
+      const planFile = await createPlanFile(context.cwd);
+      const displayPath = getDisplayPath(planFile.path, context.cwd);
+
+      // Enter plan mode
+      manager.enter(planFile.path);
+
+      // Build response
+      const output = `
+Entered PLAN mode.
+
+Plan file: ${displayPath}
+
+In plan mode, you have access to read-only tools for exploration:
+${PLAN_MODE_ALLOWED_TOOLS.map((t) => `  - ${t}`).join('\n')}
+
+Blocked tools (write/execute operations):
+${PLAN_MODE_BLOCKED_TOOLS.map((t) => `  - ${t}`).join('\n')}
+
+Instructions:
+1. Explore the codebase using Read, Glob, Grep tools
+2. Research if needed using WebFetch, WebSearch
+3. Design your implementation approach
+4. Write your plan to the plan file using Write (plan file only)
+5. Call ExitPlanMode when ready for user approval
+
+Use Shift+Tab to toggle between Plan and Build modes.
+`.trim();
+
+      return {
+        success: true,
+        output,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: '',
+        error: `Failed to enter plan mode: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};

package/src/planning/tools/exit-plan-mode.ts

@@ -0,0 +1,170 @@
+/**
+ * ExitPlanMode Tool
+ *
+ * Exits plan mode and requests user approval for the implementation plan.
+ * Supports pre-approving permissions for bash commands needed during execution.
+ */
+
+import { z } from 'zod';
+import type { Tool, ToolResult, ToolContext } from '../../tools/types.js';
+import { getPlanModeManager } from '../state.js';
+import { readPlanFile, parseFilesToChange, parsePreApprovedPermissions, getDisplayPath } from '../plan-file.js';
+import type { AllowedPrompt } from '../types.js';
+
+// ============================================================================
+// Tool Definition
+// ============================================================================
+
+const AllowedPromptSchema = z.object({
+  tool: z.literal('Bash').describe('The tool this permission applies to'),
+  prompt: z.string().describe('Semantic description of the action, e.g., "run tests", "install dependencies"'),
+});
+
+const ExitPlanModeInputSchema = z.object({
+  allowedPrompts: z
+    .array(AllowedPromptSchema)
+    .optional()
+    .describe('Prompt-based permissions needed to implement the plan'),
+});
+
+export type ExitPlanModeInput = z.infer<typeof ExitPlanModeInputSchema>;
+
+/**
+ * ExitPlanMode Tool
+ *
+ * Call this when you have finished writing your plan and are ready
+ * for user approval. The plan file should already be written.
+ */
+export const exitPlanModeTool: Tool<ExitPlanModeInput> = {
+  name: 'ExitPlanMode',
+
+  description: `Exit plan mode and request user approval for the implementation plan.
+
+## How This Tool Works
+- You should have already written your plan to the plan file
+- This tool reads the plan from the file you wrote
+- The user will see the plan contents and approve/modify/cancel
+
+## Requesting Permissions (allowedPrompts)
+Request prompt-based permissions for bash commands your plan will need:
+
+\`\`\`json
+{
+  "allowedPrompts": [
+    { "tool": "Bash", "prompt": "run tests" },
+    { "tool": "Bash", "prompt": "install dependencies" },
+    { "tool": "Bash", "prompt": "build the project" }
+  ]
+}
+\`\`\`
+
+Guidelines for prompts:
+- Use semantic descriptions that capture the action's purpose
+- "run tests" matches: npm test, pytest, go test, etc.
+- "install dependencies" matches: npm install, pip install, etc.
+- Keep descriptions concise but descriptive
+- Only request permissions you actually need
+- Scope permissions narrowly
+
+## When to Use This Tool
+Only use this tool when you have finished planning and are ready for approval.
+Do NOT use this tool for research tasks - only for implementation planning.`,
+
+  parameters: ExitPlanModeInputSchema,
+
+  async execute(input: ExitPlanModeInput, context: ToolContext): Promise<ToolResult> {
+    const manager = getPlanModeManager();
+
+    // Check if in plan mode
+    if (!manager.isActive()) {
+      return {
+        success: false,
+        output: '',
+        error: 'Not in plan mode. Use EnterPlanMode first.',
+      };
+    }
+
+    const planFilePath = manager.getPlanFilePath();
+    if (!planFilePath) {
+      return {
+        success: false,
+        output: '',
+        error: 'No plan file found. This should not happen.',
+      };
+    }
+
+    try {
+      // Read plan file
+      const planFile = await readPlanFile(planFilePath);
+      if (!planFile) {
+        return {
+          success: false,
+          output: '',
+          error: `Could not read plan file: ${planFilePath}`,
+        };
+      }
+
+      // Parse plan content
+      const filesToChange = parseFilesToChange(planFile.content);
+      const planPermissions = parsePreApprovedPermissions(planFile.content);
+
+      // Combine with input permissions
+      const requestedPermissions: AllowedPrompt[] = [
+        ...planPermissions,
+        ...(input.allowedPrompts || []),
+      ];
+
+      // Store permissions for approval UI
+      manager.setRequestedPermissions(requestedPermissions);
+      manager.setPhase('approval');
+
+      // Build response for the LLM
+      const displayPath = getDisplayPath(planFilePath, context.cwd);
+      let output = `
+Plan ready for approval.
+
+Plan file: ${displayPath}
+
+`;
+
+      // Summary of files to change
+      if (filesToChange.length > 0) {
+        output += 'Files to change:\n';
+        for (const file of filesToChange) {
+          const icon = file.action === 'create' ? '+' : file.action === 'modify' ? '~' : '-';
+          output += `  ${icon} ${file.path} (${file.action})\n`;
+        }
+        output += '\n';
+      }
+
+      // Requested permissions
+      if (requestedPermissions.length > 0) {
+        output += 'Requested permissions:\n';
+        for (const perm of requestedPermissions) {
+          output += `  - ${perm.tool}(prompt: ${perm.prompt})\n`;
+        }
+        output += '\n';
+      }
+
+      output += `
+The user will now be prompted to:
+1. Approve - Accept plan and proceed with execution
+2. Modify - Go back and modify the plan
+3. Cancel - Exit plan mode without executing
+
+Waiting for user decision...
+`.trim();
+
+      return {
+        success: true,
+        output,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: '',
+        error: `Failed to exit plan mode: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};

package/src/planning/types.ts

@@ -0,0 +1,150 @@
+/**
+ * Plan Mode Type Definitions
+ *
+ * Types for Plan Mode - a read-only exploration mode that allows
+ * the LLM to plan implementations before executing changes.
+ */
+
+// ============================================================================
+// Plan Mode State Types
+// ============================================================================
+
+/**
+ * Plan mode phases following Claude Code's workflow
+ */
+export type PlanPhase =
+  | 'understanding' // Initial exploration
+  | 'design' // Planning approach
+  | 'review' // Clarifying with user
+  | 'final' // Writing plan file
+  | 'approval'; // Waiting for user approval
+
+/**
+ * User approval options for plan mode
+ */
+export type PlanApprovalOption =
+  | 'approve' // Accept plan and execute with auto-accept edits
+  | 'approve_clear' // Accept plan, clear context, auto-accept edits
+  | 'approve_manual' // Accept plan but manually approve each edit
+  | 'modify' // Go back to modify the plan
+  | 'cancel'; // Cancel plan mode entirely
+
+/**
+ * Pre-approved permission request (Claude Code ExitPlanMode style)
+ */
+export interface AllowedPrompt {
+  tool: 'Bash';
+  prompt: string; // Semantic description, e.g., "run tests", "install dependencies"
+}
+
+/**
+ * Plan mode state
+ */
+export interface PlanModeState {
+  /** Whether plan mode is currently active */
+  active: boolean;
+
+  /** Current phase of planning */
+  phase: PlanPhase;
+
+  /** Path to the plan file */
+  planFilePath: string | null;
+
+  /** User's original request that triggered plan mode */
+  originalRequest: string | null;
+
+  /** Requested permissions for execution phase */
+  requestedPermissions: AllowedPrompt[];
+
+  /** Timestamp when plan mode was entered */
+  enteredAt: Date | null;
+}
+
+/**
+ * Plan file structure
+ */
+export interface PlanFile {
+  /** Plan file path */
+  path: string;
+
+  /** Plan content in markdown */
+  content: string;
+
+  /** Creation timestamp */
+  createdAt: Date;
+
+  /** Last update timestamp */
+  updatedAt: Date;
+}
+
+// ============================================================================
+// Tool Filtering Types
+// ============================================================================
+
+/**
+ * Tools allowed in plan mode (read-only + planning tools)
+ */
+export const PLAN_MODE_ALLOWED_TOOLS = [
+  'Read',
+  'Glob',
+  'Grep',
+  'WebFetch',
+  'WebSearch',
+  'TodoWrite',
+  'AskUserQuestion',
+  'EnterPlanMode', // Can re-enter if needed
+  'ExitPlanMode', // To exit plan mode
+] as const;
+
+/**
+ * Tools blocked in plan mode (write/execute operations)
+ */
+export const PLAN_MODE_BLOCKED_TOOLS = ['Write', 'Edit', 'Bash'] as const;
+
+export type PlanModeAllowedTool = (typeof PLAN_MODE_ALLOWED_TOOLS)[number];
+export type PlanModeBlockedTool = (typeof PLAN_MODE_BLOCKED_TOOLS)[number];
+
+// ============================================================================
+// UI Types
+// ============================================================================
+
+/**
+ * Operating mode (cycle with Shift+Tab: normal → plan → accept → normal)
+ * - normal: Default mode, edits require confirmation
+ * - plan: Read-only exploration mode, edits blocked
+ * - accept: Auto-accept mode, edits approved without confirmation
+ */
+export type ModeType = 'normal' | 'plan' | 'accept';
+
+/**
+ * Plan approval UI state
+ */
+export interface PlanApprovalState {
+  /** Plan content for display */
+  planContent: string;
+
+  /** Summary of files to change */
+  filesToChange: Array<{
+    path: string;
+    action: 'create' | 'modify' | 'delete';
+  }>;
+
+  /** Requested permissions */
+  requestedPermissions: AllowedPrompt[];
+
+  /** Callback when user makes decision */
+  onDecision: (option: PlanApprovalOption) => void;
+}
+
+// ============================================================================
+// Event Types
+// ============================================================================
+
+/**
+ * Plan mode events for UI updates
+ */
+export type PlanModeEvent =
+  | { type: 'enter'; planFilePath: string }
+  | { type: 'phase_change'; phase: PlanPhase }
+  | { type: 'exit'; approved: boolean }
+  | { type: 'toggle' }; // Shift+Tab toggle

package/src/pricing/calculator.ts

@@ -0,0 +1,71 @@
+/**
+ * Cost calculation utilities
+ */
+
+import { getModelPricing } from './models.js';
+import { CostEstimate, TokenUsage } from './types.js';
+
+/**
+ * Calculate cost from token usage
+ */
+export function calculateCost(
+  provider: string,
+  model: string,
+  tokens: TokenUsage
+): CostEstimate {
+  const pricing = getModelPricing(provider, model);
+
+  // If no pricing found, return zero cost
+  if (!pricing) {
+    return {
+      inputCost: 0,
+      outputCost: 0,
+      totalCost: 0,
+      currency: 'USD',
+    };
+  }
+
+  // Calculate cost per token type
+  const inputCost = (tokens.inputTokens / 1_000_000) * pricing.inputPer1M;
+  const outputCost = (tokens.outputTokens / 1_000_000) * pricing.outputPer1M;
+
+  return {
+    inputCost,
+    outputCost,
+    totalCost: inputCost + outputCost,
+    currency: 'USD',
+  };
+}
+
+/**
+ * Format cost for display
+ */
+export function formatCost(cost: number): string {
+  if (cost === 0) {
+    return '$0.00';
+  }
+  if (cost < 0.01) {
+    return '<$0.01';
+  }
+  return `$${cost.toFixed(2)}`;
+}
+
+/**
+ * Format token count for display
+ */
+export function formatTokens(count: number): string {
+  if (count >= 1_000_000) {
+    return `${(count / 1_000_000).toFixed(1)}M`;
+  }
+  if (count >= 1_000) {
+    return `${(count / 1_000).toFixed(1)}K`;
+  }
+  return count.toString();
+}
+
+/**
+ * Format cost estimate for display
+ */
+export function formatCostEstimate(estimate: CostEstimate): string {
+  return formatCost(estimate.totalCost);
+}

package/src/pricing/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Pricing and cost tracking module
+ */
+
+export * from './types.js';
+export * from './models.js';
+export * from './calculator.js';