@openclaw-cloud/agent-controller 0.1.4 → 0.1.6

package/__tests__/file-delete.test.ts

@@ -0,0 +1,90 @@
+import { handleFileDelete } from '../src/handlers/file-delete';
+import type { AgentCommand } from '../src/types';
+import fs from 'node:fs/promises';
+
+jest.mock('node:fs/promises');
+
+const mockUnlink = fs.unlink as jest.Mock;
+
+const baseCmd: AgentCommand = { id: '1', type: 'file_delete', payload: {} };
+
+describe('handleFileDelete', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockUnlink.mockResolvedValue(undefined);
+  });
+
+  it('deletes file and returns success', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: 'config/agent.yml' } };
+    const res = await handleFileDelete(cmd);
+    expect(res.success).toBe(true);
+    expect(mockUnlink).toHaveBeenCalledWith(expect.stringContaining('agent.yml'));
+  });
+
+  it('returns resolved path in data on success', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: 'some/file.txt' } };
+    const res = await handleFileDelete(cmd);
+    expect(res.success).toBe(true);
+    expect(res.data?.path).toEqual(expect.stringContaining('file.txt'));
+  });
+
+  it('rejects path traversal with ".."', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: '../etc/passwd' } };
+    const res = await handleFileDelete(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Invalid path');
+    expect(mockUnlink).not.toHaveBeenCalled();
+  });
+
+  it('rejects nested path traversal (foo/../bar)', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: 'foo/../bar/secret' } };
+    const res = await handleFileDelete(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Invalid path');
+    expect(mockUnlink).not.toHaveBeenCalled();
+  });
+
+  it('rejects absolute path starting with "/"', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: '/etc/passwd' } };
+    const res = await handleFileDelete(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Invalid path');
+    expect(mockUnlink).not.toHaveBeenCalled();
+  });
+
+  it('returns error when path is missing', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: {} };
+    const res = await handleFileDelete(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('Missing');
+    expect(mockUnlink).not.toHaveBeenCalled();
+  });
+
+  it('returns error when unlink fails (file not found)', async () => {
+    mockUnlink.mockRejectedValue(new Error('ENOENT: no such file or directory'));
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: 'missing.txt' } };
+    const res = await handleFileDelete(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('ENOENT');
+  });
+
+  it('returns error when unlink fails (permission denied)', async () => {
+    mockUnlink.mockRejectedValue(new Error('EACCES: permission denied'));
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: 'protected.txt' } };
+    const res = await handleFileDelete(cmd);
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('EACCES');
+  });
+
+  it('response type is file_delete', async () => {
+    const cmd: AgentCommand = { ...baseCmd, payload: { path: 'file.txt' } };
+    const res = await handleFileDelete(cmd);
+    expect(res.type).toBe('file_delete');
+  });
+
+  it('response id matches command id', async () => {
+    const cmd: AgentCommand = { ...baseCmd, id: 'unique-cmd-id', payload: { path: 'file.txt' } };
+    const res = await handleFileDelete(cmd);
+    expect(res.id).toBe('unique-cmd-id');
+  });
+});

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');
+  });
+});

package/__tests__/gateway-adapter.test.ts

@@ -0,0 +1,366 @@
+// Mock GatewayClient before importing gateway-adapter
+jest.mock('../src/openclaw/gateway-client');
+
+import { GatewayClient } from '../src/openclaw/gateway-client';
+import { OpenclawGatewayAdapter } from '../src/openclaw/gateway-adapter';
+
+const MockGatewayClient = GatewayClient as jest.MockedClass<typeof GatewayClient>;
+
+type EventHandler = (event: { event: string; payload: any }) => void;
+
+function makeAdapter(): {
+  adapter: OpenclawGatewayAdapter;
+  mock: jest.Mocked<GatewayClient>;
+  simulateStreamEvent: (payload: Record<string, unknown>) => void;
+} {
+  const mock: jest.Mocked<GatewayClient> = {
+    connect: jest.fn().mockResolvedValue(undefined),
+    disconnect: jest.fn(),
+    isConnected: jest.fn().mockReturnValue(false),
+    request: jest.fn().mockResolvedValue(undefined),
+    setEventHandler: jest.fn(),
+  } as unknown as jest.Mocked<GatewayClient>;
+
+  MockGatewayClient.mockImplementation(() => mock);
+
+  const adapter = new OpenclawGatewayAdapter('ws://localhost', 'token');
+
+  // Capture the event handler registered in the constructor
+  const capturedHandler: EventHandler = mock.setEventHandler.mock.calls[0][0];
+
+  return {
+    adapter,
+    mock,
+    simulateStreamEvent: (payload) => capturedHandler({ event: 'chat.stream', payload }),
+  };
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  MockGatewayClient.mockClear();
+});
+
+describe('OpenclawGatewayAdapter – construction', () => {
+  it('creates a GatewayClient and registers an event handler', () => {
+    const { mock } = makeAdapter();
+    expect(MockGatewayClient).toHaveBeenCalledTimes(1);
+    expect(mock.setEventHandler).toHaveBeenCalledTimes(1);
+    expect(mock.setEventHandler).toHaveBeenCalledWith(expect.any(Function));
+  });
+});
+
+describe('OpenclawGatewayAdapter – isConnected()', () => {
+  it('delegates to GatewayClient.isConnected()', () => {
+    const { adapter, mock } = makeAdapter();
+    mock.isConnected.mockReturnValueOnce(false);
+    expect(adapter.isConnected()).toBe(false);
+    mock.isConnected.mockReturnValueOnce(true);
+    expect(adapter.isConnected()).toBe(true);
+  });
+});
+
+describe('OpenclawGatewayAdapter – connect()', () => {
+  it('delegates to GatewayClient.connect()', async () => {
+    const { adapter, mock } = makeAdapter();
+    await adapter.connect();
+    expect(mock.connect).toHaveBeenCalledTimes(1);
+  });
+
+  it('propagates rejection from GatewayClient.connect()', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.connect.mockRejectedValue(new Error('ECONNREFUSED'));
+    await expect(adapter.connect()).rejects.toThrow('ECONNREFUSED');
+  });
+});
+
+describe('OpenclawGatewayAdapter – disconnect()', () => {
+  it('delegates to GatewayClient.disconnect()', () => {
+    const { adapter, mock } = makeAdapter();
+    adapter.disconnect();
+    expect(mock.disconnect).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('OpenclawGatewayAdapter – listSessions()', () => {
+  it('calls request("sessions.list", {}) and maps result', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue({
+      sessions: [
+        { key: 's1', sessionId: 'sid-1', kind: 'direct', updatedAt: 1000, model: 'claude-3' },
+        { key: 's2', sessionId: 'sid-2', kind: 'project', updatedAt: 2000 },
+      ],
+    });
+
+    const result = await adapter.listSessions();
+
+    expect(mock.request).toHaveBeenCalledWith('sessions.list', {});
+    expect(result).toHaveLength(2);
+    expect(result[0]).toMatchObject({ key: 's1', sessionId: 'sid-1', kind: 'direct', updatedAt: 1000, model: 'claude-3' });
+    expect(result[1]).toMatchObject({ key: 's2', sessionId: 'sid-2', kind: 'project', updatedAt: 2000 });
+  });
+
+  it('uses default values for missing session fields', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue({ sessions: [{ key: 'k1' }] });
+
+    const result = await adapter.listSessions();
+
+    expect(result[0]).toMatchObject({ key: 'k1', sessionId: '', kind: 'direct', updatedAt: 0 });
+  });
+
+  it('returns [] when result is null', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue(null);
+
+    const result = await adapter.listSessions();
+    expect(result).toEqual([]);
+  });
+
+  it('returns [] when sessions field is missing', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue({});
+
+    const result = await adapter.listSessions();
+    expect(result).toEqual([]);
+  });
+});
+
+describe('OpenclawGatewayAdapter – getHistory()', () => {
+  it('calls request("chat.history") with sessionKey and default limit 200', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue({ messages: [] });
+
+    await adapter.getHistory('sess-1');
+
+    expect(mock.request).toHaveBeenCalledWith('chat.history', { sessionKey: 'sess-1', limit: 200 });
+  });
+
+  it('passes custom limit when provided', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue({ messages: [] });
+
+    await adapter.getHistory('sess-1', 50);
+
+    expect(mock.request).toHaveBeenCalledWith('chat.history', { sessionKey: 'sess-1', limit: 50 });
+  });
+
+  it('filters out system and tool messages', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue({
+      messages: [
+        { role: 'user', content: 'hello', timestamp: '2026-01-01T00:00:00Z' },
+        { role: 'system', content: 'ignored' },
+        { role: 'assistant', content: 'hi', timestamp: '2026-01-01T00:00:01Z' },
+        { role: 'tool', content: 'ignored' },
+      ],
+    });
+
+    const result = await adapter.getHistory('sess-1');
+
+    expect(result).toHaveLength(2);
+    expect(result[0].role).toBe('user');
+    expect(result[1].role).toBe('assistant');
+  });
+
+  it('concatenates text blocks when content is an array', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue({
+      messages: [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'foo' },
+            { type: 'image', data: 'ignored' },
+            { type: 'text', text: 'bar' },
+          ],
+          timestamp: 0,
+        },
+      ],
+    });
+
+    const result = await adapter.getHistory('sess-1');
+    expect(result[0].content).toBe('foobar');
+  });
+
+  it('uses string content directly', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue({
+      messages: [{ role: 'user', content: 'plain text', timestamp: '2026-01-01T00:00:00Z' }],
+    });
+
+    const result = await adapter.getHistory('sess-1');
+    expect(result[0].content).toBe('plain text');
+  });
+
+  it('converts numeric timestamp to ISO string', async () => {
+    const { adapter, mock } = makeAdapter();
+    const ts = Date.UTC(2026, 0, 1, 12, 0, 0);
+    mock.request.mockResolvedValue({
+      messages: [{ role: 'user', content: 'hi', timestamp: ts }],
+    });
+
+    const result = await adapter.getHistory('sess-1');
+    expect(result[0].timestamp).toBe(new Date(ts).toISOString());
+  });
+
+  it('returns [] when result is null', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue(null);
+
+    const result = await adapter.getHistory('sess-1');
+    expect(result).toEqual([]);
+  });
+});
+
+describe('OpenclawGatewayAdapter – sendMessage()', () => {
+  it('sends chat.send request with correct payload', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue(undefined);
+
+    await adapter.sendMessage({ sessionKey: 'sess-1', text: 'hello', idempotencyKey: 'idem-1' });
+
+    expect(mock.request).toHaveBeenCalledWith('chat.send', {
+      sessionKey: 'sess-1',
+      message: 'hello',
+      deliver: false,
+      idempotencyKey: 'idem-1',
+    });
+  });
+
+  it('includes attachments in payload when provided', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue(undefined);
+    const attachments = [{ type: 'image' as const, mimeType: 'image/png', content: 'base64data' }];
+
+    await adapter.sendMessage({ sessionKey: 'sess-1', text: 'hi', idempotencyKey: 'k1', attachments });
+
+    const [, payload] = mock.request.mock.calls[0] as [string, any];
+    expect(payload.attachments).toEqual(attachments);
+  });
+
+  it('omits attachments field when not provided', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue(undefined);
+
+    await adapter.sendMessage({ sessionKey: 'sess-1', text: 'hi', idempotencyKey: 'k1' });
+
+    const [, payload] = mock.request.mock.calls[0] as [string, any];
+    expect(payload.attachments).toBeUndefined();
+  });
+
+  it('calls onError and removes callback when request throws', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockRejectedValue(new Error('network fail'));
+    const onError = jest.fn();
+
+    await adapter.sendMessage({ sessionKey: 'sess-1', text: 'hi', idempotencyKey: 'k1', onError });
+
+    expect(onError).toHaveBeenCalledWith('network fail');
+  });
+
+  it('calls onDelta when delta stream event arrives', async () => {
+    const { adapter, mock, simulateStreamEvent } = makeAdapter();
+    mock.request.mockResolvedValue(undefined);
+    const onDelta = jest.fn();
+
+    await adapter.sendMessage({ sessionKey: 'sess-1', text: 'hi', idempotencyKey: 'k1', onDelta });
+    simulateStreamEvent({ sessionKey: 'sess-1', runId: 'k1', state: 'delta', message: 'partial text' });
+
+    expect(onDelta).toHaveBeenCalledWith('partial text');
+  });
+
+  it('calls onDone with accumulated text on final event', async () => {
+    const { adapter, mock, simulateStreamEvent } = makeAdapter();
+    mock.request.mockResolvedValue(undefined);
+    const onDone = jest.fn();
+
+    await adapter.sendMessage({ sessionKey: 'sess-1', text: 'hi', idempotencyKey: 'k1', onDone });
+    simulateStreamEvent({ sessionKey: 'sess-1', runId: 'k1', state: 'delta', message: 'full text' });
+    simulateStreamEvent({ sessionKey: 'sess-1', runId: 'k1', state: 'final' });
+
+    expect(onDone).toHaveBeenCalledWith('full text');
+  });
+
+  it('calls onDone on aborted event with last accumulated text', async () => {
+    const { adapter, mock, simulateStreamEvent } = makeAdapter();
+    mock.request.mockResolvedValue(undefined);
+    const onDone = jest.fn();
+
+    await adapter.sendMessage({ sessionKey: 'sess-1', text: 'hi', idempotencyKey: 'k1', onDone });
+    simulateStreamEvent({ sessionKey: 'sess-1', runId: 'k1', state: 'delta', message: 'partial' });
+    simulateStreamEvent({ sessionKey: 'sess-1', runId: 'k1', state: 'aborted' });
+
+    expect(onDone).toHaveBeenCalledWith('partial');
+  });
+
+  it('calls onError when error stream event arrives with string error', async () => {
+    const { adapter, mock, simulateStreamEvent } = makeAdapter();
+    mock.request.mockResolvedValue(undefined);
+    const onError = jest.fn();
+
+    await adapter.sendMessage({ sessionKey: 'sess-1', text: 'hi', idempotencyKey: 'k1', onError });
+    simulateStreamEvent({ sessionKey: 'sess-1', runId: 'k1', state: 'error', error: 'stream error' });
+
+    expect(onError).toHaveBeenCalledWith('stream error');
+  });
+
+  it('calls onError with error.message when error is an object', async () => {
+    const { adapter, mock, simulateStreamEvent } = makeAdapter();
+    mock.request.mockResolvedValue(undefined);
+    const onError = jest.fn();
+
+    await adapter.sendMessage({ sessionKey: 'sess-1', text: 'hi', idempotencyKey: 'k1', onError });
+    simulateStreamEvent({ sessionKey: 'sess-1', runId: 'k1', state: 'error', error: { message: 'obj error' } });
+
+    expect(onError).toHaveBeenCalledWith('obj error');
+  });
+
+  it('ignores stream events with unknown runId', async () => {
+    const { adapter, mock, simulateStreamEvent } = makeAdapter();
+    mock.request.mockResolvedValue(undefined);
+    const onDelta = jest.fn();
+
+    await adapter.sendMessage({ sessionKey: 'sess-1', text: 'hi', idempotencyKey: 'k1', onDelta });
+    simulateStreamEvent({ sessionKey: 'sess-1', runId: 'unknown-id', state: 'delta', message: 'x' });
+
+    expect(onDelta).not.toHaveBeenCalled();
+  });
+
+  it('ignores events with missing sessionKey in payload', async () => {
+    const { adapter, mock, simulateStreamEvent } = makeAdapter();
+    mock.request.mockResolvedValue(undefined);
+    const onDelta = jest.fn();
+
+    await adapter.sendMessage({ sessionKey: 'sess-1', text: 'hi', idempotencyKey: 'k1', onDelta });
+    simulateStreamEvent({ runId: 'k1', state: 'delta', message: 'x' } as any);
+
+    expect(onDelta).not.toHaveBeenCalled();
+  });
+});
+
+describe('OpenclawGatewayAdapter – abort()', () => {
+  it('calls chat.abort with sessionKey and runId', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue(undefined);
+
+    await adapter.abort('sess-1', 'run-1');
+
+    expect(mock.request).toHaveBeenCalledWith('chat.abort', { sessionKey: 'sess-1', runId: 'run-1' });
+  });
+
+  it('calls chat.abort without runId when not provided', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockResolvedValue(undefined);
+
+    await adapter.abort('sess-1');
+
+    expect(mock.request).toHaveBeenCalledWith('chat.abort', { sessionKey: 'sess-1', runId: undefined });
+  });
+
+  it('does not throw when request rejects', async () => {
+    const { adapter, mock } = makeAdapter();
+    mock.request.mockRejectedValue(new Error('abort failed'));
+
+    await expect(adapter.abort('sess-1', 'run-1')).resolves.toBeUndefined();
+  });
+});