agent-gear 1.0.0

package/tests/acp-sync-bridge.test.ts

@@ -0,0 +1,263 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+function buildMockConn() {
+  return {
+    initialize: vi.fn<[unknown], Promise<{ protocolVersion: number }>>().mockResolvedValue({ protocolVersion: 1 }),
+    newSession: vi.fn<[unknown], Promise<{ sessionId: string }>>().mockResolvedValue({ sessionId: 'sync-sess-1' }),
+    listSessions: vi.fn<[unknown], Promise<{ sessions: Array<{ sessionId: string; title: string | null; cwd: string; updatedAt: string | null }> }>>()
+      .mockResolvedValue({ sessions: [{ sessionId: 'hist-1', title: 'Session 1', cwd: '/home/user', updatedAt: '2026-01-01T00:00:00Z' }] }),
+    loadSession: vi.fn<[unknown], Promise<object>>().mockResolvedValue({}),
+    cancel: vi.fn<[unknown], Promise<void>>().mockResolvedValue(undefined),
+    closeSession: vi.fn<[unknown], Promise<object>>().mockResolvedValue({}),
+  };
+}
+
+let mockConnInstance = buildMockConn();
+
+vi.mock('@agentclientprotocol/sdk', () => ({
+  ndJsonStream: vi.fn(() => ({})),
+  ClientSideConnection: vi.fn(function () { return mockConnInstance; }),
+}));
+
+import { AcpSyncBridge } from '../src/acp/sync-bridge.js';
+
+class MockAcpSpawner {
+  start = vi.fn();
+  stop = vi.fn();
+  isRunning = vi.fn().mockReturnValue(true);
+  _stdin = new WritableStream();
+  _stdout = new ReadableStream();
+  private _resolveClosed: (() => void) | null = null;
+  private _closed: Promise<void>;
+
+  constructor() {
+    this._closed = new Promise((resolve) => { this._resolveClosed = resolve; });
+  }
+
+  get stdin() { return this._stdin; }
+  get stdout() { return this._stdout; }
+  get closed() { return this._closed; }
+
+  triggerExit() {
+    this._resolveClosed?.();
+  }
+}
+
+function createBridge(spawner?: MockAcpSpawner) {
+  return new AcpSyncBridge({ cwd: '/home/user' }, spawner as never);
+}
+
+function mc() { return mockConnInstance; }
+
+describe('AcpSyncBridge', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockConnInstance = buildMockConn();
+  });
+
+  describe('connect', () => {
+    it('should spawn ACP process and initialize connection', async () => {
+      const mockSpawner = new MockAcpSpawner();
+      const bridge = createBridge(mockSpawner);
+      await bridge.connect();
+
+      expect(mockSpawner.start).toHaveBeenCalledOnce();
+      expect(mc().initialize).toHaveBeenCalledWith({
+        protocolVersion: 1,
+        clientCapabilities: {},
+        clientInfo: { name: 'agent-gear', version: '1.0.0' },
+      });
+    });
+
+    it('should throw when connection fails', async () => {
+      mc().initialize.mockRejectedValue(new Error('connection failed'));
+      const mockSpawner = new MockAcpSpawner();
+      const bridge = createBridge(mockSpawner);
+
+      await expect(bridge.connect()).rejects.toThrow('connection failed');
+    });
+
+    it('should throw when process exits during connect', async () => {
+      mc().initialize.mockReturnValue(new Promise(() => {}));
+      const mockSpawner = new MockAcpSpawner();
+      const bridge = createBridge(mockSpawner);
+
+      mockSpawner.triggerExit();
+
+      await expect(bridge.connect()).rejects.toThrow('ACP process exited unexpectedly');
+    });
+
+    it('should throw on connect timeout', async () => {
+      vi.useFakeTimers();
+      try {
+        mc().initialize.mockReturnValue(new Promise(() => {}));
+        const mockSpawner = new MockAcpSpawner();
+        const bridge = createBridge(mockSpawner);
+
+        const connectPromise = bridge.connect(1000);
+        vi.advanceTimersByTime(1000);
+
+        await expect(connectPromise).rejects.toThrow('timed out');
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+  });
+
+  describe('listSessions', () => {
+    it('should return session list from ACP', async () => {
+      const mockSpawner = new MockAcpSpawner();
+      const bridge = createBridge(mockSpawner);
+      await bridge.connect();
+
+      const result = await bridge.listSessions('/home/user');
+
+      expect(mc().listSessions).toHaveBeenCalledWith({ cwd: '/home/user' });
+      expect(result.sessions).toHaveLength(1);
+      expect(result.sessions[0].sessionId).toBe('hist-1');
+      expect(result.sessions[0].title).toBe('Session 1');
+    });
+
+    it('should return empty list when no sessions', async () => {
+      mc().listSessions.mockResolvedValue({ sessions: [] });
+      const mockSpawner = new MockAcpSpawner();
+      const bridge = createBridge(mockSpawner);
+      await bridge.connect();
+
+      const result = await bridge.listSessions('/home/user');
+
+      expect(result.sessions).toEqual([]);
+    });
+  });
+
+  describe('loadSession', () => {
+    it('should return config and collected updates', async () => {
+      mc().loadSession.mockResolvedValue({});
+      const mockSpawner = new MockAcpSpawner();
+      const bridge = createBridge(mockSpawner);
+      await bridge.connect();
+
+      const result = await bridge.loadSession('hist-1', '/home/user');
+
+      expect(mc().loadSession).toHaveBeenCalledWith({
+        cwd: '/home/user',
+        sessionId: 'hist-1',
+        mcpServers: [],
+      });
+      expect(result.updates).toEqual([]);
+    });
+
+    it('should collect sessionUpdate notifications during load', async () => {
+      let bridge!: AcpSyncBridge;
+      mc().loadSession.mockImplementation(async () => {
+        await bridge.sessionUpdate({
+          sessionId: 'hist-1',
+          update: { sessionUpdate: 'user_message_chunk', content: { type: 'text', text: 'hello' } },
+        } as never);
+        await bridge.sessionUpdate({
+          sessionId: 'hist-1',
+          update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'hi there' } },
+        } as never);
+        return {};
+      });
+
+      const mockSpawner = new MockAcpSpawner();
+      bridge = createBridge(mockSpawner);
+      await bridge.connect();
+
+      const result = await bridge.loadSession('hist-1', '/home/user');
+
+      expect(result.updates).toHaveLength(2);
+      expect(result.updates[0].update.sessionUpdate).toBe('user_message_chunk');
+      expect(result.updates[1].update.sessionUpdate).toBe('agent_message_chunk');
+    });
+
+    it('should throw when process exits during loadSession', async () => {
+      mc().loadSession.mockReturnValue(new Promise(() => {}));
+      const mockSpawner = new MockAcpSpawner();
+      const bridge = createBridge(mockSpawner);
+      await bridge.connect();
+
+      mockSpawner.triggerExit();
+
+      await expect(bridge.loadSession('hist-1', '/home/user')).rejects.toThrow('ACP process exited unexpectedly');
+    });
+
+    it('should throw on load-session timeout', async () => {
+      vi.useFakeTimers();
+      try {
+        mc().loadSession.mockReturnValue(new Promise(() => {}));
+        const mockSpawner = new MockAcpSpawner();
+        const bridge = createBridge(mockSpawner);
+        await bridge.connect();
+
+        const loadPromise = bridge.loadSession('hist-1', '/home/user', 1000);
+        vi.advanceTimersByTime(1000);
+
+        await expect(loadPromise).rejects.toThrow('timed out');
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+  });
+
+  describe('disconnect', () => {
+    it('should close session with given ID and stop spawner', async () => {
+      const mockSpawner = new MockAcpSpawner();
+      const bridge = createBridge(mockSpawner);
+      await bridge.connect();
+
+      await bridge.disconnect('hist-1');
+
+      expect(mc().closeSession).toHaveBeenCalledWith({ sessionId: 'hist-1' });
+      expect(mockSpawner.stop).toHaveBeenCalledOnce();
+    });
+
+    it('should skip closeSession when no sessionId given', async () => {
+      const mockSpawner = new MockAcpSpawner();
+      const bridge = createBridge(mockSpawner);
+      await bridge.connect();
+
+      await bridge.disconnect();
+
+      expect(mc().closeSession).not.toHaveBeenCalled();
+      expect(mockSpawner.stop).toHaveBeenCalledOnce();
+    });
+
+    it('should not throw when not connected', async () => {
+      const mockSpawner = new MockAcpSpawner();
+      const bridge = createBridge(mockSpawner);
+      await expect(bridge.disconnect()).resolves.not.toThrow();
+    });
+  });
+
+  describe('sessionUpdate', () => {
+    it('should collect notifications and return them in loadSession', async () => {
+      let bridge!: AcpSyncBridge;
+      mc().loadSession.mockImplementation(async () => {
+        await bridge.sessionUpdate({
+          sessionId: 'hist-1',
+          update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'test' } },
+        } as never);
+        return {};
+      });
+
+      const mockSpawner = new MockAcpSpawner();
+      bridge = createBridge(mockSpawner);
+      await bridge.connect();
+
+      const result = await bridge.loadSession('hist-1', '/home/user');
+      expect(result.updates).toHaveLength(1);
+    });
+  });
+
+  describe('requestPermission', () => {
+    it('should always reject', async () => {
+      const mockSpawner = new MockAcpSpawner();
+      const bridge = createBridge(mockSpawner);
+      const result = await bridge.requestPermission({} as never);
+
+      expect(result).toEqual({ outcome: { outcome: 'cancelled' } });
+    });
+  });
+});

package/tests/config.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+const TEST_CONFIG_DIR = join(tmpdir(), 'zag-test-config');
+const TEST_CONFIG_FILE = join(TEST_CONFIG_DIR, 'config.toml');
+
+vi.mock('smol-toml', () => ({
+  parse: vi.fn(),
+  stringify: vi.fn(),
+}));
+
+describe('Config', () => {
+  beforeEach(() => {
+    if (existsSync(TEST_CONFIG_DIR)) {
+      rmSync(TEST_CONFIG_DIR, { recursive: true });
+    }
+    mkdirSync(TEST_CONFIG_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_CONFIG_DIR)) {
+      rmSync(TEST_CONFIG_DIR, { recursive: true });
+    }
+  });
+
+  it('should read and write config', async () => {
+    const { parse, stringify } = await import('smol-toml');
+    const configContent = '[key]\nvalue = "zag_k_1_abc123"\n\n[server]\nendpoint = "http://localhost:4001"\n';
+    vi.mocked(parse).mockReturnValue({
+      key: { value: 'zag_k_1_abc123' },
+      server: { endpoint: 'http://localhost:4001' },
+    });
+    vi.mocked(stringify).mockReturnValue(configContent);
+
+    writeFileSync(TEST_CONFIG_FILE, configContent, 'utf-8');
+    const content = readFileSync(TEST_CONFIG_FILE, 'utf-8');
+    const parsed = parse(content);
+
+    expect(parsed).toEqual({
+      key: { value: 'zag_k_1_abc123' },
+      server: { endpoint: 'http://localhost:4001' },
+    });
+  });
+
+  it('should handle empty config', async () => {
+    const { parse } = await import('smol-toml');
+    vi.mocked(parse).mockReturnValue({});
+
+    const config = parse('');
+    expect(config).toEqual({});
+  });
+});
+
+describe('Config functions', () => {
+  describe('resolveKey', () => {
+    it('should return cli key when provided', async () => {
+      const { resolveKey } = await import('../src/config.js');
+      expect(resolveKey('cli-key')).toBe('cli-key');
+    });
+
+    it('should return env key when cli key not provided', async () => {
+      process.env.ZAG_CONTROLLER_KEY = 'env-key';
+      const { resolveKey } = await import('../src/config.js');
+      expect(resolveKey()).toBe('env-key');
+      delete process.env.ZAG_CONTROLLER_KEY;
+    });
+  });
+
+  describe('resolveEndpoint', () => {
+    it('should return cli endpoint when provided', async () => {
+      const { resolveEndpoint } = await import('../src/config.js');
+      expect(resolveEndpoint('http://cli:4001')).toBe('http://cli:4001');
+    });
+
+    it('should return env endpoint when cli endpoint not provided', async () => {
+      process.env.ZAG_SERVER_ENDPOINT = 'http://env:4001';
+      const { resolveEndpoint } = await import('../src/config.js');
+      expect(resolveEndpoint()).toBe('http://env:4001');
+      delete process.env.ZAG_SERVER_ENDPOINT;
+    });
+  });
+});
+
+describe('Heartbeat', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('should start and stop heartbeat', async () => {
+    const { Heartbeat } = await import('../src/heartbeat.js');
+    const heartbeat = new Heartbeat();
+    const sendFn = vi.fn();
+
+    heartbeat.start(sendFn);
+    vi.advanceTimersByTime(30_000);
+
+    expect(sendFn).toHaveBeenCalled();
+    heartbeat.stop();
+  });
+
+  it('should not call sendFn before interval', async () => {
+    const { Heartbeat } = await import('../src/heartbeat.js');
+    const heartbeat = new Heartbeat();
+    const sendFn = vi.fn();
+
+    heartbeat.start(sendFn);
+    vi.advanceTimersByTime(29_999);
+
+    expect(sendFn).not.toHaveBeenCalled();
+    heartbeat.stop();
+  });
+
+  it('should stop calling after stop', async () => {
+    const { Heartbeat } = await import('../src/heartbeat.js');
+    const heartbeat = new Heartbeat();
+    const sendFn = vi.fn();
+
+    heartbeat.start(sendFn);
+    heartbeat.stop();
+    vi.advanceTimersByTime(60_000);
+
+    expect(sendFn).not.toHaveBeenCalled();
+  });
+});
+
+describe('Daemon', () => {
+  it('should write and read pid', async () => {
+    const { writePid, readPid, removePid } = await import('../src/daemon.js');
+    writePid();
+    expect(readPid()).toBe(process.pid);
+    removePid();
+  });
+
+  it('should return null when no pid file', async () => {
+    const { readPid, removePid } = await import('../src/daemon.js');
+    removePid();
+    expect(readPid()).toBeNull();
+  });
+
+  it('should remove pid file', async () => {
+    const { writePid, readPid, removePid } = await import('../src/daemon.js');
+    writePid();
+    expect(readPid()).toBe(process.pid);
+    removePid();
+    expect(readPid()).toBeNull();
+  });
+
+  it('should detect running process', async () => {
+    const { writePid, isRunning, removePid } = await import('../src/daemon.js');
+    writePid();
+    expect(isRunning()).toBe(true);
+    removePid();
+  });
+
+  it('should detect non-running process', async () => {
+    const { isRunning, removePid } = await import('../src/daemon.js');
+    removePid();
+    expect(isRunning()).toBe(false);
+  });
+});

package/tests/socketio-client.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const { mockStart, mockStop, MockHeartbeat } = vi.hoisted(() => {
+  const start = vi.fn();
+  const stop = vi.fn();
+  const HB = vi.fn().mockImplementation(function () {
+    return { start, stop };
+  });
+  return { mockStart: start, mockStop: stop, MockHeartbeat: HB };
+});
+
+vi.mock('socket.io-client', () => ({
+  io: vi.fn(),
+}));
+
+vi.mock('../src/heartbeat.js', () => ({
+  Heartbeat: MockHeartbeat,
+}));
+
+vi.mock('../src/config.js', () => ({
+  clearConfigKey: vi.fn(),
+  saveKeyToConfig: vi.fn(),
+  saveEndpointToConfig: vi.fn(),
+}));
+
+vi.mock('os', () => ({
+  hostname: vi.fn().mockReturnValue('test-machine'),
+}));
+
+import { connectToServer, unregister } from '../src/socketio-client.js';
+import { io } from 'socket.io-client';
+import { clearConfigKey } from '../src/config.js';
+
+function createMockSocket() {
+  const handlers: Record<string, (...args: unknown[]) => void> = {};
+  return {
+    on: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+      handlers[event] = handler;
+    }),
+    emit: vi.fn(),
+    disconnect: vi.fn(),
+    close: vi.fn(),
+    _handlers: handlers,
+    _trigger: (event: string, ...args: unknown[]) => {
+      handlers[event]?.(...args);
+    },
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockStart.mockClear();
+  mockStop.mockClear();
+  vi.spyOn(process, 'exit').mockImplementation(() => undefined as never);
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('SocketIO Client', () => {
+  describe('connectToServer', () => {
+    it('should create socket with correct options', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123');
+
+      expect(io).toHaveBeenCalledWith('http://localhost:4001', {
+        transports: ['websocket'],
+        reconnection: true,
+        reconnectionDelay: 1000,
+        reconnectionDelayMax: 60000,
+      });
+    });
+
+    it('should emit register on connect', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123', { serverName: 'my-machine' });
+
+      mockSocket._trigger('connect');
+
+      expect(mockSocket.emit).toHaveBeenCalledWith('register', {
+        key: 'zag_k_1_abc123',
+        hostname: 'my-machine',
+        version: '1.0.0',
+      });
+    });
+
+    it('should use default hostname when serverName not provided', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123');
+
+      mockSocket._trigger('connect');
+
+      expect(mockSocket.emit).toHaveBeenCalledWith('register', {
+        key: 'zag_k_1_abc123',
+        hostname: 'test-machine',
+        version: '1.0.0',
+      });
+    });
+
+    it('should start heartbeat on registered', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123');
+
+      mockSocket._trigger('registered', { controllerId: 'ctrl123' });
+
+      expect(MockHeartbeat).toHaveBeenCalled();
+      expect(mockStart).toHaveBeenCalled();
+    });
+
+    it('should disconnect and exit on error', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123');
+
+      mockSocket._trigger('error', { code: 'INVALID_KEY', message: 'Invalid key' });
+
+      expect(mockSocket.disconnect).toHaveBeenCalled();
+      expect(process.exit).toHaveBeenCalledWith(1);
+    });
+
+    it('should clear config and exit on unregistered', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123');
+
+      mockSocket._trigger('unregistered');
+
+      expect(mockStop).toHaveBeenCalled();
+      expect(clearConfigKey).toHaveBeenCalled();
+      expect(mockSocket.close).toHaveBeenCalled();
+      expect(process.exit).toHaveBeenCalledWith(0);
+    });
+
+    it('should clear config and exit on shutdown', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123');
+
+      mockSocket._trigger('shutdown', { reason: 'key_revoked' });
+
+      expect(mockStop).toHaveBeenCalled();
+      expect(clearConfigKey).toHaveBeenCalled();
+      expect(mockSocket.close).toHaveBeenCalled();
+      expect(process.exit).toHaveBeenCalledWith(0);
+    });
+
+    it('should stop heartbeat on disconnect', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123');
+
+      mockSocket._trigger('disconnect', 'transport close');
+
+      expect(mockStop).toHaveBeenCalled();
+      expect(console.log).toHaveBeenCalledWith('Disconnected: transport close');
+    });
+
+    it('should log on connect_error', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123');
+
+      mockSocket._trigger('connect_error', new Error('connection failed'));
+
+      expect(console.error).toHaveBeenCalledWith('Connection error: connection failed');
+    });
+  });
+
+  describe('unregister', () => {
+    it('should emit unregister event', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      const socket = connectToServer('http://localhost:4001', 'zag_k_1_abc123');
+      unregister(socket);
+
+      expect(mockSocket.emit).toHaveBeenCalledWith('unregister', { reason: 'user_detach' });
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'text-summary'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.test.ts', 'src/index.ts'],
+    },
+  },
+});