The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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()
}
})