import { runScenarios } from '../../../scripts/test-scenarios.mjs' import { afterEach, describe, expect, it, vi } from 'vitest' import { createEvent, createRpcError, createRpcResponse, encodeMessage } from '@dsh-remote/protocol' import { BaseTransport } from '@dsh-remote/webrtc' import { CodexRemoteClient, HarnessAlphaClient, RemoteClientCore, RemoteClientError, RemoteTypertGateway, probeRemoteHostFeatures, } from '../src/index.js' class LoopbackTransport extends BaseTransport { sent: Uint8Array[] = [] sendGate?: Promise closeError?: Error async connect() {} async send(data: Uint8Array) { this.sent.push(data) await this.sendGate } async close() { if (this.closeError !== undefined) throw this.closeError } getStats() { return { mode: 'Relay' as const, connected: true } } push(data: Uint8Array) { this.emit(data) } drop(error?: Error) { this.emitClose(error) } } const cleanupContract1 = () => { vi.useRealTimers() vi.restoreAllMocks() } afterEach(cleanupContract1) describe('RemoteClientCore', () => { it('preserves terminal close reasons for recovery and notifies only once', async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) await client.connect() const closed = vi.fn() client.onClose(closed) const error = Object.assign(new Error('replaced'), { code: 'CONNECTION_REPLACED' }) transport.drop(error) await client.close() expect(closed).toHaveBeenCalledOnce() expect(closed).toHaveBeenCalledWith(error) }) it('matches responses to pending RPC calls', async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) await client.connect() const call = client.rpc('harness.api.call', {}) const request = JSON.parse(new TextDecoder().decode(transport.sent[0]!)) transport.push(encodeMessage(createRpcResponse(request.id, { ok: true }))) await expect(call).resolves.toEqual({ ok: true }) }) it('terminates pending RPCs with the correct close reason', async () => { await runScenarios( [ { name: 'uses TRANSPORT_CLOSED when the transport terminates a pending RPC', run: async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) await client.connect() let closed = false client.onClose(() => { closed = true }) const call = client.rpc('harness.api.call', {}) transport.drop() await expect(call).rejects.toMatchObject({ name: 'RemoteClientError', code: 'TRANSPORT_CLOSED', }) expect(closed).toBe(true) await expect(client.rpc('harness.remote.stream.close', {})).rejects.toMatchObject({ code: 'TRANSPORT_CLOSED' }) await client.close() await expect(client.rpc('harness.remote.stream.close', {})).rejects.toMatchObject({ code: 'TRANSPORT_CLOSED' }) expect(transport.sent).toHaveLength(1) }, }, { name: 'uses CLIENT_CLOSED when close terminates a pending RPC', run: async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) await client.connect() const call = client.rpc('harness.api.call', {}) await client.close() await expect(call).rejects.toMatchObject({ name: 'RemoteClientError', code: 'CLIENT_CLOSED', }) await expect(client.rpc('harness.remote.stream.close', {})).rejects.toMatchObject({ code: 'CLIENT_CLOSED' }) expect(transport.sent).toHaveLength(1) }, }, { name: 'rejects pending RPCs before a failing transport close completes', run: async () => { const transport = new LoopbackTransport() transport.closeError = new Error('transport close failed') const client = new RemoteClientCore(transport) await client.connect() const closed = vi.fn() client.onClose(closed) const call = client.rpc('harness.api.call', {}) const termination = expect(call).rejects.toMatchObject({ code: 'CLIENT_CLOSED' }) const closing = client.close() expect(closed).toHaveBeenCalledOnce() await expect(closing).rejects.toThrow('transport close failed') await termination }, }, ], async () => { await cleanupContract1() }, ) }, 15000) it('enforces RPC deadlines even while send is pending', async () => { await runScenarios( [ { name: 'uses RPC_TIMEOUT when a pending RPC reaches its deadline', run: async () => { vi.useFakeTimers() const transport = new LoopbackTransport() const client = new RemoteClientCore(transport, 1_000) await client.connect() const call = client.rpc('harness.api.call', {}) const termination = expect(call).rejects.toMatchObject({ name: 'RemoteClientError', code: 'RPC_TIMEOUT', }) await vi.advanceTimersByTimeAsync(1_000) await termination }, }, { name: 'allows a per-call timeout longer than the client default', run: async () => { vi.useFakeTimers() const transport = new LoopbackTransport() const client = new RemoteClientCore(transport, 1_000) await client.connect() const call = client.rpc( 'agent.acp.call', { method: 'session/prompt', params: {} }, undefined, 5_000, ) const pending = expect(call).rejects.toMatchObject({ code: 'RPC_TIMEOUT' }) await vi.advanceTimersByTimeAsync(1_000) await Promise.resolve() await vi.advanceTimersByTimeAsync(4_000) await pending }, }, { name: 'times out even when transport.send never settles', run: async () => { vi.useFakeTimers() const transport = new LoopbackTransport() transport.sendGate = new Promise(() => undefined) const client = new RemoteClientCore(transport, 1_000) await client.connect() const call = client.rpc('harness.api.call', {}) const termination = expect(call).rejects.toMatchObject({ code: 'RPC_TIMEOUT' }) await vi.advanceTimersByTimeAsync(1_000) await termination }, }, { name: 'applies a per-call deadline while ordinary calls keep the client-wide one', run: async () => { vi.useFakeTimers() const transport = new LoopbackTransport() const client = new RemoteClientCore(transport, 1_000) await client.connect() const ordinary = client.rpc('harness.remote.call', {}) const ordinaryTermination = expect(ordinary).rejects.toMatchObject({ name: 'RemoteClientError', code: 'RPC_TIMEOUT', message: 'RPC harness.remote.call timed out after 1000ms', }) const extended = client.rpc('harness.remote.call', {}, undefined, { timeoutMs: 5_000 }) const extendedTermination = expect(extended).rejects.toMatchObject({ name: 'RemoteClientError', code: 'RPC_TIMEOUT', message: 'RPC harness.remote.call timed out after 5000ms', }) await vi.advanceTimersByTimeAsync(1_000) await ordinaryTermination await vi.advanceTimersByTimeAsync(4_000) await extendedTermination }, }, ], async () => { await cleanupContract1() }, ) }, 20000) it('aborts pending RPCs and preserves the abort reason', async () => { await runScenarios( [ { name: 'uses RPC_ABORTED and preserves the abort reason as the cause', run: async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) const controller = new AbortController() await client.connect() const call = client.rpc('harness.api.call', {}, controller.signal) const reason = new Error('cancelled by caller') controller.abort(reason) await expect(call).rejects.toMatchObject({ name: 'RemoteClientError', code: 'RPC_ABORTED', cause: reason, }) }, }, { name: 'aborts even when transport.send never settles', run: async () => { const transport = new LoopbackTransport() transport.sendGate = new Promise(() => undefined) const client = new RemoteClientCore(transport) const controller = new AbortController() await client.connect() const call = client.rpc('harness.api.call', {}, controller.signal) controller.abort() await expect(call).rejects.toMatchObject({ code: 'RPC_ABORTED' }) }, }, { name: 'uses RPC_ABORTED for an already-aborted signal', run: async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) const controller = new AbortController() controller.abort('cancelled before dispatch') await client.connect() await expect(client.rpc('harness.api.call', {}, controller.signal)).rejects.toMatchObject({ name: 'RemoteClientError', code: 'RPC_ABORTED', cause: 'cancelled before dispatch', }) expect(transport.sent).toHaveLength(0) }, }, ], async () => { await cleanupContract1() }, ) }, 15000) it('keeps the first termination reason when send fails after transport close', async () => { let rejectSend!: (error: Error) => void const transport = new LoopbackTransport() transport.sendGate = new Promise((_, reject) => { rejectSend = reject }) const client = new RemoteClientCore(transport) await client.connect() const call = client.rpc('harness.api.call', {}) const termination = expect(call).rejects.toMatchObject({ code: 'TRANSPORT_CLOSED' }) transport.drop() rejectSend(new Error('socket write failed')) await termination }) it('ignores late responses after a call has already terminated', async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) const controller = new AbortController() await client.connect() const call = client.rpc('harness.api.call', {}, controller.signal) const request = JSON.parse(new TextDecoder().decode(transport.sent[0]!)) controller.abort() await expect(call).rejects.toBeInstanceOf(RemoteClientError) transport.push(encodeMessage(createRpcResponse(request.id, { late: true }))) }) }) describe('Remote Host feature probing', () => { it('negotiates compatible Typert session generations', async () => { await runScenarios( [ { name: 'recognizes v0.1.2 Typert Remote Gateway capabilities', run: async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) await client.connect() const probing = probeRemoteHostFeatures(client) const request = JSON.parse(new TextDecoder().decode(transport.sent[0]!)) transport.push( encodeMessage( createRpcResponse(request.id, { capabilities: ['harness.remote.v1', 'harness.remote.transfer.v1'], }), ), ) await expect(probing).resolves.toMatchObject({ apiProxy: false, remoteGateway: true, remoteTransfer: true, }) }, }, { name: 'recognizes the v0.1.5 Session V3 Typert capability', run: async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) await client.connect() const probing = probeRemoteHostFeatures(client) const request = JSON.parse(new TextDecoder().decode(transport.sent[0]!)) transport.push( encodeMessage( createRpcResponse(request.id, { capabilities: ['harness.remote.v3', 'harness.remote.transfer.v1'], }), ), ) await expect(probing).resolves.toMatchObject({ apiProxy: false, remoteGateway: true, sessionFormat: 3, remoteTransfer: true, }) }, }, { name: 'rejects a Host that advertises conflicting Session generations', run: async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) await client.connect() const probing = probeRemoteHostFeatures(client) const request = JSON.parse(new TextDecoder().decode(transport.sent[0]!)) transport.push( encodeMessage( createRpcResponse(request.id, { capabilities: ['harness.remote.v1', 'harness.remote.v3'], }), ), ) await expect(probing).rejects.toMatchObject({ code: 'INVALID_MESSAGE' }) }, }, ], async () => { await cleanupContract1() }, ) }, 15000) it('falls back to ApiProxy for legacy Hosts without describe', async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) await client.connect() const probing = probeRemoteHostFeatures(client, 'v0.3.17') const request = JSON.parse(new TextDecoder().decode(transport.sent[0]!)) transport.push(encodeMessage(createRpcError(request.id, 'METHOD_NOT_FOUND', 'not found'))) await expect(probing).resolves.toMatchObject({ apiProxy: true, remoteGateway: false, commandList: true, fileViewer: true, }) }) it('parses workspaceTypes from Host description and safely handles malformed values', async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) await client.connect() const probing = probeRemoteHostFeatures(client) const request = JSON.parse(new TextDecoder().decode(transport.sent[0]!)) transport.push(encodeMessage(createRpcResponse(request.id, { capabilities: ['harness.remote.v3', 'codex.appserver.v1'], workspaceTypes: [ { id: 'codex', name: 'CodeX', capability: 'codex.appserver.v1', available: true }, { id: 999 }, // malformed entry ignored ], }))) const features = await probing expect(features.capabilities).toEqual(['harness.remote.v3', 'codex.appserver.v1']) expect(features.workspaceTypes).toEqual([ { id: 'codex', name: 'CodeX', capability: 'codex.appserver.v1', available: true }, ]) }) }) describe('RemoteTypertGateway', () => { it('dispatches alpha Gateway calls over harness.remote.call', async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) const gateway = new RemoteTypertGateway(client) await client.connect() const call = gateway.call('session/list', { args: { _request: {} } }) const request = JSON.parse(new TextDecoder().decode(transport.sent[0]!)) expect(request.payload).toMatchObject({ method: 'harness.remote.call', params: { endpoint: 'session/list', payload: { args: { _request: {} } } }, }) transport.push(encodeMessage(createRpcResponse(request.id, { ok: true, value: { items: [] } }))) await expect(call).resolves.toEqual({ items: [] }) }) it('restores binary workspace preview fields for the native Client API codec', async () => { const rpc = vi.fn(async () => ({ ok: true, value: { absolutePath: '/tmp/image.png', version: 'v1', bytes: 3, offset: 0, data: 'AP8Q', eof: true, }, })) const client = { rpc } as unknown as RemoteClientCore const result = await new RemoteTypertGateway(client).dispatch( 'workspaceFiles/readBytes', { args: { path: '/tmp/image.png', range: { offset: 0, length: 3 } } }, ) expect(result).toMatchObject({ ok: true, value: { data: expect.any(Uint8Array) } }) expect(Array.from((result as { ok: true; value: { data: Uint8Array } }).value.data)).toEqual([0, 255, 16]) }) it('keeps a transfer deadline across upload and commit and bounds the cleanup close', async () => { let now = 0 vi.spyOn(performance, 'now').mockImplementation(() => now) const calls: Array<{ method: string; options?: unknown }> = [] const rpc = vi.fn(async (method: string, _params: unknown, _signal?: unknown, options?: unknown) => { calls.push({ method, options }) now += 1_000 if (method === 'harness.remote.call') throw Object.assign(new Error('too large'), { code: 'RESPONSE_TOO_LARGE' }) if (method === 'harness.remote.transfer.commit') return { kind: 'inline', response: { ok: true, value: 'converted' } } if (method === 'harness.remote.transfer.close') return { closed: true } return { accepted: true } }) const client = { rpc } as unknown as RemoteClientCore await expect(new RemoteTypertGateway(client).call( 'officeToPdf/render', { args: {} }, undefined, { timeoutMs: 120_000 }, )).resolves.toBe('converted') expect(calls.map(call => call.method)).toEqual([ 'harness.remote.call', 'harness.remote.transfer.open', 'harness.remote.transfer.chunk', 'harness.remote.transfer.commit', 'harness.remote.transfer.close', ]) expect(calls.slice(0, 4).map(call => call.options)).toEqual([ { timeoutMs: 120_000 }, { timeoutMs: 30_000 }, { timeoutMs: 30_000 }, { timeoutMs: 118_000 }, ]) const cleanup = calls[4]?.options as { timeoutMs: number } | undefined expect(cleanup?.timeoutMs).toBeGreaterThan(0) expect(cleanup?.timeoutMs).toBeLessThanOrEqual(5_000) }) it('enforces one transfer deadline and integer per-step timeouts', async () => { await runScenarios([ { name: 'default deadline before commit', options: undefined, elapsed: 60_000, rejectedStep: 'commit' }, { name: 'explicit deadline before upload', options: { timeoutMs: 1_000 }, elapsed: 1_000, rejectedStep: 'chunk:0' }, { name: 'chunk cap without an overall override', options: { chunkTimeoutMs: 50 }, elapsed: 0, rejectedStep: undefined }, ].map(({ name, options, elapsed, rejectedStep }) => ({ name, run: async () => { let now = 0 vi.spyOn(performance, 'now').mockImplementation(() => now) const calls: Array<{ method: string; timeoutMs?: number }> = [] const rpc = vi.fn(async (method: string, _params: unknown, _signal?: unknown, opts?: { timeoutMs?: number }) => { calls.push({ method, timeoutMs: opts?.timeoutMs }) if (method === 'harness.remote.call') throw Object.assign(new Error('too large'), { code: 'RESPONSE_TOO_LARGE' }) if (method === 'harness.remote.transfer.open') now += Math.min(elapsed, 1_000) if (method === 'harness.remote.transfer.chunk') now += Math.max(0, elapsed - 1_000) if (method === 'harness.remote.transfer.commit') return { kind: 'inline', response: { ok: true, value: 'done' } } return { accepted: true } }) const call = new RemoteTypertGateway({ rpc } as unknown as RemoteClientCore).call('session/list', {}, undefined, options) if (rejectedStep) { await expect(call).rejects.toMatchObject({ code: 'RPC_TIMEOUT', details: { step: rejectedStep } }) expect(calls.some(call => call.method === `harness.remote.transfer.${rejectedStep.split(':')[0]}`)).toBe(false) } else { await expect(call).resolves.toBe('done') expect(calls.find(call => call.method.endsWith('.chunk'))?.timeoutMs).toBe(50) } expect(calls.at(-1)?.method).toBe('harness.remote.transfer.close') vi.restoreAllMocks() } }))) // Exercise RemoteClientCore's real timer validation: fractional durations // would silently fall back to its 30s default, exceeding this deadline. vi.useFakeTimers() let now = 0 vi.spyOn(performance, 'now').mockImplementation(() => now) const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) await client.connect() const call = new RemoteTypertGateway(client).call('session/list', {}, undefined, { timeoutMs: 1_000 }) const failure = expect(call).rejects.toMatchObject({ code: 'RPC_TIMEOUT' }) const answer = (index: number, value: unknown) => { const request = JSON.parse(new TextDecoder().decode(transport.sent[index]!)) transport.push(encodeMessage(createRpcResponse(request.id, value))) } const direct = JSON.parse(new TextDecoder().decode(transport.sent[0]!)) transport.push(encodeMessage(createRpcError(direct.id, 'RESPONSE_TOO_LARGE', 'too large'))) await vi.advanceTimersByTimeAsync(0) answer(1, { opened: true }) await vi.advanceTimersByTimeAsync(0) answer(2, { accepted: true }) await vi.advanceTimersByTimeAsync(0) now = 700.25 const open = JSON.parse(new TextDecoder().decode(transport.sent[1]!)) answer(3, { kind: 'chunked', transferId: open.payload.params.transferId, totalBytes: 100, totalChunks: 1 }) await vi.advanceTimersByTimeAsync(0) await vi.advanceTimersByTimeAsync(299) const close = JSON.parse(new TextDecoder().decode(transport.sent.at(-1)!)) expect(close.payload.method).toBe('harness.remote.transfer.close') answer(5, { closed: true }) await failure await client.close() }) it('does not replay a cancelled transferred call and releases the caller once the close is bounded', async () => { vi.useFakeTimers() const transport = new LoopbackTransport() const client = new RemoteClientCore(transport, 35_000) const gateway = new RemoteTypertGateway(client) const flush = () => vi.advanceTimersByTimeAsync(0) const sentMessage = (index: number) => JSON.parse(new TextDecoder().decode(transport.sent[index]!)) await client.connect() const controller = new AbortController() const call = gateway.call('officeToPdf/render', { args: {} }, controller.signal, { timeoutMs: 120_000 }) const termination = expect(call).rejects.toMatchObject({ code: 'RPC_ABORTED' }) const direct = sentMessage(0) transport.push(encodeMessage(createRpcError(direct.id, 'RESPONSE_TOO_LARGE', 'too large'))) await flush() const open = sentMessage(1) expect(open.payload).toMatchObject({ method: 'harness.remote.transfer.open' }) transport.push(encodeMessage(createRpcResponse(open.id, { opened: true }))) await flush() const chunk = sentMessage(2) expect(chunk.payload).toMatchObject({ method: 'harness.remote.transfer.chunk' }) transport.push(encodeMessage(createRpcResponse(chunk.id, { accepted: true }))) await flush() expect(sentMessage(3).payload).toMatchObject({ method: 'harness.remote.transfer.commit' }) controller.abort() await flush() const close = JSON.parse(new TextDecoder().decode(transport.sent.at(-1)!)) expect(close.payload).toMatchObject({ method: 'harness.remote.transfer.close', params: { transferId: open.payload.params.transferId }, }) const calls = transport.sent.map(data => JSON.parse(new TextDecoder().decode(data)).payload.method) expect(calls.filter(method => method === 'harness.remote.call')).toHaveLength(1) await vi.advanceTimersByTimeAsync(5_000) await termination }) it('validates bounded transfer response descriptors and lengths', async () => { await runScenarios( [ { name: 'rejects an oversized transferred response before allocating it', run: async () => { const methods: string[] = [] let transferId = '' const rpc = vi.fn(async (method: string, params: unknown) => { methods.push(method) if (method === 'harness.remote.call') throw Object.assign(new Error('too large'), { code: 'RESPONSE_TOO_LARGE' }) if (method === 'harness.remote.transfer.open') { transferId = (params as { transferId: string }).transferId return { opened: true } } if (method === 'harness.remote.transfer.commit') { return { kind: 'chunked', transferId, totalBytes: 100 * 1024 * 1024, totalChunks: 200 } } return { accepted: true } }) const client = { rpc } as unknown as RemoteClientCore await expect( new RemoteTypertGateway(client).call('officeToPdf/render', { args: {} }, undefined, { timeoutMs: 120_000, maxResponseBytes: 12 * 1024 * 1024, }), ).rejects.toMatchObject({ code: 'RESPONSE_TOO_LARGE', details: { totalBytes: 100 * 1024 * 1024, maxResponseBytes: 12 * 1024 * 1024 }, }) expect(methods).not.toContain('harness.remote.transfer.read') expect(methods).toContain('harness.remote.transfer.close') }, }, { name: 'finishes a transferred response inside the requested limit', run: async () => { let transferId = '' const rpc = vi.fn(async (method: string, params: unknown) => { if (method === 'harness.remote.call') throw Object.assign(new Error('too large'), { code: 'RESPONSE_TOO_LARGE' }) if (method === 'harness.remote.transfer.open') { transferId = (params as { transferId: string }).transferId return { opened: true } } if (method === 'harness.remote.transfer.commit') { return { kind: 'chunked', transferId, totalBytes: 11, totalChunks: 1 } } if (method === 'harness.remote.transfer.read') return { transferId, index: 0, data: btoa('{"ok":true}') } return { accepted: true } }) const client = { rpc } as unknown as RemoteClientCore await expect( new RemoteTypertGateway(client).call('officeToPdf/render', { args: {} }, undefined, { maxResponseBytes: 1024, }), ).resolves.toBeUndefined() }, }, { name: 'refuses an invalid transfer response limit instead of silently uncapping it', run: async () => { const rpc = vi.fn(async (method: string) => { if (method === 'harness.remote.call') throw Object.assign(new Error('too large'), { code: 'RESPONSE_TOO_LARGE' }) return { opened: true } }) const client = { rpc } as unknown as RemoteClientCore for (const maxResponseBytes of [Number.POSITIVE_INFINITY, 0, -1, 1.5]) { await expect( new RemoteTypertGateway(client).call('officeToPdf/render', { args: {} }, undefined, { maxResponseBytes, }), ).rejects.toMatchObject({ code: 'INVALID_MESSAGE' }) } expect(rpc).toHaveBeenCalledTimes(4) }, }, { name: 'rejects an invalid transferred descriptor before reading it', run: async () => { let transferId = '' const methods: string[] = [] const rpc = vi.fn(async (method: string, params: unknown) => { methods.push(method) if (method === 'harness.remote.call') throw Object.assign(new Error('too large'), { code: 'RESPONSE_TOO_LARGE' }) if (method === 'harness.remote.transfer.open') { transferId = (params as { transferId: string }).transferId return { opened: true } } if (method === 'harness.remote.transfer.commit') { return { kind: 'chunked', transferId, totalBytes: 11.5, totalChunks: 1 } } return { accepted: true } }) const client = { rpc } as unknown as RemoteClientCore await expect( new RemoteTypertGateway(client).call('officeToPdf/render', { args: {} }), ).rejects.toMatchObject({ code: 'INVALID_MESSAGE' }) expect(methods).not.toContain('harness.remote.transfer.read') }, }, { name: 'fails with RPC_TIMEOUT when a chunk read times out', run: async () => { let transferId = '' const rpc = vi.fn(async (method: string, params: unknown) => { if (method === 'harness.remote.call') throw Object.assign(new Error('too large'), { code: 'RESPONSE_TOO_LARGE' }) if (method === 'harness.remote.transfer.open') { transferId = (params as { transferId: string }).transferId return { opened: true } } if (method === 'harness.remote.transfer.commit') { return { kind: 'chunked', transferId: (params as { transferId: string }).transferId, totalBytes: 100, totalChunks: 1 } } if (method === 'harness.remote.transfer.read') { throw Object.assign(new Error('RPC timed out'), { code: 'RPC_TIMEOUT' }) } return { accepted: true } }) const client = { rpc } as unknown as RemoteClientCore await expect( new RemoteTypertGateway(client).call('officeToPdf/render', { args: {} }, undefined, { chunkTimeoutMs: 5_000, }), ).rejects.toMatchObject({ code: 'RPC_TIMEOUT', details: expect.objectContaining({ transferId: expect.any(String), index: 0, totalChunks: 1, }), }) }, }, { name: 'fails with TRANSFER_FAILED when a chunk read encounters a network error', run: async () => { let transferId = '' const rpc = vi.fn(async (method: string, params: unknown) => { if (method === 'harness.remote.call') throw Object.assign(new Error('too large'), { code: 'RESPONSE_TOO_LARGE' }) if (method === 'harness.remote.transfer.open') { transferId = (params as { transferId: string }).transferId return { opened: true } } if (method === 'harness.remote.transfer.commit') { return { kind: 'chunked', transferId: (params as { transferId: string }).transferId, totalBytes: 100, totalChunks: 1 } } if (method === 'harness.remote.transfer.read') { throw new Error('Connection reset by peer') } return { accepted: true } }) const client = { rpc } as unknown as RemoteClientCore await expect( new RemoteTypertGateway(client).call('officeToPdf/render', { args: {} }), ).rejects.toMatchObject({ code: 'TRANSFER_FAILED', details: expect.objectContaining({ index: 0, totalChunks: 1, }), }) }, }, { name: 'rejects invalid transfer timeout options', run: async () => { const rpc = vi.fn(async (method: string) => { if (method === 'harness.remote.call') throw Object.assign(new Error('too large'), { code: 'RESPONSE_TOO_LARGE' }) return { opened: true } }) const client = { rpc } as unknown as RemoteClientCore for (const field of ['timeoutMs', 'chunkTimeoutMs'] as const) { for (const value of [0, -1, 1.5, Number.NaN, Number.POSITIVE_INFINITY, 2_147_483_648]) { await expect( new RemoteTypertGateway(client).call('officeToPdf/render', { args: {} }, undefined, { [field]: value }), ).rejects.toMatchObject({ code: 'INVALID_MESSAGE' }) } } }, }, ], async () => { await cleanupContract1() }, ) }, 20000) it('routes Remote stream frames and closes the stream on iterator return', async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) const gateway = new RemoteTypertGateway(client) await client.connect() const opening = gateway.open('$events', { args: {} }) const request = JSON.parse(new TextDecoder().decode(transport.sent[0]!)) expect(request.payload).toMatchObject({ method: 'harness.remote.stream.open', params: { endpoint: '$events', payload: { args: {} } }, }) const streamId = request.payload.params.streamId as string transport.push(encodeMessage(createRpcResponse(request.id, {}))) const iterator = (await opening)[Symbol.asyncIterator]() transport.push(encodeMessage(createEvent('harness.remote.frame', { streamId, hasValue: true, value: { type: 'ready', clientId: 'client-1', host: { home: '/home/u' } }, }))) await expect(iterator.next()).resolves.toEqual({ done: false, value: { type: 'ready', clientId: 'client-1', host: { home: '/home/u' } }, }) const closing = iterator.return?.() await vi.waitFor(() => { const close = JSON.parse(new TextDecoder().decode(transport.sent.at(-1)!)) expect(close.payload).toMatchObject({ method: 'harness.remote.stream.close', params: { streamId }, }) }) const close = JSON.parse(new TextDecoder().decode(transport.sent.at(-1)!)) expect(close.payload).toMatchObject({ method: 'harness.remote.stream.close', params: { streamId }, }) transport.push(encodeMessage(createRpcResponse(close.id, {}))) await closing }) }) describe('CodexRemoteClient', () => { it('cleans up subscriptions when the Host closes a CodeX stream', async () => { const transport = new LoopbackTransport() const client = new RemoteClientCore(transport) const codex = new CodexRemoteClient(client) const frames: unknown[] = [] const closed: string[] = [] await client.connect() const opening = codex.subscribe('thr_1', frame => frames.push(frame), undefined, reason => closed.push(reason)) const request = JSON.parse(new TextDecoder().decode(transport.sent[0]!)) expect(request.payload).toMatchObject({ method: 'codex.app.stream.open', params: { threadId: 'thr_1' }, }) const streamId = request.payload.params.streamId as string transport.push(encodeMessage(createRpcResponse(request.id, { opened: true }))) const stream = await opening transport.push(encodeMessage(createEvent('codex.app.frame', { streamId, frame: { method: 'turn/started', params: { threadId: 'thr_1' } }, }))) expect(frames).toEqual([{ method: 'turn/started', params: { threadId: 'thr_1' } }]) transport.push(encodeMessage(createEvent('codex.app.stream.closed', { streamId, reason: 'failed' }))) expect(closed).toEqual(['failed']) transport.push(encodeMessage(createEvent('codex.app.frame', { streamId, frame: { method: 'turn/completed', params: { threadId: 'thr_1' } }, }))) expect(frames).toHaveLength(1) await stream.close() expect(transport.sent).toHaveLength(1) await client.close() }) }) class ScriptedCore { private readonly eventHandlers = new Set<(event: unknown) => void>() private readonly closeHandlers = new Set<() => void>() readonly rpcCalls: Array<{ method: string; params?: unknown }> = [] async rpc(method: string, params?: unknown): Promise { this.rpcCalls.push({ method, params }) if (method === 'harness.remote.call') { const request = params as { endpoint?: string; payload?: { args?: Record } } if (request.endpoint === '$events/result') return { ok: true, value: undefined } if (request.endpoint === 'session/list') { return { ok: true, value: { items: [{ sessionId: 'legacy-session', updatedAt: 1, running: false, blank: false, agentPreset: 'code', projections: { asOfSeq: 4, values: { agentPreset: 'code', other: 'code' }, }, }], }, } } if (request.endpoint === 'commands/execute') { return { ok: true, value: { commandId: 'permission', result: { kind: 'success' } } } } return { ok: true, value: undefined } } return {} } onEvent(handler: (event: unknown) => void): () => void { this.eventHandlers.add(handler) return () => this.eventHandlers.delete(handler) } onClose(handler: () => void): () => void { this.closeHandlers.add(handler) return () => this.closeHandlers.delete(handler) } emit(event: unknown): void { for (const handler of this.eventHandlers) handler(event) } streamIdFor(endpoint: string): string { const open = this.rpcCalls.find(call => call.method === 'harness.remote.stream.open' && (call.params as { endpoint?: string }).endpoint === endpoint) if (open === undefined) throw new Error(`missing stream ${endpoint}`) return (open.params as { streamId: string }).streamId } } describe('HarnessAlphaClient', () => { it('ignores a superseded follow snapshot and restores only the latest subscription', async () => { const core = new ScriptedCore() const frames: Array<{ rpcId: string; payload: Record }> = [] const client = new HarnessAlphaClient(core as unknown as RemoteClientCore, {}, frame => frames.push(frame)) const first = client.sessionHistory('old').then(value => value, error => error) await vi.waitFor(() => expect(core.streamIdFor('session/follow')).toBeTruthy()) const oldId = core.streamIdFor('session/follow') const second = client.sessionHistory('new') await vi.waitFor(() => expect(core.rpcCalls.filter(call => call.method === 'harness.remote.stream.open')).toHaveLength(2)) const latest = core.rpcCalls.filter(call => call.method === 'harness.remote.stream.open').at(-1)!.params as { streamId: string } core.emit({ event: 'harness.remote.frame', data: { streamId: oldId, hasValue: true, value: { type: 'snapshot', cursor: 1, records: [], projections: { asOfSeq: 1, values: { permissions: { currentValue: 'stale' } } } } } }) core.emit({ event: 'harness.remote.frame', data: { streamId: latest.streamId, hasValue: true, value: { type: 'snapshot', cursor: 10, records: [], hasMore: false, projections: { asOfSeq: 10, values: { permissions: { currentValue: 'read-only' } } } } } }) expect(await first).toMatchObject({ code: 'CANCELLED' }) expect(await second).toEqual({ events: [], hasMore: false, throughSeq: 10 }) expect(frames).toMatchObject([{ payload: { sessionId: 'new', key: 'permissions', value: { currentValue: 'read-only' } } }]) expect(frames).toHaveLength(1) await client.close() }) it('normalizes legacy code presets in history and live frames', async () => { await runScenarios( [ { name: 'normalizes legacy code preset in session list projections', run: async () => { const core = new ScriptedCore() const client = new HarnessAlphaClient(core as unknown as RemoteClientCore) const sessions = await client.sessionList() expect(sessions).toEqual([ expect.objectContaining({ sessionId: 'legacy-session', agentPreset: 'ptc', projections: { asOfSeq: 4, values: { agentPreset: 'ptc', other: 'code' }, }, }), ]) }, }, { name: 'normalizes legacy code preset in live projection frames', run: async () => { const core = new ScriptedCore() const frames: Array<{ rpcId: string; payload: Record }> = [] const client = new HarnessAlphaClient(core as unknown as RemoteClientCore, {}, (frame) => frames.push(frame), ) client.start() await vi.waitFor(() => expect(core.streamIdFor('session/control')).toBeTruthy()) core.emit({ event: 'harness.remote.frame', data: { streamId: core.streamIdFor('session/control'), hasValue: true, value: { type: 'projection', sessionId: 'legacy-session', key: 'agentPreset', value: 'code', seq: 7, }, }, }) await vi.waitFor(() => { expect(frames).toContainEqual({ rpcId: '', payload: { type: 'session/projection', sessionId: 'legacy-session', key: 'agentPreset', value: 'ptc', seq: 7, }, }) }) await client.close() }, }, ], async () => { await cleanupContract1() }, ) }, 10000) it('maps alpha approval waterfalls to legacy client frames and answers through $events/result', async () => { const core = new ScriptedCore() const frames: Array<{ rpcId: string; payload: Record }> = [] const client = new HarnessAlphaClient(core as unknown as RemoteClientCore, {}, frame => frames.push(frame)) client.start() await vi.waitFor(() => expect(core.streamIdFor('$events')).toBeTruthy()) const streamId = core.streamIdFor('$events') core.emit({ event: 'harness.remote.frame', data: { streamId, hasValue: true, value: { type: 'ready', clientId: 'client-1', host: { home: '/home/u' } } } }) core.emit({ event: 'harness.remote.frame', data: { streamId, hasValue: true, value: { type: 'waterfall', event: 'approval/request', eventId: 'approval-1', agentId: 'session-1', request: { toolName: 'edit', reason: 'needs approval' }, }, }, }) await vi.waitFor(() => { expect(frames).toContainEqual({ rpcId: 'approval-1', payload: { type: 'approval/requested', sessionId: 'session-1', approvalId: 'approval-1', toolName: 'edit', reason: 'needs approval', }, }) }) await client.respondApproval('approval-1', 'session-1', 'approval-1', 'allowed-once') expect(core.rpcCalls).toContainEqual({ method: 'harness.remote.call', params: { endpoint: '$events/result', payload: { args: { clientId: 'client-1', eventId: 'approval-1', outcome: { kind: 'result', value: 'allowed-once' }, }, }, }, }) await client.close() }) it('opens session/follow and expands packed text chunks for legacy history reducers', async () => { const core = new ScriptedCore() const client = new HarnessAlphaClient(core as unknown as RemoteClientCore) const history = client.sessionHistory('session-1') await vi.waitFor(() => expect(core.streamIdFor('session/follow')).toBeTruthy()) core.emit({ event: 'harness.remote.frame', data: { streamId: core.streamIdFor('session/follow'), hasValue: true, value: { type: 'snapshot', cursor: 9, records: [{ type: 'chunks', event: { type: 'chunkrow/text-chunks', seq: 2, time: 100, data: { turn: 1, step: 1, index: 0, dt: [5], texts: ['hel', 'lo'] }, }, }], hasMore: false, projections: { asOfSeq: 9, values: {} }, }, }, }) await expect(history).resolves.toEqual({ hasMore: false, throughSeq: 9, events: [ { event: { type: 'assistant/chunk', seq: 2, time: 100, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'hel' } } } }, { event: { type: 'assistant/chunk', seq: 3, time: 105, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'lo' } } } }, ], }) await client.close() }) it('requests and projects v0.1.5 assistant stream frames', async () => { const core = new ScriptedCore() const frames: Array<{ rpcId: string; payload: Record }> = [] const client = new HarnessAlphaClient( core as unknown as RemoteClientCore, { sessionFormat: 3 }, frame => frames.push(frame), ) const history = client.sessionHistory('session-v3') await vi.waitFor(() => expect(core.streamIdFor('session/follow')).toBeTruthy()) const streamId = core.streamIdFor('session/follow') const open = core.rpcCalls.find(call => call.method === 'harness.remote.stream.open' && (call.params as { streamId?: string }).streamId === streamId) expect(open?.params).toMatchObject({ endpoint: 'session/follow', payload: { args: { request: { assistantStream: true } } }, }) core.emit({ event: 'harness.remote.frame', data: { streamId, hasValue: true, value: { type: 'snapshot', cursor: 4, records: [{ type: 'event', event: { type: 'tool/result', seq: 4, time: 100, data: {}, sourceEventSeqs: [3], surfaceOp: { op: 'replace', startSeq: 3, endSeq: 3 }, } }], hasMore: false, projections: { asOfSeq: 4, values: {} }, assistantStream: { revision: 0 }, } } }) await expect(history).resolves.toEqual({ events: [{ event: { type: 'tool/result', seq: 4, time: 100, data: {}, sourceEventSeqs: [3], surfaceOp: { op: 'replace', startSeq: 3, endSeq: 3 }, } }], hasMore: false, throughSeq: 4 }) core.emit({ event: 'harness.remote.frame', data: { streamId, hasValue: true, value: { type: 'assistant-stream', frame: { type: 'start', attemptId: 'attempt-1', revision: 1, startedAfterSeq: 4, turn: 2, step: 1, }, } } }) core.emit({ event: 'harness.remote.frame', data: { streamId, hasValue: true, value: { type: 'assistant-stream', frame: { type: 'chunk', attemptId: 'attempt-1', revision: 2, index: 0, time: 123, chunk: { type: 'text-delta', index: 0, text: 'hello' }, }, } } }) await vi.waitFor(() => expect(frames).toContainEqual({ rpcId: '', payload: { type: 'session/event', sessionId: 'session-v3', event: { type: 'assistant/chunk', seq: 4.5, time: 123, data: { turn: 2, step: 1, chunk: { type: 'text-delta', index: 0, text: 'hello' } }, }, }, })) await client.close() }) it('re-emits pending blocking questions and approvals when sessionHistory re-opens the session', async () => { const core = new ScriptedCore() const frames: Array<{ rpcId: string; payload: Record }> = [] const client = new HarnessAlphaClient( core as unknown as RemoteClientCore, { sessionFormat: 3 }, frame => frames.push(frame), ) client.start() await vi.waitFor(() => expect(core.streamIdFor('$events')).toBeTruthy()) const eventsStreamId = core.streamIdFor('$events') core.emit({ event: 'harness.remote.frame', data: { streamId: eventsStreamId, hasValue: true, value: { type: 'ready', clientId: 'client-1', host: { sessionFormat: 3 } }, }, }) core.emit({ event: 'harness.remote.frame', data: { streamId: eventsStreamId, hasValue: true, value: { type: 'waterfall', event: 'user-questions/request', eventId: 'evt-q-1', agentId: 'session-q', request: { questions: [{ id: 'q1', question: 'Confirm?' }] }, }, }, }) core.emit({ event: 'harness.remote.frame', data: { streamId: eventsStreamId, hasValue: true, value: { type: 'waterfall', event: 'approval/request', eventId: 'evt-a-1', agentId: 'session-q', request: { toolName: 'bash', callId: 'call-1' }, }, }, }) await vi.waitFor(() => expect(frames.filter(item => item.rpcId === 'evt-q-1')).toHaveLength(1)) expect(frames.filter(item => item.rpcId === 'evt-a-1')).toHaveLength(1) const history = client.sessionHistory('session-q') await vi.waitFor(() => expect(core.streamIdFor('session/follow')).toBeTruthy()) const followStreamId = core.streamIdFor('session/follow') core.emit({ event: 'harness.remote.frame', data: { streamId: followStreamId, hasValue: true, value: { type: 'snapshot', cursor: 1, records: [], hasMore: false, projections: { asOfSeq: 1, values: {} }, }, }, }) await history expect(frames.filter(item => item.rpcId === 'evt-q-1')).toHaveLength(2) expect(frames.filter(item => item.rpcId === 'evt-a-1')).toHaveLength(2) await client.close() }) }) describe('HarnessAlphaClient.sessionAttachment', () => { const data = 'iVBORw0KGgo=' const makeCore = () => ({ rpc: vi.fn(async (method: string, params: any) => { if (method === 'harness.remote.call' && params?.endpoint === 'session/attachment') { return { ok: true, value: { attachment: { mediaType: 'image/png' }, data } } } return { ok: true, value: {} } }), }) const requestOf = (core: ReturnType) => { const call = core.rpc.mock.calls.find(([method, params]) => method === 'harness.remote.call' && params?.endpoint === 'session/attachment') return call?.[1]?.payload?.args?.request } it('keeps the id-only request for a string attachmentId', async () => { const core = makeCore() const client = new HarnessAlphaClient(core as any) await client.sessionAttachment('s1', 'att-1') expect(requestOf(core)).toEqual({ sessionId: 's1', attachmentId: 'att-1' }) }) it('keeps both attachment and attachmentId for a full reference', async () => { const core = makeCore() const client = new HarnessAlphaClient(core as any) const reference = { attachmentId: 'att-1', mediaType: 'image/png', bytes: 8, width: 4, height: 2, name: 'a.png' } const result = await client.sessionAttachment('s1', reference) expect(result.data).toBe(data) expect(requestOf(core)).toEqual({ sessionId: 's1', attachmentId: 'att-1', attachment: reference }) }) })