@pi-in-go/pigpen-acp 0.1.0

package/port/oracle/pi-acp/src/pi-rpc/process.ts

@@ -0,0 +1,432 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import * as readline from 'node:readline'
+import crossSpawn from 'cross-spawn'
+import { getPiCommand, shouldUseShellForPiCommand } from './command.js'
+
+export class PiRpcSpawnError extends Error {
+  /** Underlying spawn error code, e.g. ENOENT, EACCES */
+  code?: string
+
+  constructor(message: string, opts?: { code?: string; cause?: unknown }) {
+    super(message)
+    this.name = 'PiRpcSpawnError'
+    this.code = opts?.code
+    ;(this as any).cause = opts?.cause
+  }
+}
+
+const ESC = String.fromCharCode(0x1b)
+const CSI = String.fromCharCode(0x9b)
+
+const ANSI_ESCAPE_REGEX = new RegExp(
+  `[${ESC}${CSI}][[\\]()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]`,
+  'g'
+)
+
+function stripAnsi(s: string): string {
+  // Basic ANSI escape stripping (colors, cursor movement, etc.)
+  return s.replace(ANSI_ESCAPE_REGEX, '')
+}
+
+type PiRpcCommand =
+  | { type: 'prompt'; id?: string; message: string; images?: unknown[] }
+  | { type: 'abort'; id?: string }
+  | { type: 'get_state'; id?: string }
+  // Model
+  | { type: 'get_available_models'; id?: string }
+  | { type: 'set_model'; id?: string; provider: string; modelId: string }
+  // Thinking
+  | { type: 'get_available_thinking_levels'; id?: string }
+  | { type: 'set_thinking_level'; id?: string; level: string }
+  // Modes
+  | { type: 'set_follow_up_mode'; id?: string; mode: 'all' | 'one-at-a-time' }
+  | { type: 'set_steering_mode'; id?: string; mode: 'all' | 'one-at-a-time' }
+  // Compaction
+  | { type: 'compact'; id?: string; customInstructions?: string }
+  | { type: 'set_auto_compaction'; id?: string; enabled: boolean }
+  // Session
+  | { type: 'get_session_stats'; id?: string }
+  | { type: 'set_session_name'; id?: string; name: string }
+  | { type: 'export_html'; id?: string; outputPath?: string }
+  | { type: 'switch_session'; id?: string; sessionPath: string }
+  // Messages
+  | { type: 'get_messages'; id?: string }
+  // Commands
+  | { type: 'get_commands'; id?: string }
+
+type PiRpcResponse = {
+  type: 'response'
+  id?: string
+  command: string
+  success: boolean
+  data?: unknown
+  error?: string
+}
+
+type PiExtensionUiResponse =
+  | { id: string; value: string }
+  | { id: string; confirmed: boolean }
+  | { id: string; cancelled: true }
+
+export type PiRpcEvent = Record<string, unknown>
+
+/** Maximum wait for an auxiliary context-usage update. */
+export const SESSION_STATS_TIMEOUT_MS = 1_000
+
+/**
+ * Shape of `stats.contextUsage` in pi's `get_session_stats` response.
+ * `tokens` is null while pi has no trustworthy token count (e.g. right after compaction).
+ */
+export type PiContextUsage = {
+  tokens?: number | null
+  contextWindow?: number | null
+}
+
+export type PiSessionStats = {
+  sessionId?: string
+  sessionFile?: string
+  totalMessages?: number
+  cost?: number
+  tokens?: {
+    input?: number
+    output?: number
+    cacheRead?: number
+    cacheWrite?: number
+    total?: number
+  }
+  contextUsage?: PiContextUsage | null
+}
+
+type SpawnParams = {
+  cwd: string
+  /** Optional override for `pi` executable name/path */
+  piCommand?: string
+  /** If set, pi will persist the session to this exact file (via `--session <path>`). */
+  sessionPath?: string
+}
+
+export class PiRpcProcess {
+  private readonly child: ChildProcessWithoutNullStreams
+  private readonly pending = new Map<string, { resolve: (v: PiRpcResponse) => void; reject: (e: unknown) => void }>()
+  private eventHandlers: Array<(ev: PiRpcEvent) => void> = []
+  private readonly preludeLines: string[] = []
+
+  private constructor(child: ChildProcessWithoutNullStreams) {
+    this.child = child
+
+    const rl = readline.createInterface({ input: child.stdout })
+    rl.on('line', line => {
+      if (!line.trim()) return
+      let msg: any
+      try {
+        msg = JSON.parse(line)
+      } catch {
+        // pi may emit a human-readable prelude on stdout before NDJSON starts.
+        // Capture it so the ACP adapter can surface it on session start.
+        const cleaned = stripAnsi(String(line)).trimEnd()
+        if (cleaned) this.preludeLines.push(cleaned)
+        return
+      }
+
+      if (msg?.type === 'response') {
+        const id = typeof msg.id === 'string' ? msg.id : undefined
+        // `resolve` removes the pending entry. Responses for unknown or already timed-out
+        // ids are dropped: a response is never a pi event, so it must not be broadcast.
+        if (id !== undefined) this.pending.get(id)?.resolve(msg as PiRpcResponse)
+        return
+      }
+
+      for (const h of this.eventHandlers) h(msg as PiRpcEvent)
+    })
+
+    child.on('exit', (code, signal) => {
+      const err = new Error(`pi process exited (code=${code}, signal=${signal})`)
+      for (const [, p] of this.pending) p.reject(err)
+      this.pending.clear()
+    })
+
+    child.on('error', err => {
+      for (const [, p] of this.pending) p.reject(err)
+      this.pending.clear()
+    })
+  }
+
+  static async spawn(params: SpawnParams): Promise<PiRpcProcess> {
+    // On Windows, npm commonly creates pi.cmd / pi.bat launcher scripts.
+    const cmd = getPiCommand(params.piCommand)
+
+    // Speed/robustness for ACP:
+    // - themes are irrelevant in rpc mode and can be noisy/slow to load.
+    // Keep extensions + prompt templates enabled because ACP users may rely on them
+    // (e.g. MCP extensions, prompt templates for workflows).
+    const args = ['--mode', 'rpc', '--no-themes']
+    if (params.sessionPath) args.push('--session', params.sessionPath)
+
+    // Windows cmd launchers need shell escaping; direct executables use native argv.
+    const start = shouldUseShellForPiCommand(cmd) ? crossSpawn : spawn
+    const child = start(cmd, args, {
+      cwd: params.cwd,
+      stdio: 'pipe',
+      env: process.env
+    }) as ChildProcessWithoutNullStreams
+
+    // Ensure spawn failures (e.g. ENOENT when pi isn't installed) are surfaced as a
+    // deterministic error instead of later EPIPE/internal-error noise.
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const onSpawn = () => {
+          cleanup()
+          resolve()
+        }
+        const onError = (err: any) => {
+          cleanup()
+          reject(err)
+        }
+        const cleanup = () => {
+          child.off('spawn', onSpawn)
+          child.off('error', onError)
+        }
+
+        child.once('spawn', onSpawn)
+        child.once('error', onError)
+      })
+    } catch (e: any) {
+      const code = typeof e?.code === 'string' ? e.code : undefined
+      if (code === 'ENOENT') {
+        throw new PiRpcSpawnError(
+          `Could not start pi: executable not found (command: ${cmd}). Pi needs to be installed before it can run in ACP clients. Install it via \`npm install -g @earendil-works/pi-coding-agent\` or ensure \`pi\` is on your PATH. Then try again.`,
+          { code, cause: e }
+        )
+      }
+
+      if (code === 'EACCES') {
+        throw new PiRpcSpawnError(`Could not start pi: permission denied (command: ${cmd}).`, { code, cause: e })
+      }
+
+      throw new PiRpcSpawnError(`Could not start pi (command: ${cmd}).`, { code, cause: e })
+    }
+
+    child.stderr.on('data', () => {
+      // leave stderr untouched; ACP clients may capture it.
+    })
+
+    const proc = new PiRpcProcess(child)
+
+    // Best-effort handshake.
+    // Important: pi may emit a get_state response pointing at a sessionFile in a directory
+    // that is created lazily. Create the parent dir up-front to avoid later parse errors
+    // when we call commands like export_html.
+    try {
+      const state = (await proc.getState()) as any
+      const sessionFile = typeof state?.sessionFile === 'string' ? state.sessionFile : null
+      if (sessionFile) {
+        const { mkdirSync } = await import('node:fs')
+        const { dirname } = await import('node:path')
+        mkdirSync(dirname(sessionFile), { recursive: true })
+      }
+    } catch {
+      // ignore for now
+    }
+
+    return proc
+  }
+
+  onEvent(handler: (ev: PiRpcEvent) => void): () => void {
+    this.eventHandlers.push(handler)
+    return () => {
+      this.eventHandlers = this.eventHandlers.filter(h => h !== handler)
+    }
+  }
+
+  dispose(signal: NodeJS.Signals | number = 'SIGTERM'): void {
+    if (this.child.killed) return
+    try {
+      this.child.kill(signal as any)
+    } catch {
+      // ignore
+    }
+  }
+
+  /**
+   * Human-readable stdout lines emitted before RPC NDJSON begins (e.g. Context/Skills/Extensions info).
+   * Themes are typically noisy/less useful for ACP, so callers can filter as needed.
+   */
+  consumePreludeLines(): string[] {
+    const lines = this.preludeLines.splice(0, this.preludeLines.length)
+    return lines
+  }
+
+  async prompt(message: string, images: unknown[] = []): Promise<void> {
+    const res = await this.request({ type: 'prompt', message, images })
+    if (!res.success) throw new Error(`pi prompt failed: ${res.error ?? JSON.stringify(res.data)}`)
+  }
+
+  async abort(): Promise<void> {
+    const res = await this.request({ type: 'abort' })
+    if (!res.success) throw new Error(`pi abort failed: ${res.error ?? JSON.stringify(res.data)}`)
+  }
+
+  async getState(): Promise<unknown> {
+    const res = await this.request({ type: 'get_state' })
+    if (!res.success) throw new Error(`pi get_state failed: ${res.error ?? JSON.stringify(res.data)}`)
+    return res.data
+  }
+
+  async getAvailableModels(): Promise<unknown> {
+    const res = await this.request({ type: 'get_available_models' })
+    if (!res.success) throw new Error(`pi get_available_models failed: ${res.error ?? JSON.stringify(res.data)}`)
+    return res.data
+  }
+
+  async setModel(provider: string, modelId: string): Promise<unknown> {
+    const res = await this.request({ type: 'set_model', provider, modelId })
+    if (!res.success) throw new Error(`pi set_model failed: ${res.error ?? JSON.stringify(res.data)}`)
+    return res.data
+  }
+
+  async getAvailableThinkingLevels(): Promise<string[]> {
+    const res = await this.request({ type: 'get_available_thinking_levels' })
+    if (!res.success)
+      throw new Error(`pi get_available_thinking_levels failed: ${res.error ?? JSON.stringify(res.data)}`)
+    const data = res.data
+    const levels = data && typeof data === 'object' && 'levels' in data ? data.levels : undefined
+    if (
+      !Array.isArray(levels) ||
+      levels.length === 0 ||
+      !levels.every(level => typeof level === 'string' && level.length > 0)
+    ) {
+      throw new Error('pi get_available_thinking_levels returned invalid levels')
+    }
+    return levels
+  }
+
+  async setThinkingLevel(level: string): Promise<void> {
+    const res = await this.request({ type: 'set_thinking_level', level })
+    if (!res.success) throw new Error(`pi set_thinking_level failed: ${res.error ?? JSON.stringify(res.data)}`)
+  }
+
+  async setFollowUpMode(mode: 'all' | 'one-at-a-time'): Promise<void> {
+    const res = await this.request({ type: 'set_follow_up_mode', mode })
+    if (!res.success) throw new Error(`pi set_follow_up_mode failed: ${res.error ?? JSON.stringify(res.data)}`)
+  }
+
+  async setSteeringMode(mode: 'all' | 'one-at-a-time'): Promise<void> {
+    const res = await this.request({ type: 'set_steering_mode', mode })
+    if (!res.success) throw new Error(`pi set_steering_mode failed: ${res.error ?? JSON.stringify(res.data)}`)
+  }
+
+  async compact(customInstructions?: string): Promise<unknown> {
+    const res = await this.request({ type: 'compact', customInstructions })
+    if (!res.success) throw new Error(`pi compact failed: ${res.error ?? JSON.stringify(res.data)}`)
+    return res.data
+  }
+
+  async setAutoCompaction(enabled: boolean): Promise<void> {
+    const res = await this.request({ type: 'set_auto_compaction', enabled })
+    if (!res.success) throw new Error(`pi set_auto_compaction failed: ${res.error ?? JSON.stringify(res.data)}`)
+  }
+
+  async getSessionStats(timeoutMs?: number): Promise<PiSessionStats> {
+    const res = await this.request({ type: 'get_session_stats' }, { timeoutMs })
+    if (!res.success) throw new Error(`pi get_session_stats failed: ${res.error ?? JSON.stringify(res.data)}`)
+    return (res.data ?? {}) as PiSessionStats
+  }
+
+  async setSessionName(name: string): Promise<void> {
+    const res = await this.request({ type: 'set_session_name', name })
+    if (!res.success) throw new Error(`pi set_session_name failed: ${res.error ?? JSON.stringify(res.data)}`)
+  }
+
+  async exportHtml(outputPath?: string): Promise<{ path: string }> {
+    const res = await this.request({ type: 'export_html', outputPath })
+    if (!res.success) throw new Error(`pi export_html failed: ${res.error ?? JSON.stringify(res.data)}`)
+    const data: any = res.data
+    return { path: String(data?.path ?? '') }
+  }
+
+  async switchSession(sessionPath: string): Promise<void> {
+    const res = await this.request({ type: 'switch_session', sessionPath })
+    if (!res.success) throw new Error(`pi switch_session failed: ${res.error ?? JSON.stringify(res.data)}`)
+  }
+
+  async getMessages(): Promise<unknown> {
+    const res = await this.request({ type: 'get_messages' })
+    if (!res.success) throw new Error(`pi get_messages failed: ${res.error ?? JSON.stringify(res.data)}`)
+    return res.data
+  }
+
+  async getCommands(): Promise<unknown> {
+    const res = await this.request({ type: 'get_commands' })
+    if (!res.success) throw new Error(`pi get_commands failed: ${res.error ?? JSON.stringify(res.data)}`)
+    return res.data
+  }
+
+  async sendExtensionUiResponse(response: PiExtensionUiResponse): Promise<void> {
+    await this.writeLine(`${JSON.stringify({ type: 'extension_ui_response', ...response })}\n`)
+  }
+
+  private request(cmd: PiRpcCommand, opts?: { timeoutMs?: number }): Promise<PiRpcResponse> {
+    const id = crypto.randomUUID()
+    const withId = { ...cmd, id }
+    const timeoutMs = opts?.timeoutMs
+
+    const line = `${JSON.stringify(withId)}\n`
+
+    return new Promise<PiRpcResponse>((resolve, reject) => {
+      let timer: ReturnType<typeof setTimeout> | undefined
+
+      // Returns false when the id was already dropped (e.g. by the timeout), so the
+      // caller can avoid settling the promise twice.
+      const drop = (): boolean => {
+        if (timer !== undefined) {
+          clearTimeout(timer)
+          timer = undefined
+        }
+        return this.pending.delete(id)
+      }
+
+      this.pending.set(id, {
+        resolve: res => {
+          drop()
+          resolve(res)
+        },
+        reject: error => {
+          drop()
+          reject(error)
+        }
+      })
+
+      if (timeoutMs !== undefined) {
+        timer = setTimeout(() => {
+          timer = undefined
+          if (!this.pending.delete(id)) return
+          reject(new Error(`pi ${cmd.type} timed out after ${timeoutMs}ms`))
+        }, timeoutMs)
+        // Never let an auxiliary request keep the event loop alive.
+        timer.unref?.()
+      }
+
+      void this.writeLine(line).catch(error => {
+        if (!drop()) return
+        reject(error)
+      })
+    })
+  }
+
+  private writeLine(line: string): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      try {
+        this.child.stdin.write(line, error => {
+          if (error) {
+            reject(error)
+            return
+          }
+
+          resolve()
+        })
+      } catch (error: unknown) {
+        reject(error)
+      }
+    })
+  }
+}

package/port/oracle/pi-acp/test/component/agent-steering-followup-modes.test.ts

@@ -0,0 +1,143 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { PiAcpAgent } from '../../src/acp/agent.js'
+import { FakeAgentSideConnection, FakePiRpcProcess, asAgentConn } from '../helpers/fakes.js'
+
+class FakeSessions {
+  constructor(private readonly session: any) {}
+  maybeGet(_id: string) {
+    return this.session
+  }
+  get(_id: string) {
+    return this.session
+  }
+}
+
+test('PiAcpAgent: /steering reports current steeringMode', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess() as any
+  proc.getState = async () => ({ steeringMode: 'all' })
+
+  const agent = new PiAcpAgent(asAgentConn(conn))
+  ;(agent as any).sessions = new FakeSessions({ sessionId: 's1', proc }) as any
+
+  const res = await agent.prompt({
+    sessionId: 's1',
+    prompt: [{ type: 'text', text: '/steering' }]
+  } as any)
+
+  assert.equal(res.stopReason, 'end_turn')
+  const last = conn.updates.at(-1)
+  assert.equal(last?.update?.sessionUpdate, 'agent_message_chunk')
+  assert.match((last as any).update.content.text, /Steering mode: all/)
+})
+
+test('PiAcpAgent: /steering sets steering mode', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess() as any
+  let setTo: string | null = null
+  proc.getState = async () => ({ steeringMode: 'all' })
+  proc.setSteeringMode = async (m: string) => {
+    setTo = m
+  }
+
+  const agent = new PiAcpAgent(asAgentConn(conn))
+  ;(agent as any).sessions = new FakeSessions({ sessionId: 's1', proc }) as any
+
+  const res = await agent.prompt({
+    sessionId: 's1',
+    prompt: [{ type: 'text', text: '/steering one-at-a-time' }]
+  } as any)
+
+  assert.equal(res.stopReason, 'end_turn')
+  assert.equal(setTo, 'one-at-a-time')
+  const last = conn.updates.at(-1)
+  assert.match((last as any).update.content.text, /Steering mode set to: one-at-a-time/)
+})
+
+test('PiAcpAgent: /steering rejects invalid value', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess() as any
+  let called = false
+  proc.getState = async () => ({ steeringMode: 'all' })
+  proc.setSteeringMode = async () => {
+    called = true
+  }
+
+  const agent = new PiAcpAgent(asAgentConn(conn))
+  ;(agent as any).sessions = new FakeSessions({ sessionId: 's1', proc }) as any
+
+  const res = await agent.prompt({
+    sessionId: 's1',
+    prompt: [{ type: 'text', text: '/steering nope' }]
+  } as any)
+
+  assert.equal(res.stopReason, 'end_turn')
+  assert.equal(called, false)
+  const last = conn.updates.at(-1)
+  assert.match((last as any).update.content.text, /Usage: \/steering/)
+})
+
+test('PiAcpAgent: /follow-up reports current followUpMode', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess() as any
+  proc.getState = async () => ({ followUpMode: 'one-at-a-time' })
+
+  const agent = new PiAcpAgent(asAgentConn(conn))
+  ;(agent as any).sessions = new FakeSessions({ sessionId: 's1', proc }) as any
+
+  const res = await agent.prompt({
+    sessionId: 's1',
+    prompt: [{ type: 'text', text: '/follow-up' }]
+  } as any)
+
+  assert.equal(res.stopReason, 'end_turn')
+  const last = conn.updates.at(-1)
+  assert.match((last as any).update.content.text, /Follow-up mode: one-at-a-time/)
+})
+
+test('PiAcpAgent: /follow-up sets follow-up mode', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess() as any
+  let setTo: string | null = null
+  proc.getState = async () => ({ followUpMode: 'one-at-a-time' })
+  proc.setFollowUpMode = async (m: string) => {
+    setTo = m
+  }
+
+  const agent = new PiAcpAgent(asAgentConn(conn))
+  ;(agent as any).sessions = new FakeSessions({ sessionId: 's1', proc }) as any
+
+  const res = await agent.prompt({
+    sessionId: 's1',
+    prompt: [{ type: 'text', text: '/follow-up all' }]
+  } as any)
+
+  assert.equal(res.stopReason, 'end_turn')
+  assert.equal(setTo, 'all')
+  const last = conn.updates.at(-1)
+  assert.match((last as any).update.content.text, /Follow-up mode set to: all/)
+})
+
+test('PiAcpAgent: /follow-up rejects invalid value', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess() as any
+  let called = false
+  proc.getState = async () => ({ followUpMode: 'one-at-a-time' })
+  proc.setFollowUpMode = async () => {
+    called = true
+  }
+
+  const agent = new PiAcpAgent(asAgentConn(conn))
+  ;(agent as any).sessions = new FakeSessions({ sessionId: 's1', proc }) as any
+
+  const res = await agent.prompt({
+    sessionId: 's1',
+    prompt: [{ type: 'text', text: '/follow-up ???' }]
+  } as any)
+
+  assert.equal(res.stopReason, 'end_turn')
+  assert.equal(called, false)
+  const last = conn.updates.at(-1)
+  assert.match((last as any).update.content.text, /Usage: \/follow-up/)
+})