@miphamai/cli 0.4.0 → 0.5.1

package/bin/mipham

@@ -1,45 +1,73 @@
 #!/usr/bin/env node
 /**
- * Mipham Code v0.2.0 — @onemipham/cli
+ * Mipham Code — @miphamai/cli
  * Multi-model open-core intelligent coding terminal by MiphamAI
  * License: Apache-2.0 | https://mipham.ai/code
+ *
+ * Node.js wrapper: detects Bun and re-launches with it for the full
+ * interactive experience. Version and package name are read from
+ * package.json (single source of truth).
  */
 
-// Detect runtime and launch accordingly
-const runtime = typeof Bun !== 'undefined' ? 'bun' : 'node'
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
 
-if (runtime === 'bun') {
-  // Bun runtime — import TS source directly
-  import('../src/index.tsx').then((m) => m.runApp({}))
-} else {
-  // Node.js runtime — prompt to use Bun for best experience
-  const nodeVersion = process.versions.node
-  const [major] = nodeVersion.split('.').map(Number)
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'))
+const VERSION = pkg.version
+const PKG_NAME = pkg.name
 
-  if (!major || major < 22) {
-    console.error(`
+// ── Check whether Bun is available ──────────────────────────────────────────
+function hasBun() {
+  try {
+    const result = spawnSync('bun', ['--version'], { stdio: 'pipe', timeout: 5000 })
+    return result.status === 0
+  } catch {
+    return false
+  }
+}
+
+// ── Bun available: re-launch with Bun for the full TUI ──────────────────────
+if (hasBun()) {
+  const tsEntry = path.join(__dirname, 'mipham.ts')
+  const result = spawnSync('bun', ['run', tsEntry, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: process.env,
+  })
+  process.exit(result.status ?? 0)
+}
+
+// ── No Bun: show version info and install guidance ─────────────────────────
+const nodeVersion = process.versions.node
+const [major] = nodeVersion.split('.').map(Number)
+
+if (!major || major < 22) {
+  process.stderr.write(`
 \`mipham\` requires Node.js 22+ or Bun 1.2+.
 
 Current Node.js: ${nodeVersion}
 
-Quick install:
-  npm install -g bun
+Quick install Bun:
+  curl -fsSL https://bun.sh/install | bash
+
+Then run:
   mipham
 
-Or:
-  curl -fsSL https://mipham.ai/install.sh | bash
+Docs: https://mipham.ai/code/docs
 `)
-    process.exit(1)
-  }
+  process.exit(1)
+}
 
-  console.log(`
-\x1b[0;36m\x1b[1m✦ Mipham Code v0.2.0\x1b[0m
-\x1b[0;36m  @onemipham/cli — Multi-model coding agent by MiphamAI\x1b[0m
+process.stdout.write(`
+\x1b[0;36m\x1b[1m✦ Mipham Code v${VERSION}\x1b[0m
+\x1b[0;36m  ${PKG_NAME} — Multi-model coding agent by MiphamAI\x1b[0m
 
 \x1b[0;33m⚠  Bun runtime is recommended for the best Mipham Code experience.\x1b[0m
 
 Quick install Bun:
-  \x1b[0;32mnpm install -g bun\x1b[0m
+  \x1b[0;32mcurl -fsSL https://bun.sh/install | bash\x1b[0m
 
 Then run:
   \x1b[0;32mmipham\x1b[0m
@@ -47,5 +75,4 @@ Then run:
 Install: \x1b[0;34mhttps://mipham.ai/code/install\x1b[0m
 Docs:    \x1b[0;34mhttps://mipham.ai/code/docs\x1b[0m
 `)
-  process.exit(0)
-}
+process.exit(0)

package/bin/mipham.ts

@@ -6,7 +6,193 @@
 
 export {} // ensure module scope (prevents global name collisions)
 
+async function runWorkflowCLI(): Promise<boolean> {
+  const args = process.argv.slice(2)
+  if (args[0] !== 'workflow') return false
+
+  const { Command } = await import('commander')
+  const program = new Command()
+
+  program.name('mipham workflow').description('Workflow orchestration commands')
+
+  program
+    .command('run <script>')
+    .description('Run a workflow script')
+    .option('--args <json>', 'JSON arguments for the workflow')
+    .action(async (scriptPath: string, opts: { args?: string }) => {
+      const { readFileSync } = await import('node:fs')
+      const { runWorkflow } = await import('../src/workflow/runtime')
+      const { loadConfig } = await import('../src/config/loader')
+      const { bootstrapProviders } = await import('../src/providers/bootstrap')
+      const { ContextManager } = await import('../src/core/context')
+      const { QueryEngine } = await import('../src/core/engine')
+      const { createToolRegistry } = await import('../src/tools')
+
+      const script = readFileSync(scriptPath, 'utf-8')
+      const workflowArgs = opts.args ? JSON.parse(opts.args) : {}
+
+      // Bootstrap minimal engine
+      const config = loadConfig()
+      const registry = bootstrapProviders(
+        config.providers,
+        config.defaultProvider,
+        config.defaultModel,
+      )
+      const context = new ContextManager({ maxTokens: 200_000, compactionThreshold: 0.9 })
+      const tools = createToolRegistry()
+      const engine = new QueryEngine(registry, context, tools)
+      engine.setupContextSummarizer()
+
+      const result = await runWorkflow(script, engine, workflowArgs)
+      console.log(JSON.stringify(result, null, 2))
+      process.exit(0)
+    })
+
+  program
+    .command('list')
+    .description('List all workflow runs')
+    .action(async () => {
+      const { listRuns } = await import('../src/workflow/journal')
+      const runs = listRuns()
+      if (runs.length === 0) {
+        console.log('No workflow runs found.')
+      } else {
+        runs.forEach((r) => console.log(r))
+      }
+      process.exit(0)
+    })
+
+  program
+    .command('resume <runId>')
+    .description('Resume a paused workflow')
+    .action(async (runId: string) => {
+      const { loadJournal } = await import('../src/workflow/journal')
+      const entries = loadJournal(runId)
+      if (entries.length === 0) {
+        console.log(`No journal found for run: ${runId}`)
+      } else {
+        console.log(`Resuming workflow ${runId} with ${entries.length} journal entries...`)
+        // Replay completed agents, continue from last state
+      }
+      process.exit(0)
+    })
+
+  program
+    .command('stop <runId>')
+    .description('Stop a running workflow')
+    .action(async (runId: string) => {
+      console.log(`Stopping workflow ${runId}...`)
+      // Mark workflow as stopped in state
+      process.exit(0)
+    })
+
+  // Commander will handle --help, unknown commands, etc.
+  await program.parseAsync(process.argv)
+  return true
+}
+
+async function runPluginCLI(): Promise<boolean> {
+  const args = process.argv.slice(2)
+  if (args[0] !== 'plugin') return false
+
+  const { Command } = await import('commander')
+  const program = new Command()
+
+  program.name('mipham plugin').description('Plugin management commands')
+
+  program
+    .command('install <path>')
+    .description('Install a plugin from a directory path')
+    .action(async (sourcePath: string) => {
+      const { PluginManager } = await import('../src/plugin/plugin-manager')
+      const manager = new PluginManager()
+      const result = manager.install(sourcePath)
+      console.log(result.message)
+      process.exit(result.success ? 0 : 1)
+    })
+
+  program
+    .command('list')
+    .description('List installed plugins')
+    .action(async () => {
+      const { PluginManager } = await import('../src/plugin/plugin-manager')
+      const manager = new PluginManager()
+      const plugins = manager.list()
+      if (plugins.length === 0) {
+        console.log('No plugins installed.')
+      } else {
+        for (const p of plugins) {
+          const status = p.enabled ? 'enabled' : 'disabled'
+          console.log(`${p.name} v${p.version} [${status}] — ${p.installedAt}`)
+        }
+      }
+      process.exit(0)
+    })
+
+  program
+    .command('remove <name>')
+    .description('Remove an installed plugin')
+    .action(async (name: string) => {
+      const { PluginManager } = await import('../src/plugin/plugin-manager')
+      const manager = new PluginManager()
+      const removed = manager.remove(name)
+      if (removed) {
+        console.log(`Plugin "${name}" removed.`)
+      } else {
+        console.log(`Plugin "${name}" not found.`)
+      }
+      process.exit(removed ? 0 : 1)
+    })
+
+  program
+    .command('enable <name>')
+    .description('Enable a disabled plugin')
+    .action(async (name: string) => {
+      const { PluginManager } = await import('../src/plugin/plugin-manager')
+      const manager = new PluginManager()
+      const enabled = manager.enable(name)
+      if (enabled) {
+        console.log(`Plugin "${name}" enabled.`)
+      } else {
+        console.log(`Plugin "${name}" not found.`)
+      }
+      process.exit(enabled ? 0 : 1)
+    })
+
+  program
+    .command('disable <name>')
+    .description('Disable an enabled plugin')
+    .action(async (name: string) => {
+      const { PluginManager } = await import('../src/plugin/plugin-manager')
+      const manager = new PluginManager()
+      const disabled = manager.disable(name)
+      if (disabled) {
+        console.log(`Plugin "${name}" disabled.`)
+      } else {
+        console.log(`Plugin "${name}" not found.`)
+      }
+      process.exit(disabled ? 0 : 1)
+    })
+
+  await program.parseAsync(process.argv)
+  return true
+}
+
 async function main() {
+  // Check for plugin subcommands first
+  const handledPlugin = await runPluginCLI()
+  if (handledPlugin) return
+
+  // Check for workflow subcommands next
+  const handled = await runWorkflowCLI()
+  if (handled) return
+
+  // Parse --safe-mode flag: skip custom agents, skills, hooks, plugins
+  const safeModeFlag = process.argv.includes('--safe-mode')
+  if (safeModeFlag) {
+    process.env.MIPHAM_SAFE_MODE = '1'
+  }
+
   try {
     const { runApp } = await import('../src/index')
     await runApp({})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/src/agent/agent-context.ts

@@ -0,0 +1,56 @@
+// apps/cli/src/agent/agent-context.ts
+import { ContextManager } from '../core/context'
+import type { ToolDefinition } from '../shared/index.ts'
+import type { AgentDefinition } from './types'
+
+export interface AgentContextResult {
+  context: ContextManager
+  allowedTools: ToolDefinition[]
+}
+
+/**
+ * Create an isolated context and tool set for a sub-agent.
+ *
+ * Tool scoping rules (first match wins):
+ * 1. If `tools` is set, only those tools are allowed.
+ * 2. If `disallowedTools` is set, those are removed from the full set.
+ * 3. If neither is set, all tools are available.
+ */
+export function createAgentContext(
+  agentDef: AgentDefinition,
+  toolRegistry: Map<string, ToolDefinition>,
+  contextWindow?: number,
+): AgentContextResult {
+  // Create isolated context
+  const context = new ContextManager({
+    maxTokens: contextWindow || 100_000,
+    compactionThreshold: 0.85,
+  })
+
+  context.setSystemPrompt(agentDef.systemPrompt)
+
+  // Scope tools
+  let allowedTools = Array.from(toolRegistry.values())
+
+  if (agentDef.tools) {
+    const allowSet = new Set(
+      agentDef.tools
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean),
+    )
+    allowedTools = allowedTools.filter((t) => allowSet.has(t.name))
+  }
+
+  if (agentDef.disallowedTools) {
+    const denySet = new Set(
+      agentDef.disallowedTools
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean),
+    )
+    allowedTools = allowedTools.filter((t) => !denySet.has(t.name))
+  }
+
+  return { context, allowedTools }
+}

package/src/agent/agent-registry.ts

@@ -0,0 +1,134 @@
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, extname } from 'node:path'
+import { parse as parseYaml } from 'yaml'
+import type { AgentDefinition, SubAgentType } from './types'
+
+interface FrontmatterResult {
+  data: Record<string, unknown>
+  content: string
+}
+
+function parseFrontmatter(raw: string): FrontmatterResult {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/)
+  if (!match) {
+    return { data: {}, content: raw }
+  }
+  return {
+    data: parseYaml(match[1] || '') as Record<string, unknown>,
+    content: (match[2] || '').trim(),
+  }
+}
+
+const BUILTIN_SYSTEM_PROMPTS: Record<SubAgentType, string> = {
+  general: 'You are a focused sub-agent. Complete the assigned task thoroughly and return results.',
+  explore:
+    'You are an exploration sub-agent. Search, read, and analyze code. Return structured findings with file paths and line numbers.',
+  plan: 'You are a planning sub-agent. Design implementation approaches. Return a step-by-step plan with files to modify.',
+  'code-review':
+    'You are a code review sub-agent. Find bugs, security issues, and code quality problems. Return findings by severity.',
+}
+
+const BUILTIN_DESCRIPTIONS: Record<SubAgentType, string> = {
+  general: 'General-purpose agent for complex multi-step tasks.',
+  explore: 'Read-only search agent for broad fan-out searches across files.',
+  plan: 'Software architect agent for designing implementation plans.',
+  'code-review': 'Code review agent for finding bugs and quality issues.',
+}
+
+export class AgentRegistry {
+  private agents = new Map<string, AgentDefinition>()
+
+  /** Load agents from a directory. Later loads override earlier ones for same name. */
+  loadDirectory(dir: string, source: 'project' | 'user'): void {
+    if (!existsSync(dir)) return
+
+    let entries: string[] = []
+    try {
+      entries = readdirSync(dir)
+    } catch {
+      // Permission errors, missing dir, etc.
+      return
+    }
+
+    for (const entry of entries) {
+      if (extname(entry) !== '.md') continue
+      const fullPath = join(dir, entry)
+      try {
+        const raw = readFileSync(fullPath, 'utf-8')
+        const { data, content } = parseFrontmatter(raw)
+
+        const name = (data.name as string) || entry.replace(/\.md$/, '')
+        const def: AgentDefinition = {
+          name,
+          description: (data.description as string) || '',
+          systemPrompt: content,
+          tools: data.tools as string | undefined,
+          disallowedTools: data.disallowedTools as string | undefined,
+          model: (data.model as string) || 'inherit',
+          permissionMode: (data.permissionMode as string) || 'inherit',
+          maxTurns: data.maxTurns as number | undefined,
+          skills: data.skills
+            ? String(data.skills)
+                .split(',')
+                .map((s) => s.trim())
+            : undefined,
+          background: (data.background as boolean) || false,
+          source,
+          filePath: fullPath,
+        }
+
+        this.agents.set(name, def)
+      } catch {
+        // Skip unparseable files
+      }
+    }
+  }
+
+  /** Load project-level agents from .mipham/agents/ */
+  loadProjectAgents(cwd: string): void {
+    this.loadDirectory(join(cwd, '.mipham', 'agents'), 'project')
+  }
+
+  /** Load user-level agents from ~/.mipham/agents/ */
+  loadUserAgents(): void {
+    const home = homedir()
+    this.loadDirectory(join(home, '.mipham', 'agents'), 'user')
+  }
+
+  /** Get a custom agent by name. Returns undefined for builtins. */
+  get(name: string): AgentDefinition | undefined {
+    return this.agents.get(name)
+  }
+
+  /** List all custom agents. */
+  list(): AgentDefinition[] {
+    return Array.from(this.agents.values())
+  }
+
+  /**
+   * Resolve an agent name to its definition.
+   * Priority: custom (project) > custom (user) > builtin.
+   * Builtins are always available and never return undefined.
+   */
+  resolve(name: string): AgentDefinition | undefined {
+    const custom = this.agents.get(name)
+    if (custom) return custom
+
+    // Check if it's a builtin type
+    const builtinType = name as SubAgentType
+    if (BUILTIN_SYSTEM_PROMPTS[builtinType]) {
+      return {
+        name: builtinType,
+        description: BUILTIN_DESCRIPTIONS[builtinType],
+        systemPrompt: BUILTIN_SYSTEM_PROMPTS[builtinType],
+        model: 'inherit',
+        permissionMode: 'inherit',
+        background: false,
+        source: 'builtin',
+      }
+    }
+
+    return undefined
+  }
+}

package/src/agent/sub-agent.ts

@@ -1,13 +1,7 @@
-import { ContextManager } from '../core/context'
-import type { ProviderRegistry } from '../providers/registry'
-
-export type SubAgentType = 'general' | 'explore' | 'plan' | 'code-review'
-
-interface SubAgentOptions {
-  type?: SubAgentType
-  systemPrompt?: string
-  maxContextMessages?: number
-}
+import type { ProviderRegistry, ProviderInstance } from '../providers/registry'
+import type { ToolDefinition } from '../shared/index.ts'
+import type { SubAgentType, SubAgentOptions, AgentDefinition } from './types'
+import { createAgentContext } from './agent-context'
 
 const TYPE_SYSTEM_PROMPTS: Record<SubAgentType, string> = {
   general: 'You are a focused sub-agent. Complete the assigned task thoroughly and return results.',
@@ -20,102 +14,93 @@ const TYPE_SYSTEM_PROMPTS: Record<SubAgentType, string> = {
 
 /**
  * Sub-agent engine — creates an isolated conversation context and processes
- * a single prompt independently. Returns the consolidated result.
- *
- * Phase 7: Pipeline-ready. Without a real AI provider, returns a structured
- * analysis of the prompt. Full AI integration in M3.
+ * a single prompt independently via the active AI provider. Returns the
+ * consolidated result text.
  */
 export class SubAgent {
-  constructor(private registry: ProviderRegistry) {}
+  constructor(
+    private registry: ProviderRegistry,
+    private toolRegistry: Map<string, ToolDefinition>,
+  ) {}
 
   async execute(
     prompt: string,
     description: string,
     options: SubAgentOptions = {},
   ): Promise<string> {
+    const provider = this.registry.getActive()
+    if (!provider) {
+      throw new Error('No active provider available for sub-agent execution')
+    }
+
+    const model = this.registry.getActiveModel()
     const type = options.type || 'general'
-    const systemPrompt = options.systemPrompt || TYPE_SYSTEM_PROMPTS[type]
+    const agentDef = options.agentDef
+
+    // Resolve system prompt: agentDef > options.systemPrompt > builtin type
+    const systemPrompt = agentDef?.systemPrompt || options.systemPrompt || TYPE_SYSTEM_PROMPTS[type]
+
+    // Create isolated context with tool scoping
+    const resolvedDef: AgentDefinition = agentDef || {
+      name: type,
+      description: '',
+      systemPrompt,
+      model: options.modelOverride || 'inherit',
+      permissionMode: 'inherit',
+      background: false,
+      source: 'builtin',
+    }
+    const { context, allowedTools } = createAgentContext(
+      resolvedDef,
+      this.toolRegistry,
+      options.maxContextMessages,
+    )
 
-    // Create isolated context for this sub-agent
-    const context = new ContextManager({
-      maxTokens: 100_000,
-      compactionThreshold: 0.9,
-    })
     context.setSystemPrompt(systemPrompt)
     context.addMessage({ role: 'user', content: prompt })
 
-    // Phase 7 pipeline: attempt real AI, fall back to structured simulation
-    try {
-      const provider = this.registry.getActive()
-      if (provider) {
-        const messages = context.getMessages()
-        const chunks: string[] = []
+    const messages = context.getMessages()
+    const toolDefs =
+      allowedTools.length > 0
+        ? allowedTools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: t.parameters,
+            input_schema: t.parameters,
+          }))
+        : undefined
 
-        for await (const chunk of provider.chat({
-          model: this.registry.getActiveModel(),
-          messages,
-          systemPrompt,
-          maxTokens: 4096,
-        })) {
-          if (chunk.type === 'text' && chunk.content) {
-            chunks.push(chunk.content)
-          }
-          if (chunk.type === 'error') {
-            // Fall through to simulation on API error
-            throw new Error(chunk.error)
-          }
-        }
+    const modelToUse = options.modelOverride || agentDef?.model || model
+    // 'inherit' means use parent model
+    const resolvedModel = modelToUse === 'inherit' ? model : modelToUse
 
-        if (chunks.length > 0) {
-          return chunks.join('')
+    const chunks: string[] = []
+
+    try {
+      for await (const chunk of provider.chat({
+        model: resolvedModel,
+        messages,
+        systemPrompt,
+        tools: toolDefs,
+        maxTokens: 4096,
+      })) {
+        if (chunk.type === 'text' && chunk.content) {
+          chunks.push(chunk.content)
+        }
+        if (chunk.type === 'error') {
+          throw new Error(`Sub-agent execution failed: ${chunk.error}`)
+        }
+        if (chunk.type === 'stop') {
+          break
         }
       }
-    } catch {
-      // API unavailable — use simulation mode
-    }
-
-    // Simulation mode: return structured task analysis
-    return this.simulate(prompt, description, type)
-  }
-
-  private simulate(prompt: string, description: string, type: SubAgentType): string {
-    const lines: string[] = [
-      `── Sub-Agent Result (${type}) ──`,
-      '',
-      `Task: ${description}`,
-      `Prompt: ${prompt.slice(0, 200)}${prompt.length > 200 ? '...' : ''}`,
-      '',
-    ]
-
-    switch (type) {
-      case 'explore':
-        lines.push(
-          'Analysis: This exploration task would search the codebase for relevant',
-          'files, patterns, and structures. The sub-agent pipeline is ready — connect',
-          'a provider API key for real AI-powered exploration.',
-        )
-        break
-      case 'plan':
-        lines.push(
-          'Plan: A step-by-step implementation plan would be generated based on',
-          'the requirements. Use /plan mode for interactive planning.',
-        )
-        break
-      case 'code-review':
-        lines.push(
-          'Review: The code review sub-agent would analyze the specified files for',
-          'bugs, security issues, and code quality concerns. Use /review for',
-          'interactive code review.',
-        )
-        break
-      default:
-        lines.push(
-          'The sub-agent pipeline is operational. Connect an API key to enable',
-          'AI-powered sub-agent execution. The infrastructure for context isolation,',
-          'prompt routing, and result aggregation is in place.',
-        )
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith('Sub-agent')) {
+        throw err
+      }
+      throw new Error(`Sub-agent execution failed: ${String(err)}`)
     }
 
-    return lines.join('\n')
+    return chunks.join('')
   }
 }