@miphamai/cli 0.3.0 → 0.5.0

package/src/shared/types.ts

@@ -50,7 +50,7 @@ export interface Message {
 
 // ── Tool Types ──
 export type ToolPermission = 'auto' | 'ask' | 'bypass'
-export type ToolCategory = 'file' | 'exec' | 'agent' | 'network' | 'system'
+export type ToolCategory = 'file' | 'exec' | 'agent' | 'network' | 'system' | 'artifact'
 
 export interface ToolContext {
   cwd: string
@@ -59,6 +59,28 @@ export interface ToolContext {
   model: string
   skillsLoader?: import('../skills/loader').SkillsLoader
   registry?: import('../providers/registry').ProviderRegistry
+  toolRegistry?: Map<string, ToolDefinition>
+  artifactServer?: import('../artifacts/server').ArtifactServer
+  agentRegistry?: import('../agent/agent-registry').AgentRegistry
+}
+
+// ── Artifact Types ──
+export interface ArtifactEntry {
+  name: string
+  path: string
+  url: string
+  size: number
+  type: 'html' | 'svg'
+  createdAt: string
+  sessionId: string
+  versions?: string[] // version tags e.g. ['v1', 'v2']
+  versionCount?: number
+}
+
+export interface ArtifactManifest {
+  version: 1
+  artifacts: ArtifactEntry[]
+  port?: number
 }
 
 export interface ToolResult {
@@ -111,6 +133,16 @@ export interface SkillDefinition {
   tools?: ToolDefinition[]
   hooks?: HookDefinition[]
   prompts?: Record<string, string>
+  /** Frontmatter: 'fork' means execute in isolated subagent, undefined means inline */
+  context?: string
+  /** Model override for fork execution */
+  model?: string
+  /** Tool whitelist for fork mode */
+  allowedTools?: string[]
+  /** When true, the skill is NOT shown in system-reminder for AI auto-triggering */
+  disableModelInvocation?: boolean
+  /** When true, users can invoke this skill directly via /<name> */
+  userInvocable?: boolean
 }
 
 // ── Hook Types ──
@@ -120,6 +152,25 @@ export type HookEvent =
   | 'SessionStart'
   | 'SessionEnd'
   | 'Notification'
+  | 'Stop'
+  | 'UserPromptSubmit'
+  | 'PreCompact'
+  | 'PostCompact'
+  | 'ConfigChange'
+
+export type HookType = 'command' | 'http' | 'code' | 'mcp_tool'
+
+export interface HookConfig {
+  type: HookType
+  command?: string
+  args?: string[]
+  url?: string
+  method?: 'GET' | 'POST'
+  headers?: Record<string, string>
+  mcpServer?: string
+  mcpTool?: string
+  continueOnBlock?: boolean
+}
 
 export interface HookDefinition {
   event: HookEvent
@@ -133,12 +184,19 @@ export interface HookContext {
   toolInput?: Record<string, unknown>
   toolResult?: ToolResult
   sessionId: string
+  userPrompt?: string
+  configKey?: string
+  configValue?: unknown
 }
 
 export interface HookResult {
   allowed: boolean
   reason?: string
   modifiedInput?: Record<string, unknown>
+  decision?: 'allow' | 'block'
+  permissionDecision?: 'allow' | 'deny' | 'ask' | 'defer'
+  additionalContext?: string
+  updatedOutput?: string
 }
 
 // ── Instruction Types ──
@@ -152,7 +210,29 @@ export interface InstructionFile {
 }
 
 // ── Permission Types ──
-export type PermissionLevel = 'auto' | 'ask' | 'bypass'
+/** Six explicit permission modes matching Claude Code's permission architecture */
+export type PermissionMode =
+  | 'default'
+  | 'acceptEdits'
+  | 'plan'
+  | 'auto'
+  | 'dontAsk'
+  | 'bypassPermissions'
+
+/** Backward-compatible alias: PermissionMode plus legacy 'ask' and 'bypass' */
+export type PermissionLevel = PermissionMode | 'ask' | 'bypass'
+
+export interface PermissionConfig {
+  mode: PermissionMode
+  allow: string[]
+  deny: string[]
+}
+
+export interface PermissionRuleEntry {
+  pattern: string // e.g., "Bash(git:*)"
+  level: 'allow' | 'deny' | 'ask'
+  compiled: RegExp
+}
 
 export interface PermissionRule {
   toolName: string

package/src/skills/fork-executor.ts

@@ -0,0 +1,40 @@
+import { SubAgent } from '../agent/sub-agent'
+import type { ProviderRegistry } from '../providers/registry'
+import type { ToolDefinition, SkillDefinition } from '../shared/index.ts'
+import type { AgentDefinition } from '../agent/types'
+
+/**
+ * Execute a skill in an isolated subagent context (context: fork).
+ *
+ * The skill's markdown body becomes the subagent's system prompt.
+ * The skill's allowed-tools become the subagent's tool whitelist.
+ * Results are returned to the AI as internal context (not shown directly to user).
+ */
+export async function executeForkedSkill(
+  skill: SkillDefinition,
+  args: string,
+  registry: ProviderRegistry,
+  toolRegistry: Map<string, ToolDefinition>,
+): Promise<string> {
+  const agentDef: AgentDefinition = {
+    name: `skill:${skill.name}`,
+    description: skill.description,
+    systemPrompt: buildSkillSystemPrompt(skill),
+    tools: skill.allowedTools?.join(', '),
+    model: skill.model || 'inherit',
+    permissionMode: 'inherit',
+    background: false,
+    source: 'builtin',
+  }
+
+  const sub = new SubAgent(registry, toolRegistry)
+  const prompt = args
+    ? `Execute the "${skill.name}" skill with arguments: ${args}`
+    : `Execute the "${skill.name}" skill.`
+
+  return sub.execute(prompt, `skill:${skill.name}`, { agentDef })
+}
+
+function buildSkillSystemPrompt(skill: SkillDefinition): string {
+  return `You are executing the "${skill.name}" skill (v${skill.version}).\n\n${skill.description}\n\nFollow the skill instructions precisely and return results.`
+}

package/src/skills/loader.ts

@@ -1,5 +1,6 @@
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
-import { join, extname } from 'node:path'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
 import { parse as parseYaml } from 'yaml'
 import type { SkillDefinition } from '../shared/index.ts'
 
@@ -84,7 +85,7 @@ export class SkillsLoader {
   private tryLoad(path: string, type: 'standard' | 'mipham'): void {
     try {
       const raw = readFileSync(path, 'utf-8')
-      const { data, content } = parseFrontmatter(raw)
+      const { data } = parseFrontmatter(raw)
 
       const skill: SkillDefinition = {
         name: (data.name as string) || this.nameFromPath(path),
@@ -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/artifact/artifact.ts

@@ -0,0 +1,144 @@
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ToolDefinition } from '../../shared/index.ts'
+import { ARTIFACTS_DIR, ARTIFACT_MAX_SIZE } from '../../shared/constants'
+import { addToManifest, readManifest, archiveVersion } from '../../artifacts/manifest'
+
+const NAME_PATTERN = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
+
+export const artifactTool: ToolDefinition = {
+  name: 'Artifact',
+  description:
+    'Create an interactive HTML or SVG artifact that opens in the browser. Use for dashboards, visualizations, reports, and interactive demos. Content must be self-contained — no external CDN references.',
+  category: 'artifact',
+  permission: 'ask',
+  parameters: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'Short kebab-case name (e.g. "user-dashboard", "pipeline-diagram")',
+      },
+      type: {
+        type: 'string',
+        enum: ['html', 'svg'],
+        description: 'Artifact type',
+      },
+      content: {
+        type: 'string',
+        description: 'Full HTML or SVG content (self-contained, inline CSS/JS only)',
+      },
+    },
+    required: ['name', 'type', 'content'],
+  },
+  async execute(params, ctx) {
+    const name = params.name as string
+    const type = params.type as string
+    const content = params.content as string
+
+    // Validate name
+    if (!NAME_PATTERN.test(name) || name.length < 3) {
+      return {
+        success: false,
+        content: '',
+        error:
+          `Invalid artifact name "${name}". Use kebab-case (letters, numbers, hyphens), ` +
+          `at least 3 characters, e.g. "my-dashboard".`,
+      }
+    }
+
+    // Validate size
+    const size = Buffer.byteLength(content, 'utf-8')
+    if (size > ARTIFACT_MAX_SIZE) {
+      return {
+        success: false,
+        content: '',
+        error: `Content size ${(size / 1_048_576).toFixed(1)}MB exceeds ${ARTIFACT_MAX_SIZE / 1_048_576}MB limit.`,
+      }
+    }
+
+    // Determine output paths
+    const baseDir = join(ctx.cwd, ARTIFACTS_DIR)
+    const sessionDir = join(baseDir, ctx.sessionId)
+    mkdirSync(sessionDir, { recursive: true })
+
+    const ext = type === 'svg' ? '.svg' : '.html'
+    const filename = `${name}${ext}`
+    const filepath = join(sessionDir, filename)
+
+    // Start server if not running
+    let port: number | undefined
+    if (ctx.artifactServer && !ctx.artifactServer.isRunning()) {
+      port = await ctx.artifactServer.start()
+    } else if (ctx.artifactServer) {
+      port = ctx.artifactServer.getPort()
+    }
+
+    // Archive previous version if this artifact already exists
+    let archivedVersion: string | undefined
+    const isUpdate = existsSync(filepath)
+    if (isUpdate) {
+      const manifest = readManifest(baseDir)
+      const existing = manifest.artifacts.find(
+        (a) => a.name === name && a.sessionId === ctx.sessionId,
+      )
+      if (existing) {
+        archivedVersion = archiveVersion(baseDir, existing)
+      }
+    }
+
+    // Write artifact
+    writeFileSync(filepath, content, 'utf-8')
+
+    // Build URL and manifest entry
+    const url = port
+      ? `http://localhost:${port}/${ctx.sessionId}/${filename}`
+      : `file://${filepath}`
+
+    // Preserve existing version count
+    const manifestPre = readManifest(baseDir)
+    const prev = manifestPre.artifacts.find((a) => a.name === name && a.sessionId === ctx.sessionId)
+    const versionCount = prev?.versionCount || (isUpdate ? 1 : undefined)
+
+    addToManifest(
+      baseDir,
+      {
+        name,
+        path: filepath,
+        url,
+        size,
+        type: type as 'html' | 'svg',
+        createdAt: new Date().toISOString(),
+        sessionId: ctx.sessionId,
+        versions: prev?.versions,
+        versionCount,
+      },
+      port,
+    )
+
+    // Notify SSE clients to refresh Gallery
+    if (ctx.artifactServer) {
+      ctx.artifactServer.notifyReload()
+    }
+
+    const galleryUrl = port ? `http://localhost:${port}` : undefined
+    const versionLine = archivedVersion ? `   Prev archived as: ${archivedVersion}` : ''
+    const galleryLine = galleryUrl ? `Gallery: ${galleryUrl}` : ''
+
+    return {
+      success: true,
+      content: [
+        `✓ Artifact "${name}" saved${isUpdate ? ' (updated)' : ''}.`,
+        `   URL:  ${url}`,
+        `   Size: ${size.toLocaleString()} bytes`,
+        versionLine,
+        galleryLine,
+        '',
+        `Open in browser: /artifact open ${name}`,
+        `List all:         /artifact list`,
+      ]
+        .filter(Boolean)
+        .join('\n'),
+    }
+  },
+}

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>
+    }>
+  }
+}