@almyty/acp-server 1.0.0

package/dist/agent.js

@@ -0,0 +1,527 @@
+/**
+ * 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 { SessionManager } from './session.js';
+import { mapStreamEvent, buildPlanFromPipeline, isTerminalEvent, extractFinalOutput, } from './events.js';
+// ── Standard JSON-RPC error codes ────────────────────────────────
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+// ── Agent implementation ─────────────────────────────────────────
+export class AlmytyAcpAgent {
+    proxy;
+    sessions;
+    agentId;
+    send;
+    agentInfo = null;
+    authenticated = false;
+    constructor(proxy, agentId, send) {
+        this.proxy = proxy;
+        this.sessions = new SessionManager();
+        this.agentId = agentId;
+        this.send = send;
+    }
+    /**
+     * Update the send function (used if transport is re-initialized).
+     */
+    setSend(send) {
+        this.send = send;
+    }
+    /**
+     * Handle an incoming JSON-RPC message from the ACP client.
+     */
+    async handleMessage(msg) {
+        const { id, method, params } = msg;
+        // Notifications have no id — they don't expect a response
+        const isNotification = id === undefined || id === null;
+        try {
+            let result;
+            switch (method) {
+                case 'initialize':
+                    result = await this.handleInitialize(params ?? {});
+                    break;
+                case 'authenticate':
+                    result = await this.handleAuthenticate(params ?? {});
+                    break;
+                case 'session/new':
+                    result = await this.handleSessionNew(params ?? {});
+                    break;
+                case 'session/list':
+                    result = await this.handleSessionList();
+                    break;
+                case 'session/load':
+                    result = await this.handleSessionLoad(params ?? {});
+                    break;
+                case 'session/prompt':
+                    result = await this.handleSessionPrompt(params ?? {});
+                    break;
+                case 'session/cancel':
+                    this.handleSessionCancel(params ?? {});
+                    if (isNotification)
+                        return; // No response for notifications
+                    result = {};
+                    break;
+                case 'session/set_mode':
+                    result = this.handleSessionSetMode(params ?? {});
+                    break;
+                case 'session/set_config_option':
+                    result = {};
+                    break;
+                case 'session/close':
+                    result = this.handleSessionClose(params ?? {});
+                    break;
+                case 'logout':
+                    this.authenticated = false;
+                    result = {};
+                    break;
+                // Document sync notifications — acknowledge silently
+                case 'document/didOpen':
+                case 'document/didChange':
+                case 'document/didClose':
+                case 'document/didSave':
+                case 'document/didFocus':
+                    return; // Notifications, no response
+                default:
+                    if (isNotification)
+                        return;
+                    this.sendError(id, METHOD_NOT_FOUND, `Unknown method: ${method}`);
+                    return;
+            }
+            if (!isNotification) {
+                this.sendResult(id, result);
+            }
+        }
+        catch (err) {
+            if (!isNotification) {
+                if (err instanceof JsonRpcError) {
+                    this.sendError(id, err.code, err.message, err.data);
+                }
+                else {
+                    const message = err instanceof Error ? err.message : String(err);
+                    this.sendError(id, INTERNAL_ERROR, message);
+                }
+            }
+            else {
+                process.stderr.write(`[acp] Error handling notification ${method}: ${err}\n`);
+            }
+        }
+    }
+    // ── Method handlers ────────────────────────────────────────────
+    async handleInitialize(_params) {
+        // Pre-fetch agent info for capabilities
+        try {
+            this.agentInfo = await this.proxy.getAgent(this.agentId);
+        }
+        catch (err) {
+            process.stderr.write(`[acp] Warning: could not fetch agent info: ${err}\n`);
+        }
+        const hasPipeline = this.agentInfo?.mode === 'workflow' && this.agentInfo.pipeline?.nodes?.length;
+        return {
+            protocolVersion: 1,
+            agentCapabilities: {
+                tools: true,
+                streaming: true,
+                sessions: true,
+                sessionList: true,
+                plan: !!hasPipeline,
+                modes: false,
+            },
+            authMethods: [
+                {
+                    id: 'almyty_token',
+                    type: 'env_var',
+                    label: 'almyty API token',
+                    envVars: ['ALMYTY_TOKEN'],
+                },
+            ],
+            agentInfo: this.agentInfo
+                ? { name: this.agentInfo.name, description: this.agentInfo.description }
+                : { name: 'almyty agent' },
+        };
+    }
+    async handleAuthenticate(params) {
+        const methodId = params.methodId;
+        if (methodId === 'almyty_token') {
+            // The token is already configured via env var or credentials file.
+            // Validate by making a lightweight API call.
+            try {
+                await this.proxy.getAgent(this.agentId);
+                this.authenticated = true;
+                return { authenticated: true };
+            }
+            catch {
+                return { authenticated: false };
+            }
+        }
+        // Unknown auth method — the token was pre-configured at startup,
+        // so we consider it authenticated if we can reach the backend.
+        try {
+            await this.proxy.getAgent(this.agentId);
+            this.authenticated = true;
+            return { authenticated: true };
+        }
+        catch {
+            return { authenticated: false };
+        }
+    }
+    async handleSessionNew(params) {
+        const mode = this.agentInfo?.mode ?? 'workflow';
+        const session = this.sessions.create(this.agentId, mode);
+        process.stderr.write(`[acp] Session created: ${session.id} (agent: ${this.agentId}, mode: ${mode})\n`);
+        // For workflow agents with a pipeline, send the plan
+        if (mode === 'workflow' && this.agentInfo?.pipeline?.nodes?.length) {
+            const plan = buildPlanFromPipeline(this.agentInfo.pipeline.nodes);
+            this.sendNotification('session/update', {
+                sessionId: session.id,
+                update: plan,
+            });
+        }
+        return { sessionId: session.id };
+    }
+    async handleSessionList() {
+        const sessions = this.sessions.list().map((s) => ({
+            id: s.id,
+            agentId: s.agentId,
+            mode: s.mode,
+        }));
+        return { sessions };
+    }
+    async handleSessionLoad(params) {
+        const sessionId = params.sessionId;
+        if (!sessionId) {
+            throw new JsonRpcError(INVALID_PARAMS, 'sessionId is required');
+        }
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new JsonRpcError(INVALID_PARAMS, `Session not found: ${sessionId}`);
+        }
+        return { sessionId: session.id };
+    }
+    async handleSessionPrompt(params) {
+        const sessionId = params.sessionId;
+        if (!sessionId) {
+            throw new JsonRpcError(INVALID_PARAMS, 'sessionId is required');
+        }
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new JsonRpcError(INVALID_PARAMS, `Session not found: ${sessionId}`);
+        }
+        // Extract text from ContentBlock array
+        const content = params.content;
+        const inputText = extractTextFromContent(content);
+        if (!inputText) {
+            throw new JsonRpcError(INVALID_PARAMS, 'No text content in prompt');
+        }
+        // Set up abort controller for this prompt turn
+        const abortController = new AbortController();
+        this.sessions.update(sessionId, { abortController });
+        try {
+            if (session.mode === 'autonomous') {
+                return await this.handleAutonomousPrompt(session, inputText, abortController.signal);
+            }
+            else {
+                return await this.handleWorkflowPrompt(session, inputText, abortController.signal);
+            }
+        }
+        finally {
+            this.sessions.update(sessionId, { abortController: undefined, activeRunId: undefined });
+        }
+    }
+    /**
+     * Handle a prompt for a workflow agent: POST /agents/:id/stream.
+     * Streams events via SSE and maps them to ACP session updates.
+     */
+    async handleWorkflowPrompt(session, input, signal) {
+        const collectedText = [];
+        try {
+            for await (const event of this.proxy.streamAgent(session.agentId, { input }, signal)) {
+                if (signal.aborted) {
+                    return { stopReason: 'cancelled' };
+                }
+                const updates = mapStreamEvent(event);
+                for (const update of updates) {
+                    this.sendSessionUpdate(session.id, update);
+                    if (update.type === 'agent_message_chunk') {
+                        collectedText.push(update.text);
+                    }
+                }
+                if (isTerminalEvent(event)) {
+                    const finalOutput = extractFinalOutput(event);
+                    if (finalOutput && !collectedText.includes(finalOutput)) {
+                        collectedText.push(finalOutput);
+                    }
+                    if (event.event === 'execution.error' || event.event === 'run.error') {
+                        return {
+                            stopReason: 'end_turn',
+                            content: [{ type: 'text', text: collectedText.join('') || 'Execution failed.' }],
+                        };
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (signal.aborted) {
+                return { stopReason: 'cancelled' };
+            }
+            // If streaming fails, fall back to synchronous invoke
+            process.stderr.write(`[acp] Streaming failed, falling back to invoke: ${err}\n`);
+            try {
+                const result = await this.proxy.invokeAgent(session.agentId, { input });
+                const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+                this.sendSessionUpdate(session.id, {
+                    type: 'agent_message_chunk',
+                    text,
+                });
+                return {
+                    stopReason: 'end_turn',
+                    content: [{ type: 'text', text }],
+                };
+            }
+            catch (invokeErr) {
+                const errMsg = invokeErr instanceof Error ? invokeErr.message : String(invokeErr);
+                return {
+                    stopReason: 'end_turn',
+                    content: [{ type: 'text', text: `Error: ${errMsg}` }],
+                };
+            }
+        }
+        return {
+            stopReason: 'end_turn',
+            content: collectedText.length > 0
+                ? [{ type: 'text', text: collectedText.join('') }]
+                : undefined,
+        };
+    }
+    /**
+     * 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.
+     */
+    async handleAutonomousPrompt(session, input, signal) {
+        const collectedText = [];
+        try {
+            let run;
+            if (session.activeRunId) {
+                // Continue an existing run that is waiting for input
+                run = await this.proxy.sendRunInput(session.agentId, session.activeRunId, { message: input });
+            }
+            else {
+                // Start a new run
+                run = await this.proxy.startRun(session.agentId, { message: input });
+                this.sessions.update(session.id, {
+                    activeRunId: run.id,
+                    conversationId: run.conversationId,
+                });
+            }
+            process.stderr.write(`[acp] Run started: ${run.id} (status: ${run.status})\n`);
+            // Stream events from the run
+            try {
+                for await (const event of this.proxy.streamRun(session.agentId, run.id, signal)) {
+                    if (signal.aborted) {
+                        // Try to cancel the run on the backend
+                        try {
+                            await this.proxy.cancelRun(session.agentId, run.id);
+                        }
+                        catch { /* best effort */ }
+                        return { stopReason: 'cancelled' };
+                    }
+                    const updates = mapStreamEvent(event);
+                    for (const update of updates) {
+                        this.sendSessionUpdate(session.id, update);
+                        if (update.type === 'agent_message_chunk') {
+                            collectedText.push(update.text);
+                        }
+                    }
+                    if (isTerminalEvent(event)) {
+                        const finalOutput = extractFinalOutput(event);
+                        if (finalOutput && !collectedText.includes(finalOutput)) {
+                            collectedText.push(finalOutput);
+                        }
+                        break;
+                    }
+                }
+            }
+            catch (streamErr) {
+                // If streaming fails, fall back to polling the run status
+                process.stderr.write(`[acp] Run streaming failed, polling: ${streamErr}\n`);
+                const finalRun = await this.pollRunToCompletion(session.agentId, run.id, signal);
+                if (finalRun.output) {
+                    const text = typeof finalRun.output === 'string'
+                        ? finalRun.output
+                        : JSON.stringify(finalRun.output, null, 2);
+                    collectedText.push(text);
+                    this.sendSessionUpdate(session.id, {
+                        type: 'agent_message_chunk',
+                        text,
+                    });
+                }
+                if (finalRun.error) {
+                    collectedText.push(`Error: ${finalRun.error}`);
+                }
+                if (finalRun.status === 'waiting_input') {
+                    // Agent needs more input — keep the run active
+                    this.sessions.update(session.id, { activeRunId: finalRun.id });
+                    return {
+                        stopReason: 'end_turn',
+                        content: collectedText.length > 0
+                            ? [{ type: 'text', text: collectedText.join('') }]
+                            : [{ type: 'text', text: 'The agent is waiting for your input.' }],
+                    };
+                }
+            }
+            // Check final run status — if still running, poll until complete
+            let finalRun = await this.proxy.getRun(session.agentId, run.id).catch(() => run);
+            if (finalRun.status === 'running') {
+                process.stderr.write(`[acp] Run still running after stream ended, polling...\n`);
+                finalRun = await this.pollRunToCompletion(session.agentId, run.id, signal);
+                if (finalRun.output) {
+                    const text = typeof finalRun.output === 'string'
+                        ? finalRun.output
+                        : JSON.stringify(finalRun.output, null, 2);
+                    if (!collectedText.includes(text)) {
+                        collectedText.push(text);
+                        this.sendSessionUpdate(session.id, { type: 'agent_message_chunk', text });
+                    }
+                }
+                if (finalRun.error) {
+                    const errText = typeof finalRun.error === 'string'
+                        ? finalRun.error
+                        : JSON.stringify(finalRun.error);
+                    collectedText.push(`Error: ${errText}`);
+                }
+            }
+            if (finalRun.status === 'waiting_input') {
+                this.sessions.update(session.id, { activeRunId: finalRun.id });
+            }
+            else {
+                this.sessions.update(session.id, { activeRunId: undefined });
+            }
+            if (finalRun.status === 'cancelled') {
+                return { stopReason: 'cancelled' };
+            }
+            return {
+                stopReason: finalRun.status === 'failed' ? 'refusal' : 'end_turn',
+                content: collectedText.length > 0
+                    ? [{ type: 'text', text: collectedText.join('') }]
+                    : undefined,
+            };
+        }
+        catch (err) {
+            if (signal.aborted) {
+                return { stopReason: 'cancelled' };
+            }
+            const errMsg = err instanceof Error ? err.message : String(err);
+            return {
+                stopReason: 'end_turn',
+                content: [{ type: 'text', text: `Error: ${errMsg}` }],
+            };
+        }
+    }
+    /**
+     * Poll a run until it reaches a terminal state or the signal is aborted.
+     */
+    async pollRunToCompletion(agentId, runId, signal) {
+        const POLL_INTERVAL_MS = 1000;
+        const MAX_POLLS = 300; // 5 minutes max
+        for (let i = 0; i < MAX_POLLS; i++) {
+            if (signal.aborted) {
+                throw new Error('Cancelled');
+            }
+            const run = await this.proxy.getRun(agentId, runId);
+            if (run.status === 'completed' || run.status === 'failed' || run.status === 'cancelled' || run.status === 'waiting_input') {
+                return run;
+            }
+            await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        }
+        throw new Error('Run polling timed out');
+    }
+    handleSessionCancel(params) {
+        const sessionId = params.sessionId;
+        if (sessionId) {
+            process.stderr.write(`[acp] Cancelling session: ${sessionId}\n`);
+            this.sessions.cancel(sessionId);
+        }
+    }
+    handleSessionSetMode(params) {
+        const sessionId = params.sessionId;
+        const mode = params.mode;
+        if (sessionId && mode) {
+            this.sessions.update(sessionId, { userMode: mode });
+        }
+        // Acknowledge but no-op — almyty agents don't have client-side modes
+        return {};
+    }
+    handleSessionClose(params) {
+        const sessionId = params.sessionId;
+        if (!sessionId) {
+            throw new JsonRpcError(INVALID_PARAMS, 'sessionId is required');
+        }
+        const closed = this.sessions.close(sessionId);
+        process.stderr.write(`[acp] Session closed: ${sessionId} (found: ${closed})\n`);
+        return { closed };
+    }
+    // ── Message sending helpers ────────────────────────────────────
+    sendResult(id, result) {
+        this.send({
+            jsonrpc: '2.0',
+            id,
+            result,
+        });
+    }
+    sendError(id, code, message, data) {
+        this.send({
+            jsonrpc: '2.0',
+            id,
+            error: { code, message, data },
+        });
+    }
+    sendNotification(method, params) {
+        this.send({
+            jsonrpc: '2.0',
+            method,
+            params,
+        });
+    }
+    sendSessionUpdate(sessionId, update) {
+        this.sendNotification('session/update', {
+            sessionId,
+            update,
+        });
+    }
+    /**
+     * Clean up all sessions. Called during shutdown.
+     */
+    shutdown() {
+        this.sessions.closeAll();
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────
+/**
+ * Extract plain text from an array of ACP ContentBlocks.
+ */
+function extractTextFromContent(content) {
+    if (!content || !Array.isArray(content))
+        return '';
+    return content
+        .filter((block) => block.type === 'text' && block.text)
+        .map((block) => block.text)
+        .join('\n');
+}
+/**
+ * Typed JSON-RPC error for structured error responses.
+ */
+class JsonRpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Credential resolver for @almyty/acp-server.
+ *
+ * Reads the shared credential store written by `npx @almyty/auth login`.
+ * Lookup order: ALMYTY_TOKEN env var, then ~/.almyty/credentials.json.
+ */
+interface StoredCredentials {
+    url: string;
+    token: string;
+    email?: string;
+    frontendUrl?: string;
+}
+export declare function loadCredentials(): StoredCredentials | null;
+/**
+ * Resolve token: env var > stored credentials. Returns null when no
+ * credentials are available.
+ */
+export declare function resolveCredentials(): {
+    url: string;
+    token: string;
+} | null;
+export {};

package/dist/auth.js

@@ -0,0 +1,36 @@
+/**
+ * Credential resolver for @almyty/acp-server.
+ *
+ * Reads the shared credential store written by `npx @almyty/auth login`.
+ * Lookup order: ALMYTY_TOKEN env var, then ~/.almyty/credentials.json.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const CREDENTIALS_FILE = join(homedir(), '.almyty', 'credentials.json');
+export function loadCredentials() {
+    try {
+        if (!existsSync(CREDENTIALS_FILE))
+            return null;
+        return JSON.parse(readFileSync(CREDENTIALS_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve token: env var > stored credentials. Returns null when no
+ * credentials are available.
+ */
+export function resolveCredentials() {
+    const envToken = process.env.ALMYTY_TOKEN;
+    const envUrl = process.env.ALMYTY_URL || 'https://api.almyty.com';
+    if (envToken) {
+        return { url: envUrl, token: envToken };
+    }
+    const creds = loadCredentials();
+    if (creds?.token) {
+        return { url: creds.url, token: creds.token };
+    }
+    return null;
+}

package/dist/events.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Event mapper: converts almyty StreamEvent / run events into ACP
+ * SessionUpdate notifications.
+ *
+ * ACP SessionUpdate variants: agent_message_chunk, tool_call,
+ * tool_call_update, plan, agent_thought_chunk, user_message_chunk.
+ */
+import type { StreamEvent, PipelineNode } from './proxy.js';
+export interface SessionUpdate {
+    sessionId: string;
+    update: SessionUpdatePayload;
+}
+export type SessionUpdatePayload = AgentMessageChunk | AgentThoughtChunk | ToolCall | ToolCallUpdate | Plan;
+export interface AgentMessageChunk {
+    type: 'agent_message_chunk';
+    /** Incremental text content. */
+    text: string;
+    /** MIME type (default text/plain). */
+    mimeType?: string;
+}
+export interface AgentThoughtChunk {
+    type: 'agent_thought_chunk';
+    text: string;
+}
+export interface ToolCall {
+    type: 'tool_call';
+    /** Unique ID for this tool invocation (for pairing with updates). */
+    toolCallId: string;
+    /** Human-readable title (tool name or node label). */
+    title: string;
+    /** Tool call kind: read, edit, execute, fetch, think, other. */
+    kind: 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'think' | 'fetch' | 'switch_mode' | 'other';
+    /** Current status. */
+    status: 'running' | 'completed' | 'error' | 'cancelled';
+    /** Raw input parameters (stringified JSON). */
+    rawInput?: string;
+}
+export interface ToolCallUpdate {
+    type: 'tool_call_update';
+    /** Matches the toolCallId from the original ToolCall. */
+    toolCallId: string;
+    /** Updated status. */
+    status: 'running' | 'completed' | 'error' | 'cancelled';
+    /** Output content (on completion). */
+    content?: string;
+    /** Error message (on failure). */
+    error?: string;
+}
+export interface PlanEntry {
+    title: string;
+    priority: 'high' | 'medium' | 'low';
+    status: 'todo' | 'in_progress' | 'done' | 'error';
+}
+export interface Plan {
+    type: 'plan';
+    entries: PlanEntry[];
+}
+/**
+ * Convert a single almyty StreamEvent into zero or more ACP SessionUpdate
+ * payloads. Most events map 1:1, but some (like node.completed with output)
+ * may produce both a tool_call_update and an agent_message_chunk.
+ */
+export declare function mapStreamEvent(event: StreamEvent): SessionUpdatePayload[];
+/**
+ * Build an ACP Plan from almyty pipeline nodes. Maps node types to
+ * priorities and initializes all entries as "todo".
+ */
+export declare function buildPlanFromPipeline(nodes: PipelineNode[]): Plan;
+/**
+ * Check if a StreamEvent indicates the execution has finished.
+ */
+export declare function isTerminalEvent(event: StreamEvent): boolean;
+/**
+ * Extract final output text from a terminal StreamEvent.
+ */
+export declare function extractFinalOutput(event: StreamEvent): string | undefined;