@miphamai/cli 0.8.0 → 0.10.0

package/src/ui/app.tsx

@@ -15,6 +15,7 @@ import {
   handleSwitch,
   type CommandContext,
 } from './commands'
+import type { PermissionMode } from '../shared/index.ts'
 
 interface AppProps {
   engine: QueryEngine
@@ -49,13 +50,29 @@ interface AgentProgress {
 // Version is read fresh from package.json at startup via runApp prop
 // (bypasses Bun module caching after npm update)
 
-type PermissionMode = 'auto' | 'ask' | 'bypass'
-
-const PERMISSION_MODES: PermissionMode[] = ['auto', 'ask', 'bypass']
+const PERMISSION_MODES: PermissionMode[] = [
+  'default',
+  'acceptEdits',
+  'plan',
+  'auto',
+  'dontAsk',
+  'bypassPermissions',
+]
 const PERMISSION_LABELS: Record<PermissionMode, string> = {
-  auto: 'auto mode on',
-  ask: 'ask mode (confirm each action)',
-  bypass: 'bypass mode (skip all checks)',
+  default: 'default · reads free',
+  acceptEdits: 'accept edits · reads + edits free',
+  plan: 'plan mode · read-only',
+  auto: 'auto mode · hooks gate',
+  dontAsk: "don't ask · pre-approved only",
+  bypassPermissions: 'bypass · skip all checks',
+}
+const PERMISSION_COLORS: Record<PermissionMode, string> = {
+  default: 'white',
+  acceptEdits: 'blue',
+  plan: 'yellow',
+  auto: 'green',
+  dontAsk: 'cyan',
+  bypassPermissions: 'red',
 }
 
 export function App({
@@ -78,7 +95,7 @@ export function App({
   const [effort, setEffort] = useState('high')
   const [focusMode, setFocusMode] = useState(false)
   const [goalText, setGoalText] = useState('')
-  const [permissionMode, setPermissionMode] = useState<PermissionMode>('auto')
+  const [permissionMode, setPermissionMode] = useState<PermissionMode>('default')
   const abortRef = useRef<AbortController | null>(null)
   const [agentProgress, setAgentProgress] = useState<AgentProgress | null>(null)
   const [agentElapsed, setAgentElapsed] = useState(0)
@@ -304,6 +321,24 @@ export function App({
               { role: 'system', content: `❌ Error: ${chunk.error}` },
             ])
           }
+
+          if (chunk.type === 'task_notification' && chunk.taskNotification) {
+            const tn = chunk.taskNotification
+            const emoji = tn.status === 'completed' ? '✅' : '❌'
+            const label = tn.status === 'completed' ? 'completed' : 'failed'
+            const preview = tn.content
+              ? tn.content.slice(0, 120) + (tn.content.length > 120 ? '...' : '')
+              : tn.error
+                ? `Error: ${tn.error.slice(0, 120)}`
+                : '(no output)'
+            setMessages((prev) => [
+              ...prev,
+              {
+                role: 'system',
+                content: `${emoji} Background Agent ${label}: ${tn.description}\n   ID: ${tn.taskId}\n   ${preview}`,
+              },
+            ])
+          }
         }
       } catch (err) {
         setMessages((prev) => [...prev, { role: 'system', content: `Error: ${String(err)}` }])
@@ -365,13 +400,13 @@ export function App({
       })
       return
     }
-    // Shift+Tab → cycle permission mode (auto → ask → bypass → auto)
+    // Shift+Tab → cycle through all 6 permission modes
     if (key.shift && key.tab) {
       setPermissionMode((prev) => {
         const idx = PERMISSION_MODES.indexOf(prev)
         const next = PERMISSION_MODES[(idx + 1) % PERMISSION_MODES.length]!
-        // Sync to engine
-        engine.getPermission().setDefaultLevel(next)
+        // Sync to engine — use setMode for proper mode semantics
+        engine.getPermission().setMode(next)
         return next
       })
       return
@@ -441,17 +476,12 @@ export function App({
           </Box>
         )}
         <Box flexDirection="row">
-          <Text
-            color={
-              permissionMode === 'auto' ? 'green' : permissionMode === 'ask' ? 'yellow' : 'red'
-            }
-          >
+          <Text color={PERMISSION_COLORS[permissionMode]}>
             ● {PERMISSION_LABELS[permissionMode]}
           </Text>
-          <Text dimColor> · ⏵⏵ accept edits on</Text>
-          <Text dimColor> (Shift+Tab to cycle)</Text>
-          <Text dimColor> · Ctrl+P pick · /help /commands · Esc cancel</Text>
-          <Text dimColor> · ← agents</Text>
+          <Text dimColor> · Shift+Tab mode</Text>
+          <Text dimColor> · Ctrl+P model · Ctrl+O expand</Text>
+          <Text dimColor> · Esc cancel · /help · ← agents</Text>
         </Box>
       </Box>
     </Box>

package/src/ui/commands.ts

@@ -392,18 +392,16 @@ const skillsCmd: CommandHandler = (ctx) => {
 // Workflow
 // ═══════════════════════════════════════════════════════════════
 
-const planCmd: CommandHandler = (_ctx) => ({
-  content: stripIndent`
-    ── Plan Mode ──
-    Plan mode activated — read-only analysis and design.
-    No code will be modified. Use /no-plan to exit.
-
-    In plan mode you can:
-    • Explore codebase and analyze architecture
-    • Design implementation approaches
-    • Create structured plans before coding
-  `,
-})
+const planCmd: CommandHandler = (_ctx, args) => {
+  const description = args.join(' ') || undefined
+  return {
+    content:
+      '── Plan Mode ──\n\nEntering plan mode — read-only analysis and design.\nUse EnterPlanMode to start, ExitPlanMode to submit for approval.',
+    forwardToAI: description
+      ? `Use EnterPlanMode with description: "${description}". Then explore, design, and use ExitPlanMode when ready for approval.`
+      : 'Use EnterPlanMode to enter plan mode. Explore the codebase, design an approach, then use ExitPlanMode to submit for approval.',
+  }
+}
 
 const tddCmd: CommandHandler = (_ctx, args) => {
   const target = args.join(' ') || 'the current task'

package/src/workflow/primitives/agent.ts

@@ -1,6 +1,7 @@
 import { SubAgent } from '../../agent/sub-agent'
 import type { ProviderRegistry } from '../../providers/registry'
 import type { ToolDefinition } from '../../shared/index.ts'
+import { validateJSONSchema, formatValidationErrors } from '../schema-validator'
 
 export interface WorkflowAgentOpts {
   label?: string
@@ -9,11 +10,19 @@ export interface WorkflowAgentOpts {
   model?: string
   provider?: string
   effort?: 'low' | 'medium' | 'high' | 'max'
+  /** Maximum retries on schema validation failure (default: 2). */
+  maxRetries?: number
 }
 
 /**
  * Workflow agent() primitive — creates a SubAgent with optional
- * provider/model override and structured output schema.
+ * provider/model override and structured output schema validation.
+ *
+ * When `schema` is provided:
+ *   1. The sub-agent is prompted to return valid JSON matching the schema.
+ *   2. The result is JSON.parsed and validated against the schema.
+ *   3. On validation failure, the sub-agent is retried with error feedback.
+ *   4. Returns the validated object, or { raw, validationErrors } on final failure.
  */
 export async function workflowAgent(
   prompt: string,
@@ -28,24 +37,77 @@ export async function workflowAgent(
     registry.switchProvider(registry.getActive().config.id, opts.model)
   }
 
-  const sub = new SubAgent(registry, toolRegistry)
-  const result = await sub.execute(prompt, opts.label || 'workflow-agent', {
-    type: 'general',
-    modelOverride: opts.model,
-    allowedTools: undefined, // use all tools by default
-  })
+  const maxRetries = opts.maxRetries ?? 2
 
-  // If schema is provided, attempt to parse the result as JSON
+  // Build the prompt — if schema is requested, instruct the model to return JSON
+  let effectivePrompt = prompt
   if (opts.schema) {
+    const schemaDesc = JSON.stringify(opts.schema, null, 2)
+    effectivePrompt =
+      `${prompt}\n\n` +
+      `IMPORTANT: Your response MUST be valid JSON matching this schema:\n` +
+      `\`\`\`json\n${schemaDesc}\n\`\`\`\n` +
+      `Return ONLY the JSON object, no other text. Do not wrap in markdown code fences.`
+  }
+
+  const sub = new SubAgent(registry, toolRegistry)
+
+  // ── Attempt execution with optional schema validation + retry ──
+  let lastResult = ''
+  let lastErrors: string[] = []
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const retryPrompt =
+      attempt === 0
+        ? effectivePrompt
+        : `${effectivePrompt}\n\n` +
+          `[RETRY #${attempt}] Your previous response did NOT match the required schema.\n` +
+          `Validation errors:\n${lastErrors.map((e) => `  • ${e}`).join('\n')}\n\n` +
+          `Please fix the errors and return a valid JSON object matching the schema exactly.`
+
+    const result = await sub.execute(retryPrompt, opts.label || 'workflow-agent', {
+      type: 'general',
+      modelOverride: opts.model,
+      allowedTools: undefined, // use all tools by default
+    })
+
+    lastResult = result
+
+    // No schema — return raw result
+    if (!opts.schema) {
+      return result
+    }
+
+    // Try to parse and validate
     try {
-      const parsed = JSON.parse(result)
-      // Basic validation: return parsed object
-      return parsed
-    } catch {
-      // Return raw text if JSON parse fails
-      return { raw: result }
+      // Extract JSON from potential markdown fences
+      let jsonStr = result.trim()
+      const fenceMatch = jsonStr.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/)
+      if (fenceMatch) {
+        jsonStr = fenceMatch[1]!.trim()
+      }
+
+      const parsed = JSON.parse(jsonStr)
+      const errors = validateJSONSchema(parsed, opts.schema as Record<string, unknown>)
+
+      if (errors.length === 0) {
+        // Valid! Return the parsed object
+        return parsed
+      }
+
+      // Not valid — collect errors for retry
+      lastErrors = [formatValidationErrors(errors)]
+    } catch (err) {
+      // JSON parse error
+      lastErrors = [`JSON parse error: ${String(err)}. Ensure your response is valid JSON only.`]
     }
   }
 
-  return result
+  // All retries exhausted — return raw result with validation errors
+  try {
+    const parsed = JSON.parse(lastResult)
+    return { raw: lastResult, parsed, validationErrors: lastErrors }
+  } catch {
+    return { raw: lastResult, validationErrors: lastErrors }
+  }
 }

package/src/workflow/runtime.ts

@@ -1,5 +1,5 @@
 import { createSandbox } from './sandbox'
-import { createJournal, appendJournal } from './journal'
+import { createJournal, appendJournal, loadJournal, loadScript } from './journal'
 import { createBudget } from './budget'
 import { workflowAgent } from './primitives/agent'
 import { parallel } from './primitives/parallel'
@@ -12,30 +12,103 @@ export interface WorkflowRunResult {
   runId: string
   result: unknown
   journalEntries: number
+  /** Number of agent() calls served from cache (only set when resumeFromRunId is used). */
+  cacheHits: number
+  /** Number of agent() calls executed live (only set when resumeFromRunId is used). */
+  cacheMisses: number
+}
+
+/**
+ * Generate a cache key for an agent() call.
+ * Uses prompt + deterministic subset of opts.
+ */
+function agentCacheKey(prompt: string, opts: Record<string, unknown> = {}): string {
+  const relevant = {
+    prompt,
+    label: opts.label,
+    phase: opts.phase,
+    model: opts.model,
+    provider: opts.provider,
+  }
+  return JSON.stringify(relevant)
 }
 
 /**
  * Execute a workflow script string.
  *
- * The script is evaluated in a sandboxed context with the workflow
- * primitives (agent, parallel, pipeline, phase, args, budget) injected.
+ * When `resumeFromRunId` is provided:
+ *   - Loads the journal from the prior run
+ *   - Compares the current script against the saved script
+ *   - Builds a cache from prior agent() results (keyed by prompt+opts)
+ *   - New agent() calls that match the cache return the cached result
+ *   - New/changed agent() calls execute live and append to the journal
+ *   - Returns cacheHits and cacheMisses counts
+ *
+ * The sandbox blocks non-deterministic APIs (Date.now, Math.random) to make
+ * this deterministic replay possible.
  */
 export async function runWorkflow(
   script: string,
   engine: QueryEngine,
   args: unknown = {},
   budgetTotal: number | null = null,
+  resumeFromRunId?: string,
 ): Promise<WorkflowRunResult> {
-  const runId = `run-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
-  createJournal(runId, script)
+  let runId: string
+  let cacheHits = 0
+  let cacheMisses = 0
+
+  // ── Resume mode: load prior journal, build cache ──
+  let resultCache: Map<string, unknown> | null = null
+  if (resumeFromRunId) {
+    const savedScript = loadScript(resumeFromRunId)
+    if (savedScript && savedScript !== script) {
+      // Script changed — warn but proceed (cache may have stale entries)
+      process.stderr.write(
+        `[workflow] ⚠ Script differs from saved run "${resumeFromRunId}". ` +
+          `Cache may contain stale entries for changed agent calls.\n`,
+      )
+    }
+
+    const priorEntries = loadJournal(resumeFromRunId)
+    if (priorEntries.length === 0) {
+      process.stderr.write(
+        `[workflow] ⚠ No journal entries found for run "${resumeFromRunId}". Proceeding without cache.\n`,
+      )
+    } else {
+      resultCache = new Map()
+      for (const entry of priorEntries) {
+        if (entry.type === 'agent' && entry.prompt && entry.result !== undefined) {
+          const key = agentCacheKey(entry.prompt, entry.opts || {})
+          resultCache.set(key, entry.result)
+        }
+      }
+    }
+
+    // Re-use the existing run directory for appending
+    runId = resumeFromRunId
+  } else {
+    runId = `run-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+    createJournal(runId, script)
+  }
 
   const registry: ProviderRegistry = engine.getRegistry()
   const toolRegistry = engine.getTools()
 
   const budget = createBudget(budgetTotal)
 
-  // Wrap primitives with journal recording
+  // Wrap primitives with journal recording + cache support
   const agent = async (prompt: string, opts?: Record<string, unknown>) => {
+    // Check cache first
+    if (resultCache) {
+      const key = agentCacheKey(prompt, opts || {})
+      if (resultCache.has(key)) {
+        cacheHits++
+        return resultCache.get(key)!
+      }
+    }
+    cacheMisses++
+
     const result = await workflowAgent(
       prompt,
       registry,
@@ -83,5 +156,9 @@ export async function runWorkflow(
 
   const result = await scriptFn(agent, parallel, pipeline, wrappedPhase, log, args, budget)
 
-  return { runId, result, journalEntries: 0 }
+  // Count journal entries from state
+  const priorEntries = loadJournal(runId)
+  const journalEntries = priorEntries.length
+
+  return { runId, result, journalEntries, cacheHits, cacheMisses }
 }

package/src/workflow/schema-validator.ts

@@ -0,0 +1,162 @@
+/**
+ * Lightweight JSON Schema validator for workflow agent() schema parameter.
+ *
+ * Supports:
+ *   - type: string | number | integer | boolean | object | array
+ *   - properties (objects), items (arrays), required, enum
+ *   - Nested objects and arrays (recursive validation)
+ *
+ * Zero external dependencies — pure TypeScript implementation.
+ */
+
+export interface ValidationError {
+  path: string // JSON path to the error, e.g. "$.name" or "$.items[0].value"
+  message: string
+}
+
+/**
+ * Validate `data` against a JSON Schema definition.
+ * Returns an array of ValidationError — empty means valid.
+ */
+export function validateJSONSchema(
+  data: unknown,
+  schema: Record<string, unknown>,
+): ValidationError[] {
+  const errors: ValidationError[] = []
+  _validate(data, schema, '$', errors)
+  return errors
+}
+
+/**
+ * Format validation errors into a human-readable message for LLM feedback.
+ */
+export function formatValidationErrors(errors: ValidationError[]): string {
+  if (errors.length === 0) return ''
+  return errors.map((e) => `  • ${e.path}: ${e.message}`).join('\n')
+}
+
+// ── Internal recursive validator ──
+
+function _validate(
+  data: unknown,
+  schema: Record<string, unknown>,
+  path: string,
+  errors: ValidationError[],
+): void {
+  const type = schema.type as string | undefined
+
+  // ── Null check ──
+  if (data === null || data === undefined) {
+    // If required, the parent object handles this. Here we just check type mismatch.
+    if (type && type !== 'null') {
+      errors.push({ path, message: `expected ${type}, got null` })
+    }
+    return
+  }
+
+  // ── Type checking ──
+  if (type) {
+    const actualType = Array.isArray(data) ? 'array' : typeof data
+    const expectedType = type === 'integer' ? 'number' : type
+
+    if (expectedType === 'number' && actualType === 'number') {
+      // OK — integer is a subset of number
+    } else if (expectedType !== actualType) {
+      errors.push({ path, message: `expected type "${type}", got "${actualType}"` })
+      return // Can't validate further if type is wrong
+    }
+
+    // Integer check
+    if (type === 'integer' && !Number.isInteger(data)) {
+      errors.push({ path, message: `expected integer, got ${data}` })
+    }
+  }
+
+  // ── Enum validation ──
+  if (schema.enum && Array.isArray(schema.enum)) {
+    if (!schema.enum.includes(data)) {
+      errors.push({
+        path,
+        message: `value must be one of: ${schema.enum.map((v) => JSON.stringify(v)).join(', ')}`,
+      })
+    }
+  }
+
+  // ── Object validation ──
+  if (type === 'object' || (!type && typeof data === 'object' && !Array.isArray(data))) {
+    const obj = data as Record<string, unknown>
+    const properties = schema.properties as Record<string, Record<string, unknown>> | undefined
+    const required = schema.required as string[] | undefined
+
+    // Required fields
+    if (required) {
+      for (const field of required) {
+        if (obj[field] === undefined || obj[field] === null) {
+          errors.push({ path: `${path}.${field}`, message: `required field is missing` })
+        }
+      }
+    }
+
+    // Property validation
+    if (properties) {
+      for (const [key, propSchema] of Object.entries(properties)) {
+        const value = obj[key]
+        if (value !== undefined && value !== null) {
+          _validate(value, propSchema, `${path}.${key}`, errors)
+        }
+      }
+    }
+  }
+
+  // ── Array validation ──
+  if (type === 'array' || (!type && Array.isArray(data))) {
+    const arr = data as unknown[]
+    const items = schema.items as Record<string, unknown> | undefined
+
+    if (items) {
+      for (let i = 0; i < arr.length; i++) {
+        _validate(arr[i], items, `${path}[${i}]`, errors)
+      }
+    }
+
+    // minItems / maxItems
+    if (schema.minItems !== undefined && arr.length < (schema.minItems as number)) {
+      errors.push({
+        path,
+        message: `array has ${arr.length} items, minimum is ${schema.minItems}`,
+      })
+    }
+    if (schema.maxItems !== undefined && arr.length > (schema.maxItems as number)) {
+      errors.push({
+        path,
+        message: `array has ${arr.length} items, maximum is ${schema.maxItems}`,
+      })
+    }
+  }
+
+  // ── String validation ──
+  if ((type === 'string' || typeof data === 'string') && typeof data === 'string') {
+    if (schema.minLength !== undefined && data.length < (schema.minLength as number)) {
+      errors.push({
+        path,
+        message: `string length ${data.length} is less than minimum ${schema.minLength}`,
+      })
+    }
+    if (schema.maxLength !== undefined && data.length > (schema.maxLength as number)) {
+      errors.push({
+        path,
+        message: `string length ${data.length} exceeds maximum ${schema.maxLength}`,
+      })
+    }
+  }
+
+  // ── Number validation ──
+  if ((type === 'number' || type === 'integer') && typeof data === 'number') {
+    if (schema.minimum !== undefined && data < (schema.minimum as number)) {
+      errors.push({ path, message: `value ${data} is less than minimum ${schema.minimum}` })
+    }
+    if (schema.maximum !== undefined && data > (schema.maximum as number)) {
+      errors.push({ path, message: `value ${data} exceeds maximum ${schema.maximum}` })
+    }
+  }
+}