diff --git a/packages/client-core/tests/client-core.test.ts b/packages/client-core/tests/client-core.test.ts new file mode 100644 index 0000000..f9689b2 --- /dev/null +++ b/packages/client-core/tests/client-core.test.ts @@ -0,0 +1,1314 @@ +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 }) + }) +})