@robota-sdk/agent-transport 3.0.0-beta.100

package/src/__tests__/file-transfer.test.ts

@@ -0,0 +1,281 @@
+import { createHash } from 'node:crypto';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  FILE_CREDIT_WINDOW,
+  receiveFileOverChannel,
+  sendFileOverChannel,
+  type IFileSink,
+  type IFileSource,
+  type TFileAdmission,
+} from '../node/file-transfer.js';
+
+import type { IFileFrameChannel, IFileOffer } from '@robota-sdk/agent-interface-session-mobility';
+
+/** Two ends of an in-memory channel. Frames arrive asynchronously, in order; `sent` records one side. */
+function channelPair(): { a: IFileFrameChannel & { sent: string[] }; b: IFileFrameChannel } {
+  type TEnd = IFileFrameChannel & {
+    sent: string[];
+    frames: Set<(frame: string) => void>;
+    closes: Set<() => void>;
+    closed: boolean;
+    other?: TEnd;
+  };
+  const make = (): TEnd => {
+    const end: TEnd = {
+      sent: [],
+      frames: new Set(),
+      closes: new Set(),
+      closed: false,
+      send(frame) {
+        if (end.closed) throw new Error('closed');
+        end.sent.push(frame);
+        const other = end.other!;
+        setImmediate(() => {
+          if (!other.closed) for (const handler of other.frames) handler(frame);
+        });
+      },
+      onFrame(handler) {
+        end.frames.add(handler);
+        return () => end.frames.delete(handler);
+      },
+      onClose(handler) {
+        end.closes.add(handler);
+        return () => end.closes.delete(handler);
+      },
+      close() {
+        for (const side of [end, end.other!]) {
+          if (side.closed) continue;
+          side.closed = true;
+          setImmediate(() => {
+            for (const handler of side.closes) handler();
+          });
+        }
+      },
+    };
+    return end;
+  };
+  const a = make();
+  const b = make();
+  a.other = b;
+  b.other = a;
+  return { a, b };
+}
+
+function sha256(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function sourceOf(bytes: Buffer, pieces = 7_000): IFileSource {
+  return {
+    size: bytes.length,
+    async *read() {
+      for (let at = 0; at < bytes.length; at += pieces) yield bytes.subarray(at, at + pieces);
+    },
+  };
+}
+
+function memorySink(): IFileSink & { written: Buffer[]; state: 'open' | 'kept' | 'discarded' } {
+  const sink = {
+    written: [] as Buffer[],
+    state: 'open' as 'open' | 'kept' | 'discarded',
+    write: async (chunk: Uint8Array) => {
+      sink.written.push(Buffer.from(chunk));
+    },
+    commit: async () => {
+      sink.state = 'kept';
+      return '/quarantine/file';
+    },
+    discard: async () => {
+      sink.state = 'discarded';
+    },
+  };
+  return sink;
+}
+
+function offerFor(bytes: Buffer, over: Partial<IFileOffer> = {}): IFileOffer {
+  return { transferId: 't1', name: 'data.bin', size: bytes.length, sha256: sha256(bytes), ...over };
+}
+
+describe('file carrier', () => {
+  it('moves a file the receiver admits, verified whole', async () => {
+    const bytes = Buffer.from(Array.from({ length: 100_000 }, (_, i) => i % 251));
+    const { a, b } = channelPair();
+    const sink = memorySink();
+    const offers: IFileOffer[] = [];
+    const [sent, received] = await Promise.all([
+      sendFileOverChannel({ channel: a, offer: offerFor(bytes), source: sourceOf(bytes) }),
+      receiveFileOverChannel({
+        channel: b,
+        admit: async (offer) => {
+          offers.push(offer);
+          return { sink };
+        },
+      }),
+    ]);
+    expect(sent).toEqual({ ok: true });
+    expect(received).toMatchObject({ ok: true, location: '/quarantine/file' });
+    expect(Buffer.concat(sink.written).equals(bytes)).toBe(true);
+    expect(sink.state).toBe('kept');
+    expect(offers).toEqual([offerFor(bytes)]);
+  });
+
+  it('sends no content before the receiver answers, and nothing at all when it refuses', async () => {
+    const bytes = Buffer.from('secret-ish');
+    const { a, b } = channelPair();
+    const [sent, received] = await Promise.all([
+      sendFileOverChannel({ channel: a, offer: offerFor(bytes), source: sourceOf(bytes) }),
+      receiveFileOverChannel({
+        channel: b,
+        admit: async (): Promise<TFileAdmission> => ({ refused: 'declined' }),
+      }),
+    ]);
+    expect(sent).toMatchObject({ ok: false, reason: 'declined' });
+    expect(received).toMatchObject({ ok: false, reason: 'declined' });
+    expect(a.sent.map((frame) => (JSON.parse(frame) as { t: string }).t)).toEqual(['file-offer']);
+  });
+
+  it('refuses an offer over the size limit without asking anyone', async () => {
+    const bytes = Buffer.alloc(2_000);
+    const { a, b } = channelPair();
+    let asked = false;
+    const [sent, received] = await Promise.all([
+      sendFileOverChannel({ channel: a, offer: offerFor(bytes), source: sourceOf(bytes) }),
+      receiveFileOverChannel({
+        channel: b,
+        maxBytes: 1_000,
+        admit: async () => {
+          asked = true;
+          return { sink: memorySink() };
+        },
+      }),
+    ]);
+    expect(asked).toBe(false);
+    expect(sent).toMatchObject({ ok: false, reason: 'too-large' });
+    expect(received).toMatchObject({ ok: false, reason: 'too-large' });
+  });
+
+  it('discards content that does not match the offered hash', async () => {
+    const bytes = Buffer.from('the real content');
+    const { a, b } = channelPair();
+    const sink = memorySink();
+    const [sent, received] = await Promise.all([
+      sendFileOverChannel({
+        channel: a,
+        offer: offerFor(bytes, { sha256: sha256(Buffer.from('something else')) }),
+        source: sourceOf(bytes),
+      }),
+      receiveFileOverChannel({ channel: b, admit: async () => ({ sink }) }),
+    ]);
+    expect(received).toMatchObject({ ok: false, reason: 'integrity' });
+    expect(sent).toMatchObject({ ok: false, reason: 'integrity' });
+    expect(sink.state).toBe('discarded');
+  });
+
+  it('discards a transfer the sender abandons midway', async () => {
+    const bytes = Buffer.alloc(200_000, 1);
+    const { a, b } = channelPair();
+    const sink = memorySink();
+    const source: IFileSource = {
+      size: bytes.length,
+      async *read() {
+        yield bytes.subarray(0, 50_000);
+        throw new Error('disk went away');
+      },
+    };
+    const [sent, received] = await Promise.all([
+      sendFileOverChannel({ channel: a, offer: offerFor(bytes), source }),
+      receiveFileOverChannel({ channel: b, admit: async () => ({ sink }) }),
+    ]);
+    expect(sent.ok).toBe(false);
+    expect(received).toMatchObject({ ok: false, reason: 'closed' });
+    expect(sink.state).toBe('discarded');
+  });
+
+  it('keeps no more than the credit window in flight', async () => {
+    const bytes = Buffer.alloc(40 * 1024 * 16, 7);
+    const { a, b } = channelPair();
+    let release: () => void = () => undefined;
+    const stalled = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    let writes = 0;
+    const sink: IFileSink = {
+      write: async () => {
+        writes += 1;
+        // The receiver's disk stalls on the first write.
+        if (writes === 1) await stalled;
+      },
+      commit: async () => '/q',
+      discard: async () => undefined,
+    };
+    const sending = sendFileOverChannel({
+      channel: a,
+      offer: offerFor(bytes),
+      source: sourceOf(bytes),
+    });
+    const receiving = receiveFileOverChannel({ channel: b, admit: async () => ({ sink }) });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    const chunks = a.sent.filter((frame) => frame.includes('"file-chunk"')).length;
+    expect(chunks).toBe(FILE_CREDIT_WINDOW);
+    release();
+    await expect(sending).resolves.toEqual({ ok: true });
+    await expect(receiving).resolves.toMatchObject({ ok: true });
+  });
+
+  it('ends a transfer whose sender ignores its credit', async () => {
+    const { a, b } = channelPair();
+    const bytes = Buffer.alloc(10);
+    const receiving = receiveFileOverChannel({
+      channel: b,
+      admit: async () => ({
+        sink: {
+          write: () => new Promise<void>((resolve) => setTimeout(resolve, 50)),
+          commit: async () => '',
+          discard: async () => undefined,
+        },
+      }),
+    });
+    a.onFrame(() => undefined);
+    a.send(JSON.stringify({ t: 'file-offer', ...offerFor(bytes, { size: 10 * 1024 * 1024 }) }));
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    for (let seq = 0; seq < FILE_CREDIT_WINDOW + 5; seq += 1) {
+      a.send(JSON.stringify({ t: 'file-chunk', seq, data: Buffer.alloc(16).toString('base64') }));
+    }
+    await expect(receiving).resolves.toMatchObject({ ok: false, reason: 'protocol' });
+  });
+
+  it('passes on a refusal detail only as printable text', async () => {
+    const bytes = Buffer.from('x');
+    const { a, b } = channelPair();
+    b.onFrame(() => {
+      b.send(
+        JSON.stringify({ t: 'file-refuse', reason: 'declined', detail: 'no\u001b[2J‮thanks' }),
+      );
+    });
+    const sent = await sendFileOverChannel({
+      channel: a,
+      offer: offerFor(bytes),
+      source: sourceOf(bytes),
+    });
+    expect(sent).toMatchObject({ ok: false, reason: 'declined' });
+    const detail = sent.ok ? '' : (sent.detail ?? '');
+    expect(detail).toContain('thanks');
+    expect([...detail].some((char) => (char.codePointAt(0) ?? 0) < 0x20)).toBe(false);
+    expect(detail).not.toContain('‮');
+  });
+
+  it('ends a transfer that sends an empty chunk', async () => {
+    const { a, b } = channelPair();
+    const bytes = Buffer.alloc(10);
+    const sink = memorySink();
+    const receiving = receiveFileOverChannel({ channel: b, admit: async () => ({ sink }) });
+    a.onFrame(() => undefined);
+    a.send(JSON.stringify({ t: 'file-offer', ...offerFor(bytes) }));
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    a.send(JSON.stringify({ t: 'file-chunk', seq: 0, data: '' }));
+    await expect(receiving).resolves.toMatchObject({ ok: false, reason: 'protocol' });
+    expect(sink.state).toBe('discarded');
+  });
+});

package/src/__tests__/handoff-chunking.test.ts

@@ -0,0 +1,261 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  chunkCountFor,
+  chunkHandoffPayload,
+  HandoffChunkAssembler,
+  type IHandoffChunk,
+} from '../handoff-chunking.js';
+import { sealHandoffRecord, verifyHandoffPayload } from '../node/handoff-manifest.js';
+import koreanText from './__fixtures__/korean-text.json';
+
+import type { IInteractiveSessionRecord } from '@robota-sdk/agent-interface-session';
+
+const ID = 'handoff_1';
+
+function assemble(chunks: readonly IHandoffChunk[], assembler = new HandoffChunkAssembler(ID)) {
+  let last;
+  for (const chunk of chunks) last = assembler.accept(chunk);
+  return { assembler, last };
+}
+
+describe('HANDOFF-001 — a payload larger than one frame travels in pieces', () => {
+  it('every chunk fits the byte budget', () => {
+    // The channel's limit is in bytes, so the budget has to be honoured in bytes. A payload of
+    // multi-byte characters is where a character-based cut overflows the frame.
+    const payload = koreanText.hangulWord.repeat(500);
+
+    const chunks = chunkHandoffPayload(ID, payload, 64);
+
+    for (const chunk of chunks) {
+      expect(Buffer.from(chunk.data, 'base64').byteLength).toBeLessThanOrEqual(64);
+    }
+  });
+
+  it('round-trips a payload whose characters do not align to the cut', () => {
+    // The cut lands mid-character by construction here. Reassembly is on bytes, so the boundary
+    // is invisible to the result — which is the property the byte-based design buys.
+    const payload = `${'a'.repeat(30)}😀${'b'.repeat(30)}`;
+
+    const { last } = assemble(chunkHandoffPayload(ID, payload, 16));
+
+    expect(last?.outcome).toBe('complete');
+    expect(last?.serialized).toBe(payload);
+  });
+
+  it('an empty payload is one chunk, not zero', () => {
+    // Zero chunks would leave a receiver unable to tell a completed empty transfer from one that
+    // never started.
+    const chunks = chunkHandoffPayload(ID, '', 64);
+
+    expect(chunks).toHaveLength(1);
+    expect(assemble(chunks).last?.serialized).toBe('');
+  });
+
+  it('every chunk carries the total, so no single lost frame hides the count', () => {
+    const chunks = chunkHandoffPayload(ID, 'x'.repeat(100), 10);
+
+    expect(chunks.every((c) => c.total === chunks.length)).toBe(true);
+  });
+
+  it('refuses a budget that would produce an endless sequence of empty chunks', () => {
+    expect(() => chunkHandoffPayload(ID, 'x', 0)).toThrow(/positive integer/);
+  });
+
+  it('predicts the chunk count from the manifest without building them', () => {
+    const { serialized, integrity } = sealHandoffRecord({
+      id: 's',
+      cwd: '/w',
+      createdAt: 'a',
+      updatedAt: 'b',
+      messages: [],
+    } as IInteractiveSessionRecord);
+
+    expect(chunkCountFor(integrity, 16)).toBe(chunkHandoffPayload(ID, serialized, 16).length);
+  });
+});
+
+describe('HANDOFF-001 — reordering and retries are normal; inconsistency is not', () => {
+  it('accepts chunks out of order', () => {
+    const chunks = [...chunkHandoffPayload(ID, 'x'.repeat(100), 10)].reverse();
+
+    const { last } = assemble(chunks);
+
+    expect(last?.outcome).toBe('complete');
+    expect(last?.serialized).toBe('x'.repeat(100));
+  });
+
+  it('a re-sent chunk is a duplicate, not a problem', () => {
+    const chunks = chunkHandoffPayload(ID, 'x'.repeat(100), 10);
+    const assembler = new HandoffChunkAssembler(ID);
+    assembler.accept(chunks[0]);
+
+    const again = assembler.accept(chunks[0]);
+
+    expect(again.outcome).toBe('duplicate');
+    expect(again.received).toBe(1);
+  });
+
+  it('different bytes for the same index is refused, not overwritten', () => {
+    const chunks = chunkHandoffPayload(ID, 'x'.repeat(100), 10);
+    const assembler = new HandoffChunkAssembler(ID);
+    assembler.accept(chunks[0]);
+
+    const conflicting = assembler.accept({
+      ...chunks[0],
+      data: Buffer.from('zz').toString('base64'),
+    });
+
+    expect(conflicting.outcome).toBe('refused');
+  });
+
+  it('a peer that changes its mind about the size is refused', () => {
+    // Either it restarted the transfer under the same id, or it is not the peer we started with.
+    // Both mean the pieces held so far can no longer be assumed to belong together.
+    const chunks = chunkHandoffPayload(ID, 'x'.repeat(100), 10);
+    const assembler = new HandoffChunkAssembler(ID);
+    assembler.accept(chunks[0]);
+
+    const result = assembler.accept({ ...chunks[1], total: 3 });
+
+    expect(result.rejection).toBe('inconsistent-total');
+  });
+
+  it('refuses a chunk belonging to a different transfer rather than routing it', () => {
+    const [chunk] = chunkHandoffPayload('other_handoff', 'x', 10);
+
+    expect(new HandoffChunkAssembler(ID).accept(chunk).rejection).toBe('wrong-handoff');
+  });
+
+  it.each([
+    ['a negative index', -1],
+    ['an index beyond the total', 99],
+  ])('refuses %s', (_label, index) => {
+    const [chunk] = chunkHandoffPayload(ID, 'x'.repeat(30), 10);
+
+    expect(new HandoffChunkAssembler(ID).accept({ ...chunk, index }).rejection).toBe(
+      'out-of-range',
+    );
+  });
+
+  it('reports which indices are still missing, so a caller can ask rather than restart', () => {
+    const chunks = chunkHandoffPayload(ID, 'x'.repeat(100), 10);
+    const assembler = new HandoffChunkAssembler(ID);
+    assembler.accept(chunks[0]);
+    assembler.accept(chunks[3]);
+
+    expect(assembler.missing()).toEqual([1, 2, 4, 5, 6, 7, 8, 9]);
+  });
+
+  it('knows nothing is missing before anything has declared a total', () => {
+    expect(new HandoffChunkAssembler(ID).missing()).toEqual([]);
+  });
+
+  it('discard drops what it held', () => {
+    const chunks = chunkHandoffPayload(ID, 'x'.repeat(100), 10);
+    const assembler = new HandoffChunkAssembler(ID);
+    assembler.accept(chunks[0]);
+
+    assembler.discard();
+
+    expect(assembler.received).toBe(0);
+    expect(assembler.expected).toBeUndefined();
+  });
+});
+
+describe('HANDOFF-001 TC-06 — a mangled chunk is caught where it arrives', () => {
+  it('refuses data that is not decodable base64', () => {
+    // Buffer.from is lenient: it drops what it cannot parse rather than throwing, so a mangled
+    // chunk would silently become a shorter one and corrupt the payload in a way only the final
+    // digest catches — after the whole transfer completed.
+    const [chunk] = chunkHandoffPayload(ID, 'x'.repeat(30), 10);
+
+    const result = new HandoffChunkAssembler(ID).accept({ ...chunk, data: 'not!valid!base64!' });
+
+    expect(result.rejection).toBe('undecodable');
+  });
+
+  it('a corrupt-but-decodable chunk survives here and is caught by the digest', () => {
+    // The two checks are deliberately different questions. This one asks "did the pieces arrive";
+    // the digest asks "are they the pieces that were sent". Asking the second one per chunk would
+    // report each piece intact while the set is not the set that was sent.
+    const record = {
+      id: 's',
+      cwd: '/w',
+      createdAt: 'a',
+      updatedAt: 'b',
+      messages: [],
+    } as IInteractiveSessionRecord;
+    const { serialized, integrity } = sealHandoffRecord(record);
+    const chunks = chunkHandoffPayload(ID, serialized, 16);
+    const swapped = chunks.map((c, i) =>
+      i === 0 ? { ...c, data: Buffer.from('0'.repeat(16)).toString('base64') } : c,
+    );
+
+    const { last } = assemble(swapped);
+
+    expect(last?.outcome).toBe('complete');
+    expect(verifyHandoffPayload(last?.serialized ?? '', integrity).intact).toBe(false);
+  });
+
+  it('the whole path holds: seal, chunk, reassemble, verify', () => {
+    const record = {
+      id: 'session_1',
+      cwd: '/home/alice/project',
+      createdAt: '2026-08-17T00:00:00.000Z',
+      updatedAt: '2026-08-17T01:00:00.000Z',
+      messages: [{ role: 'user', content: koreanText.greetingWithSmileEmoji }],
+    } as unknown as IInteractiveSessionRecord;
+    const { serialized, integrity } = sealHandoffRecord(record);
+
+    const { last } = assemble(chunkHandoffPayload(ID, serialized, 24));
+
+    expect(verifyHandoffPayload(last?.serialized ?? '', integrity).intact).toBe(true);
+    expect(JSON.parse(last?.serialized ?? '{}')).toEqual(record);
+  });
+});
+
+describe('without Node’s Buffer, as in the browser build', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('chunks and reassembles a multi-byte payload', () => {
+    vi.stubGlobal('Buffer', undefined);
+    const serialized = JSON.stringify({
+      text: koreanText.handoffLabelWithCheckmarkAndTrailingSpace.repeat(200),
+    });
+    const assembler = new HandoffChunkAssembler('h-browser');
+    let result: ReturnType<HandoffChunkAssembler['accept']> | undefined;
+
+    for (const chunk of chunkHandoffPayload('h-browser', serialized, 64)) {
+      result = assembler.accept(chunk);
+    }
+
+    expect(result).toMatchObject({ outcome: 'complete', serialized });
+  });
+
+  it('keeps a leading byte-order mark', () => {
+    vi.stubGlobal('Buffer', undefined);
+    const serialized = '\uFEFF{"text":"bom"}';
+    const assembler = new HandoffChunkAssembler('h-bom');
+    let result: ReturnType<HandoffChunkAssembler['accept']> | undefined;
+
+    for (const chunk of chunkHandoffPayload('h-bom', serialized, 4)) {
+      result = assembler.accept(chunk);
+    }
+
+    expect(result).toMatchObject({ outcome: 'complete', serialized });
+  });
+
+  it('refuses a chunk whose base64 is not canonical', () => {
+    vi.stubGlobal('Buffer', undefined);
+    const [chunk] = chunkHandoffPayload('h-browser', 'hello', 64);
+    const assembler = new HandoffChunkAssembler('h-browser');
+
+    expect(assembler.accept({ ...chunk!, data: ` ${chunk!.data}` })).toMatchObject({
+      outcome: 'refused',
+      rejection: 'undecodable',
+    });
+  });
+});

package/src/__tests__/handoff-manifest.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+
+import { sealHandoffRecord, verifyHandoffPayload } from '../node/handoff-manifest.js';
+
+import type { IInteractiveSessionRecord } from '@robota-sdk/agent-interface-session';
+
+function aRecord(over: Partial<IInteractiveSessionRecord> = {}): IInteractiveSessionRecord {
+  return {
+    id: 'session_1',
+    cwd: '/home/alice/project',
+    createdAt: '2026-08-17T00:00:00.000Z',
+    updatedAt: '2026-08-17T01:00:00.000Z',
+    messages: [],
+    ...over,
+  };
+}
+
+describe('HANDOFF-001 TC-06 — a payload that did not arrive whole is refused', () => {
+  it('accepts the exact bytes that were sealed', () => {
+    const { serialized, integrity } = sealHandoffRecord(aRecord());
+
+    expect(verifyHandoffPayload(serialized, integrity).intact).toBe(true);
+  });
+
+  it('reports a truncated payload as truncated, not as corruption', () => {
+    // Checked BEFORE the digest. Hashing a short buffer to discover it was short wastes the work
+    // and reports a dropped connection as tampering.
+    const { serialized, integrity } = sealHandoffRecord(aRecord());
+
+    const verdict = verifyHandoffPayload(serialized.slice(0, -20), integrity);
+
+    expect(verdict.failure).toBe('truncated');
+    expect(verdict.expectedBytes).toBe(integrity.byteLength);
+    expect(verdict.actualBytes).toBeLessThan(integrity.byteLength);
+  });
+
+  it('reports a same-length substitution as a digest mismatch', () => {
+    // The case length alone cannot catch, which is why the digest is there at all.
+    const { serialized, integrity } = sealHandoffRecord(aRecord());
+    const tampered = serialized.replace('/home/alice/project', '/home/mallor/projec');
+
+    expect(tampered).toHaveLength(serialized.length);
+    expect(verifyHandoffPayload(tampered, integrity).failure).toBe('digest-mismatch');
+  });
+
+  it('two different records do not seal to the same digest', () => {
+    const a = sealHandoffRecord(aRecord());
+    const b = sealHandoffRecord(aRecord({ cwd: '/elsewhere' }));
+
+    expect(a.integrity.digest).not.toBe(b.integrity.digest);
+  });
+});