import { RemoteError, typertOwnedValue } from '@deepseek-ai/dsh-typert-protocol' import { Context, Service } from '@deepseek-ai/cordis' import type { Fiber } from '@deepseek-ai/cordis' import { describe, expect, expectTypeOf, it, vi } from 'vitest' import { z } from 'zod' import { RemoteMock } from '@deepseek-ai/dsh-remote-mock' import { apply as applyConnection, type ClientTransportHooks, type ConnectionGeneration, type ConnectionGenerationSource, type ConnectionHandle, } from '@deepseek-ai/dsh-client-connection/client' import type { InvocationDescriptor, RemoteResult, RemoteStreamHandle, TypertContextMap, TypertContextWire, TypertContext, TypertLookup, TypertRemoteScopeApi, TypertRemoteNamespace, } from '@deepseek-ai/dsh-typert-protocol' import TypertRegistry from '@deepseek-ai/dsh-typert-registry' import type { ClientRemote } from '../src/client/index.ts' import { apply, inject, RemoteStream } from '../src/client/index.ts' import { ClientUplinkQueue, RemoteStreamCarrierError, RemoteStreamMuxClient, } from '../src/client/stream-client.ts' import { parseRemoteStreamClientMessage } from '../src/stream-protocol.ts' type FixtureApprovalOutcome = 'allowed' | 'unavailable' const fixtureContextTag = Symbol('fixture-context-tag') type AgentWireId = TypertContextWire const agentId = (value: string): AgentWireId => value as AgentWireId interface FixtureAgent { readonly agentId: string } declare module '@deepseek-ai/cordis' { interface Events { /** * Test-only forwarded Host event. * @param namespace - marker payload recorded by listeners. */ 'fixture/changed'(namespace: string): void /** * Test-only forwarded Host event nobody subscribes to. * @param count - marker payload never observed. */ 'fixture/idle'(count: number): void /** * Test-only scoped waterfall forwarded through the existing Remote Event stream. * @param request - JSON-safe request payload. * @param next - delegates to the next Client listener or Host waterfall. * @returns the claimed or delegated outcome. */ 'fixture/approval'( this: Context, request: { readonly prompt: string readonly agent: FixtureAgent readonly signal?: AbortSignal }, next: () => Promise, ): Promise /** * Test-only event the Host assembly does not forward. * @param flag - marker payload never delivered. */ 'fixture/unselected'(flag: boolean): void } } declare module '@deepseek-ai/dsh-typert-protocol' { interface TypertRemoteEventSelection extends Record<'fixture/changed' | 'fixture/idle' | 'fixture/approval', true> {} interface TypertContextMap { fixture: TypertContext } interface TypertLookupMap { fixture: TypertLookup } interface TypertRemoteMap { 'probe/create': ( agentId: string, request: { readonly objective: string }, signal?: AbortSignal, ) => Promise> 'probe/maybe': (value: string | null | undefined) => Promise> 'probe/watch': (topic: string, signal?: AbortSignal) => AsyncIterable 'probe/attach': (topic: string, signal?: AbortSignal) => RemoteStreamHandle } interface TypertRemoteScopeMap { 'fixture:probe/create': ( request: { readonly objective: string }, signal?: AbortSignal, ) => Promise> 'fixture:probe/rename': ( request: { readonly objective: string }, ) => Promise> } interface TypertRemoteNamespaceMap { probe: TypertRemoteNamespace<'probe'> } } type FixtureContext = Omit & { readonly remote: ClientRemote & TypertRemoteScopeApi<'fixture'> } // Compile-time contract of `$on`: the key face is the forwarding selection and // the listener signature is the owning package's own Cordis declaration. function remoteEventContracts(remote: ClientRemote): void { remote.$on('fixture/changed', (namespace) => { void namespace }) remote.$on('fixture/approval', async function (request, next) { expectTypeOf(this).toEqualTypeOf() expectTypeOf(request.agent).toEqualTypeOf() expectTypeOf(request.signal).toEqualTypeOf() return request.prompt === '' ? next() : 'allowed' }) // @ts-expect-error -- declared in Events but outside the forwarding selection. remote.$on('fixture/unselected', () => {}) // @ts-expect-error -- not declared in Events at all. remote.$on('fixture/absent', () => {}) // @ts-expect-error -- the listener signature comes from the event declaration. remote.$on('fixture/changed', (count: number) => { void count }) } void remoteEventContracts const idSchema = z.string().min(1) const requestSchema = z.object({ objective: z.string().min(1) }) const createResultSchema = z.object({ ref: z.string().min(1) }) const renameResultSchema = z.object({ renamed: z.boolean() }) function directDescriptor(): InvocationDescriptor { return { id: '@fixture/probe#probe/create', service: 'probe', namespace: 'probe', method: 'create', invocation: { kind: 'direct' }, scope: { context: 'fixture', wire: 'agentId' }, parameters: [{ name: 'agent', wire: 'agentId', source: 'lookup', lookup: 'fixture', codec: { mode: 'strict', typeSymbol: '@fixture#AgentId', create: () => idSchema }, }, { name: 'request', wire: 'request', source: 'json', codec: { mode: 'strict', typeSymbol: '@fixture#CreateRequest', create: () => requestSchema }, }], cancellation: { parameter: 'signal' }, result: { mode: 'strict', typeSymbol: '@fixture#CreateResult', create: () => createResultSchema }, } } function contextDescriptor(): InvocationDescriptor { return { id: '@fixture/probe#probe/rename', service: 'probe', namespace: 'probe', method: 'rename', invocation: { kind: 'context', context: 'fixture', wire: 'agentId', codec: { mode: 'strict', typeSymbol: '@fixture#AgentId', create: () => idSchema }, }, parameters: [{ name: 'request', wire: 'request', source: 'json', codec: { mode: 'strict', typeSymbol: '@fixture#RenameRequest', create: () => requestSchema }, }], result: { mode: 'strict', typeSymbol: '@fixture#RenameResult', create: () => renameResultSchema }, } } function maybeDescriptor(): InvocationDescriptor { const schema = z.union([z.string(), z.null(), z.undefined()]) return { id: '@fixture/probe#probe/maybe', service: 'probe', namespace: 'probe', method: 'maybe', invocation: { kind: 'direct' }, parameters: [{ name: 'value', wire: 'value', source: 'json', acceptsUndefined: true, codec: { mode: 'strict', typeSymbol: '@fixture#MaybeValue', create: () => schema }, }], result: { mode: 'strict', typeSymbol: '@fixture#MaybeValue', create: () => schema }, } } function streamDescriptor(): InvocationDescriptor { return { id: '@fixture/probe#probe/watch', service: 'probe', namespace: 'probe', method: 'watch', mode: 'stream', invocation: { kind: 'direct' }, parameters: [{ name: 'topic', wire: 'topic', source: 'json', codec: { mode: 'strict', typeSymbol: '@fixture#Topic', create: () => z.string().min(1) }, }], cancellation: { parameter: 'signal' }, result: { mode: 'strict', typeSymbol: '@fixture#WatchItem', create: () => z.string().min(1) }, } } function attachDescriptor(): InvocationDescriptor { return { id: '@fixture/probe#probe/attach', service: 'probe', namespace: 'probe', method: 'attach', mode: 'stream', invocation: { kind: 'direct' }, parameters: [{ name: 'topic', wire: 'topic', source: 'json', codec: { mode: 'strict', typeSymbol: '@fixture#Topic', create: () => z.string().min(1) }, }], uplink: { codec: { mode: 'strict', typeSymbol: '@fixture#AttachInput', create: () => z.string() }, }, cancellation: { parameter: 'signal' }, result: { mode: 'strict', typeSymbol: '@fixture#AttachItem', create: () => z.string().min(1) }, } } type WebSocketGlobal = { WebSocket?: typeof WebSocket } class FakeWebSocket extends EventTarget { static readonly CONNECTING = 0 static readonly OPEN = 1 static readonly CLOSING = 2 static readonly CLOSED = 3 static readonly sockets: FakeWebSocket[] = [] static autoOpen = true static dispatchClose = true readonly url: string readonly sent: string[] = [] readonly closedWith: { readonly code?: number; readonly reason?: string }[] = [] readyState = FakeWebSocket.CONNECTING constructor(url: string | URL) { super() this.url = String(url) FakeWebSocket.sockets.push(this) queueMicrotask(() => { if (FakeWebSocket.autoOpen) this.open() }) } open(): void { if (this.readyState !== FakeWebSocket.CONNECTING) return this.readyState = FakeWebSocket.OPEN this.dispatchEvent(new Event('open')) } fail(): void { this.dispatchEvent(new Event('error')) } send(data: string): void { if (this.readyState !== FakeWebSocket.OPEN) throw new Error('fixture socket is not open') this.sent.push(data) } close(code?: number, reason?: string): void { this.closedWith.push({ ...(code === undefined ? {} : { code }), ...(reason === undefined ? {} : { reason }), }) if (this.readyState === FakeWebSocket.CLOSED) return if (!FakeWebSocket.dispatchClose) { this.readyState = FakeWebSocket.CLOSING return } this.drop() } drop(): void { if (this.readyState === FakeWebSocket.CLOSED) return this.readyState = FakeWebSocket.CLOSED this.dispatchEvent(new Event('close')) } receive(value: unknown): void { this.receiveRaw(typeof value === 'string' ? value : JSON.stringify(value)) } receiveRaw(data: unknown): void { this.dispatchEvent(new MessageEvent('message', { data, })) } } async function bench( call: ConnectionHandle['rpc']['call'], carrier: 'in-process' | 'web' = 'in-process', ): Promise { const { ctx } = await benchFiber(call, carrier) return ctx } async function benchFiber( call: ConnectionHandle['rpc']['call'], carrier: 'in-process' | 'web' = 'in-process', open: NonNullable = () => unexpectedInProcessStream(), ): Promise<{ readonly ctx: Context readonly client: Fiber readonly generation: GenerationHarness readonly start: ReturnType> }> { const ctx = new Context() await ctx.plugin(TypertRegistry) const rpc = carrier === 'web' ? { call } : { call, open } const generation = new GenerationHarness() const start = vi.fn(() => ({ stop: () => {} })) ctx.provide('connection', { rpc, registerGenerationSource: generation.register, start, } as unknown as ConnectionHandle) const client = ctx.plugin({ inject, apply }) await client return { ctx, client, generation, start } } async function *unexpectedInProcessStream(): AsyncGenerator { throw new Error('fixture did not install an in-process stream') } interface GenerationRun { readonly signal: AbortSignal readonly ready: Promise readonly done: Promise abort(reason?: unknown): void } class GenerationHarness { private source: ConnectionGenerationSource | undefined private active: AbortController | undefined readonly register = (source: ConnectionGenerationSource): (() => void) => { if (this.source !== undefined) throw new Error('fixture generation source already registered') this.source = source return () => { if (this.source !== source) return this.source = undefined this.active?.abort(new Error('fixture generation source removed')) this.active = undefined } } start(): GenerationRun { if (this.source === undefined) throw new Error('fixture generation source is not registered') if (this.active !== undefined) throw new Error('fixture generation is already active') const source = this.source const controller = new AbortController() this.active = controller let reportReady!: () => void const ready = new Promise((resolve) => { reportReady = resolve }) const done = Promise.resolve() .then(() => source(controller.signal, reportReady)) .finally(() => { if (this.active === controller) this.active = undefined }) void done.catch(() => undefined) return { signal: controller.signal, ready, done, abort: (reason) => { controller.abort(reason) }, } } startOverlapping(): GenerationRun { if (this.source === undefined) throw new Error('fixture generation source is not registered') const controller = new AbortController() let reportReady!: () => void const ready = new Promise((resolve) => { reportReady = resolve }) const done = Promise.resolve().then(() => this.source?.(controller.signal, reportReady)) .then(() => undefined) void done.catch(() => undefined) return { signal: controller.signal, ready, done, abort: (reason) => { controller.abort(reason) }, } } } function deferredReadiness(): { readonly promise: Promise readonly resolve: () => void readonly reject: (error: unknown) => void } { let resolve!: () => void let reject!: (error: unknown) => void const promise = new Promise((accept, decline) => { resolve = accept reject = decline }) return { promise, resolve, reject } } async function loaderReadinessBench( readiness: Promise, carrier: 'in-process' | 'web' = 'in-process', ): Promise<{ readonly client: Fiber readonly start: ReturnType> readonly stop: ReturnType void>> }> { const ctx = new Context() await ctx.plugin(TypertRegistry) const generation = new GenerationHarness() const stop = vi.fn<() => void>() const start = vi.fn(() => ({ stop })) const call = vi.fn() ctx.provide('connection', { rpc: carrier === 'web' ? { call } : { call, open: () => unexpectedInProcessStream() }, registerGenerationSource: generation.register, start, } as unknown as ConnectionHandle) ctx.provide('loader', { await: () => readiness }) const client = ctx.plugin({ inject, apply }) await client return { client, start, stop } } type EventStreamItem = | { readonly kind: 'frame'; readonly value: unknown } | { readonly kind: 'end' } | { readonly kind: 'fail'; readonly error: unknown } interface EventStreamConnection { readonly items: EventStreamItem[] wake: (() => void) | undefined } class RemoteEventCarrier { readonly calls: { readonly channel: string readonly endpoint: string readonly payload: unknown readonly signal: AbortSignal }[] = [] private readonly connections = new Set() private nextClient = 1 get activeConnections(): number { return this.connections.size } readonly open: NonNullable = (channel, endpoint, payload, signal) => { this.calls.push({ channel, endpoint, payload, signal }) return this.iterate(signal) } emit(value: unknown): void { this.feed({ kind: 'frame', value }) } end(): void { this.feed({ kind: 'end' }) } fail(error: unknown): void { this.feed({ kind: 'fail', error }) } private feed(item: EventStreamItem): void { for (const connection of this.connections) { connection.items.push(item) connection.wake?.() } } private async *iterate(signal: AbortSignal): AsyncGenerator { signal.throwIfAborted() const clientId = `event-client-${String(this.nextClient++)}` const connection: EventStreamConnection = { items: [], wake: undefined } this.connections.add(connection) const abort = (): void => { connection.wake?.() } signal.addEventListener('abort', abort, { once: true }) try { yield { type: 'ready', clientId, host: { home: '/home/fixture' } } while (!signal.aborted) { while (connection.items.length > 0) { const item = connection.items.shift() as EventStreamItem if (item.kind === 'end') return if (item.kind === 'fail') throw item.error yield item.value } if (signal.aborted) return await new Promise((resolve) => { connection.wake = resolve }) connection.wake = undefined } } finally { signal.removeEventListener('abort', abort) this.connections.delete(connection) } } } async function eventBench( call: ConnectionHandle['rpc']['call'] = vi.fn() .mockResolvedValue({ ok: true, value: undefined }), ): Promise<{ readonly ctx: Context readonly client: Fiber readonly carrier: RemoteEventCarrier readonly generation: GenerationHarness readonly run: GenerationRun readonly call: ConnectionHandle['rpc']['call'] }> { const carrier = new RemoteEventCarrier() const { ctx, client, generation } = await benchFiber( call, 'in-process', carrier.open, ) const run = generation.start() await run.ready return { ctx, client, carrier, generation, run, call } } function approvalFrame(eventId: string, agentId: string, prompt: string): object { return { type: 'waterfall', event: 'fixture/approval', eventId, agentId, request: { prompt }, } } describe('Client Remote transport readiness', () => { it('creates logical stream supervisors against the installed Connection', async () => { const { ctx, client } = await benchFiber(vi.fn()) const stream = ctx.remote.$stream({ name: 'fixture stream', open: () => unexpectedInProcessStream(), ended: () => new Error('fixture stream ended'), }) expect(stream).toBeInstanceOf(RemoteStream) await stream.dispose() await client.dispose() }) it('reports Host facts as plain reads and keeps them through Connection withdrawal', async () => { const ctx = new Context() await ctx.plugin(TypertRegistry) const generation = new GenerationHarness() const live: { snapshot: ConnectionGeneration | undefined } = { snapshot: undefined } const handle = { isLoopback: true, generation: { getSnapshot: () => live.snapshot, subscribe: () => () => {} }, rpc: { call: vi.fn(), open: () => unexpectedInProcessStream(), }, registerGenerationSource: generation.register, start: () => ({ stop: () => {} }), } as unknown as ConnectionHandle const withdraw = ctx.provide('connection', handle) const client = ctx.plugin({ inject, apply }) await client const remote = ctx.remote const beforeReady = remote.$host expect(beforeReady).toEqual({ home: undefined, isLoopback: true }) expect(remote.$host).toBe(beforeReady) live.snapshot = { id: 1, host: { home: '/hosts/primary' } } const afterReady = remote.$host expect(afterReady).toEqual({ home: '/hosts/primary', isLoopback: true }) expect(afterReady).not.toBe(beforeReady) expect(remote.$host).toBe(afterReady) withdraw() expect(ctx.get('connection')).toBeUndefined() expect(remote.$host).toBe(afterReady) }) it('forwards each connection retry to the browser WebSocket owner', async () => { await withFakeWebSocket('https://harness.example', async () => { FakeWebSocket.autoOpen = false const { client, start } = await benchFiber( vi.fn(), 'web', ) try { expect(FakeWebSocket.sockets).toHaveLength(1) start.mock.calls[0]![0].onReconnectRequested?.() await vi.waitFor(() => { expect(FakeWebSocket.sockets).toHaveLength(2) }) } finally { await client.dispose() } }) }) it.each([false, true])('replaces a stalled carrier and restores events (socket opened: %s)', async (autoOpen) => { await withFakeWebSocket('https://harness.example', async () => { vi.useFakeTimers() vi.stubGlobal('__DSH_CONNECTION_RECOVERY__', { backoffBaseMs: 10, backoffMaxMs: 10, generationReadyTimeoutMs: 100, }) Object.assign(globalThis.location, { hostname: 'harness.example', search: '' }) const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined) FakeWebSocket.autoOpen = autoOpen const ctx = new Context() const reset = vi.fn() ctx.on('connection/reset', reset) try { await ctx.plugin(TypertRegistry) await ctx.plugin({ inject: [], apply: applyConnection }) await ctx.plugin({ inject, apply }) await vi.advanceTimersByTimeAsync(0) const connection = ctx.get('connection') as ConnectionHandle expect(FakeWebSocket.sockets).toHaveLength(1) expect(connection.generation.getSnapshot()).toBeUndefined() await vi.advanceTimersByTimeAsync(110) expect(FakeWebSocket.sockets).toHaveLength(2) expect(FakeWebSocket.sockets[0]?.readyState).toBe(FakeWebSocket.CLOSED) expect(FakeWebSocket.sockets[0]?.closedWith).toHaveLength(1) expect(reset).not.toHaveBeenCalled() const replacement = FakeWebSocket.sockets[1]! replacement.open() await vi.advanceTimersByTimeAsync(0) const opening = JSON.parse(replacement.sent[0]!) as { streamId: string } replacement.receive({ type: 'item', streamId: opening.streamId, value: { type: 'ready', clientId: 'recovered-client', host: { home: '/recovered' } }, }) await vi.advanceTimersByTimeAsync(0) expect(connection.state.getSnapshot()).toBe('connected') expect(connection.generation.getSnapshot()?.host.home).toBe('/recovered') expect(reset).toHaveBeenCalledOnce() expect(vi.getTimerCount()).toBe(0) } finally { await ctx.fiber.dispose() await vi.advanceTimersByTimeAsync(0) warnSpy.mockRestore() vi.unstubAllGlobals() vi.useRealTimers() } }) }) it('does not replace an in-process carrier when Connection retries', async () => { const { client, start } = await benchFiber( vi.fn(), 'in-process', ) try { expect(() => { start.mock.calls[0]![0].onReconnectRequested?.() }).not.toThrow() } finally { await client.dispose() } }) it('starts after Loader settlement and stops the owned loop on disposal', async () => { const readiness = deferredReadiness() const { client, start, stop } = await loaderReadinessBench(readiness.promise) expect(start).not.toHaveBeenCalled() readiness.resolve() await vi.waitFor(() => { expect(start).toHaveBeenCalledTimes(1) }) await client.dispose() expect(stop).toHaveBeenCalledTimes(1) }) it('starts a fresh WebSocket attempt when Loader settles after the eager attempt failed', async () => { await withFakeWebSocket('https://harness.example', async () => { FakeWebSocket.autoOpen = false const readiness = deferredReadiness() const { client, start } = await loaderReadinessBench(readiness.promise, 'web') expect(FakeWebSocket.sockets).toHaveLength(1) FakeWebSocket.sockets[0]!.fail() readiness.resolve() await vi.waitFor(() => { expect(FakeWebSocket.sockets).toHaveLength(2) }) expect(start).toHaveBeenCalledOnce() await client.dispose() }) }) it('does not start when disposal wins the Loader-settlement race', async () => { const readiness = deferredReadiness() const { client, start, stop } = await loaderReadinessBench(readiness.promise) await client.dispose() readiness.resolve() await Promise.resolve() expect(start).not.toHaveBeenCalled() expect(stop).not.toHaveBeenCalled() }) it('leaves the transport stopped when Loader settlement rejects', async () => { const readiness = deferredReadiness() const { client, start, stop } = await loaderReadinessBench(readiness.promise) readiness.reject(new Error('fixture Loader failed')) await Promise.resolve() await Promise.resolve() expect(start).not.toHaveBeenCalled() await client.dispose() expect(stop).not.toHaveBeenCalled() }) }) describe('Client Typert API', () => { it('mounts concrete direct methods, forwards inputs, and withdraws retained handles', async () => { const call = vi.fn() .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } }) const ctx = await bench(call) const businessProbe = { owner: 'host business service' } const disposeBusinessProbe = ctx.provide('probe', businessProbe) const assembly = ctx.plugin(Object.assign( (scope: Context) => scope.remote.$mount({ package: '@fixture/probe', descriptors: [directDescriptor()] }), { inject: ['remote'] }, )) await assembly const retained = ctx.remote.probe.create await expect(ctx.remote.probe.create('agent-1', { objective: 'ship' })) .resolves.toEqual({ ok: true, value: { ref: 'goal-1' } }) expect(call).toHaveBeenCalledWith( '/api', 'probe/create', { args: { agentId: 'agent-1', request: { objective: 'ship' } } }, expect.any(AbortSignal), ) const callerAbort = new AbortController() await expect(ctx.remote.probe.create( 'agent-1', { objective: 'cancel me' }, callerAbort.signal, )).resolves.toEqual({ ok: true, value: { ref: 'goal-1' } }) const combinedSignal = call.mock.calls.at(-1)?.[3] expect(combinedSignal).toBeInstanceOf(AbortSignal) expect(combinedSignal).not.toBe(callerAbort.signal) const cancellation = new Error('caller cancelled') callerAbort.abort(cancellation) expect(combinedSignal?.aborted).toBe(true) expect(combinedSignal?.reason).toBe(cancellation) await expect(ctx.remote.probe.create('', { objective: 'ship' })) .resolves.toEqual({ ok: true, value: { ref: 'goal-1' } }) expect(call).toHaveBeenLastCalledWith( '/api', 'probe/create', { args: { agentId: '', request: { objective: 'ship' } } }, expect.any(AbortSignal), ) call.mockResolvedValueOnce({ ok: true, value: { ref: 1 } }) await expect(ctx.remote.probe.create('agent-1', { objective: 'ship' })).resolves.toEqual({ ok: true, value: { ref: 1 }, }) await assembly.dispose() expect((ctx.remote as unknown as Record).probe).toBeUndefined() expect(ctx.get('remote.probe')).toBeUndefined() expect(ctx.get('probe')).toBe(businessProbe) expect(ctx.typert.remotes.list()).toEqual([]) await expect(retained?.('agent-1', { objective: 'ship' })).resolves.toMatchObject({ ok: false, error: { code: 'gateway/internal', message: 'client api: Remote method probe/create is no longer mounted', details: {}, }, }) disposeBusinessProbe() }) it('encodes declared undefined as an omitted argument and distinguishes it from null results', async () => { const call = vi.fn() .mockResolvedValueOnce({ ok: true, value: undefined }) .mockResolvedValueOnce({ ok: true, value: null }) const ctx = await bench(call) const dispose = await ctx.remote.$mount({ package: '@fixture/maybe', descriptors: [maybeDescriptor()], }) await expect(ctx.remote.probe.maybe(undefined)).resolves.toStrictEqual({ ok: true, value: undefined }) expect(call).toHaveBeenNthCalledWith( 1, '/api', 'probe/maybe', { args: {} }, expect.any(AbortSignal), ) await expect(ctx.remote.probe.maybe(null)).resolves.toStrictEqual({ ok: true, value: null }) expect(call).toHaveBeenNthCalledWith( 2, '/api', 'probe/maybe', { args: { value: null } }, expect.any(AbortSignal), ) await dispose() }) it('projects one direct lookup descriptor onto an Agent-scoped alias', async () => { const call = vi.fn() .mockResolvedValue({ ok: true, value: { ref: 'goal-2' } }) const ctx = await bench(call) const agentCtx = ctx.extend({ fixtureId: 'agent-2' }) as FixtureContext ctx.typert.contexts.registerClient('fixture', { identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId, resolve: id => id === 'agent-2' ? agentCtx : undefined, }) const assembly = ctx.plugin(Object.assign( (scope: Context) => scope.remote.$mount({ package: '@fixture/probe', descriptors: [directDescriptor()] }), { inject: ['remote'] }, )) await assembly await expect(agentCtx.remote.probe.create({ objective: 'ship scoped' })) .resolves.toEqual({ ok: true, value: { ref: 'goal-2' } }) expect(call).toHaveBeenCalledWith( '/api', 'probe/create', { args: { agentId: 'agent-2', request: { objective: 'ship scoped' } } }, expect.any(AbortSignal), ) await expect((ctx as FixtureContext).remote.probe.create({ objective: 'wrong scope' })) .rejects.toThrow('expected 2 business argument(s)') await assembly.dispose() expect((ctx.remote as unknown as Record).probe).toBeUndefined() expect(ctx.get('remote.probe')).toBeUndefined() }) it('uses the caller Context identity for scoped namespace methods', async () => { const call = vi.fn() .mockResolvedValue({ ok: true, value: { renamed: true } }) const ctx = await bench(call) const agentCtx = ctx.extend({ fixtureId: 'agent-2' }) as FixtureContext ctx.typert.contexts.registerClient('fixture', { identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId, resolve: id => id === 'agent-2' ? agentCtx : undefined, }) const assembly = ctx.plugin(Object.assign( (scope: Context) => scope.remote.$mount({ package: '@fixture/probe', descriptors: [contextDescriptor()] }), { inject: ['remote'] }, )) await assembly await expect(agentCtx.remote.probe.rename({ objective: 'land' })) .resolves.toEqual({ ok: true, value: { renamed: true } }) expect(call).toHaveBeenCalledWith( '/api', 'probe/rename', { args: { agentId: 'agent-2', request: { objective: 'land' } } }, expect.any(AbortSignal), ) await expect((ctx as FixtureContext).remote.probe.rename({ objective: 'land' })) .rejects.toThrow('requires a "fixture" Context') await assembly.dispose() expect(ctx.get('remote.probe')).toBeUndefined() }) it('accepts weak result codecs and rejects namespace collisions before registration', async () => { const ctx = await bench(vi.fn()) const weak: InvocationDescriptor = { ...directDescriptor(), result: { mode: 'src-json' }, } const disposeWeak = await ctx.remote.$mount({ package: '@fixture/weak', descriptors: [weak] }) await disposeWeak() await expect(ctx.remote.$mount({ package: '@fixture/conflict', descriptors: [{ ...directDescriptor(), namespace: '$mount' }], })).rejects.toThrow('conflicts with the Remote service') expect(ctx.typert.remotes.list()).toEqual([]) }) it('rejects duplicate, live, scoped-service, and Context namespace collisions', async () => { const call = vi.fn() .mockResolvedValue({ ok: true, value: { renamed: true } }) const ctx = await bench(call) const agentCtx = ctx.extend({ fixtureId: 'agent-remounted' }) as FixtureContext ctx.typert.contexts.registerClient('fixture', { identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId, resolve: id => id === 'agent-remounted' ? agentCtx : undefined, }) const direct = directDescriptor() const context = contextDescriptor() await expect(ctx.remote.$mount({ package: '@fixture/direct-duplicates', descriptors: [direct, { ...direct, id: '@fixture/probe#probe/create-again' }], })).rejects.toThrow('repeats direct method') await expect(ctx.remote.$mount({ package: '@fixture/scoped-duplicates', descriptors: [context, { ...context, id: '@fixture/probe#probe/rename-again' }], })).rejects.toThrow('repeats scoped method') const disposeDirect = await ctx.remote.$mount({ package: '@fixture/direct-live', descriptors: [direct] }) await expect(ctx.remote.$mount({ package: '@fixture/direct-conflict', descriptors: [{ ...direct, id: '@fixture/other#probe/create' }], })).rejects.toThrow('direct method probe/create is already mounted') await disposeDirect() const disposeScoped = await ctx.remote.$mount({ package: '@fixture/scoped-live', descriptors: [context] }) await expect(ctx.remote.$mount({ package: '@fixture/scoped-conflict', descriptors: [{ ...context, id: '@fixture/other#probe/rename' }], })).rejects.toThrow('scoped method probe/rename is already mounted') await expect(ctx.remote.$mount({ package: '@fixture/service-method-conflict', descriptors: [{ ...context, id: '@fixture/probe#probe/remove', method: 'remove' }], })).rejects.toThrow('conflicts with its namespace service') const scopedService = ctx.get('remote.probe') as unknown as object Object.defineProperty(scopedService, 'custom', { configurable: true, value: () => undefined }) await expect(ctx.remote.$mount({ package: '@fixture/service-own-property-conflict', descriptors: [{ ...direct, id: '@fixture/probe#probe/custom', method: 'custom' }], })).rejects.toThrow('conflicts with its namespace service') Reflect.deleteProperty(scopedService, 'custom') await disposeScoped() const disposeRemoteTypert = ctx.reflect.provide('remote.typert', { owner: 'fixture' }) await expect(ctx.remote.$mount({ package: '@fixture/context-property-conflict', descriptors: [{ ...context, namespace: 'typert' }], })).rejects.toThrow('conflicts with an existing Remote namespace') await disposeRemoteTypert() const disposeMultipleScoped = await ctx.remote.$mount({ package: '@fixture/multiple-scoped', descriptors: [directDescriptor(), contextDescriptor()], }) await expect(agentCtx.remote.probe.rename({ objective: 'remounted' })) .resolves.toEqual({ ok: true, value: { renamed: true } }) expect(call).toHaveBeenLastCalledWith( '/api', 'probe/rename', { args: { agentId: 'agent-remounted', request: { objective: 'remounted' } } }, expect.any(AbortSignal), ) await disposeMultipleScoped() }) it('rolls back earlier descriptors when a later descriptor fails to install', async () => { const ctx = await bench(vi.fn()) const { scope: _scope, ...first } = directDescriptor() const second: InvocationDescriptor = { ...first, id: '@fixture/probe#probe/archive', method: 'archive', } const defineProperty = Object.defineProperty const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => { if (key === 'archive') throw new Error('fixture later-descriptor failure') return defineProperty(target, key, attributes) }) try { await expect(ctx.remote.$mount({ package: '@fixture/failing-batch', descriptors: [first, second] })) .rejects.toThrow('fixture later-descriptor failure') } finally { spy.mockRestore() } expect((ctx.remote as unknown as Record).probe).toBeUndefined() await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) }) const retry = await ctx.remote.$mount({ package: '@fixture/retry-batch', descriptors: [first, second] }) expect(ctx.remote.probe.create).toBeTypeOf('function') expect((ctx.remote.probe as Record).archive).toBeTypeOf('function') await retry() }) it('rolls back earlier namespaces when a later namespace fails to install', async () => { const ctx = await bench(vi.fn()) const { scope: _scope, ...first } = directDescriptor() const second: InvocationDescriptor = { ...first, id: '@fixture/archive#archive/store', namespace: 'archive', method: 'store', } const defineProperty = Object.defineProperty const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => { if (key === 'store') throw new Error('fixture later-namespace failure') return defineProperty(target, key, attributes) }) try { await expect(ctx.remote.$mount({ package: '@fixture/failing-namespaces', descriptors: [first, second], })).rejects.toThrow('fixture later-namespace failure') } finally { spy.mockRestore() } expect((ctx.remote as unknown as Record).probe).toBeUndefined() expect((ctx.remote as unknown as Record).archive).toBeUndefined() await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) }) const retry = await ctx.remote.$mount({ package: '@fixture/retry-namespaces', descriptors: [first, second], }) expect(ctx.remote.probe.create).toBeTypeOf('function') expect((ctx.remote as unknown as Record>).archive?.store).toBeTypeOf('function') await retry() }) it('rolls back a direct projection when its scoped projection fails to install', async () => { const ctx = await bench(vi.fn()) const disposeContext = await ctx.remote.$mount({ package: '@fixture/context-anchor', descriptors: [contextDescriptor()], }) const namespace = ctx.get('remote.probe') as unknown as { installScoped: (...args: unknown[]) => void readonly create?: unknown } const installScoped = vi.spyOn(namespace, 'installScoped').mockImplementation(() => { throw new Error('fixture scoped projection failure') }) try { await expect(ctx.remote.$mount({ package: '@fixture/direct-projection-failure', descriptors: [directDescriptor()], })).rejects.toThrow('fixture scoped projection failure') } finally { installScoped.mockRestore() } expect(namespace.create).toBeUndefined() await disposeContext() }) it('unwinds an already-installed namespace when a later namespace fails to install', async () => { const ctx = await bench(vi.fn()) const { scope: _scope, ...probe } = directDescriptor() const vault: InvocationDescriptor = { ...probe, id: '@fixture/vault#vault/seal', service: 'vault', namespace: 'vault', method: 'seal', } const defineProperty = Object.defineProperty const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => { if (key === 'seal') throw new Error('fixture later-namespace failure') return defineProperty(target, key, attributes) }) try { await expect(ctx.remote.$mount({ package: '@fixture/two-namespaces', descriptors: [probe, vault] })) .rejects.toThrow('fixture later-namespace failure') } finally { spy.mockRestore() } expect((ctx.remote as unknown as Record).probe).toBeUndefined() expect((ctx.remote as unknown as Record).vault).toBeUndefined() await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) }) }) it('rolls back an earlier scoped projection when a later descriptor fails to install', async () => { const ctx = await bench(vi.fn()) const { scope: _scope, ...direct } = directDescriptor() const failing: InvocationDescriptor = { ...direct, id: '@fixture/probe#probe/archive', method: 'archive', } const defineProperty = Object.defineProperty const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => { if (key === 'archive') throw new Error('fixture trailing failure') return defineProperty(target, key, attributes) }) try { await expect(ctx.remote.$mount({ package: '@fixture/scoped-then-failing', descriptors: [contextDescriptor(), failing], })).rejects.toThrow('fixture trailing failure') } finally { spy.mockRestore() } expect((ctx.remote as unknown as Record).probe).toBeUndefined() await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) }) }) it('keeps a namespace another contribution still populates when a group leaves', async () => { const call = vi.fn() .mockResolvedValue({ ok: true, value: { renamed: true } }) const ctx = await bench(call) const { scope: _scope, ...direct } = directDescriptor() const disposeDirect = await ctx.remote.$mount({ package: '@fixture/direct-owner', descriptors: [direct] }) const disposeScoped = await ctx.remote.$mount({ package: '@fixture/scoped-owner', descriptors: [contextDescriptor()] }) await disposeDirect() // The namespace survives its first group: the second contribution still owns methods on it. const surviving = ctx.get('remote.probe') as unknown as Record | undefined expect(surviving).toBeDefined() expect(surviving?.create).toBeUndefined() await disposeScoped() expect(ctx.get('remote.probe')).toBeUndefined() }) it('unparks a namespace dependent only after its contribution methods exist', async () => { const ctx = await bench(vi.fn()) const { scope: _scope, ...direct } = directDescriptor() let observed: string | undefined // Parked before the mount: the unpark moment is the observation — the // atomic-visibility guarantee says the service never appears methodless. const parked = ctx.inject(['remote.probe'], (probeCtx) => { observed = typeof (probeCtx.get('remote.probe') as { create?: unknown } | undefined)?.create }) const dispose = await ctx.remote.$mount({ package: '@fixture/atomic-visibility', descriptors: [direct] }) await parked expect(observed).toBe('function') await dispose() }) it('rejects weak parameter and Context codecs plus malformed scope projections', async () => { const ctx = await bench(vi.fn()) const direct = directDescriptor() const context = contextDescriptor() await expect(ctx.remote.$mount({ package: '@fixture/weak-parameter', descriptors: [{ ...direct, parameters: direct.parameters.map((parameter, index) => index === 0 ? { ...parameter, codec: { mode: 'src-json' } } : parameter), }], })).rejects.toThrow('has no strict codec') await expect(ctx.remote.$mount({ package: '@fixture/weak-context', descriptors: [{ ...context, invocation: { ...context.invocation, codec: { mode: 'src-json' } }, } as InvocationDescriptor], })).rejects.toThrow('has no strict codec') await expect(ctx.remote.$mount({ package: '@fixture/malformed-scope', descriptors: [{ ...direct, scope: { context: 'fixture', wire: 'missingId' } }], })).rejects.toThrow('scope must select its only lookup parameter') await expect(ctx.remote.$mount({ package: '@fixture/ambiguous-scope', descriptors: [{ ...direct, parameters: [...direct.parameters, { name: 'other', wire: 'otherId', source: 'lookup', lookup: 'fixture', codec: { mode: 'strict', typeSymbol: '@fixture#AgentId', create: () => idSchema }, }], }], })).rejects.toThrow('scope must select its only lookup parameter') }) it('validates invocation arity and required adapters, and requires a live Connection', async () => { const call = vi.fn() .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } }) const ctx = await bench(call) const descriptor = directDescriptor() const dispose = await ctx.remote.$mount({ package: '@fixture/probe', descriptors: [descriptor, contextDescriptor()], }) const create = ctx.remote.probe.create as unknown as (...args: unknown[]) => Promise const probe = (ctx as FixtureContext).remote.probe const rename = probe.rename as unknown as (...args: unknown[]) => Promise await expect(create('agent-1')).rejects.toThrow('expected 2 business argument(s) plus an optional AbortSignal, got 1') await expect(create('agent-1', { objective: 'ship' }, undefined, 'extra')) .rejects.toThrow('got 4') await expect(rename.call(probe)).rejects.toThrow('expected 1 argument(s), got 0') await expect((ctx as FixtureContext).remote.probe.create({ objective: 'ship' })) .rejects.toThrow('expected 2 business argument(s)') await expect((ctx as FixtureContext).remote.probe.rename({ objective: 'ship' })) .rejects.toThrow('no Client Context adapter') ctx.set('connection', undefined) await expect(ctx.remote.probe.create('agent-1', { objective: 'ship' })).rejects.toThrow('no active Connection') await dispose() }) it('withdraws a pending invocation and preserves a direct namespace until its last method leaves', async () => { let resolveCall!: (result: Awaited>) => void const pending = new Promise>>((resolve) => { resolveCall = resolve }) const call = vi.fn().mockReturnValue(pending) const ctx = await bench(call) const { scope: _scope, ...first } = directDescriptor() const second: InvocationDescriptor = { ...first, id: '@fixture/probe#probe/archive', method: 'archive', } const dispose = await ctx.remote.$mount({ package: '@fixture/probe', descriptors: [first, second] }) const invocation = ctx.remote.probe.create('agent-1', { objective: 'ship' }) await vi.waitFor(() => { expect(call).toHaveBeenCalledTimes(1) }) await dispose() resolveCall({ ok: true, value: { ref: 'goal-1' } }) await expect(invocation).resolves.toMatchObject({ ok: false, error: { code: 'gateway/internal', message: 'client api: Remote method probe/create is no longer mounted', details: {}, }, }) expect((ctx.remote as unknown as Record).probe).toBeUndefined() }) it('keeps a namespace while another contribution still owns a method', async () => { const ctx = await bench(vi.fn()) const disposeCreate = await ctx.remote.$mount({ package: '@fixture/create-contribution', descriptors: [directDescriptor()], }) const disposeMaybe = await ctx.remote.$mount({ package: '@fixture/maybe-contribution', descriptors: [maybeDescriptor()], }) const namespace = ctx.get('remote.probe') as unknown as Record await disposeCreate() expect(ctx.get('remote.probe') !== undefined).toBe(true) expect(namespace.create).toBeUndefined() expect(namespace.maybe).toBeTypeOf('function') await disposeMaybe() expect(ctx.get('remote.probe')).toBeUndefined() }) it('fails a method obtained from a withdrawn namespace getter', async () => { const ctx = await bench(vi.fn()) const dispose = await ctx.remote.$mount({ package: '@fixture/probe', descriptors: [directDescriptor()] }) const namespace = ctx.get('remote.probe') as unknown as object const getWithdrawn = Object.getOwnPropertyDescriptor(namespace, 'create')?.get?.bind(namespace) await dispose() expect(getWithdrawn).toBeTypeOf('function') const withdrawn = getWithdrawn?.() as (...args: unknown[]) => Promise expect(() => withdrawn('agent-1', { objective: 'ship' })) .toThrow('Remote method is no longer mounted') }) it('preserves a __proto__ wire parameter as an own named argument', async () => { const call = vi.fn() .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } }) const ctx = await bench(call) const { scope: _scope, ...base } = directDescriptor() const descriptor: InvocationDescriptor = { ...base, id: '@fixture/probe#probe/prototype', method: 'prototype', parameters: [{ name: 'value', wire: '__proto__', source: 'json', codec: { mode: 'strict', typeSymbol: '@fixture#PrototypeValue', create: () => z.string() }, }], } const dispose = await ctx.remote.$mount({ package: '@fixture/prototype', descriptors: [descriptor] }) const method = (ctx.remote.probe as unknown as Record Promise>).prototype await expect(method?.('wire-value')).resolves.toEqual({ ok: true, value: { ref: 'goal-1' } }) const payload = call.mock.calls[0]?.[2] as { readonly args: Record } expect(Object.getPrototypeOf(payload.args)).toBeNull() expect(Object.hasOwn(payload.args, '__proto__')).toBe(true) expect(payload.args.__proto__).toBe('wire-value') await dispose() }) it('rolls back Remote registration when namespace Service startup fails', async () => { const ctx = await bench(vi.fn()) const defineProperty = Object.defineProperty const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => { if (key === Service.tracker) throw new Error('fixture namespace startup failure') return defineProperty(target, key, attributes) }) try { await expect(ctx.remote.$mount({ package: '@fixture/probe', descriptors: [directDescriptor()] })) .rejects.toThrow('fixture namespace startup failure') await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) }) } finally { spy.mockRestore() } const retry = await ctx.remote.$mount({ package: '@fixture/probe-retry', descriptors: [directDescriptor()] }) expect(ctx.remote.probe.create).toBeTypeOf('function') await retry() }) it('withdraws a fresh direct namespace when its first method fails to install', async () => { const ctx = await bench(vi.fn()) const defineProperty = Object.defineProperty const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => { if (key === 'create') throw new Error('fixture direct method installation failure') return defineProperty(target, key, attributes) }) try { await expect(ctx.remote.$mount({ package: '@fixture/direct-method-failure', descriptors: [directDescriptor()], })).rejects.toThrow('fixture direct method installation failure') } finally { spy.mockRestore() } expect((ctx.remote as unknown as Record).probe).toBeUndefined() await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) }) const retry = await ctx.remote.$mount({ package: '@fixture/direct-method-retry', descriptors: [directDescriptor()], }) expect(ctx.remote.probe.create).toBeTypeOf('function') await retry() }) it('withdraws a fresh scoped Service when its first method fails to install', async () => { const ctx = await bench(vi.fn()) const defineProperty = Object.defineProperty const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => { if (key === 'rename') throw new Error('fixture scoped installation failure') return defineProperty(target, key, attributes) }) try { await expect(ctx.remote.$mount({ package: '@fixture/scoped-failure', descriptors: [contextDescriptor()] })) .rejects.toThrow('fixture scoped installation failure') } finally { spy.mockRestore() } expect(ctx.get('remote.probe')).toBeUndefined() await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) }) const retry = await ctx.remote.$mount({ package: '@fixture/scoped-retry', descriptors: [contextDescriptor()] }) expect((ctx.get('remote.probe') as unknown as Record).rename).toBeTypeOf('function') await retry() }) it('unregisters an empty scoped namespace so another provider can claim its name', async () => { const ctx = await bench(vi.fn()) const dispose = await ctx.remote.$mount({ package: '@fixture/scoped', descriptors: [contextDescriptor()] }) expect(ctx.get('remote.probe')).toBeDefined() await dispose() expect(ctx.get('remote.probe')).toBeUndefined() const replacement = { owner: 'replacement' } const disposeReplacement = ctx.reflect.provide('remote.probe', replacement) expect(ctx.get('remote.probe')).toBe(replacement) await disposeReplacement() }) it('delivers an RPC failure in the error branch with the Host error verbatim', async () => { const rpcError = { code: 'gateway/internal' as const, message: 'host failed', details: {} } const ctx = await bench(vi.fn().mockResolvedValue({ ok: false, error: rpcError })) await ctx.remote.$mount({ package: '@fixture/probe', descriptors: [directDescriptor()] }) const outcome = await ctx.remote.probe.create('agent-1', { objective: 'ship' }) expect(outcome.ok).toBe(false) if (outcome.ok) throw new Error('expected the Client API invocation to report a failure') expect(outcome.error).toMatchObject(rpcError) }) it('folds a transport throw into the error branch', async () => { const ctx = await bench(vi.fn() .mockRejectedValue(new Error('carrier offline'))) await ctx.remote.$mount({ package: '@fixture/probe', descriptors: [directDescriptor()] }) await expect(ctx.remote.probe.create('agent-1', { objective: 'ship' })).resolves.toMatchObject({ ok: false, error: { code: 'gateway/internal', message: 'client api: probe/create failed: carrier offline', details: {}, }, }) }) it('folds a carrier throw that is not an Error into the error branch', async () => { const ctx = await bench(vi.fn() .mockRejectedValue('carrier exploded')) await ctx.remote.$mount({ package: '@fixture/probe', descriptors: [directDescriptor()] }) await expect(ctx.remote.probe.create('agent-1', { objective: 'ship' })).resolves.toMatchObject({ ok: false, error: { code: 'gateway/internal', message: 'client api: probe/create failed: carrier exploded', details: {}, }, }) }) it('classifies a carrier throw under a caller-aborted signal as gateway/cancelled', async () => { const controller = new AbortController() const ctx = await bench(vi.fn().mockImplementation(async () => { controller.abort() throw new Error('carrier aborted mid-flight') })) await ctx.remote.$mount({ package: '@fixture/probe', descriptors: [directDescriptor()] }) await expect(ctx.remote.probe.create('agent-1', { objective: 'ship' }, controller.signal)) .resolves.toMatchObject({ ok: false, error: { code: 'gateway/cancelled', message: 'client api: Remote invocation "probe/create" was aborted', details: {}, }, }) }) it('keeps a carrier throw under an unaborted caller signal in the internal branch', async () => { const controller = new AbortController() const ctx = await bench(vi.fn() .mockRejectedValue(new Error('carrier offline'))) await ctx.remote.$mount({ package: '@fixture/probe', descriptors: [directDescriptor()] }) await expect(ctx.remote.probe.create('agent-1', { objective: 'ship' }, controller.signal)) .resolves.toMatchObject({ ok: false, error: { code: 'gateway/internal', message: 'client api: probe/create failed: carrier offline', details: {}, }, }) }) it('owns each $on subscription in the calling fiber', async () => { const { ctx, client, carrier } = await eventBench() const seen: string[] = [] const subscriber = ctx.plugin(Object.assign( (scope: Context) => { scope.remote.$on('fixture/changed', (namespace) => { seen.push(namespace) }) }, { inject: ['remote'] }, )) await subscriber expect(carrier.calls).toEqual([expect.objectContaining({ channel: '/api', endpoint: '$events', payload: { args: {} }, })]) carrier.emit({ type: 'emit', event: 'fixture/changed', args: ['settings'] }) await vi.waitFor(() => { expect(seen).toEqual(['settings']) }) await subscriber.dispose() carrier.emit({ type: 'emit', event: 'fixture/changed', args: ['after fiber disposal'] }) await Promise.resolve() expect(seen).toEqual(['settings']) await client.dispose() expect(ctx.get('remote')).toBeUndefined() }) it('isolates throwing and rejected notification listeners', async () => { const { ctx, client, carrier } = await eventBench() const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined) const seen: string[] = [] const failingListener = (namespace: string): unknown => { if (namespace === 'sync') throw new Error('fixture listener failure') return Promise.reject(new Error('fixture async failure')) } const disposeThrowing = ctx.remote.$on('fixture/changed', failingListener) ctx.remote.$on('fixture/changed', (namespace) => { seen.push(namespace) }) try { carrier.emit({ type: 'emit', event: 'fixture/changed', args: ['sync'] }) await vi.waitFor(() => { expect(seen).toEqual(['sync']) }) carrier.emit({ type: 'emit', event: 'fixture/changed', args: ['async'] }) await vi.waitFor(() => { expect(seen).toEqual(['sync', 'async']) }) expect(consoleError).toHaveBeenCalledTimes(2) disposeThrowing() carrier.emit({ type: 'emit', event: 'fixture/changed', args: ['survivor'] }) await vi.waitFor(() => { expect(seen).toEqual(['sync', 'async', 'survivor']) }) } finally { consoleError.mockRestore() await client.dispose() } }) it('retires only its own registration when one listener subscribes twice', async () => { const { ctx, client, carrier } = await eventBench() const seen: string[] = [] const listener = (namespace: string): void => { seen.push(namespace) } const disposeFirst = ctx.remote.$on('fixture/changed', listener) ctx.remote.$on('fixture/changed', listener) carrier.emit({ type: 'emit', event: 'fixture/changed', args: ['both'] }) await vi.waitFor(() => { expect(seen).toEqual(['both', 'both']) }) disposeFirst() carrier.emit({ type: 'emit', event: 'fixture/changed', args: ['survivor'] }) await vi.waitFor(() => { expect(seen).toEqual(['both', 'both', 'survivor']) }) disposeFirst() carrier.emit({ type: 'emit', event: 'fixture/changed', args: ['still here'] }) await vi.waitFor(() => { expect(seen).toEqual(['both', 'both', 'survivor', 'still here']) }) await client.dispose() }) it('keeps the carrier handoff private', () => { expectTypeOf().toHaveProperty('$on') expectTypeOf<'$dispatch' extends keyof ClientRemote ? true : false>().toEqualTypeOf() }) it('drops an unobserved notification and accepts a null-prototype frame', async () => { const { ctx, client, carrier } = await eventBench() const seen: string[] = [] ctx.remote.$on('fixture/changed', (namespace) => { seen.push(namespace) }) carrier.emit({ type: 'emit', event: 'fixture/idle', args: [1] }) carrier.emit(Object.assign(Object.create(null) as Record, { type: 'emit', event: 'fixture/changed', args: ['null prototype'], })) await vi.waitFor(() => { expect(seen).toEqual(['null prototype']) }) await client.dispose() }) it('delegates immediately when the Agent adapter or Context is unavailable', async () => { const { ctx, client, carrier, call } = await eventBench() carrier.emit(approvalFrame('event-no-adapter', 'agent-late', 'no adapter')) await vi.waitFor(() => { expect(call).toHaveBeenCalledTimes(1) }) const target = ctx.extend() const resolve = vi.fn((id: unknown) => id === 'agent-found' ? target : undefined) ctx.typert.contexts.registerClient('agent', { identity: candidate => candidate === target ? agentId('agent-found') : undefined, resolve, }) carrier.emit(approvalFrame('event-missing-context', 'agent-missing', 'missing')) carrier.emit(approvalFrame('event-no-listener', 'agent-found', 'delegate')) await vi.waitFor(() => { expect(call).toHaveBeenCalledTimes(3) }) expect(resolve).toHaveBeenCalledTimes(2) for (const eventId of ['event-no-adapter', 'event-missing-context', 'event-no-listener']) { expect(call).toHaveBeenCalledWith( '/api', '$events/result', { args: { clientId: 'event-client-1', eventId, outcome: { kind: 'next' } } }, expect.any(AbortSignal), ) } await client.dispose() }) it('reports Agent Context resolution failures and delegates', async () => { const { ctx, client, carrier, call } = await eventBench() ctx.typert.contexts.registerClient('agent', { identity: () => undefined, resolve: () => { throw new Error('fixture Context lookup failed') }, }) const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined) try { carrier.emit(approvalFrame('event-resolve-error', 'agent-error', 'resolve')) await vi.waitFor(() => { expect(call).toHaveBeenCalledTimes(1) }) expect(consoleError).toHaveBeenCalledWith( 'client api: Remote event "fixture/approval" listener threw:', expect.objectContaining({ message: 'fixture Context lookup failed' }), ) expect(call).toHaveBeenCalledWith( '/api', '$events/result', { args: { clientId: 'event-client-1', eventId: 'event-resolve-error', outcome: { kind: 'next' }, }, }, expect.any(AbortSignal), ) } finally { consoleError.mockRestore() await client.dispose() } }) it('normalizes undefined waterfall results and rejects non-JSON results', async () => { const { ctx, client, carrier, call } = await eventBench() const target = ctx.extend() ctx.typert.contexts.registerClient('agent', { identity: candidate => candidate === target ? agentId('agent-results') : undefined, resolve: id => id === 'agent-results' ? target : undefined, }) target.remote.$on('fixture/approval', async request => request.prompt === 'undefined' ? undefined as unknown as FixtureApprovalOutcome : Symbol('not JSON') as unknown as FixtureApprovalOutcome) carrier.emit(approvalFrame('event-undefined', 'agent-results', 'undefined')) carrier.emit(approvalFrame('event-invalid', 'agent-results', 'invalid')) await vi.waitFor(() => { expect(call).toHaveBeenCalledTimes(2) }) expect(call).toHaveBeenCalledWith( '/api', '$events/result', { args: { clientId: 'event-client-1', eventId: 'event-undefined', outcome: { kind: 'result' } } }, expect.any(AbortSignal), ) expect(call).toHaveBeenCalledWith( '/api', '$events/result', { args: { clientId: 'event-client-1', eventId: 'event-invalid', outcome: { kind: 'rejected', error: { name: 'TypeError', message: 'Remote event listener result is not lossless JSON data', }, }, }, }, expect.any(AbortSignal), ) await client.dispose() }) it('holds an owned Context through handler and reply settlement', async () => { const replyEntered = Promise.withResolvers() const reply = Promise.withResolvers>>() const call = vi.fn(() => { replyEntered.resolve(undefined) return reply.promise }) const { ctx, client, carrier } = await eventBench(call) const target = ctx.extend() const release = vi.fn() const entered = Promise.withResolvers() const handler = Promise.withResolvers() ctx.typert.contexts.registerClient('agent', { identity: candidate => candidate === target ? agentId('owned-context') : undefined, resolve: () => typertOwnedValue(target, release), }) target.remote.$on('fixture/approval', async () => { entered.resolve(undefined) await handler.promise expect(release).not.toHaveBeenCalled() return 'allowed' }) try { carrier.emit(approvalFrame('owned-event', 'owned-context', 'wait')) await entered.promise expect(release).not.toHaveBeenCalled() handler.resolve(undefined) await replyEntered.promise expect(release).not.toHaveBeenCalled() reply.resolve({ ok: true, value: undefined }) await vi.waitFor(() => { expect(release).toHaveBeenCalledOnce() }) } finally { handler.resolve(undefined) reply.resolve({ ok: true, value: undefined }) await client.dispose() } }) it.each(['success', 'failure'] as const)('keeps cancelled Context ownership through handler %s and joins disposal', async (outcome) => { const { ctx, client, carrier, call } = await eventBench() const target = ctx.extend() const release = vi.fn() const entered = Promise.withResolvers() const handler = Promise.withResolvers() ctx.typert.contexts.registerClient('agent', { identity: candidate => candidate === target ? agentId('owned-cancelled') : undefined, resolve: () => typertOwnedValue(target, release), }) target.remote.$on('fixture/approval', async (request) => { if (request.signal === undefined) throw new Error('expected invocation cancellation') entered.resolve(request.signal) await handler.promise expect(release).not.toHaveBeenCalled() return 'allowed' }) let disposal: Promise | undefined try { carrier.emit(approvalFrame('owned-cancel-event', 'owned-cancelled', 'wait')) const signal = await entered.promise carrier.emit({ type: 'cancel', eventId: 'owned-cancel-event' }) await vi.waitFor(() => { expect(signal.aborted).toBe(true) }) expect(release).not.toHaveBeenCalled() let disposed = false disposal = client.dispose().then(() => { disposed = true }) expect(disposed).toBe(false) if (outcome === 'failure') handler.reject(new Error('cancelled handler failed')) else handler.resolve(undefined) await disposal expect(release).toHaveBeenCalledOnce() expect(call).not.toHaveBeenCalled() } finally { handler.resolve(undefined) await disposal await client.dispose() } }) it('fails the Connection generation when a result RPC is rejected', async () => { const call = vi.fn().mockResolvedValue({ ok: false, error: { code: 'gateway/internal', message: 'fixture result rejected', details: {} }, }) const { client, carrier, run } = await eventBench(call) carrier.emit(approvalFrame('event-result-rejected', 'agent-missing', 'respond')) await expect(run.done).rejects.toThrow('fixture result rejected') await client.dispose() }) it('filters scoped waterfall listeners and returns the first claimed result', async () => { const call = vi.fn() .mockResolvedValue({ ok: true, value: undefined }) const { ctx, client, carrier } = await eventBench(call) const target = ctx.extend({ [Context.filter](candidate: Context): boolean { const tag = (candidate as Context & { [fixtureContextTag]?: string })[fixtureContextTag] return tag === undefined || tag === 'agent-1' }, }) ctx.typert.contexts.registerClient('agent', { identity: candidate => candidate === target ? agentId('agent-1') : undefined, resolve: id => id === 'agent-1' ? target : undefined, }) const matching = ctx.extend({ [fixtureContextTag]: 'agent-1' }) const excluded = ctx.extend({ [fixtureContextTag]: 'agent-2' }) const seen: string[] = [] ctx.remote.$on('fixture/approval', async function (request, next) { expect(this).toBe(target) expect(request.agent).toBe(target) expect(request.signal).toBeInstanceOf(AbortSignal) seen.push('root') return next() }) matching.remote.$on('fixture/approval', async (_request, next) => { seen.push('matching-next') return next() }) excluded.remote.$on('fixture/approval', async () => { seen.push('excluded') return 'unavailable' }) matching.remote.$on('fixture/approval', async () => { seen.push('matching-result') return 'allowed' }) carrier.emit(approvalFrame('event-1', 'agent-1', 'ship')) await vi.waitFor(() => { expect(call).toHaveBeenCalledTimes(1) }) expect(seen).toEqual(['root', 'matching-next', 'matching-result']) expect(call).toHaveBeenCalledWith( '/api', '$events/result', { args: { clientId: 'event-client-1', eventId: 'event-1', outcome: { kind: 'result', value: 'allowed' }, }, }, expect.any(AbortSignal), ) await client.dispose() }) it('returns a scoped listener rejection to the Host', async () => { const call = vi.fn() .mockResolvedValue({ ok: true, value: undefined }) const { ctx, client, carrier } = await eventBench(call) const target = ctx.extend() ctx.typert.contexts.registerClient('agent', { identity: candidate => candidate === target ? agentId('agent-rejected') : undefined, resolve: id => id === 'agent-rejected' ? target : undefined, }) const rejection = Object.assign(new Error('the user cancelled ask_user_question'), { name: 'UserQuestionError', code: 'ASK_CANCELLED', details: { questionId: 'question-1' }, }) target.remote.$on('fixture/approval', () => Promise.reject(rejection)) carrier.emit(approvalFrame('event-rejected', 'agent-rejected', 'gateway/cancelled')) await vi.waitFor(() => { expect(call).toHaveBeenCalledTimes(1) }) expect(call).toHaveBeenCalledWith( '/api', '$events/result', { args: { clientId: 'event-client-1', eventId: 'event-rejected', outcome: { kind: 'rejected', error: { name: 'UserQuestionError', message: 'the user cancelled ask_user_question', code: 'ASK_CANCELLED', details: { questionId: 'question-1' }, }, }, }, }, expect.any(AbortSignal), ) await client.dispose() }) it('returns Context-filter failures as rejections', async () => { const call = vi.fn() .mockResolvedValue({ ok: true, value: undefined }) const { ctx, client, carrier } = await eventBench(call) const target = ctx.extend({ [Context.filter](): boolean { throw new Error('fixture Context filter failed') }, }) ctx.typert.contexts.registerClient('agent', { identity: candidate => candidate === target ? agentId('agent-filter-failure') : undefined, resolve: id => id === 'agent-filter-failure' ? target : undefined, }) ctx.remote.$on('fixture/approval', async (_request, next) => next()) carrier.emit(approvalFrame('event-filter-failure', 'agent-filter-failure', 'filter')) await vi.waitFor(() => { expect(call).toHaveBeenCalledTimes(1) }) expect(call).toHaveBeenCalledWith( '/api', '$events/result', { args: { clientId: 'event-client-1', eventId: 'event-filter-failure', outcome: { kind: 'rejected', error: { name: 'Error', message: 'fixture Context filter failed', }, }, }, }, expect.any(AbortSignal), ) await client.dispose() }) it('cancels a pending Client listener without returning a late result', async () => { const { ctx, client, carrier, call } = await eventBench() const target = ctx.extend() ctx.typert.contexts.registerClient('agent', { identity: candidate => candidate === target ? agentId('agent-cancel') : undefined, resolve: id => id === 'agent-cancel' ? target : undefined, }) const entered = Promise.withResolvers() target.remote.$on('fixture/approval', async (request) => { const signal = request.signal as AbortSignal entered.resolve(signal) await new Promise((resolve) => { if (signal.aborted) resolve() else signal.addEventListener('abort', () => { resolve() }, { once: true }) }) return 'allowed' }) carrier.emit(approvalFrame('event-cancel', 'agent-cancel', 'wait')) const deliverySignal = await entered.promise carrier.emit({ type: 'cancel', eventId: 'event-cancel' }) await vi.waitFor(() => { expect(deliverySignal.aborted).toBe(true) }) await Promise.resolve() expect(call).not.toHaveBeenCalled() await client.dispose() }) it('drops a settled listener result when cancellation wins before reply', async () => { const { ctx, client, carrier, call } = await eventBench() const target = ctx.extend() ctx.typert.contexts.registerClient('agent', { identity: candidate => candidate === target ? agentId('agent-cancel-race') : undefined, resolve: id => id === 'agent-cancel-race' ? target : undefined, }) const entered = Promise.withResolvers() const release = Promise.withResolvers() target.remote.$on('fixture/approval', async (request) => { entered.resolve(request.signal as AbortSignal) await release.promise return 'allowed' }) carrier.emit(approvalFrame('event-cancel-race', 'agent-cancel-race', 'wait')) const deliverySignal = await entered.promise carrier.emit({ type: 'cancel', eventId: 'event-cancel-race' }) await vi.waitFor(() => { expect(deliverySignal.aborted).toBe(true) }) release.resolve(undefined) await client.dispose() expect(call).not.toHaveBeenCalled() }) it('cancels pending listener work when the generation ends', async () => { const { ctx, client, carrier, run, call } = await eventBench() const target = ctx.extend() ctx.typert.contexts.registerClient('agent', { identity: candidate => candidate === target ? agentId('agent-generation') : undefined, resolve: id => id === 'agent-generation' ? target : undefined, }) const entered = Promise.withResolvers() target.remote.$on('fixture/approval', async (request) => { const signal = request.signal as AbortSignal entered.resolve(signal) await new Promise((resolve) => { if (signal.aborted) resolve() else signal.addEventListener('abort', () => { resolve() }, { once: true }) }) return 'allowed' }) carrier.emit(approvalFrame('event-generation', 'agent-generation', 'wait')) const deliverySignal = await entered.promise run.abort(new Error('fixture generation ended')) await expect(run.done).resolves.toBeUndefined() expect(deliverySignal.aborted).toBe(true) expect(call).not.toHaveBeenCalled() await client.dispose() }) it('contains a result transport failure after the generation is cancelled', async () => { const response = Promise.withResolvers() const call = vi.fn(() => response.promise) const { client, carrier, run } = await eventBench(call) carrier.emit(approvalFrame('event-late-result', 'agent-missing', 'respond')) await vi.waitFor(() => { expect(call).toHaveBeenCalledOnce() }) run.abort(new Error('fixture generation cancelled')) response.reject(new Error('fixture late result failure')) await expect(run.done).resolves.toBeUndefined() await client.dispose() }) it('normalizes a non-Error result transport failure', async () => { const call = vi.fn().mockRejectedValue('fixture transport failure') const { client, carrier, run } = await eventBench(call) carrier.emit(approvalFrame('event-result-throw', 'agent-missing', 'respond')) await expect(run.done).rejects.toMatchObject({ message: 'client api: Remote event result delivery failed', cause: 'fixture transport failure', }) await client.dispose() }) it('keeps the newer generation tracked when an overlapping generation settles', async () => { const { client, generation, run } = await eventBench() const overlapping = generation.startOverlapping() await overlapping.ready run.abort(new Error('fixture older generation ended')) await expect(run.done).resolves.toBeUndefined() overlapping.abort(new Error('fixture newer generation ended')) await expect(overlapping.done).resolves.toBeUndefined() await client.dispose() }) it('opens the forwarded-event stream on the browser Remote mux', async () => { await withFakeWebSocket('https://harness.example', async () => { const call = vi.fn() .mockResolvedValue({ ok: true, value: undefined }) const { ctx, client, generation } = await benchFiber(call, 'web') const seen: string[] = [] const target = ctx.extend() ctx.typert.contexts.registerClient('agent', { identity: candidate => candidate === target ? agentId('agent-browser') : undefined, resolve: id => id === 'agent-browser' ? target : undefined, }) ctx.remote.$on('fixture/changed', (namespace) => { seen.push(namespace) }) target.remote.$on('fixture/approval', async function (request) { expect(this).toBe(target) expect(request.agent).toBe(this) expect(request.signal).toBeInstanceOf(AbortSignal) return 'allowed' }) const run = generation.start() await vi.waitFor(() => { expect(FakeWebSocket.sockets[0]?.sent).toHaveLength(1) }) const socket = FakeWebSocket.sockets[0]! const opened = JSON.parse(socket.sent[0]!) as { streamId: string } expect(opened).toMatchObject({ type: 'open', endpoint: '$events', payload: { args: {} }, }) socket.receive({ type: 'item', streamId: opened.streamId, value: { type: 'ready', clientId: 'browser-client', host: { home: '/home/browser' } }, }) await run.ready socket.receive({ type: 'item', streamId: opened.streamId, value: { type: 'emit', event: 'fixture/changed', args: ['browser'] }, }) await vi.waitFor(() => { expect(seen).toEqual(['browser']) }) socket.receive({ type: 'item', streamId: opened.streamId, value: { type: 'waterfall', event: 'fixture/approval', eventId: 'event-browser', agentId: 'agent-browser', request: { prompt: 'browser approval' }, }, }) await vi.waitFor(() => { expect(call).toHaveBeenCalledTimes(1) }) expect(socket.sent).toHaveLength(1) expect(call).toHaveBeenCalledWith( '/api', '$events/result', { args: { clientId: 'browser-client', eventId: 'event-browser', outcome: { kind: 'result', value: 'allowed' }, }, }, expect.any(AbortSignal), ) await client.dispose() }) }) it('publishes injected Host facts after Remote events report ready', async () => { const locationDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'location') const transportDescriptor = Object.getOwnPropertyDescriptor(globalThis, '__DSH_TRANSPORT__') const mock = RemoteMock.create({ host: { home: '/home/mock' } }) Object.defineProperty(globalThis, 'location', { configurable: true, value: { hostname: '127.0.0.1', search: '' }, }) Object.defineProperty(globalThis, '__DSH_TRANSPORT__', { configurable: true, value: { rpc: mock.rpc } satisfies ClientTransportHooks, }) const ctx = new Context() try { await ctx.plugin(TypertRegistry) await ctx.plugin({ inject: [], apply: applyConnection }) await ctx.plugin({ inject, apply }) const connection = ctx.get('connection') as ConnectionHandle | undefined if (connection === undefined) throw new Error('injected Connection service is unavailable') await vi.waitFor(() => { expect(connection.generation.getSnapshot()?.host.home).toBe('/home/mock') }) } finally { await ctx.fiber.dispose() if (locationDescriptor === undefined) Reflect.deleteProperty(globalThis, 'location') else Object.defineProperty(globalThis, 'location', locationDescriptor) if (transportDescriptor === undefined) Reflect.deleteProperty(globalThis, '__DSH_TRANSPORT__') else Object.defineProperty(globalThis, '__DSH_TRANSPORT__', transportDescriptor) } }) it.each([ null, [], {}, { type: 'pending' }, { type: 'ready' }, { type: 'ready', clientId: '' }, { type: 'ready', clientId: 'client', extra: true }, { type: 'ready', clientId: 'client', host: null }, { type: 'ready', clientId: 'client', host: {} }, { type: 'ready', clientId: 'client', host: { home: 1 } }, { type: 'ready', clientId: 'client', host: { home: '/home', extra: true } }, { type: 'emit', event: 'fixture/changed', args: ['too early'] }, ])('rejects malformed forwarded-event readiness item %#', async (opening) => { const open: NonNullable = () => (async function *() { yield opening })() const { client, generation } = await benchFiber( vi.fn(), 'in-process', open, ) const run = generation.start() try { await expect(run.done).rejects.toThrow('forwarded Remote event stream did not begin with ready') } finally { await client.dispose() } }) it('propagates physical carrier failure and opens events for the replacement generation', async () => { const { ctx, client, carrier, generation, run } = await eventBench() const seen: string[] = [] ctx.remote.$on('fixture/changed', (namespace) => { seen.push(namespace) }) expect(carrier.calls).toHaveLength(1) carrier.fail(new RemoteStreamCarrierError('fixture generation lost')) await expect(run.done).rejects.toThrow('fixture generation lost') const replacement = generation.start() await replacement.ready await vi.waitFor(() => { expect(carrier.calls).toHaveLength(2) }) carrier.emit({ type: 'emit', event: 'fixture/changed', args: ['replacement'] }) await vi.waitFor(() => { expect(seen).toEqual(['replacement']) }) await client.dispose() }) it.each([ { name: 'Host failure', stop: (carrier: RemoteEventCarrier) => { carrier.fail(new RemoteError('gateway/internal', 'fixture Host failed', {})) }, message: 'fixture Host failed', }, { name: 'normal end', stop: (carrier: RemoteEventCarrier) => { carrier.end() }, message: 'forwarded Remote event stream ended unexpectedly', }, ])('fails the active generation after $name', async ({ stop, message }) => { const { ctx, client, carrier, run } = await eventBench() const seen: string[] = [] ctx.remote.$on('fixture/changed', (namespace) => { seen.push(namespace) }) stop(carrier) await expect(run.done).rejects.toThrow(message) carrier.emit({ type: 'emit', event: 'fixture/changed', args: ['too late'] }) await Promise.resolve() expect(carrier.calls).toHaveLength(1) expect(seen).toEqual([]) await client.dispose() }) it.each([ 'not an object', null, [], {}, { type: 'unknown' }, { type: 'emit', event: 'fixture/changed' }, { type: 'emit', event: 'fixture/changed', args: [], extra: true }, { type: 'emit', event: 1, args: [] }, { type: 'emit', event: '', args: [] }, { type: 'emit', event: 'fixture/changed', args: {} }, { type: 'emit', event: 'fixture/changed', args: [1n] }, { type: 'waterfall', event: 'fixture/approval', eventId: '', agentId: 'agent-1', request: {} }, { type: 'waterfall', event: 'fixture/approval', eventId: 'event-1', agentId: '', request: {} }, { type: 'waterfall', event: 'fixture/approval', eventId: 'event-1', agentId: 'agent-1', request: { agent: null }, }, { type: 'waterfall', event: 'fixture/approval', eventId: 'event-1', agentId: 'agent-1', request: { signal: null }, }, { type: 'cancel', eventId: '' }, { type: 'cancel', eventId: 'event-1', extra: true }, ])('rejects malformed forwarded-event frame %# and stops that stream', async (frame) => { const { ctx, client, carrier, run } = await eventBench() const seen: string[] = [] ctx.remote.$on('fixture/changed', (namespace) => { seen.push(namespace) }) carrier.emit(frame) await expect(run.done).rejects.toThrow('client api: invalid forwarded Remote event frame') carrier.emit({ type: 'emit', event: 'fixture/changed', args: ['too late'] }) await Promise.resolve() expect(carrier.calls).toHaveLength(1) expect(seen).toEqual([]) await client.dispose() }) it('aborts and awaits forwarded-event delivery during disposal', async () => { const { ctx, client, carrier, run } = await eventBench() ctx.remote.$on('fixture/changed', () => {}) expect(carrier.activeConnections).toBe(1) const signal = carrier.calls[0]?.signal await client.dispose() await expect(run.done).resolves.toBeUndefined() expect(signal?.aborted).toBe(true) expect(carrier.activeConnections).toBe(0) expect(ctx.get('remote')).toBeUndefined() }) it('rejects a generation when its Connection has been withdrawn', async () => { const carrier = new RemoteEventCarrier() const { ctx, client, generation } = await benchFiber( vi.fn(), 'in-process', carrier.open, ) ctx.set('connection', undefined) const run = generation.start() await expect(run.done).rejects.toThrow('$events has no active Connection') expect(carrier.calls).toEqual([]) await client.dispose() }) it('guards stream iteration across mount and Connection withdrawal', async () => { const call = vi.fn() const ctx = await bench(call) let release!: () => void const released = new Promise((resolve) => { release = resolve }) let markStarted!: () => void const started = new Promise((resolve) => { markStarted = resolve }) const source = async function *(): AsyncIterable { markStarted() await released yield 'late item' } ctx.set('connection', { rpc: { call, open: () => source() }, } as unknown as ConnectionHandle) const firstDispose = await ctx.remote.$mount({ package: '@fixture/stream-first', descriptors: [streamDescriptor()], }) // The handle opens its stream when the method is called; the mount is withdrawn before the first item arrives. const active = ctx.remote.probe.watch('active')[Symbol.asyncIterator]() const pending = active.next() await started await firstDispose() release() await expect(pending).rejects.toThrow('Remote method probe/watch is no longer mounted') const secondDispose = await ctx.remote.$mount({ package: '@fixture/stream-second', descriptors: [streamDescriptor()], }) ctx.set('connection', undefined) expect(() => ctx.remote.probe.watch('offline')).toThrow('probe/watch has no active Connection') // A method function read before the withdrawal keeps its mount token and refuses afterwards. const retained = ctx.remote.probe.watch await secondDispose() expect(() => retained('withdrawn')).toThrow('Remote method probe/watch is no longer mounted') }) it('publishes a namespace only after every contributed method is installed', async () => { const ctx = await bench(vi.fn()) let visible: string[] | undefined const consumer = ctx.plugin({ inject: ['remote.probe'], apply(scope) { const namespace = scope.get('remote.probe') as unknown as Record visible = [typeof namespace.watch, typeof namespace.archive] }, }) const archive: InvocationDescriptor = { ...streamDescriptor(), id: '@fixture/probe#probe/archive', method: 'archive', } const dispose = await ctx.remote.$mount({ package: '@fixture/atomic-namespace', descriptors: [streamDescriptor(), archive], }) await consumer.await() expect(visible).toEqual(['function', 'function']) await dispose() }) it('normalizes worker-local structural stream failures without sharing class identity', async () => { const cases = [{ failure: Object.assign(new Error('fixture Host rejected the stream'), { dshRemoteStreamFailure: { kind: 'remote' as const, code: 'fixture/rejected', details: { retry: false }, }, }), assert: (error: unknown) => { expect(error).toBeInstanceOf(RemoteError) expect(error).toMatchObject({ code: 'fixture/rejected', message: 'fixture Host rejected the stream', details: { retry: false }, }) }, }, { failure: Object.assign(new Error('worker carrier stopped'), { dshRemoteStreamFailure: { kind: 'carrier' as const }, }), assert: (error: unknown) => { expect(error).toBeInstanceOf(RemoteStreamCarrierError) expect(error).toMatchObject({ message: 'worker carrier stopped' }) }, }, { failure: 'caller abort sentinel', assert: (error: unknown) => { expect(error).toBe('caller abort sentinel') }, }] for (const testCase of cases) { const open: NonNullable = () => (async function *(): AsyncGenerator { throw testCase.failure })() const { ctx, client } = await benchFiber( vi.fn(), 'in-process', open, ) const dispose = await ctx.remote.$mount({ package: '@fixture/worker-stream', descriptors: [streamDescriptor()] }) try { const error = await ctx.remote.probe.watch('failure')[Symbol.asyncIterator]().next() .then(() => undefined, (reason: unknown) => reason) testCase.assert(error) } finally { await dispose() await client.dispose() } } }) it('multiplexes Remote streams without using the Connection RPC caller', async () => { const originalWebSocket = globalThis.WebSocket const documentDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'document') ;(globalThis as WebSocketGlobal).WebSocket = FakeWebSocket as unknown as typeof WebSocket Object.defineProperty(globalThis, 'document', { configurable: true, value: { baseURI: 'https://harness.example/' }, }) FakeWebSocket.sockets.length = 0 const call = vi.fn() const ctx = await bench(call, 'web') expect(FakeWebSocket.sockets).toHaveLength(1) const dispose = await ctx.remote.$mount({ package: '@fixture/stream', descriptors: [streamDescriptor()] }) try { const first = ctx.remote.probe.watch('alpha')[Symbol.asyncIterator]() const firstItem = first.next() await vi.waitFor(() => { expect(FakeWebSocket.sockets[0]?.sent).toHaveLength(1) }) const socket = FakeWebSocket.sockets[0]! expect(socket.url).toBe('wss://harness.example/api/remote.mux') const opened = JSON.parse(socket.sent[0]!) as { streamId: string } expect(opened).toMatchObject({ type: 'open', endpoint: 'probe/watch', payload: { args: { topic: 'alpha' } }, }) socket.receive({ type: 'item', streamId: opened.streamId, value: 'alpha:one' }) await expect(firstItem).resolves.toEqual({ done: false, value: 'alpha:one' }) const firstEnd = first.next() socket.receive({ type: 'end', streamId: opened.streamId }) await expect(firstEnd).resolves.toEqual({ done: true, value: undefined }) const failed = ctx.remote.probe.watch('failure')[Symbol.asyncIterator]() const failedItem = failed.next() await vi.waitFor(() => { expect(socket.sent).toHaveLength(2) }) const failedOpen = JSON.parse(socket.sent[1]!) as { streamId: string } socket.receive({ type: 'error', streamId: failedOpen.streamId, error: { code: 'gateway/lookup-unavailable', message: 'fixture stream failed', details: { lookup: 'missing' }, }, }) await expect(failedItem).rejects.toMatchObject({ name: 'RemoteError', code: 'gateway/lookup-unavailable', message: 'fixture stream failed', details: { lookup: 'missing' }, }) const abort = new AbortController() const cancelled = ctx.remote.probe.watch('cancel', abort.signal)[Symbol.asyncIterator]() const cancelledItem = cancelled.next() await vi.waitFor(() => { expect(socket.sent).toHaveLength(3) }) const cancelledOpen = JSON.parse(socket.sent[2]!) as { streamId: string } const cancellation = new Error('caller cancelled') socket.receive({ type: 'item', streamId: cancelledOpen.streamId, value: 'already queued' }) abort.abort(cancellation) socket.receive({ type: 'item', streamId: cancelledOpen.streamId, value: 'after cancellation' }) await expect(cancelledItem).rejects.toBe(cancellation) await vi.waitFor(() => { expect(socket.sent.map(text => JSON.parse(text) as unknown)).toContainEqual({ type: 'cancel', streamId: cancelledOpen.streamId, }) }) expect(call).not.toHaveBeenCalled() } finally { await dispose() await ctx.fiber.dispose() FakeWebSocket.sockets.length = 0 FakeWebSocket.autoOpen = true FakeWebSocket.dispatchClose = true if (originalWebSocket === undefined) delete (globalThis as WebSocketGlobal).WebSocket else globalThis.WebSocket = originalWebSocket if (documentDescriptor === undefined) Reflect.deleteProperty(globalThis, 'document') else Object.defineProperty(globalThis, 'document', documentDescriptor) } }) it('hands the handle uplink to the in-process carrier and echoes it through remote-mock', async () => { const mock = RemoteMock.create().stream('probe/attach', async (args, stream) => { const [{ topic }] = args as [{ readonly topic: string }] for await (const item of stream.uplink) stream.push(`${topic}:${String(item)}`) stream.end() }) const call = vi.fn() const { ctx, client } = await benchFiber(call, 'in-process', mock.rpc.open) await expect(ctx.remote.$mount({ package: '@fixture/weak-uplink', descriptors: [{ ...attachDescriptor(), uplink: { codec: { mode: 'src-json' } } }], })).rejects.toThrow('client api: generated Remote probe/attach field "uplink" has no strict codec') const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { const alpha = ctx.remote.probe.attach('alpha') alpha.send('a') alpha.send('b') alpha.end() alpha.end() await expect(drainStream(alpha)).resolves.toEqual(['alpha:a', 'alpha:b']) expect(() => { alpha.send('late') }).toThrow('client api: probe/attach stream has terminated') const beta = ctx.remote.probe.attach('beta', new AbortController().signal) beta.send('c') expect(() => { beta.end(); beta.send('d') }).toThrow('client api: probe/attach uplink was ended') await expect(drainStream(beta)).resolves.toEqual(['beta:c']) expect(mock.log.streams('probe/attach').map(open => open.args)).toEqual([[{ topic: 'alpha' }], [{ topic: 'beta' }]]) // Arity is a runtime contract, so the topic is deliberately omitted through Reflect. expect(() => { Reflect.apply(ctx.remote.probe.attach, ctx.remote.probe, []) }).toThrow( 'client api: probe/attach expected 1 business argument(s) plus an optional AbortSignal, got 0', ) expect(call).not.toHaveBeenCalled() } finally { await dispose() await client.dispose() } }) it('sends handle uplink items as wire frames, queued until the open frame, and half-closes on end', async () => { await withFakeWebSocket('https://harness.example/', async () => { const ctx = await bench(vi.fn(), 'web') const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { const handle = ctx.remote.probe.attach('alpha') handle.send('a') handle.send('b') handle.end() const stream = handle[Symbol.asyncIterator]() const first = stream.next() const socket = FakeWebSocket.sockets[0]! await vi.waitFor(() => { expect(socket.sent).toHaveLength(4) }) const frames = socket.sent.map(text => parseRemoteStreamClientMessage(text)) const opened = frames[0] if (opened?.type !== 'open') throw new Error('fixture expected the open frame first') expect(opened).toMatchObject({ endpoint: 'probe/attach', payload: { args: { topic: 'alpha' } } }) expect(frames.slice(1)).toEqual([ { type: 'item', streamId: opened.streamId, value: 'a' }, { type: 'item', streamId: opened.streamId, value: 'b' }, { type: 'end', streamId: opened.streamId }, ]) socket.receive({ type: 'item', streamId: opened.streamId, value: 'alpha:a' }) await expect(first).resolves.toEqual({ done: false, value: 'alpha:a' }) const ended = stream.next() socket.receive({ type: 'end', streamId: opened.streamId }) await expect(ended).resolves.toEqual({ done: true, value: undefined }) expect(socket.sent).toHaveLength(4) expect(() => { handle.send('late') }).toThrow('client api: probe/attach stream has terminated') handle.end() expect(socket.sent).toHaveLength(4) } finally { await dispose() await ctx.fiber.dispose() } }) }) it('terminates the handle uplink when the downlink ends first', async () => { await withFakeWebSocket('https://harness.example/', async () => { const ctx = await bench(vi.fn(), 'web') const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { const handle = ctx.remote.probe.attach('alpha') const stream = handle[Symbol.asyncIterator]() const pending = stream.next() handle.send('first') const socket = FakeWebSocket.sockets[0]! await vi.waitFor(() => { expect(socket.sent).toHaveLength(2) }) const opened = JSON.parse(socket.sent[0]!) as { streamId: string } socket.receive({ type: 'end', streamId: opened.streamId }) await expect(pending).resolves.toEqual({ done: true, value: undefined }) expect(() => { handle.send('second') }).toThrow('client api: probe/attach stream has terminated') expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'item']) } finally { await dispose() await ctx.fiber.dispose() } }) }) it('sends cancel and ends the downlink quietly when the handle is disposed', async () => { await withFakeWebSocket('https://harness.example/', async () => { const ctx = await bench(vi.fn(), 'web') const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { const handle = ctx.remote.probe.attach('alpha') const pending = handle[Symbol.asyncIterator]().next() const socket = FakeWebSocket.sockets[0]! await vi.waitFor(() => { expect(socket.sent).toHaveLength(1) }) handle.dispose() handle.dispose() await expect(pending).resolves.toEqual({ done: true, value: undefined }) expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'cancel']) expect(() => { handle.send('after dispose') }).toThrow('client api: probe/attach stream has terminated') // Breaking out of the iteration early is the same as dispose(). const second = ctx.remote.probe.attach('beta') const iterator = second[Symbol.asyncIterator]() const opened = iterator.next() await vi.waitFor(() => { expect(socket.sent).toHaveLength(3) }) const betaId = (JSON.parse(socket.sent[2]!) as { streamId: string }).streamId socket.receive({ type: 'item', streamId: betaId, value: 'beta:1' }) await expect(opened).resolves.toEqual({ done: false, value: 'beta:1' }) await expect(iterator.return?.()).resolves.toEqual({ done: true, value: undefined }) expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)) .toEqual(['open', 'cancel', 'open', 'cancel']) expect(() => { second.send('late') }).toThrow('client api: probe/attach stream has terminated') } finally { await dispose() await ctx.fiber.dispose() } }) }) it('sends cancel on dispose while nobody reads, and drops what was buffered', async () => { await withFakeWebSocket('https://harness.example/', async () => { const ctx = await bench(vi.fn(), 'web') const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { const handle = ctx.remote.probe.attach('alpha') const iterator = handle[Symbol.asyncIterator]() const socket = FakeWebSocket.sockets[0]! await vi.waitFor(() => { expect(socket.sent).toHaveLength(1) }) const opened = JSON.parse(socket.sent[0]!) as { streamId: string } socket.receive({ type: 'item', streamId: opened.streamId, value: 'alpha:1' }) await expect(iterator.next()).resolves.toEqual({ done: false, value: 'alpha:1' }) // No read is pending: the cancel still goes out on dispose, and the buffered item is dropped. socket.receive({ type: 'item', streamId: opened.streamId, value: 'alpha:2' }) handle.dispose() await vi.waitFor(() => { expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'cancel']) }) await expect(iterator.next()).resolves.toEqual({ done: true, value: undefined }) expect(() => { handle.send('late') }).toThrow('client api: probe/attach stream has terminated') } finally { await dispose() await ctx.fiber.dispose() } }) }) it('ends the uplink the moment a terminal frame arrives, before the consumer reads it', async () => { await withFakeWebSocket('https://harness.example/', async () => { const ctx = await bench(vi.fn(), 'web') const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { const handle = ctx.remote.probe.attach('alpha') handle.send('a') const socket = FakeWebSocket.sockets[0]! await vi.waitFor(() => { expect(socket.sent).toHaveLength(2) }) const opened = JSON.parse(socket.sent[0]!) as { streamId: string } socket.receive({ type: 'end', streamId: opened.streamId }) expect(() => { handle.send('after end') }).toThrow('client api: probe/attach stream has terminated') handle.end() await expect(drainStream(handle)).resolves.toEqual([]) expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'item']) } finally { await dispose() await ctx.fiber.dispose() } }) }) it('ignores server frames for a stream it no longer tracks', async () => { await withFakeWebSocket('https://harness.example/', async () => { const ctx = await bench(vi.fn(), 'web') const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { const alpha = ctx.remote.probe.attach('alpha') const socket = FakeWebSocket.sockets[0]! await vi.waitFor(() => { expect(socket.sent).toHaveLength(1) }) const alphaId = (JSON.parse(socket.sent[0]!) as { streamId: string }).streamId const beta = ctx.remote.probe.attach('beta') await vi.waitFor(() => { expect(socket.sent).toHaveLength(2) }) const betaId = (JSON.parse(socket.sent[1]!) as { streamId: string }).streamId alpha.dispose() await vi.waitFor(() => { expect(socket.sent).toHaveLength(3) }) // The Host's end for alpha crosses the cancel on the wire, so no stream owns that id any more; a // never-opened id is just as unknown. Neither frame disturbs beta or the socket. socket.receive({ type: 'end', streamId: alphaId }) socket.receive({ type: 'item', streamId: 'never-opened', value: 'stray' }) socket.receive({ type: 'item', streamId: betaId, value: 'beta:1' }) socket.receive({ type: 'end', streamId: betaId }) await expect(drainStream(beta)).resolves.toEqual(['beta:1']) expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'open', 'cancel']) expect(socket.closedWith).toEqual([]) } finally { await dispose() await ctx.fiber.dispose() } }) }) it('swallows a carrier iterator whose return() rejects on dispose', async () => { // One item, then silence: dispose reaches the carrier's return() while the stream is suspended at that item. const next = vi.fn<() => Promise>>() .mockResolvedValueOnce({ value: 'alpha:1', done: false }) .mockReturnValue(new Promise>(() => {})) const returned = vi.fn<() => Promise>>() .mockRejectedValueOnce(new Error('carrier return failed')) .mockResolvedValue({ value: undefined, done: true }) const open: NonNullable = () => ({ [Symbol.asyncIterator]: () => ({ next, return: returned }), }) const { ctx, client } = await benchFiber(vi.fn(), 'in-process', open) const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { const handle = ctx.remote.probe.attach('alpha') const iterator = handle[Symbol.asyncIterator]() await expect(iterator.next()).resolves.toEqual({ done: false, value: 'alpha:1' }) handle.dispose() await vi.waitFor(() => { expect(returned).toHaveBeenCalledOnce() }) // The rejection is swallowed (an unhandled rejection would fail this test) and the iteration ends quietly. await expect(iterator.next()).resolves.toEqual({ done: true, value: undefined }) } finally { await dispose() await client.dispose() } }) it('sends a top-level undefined item as an item frame without value', async () => { await withFakeWebSocket('https://harness.example/', async () => { const ctx = await bench(vi.fn(), 'web') const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { const handle: RemoteStreamHandle = ctx.remote.probe.attach('alpha') handle.send(undefined) expect(() => { handle.send({ nested: undefined }) }).toThrow('is not a lossless JSON value') const socket = FakeWebSocket.sockets[0]! await vi.waitFor(() => { expect(socket.sent).toHaveLength(2) }) const opened = JSON.parse(socket.sent[0]!) as { streamId: string } const item = JSON.parse(socket.sent[1]!) as Record expect(item).toEqual({ type: 'item', streamId: opened.streamId }) expect(Object.keys(item)).toEqual(['type', 'streamId']) handle.dispose() } finally { await dispose() await ctx.fiber.dispose() } }) }) it('disposes on an iterator return that precedes the first read', async () => { await withFakeWebSocket('https://harness.example/', async () => { const ctx = await bench(vi.fn(), 'web') const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { const handle = ctx.remote.probe.attach('alpha') const socket = FakeWebSocket.sockets[0]! await vi.waitFor(() => { expect(socket.sent).toHaveLength(1) }) await expect(handle[Symbol.asyncIterator]().return?.()).resolves.toEqual({ done: true, value: undefined }) await vi.waitFor(() => { expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'cancel']) }) expect(() => { handle.send('late') }).toThrow('client api: probe/attach stream has terminated') } finally { await dispose() await ctx.fiber.dispose() } }) }) it('closes the uplink when the stream fails to open and keeps the failure for the reader', async () => { const open: NonNullable = () => ({ [Symbol.asyncIterator]: () => ({ next: () => Promise.reject(new Error('handshake failed')) }), }) const { ctx, client } = await benchFiber(vi.fn(), 'in-process', open) const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { const handle = ctx.remote.probe.attach('alpha') await vi.waitFor(() => { expect(() => { handle.send('late') }).toThrow('client api: probe/attach stream has terminated') }) await expect(drainStream(handle)).rejects.toThrow('handshake failed') } finally { await dispose() await client.dispose() } }) it('refuses an uplink item that is not a lossless JSON value', async () => { const mock = RemoteMock.create().stream('probe/attach', async (args, stream) => { const [{ topic }] = args as [{ readonly topic: string }] for await (const item of stream.uplink) stream.push(`${topic}:${String(item)}`) stream.end() }) const { ctx, client } = await benchFiber(vi.fn(), 'in-process', mock.rpc.open) const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { // Widened to the loosest caller `send` accepts: the check is on the value, not on the generated type. const handle: RemoteStreamHandle = ctx.remote.probe.attach('alpha') expect(() => { handle.send(1n) }).toThrow('client api: probe/attach uplink item is not a lossless JSON value') expect(() => { handle.send(Number.NaN) }).toThrow('is not a lossless JSON value') handle.send('ok') handle.end() await expect(drainStream(handle)).resolves.toEqual(['alpha:ok']) } finally { await dispose() await client.dispose() } }) it('lets one uplink read wait at a time', async () => { const queue = new ClientUplinkQueue('probe/attach') const first = queue.next() await expect(queue.next()).rejects.toThrow('client api: probe/attach uplink has one pending read') queue.push('x') await expect(first).resolves.toEqual({ value: 'x', done: false }) queue.end() await expect(queue.next()).resolves.toEqual({ value: undefined, done: true }) expect(() => { queue.push('late') }).toThrow('client api: probe/attach uplink was ended') await expect(queue.return()).resolves.toEqual({ value: undefined, done: true }) expect(() => { queue.push('closed') }).toThrow('client api: probe/attach stream has terminated') }) it('sends cancel and fails the downlink when the caller signal aborts', async () => { await withFakeWebSocket('https://harness.example/', async () => { const ctx = await bench(vi.fn(), 'web') const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] }) try { const abort = new AbortController() const handle = ctx.remote.probe.attach('alpha', abort.signal) const pending = handle[Symbol.asyncIterator]().next() const socket = FakeWebSocket.sockets[0]! await vi.waitFor(() => { expect(socket.sent).toHaveLength(1) }) const reason = new Error('caller left') abort.abort(reason) await expect(pending).rejects.toBe(reason) expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'cancel']) expect(() => { handle.send('after abort') }).toThrow('client api: probe/attach stream has terminated') expect(() => handle[Symbol.asyncIterator]().next()).toThrow('client api: probe/attach stream has one consumer') } finally { await dispose() await ctx.fiber.dispose() } }) }) }) describe('Remote stream client carrier lifecycle', () => { it('connects to the shell-owned Host while the document uses a local asset origin', async () => { await withFakeWebSocket('dsh-app://app', async () => { vi.stubGlobal('__DSH_TRANSPORT__', { streamBaseUrl: 'http://127.0.0.1:43210' }) const client = new RemoteStreamMuxClient() try { client.start() expect(FakeWebSocket.sockets[0]!.url).toBe('ws://127.0.0.1:43210/api/remote.mux') } finally { await client.close() vi.unstubAllGlobals() } }) }) it('fails the downlink and cancels when an uplink iterable throws, and swallows a rejecting uplink return()', async () => { await withFakeWebSocket('https://harness.example', async () => { const client = new RemoteStreamMuxClient() client.start() const socket = FakeWebSocket.sockets[0]! const exploding = (async function* (): AsyncGenerator { yield 'a' throw new Error('uplink exploded') })() const pending = client.open('probe/attach', {}, new AbortController().signal, exploding)[Symbol.asyncIterator]().next() await expect(pending).rejects.toThrow('uplink exploded') expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'item', 'cancel']) const returned = vi.fn(async (): Promise> => { throw new Error('fixture release failure') }) const stuck: AsyncIterable = { [Symbol.asyncIterator]: () => ({ next: () => new Promise>(() => {}), return: returned, }), } const abort = new AbortController() const second = client.open('probe/attach', {}, abort.signal, stuck)[Symbol.asyncIterator]().next() await vi.waitFor(() => { expect(socket.sent).toHaveLength(4) }) const reason = new Error('caller left') abort.abort(reason) await expect(second).rejects.toBe(reason) await vi.waitFor(() => { expect(returned).toHaveBeenCalledOnce() }) expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'item', 'cancel', 'open', 'cancel']) await client.close() }) }) it('requires the transport owner to start the physical carrier', async () => { const client = new RemoteStreamMuxClient() await expect(client.open('feed/follow', {}, new AbortController().signal) [Symbol.asyncIterator]().next()).rejects.toThrow('Remote stream client not started') await client.close() }) it('connects without a logical stream, waits for owner-driven retries, and stops permanently', async () => { await withFakeWebSocket('https://harness.example', async () => { FakeWebSocket.autoOpen = false const client = new RemoteStreamMuxClient() client.start() client.start() expect(FakeWebSocket.sockets).toHaveLength(1) const failed = FakeWebSocket.sockets[0]! failed.fail() await Promise.resolve() expect(FakeWebSocket.sockets).toHaveLength(1) client.reconnect() await vi.waitFor(() => { expect(FakeWebSocket.sockets).toHaveLength(2) }) const connected = FakeWebSocket.sockets[1]! connected.open() await Promise.resolve() client.start() expect(FakeWebSocket.sockets).toHaveLength(2) expect(connected.sent).toEqual([]) connected.fail() await Promise.resolve() expect(FakeWebSocket.sockets).toHaveLength(2) client.reconnect() await vi.waitFor(() => { expect(FakeWebSocket.sockets).toHaveLength(3) }) const final = FakeWebSocket.sockets[2]! final.open() await client.close() await client.close() client.start() await expect(client.open('feed/follow', {}, new AbortController().signal) [Symbol.asyncIterator]().next()).rejects.toThrow('Remote stream client disposed') expect(FakeWebSocket.sockets).toHaveLength(3) expect(final.closedWith).toContainEqual({ code: 1000, reason: 'disposed' }) const stopping = new RemoteStreamMuxClient() stopping.start() const racing = FakeWebSocket.sockets[3]! racing.open() racing.drop() await stopping.close() expect(FakeWebSocket.sockets).toHaveLength(4) }) }) it('mints a new wire stream id when the same endpoint opens on a replacement socket', async () => { await withFakeWebSocket('https://harness.example', async () => { const client = new RemoteStreamMuxClient() client.start() const first = client.open('feed/follow', { label: 'same' }, new AbortController().signal) [Symbol.asyncIterator]() const firstPending = first.next() await vi.waitFor(() => { expect(FakeWebSocket.sockets[0]?.sent).toHaveLength(1) }) const firstSocket = FakeWebSocket.sockets[0]! const firstOpen = JSON.parse(firstSocket.sent[0]!) as { streamId: string } firstSocket.receive({ type: 'end', streamId: firstOpen.streamId }) await expect(firstPending).resolves.toEqual({ done: true, value: undefined }) client.reconnect() await vi.waitFor(() => { expect(FakeWebSocket.sockets).toHaveLength(2) }) const second = client.open('feed/follow', { label: 'same' }, new AbortController().signal) [Symbol.asyncIterator]() const secondPending = second.next() const secondSocket = FakeWebSocket.sockets[1]! await vi.waitFor(() => { expect(secondSocket.sent).toHaveLength(1) }) const secondOpen = JSON.parse(secondSocket.sent[0]!) as { streamId: string } expect(secondOpen.streamId).not.toBe(firstOpen.streamId) secondSocket.receive({ type: 'end', streamId: secondOpen.streamId }) await expect(secondPending).resolves.toEqual({ done: true, value: undefined }) await client.close() }) }) it('replaces an in-flight candidate and an open socket on reconnect', async () => { await withFakeWebSocket('https://harness.example', async () => { FakeWebSocket.autoOpen = false const client = new RemoteStreamMuxClient() client.start() const candidate = FakeWebSocket.sockets[0]! client.reconnect() const replacementPending = client.open( 'feed/follow', { label: 'replacement' }, new AbortController().signal, )[Symbol.asyncIterator]().next() await vi.waitFor(() => { expect(FakeWebSocket.sockets).toHaveLength(2) }) expect(candidate.closedWith).toContainEqual({}) const connected = FakeWebSocket.sockets[1]! connected.open() await vi.waitFor(() => { expect(connected.sent).toHaveLength(1) }) const opened = JSON.parse(connected.sent[0]!) as { streamId: string } connected.receive({ type: 'end', streamId: opened.streamId }) await expect(replacementPending).resolves.toEqual({ done: true, value: undefined }) client.reconnect() await vi.waitFor(() => { expect(FakeWebSocket.sockets).toHaveLength(3) }) expect(connected.closedWith).toContainEqual({ code: 4000, reason: 'reconnect requested' }) await client.close() client.reconnect() await Promise.resolve() expect(FakeWebSocket.sockets).toHaveLength(3) }) }) it('coalesces repeated candidate replacements and drops one queued after close', async () => { await withFakeWebSocket('https://harness.example', async () => { FakeWebSocket.autoOpen = false const client = new RemoteStreamMuxClient() client.start() const first = FakeWebSocket.sockets[0]! client.reconnect() client.reconnect() await vi.waitFor(() => { expect(FakeWebSocket.sockets).toHaveLength(2) }) expect(first.closedWith).toContainEqual({}) client.reconnect() await client.close() await Promise.resolve() expect(FakeWebSocket.sockets).toHaveLength(2) }) }) it('shares an in-flight connection and resolves the mux route against the document base', async () => { await withFakeWebSocket('https://harness.example/mounted/app/', async () => { FakeWebSocket.autoOpen = false const client = new RemoteStreamMuxClient() client.start() const first = client.open('feed/follow', { label: 'first' }, new AbortController().signal) [Symbol.asyncIterator]() const second = client.open('feed/follow', { label: 'second' }, new AbortController().signal) [Symbol.asyncIterator]() const firstPending = first.next() const secondPending = second.next() expect(FakeWebSocket.sockets).toHaveLength(1) const socket = FakeWebSocket.sockets[0]! expect(socket.url).toBe('wss://harness.example/mounted/app/api/remote.mux') socket.open() await vi.waitFor(() => { expect(socket.sent).toHaveLength(2) }) const streamIds = socket.sent.map(text => (JSON.parse(text) as { streamId: string }).streamId) socket.receive({ type: 'end', streamId: streamIds[0] }) socket.receive({ type: 'end', streamId: streamIds[1] }) await expect(firstPending).resolves.toEqual({ done: true, value: undefined }) await expect(secondPending).resolves.toEqual({ done: true, value: undefined }) await client.close() }) }) it('fails waiters with one socket attempt and lets the owner start the next attempt', async () => { await withFakeWebSocket('http://harness.example/', async () => { FakeWebSocket.autoOpen = false const closedClient = new RemoteStreamMuxClient() closedClient.start() const closed = closedClient.open('feed/follow', {}, new AbortController().signal) [Symbol.asyncIterator]().next() FakeWebSocket.sockets[0]!.drop() await expect(closed).rejects.toThrow('Remote stream WebSocket closed before opening') closedClient.reconnect() const replacementStream = closedClient.open('feed/follow', {}, new AbortController().signal) [Symbol.asyncIterator]().next() await vi.waitFor(() => { expect(FakeWebSocket.sockets).toHaveLength(2) }) const replacement = FakeWebSocket.sockets[1]! replacement.open() await vi.waitFor(() => { expect(replacement.sent).toHaveLength(1) }) const { streamId } = JSON.parse(replacement.sent[0]!) as { streamId: string } replacement.receive({ type: 'end', streamId }) await expect(replacementStream).resolves.toEqual({ done: true, value: undefined }) await closedClient.close() const disposedClient = new RemoteStreamMuxClient() disposedClient.start() const disposed = disposedClient.open('feed/follow', {}, new AbortController().signal) [Symbol.asyncIterator]().next() await disposedClient.close() await expect(disposed).rejects.toThrow('Remote stream client disposed') const abortedClient = new RemoteStreamMuxClient() abortedClient.start() const abort = new AbortController() const aborted = abortedClient.open('feed/follow', {}, abort.signal)[Symbol.asyncIterator]().next() abort.abort('cancelled while connecting') await expect(aborted).rejects.toBe('cancelled while connecting') await abortedClient.close() expect(FakeWebSocket.sockets[3]?.url).toBe('ws://harness.example/api/remote.mux') }) }) it('fails active streams on an invalid frame and ignores later frames', async () => { await withFakeWebSocket('https://harness.example', async () => { const client = new RemoteStreamMuxClient() client.start() const stream = client.open('feed/follow', {}, new AbortController().signal)[Symbol.asyncIterator]() const pending = stream.next() await vi.waitFor(() => { expect(FakeWebSocket.sockets[0]?.sent).toHaveLength(1) }) const socket = FakeWebSocket.sockets[0]! const { streamId } = JSON.parse(socket.sent[0]!) as { streamId: string } FakeWebSocket.dispatchClose = false socket.receiveRaw(new Uint8Array([1, 2, 3])) socket.receive({ type: 'item', streamId, value: 'too late' }) socket.drop() await expect(pending).rejects.toMatchObject({ name: 'RemoteStreamCarrierError', message: 'api gateway: invalid Remote stream frame', }) expect(socket.closedWith).toContainEqual({ code: 4002, reason: 'invalid Remote stream frame' }) await client.close() }) }) it('completes a stream and drops a frame racing with cancellation', async () => { await withFakeWebSocket('https://harness.example', async () => { const client = new RemoteStreamMuxClient() client.start() const completed = client.open('feed/follow', {}, new AbortController().signal) [Symbol.asyncIterator]() const completedPending = completed.next() await vi.waitFor(() => { expect(FakeWebSocket.sockets[0]?.sent).toHaveLength(1) }) const socket = FakeWebSocket.sockets[0]! const completedOpen = JSON.parse(socket.sent[0]!) as { streamId: string } socket.receive({ type: 'end', streamId: completedOpen.streamId }) await expect(completedPending).resolves.toEqual({ done: true, value: undefined }) const abort = new AbortController() const cancelled = client.open('feed/follow', {}, abort.signal)[Symbol.asyncIterator]().next() await vi.waitFor(() => { expect(socket.sent).toHaveLength(2) }) const cancelledOpen = JSON.parse(socket.sent[1]!) as { streamId: string } const reason = new Error('fixture cancellation race') abort.abort(reason) socket.receive({ type: 'item', streamId: cancelledOpen.streamId, value: 'too late' }) await expect(cancelled).rejects.toBe(reason) await client.close() }) }) it('contains non-Error cancellation reasons and late socket close events', async () => { await withFakeWebSocket('http://harness.example', async () => { const cancelledClient = new RemoteStreamMuxClient() cancelledClient.start() const abort = new AbortController() const cancelled = cancelledClient.open('feed/follow', {}, abort.signal)[Symbol.asyncIterator]().next() await vi.waitFor(() => { expect(FakeWebSocket.sockets[0]?.sent).toHaveLength(1) }) abort.abort('caller cancelled') await expect(cancelled).rejects.toThrow('caller cancelled') await cancelledClient.close() FakeWebSocket.dispatchClose = false const disposedClient = new RemoteStreamMuxClient() disposedClient.start() const disposed = disposedClient.open('feed/follow', {}, new AbortController().signal) [Symbol.asyncIterator]().next() await vi.waitFor(() => { expect(FakeWebSocket.sockets[1]?.sent).toHaveLength(1) }) const disposedSocket = FakeWebSocket.sockets[1]! await disposedClient.close() disposedSocket.receive({ type: 'end', streamId: 'stale' }) disposedSocket.drop() await expect(disposed).rejects.toThrow('Remote stream client disposed') }) }) }) async function withFakeWebSocket( baseURI: string, run: () => Promise, ): Promise { const originalWebSocket = globalThis.WebSocket const documentDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'document') const locationDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'location') ;(globalThis as WebSocketGlobal).WebSocket = FakeWebSocket as unknown as typeof WebSocket Object.defineProperty(globalThis, 'document', { configurable: true, value: { baseURI } }) Object.defineProperty(globalThis, 'location', { configurable: true, value: { origin: new URL(baseURI).origin }, }) FakeWebSocket.sockets.length = 0 FakeWebSocket.autoOpen = true FakeWebSocket.dispatchClose = true try { await run() } finally { FakeWebSocket.sockets.length = 0 FakeWebSocket.autoOpen = true FakeWebSocket.dispatchClose = true if (originalWebSocket === undefined) delete (globalThis as WebSocketGlobal).WebSocket else globalThis.WebSocket = originalWebSocket if (documentDescriptor === undefined) Reflect.deleteProperty(globalThis, 'document') else Object.defineProperty(globalThis, 'document', documentDescriptor) if (locationDescriptor === undefined) Reflect.deleteProperty(globalThis, 'location') else Object.defineProperty(globalThis, 'location', locationDescriptor) } } async function drainStream(source: AsyncIterable): Promise { const values: unknown[] = [] for await (const value of source) values.push(value) return values }