@openclaw-cloud/agent-controller 0.1.4 → 0.1.6

package/__tests__/gateway-client.test.ts

@@ -0,0 +1,272 @@
+// Mock ws before importing anything that uses it.
+// The 'instances' array lives inside the factory closure and is exposed via the
+// static property so tests can grab the last created socket.
+jest.mock('ws', () => {
+  const { EventEmitter } = require('node:events');
+  const instances: any[] = [];
+
+  class MockWebSocket extends EventEmitter {
+    static OPEN = 1;
+    static instances = instances;
+    readyState = 1;
+    send = jest.fn();
+    close = jest.fn(() => (this as any).emit('close'));
+
+    constructor() {
+      super();
+      instances.push(this);
+    }
+  }
+
+  return MockWebSocket;
+});
+
+import WebSocket from 'ws';
+import { GatewayClient } from '../src/openclaw/gateway-client';
+
+const WS = WebSocket as any;
+
+function lastWs(): any {
+  return WS.instances[WS.instances.length - 1];
+}
+
+// Complete the connect handshake (challenge → auth → resolve).
+async function doConnect(client: GatewayClient): Promise<any> {
+  const connectPromise = client.connect();
+  const ws = lastWs();
+
+  ws.emit('message', JSON.stringify({ type: 'event', event: 'connect.challenge', payload: {} }));
+  await Promise.resolve(); // let the async handler send the auth request
+
+  const sent = JSON.parse(ws.send.mock.calls[0][0]);
+  ws.emit('message', JSON.stringify({ type: 'res', id: sent.id, ok: true, payload: {} }));
+  await connectPromise;
+
+  ws.send.mockClear();
+  return ws;
+}
+
+beforeEach(() => {
+  WS.instances.length = 0;
+  jest.clearAllMocks();
+});
+
+describe('GatewayClient – initial state', () => {
+  it('is not connected before connect()', () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    expect(client.isConnected()).toBe(false);
+  });
+
+  it('setEventHandler does not throw', () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    expect(() => client.setEventHandler(jest.fn())).not.toThrow();
+  });
+});
+
+describe('GatewayClient – request() before connect', () => {
+  it('rejects with "Not connected" when ws is null', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    await expect(client.request('test', {})).rejects.toThrow('Not connected');
+  });
+});
+
+describe('GatewayClient – disconnect()', () => {
+  it('is safe to call when not connected', () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    expect(() => client.disconnect()).not.toThrow();
+  });
+
+  it('marks client as not connected after connect → disconnect', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    await doConnect(client);
+
+    expect(client.isConnected()).toBe(true);
+    client.disconnect();
+    expect(client.isConnected()).toBe(false);
+  });
+
+  it('rejects pending requests on disconnect', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    const ws = await doConnect(client);
+
+    const pending = client.request('slow.method', {});
+    client.disconnect();
+
+    await expect(pending).rejects.toThrow('Connection closed');
+  });
+});
+
+describe('GatewayClient – connect()', () => {
+  it('creates WebSocket with the given url', async () => {
+    const client = new GatewayClient('ws://test-host:8000', 'tok');
+    await doConnect(client);
+    expect(WS.instances).toHaveLength(1);
+  });
+
+  it('sends auth request containing the token after connect.challenge', async () => {
+    const client = new GatewayClient('ws://localhost', 'secret-token');
+    const connectPromise = client.connect();
+    const ws = lastWs();
+
+    ws.emit('message', JSON.stringify({ type: 'event', event: 'connect.challenge', payload: {} }));
+    await Promise.resolve();
+
+    expect(ws.send).toHaveBeenCalledTimes(1);
+    const msg = JSON.parse(ws.send.mock.calls[0][0]);
+    expect(msg.method).toBe('connect');
+    expect(msg.params.auth.token).toBe('secret-token');
+    expect(msg.type).toBe('req');
+
+    ws.emit('message', JSON.stringify({ type: 'res', id: msg.id, ok: true, payload: {} }));
+    await connectPromise;
+  });
+
+  it('resolves and sets isConnected to true after successful auth', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    await doConnect(client);
+    expect(client.isConnected()).toBe(true);
+  });
+
+  it('rejects when WebSocket emits error before connecting', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    const connectPromise = client.connect();
+    lastWs().emit('error', new Error('ECONNREFUSED'));
+    await expect(connectPromise).rejects.toThrow('ECONNREFUSED');
+  });
+
+  it('rejects when auth response is an error', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    const connectPromise = client.connect();
+    const ws = lastWs();
+
+    ws.emit('message', JSON.stringify({ type: 'event', event: 'connect.challenge', payload: {} }));
+    await Promise.resolve();
+
+    const msg = JSON.parse(ws.send.mock.calls[0][0]);
+    ws.emit('message', JSON.stringify({ type: 'res', id: msg.id, ok: false, error: { message: 'Unauthorized' } }));
+
+    await expect(connectPromise).rejects.toThrow('Unauthorized');
+  });
+
+  it('ignores events other than connect.challenge during handshake', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    const connectPromise = client.connect();
+    const ws = lastWs();
+
+    ws.emit('message', JSON.stringify({ type: 'event', event: 'other.event', payload: {} }));
+    await Promise.resolve();
+    expect(ws.send).not.toHaveBeenCalled();
+
+    ws.emit('message', JSON.stringify({ type: 'event', event: 'connect.challenge', payload: {} }));
+    await Promise.resolve();
+    expect(ws.send).toHaveBeenCalledTimes(1);
+
+    const msg = JSON.parse(ws.send.mock.calls[0][0]);
+    ws.emit('message', JSON.stringify({ type: 'res', id: msg.id, ok: true, payload: {} }));
+    await connectPromise;
+  });
+
+  it('restores original event handler after auth completes', async () => {
+    const originalHandler = jest.fn();
+    const client = new GatewayClient('ws://localhost', 'token');
+    client.setEventHandler(originalHandler);
+    const ws = await doConnect(client);
+
+    // Post-connect event should reach the original handler
+    ws.emit('message', JSON.stringify({ type: 'event', event: 'some.event', payload: { x: 1 } }));
+    await Promise.resolve();
+
+    expect(originalHandler).toHaveBeenCalledWith(expect.objectContaining({ event: 'some.event' }));
+  });
+});
+
+describe('GatewayClient – request() after connect', () => {
+  it('sends request with correct type, method, params, and id fields', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    const ws = await doConnect(client);
+
+    const reqPromise = client.request('sessions.list', { limit: 10 });
+    expect(ws.send).toHaveBeenCalledTimes(1);
+
+    const sent = JSON.parse(ws.send.mock.calls[0][0]);
+    expect(sent.type).toBe('req');
+    expect(sent.method).toBe('sessions.list');
+    expect(sent.params).toEqual({ limit: 10 });
+    expect(typeof sent.id).toBe('string');
+
+    ws.emit('message', JSON.stringify({ type: 'res', id: sent.id, ok: true, payload: { sessions: [] } }));
+    const result = await reqPromise;
+    expect(result.sessions).toEqual([]);
+  });
+
+  it('rejects when response has ok:false', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    const ws = await doConnect(client);
+
+    const reqPromise = client.request('sessions.list', {});
+    const sent = JSON.parse(ws.send.mock.calls[0][0]);
+    ws.emit('message', JSON.stringify({ type: 'res', id: sent.id, ok: false, error: { message: 'Not found' } }));
+
+    await expect(reqPromise).rejects.toThrow('Not found');
+  });
+
+  it('rejects with generic message when error has no message field', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    const ws = await doConnect(client);
+
+    const reqPromise = client.request('test', {});
+    const sent = JSON.parse(ws.send.mock.calls[0][0]);
+    ws.emit('message', JSON.stringify({ type: 'res', id: sent.id, ok: false }));
+
+    await expect(reqPromise).rejects.toThrow('Request failed');
+  });
+
+  it('ignores response for an unknown request id', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    const ws = await doConnect(client);
+
+    const reqPromise = client.request('test', {});
+    ws.emit('message', JSON.stringify({ type: 'res', id: 'stale-id', ok: true, payload: {} }));
+    await Promise.resolve();
+
+    let resolved = false;
+    reqPromise.then(() => { resolved = true; }).catch(() => {});
+    await Promise.resolve();
+    expect(resolved).toBe(false);
+
+    // Clean up to avoid open handles
+    client.disconnect();
+    await reqPromise.catch(() => {});
+  });
+
+  it('ignores messages with unknown type', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    const ws = await doConnect(client);
+
+    expect(() => {
+      ws.emit('message', JSON.stringify({ type: 'unknown_type', id: 'x' }));
+    }).not.toThrow();
+  });
+
+  it('ignores malformed JSON messages', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    const ws = await doConnect(client);
+
+    expect(() => {
+      ws.emit('message', '{ bad json');
+    }).not.toThrow();
+  });
+});
+
+describe('GatewayClient – connection close', () => {
+  it('marks as disconnected and rejects pending requests when connection closes', async () => {
+    const client = new GatewayClient('ws://localhost', 'token');
+    const ws = await doConnect(client);
+
+    const pendingReq = client.request('test', {});
+    ws.emit('close');
+
+    await expect(pendingReq).rejects.toThrow('Connection closed');
+    expect(client.isConnected()).toBe(false);
+  });
+});

package/__tests__/onboarding.test.ts

@@ -0,0 +1,55 @@
+import { handleOnboardingComplete } from '../src/handlers/onboarding';
+import type { AgentCommand } from '../src/types';
+import childProcess from 'node:child_process';
+
+jest.mock('node:child_process');
+
+const mockExec = childProcess.exec as unknown as jest.Mock;
+
+function fakeExec(error: Error | null, stdout = '', stderr = '') {
+  mockExec.mockImplementation((_cmd: string, _opts: unknown, cb: Function) => {
+    cb(error, Buffer.from(stdout), Buffer.from(stderr));
+  });
+}
+
+const baseCmd: AgentCommand = { id: '1', type: 'onboarding_complete', payload: { agentId: 'agent-123' } };
+
+describe('handleOnboardingComplete', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('triggers "openclaw gateway restart" and returns success', async () => {
+    fakeExec(null, 'restarted', '');
+    const res = await handleOnboardingComplete(baseCmd);
+    expect(res.success).toBe(true);
+    expect(res.id).toBe('1');
+    expect(res.type).toBe('onboarding_complete');
+    expect(mockExec).toHaveBeenCalledWith(
+      'openclaw gateway restart',
+      expect.any(Object),
+      expect.any(Function),
+    );
+  });
+
+  it('returns success:false with error message when restart fails', async () => {
+    fakeExec(new Error('restart failed'), '', 'stderr output');
+    const res = await handleOnboardingComplete({ ...baseCmd, id: '2' });
+    expect(res.success).toBe(false);
+    expect(res.error).toBe('restart failed');
+    expect(res.id).toBe('2');
+  });
+
+  it('includes stdout and stderr in data', async () => {
+    fakeExec(null, 'gateway restarted ok', 'some warning');
+    const res = await handleOnboardingComplete(baseCmd);
+    expect(res.data?.stdout).toBe('gateway restarted ok');
+    expect(res.data?.stderr).toBe('some warning');
+  });
+
+  it('does not set error field on success', async () => {
+    fakeExec(null);
+    const res = await handleOnboardingComplete(baseCmd);
+    expect(res.error).toBeUndefined();
+  });
+});

package/__tests__/package-install.test.ts

@@ -0,0 +1,109 @@
+import { handlePackageInstall } from '../src/handlers/package-install';
+import type { AgentCommand } from '../src/types';
+import childProcess from 'node:child_process';
+
+jest.mock('node:child_process');
+
+const mockExec = childProcess.exec as unknown as jest.Mock;
+
+function fakeExec(error: Error | null) {
+  mockExec.mockImplementation((_cmd: string, _opts: unknown, cb: Function) => {
+    cb(error, Buffer.from(''), Buffer.from(''));
+  });
+}
+
+const baseCmd: AgentCommand = { id: '1', type: 'package_install', payload: {} };
+
+describe('handlePackageInstall', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('returns success with empty installed when no packages provided', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { packages: {} } };
+    const res = await handlePackageInstall(cmd);
+    expect(res.success).toBe(true);
+    expect(res.data?.installed).toEqual({ apt: [], npm: [], pip: [] });
+    expect(res.data?.errors).toEqual([]);
+    expect(mockExec).not.toHaveBeenCalled();
+  });
+
+  it('returns success with empty installed when packages key is missing', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: {} };
+    const res = await handlePackageInstall(cmd);
+    expect(res.success).toBe(true);
+    expect(res.data?.installed).toEqual({ apt: [], npm: [], pip: [] });
+    expect(mockExec).not.toHaveBeenCalled();
+  });
+
+  it('installs apt packages and runs apt-get install -y per package', async () => {
+    fakeExec(null);
+    const cmd: AgentCommand = { ...baseCmd, payload: { packages: { apt: ['curl', 'git'] } } };
+    const res = await handlePackageInstall(cmd);
+    expect(res.success).toBe(true);
+    expect((res.data?.installed as any).apt).toEqual(['curl', 'git']);
+    expect(mockExec).toHaveBeenCalledWith('apt-get install -y curl', expect.any(Object), expect.any(Function));
+    expect(mockExec).toHaveBeenCalledWith('apt-get install -y git', expect.any(Object), expect.any(Function));
+  });
+
+  it('installs npm packages with npm install -g', async () => {
+    fakeExec(null);
+    const cmd: AgentCommand = { ...baseCmd, payload: { packages: { npm: ['typescript'] } } };
+    const res = await handlePackageInstall(cmd);
+    expect(res.success).toBe(true);
+    expect((res.data?.installed as any).npm).toEqual(['typescript']);
+    expect(mockExec).toHaveBeenCalledWith('npm install -g typescript', expect.any(Object), expect.any(Function));
+  });
+
+  it('installs pip packages with pip install', async () => {
+    fakeExec(null);
+    const cmd: AgentCommand = { ...baseCmd, payload: { packages: { pip: ['requests'] } } };
+    const res = await handlePackageInstall(cmd);
+    expect(res.success).toBe(true);
+    expect((res.data?.installed as any).pip).toEqual(['requests']);
+    expect(mockExec).toHaveBeenCalledWith('pip install requests', expect.any(Object), expect.any(Function));
+  });
+
+  it('continues with other packages when one npm package fails (partial failure)', async () => {
+    let call = 0;
+    mockExec.mockImplementation((_cmd: string, _opts: unknown, cb: Function) => {
+      call === 0
+        ? cb(new Error('package not found'), Buffer.from(''), Buffer.from(''))
+        : cb(null, Buffer.from(''), Buffer.from(''));
+      call++;
+    });
+    const cmd: AgentCommand = { ...baseCmd, payload: { packages: { npm: ['bad-pkg', 'typescript'] } } };
+    const res = await handlePackageInstall(cmd);
+    expect(res.success).toBe(false);
+    expect((res.data?.installed as any).npm).toEqual(['typescript']);
+    expect((res.data?.errors as any[]).length).toBe(1);
+    expect((res.data?.errors as any[])[0].name).toBe('bad-pkg');
+    expect((res.data?.errors as any[])[0].error).toContain('package not found');
+  });
+
+  it('collects errors across all package types when all fail', async () => {
+    fakeExec(new Error('install failed'));
+    const cmd: AgentCommand = {
+      ...baseCmd,
+      payload: { packages: { apt: ['pkg1'], npm: ['pkg2'], pip: ['pkg3'] } },
+    };
+    const res = await handlePackageInstall(cmd);
+    expect(res.success).toBe(false);
+    expect((res.data?.errors as any[]).length).toBe(3);
+    expect((res.data?.installed as any)).toEqual({ apt: [], npm: [], pip: [] });
+  });
+
+  it('succeeds with success:true when all packages across all types install', async () => {
+    fakeExec(null);
+    const cmd: AgentCommand = {
+      ...baseCmd,
+      payload: { packages: { apt: ['curl'], npm: ['ts-node'], pip: ['boto3'] } },
+    };
+    const res = await handlePackageInstall(cmd);
+    expect(res.success).toBe(true);
+    expect((res.data?.errors as any[]).length).toBe(0);
+    expect((res.data?.installed as any).apt).toEqual(['curl']);
+    expect((res.data?.installed as any).npm).toEqual(['ts-node']);
+    expect((res.data?.installed as any).pip).toEqual(['boto3']);
+  });
+});

package/__tests__/pair.test.ts

@@ -0,0 +1,60 @@
+import { handlePair } from '../src/handlers/pair';
+import type { AgentCommand } from '../src/types';
+
+describe('handlePair', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv, AGENT_ID: 'agent-uuid-123' };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('rejects when token is missing', async () => {
+    const cmd: AgentCommand = { id: '1', type: 'pair', payload: { targetId: 'target-1' } };
+    const res = await handlePair(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Missing');
+  });
+
+  it('rejects when targetId is missing', async () => {
+    const cmd: AgentCommand = { id: '2', type: 'pair', payload: { token: 'abc' } };
+    const res = await handlePair(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Missing');
+  });
+
+  it('rejects when both token and targetId are missing', async () => {
+    const cmd: AgentCommand = { id: '3', type: 'pair', payload: {} };
+    const res = await handlePair(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Missing');
+  });
+
+  it('returns paired:true with targetId and agentId from env', async () => {
+    const cmd: AgentCommand = {
+      id: '4',
+      type: 'pair',
+      payload: { token: 'my-token', targetId: 'target-42' },
+    };
+    const res = await handlePair(cmd);
+    expect(res.success).toBe(true);
+    expect(res.data?.paired).toBe(true);
+    expect(res.data?.targetId).toBe('target-42');
+    expect(res.data?.agentId).toBe('agent-uuid-123');
+  });
+
+  it('returns agentId as undefined when AGENT_ID env var is not set', async () => {
+    delete process.env.AGENT_ID;
+    const cmd: AgentCommand = {
+      id: '5',
+      type: 'pair',
+      payload: { token: 'tok', targetId: 'target-1' },
+    };
+    const res = await handlePair(cmd);
+    expect(res.success).toBe(true);
+    expect(res.data?.agentId).toBeUndefined();
+  });
+});

package/__tests__/self-update.test.ts

@@ -0,0 +1,123 @@
+import { selfUpdate } from '../src/commands/self-update';
+import childProcess from 'node:child_process';
+
+jest.mock('node:child_process');
+
+const mockExec = childProcess.exec as unknown as jest.Mock;
+
+type ExecFakeResult = { error: Error | null; stdout: string };
+
+function fakeExecSequence(results: ExecFakeResult[]) {
+  let call = 0;
+  mockExec.mockImplementation((_cmd: string, _opts: unknown, cb: Function) => {
+    const result = results[call++] ?? { error: new Error('unexpected call'), stdout: '' };
+    cb(result.error, Buffer.from(result.stdout), Buffer.from(''));
+  });
+}
+
+describe('selfUpdate', () => {
+  let exitSpy: jest.SpyInstance;
+  let logSpy: jest.SpyInstance;
+  let errorSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => undefined as never);
+    logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+    errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('prints "Already up to date" and does not exit when version matches', async () => {
+    fakeExecSequence([{ error: null, stdout: '1.2.3' }]);
+
+    await selfUpdate('1.2.3');
+
+    expect(mockExec).toHaveBeenCalledTimes(1);
+    expect(mockExec).toHaveBeenCalledWith(
+      'npm view @openclaw-cloud/agent-controller version',
+      expect.any(Object),
+      expect.any(Function),
+    );
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Already up to date'));
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it('installs latest and calls process.exit(0) when a new version is available', async () => {
+    fakeExecSequence([
+      { error: null, stdout: '1.3.0' },
+      { error: null, stdout: '' },
+    ]);
+
+    await selfUpdate('1.2.3');
+
+    expect(mockExec).toHaveBeenCalledTimes(2);
+    expect(mockExec).toHaveBeenNthCalledWith(
+      1,
+      'npm view @openclaw-cloud/agent-controller version',
+      expect.any(Object),
+      expect.any(Function),
+    );
+    expect(mockExec).toHaveBeenNthCalledWith(
+      2,
+      'npm install -g @openclaw-cloud/agent-controller@latest',
+      expect.any(Object),
+      expect.any(Function),
+    );
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Updating from 1.2.3 to 1.3.0'));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Successfully updated to 1.3.0'));
+    expect(exitSpy).toHaveBeenCalledWith(0);
+  });
+
+  it('calls process.exit(1) when npm view fails', async () => {
+    fakeExecSequence([{ error: new Error('network error'), stdout: '' }]);
+
+    await selfUpdate('1.2.3');
+
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(errorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Failed to fetch latest version'),
+      'network error',
+    );
+    expect(mockExec).toHaveBeenCalledTimes(1);
+  });
+
+  it('calls process.exit(1) when npm install fails', async () => {
+    fakeExecSequence([
+      { error: null, stdout: '1.3.0' },
+      { error: new Error('npm install failed'), stdout: '' },
+    ]);
+
+    await selfUpdate('1.2.3');
+
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(errorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Update failed'),
+      'npm install failed',
+    );
+  });
+
+  it('logs current and latest versions before updating', async () => {
+    fakeExecSequence([
+      { error: null, stdout: '2.0.0' },
+      { error: null, stdout: '' },
+    ]);
+
+    await selfUpdate('1.0.0');
+
+    expect(logSpy).toHaveBeenCalledWith('Current version: 1.0.0');
+    expect(logSpy).toHaveBeenCalledWith('Latest version: 2.0.0');
+  });
+
+  it('trims whitespace from npm view output before comparing', async () => {
+    fakeExecSequence([{ error: null, stdout: '1.2.3\n' }]);
+
+    await selfUpdate('1.2.3');
+
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Already up to date'));
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+});

package/__tests__/stop.test.ts

@@ -0,0 +1,38 @@
+import { handleStop } from '../src/handlers/stop';
+import type { AgentCommand } from '../src/types';
+
+describe('handleStop', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    jest.spyOn(process, 'exit').mockImplementation(() => undefined as never);
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  });
+
+  it('returns success response with graceful shutdown message', async () => {
+    const cmd: AgentCommand = { id: '1', type: 'stop', payload: {} };
+    const res = await handleStop(cmd);
+    expect(res.success).toBe(true);
+    expect(res.data?.message).toContain('gracefully');
+    expect(res.id).toBe('1');
+    expect(res.type).toBe('stop');
+  });
+
+  it('does not call process.exit before 500ms', async () => {
+    const cmd: AgentCommand = { id: '2', type: 'stop', payload: {} };
+    await handleStop(cmd);
+    jest.advanceTimersByTime(499);
+    expect(process.exit).not.toHaveBeenCalled();
+  });
+
+  it('calls process.exit(0) after 500ms', async () => {
+    const cmd: AgentCommand = { id: '3', type: 'stop', payload: {} };
+    await handleStop(cmd);
+    expect(process.exit).not.toHaveBeenCalled();
+    jest.advanceTimersByTime(500);
+    expect(process.exit).toHaveBeenCalledWith(0);
+  });
+});

package/bin/agent-controller.js

@@ -1,5 +1,18 @@
 #!/usr/bin/env node
 
-import { main } from '../dist/index.js';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 
-main();
+const require = createRequire(import.meta.url);
+const pkg = require(join(dirname(fileURLToPath(import.meta.url)), '../package.json'));
+
+const [,, command] = process.argv;
+
+if (command === 'self-update') {
+  const { selfUpdate } = await import('../dist/commands/self-update.js');
+  await selfUpdate(pkg.version);
+} else {
+  const { main } = await import('../dist/index.js');
+  main();
+}

package/dist/commands/self-update.d.ts

@@ -0,0 +1 @@
+export declare function selfUpdate(currentVersion: string): Promise<void>;