@openclaw-cloud/agent-controller 0.2.5 → 0.2.7

package/CLAUDE.md

@@ -1,172 +0,0 @@
-# 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.
-
-## Codebase Navigation
-
-### Project Structure
-```
-src/
-├── index.ts           # Entry point — parse args, start connection
-├── connection.ts      # Centrifugo WS client, command dispatcher
-├── heartbeat.ts       # Periodic heartbeat publisher
-├── api.ts             # HTTP client for backend API calls
-├── types.ts           # AgentCommand, AgentResponse, CommandType
-├── handlers/          # Command handlers (backend → agent)
-│   ├── file-write.ts      # Write file to workspace
-│   ├── file-delete.ts     # Delete file from workspace
-│   ├── package-install.ts # Install apt/npm/pip packages
-│   ├── restart.ts         # Restart openclaw gateway
-│   ├── stop.ts            # Stop agent
-│   ├── backup.ts          # Create workspace backup
-│   ├── config.ts          # Update config files
-│   ├── deploy.ts          # Deploy/redeploy
-│   ├── exec.ts            # Execute shell commands
-│   ├── chat.ts            # Chat relay
-│   ├── onboarding.ts      # Onboarding completion
-│   ├── pair.ts            # Node pairing
-│   ├── board-handler.ts   # Kanban board integration
-│   └── self-update.ts     # Self-update via npm
-├── commands/          # CLI subcommands (agent-controller <cmd>)
-│   └── self-update.ts # `agent-controller self-update`
-└── openclaw/          # OpenClaw gateway process management
-```
-
-### Command dispatch flow
-```
-Centrifugo WS message → connection.ts (handler map) → handlers/<type>.ts → AgentResponse → POST /api/internal/agent-response
-```
-
-Handler map in `connection.ts`:
-```ts
-const handlers: Record<CommandType, Handler> = {
-  package_install: handlePackageInstall,
-  file_write: handleFileWrite,
-  file_delete: handleFileDelete,
-  restart: handleRestart,
-  // ...
-};
-```
-
-### Adding a new command handler
-1. Create `src/handlers/my-handler.ts` — export `async function handleMyHandler(cmd: AgentCommand): Promise<AgentResponse>`
-2. Add `'my_handler'` to `CommandType` union in `src/types.ts`
-3. Register in handler map in `src/connection.ts`
-4. Backend sends via `container.centrifugo.publishCommand(agentId, { type: 'my_handler', id, payload })`
-
-### Known Issues & Pitfalls
-- **WORKSPACE_DIR**: Defaults to `/etc/openclaw/workspace`. All file operations are sandboxed here (no `..`, no absolute paths).
-- **Command names must match backend exactly**: e.g. `package_install` not `install_packages`. Mismatches silently drop.
-- **npm publish required**: After changes, bump version in `package.json`, `npm publish`, then update agent Dockerfile + user-data.ts to pull new version.
-- **PID 1 kill**: If agent-controller crashes, it kills PID 1 to force K8s pod restart. Don't swallow fatal errors.
-
-## Quick Reference
-
-```bash
-npx jest --forceExit           # Run tests
-npx tsc --noEmit               # Type check
-npm run build                  # Build
-```
-
-## Architecture
-
-Agent-controller is a Node.js process that runs inside every agent container (K8s pod) or VM. It's the single communication interface between the agent and the backend.
-
-### Communication Flow
-```
-Backend → Centrifugo WS (port 8000) → agent-controller → local agent process
-agent-controller → Backend HTTP API → /api/internal/agent-response  (command responses)
-agent-controller → Backend HTTP API → /api/internal/agent-heartbeat  (heartbeat)
-```
-
-Centrifugo WS is **read-only** from agent-controller's perspective — all outbound traffic goes through the backend HTTP API, not directly to Centrifugo.
-
-### Key Components
-- **WebSocket client** — Connects to Centrifugo, subscribes to agent channel (read-only)
-- **Heartbeat publisher** — Sends periodic heartbeats via `POST /api/internal/agent-heartbeat`
-- **Command handlers** — Processes commands from backend, sends responses via `POST /api/internal/agent-response`
-- **Board handler** — Kanban board integration (claim cards, move cards, report status)
-- **JWT auth** — Fetches JWT from backend's `/api/internal/centrifugo-token` endpoint, auto-refreshes before expiry (24h TTL)
-
-### Environment Variables
-- `AGENT_ID` — UUID of this agent
-- `AGENT_TOKEN` — Internal auth token
-- `CENTRIFUGO_URL` — WebSocket URL (port 8000, converted from http→ws)
-- `API_BASE_URL` — Backend API URL (JWT fetch, agent responses, heartbeat)
-
-### Deployment
-
-Agent-controller is delivered via **npm** (not Docker image copy):
-
-- **K8s pods**: `npm install -g @openclaw-cloud/agent-controller` in agent Dockerfile (`backend/charts/openclaw-kube/Dockerfile`)
-- **VMs**: `npm install -g @openclaw-cloud/agent-controller` in EC2 user-data script (`backend/src/modules/vm-provisioner/user-data.ts`)
-- Runs in same container/VM as OpenClaw agent (not sidecar)
-- Started via bash wrapper in K8s StatefulSet command
-- PID monitoring: if agent-controller dies, `kill 1` terminates container → K8s restarts pod
-
-### Docker
-
-The `Dockerfile` in this repo is for **local development and testing only**. It is NOT used in production. Production installs agent-controller from npm registry.
-
-
-## Business Context
-
-For full understanding of all platform components, architecture, deployment models, roadmap, and unit-economics — see `BIZPLAN.md` in this repo.
-

package/Dockerfile

@@ -1,9 +0,0 @@
-# Agent Controller — standalone build image
-FROM node:22-alpine AS build
-
-WORKDIR /app
-COPY package.json package-lock.json ./
-RUN npm ci --omit=dev
-COPY dist/ dist/
-COPY bin/ bin/
-RUN chmod +x bin/agent-controller.js

package/__tests__/api.test.ts

@@ -1,183 +0,0 @@
-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');
-  });
-});
-
-describe('createAgentApi – publishResponse()', () => {
-  it('POSTs to /api/internal/agent-response with agentId and data', async () => {
-    const api = createAgentApi('http://backend', 'tok');
-    mockFetch.mockResolvedValue(makeOkResponse(null));
-
-    await api.publishResponse('agent-1', { id: 'cmd-1', type: 'exec', success: true });
-
-    const [url, init] = mockFetch.mock.calls[0];
-    expect(url).toBe('http://backend/api/internal/agent-response');
-    expect(init.method).toBe('POST');
-    expect(JSON.parse(init.body)).toEqual({
-      agentId: 'agent-1',
-      data: { id: 'cmd-1', type: 'exec', success: true },
-    });
-  });
-
-  it('throws when response is not ok', async () => {
-    const api = createAgentApi('http://backend', 'tok');
-    mockFetch.mockResolvedValue(makeErrorResponse(503));
-
-    await expect(api.publishResponse('agent-1', {})).rejects.toThrow('HTTP 503');
-  });
-
-  it('propagates network errors', async () => {
-    const api = createAgentApi('http://backend', 'tok');
-    mockFetch.mockRejectedValue(new Error('ECONNREFUSED'));
-
-    await expect(api.publishResponse('agent-1', {})).rejects.toThrow('ECONNREFUSED');
-  });
-});
-
-describe('createAgentApi – publishHeartbeat()', () => {
-  it('POSTs to /api/internal/agent-heartbeat with agentId and payload', async () => {
-    const api = createAgentApi('http://backend', 'tok');
-    mockFetch.mockResolvedValue(makeOkResponse(null));
-
-    const payload = { type: 'heartbeat', agentId: 'agent-1', ts: 123, metrics: {} };
-    await api.publishHeartbeat('agent-1', payload);
-
-    const [url, init] = mockFetch.mock.calls[0];
-    expect(url).toBe('http://backend/api/internal/agent-heartbeat');
-    expect(init.method).toBe('POST');
-    expect(JSON.parse(init.body)).toEqual({ agentId: 'agent-1', payload });
-  });
-
-  it('throws when response is not ok', async () => {
-    const api = createAgentApi('http://backend', 'tok');
-    mockFetch.mockResolvedValue(makeErrorResponse(500));
-
-    await expect(api.publishHeartbeat('agent-1', {})).rejects.toThrow('HTTP 500');
-  });
-
-  it('propagates network errors', async () => {
-    const api = createAgentApi('http://backend', 'tok');
-    mockFetch.mockRejectedValue(new Error('timeout'));
-
-    await expect(api.publishHeartbeat('agent-1', {})).rejects.toThrow('timeout');
-  });
-});

package/__tests__/backup.test.ts

@@ -1,145 +0,0 @@
-import { handleBackup } from '../src/handlers/backup';
-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 mockStat = fs.stat as jest.Mock;
-const mockReadFile = fs.readFile as jest.Mock;
-const mockUnlink = fs.unlink as jest.Mock;
-
-function fakeExecSuccess() {
-  mockExec.mockImplementation((_cmd: string, _opts: unknown, cb: Function) => {
-    cb(null, Buffer.from(''), Buffer.from(''));
-  });
-}
-
-function fakeExecError(message: string, stderr = '') {
-  mockExec.mockImplementation((_cmd: string, _opts: unknown, cb: Function) => {
-    cb(new Error(message), Buffer.from(''), Buffer.from(stderr));
-  });
-}
-
-const mockFetch = jest.fn() as jest.Mock;
-(globalThis as any).fetch = mockFetch;
-
-describe('handleBackup', () => {
-  beforeEach(() => {
-    jest.clearAllMocks();
-    mockUnlink.mockResolvedValue(undefined);
-  });
-
-  it('rejects missing uploadUrl', async () => {
-    const cmd: AgentCommand = { id: '1', type: 'backup', payload: {} };
-    const res = await handleBackup(cmd);
-    expect(res.success).toBe(false);
-    expect(res.error).toContain('Missing "uploadUrl"');
-  });
-
-  it('creates tar, uploads, cleans up on success', async () => {
-    fakeExecSuccess();
-    mockStat.mockResolvedValue({ size: 1024 });
-    mockReadFile.mockResolvedValue(Buffer.from('fake-archive'));
-    mockFetch.mockResolvedValue({ ok: true, status: 200, statusText: 'OK' });
-
-    const cmd: AgentCommand = {
-      id: '2',
-      type: 'backup',
-      payload: { uploadUrl: 'https://backend.test/upload' },
-    };
-    const res = await handleBackup(cmd);
-
-    expect(res.success).toBe(true);
-    expect(res.data?.size).toBe(1024);
-    expect(res.data?.filename).toMatch(/^backup-\d+\.tar\.gz$/);
-
-    // verify tar command
-    expect(mockExec).toHaveBeenCalledWith(
-      expect.stringContaining('tar -czf /tmp/backup-'),
-      expect.any(Object),
-      expect.any(Function),
-    );
-
-    // verify upload
-    expect(mockFetch).toHaveBeenCalledWith(
-      'https://backend.test/upload',
-      expect.objectContaining({ method: 'POST' }),
-    );
-
-    // verify cleanup
-    expect(mockUnlink).toHaveBeenCalledWith(expect.stringContaining('/tmp/backup-'));
-  });
-
-  it('returns error when tar fails', async () => {
-    fakeExecError('tar failed', 'No such file or directory');
-
-    const cmd: AgentCommand = {
-      id: '3',
-      type: 'backup',
-      payload: { uploadUrl: 'https://backend.test/upload' },
-    };
-    const res = await handleBackup(cmd);
-
-    expect(res.success).toBe(false);
-    expect(res.error).toContain('tar failed');
-    expect(mockUnlink).toHaveBeenCalled();
-  });
-
-  it('returns error when upload fails', async () => {
-    fakeExecSuccess();
-    mockStat.mockResolvedValue({ size: 512 });
-    mockReadFile.mockResolvedValue(Buffer.from('fake'));
-    mockFetch.mockResolvedValue({ ok: false, status: 500, statusText: 'Internal Server Error', text: () => Promise.resolve('') });
-
-    const cmd: AgentCommand = {
-      id: '4',
-      type: 'backup',
-      payload: { uploadUrl: 'https://backend.test/upload' },
-    };
-    const res = await handleBackup(cmd);
-
-    expect(res.success).toBe(false);
-    expect(res.error).toContain('Upload failed');
-    expect(res.error).toContain('500');
-    expect(mockUnlink).toHaveBeenCalled();
-  });
-
-  it('returns error when fetch throws (network error)', async () => {
-    fakeExecSuccess();
-    mockStat.mockResolvedValue({ size: 256 });
-    mockReadFile.mockResolvedValue(Buffer.from('fake'));
-    mockFetch.mockRejectedValue(new Error('network error'));
-
-    const cmd: AgentCommand = {
-      id: '5',
-      type: 'backup',
-      payload: { uploadUrl: 'https://backend.test/upload' },
-    };
-    const res = await handleBackup(cmd);
-
-    expect(res.success).toBe(false);
-    expect(res.error).toContain('network error');
-    expect(mockUnlink).toHaveBeenCalled();
-  });
-
-  it('cleans up even if unlink fails', async () => {
-    fakeExecSuccess();
-    mockStat.mockResolvedValue({ size: 100 });
-    mockReadFile.mockResolvedValue(Buffer.from('fake'));
-    mockFetch.mockResolvedValue({ ok: true, status: 200, statusText: 'OK' });
-    mockUnlink.mockRejectedValue(new Error('ENOENT'));
-
-    const cmd: AgentCommand = {
-      id: '6',
-      type: 'backup',
-      payload: { uploadUrl: 'https://backend.test/upload' },
-    };
-    const res = await handleBackup(cmd);
-
-    // should still succeed despite cleanup error
-    expect(res.success).toBe(true);
-  });
-});