@plaited/acp-harness 0.3.2 → 0.4.0

package/src/headless-output-parser.ts

@@ -0,0 +1,251 @@
+/**
+ * Generic output parser for headless CLI agents.
+ *
+ * @remarks
+ * Uses schema-defined mappings to convert CLI JSON output into ACP session updates.
+ * Supports JSONPath-like expressions for matching and extraction.
+ *
+ * @packageDocumentation
+ */
+
+import type { HeadlessAdapterConfig, OutputEventMapping } from './headless.schemas.ts'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** ACP session update types */
+export type SessionUpdateType = 'thought' | 'tool_call' | 'message' | 'plan'
+
+/** Parsed session update from CLI output */
+export type ParsedUpdate = {
+  type: SessionUpdateType
+  content?: string
+  title?: string
+  status?: string
+  raw: unknown
+}
+
+/** Result extraction from CLI output */
+export type ParsedResult = {
+  isResult: true
+  content: string
+  raw: unknown
+}
+
+/** Not a result */
+export type NotResult = {
+  isResult: false
+}
+
+/** Parse result for final output */
+export type ResultParseResult = ParsedResult | NotResult
+
+// ============================================================================
+// JSONPath Implementation
+// ============================================================================
+
+/**
+ * Extracts a value from an object using a simple JSONPath expression.
+ *
+ * @remarks
+ * Supports:
+ * - `$.field` - Root field access
+ * - `$.nested.field` - Nested field access
+ * - `$.array[0]` - Array index access
+ * - `$.array[0].field` - Combined array and field access
+ * - `'literal'` - Literal string values (single quotes)
+ *
+ * @param obj - Object to extract from
+ * @param path - JSONPath expression
+ * @returns Extracted value or undefined
+ */
+export const jsonPath = (obj: unknown, path: string): unknown => {
+  // Handle literal strings (e.g., "'pending'")
+  if (path.startsWith("'") && path.endsWith("'")) {
+    return path.slice(1, -1)
+  }
+
+  // Handle JSONPath expressions (e.g., "$.type", "$.message.content[0].text")
+  if (!path.startsWith('$.')) {
+    return undefined
+  }
+
+  // Parse path into segments, handling both dot notation and array indices
+  // e.g., "message.content[0].text" -> ["message", "content", 0, "text"]
+  const segments: (string | number)[] = []
+  const pathBody = path.slice(2) // Remove "$."
+
+  // Split by dots first, then handle array indices within each part
+  for (const part of pathBody.split('.')) {
+    if (!part) continue
+
+    // Check for array index: "content[0]" or just "[0]"
+    const arrayMatch = part.match(/^([^[]*)\[(\d+)\]$/)
+    if (arrayMatch) {
+      const propName = arrayMatch[1]
+      const indexStr = arrayMatch[2]
+      if (propName) {
+        segments.push(propName)
+      }
+      if (indexStr) {
+        segments.push(parseInt(indexStr, 10))
+      }
+    } else {
+      segments.push(part)
+    }
+  }
+
+  let current: unknown = obj
+
+  for (const segment of segments) {
+    if (current === null || current === undefined) {
+      return undefined
+    }
+
+    if (typeof segment === 'number') {
+      // Array index access
+      if (!Array.isArray(current)) {
+        return undefined
+      }
+      current = current[segment]
+    } else {
+      // Property access
+      if (typeof current !== 'object') {
+        return undefined
+      }
+      current = (current as Record<string, unknown>)[segment]
+    }
+  }
+
+  return current
+}
+
+/**
+ * Extracts a string value from an object using JSONPath.
+ *
+ * @param obj - Object to extract from
+ * @param path - JSONPath expression
+ * @returns String value or undefined
+ */
+export const jsonPathString = (obj: unknown, path: string): string | undefined => {
+  const value = jsonPath(obj, path)
+  if (value === undefined || value === null) {
+    return undefined
+  }
+  return String(value)
+}
+
+// ============================================================================
+// Output Parser Factory
+// ============================================================================
+
+/**
+ * Creates an output parser from adapter configuration.
+ *
+ * @remarks
+ * The parser uses the schema's outputEvents mappings to:
+ * 1. Match incoming JSON lines against patterns
+ * 2. Extract content using JSONPath expressions
+ * 3. Emit ACP session update objects
+ *
+ * @param config - Headless adapter configuration
+ * @returns Parser function for individual lines
+ */
+export const createOutputParser = (config: HeadlessAdapterConfig) => {
+  const { outputEvents, result } = config
+
+  /**
+   * Parses a single JSON line from CLI output.
+   *
+   * @param line - JSON string from CLI stdout
+   * @returns Parsed update or null if no mapping matches
+   */
+  const parseLine = (line: string): ParsedUpdate | null => {
+    let event: unknown
+    try {
+      event = JSON.parse(line)
+    } catch {
+      // Not valid JSON, skip
+      return null
+    }
+
+    // Try each mapping until one matches
+    for (const mapping of outputEvents) {
+      const matchValue = jsonPath(event, mapping.match.path)
+      // Support wildcard "*" to match any non-null value
+      if (mapping.match.value === '*') {
+        if (matchValue !== undefined && matchValue !== null) {
+          return createUpdate(event, mapping)
+        }
+      } else if (matchValue === mapping.match.value) {
+        return createUpdate(event, mapping)
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Creates a ParsedUpdate from a matched event.
+   */
+  const createUpdate = (event: unknown, mapping: OutputEventMapping): ParsedUpdate => {
+    const update: ParsedUpdate = {
+      type: mapping.emitAs,
+      raw: event,
+    }
+
+    if (mapping.extract) {
+      if (mapping.extract.content) {
+        update.content = jsonPathString(event, mapping.extract.content)
+      }
+      if (mapping.extract.title) {
+        update.title = jsonPathString(event, mapping.extract.title)
+      }
+      if (mapping.extract.status) {
+        update.status = jsonPathString(event, mapping.extract.status)
+      }
+    }
+
+    return update
+  }
+
+  /**
+   * Checks if a JSON line represents the final result.
+   *
+   * @param line - JSON string from CLI stdout
+   * @returns Result extraction or indication that it's not a result
+   */
+  const parseResult = (line: string): ResultParseResult => {
+    let event: unknown
+    try {
+      event = JSON.parse(line)
+    } catch {
+      return { isResult: false }
+    }
+
+    const matchValue = jsonPath(event, result.matchPath)
+    // Support wildcard "*" to match any non-null value
+    const matches =
+      result.matchValue === '*' ? matchValue !== undefined && matchValue !== null : matchValue === result.matchValue
+
+    if (matches) {
+      const content = jsonPathString(event, result.contentPath)
+      return {
+        isResult: true,
+        content: content ?? '',
+        raw: event,
+      }
+    }
+
+    return { isResult: false }
+  }
+
+  return {
+    parseLine,
+    parseResult,
+  }
+}
+
+/** Output parser type */
+export type OutputParser = ReturnType<typeof createOutputParser>

package/src/headless-session-manager.ts

@@ -0,0 +1,389 @@
+/**
+ * Session manager for headless CLI agents.
+ *
+ * @remarks
+ * Manages the lifecycle of CLI agent sessions including:
+ * - Process spawning and tracking
+ * - Stream mode (persistent process) vs iterative mode (new process per turn)
+ * - Output parsing and ACP update emission
+ * - Session state management
+ *
+ * @packageDocumentation
+ */
+
+import type { Subprocess } from 'bun'
+import type { HeadlessAdapterConfig } from './headless.schemas.ts'
+import { createHistoryBuilder, type HistoryBuilder } from './headless-history-builder.ts'
+import { createOutputParser, type OutputParser, type ParsedUpdate } from './headless-output-parser.ts'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Session state */
+export type Session = {
+  /** Unique session identifier */
+  id: string
+  /** Working directory for this session */
+  cwd: string
+  /** Subprocess (stream mode only) */
+  process?: Subprocess
+  /** History builder (iterative mode only) */
+  history?: HistoryBuilder
+  /** Session ID from CLI (for resume, stream mode) */
+  cliSessionId?: string
+  /** Whether the session is active */
+  active: boolean
+  /** Turn count for this session */
+  turnCount: number
+}
+
+/** Update callback for emitting ACP session updates */
+export type UpdateCallback = (update: ParsedUpdate) => void
+
+/** Prompt result with final output */
+export type PromptResult = {
+  /** Final output content */
+  output: string
+  /** All updates collected during the prompt */
+  updates: ParsedUpdate[]
+  /** Session ID from CLI (if available) */
+  cliSessionId?: string
+}
+
+/** Session manager configuration */
+export type SessionManagerConfig = {
+  /** Headless adapter configuration */
+  schema: HeadlessAdapterConfig
+  /** Default timeout for operations in ms */
+  timeout?: number
+}
+
+// ============================================================================
+// Session Manager Factory
+// ============================================================================
+
+/**
+ * Creates a session manager for headless CLI agents.
+ *
+ * @remarks
+ * The session manager is the core orchestrator for CLI agent interaction:
+ *
+ * **Stream mode:**
+ * - Spawns one process per session
+ * - Keeps process alive across turns
+ * - Uses stdin/stdout for communication
+ * - Supports session resume via CLI flags
+ *
+ * **Iterative mode:**
+ * - Spawns a new process per turn
+ * - Accumulates history in prompts
+ * - No persistent process state
+ *
+ * @param config - Session manager configuration
+ * @returns Session manager with create, prompt, and cancel methods
+ */
+export const createSessionManager = (config: SessionManagerConfig) => {
+  const { schema, timeout = 60000 } = config
+  const sessions = new Map<string, Session>()
+  const outputParser = createOutputParser(schema)
+
+  /**
+   * Creates a new session.
+   *
+   * @param cwd - Working directory for the session
+   * @returns Created session
+   */
+  const create = async (cwd: string): Promise<Session> => {
+    const id = generateSessionId()
+
+    const session: Session = {
+      id,
+      cwd,
+      active: true,
+      turnCount: 0,
+    }
+
+    // Initialize mode-specific state
+    if (schema.sessionMode === 'iterative') {
+      session.history = createHistoryBuilder({
+        template: schema.historyTemplate,
+      })
+    }
+
+    sessions.set(id, session)
+    return session
+  }
+
+  /**
+   * Sends a prompt to a session and collects the response.
+   *
+   * @param sessionId - Session ID
+   * @param promptText - Prompt text to send
+   * @param onUpdate - Callback for streaming updates
+   * @returns Prompt result with output and updates
+   */
+  const prompt = async (sessionId: string, promptText: string, onUpdate?: UpdateCallback): Promise<PromptResult> => {
+    const session = sessions.get(sessionId)
+    if (!session) {
+      throw new Error(`Session not found: ${sessionId}`)
+    }
+
+    if (!session.active) {
+      throw new Error(`Session is not active: ${sessionId}`)
+    }
+
+    session.turnCount++
+
+    if (schema.sessionMode === 'stream') {
+      return promptStream(session, promptText, onUpdate)
+    }
+
+    return promptIterative(session, promptText, onUpdate)
+  }
+
+  /**
+   * Stream mode: send prompt via stdin to persistent process.
+   */
+  const promptStream = async (
+    session: Session,
+    promptText: string,
+    onUpdate?: UpdateCallback,
+  ): Promise<PromptResult> => {
+    // Build command for first turn or if no process exists
+    if (!session.process || session.process.killed) {
+      const args = buildCommand(session, promptText)
+      // First turn: prompt is in command line, use 'ignore' for stdin
+      // Some CLIs (like Claude) hang when stdin is piped but not written to
+      session.process = Bun.spawn(args, {
+        cwd: session.cwd,
+        stdin: 'ignore',
+        stdout: 'pipe',
+        stderr: 'inherit',
+      })
+    } else {
+      // Subsequent turns: spawn new process with resume flag
+      // (stdin-based multi-turn not currently supported)
+      const args = buildCommand(session, promptText)
+      session.process = Bun.spawn(args, {
+        cwd: session.cwd,
+        stdin: 'ignore',
+        stdout: 'pipe',
+        stderr: 'inherit',
+      })
+    }
+
+    return collectOutput(session, outputParser, onUpdate, timeout)
+  }
+
+  /**
+   * Iterative mode: spawn new process per turn with history context.
+   */
+  const promptIterative = async (
+    session: Session,
+    promptText: string,
+    onUpdate?: UpdateCallback,
+  ): Promise<PromptResult> => {
+    // Build full prompt with history
+    const fullPrompt = session.history?.buildPrompt(promptText) ?? promptText
+
+    // Build and spawn command
+    // Use 'ignore' for stdin - prompt is passed via command line flag
+    const args = buildCommand(session, fullPrompt)
+    session.process = Bun.spawn(args, {
+      cwd: session.cwd,
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'inherit',
+    })
+
+    const result = await collectOutput(session, outputParser, onUpdate, timeout)
+
+    // Store in history for next turn
+    session.history?.addTurn(promptText, result.output)
+
+    // Clean up process
+    session.process = undefined
+
+    return result
+  }
+
+  /**
+   * Builds the command array for spawning the CLI.
+   */
+  const buildCommand = (session: Session, promptText: string): string[] => {
+    const args = [...schema.command]
+
+    // Add output format flags
+    args.push(schema.output.flag, schema.output.value)
+
+    // Add auto-approve flags
+    if (schema.autoApprove) {
+      args.push(...schema.autoApprove)
+    }
+
+    // Add cwd flag if specified
+    if (schema.cwdFlag) {
+      args.push(schema.cwdFlag, session.cwd)
+    }
+
+    // Add resume flag if available (stream mode, after first turn)
+    if (schema.sessionMode === 'stream' && schema.resume && session.cliSessionId) {
+      args.push(schema.resume.flag, session.cliSessionId)
+    }
+
+    // Add prompt flag and text
+    if (schema.prompt.flag) {
+      args.push(schema.prompt.flag, promptText)
+    } else {
+      // Positional argument (no flag)
+      args.push(promptText)
+    }
+
+    return args
+  }
+
+  /**
+   * Cancels an active session.
+   *
+   * @param sessionId - Session ID to cancel
+   */
+  const cancel = (sessionId: string): void => {
+    const session = sessions.get(sessionId)
+    if (!session) return
+
+    session.active = false
+
+    if (session.process && !session.process.killed) {
+      session.process.kill()
+    }
+  }
+
+  /**
+   * Gets a session by ID.
+   *
+   * @param sessionId - Session ID
+   * @returns Session or undefined
+   */
+  const get = (sessionId: string): Session | undefined => {
+    return sessions.get(sessionId)
+  }
+
+  /**
+   * Deletes a session.
+   *
+   * @param sessionId - Session ID
+   */
+  const destroy = (sessionId: string): void => {
+    cancel(sessionId)
+    sessions.delete(sessionId)
+  }
+
+  return {
+    create,
+    prompt,
+    cancel,
+    get,
+    destroy,
+  }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Generates a unique session ID.
+ */
+const generateSessionId = (): string => {
+  return `sess_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+}
+
+/**
+ * Collects output from a running process.
+ *
+ * @param session - Active session
+ * @param parser - Output parser
+ * @param onUpdate - Update callback
+ * @param timeout - Timeout in ms
+ * @returns Collected output and updates
+ */
+const collectOutput = async (
+  session: Session,
+  parser: OutputParser,
+  onUpdate: UpdateCallback | undefined,
+  timeout: number,
+): Promise<PromptResult> => {
+  const updates: ParsedUpdate[] = []
+  let output = ''
+  let cliSessionId: string | undefined
+
+  const stdout = session.process?.stdout
+  if (!stdout || typeof stdout === 'number') {
+    throw new Error('No stdout available')
+  }
+
+  const reader = stdout.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    setTimeout(() => reject(new Error(`Prompt timed out after ${timeout}ms`)), timeout)
+  })
+
+  try {
+    const readLoop = async () => {
+      readLines: while (true) {
+        const { done, value } = await reader.read()
+
+        if (done) break
+
+        buffer += decoder.decode(value, { stream: true })
+
+        // Process complete lines
+        const lines = buffer.split('\n')
+        buffer = lines.pop() ?? ''
+
+        for (const line of lines) {
+          if (!line.trim()) continue
+
+          // Parse as update first (so updates are emitted even for result lines)
+          const update = parser.parseLine(line)
+          if (update) {
+            updates.push(update)
+            onUpdate?.(update)
+
+            // Extract CLI session ID if available
+            if (!cliSessionId && update.raw && typeof update.raw === 'object') {
+              const raw = update.raw as Record<string, unknown>
+              if (typeof raw.session_id === 'string') {
+                cliSessionId = raw.session_id
+                session.cliSessionId = cliSessionId
+              }
+            }
+          }
+
+          // Check for final result (after emitting update)
+          const resultCheck = parser.parseResult(line)
+          if (resultCheck.isResult) {
+            output = resultCheck.content
+            break readLines // Exit both loops immediately on result
+          }
+        }
+      }
+    }
+
+    await Promise.race([readLoop(), timeoutPromise])
+  } finally {
+    reader.releaseLock()
+  }
+
+  return {
+    output,
+    updates,
+    cliSessionId,
+  }
+}
+
+/** Session manager type */
+export type SessionManager = ReturnType<typeof createSessionManager>