@robota-sdk/agent-transport 3.0.0-beta.81 → 3.0.0-beta.83

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__/history-attached-budget.test.ts

@@ -0,0 +1,216 @@
+/**
+ * #3189: a history larger than an attached terminal's backpressure budget reaches that terminal
+ * whole, over a real socket, without the connection being cut.
+ *
+ * The carrier here is wired as the supervised attach carrier is: every reply goes through
+ * `createOutboundDelivery` measuring the socket's `writableLength` against
+ * `ATTACHED_SURFACE_MAX_PENDING_BYTES`, and a failure destroys the socket. The client sends what an
+ * attached terminal sends when it starts, all at once, and pages the history as it arrives.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { createConnection, createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  ATTACHED_SURFACE_MAX_PENDING_BYTES,
+  createOutboundDelivery,
+} from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+
+import type { TClientMessage, TServerMessage } from '../wire-messages.js';
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { Server, Socket } from 'node:net';
+
+type TListener = (...args: unknown[]) => void;
+
+const ENTRY_BYTES = 20_000;
+/** Half as much again as the budget, so one frame holding it all would trip it. */
+const HISTORY_BYTES = ATTACHED_SURFACE_MAX_PENDING_BYTES * 1.5;
+
+const STARTUP: readonly TClientMessage[] = [
+  { type: 'get-history' },
+  { type: 'get-context' },
+  { type: 'get-commands' },
+  { type: 'get-status' },
+  { type: 'get-executing' },
+  { type: 'get-pending' },
+  { type: 'get-execution-workspace' },
+];
+
+function longHistory(): IHistoryEntry[] {
+  return Array.from({ length: Math.ceil(HISTORY_BYTES / ENTRY_BYTES) }, (_, index) => ({
+    id: `e${index}`,
+    timestamp: new Date('2026-09-26T00:00:00.000Z'),
+    category: 'chat',
+    type: 'assistant',
+    data: { role: 'assistant', content: 'x'.repeat(ENTRY_BYTES) },
+  }));
+}
+
+function emittingSession(
+  history: IHistoryEntry[],
+): IInteractiveSession & { emit: (event: string, payload: unknown) => void } {
+  const listeners = new Map<string, Set<TListener>>();
+  const session = createTestInteractiveSession({
+    getFullHistory: () => history,
+    on: ((event: string, handler: TListener) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(handler);
+    }) as IInteractiveSession['on'],
+    off: ((event: string, handler: TListener) => {
+      listeners.get(event)?.delete(handler);
+    }) as IInteractiveSession['off'],
+  });
+  return Object.assign(session, {
+    emit: (event: string, payload: unknown) => {
+      for (const handler of listeners.get(event) ?? []) handler(payload);
+    },
+  });
+}
+
+/** One connection's carrier, as the supervised attach carrier builds it. */
+function serve(session: IInteractiveSession, socket: Socket, onCut: (error: Error) => void): void {
+  const deliver = createOutboundDelivery(
+    (message) => {
+      socket.write(`${JSON.stringify(message)}\n`);
+    },
+    (error) => {
+      onCut(error);
+      socket.destroy();
+    },
+    () => socket.writableLength,
+    ATTACHED_SURFACE_MAX_PENDING_BYTES,
+  );
+  const { onMessage, cleanup } = createSessionMessageHandler({ session, deliver });
+  let buffered = '';
+  socket.setEncoding('utf8');
+  socket.on('data', (chunk: string) => {
+    buffered += chunk;
+    // Every complete line of a chunk is handled in one pass, as the carrier's drain loop does.
+    for (let end = buffered.indexOf('\n'); end !== -1; end = buffered.indexOf('\n')) {
+      const line = buffered.slice(0, end);
+      buffered = buffered.slice(end + 1);
+      onMessage(line);
+    }
+  });
+  socket.on('close', cleanup);
+}
+
+interface IClient {
+  readonly frames: TServerMessage[];
+  readonly closed: Promise<void>;
+  send(message: TClientMessage): void;
+  next(predicate: (frame: TServerMessage) => boolean): Promise<TServerMessage>;
+  end(): void;
+}
+
+function connect(path: string): Promise<IClient> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(path);
+    const frames: TServerMessage[] = [];
+    const waiters: {
+      predicate: (frame: TServerMessage) => boolean;
+      found: (f: TServerMessage) => void;
+      lost: (error: Error) => void;
+    }[] = [];
+    let buffered = '';
+    let markClosed: () => void = () => undefined;
+    const closed = new Promise<void>((done) => {
+      markClosed = done;
+    });
+    socket.setEncoding('utf8');
+    socket.on('data', (chunk: string) => {
+      buffered += chunk;
+      for (let end = buffered.indexOf('\n'); end !== -1; end = buffered.indexOf('\n')) {
+        const frame = JSON.parse(buffered.slice(0, end)) as TServerMessage;
+        buffered = buffered.slice(end + 1);
+        frames.push(frame);
+        for (const waiter of waiters.splice(0)) {
+          if (waiter.predicate(frame)) waiter.found(frame);
+          else waiters.push(waiter);
+        }
+      }
+    });
+    socket.on('close', () => {
+      markClosed();
+      for (const waiter of waiters.splice(0))
+        waiter.lost(new Error('the host closed the connection'));
+    });
+    socket.on('error', reject);
+    socket.on('connect', () =>
+      resolve({
+        frames,
+        closed,
+        send: (message) => socket.write(`${JSON.stringify(message)}\n`),
+        next: (predicate) =>
+          new Promise((found, lost) => {
+            waiters.push({ predicate, found, lost });
+          }),
+        end: () => socket.end(),
+      }),
+    );
+  });
+}
+
+function isHistory(frame: TServerMessage): frame is Extract<TServerMessage, { type: 'history' }> {
+  return frame.type === 'history';
+}
+
+describe('a history larger than the attached-surface budget (#3189)', () => {
+  let server: Server | undefined;
+  let dir: string | undefined;
+
+  afterEach(async () => {
+    await new Promise<void>((done) => (server ? server.close(() => done()) : done()));
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('reaches an attached terminal whole, and the turn after it does not cut the terminal off', async () => {
+    const history = longHistory();
+    const session = emittingSession(history);
+    const cuts: Error[] = [];
+    dir = mkdtempSync(join(tmpdir(), 'rh-'));
+    const path = join(dir, 's.sock');
+    server = createServer((socket) => serve(session, socket, (error) => cuts.push(error)));
+    await new Promise<void>((done) => server!.listen(path, done));
+    const client = await connect(path);
+
+    // What an attached terminal sends when it starts, in one burst.
+    for (const message of STARTUP) client.send(message);
+    const received: string[] = [];
+    let page = (await client.next(isHistory)) as Extract<TServerMessage, { type: 'history' }>;
+    for (;;) {
+      received.push(...page.entries.map((entry) => entry.id));
+      const next = page.startIndex + page.entries.length;
+      if (next >= page.total) break;
+      const arriving = client.next(isHistory);
+      client.send({ type: 'get-history', fromIndex: next });
+      page = (await arriving) as Extract<TServerMessage, { type: 'history' }>;
+    }
+    expect(received).toEqual(history.map((entry) => entry.id));
+
+    // A turn ends: its result, then more frames at once, as the host sends them.
+    const thinking = client.next((frame) => frame.type === 'thinking');
+    session.emit('complete', {
+      response: 'done',
+      history,
+      toolSummaries: [],
+      contextState: { usedTokens: 1, maxTokens: 10, usedPercentage: 10 },
+    });
+    session.emit('thinking', false);
+    await thinking;
+
+    expect(cuts).toEqual([]);
+    expect(client.frames.map((frame) => frame.type)).toEqual(
+      expect.arrayContaining(['context', 'commands', 'session_status', 'pending', 'complete']),
+    );
+    client.end();
+    await client.closed;
+  }, 20_000);
+});