@plaited/acp-harness 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaited/acp-harness",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "CLI tool for capturing agent trajectories from ACP-compatible agents",
   "license": "ISC",
   "engines": {

package/src/headless-output-parser.ts

@@ -53,12 +53,13 @@ export type ResultParseResult = ParsedResult | NotResult
  * - `$.field` - Root field access
  * - `$.nested.field` - Nested field access
  * - `$.array[0]` - Array index access
+ * - `$.array[*]` - Array wildcard (returns all items)
  * - `$.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
+ * @returns Extracted value, array of values (for wildcard), or undefined
  */
 export const jsonPath = (obj: unknown, path: string): unknown => {
   // Handle literal strings (e.g., "'pending'")
@@ -73,13 +74,25 @@ export const jsonPath = (obj: unknown, path: string): unknown => {
 
   // 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)[] = []
+  // e.g., "message.content[*].type" -> ["message", "content", "*", "type"]
+  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 wildcard: "content[*]"
+    const wildcardMatch = part.match(/^([^[]*)\[\*\]$/)
+    if (wildcardMatch) {
+      const propName = wildcardMatch[1]
+      if (propName) {
+        segments.push(propName)
+      }
+      segments.push('*')
+      continue
+    }
+
     // Check for array index: "content[0]" or just "[0]"
     const arrayMatch = part.match(/^([^[]*)\[(\d+)\]$/)
     if (arrayMatch) {
@@ -103,7 +116,13 @@ export const jsonPath = (obj: unknown, path: string): unknown => {
       return undefined
     }
 
-    if (typeof segment === 'number') {
+    if (segment === '*') {
+      // Array wildcard - return array as-is for further processing
+      if (!Array.isArray(current)) {
+        return undefined
+      }
+      return current
+    } else if (typeof segment === 'number') {
       // Array index access
       if (!Array.isArray(current)) {
         return undefined
@@ -159,9 +178,9 @@ export const createOutputParser = (config: HeadlessAdapterConfig) => {
    * Parses a single JSON line from CLI output.
    *
    * @param line - JSON string from CLI stdout
-   * @returns Parsed update or null if no mapping matches
+   * @returns Parsed update, array of updates (for wildcard matches), or null if no mapping matches
    */
-  const parseLine = (line: string): ParsedUpdate | null => {
+  const parseLine = (line: string): ParsedUpdate | ParsedUpdate[] | null => {
     let event: unknown
     try {
       event = JSON.parse(line)
@@ -173,13 +192,40 @@ export const createOutputParser = (config: HeadlessAdapterConfig) => {
     // 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) {
+
+      // Handle array results from wildcard paths (e.g., $.message.content[*])
+      if (Array.isArray(matchValue)) {
+        const updates: ParsedUpdate[] = []
+        for (const item of matchValue) {
+          // Check if this array item matches the expected value
+          if (mapping.match.value === '*') {
+            // Wildcard: match any non-null item
+            if (item !== undefined && item !== null) {
+              updates.push(createUpdate(item, mapping))
+            }
+          } else if (typeof item === 'object' && item !== null && 'type' in item) {
+            // For objects with 'type' property, check nested match
+            const itemType = (item as Record<string, unknown>).type
+            if (itemType === mapping.match.value) {
+              updates.push(createUpdate(item, mapping))
+            }
+          } else if (item === mapping.match.value) {
+            // For primitives, direct match
+            updates.push(createUpdate(item, mapping))
+          }
+        }
+        if (updates.length > 0) {
+          return updates
+        }
+      } else {
+        // Single value matching (original behavior)
+        if (mapping.match.value === '*') {
+          if (matchValue !== undefined && matchValue !== null) {
+            return createUpdate(event, mapping)
+          }
+        } else if (matchValue === mapping.match.value) {
           return createUpdate(event, mapping)
         }
-      } else if (matchValue === mapping.match.value) {
-        return createUpdate(event, mapping)
       }
     }
 

package/src/headless-session-manager.ts

@@ -153,24 +153,37 @@ export const createSessionManager = (config: SessionManagerConfig) => {
     // 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
+
+      // Choose stdin mode based on schema configuration
+      const stdinMode = schema.prompt.stdin ? 'pipe' : 'ignore'
+
       session.process = Bun.spawn(args, {
         cwd: session.cwd,
-        stdin: 'ignore',
+        stdin: stdinMode,
         stdout: 'pipe',
         stderr: 'inherit',
       })
+
+      // If using stdin, write the prompt
+      if (schema.prompt.stdin && session.process) {
+        writePromptToStdin(session.process, promptText)
+      }
     } else {
       // Subsequent turns: spawn new process with resume flag
-      // (stdin-based multi-turn not currently supported)
       const args = buildCommand(session, promptText)
+      const stdinMode = schema.prompt.stdin ? 'pipe' : 'ignore'
+
       session.process = Bun.spawn(args, {
         cwd: session.cwd,
-        stdin: 'ignore',
+        stdin: stdinMode,
         stdout: 'pipe',
         stderr: 'inherit',
       })
+
+      // If using stdin, write the prompt
+      if (schema.prompt.stdin && session.process) {
+        writePromptToStdin(session.process, promptText)
+      }
     }
 
     return collectOutput(session, outputParser, onUpdate, timeout)
@@ -188,15 +201,21 @@ export const createSessionManager = (config: SessionManagerConfig) => {
     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)
+    const stdinMode = schema.prompt.stdin ? 'pipe' : 'ignore'
+
     session.process = Bun.spawn(args, {
       cwd: session.cwd,
-      stdin: 'ignore',
+      stdin: stdinMode,
       stdout: 'pipe',
       stderr: 'inherit',
     })
 
+    // If using stdin, write the prompt
+    if (schema.prompt.stdin && session.process) {
+      writePromptToStdin(session.process, fullPrompt)
+    }
+
     const result = await collectOutput(session, outputParser, onUpdate, timeout)
 
     // Store in history for next turn
@@ -232,12 +251,14 @@ export const createSessionManager = (config: SessionManagerConfig) => {
       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)
+    // Add prompt flag and text (skip if using stdin)
+    if (!schema.prompt.stdin) {
+      if (schema.prompt.flag) {
+        args.push(schema.prompt.flag, promptText)
+      } else {
+        // Positional argument (no flag)
+        args.push(promptText)
+      }
     }
 
     return args
@@ -299,6 +320,32 @@ const generateSessionId = (): string => {
   return `sess_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
 }
 
+/**
+ * Writes a prompt to a process stdin stream.
+ *
+ * @remarks
+ * Uses Bun's FileSink API to write text to the process stdin.
+ * The FileSink type provides `write()` and `flush()` methods for
+ * efficient stream writing without async overhead.
+ *
+ * Type guard ensures stdin is a FileSink (not a file descriptor number)
+ * before attempting to write. This handles Bun's subprocess stdin types:
+ * - `'pipe'` → FileSink with write/flush methods
+ * - `'ignore'` → null (not writable)
+ * - number → file descriptor (not a FileSink)
+ *
+ * @param process - Subprocess with stdin stream
+ * @param prompt - Prompt text to write
+ *
+ * @internal
+ */
+const writePromptToStdin = (process: Subprocess, prompt: string): void => {
+  if (process.stdin && typeof process.stdin !== 'number') {
+    process.stdin.write(`${prompt}\n`)
+    process.stdin.flush()
+  }
+}
+
 /**
  * Collects output from a running process.
  *
@@ -349,16 +396,21 @@ const collectOutput = async (
 
           // 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
+          if (update !== null) {
+            // Handle both single updates and arrays of updates (from wildcard matches)
+            const updatesToProcess = Array.isArray(update) ? update : [update]
+
+            for (const singleUpdate of updatesToProcess) {
+              updates.push(singleUpdate)
+              onUpdate?.(singleUpdate)
+
+              // Extract CLI session ID if available
+              if (!cliSessionId && singleUpdate.raw && typeof singleUpdate.raw === 'object') {
+                const raw = singleUpdate.raw as Record<string, unknown>
+                if (typeof raw.session_id === 'string') {
+                  cliSessionId = raw.session_id
+                  session.cliSessionId = cliSessionId
+                }
               }
             }
           }

package/src/headless.schemas.ts

@@ -79,13 +79,25 @@ export type OutputEventMapping = z.infer<typeof OutputEventMappingSchema>
 
 /**
  * Schema for how to pass prompts to the CLI.
+ *
+ * @remarks
+ * Three modes are supported:
+ * 1. **Flag-based**: `flag: "-p"` - Pass prompt via command-line flag
+ * 2. **Positional**: `flag: ""` - Pass prompt as positional argument
+ * 3. **Stdin**: `stdin: true` - Write prompt to stdin (command should include `-` or equivalent)
  */
-export const PromptConfigSchema = z.object({
-  /** Flag to pass prompt (e.g., "-p", "--prompt"). Omit for stdin. */
-  flag: z.string().optional(),
-  /** Format for stdin input in stream mode */
-  stdinFormat: z.enum(['text', 'json']).optional(),
-})
+export const PromptConfigSchema = z
+  .object({
+    /** Flag to pass prompt (e.g., "-p", "--prompt"). Empty string for positional. */
+    flag: z.string().optional(),
+    /** Use stdin to pass prompt instead of command args */
+    stdin: z.boolean().optional(),
+    /** Format for stdin input in stream mode */
+    stdinFormat: z.enum(['text', 'json']).optional(),
+  })
+  .refine((data) => !(data.flag && data.stdin), {
+    message: "Cannot specify both 'flag' and 'stdin' modes - use either flag-based or stdin mode, not both",
+  })
 
 /** Prompt configuration type */
 export type PromptConfig = z.infer<typeof PromptConfigSchema>

package/src/tests/headless.spec.ts

@@ -118,6 +118,59 @@ describe('HeadlessAdapterSchema', () => {
     })
   })
 
+  describe('stdin mode configuration', () => {
+    test('validates schema with stdin: true', () => {
+      const stdinSchema = {
+        version: 1,
+        name: 'stdin-agent',
+        command: ['agent', 'exec', '-'],
+        sessionMode: 'stream',
+        prompt: { stdin: true },
+        output: { flag: '--format', value: 'json' },
+        outputEvents: [],
+        result: { matchPath: '$.type', matchValue: 'done', contentPath: '$.text' },
+      }
+      const result = HeadlessAdapterSchema.safeParse(stdinSchema)
+      expect(result.success).toBe(true)
+    })
+
+    test('validates schema with stdin: false', () => {
+      const stdinSchema = {
+        version: 1,
+        name: 'stdin-agent',
+        command: ['agent'],
+        sessionMode: 'stream',
+        prompt: { stdin: false, flag: '-p' },
+        output: { flag: '--format', value: 'json' },
+        outputEvents: [],
+        result: { matchPath: '$.type', matchValue: 'done', contentPath: '$.text' },
+      }
+      const result = HeadlessAdapterSchema.safeParse(stdinSchema)
+      expect(result.success).toBe(true)
+    })
+
+    test('validates schema with positional prompt and - in command', () => {
+      const stdinSchema = {
+        version: 1,
+        name: 'codex-like',
+        command: ['codex', 'exec', '--json', '-'],
+        sessionMode: 'iterative',
+        prompt: { stdin: true },
+        output: { flag: '', value: '' },
+        outputEvents: [
+          {
+            match: { path: '$.item.type', value: 'agent_message' },
+            emitAs: 'message',
+            extract: { content: '$.item.text' },
+          },
+        ],
+        result: { matchPath: '$.type', matchValue: 'turn.completed', contentPath: '$.usage.output_tokens' },
+      }
+      const result = HeadlessAdapterSchema.safeParse(stdinSchema)
+      expect(result.success).toBe(true)
+    })
+  })
+
   describe('invalid schemas', () => {
     test('rejects missing version', () => {
       const invalid = { ...validClaudeSchema, version: undefined }
@@ -143,6 +196,22 @@ describe('HeadlessAdapterSchema', () => {
       expect(result.success).toBe(false)
     })
 
+    test('rejects both flag and stdin specified', () => {
+      const invalid = {
+        ...validClaudeSchema,
+        prompt: {
+          flag: '-p',
+          stdin: true,
+        },
+      }
+      const result = HeadlessAdapterSchema.safeParse(invalid)
+      expect(result.success).toBe(false)
+      // Type assertion after checking success is false
+      const error = (result as { success: false; error: { issues: Array<{ message: string }> } }).error
+      expect(error.issues.length).toBeGreaterThan(0)
+      expect(error.issues[0]!.message).toContain("Cannot specify both 'flag' and 'stdin' modes")
+    })
+
     test('rejects invalid emitAs type', () => {
       const invalid = {
         ...validClaudeSchema,
@@ -287,17 +356,21 @@ describe('createOutputParser', () => {
       const line = JSON.stringify({ type: 'assistant', message: { text: 'Hello' } })
       const result = parser.parseLine(line)
       expect(result).not.toBeNull()
-      expect(result?.type).toBe('message')
-      expect(result?.content).toBe('Hello')
+      // Handle both single result and array of results
+      const singleResult = Array.isArray(result) ? result[0] : result
+      expect(singleResult?.type).toBe('message')
+      expect(singleResult?.content).toBe('Hello')
     })
 
     test('maps tool_use type to tool_call', () => {
       const line = JSON.stringify({ type: 'tool_use', name: 'Read' })
       const result = parser.parseLine(line)
       expect(result).not.toBeNull()
-      expect(result?.type).toBe('tool_call')
-      expect(result?.title).toBe('Read')
-      expect(result?.status).toBe('pending')
+      // Handle both single result and array of results
+      const singleResult = Array.isArray(result) ? result[0] : result
+      expect(singleResult?.type).toBe('tool_call')
+      expect(singleResult?.title).toBe('Read')
+      expect(singleResult?.status).toBe('pending')
     })
 
     test('returns null for unmapped event types', () => {
@@ -320,7 +393,152 @@ describe('createOutputParser', () => {
       const event = { type: 'assistant', message: { text: 'Hi' } }
       const line = JSON.stringify(event)
       const result = parser.parseLine(line)
-      expect(result?.raw).toEqual(event)
+      // Handle both single result and array of results
+      const singleResult = Array.isArray(result) ? result[0] : result
+      expect(singleResult?.raw).toEqual(event)
+    })
+  })
+
+  describe('parseLine with array wildcards', () => {
+    const wildcardConfig = parseHeadlessConfig({
+      version: 1,
+      name: 'wildcard-test',
+      command: ['test'],
+      sessionMode: 'stream',
+      prompt: { flag: '-p' },
+      output: { flag: '--output', value: 'json' },
+      outputEvents: [
+        {
+          match: { path: '$.message.content[*].type', value: 'tool_use' },
+          emitAs: 'tool_call',
+          extract: { title: '$.name', status: "'pending'" },
+        },
+        {
+          match: { path: '$.items[*]', value: '*' },
+          emitAs: 'message',
+          extract: { content: '$.text' },
+        },
+      ],
+      result: {
+        matchPath: '$.type',
+        matchValue: 'result',
+        contentPath: '$.output',
+      },
+    })
+    const wildcardParser = createOutputParser(wildcardConfig)
+
+    test('returns array of updates for matching array items', () => {
+      const line = JSON.stringify({
+        message: {
+          content: [
+            { type: 'tool_use', name: 'Read', input: {} },
+            { type: 'text', value: 'Hello' },
+            { type: 'tool_use', name: 'Write', input: {} },
+          ],
+        },
+      })
+      const result = wildcardParser.parseLine(line)
+      expect(Array.isArray(result)).toBe(true)
+      if (Array.isArray(result)) {
+        expect(result).toHaveLength(2)
+        expect(result[0]!.type).toBe('tool_call')
+        expect(result[0]!.title).toBe('Read')
+        expect(result[0]!.status).toBe('pending')
+        expect(result[1]!.type).toBe('tool_call')
+        expect(result[1]!.title).toBe('Write')
+        expect(result[1]!.status).toBe('pending')
+      }
+    })
+
+    test('handles empty array gracefully', () => {
+      const line = JSON.stringify({
+        message: { content: [] },
+      })
+      const result = wildcardParser.parseLine(line)
+      expect(result).toBeNull()
+    })
+
+    test('handles non-matching array items', () => {
+      const line = JSON.stringify({
+        message: {
+          content: [
+            { type: 'text', value: 'No tool use here' },
+            { type: 'image', data: 'base64...' },
+          ],
+        },
+      })
+      const result = wildcardParser.parseLine(line)
+      expect(result).toBeNull()
+    })
+
+    test('matches wildcard value for all non-null items', () => {
+      const line = JSON.stringify({
+        items: [{ text: 'Item 1' }, { text: 'Item 2' }, { text: 'Item 3' }],
+      })
+      const result = wildcardParser.parseLine(line)
+      expect(Array.isArray(result)).toBe(true)
+      if (Array.isArray(result)) {
+        expect(result).toHaveLength(3)
+        expect(result[0]!.content).toBe('Item 1')
+        expect(result[1]!.content).toBe('Item 2')
+        expect(result[2]!.content).toBe('Item 3')
+      }
+    })
+
+    test('handles mixed array content with type guards', () => {
+      const line = JSON.stringify({
+        message: {
+          content: [
+            { type: 'tool_use', name: 'Valid' },
+            'string-item',
+            { no_type_property: true },
+            null,
+            { type: 'tool_use', name: 'AlsoValid' },
+          ],
+        },
+      })
+      const result = wildcardParser.parseLine(line)
+      expect(Array.isArray(result)).toBe(true)
+      if (Array.isArray(result)) {
+        expect(result).toHaveLength(2)
+        expect(result[0]!.title).toBe('Valid')
+        expect(result[1]!.title).toBe('AlsoValid')
+      }
+    })
+  })
+
+  describe('jsonPath with array wildcard', () => {
+    test('extracts array with [*] wildcard', () => {
+      const obj = { items: [{ id: 1 }, { id: 2 }] }
+      const result = jsonPath(obj, '$.items[*]')
+      expect(Array.isArray(result)).toBe(true)
+      if (Array.isArray(result)) {
+        expect(result).toHaveLength(2)
+      }
+    })
+
+    test('returns undefined for non-array at wildcard position', () => {
+      const obj = { items: 'not-an-array' }
+      const result = jsonPath(obj, '$.items[*]')
+      expect(result).toBeUndefined()
+    })
+
+    test('handles empty array', () => {
+      const obj = { items: [] }
+      const result = jsonPath(obj, '$.items[*]')
+      expect(result).toEqual([])
+    })
+
+    test('handles nested path to array', () => {
+      const obj = { message: { content: [1, 2, 3] } }
+      const result = jsonPath(obj, '$.message.content[*]')
+      expect(result).toEqual([1, 2, 3])
+    })
+
+    test('returns undefined when path before wildcard is invalid', () => {
+      const obj = { items: [1, 2, 3] }
+      const result = jsonPath(obj, '$.missing[*]')
+      expect(result).toBeUndefined()
     })
   })