@openclaw-cloud/agent-controller 0.1.4 → 0.1.5

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx tsc --noEmit

package/__tests__/api.test.ts

@@ -0,0 +1,123 @@
+import { createAgentApi } from '../src/api';
+
+const mockFetch = jest.fn();
+(global as any).fetch = mockFetch;
+
+function makeOkResponse(data: unknown, status = 200): Response {
+  return {
+    ok: true,
+    status,
+    json: jest.fn().mockResolvedValue(data),
+    text: jest.fn().mockResolvedValue(''),
+  } as unknown as Response;
+}
+
+function makeErrorResponse(status: number, body = ''): Response {
+  return {
+    ok: false,
+    status,
+    json: jest.fn(),
+    text: jest.fn().mockResolvedValue(body),
+  } as unknown as Response;
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('createAgentApi – get()', () => {
+  it('sends GET request with correct URL, method, and Authorization header', async () => {
+    const api = createAgentApi('http://backend', 'my-token');
+    mockFetch.mockResolvedValue(makeOkResponse({ ok: true }));
+
+    await api.get('/api/test');
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('http://backend/api/test');
+    expect(init.method).toBe('GET');
+    expect(init.headers['Authorization']).toBe('Bearer my-token');
+    expect(init.headers['Content-Type']).toBe('application/json');
+  });
+
+  it('returns parsed JSON body on success', async () => {
+    const api = createAgentApi('http://backend', 'tok');
+    const data = { id: 1, name: 'test' };
+    mockFetch.mockResolvedValue(makeOkResponse(data));
+
+    const result = await api.get('/resource');
+    expect(result).toEqual(data);
+  });
+
+  it('throws containing HTTP status when response is not ok', async () => {
+    const api = createAgentApi('http://backend', 'tok');
+    mockFetch.mockResolvedValue(makeErrorResponse(404));
+
+    await expect(api.get('/missing')).rejects.toThrow('HTTP 404');
+  });
+
+  it('throws containing the path in the error message', async () => {
+    const api = createAgentApi('http://backend', 'tok');
+    mockFetch.mockResolvedValue(makeErrorResponse(500));
+
+    await expect(api.get('/crash')).rejects.toThrow('/crash');
+  });
+
+  it('propagates network errors from fetch', async () => {
+    const api = createAgentApi('http://backend', 'tok');
+    mockFetch.mockRejectedValue(new Error('ECONNREFUSED'));
+
+    await expect(api.get('/path')).rejects.toThrow('ECONNREFUSED');
+  });
+});
+
+describe('createAgentApi – post()', () => {
+  it('sends POST request with correct URL, method, and Authorization header', async () => {
+    const api = createAgentApi('http://backend', 'my-token');
+    mockFetch.mockResolvedValue(makeOkResponse(null));
+
+    await api.post('/api/action');
+
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('http://backend/api/action');
+    expect(init.method).toBe('POST');
+    expect(init.headers['Authorization']).toBe('Bearer my-token');
+  });
+
+  it('serializes body as JSON when provided', async () => {
+    const api = createAgentApi('http://backend', 'tok');
+    mockFetch.mockResolvedValue(makeOkResponse(null));
+
+    await api.post('/endpoint', { key: 'value', num: 42 });
+
+    const [, init] = mockFetch.mock.calls[0];
+    expect(init.body).toBe('{"key":"value","num":42}');
+  });
+
+  it('omits body field when no body argument given', async () => {
+    const api = createAgentApi('http://backend', 'tok');
+    mockFetch.mockResolvedValue(makeOkResponse(null));
+
+    await api.post('/endpoint');
+
+    const [, init] = mockFetch.mock.calls[0];
+    expect(init.body).toBeUndefined();
+  });
+
+  it('returns the raw Response object without throwing on non-ok', async () => {
+    const api = createAgentApi('http://backend', 'tok');
+    const fakeRes = makeErrorResponse(400);
+    mockFetch.mockResolvedValue(fakeRes);
+
+    const result = await api.post('/endpoint', {});
+    expect(result).toBe(fakeRes);
+    expect(result.status).toBe(400);
+  });
+
+  it('propagates network errors from fetch', async () => {
+    const api = createAgentApi('http://backend', 'tok');
+    mockFetch.mockRejectedValue(new Error('timeout'));
+
+    await expect(api.post('/endpoint')).rejects.toThrow('timeout');
+  });
+});

package/__tests__/chat.test.ts

@@ -0,0 +1,191 @@
+import { handleChatListSessions, handleChatHistory, handleChatSend } from '../src/handlers/chat';
+import type { AgentCommand } from '../src/types';
+
+jest.mock('../src/openclaw/index');
+
+import { getChatProvider } from '../src/openclaw/index';
+
+const mockGetChatProvider = getChatProvider as jest.Mock;
+
+function makeCommand(
+  type: AgentCommand['type'],
+  payload: Record<string, unknown> = {},
+  id = 'cmd-1',
+): AgentCommand {
+  return { id, type, payload };
+}
+
+describe('handleChatListSessions', () => {
+  let publish: jest.Mock;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    publish = jest.fn().mockResolvedValue(undefined);
+  });
+
+  it('publishes error when provider is null', async () => {
+    mockGetChatProvider.mockReturnValue(null);
+    const cmd = makeCommand('chat_list_sessions');
+    await handleChatListSessions(cmd, publish);
+    expect(publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'chat_sessions_response',
+        correlationId: 'cmd-1',
+        sessions: [],
+        error: expect.stringContaining('not initialized'),
+      }),
+    );
+  });
+
+  it('publishes sessions on success', async () => {
+    const sessions = [{ key: 'sess-1', sessionId: 'sid-1', kind: 'direct', updatedAt: 0 }];
+    mockGetChatProvider.mockReturnValue({
+      listSessions: jest.fn().mockResolvedValue(sessions),
+    });
+    const cmd = makeCommand('chat_list_sessions');
+    await handleChatListSessions(cmd, publish);
+    expect(publish).toHaveBeenCalledWith({
+      type: 'chat_sessions_response',
+      correlationId: 'cmd-1',
+      sessions,
+    });
+  });
+
+  it('publishes error when provider.listSessions throws', async () => {
+    mockGetChatProvider.mockReturnValue({
+      listSessions: jest.fn().mockRejectedValue(new Error('db error')),
+    });
+    const cmd = makeCommand('chat_list_sessions');
+    await handleChatListSessions(cmd, publish);
+    expect(publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'chat_sessions_response',
+        sessions: [],
+        error: 'db error',
+      }),
+    );
+  });
+});
+
+describe('handleChatHistory', () => {
+  let publish: jest.Mock;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    publish = jest.fn().mockResolvedValue(undefined);
+  });
+
+  it('publishes messages on success', async () => {
+    const messages = [{ role: 'user', content: 'hello', timestamp: '2026-01-01T00:00:00Z' }];
+    mockGetChatProvider.mockReturnValue({
+      getHistory: jest.fn().mockResolvedValue(messages),
+    });
+    const cmd = makeCommand('chat_history', { sessionKey: 'sess-1', limit: 50 });
+    await handleChatHistory(cmd, publish);
+    expect(publish).toHaveBeenCalledWith({
+      type: 'chat_history_response',
+      correlationId: 'cmd-1',
+      messages,
+    });
+  });
+
+  it('publishes error when provider is null', async () => {
+    mockGetChatProvider.mockReturnValue(null);
+    const cmd = makeCommand('chat_history', { sessionKey: 'sess-1' });
+    await handleChatHistory(cmd, publish);
+    expect(publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'chat_history_response',
+        messages: [],
+        error: expect.stringContaining('not initialized'),
+      }),
+    );
+  });
+
+  it('publishes error when provider.getHistory throws', async () => {
+    mockGetChatProvider.mockReturnValue({
+      getHistory: jest.fn().mockRejectedValue(new Error('history error')),
+    });
+    const cmd = makeCommand('chat_history', { sessionKey: 'sess-1' });
+    await handleChatHistory(cmd, publish);
+    expect(publish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'chat_history_response',
+        messages: [],
+        error: 'history error',
+      }),
+    );
+  });
+});
+
+describe('handleChatSend', () => {
+  let publish: jest.Mock;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    publish = jest.fn().mockResolvedValue(undefined);
+  });
+
+  it('always sends typing indicator before checking provider', async () => {
+    mockGetChatProvider.mockReturnValue(null);
+    const cmd = makeCommand('chat_send', { sessionKey: 'sess-1', text: 'hi' });
+    await handleChatSend(cmd, publish, 'agent-1');
+    expect(publish).toHaveBeenCalledWith({ type: 'chat_typing', agentId: 'agent-1', state: true });
+  });
+
+  it('publishes error response when provider is null', async () => {
+    mockGetChatProvider.mockReturnValue(null);
+    const cmd = makeCommand('chat_send', { sessionKey: 'sess-1', text: 'hi' });
+    await handleChatSend(cmd, publish, 'agent-1');
+    const published = (publish as jest.Mock).mock.calls.map((c) => c[0]);
+    expect(published).toContainEqual(
+      expect.objectContaining({
+        type: 'chat_response',
+        correlationId: 'cmd-1',
+        error: expect.stringContaining('not initialized'),
+      }),
+    );
+  });
+
+  it('calls onDelta and onDone via sendMessage callbacks', async () => {
+    const sendMessage = jest.fn().mockImplementation(async (params: any) => {
+      await params.onDelta('partial');
+      await params.onDone('full response');
+    });
+    mockGetChatProvider.mockReturnValue({ sendMessage });
+    const cmd = makeCommand('chat_send', { sessionKey: 'sess-1', text: 'hi' });
+    await handleChatSend(cmd, publish, 'agent-1');
+    const published = (publish as jest.Mock).mock.calls.map((c) => c[0]);
+    expect(published).toContainEqual(
+      expect.objectContaining({ type: 'chat_delta', correlationId: 'cmd-1', text: 'partial' }),
+    );
+    expect(published).toContainEqual(
+      expect.objectContaining({ type: 'chat_response', correlationId: 'cmd-1', text: 'full response' }),
+    );
+  });
+
+  it('publishes error via onError callback', async () => {
+    const sendMessage = jest.fn().mockImplementation(async (params: any) => {
+      await params.onError('stream error');
+    });
+    mockGetChatProvider.mockReturnValue({ sendMessage });
+    const cmd = makeCommand('chat_send', { sessionKey: 'sess-1', text: 'hi' });
+    await handleChatSend(cmd, publish, 'agent-1');
+    const published = (publish as jest.Mock).mock.calls.map((c) => c[0]);
+    expect(published).toContainEqual(
+      expect.objectContaining({ type: 'chat_response', error: 'stream error' }),
+    );
+  });
+
+  it('publishes error when provider.sendMessage throws', async () => {
+    mockGetChatProvider.mockReturnValue({
+      sendMessage: jest.fn().mockRejectedValue(new Error('send failed')),
+    });
+    const cmd = makeCommand('chat_send', { sessionKey: 'sess-1', text: 'hi' });
+    await handleChatSend(cmd, publish, 'agent-1');
+    const published = (publish as jest.Mock).mock.calls.map((c) => c[0]);
+    expect(published).toContainEqual(
+      expect.objectContaining({ type: 'chat_response', error: 'send failed' }),
+    );
+  });
+});

package/__tests__/config.test.ts

@@ -0,0 +1,100 @@
+import { handleConfig } from '../src/handlers/config';
+import type { AgentCommand } from '../src/types';
+import childProcess from 'node:child_process';
+import fs from 'node:fs/promises';
+
+jest.mock('node:child_process');
+jest.mock('node:fs/promises');
+
+const mockExec = childProcess.exec as unknown as jest.Mock;
+const mockMkdir = fs.mkdir as jest.Mock;
+const mockWriteFile = fs.writeFile 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));
+  });
+}
+
+describe('handleConfig', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockMkdir.mockResolvedValue(undefined);
+    mockWriteFile.mockResolvedValue(undefined);
+  });
+
+  it('rejects missing filename', async () => {
+    const cmd: AgentCommand = { id: '1', type: 'config', payload: { content: 'some: config' } };
+    const res = await handleConfig(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Missing');
+  });
+
+  it('rejects missing content', async () => {
+    const cmd: AgentCommand = { id: '2', type: 'config', payload: { filename: 'test.yml' } };
+    const res = await handleConfig(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Missing');
+  });
+
+  it('creates directory, writes file, and runs restart on success', async () => {
+    fakeExec(null, 'restarted', '');
+    const cmd: AgentCommand = {
+      id: '3',
+      type: 'config',
+      payload: { filename: 'agent.yml', content: 'key: val' },
+    };
+    const res = await handleConfig(cmd);
+
+    expect(fs.mkdir).toHaveBeenCalledWith('/etc/openclaw', { recursive: true });
+    expect(fs.writeFile).toHaveBeenCalledWith(
+      expect.stringContaining('agent.yml'),
+      'key: val',
+      'utf-8',
+    );
+    expect(mockExec).toHaveBeenCalledWith(
+      'openclaw gateway restart',
+      expect.any(Object),
+      expect.any(Function),
+    );
+    expect(res.success).toBe(true);
+    expect(res.data?.path).toContain('agent.yml');
+  });
+
+  it('returns error when writeFile fails', async () => {
+    mockWriteFile.mockRejectedValue(new Error('EACCES: permission denied'));
+    const cmd: AgentCommand = {
+      id: '4',
+      type: 'config',
+      payload: { filename: 'agent.yml', content: 'key: val' },
+    };
+    const res = await handleConfig(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('EACCES');
+  });
+
+  it('returns success:false with error message when restart fails', async () => {
+    fakeExec(new Error('restart failed'), '', 'stderr output');
+    const cmd: AgentCommand = {
+      id: '5',
+      type: 'config',
+      payload: { filename: 'agent.yml', content: 'key: val' },
+    };
+    const res = await handleConfig(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toBe('restart failed');
+    expect(res.data?.path).toContain('agent.yml');
+  });
+
+  it('strips directory traversal from filename', async () => {
+    fakeExec(null, '', '');
+    const cmd: AgentCommand = {
+      id: '6',
+      type: 'config',
+      payload: { filename: '../../../etc/passwd', content: 'root:x:0:0' },
+    };
+    const res = await handleConfig(cmd);
+    // path.basename strips the directory part
+    expect(res.data?.path).toBe('/etc/openclaw/passwd');
+  });
+});

package/__tests__/file-write.test.ts

@@ -0,0 +1,119 @@
+import { handleFileWrite } from '../src/handlers/file-write';
+import type { AgentCommand } from '../src/types';
+import fs from 'node:fs/promises';
+
+jest.mock('node:fs/promises');
+
+const mockMkdir = fs.mkdir as jest.Mock;
+const mockWriteFile = fs.writeFile as jest.Mock;
+const mockAccess = fs.access as jest.Mock;
+
+const baseCmd: AgentCommand = { id: '1', type: 'file_write', payload: {} };
+
+describe('handleFileWrite', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockMkdir.mockResolvedValue(undefined);
+    mockWriteFile.mockResolvedValue(undefined);
+  });
+
+  it('writes file and returns written:true', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: 'config/agent.yml', content: 'key: val' } };
+    const res = await handleFileWrite(cmd);
+    expect(res.success).toBe(true);
+    expect(res.data?.written).toBe(true);
+    expect(mockWriteFile).toHaveBeenCalledWith(
+      expect.stringContaining('agent.yml'),
+      'key: val',
+      'utf-8',
+    );
+  });
+
+  it('skips write when overwrite=false and file already exists', async () => {
+    mockAccess.mockResolvedValue(undefined); // file exists
+    const cmd: AgentCommand = {
+      ...baseCmd,
+      payload: { path: 'config/agent.yml', content: 'key: val', overwrite: false },
+    };
+    const res = await handleFileWrite(cmd);
+    expect(res.success).toBe(true);
+    expect(res.data?.written).toBe(false);
+    expect(res.data?.skipped).toBe(true);
+    expect(mockWriteFile).not.toHaveBeenCalled();
+  });
+
+  it('writes when overwrite=false and file does not exist', async () => {
+    mockAccess.mockRejectedValue(new Error('ENOENT'));
+    const cmd: AgentCommand = {
+      ...baseCmd,
+      payload: { path: 'config/new.yml', content: 'data', overwrite: false },
+    };
+    const res = await handleFileWrite(cmd);
+    expect(res.success).toBe(true);
+    expect(res.data?.written).toBe(true);
+    expect(mockWriteFile).toHaveBeenCalled();
+  });
+
+  it('rejects path traversal with ".."', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: '../etc/passwd', content: 'root' } };
+    const res = await handleFileWrite(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Invalid path');
+    expect(mockWriteFile).not.toHaveBeenCalled();
+  });
+
+  it('rejects nested path traversal (foo/../bar)', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: 'foo/../bar/secret', content: 'x' } };
+    const res = await handleFileWrite(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Invalid path');
+    expect(mockWriteFile).not.toHaveBeenCalled();
+  });
+
+  it('rejects absolute path starting with "/"', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: '/etc/passwd', content: 'root' } };
+    const res = await handleFileWrite(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Invalid path');
+    expect(mockWriteFile).not.toHaveBeenCalled();
+  });
+
+  it('creates parent directories before writing', async () => {
+    const cmd: AgentCommand = {
+      ...baseCmd,
+      payload: { path: 'deep/nested/dir/file.txt', content: 'hello' },
+    };
+    const res = await handleFileWrite(cmd);
+    expect(res.success).toBe(true);
+    expect(mockMkdir).toHaveBeenCalledWith(expect.any(String), { recursive: true });
+  });
+
+  it('returns error when path is missing', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { content: 'data' } };
+    const res = await handleFileWrite(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Missing');
+  });
+
+  it('returns error when content is missing', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: 'file.txt' } };
+    const res = await handleFileWrite(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Missing');
+  });
+
+  it('allows empty string content', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: 'empty.txt', content: '' } };
+    const res = await handleFileWrite(cmd);
+    expect(res.success).toBe(true);
+    expect(mockWriteFile).toHaveBeenCalledWith(expect.any(String), '', 'utf-8');
+  });
+
+  it('returns error when writeFile fails', async () => {
+    mockWriteFile.mockRejectedValue(new Error('EACCES: permission denied'));
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: 'file.txt', content: 'data' } };
+    const res = await handleFileWrite(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('EACCES');
+  });
+});