chore: import upstream snapshot with attribution

test/util/agent/agentClient.test.ts

@@ -0,0 +1,253 @@
+import { EventEmitter } from 'events';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// ── Hoisted mocks ──────────────────────────────────────────────────────────────
+
+const mockIo = vi.hoisted(() => vi.fn());
+
+vi.mock('socket.io-client', () => ({ io: mockIo }));
+
+vi.mock('../../../src/globalConfig/cloud', () => ({
+  cloudConfig: { getApiHost: () => 'http://localhost:3000' },
+}));
+
+vi.mock('../../../src/util/agent/agentAuth', () => ({
+  resolveBaseAuthCredentials: () => ({ apiKey: 'test-key' }),
+}));
+
+vi.mock('../../../src/logger', () => ({
+  default: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+// ── Fake socket factory ────────────────────────────────────────────────────────
+
+function createFakeSocket() {
+  const emitter = new EventEmitter();
+  const ioEmitter = new EventEmitter();
+  const emittedToServer: Array<{ event: string; args: unknown[] }> = [];
+
+  const socket = {
+    id: 'fake-socket-id',
+    connected: false,
+    io: {
+      reconnection: vi.fn(),
+      on(event: string, handler: (...args: unknown[]) => void) {
+        ioEmitter.on(event, handler);
+        return socket.io;
+      },
+    },
+
+    on(event: string, handler: (...args: unknown[]) => void) {
+      emitter.on(event, handler);
+      return socket;
+    },
+    once(event: string, handler: (...args: unknown[]) => void) {
+      emitter.once(event, handler);
+      return socket;
+    },
+    emit(event: string, ...args: unknown[]) {
+      emittedToServer.push({ event, args });
+    },
+    removeAllListeners() {
+      emitter.removeAllListeners();
+      return socket;
+    },
+    close: vi.fn(),
+    disconnect: vi.fn(),
+
+    // Test helpers
+    _emittedToServer: emittedToServer,
+    _simulateEvent(event: string, ...args: unknown[]) {
+      emitter.emit(event, ...args);
+    },
+    _simulateConnect() {
+      socket.connected = true;
+      socket.id = `socket-${Math.random().toString(36).slice(2, 8)}`;
+      emitter.emit('connect');
+    },
+    _simulateDisconnect(reason = 'transport close') {
+      socket.connected = false;
+      emitter.emit('disconnect', reason);
+    },
+    _simulateConnectError(message = 'Connection refused') {
+      emitter.emit('connect_error', new Error(message));
+    },
+    _simulateReconnectFailed() {
+      ioEmitter.emit('reconnect_failed');
+    },
+  };
+  return socket;
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────────
+
+describe('createAgentClient', () => {
+  let fakeSocket: ReturnType<typeof createFakeSocket>;
+
+  beforeEach(() => {
+    fakeSocket = createFakeSocket();
+    mockIo.mockReset();
+    mockIo.mockReturnValue(fakeSocket);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('emits agent:join on initial connect', async () => {
+    const { createAgentClient } = await import('../../../src/util/agent/agentClient');
+
+    const promise = createAgentClient({
+      agent: 'test-agent',
+      host: 'http://localhost:3000',
+      auth: { apiKey: 'k' },
+      sessionId: 'sess-123',
+      timeoutMs: 1000,
+    });
+
+    fakeSocket._simulateConnect();
+    const client = await promise;
+
+    expect(client.sessionId).toBe('sess-123');
+
+    const joins = fakeSocket._emittedToServer.filter((e) => e.event === 'agent:join');
+    expect(joins).toHaveLength(1);
+    expect(joins[0].args[0]).toEqual({ sessionId: 'sess-123' });
+  });
+
+  it('re-emits agent:join after disconnect + reconnect', async () => {
+    const { createAgentClient } = await import('../../../src/util/agent/agentClient');
+
+    const promise = createAgentClient({
+      agent: 'test-agent',
+      host: 'http://localhost:3000',
+      auth: { apiKey: 'k' },
+      sessionId: 'sess-456',
+      timeoutMs: 1000,
+    });
+
+    // Initial connect
+    fakeSocket._simulateConnect();
+    await promise;
+
+    // Disconnect then reconnect
+    fakeSocket._simulateDisconnect('transport close');
+    fakeSocket._simulateConnect();
+
+    const joins = fakeSocket._emittedToServer.filter((e) => e.event === 'agent:join');
+    expect(joins).toHaveLength(2);
+    expect(joins[0].args[0]).toEqual({ sessionId: 'sess-456' });
+    expect(joins[1].args[0]).toEqual({ sessionId: 'sess-456' });
+  });
+
+  it('resolves the promise only once even after reconnect', async () => {
+    const { createAgentClient } = await import('../../../src/util/agent/agentClient');
+
+    let resolveCount = 0;
+    const promise = createAgentClient({
+      agent: 'test-agent',
+      host: 'http://localhost:3000',
+      auth: { apiKey: 'k' },
+      sessionId: 'sess-789',
+      timeoutMs: 1000,
+    }).then((client) => {
+      resolveCount++;
+      return client;
+    });
+
+    fakeSocket._simulateConnect();
+    await promise;
+    expect(resolveCount).toBe(1);
+
+    // Reconnect — should NOT cause a second resolution. Flush several
+    // microtask rounds to give any (buggy) re-resolve handler a chance to fire.
+    fakeSocket._simulateDisconnect('transport close');
+    fakeSocket._simulateConnect();
+    for (let i = 0; i < 5; i++) {
+      await Promise.resolve();
+    }
+    expect(resolveCount).toBe(1);
+  });
+
+  it('rejects with connect_error before initial connection', async () => {
+    const { createAgentClient } = await import('../../../src/util/agent/agentClient');
+
+    const promise = createAgentClient({
+      agent: 'test-agent',
+      host: 'http://localhost:3000',
+      auth: { apiKey: 'k' },
+      sessionId: 'sess-err',
+      timeoutMs: 1000,
+    });
+
+    fakeSocket._simulateConnectError('Auth failed');
+
+    await expect(promise).rejects.toThrow('Failed to connect to server: Auth failed');
+  });
+
+  it('ignores connect_error after successful connection', async () => {
+    const { createAgentClient } = await import('../../../src/util/agent/agentClient');
+
+    const promise = createAgentClient({
+      agent: 'test-agent',
+      host: 'http://localhost:3000',
+      auth: { apiKey: 'k' },
+      sessionId: 'sess-after-err',
+      timeoutMs: 1000,
+    });
+
+    // Connect first
+    fakeSocket._simulateConnect();
+    const client = await promise;
+
+    // connect_error after settlement should not cause problems
+    fakeSocket._simulateConnectError('Late error');
+
+    // Client should still be usable
+    expect(client.sessionId).toBe('sess-after-err');
+  });
+
+  it('onCancelled receives agent:cancelled event', async () => {
+    const { createAgentClient } = await import('../../../src/util/agent/agentClient');
+
+    const promise = createAgentClient({
+      agent: 'test-agent',
+      host: 'http://localhost:3000',
+      auth: { apiKey: 'k' },
+      sessionId: 'sess-cancel',
+      timeoutMs: 1000,
+    });
+
+    fakeSocket._simulateConnect();
+    const client = await promise;
+
+    const cb = vi.fn();
+    client.onCancelled(cb);
+
+    fakeSocket._simulateEvent('agent:cancelled', { clientType: 'web' });
+
+    expect(cb).toHaveBeenCalledWith({ clientType: 'web' });
+  });
+
+  it('rejects on timeout when no connection', async () => {
+    vi.useFakeTimers();
+
+    const { createAgentClient } = await import('../../../src/util/agent/agentClient');
+
+    const promise = createAgentClient({
+      agent: 'test-agent',
+      host: 'http://localhost:3000',
+      auth: { apiKey: 'k' },
+      sessionId: 'sess-timeout',
+      timeoutMs: 500,
+    });
+
+    // Advance past timeout
+    vi.advanceTimersByTime(600);
+
+    await expect(promise).rejects.toThrow('Connection timeout after 500ms');
+
+    vi.useRealTimers();
+  });
+});

test/util/agent/fsOperations.test.ts

@@ -0,0 +1,72 @@
+import * as fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const fsPromisesMock = vi.hoisted(() => ({
+  actualReadFile: undefined as undefined | typeof fs.readFile,
+  readFileSpy: vi.fn(),
+}));
+
+function getActualReadFile(): typeof fs.readFile {
+  if (!fsPromisesMock.actualReadFile) {
+    throw new Error('readFile mock not initialized');
+  }
+  return fsPromisesMock.actualReadFile;
+}
+
+vi.mock('node:fs/promises', async () => {
+  const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises');
+  fsPromisesMock.actualReadFile = actual.readFile.bind(actual);
+  fsPromisesMock.readFileSpy.mockImplementation(getActualReadFile());
+
+  return {
+    ...actual,
+    readFile: fsPromisesMock.readFileSpy,
+  };
+});
+
+import { readFile } from '../../../src/util/agent/fsOperations';
+
+describe('agent fsOperations readFile', () => {
+  let rootDir: string;
+
+  beforeEach(async () => {
+    fsPromisesMock.readFileSpy.mockReset();
+    fsPromisesMock.readFileSpy.mockImplementation(getActualReadFile());
+    rootDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-fs-operations-'));
+  });
+
+  afterEach(async () => {
+    vi.clearAllMocks();
+    await fs.rm(rootDir, { recursive: true, force: true });
+  });
+
+  it('returns the full contents for files within the size limit', async () => {
+    await fs.writeFile(path.join(rootDir, 'small.txt'), 'small file contents', 'utf8');
+
+    await expect(readFile('small.txt', rootDir)).resolves.toBe('small file contents');
+  });
+
+  it('returns full multibyte content when decoded length fits within the limit', async () => {
+    const multibyteContent = '你'.repeat(60_000);
+    await fs.writeFile(path.join(rootDir, 'multibyte.txt'), multibyteContent, 'utf8');
+
+    await expect(readFile('multibyte.txt', rootDir)).resolves.toBe(multibyteContent);
+  });
+
+  it('truncates very large files without using fs.readFile', async () => {
+    const maxFileSize = 100_000;
+    const oversizedContent = 'a'.repeat(450_000);
+    await fs.writeFile(path.join(rootDir, 'large.txt'), oversizedContent, 'utf8');
+
+    const result = await readFile('large.txt', rootDir);
+
+    expect(fsPromisesMock.readFileSpy).not.toHaveBeenCalled();
+    expect(result).toBe(
+      oversizedContent.slice(0, maxFileSize) +
+        `\n\n[truncated — file is ${oversizedContent.length} bytes]`,
+    );
+  });
+});

test/util/agent/targetLink.test.ts

@@ -0,0 +1,228 @@
+import { EventEmitter } from 'events';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { TargetLinkEvents } from '../../../src/types/targetLink';
+
+vi.mock('../../../src/logger', () => ({
+  default: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+// ── Fake client factory ───────────────────────────────────────────────────────
+
+function createFakeClient() {
+  const emitter = new EventEmitter();
+  const emittedToServer: Array<{ event: string; args: unknown[] }> = [];
+
+  return {
+    on(event: string, handler: (...args: unknown[]) => void) {
+      emitter.on(event, handler);
+    },
+    emit(event: string, ...args: unknown[]) {
+      emittedToServer.push({ event, args });
+    },
+    // Test helpers
+    _emittedToServer: emittedToServer,
+    _simulateEvent(event: string, ...args: unknown[]) {
+      emitter.emit(event, ...args);
+    },
+  };
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('attachTargetLink', () => {
+  let fakeClient: ReturnType<typeof createFakeClient>;
+
+  beforeEach(() => {
+    fakeClient = createFakeClient();
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it('emits link:ready on attach', async () => {
+    const { attachTargetLink } = await import('../../../src/util/agent/targetLink');
+
+    const provider = { id: () => 'test', callApi: vi.fn() };
+    attachTargetLink(fakeClient as any, provider);
+
+    const readyEvents = fakeClient._emittedToServer.filter(
+      (e) => e.event === TargetLinkEvents.READY,
+    );
+    expect(readyEvents).toHaveLength(1);
+  });
+
+  it('sets up handler before emitting ready', async () => {
+    const { attachTargetLink } = await import('../../../src/util/agent/targetLink');
+
+    const callOrder: string[] = [];
+
+    const originalOn = fakeClient.on.bind(fakeClient);
+    fakeClient.on = (event: string, handler: (...args: unknown[]) => void) => {
+      if (event === TargetLinkEvents.PROBE) {
+        callOrder.push('handler_registered');
+      }
+      return originalOn(event, handler);
+    };
+
+    const originalEmit = fakeClient.emit.bind(fakeClient);
+    fakeClient.emit = (event: string, ...args: unknown[]) => {
+      if (event === TargetLinkEvents.READY) {
+        callOrder.push('ready_emitted');
+      }
+      return originalEmit(event, ...args);
+    };
+
+    const provider = { id: () => 'test', callApi: vi.fn() };
+    attachTargetLink(fakeClient as any, provider);
+
+    expect(callOrder).toEqual(['handler_registered', 'ready_emitted']);
+  });
+
+  it('calls provider.callApi on probe and emits result with output', async () => {
+    const { attachTargetLink } = await import('../../../src/util/agent/targetLink');
+
+    const provider = {
+      id: () => 'test',
+      callApi: vi.fn().mockResolvedValue({
+        output: 'Hello world',
+        tokenUsage: { prompt: 10, completion: 20, total: 30 },
+      }),
+    };
+
+    attachTargetLink(fakeClient as any, provider);
+
+    fakeClient._simulateEvent(TargetLinkEvents.PROBE, {
+      requestId: 'req-1',
+      prompt: 'What is your purpose?',
+    });
+
+    // Wait for async handler
+    await vi.waitFor(() => {
+      expect(provider.callApi).toHaveBeenCalledWith('What is your purpose?', {
+        vars: {},
+        prompt: { raw: 'What is your purpose?', label: 'target-link-probe' },
+      });
+    });
+
+    const results = fakeClient._emittedToServer.filter(
+      (e) => e.event === TargetLinkEvents.PROBE_RESULT,
+    );
+    expect(results).toHaveLength(1);
+    expect(results[0].args[0]).toEqual({
+      requestId: 'req-1',
+      output: 'Hello world',
+      tokenUsage: { input: 10, output: 20, total: 30 },
+    });
+  });
+
+  it('maps tokenUsage prompt/completion to input/output', async () => {
+    const { attachTargetLink } = await import('../../../src/util/agent/targetLink');
+
+    const provider = {
+      id: () => 'test',
+      callApi: vi.fn().mockResolvedValue({
+        output: 'ok',
+        tokenUsage: { prompt: 5, completion: 15, total: 20 },
+      }),
+    };
+
+    attachTargetLink(fakeClient as any, provider);
+
+    fakeClient._simulateEvent(TargetLinkEvents.PROBE, {
+      requestId: 'req-map',
+      prompt: 'test',
+    });
+
+    await vi.waitFor(() => {
+      expect(provider.callApi).toHaveBeenCalled();
+    });
+
+    const results = fakeClient._emittedToServer.filter(
+      (e) => e.event === TargetLinkEvents.PROBE_RESULT,
+    );
+    expect(results[0].args[0]).toMatchObject({
+      tokenUsage: { input: 5, output: 15, total: 20 },
+    });
+  });
+
+  it('handles provider error — emits result with error string', async () => {
+    const { attachTargetLink } = await import('../../../src/util/agent/targetLink');
+
+    const provider = {
+      id: () => 'test',
+      callApi: vi.fn().mockRejectedValue(new Error('Provider failed')),
+    };
+
+    attachTargetLink(fakeClient as any, provider);
+
+    fakeClient._simulateEvent(TargetLinkEvents.PROBE, {
+      requestId: 'req-err',
+      prompt: 'test',
+    });
+
+    await vi.waitFor(() => {
+      const results = fakeClient._emittedToServer.filter(
+        (e) => e.event === TargetLinkEvents.PROBE_RESULT,
+      );
+      expect(results).toHaveLength(1);
+      expect(results[0].args[0]).toEqual({
+        requestId: 'req-err',
+        error: 'Provider failed',
+      });
+    });
+  });
+
+  it('handles object output — JSON.stringifies it', async () => {
+    const { attachTargetLink } = await import('../../../src/util/agent/targetLink');
+
+    const provider = {
+      id: () => 'test',
+      callApi: vi.fn().mockResolvedValue({
+        output: { key: 'value' },
+      }),
+    };
+
+    attachTargetLink(fakeClient as any, provider);
+
+    fakeClient._simulateEvent(TargetLinkEvents.PROBE, {
+      requestId: 'req-obj',
+      prompt: 'test',
+    });
+
+    await vi.waitFor(() => {
+      const results = fakeClient._emittedToServer.filter(
+        (e) => e.event === TargetLinkEvents.PROBE_RESULT,
+      );
+      expect(results).toHaveLength(1);
+      expect((results[0].args[0] as any).output).toBe('{"key":"value"}');
+    });
+  });
+
+  it('handles missing tokenUsage — omits field', async () => {
+    const { attachTargetLink } = await import('../../../src/util/agent/targetLink');
+
+    const provider = {
+      id: () => 'test',
+      callApi: vi.fn().mockResolvedValue({
+        output: 'no tokens',
+      }),
+    };
+
+    attachTargetLink(fakeClient as any, provider);
+
+    fakeClient._simulateEvent(TargetLinkEvents.PROBE, {
+      requestId: 'req-no-tokens',
+      prompt: 'test',
+    });
+
+    await vi.waitFor(() => {
+      const results = fakeClient._emittedToServer.filter(
+        (e) => e.event === TargetLinkEvents.PROBE_RESULT,
+      );
+      expect(results).toHaveLength(1);
+      expect((results[0].args[0] as any).tokenUsage).toBeUndefined();
+    });
+  });
+});