@miphamai/cli 0.9.0 → 0.10.0

package/package.json

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

package/src/agent/background-registry.ts

@@ -0,0 +1,192 @@
+/**
+ * BackgroundAgentRegistry — lifecycle manager for background agent tasks.
+ *
+ * Each background task runs as a detached Promise with an AbortController
+ * for cancellation. The registry tracks status and stores results, which
+ * can be queried via the Task tool (output/stop actions) or the Agent View.
+ */
+
+export type BackgroundTaskStatus = 'running' | 'completed' | 'failed'
+
+export interface BackgroundTask {
+  id: string
+  description: string
+  agentType: string
+  status: BackgroundTaskStatus
+  startedAt: Date
+  completedAt?: Date
+  result?: string
+  error?: string
+  abortController: AbortController
+}
+
+type CompleteCallback = (task: BackgroundTask) => void
+
+export class BackgroundAgentRegistry {
+  private tasks: Map<string, BackgroundTask> = new Map()
+  private completeCallbacks: Map<string, CompleteCallback[]> = new Map()
+  private idCounter = 0
+
+  /**
+   * Spawn a background task. Returns the task ID immediately.
+   * The executor function runs asynchronously; its result is stored in the task.
+   *
+   * @param description - Human-readable description
+   * @param agentType - Sub-agent type (general, explore, plan, code-review)
+   * @param executor - Async function that performs the work
+   */
+  spawn(
+    description: string,
+    agentType: string,
+    executor: (signal: AbortSignal) => Promise<string>,
+  ): string {
+    const id = `bg-${++this.idCounter}-${Date.now().toString(36)}`
+
+    const task: BackgroundTask = {
+      id,
+      description,
+      agentType,
+      status: 'running',
+      startedAt: new Date(),
+      abortController: new AbortController(),
+    }
+
+    this.tasks.set(id, task)
+
+    // Execute in background — do NOT await
+    executor(task.abortController.signal)
+      .then((result) => {
+        task.status = 'completed'
+        task.completedAt = new Date()
+        task.result = result
+        this.fireComplete(id)
+      })
+      .catch((err) => {
+        // Don't mark as failed if it was intentionally aborted
+        if (err instanceof Error && err.name === 'AbortError') {
+          task.status = 'failed'
+          task.error = 'Task was cancelled.'
+        } else {
+          task.status = 'failed'
+          task.error = String(err)
+        }
+        task.completedAt = new Date()
+        this.fireComplete(id)
+      })
+
+    return id
+  }
+
+  /**
+   * Get a task by ID. Returns undefined if not found.
+   */
+  get(id: string): BackgroundTask | undefined {
+    return this.tasks.get(id)
+  }
+
+  /**
+   * List all background tasks, newest first.
+   */
+  list(): BackgroundTask[] {
+    return Array.from(this.tasks.values()).sort(
+      (a, b) => b.startedAt.getTime() - a.startedAt.getTime(),
+    )
+  }
+
+  /**
+   * List only running tasks.
+   */
+  listRunning(): BackgroundTask[] {
+    return this.list().filter((t) => t.status === 'running')
+  }
+
+  /**
+   * Stop a running task by aborting its controller.
+   * Returns true if the task was running and was stopped.
+   */
+  stop(id: string): boolean {
+    const task = this.tasks.get(id)
+    if (!task) return false
+    if (task.status !== 'running') return false
+
+    task.abortController.abort()
+    return true
+  }
+
+  /**
+   * Register a callback that fires when a task completes (success or failure).
+   * The callback is called once and then automatically removed.
+   */
+  onComplete(id: string, callback: CompleteCallback): void {
+    // If already complete, call immediately
+    const task = this.tasks.get(id)
+    if (task && task.status !== 'running') {
+      callback(task)
+      return
+    }
+
+    const cbs = this.completeCallbacks.get(id) || []
+    cbs.push(callback)
+    this.completeCallbacks.set(id, cbs)
+  }
+
+  /**
+   * Remove completed/failed tasks older than `maxAgeMs`.
+   * Returns the number of tasks pruned.
+   */
+  prune(maxAgeMs: number = 30 * 60 * 1000): number {
+    const now = Date.now()
+    let removed = 0
+    for (const [id, task] of this.tasks) {
+      if (task.status === 'running') continue
+      if (task.completedAt && now - task.completedAt.getTime() > maxAgeMs) {
+        this.tasks.delete(id)
+        this.completeCallbacks.delete(id)
+        removed++
+      }
+    }
+    return removed
+  }
+
+  /**
+   * Count tasks by status.
+   */
+  countByStatus(): Record<BackgroundTaskStatus, number> {
+    const counts: Record<BackgroundTaskStatus, number> = {
+      running: 0,
+      completed: 0,
+      failed: 0,
+    }
+    for (const [, task] of this.tasks) {
+      counts[task.status]++
+    }
+    return counts
+  }
+
+  private fireComplete(id: string): void {
+    const task = this.tasks.get(id)
+    if (!task) return
+
+    const cbs = this.completeCallbacks.get(id)
+    if (cbs) {
+      for (const cb of cbs) {
+        try {
+          cb(task)
+        } catch {
+          // Callback errors should not propagate
+        }
+      }
+      this.completeCallbacks.delete(id)
+    }
+  }
+}
+
+/** Singleton instance for the CLI process. */
+let _instance: BackgroundAgentRegistry | null = null
+
+export function getBackgroundAgentRegistry(): BackgroundAgentRegistry {
+  if (!_instance) {
+    _instance = new BackgroundAgentRegistry()
+  }
+  return _instance
+}

package/src/agent/message-bus.ts

@@ -0,0 +1,113 @@
+/**
+ * AgentMessageBus — inter-agent communication channel.
+ *
+ * Agents (main session + background sub-agents) can post and poll messages.
+ * Messages are stored in-memory and keyed by recipient. Each message has a
+ * read flag so recipients can distinguish new from seen messages.
+ *
+ * Usage:
+ *   const bus = getMessageBus()
+ *   const msgId = bus.post('main', 'bg-1', 'hello', 'How is it going?')
+ *   const unread = bus.poll('bg-1')  // messages addressed TO bg-1
+ */
+
+export interface AgentMessage {
+  id: string
+  from: string
+  to: string
+  summary: string
+  message: string
+  timestamp: Date
+  read: boolean
+}
+
+export class AgentMessageBus {
+  private messages: AgentMessage[] = []
+  private idCounter = 0
+
+  /**
+   * Post a message from one agent to another.
+   * Returns the message ID.
+   */
+  post(from: string, to: string, summary: string, message: string): string {
+    const id = `msg-${++this.idCounter}`
+    this.messages.push({
+      id,
+      from,
+      to,
+      summary: summary.slice(0, 200),
+      message,
+      timestamp: new Date(),
+      read: false,
+    })
+    return id
+  }
+
+  /**
+   * Get all unread messages addressed to the given agent.
+   * Does NOT mark them as read — use markRead() for that.
+   */
+  poll(agentId: string): AgentMessage[] {
+    return this.messages.filter((m) => m.to === agentId && !m.read)
+  }
+
+  /**
+   * Get all messages addressed to the given agent (read + unread).
+   */
+  list(agentId: string): AgentMessage[] {
+    return this.messages.filter((m) => m.to === agentId)
+  }
+
+  /**
+   * Mark a specific message as read by ID.
+   * Returns true if the message was found and marked.
+   */
+  markRead(messageId: string): boolean {
+    const msg = this.messages.find((m) => m.id === messageId)
+    if (!msg) return false
+    msg.read = true
+    return true
+  }
+
+  /**
+   * Mark all messages for a recipient as read.
+   * Returns the count of messages marked.
+   */
+  markAllRead(agentId: string): number {
+    let count = 0
+    for (const msg of this.messages) {
+      if (msg.to === agentId && !msg.read) {
+        msg.read = true
+        count++
+      }
+    }
+    return count
+  }
+
+  /**
+   * Get unread message count for an agent.
+   */
+  unreadCount(agentId: string): number {
+    return this.messages.filter((m) => m.to === agentId && !m.read).length
+  }
+
+  /**
+   * Prune messages older than maxAgeMs. Returns the number pruned.
+   */
+  prune(maxAgeMs: number = 60 * 60 * 1000): number {
+    const now = Date.now()
+    const before = this.messages.length
+    this.messages = this.messages.filter((m) => now - m.timestamp.getTime() < maxAgeMs)
+    return before - this.messages.length
+  }
+}
+
+/** Singleton instance. */
+let _instance: AgentMessageBus | null = null
+
+export function getMessageBus(): AgentMessageBus {
+  if (!_instance) {
+    _instance = new AgentMessageBus()
+  }
+  return _instance
+}

package/src/agent/sub-agent.ts

@@ -2,6 +2,8 @@ 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'
+import { getBackgroundAgentRegistry } from './background-registry'
+import type { HookEngine } from '../core/hooks'
 
 const TYPE_SYSTEM_PROMPTS: Record<SubAgentType, string> = {
   general: 'You are a focused sub-agent. Complete the assigned task thoroughly and return results.',
@@ -16,17 +18,91 @@ const TYPE_SYSTEM_PROMPTS: Record<SubAgentType, string> = {
  * Sub-agent engine — creates an isolated conversation context and processes
  * a single prompt independently via the active AI provider. Returns the
  * consolidated result text.
+ *
+ * Supports background execution via `runInBackground` option — when true,
+ * execution is spawned as a detached promise and the method returns immediately
+ * with a `[background-task:<id>]` marker.
  */
 export class SubAgent {
   constructor(
     private registry: ProviderRegistry,
     private toolRegistry: Map<string, ToolDefinition>,
+    private hookEngine?: HookEngine,
   ) {}
 
+  /**
+   * Execute a sub-agent task.
+   *
+   * When `options.runInBackground` is true:
+   *   - The task runs asynchronously in BackgroundAgentRegistry
+   *   - Returns immediately with `[background-task:<id>]`
+   *   - Results are retrievable via Task output or Agent View
+   */
   async execute(
     prompt: string,
     description: string,
     options: SubAgentOptions = {},
+  ): Promise<string> {
+    const agentType = options.type || 'general'
+
+    // ── Fire SubagentStart hook ──
+    if (this.hookEngine) {
+      await this.hookEngine.executeSubagentStart(agentType, description, 'sub-agent')
+    }
+
+    // ── Background execution path ──
+    if (options.runInBackground) {
+      const bgRegistry = getBackgroundAgentRegistry()
+
+      const taskId = bgRegistry.spawn(description, agentType, async (signal) => {
+        // Run the synchronous execution inside the background executor
+        return this.runExecution(prompt, options, signal)
+      })
+
+      // Register completion callback for hook firing
+      bgRegistry.onComplete(taskId, (task) => {
+        if (this.hookEngine) {
+          this.hookEngine.executeSubagentStop(
+            agentType,
+            description,
+            taskId,
+            task.status === 'completed',
+            task.result || task.error,
+          )
+        }
+      })
+
+      return `[background-task:${taskId}]`
+    }
+
+    // ── Synchronous execution path ──
+    try {
+      const result = await this.runExecution(prompt, options)
+      if (this.hookEngine) {
+        await this.hookEngine.executeSubagentStop(agentType, description, 'sub-agent', true, result)
+      }
+      return result
+    } catch (err) {
+      if (this.hookEngine) {
+        await this.hookEngine.executeSubagentStop(
+          agentType,
+          description,
+          'sub-agent',
+          false,
+          String(err),
+        )
+      }
+      throw err
+    }
+  }
+
+  /**
+   * Internal execution method — shared by sync and background paths.
+   */
+  private async runExecution(
+    prompt: string,
+    options: SubAgentOptions,
+    signal?: AbortSignal,
   ): Promise<string> {
     const provider = this.registry.getActive()
     if (!provider) {
@@ -34,15 +110,16 @@ export class SubAgent {
     }
 
     const model = this.registry.getActiveModel()
-    const type = options.type || 'general'
+    const agentType = options.type || 'general'
     const agentDef = options.agentDef
 
     // Resolve system prompt: agentDef > options.systemPrompt > builtin type
-    const systemPrompt = agentDef?.systemPrompt || options.systemPrompt || TYPE_SYSTEM_PROMPTS[type]
+    const systemPrompt =
+      agentDef?.systemPrompt || options.systemPrompt || TYPE_SYSTEM_PROMPTS[agentType]
 
     // Create isolated context with tool scoping
     const resolvedDef: AgentDefinition = agentDef || {
-      name: type,
+      name: agentType,
       description: '',
       systemPrompt,
       model: options.modelOverride || 'inherit',
@@ -82,6 +159,11 @@ export class SubAgent {
 
     try {
       for (let turn = 0; turn < MAX_TOOL_TURNS; turn++) {
+        // Check abort signal
+        if (signal?.aborted) {
+          throw new DOMException('Aborted', 'AbortError')
+        }
+
         const toolUses: Array<{ id: string; name: string; input: Record<string, unknown> }> = []
         let turnText = ''
 
@@ -92,8 +174,17 @@ export class SubAgent {
           tools: toolDefs,
           maxTokens: 4096,
         })) {
+          // Check abort signal mid-stream
+          if (signal?.aborted) {
+            throw new DOMException('Aborted', 'AbortError')
+          }
+
           if (chunk.type === 'text' && chunk.content) {
             turnText += chunk.content
+            // Stream progress to callback if provided
+            if (options.onProgress) {
+              options.onProgress(chunk.content)
+            }
           }
           if (chunk.type === 'tool_use' && chunk.toolUse) {
             toolUses.push({
@@ -125,6 +216,10 @@ export class SubAgent {
         ]
 
         for (const tu of toolUses) {
+          if (signal?.aborted) {
+            throw new DOMException('Aborted', 'AbortError')
+          }
+
           const tool = this.toolRegistry.get(tu.name)
           if (!tool) {
             currentMessages.push({
@@ -168,6 +263,9 @@ export class SubAgent {
         currentSystemPrompt = ''
       }
     } catch (err) {
+      if (err instanceof DOMException && err.name === 'AbortError') {
+        throw err
+      }
       if (err instanceof Error && err.message.startsWith('Sub-agent')) {
         throw err
       }

package/src/agent/types.ts

@@ -38,4 +38,8 @@ export interface SubAgentOptions {
   modelOverride?: string
   /** Maximum tool-calling turns (default: 5) to prevent infinite loops. */
   maxTurns?: number
+  /** When true, execute in background and return immediately with a task ID. */
+  runInBackground?: boolean
+  /** Optional callback for streaming progress chunks during background execution. */
+  onProgress?: (chunk: string) => void
 }

package/src/agent-view/agent-view-manager.ts

@@ -200,6 +200,16 @@ export class AgentViewManager {
     return counts
   }
 
+  /**
+   * Rename a session's title. Returns true if found and renamed.
+   */
+  rename(id: string, newTitle: string): boolean {
+    const session = this.sessions.get(id)
+    if (!session) return false
+    session.title = newTitle
+    return true
+  }
+
   /**
    * Remove all completed and failed sessions (cleanup).
    */

package/src/agent-view/dashboard.tsx

@@ -30,6 +30,7 @@ const STATUS_HEADERS: Record<string, { label: string; color: string }> = {
 export function AgentViewDashboard({ manager, onAttach, onExit }: DashboardProps) {
   const [selectedIndex, setSelectedIndex] = useState(0)
   const [peekingSessionId, setPeekingSessionId] = useState<string | null>(null)
+  const [groupBy, setGroupBy] = useState<'status' | 'directory'>('status')
 
   // Build a flat list of sessions in group order, with group headers
   const flatList = useMemo(() => {
@@ -95,6 +96,22 @@ export function AgentViewDashboard({ manager, onAttach, onExit }: DashboardProps
       return
     }
 
+    // Ctrl+S — toggle group by (status ↔ directory)
+    if (input === '\x13') {
+      setGroupBy((prev) => (prev === 'status' ? 'directory' : 'status'))
+      return
+    }
+
+    // Ctrl+R — rename selected session
+    if (input === '\x12') {
+      if (sessionsOnly.length === 0) return
+      const current = sessionsOnly[selectedIndex]
+      if (!current) return
+      const newTitle = `session-${Date.now().toString(36)}`
+      manager.rename(current.session.id, newTitle)
+      return
+    }
+
     if (input === 'j') {
       setSelectedIndex((prev) => Math.min(prev + 1, sessionsOnly.length - 1))
       setPeekingSessionId(null)
@@ -163,7 +180,9 @@ export function AgentViewDashboard({ manager, onAttach, onExit }: DashboardProps
           </Text>
         </Box>
         <Box>
-          <Text dimColor>j/k navigate · Space peek · Enter attach · Esc back</Text>
+          <Text dimColor>
+            j/k navigate · Space peek · Enter attach · Ctrl+S group · Ctrl+R rename · Esc back
+          </Text>
         </Box>
       </Box>
 

package/src/core/engine.ts

@@ -9,6 +9,7 @@ import { analyzeForMemory } from './memory/memory-writer'
 import { getMemoryManager } from './memory/memory-loader'
 import type { AgentViewManager } from '../agent-view/agent-view-manager'
 import type { SkillsLoader } from '../skills/loader'
+import { getBackgroundAgentRegistry } from '../agent/background-registry'
 
 export class QueryEngine {
   private hookEngine?: HookEngine
@@ -70,6 +71,46 @@ export class QueryEngine {
     this.skillsLoader = loader
   }
 
+  /** Pending task notifications from background agents (cleared after draining). */
+  private pendingTaskNotifications: Array<StreamChunk> = []
+
+  /**
+   * Drain pending background task notifications.
+   * Call this after tool execution to surface completed/failed background agent results.
+   * Returns an array of StreamChunks that can be yielded in a generator.
+   */
+  drainTaskNotifications(): StreamChunk[] {
+    const bgRegistry = getBackgroundAgentRegistry()
+    const tasks = bgRegistry.list()
+    const chunks: StreamChunk[] = []
+
+    for (const task of tasks) {
+      if (task.status === 'running') continue
+
+      // Check if we've already notified for this task
+      const alreadyNotified = this.pendingTaskNotifications.some(
+        (n) => n.taskNotification?.taskId === task.id,
+      )
+      if (alreadyNotified) continue
+
+      const chunk: StreamChunk = {
+        type: 'task_notification',
+        taskNotification: {
+          taskId: task.id,
+          status: task.status as 'completed' | 'failed',
+          description: task.description,
+          content: task.result,
+          error: task.error,
+        },
+      }
+
+      this.pendingTaskNotifications.push(chunk)
+      chunks.push(chunk)
+    }
+
+    return chunks
+  }
+
   /** Set the session goal for goal-driven execution. */
   setGoal(
     goal: string,
@@ -310,6 +351,11 @@ export class QueryEngine {
       })
     }
 
+    // Drain task notifications after tool execution
+    for (const chunk of this.drainTaskNotifications()) {
+      yield chunk
+    }
+
     // If tools were executed, recursively continue the conversation
     if (toolUses.length > 0) {
       yield* this.continueWithTools(signal)
@@ -318,6 +364,11 @@ export class QueryEngine {
 
     // Fire Stop hooks when AI finishes with no tool calls
     yield* this.checkStopHook(signal)
+
+    // Final drain of task notifications
+    for (const chunk of this.drainTaskNotifications()) {
+      yield chunk
+    }
   }
 
   async *processWithGoal(input: string, signal?: AbortSignal): AsyncGenerator<StreamChunk> {
@@ -579,6 +630,7 @@ export class QueryEngine {
         toolRegistry: this.tools,
         artifactServer: this.artifactServer,
         agentRegistry: this.agentRegistry,
+        backgroundAgentRegistry: getBackgroundAgentRegistry(),
       })
 
       // Run PostToolUse hooks

package/src/core/hooks.ts

@@ -107,6 +107,54 @@ export class HookEngine {
     return this.runHooks('ConfigChange', undefined, ctx)
   }
 
+  /** SubagentStart: fires when a sub-agent begins execution. */
+  async executeSubagentStart(
+    agentType: string,
+    description: string,
+    sessionId: string,
+  ): Promise<HookResult> {
+    const ctx: HookContext = {
+      event: 'SubagentStart',
+      sessionId,
+      toolInput: { agentType, description },
+    }
+    return this.runHooks('SubagentStart', undefined, ctx)
+  }
+
+  /** SubagentStop: fires when a sub-agent completes (success or failure). */
+  async executeSubagentStop(
+    agentType: string,
+    description: string,
+    sessionId: string,
+    success: boolean,
+    result?: string,
+  ): Promise<HookResult> {
+    const ctx: HookContext = {
+      event: 'SubagentStop',
+      sessionId,
+      toolInput: { agentType, description, success },
+      toolResult: result ? { success, content: result.slice(0, 2000) } : undefined,
+    }
+    return this.runHooks('SubagentStop', undefined, ctx)
+  }
+
+  /** PostToolUseFailure: fires when a tool call fails. */
+  async executePostToolUseFailure(
+    toolName: string,
+    toolInput: Record<string, unknown>,
+    error: string,
+    sessionId: string,
+  ): Promise<HookResult> {
+    const ctx: HookContext = {
+      event: 'PostToolUseFailure',
+      toolName,
+      toolInput,
+      toolResult: { success: false, content: '', error },
+      sessionId,
+    }
+    return this.runHooks('PostToolUseFailure', toolName, ctx)
+  }
+
   // ── Core execution ──
 
   private async runHooks(