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
8.6 KB
Raw Blame
/**
 * Contract tests for the BYOA ZCode (`zcode`) adapter.
 *
 * The fake bridge implements the zcode-acp-server wire surface the adapter
 * actually speaks — initialize / session/new|load / session/set_config_option /
 * session/prompt over newline-delimited JSON-RPC — and is injected through
 * CUMORA_ZCODE_ACP_BIN, the same escape hatch operators use, so the resolution
 * seam stays under test. Scenarios cover the pin-retry semantics, the
 * stale-resume self-heal at load time, and the "Session is not active" →
 * resume-not-found mapping at prompt time.
 */
import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, test } from 'node:test'
import assert from 'node:assert/strict'
import { getAdapter, type EngineHopReport } from '../agents/computer/engine.js'

const tempDirs: string[] = []

afterEach(async () => {
  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })))
})

const FAKE_BRIDGE = `#!/usr/bin/env node
'use strict'
const fs = require('node:fs')
const readline = require('node:readline')
const mode = process.env.FAKE_ACP_MODE || 'ok'
const log = process.env.FAKE_ACP_LOG
let nextSid = 0
let loaded = false
const out = (msg) => process.stdout.write(JSON.stringify(msg) + '\\n')
const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity })
rl.on('line', (line) => {
  if (!line.trim()) return
  let req
  try { req = JSON.parse(line) } catch { return }
  if (!req.id || !req.method) return
  if (log) fs.appendFileSync(log, JSON.stringify({ method: req.method, params: req.params }) + '\\n')
  const reply = (result) => out({ jsonrpc: '2.0', id: req.id, result })
  const fail = (message) => out({ jsonrpc: '2.0', id: req.id, error: { message } })
  if (req.method === 'initialize') return reply({})
  if (req.method === 'session/load') {
    if (mode === 'stale-load') return fail('Internal error')
    loaded = true
    return reply({ sessionId: req.params.sessionId })
  }
  if (req.method === 'session/new') {
    loaded = false
    return reply({ sessionId: 'fresh-' + (++nextSid) })
  }
  if (req.method === 'session/set_config_option') {
    if (mode === 'reject-pin') return fail('Internal error')
    return reply({ kind: 'model', currentValue: req.params.value })
  }
  if (req.method === 'session/prompt') {
    if (mode === 'stale-prompt' && loaded) return fail('Session is not active')
    if (mode === 'die-midturn') return process.exit(3)
    out({ jsonrpc: '2.0', method: 'session/update', params: { update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'OK' } } } })
    return reply({ stopReason: 'end_turn' })
  }
  return reply({})
})
`

interface Fixture { home: string; log: string; env: NodeJS.ProcessEnv; logs: string[] }

async function fixture(scenario = 'ok'): Promise<Fixture> {
  const root = await mkdtemp(join(tmpdir(), 'cumora-zcode-'))
  tempDirs.push(root)
  const home = join(root, 'home')
  const log = join(root, 'fake.log')
  await mkdir(home, { recursive: true })
  const fake = join(root, 'fake-acp-bridge.cjs')
  await writeFile(fake, FAKE_BRIDGE, 'utf8')
  await chmod(fake, 0o755)
  const logs: string[] = []
  return {
    home, log, logs,
    env: {
      ...process.env,
      CUMORA_ZCODE_ACP_BIN: fake,
      FAKE_ACP_MODE: scenario,
      FAKE_ACP_LOG: log,
    },
  }
}

async function bridgeLog(f: Fixture): Promise<Array<{ method: string; params: Record<string, unknown> }>> {
  return (await readFile(f.log, 'utf8')).split('\n').filter(Boolean).map((line) => JSON.parse(line))
}

test('zcode persistent session pins the model once and rides one session across wakes', async () => {
  const f = await fixture()
  const hops: EngineHopReport[] = []
  const session = getAdapter('zcode').startSession?.({
    home: f.home,
    env: f.env,
    model: 'GLM-5.3',
    standingPrompt: 'scaffold',
    onLog: (line) => f.logs.push(line),
    onHopUsage: (hop) => hops.push(hop),
  })
  assert.ok(session)
  assert.equal(session.carriesStandingPrompt, false, 'no out-of-band standing-prompt channel — the daemon inlines it')

  const first = await session.send('first prompt')
  const second = await session.send('second prompt')
  await session.stop()

  assert.equal(first.exitCode, 0)
  assert.equal(first.sessionId, 'fresh-1')
  assert.equal(second.exitCode, 0)
  assert.equal(second.sessionId, 'fresh-1', 'the same bridge session carries both wakes')
  assert.equal(hops.length, 2, 'one hop per wake')

  const requests = await bridgeLog(f)
  const pins = requests.filter((r) => r.method === 'session/set_config_option')
  assert.equal(pins.length, 1, 'an accepted pin is sent once, not on every wake')
  assert.equal(pins[0].params.configId, 'model')
  assert.equal(pins[0].params.value, 'GLM-5.3')
  const prompts = requests.filter((r) => r.method === 'session/prompt')
  assert.deepEqual(prompts.map((r) => (r.params.prompt as Array<{ text: string }>)[0].text), ['first prompt', 'second prompt'])
  assert.ok(prompts.every((r) => r.params.sessionId === 'fresh-1'))
})

test('zcode retries a rejected model pin on the next wake and still turns', async () => {
  const f = await fixture('reject-pin')
  const session = getAdapter('zcode').startSession?.({
    home: f.home,
    env: f.env,
    model: 'GLM-5.3',
    standingPrompt: null,
    onLog: (line) => f.logs.push(line),
  })
  assert.ok(session)
  const first = await session.send('first prompt')
  const second = await session.send('second prompt')
  await session.stop()

  assert.equal(first.exitCode, 0, 'a rejected pin is a preference loss, not a turn failure')
  assert.equal(second.exitCode, 0)
  assert.ok(f.logs.some((line) => line.includes('model pin rejected')))
  const requests = await bridgeLog(f)
  assert.equal(requests.filter((r) => r.method === 'session/set_config_option').length, 2, 'a rejected pin retries on each wake')
})

test('zcode self-heals a stale resume at load time and reports a fresh session', async () => {
  const f = await fixture('stale-load')
  const session = getAdapter('zcode').startSession?.({
    home: f.home,
    env: f.env,
    model: null,
    standingPrompt: null,
    resumeSessionId: 'stale-sid',
    onLog: (line) => f.logs.push(line),
  })
  assert.ok(session)
  const result = await session.send('first prompt after restart')
  await session.stop()

  assert.equal(result.exitCode, 0)
  assert.equal(result.sessionId, 'fresh-1', 'the fresh session replaces the stale one')
  assert.ok(f.logs.some((line) => line.includes('session/load failed') && line.includes('starting a fresh session')))
  const requests = await bridgeLog(f)
  assert.equal(requests[1]?.method, 'session/load')
  assert.equal(requests[2]?.method, 'session/new')
})

test('zcode maps a mid-life missing backend session to resume-not-found', async () => {
  const f = await fixture('stale-prompt')
  const session = getAdapter('zcode').startSession?.({
    home: f.home,
    env: f.env,
    model: null,
    standingPrompt: null,
    resumeSessionId: 'real-but-dead',
    onLog: (line) => f.logs.push(line),
  })
  assert.ok(session)
  const result = await session.send('prompt a vanished session')
  await session.stop()

  assert.equal(result.exitCode, 1)
  assert.equal(result.failure?.kind, 'resume-not-found', 'the bridge\'s "Session is not active" is not in the generic patterns — the adapter maps it')
  assert.ok(result.error?.includes('Session is not active'))
})

test('zcode a bridge dying MID-TURN resolves the turn as a failure, never rejects', async () => {
  const f = await fixture('die-midturn')
  const session = getAdapter('zcode').startSession?.({
    home: f.home,
    env: f.env,
    model: null,
    standingPrompt: null,
    onLog: (line) => f.logs.push(line),
  })
  assert.ok(session)
  // die() races send()'s own settlement here: the rpc waiters reject while the
  // in-flight turn is already closed. send() must still RESOLVE a failure.
  const result = await session.send('prompt that kills the bridge')
  await session.stop()

  assert.equal(result.exitCode, 3)
  assert.ok(result.error)
  assert.notEqual(result.failure?.kind, 'resume-not-found', 'no resume involved — the generic classifier owns this kind')
})

test('zcode probeWake exercises the bridge handshake and one-shot run returns text', async () => {
  const f = await fixture()
  const adapter = getAdapter('zcode')
  const wake = await adapter.probeWake({ cwd: f.home, env: f.env, signal: AbortSignal.timeout(10_000) })
  assert.equal(wake.ok, true)

  const run = await adapter.run({
    home: f.home,
    prompt: 'echo prompt',
    env: f.env,
    signal: AbortSignal.timeout(10_000),
    onLog: () => {},
  })
  assert.equal(run.exitCode, 0)
  assert.equal(run.sessionId, 'fresh-1')
})