@openclaw-cloud/agent-controller 0.1.3 → 0.1.5

package/.husky/pre-commit

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

package/CLAUDE.md

@@ -1,5 +1,64 @@
 # CLAUDE.md — Agent Controller Context
 
+Review this plan thoroughly before making any code changes. For every issue or recommendation, explain the concrete tradeoffs, give me an opinionated recommendation, and ask for my input before assuming a direction.
+
+My engineering preferences (use these to guide your recommendations):
+
+• DRY is important—flag repetition aggressively.
+• Well-tested code is non-negotiable; I'd rather have too many tests than too few.
+• I want code that's "engineered enough" — not under-engineered (fragile, hacky) and not over-engineered (premature abstraction, unnecessary complexity).
+• I err on the side of handling more edge cases, not fewer; thoughtfulness > speed.
+• Bias toward explicit over clever.
+
+1. Architecture review
+   Evaluate:
+
+• Overall system design and component boundaries.
+• Dependency graph and coupling concerns.
+• Data flow patterns and potential bottlenecks.
+• Scaling characteristics and single points of failure.
+• Security architecture (auth, data access, API boundaries).
+2. Code quality review
+   Evaluate:
+
+• Code organization and module structure.
+• DRY violations—be aggressive here.
+• Error handling patterns and missing edge cases (call these out explicitly).
+• Technical debt hotspots.
+• Areas that are over-engineered or under-engineered relative to my preferences.
+3. Test review
+   Evaluate:
+
+• Test coverage gaps (unit, integration, e2e).
+• Test quality and assertion strength.
+• Missing edge case coverage—be thorough.
+• Untested failure modes and error paths.
+4. Performance review
+   Evaluate:
+
+• N+1 queries and database access patterns.
+• Memory-usage concerns.
+• Caching opportunities.
+• Slow or high-complexity code paths.
+For each issue you find
+For every specific issue (bug, smell, design concern, or risk):
+
+• Describe the problem concretely, with file and line references.
+• Present 2–3 options, including "do nothing" where that's reasonable.
+• For each option, specify: implementation effort, risk, impact on other code, and maintenance burden.
+• Give me your recommended option and why, mapped to my preferences above.
+• Then explicitly ask whether I agree or want to choose a different direction before proceeding.
+Workflow and interaction
+
+• Do not assume my priorities on timeline or scale.
+• After each section, pause and ask for my feedback before moving on.
+BEFORE YOU START:
+Ask if I want one of two options:
+1/ BIG CHANGE: Work through this interactively, one section at a time (Architecture → Code Quality → Tests → Performance) with at most 4 top issues in each section.
+2/ SMALL CHANGE: Work through interactively ONE question per review section
+
+FOR EACH STAGE OF REVIEW: output the explanation and pros and cons of each stage's questions AND your opinionated recommendation and why, and then use AskUserQuestion. Also NUMBER issues and then give LETTERS for options and when using AskUserQuestion make sure each option clearly labels the issue NUMBER and option LETTER so the user doesn't get confused. Make the recommended option always the 1st option.
+
 ## Quick Reference
 
 ```bash

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__/board-handler.test.ts

@@ -16,12 +16,14 @@ function mockApi(overrides: Partial<AgentApi> = {}): AgentApi {
 
 function makeBoardInfo(opts: Partial<{
   boardId: string;
+  workspaceId: string;
   myColumnIds: string[];
   columns: BoardInfo['board']['columns'];
 }> = {}): BoardInfo {
   return {
     board: {
       id: opts.boardId ?? 'board-1',
+      workspaceId: opts.workspaceId ?? 'ws-1',
       myColumnIds: opts.myColumnIds ?? ['col-1'],
       columns: opts.columns ?? [{
         id: 'col-1',
@@ -70,13 +72,14 @@ describe('BoardHandler', () => {
   });
 
   describe('initialize', () => {
-    it('sets boardId and myColumnIds from API response', async () => {
-      const info = makeBoardInfo({ boardId: 'b-42', myColumnIds: ['c-1', 'c-2'] });
+    it('sets boardId, workspaceId and myColumnIds from API response', async () => {
+      const info = makeBoardInfo({ boardId: 'b-42', workspaceId: 'ws-99', myColumnIds: ['c-1', 'c-2'] });
       (api.get as jest.Mock).mockResolvedValue(info);
 
       const result = await handler.initialize();
 
-      expect(result).toBe('b-42');
+      // initialize() returns workspaceId for channel subscription
+      expect(result).toBe('ws-99');
       expect(handler.getBoardId()).toBe('b-42');
       expect(api.get).toHaveBeenCalledWith('/api/agent/board');
     });

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