@almyty/acp-server 1.0.0

package/dist/events.js

@@ -0,0 +1,247 @@
+/**
+ * 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.
+ */
+// ── Mapping functions ────────────────────────────────────────────
+/**
+ * Infer a tool call kind from the node type or tool name.
+ */
+function inferKind(nodeType, toolName) {
+    if (nodeType === 'llm_call' || nodeType === 'sub_agent')
+        return 'think';
+    if (nodeType === 'transform')
+        return 'edit';
+    if (nodeType === 'condition')
+        return 'other';
+    if (toolName) {
+        const lower = toolName.toLowerCase();
+        if (lower.includes('read') || lower.includes('get') || lower.includes('list') || lower.includes('fetch'))
+            return 'read';
+        if (lower.includes('create') || lower.includes('update') || lower.includes('write') || lower.includes('set'))
+            return 'edit';
+        if (lower.includes('delete') || lower.includes('remove'))
+            return 'delete';
+        if (lower.includes('search') || lower.includes('find') || lower.includes('query'))
+            return 'search';
+        if (lower.includes('execute') || lower.includes('run') || lower.includes('invoke'))
+            return 'execute';
+    }
+    return 'other';
+}
+/**
+ * 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 function mapStreamEvent(event) {
+    const updates = [];
+    const data = event.data;
+    switch (event.event) {
+        // ── Node lifecycle events (workflow agents) ──────────────────
+        case 'node.started': {
+            const nodeId = String(data.nodeId ?? data.id ?? '');
+            const nodeType = String(data.nodeType ?? data.type ?? '');
+            const label = String(data.label ?? data.name ?? nodeType);
+            updates.push({
+                type: 'tool_call',
+                toolCallId: nodeId,
+                title: label,
+                kind: inferKind(nodeType, String(data.toolName ?? '')),
+                status: 'running',
+                rawInput: data.input ? JSON.stringify(data.input) : undefined,
+            });
+            break;
+        }
+        case 'node.output': {
+            const nodeId = String(data.nodeId ?? data.id ?? '');
+            const output = data.output ?? data.result;
+            const outputStr = typeof output === 'string' ? output : JSON.stringify(output);
+            // If this is an LLM node, surface as agent message chunk
+            if (data.nodeType === 'llm_call' || data.type === 'llm_call') {
+                updates.push({
+                    type: 'agent_message_chunk',
+                    text: outputStr,
+                });
+            }
+            updates.push({
+                type: 'tool_call_update',
+                toolCallId: nodeId,
+                status: 'completed',
+                content: outputStr,
+            });
+            break;
+        }
+        case 'node.completed': {
+            const nodeId = String(data.nodeId ?? data.id ?? '');
+            const output = data.output ?? data.result;
+            updates.push({
+                type: 'tool_call_update',
+                toolCallId: nodeId,
+                status: 'completed',
+                content: output != null ? (typeof output === 'string' ? output : JSON.stringify(output)) : undefined,
+            });
+            break;
+        }
+        case 'node.error': {
+            const nodeId = String(data.nodeId ?? data.id ?? '');
+            updates.push({
+                type: 'tool_call_update',
+                toolCallId: nodeId,
+                status: 'error',
+                error: String(data.error ?? data.message ?? 'Unknown error'),
+            });
+            break;
+        }
+        // ── Text streaming events ────────────────────────────────────
+        case 'text':
+        case 'message':
+        case 'chunk':
+        case 'token': {
+            const text = String(data.text ?? data.content ?? data.chunk ?? data.token ?? '');
+            if (text) {
+                updates.push({
+                    type: 'agent_message_chunk',
+                    text,
+                });
+            }
+            break;
+        }
+        case 'thought':
+        case 'thinking': {
+            const text = String(data.text ?? data.content ?? '');
+            if (text) {
+                updates.push({
+                    type: 'agent_thought_chunk',
+                    text,
+                });
+            }
+            break;
+        }
+        // ── Tool call events (autonomous agents) ─────────────────────
+        case 'tool_call':
+        case 'tool.started': {
+            const toolCallId = String(data.toolCallId ?? data.id ?? data.callId ?? '');
+            const toolName = String(data.toolName ?? data.name ?? data.tool ?? '');
+            updates.push({
+                type: 'tool_call',
+                toolCallId,
+                title: toolName,
+                kind: inferKind(undefined, toolName),
+                status: 'running',
+                rawInput: data.arguments ? JSON.stringify(data.arguments) : (data.input ? JSON.stringify(data.input) : undefined),
+            });
+            break;
+        }
+        case 'tool_result':
+        case 'tool.completed': {
+            const toolCallId = String(data.toolCallId ?? data.id ?? data.callId ?? '');
+            const result = data.result ?? data.output;
+            updates.push({
+                type: 'tool_call_update',
+                toolCallId,
+                status: 'completed',
+                content: result != null ? (typeof result === 'string' ? result : JSON.stringify(result)) : undefined,
+            });
+            break;
+        }
+        case 'tool.error': {
+            const toolCallId = String(data.toolCallId ?? data.id ?? data.callId ?? '');
+            updates.push({
+                type: 'tool_call_update',
+                toolCallId,
+                status: 'error',
+                error: String(data.error ?? data.message ?? 'Tool execution failed'),
+            });
+            break;
+        }
+        // ── Execution lifecycle ──────────────────────────────────────
+        case 'execution.started':
+        case 'execution.completed':
+        case 'execution.error':
+        case 'run.completed':
+        case 'run.error':
+        case 'done':
+            // Terminal events — the caller handles these to finalize the
+            // PromptResponse. We optionally surface errors as message chunks.
+            if (data.error) {
+                updates.push({
+                    type: 'agent_message_chunk',
+                    text: `Error: ${String(data.error)}`,
+                });
+            }
+            if (data.output && event.event === 'execution.completed') {
+                const text = typeof data.output === 'string' ? data.output : JSON.stringify(data.output);
+                updates.push({
+                    type: 'agent_message_chunk',
+                    text,
+                });
+            }
+            break;
+        default:
+            // Unknown event types are silently ignored.
+            break;
+    }
+    return updates;
+}
+/**
+ * Build an ACP Plan from almyty pipeline nodes. Maps node types to
+ * priorities and initializes all entries as "todo".
+ */
+export function buildPlanFromPipeline(nodes) {
+    const entries = nodes
+        .filter((n) => n.type !== 'input' && n.type !== 'output')
+        .map((node) => ({
+        title: node.label || `${node.type} (${node.id})`,
+        priority: inferPriority(node.type),
+        status: 'todo',
+    }));
+    return { type: 'plan', entries };
+}
+/**
+ * Map node type to plan entry priority.
+ */
+function inferPriority(nodeType) {
+    switch (nodeType) {
+        case 'llm_call':
+        case 'tool_call':
+        case 'sub_agent':
+            return 'high';
+        case 'condition':
+        case 'loop':
+        case 'parallel':
+            return 'medium';
+        default:
+            return 'low';
+    }
+}
+/**
+ * Check if a StreamEvent indicates the execution has finished.
+ */
+export function isTerminalEvent(event) {
+    return [
+        'execution.completed',
+        'execution.error',
+        'run.completed',
+        'run.error',
+        'done',
+    ].includes(event.event);
+}
+/**
+ * Extract final output text from a terminal StreamEvent.
+ */
+export function extractFinalOutput(event) {
+    const data = event.data;
+    if (data.output) {
+        return typeof data.output === 'string' ? data.output : JSON.stringify(data.output);
+    }
+    if (data.result) {
+        return typeof data.result === 'string' ? data.result : JSON.stringify(data.result);
+    }
+    if (data.error) {
+        return `Error: ${String(data.error)}`;
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * @almyty/acp-server — ACP agent server for almyty.
+ *
+ * Exposes any almyty agent via the Agent Client Protocol (ACP) over
+ * ndjson stdio. Compatible with Zed, JetBrains AI, and other ACP clients.
+ *
+ * Usage:
+ *   npx @almyty/acp-server <agent>          Start ACP server for a specific agent
+ *   npx @almyty/acp-server my-agent         Agent by name or ID
+ *
+ * Environment:
+ *   ALMYTY_URL     Base URL of the almyty backend (default: https://api.almyty.com)
+ *   ALMYTY_TOKEN   API key (auto-read from ~/.almyty/credentials.json)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * @almyty/acp-server — ACP agent server for almyty.
+ *
+ * Exposes any almyty agent via the Agent Client Protocol (ACP) over
+ * ndjson stdio. Compatible with Zed, JetBrains AI, and other ACP clients.
+ *
+ * Usage:
+ *   npx @almyty/acp-server <agent>          Start ACP server for a specific agent
+ *   npx @almyty/acp-server my-agent         Agent by name or ID
+ *
+ * Environment:
+ *   ALMYTY_URL     Base URL of the almyty backend (default: https://api.almyty.com)
+ *   ALMYTY_TOKEN   API key (auto-read from ~/.almyty/credentials.json)
+ */
+import * as readline from 'node:readline';
+import { resolveCredentials } from './auth.js';
+import { AlmytyProxy } from './proxy.js';
+import { AlmytyAcpAgent } from './agent.js';
+// ── Argument parsing ─────────────────────────────────────────────
+const args = process.argv.slice(2);
+const HELP_FLAGS = ['--help', '-h'];
+if (args.some((a) => HELP_FLAGS.includes(a)) || args.length === 0) {
+    const text = `
+@almyty/acp-server — Expose any almyty agent via the Agent Client Protocol
+
+Connects an almyty agent to ACP-compatible clients (Zed, JetBrains AI,
+Toad, and others) over ndjson stdio. The server proxies all requests to
+the almyty backend REST API.
+
+Usage:
+  npx @almyty/acp-server <agent>
+  npx @almyty/acp-server my-agent
+  npx @almyty/acp-server 550e8400-e29b-41d4-a716-446655440000
+
+Authentication:
+  npx @almyty/auth login              Browser-based login (one-time setup)
+
+Environment:
+  ALMYTY_URL         Base URL (default: https://api.almyty.com)
+  ALMYTY_TOKEN       API key (auto-read from ~/.almyty/credentials.json)
+
+Client configuration:
+
+  Zed (settings.json):
+    {
+      "agent": {
+        "profiles": {
+          "almyty": {
+            "provider": "agent-client-protocol",
+            "binary": {
+              "name": "npx",
+              "args": ["-y", "@almyty/acp-server", "my-agent"]
+            }
+          }
+        }
+      }
+    }
+
+  JetBrains (AI Assistant settings):
+    Binary path:  npx
+    Arguments:    -y @almyty/acp-server my-agent
+
+  Custom / stdio:
+    echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}' | npx @almyty/acp-server my-agent
+`;
+    // Write help to stdout (not stderr) so piping works
+    process.stdout.write(text.trimStart());
+    process.exit(args.length === 0 ? 1 : 0);
+}
+// Filter out any flags, take the first positional arg as the agent identifier
+const agentArg = args.find((a) => !a.startsWith('-'));
+if (!agentArg) {
+    process.stderr.write('Error: Agent name or ID is required.\nUsage: npx @almyty/acp-server <agent>\n');
+    process.exit(1);
+}
+// ── Main ─────────────────────────────────────────────────────────
+async function main() {
+    // Resolve credentials
+    const creds = resolveCredentials();
+    if (!creds) {
+        process.stderr.write('Error: No authentication token found.\n' +
+            'Set ALMYTY_TOKEN environment variable or run: npx @almyty/auth login\n');
+        process.exit(1);
+    }
+    const proxy = new AlmytyProxy(creds.url, creds.token);
+    // Resolve agent: try as ID first, then search by name/slug
+    let agentId = agentArg;
+    try {
+        const agent = await proxy.getAgent(agentId);
+        agentId = agent.id;
+        process.stderr.write(`[acp] Agent resolved: ${agent.name} (${agent.id}, mode: ${agent.mode})\n`);
+    }
+    catch {
+        // If direct lookup fails, try listing agents and matching by name/slug
+        try {
+            const agents = await proxy.listAgents();
+            const match = agents.find((a) => a.name === agentArg ||
+                a.slug === agentArg ||
+                a.name.toLowerCase() === agentArg.toLowerCase() ||
+                a.slug?.toLowerCase() === agentArg.toLowerCase());
+            if (match) {
+                agentId = match.id;
+                process.stderr.write(`[acp] Agent resolved by name: ${match.name} (${match.id}, mode: ${match.mode})\n`);
+            }
+            else {
+                process.stderr.write(`Error: Agent "${agentArg}" not found.\n` +
+                    `Available agents: ${agents.map((a) => a.name).join(', ') || '(none)'}\n`);
+                process.exit(1);
+            }
+        }
+        catch (listErr) {
+            process.stderr.write(`Error: Could not resolve agent "${agentArg}": ${listErr}\n`);
+            process.exit(1);
+        }
+    }
+    // Create the send function: write ndjson to stdout
+    const send = (msg) => {
+        try {
+            const line = JSON.stringify(msg);
+            process.stdout.write(line + '\n');
+        }
+        catch (err) {
+            process.stderr.write(`[acp] Failed to serialize message: ${err}\n`);
+        }
+    };
+    // Create the ACP agent handler
+    const agent = new AlmytyAcpAgent(proxy, agentId, send);
+    // Set up ndjson readline on stdin
+    const rl = readline.createInterface({
+        input: process.stdin,
+        terminal: false,
+    });
+    process.stderr.write(`[acp] Server ready. Listening for JSON-RPC messages on stdin.\n`);
+    rl.on('line', async (line) => {
+        // Skip empty lines
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        // Parse JSON-RPC message
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            // Malformed JSON — send parse error if it looks like it had an id
+            send({
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: -32700, message: 'Parse error: invalid JSON' },
+            });
+            return;
+        }
+        // Validate basic JSON-RPC structure
+        if (!msg.jsonrpc || msg.jsonrpc !== '2.0' || !msg.method) {
+            if (msg.id !== undefined) {
+                send({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    error: { code: -32600, message: 'Invalid JSON-RPC 2.0 request' },
+                });
+            }
+            return;
+        }
+        // Dispatch to agent handler
+        try {
+            await agent.handleMessage(msg);
+        }
+        catch (err) {
+            process.stderr.write(`[acp] Unhandled error in message handler: ${err}\n`);
+            if (msg.id !== undefined && msg.id !== null) {
+                send({
+                    jsonrpc: '2.0',
+                    id: msg.id,
+                    error: { code: -32603, message: 'Internal error' },
+                });
+            }
+        }
+    });
+    // Handle stdin close (client disconnected)
+    rl.on('close', () => {
+        process.stderr.write('[acp] Client disconnected. Shutting down.\n');
+        agent.shutdown();
+        process.exit(0);
+    });
+    // Handle process signals
+    const shutdown = () => {
+        process.stderr.write('[acp] Shutting down.\n');
+        agent.shutdown();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    // Handle uncaught errors — never crash the stdio process
+    process.on('uncaughtException', (err) => {
+        process.stderr.write(`[acp] Uncaught exception: ${err}\n`);
+    });
+    process.on('unhandledRejection', (err) => {
+        process.stderr.write(`[acp] Unhandled rejection: ${err}\n`);
+    });
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${err instanceof Error ? err.message : err}\n`);
+    process.exit(1);
+});

package/dist/proxy.d.ts

@@ -0,0 +1,78 @@
+/**
+ * HTTP proxy client to the almyty backend REST API.
+ *
+ * Provides typed methods for agent discovery, invocation, streaming,
+ * and autonomous run management. All stdout is reserved for the ACP
+ * protocol; diagnostics go to stderr.
+ */
+/** Minimal agent shape returned by the backend. */
+export interface AgentInfo {
+    id: string;
+    name: string;
+    slug?: string;
+    description?: string;
+    mode: 'workflow' | 'autonomous';
+    status?: string;
+    pipeline?: {
+        nodes?: PipelineNode[];
+    };
+}
+export interface PipelineNode {
+    id: string;
+    type: string;
+    label?: string;
+    config?: Record<string, unknown>;
+}
+/** Autonomous run state from the backend. */
+export interface AgentRun {
+    id: string;
+    agentId: string;
+    status: 'pending' | 'running' | 'waiting_input' | 'completed' | 'failed' | 'cancelled';
+    conversationId?: string;
+    output?: unknown;
+    error?: string;
+}
+/** A single SSE event emitted by the streaming endpoints. */
+export interface StreamEvent {
+    event: string;
+    data: Record<string, unknown>;
+}
+export declare class AlmytyProxy {
+    private readonly baseUrl;
+    private readonly token;
+    constructor(baseUrl: string, token: string);
+    listAgents(): Promise<AgentInfo[]>;
+    getAgent(id: string): Promise<AgentInfo>;
+    invokeAgent(id: string, input: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Stream a workflow agent execution via SSE. Yields StreamEvent objects
+     * as they arrive. The caller is responsible for consuming the async
+     * iterator; aborting the signal will terminate the stream.
+     */
+    streamAgent(id: string, input: Record<string, unknown>, signal?: AbortSignal): AsyncGenerator<StreamEvent>;
+    startRun(id: string, input: Record<string, unknown>): Promise<AgentRun>;
+    getRun(agentId: string, runId: string): Promise<AgentRun>;
+    sendRunInput(agentId: string, runId: string, input: Record<string, unknown>): Promise<AgentRun>;
+    cancelRun(agentId: string, runId: string): Promise<void>;
+    /**
+     * Stream an autonomous run via SSE. Similar to streamAgent but uses the
+     * run-specific SSE endpoint.
+     */
+    streamRun(agentId: string, runId: string, signal?: AbortSignal): AsyncGenerator<StreamEvent>;
+    private headers;
+    private get;
+    private post;
+    /**
+     * Consume an SSE stream from a POST endpoint. Uses eventsource-parser
+     * to handle the text/event-stream format.
+     */
+    private ssePost;
+    /**
+     * Consume an SSE stream from a GET endpoint.
+     */
+    private sseGet;
+    /**
+     * Parse an SSE response body into StreamEvent objects.
+     */
+    private consumeSse;
+}