@miphamai/cli 0.9.0 → 0.11.0

package/package.json

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

package/src/agent/agent-context.ts

@@ -1,4 +1,7 @@
 // apps/cli/src/agent/agent-context.ts
+import { readdirSync, readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
 import { ContextManager } from '../core/context'
 import type { ToolDefinition } from '../shared/index.ts'
 import type { AgentDefinition } from './types'
@@ -8,6 +11,50 @@ export interface AgentContextResult {
   allowedTools: ToolDefinition[]
 }
 
+/**
+ * Load agent memory files from the appropriate scope directory.
+ * Returns combined content for injection into the system prompt.
+ */
+function loadAgentMemory(agentName: string, scope: 'user' | 'project' | 'local'): string {
+  let memoryDir: string
+  const home = homedir()
+
+  switch (scope) {
+    case 'user':
+      memoryDir = join(home, '.mipham', 'agent-memory', agentName)
+      break
+    case 'project':
+      memoryDir = join(process.cwd(), '.mipham', 'agent-memory', agentName)
+      break
+    case 'local':
+      memoryDir = join(process.cwd(), '.mipham', 'agent-memory-local', agentName)
+      break
+  }
+
+  if (!existsSync(memoryDir)) return ''
+
+  try {
+    const files = readdirSync(memoryDir).filter((f) => f.endsWith('.md'))
+    if (files.length === 0) return ''
+
+    const contents: string[] = []
+    for (const file of files.slice(0, 10)) {
+      // max 10 files
+      try {
+        const content = readFileSync(join(memoryDir, file), 'utf-8').trim()
+        if (content) contents.push(content)
+      } catch {
+        // skip unreadable
+      }
+    }
+
+    if (contents.length === 0) return ''
+    return [`[Agent Memory — ${scope} scope]`, ...contents].join('\n\n')
+  } catch {
+    return ''
+  }
+}
+
 /**
  * Create an isolated context and tool set for a sub-agent.
  *
@@ -15,6 +62,9 @@ export interface AgentContextResult {
  * 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.
+ *
+ * Agent memory: if agentDef.memory is set, loads memory files from the
+ * appropriate scope and injects them into the system prompt.
  */
 export function createAgentContext(
   agentDef: AgentDefinition,
@@ -27,7 +77,16 @@ export function createAgentContext(
     compactionThreshold: 0.85,
   })
 
-  context.setSystemPrompt(agentDef.systemPrompt)
+  // Build system prompt with optional agent memory
+  let systemPrompt = agentDef.systemPrompt
+  if (agentDef.memory) {
+    const memory = loadAgentMemory(agentDef.name, agentDef.memory)
+    if (memory) {
+      systemPrompt = `${systemPrompt}\n\n---\n\n${memory}`
+    }
+  }
+
+  context.setSystemPrompt(systemPrompt)
 
   // Scope tools
   let allowedTools = Array.from(toolRegistry.values())

package/src/agent/agent-registry.ts

@@ -74,6 +74,7 @@ export class AgentRegistry {
                 .map((s) => s.trim())
             : undefined,
           background: (data.background as boolean) || false,
+          memory: data.memory as 'user' | 'project' | 'local' | undefined,
           source,
           filePath: fullPath,
         }

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

@@ -12,6 +12,7 @@ export interface AgentFrontmatter {
   maxTurns?: number
   skills?: string
   background?: boolean
+  memory?: 'user' | 'project' | 'local' // agent memory scope
 }
 
 export interface AgentDefinition {
@@ -27,6 +28,7 @@ export interface AgentDefinition {
   background: boolean
   source: 'builtin' | 'project' | 'user'
   filePath?: string
+  memory?: 'user' | 'project' | 'local' // agent memory scope
 }
 
 export interface SubAgentOptions {
@@ -38,4 +40,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>