qlogicagent 0.2.1 → 0.4.0

package/dist/agent/tool-loop.js

@@ -1,575 +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 { accumulateToolCalls } from "../llm/transport.js";
-import { advanceToolLoopState, applyToolChoicePolicy, buildAssistantToolCallMessage, buildToolResultMessage, filterToolCallsByAccessPolicy, recoverToolLoopStateFromChatConversation, resolveParallelToolCallScheduling, resolveSidechainToolAccessByType, settleToolLoopState, calculateTokenWarningState, resolveApiErrorRecovery, resolveOutputTokenEscalation, shouldAbortTurn, createTurnLoopGuardState, shouldAttemptReactiveCompact, createReactiveCompactState, classifyError, buildSkillInstruction, } from "../orchestration/index.js";
-// ── Budget constants (same as Hub) ───────────────────────────────────────────
-const MAX_TOOL_BUDGET_CAP = 100;
-const DEFAULT_TOOL_BUDGET = Math.min(Math.max(1, Number(process.env.TOOL_LOOP_DEFAULT_BUDGET) || 25), MAX_TOOL_BUDGET_CAP);
-const MAX_CONSECUTIVE_FAILURES = 3;
-const MAX_SIDECHAIN_DEPTH = 2;
-// ── Helper: resolve budget ───────────────────────────────────────────────────
-function resolveToolLoopBudget(requested) {
-    if (typeof requested === "number" && Number.isFinite(requested) && requested >= 1) {
-        return Math.min(Math.round(requested), MAX_TOOL_BUDGET_CAP);
-    }
-    return DEFAULT_TOOL_BUDGET;
-}
-// ── Main tool loop ───────────────────────────────────────────────────────────
-/**
- * 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 async function* executeToolLoop(params, transport, toolInvoker, log) {
-    const { turnId, sessionId, messages: inputMessages, tools, model, apiKey, temperature, hooks, signal, } = params;
-    const hookCtx = { sessionId, turnId };
-    // ── Tool eligibility filtering (CC permission-level parity) ────
-    const { resolveToolEligibility } = await import("../runtime/tool-eligibility.js");
-    const eligibility = resolveToolEligibility(tools, params.toolEligibilityContext);
-    const effectiveTools = eligibility.eligibleTools;
-    // Emit blocked tool events
-    for (const blocked of eligibility.blockedTools) {
-        yield { type: "tool_blocked", turnId, callId: "", name: blocked.toolName, reason: "blocked-by-policy" };
-    }
-    // ── No tools: single LLM call, no loop ─────────────────────────
-    if (!effectiveTools.length) {
-        yield* executeSingleLLMRound(turnId, model, inputMessages, apiKey, temperature, signal, transport, log);
-        return;
-    }
-    // ── Tool loop setup ────────────────────────────────────────────
-    const toolBudget = resolveToolLoopBudget(params.maxRounds);
-    const messages = [...inputMessages];
-    // Recover tool loop state from conversation history
-    let toolLoopState = recoverToolLoopStateFromChatConversation({
-        maxRounds: toolBudget,
-        replayMessages: messages,
-    }).state;
-    // Turn-loop-guard config (CC-aligned)
-    const guardConfig = {
-        contextWindowTokens: params.contextWindowTokens ?? 128_000,
-        responseBufferTokens: 13_000,
-        maxOutputTokens: params.maxOutputTokens ?? 16_384,
-        abortSignal: signal,
-        reactiveCompactEnabled: true,
-        outputEscalationEnabled: true,
-    };
-    let guardState = createTurnLoopGuardState(guardConfig);
-    let reactiveCompactState = createReactiveCompactState();
-    // In-memory sidechain depth (replaces Hub's PG recursive CTE)
-    let sidechainStarted = false;
-    let activeSidechainToolPolicy = null;
-    const sidechainDepth = (params.parentDepth ?? 0) + 1;
-    let lastUsage;
-    let finalText = "";
-    let consecutiveFailedRounds = 0;
-    let totalUsage = { prompt: 0, completion: 0 };
-    // Skill learning metrics
-    const distinctToolNames = new Set();
-    let totalToolCallCount = 0;
-    // ── Main loop ──────────────────────────────────────────────────
-    for (let round = 0; round < toolBudget; round++) {
-        // Turn-loop-guard: pre-round abort check (CC-aligned)
-        if (shouldAbortTurn(guardState, guardConfig)) {
-            log.info(`turn aborted by guard at round ${round}`);
-            break;
-        }
-        // Turn-loop-guard: token budget pre-check
-        const tokenWarning = calculateTokenWarningState(guardState, guardConfig);
-        if (tokenWarning.level === "blocking") {
-            if (tokenWarning.reason === "prompt_too_long" &&
-                shouldAttemptReactiveCompact(reactiveCompactState)) {
-                reactiveCompactState.attemptedThisTurn = true;
-                guardState.hasAttemptedReactiveCompact = true;
-                log.info(`token budget blocking (${tokenWarning.reason}), reactive compact needed`);
-            }
-            log.info(`token budget blocking (${tokenWarning.reason}), breaking tool loop`);
-            break;
-        }
-        if (tokenWarning.level === "warning") {
-            log.info(`token budget warning: ${tokenWarning.usagePercent}% used, ${tokenWarning.remainingTokens} remaining`);
-        }
-        // Build tool loop request: tool choice policy + state recovery
-        const toolChoiceResult = applyToolChoicePolicy({
-            tools: effectiveTools,
-            toolChoice: params.toolChoice ?? "auto",
-        });
-        const repaired = recoverToolLoopStateFromChatConversation({
-            maxRounds: toolBudget,
-            replayMessages: messages,
-            lastStopReason: toolLoopState.lastStopReason,
-            options: { stopReason: toolLoopState.lastStopReason },
-        });
-        const requestMessages = toolChoiceResult.extraSystemPrompt
-            ? [
-                { role: "system", content: toolChoiceResult.extraSystemPrompt },
-                ...repaired.state.replayMessages,
-            ]
-            : repaired.state.replayMessages;
-        if (repaired.recoveryActions.length > 0) {
-            log.debug(`tool loop recovery: ${repaired.recoveryActions.map((a) => a.detail ?? a.kind).join("; ")}`);
-        }
-        log.debug(`round ${round + 1}/${toolBudget}, messages: ${requestMessages.length}`);
-        // Hook: turn.before_inference
-        hooks?.invoke("turn.before_inference", { ...hookCtx, model }).catch(() => { });
-        // ── Streaming LLM round with Hermes delta suppression ───────
-        let hasToolCalls = false;
-        const textChunks = [];
-        const toolCallAccumulator = new Map();
-        let finishReason = "stop";
-        let roundUsage;
-        let streamError = null;
-        try {
-            for await (const chunk of transport.stream({
-                model,
-                messages: requestMessages,
-                tools: toolChoiceResult.tools,
-                toolChoice: toolChoiceResult.normalizedToolChoice ??
-                    "auto",
-                temperature,
-                maxTokens: guardState.currentMaxOutputTokens || undefined,
-            }, apiKey, signal)) {
-                switch (chunk.type) {
-                    case "delta":
-                        textChunks.push(chunk.text);
-                        // Hermes delta suppression: stop text forwarding once tool_calls detected
-                        if (!hasToolCalls) {
-                            yield { type: "delta", turnId, text: chunk.text };
-                        }
-                        break;
-                    case "tool_call_delta":
-                        hasToolCalls = true;
-                        accumulateToolCalls(toolCallAccumulator, chunk);
-                        break;
-                    case "reasoning_delta":
-                        break;
-                    case "usage":
-                        roundUsage = {
-                            prompt: chunk.promptTokens,
-                            completion: chunk.completionTokens,
-                            reasoning: chunk.reasoningTokens,
-                        };
-                        break;
-                    case "done":
-                        finishReason = chunk.finishReason;
-                        break;
-                }
-            }
-            // Hook: turn.after_inference (success path)
-            if (!hasToolCalls) {
-                hooks?.invoke("turn.after_inference", { ...hookCtx, model }).catch(() => { });
-            }
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            const status = typeof err?.status === "number"
-                ? err.status
-                : undefined;
-            streamError = { status, message };
-        }
-        // Hook: turn.after_inference (error path)
-        if (streamError) {
-            hooks?.invoke("turn.after_inference", { ...hookCtx, model, response: { error: streamError.message } }).catch(() => { });
-        }
-        // ── Handle LLM errors with turn-loop-guard recovery ────────
-        if (streamError) {
-            const recovery = resolveApiErrorRecovery({ status: streamError.status ?? 500, message: streamError.message }, guardState, guardConfig);
-            if (recovery.action === "reactive_compact" &&
-                shouldAttemptReactiveCompact(reactiveCompactState)) {
-                reactiveCompactState.attemptedThisTurn = true;
-                guardState.hasAttemptedReactiveCompact = true;
-                yield { type: "recovery", turnId, action: "reactive_compact", detail: `API ${streamError.status ?? 500}: ${streamError.message}` };
-            }
-            if (recovery.action === "retry") {
-                yield { type: "recovery", turnId, action: "retry", detail: recovery.reason };
-                continue;
-            }
-            const category = classifyError(streamError.status, streamError.message);
-            yield { type: "error", turnId, error: streamError.message, code: category };
-            return;
-        }
-        // Accumulate usage
-        if (roundUsage) {
-            totalUsage.prompt += roundUsage.prompt;
-            totalUsage.completion += roundUsage.completion;
-            if (roundUsage.reasoning) {
-                totalUsage.reasoning = (totalUsage.reasoning ?? 0) + roundUsage.reasoning;
-            }
-        }
-        // Turn-loop-guard: update token state from usage feedback
-        if (roundUsage?.prompt) {
-            guardState.promptTokens = roundUsage.prompt;
-        }
-        // Turn-loop-guard: handle max_tokens truncation → escalate output budget (CC-aligned)
-        if (finishReason === "length" || finishReason === "max_tokens") {
-            guardState.consecutiveTruncations += 1;
-            const modelMaxOutput = params.modelMaxOutputTokens ?? 65_536;
-            const escalation = resolveOutputTokenEscalation(guardState, guardConfig, modelMaxOutput);
-            if (escalation.shouldEscalate) {
-                guardState.currentMaxOutputTokens = escalation.newMax;
-                yield { type: "recovery", turnId, action: "output_escalation", detail: `${escalation.newMax} tokens` };
-            }
-        }
-        else {
-            guardState.consecutiveTruncations = 0;
-        }
-        lastUsage = roundUsage;
-        finalText = textChunks.join("");
-        // Convert accumulated tool call deltas to OpenAiToolCall[]
-        let toolCalls = [...toolCallAccumulator.values()].map((tc) => ({
-            id: tc.id || `tc_${turnId}_${round}_${Math.random().toString(36).slice(2, 8)}`,
-            type: "function",
-            function: { name: tc.name, arguments: tc.arguments },
-        }));
-        // Filter tool_calls against active sidechain policy
-        if (activeSidechainToolPolicy && toolCalls.length > 0) {
-            const filterResult = filterToolCallsByAccessPolicy(toolCalls, activeSidechainToolPolicy);
-            if (filterResult.denied.length > 0) {
-                log.info(`sidechain policy denied: ${filterResult.denied.map((d) => `${d.toolCall.function.name} (${d.reason})`).join(", ")}`);
-            }
-            toolCalls = filterResult.allowed;
-        }
-        // ── No tool calls → loop complete ──────────────────────────
-        if (toolCalls.length === 0) {
-            toolLoopState = settleToolLoopState(toolLoopState, {
-                replayMessages: messages,
-                lastStopReason: "completed",
-            });
-            // Sidechain completed event
-            if (sidechainStarted) {
-                yield { type: "sidechain_completed", turnId, depth: sidechainDepth, toolCallCount: totalToolCallCount };
-            }
-            // Skill learning: evaluate turn for skill instruction
-            if (totalToolCallCount > 0) {
-                const skillResult = {
-                    ok: true,
-                    toolCallCount: totalToolCallCount,
-                    distinctToolCount: distinctToolNames.size,
-                    multiStep: totalToolCallCount >= 2,
-                    hasSidechain: sidechainStarted,
-                    feedback: null,
-                    existingSkillName: null,
-                };
-                const skillInstruction = buildSkillInstruction(skillResult, {
-                    tools: [...distinctToolNames],
-                });
-                if (skillInstruction) {
-                    yield { type: "skill_instruction", turnId, instruction: skillInstruction };
-                }
-            }
-            yield { type: "end", turnId, content: finalText, usage: totalUsage, model };
-            return;
-        }
-        // ── Has tool calls → execute them ──────────────────────────
-        // Emit tool_call events for the host
-        for (const tc of toolCalls) {
-            yield {
-                type: "tool_call",
-                turnId,
-                callId: tc.id,
-                name: tc.function.name,
-                arguments: tc.function.arguments,
-            };
-        }
-        // Build assistant message with tool calls
-        messages.push(buildAssistantToolCallMessage(toolCalls));
-        // Setup sidechain on first tool calls (in-memory depth tracking)
-        if (!sidechainStarted) {
-            if (sidechainDepth > MAX_SIDECHAIN_DEPTH) {
-                yield {
-                    type: "error",
-                    turnId,
-                    error: `sidechain depth ${sidechainDepth} exceeds max ${MAX_SIDECHAIN_DEPTH}`,
-                    code: "SIDECHAIN_DEPTH_LIMIT",
-                };
-                return;
-            }
-            sidechainStarted = true;
-            const sidechainRole = sidechainDepth >= MAX_SIDECHAIN_DEPTH ? "leaf" : "orchestrator";
-            yield { type: "sidechain_started", turnId, depth: sidechainDepth, role: sidechainRole };
-            activeSidechainToolPolicy = resolveSidechainToolAccessByType({
-                type: "planner",
-                depth: sidechainDepth,
-                maxDepth: MAX_SIDECHAIN_DEPTH,
-                role: sidechainDepth >= MAX_SIDECHAIN_DEPTH ? "leaf" : "orchestrator",
-                toolNames: tools.map((t) => t.function.name),
-            });
-        }
-        // Advance tool loop state
-        toolLoopState = advanceToolLoopState(toolLoopState, {
-            replayMessages: messages,
-            pendingToolCallIds: toolCalls.map((tc) => tc.id),
-            completedToolCallIds: toolLoopState.completedToolCallIds,
-            lastStopReason: "tool_calls",
-        });
-        // Resolve parallel/serial scheduling
-        const scheduling = resolveParallelToolCallScheduling({
-            requestedPreference: undefined,
-            providerSupportsParallel: true,
-            toolCalls,
-            toolCapabilities: effectiveTools.map((t) => ({
-                name: t.function.name,
-                requiresApproval: t.meta?.requiresApproval ?? false,
-                approvalMode: (t.meta?.requiresApproval ? "user-confirm" : "pre-authorized"),
-                parallelSafe: t.meta?.parallelSafe ?? true,
-                serialOnly: t.meta?.serialOnly ?? false,
-            })),
-        });
-        // ── Execute tool calls in batches ──────────────────────────
-        const executedToolCallIds = [];
-        try {
-            for (const batch of scheduling.batches) {
-                if (batch.mode === "parallel") {
-                    const toolCallOpts = { hooks, sessionId };
-                    const batchResults = await Promise.all(batch.calls.map((tc) => executeToolCall(tc, turnId, toolInvoker, signal, log, toolCallOpts)));
-                    for (const r of batchResults) {
-                        if (r.blocked) {
-                            yield { type: "tool_blocked", turnId, callId: r.callId, name: r.toolName, reason: r.blockReason ?? "blocked" };
-                        }
-                        messages.push(r.message);
-                        executedToolCallIds.push(r.callId);
-                        distinctToolNames.add(r.toolName);
-                        totalToolCallCount++;
-                        yield {
-                            type: "tool_result",
-                            turnId,
-                            callId: r.callId,
-                            name: r.toolName,
-                            ok: r.ok,
-                            error: r.error,
-                        };
-                    }
-                }
-                else {
-                    for (const tc of batch.calls) {
-                        if (signal?.aborted) {
-                            yield { type: "error", turnId, error: "Turn aborted", code: "ABORTED" };
-                            return;
-                        }
-                        const r = await executeToolCall(tc, turnId, toolInvoker, signal, log, { hooks, sessionId });
-                        if (r.blocked) {
-                            yield { type: "tool_blocked", turnId, callId: r.callId, name: r.toolName, reason: r.blockReason ?? "blocked" };
-                        }
-                        messages.push(r.message);
-                        executedToolCallIds.push(r.callId);
-                        distinctToolNames.add(r.toolName);
-                        totalToolCallCount++;
-                        yield {
-                            type: "tool_result",
-                            turnId,
-                            callId: r.callId,
-                            name: r.toolName,
-                            ok: r.ok,
-                            error: r.error,
-                        };
-                    }
-                }
-            }
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            yield { type: "error", turnId, error: message, code: "TOOL_EXECUTION_ERROR" };
-            return;
-        }
-        // Settle tool loop state
-        toolLoopState = settleToolLoopState(toolLoopState, {
-            replayMessages: messages,
-            completedToolCallIds: [
-                ...toolLoopState.completedToolCallIds,
-                ...executedToolCallIds,
-            ],
-            lastStopReason: scheduling.mode,
-        });
-        // ── Consecutive failure tracking ───────────────────────────
-        const roundToolResults = messages.slice(-toolCalls.length);
-        const allFailed = roundToolResults.length > 0 &&
-            roundToolResults.every((msg) => {
-                const content = msg?.content;
-                if (typeof content !== "string")
-                    return false;
-                try {
-                    return JSON.parse(content)?.ok === false;
-                }
-                catch {
-                    return false;
-                }
-            });
-        if (allFailed) {
-            consecutiveFailedRounds += 1;
-            if (consecutiveFailedRounds >= MAX_CONSECUTIVE_FAILURES && finalText) {
-                log.info(`early exit: ${consecutiveFailedRounds} consecutive failed rounds, returning partial response`);
-                yield { type: "end", turnId, content: finalText, usage: totalUsage };
-                return;
-            }
-        }
-        else {
-            consecutiveFailedRounds = 0;
-        }
-    }
-    // ── Budget exhaustion ──────────────────────────────────────────
-    if (finalText) {
-        log.info(`tool loop budget exhausted (${toolBudget} rounds), returning partial response`);
-        // Sidechain completed event (budget exhaustion)
-        if (sidechainStarted) {
-            yield { type: "sidechain_completed", turnId, depth: sidechainDepth, toolCallCount: totalToolCallCount };
-        }
-        // Skill learning on partial completion
-        if (totalToolCallCount > 0) {
-            const skillResult = {
-                ok: true,
-                toolCallCount: totalToolCallCount,
-                distinctToolCount: distinctToolNames.size,
-                multiStep: totalToolCallCount >= 2,
-                hasSidechain: sidechainStarted,
-                feedback: null,
-                existingSkillName: null,
-            };
-            const skillInstruction = buildSkillInstruction(skillResult, {
-                tools: [...distinctToolNames],
-            });
-            if (skillInstruction) {
-                yield { type: "skill_instruction", turnId, instruction: skillInstruction };
-            }
-        }
-        yield { type: "end", turnId, content: finalText, usage: totalUsage, model };
-        return;
-    }
-    yield {
-        type: "error",
-        turnId,
-        error: `Tool loop exceeded budget (${toolBudget} rounds)`,
-        code: "TOOL_LOOP_LIMIT",
-    };
-}
-async function executeToolCall(toolCall, turnId, toolInvoker, signal, log, options) {
-    const toolName = toolCall.function.name;
-    log.debug(`tool_call: ${toolName}`);
-    const hooks = options?.hooks;
-    // Hook: tool.before_invoke — can block or mutate input (CC PreToolUse parity)
-    let effectiveArguments = toolCall.function.arguments;
-    if (hooks) {
-        try {
-            const hookResult = await hooks.invoke("tool.before_invoke", {
-                sessionId: options?.sessionId ?? "",
-                turnId,
-                callId: toolCall.id,
-                toolName,
-                arguments: safeParseJsonArgs(toolCall.function.arguments),
-            });
-            if (hookResult.action === "abort") {
-                const reason = hookResult.reason ?? "blocked by policy";
-                log.info(`tool ${toolName} blocked: ${reason}`);
-                // Emit approval.requested for blocked tools requiring approval
-                hooks.invoke("approval.requested", {
-                    sessionId: options?.sessionId ?? "",
-                    turnId,
-                    approvalId: toolCall.id,
-                    callId: toolCall.id,
-                    toolName,
-                }).catch(() => { });
-                const message = buildToolResultMessage(toolCall.id, {
-                    ok: false,
-                    error: reason,
-                });
-                return { callId: toolCall.id, toolName, ok: false, error: reason, blocked: true, blockReason: reason, message };
-            }
-            // CC PreToolUse input mutation: hook can return modified arguments via context
-            if (hookResult.action === "continue" && hookResult.context?.arguments) {
-                effectiveArguments = JSON.stringify(hookResult.context.arguments);
-                log.debug(`tool ${toolName}: input mutated by hook`);
-            }
-        }
-        catch {
-            // Hook failures are non-blocking — proceed with tool execution
-        }
-    }
-    const invokeResult = await toolInvoker.invoke(turnId, toolName, effectiveArguments, signal);
-    const ok = !invokeResult.error;
-    const message = buildToolResultMessage(toolCall.id, {
-        ok,
-        payload: invokeResult.result,
-        error: invokeResult.error,
-    });
-    // Hook: tool.after_invoke / tool.invoke_failed (fire-and-forget observability)
-    hooks?.invoke(ok ? "tool.after_invoke" : "tool.invoke_failed", {
-        sessionId: options?.sessionId ?? "",
-        turnId,
-        callId: toolCall.id,
-        toolName,
-        ok,
-        ...(invokeResult.error ? { error: invokeResult.error } : {}),
-    }).catch(() => { });
-    return {
-        callId: toolCall.id,
-        toolName,
-        ok,
-        error: invokeResult.error,
-        message,
-    };
-}
-function safeParseJsonArgs(raw) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return undefined;
-    }
-}
-// ── Internal: single LLM round (no tools) ───────────────────────────────────
-async function* executeSingleLLMRound(turnId, model, messages, apiKey, temperature, signal, transport, log) {
-    const textChunks = [];
-    let usage;
-    log.debug(`single LLM round, messages: ${messages.length}`);
-    for await (const chunk of transport.stream({ model, messages, temperature }, apiKey, signal)) {
-        switch (chunk.type) {
-            case "delta":
-                textChunks.push(chunk.text);
-                yield { type: "delta", turnId, text: chunk.text };
-                break;
-            case "usage":
-                usage = {
-                    prompt: chunk.promptTokens,
-                    completion: chunk.completionTokens,
-                    reasoning: chunk.reasoningTokens,
-                };
-                break;
-            case "done":
-                break;
-        }
-    }
-    yield {
-        type: "end",
-        turnId,
-        content: textChunks.join(""),
-        usage: usage ?? { prompt: 0, completion: 0 },
-        model,
-    };
-}