qlogicagent 2.13.4 → 2.13.5

package/dist/transport/acp-event-emitter.js

@@ -0,0 +1,142 @@
+/**
+ * ACP Event Emittertranslates internal qlogicagent notifications to ACP
+ * session/update notifications.
+ *
+ * Maps the 47+ internal notification methods (turn.delta, turn.tool_call, etc.)
+ * to 9 standard + 19 extended ACP sessionUpdate types.
+ *
+ * Usage: Called by the StdioServer event loop. Instead of (or in addition to)
+ * emitting raw notifications, events are translated and emitted through the
+ * AcpServer.emitSessionUpdate() method.
+ */
+import { ACP_SESSION_UPDATE_TYPES, ACP_EXTENDED_SESSION_UPDATE_TYPES, } from "../protocol/wire/index.js";
+// ── Event Translator ─────────────────────────────────────────────────────────
+/**
+ * Translates and emits a qlogicagent internal notification as an ACP session/update.
+ *
+ * @param server The AcpServer instance to emit through
+ * @param sessionId Active ACP session ID
+ * @param method Internal notification method name
+ * @param params Internal notification payload
+ */
+export function emitAcpUpdate(server, sessionId, method, params) {
+    const mapped = mapToAcpUpdate(method, params);
+    if (!mapped)
+        return false; // ACP does not model this event (lifecycle/global/internal)
+    server.emitSessionUpdate(sessionId, mapped.type, mapped.payload);
+    return true;
+}
+function mapToAcpUpdate(method, params) {
+    switch (method) {
+        // ACP has no turn.start; carry turn-start context (projectId/model/provider) as
+        // x_session_info so the host can synthesize its turn.start (Stage 4 fidelity).
+        case "turn.start":
+            return {
+                type: ACP_EXTENDED_SESSION_UPDATE_TYPES.X_SESSION_INFO,
+                payload: {
+                    sessionId: params.sessionId,
+                    projectId: params.projectId,
+                    model: params.model,
+                    provider: params.provider,
+                },
+            };
+        case "session.info":
+            return {
+                type: ACP_EXTENDED_SESSION_UPDATE_TYPES.X_SESSION_INFO,
+                payload: {
+                    sessionId: params.sessionId,
+                    projectId: params.projectId,
+                    provider: params.provider,
+                    model: params.model,
+                    metadata: { cwd: params.cwd, turnCount: params.turnCount },
+                },
+            };
+        case "turn.delta":
+            return {
+                type: ACP_SESSION_UPDATE_TYPES.AGENT_MESSAGE_CHUNK,
+                payload: { content: { type: "text", text: params.text } },
+            };
+        case "turn.reasoning_delta":
+            return {
+                type: ACP_SESSION_UPDATE_TYPES.AGENT_THOUGHT_CHUNK,
+                payload: { content: { type: "text", text: params.delta } },
+            };
+        case "turn.tool_call":
+            return {
+                type: ACP_SESSION_UPDATE_TYPES.TOOL_CALL,
+                payload: {
+                    toolCallId: params.callId,
+                    toolName: params.name,
+                    status: "in_progress",
+                    title: params.name,
+                    kind: "execute",
+                    rawInput: parseRawInput(params.arguments),
+                    // Full-fidelity fields for the openclaw gateway (lossless round-trip).
+                    arguments: params.arguments,
+                    inputSummary: params.inputSummary,
+                },
+            };
+        case "turn.tool_result":
+            return {
+                type: ACP_SESSION_UPDATE_TYPES.TOOL_CALL_UPDATE,
+                payload: {
+                    toolCallId: params.callId,
+                    status: params.ok ? "completed" : "failed",
+                    ...(params.outputPreview ? {
+                        content: [{ type: "content", content: { type: "text", text: params.outputPreview } }],
+                    } : {}),
+                    ...(params.error ? {
+                        content: [{ type: "content", content: { type: "text", text: params.error } }],
+                    } : {}),
+                    // Full-fidelity fields for the openclaw gateway (lossless round-trip).
+                    toolName: params.name,
+                    ok: params.ok,
+                    error: params.error,
+                    outputPreview: params.outputPreview,
+                    durationMs: params.durationMs,
+                    exitCode: params.exitCode,
+                    stdout: params.stdout,
+                    stderr: params.stderr,
+                    details: params.details,
+                },
+            };
+        case "turn.skill_instruction":
+            return {
+                type: ACP_EXTENDED_SESSION_UPDATE_TYPES.X_SKILL_INSTRUCTION,
+                payload: {
+                    skillId: "unknown",
+                    instruction: String(params.instruction ?? ""),
+                },
+            };
+        // turn.end + turn.error ride the session/prompt response; approval flows via
+        // session/request_permission; pong is transport keepalive.
+        case "turn.end":
+        case "turn.error":
+        case "turn.media_usage":
+        case "tool.approval.request":
+        case "pong":
+            return null;
+        default:
+            // Global/lifecycle events stay raw for the host's persistent lifecycle handler.
+            if (method.startsWith("project.") || method.startsWith("session.") || method.startsWith("workflow.")) {
+                return null;
+            }
+            // Other turn-scoped events (turn.*, agents.*, product.*, solo.*, memory.*, …) ride a
+            // generic x_relay so the host reconstructs them losslessly (matches legacy relay).
+            return {
+                type: ACP_EXTENDED_SESSION_UPDATE_TYPES.X_RELAY,
+                payload: { method, params },
+            };
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function parseRawInput(args) {
+    if (!args)
+        return undefined;
+    try {
+        return JSON.parse(args);
+    }
+    catch {
+        return { raw: args };
+    }
+}

package/dist/transport/acp-event-emitter.test.d.ts

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

package/dist/transport/acp-event-emitter.test.js

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { emitAcpUpdate } from "./acp-event-emitter.js";
+/**
+ * A minimal AcpServer stand-in that records every emitSessionUpdate call.
+ * emitAcpUpdate() only ever touches server.emitSessionUpdate, so this captures
+ * the full output contract of the emitter without spinning up a transport.
+ */
+function makeEmitterSink() {
+    const emitted = [];
+    const server = {
+        emitSessionUpdate(sessionId, type, payload) {
+            emitted.push({ sessionId, type, payload });
+        },
+    };
+    return { server, emitted };
+}
+describe("emitAcpUpdate mapping", () => {
+    it("maps turn.start to x_session_info, passing through projectId/model/provider", () => {
+        const { server, emitted } = makeEmitterSink();
+        const handled = emitAcpUpdate(server, "s1", "turn.start", {
+            sessionId: "s1",
+            projectId: "p1",
+            model: "deepseek-chat",
+            provider: "deepseek",
+        });
+        expect(handled).toBe(true);
+        expect(emitted).toHaveLength(1);
+        expect(emitted[0].type).toBe("x_session_info");
+        expect(emitted[0].sessionId).toBe("s1");
+        expect(emitted[0].payload).toMatchObject({
+            sessionId: "s1",
+            projectId: "p1",
+            model: "deepseek-chat",
+            provider: "deepseek",
+        });
+    });
+    it("maps turn.delta to the standard agent_message_chunk", () => {
+        const { server, emitted } = makeEmitterSink();
+        const handled = emitAcpUpdate(server, "s1", "turn.delta", { text: "hello" });
+        expect(handled).toBe(true);
+        expect(emitted).toHaveLength(1);
+        expect(emitted[0].type).toBe("agent_message_chunk");
+        expect(emitted[0].payload).toEqual({ content: { type: "text", text: "hello" } });
+    });
+    it("maps turn.reasoning_delta to the standard agent_thought_chunk", () => {
+        const { server, emitted } = makeEmitterSink();
+        const handled = emitAcpUpdate(server, "s1", "turn.reasoning_delta", { delta: "thinking" });
+        expect(handled).toBe(true);
+        expect(emitted[0].type).toBe("agent_thought_chunk");
+        expect(emitted[0].payload).toEqual({ content: { type: "text", text: "thinking" } });
+    });
+    it("does not emit for turn.end (rides the session/prompt response)", () => {
+        const { server, emitted } = makeEmitterSink();
+        const handled = emitAcpUpdate(server, "s1", "turn.end", { stopReason: "end_turn" });
+        expect(handled).toBe(false);
+        expect(emitted).toHaveLength(0);
+    });
+    it("does not emit for turn.error (rides the JSON-RPC error / chunks)", () => {
+        const { server, emitted } = makeEmitterSink();
+        const handled = emitAcpUpdate(server, "s1", "turn.error", { error: { code: "NO_PROVIDER" } });
+        expect(handled).toBe(false);
+        expect(emitted).toHaveLength(0);
+    });
+    it("does not emit for tool.approval.request (flows via session/request_permission)", () => {
+        const { server, emitted } = makeEmitterSink();
+        const handled = emitAcpUpdate(server, "s1", "tool.approval.request", { callId: "c1" });
+        expect(handled).toBe(false);
+        expect(emitted).toHaveLength(0);
+    });
+    it("drops lifecycle/global events (project.*, session.*, workflow.*) as raw", () => {
+        const { server, emitted } = makeEmitterSink();
+        expect(emitAcpUpdate(server, "s1", "project.opened", { projectId: "p1" })).toBe(false);
+        expect(emitAcpUpdate(server, "s1", "workflow.started", {})).toBe(false);
+        expect(emitted).toHaveLength(0);
+    });
+    it("relays unmodelled turn-scoped events losslessly via x_relay", () => {
+        const { server, emitted } = makeEmitterSink();
+        const handled = emitAcpUpdate(server, "s1", "turn.custom_event", { foo: "bar", n: 1 });
+        expect(handled).toBe(true);
+        expect(emitted).toHaveLength(1);
+        expect(emitted[0].type).toBe("x_relay");
+        expect(emitted[0].payload).toEqual({
+            method: "turn.custom_event",
+            params: { foo: "bar", n: 1 },
+        });
+    });
+});

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

@@ -0,0 +1,169 @@
+/**
+ * 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 type { Transport } from "./io-transport.js";
+import { type AcpInitializeParams, type AcpInitializeResult, type AcpSessionNewParams, type AcpSessionLoadParams, type AcpSessionNewResult, type AcpSessionPromptParams, type AcpSessionPromptResult, type AcpSessionCloseParams, type AcpSessionSetConfigParams, type AcpSessionUpdateType, type AcpPermissionRequestParams, type AcpPermissionRequestResult } from "../protocol/wire/index.js";
+export declare const ACP_ERROR_CODES: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    /** Protocol version mismatch */
+    readonly PROTOCOL_MISMATCH: -32001;
+    /** Session not found */
+    readonly SESSION_NOT_FOUND: -32002;
+    /** Agent busy (turn in progress) */
+    readonly AGENT_BUSY: -32003;
+};
+/**
+ * Interface that StdioServer (or any backend) implements to handle ACP requests.
+ * Each method corresponds to an ACP protocol method.
+ */
+export interface AcpRequestHandler {
+    handleAcpInitialize(params: AcpInitializeParams): Promise<AcpInitializeResult>;
+    handleAcpSessionNew(params: AcpSessionNewParams): Promise<AcpSessionNewResult>;
+    handleAcpSessionPrompt(params: AcpSessionPromptParams): Promise<AcpSessionPromptResult>;
+    handleAcpSessionClose(params: AcpSessionCloseParams): Promise<void>;
+    handleAcpSessionSetConfig(params: AcpSessionSetConfigParams): Promise<void>;
+    handleAcpSessionSetModel(sessionId: string, model: string): Promise<void>;
+    handleAcpSessionSetMode(sessionId: string, modeId: string): Promise<string>;
+    handleAcpSessionLoad(params: AcpSessionLoadParams): Promise<{
+        replay: Array<{
+            type: "user_message_chunk" | "agent_message_chunk";
+            content: string;
+        }>;
+    }>;
+    /** Single source of truth for advertised slash commands (also summarized by /help). */
+    buildAvailableCommands(): Array<{
+        name: string;
+        description?: string;
+    }>;
+    /** Pre-prompt slash-command intercept. Returns {handled,reply}; server emits + acks. */
+    tryDispatchCommand(params: AcpSessionPromptParams): Promise<{
+        handled: boolean;
+        reply?: string;
+    }>;
+    handleAcpPermissionResponse(permissionId: string, optionId: string): void;
+    handleAcpAbort(params: {
+        sessionId: string;
+        turnId?: string;
+    }): Promise<void>;
+    handleAcpDream(params: {
+        sessionId: string;
+        config?: Record<string, unknown>;
+    }): Promise<{
+        ok: boolean;
+        summary?: string;
+    }>;
+    handleAcpAgentsList(): Promise<unknown>;
+    handleAcpSoloStart(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpSoloStatus(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpSoloSelect(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpSoloCancel(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpSoloSubscribe(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpSoloMessage(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpSoloEvaluate(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpSoloSpecChat(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpWorkflowChat(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpWorkflowMatchIntent(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpSoloSpecJudge(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductCreate(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductPlan(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductConfirm(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductMessage(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductPause(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductResume(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductCancel(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductRollback(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductStatus(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductSubscribe(params: Record<string, unknown>): Promise<unknown>;
+}
+export interface AcpServerConfig {
+    verbose?: boolean;
+}
+/**
+ * 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 declare class AcpServer {
+    private transport;
+    private handler;
+    private verbose;
+    /** Host capabilities declared during initialize */
+    private hostCapabilities;
+    /** Whether the host supports x_ extended events */
+    private hostSupportsExtendedEvents;
+    /** Whether the host supports x/ extended RPC methods */
+    private hostSupportsExtendedMethods;
+    /** Sessions registered via session/new on this connection (multi-session per connection). */
+    private registeredSessions;
+    /** Pending permission requests (agent -> host) waiting for response */
+    private pendingPermissions;
+    /** Map from outbound JSON-RPC request id -> permissionId for response matching */
+    private outboundRequestMap;
+    constructor(transport: Transport, handler: AcpRequestHandler, config?: AcpServerConfig);
+    /**
+     * 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: unknown): boolean;
+    /**
+     * 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: string, type: AcpSessionUpdateType, payload: Record<string, unknown>): void;
+    /**
+     * Send a permission request to the host (agent -> host RPC).
+     * Returns a promise that resolves with the host's chosen option.
+     */
+    requestPermission(params: AcpPermissionRequestParams): Promise<AcpPermissionRequestResult>;
+    /** Whether the host supports extended events */
+    get supportsExtendedEvents(): boolean;
+    /** Whether the host supports extended methods */
+    get supportsExtendedMethods(): boolean;
+    /** Whether a session id has been registered via session/new on this connection. */
+    hasSession(sessionId: string): boolean;
+    private handleRequest;
+    private handleNotification;
+    private handleResponse;
+    private onInitialize;
+    private onSessionNew;
+    private onSessionLoad;
+    private onSessionPrompt;
+    private onSessionClose;
+    private onSessionSetConfig;
+    private onSessionSetModel;
+    private onSessionSetMode;
+    private onAbort;
+    private onSessionCancel;
+    private onCancel;
+    private onDream;
+    private sendResult;
+    private sendError;
+    private isJsonRpcResponse;
+    private log;
+}