qlogicagent 1.3.0 → 2.1.0

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

@@ -0,0 +1,130 @@
+/**
+ * ACP Server — Agent-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/end
+ * - 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 "../cli/transport.js";
+import { type AcpInitializeParams, type AcpInitializeResult, type AcpSessionNewParams, type AcpSessionNewResult, type AcpSessionPromptParams, type AcpSessionPromptResult, type AcpSessionEndParams, type AcpSessionSetConfigParams, type AcpSessionUpdateType, type AcpPermissionRequestParams, type AcpPermissionRequestResult } from "qlogicagent-runtime-contracts";
+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>;
+    handleAcpSessionEnd(params: AcpSessionEndParams): Promise<void>;
+    handleAcpSessionSetConfig(params: AcpSessionSetConfigParams): Promise<void>;
+    handleAcpSessionSetModel(sessionId: string, model: string): Promise<void>;
+    handleAcpSessionSetMode(sessionId: string, mode: string): Promise<void>;
+    handleAcpPermissionResponse(permissionId: string, optionId: string): void;
+    handleAcpAbort(params: {
+        sessionId: string;
+    }): Promise<void>;
+    handleAcpDream(params: {
+        sessionId: string;
+        config?: Record<string, unknown>;
+    }): Promise<{
+        ok: boolean;
+        summary?: string;
+    }>;
+    handleAcpSoloStart(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpSoloStatus(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpSoloSelect(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductCreate(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductResume(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpProductStatus(params: Record<string, unknown>): Promise<unknown>;
+    handleAcpTeamDelegate(params: Record<string, unknown>): Promise<unknown>;
+}
+export interface AcpServerConfig {
+    verbose?: boolean;
+}
+/**
+ * AcpServer — manages 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/end` → 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;
+    /** Active session ID (ACP v1 = single session per connection) */
+    private activeSessionId;
+    /** Pending permission requests (agent → host) waiting for response */
+    private pendingPermissions;
+    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 host declared
+     * capabilities.extendedEvents = true.
+     */
+    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;
+    /** Get the active session ID */
+    get sessionId(): string | null;
+    private handleRequest;
+    private handleNotification;
+    private handleResponse;
+    private onInitialize;
+    private onSessionNew;
+    private onSessionPrompt;
+    private onSessionEnd;
+    private onSessionSetConfig;
+    private onAbort;
+    private onDream;
+    private sendResult;
+    private sendError;
+    private isJsonRpcResponse;
+    private log;
+}

package/dist/types/transport/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Transport layer — ACP Server + Event Emitter.
+ */
+export { AcpServer, ACP_ERROR_CODES } from "./acp-server.js";
+export type { AcpRequestHandler, AcpServerConfig } from "./acp-server.js";
+export { emitAcpUpdate } from "./acp-event-emitter.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qlogicagent",
-  "version": "1.3.0",
+  "version": "2.1.0",
   "description": "XiaozhiClaw Agent CLI — subprocess architecture (JSON-RPC over stdio)",
   "type": "module",
   "main": "dist/index.js",

package/dist/types/skills/memory/memory-store.d.ts

@@ -1,86 +0,0 @@
-export declare const MEMORY_ENTRY_DELIMITER = "\n\u00A7\n";
-export declare const DEFAULT_MEMORY_CHAR_LIMIT = 2200;
-export declare const DEFAULT_USER_CHAR_LIMIT = 1375;
-export type MemoryStoreTarget = "memory" | "user";
-export interface MemoryStoreResult {
-    ok: boolean;
-    message: string;
-    target: MemoryStoreTarget;
-    entries: readonly string[];
-    entryCount: number;
-    usage: string;
-    errorCode?: string;
-}
-export interface MemoryStoreOptions {
-    memoryCharLimit?: number;
-    userCharLimit?: number;
-    /** When true, mutations automatically persist to ~/.qlogicagent/memory.json */
-    persistToDisk?: boolean;
-}
-export interface MemoryStoreSerialized {
-    memory: string;
-    user: string;
-}
-export declare class MemoryStore {
-    private memoryEntries;
-    private userEntries;
-    private frozenSnapshot;
-    private snapshotFrozen;
-    private saveTimer;
-    private readonly memoryCharLimit;
-    private readonly userCharLimit;
-    private readonly persistToDisk;
-    constructor(options?: MemoryStoreOptions);
-    /**
-     * Load from serialized form (e.g. from PG or filesystem).
-     * Deduplicates entries on load.
-     */
-    loadFromSerialized(data: Partial<MemoryStoreSerialized>): void;
-    /**
-     * Serialize current live state for persistence.
-     */
-    serialize(): MemoryStoreSerialized;
-    /**
-     * Load from disk (~/.qlogicagent/memory.json). No-op if file doesn't exist.
-     * Call this at startup when persistToDisk is enabled.
-     */
-    loadFromDisk(): Promise<void>;
-    /**
-     * Synchronous variant for use in sync constructors / init paths.
-     */
-    loadFromDiskSync(): void;
-    /**
-     * Schedule a debounced save to disk (500ms). Multiple rapid mutations
-     * coalesce into a single disk write.
-     */
-    private scheduleSave;
-    /** Flush any pending save immediately. Call before shutdown. */
-    flush(): Promise<void>;
-    /**
-     * Freeze current entries for system prompt injection.
-     * Call once at session start. After freezing, mutations update
-     * live state but NOT the system prompt block.
-     */
-    freezeSnapshot(): void;
-    /**
-     * Get frozen system prompt block for the given target.
-     * Returns empty string if no entries or not yet frozen.
-     */
-    getSystemPromptBlock(target: MemoryStoreTarget): string;
-    add(target: MemoryStoreTarget, content: string): MemoryStoreResult;
-    replace(target: MemoryStoreTarget, oldText: string, newContent: string): MemoryStoreResult;
-    remove(target: MemoryStoreTarget, oldText: string): MemoryStoreResult;
-    getEntries(target: MemoryStoreTarget): readonly string[];
-    getUsage(target: MemoryStoreTarget): {
-        used: number;
-        limit: number;
-        percent: number;
-    };
-    isEmpty(): boolean;
-    private entriesFor;
-    private charLimitFor;
-    private formatUsage;
-    private renderBlock;
-    private successResult;
-    private errorResult;
-}

package/dist/types/skills/tools/skill-invoke-tool.d.ts

@@ -1,46 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-import type { WorkspaceSkill } from "../skill-system/skill-types.js";
-export declare const SKILL_TOOL_NAME: "skill_invoke";
-export interface SkillInvokeParams {
-    skill: string;
-    args?: string;
-}
-export declare const SKILL_INVOKE_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly skill: {
-            readonly type: "string";
-            readonly description: "Name of the skill to invoke. Use skill_list to see available skills.";
-        };
-        readonly args: {
-            readonly type: "string";
-            readonly description: string;
-        };
-    };
-    readonly required: readonly ["skill"];
-};
-export interface SkillToolDeps {
-    /**
-     * Get all available skills (Layer 0 metadata).
-     * Returns name + description pairs for tool manifest enrichment.
-     */
-    listSkills(): WorkspaceSkill[];
-    /**
-     * Read skill content (Layer 1 instructions).
-     * Returns the full SKILL.md content for the named skill.
-     * Returns null if skill not found.
-     */
-    readSkillContent(name: string): Promise<string | null>;
-    /**
-     * Execute the skill instructions as a sub-turn.
-     * The implementation should:
-     *   1. Build system prompt from SKILL.md content
-     *   2. Run a sub-turn (fork) with skill instructions
-     *   3. Return the sub-turn's final response
-     *
-     * If not provided, the skill content is returned directly
-     * (the LLM can then follow the instructions in context).
-     */
-    executeSkillSubturn?(skillName: string, skillContent: string, userArgs: string | undefined, signal?: AbortSignal): Promise<string>;
-}
-export declare function createSkillTool(deps: SkillToolDeps): PortableTool<SkillInvokeParams>;

package/dist/types/skills/tools/skill-list-tool.d.ts

@@ -1,33 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-export declare const SKILL_LIST_TOOL_NAME: "skill_list";
-export interface SkillListToolParams {
-    category?: string;
-}
-export declare const SKILL_LIST_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly category: {
-            readonly type: "string";
-            readonly description: "Filter skills by category (e.g. 'devops', 'mlops'). Omit to list all.";
-        };
-    };
-    readonly required: readonly [];
-};
-export interface SkillListItem {
-    name: string;
-    description: string;
-    version?: string;
-    category?: string;
-}
-export interface SkillListOutput {
-    skills: SkillListItem[];
-    categories: string[];
-}
-/**
- * Host-provided skill registry for listing.
- */
-export interface SkillListToolDeps {
-    /** List all available skills, optionally filtered by category. */
-    listSkills(category?: string): Promise<SkillListOutput>;
-}
-export declare function createSkillListTool(deps: SkillListToolDeps): PortableTool<SkillListToolParams>;

package/dist/types/skills/tools/skill-manage-tool.d.ts

@@ -1,73 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-export declare const SKILL_MANAGE_TOOL_NAME: "skill_manage";
-export type SkillManageAction = "create" | "edit" | "patch" | "delete" | "write_file" | "remove_file";
-export interface SkillManageToolParams {
-    action: SkillManageAction;
-    name: string;
-    content?: string;
-    category?: string;
-    filePath?: string;
-    fileContent?: string;
-    oldString?: string;
-    newString?: string;
-}
-export declare const SKILL_MANAGE_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly action: {
-            readonly type: "string";
-            readonly enum: readonly ["create", "edit", "patch", "delete", "write_file", "remove_file"];
-            readonly description: string;
-        };
-        readonly name: {
-            readonly type: "string";
-            readonly description: "Skill name (lowercase, max 64 chars, kebab-case: letters, digits, hyphens).";
-        };
-        readonly content: {
-            readonly type: "string";
-            readonly description: string;
-        };
-        readonly category: {
-            readonly type: "string";
-            readonly description: "Category/domain (e.g. 'devops', 'mlops'). Used by create to organize skills.";
-        };
-        readonly filePath: {
-            readonly type: "string";
-            readonly description: string;
-        };
-        readonly fileContent: {
-            readonly type: "string";
-            readonly description: "Content for write_file action. Max 1 MiB.";
-        };
-        readonly oldString: {
-            readonly type: "string";
-            readonly description: "Text to find for patch action (must match uniquely in SKILL.md).";
-        };
-        readonly newString: {
-            readonly type: "string";
-            readonly description: "Replacement text for patch action (can be empty to delete).";
-        };
-    };
-    readonly required: readonly ["action", "name"];
-};
-export interface SkillManageResult {
-    success: boolean;
-    message: string;
-    path?: string;
-}
-/**
- * Host-provided skill management backend.
- */
-export interface SkillManageToolDeps {
-    /**
-     * Execute a skill management action.
-     * The host handles file system operations, validation, and security scanning.
-     */
-    manageSkill(params: SkillManageToolParams): Promise<SkillManageResult>;
-    /**
-     * Validate skill name format.
-     * If not provided, tool uses built-in validation.
-     */
-    validateName?(name: string): string | null;
-}
-export declare function createSkillManageTool(deps: SkillManageToolDeps): PortableTool<SkillManageToolParams>;

package/dist/types/skills/tools/skill-view-tool.d.ts

@@ -1,37 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-export declare const SKILL_VIEW_TOOL_NAME: "skill_view";
-export interface SkillViewToolParams {
-    name: string;
-    filePath?: string;
-}
-export declare const SKILL_VIEW_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly name: {
-            readonly type: "string";
-            readonly description: "Skill name to view (e.g. 'code-review', 'deploy-ecs').";
-        };
-        readonly filePath: {
-            readonly type: "string";
-            readonly description: string;
-        };
-    };
-    readonly required: readonly ["name"];
-};
-export interface SkillViewOutput {
-    name: string;
-    content: string;
-    referenceFiles?: string[];
-    tags?: string[];
-}
-/**
- * Host-provided skill viewer.
- */
-export interface SkillViewToolDeps {
-    /**
-     * Read skill content. Returns the main SKILL.md or a specific file.
-     * Returns null if skill not found.
-     */
-    viewSkill(name: string, filePath?: string): Promise<SkillViewOutput | null>;
-}
-export declare function createSkillViewTool(deps: SkillViewToolDeps): PortableTool<SkillViewToolParams>;