@miphamai/cli 0.4.0 → 0.5.1

package/src/agent/types.ts

@@ -0,0 +1,39 @@
+// apps/cli/src/agent/types.ts
+
+export type SubAgentType = 'general' | 'explore' | 'plan' | 'code-review'
+
+export interface AgentFrontmatter {
+  name: string
+  description: string
+  tools?: string // comma-separated allowlist
+  disallowedTools?: string
+  model?: string // 'sonnet' | 'opus' | 'haiku' | 'inherit' | full model ID
+  permissionMode?: 'default' | 'acceptEdits' | 'auto' | 'bypass' | 'plan'
+  maxTurns?: number
+  skills?: string
+  background?: boolean
+}
+
+export interface AgentDefinition {
+  name: string
+  description: string
+  systemPrompt: string // markdown body after frontmatter
+  tools?: string
+  disallowedTools?: string
+  model: string
+  permissionMode: string
+  maxTurns?: number
+  skills?: string[]
+  background: boolean
+  source: 'builtin' | 'project' | 'user'
+  filePath?: string
+}
+
+export interface SubAgentOptions {
+  type?: SubAgentType
+  agentDef?: AgentDefinition
+  systemPrompt?: string
+  maxContextMessages?: number
+  allowedTools?: string[]
+  modelOverride?: string
+}

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

@@ -0,0 +1,217 @@
+/**
+ * AgentViewManager — multi-session lifecycle manager for background agent sessions.
+ *
+ * Each session represents a background sub-agent task. The manager tracks
+ * status transitions, elapsed time, and provides grouping/peek/attach/kill
+ * operations used by the Agent View Dashboard TUI.
+ */
+
+export type SessionStatus = 'needs-input' | 'working' | 'completed' | 'failed'
+
+export interface SessionMessage {
+  role: 'user' | 'assistant' | 'system'
+  content: string
+}
+
+export interface AgentSession {
+  id: string
+  title: string
+  status: SessionStatus
+  provider: string
+  model: string
+  task: string
+  createdAt: Date
+  startedAt?: Date
+  completedAt?: Date
+  elapsedMs: number
+  messages: SessionMessage[]
+}
+
+export interface CreateSessionOptions {
+  provider?: string
+  model?: string
+}
+
+export interface SessionPeek {
+  session: AgentSession
+  recentMessages: SessionMessage[]
+}
+
+export type StatusGroups = Record<SessionStatus, AgentSession[]>
+
+export class AgentViewManager {
+  private sessions: Map<string, AgentSession> = new Map()
+  private sessionOrder: string[] = []
+  private idCounter = 0
+
+  /**
+   * Create a new background agent session.
+   */
+  create(title: string, task: string, options: CreateSessionOptions = {}): AgentSession {
+    const id = `agent-${++this.idCounter}-${Date.now()}`
+    const session: AgentSession = {
+      id,
+      title,
+      status: 'needs-input',
+      provider: options.provider ?? 'unknown',
+      model: options.model ?? 'unknown',
+      task,
+      createdAt: new Date(),
+      elapsedMs: 0,
+      messages: [],
+    }
+
+    this.sessions.set(id, session)
+    this.sessionOrder.push(id)
+
+    return session
+  }
+
+  /**
+   * List all sessions in creation order (newest first).
+   */
+  list(): AgentSession[] {
+    return [...this.sessionOrder]
+      .reverse()
+      .map((id) => this.sessions.get(id)!)
+      .filter(Boolean)
+  }
+
+  /**
+   * Group all sessions by their current status.
+   * Returns a record with keys for all four statuses (empty arrays if none).
+   */
+  groupByStatus(): StatusGroups {
+    const groups: StatusGroups = {
+      'needs-input': [],
+      working: [],
+      completed: [],
+      failed: [],
+    }
+
+    for (const id of this.sessionOrder) {
+      const session = this.sessions.get(id)
+      if (session) {
+        groups[session.status].push(session)
+      }
+    }
+
+    return groups
+  }
+
+  /**
+   * Get a session by ID.
+   */
+  get(id: string): AgentSession | undefined {
+    return this.sessions.get(id)
+  }
+
+  /**
+   * Peek at a session — returns the session metadata and up to 5 recent messages.
+   */
+  peek(id: string): SessionPeek | undefined {
+    const session = this.sessions.get(id)
+    if (!session) return undefined
+
+    const recentMessages = session.messages.slice(-5)
+    return { session, recentMessages }
+  }
+
+  /**
+   * Attach to a session — marks the session as working (if needs-input) and
+   * returns it so the caller can switch the main UI to this session.
+   */
+  attach(id: string): AgentSession | undefined {
+    const session = this.sessions.get(id)
+    if (!session) return undefined
+
+    // If the session was waiting for input, transition to working
+    if (session.status === 'needs-input') {
+      session.status = 'working'
+      session.startedAt = new Date()
+    }
+
+    return session
+  }
+
+  /**
+   * Kill (terminate) a session. Only kills sessions that are not already completed/failed.
+   * Returns true if the session was found and killed, false otherwise.
+   */
+  kill(id: string): boolean {
+    const session = this.sessions.get(id)
+    if (!session) return false
+
+    // Don't re-kill already terminal sessions
+    if (session.status === 'completed' || session.status === 'failed') {
+      return false
+    }
+
+    session.status = 'failed'
+    session.completedAt = new Date()
+    return true
+  }
+
+  /**
+   * Update a session's status and optionally add a message.
+   */
+  updateStatus(id: string, status: SessionStatus): boolean {
+    const session = this.sessions.get(id)
+    if (!session) return false
+
+    session.status = status
+
+    if (status === 'working' && !session.startedAt) {
+      session.startedAt = new Date()
+    }
+    if ((status === 'completed' || status === 'failed') && !session.completedAt) {
+      session.completedAt = new Date()
+    }
+
+    return true
+  }
+
+  /**
+   * Add a message to a session's message history.
+   */
+  addMessage(id: string, message: SessionMessage): boolean {
+    const session = this.sessions.get(id)
+    if (!session) return false
+
+    session.messages.push(message)
+    return true
+  }
+
+  /**
+   * Count sessions by status.
+   */
+  countByStatus(): Record<SessionStatus, number> {
+    const counts: Record<SessionStatus, number> = {
+      'needs-input': 0,
+      working: 0,
+      completed: 0,
+      failed: 0,
+    }
+
+    for (const [, session] of this.sessions) {
+      counts[session.status]++
+    }
+
+    return counts
+  }
+
+  /**
+   * Remove all completed and failed sessions (cleanup).
+   */
+  prune(): number {
+    let removed = 0
+    for (const [id, session] of this.sessions) {
+      if (session.status === 'completed' || session.status === 'failed') {
+        this.sessions.delete(id)
+        this.sessionOrder = this.sessionOrder.filter((oid) => oid !== id)
+        removed++
+      }
+    }
+    return removed
+  }
+}

package/src/agent-view/dashboard.tsx

@@ -0,0 +1,218 @@
+/**
+ * AgentViewDashboard — Ink TUI for background agent session management.
+ *
+ * Displays sessions grouped by status (needs-input / working / completed / failed),
+ * with j/k navigation, Space peek, Enter attach, and Esc exit.
+ *
+ * Usage:
+ *   mipham agents          (from CLI)
+ *   /agents                (from slash command within a running session)
+ */
+import React, { useState, useCallback, useMemo } from 'react'
+import { Box, Text, useInput } from 'ink'
+import { AgentViewManager, type AgentSession, type SessionStatus } from './agent-view-manager'
+import { SessionRow } from './session-row'
+import { SessionPeek } from './session-peek'
+
+interface DashboardProps {
+  manager: AgentViewManager
+  onAttach?: (session: AgentSession) => void
+  onExit: () => void
+}
+
+const STATUS_HEADERS: Record<string, { label: string; color: string }> = {
+  'needs-input': { label: 'Needs Input', color: 'yellow' },
+  working: { label: 'Working', color: 'cyan' },
+  completed: { label: 'Completed', color: 'green' },
+  failed: { label: 'Failed', color: 'red' },
+}
+
+export function AgentViewDashboard({ manager, onAttach, onExit }: DashboardProps) {
+  const [selectedIndex, setSelectedIndex] = useState(0)
+  const [peekingSessionId, setPeekingSessionId] = useState<string | null>(null)
+
+  // Build a flat list of sessions in group order, with group headers
+  const flatList = useMemo(() => {
+    const groups = manager.groupByStatus()
+    const result: Array<
+      | { type: 'header'; status: string; label: string; color: string; count: number }
+      | { type: 'session'; session: AgentSession }
+    > = []
+
+    const statusOrder: Array<keyof typeof STATUS_HEADERS> = [
+      'working',
+      'needs-input',
+      'completed',
+      'failed',
+    ]
+
+    for (const _status of statusOrder) {
+      const status = _status as SessionStatus
+      const sessions = groups[status] ?? []
+      result.push({
+        type: 'header',
+        status,
+        label: STATUS_HEADERS[status]!.label,
+        color: STATUS_HEADERS[status]!.color,
+        count: sessions.length,
+      })
+
+      for (const session of sessions) {
+        result.push({ type: 'session', session })
+      }
+    }
+
+    return result
+  }, [manager])
+
+  // Flatten sessions only for navigation (skip headers)
+  const sessionsOnly = useMemo(
+    () =>
+      flatList.filter((item) => item.type === 'session') as Array<{
+        type: 'session'
+        session: AgentSession
+      }>,
+    [flatList],
+  )
+
+  const handleAttach = useCallback(
+    (sessionId: string) => {
+      const session = manager.attach(sessionId)
+      if (session && onAttach) {
+        onAttach(session)
+      }
+    },
+    [manager, onAttach],
+  )
+
+  useInput((input, key) => {
+    if (key.escape) {
+      if (peekingSessionId) {
+        setPeekingSessionId(null)
+        return
+      }
+      onExit()
+      return
+    }
+
+    if (input === 'j') {
+      setSelectedIndex((prev) => Math.min(prev + 1, sessionsOnly.length - 1))
+      setPeekingSessionId(null)
+      return
+    }
+
+    if (input === 'k') {
+      setSelectedIndex((prev) => Math.max(prev - 1, 0))
+      setPeekingSessionId(null)
+      return
+    }
+
+    // Space — toggle peek
+    if (input === ' ') {
+      if (sessionsOnly.length === 0) return
+      const current = sessionsOnly[selectedIndex]
+      if (!current) return
+      setPeekingSessionId(peekingSessionId === current.session.id ? null : current.session.id)
+      return
+    }
+
+    // Enter — attach to selected session
+    if (key.return) {
+      if (sessionsOnly.length === 0) return
+      const current = sessionsOnly[selectedIndex]
+      if (!current) return
+      if (peekingSessionId) {
+        handleAttach(current.session.id)
+      } else {
+        handleAttach(current.session.id)
+      }
+      return
+    }
+  })
+
+  // Compute the peek data for the currently peeking session
+  const peekData = useMemo(() => {
+    if (!peekingSessionId) return null
+    return manager.peek(peekingSessionId) ?? null
+  }, [manager, peekingSessionId])
+
+  const totalSessions = sessionsOnly.length
+  const counts = manager.countByStatus()
+
+  return (
+    <Box flexDirection="column" padding={1} height="100%">
+      {/* Header */}
+      <Box marginBottom={1} flexDirection="column">
+        <Box>
+          <Text bold color="cyan">
+            Agent View
+          </Text>
+          <Text dimColor> — Background Agent Dashboard</Text>
+        </Box>
+        <Box>
+          <Text dimColor>
+            {totalSessions} session{totalSessions !== 1 ? 's' : ''}
+            {' · '}
+            <Text color="cyan">{counts.working} working</Text>
+            {' · '}
+            <Text color="yellow">{counts['needs-input']} input</Text>
+            {' · '}
+            <Text color="green">{counts.completed} done</Text>
+            {' · '}
+            <Text color="red">{counts.failed} failed</Text>
+          </Text>
+        </Box>
+        <Box>
+          <Text dimColor>j/k navigate · Space peek · Enter attach · Esc back</Text>
+        </Box>
+      </Box>
+
+      {/* Divider */}
+      <Box marginBottom={1}>
+        <Text dimColor>{'─'.repeat(70)}</Text>
+      </Box>
+
+      {/* Empty state */}
+      {totalSessions === 0 ? (
+        <Box flexDirection="column" paddingY={2} paddingLeft={2}>
+          <Text dimColor>No background agents.</Text>
+          <Text dimColor>
+            Use the Agent tool or type &quot;run this in background&quot; to spawn one.
+          </Text>
+        </Box>
+      ) : (
+        <Box flexDirection="column">
+          {/* Session list with group headers */}
+          {flatList.map((item, flatIdx) => {
+            if (item.type === 'header') {
+              return (
+                <Box key={`h-${item.status}`} marginY={1}>
+                  <Text bold color={item.color}>
+                    {' '}
+                    {item.label} ({item.count})
+                  </Text>
+                </Box>
+              )
+            }
+
+            // Map this session's position in sessionsOnly to selectedIndex
+            const sessionIdx = sessionsOnly.findIndex((s) => s.session.id === item.session.id)
+
+            return (
+              <SessionRow
+                key={item.session.id}
+                session={item.session}
+                isSelected={sessionIdx === selectedIndex}
+              />
+            )
+          })}
+        </Box>
+      )}
+
+      {/* Peek panel (shown below the list when peeking) */}
+      {peekData && (
+        <SessionPeek session={peekData.session} recentMessages={peekData.recentMessages} />
+      )}
+    </Box>
+  )
+}

package/src/agent-view/session-peek.tsx

@@ -0,0 +1,72 @@
+/**
+ * SessionPeek — a popup panel that shows the last few messages of
+ * a selected agent session. Invoked by pressing Space on a session row.
+ */
+import React from 'react'
+import { Box, Text } from 'ink'
+import type { AgentSession, SessionMessage } from './agent-view-manager'
+
+interface SessionPeekProps {
+  session: AgentSession
+  recentMessages: SessionMessage[]
+}
+
+const ROLE_COLORS: Record<string, string> = {
+  user: 'green',
+  assistant: 'cyan',
+  system: 'yellow',
+}
+
+export function SessionPeek({ session, recentMessages }: SessionPeekProps) {
+  return (
+    <Box flexDirection="column" borderStyle="single" borderColor="blue" padding={1} marginY={1}>
+      {/* Header */}
+      <Box marginBottom={1}>
+        <Text bold color="blue">
+          {' '}
+          Peek: {session.id}{' '}
+        </Text>
+        <Text dimColor>
+          — {session.title} · {session.provider}/{session.model}
+        </Text>
+      </Box>
+
+      {/* Divider */}
+      <Box marginBottom={1}>
+        <Text dimColor>{'─'.repeat(60)}</Text>
+      </Box>
+
+      {/* Messages */}
+      {recentMessages.length === 0 ? (
+        <Box paddingLeft={2}>
+          <Text dimColor>(no messages yet)</Text>
+        </Box>
+      ) : (
+        recentMessages.map((msg, i) => (
+          <Box key={i} flexDirection="column" marginBottom={1}>
+            <Text color={ROLE_COLORS[msg.role] || 'white'} bold>
+              [{msg.role}]
+            </Text>
+            <Box paddingLeft={4}>
+              <Text dimColor>
+                {msg.content.length > 120 ? msg.content.slice(0, 120) + '...' : msg.content}
+              </Text>
+            </Box>
+          </Box>
+        ))
+      )}
+
+      {/* Footer */}
+      <Box marginTop={1}>
+        <Text dimColor>{'─'.repeat(60)}</Text>
+      </Box>
+      <Box>
+        <Text dimColor>
+          {' '}
+          {recentMessages.length} message(s) · Total: {session.messages.length} · Status:{' '}
+          {session.status}
+        </Text>
+      </Box>
+    </Box>
+  )
+}

package/src/agent-view/session-row.tsx

@@ -0,0 +1,70 @@
+/**
+ * SessionRow — a single row in the Agent View dashboard.
+ * Shows provider, model, task, and elapsed time for one background agent session.
+ */
+import React from 'react'
+import { Box, Text } from 'ink'
+import type { AgentSession } from './agent-view-manager'
+
+interface SessionRowProps {
+  session: AgentSession
+  isSelected: boolean
+}
+
+function formatElapsed(ms: number): string {
+  if (ms < 1000) return '<1s'
+  const seconds = Math.floor(ms / 1000)
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.floor(seconds / 60)
+  const remainingSecs = seconds % 60
+  if (minutes < 60) return `${minutes}m ${remainingSecs}s`
+  const hours = Math.floor(minutes / 60)
+  const remainingMin = minutes % 60
+  return `${hours}h ${remainingMin}m`
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  'needs-input': 'yellow',
+  working: 'cyan',
+  completed: 'green',
+  failed: 'red',
+}
+
+const STATUS_LABELS: Record<string, string> = {
+  'needs-input': '[INPUT]',
+  working: '[WORK] ',
+  completed: '[DONE] ',
+  failed: '[FAIL] ',
+}
+
+export function SessionRow({ session, isSelected }: SessionRowProps) {
+  const color = STATUS_COLORS[session.status] || 'white'
+  const label = STATUS_LABELS[session.status] || ''
+  const prefix = isSelected ? '❯' : ' '
+
+  const taskPreview = session.task.length > 60 ? session.task.slice(0, 60) + '...' : session.task
+
+  return (
+    <Box flexDirection="column">
+      <Box>
+        <Text color={isSelected ? 'blue' : undefined} bold={isSelected}>
+          {prefix}{' '}
+        </Text>
+        <Text color={color}>{label}</Text>
+        <Text> </Text>
+        <Text bold={isSelected}>{session.id}</Text>
+        <Text dimColor>
+          {' '}
+          · {session.provider}/{session.model}
+        </Text>
+        <Text dimColor> · {formatElapsed(session.elapsedMs)}</Text>
+      </Box>
+      <Box paddingLeft={isSelected ? 4 : 3}>
+        <Text dimColor={!isSelected} color={isSelected ? 'white' : undefined}>
+          {taskPreview}
+        </Text>
+        {session.title !== session.task.slice(0, 60) && <Text dimColor> — {session.title}</Text>}
+      </Box>
+    </Box>
+  )
+}

package/src/artifacts/server.ts

@@ -3,6 +3,7 @@ import { createReadStream, existsSync, statSync } from 'node:fs'
 import { join, normalize, extname } from 'node:path'
 import { ARTIFACT_ALLOWED_EXTENSIONS } from '../shared/constants'
 import { readManifest } from './manifest'
+import { ArtifactVersioning } from './versioning'
 import type { ArtifactEntry } from '../shared/types'
 
 // ── SSE client tracking ──
@@ -27,10 +28,12 @@ export class ArtifactServer {
   private started = false
   private sseClients: SseClient[] = []
   private sseIdCounter = 0
+  private versioning: ArtifactVersioning
 
   constructor(artifactsDir: string, preferredPort: number) {
     this.artifactsDir = artifactsDir
     this.port = preferredPort
+    this.versioning = new ArtifactVersioning(artifactsDir)
   }
 
   /** Notify all connected SSE clients to reload. Called after artifact changes. */
@@ -133,6 +136,15 @@ export class ArtifactServer {
       return
     }
 
+    // Name-based SSE endpoint: GET /:name/sse
+    if (urlPath.endsWith('/sse') && urlPath.length > 4) {
+      const name = urlPath.slice(1, -4) // strip leading '/' and trailing '/sse'
+      if (name.length > 0 && !name.includes('/')) {
+        this.handleNameSse(name, res)
+        return
+      }
+    }
+
     // Gallery page
     if (urlPath === '/' || urlPath === '/index.html') {
       this.serveGallery(res)
@@ -165,6 +177,25 @@ export class ArtifactServer {
     })
   }
 
+  /** Per-artifact SSE stream: pushes content updates to connected browsers every 500ms. */
+  private handleNameSse(name: string, res: any): void {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    })
+
+    const interval = setInterval(() => {
+      const content = this.versioning.getVersion(name)
+      if (content) {
+        res.write(`data: ${JSON.stringify({ type: 'update', name, content })}\n\n`)
+      }
+    }, 500)
+
+    res.on('close', () => clearInterval(interval))
+  }
+
   // ── Gallery Page ──
 
   private serveGallery(res: any): void {