Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript
21.3 KB
Raw Blame
/** Contract tests for the BYOA Maka (`maka --acp`) ACP adapter. */
import assert from 'node:assert/strict'
import { chmod, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, test } from 'node:test'
import { getAdapter, resolveMakaBin, type EngineHopReport } from '../agents/computer/engine.js'

const tempDirs: string[] = []
const liveSessions: Array<{ stop(): void | Promise<void> }> = []

const FAKE_MAKA_ACP_SOURCE = String.raw`
import { appendFileSync } from 'node:fs'
import { createInterface } from 'node:readline'

const logFile = process.env.FAKE_MAKA_LOG
const mode = process.env.FAKE_MAKA_MODE || 'ok'
const argv = process.argv.slice(2)
if (argv.length !== 1 || argv[0] !== '--acp') {
  process.stderr.write('maka --acp does not accept extra arguments\n')
  process.exit(2)
}

let prompts = 0
let permissionReply = null
let pendingPrompt = null
const send = (obj) => process.stdout.write(JSON.stringify(obj) + '\n')
const record = (entry) => {
  if (logFile) appendFileSync(logFile, JSON.stringify(entry) + '\n')
}
const finishPrompt = (id, sid) => {
  send({
    jsonrpc: '2.0',
    method: 'session/update',
    params: { sessionId: sid, update: { sessionUpdate: 'tool_call', toolCallId: 'tc-1', title: 'Read README.md' } },
  })
  send({
    jsonrpc: '2.0',
    method: 'session/update',
    params: {
      sessionId: sid,
      update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'pong #' + prompts } },
    },
  })
  send({
    jsonrpc: '2.0',
    id,
    result: mode === 'with-usage'
      ? {
          stopReason: 'end_turn',
          usage: { inputTokens: 110, cachedReadTokens: 30, cachedWriteTokens: 10, outputTokens: 15 },
        }
      : {
          stopReason: 'end_turn',
        },
  })
}

const rl = createInterface({ input: process.stdin })
rl.on('line', (line) => {
  const msg = JSON.parse(line)
  record(msg)
  if (msg.id !== undefined && !msg.method) {
    permissionReply = msg.result
    if (pendingPrompt) {
      const { id, sid } = pendingPrompt
      pendingPrompt = null
      finishPrompt(id, sid)
    }
    return
  }
  if (msg.method === 'initialize') {
    send({ jsonrpc: '2.0', id: msg.id, result: { protocolVersion: 1, agentCapabilities: { loadSession: true } } })
  } else if (msg.method === 'session/new') {
    send({ jsonrpc: '2.0', id: msg.id, result: { sessionId: 'maka-sess-fresh', configOptions: [] } })
  } else if (msg.method === 'session/resume' || msg.method === 'session/load') {
    if (mode === 'fail-load') {
      send({ jsonrpc: '2.0', id: msg.id, error: { code: -32603, message: 'Runtime Host Session was not found.' } })
    } else {
      if (mode === 'replay-on-load') {
        send({
          jsonrpc: '2.0',
          method: 'session/update',
          params: {
            sessionId: msg.params.sessionId,
            update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'STALE_REPLAY_TEXT ' } },
          },
        })
      }
      send({ jsonrpc: '2.0', id: msg.id, result: { sessionId: msg.params.sessionId, configOptions: [] } })
    }
  } else if (msg.method === 'session/set_config_option') {
    if (mode === 'reject-ask' && msg.params?.value === 'ask') {
      send({ jsonrpc: '2.0', id: msg.id, error: { code: -32602, message: 'permission mode is unavailable' } })
    } else if (msg.params?.configId !== 'permission_mode' || !['ask', 'bypass'].includes(msg.params?.value)) {
      send({ jsonrpc: '2.0', id: msg.id, error: { code: -32602, message: 'Invalid params: Invalid Session configuration option' } })
    } else {
      send({ jsonrpc: '2.0', id: msg.id, result: { configOptions: [] } })
    }
  } else if (msg.method === 'session/prompt') {
    prompts += 1
    if (mode === 'session-gone-after-first' && prompts >= 2) {
      // The turn began without a resume, so the resumed flag is already false.
      send({ jsonrpc: '2.0', id: msg.id, error: { code: -32603, message: 'Session is not owned by this ACP connection' } })
      return
    }
    if (mode === 'die-mid-turn') {
      process.exit(17)
    }
    if (mode === 'session-gone') {
      send({ jsonrpc: '2.0', id: msg.id, error: { code: -32603, message: 'Session is not owned by this ACP connection' } })
      return
    }
    if (mode === 'cwd-mismatch') {
      send({ jsonrpc: '2.0', id: msg.id, error: { code: -32602, message: 'cwd does not match the existing session workspace' } })
      return
    }
    if (mode === 'cancelled') {
      send({
        jsonrpc: '2.0',
        id: msg.id,
        result: { stopReason: 'cancelled' },
      })
      return
    }
    if (mode === 'ask-permission') {
      pendingPrompt = { id: msg.id, sid: msg.params.sessionId }
      // Deliberately reuse the pending prompt's own id: a server->client request
      // must be routed by method, never by id, or it would be delivered as the
      // prompt's response.
      send({
        jsonrpc: '2.0',
        id: msg.id,
        method: 'session/request_permission',
        params: {
          sessionId: msg.params.sessionId,
          toolCall: { toolCallId: 'tc-perm', title: 'Write file' },
          options: [
            { optionId: '550e8400-e29b-41d4-a716-446655440001', name: 'Allow once', kind: 'allow_once' },
            { optionId: '550e8400-e29b-41d4-a716-446655440002', name: 'Always allow', kind: 'allow_always' },
            { optionId: '550e8400-e29b-41d4-a716-446655440003', name: 'Reject', kind: 'reject_once' },
          ],
        },
      })
      return
    }
    if (mode === 'ask-permission-reject-only') {
      pendingPrompt = { id: msg.id, sid: msg.params.sessionId }
      send({
        jsonrpc: '2.0',
        id: msg.id,
        method: 'session/request_permission',
        params: {
          sessionId: msg.params.sessionId,
          toolCall: { toolCallId: 'tc-perm', title: 'Write file' },
          options: [
            { optionId: '550e8400-e29b-41d4-a716-446655440003', name: 'Reject', kind: 'reject_once' },
          ],
        },
      })
      return
    }
    const sid = msg.params.sessionId
    if (mode === 'split-utf8') {
      const updateFrame = Buffer.from(
        JSON.stringify({
          jsonrpc: '2.0',
          method: 'session/update',
          params: {
            sessionId: sid,
            update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: '你好世界' } },
          },
        }) + '\n',
        'utf8',
      )
      // '你' in UTF-8 is 0xe4 0xbd 0xa0 — split right after the first byte (0xe4)
      const splitIndex = updateFrame.indexOf(0xe4) + 1
      process.stdout.write(updateFrame.subarray(0, splitIndex))
      setTimeout(() => {
        process.stdout.write(updateFrame.subarray(splitIndex))
        send({
          jsonrpc: '2.0',
          id: msg.id,
          result: { stopReason: 'end_turn' },
        })
      }, 15)
      return
    }
    finishPrompt(msg.id, sid)
  }
})
`

async function makeFixture(mode = 'ok'): Promise<{
  home: string
  env: NodeJS.ProcessEnv
  readCalls: () => Promise<Array<{ id?: number; method?: string; params?: Record<string, unknown>; result?: Record<string, unknown> }>>
}> {
  const root = await mkdtemp(join(tmpdir(), 'cumora-maka-'))
  tempDirs.push(root)
  const home = join(root, 'home')
  await mkdir(home, { recursive: true })
  const bridge = join(root, 'fake-maka.mjs')
  const logFile = join(root, 'calls.jsonl')
  await writeFile(bridge, FAKE_MAKA_ACP_SOURCE, 'utf8')
  return {
    home,
    env: {
      ...process.env,
      CUMORA_MAKA_BIN: bridge,
      FAKE_MAKA_LOG: logFile,
      FAKE_MAKA_MODE: mode,
    },
    readCalls: async () => {
      const raw = await readFile(logFile, 'utf8').catch(() => '')
      return raw.trim().split('\n').filter(Boolean).map((l) => JSON.parse(l))
    },
  }
}

afterEach(async () => {
  for (const s of liveSessions.splice(0)) {
    try { await s.stop() } catch { /* already gone */ }
  }
  await Promise.all(tempDirs.splice(0).map((d) => rm(d, { recursive: true, force: true })))
})

test('maka persistent session pins permission_mode=bypass once across wakes and ignores model pin', async () => {
  const f = await makeFixture()
  const logs: string[] = []
  const hops: EngineHopReport[] = []
  const session = getAdapter('maka').startSession?.({
    home: f.home,
    env: f.env,
    model: 'claude-sonnet-4-6',
    standingPrompt: null,
    resumeSessionId: null,
    onLog: (l) => logs.push(l),
    onHopUsage: (h) => hops.push(h),
  })
  assert.ok(session)
  liveSessions.push(session)

  const r1 = await session.send('first wake')
  const r2 = await session.send('second wake')

  assert.equal(r1.exitCode, 0)
  assert.equal(r2.exitCode, 0)
  assert.equal(r1.sessionId, 'maka-sess-fresh')
  assert.equal(r2.sessionId, 'maka-sess-fresh')
  assert.equal(r1.model, '<maka-default>')
  assert.equal(r1.usage, undefined)
  assert.equal(hops.length, 2)
  assert.equal(hops[0]?.model, '<maka-default>')
  assert.equal(hops[0]?.usage, undefined)
  assert.equal(
    logs.filter((l) => l.includes('[maka] model pin (claude-sonnet-4-6) is ignored')).length,
    1,
  )
  assert.ok(logs.some((l) => l.includes('[maka] tool Read README.md')))
  assert.ok(logs.some((l) => l.includes('pong #1')))
  assert.ok(logs.some((l) => l.includes('pong #2')))

  const calls = await f.readCalls()
  assert.deepEqual(
    calls.map((c) => c.method),
    [
      'initialize',
      'session/new',
      'session/set_config_option',
      'session/prompt',
      'session/prompt',
    ],
  )
  assert.deepEqual(calls[2]?.params, {
    sessionId: 'maka-sess-fresh',
    configId: 'permission_mode',
    value: 'bypass',
  })
  assert.equal(
    calls.some((c) => c.method === 'session/set_config_option' && c.params?.configId === 'model'),
    false,
  )
})

test('maka uses session/resume when resumeSessionId is supplied and ignores non-turn session/update notifications', async () => {
  const f = await makeFixture('replay-on-load')
  const logs: string[] = []
  const session = getAdapter('maka').startSession?.({
    home: f.home,
    env: f.env,
    standingPrompt: null,
    resumeSessionId: 'maka-sess-existing',
    onLog: (l) => logs.push(l),
  })
  assert.ok(session)
  liveSessions.push(session)

  const r = await session.send('wake after resume')
  assert.equal(r.exitCode, 0)
  assert.equal(r.sessionId, 'maka-sess-existing')
  assert.ok(!logs.some((l) => l.includes('STALE_REPLAY_TEXT')), 'non-turn chunks must not leak into new turn logs')
  assert.ok(logs.some((l) => l.includes('pong #1')))

  const calls = await f.readCalls()
  assert.deepEqual(calls.slice(0, 2).map((c) => c.method), ['initialize', 'session/resume'])
})

test('maka still recovers when the session disappears after a successful turn', async () => {
  const f = await makeFixture('session-gone-after-first')
  const session = getAdapter('maka').startSession?.({
    home: f.home,
    env: f.env,
    standingPrompt: null,
    resumeSessionId: 'maka-sess-existing',
    onLog: () => {},
  })
  assert.ok(session)
  liveSessions.push(session)

  // The first turn succeeds, which clears `resumed` on the connection.
  const first = await session.send('first turn')
  assert.equal(first.exitCode, 0)

  // The backend loses the session afterwards. Without classifying Maka's own
  // wording independently of `resumed`, this reads as an unknown error and
  // recovery never happens.
  const second = await session.send('second turn')
  assert.equal(second.failure?.kind, 'resume-not-found')
})

test('maka auto-answers server-initiated session/request_permission requests and cancels when no allow option exists', async () => {
  const f = await makeFixture('ask-permission')
  const session = getAdapter('maka').startSession?.({
    home: f.home,
    env: f.env,
    standingPrompt: null,
    resumeSessionId: null,
    onLog: () => {},
  })
  assert.ok(session)
  liveSessions.push(session)

  const r = await session.send('do something requiring permission')
  assert.equal(r.exitCode, 0)

  const calls = await f.readCalls()
  const promptCall = calls.find((c) => c.method === 'session/prompt')
  const reply = calls.find((c) => c.id === promptCall?.id && !c.method)
  // Same id as the outstanding prompt: routing by id would have been wrong.
  assert.equal(reply?.id, promptCall?.id)
  assert.deepEqual(reply?.result, {
    outcome: { outcome: 'selected', optionId: '550e8400-e29b-41d4-a716-446655440002' },
  })

  const fRejectOnly = await makeFixture('ask-permission-reject-only')
  const sessionRejectOnly = getAdapter('maka').startSession?.({
    home: fRejectOnly.home,
    env: fRejectOnly.env,
    standingPrompt: null,
    resumeSessionId: null,
    onLog: () => {},
  })
  assert.ok(sessionRejectOnly)
  liveSessions.push(sessionRejectOnly)

  const r2 = await sessionRejectOnly.send('permission options lack allow')
  assert.equal(r2.exitCode, 0)

  const callsRejectOnly = await fRejectOnly.readCalls()
  const promptCallRejectOnly = callsRejectOnly.find((c) => c.method === 'session/prompt')
  const replyRejectOnly = callsRejectOnly.find((c) => c.id === promptCallRejectOnly?.id && !c.method)
  assert.equal(replyRejectOnly?.id, promptCallRejectOnly?.id)
  assert.deepEqual(replyRejectOnly?.result, {
    outcome: { outcome: 'cancelled' },
  })
})

test('maka treats stopReason=cancelled as a failed turn instead of success', async () => {
  const f = await makeFixture('cancelled')
  const hops: EngineHopReport[] = []
  const session = getAdapter('maka').startSession?.({
    home: f.home,
    env: f.env,
    standingPrompt: null,
    resumeSessionId: null,
    onLog: () => {},
    onHopUsage: (h) => hops.push(h),
  })
  assert.ok(session)
  liveSessions.push(session)

  const r = await session.send('fail with cancelled stopReason')
  assert.equal(r.exitCode, 1)
  assert.match(r.error ?? '', /cancelled/i)
  assert.equal(hops.length, 0)
})

test('maka self-heals a stale resume at handshake time via session/resume -> session/new and reports a fresh session', async () => {
  const f = await makeFixture('fail-load')
  const logs: string[] = []
  const session = getAdapter('maka').startSession?.({
    home: f.home,
    env: f.env,
    standingPrompt: null,
    resumeSessionId: 'maka-sess-stale',
    onLog: (l) => logs.push(l),
  })
  assert.ok(session)
  liveSessions.push(session)

  const r = await session.send('after stale resume')
  assert.equal(r.exitCode, 0)
  assert.equal(r.sessionId, 'maka-sess-fresh')
  assert.ok(logs.some((l) => l.includes('session/resume failed') && l.includes('fresh session')))

  const calls = await f.readCalls()
  assert.deepEqual(calls.slice(0, 3).map((c) => c.method), ['initialize', 'session/resume', 'session/new'])
})

test('maka maps mid-life missing or cwd-mismatched Runtime Host sessions to resume-not-found', async () => {
  const f = await makeFixture('session-gone')
  const session = getAdapter('maka').startSession?.({
    home: f.home,
    env: f.env,
    standingPrompt: null,
    resumeSessionId: 'maka-sess-stale',
    onLog: () => {},
  })
  assert.ok(session)
  liveSessions.push(session)

  const r = await session.send('turn on dead backend session')
  assert.equal(r.exitCode, 1)
  assert.equal(r.failure?.kind, 'resume-not-found')

  const fCwd = await makeFixture('cwd-mismatch')
  const sessionCwd = getAdapter('maka').startSession?.({
    home: fCwd.home,
    env: fCwd.env,
    standingPrompt: null,
    resumeSessionId: 'maka-sess-cwd',
    onLog: () => {},
  })
  assert.ok(sessionCwd)
  liveSessions.push(sessionCwd)

  const rCwd = await sessionCwd.send('turn on mismatched workspace')
  assert.equal(rCwd.exitCode, 1)
  assert.equal(rCwd.failure?.kind, 'resume-not-found')
})

test('maka process dying MID-TURN resolves the turn as a failure, never rejects', async () => {
  const f = await makeFixture('die-mid-turn')
  const session = getAdapter('maka').startSession?.({
    home: f.home,
    env: f.env,
    standingPrompt: null,
    resumeSessionId: null,
    onLog: () => {},
  })
  assert.ok(session)
  liveSessions.push(session)

  const r = await session.send('crash now')
  assert.equal(r.exitCode, 17)
  assert.match(r.error ?? '', /exited with code 17/)
  assert.equal(session.alive, false)
})

test('maka seedHome writes AGENTS.md and .agents/skills, and classify uses ask mode', async () => {
  const f = await makeFixture()
  const adapter = getAdapter('maka')
  await adapter.seedHome(f.home, {
    id: 'agent-maka',
    name: 'Maka Engineer',
    role: 'engineer',
    systemPrompt: 'Follow first principles.',
  })
  const agentsMd = await readFile(join(f.home, 'AGENTS.md'), 'utf8')
  assert.match(agentsMd, /Maka Engineer/)
  assert.match(agentsMd, /\.agents\/skills\//)
  assert.equal((await stat(join(f.home, '.agents', 'skills'))).isDirectory(), true)

  const controller = new AbortController()
  const classified = await adapter.classify({
    cwd: f.home,
    env: f.env,
    prompt: 'Actionable?',
    signal: controller.signal,
  })
  assert.equal(classified.error, undefined)
  assert.equal(classified.text, 'pong #1')

  const calls = await f.readCalls()
  const permCfg = calls.find((c) => c.method === 'session/set_config_option' && c.params?.configId === 'permission_mode')
  assert.equal(permCfg?.params?.value, 'ask')
})

test('maka triage cancels permission requests instead of approving them', async () => {
  const f = await makeFixture('ask-permission')
  const classified = await getAdapter('maka').classify({
    cwd: f.home,
    env: f.env,
    prompt: 'classify without tools',
    signal: new AbortController().signal,
  })
  assert.equal(classified.error, undefined)
  const calls = await f.readCalls()
  const permCfg = calls.find((c) => c.method === 'session/set_config_option' && c.params?.configId === 'permission_mode')
  assert.equal(permCfg?.params?.value, 'ask')
  const promptCall = calls.find((c) => c.method === 'session/prompt')
  const reply = calls.find((c) => c.id === promptCall?.id && !c.method)
  assert.deepEqual(reply?.result, { outcome: { outcome: 'cancelled' } })
})

test('maka triage fails closed when ask mode cannot be applied', async () => {
  const f = await makeFixture('reject-ask')
  const classified = await getAdapter('maka').classify({
    cwd: f.home,
    env: f.env,
    prompt: 'classify without tools',
    signal: new AbortController().signal,
  })
  assert.match(classified.error ?? '', /permission_mode=ask could not be applied/)
  const calls = await f.readCalls()
  assert.equal(calls.some((c) => c.method === 'session/prompt'), false)
})

test('maka probeWake exercises the acp handshake and one-shot run forwards resumeSessionId', async () => {
  const f = await makeFixture()
  const adapter = getAdapter('maka')
  const controller = new AbortController()

  const wake = await adapter.probeWake({ cwd: f.home, env: f.env, signal: controller.signal })
  assert.equal(wake.ok, true)

  const oneShot = await adapter.run({
    home: f.home,
    env: f.env,
    prompt: 'say pong',
    resumeSessionId: 'maka-sess-resumed-run',
    signal: controller.signal,
    onLog: () => {},
  })
  assert.equal(oneShot.exitCode, 0)
  assert.equal(oneShot.sessionId, 'maka-sess-resumed-run')

  const calls = await f.readCalls()
  assert.ok(
    calls.some((c) => c.method === 'session/resume' && c.params?.sessionId === 'maka-sess-resumed-run'),
    'MakaAdapter.run must forward resumeSessionId to session/resume',
  )

  const probed = await adapter.probe({ cwd: f.home, env: f.env, tier: 'big', signal: controller.signal })
  assert.equal(probed.text, 'pong #1')
})

test('maka does not fall back to dsh when only dsh is on PATH', async () => {
  const root = await mkdtemp(join(tmpdir(), 'cumora-maka-dsh-only-'))
  tempDirs.push(root)
  const binDir = join(root, 'bin')
  await mkdir(binDir, { recursive: true })
  const dshBin = join(binDir, process.platform === 'win32' ? 'dsh.cmd' : 'dsh')
  await writeFile(dshBin, '#!/bin/sh\nexit 0\n', 'utf8')
  await chmod(dshBin, 0o755)

  const envWithOnlyDsh: NodeJS.ProcessEnv = { PATH: binDir }
  assert.equal(resolveMakaBin(envWithOnlyDsh), null)

  const controller = new AbortController()
  const wake = await getAdapter('maka').probeWake({
    cwd: root,
    env: envWithOnlyDsh,
    signal: controller.signal,
  })
  assert.equal(wake.ok, false)
})

test('maka extracts ACP standard cachedReadTokens and cachedWriteTokens when usage is present', async () => {
  const f = await makeFixture('with-usage')
  const hops: EngineHopReport[] = []
  const session = getAdapter('maka').startSession?.({
    home: f.home,
    env: f.env,
    standingPrompt: null,
    resumeSessionId: null,
    onLog: () => {},
    onHopUsage: (h) => hops.push(h),
  })
  assert.ok(session)
  liveSessions.push(session)

  const r = await session.send('turn with usage')
  assert.equal(r.exitCode, 0)
  assert.deepEqual(r.usage, {
    input_tokens: 110,
    output_tokens: 15,
    cache_read_input_tokens: 30,
    cache_creation_input_tokens: 10,
  })
  assert.equal(hops.length, 1)
  assert.deepEqual(hops[0]?.usage, {
    input_tokens: 110,
    output_tokens: 15,
    cache_read_input_tokens: 30,
    cache_creation_input_tokens: 10,
  })
})

test('acp connection decodes multi-byte UTF-8 characters split across stdout chunks without replacement characters', async () => {
  const f = await makeFixture('split-utf8')
  const controller = new AbortController()
  const classified = await getAdapter('maka').classify({
    cwd: f.home,
    env: f.env,
    prompt: 'say hello in Chinese',
    signal: controller.signal,
  })
  assert.equal(classified.error, undefined)
  assert.equal(classified.text, '你好世界')
  assert.ok(!classified.text.includes('\uFFFD'))
})