@pi-in-go/pigpen-acp 0.1.0

package/port/oracle/pi-acp/test/unit/builtin-commands.test.ts

@@ -0,0 +1,60 @@
+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 is handled adapter-side', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess() as any
+  proc.getState = async () => ({ steeringMode: 'one-at-a-time' })
+
+  const agent = new PiAcpAgent(asAgentConn(conn))
+  ;(agent as any).sessions = new FakeSessions({ sessionId: 's1', proc, fileCommands: [] }) as any
+
+  const res = await agent.prompt({
+    sessionId: 's1',
+    prompt: [{ type: 'text', text: '/steering' }]
+  } as any)
+
+  assert.equal(res.stopReason, 'end_turn')
+  assert.equal(proc.prompts.length, 0)
+  const last = conn.updates.at(-1)
+  assert.match((last as any).update.content.text, /Steering mode: one-at-a-time/)
+})
+
+test('PiAcpAgent: /name sets session display name adapter-side', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess() as any
+
+  let setTo: string | null = null
+  proc.setSessionName = async (name: string) => {
+    setTo = name
+  }
+
+  const agent = new PiAcpAgent(asAgentConn(conn))
+  ;(agent as any).sessions = new FakeSessions({ sessionId: 's1', proc, fileCommands: [] }) as any
+
+  const res = await agent.prompt({
+    sessionId: 's1',
+    prompt: [{ type: 'text', text: '/name My Session' }]
+  } as any)
+
+  assert.equal(res.stopReason, 'end_turn')
+  assert.equal(proc.prompts.length, 0)
+  assert.equal(setTo, 'My Session')
+  const info = conn.updates.find(u => (u as any).update?.sessionUpdate === 'session_info_update')
+  assert.equal((info as any)?.update?.title, 'My Session')
+
+  const last = conn.updates.at(-1)
+  assert.match((last as any).update.content.text, /Session name set: My Session/)
+})

package/port/oracle/pi-acp/test/unit/context-usage.test.ts

@@ -0,0 +1,204 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { PiAcpAgent } from '../../src/acp/agent.js'
+import { PiAcpSession } from '../../src/acp/session.js'
+import { SESSION_STATS_TIMEOUT_MS } from '../../src/pi-rpc/process.js'
+import { FakeAgentSideConnection, FakePiRpcProcess, asAgentConn } from '../helpers/fakes.js'
+
+class FakeSessions {
+  constructor(private readonly session: any) {}
+
+  async create() {
+    return this.session
+  }
+
+  maybeGet(sessionId: string) {
+    if (sessionId !== this.session.sessionId) return undefined
+    return this.session
+  }
+
+  get(sessionId: string) {
+    if (sessionId !== this.session.sessionId) {
+      throw new Error(`Unknown sessionId: ${sessionId}`)
+    }
+    return this.session
+  }
+}
+
+/** Let the `setTimeout(..., 0)` continuations scheduled after session/new or session/load run. */
+async function drainScheduledWork(): Promise<void> {
+  for (let i = 0; i < 5; i += 1) await new Promise(resolve => setTimeout(resolve, 0))
+}
+
+function makeSession(proc: FakePiRpcProcess, conn: FakeAgentSideConnection): PiAcpSession {
+  return new PiAcpSession({
+    sessionId: 's1',
+    cwd: process.cwd(),
+    mcpServers: [],
+    proc: proc as any,
+    conn: asAgentConn(conn),
+    fileCommands: []
+  })
+}
+
+test('PiAcpSession: context usage request specifies the auxiliary timeout', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess()
+  let requestedTimeout: number | undefined
+  proc.getSessionStats = async (timeoutMs?: number) => {
+    requestedTimeout = timeoutMs
+    return { contextUsage: { tokens: 100, contextWindow: 100_000 } }
+  }
+
+  await makeSession(proc, conn).publishContextUsage()
+
+  assert.equal(requestedTimeout, SESSION_STATS_TIMEOUT_MS)
+  assert.deepEqual(conn.updates, [
+    { sessionId: 's1', update: { sessionUpdate: 'usage_update', used: 100, size: 100_000 } }
+  ])
+})
+
+test('PiAcpAgent: newSession publishes context usage only after the response is returned', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess()
+  proc.sessionStats = { contextUsage: { tokens: 1_234, contextWindow: 100_000 } }
+  proc.getState = async () => ({ thinkingLevel: 'medium' })
+  const session = makeSession(proc, conn)
+
+  const agent = new PiAcpAgent(asAgentConn(conn), {} as any)
+  ;(agent as any).sessions = new FakeSessions(session) as any
+
+  const result = await agent.newSession({ cwd: process.cwd(), mcpServers: [] } as any)
+  assert.equal(result.sessionId, 's1')
+  assert.equal(
+    conn.updates.some(u => u.update.sessionUpdate === 'usage_update'),
+    false
+  )
+
+  await drainScheduledWork()
+
+  assert.deepEqual(
+    conn.updates.filter(u => u.update.sessionUpdate === 'usage_update'),
+    [{ sessionId: 's1', update: { sessionUpdate: 'usage_update', used: 1_234, size: 100_000 } }]
+  )
+})
+
+test('PiAcpAgent: newSession tolerates a failing get_session_stats', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess()
+  proc.sessionStatsError = new Error('pi get_session_stats failed: unsupported')
+  proc.getState = async () => ({ thinkingLevel: 'medium' })
+  const session = makeSession(proc, conn)
+
+  const agent = new PiAcpAgent(asAgentConn(conn), {} as any)
+  ;(agent as any).sessions = new FakeSessions(session) as any
+
+  const result = await agent.newSession({ cwd: process.cwd(), mcpServers: [] } as any)
+  assert.equal(result.sessionId, 's1')
+
+  await drainScheduledWork()
+
+  assert.equal(
+    conn.updates.some(u => u.update.sessionUpdate === 'usage_update'),
+    false
+  )
+})
+
+test('PiAcpAgent: switching the model config option refreshes context usage', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess()
+  const state: { thinkingLevel: string; model: { provider: string; id: string } } = {
+    thinkingLevel: 'medium',
+    model: { provider: 'test', id: 'alpha' }
+  }
+  proc.getAvailableModels = async () => ({
+    models: [
+      { provider: 'test', id: 'alpha', name: 'Alpha' },
+      { provider: 'test', id: 'beta', name: 'Beta' }
+    ]
+  })
+  proc.getState = async () => state
+  ;(proc as any).setModel = async (provider: string, modelId: string) => {
+    state.model = { provider, id: modelId }
+    proc.sessionStats = { contextUsage: { tokens: 500, contextWindow: modelId === 'beta' ? 200_000 : 100_000 } }
+  }
+  proc.sessionStats = { contextUsage: { tokens: 500, contextWindow: 100_000 } }
+
+  const session = makeSession(proc, conn)
+  const agent = new PiAcpAgent(asAgentConn(conn), {} as any)
+  ;(agent as any).sessions = new FakeSessions(session) as any
+
+  await agent.setSessionConfigOption({ sessionId: 's1', configId: 'model', value: 'test/beta' } as any)
+
+  assert.deepEqual(
+    conn.updates.map(u => u.update.sessionUpdate),
+    ['current_mode_update', 'config_option_update', 'usage_update']
+  )
+  assert.deepEqual(conn.updates.at(-1), {
+    sessionId: 's1',
+    update: { sessionUpdate: 'usage_update', used: 500, size: 200_000 }
+  })
+})
+
+test('PiAcpAgent: unstable_setSessionModel refreshes context usage', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess()
+  const state: { thinkingLevel: string; model: { provider: string; id: string } } = {
+    thinkingLevel: 'medium',
+    model: { provider: 'test', id: 'alpha' }
+  }
+  proc.getAvailableModels = async () => ({
+    models: [
+      { provider: 'test', id: 'alpha', name: 'Alpha' },
+      { provider: 'test', id: 'beta', name: 'Beta' }
+    ]
+  })
+  proc.getState = async () => state
+  ;(proc as any).setModel = async (provider: string, modelId: string) => {
+    state.model = { provider, id: modelId }
+    proc.sessionStats = { contextUsage: { tokens: 700, contextWindow: modelId === 'beta' ? 200_000 : 100_000 } }
+  }
+  proc.sessionStats = { contextUsage: { tokens: 700, contextWindow: 100_000 } }
+
+  const session = makeSession(proc, conn)
+  const agent = new PiAcpAgent(asAgentConn(conn), {} as any)
+  ;(agent as any).sessions = new FakeSessions(session) as any
+
+  await agent.unstable_setSessionModel({ sessionId: 's1', modelId: 'test/beta' })
+
+  assert.equal(proc.getSessionStatsCount, 1)
+  assert.deepEqual(
+    conn.updates.map(u => u.update.sessionUpdate),
+    ['current_mode_update', 'config_option_update', 'usage_update']
+  )
+  assert.deepEqual(conn.updates.at(-1), {
+    sessionId: 's1',
+    update: { sessionUpdate: 'usage_update', used: 700, size: 200_000 }
+  })
+})
+
+test('PiAcpAgent: switching the thinking level does not publish context usage', async () => {
+  const conn = new FakeAgentSideConnection()
+  const proc = new FakePiRpcProcess()
+  const state: { thinkingLevel: string; model: { provider: string; id: string } } = {
+    thinkingLevel: 'medium',
+    model: { provider: 'test', id: 'alpha' }
+  }
+  proc.getState = async () => state
+  ;(proc as any).setThinkingLevel = async (level: string) => {
+    state.thinkingLevel = level
+  }
+  proc.sessionStats = { contextUsage: { tokens: 500, contextWindow: 100_000 } }
+
+  const session = makeSession(proc, conn)
+  const agent = new PiAcpAgent(asAgentConn(conn), {} as any)
+  ;(agent as any).sessions = new FakeSessions(session) as any
+
+  await agent.setSessionConfigOption({ sessionId: 's1', configId: 'thought_level', value: 'high' } as any)
+
+  assert.equal(proc.getSessionStatsCount, 0)
+  assert.equal(
+    conn.updates.some(u => u.update.sessionUpdate === 'usage_update'),
+    false
+  )
+})

package/port/oracle/pi-acp/test/unit/merge-commands.test.ts

@@ -0,0 +1,19 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+// Minimal local impl (mirrors src/acp/agent.ts behavior)
+function mergeCommands(a: Array<{ name: string }>, b: Array<{ name: string }>) {
+  const out: Array<{ name: string }> = []
+  const seen = new Set<string>()
+  for (const c of [...a, ...b]) {
+    if (seen.has(c.name)) continue
+    seen.add(c.name)
+    out.push(c)
+  }
+  return out
+}
+
+test('mergeCommands: preserves order and de-dupes (first wins)', () => {
+  const res = mergeCommands([{ name: 'a' }, { name: 'b' }], [{ name: 'b' }, { name: 'c' }])
+  assert.deepEqual(res, [{ name: 'a' }, { name: 'b' }, { name: 'c' }])
+})

package/port/oracle/pi-acp/test/unit/model-thinking-levels.test.ts

@@ -0,0 +1,268 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { SessionManager } from '../../src/acp/session.js'
+import { SessionStore } from '../../src/acp/session-store.js'
+import { PiAcpAgent } from '../../src/acp/agent.js'
+import { PiRpcProcess } from '../../src/pi-rpc/process.js'
+import { FakeAgentSideConnection, asAgentConn } from '../helpers/fakes.js'
+
+function fixture() {
+  const conn = new FakeAgentSideConnection()
+  const state = { thinkingLevel: 'max', model: { provider: 'test', id: 'reasoning' } }
+  const calls: string[] = []
+  const proc = {
+    onEvent: () => () => {},
+    getMessages: async () => ({ messages: [] }),
+    getState: async () => state,
+    getAvailableModels: async () => ({
+      models: [
+        { provider: 'test', id: 'reasoning' },
+        { provider: 'test', id: 'plain' }
+      ]
+    }),
+    getAvailableThinkingLevels: async () => (state.model.id === 'plain' ? ['off'] : ['low', 'high', 'max']),
+    async setThinkingLevel(level: string) {
+      calls.push(level)
+      state.thinkingLevel = 'max'
+    },
+    async setModel(provider: string, id: string) {
+      calls.push(id)
+      state.model = { provider, id }
+      state.thinkingLevel = id === 'plain' ? 'off' : 'max'
+    }
+  }
+  const session = {
+    sessionId: 's1',
+    cwd: process.cwd(),
+    proc,
+    setStartupInfo() {},
+    sendStartupInfoIfPending() {},
+    async publishContextUsage() {}
+  }
+  const agent = new PiAcpAgent(asAgentConn(conn))
+  Reflect.set(agent, 'sessions', {
+    maybeGet: () => session,
+    get: () => session,
+    create: async () => session,
+    close() {}
+  })
+  return { agent, conn, proc, state, calls }
+}
+
+function assertUpdates(conn: FakeAgentSideConnection, level: string, levels: string[]) {
+  assert.equal(conn.updates.length, 2)
+  assert.deepEqual(conn.updates[0], {
+    sessionId: 's1',
+    update: { sessionUpdate: 'current_mode_update', currentModeId: level }
+  })
+  const update = conn.updates[1].update as {
+    configOptions: Array<{ id: string; currentValue: string; options: Array<{ value: string }> }>
+  }
+  const option = update.configOptions.find(option => option.id === 'thought_level')!
+  assert.equal(option.currentValue, level)
+  assert.deepEqual(
+    option.options.map(option => option.value),
+    levels
+  )
+}
+
+for (const legacy of [false, true]) {
+  for (const requested of ['max', 'xhigh', 'ordinary', ' mean ', ' ']) {
+    test(`${legacy ? 'legacy' : 'config'} reasoning setter reports actual max for ${requested}`, async () => {
+      const { agent, conn, calls } = fixture()
+      if (legacy) await agent.setSessionMode({ sessionId: 's1', modeId: requested })
+      else {
+        const result = await agent.setSessionConfigOption({
+          sessionId: 's1',
+          configId: 'thought_level',
+          value: requested
+        })
+        assert.equal(result.configOptions.find(option => option.id === 'thought_level')?.currentValue, 'max')
+      }
+      assert.deepEqual(calls, [requested])
+      assertUpdates(conn, 'max', ['low', 'high', 'max'])
+    })
+  }
+  test(`${legacy ? 'legacy' : 'config'} reasoning setter reports an opaque applied level`, async () => {
+    const { agent, conn, proc, state, calls } = fixture()
+    proc.getAvailableThinkingLevels = async () => ['ordinary', 'mean']
+    proc.setThinkingLevel = async level => {
+      calls.push(level)
+      state.thinkingLevel = 'mean'
+    }
+    if (legacy) await agent.setSessionMode({ sessionId: 's1', modeId: 'ordinary' })
+    else {
+      const result = await agent.setSessionConfigOption({
+        sessionId: 's1',
+        configId: 'thought_level',
+        value: 'ordinary'
+      })
+      assert.equal(result.configOptions.find(option => option.id === 'thought_level')?.currentValue, 'mean')
+    }
+    assert.deepEqual(calls, ['ordinary'])
+    assertUpdates(conn, 'mean', ['ordinary', 'mean'])
+  })
+  test(`${legacy ? 'legacy' : 'config'} model setter refreshes model-specific levels and current mode`, async () => {
+    const { agent, conn } = fixture()
+    for (const model of ['plain', 'reasoning']) {
+      conn.updates.length = 0
+      if (legacy) await agent.unstable_setSessionModel({ sessionId: 's1', modelId: `test/${model}` })
+      else await agent.setSessionConfigOption({ sessionId: 's1', configId: 'model', value: `test/${model}` })
+      assertUpdates(conn, model === 'plain' ? 'off' : 'max', model === 'plain' ? ['off'] : ['low', 'high', 'max'])
+    }
+  })
+  for (const failure of ['state', 'discovery', 'empty', 'non-string', 'inconsistent']) {
+    test(`${legacy ? 'legacy' : 'config'} reasoning setter emits no success on ${failure} read failure`, async () => {
+      const { agent, conn, proc, state } = fixture()
+      if (failure === 'state')
+        proc.getState = async () => {
+          throw new Error('state failed')
+        }
+      if (failure === 'discovery')
+        proc.getAvailableThinkingLevels = async () => {
+          throw new Error('discovery failed')
+        }
+      if (failure === 'empty' || failure === 'non-string' || failure === 'inconsistent')
+        proc.setThinkingLevel = async () => {
+          Reflect.set(state, 'thinkingLevel', failure === 'empty' ? '' : failure === 'non-string' ? 1 : 'medium')
+        }
+      await assert.rejects(
+        legacy
+          ? agent.setSessionMode({ sessionId: 's1', modeId: 'max' })
+          : agent.setSessionConfigOption({ sessionId: 's1', configId: 'thought_level', value: 'max' })
+      )
+      assert.deepEqual(conn.updates, [])
+    })
+  }
+}
+
+test('invalid configuration and legacy mode requests do not mutate Pi', async () => {
+  const { agent, calls, conn } = fixture()
+  for (const request of [
+    { configId: 'thought_level', value: '' },
+    { configId: 'unknown', value: 'high' },
+    { configId: 'thought_level', value: 1 }
+  ]) {
+    await assert.rejects(
+      agent.setSessionConfigOption({ sessionId: 's1', ...request } as Parameters<
+        PiAcpAgent['setSessionConfigOption']
+      >[0]),
+      { code: -32602 }
+    )
+  }
+  for (const modeId of ['', 1, null]) {
+    await assert.rejects(
+      agent.setSessionMode({ sessionId: 's1', modeId } as Parameters<PiAcpAgent['setSessionMode']>[0]),
+      { code: -32602 }
+    )
+  }
+  assert.deepEqual(calls, [])
+  assert.deepEqual(conn.updates, [])
+})
+
+for (const load of [false, true]) {
+  for (const levels of [['off'], ['low', 'high', 'max'], ['ordinary', 'mean']]) {
+    test(`${load ? 'load' : 'new'} session advertises exact ${levels} levels`, async t => {
+      const { agent, proc, state } = fixture()
+      state.thinkingLevel = levels[levels.length - 1]
+      proc.getAvailableThinkingLevels = async () => levels
+      t.mock.method(globalThis, 'setTimeout', () => 0 as unknown as ReturnType<typeof setTimeout>)
+      t.mock.method(PiRpcProcess, 'spawn', async () => proc as unknown as PiRpcProcess)
+      Reflect.set(agent, 'store', {
+        get: () => ({ cwd: process.cwd(), sessionFile: '/tmp/thinking-test.jsonl' }),
+        upsert() {},
+        delete() {}
+      })
+      const result = load
+        ? await agent.loadSession({ sessionId: 's1', cwd: process.cwd(), mcpServers: [] })
+        : await agent.newSession({ cwd: process.cwd(), mcpServers: [] })
+      assert.equal(result.modes?.currentModeId, state.thinkingLevel)
+      assert.deepEqual(
+        result.modes?.availableModes.map(mode => mode.id),
+        levels
+      )
+      const option = result.configOptions?.find(option => option.id === 'thought_level')
+      assert.equal(option?.currentValue, state.thinkingLevel)
+      assert.deepEqual(
+        option?.options.map(option => ('value' in option ? option.value : undefined)),
+        levels
+      )
+    })
+  }
+}
+
+for (const failure of ['discovery', 'missing-current', 'inconsistent-current', 'state']) {
+  test(`load configuration ${failure} failure closes restored child and preserves history for retry`, async t => {
+    const root = mkdtempSync(join(tmpdir(), 'pi-acp-load-thinking-'))
+    t.after(() => rmSync(root, { recursive: true, force: true }))
+    t.mock.method(globalThis, 'setTimeout', () => 0 as unknown as ReturnType<typeof setTimeout>)
+    const sessionFile = join(root, 'history.jsonl')
+    writeFileSync(sessionFile, 'persisted history\n')
+    const store = new SessionStore(join(root, 'map.json'))
+    store.upsert({ sessionId: 's1', cwd: root, sessionFile })
+    const { agent, conn, proc } = fixture()
+    const sessions = new SessionManager()
+    Reflect.set(agent, 'sessions', sessions)
+    Reflect.set(agent, 'store', store)
+    let existingDisposed = 0
+    let restoredDisposed = 0
+    let historyReads = 0
+    let shouldFail = true
+    let spawns = 0
+    sessions.getOrCreate('existing', {
+      cwd: root,
+      mcpServers: [],
+      conn: asAgentConn(conn),
+      proc: {
+        onEvent: () => () => {},
+        dispose() {
+          existingDisposed++
+        }
+      } as unknown as PiRpcProcess
+    })
+    t.after(() => sessions.disposeAll())
+    t.mock.method(PiRpcProcess, 'spawn', async () => {
+      spawns++
+      return {
+        ...proc,
+        dispose() {
+          restoredDisposed++
+        },
+        async getState() {
+          if (shouldFail && failure === 'state') throw new Error('state unavailable')
+          if (shouldFail && failure === 'missing-current') return {}
+          if (shouldFail && failure === 'inconsistent-current') return { thinkingLevel: 'medium' }
+          return proc.getState()
+        },
+        async getAvailableThinkingLevels() {
+          if (shouldFail && failure === 'discovery') throw new Error('discovery unavailable')
+          return proc.getAvailableThinkingLevels()
+        },
+        async getMessages() {
+          historyReads++
+          return { messages: [{ role: 'user', content: 'persisted prompt' }] }
+        }
+      } as unknown as PiRpcProcess
+    })
+    await assert.rejects(agent.loadSession({ sessionId: 's1', cwd: root, mcpServers: [] }))
+    assert.equal(restoredDisposed, 1)
+    assert.equal(sessions.maybeGet('s1'), undefined)
+    assert.ok(sessions.maybeGet('existing'))
+    assert.equal(existingDisposed, 0)
+    assert.equal(historyReads, 0)
+    assert.equal(conn.updates.length, 0)
+    assert.equal(readFileSync(sessionFile, 'utf8'), 'persisted history\n')
+    assert.equal(store.get('s1')?.sessionFile, sessionFile)
+    shouldFail = false
+    const result = await agent.loadSession({ sessionId: 's1', cwd: root, mcpServers: [] })
+    assert.equal(result.modes?.currentModeId, 'max')
+    assert.equal(spawns, 2)
+    assert.equal(restoredDisposed, 1)
+    assert.equal(historyReads, 1)
+    assert.ok(conn.updates.some(update => update.update.sessionUpdate === 'user_message_chunk'))
+    assert.equal(readFileSync(sessionFile, 'utf8'), 'persisted history\n')
+  })
+}

package/port/oracle/pi-acp/test/unit/new-session-auth-required-when-no-models.test.ts

@@ -0,0 +1,51 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { PiAcpAgent } from '../../src/acp/agent.js'
+import { FakeAgentSideConnection, asAgentConn } from '../helpers/fakes.js'
+
+class FakeSessions {
+  closeCalls: string[] = []
+
+  constructor(private readonly session: any) {}
+
+  async create(_params: any) {
+    return this.session
+  }
+
+  close(sessionId: string) {
+    this.closeCalls.push(sessionId)
+  }
+}
+
+test('PiAcpAgent: newSession throws AUTH_REQUIRED when pi reports zero available models', async () => {
+  const conn = new FakeAgentSideConnection()
+
+  const session = {
+    sessionId: 's1',
+    cwd: process.cwd(),
+    proc: {
+      async getAvailableModels() {
+        return { models: [] }
+      },
+      async getState() {
+        return { thinkingLevel: 'medium', model: null }
+      }
+    }
+  }
+
+  const sessions = new FakeSessions(session)
+  const agent = new PiAcpAgent(asAgentConn(conn), {} as any)
+  ;(agent as any).sessions = sessions as any
+
+  let threw = false
+  try {
+    await agent.newSession({ cwd: process.cwd(), mcpServers: [] } as any)
+  } catch (e: any) {
+    threw = true
+    assert.equal(e?.code, -32000)
+    assert.match(String(e?.message), /Configure an API key or log in with an OAuth provider/i)
+  }
+
+  assert.equal(threw, true)
+  assert.deepEqual(sessions.closeCalls, ['s1'])
+})

package/port/oracle/pi-acp/test/unit/new-session-pi-not-found.test.ts

@@ -0,0 +1,26 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { PiAcpAgent } from '../../src/acp/agent.js'
+import { FakeAgentSideConnection, asAgentConn } from '../helpers/fakes.js'
+
+test('PiAcpAgent: newSession returns a helpful Internal error when pi is not installed', async () => {
+  const prevPiCmd = process.env.PI_ACP_PI_COMMAND
+  process.env.PI_ACP_PI_COMMAND = 'pi-does-not-exist-12345'
+
+  try {
+    const conn = new FakeAgentSideConnection()
+    const agent = new PiAcpAgent(asAgentConn(conn), {} as any)
+
+    await assert.rejects(
+      () => agent.newSession({ cwd: process.cwd(), mcpServers: [] } as any),
+      (e: any) =>
+        e?.code === -32603 &&
+        String(e?.message ?? '')
+          .toLowerCase()
+          .includes('executable not found')
+    )
+  } finally {
+    if (prevPiCmd == null) delete process.env.PI_ACP_PI_COMMAND
+    else process.env.PI_ACP_PI_COMMAND = prevPiCmd
+  }
+})