qlogicagent 0.2.1 → 0.4.0

package/README.md

@@ -1,45 +1,45 @@
-# qlogicagent
-
-CLI 子进程 Agent。小智 Claw 的本地 AI Agent 运行时，作为 openclaw Gateway 的子进程通过 **JSON-RPC over stdio** 通信。
-
-## 职责
-
-1. 接收 `agent.turn` JSON-RPC 请求，执行 Agent Loop（prompt → LLM → tool calls → iterate）。
-2. 通过 stdout 流式输出 `turn.chunk`、`turn.tool_call`、`turn.done` 等 JSON-RPC 事件。
-3. 工具执行委托回 Gateway（`turn.tool_call` → Gateway 执行 → `tool.result` 返回）。
-4. 支持 failover、parallel tools、context compression、team orchestration 等编排策略。
-5. 可选 qmemory 集成（memory hooks、skill learning、dream mechanism）。
-
-## 不负责
-
-1. HTTP/WebSocket 服务 — 由 qlogicagent-hub 负责。
-2. 持久化存储 — Agent 是无状态子进程，Session/Skill/Plan 由 Gateway 管理。
-3. LLM API Key 管理 — 配置通过 `agent.turn` 请求的 `config.llm` 字段传入。
-4. 平台 API、订阅、计费 — 由 qlogicagent-hub + openclaw-admin 负责。
-
-## 模块结构
-
-```
-src/
-├── cli/            # JSON-RPC stdio 入口 (main.ts, stdio-server.ts)
-├── agent/          # Agent 核心 (agent.ts, tool-loop.ts, types.ts)
-├── llm/            # LLM provider 注册、传输层 (OpenAI, Anthropic)
-├── orchestration/  # 编排策略 (failover, retry, parallel, compression, team)
-├── skills/         # PortableTool 实现 + 外部 skill 加载
-├── runtime/        # Hook registry, memory hooks, context compression
-├── contracts/      # Hook / planner / skill candidate / todo 契约
-└── config/         # 配置管理
-```
-
-## 运行命令
-
-```bash
-pnpm build          # TypeScript 编译
-pnpm test           # vitest 测试
-pnpm dev            # tsx watch 开发
-```
-
-## 测试
-
-- 单元测试：`test/` 目录，覆盖 LLM provider、orchestration、semantic turn tools。
-- E2E 测试：`test/e2e/` 目录，spawn CLI 进程验证 JSON-RPC 协议行为。
+# qlogicagent
+
+CLI 子进程 Agent。小智 Claw 的本地 AI Agent 运行时，作为 openclaw Gateway 的子进程通过 **JSON-RPC over stdio** 通信。
+
+## 职责
+
+1. 接收 `agent.turn` JSON-RPC 请求，执行 Agent Loop（prompt → LLM → tool calls → iterate）。
+2. 通过 stdout 流式输出 `turn.chunk`、`turn.tool_call`、`turn.done` 等 JSON-RPC 事件。
+3. 工具执行委托回 Gateway（`turn.tool_call` → Gateway 执行 → `tool.result` 返回）。
+4. 支持 failover、parallel tools、context compression、team orchestration 等编排策略。
+5. 可选 qmemory 集成（memory hooks、skill learning、dream mechanism）。
+
+## 不负责
+
+1. HTTP/WebSocket 服务 — 由 qlogicagent-hub 负责。
+2. 持久化存储 — Agent 是无状态子进程，Session/Skill/Plan 由 Gateway 管理。
+3. LLM API Key 管理 — 配置通过 `agent.turn` 请求的 `config.llm` 字段传入。
+4. 平台 API、订阅、计费 — 由 qlogicagent-hub + openclaw-admin 负责。
+
+## 模块结构
+
+```
+src/
+├── cli/            # JSON-RPC stdio 入口 (main.ts, stdio-server.ts)
+├── agent/          # Agent 核心 (agent.ts, tool-loop.ts, types.ts)
+├── llm/            # LLM provider 注册、传输层 (OpenAI, Anthropic)
+├── orchestration/  # 编排策略 (failover, retry, parallel, compression, team)
+├── skills/         # PortableTool 实现 + 外部 skill 加载
+├── runtime/        # Hook registry, memory hooks, context compression
+├── contracts/      # Hook / planner / skill candidate / todo 契约
+└── config/         # 配置管理
+```
+
+## 运行命令
+
+```bash
+pnpm build          # TypeScript 编译
+pnpm test           # vitest 测试
+pnpm dev            # tsx watch 开发
+```
+
+## 测试
+
+- 单元测试：`test/` 目录，覆盖 LLM provider、orchestration、semantic turn tools。
+- E2E 测试：`test/e2e/` 目录，spawn CLI 进程验证 JSON-RPC 协议行为。

package/package.json

@@ -1,43 +1,57 @@
-{
-  "name": "qlogicagent",
-  "version": "0.2.1",
-  "description": "XiaozhiClaw Agent CLI — subprocess architecture (JSON-RPC over stdio)",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "qlogicagent": "dist/cli/main.js"
-  },
-  "exports": {
-    ".": "./dist/index.js",
-    "./agent": "./dist/agent/agent.js",
-    "./contracts": "./dist/contracts/index.js",
-    "./orchestration": "./dist/orchestration/index.js"
-  },
-  "files": [
-    "dist/"
-  ],
-  "scripts": {
-    "dev": "tsx watch src/index.ts",
-    "build": "tsc --noCheck",
-    "start": "node dist/cli/main.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "oxlint ."
-  },
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "dependencies": {
-    "dotenv": "^17.3.1",
-    "nanoid": "^5.1.5",
-    "qlogicagent-runtime-contracts": "^3.0.0",
-    "pino": "^9.6.0",
-    "pino-pretty": "^13.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.15.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.9.0",
-    "vitest": "^3.1.0"
-  }
+{
+  "name": "qlogicagent",
+  "version": "0.4.0",
+  "description": "XiaozhiClaw Agent CLI — subprocess architecture (JSON-RPC over stdio)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "qlogicagent": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./agent": {
+      "types": "./dist/types/agent/agent.d.ts",
+      "default": "./dist/agent.js"
+    },
+    "./contracts": {
+      "types": "./dist/types/contracts/index.d.ts",
+      "default": "./dist/contracts.js"
+    },
+    "./orchestration": {
+      "types": "./dist/types/orchestration/index.d.ts",
+      "default": "./dist/orchestration.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "node scripts/build.mjs",
+    "build:tsc": "tsc --noCheck",
+    "start": "node dist/cli/main.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint ."
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "dotenv": "^17.3.1",
+    "nanoid": "^5.1.5",
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.0.0",
+    "qlogicagent-runtime-contracts": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "esbuild": "^0.28.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.1.0"
+  }
 }

package/dist/agent/agent.d.ts

@@ -1,43 +0,0 @@
-/**
- * Agent — clean agent execution loop for CLI subprocess mode.
- *
- * Thin wrapper around tool-loop.ts. Handles:
- *   - DI injection (LLMTransport, ToolInvoker, AgentLogger)
- *   - Turn lifecycle (start event + message repair + delegate to tool loop)
- *   - Top-level error handling
- *
- * The actual tool loop state machine (turn-loop-guard, tool-loop-state,
- * parallel scheduling, sidechain filtering, etc.) lives in tool-loop.ts,
- * ported faithfully from Hub's semantic-turn-tools.ts.
- *
- * Zero imports from express/pg/ioredis/ws.
- */
-import type { AgentLogger, ToolInvoker, TurnEvent, TurnRequest, HookRegistry } from "./types.js";
-import type { LLMTransport } from "../llm/transport.js";
-export interface AgentConfig {
-    llmTransport: LLMTransport;
-    apiKey: string;
-    toolInvoker: ToolInvoker;
-    log: AgentLogger;
-    hooks?: HookRegistry;
-    maxRounds?: number;
-    verbose?: boolean;
-}
-export declare class Agent {
-    private transport;
-    private apiKey;
-    private toolInvoker;
-    private log;
-    private hooks?;
-    private maxRounds;
-    constructor(config: AgentConfig);
-    /**
-     * Execute an agent turn. Yields TurnEvent stream.
-     *
-     * 1. Emit start
-     * 2. Repair conversation history
-     * 3. Delegate to executeToolLoop() (full Hub-ported tool loop state machine)
-     * 4. Catch unhandled errors
-     */
-    run(request: TurnRequest, signal?: AbortSignal): AsyncGenerator<TurnEvent>;
-}

package/dist/agent/agent.js

@@ -1,113 +0,0 @@
-/**
- * Agent — clean agent execution loop for CLI subprocess mode.
- *
- * Thin wrapper around tool-loop.ts. Handles:
- *   - DI injection (LLMTransport, ToolInvoker, AgentLogger)
- *   - Turn lifecycle (start event + message repair + delegate to tool loop)
- *   - Top-level error handling
- *
- * The actual tool loop state machine (turn-loop-guard, tool-loop-state,
- * parallel scheduling, sidechain filtering, etc.) lives in tool-loop.ts,
- * ported faithfully from Hub's semantic-turn-tools.ts.
- *
- * Zero imports from express/pg/ioredis/ws.
- */
-import { repairOpenAiChatConversation, classifyError, getRetryStrategy, } from "../orchestration/index.js";
-import { executeToolLoop } from "./tool-loop.js";
-const MAX_ROUNDS_LIMIT = 100;
-export class Agent {
-    transport;
-    apiKey;
-    toolInvoker;
-    log;
-    hooks;
-    maxRounds;
-    constructor(config) {
-        this.transport = config.llmTransport;
-        this.apiKey = config.apiKey;
-        this.toolInvoker = config.toolInvoker;
-        this.log = config.log;
-        this.hooks = config.hooks;
-        this.maxRounds = Math.min(config.maxRounds ?? 25, MAX_ROUNDS_LIMIT);
-    }
-    /**
-     * Execute an agent turn. Yields TurnEvent stream.
-     *
-     * 1. Emit start
-     * 2. Repair conversation history
-     * 3. Delegate to executeToolLoop() (full Hub-ported tool loop state machine)
-     * 4. Catch unhandled errors
-     */
-    async *run(request, signal) {
-        const { turnId, messages: inputMessages, tools, systemPrompt, config } = request;
-        const hookCtx = { sessionId: request.sessionId, turnId };
-        yield { type: "start", turnId };
-        // Hook: turn.submitted
-        this.hooks?.invoke("turn.submitted", {
-            ...hookCtx,
-            prompt: inputMessages[inputMessages.length - 1]?.content ?? undefined,
-        }).catch(() => { });
-        // Repair malformed tool-call sequences in the input conversation history
-        const repairedMessages = repairOpenAiChatConversation(inputMessages);
-        // Build conversation: prepend system prompt if provided
-        const conversation = [];
-        if (systemPrompt) {
-            conversation.push({ role: "system", content: systemPrompt });
-        }
-        conversation.push(...repairedMessages);
-        const model = config?.model ?? "";
-        const maxRounds = Math.min(config?.maxRounds ?? this.maxRounds, MAX_ROUNDS_LIMIT);
-        try {
-            const toolLoopParams = {
-                turnId,
-                sessionId: request.sessionId,
-                messages: conversation,
-                tools,
-                model,
-                apiKey: config?.apiKey ?? this.apiKey,
-                temperature: config?.temperature,
-                maxRounds,
-                contextWindowTokens: config?.contextWindowTokens,
-                maxOutputTokens: config?.maxOutputTokens,
-                modelMaxOutputTokens: config?.modelMaxOutputTokens,
-                toolChoice: config?.toolChoice,
-                parentDepth: config?.parentDepth,
-                hooks: this.hooks,
-                signal,
-            };
-            let lastEvent;
-            for await (const event of executeToolLoop(toolLoopParams, this.transport, this.toolInvoker, this.log)) {
-                lastEvent = event;
-                yield event;
-            }
-            // Hook: turn.completed / turn.failed based on final event
-            if (lastEvent?.type === "end") {
-                this.hooks?.invoke("turn.completed", { ...hookCtx }).catch(() => { });
-            }
-            else if (lastEvent?.type === "error") {
-                this.hooks?.invoke("turn.failed", {
-                    ...hookCtx,
-                    code: lastEvent.code,
-                    error: lastEvent.error,
-                }).catch(() => { });
-            }
-        }
-        catch (err) {
-            if (signal?.aborted) {
-                this.hooks?.invoke("turn.failed", { ...hookCtx, code: "ABORTED", error: "Turn aborted" }).catch(() => { });
-                yield { type: "error", turnId, error: "Turn aborted", code: "ABORTED" };
-            }
-            else {
-                const message = err instanceof Error ? err.message : String(err);
-                const status = typeof err?.status === "number"
-                    ? err.status
-                    : undefined;
-                const category = classifyError(status, message);
-                const strategy = getRetryStrategy(category);
-                this.log.error(`turn ${turnId} error [${category}, retryable=${strategy.retryable}]: ${message}`);
-                this.hooks?.invoke("turn.failed", { ...hookCtx, code: category, error: message }).catch(() => { });
-                yield { type: "error", turnId, error: message, code: category };
-            }
-        }
-    }
-}

package/dist/agent/tool-loop.d.ts

@@ -1,64 +0,0 @@
-/**
- * Tool loop state machine — faithful port of Hub's semantic-turn-tools.ts.
- *
- * Replaces Hub infrastructure with DI abstractions:
- *   - invokeGatewayTool() (WS) → ToolInvoker.invoke()
- *   - createAdminInferProxyClient().stream() → LLMTransport.stream()
- *   - SemanticTurnDeps (PG/Redis) → in-memory state
- *   - sidechain DB depth → in-memory depth counter
- *   - Hub approval flow → skipped (CLI is local, all tools pre-authorized)
- *
- * Keeps ALL orchestration strategy calls from Hub:
- *   - turn-loop-guard (abort, token budget, output escalation)
- *   - tool-loop-state (advance/settle/recover)
- *   - parallel/serial tool call scheduling
- *   - sidechain tool access policy filtering
- *   - consecutive failure early exit
- *   - API error recovery
- *   - message repair
- *   - skill learning evaluation
- *
- * Zero imports from express/pg/ioredis/ws.
- */
-import type { AgentLogger, ChatMessage, ToolDefinition, ToolInvoker, TurnEvent, HookRegistry } from "./types.js";
-import type { LLMTransport } from "../llm/transport.js";
-export interface ToolLoopParams {
-    turnId: string;
-    sessionId: string;
-    messages: ChatMessage[];
-    tools: ToolDefinition[];
-    model: string;
-    apiKey: string;
-    temperature?: number;
-    maxRounds?: number;
-    /** Context window size in tokens (for turn-loop-guard budget checks) */
-    contextWindowTokens?: number;
-    /** Max output tokens for current model */
-    maxOutputTokens?: number;
-    /** Model's absolute max output tokens (escalation ceiling) */
-    modelMaxOutputTokens?: number;
-    /** Tool choice strategy (default "auto") */
-    toolChoice?: "auto" | "none" | "required";
-    /** Parent sidechain depth (0 = top-level) */
-    parentDepth?: number;
-    /** Tool eligibility context for policy-based filtering */
-    toolEligibilityContext?: import("../runtime/tool-eligibility.js").ToolEligibilityContext;
-    /** Hook registry for lifecycle events (optional, fire-and-forget) */
-    hooks?: HookRegistry;
-    signal?: AbortSignal;
-}
-/**
- * Execute the tool loop — faithful port of Hub's orchestrateAgentTurnWithGatewayTools().
- *
- * Yields TurnEvent stream. The caller (Agent class) wraps this with
- * start/end lifecycle and error handling.
- *
- * Events yielded:
- *   - delta: streaming text from LLM
- *   - tool_call: LLM requested a tool call
- *   - tool_result: tool execution completed
- *   - skill_instruction: skill learning evaluation result
- *   - end: turn completed successfully
- *   - error: unrecoverable error
- */
-export declare function executeToolLoop(params: ToolLoopParams, transport: LLMTransport, toolInvoker: ToolInvoker, log: AgentLogger): AsyncGenerator<TurnEvent>;