@miphamai/cli 0.4.0 → 0.5.1

package/src/skills/loader.ts

@@ -1,5 +1,6 @@
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
+import { homedir } from 'node:os'
 import { parse as parseYaml } from 'yaml'
 import type { SkillDefinition } from '../shared/index.ts'
 
@@ -94,6 +95,12 @@ export class SkillsLoader {
         tools: data.tools as SkillDefinition['tools'],
         hooks: data.hooks as SkillDefinition['hooks'],
         prompts: data.prompts as SkillDefinition['prompts'],
+        // NEW: frontmatter fields for fork/auto-trigger support
+        context: data.context as string | undefined,
+        model: data.model as string | undefined,
+        allowedTools: data['allowed-tools'] as string[] | undefined,
+        disableModelInvocation: data['disable-model-invocation'] as boolean | undefined,
+        userInvocable: data['user-invocable'] as boolean | undefined,
       }
 
       this.skills.set(skill.name, skill)
@@ -102,6 +109,45 @@ export class SkillsLoader {
     }
   }
 
+  /**
+   * Build the system-reminder block for AI auto-triggering.
+   * Injects available skill names + descriptions so the AI can match
+   * user requests to relevant skills.
+   */
+  buildSystemReminder(maxTokens: number = 5000): string {
+    const skills = this.list().filter((s) => {
+      // Skip skills that disable model invocation
+      return !s.disableModelInvocation
+    })
+
+    if (skills.length === 0) return ''
+
+    const lines: string[] = [
+      '<system-reminder>',
+      'The following skills are available. Invoke via the Skill tool when relevant:',
+    ]
+
+    let tokenBudget = 0
+    for (const skill of skills) {
+      const entry = `- ${skill.name}: ${skill.description}`
+      const entryTokens = Math.ceil(entry.length / 4) + 1 // rough estimate
+      if (tokenBudget + entryTokens > maxTokens) break
+
+      lines.push(entry)
+      tokenBudget += entryTokens
+    }
+
+    lines.push('</system-reminder>')
+    return lines.join('\n')
+  }
+
+  /** Load skills from ~/.mipham/skills/ (user home directory). */
+  loadUserSkills(): void {
+    const home = homedir()
+    const userSkillsPath = join(home, '.mipham', 'skills')
+    this.loadExternal([userSkillsPath])
+  }
+
   private nameFromPath(path: string): string {
     const base = path.split('/').pop() || ''
     return base.replace(/\.(SKILL|mipham-skill)\.md$/i, '')

package/src/tools/agent/agent.ts

@@ -1,5 +1,6 @@
 import type { ToolDefinition } from '../../shared/index.ts'
-import { SubAgent, type SubAgentType } from '../../agent/sub-agent'
+import { SubAgent } from '../../agent/sub-agent'
+import type { SubAgentType } from '../../agent/types'
 
 const VALID_TYPES: SubAgentType[] = ['general', 'explore', 'plan', 'code-review']
 
@@ -35,17 +36,25 @@ export const agentTool: ToolDefinition = {
     }
 
     const registry = ctx.registry
-    if (!registry) {
-      // No registry in context — return structured simulation
-      const sub = new SubAgent(
-        null as unknown as import('../../providers/registry').ProviderRegistry,
-      )
-      const result = await sub.execute(prompt, description, { type: agentType })
-      return { success: true, content: result }
+    const toolRegistry = ctx.toolRegistry
+    if (!registry || !toolRegistry) {
+      return {
+        success: false,
+        content: '',
+        error:
+          'Sub-agent execution requires an active provider and tool registry. Connect a provider API key first.',
+      }
     }
 
-    const sub = new SubAgent(registry)
-    const result = await sub.execute(prompt, description, { type: agentType })
-    return { success: true, content: result }
+    // Resolve agent definition from registry (custom > builtin)
+    const agentDef = ctx.agentRegistry?.resolve(agentType)
+
+    try {
+      const sub = new SubAgent(registry, toolRegistry)
+      const result = await sub.execute(prompt, description, { type: agentType, agentDef })
+      return { success: true, content: result }
+    } catch (err) {
+      return { success: false, content: '', error: String(err) }
+    }
   },
 }

package/src/tools/agent/skill.ts

@@ -1,4 +1,5 @@
-import type { ToolDefinition } from '../../shared/index.ts'
+import type { ToolDefinition, SkillDefinition, ToolResult } from '../../shared/index.ts'
+import { executeForkedSkill } from '../../skills/fork-executor'
 
 export const skillTool: ToolDefinition = {
   name: 'Skill',
@@ -34,7 +35,36 @@ export const skillTool: ToolDefinition = {
         }
       }
 
-      // Build skill invocation content
+      // Check if skill has context: fork — execute in isolated subagent
+      if (skill.context === 'fork') {
+        const registry = ctx.registry
+        if (!registry) {
+          return {
+            success: false,
+            content: '',
+            error: 'Provider registry not available for forked skill execution.',
+          }
+        }
+
+        try {
+          const result = await executeForkedSkill(
+            skill,
+            args,
+            registry,
+            ctx.toolRegistry || new Map(),
+          )
+          // Return to AI as internal context
+          return { success: true, content: `[Forked skill "${skillName}" result]:\n${result}` }
+        } catch (err) {
+          return {
+            success: false,
+            content: '',
+            error: `Forked skill execution failed: ${String(err)}`,
+          }
+        }
+      }
+
+      // Standard inline execution — return metadata for AI to follow
       const lines: string[] = [
         `── Skill Invoked: ${skill.name} ──`,
         `Type: ${skill.type} | Version: ${skill.version}`,

package/src/tools/computer/app-launcher.ts

@@ -0,0 +1,39 @@
+import { execSync } from 'node:child_process'
+
+const ALLOWED_APPS = new Set([
+  'Finder',
+  'Safari',
+  'Google Chrome',
+  'Firefox',
+  'Terminal',
+  'VS Code',
+  'System Settings',
+  'Activity Monitor',
+  'TextEdit',
+  'Preview',
+])
+
+export function launchApp(appName: string): { success: boolean; message: string } {
+  if (!ALLOWED_APPS.has(appName)) {
+    return {
+      success: false,
+      message: `App "${appName}" is not in the allowed list. Allowed: ${[...ALLOWED_APPS].join(', ')}`,
+    }
+  }
+
+  try {
+    const platform = process.platform
+    if (platform === 'darwin') {
+      execSync(`open -a "${appName}"`, { timeout: 5000 })
+    } else if (platform === 'linux') {
+      execSync(`xdg-open "${appName}"`, { timeout: 5000 })
+    } else if (platform === 'win32') {
+      execSync(`start "" "${appName}"`, { timeout: 5000, shell: 'cmd.exe' })
+    } else {
+      return { success: false, message: `Unsupported platform: ${platform}` }
+    }
+    return { success: true, message: `Launched: ${appName}` }
+  } catch (err) {
+    return { success: false, message: `Failed to launch ${appName}: ${String(err)}` }
+  }
+}

package/src/tools/computer/browser.ts

@@ -0,0 +1,48 @@
+let browserPromise: Promise<unknown> | null = null
+
+async function getPage(): Promise<unknown> {
+  if (!browserPromise) {
+    // Dynamic import — Playwright is optional
+    let playwrightModule: { chromium: unknown }
+    try {
+      playwrightModule = await import('playwright')
+    } catch {
+      throw new Error('Playwright is not installed. Install it with: npm install playwright')
+    }
+    const { chromium } = playwrightModule as {
+      chromium: {
+        launch: (opts?: Record<string, unknown>) => Promise<{
+          newPage: () => Promise<unknown>
+        }>
+      }
+    }
+    const browser = await chromium.launch({ headless: false })
+    browserPromise = browser.newPage()
+  }
+  return browserPromise
+}
+
+export async function browserNavigate(url: string): Promise<string> {
+  const page = (await getPage()) as {
+    goto: (u: string) => Promise<void>
+    url: () => string
+  }
+  await page.goto(url)
+  return `Navigated to: ${page.url()}`
+}
+
+export async function browserSnapshot(): Promise<string> {
+  const page = (await getPage()) as {
+    accessibility: { snapshot: () => Promise<unknown> }
+  }
+  const snapshot = await page.accessibility.snapshot()
+  return JSON.stringify(snapshot, null, 2)
+}
+
+export async function browserClick(uid: string): Promise<string> {
+  const page = (await getPage()) as {
+    locator: (s: string) => { click: () => Promise<void> }
+  }
+  await page.locator(`[uid="${uid}"]`).click()
+  return `Clicked: ${uid}`
+}

package/src/tools/computer/computer-use.ts

@@ -0,0 +1,88 @@
+import type { ToolDefinition } from '../../shared/index.ts'
+import { takeScreenshot } from './screenshot'
+import { launchApp } from './app-launcher'
+import { browserNavigate, browserSnapshot, browserClick } from './browser'
+
+export const computerUseTool: ToolDefinition = {
+  name: 'ComputerUse',
+  description:
+    'Take screenshots, launch apps, or control a browser. Always requires user approval.',
+  category: 'system',
+  permission: 'ask', // ALWAYS ask — security requirement
+  parameters: {
+    type: 'object',
+    properties: {
+      action: {
+        type: 'string',
+        enum: ['screenshot', 'launch', 'browser_navigate', 'browser_snapshot', 'browser_click'],
+        description: 'The computer-use action to perform',
+      },
+      target: {
+        type: 'string',
+        description: 'App name (launch), URL (browser_navigate), or element UID (browser_click)',
+      },
+      text: {
+        type: 'string',
+        description: 'Text to type (reserved for future browser_type action)',
+      },
+    },
+    required: ['action'],
+  },
+  async execute(params, _ctx) {
+    const action = params.action as string
+    const target = (params.target as string) || ''
+
+    switch (action) {
+      case 'screenshot': {
+        const result = await takeScreenshot()
+        return result.success
+          ? { success: true, content: `Screenshot captured: ${result.data!.slice(0, 100)}...` }
+          : { success: false, content: '', error: result.error }
+      }
+      case 'launch': {
+        const result = launchApp(target)
+        return result.success
+          ? { success: true, content: result.message }
+          : { success: false, content: '', error: result.message }
+      }
+      case 'browser_navigate': {
+        try {
+          const url = await browserNavigate(target)
+          return { success: true, content: url }
+        } catch (err) {
+          return {
+            success: false,
+            content: '',
+            error: `Browser navigation failed: ${String(err)}`,
+          }
+        }
+      }
+      case 'browser_snapshot': {
+        try {
+          const snapshot = await browserSnapshot()
+          return { success: true, content: snapshot }
+        } catch (err) {
+          return {
+            success: false,
+            content: '',
+            error: `Browser snapshot failed: ${String(err)}`,
+          }
+        }
+      }
+      case 'browser_click': {
+        try {
+          const result = await browserClick(target)
+          return { success: true, content: result }
+        } catch (err) {
+          return {
+            success: false,
+            content: '',
+            error: `Browser click failed: ${String(err)}`,
+          }
+        }
+      }
+      default:
+        return { success: false, content: '', error: `Unknown action: ${action}` }
+    }
+  },
+}

package/src/tools/computer/playwright.d.ts

@@ -0,0 +1,7 @@
+declare module 'playwright' {
+  export const chromium: {
+    launch: (opts?: Record<string, unknown>) => Promise<{
+      newPage: () => Promise<unknown>
+    }>
+  }
+}

package/src/tools/computer/screenshot.ts

@@ -0,0 +1,57 @@
+import { execSync } from 'node:child_process'
+import { readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+export async function takeScreenshot(): Promise<{
+  success: boolean
+  data?: string
+  error?: string
+}> {
+  const tmpPath = join(tmpdir(), `mipham-screenshot-${Date.now()}.png`)
+
+  try {
+    const platform = process.platform
+    if (platform === 'darwin') {
+      execSync(`screencapture -x ${tmpPath}`, { timeout: 10000 })
+    } else if (platform === 'linux') {
+      execSync(`import -window root ${tmpPath}`, { timeout: 10000 })
+    } else if (platform === 'win32') {
+      // PowerShell script to capture primary screen and save as PNG
+      const psScript = `
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+$screen = [System.Windows.Forms.Screen]::PrimaryScreen
+$bitmap = New-Object System.Drawing.Bitmap($screen.Bounds.Width, $screen.Bounds.Height)
+$graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+$graphics.CopyFromScreen($screen.Bounds.X, $screen.Bounds.Y, 0, 0, $bitmap.Size)
+$bitmap.Save('${tmpPath.replace(/\\/g, '\\\\')}', [System.Drawing.Imaging.ImageFormat]::Png)
+$graphics.Dispose()
+$bitmap.Dispose()
+      `.trim()
+      const psPath = join(tmpdir(), `mipham-sc-${Date.now()}.ps1`)
+      writeFileSync(psPath, psScript, 'utf-8')
+      execSync(`powershell -ExecutionPolicy Bypass -File "${psPath}"`, { timeout: 15000 })
+      try {
+        unlinkSync(psPath)
+      } catch {
+        // ignore cleanup failures
+      }
+    }
+
+    const data = readFileSync(tmpPath, 'base64')
+    try {
+      unlinkSync(tmpPath)
+    } catch {
+      // ignore cleanup failures
+    }
+    return { success: true, data: `data:image/png;base64,${data}` }
+  } catch (err) {
+    try {
+      unlinkSync(tmpPath)
+    } catch {
+      // ignore cleanup failures
+    }
+    return { success: false, error: `Screenshot failed: ${String(err)}` }
+  }
+}

package/src/tools/index.ts

@@ -16,6 +16,7 @@ import { webSearchTool } from './network/web-search'
 import { configTool } from './system/config'
 import { mcpTool } from './system/mcp'
 import { artifactTool } from './artifact/artifact'
+import { computerUseTool } from './computer/computer-use'
 
 /**
  * Validate tool parameters against the tool's JSON Schema definition.
@@ -119,6 +120,8 @@ export function createToolRegistry(): Map<string, ToolDefinition> {
     withValidation(mcpTool),
     // Artifact tools
     withValidation(artifactTool),
+    // Computer Use tools
+    withValidation(computerUseTool),
   ]
 
   const map = new Map<string, ToolDefinition>()

package/src/tools/network/web-fetch.ts

@@ -28,7 +28,7 @@ export const webFetchTool: ToolDefinition = {
       const timer = setTimeout(() => controller.abort(), 30_000) // 30s timeout
 
       const response = await fetch(url, {
-        headers: { 'User-Agent': 'Mipham-Code/0.1.0' },
+        headers: { 'User-Agent': 'Mipham-Code/0.5.0' },
         redirect: 'follow',
         signal: controller.signal,
       })

package/src/ui/app.tsx

@@ -1,8 +1,9 @@
-import React, { useState, useCallback, useRef } from 'react'
+import React, { useState, useCallback, useRef, useMemo } from 'react'
 import { Box, Text, useInput } from 'ink'
 import type { QueryEngine } from '../core/engine'
 import type { MiphamConfig } from '../shared/index.ts'
 import type { SkillsLoader } from '../skills/loader'
+import { AgentRegistry } from '../agent/agent-registry'
 import { ChatPanel } from './chat'
 import { InputBar } from './input'
 import { ModelPicker } from './picker'
@@ -42,7 +43,9 @@ interface AgentProgress {
   startTime: number
 }
 
-const VERSION = '0.3.0'
+import { PACKAGE_VERSION } from '@mipham/shared'
+
+const VERSION = PACKAGE_VERSION
 
 type PermissionMode = 'auto' | 'ask' | 'bypass'
 
@@ -88,6 +91,14 @@ export function App({
     return () => clearInterval(interval)
   }, [agentProgress])
 
+  // Initialize agent registry (one-time, on mount)
+  useMemo(() => {
+    const agentRegistry = new AgentRegistry()
+    agentRegistry.loadUserAgents()
+    agentRegistry.loadProjectAgents(process.cwd())
+    engine.setAgentRegistry(agentRegistry)
+  }, [])
+
   const mkCtx = useCallback(
     (): CommandContext => ({
       engine,
@@ -348,7 +359,7 @@ export function App({
           <Text bold color="cyan">
             Mipham Code
           </Text>
-          <Text dimColor> v0.3.0</Text>
+          <Text dimColor> v{VERSION}</Text>
           {sessionTitle ? (
             <Text color="yellow"> — {sessionTitle}</Text>
           ) : (

package/src/ui/commands.ts

@@ -8,7 +8,7 @@ import type { QueryEngine } from '../core/engine'
 import type { MiphamConfig } from '../shared/index.ts'
 import type { SkillsLoader } from '../skills/loader'
 import { McpClient } from '../mcp/client'
-import { NPM_INSTALL_COMMAND, NPM_UPDATE_COMMAND } from '@mipham/shared'
+import { NPM_INSTALL_COMMAND, NPM_UPDATE_COMMAND, PACKAGE_VERSION } from '@mipham/shared'
 
 export interface CommandContext {
   engine: QueryEngine
@@ -51,7 +51,7 @@ type CommandHandler = (
 
 const helpCmd: CommandHandler = (_ctx) => ({
   content: stripIndent`
-    Mipham Code v0.2.0 — Commands
+    Mipham Code v${PACKAGE_VERSION} — Commands
 
     ── Session ──────────────────────────
     /help          Show this help
@@ -126,7 +126,10 @@ const helpCmd: CommandHandler = (_ctx) => ({
     /login         Show API key status
     /logout        Clear credentials guide
     /feedback      Send feedback
-    /agents        Agent management
+
+    ── Agents ──────────────────────────
+    /agents        Agent view dashboard
+    /bg <prompt>   Run a background agent task
 
     Type /exit or Esc to quit.
   `,
@@ -419,6 +422,7 @@ const goalCmd: CommandHandler = (ctx, args) => {
     }
   }
   ctx.setGoal(goal.trim())
+  ctx.engine.setGoal(goal.trim())
   return {
     content: `✓ Goal set: "${goal.trim()}"\n\nUse /status to view progress. Type /goal without arguments to clear.`,
   }
@@ -2078,47 +2082,111 @@ const feedbackCmd: CommandHandler = (ctx, args) => {
 // Phase 4 — Agent Management
 // ═══════════════════════════════════════════════════════════════
 
-const agentsCmd: CommandHandler = () => ({
-  content: `── Agent System ──
+const agentsCmd: CommandHandler = (ctx) => {
+  const agentViewManager = ctx.engine.getAgentViewManager?.()
+  if (!agentViewManager) {
+    return { content: 'Agent View dashboard is initializing...' }
+  }
+  const counts = agentViewManager.countByStatus()
+  const total = counts['needs-input'] + counts.working + counts.completed + counts.failed
+
+  if (total === 0) {
+    return {
+      content: `── Agent View ──
+
+No background agents running.
+
+Use /bg <prompt> to spawn a background agent session.
+
+Example:
+  /bg Fix all TypeScript errors in the project
+  /bg Review the auth module for security issues
+
+Or use the Agent tool in a conversation to launch a sub-agent.`,
+    }
+  }
+
+  const lines: string[] = [
+    '── Agent View ──',
+    '',
+    `  ${total} session(s):`,
+    `  🟡 Needs input: ${counts['needs-input']}`,
+    `  🔵 Working:     ${counts.working}`,
+    `  🟢 Completed:   ${counts.completed}`,
+    `  🔴 Failed:      ${counts.failed}`,
+    '',
+    'Sessions:',
+  ]
+
+  const all = agentViewManager.list()
+  for (const s of all.slice(0, 10)) {
+    const statusIcon: Record<string, string> = {
+      'needs-input': '🟡',
+      working: '🔵',
+      completed: '🟢',
+      failed: '🔴',
+    }
+    const elapsed =
+      s.elapsedMs < 1000
+        ? '<1s'
+        : s.elapsedMs < 60000
+          ? `${Math.floor(s.elapsedMs / 1000)}s`
+          : `${Math.floor(s.elapsedMs / 60000)}m`
+    lines.push(
+      `  ${statusIcon[s.status] || '⚪'} ${s.id} · ${s.provider}/${s.model} · ${elapsed} · ${s.task.slice(0, 50)}`,
+    )
+  }
+
+  if (total > 10) {
+    lines.push(`  ... and ${total - 10} more`)
+  }
 
-Mipham Code includes 4 agent-type tools for structured workflows:
+  lines.push('', 'Run `mipham agents` for the full interactive dashboard with j/k navigation.')
 
-  ┌──────────┬──────────────────────────────────────┬──────────┬──────────────────────────┐
-  │ Agent    │ Category │ Permission │ Parameters                     │
-  ├──────────┼──────────┼────────────┼────────────────────────────────┤
-  │ Agent    │ agent    │ ask        │ description*, prompt*,          │
-  │          │          │            │ subagent_type (optional)        │
-  │ Skill    │ agent    │ auto       │ skill*, args (optional)         │
-  │ Plan     │ agent    │ auto       │ (no required params)            │
-  │ Memory   │ agent    │ auto       │ action* (read|write|list),      │
-  │          │          │            │ name, content                   │
-  └──────────┴──────────┴────────────┴────────────────────────────────┘
+  return { content: lines.join('\n') }
+}
 
-── Agent Descriptions ──
+const bgCmd: CommandHandler = (ctx, args) => {
+  const prompt = args.join(' ')
+  if (!prompt.trim()) {
+    return {
+      content: `Usage: /bg <prompt>
 
-  Agent    Launch a sub-agent for complex, multi-step tasks.
-           Types: general-purpose, Explore, Plan, code-reviewer, etc.
+Spawn a background agent to work on a task while you continue chatting.
 
-  Skill    Invoke a named skill (11 built-in, custom via .SKILL.md).
-           Skills extend AI capabilities with specialized instructions.
+Examples:
+  /bg Run the full test suite and report failures
+  /bg Audit the src/ directory for security issues
+  /bg Generate API documentation from JSDoc comments
 
-  Plan     Enter plan mode — read-only analysis and design.
-           Use before complex changes. Exit with /no-plan.
+Background agents appear in the Agent View dashboard (/agents).`,
+    }
+  }
 
-  Memory   Persistent memory read/write across sessions.
-           Stored in ~/.mipham/memory/ as markdown files.
+  const agentViewManager = ctx.engine.getAgentViewManager?.()
+  if (!agentViewManager) {
+    return { content: 'Agent View manager is initializing...' }
+  }
 
-── Architecture ──
+  const session = agentViewManager.create(prompt, prompt, {
+    provider: ctx.providerId,
+    model: ctx.modelId,
+  })
 
-  User → QueryEngine → Agent Tool → Sub-agent → Tool Results → User
+  agentViewManager.addMessage(session.id, { role: 'user', content: prompt })
+  agentViewManager.updateStatus(session.id, 'working')
 
-  Agent tools are dispatched by the AI during conversations.
-  The AI decides when to use them — you can also request them directly.
+  return {
+    content: `✓ Background agent spawned: ${session.id}
 
-  Full multi-agent orchestration (Workflow tool) is in the M3 milestone.
+  Task:     ${session.task.slice(0, 80)}
+  Provider: ${session.provider} / ${session.model}
+  Status:   working
 
-  Use /tools to see all 16 tools, including the 4 agent tools.`,
-})
+Use /agents to view all background sessions.
+Run \`mipham agents\` for the interactive dashboard.`,
+  }
+}
 
 // ═══════════════════════════════════════════════════════════════
 // Artifacts
@@ -2286,6 +2354,7 @@ registry.set('/login', loginCmd)
 registry.set('/logout', logoutCmd)
 registry.set('/feedback', feedbackCmd)
 registry.set('/agents', agentsCmd)
+registry.set('/bg', bgCmd)
 
 // Artifacts
 registry.set('/artifact', artifactBaseCmd)