qlogicagent 2.13.4 → 2.13.5

package/dist/transport/acp-server.js

@@ -0,0 +1,480 @@
+/**
+ * ACP ServerAgent-Client Protocol server layer for qlogicagent.
+ *
+ * This module implements qlogicagent as an ACP Server, allowing any ACP-compliant
+ * host (AionUI, Cursor, openclaw, etc.) to connect and interact with the agent.
+ *
+ * Protocol: ACP v1 over JSON-RPC 2.0 / stdio (line-delimited JSON).
+ *
+ * Responsibilities:
+ * - Accepts ACP standard methods: initialize, session/new, session/prompt, session/close
+ * - Accepts x/ extended methods: x/abort, x/dream, x/solo.*, x/product.*
+ * - Emits ACP session/update notifications (standard + x_ extended)
+ * - Translates host permission responses back to the agent
+ *
+ * Architecture: AcpServer wraps a Transport and delegates to an AcpRequestHandler
+ * interface. The StdioServer implements this interface by routing ACP methods to
+ * existing internal handlers.
+ */
+import { randomUUID } from "node:crypto";
+import { ACP_METHODS, ACP_EXTENDED_METHODS, ACP_SESSION_UPDATE_TYPES, isAcpJsonRpcRequest, isAcpJsonRpcNotification, } from "../protocol/wire/index.js";
+// ── Error Codes ──────────────────────────────────────────────────────────────
+export const ACP_ERROR_CODES = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+    /** Protocol version mismatch */
+    PROTOCOL_MISMATCH: -32001,
+    /** Session not found */
+    SESSION_NOT_FOUND: -32002,
+    /** Agent busy (turn in progress) */
+    AGENT_BUSY: -32003,
+};
+/**
+ * AcpServermanages the ACP protocol state machine.
+ *
+ * Lifecycle:
+ * 1. Host connects (stdio)
+ * 2. Host sends `initialize` -> agent responds with capabilities
+ * 3. Host sends `session/new` -> session created
+ * 4. Host sends `session/prompt` -> agent runs turn, emits session/update notifications
+ * 5. Host sends `session/close` -> session cleaned up
+ */
+export class AcpServer {
+    transport;
+    handler;
+    verbose;
+    /** Host capabilities declared during initialize */
+    hostCapabilities = {};
+    /** Whether the host supports x_ extended events */
+    hostSupportsExtendedEvents = false;
+    /** Whether the host supports x/ extended RPC methods */
+    hostSupportsExtendedMethods = false;
+    /** Sessions registered via session/new on this connection (multi-session per connection). */
+    registeredSessions = new Set();
+    /** Pending permission requests (agent -> host) waiting for response */
+    pendingPermissions = new Map();
+    /** Map from outbound JSON-RPC request id -> permissionId for response matching */
+    outboundRequestMap = new Map();
+    constructor(transport, handler, config) {
+        this.transport = transport;
+        this.handler = handler;
+        this.verbose = config?.verbose ?? false;
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────
+    /**
+     * Route an incoming raw message through ACP protocol handling.
+     * Called by the unified message dispatcher in StdioServer.
+     * Returns true if the message was handled, false otherwise.
+     */
+    dispatchMessage(raw) {
+        // Handle responses to our outbound requests (permission responses)
+        if (this.isJsonRpcResponse(raw)) {
+            this.handleResponse(raw);
+            return true;
+        }
+        if (isAcpJsonRpcRequest(raw)) {
+            const req = raw;
+            process.stderr.write(`[acp-server] -> recv id=${String(req.id)} method=${req.method}\n`);
+            this.handleRequest(req);
+            return true;
+        }
+        if (isAcpJsonRpcNotification(raw)) {
+            this.handleNotification(raw);
+            return true;
+        }
+        return false;
+    }
+    // ── Outbound: session/update notifications ───────────────────────────
+    /**
+     * Emit an ACP session/update notification to the host.
+     * Standard update types are always sent; x_ types only if the host declared
+     * the qlogicagent capability with events enabled.
+     */
+    emitSessionUpdate(sessionId, type, payload) {
+        // Filter x_ events if host doesn't support them
+        if (type.startsWith("x_") && !this.hostSupportsExtendedEvents) {
+            return;
+        }
+        const notification = {
+            jsonrpc: "2.0",
+            method: ACP_METHODS.SESSION_UPDATE,
+            params: {
+                sessionId,
+                update: {
+                    sessionUpdate: type,
+                    ...payload,
+                },
+            },
+        };
+        this.transport.send(notification);
+    }
+    /**
+     * Send a permission request to the host (agent -> host RPC).
+     * Returns a promise that resolves with the host's chosen option.
+     */
+    async requestPermission(params) {
+        const id = `perm-${randomUUID().slice(0, 8)}`;
+        const request = {
+            jsonrpc: "2.0",
+            method: ACP_METHODS.SESSION_REQUEST_PERMISSION,
+            params: params,
+            id,
+        };
+        return new Promise((resolve) => {
+            // Track id -> permissionId so handleResponse can resolve this
+            this.outboundRequestMap.set(id, params.permissionId);
+            this.pendingPermissions.set(params.permissionId, {
+                resolve: (optionId) => resolve({ optionId }),
+            });
+            this.transport.send(request);
+        });
+    }
+    /** Whether the host supports extended events */
+    get supportsExtendedEvents() {
+        return this.hostSupportsExtendedEvents;
+    }
+    /** Whether the host supports extended methods */
+    get supportsExtendedMethods() {
+        return this.hostSupportsExtendedMethods;
+    }
+    /** Whether a session id has been registered via session/new on this connection. */
+    hasSession(sessionId) {
+        return this.registeredSessions.has(sessionId);
+    }
+    // ── Inbound message dispatch ─────────────────────────────────────────
+    async handleRequest(msg) {
+        const { method, params, id } = msg;
+        const p = (params ?? {});
+        try {
+            if (method.startsWith("x/") && !this.hostSupportsExtendedMethods) {
+                this.sendError(id, ACP_ERROR_CODES.METHOD_NOT_FOUND, `Unknown method: ${method}`);
+                return;
+            }
+            switch (method) {
+                // ── Standard ACP methods ──────────────────────────────
+                case ACP_METHODS.INITIALIZE:
+                    await this.onInitialize(id, p);
+                    break;
+                case ACP_METHODS.SESSION_NEW:
+                    await this.onSessionNew(id, p);
+                    break;
+                case ACP_METHODS.SESSION_PROMPT:
+                    await this.onSessionPrompt(id, p);
+                    break;
+                case ACP_METHODS.SESSION_CLOSE:
+                    await this.onSessionClose(id, p);
+                    break;
+                case ACP_METHODS.SESSION_LOAD:
+                    await this.onSessionLoad(id, p);
+                    break;
+                case ACP_METHODS.SESSION_SET_CONFIG:
+                    await this.onSessionSetConfig(id, p);
+                    break;
+                case ACP_METHODS.SESSION_SET_MODEL:
+                    await this.onSessionSetModel(id, p);
+                    break;
+                case ACP_METHODS.SESSION_CANCEL:
+                    await this.onSessionCancel(id, p);
+                    break;
+                case ACP_METHODS.SESSION_SET_MODE:
+                    await this.onSessionSetMode(id, p);
+                    break;
+                // ── Extended methods (x/ prefix) ─────────────────────
+                case ACP_EXTENDED_METHODS.ABORT:
+                    await this.onAbort(id, p);
+                    break;
+                case ACP_EXTENDED_METHODS.DREAM:
+                    await this.onDream(id, p);
+                    break;
+                case ACP_EXTENDED_METHODS.AGENTS_LIST: {
+                    const result = await this.handler.handleAcpAgentsList();
+                    this.sendResult(id, result);
+                    break;
+                }
+                // ── Extended: Solo mode ───────────────────────────────
+                case ACP_EXTENDED_METHODS.SOLO_START: {
+                    const result = await this.handler.handleAcpSoloStart(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.SOLO_STATUS: {
+                    const result = await this.handler.handleAcpSoloStatus(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.SOLO_SELECT: {
+                    const result = await this.handler.handleAcpSoloSelect(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.SOLO_CANCEL: {
+                    const result = await this.handler.handleAcpSoloCancel(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.SOLO_SUBSCRIBE: {
+                    const result = await this.handler.handleAcpSoloSubscribe(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.SOLO_MESSAGE: {
+                    const result = await this.handler.handleAcpSoloMessage(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.SOLO_EVALUATE: {
+                    const result = await this.handler.handleAcpSoloEvaluate(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.WORKFLOW_CHAT: {
+                    const result = await this.handler.handleAcpWorkflowChat(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.WORKFLOW_MATCH_INTENT: {
+                    const result = await this.handler.handleAcpWorkflowMatchIntent(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.SOLO_SPEC_CHAT: {
+                    const result = await this.handler.handleAcpSoloSpecChat(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.SOLO_SPEC_JUDGE: {
+                    const result = await this.handler.handleAcpSoloSpecJudge(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                // ── Extended: Product mode ────────────────────────────────
+                case ACP_EXTENDED_METHODS.PRODUCT_CREATE: {
+                    const result = await this.handler.handleAcpProductCreate(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.PRODUCT_PLAN: {
+                    const result = await this.handler.handleAcpProductPlan(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.PRODUCT_CONFIRM: {
+                    const result = await this.handler.handleAcpProductConfirm(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.PRODUCT_MESSAGE: {
+                    const result = await this.handler.handleAcpProductMessage(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.PRODUCT_PAUSE: {
+                    const result = await this.handler.handleAcpProductPause(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.PRODUCT_RESUME: {
+                    const result = await this.handler.handleAcpProductResume(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.PRODUCT_CANCEL: {
+                    const result = await this.handler.handleAcpProductCancel(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.PRODUCT_ROLLBACK: {
+                    const result = await this.handler.handleAcpProductRollback(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.PRODUCT_STATUS: {
+                    const result = await this.handler.handleAcpProductStatus(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                case ACP_EXTENDED_METHODS.PRODUCT_SUBSCRIBE: {
+                    const result = await this.handler.handleAcpProductSubscribe(p);
+                    this.sendResult(id, result);
+                    break;
+                }
+                default:
+                    this.sendError(id, ACP_ERROR_CODES.METHOD_NOT_FOUND, `Unknown method: ${method}`);
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            this.sendError(id, ACP_ERROR_CODES.INTERNAL_ERROR, err.message, typeof code === "string" ? { code } : undefined);
+        }
+    }
+    handleNotification(msg) {
+        // Host -> agent notifications (no id, no response expected).
+        if (msg.method === ACP_METHODS.SESSION_CANCEL) {
+            void this.onCancel((msg.params ?? {}));
+            return;
+        }
+        this.log(`received notification: ${msg.method}`);
+    }
+    handleResponse(msg) {
+        // Responses to our outbound permission requests.
+        // Match the RPC id back to the permissionId via outboundRequestMap.
+        const permissionId = this.outboundRequestMap.get(msg.id);
+        if (permissionId) {
+            this.outboundRequestMap.delete(msg.id);
+            const pending = this.pendingPermissions.get(permissionId);
+            if (pending) {
+                this.pendingPermissions.delete(permissionId);
+                const result = msg.result;
+                pending.resolve(result?.optionId ?? "deny");
+            }
+        }
+        else {
+            this.log(`received response for id=${String(msg.id)} (no matching outbound request)`);
+        }
+    }
+    // ── Standard ACP method handlers ─────────────────────────────────────
+    async onInitialize(id, params) {
+        // Store host capabilities (standard field: clientCapabilities)
+        this.hostCapabilities = (params.clientCapabilities ?? {});
+        const qc = this.hostCapabilities.qlogicagent;
+        this.hostSupportsExtendedEvents = !!qc && (qc.events ?? true);
+        this.hostSupportsExtendedMethods = !!qc && (qc.methods ?? true);
+        const hostName = params.clientInfo?.name ?? "unknown";
+        const hostVersion = params.clientInfo?.version ?? "unknown";
+        this.log(`initialize: host=${hostName} v=${hostVersion}, proto=${String(params.protocolVersion)}, ` +
+            `qlogicagentExt=${!!qc}, events=${this.hostSupportsExtendedEvents}, methods=${this.hostSupportsExtendedMethods}`);
+        const result = await this.handler.handleAcpInitialize(params);
+        this.sendResult(id, result);
+    }
+    async onSessionNew(id, params) {
+        const result = await this.handler.handleAcpSessionNew(params);
+        this.registeredSessions.add(result.sessionId);
+        this.sendResult(id, result);
+        // Advertise the available slash commands (single source: handler.buildAvailableCommands).
+        this.emitSessionUpdate(result.sessionId, ACP_SESSION_UPDATE_TYPES.AVAILABLE_COMMANDS_UPDATE, {
+            availableCommands: this.handler.buildAvailableCommands(),
+        });
+    }
+    async onSessionLoad(id, params) {
+        // Standard ACP session/load: register the session, then replay persisted history to the
+        // host as display-only chunks. The handler returns data only (no server ref); the server
+        // owns the single send path. Backend context is NOT rebuilt here - turn-handler hydrates
+        // from disk via withResumedHistory on the next prompt.
+        this.registeredSessions.add(params.sessionId);
+        const { replay } = await this.handler.handleAcpSessionLoad(params);
+        for (const m of replay) {
+            this.emitSessionUpdate(params.sessionId, m.type, { content: { type: "text", text: m.content } });
+        }
+        this.sendResult(id, {});
+    }
+    async onSessionPrompt(id, params) {
+        if (!this.registeredSessions.has(params.sessionId)) {
+            this.sendError(id, ACP_ERROR_CODES.SESSION_NOT_FOUND, `No active session with id: ${params.sessionId}`);
+            return;
+        }
+        // Slash-command intercept (single send path): if the prompt is a command, the handler
+        // returns its reply as data; the server emits one agent_message_chunk and acks end_turn —
+        // no real turn runs. handleAcpSessionPrompt stays a pure standard response otherwise.
+        const cmd = await this.handler.tryDispatchCommand(params);
+        if (cmd.handled) {
+            if (cmd.reply) {
+                this.emitSessionUpdate(params.sessionId, ACP_SESSION_UPDATE_TYPES.AGENT_MESSAGE_CHUNK, { content: { type: "text", text: cmd.reply } });
+            }
+            this.sendResult(id, { stopReason: "end_turn" });
+            return;
+        }
+        // ACP v1: session/prompt response = turn result (returned when turn completes)
+        // During the turn, session/update notifications stream to the host.
+        const result = await this.handler.handleAcpSessionPrompt(params);
+        this.sendResult(id, result);
+    }
+    async onSessionClose(id, params) {
+        await this.handler.handleAcpSessionClose(params);
+        this.registeredSessions.delete(params.sessionId);
+        this.sendResult(id, {});
+    }
+    async onSessionSetConfig(id, params) {
+        if (!this.registeredSessions.has(params.sessionId)) {
+            this.sendError(id, ACP_ERROR_CODES.SESSION_NOT_FOUND, `No active session with id: ${params.sessionId}`);
+            return;
+        }
+        await this.handler.handleAcpSessionSetConfig(params);
+        this.sendResult(id, {});
+    }
+    async onSessionSetModel(id, p) {
+        const sessionId = p.sessionId ?? "";
+        if (!this.registeredSessions.has(sessionId)) {
+            this.sendError(id, ACP_ERROR_CODES.SESSION_NOT_FOUND, `No active session with id: ${sessionId}`);
+            return;
+        }
+        await this.handler.handleAcpSessionSetModel(sessionId, (p.modelId ?? p.model) ?? "");
+        this.sendResult(id, {});
+    }
+    async onSessionSetMode(id, p) {
+        // Standard ACP session/set_mode: the handler validates + records the mode on acpSessionMeta
+        // (single track — the next prompt's syncTurnPermissionConfig applies it), then the server
+        // emits current_mode_update and acks. An unknown mode throws and surfaces as a JSON-RPC error.
+        const sessionId = p.sessionId ?? "";
+        if (!this.registeredSessions.has(sessionId)) {
+            this.sendError(id, ACP_ERROR_CODES.SESSION_NOT_FOUND, `No active session with id: ${sessionId}`);
+            return;
+        }
+        const modeId = (p.modeId ?? p.mode) ?? "";
+        const applied = await this.handler.handleAcpSessionSetMode(sessionId, modeId);
+        this.emitSessionUpdate(sessionId, ACP_SESSION_UPDATE_TYPES.CURRENT_MODE_UPDATE, { currentModeId: applied });
+        this.sendResult(id, {});
+    }
+    // ── Extended method handlers ─────────────────────────────────────────
+    async onAbort(id, params) {
+        await this.handler.handleAcpAbort(params);
+        this.sendResult(id, { aborted: true });
+    }
+    async onSessionCancel(id, params) {
+        if (!this.registeredSessions.has(params.sessionId)) {
+            this.sendError(id, ACP_ERROR_CODES.SESSION_NOT_FOUND, `No active session with id: ${params.sessionId}`);
+            return;
+        }
+        await this.onCancel(params);
+        this.sendResult(id, {});
+    }
+    async onCancel(params) {
+        await this.handler.handleAcpAbort({ sessionId: params.sessionId, turnId: params.turnId });
+    }
+    async onDream(id, params) {
+        const result = await this.handler.handleAcpDream(params);
+        this.sendResult(id, result);
+    }
+    // ── Wire format helpers ──────────────────────────────────────────────
+    sendResult(id, result) {
+        process.stderr.write(`[acp-server] -> send id=${String(id)} result\n`);
+        const response = {
+            jsonrpc: "2.0",
+            id,
+            result,
+        };
+        this.transport.send(response);
+    }
+    sendError(id, code, message, data) {
+        process.stderr.write(`[acp-server] -> send id=${String(id)} error=${message}\n`);
+        const response = {
+            jsonrpc: "2.0",
+            id,
+            error: { code, message, ...(data !== undefined ? { data } : {}) },
+        };
+        this.transport.send(response);
+    }
+    isJsonRpcResponse(msg) {
+        if (!msg || typeof msg !== "object")
+            return false;
+        const m = msg;
+        return m.jsonrpc === "2.0" && "id" in m && ("result" in m || "error" in m) && !("method" in m);
+    }
+    log(message) {
+        if (this.verbose) {
+            process.stderr.write(`[acp-server] ${message}\n`);
+        }
+    }
+}

package/dist/transport/acp-server.test.d.ts

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