Skip to content

The agent that grows with you

19.2 KB
Raw Blame
import { expect, test, vi } from 'vitest'

import { CanonicalDesktopProtocol } from './canonical-protocol'

test('sibling routes survive every rebuilt control and compression follow-up', async () => {
  const protocol = new CanonicalDesktopProtocol()
  protocol.result('session.resume', { session_id: 's', profile: 'sibling' }, {
    session_id: 's', revision: 4, execution_generation: 9,
    prompts: [{ kind: 'approval', prompt_id: 'p', execution_generation: 9 }],
    pending: [{ admission_id: 'lost', status: 'unknown', execution_generation: 3 }]
  })

  const requests: Array<[string, Record<string, unknown>]> = [
    ['session.title', { title: 'title' }], ['session.archive', { archived: true }],
    ['session.branch', {}], ['session.branch_stored', { parent_session_id: 's' }],
    ['session.compress', {}], ['slash.exec', { command: 'model new-model' }],
    ['approval.respond', { request_id: 'p', choice: 'once' }],
    ['prompt.resolve_unknown', { admission_id: 'lost' }]
  ]

  for (const [method, params] of requests) {
    expect(protocol.prepare(method, { session_id: 's', profile: 'sibling', ...params })).toMatchObject({ profile: 'sibling' })
  }

  const calls: unknown[] = []
  const params = protocol.prepare('session.compress', { session_id: 's', profile: 'sibling' })
  await protocol.settle('session.compress', params, { message_count: 1 }, async (method, followUp) => {
    calls.push([method, followUp])

    return { messages: [], info: {} }
  })
  expect(calls).toEqual([['session.resume', { session_id: 's', profile: 'sibling' }]])
})

test('slash compress refreshes its transcript on the owner route and previews stay read-only', async () => {
  const protocol = new CanonicalDesktopProtocol()
  protocol.result('session.resume', { profile: 'sibling' }, { session_id: 's', revision: 1, execution_generation: 2 })
  const prepared = protocol.prepare('slash.exec', { session_id: 's', profile: 'sibling', command: 'compress' })
  const calls: unknown[] = []

  const followUp = async (method: string, params: Record<string, unknown>) => {
    calls.push([method, params])

    return { messages: [{ role: 'assistant', content: 'retained' }], info: {} }
  }

  const result = protocol.result('slash.exec', prepared, { session_id: 's', revision: 2, message_count: 1 })
  expect(await protocol.settle('slash.exec', prepared, result, followUp)).toMatchObject({ type: 'exec', messages: [{ content: 'retained' }] })
  expect(calls).toEqual([['session.resume', { session_id: 's', profile: 'sibling' }]])
  const preview = protocol.result('slash.exec', prepared, { session_id: 's', status: 'preview', lines: ['report'] })
  await protocol.settle('slash.exec', prepared, preview, followUp)
  expect(calls).toHaveLength(1)
})

test('corrections preserve intent and fence the observed session generation', () => {
  const protocol = new CanonicalDesktopProtocol()

  for (const method of ['session.redirect', 'session.steer']) {
    expect(() => protocol.prepare(method, { session_id: 's', text: 'correction' })).toThrow('execution identity')
  }

  protocol.event({ type: 'message.start', session_id: 's', payload: { execution_generation: 4 } })
  protocol.event({ type: 'message.start', session_id: 'other', payload: { execution_generation: 9 } })

  for (const method of ['session.redirect', 'session.steer']) {
    const params = protocol.prepare(method, { session_id: 's', text: 'correction' })
    expect(params).toEqual({ session_id: 's', text: 'correction', execution_generation: 4 })
    expect(protocol.wire(method, params)).toBe(method)
    expect(protocol.prepare(method, { ...params, execution_generation: 2 }).execution_generation).toBe(2)
  }
})

test('metadata writes retain the original CAS revision and request identity until acknowledgement', () => {
  const protocol = new CanonicalDesktopProtocol()
  protocol.result('session.resume', { session_id: 's' }, { session_id: 's', revision: 7 })
  const first = protocol.prepare('session.title', { session_id: 's', title: 'new title' })
  expect(first).toEqual({ session_id: 's', request_id: expect.any(String), expected_revision: 7, operation: 'rename', payload: { title: 'new title' } })
  protocol.result('session.resume', { session_id: 's' }, { session_id: 's', revision: 8 })
  expect(protocol.prepare('session.title', { session_id: 's', title: 'new title' })).toEqual(first)
  protocol.failure(first, { data: { reason: 'revision_conflict' } })
  const retry = protocol.prepare('session.title', { session_id: 's', title: 'new title' })
  expect(retry.expected_revision).toBe(8)
  expect(retry.request_id).not.toBe(first.request_id)
  protocol.result('session.title', first, { session_id: 's', revision: 8, title: 'new title' })
  expect(protocol.prepare('session.archive', { session_id: 's', archived: true })).toMatchObject({ expected_revision: 8, operation: 'archive', payload: { archived: true } })
})

test('canonical create retries retain identity', () => {
  const protocol = new CanonicalDesktopProtocol()
  const params = { source: 'desktop', profile: 'default', cols: 96, fast: false, cwd: '/tmp' }
  const first = protocol.prepare('session.create', params)
  expect(first).toMatchObject({ source: 'gui', cwd: '/tmp', request_id: expect.any(String) })
  expect(protocol.prepare('session.create', { ...params })).toEqual(first)
  // RT-26: the picked profile rides the create, `default` included (a named launch profile would own it otherwise).
  expect(first).toHaveProperty('profile', 'default')
  expect(protocol.prepare('session.create', { ...params, fast: true })).toMatchObject({ service_tier: 'priority' })
  const manual = protocol.prepare('session.create', { ...params, model: 'gpt-5', provider: 'custom' })
  expect(manual).toMatchObject({ model: 'gpt-5', provider: 'custom' })
  expect(protocol.prepare('session.create', { ...params, model: 'gpt-5', provider: 'custom' })).toEqual(manual)
  protocol.result('session.create', first, { session_id: 'canonical', stored_session_id: 'canonical' })
  expect(protocol.prepare('session.create', params).request_id).not.toBe(first.request_id)
})

// TUI-26: a bare stop phrase typed into a LOCAL voice chat (turned on by another viewer) ends the
// chat on the owner and admits nothing; the owner answers `{voice_stopped: true}`.
test('a voice_stopped prompt.submit reply is a settled no-admission receipt, never a mismatch', () => {
  const protocol = new CanonicalDesktopProtocol()
  const params = protocol.prepare('prompt.submit', { session_id: 's', text: 'stop' })
  const receipt = protocol.result('prompt.submit', params, { voice_stopped: true, extra: 'dropped' })
  expect(receipt).toEqual({ voice_stopped: true, session_id: 's', submission_id: params.submission_id })
  expect(() => protocol.result('prompt.submit', params, { voice_stopped: false })).toThrow('destination')
})

test('canonical receipts preserve admission identity and replay restores fenced controls', () => {
  const protocol = new CanonicalDesktopProtocol()
  const receipt = protocol.result('prompt.submit', { session_id: 's', submission_id: 'input' }, { admission_id: 'admission', ref: { session_id: 's', profile_id: '/tmp/profile' }, status: 'queued' })
  expect(receipt).toMatchObject({ admission_id: 'admission', submission_id: 'input', session_id: 's' })
  expect(() => protocol.result('prompt.submit', { session_id: 'other', submission_id: 'input' }, receipt)).toThrow('destination')
  const resumed = protocol.result('session.resume', { session_id: 's' }, { session_id: 's', stored_session_id: 's', execution_generation: 3, prompts: [{ kind: 'approval', prompt_id: 'p', execution_generation: 3, command: 'test' }] })
  expect(resumed.pending_approval).toMatchObject({ request_id: 'p', execution_generation: 3 })
  expect(protocol.prepare('approval.respond', { session_id: 's', request_id: 'p', choice: 'once' })).toEqual({ session_id: 's', execution_generation: 3, prompt_id: 'p', choice: 'once' })
  expect(protocol.prepare('session.interrupt', { session_id: 's' })).toEqual({ session_id: 's', execution_generation: 3 })
  protocol.event({ type: 'message.start', session_id: 's', payload: { execution_generation: 4 } })
  expect(() => protocol.prepare('approval.respond', { session_id: 's', request_id: 'p', choice: 'once' })).toThrow('stale')
})

test('pending resume and live updates share the existing queue projection', () => {
  const protocol = new CanonicalDesktopProtocol()
  const pending = [{ admission_id: 'a', input_id: 'original', text: 'queued text', status: 'queued' }]
  const resumed = protocol.result('session.resume', {}, { session_id: 's', pending })
  const event = { type: 'session.info', session_id: 's', payload: { pending } }
  protocol.event(event)
  expect(resumed.info.pending_submissions).toEqual([{ ...pending[0], user: 'queued text' }])
  expect(event.payload).toHaveProperty('pending_submissions', resumed.info.pending_submissions)
  const cleared = { type: 'session.info', session_id: 's', payload: { pending: [] } }
  protocol.event(cleared)
  expect(cleared.payload).toHaveProperty('pending_submissions', [])
})

test('a stored-parent branch travels as the canonical branch mutation on the parent', () => {
  // A legacy `session.branch_stored` mints a child the authority cannot restore (no local
  // policy), so every resume on it answers not_found and the first submit never leaves.
  const protocol = new CanonicalDesktopProtocol()
  protocol.result('session.resume', { session_id: 'p' }, { session_id: 'p', revision: 3, execution_generation: 1 })
  const prepared = protocol.prepare('session.branch_stored', { cols: 96, source: 'desktop', parent_session_id: 'p', profile: 'default' })
  expect(protocol.wire('session.branch_stored', prepared)).toBe('session.mutate')
  expect(prepared).toMatchObject({ session_id: 'p', operation: 'branch', payload: {}, expected_revision: 3, expected_generation: 1 })
  const child = protocol.result('session.branch_stored', prepared, { session_id: 'p', revision: 4, operation: 'branch', branched_session_id: 'c', copied_messages: 4 })
  expect(child).toMatchObject({ session_id: 'c', stored_session_id: 'c', parent_session_id: 'p', message_count: 4 })
})

test('composer branch and model switch become canonical prepared mutations with identity retained', () => {
  const protocol = new CanonicalDesktopProtocol()
  protocol.result('session.resume', { session_id: 's' }, { session_id: 's', revision: 4, execution_generation: 9 })
  const branch = protocol.prepare('session.branch', { session_id: 's' })
  expect(protocol.wire('session.branch')).toBe('session.mutate')
  expect(branch).toEqual({ session_id: 's', request_id: expect.any(String), expected_revision: 4, expected_generation: 9, operation: 'branch', payload: {} })
  expect(protocol.prepare('session.branch', { session_id: 's' })).toEqual(branch)
  const branched = protocol.result('session.branch', branch, { session_id: 's', revision: 5, operation: 'branch', branched_session_id: 'child', copied_messages: 6 })
  expect(branched).toMatchObject({ session_id: 'child', stored_session_id: 'child', parent_session_id: 's' })
  expect(protocol.prepare('session.branch', { session_id: 's' }).request_id).not.toBe(branch.request_id)

  const model = protocol.prepare('slash.exec', { session_id: 's', command: 'model switched' })
  expect(protocol.wire('slash.exec', model)).toBe('session.mutate')
  expect(model).toMatchObject({ session_id: 's', expected_revision: 5, operation: 'model', payload: { model: 'switched' } })
  expect(protocol.result('slash.exec', model, { session_id: 's', revision: 6, operation: 'model', model: 'switched', provider: 'custom' })).toMatchObject({ type: 'exec', output: expect.stringContaining('switched') })
  expect(protocol.wire('slash.exec', protocol.prepare('slash.exec', { session_id: 's', command: 'help' }))).toBe('slash.exec')
})

test('a session.info fanout after a turn refreshes the CAS revision the next mutation presents', () => {
  const protocol = new CanonicalDesktopProtocol()
  protocol.result('session.resume', { session_id: 's' }, { session_id: 's', revision: 2, execution_generation: 1 })
  protocol.event({ type: 'session.info', session_id: 's', payload: { pending: [], running: false, execution_generation: 2, revision: 5 } })
  expect(protocol.prepare('session.branch', { session_id: 's' })).toMatchObject({ expected_revision: 5, expected_generation: 2 })
})

test('acknowledging a turn lost across a restart presents the unknown row\'s own generation', () => {
  const protocol = new CanonicalDesktopProtocol()
  protocol.result('session.resume', { session_id: 's' }, { session_id: 's', stored_session_id: 's', execution_generation: 9, revision: 2,
    pending: [{ admission_id: 'lost', status: 'unknown', execution_generation: 4, text: 'LOST' }, { admission_id: 'next', status: 'queued', execution_generation: null, text: 'NEXT' }] })
  expect(protocol.prepare('prompt.resolve_unknown', { session_id: 's', admission_id: 'lost' }))
    .toEqual({ session_id: 's', admission_id: 'lost', execution_generation: 4 })
  expect(() => protocol.prepare('prompt.resolve_unknown', { session_id: 's', admission_id: 'next' })).toThrow('unknown')

  const receipt = protocol.result('prompt.resolve_unknown', { session_id: 's', admission_id: 'lost', execution_generation: 4 },
    { admission_id: 'lost', ref: { session_id: 's', profile_id: '/tmp/profile' }, status: 'terminal', outcome: 'interrupted' })

  expect(receipt).toMatchObject({ admission_id: 'lost', session_id: 's', status: 'terminal' })
  protocol.event({ type: 'session.info', session_id: 's', payload: { pending: [{ admission_id: 'next', status: 'started', execution_generation: 10, text: 'NEXT' }], execution_generation: 10 } })
  expect(() => protocol.prepare('prompt.resolve_unknown', { session_id: 's', admission_id: 'lost' })).toThrow('unknown')
})

test('the dedicated compress action becomes a fenced canonical mutation and settles with the resumed transcript', async () => {
  const protocol = new CanonicalDesktopProtocol()
  protocol.result('session.resume', { session_id: 's' }, { session_id: 's', revision: 4, execution_generation: 9 })

  const prepared = protocol.prepare('session.compress', { session_id: 's', focus_topic: 'billing' })
  expect(prepared).toEqual({ session_id: 's', request_id: expect.any(String), expected_revision: 4, expected_generation: 9, operation: 'compress', payload: { focus: 'billing' } })
  expect(protocol.prepare('session.compress', { session_id: 's' }).payload).toEqual({})
  expect(protocol.wire('session.compress', prepared)).toBe('session.mutate')
  expect(() => protocol.result('session.compress', prepared, { session_id: 'other', revision: 5, operation: 'compress' })).toThrow('destination')

  const calls: Array<[string, Record<string, unknown>]> = []
  const resumed = { session_id: 's', messages: [{ role: 'assistant', content: 'summary' }], info: { title: 'T' } }

  const fakeRequest = async (method: string, params: Record<string, unknown>) => { calls.push([method, params]);

 return resumed }

  const receipt = protocol.result('session.compress', prepared, { session_id: 's', revision: 5, operation: 'compress', target_session_id: 's', message_count: 3 })
  const settled = await protocol.settle('session.compress', prepared, receipt, fakeRequest)

  expect(settled.messages).toEqual(resumed.messages)
  expect(settled.info).toEqual(resumed.info)
  expect(settled.host_ack.output).toContain('3')
  expect(calls).toEqual([['session.resume', { session_id: 's' }]])
  // Acknowledged: the next compress presents the refreshed revision under a new request id.
  expect(protocol.prepare('session.compress', { session_id: 's', focus_topic: 'billing' })).toMatchObject({ expected_revision: 5 })
  expect(protocol.prepare('session.compress', { session_id: 's', focus_topic: 'billing' }).request_id).not.toBe(prepared.request_id)

  const untouched = { session_id: 's', ok: true }
  expect(await protocol.settle('session.title', { session_id: 's' }, untouched, fakeRequest)).toBe(untouched)
  expect(calls).toHaveLength(1)
})

test('the composer model picker travels as the canonical model mutation, not an unsupported config.set', () => {
  const protocol = new CanonicalDesktopProtocol()
  protocol.result('session.resume', { session_id: 's' }, { session_id: 's', revision: 3, execution_generation: 2 })

  for (const value of ['gpt-5 --provider openrouter', 'gpt-5 --provider openrouter --session']) {
    const pick = protocol.prepare('config.set', { session_id: 's', key: 'model', value })
    expect(protocol.wire('config.set', pick)).toBe('session.mutate')
    expect(pick).toEqual({ session_id: 's', request_id: expect.any(String), expected_revision: 3, expected_generation: 2, operation: 'model', payload: { model: 'gpt-5', provider: 'openrouter' } })
    expect(protocol.result('config.set', pick, { session_id: 's', revision: 4, operation: 'model', model: 'gpt-5', provider: 'openrouter' })).toMatchObject({ ok: true, model: 'gpt-5' })
    protocol.result('session.resume', { session_id: 's' }, { session_id: 's', revision: 3, execution_generation: 2 })
  }

  // Other preferences, and model flags the mutation has no field for, keep their own route.
  expect(protocol.wire('config.set', protocol.prepare('config.set', { session_id: 's', key: 'busy', value: 'queue' }))).toBe('config.set')
  expect(protocol.wire('config.set', protocol.prepare('config.set', { session_id: 's', key: 'model', value: 'gpt-5 --global' }))).toBe('config.set')
})

test('a message-level branch carries its durable boundary row; a whole-chat branch copies everything', () => {
  const protocol = new CanonicalDesktopProtocol()
  protocol.result('session.resume', { session_id: 's' }, { session_id: 's', revision: 3, execution_generation: 1 })
  const selected = protocol.prepare('session.branch', { session_id: 's', idempotency_key: 'k', count: 2, through_message_id: 41 })
  expect(protocol.wire('session.branch', selected)).toBe('session.mutate')
  expect(selected).toMatchObject({ operation: 'branch', payload: { through_message_id: 41 } })
  // A lost-response retry presents the identical mutation (the boundary is part of its identity).
  expect(protocol.prepare('session.branch', { session_id: 's', idempotency_key: 'k', count: 2, through_message_id: 41 })).toEqual(selected)
  // A selected message with no durable row yet must never fall back to a whole-history copy.
  expect(() => protocol.prepare('session.branch', { session_id: 's', count: 2 })).toThrow(/not saved yet/)
  expect(protocol.prepare('session.branch', { session_id: 's' })).toMatchObject({ payload: {} })
})

test('mints v4 create, submit and mutation ids where crypto.randomUUID is absent (plain-HTTP LAN origin)', () => {
  const V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
  vi.stubGlobal('crypto', { getRandomValues: crypto.getRandomValues.bind(crypto) })

  try {
    const protocol = new CanonicalDesktopProtocol()
    protocol.result('session.resume', { profile: 'default', session_id: 's' }, { session_id: 's', revision: 2, execution_generation: 3 })

    const cases: Array<[string, Record<string, unknown>, string]> = [
      ['session.create', { profile: 'default', source: 'desktop' }, 'request_id'],
      ['prompt.submit', { profile: 'default', session_id: 's', text: 'hi' }, 'submission_id'],
      ['session.title', { profile: 'default', session_id: 's', title: 't' }, 'request_id']
    ]

    for (const [method, params, key] of cases) {
      expect(JSON.stringify(protocol.prepare(method, params)).match(new RegExp(`"${key}":"([^"]+)"`))?.[1]).toMatch(V4)
    }
  } finally {
    vi.unstubAllGlobals()
  }
})