qlogicagent 2.13.3 → 2.13.5

package/dist/runtime/execution/streaming-tool-executor.js

@@ -0,0 +1,345 @@
+/**
+ * Streaming Tool Executor — CC StreamingToolExecutor parity.
+ *
+ * Executes tools as they stream in with concurrency control:
+ *   - Concurrent-safe tools execute in parallel with other concurrent-safe tools
+ *   - Non-concurrent tools execute alone (exclusive access)
+ *   - Results are buffered and emitted in the order tools were received
+ *   - Bash errors cascade to abort sibling tools
+ *   - Progress messages are yielded immediately
+ *
+ * Reference: claude-code src/services/tools/StreamingToolExecutor.ts
+ */
+import { buildToolResultMessage } from "../ports/tool-call-contracts.js";
+import { maybePersistLargeToolResult } from "./tool-result-storage.js";
+// ── Default concurrency-safe tools (CC parity) ──────────────
+const DEFAULT_CONCURRENT_SAFE = new Set([
+    "read_file", "file_read", "FileRead",
+    "grep", "Grep", "glob", "Glob",
+    "search", "list_dir", "find_files",
+    "web_fetch", "web_search", "WebFetch", "WebSearch",
+    // 检索编排工具(只读 egress,设计 §15-3:并发白名单按工具名硬编码,isConcurrencySafe 标志无效)
+    "web_answer", "web_research",
+]);
+/** Bash tool names — errors in these cascade to abort siblings (CC parity) */
+const BASH_TOOL_NAMES = new Set([
+    "bash", "execute_command", "Bash", "shell",
+]);
+// ── StreamingToolExecutor ───────────────────────────────────
+/**
+ * Executes tools with concurrency control and streaming progress.
+ *
+ * Usage:
+ *   1. Call addTool() for each tool call as they arrive from the LLM stream
+ *   2. Call getCompletedResults() to drain completed results (non-blocking)
+ *   3. Call getRemainingResults() to wait for all remaining tools
+ */
+export class StreamingToolExecutor {
+    tools = [];
+    hasErrored = false;
+    erroredToolDescription = "";
+    discarded = false;
+    siblingAbortController;
+    progressResolve;
+    config;
+    concurrencySafe;
+    constructor(config) {
+        this.config = config;
+        this.concurrencySafe = config.concurrencySafeTools ?? DEFAULT_CONCURRENT_SAFE;
+        // Child controller: fires when a bash tool errors so siblings die immediately
+        this.siblingAbortController = new AbortController();
+        if (config.signal) {
+            config.signal.addEventListener("abort", () => {
+                this.siblingAbortController.abort("parent_abort");
+            }, { once: true });
+        }
+    }
+    /**
+     * Discard all pending and in-progress tools.
+     * Queued tools won't start, and in-progress tools receive synthetic errors.
+     */
+    discard() {
+        this.discarded = true;
+    }
+    /**
+     * Add a tool to the execution queue. Starts executing immediately if conditions allow.
+     */
+    addTool(toolCall) {
+        const isConcurrencySafe = this.concurrencySafe.has(toolCall.function.name);
+        this.tools.push({
+            id: toolCall.id,
+            toolCall,
+            status: "queued",
+            isConcurrencySafe,
+            results: [],
+            pendingProgress: [],
+        });
+        void this.processQueue();
+    }
+    /**
+     * Check if a tool can execute based on current concurrency state.
+     */
+    canExecuteTool(isConcurrencySafe) {
+        const executing = this.tools.filter(t => t.status === "executing");
+        // Hard ceiling (CC maxConcurrentTools parity)
+        const cap = this.config.maxConcurrentTools;
+        if (cap && cap > 0 && executing.length >= cap)
+            return false;
+        return (executing.length === 0 ||
+            (isConcurrencySafe && executing.every(t => t.isConcurrencySafe)));
+    }
+    /**
+     * Process the queue, starting tools when concurrency conditions allow.
+     */
+    async processQueue() {
+        for (const tool of this.tools) {
+            if (tool.status !== "queued")
+                continue;
+            if (this.canExecuteTool(tool.isConcurrencySafe)) {
+                await this.executeTool(tool);
+            }
+            else if (!tool.isConcurrencySafe) {
+                break; // Non-concurrent tools block the queue
+            }
+        }
+    }
+    /**
+     * Get abort reason for a tool.
+     */
+    getAbortReason() {
+        if (this.discarded)
+            return "discarded";
+        if (this.hasErrored)
+            return "sibling_error";
+        if (this.config.signal?.aborted)
+            return "user_interrupted";
+        return null;
+    }
+    /**
+     * Get a human-readable description of a tool for error messages.
+     */
+    getToolDescription(tool) {
+        let args;
+        try {
+            args = JSON.parse(tool.toolCall.function.arguments);
+        }
+        catch { /* ignore */ }
+        const summary = args?.command ?? args?.file_path ?? args?.pattern ?? "";
+        if (typeof summary === "string" && summary.length > 0) {
+            const truncated = summary.length > 40 ? summary.slice(0, 40) + "…" : summary;
+            return `${tool.toolCall.function.name}(${truncated})`;
+        }
+        return tool.toolCall.function.name;
+    }
+    /**
+     * Create a synthetic error result for an aborted tool.
+     */
+    createSyntheticError(tool, reason) {
+        const desc = this.erroredToolDescription;
+        const msg = reason === "user_interrupted"
+            ? "User rejected tool use"
+            : reason === "discarded"
+                ? "Streaming fallback - tool execution discarded"
+                : desc
+                    ? `Cancelled: parallel tool call ${desc} errored`
+                    : "Cancelled: parallel tool call errored";
+        return {
+            callId: tool.id,
+            toolName: tool.toolCall.function.name,
+            ok: false,
+            error: msg,
+            message: buildToolResultMessage(tool.id, { ok: false, error: msg }),
+        };
+    }
+    /**
+     * Execute a single tool.
+     */
+    async executeTool(tool) {
+        tool.status = "executing";
+        const collectResults = async () => {
+            // Pre-flight abort check
+            const initialAbort = this.getAbortReason();
+            if (initialAbort) {
+                tool.results.push(this.createSyntheticError(tool, initialAbort));
+                tool.status = "completed";
+                return;
+            }
+            const { toolInvoker, hooks, sessionId, turnId, log } = this.config;
+            const toolName = tool.toolCall.function.name;
+            let thisToolErrored = false;
+            // Hook: tool.before_invoke
+            let effectiveArguments = tool.toolCall.function.arguments;
+            if (hooks) {
+                try {
+                    const hookResult = await hooks.invoke("tool.before_invoke", {
+                        sessionId,
+                        turnId,
+                        callId: tool.id,
+                        toolName,
+                        arguments: safeParseJsonArgs(effectiveArguments),
+                    });
+                    if (hookResult.action === "abort") {
+                        const reason = hookResult.reason ?? "blocked by policy";
+                        log.info(`tool ${toolName} blocked: ${reason}`);
+                        tool.results.push({
+                            callId: tool.id,
+                            toolName,
+                            ok: false,
+                            error: reason,
+                            blocked: true,
+                            blockReason: reason,
+                            message: buildToolResultMessage(tool.id, { ok: false, error: reason }),
+                        });
+                        tool.status = "completed";
+                        return;
+                    }
+                    if (hookResult.action === "continue" && hookResult.context?.arguments) {
+                        effectiveArguments = JSON.stringify(hookResult.context.arguments);
+                    }
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    const reason = `permission preflight failed: ${message}`;
+                    log.warn(`tool ${toolName} blocked: ${reason}`);
+                    tool.results.push({
+                        callId: tool.id,
+                        toolName,
+                        ok: false,
+                        error: reason,
+                        blocked: true,
+                        blockReason: reason,
+                        message: buildToolResultMessage(tool.id, { ok: false, error: reason }),
+                    });
+                    tool.status = "completed";
+                    return;
+                }
+            }
+            // Execute the tool
+            const startedAt = Date.now();
+            const invokeResult = await toolInvoker.invoke(turnId, toolName, effectiveArguments, this.siblingAbortController.signal);
+            const durationMs = Math.max(0, Date.now() - startedAt);
+            // Check for mid-execution abort
+            const midAbort = this.getAbortReason();
+            if (midAbort && !thisToolErrored) {
+                tool.results.push(this.createSyntheticError(tool, midAbort));
+                tool.status = "completed";
+                return;
+            }
+            const ok = !invokeResult.error;
+            // Level 1: Persist oversized tool results to disk (CC maybePersistLargeToolResult parity).
+            // Replaces old hard truncation at 51_200 chars with disk persistence + preview reference.
+            let payload = invokeResult.result;
+            if (ok && payload && payload.length > 50_000) {
+                payload = await maybePersistLargeToolResult(payload, tool.id, sessionId);
+            }
+            const message = buildToolResultMessage(tool.id, {
+                ok,
+                payload,
+                error: invokeResult.error,
+                toolReferences: invokeResult.toolReferences,
+                imageUrls: invokeResult.imageUrls,
+            });
+            if (!ok) {
+                thisToolErrored = true;
+                // Only bash errors cascade to siblings (CC parity)
+                if (BASH_TOOL_NAMES.has(toolName)) {
+                    this.hasErrored = true;
+                    this.erroredToolDescription = this.getToolDescription(tool);
+                    this.siblingAbortController.abort("sibling_error");
+                }
+            }
+            // Hook: tool.after_invoke / tool.invoke_failed
+            hooks?.invoke(ok ? "tool.after_invoke" : "tool.invoke_failed", {
+                sessionId,
+                turnId,
+                callId: tool.id,
+                toolName,
+                ok,
+                ...(invokeResult.error ? { error: invokeResult.error } : {}),
+            }).catch(() => { });
+            tool.results.push({
+                callId: tool.id,
+                toolName,
+                ok,
+                error: invokeResult.error,
+                durationMs,
+                details: invokeResult.details,
+                message,
+            });
+            tool.status = "completed";
+        };
+        const promise = collectResults();
+        tool.promise = promise;
+        // Process more queue when done
+        void promise.finally(() => {
+            void this.processQueue();
+        });
+    }
+    /**
+     * Get completed results that haven't been yielded yet (non-blocking).
+     * Maintains order where necessary.
+     */
+    *getCompletedResults() {
+        if (this.discarded)
+            return;
+        for (const tool of this.tools) {
+            if (tool.status === "yielded")
+                continue;
+            if (tool.status === "completed" && tool.results.length > 0) {
+                tool.status = "yielded";
+                for (const result of tool.results) {
+                    yield result;
+                }
+            }
+            else if (tool.status === "executing" && !tool.isConcurrencySafe) {
+                break; // Non-concurrent tools block yielding
+            }
+        }
+    }
+    /**
+     * Wait for remaining tools and yield results as they complete.
+     */
+    async *getRemainingResults() {
+        if (this.discarded)
+            return;
+        while (this.hasUnfinishedTools()) {
+            await this.processQueue();
+            for (const result of this.getCompletedResults()) {
+                yield result;
+            }
+            // Wait for executing tools to complete
+            if (this.hasExecutingTools() && !this.hasCompletedResults()) {
+                const executingPromises = this.tools
+                    .filter(t => t.status === "executing" && t.promise)
+                    .map(t => t.promise);
+                const progressPromise = new Promise(resolve => {
+                    this.progressResolve = resolve;
+                });
+                if (executingPromises.length > 0) {
+                    await Promise.race([...executingPromises, progressPromise]);
+                }
+            }
+        }
+        // Final drain
+        for (const result of this.getCompletedResults()) {
+            yield result;
+        }
+    }
+    hasCompletedResults() {
+        return this.tools.some(t => t.status === "completed");
+    }
+    hasExecutingTools() {
+        return this.tools.some(t => t.status === "executing");
+    }
+    hasUnfinishedTools() {
+        return this.tools.some(t => t.status !== "yielded");
+    }
+}
+function safeParseJsonArgs(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/runtime/execution/streaming-tool-executor.test.d.ts

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

package/dist/runtime/execution/streaming-tool-executor.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from "vitest";
+import { StreamingToolExecutor } from "./streaming-tool-executor.js";
+const log = {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+};
+describe("StreamingToolExecutor permission preflight", () => {
+    it("blocks the tool when tool.before_invoke cannot be evaluated", async () => {
+        const invoker = {
+            invoke: vi.fn(async () => ({ result: "should not run" })),
+        };
+        const hooks = {
+            register: vi.fn(() => () => { }),
+            invoke: vi.fn(async () => {
+                throw new Error("permission hook offline");
+            }),
+        };
+        const executor = new StreamingToolExecutor({
+            toolInvoker: invoker,
+            hooks,
+            sessionId: "s1",
+            turnId: "t1",
+            log,
+        });
+        executor.addTool({
+            id: "call-write",
+            type: "function",
+            function: {
+                name: "write",
+                arguments: "{\"path\":\"a.txt\",\"content\":\"x\"}",
+            },
+        });
+        const results = [];
+        for await (const result of executor.getRemainingResults()) {
+            results.push(result);
+        }
+        expect(invoker.invoke).not.toHaveBeenCalled();
+        expect(results).toHaveLength(1);
+        expect(results[0]).toMatchObject({
+            callId: "call-write",
+            toolName: "write",
+            ok: false,
+            blocked: true,
+            blockReason: "permission preflight failed: permission hook offline",
+        });
+    });
+});

package/dist/runtime/execution/tool-eligibility.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tool eligibility resolver for CLI subprocess mode.
+ *
+ * This layer only gates whether a tool may be offered to the model at all.
+ * Permission prompts are handled by the permission rule engine.
+ */
+import type { ToolDefinition } from "../ports/agent-execution-contracts.js";
+import type { PermissionRiskLevel } from "../ports/permission-contracts.js";
+export type ToolEligibilityDecision = "allow" | "ask" | "deny";
+export type ToolEligibilityStatus = "eligible" | "approval-required" | "blocked-by-policy";
+export type ToolEligibilityReasonCode = "policy_blocked" | "requires_approval" | "risk_read" | "risk_write" | "risk_system" | "risk_external_egress";
+export interface ToolEligibilityEntry {
+    toolName: string;
+    status: ToolEligibilityStatus;
+    decision: ToolEligibilityDecision;
+    riskLevel: PermissionRiskLevel;
+    approvalRequired: boolean;
+    reasonCodes: ToolEligibilityReasonCode[];
+}
+export interface ToolEligibilityContext {
+    /** Explicitly blocked tool names from config or policy. */
+    blockedToolNames?: string[];
+    /** Tool name regexes treated as system risk when no manifest risk is present. */
+    dangerousPatterns?: string[];
+}
+export interface ToolEligibilityResult {
+    /** Tools eligible for execution, including ask-before-run tools. */
+    eligibleTools: ToolDefinition[];
+    /** Tools blocked by policy and removed from the LLM tool list. */
+    blockedTools: ToolEligibilityEntry[];
+    /** Tools needing approval before execution. */
+    approvalRequiredTools: ToolEligibilityEntry[];
+    /** Full eligibility map by tool name. */
+    eligibilityByName: Map<string, ToolEligibilityEntry>;
+}
+export declare function resolveToolEligibility(tools: ToolDefinition[], context?: ToolEligibilityContext): ToolEligibilityResult;

package/dist/runtime/execution/tool-eligibility.js

@@ -0,0 +1,94 @@
+/**
+ * Tool eligibility resolver for CLI subprocess mode.
+ *
+ * This layer only gates whether a tool may be offered to the model at all.
+ * Permission prompts are handled by the permission rule engine.
+ */
+import { resolveToolRisk } from "../ports/tool-risk.js";
+const BUILTIN_SYSTEM_RISK_PATTERNS = [
+    /^(?:bash|shell|exec|terminal|run_command)$/i,
+    /^(?:git_push|git_reset|git_force)$/i,
+];
+function matchesSystemRiskPattern(toolName, extraPatterns) {
+    if (BUILTIN_SYSTEM_RISK_PATTERNS.some((re) => re.test(toolName))) {
+        return true;
+    }
+    if (extraPatterns) {
+        for (const pattern of extraPatterns) {
+            try {
+                if (new RegExp(pattern, "i").test(toolName))
+                    return true;
+            }
+            catch {
+                // Ignore invalid host-provided regexes.
+            }
+        }
+    }
+    return false;
+}
+function resolveRiskLevel(tool, context) {
+    // Shared core: explicit fields (riskLevel > isDangerous > isReadOnly > isEgress > write)
+    const r = resolveToolRisk(tool.meta);
+    // Site-specific escalation: name-pattern check on top of core result
+    if (r === "write" && matchesSystemRiskPattern(tool.function.name, context.dangerousPatterns))
+        return "system";
+    return r;
+}
+function riskReason(riskLevel) {
+    return `risk_${riskLevel}`;
+}
+function resolveEligibility(tool, context) {
+    const name = tool.function.name;
+    const riskLevel = resolveRiskLevel(tool, context);
+    const reasonCodes = [];
+    if (context.blockedToolNames?.includes(name)) {
+        reasonCodes.push("policy_blocked");
+        return { decision: "deny", riskLevel, reasonCodes };
+    }
+    reasonCodes.push(riskReason(riskLevel));
+    if (tool.meta?.requiresApproval || riskLevel === "system" || riskLevel === "external_egress") {
+        if (tool.meta?.requiresApproval)
+            reasonCodes.unshift("requires_approval");
+        return { decision: "ask", riskLevel, reasonCodes };
+    }
+    return { decision: "allow", riskLevel, reasonCodes };
+}
+function decisionToStatus(decision) {
+    switch (decision) {
+        case "allow":
+            return "eligible";
+        case "ask":
+            return "approval-required";
+        case "deny":
+            return "blocked-by-policy";
+    }
+}
+export function resolveToolEligibility(tools, context = {}) {
+    const eligibilityByName = new Map();
+    const eligibleTools = [];
+    const blockedTools = [];
+    const approvalRequiredTools = [];
+    for (const tool of tools) {
+        const name = tool.function.name;
+        const { decision, riskLevel, reasonCodes } = resolveEligibility(tool, context);
+        const status = decisionToStatus(decision);
+        const entry = {
+            toolName: name,
+            status,
+            decision,
+            riskLevel,
+            approvalRequired: decision === "ask",
+            reasonCodes,
+        };
+        eligibilityByName.set(name, entry);
+        if (decision === "deny") {
+            blockedTools.push(entry);
+            continue;
+        }
+        eligibleTools.push(tool);
+        if (decision === "ask") {
+            approvalRequiredTools.push(entry);
+        }
+    }
+    return { eligibleTools, blockedTools, approvalRequiredTools, eligibilityByName };
+}

package/dist/runtime/execution/tool-eligibility.test.d.ts

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

package/dist/runtime/execution/tool-eligibility.test.js

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import { resolveToolEligibility } from "./tool-eligibility.js";
+function tool(name, meta) {
+    return {
+        type: "function",
+        function: {
+            name,
+            description: `${name} tool`,
+            parameters: { type: "object", properties: {} },
+        },
+        meta,
+    };
+}
+describe("resolveToolEligibility", () => {
+    it("uses allow, ask, and deny decisions with unified risk levels", () => {
+        const result = resolveToolEligibility([
+            tool("read", { riskLevel: "read" }),
+            tool("exec", { riskLevel: "system" }),
+            tool("web_fetch", { riskLevel: "external_egress" }),
+            tool("blocked", { riskLevel: "write" }),
+        ], { blockedToolNames: ["blocked"] });
+        expect(result.eligibilityByName.get("read")).toMatchObject({
+            decision: "allow",
+            riskLevel: "read",
+            status: "eligible",
+            approvalRequired: false,
+        });
+        expect(result.eligibilityByName.get("exec")).toMatchObject({
+            decision: "ask",
+            riskLevel: "system",
+            status: "approval-required",
+            approvalRequired: true,
+        });
+        expect(result.eligibilityByName.get("web_fetch")).toMatchObject({
+            decision: "ask",
+            riskLevel: "external_egress",
+            status: "approval-required",
+            approvalRequired: true,
+        });
+        expect(result.eligibilityByName.get("blocked")).toMatchObject({
+            decision: "deny",
+            riskLevel: "write",
+            status: "blocked-by-policy",
+            approvalRequired: false,
+        });
+        expect(result.eligibilityByName.get("read")).not.toHaveProperty("permissionLevel");
+        expect(result.eligibleTools.map((entry) => entry.function.name)).toEqual(["read", "exec", "web_fetch"]);
+        expect(result.blockedTools.map((entry) => entry.toolName)).toEqual(["blocked"]);
+    });
+    it("keeps tool eligibility decisions identical when only assistantId changes", () => {
+        const tools = [
+            tool("read", { riskLevel: "read" }),
+            tool("exec", { riskLevel: "system" }),
+            tool("blocked", { riskLevel: "write" }),
+        ];
+        const basePolicy = { blockedToolNames: ["blocked"] };
+        const codeAssistant = resolveToolEligibility(tools, {
+            ...basePolicy,
+            assistantId: "builtin.code",
+        });
+        const docsAssistant = resolveToolEligibility(tools, {
+            ...basePolicy,
+            assistantId: "builtin.docs",
+        });
+        expect(summarize(codeAssistant)).toEqual(summarize(docsAssistant));
+    });
+});
+function summarize(result) {
+    return {
+        eligibleTools: result.eligibleTools.map((entry) => entry.function.name),
+        blockedTools: result.blockedTools.map(({ toolName, status, decision, riskLevel, approvalRequired }) => ({
+            toolName,
+            status,
+            decision,
+            riskLevel,
+            approvalRequired,
+        })),
+        approvalRequiredTools: result.approvalRequiredTools.map(({ toolName, status, decision, riskLevel, approvalRequired }) => ({
+            toolName,
+            status,
+            decision,
+            riskLevel,
+            approvalRequired,
+        })),
+        eligibilityByName: Array.from(result.eligibilityByName.entries()).map(([toolName, entry]) => [
+            toolName,
+            {
+                status: entry.status,
+                decision: entry.decision,
+                riskLevel: entry.riskLevel,
+                approvalRequired: entry.approvalRequired,
+                reasonCodes: entry.reasonCodes,
+            },
+        ]),
+    };
+}