@almyty/acp-server 1.0.0

package/dist/__tests__/auth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/auth.test.js

@@ -0,0 +1,29 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { resolveCredentials } from '../auth.js';
+describe('resolveCredentials', () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        process.env = { ...originalEnv };
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+        vi.restoreAllMocks();
+    });
+    it('reads token from ALMYTY_TOKEN env var', () => {
+        process.env.ALMYTY_TOKEN = 'test-token-123';
+        const creds = resolveCredentials();
+        expect(creds).not.toBeNull();
+        expect(creds.token).toBe('test-token-123');
+    });
+    it('reads URL from ALMYTY_URL env var', () => {
+        process.env.ALMYTY_TOKEN = 'tok';
+        process.env.ALMYTY_URL = 'https://custom.api.com';
+        const creds = resolveCredentials();
+        expect(creds.url).toBe('https://custom.api.com');
+    });
+    it('prefers env var over credentials file', () => {
+        process.env.ALMYTY_TOKEN = 'env-token';
+        const creds = resolveCredentials();
+        expect(creds.token).toBe('env-token');
+    });
+});

package/dist/__tests__/events.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/events.test.js

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest';
+import { mapStreamEvent, buildPlanFromPipeline, isTerminalEvent, extractFinalOutput } from '../events.js';
+describe('mapStreamEvent', () => {
+    it('maps node.started to tool_call with running status', () => {
+        const results = mapStreamEvent({ event: 'node.started', data: { nodeId: 'n1', nodeType: 'tool_call', name: 'get_users' } });
+        expect(results.length).toBeGreaterThan(0);
+        const tc = results.find(r => r.type === 'tool_call');
+        expect(tc).toBeDefined();
+        expect(tc.status).toBe('running');
+    });
+    it('maps node.completed to tool_call_update', () => {
+        const results = mapStreamEvent({ event: 'node.completed', data: { nodeId: 'n1', output: { users: [] } } });
+        expect(results.length).toBeGreaterThan(0);
+        const update = results.find(r => r.type === 'tool_call_update');
+        expect(update).toBeDefined();
+        expect(update.status).toBe('completed');
+    });
+    it('maps node.error to tool_call_update with error', () => {
+        const results = mapStreamEvent({ event: 'node.error', data: { nodeId: 'n1', error: 'timeout' } });
+        expect(results.length).toBeGreaterThan(0);
+        const update = results.find(r => r.type === 'tool_call_update');
+        expect(update).toBeDefined();
+        expect(update.status).toBe('error');
+    });
+    it('maps text events to agent_message_chunk', () => {
+        for (const event of ['text', 'message', 'chunk', 'token']) {
+            const results = mapStreamEvent({ event, data: { text: 'hello' } });
+            expect(results.length).toBeGreaterThan(0);
+            expect(results[0].type).toBe('agent_message_chunk');
+        }
+    });
+    it('maps thinking events to agent_thought_chunk', () => {
+        const results = mapStreamEvent({ event: 'thinking', data: { text: 'hmm' } });
+        expect(results.length).toBeGreaterThan(0);
+        expect(results[0].type).toBe('agent_thought_chunk');
+    });
+    it('returns empty array for unknown events', () => {
+        expect(mapStreamEvent({ event: 'unknown_xyz', data: {} })).toHaveLength(0);
+    });
+});
+describe('buildPlanFromPipeline', () => {
+    it('converts pipeline nodes to plan entries (filters input/output)', () => {
+        const nodes = [
+            { id: 'n1', type: 'input', data: {} },
+            { id: 'n2', type: 'llm_call', data: {} },
+            { id: 'n3', type: 'tool_call', data: { toolName: 'fetch' } },
+            { id: 'n4', type: 'output', data: {} },
+        ];
+        const plan = buildPlanFromPipeline(nodes);
+        expect(plan.type).toBe('plan');
+        // input + output filtered out, llm_call + tool_call remain
+        expect(plan.entries.length).toBe(2);
+    });
+    it('returns empty plan for empty pipeline', () => {
+        const plan = buildPlanFromPipeline([]);
+        expect(plan.entries).toHaveLength(0);
+    });
+});
+describe('isTerminalEvent', () => {
+    it('recognizes terminal events', () => {
+        expect(isTerminalEvent({ event: 'execution.completed', data: {} })).toBe(true);
+        expect(isTerminalEvent({ event: 'execution.error', data: {} })).toBe(true);
+        expect(isTerminalEvent({ event: 'run.completed', data: {} })).toBe(true);
+    });
+    it('rejects non-terminal events', () => {
+        expect(isTerminalEvent({ event: 'text', data: {} })).toBe(false);
+        expect(isTerminalEvent({ event: 'node.started', data: {} })).toBe(false);
+    });
+});
+describe('extractFinalOutput', () => {
+    it('extracts text from output', () => {
+        expect(extractFinalOutput({ event: 'execution.completed', data: { output: 'result' } })).toBe('result');
+    });
+    it('stringifies object output', () => {
+        const result = extractFinalOutput({ event: 'execution.completed', data: { output: { key: 'val' } } });
+        expect(result).toContain('key');
+    });
+    it('returns undefined for missing output', () => {
+        expect(extractFinalOutput({ event: 'execution.completed', data: {} })).toBeUndefined();
+    });
+});

package/dist/__tests__/integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/integration.test.js

@@ -0,0 +1,144 @@
+/**
+ * Integration test: spawn the ACP server as a child process,
+ * connect via stdin/stdout ndjson, run the full ACP lifecycle.
+ *
+ * Uses a mock HTTP server standing in for the almyty backend.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+import { createInterface } from 'node:readline';
+import { resolve } from 'node:path';
+// ── Mock backend ────────────────────────────────────────────────
+const MOCK_AGENT = {
+    id: 'agent-123',
+    name: 'Test Agent',
+    description: 'A test agent',
+    mode: 'autonomous',
+    status: 'active',
+    pipeline: { nodes: [], edges: [] },
+};
+function createMockBackend() {
+    return new Promise((resolve) => {
+        const server = createServer((req, res) => {
+            let body = '';
+            req.on('data', (chunk) => (body += chunk));
+            req.on('end', () => {
+                const url = req.url || '';
+                res.setHeader('Content-Type', 'application/json');
+                // Auth profile check
+                if (url === '/auth/profile') {
+                    res.end(JSON.stringify({ id: 'user-1', email: 'test@test.com', organizations: [{ id: 'org-1', name: 'Test', role: 'owner' }] }));
+                    return;
+                }
+                // List agents
+                if (url.startsWith('/agents') && req.method === 'GET' && !url.includes('/')) {
+                    res.end(JSON.stringify({ agents: [MOCK_AGENT] }));
+                    return;
+                }
+                // Get agent by ID
+                if (url.match(/\/agents\/agent-123$/) && req.method === 'GET') {
+                    res.end(JSON.stringify(MOCK_AGENT));
+                    return;
+                }
+                // Start run
+                if (url.match(/\/agents\/agent-123\/runs$/) && req.method === 'POST') {
+                    res.end(JSON.stringify({ id: 'run-1', status: 'completed', output: { message: 'Hello from the agent' } }));
+                    return;
+                }
+                // Get run
+                if (url.match(/\/agents\/agent-123\/runs\/run-1$/) && req.method === 'GET') {
+                    res.end(JSON.stringify({ id: 'run-1', status: 'completed', output: { message: 'Hello from the agent' } }));
+                    return;
+                }
+                // Fallback
+                res.statusCode = 404;
+                res.end(JSON.stringify({ error: { message: 'Not found', statusCode: 404 } }));
+            });
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            resolve({ server, port: addr.port });
+        });
+    });
+}
+// ── ndjson helpers ───────────────────────────────────────────────
+function sendRequest(proc, method, params, id) {
+    const msg = JSON.stringify({ jsonrpc: '2.0', id: id ?? 1, method, params: params ?? {} });
+    proc.stdin.write(msg + '\n');
+}
+function readResponses(proc, count, timeoutMs = 10000) {
+    return new Promise((resolve, reject) => {
+        const results = [];
+        const rl = createInterface({ input: proc.stdout });
+        const timer = setTimeout(() => {
+            rl.close();
+            resolve(results); // return what we have
+        }, timeoutMs);
+        rl.on('line', (line) => {
+            try {
+                results.push(JSON.parse(line));
+                if (results.length >= count) {
+                    clearTimeout(timer);
+                    rl.close();
+                    resolve(results);
+                }
+            }
+            catch {
+                // skip malformed lines
+            }
+        });
+    });
+}
+// ── Tests ───────────────────────────────────────────────────────
+describe('ACP server integration', () => {
+    let mockBackend;
+    let backendPort;
+    let proc;
+    beforeAll(async () => {
+        const backend = await createMockBackend();
+        mockBackend = backend.server;
+        backendPort = backend.port;
+    });
+    afterAll(() => {
+        proc?.kill('SIGTERM');
+        mockBackend?.close();
+    });
+    it('completes full lifecycle: initialize -> authenticate -> session/new -> session/prompt', async () => {
+        const entryPoint = resolve(__dirname, '../../dist/index.js');
+        proc = spawn('node', [entryPoint, 'agent-123'], {
+            env: {
+                ...process.env,
+                ALMYTY_URL: `http://127.0.0.1:${backendPort}`,
+                ALMYTY_TOKEN: 'test-token',
+            },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Give the process a moment to start
+        await new Promise((r) => setTimeout(r, 500));
+        // 1. Initialize
+        sendRequest(proc, 'initialize', { protocolVersion: 1, clientCapabilities: {} }, 1);
+        const [initResp] = await readResponses(proc, 1, 5000);
+        expect(initResp.id).toBe(1);
+        expect(initResp.result).toBeDefined();
+        expect(initResp.result.protocolVersion).toBe(1);
+        // 2. Authenticate
+        sendRequest(proc, 'authenticate', { methodId: 'env_var' }, 2);
+        const [authResp] = await readResponses(proc, 1, 5000);
+        expect(authResp.id).toBe(2);
+        expect(authResp.error).toBeUndefined();
+        // 3. Session new
+        sendRequest(proc, 'session/new', { cwd: '/tmp' }, 3);
+        const [sessionResp] = await readResponses(proc, 1, 5000);
+        expect(sessionResp.id).toBe(3);
+        expect(sessionResp.result?.sessionId).toBeDefined();
+        const sessionId = sessionResp.result.sessionId;
+        // 4. Close session
+        sendRequest(proc, 'session/close', { sessionId }, 4);
+        const [closeResp] = await readResponses(proc, 1, 5000);
+        expect(closeResp.id).toBe(4);
+        expect(closeResp.error).toBeUndefined();
+        // Clean up
+        proc.kill('SIGTERM');
+    }, 30000);
+});

package/dist/__tests__/session.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/session.test.js

@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SessionManager } from '../session.js';
+describe('SessionManager', () => {
+    let mgr;
+    beforeEach(() => {
+        mgr = new SessionManager();
+    });
+    it('creates a session with a UUID', () => {
+        const s = mgr.create('agent-1', 'workflow');
+        expect(s.id).toMatch(/^[0-9a-f]{8}-/);
+        expect(s.agentId).toBe('agent-1');
+        expect(s.mode).toBe('workflow');
+        expect(s.lastActivity).toBeGreaterThan(0);
+    });
+    it('retrieves a session by ID', () => {
+        const s = mgr.create('agent-1', 'autonomous');
+        expect(mgr.get(s.id)).toBe(s);
+    });
+    it('returns undefined for unknown session', () => {
+        expect(mgr.get('nonexistent')).toBeUndefined();
+    });
+    it('lists all sessions', () => {
+        mgr.create('a1', 'workflow');
+        mgr.create('a2', 'autonomous');
+        expect(mgr.list()).toHaveLength(2);
+    });
+    it('updates session fields', () => {
+        const s = mgr.create('a1', 'autonomous');
+        mgr.update(s.id, { conversationId: 'conv-1', activeRunId: 'run-1' });
+        const updated = mgr.get(s.id);
+        expect(updated.conversationId).toBe('conv-1');
+        expect(updated.activeRunId).toBe('run-1');
+    });
+    it('cancel aborts the controller and clears activeRunId', () => {
+        const s = mgr.create('a1', 'autonomous');
+        const ac = new AbortController();
+        mgr.update(s.id, { abortController: ac, activeRunId: 'run-1' });
+        mgr.cancel(s.id);
+        expect(ac.signal.aborted).toBe(true);
+        expect(mgr.get(s.id).activeRunId).toBeUndefined();
+    });
+    it('close removes the session', () => {
+        const s = mgr.create('a1', 'workflow');
+        expect(mgr.close(s.id)).toBe(true);
+        expect(mgr.get(s.id)).toBeUndefined();
+        expect(mgr.close(s.id)).toBe(false);
+    });
+    it('closeAll aborts all and clears', () => {
+        const ac1 = new AbortController();
+        const ac2 = new AbortController();
+        const s1 = mgr.create('a1', 'workflow');
+        const s2 = mgr.create('a2', 'autonomous');
+        mgr.update(s1.id, { abortController: ac1 });
+        mgr.update(s2.id, { abortController: ac2 });
+        mgr.closeAll();
+        expect(ac1.signal.aborted).toBe(true);
+        expect(ac2.signal.aborted).toBe(true);
+        expect(mgr.list()).toHaveLength(0);
+    });
+    it('handles concurrent sessions for different agents', () => {
+        const s1 = mgr.create('agent-a', 'workflow');
+        const s2 = mgr.create('agent-b', 'autonomous');
+        const s3 = mgr.create('agent-a', 'autonomous');
+        expect(mgr.list()).toHaveLength(3);
+        expect(mgr.get(s1.id).agentId).toBe('agent-a');
+        expect(mgr.get(s2.id).agentId).toBe('agent-b');
+        expect(mgr.get(s3.id).agentId).toBe('agent-a');
+    });
+});

package/dist/agent.d.ts

@@ -0,0 +1,85 @@
+/**
+ * AlmytyAcpAgent: handles all ACP JSON-RPC methods.
+ *
+ * Bridges the ACP protocol to the almyty backend REST API. Manages
+ * session lifecycle, dispatches prompts to the correct execution engine,
+ * and streams SessionUpdate notifications back to the client.
+ */
+import type { AlmytyProxy } from './proxy.js';
+/** JSON-RPC 2.0 request. */
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+/** JSON-RPC 2.0 response. */
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** JSON-RPC 2.0 notification (no id). */
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: Record<string, unknown>;
+}
+type JsonRpcMessage = JsonRpcResponse | JsonRpcNotification;
+/** Callback for sending messages to the ACP client. */
+export type SendFn = (msg: JsonRpcMessage) => void;
+export declare class AlmytyAcpAgent {
+    private readonly proxy;
+    private readonly sessions;
+    private readonly agentId;
+    private send;
+    private agentInfo;
+    private authenticated;
+    constructor(proxy: AlmytyProxy, agentId: string, send: SendFn);
+    /**
+     * Update the send function (used if transport is re-initialized).
+     */
+    setSend(send: SendFn): void;
+    /**
+     * Handle an incoming JSON-RPC message from the ACP client.
+     */
+    handleMessage(msg: JsonRpcRequest): Promise<void>;
+    private handleInitialize;
+    private handleAuthenticate;
+    private handleSessionNew;
+    private handleSessionList;
+    private handleSessionLoad;
+    private handleSessionPrompt;
+    /**
+     * Handle a prompt for a workflow agent: POST /agents/:id/stream.
+     * Streams events via SSE and maps them to ACP session updates.
+     */
+    private handleWorkflowPrompt;
+    /**
+     * Handle a prompt for an autonomous agent: start or continue a run.
+     * If the session has no active conversation, starts a new run.
+     * If the agent is waiting for input, sends input to the existing run.
+     */
+    private handleAutonomousPrompt;
+    /**
+     * Poll a run until it reaches a terminal state or the signal is aborted.
+     */
+    private pollRunToCompletion;
+    private handleSessionCancel;
+    private handleSessionSetMode;
+    private handleSessionClose;
+    private sendResult;
+    private sendError;
+    private sendNotification;
+    private sendSessionUpdate;
+    /**
+     * Clean up all sessions. Called during shutdown.
+     */
+    shutdown(): void;
+}
+export {};