qlogicagent 2.13.4 → 2.13.5

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

@@ -0,0 +1,2 @@
+import type { AgentLogger, ChatMessage, LLMTransport, TurnEvent } from "../types.js";
+export declare function executeSingleLLMRound(turnId: string, model: string, messages: ChatMessage[], apiKey: string, temperature: number | undefined, signal: AbortSignal | undefined, transport: LLMTransport, log: AgentLogger): AsyncGenerator<TurnEvent>;

package/dist/agent/tool-loop/single-round.js

@@ -0,0 +1,43 @@
+export async function* executeSingleLLMRound(turnId, model, messages, apiKey, temperature, signal, transport, log) {
+    const textChunks = [];
+    let usage;
+    let sawTerminalChunk = false;
+    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 = {
+                    inputTokens: chunk.promptTokens,
+                    outputTokens: chunk.completionTokens,
+                    reasoningTokens: chunk.reasoningTokens,
+                    cacheRead: chunk.cacheReadTokens,
+                    cacheWrite: chunk.cacheCreationTokens,
+                };
+                break;
+            case "done":
+                sawTerminalChunk = true;
+                break;
+        }
+    }
+    if (!sawTerminalChunk) {
+        yield {
+            type: "error",
+            turnId,
+            error: "LLM stream closed before a terminal event; the response was likely truncated upstream.",
+            code: "RETRYABLE_TRANSIENT",
+            usage: usage ?? { inputTokens: 0, outputTokens: 0 },
+        };
+        return;
+    }
+    yield {
+        type: "end",
+        turnId,
+        content: textChunks.join(""),
+        usage: usage ?? { inputTokens: 0, outputTokens: 0 },
+        model,
+    };
+}

package/dist/agent/tool-loop/skill-instruction-policy.d.ts

@@ -0,0 +1,7 @@
+import { buildSkillInstruction } from "../../orchestration/index.js";
+export interface SkillInstructionPolicyInput {
+    totalToolCallCount: number;
+    distinctToolNames: ReadonlySet<string>;
+    projectRoot?: string;
+}
+export declare function resolveToolUsageSkillInstruction(input: SkillInstructionPolicyInput): ReturnType<typeof buildSkillInstruction>;

package/dist/agent/tool-loop/skill-instruction-policy.js

@@ -0,0 +1,18 @@
+import { buildSkillInstruction, } from "../../orchestration/index.js";
+export function resolveToolUsageSkillInstruction(input) {
+    if (input.totalToolCallCount <= 0)
+        return null;
+    const skillResult = {
+        ok: true,
+        toolCallCount: input.totalToolCallCount,
+        distinctToolCount: input.distinctToolNames.size,
+        multiStep: input.totalToolCallCount >= 2,
+        hasSubAgent: false,
+        feedback: null,
+        existingSkillName: null,
+    };
+    return buildSkillInstruction(skillResult, {
+        tools: [...input.distinctToolNames],
+        projectRoot: input.projectRoot,
+    });
+}

package/dist/agent/tool-loop/stream-error-recovery.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Stream-error recovery — extracted phase of the tool loop (CC withRetry.ts parity).
+ *
+ * Handles an error thrown while streaming the LLM round. This is the loop's densest,
+ * most regression-prone branch, so it is pulled out behind a small control-flow
+ * protocol: the generator yields any user-facing events (recovery / error / heartbeat)
+ * and RETURNS a decision the loop acts on, instead of `continue`/`return`-ing the outer
+ * loop itself (which a sub-generator cannot do):
+ *
+ *   - { kind: "continue", patch } → loop applies `state = { ...state, ...patch }` and retries
+ *   - { kind: "return" }          → loop returns (a terminal error event was already yielded)
+ *   - { kind: "streamError", … }  → loop sets streamError and falls through to error withholding
+ *
+ * Behavior is byte-for-byte the same as the former inline catch block, including the
+ * in-place `consecutive529Errors` increment (so the count persists onto the loop's State
+ * whether we continue or fall through). Covered by tool-loop.states.test.ts:
+ * fallback / stale-connection / max-tokens-overflow / 429-retry.
+ */
+import type { AgentLogger, TokenUsage, ToolLoopTransition, TurnEvent } from "../types.js";
+/** Subset of the loop's State this phase reads / mutates in place. */
+export interface StreamErrorState {
+    consecutive529Errors: number;
+    consecutiveApiRetries: number;
+    currentModel: string;
+    totalUsage: TokenUsage;
+}
+/** Fields the loop should merge into State before continuing. */
+export interface StreamErrorPatch {
+    currentModel?: string;
+    consecutive529Errors?: number;
+    consecutiveApiRetries?: number;
+    maxOutputTokensOverride?: number;
+    transition?: ToolLoopTransition | undefined;
+}
+export type StreamErrorDecision = {
+    kind: "continue";
+    patch: StreamErrorPatch;
+} | {
+    kind: "return";
+} | {
+    kind: "streamError";
+    streamError: {
+        status?: number;
+        message: string;
+    };
+};
+export interface StreamErrorCtx {
+    state: StreamErrorState;
+    guardState: {
+        currentMaxOutputTokens: number;
+    };
+    fallbackModel: string | undefined;
+    signal: AbortSignal | undefined;
+    querySource: string | undefined;
+    turnId: string;
+    log: AgentLogger;
+    emitRecovery: (action: string, detail?: string) => TurnEvent;
+}
+export declare function handleStreamError(err: unknown, ctx: StreamErrorCtx): AsyncGenerator<TurnEvent, StreamErrorDecision>;

package/dist/agent/tool-loop/stream-error-recovery.js

@@ -0,0 +1,93 @@
+import { FallbackTriggeredError, isPersistentRetryEnabled, computeRetryBackoff, isForegroundSource, isTransientCapacityError, } from "../../orchestration/index.js";
+import { parseMaxTokensOverflow, parseRetryAfterMs } from "./recovery-helpers.js";
+import { MAX_API_RETRIES, MAX_529_RETRIES, HEARTBEAT_INTERVAL_MS } from "../tunable-defaults.js";
+export async function* handleStreamError(err, ctx) {
+    const { state, guardState, fallbackModel, signal, querySource, turnId, log, emitRecovery } = ctx;
+    // P0: FallbackTriggeredError catch (CC parity)
+    if (err instanceof FallbackTriggeredError && fallbackModel) {
+        log.info(`model fallback triggered: ${err.originalModel} -> ${err.fallbackModel}`);
+        yield emitRecovery("model_fallback", `${err.originalModel} -> ${err.fallbackModel}`);
+        return {
+            kind: "continue",
+            patch: { currentModel: err.fallbackModel, consecutive529Errors: 0, consecutiveApiRetries: 0, transition: undefined },
+        };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    const status = typeof err?.status === "number"
+        ? err.status
+        : undefined;
+    // CC isStaleConnectionError parity: ECONNRESET/EPIPE -> retry immediately
+    if (!status && message && (message.includes("ECONNRESET") || message.includes("EPIPE"))) {
+        const nextRetries = (state.consecutiveApiRetries ?? 0) + 1;
+        if (nextRetries > MAX_API_RETRIES) {
+            log.info(`stale connection retry limit reached (${MAX_API_RETRIES}), aborting`);
+            yield { type: "error", turnId, error: message, code: "RETRIES_EXHAUSTED", usage: state.totalUsage };
+            return { kind: "return" };
+        }
+        log.info(`stale connection (${message.includes("ECONNRESET") ? "ECONNRESET" : "EPIPE"}): retrying`);
+        yield emitRecovery("stale_connection_retry", message.slice(0, 80));
+        return { kind: "continue", patch: { consecutiveApiRetries: nextRetries, transition: undefined } };
+    }
+    // P2: max_tokens context overflow (CC parseMaxTokensContextOverflowError)
+    const overflowMaxTokens = parseMaxTokensOverflow({ status, message });
+    if (overflowMaxTokens !== null) {
+        log.info(`max_tokens overflow: adjusting to ${overflowMaxTokens}`);
+        guardState.currentMaxOutputTokens = overflowMaxTokens;
+        return { kind: "continue", patch: { maxOutputTokensOverride: overflowMaxTokens, transition: undefined } };
+    }
+    // P0: 529/429 consecutive tracking + fallback (CC withRetry.ts parity)
+    if (isTransientCapacityError(status)) {
+        // In-place increment so the count persists onto State on every exit path
+        // (continue OR streamError fall-through), matching the former inline behavior.
+        state.consecutive529Errors++;
+        // Hard limit: abort after too many consecutive transient errors without fallback
+        // or persistent retry. Transport retries 2x/call, so limit=2 caps at ~9 HTTP reqs.
+        const TRANSIENT_HARD_LIMIT = 2;
+        const canFallback = fallbackModel && state.currentModel !== fallbackModel;
+        if (state.consecutive529Errors > TRANSIENT_HARD_LIMIT && !canFallback && !isPersistentRetryEnabled()) {
+            log.info(`transient ${status} 脳 ${state.consecutive529Errors}: hard limit reached, aborting`);
+            yield {
+                type: "error",
+                turnId,
+                error: `API unavailable after ${state.consecutive529Errors} consecutive ${status} errors`,
+                code: "API_ERROR",
+                usage: state.totalUsage,
+            };
+            return { kind: "return" };
+        }
+        if (state.consecutive529Errors >= MAX_529_RETRIES && fallbackModel && state.currentModel !== fallbackModel) {
+            log.info(`529 脳 ${state.consecutive529Errors}: triggering fallback to ${fallbackModel}`);
+            yield emitRecovery("model_fallback", `529 脳 ${state.consecutive529Errors}`);
+            return { kind: "continue", patch: { currentModel: fallbackModel, consecutive529Errors: 0, transition: undefined } };
+        }
+        // P0: Persistent retry (CC UNATTENDED_RETRY parity)
+        if (isPersistentRetryEnabled()) {
+            const backoff = computeRetryBackoff(state.consecutive529Errors);
+            log.info(`persistent retry: waiting ${backoff}ms (attempt ${state.consecutive529Errors})`);
+            let remaining = backoff;
+            while (remaining > 0) {
+                if (signal?.aborted) {
+                    yield { type: "error", turnId, error: "Aborted during retry wait", code: "ABORTED", usage: state.totalUsage };
+                    return { kind: "return" };
+                }
+                yield { type: "heartbeat", turnId, message: `Retrying in ${Math.ceil(remaining / 1000)}s (${status})` };
+                const chunk = Math.min(remaining, HEARTBEAT_INTERVAL_MS);
+                await new Promise((r) => setTimeout(r, chunk));
+                remaining -= chunk;
+            }
+            return { kind: "continue", patch: { transition: undefined } };
+        }
+        // Foreground/background retry distinction (CC parity)
+        if (isForegroundSource(querySource)) {
+            const retryDelay = parseRetryAfterMs({ status, message });
+            const delay = retryDelay ?? computeRetryBackoff(state.consecutive529Errors);
+            log.info(`transient ${status}: retry in ${delay}ms`);
+            yield emitRecovery("retry", `${status} retry in ${delay}ms`);
+            await new Promise((r) => setTimeout(r, delay));
+            return { kind: "continue", patch: { transition: undefined } };
+        }
+        // Background: bail immediately
+        log.info(`background source ${querySource}: not retrying ${status}`);
+    }
+    return { kind: "streamError", streamError: { status, message } };
+}

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

@@ -0,0 +1,22 @@
+import type { ChatMessage } from "../types.js";
+import type { OpenAiToolCall } from "../../orchestration/index.js";
+export interface VariantBlockedToolCall {
+    call: OpenAiToolCall;
+    failCount: number;
+    error: string;
+}
+export declare function splitVariantToolCalls(calls: readonly OpenAiToolCall[], toolFailureCounts: ReadonlyMap<string, number>): {
+    allowed: OpenAiToolCall[];
+    blocked: VariantBlockedToolCall[];
+};
+export declare function variantBlockNudge(): ChatMessage;
+export declare function recordToolFailureResult(input: {
+    toolFailureCounts: Map<string, number>;
+    toolName: string;
+    ok: boolean;
+    softEmpty: boolean;
+}): void;
+export declare function newVariantFailureNudges(input: {
+    toolFailureCounts: ReadonlyMap<string, number>;
+    snapshot: ReadonlyMap<string, number>;
+}): ChatMessage[];

package/dist/agent/tool-loop/tool-failure-policy.js

@@ -0,0 +1,46 @@
+import { MAX_TOOL_VARIANT_FAILURES } from "../tunable-defaults.js";
+export function splitVariantToolCalls(calls, toolFailureCounts) {
+    const allowed = [];
+    const blocked = [];
+    for (const call of calls) {
+        const failCount = toolFailureCounts.get(call.function.name) ?? 0;
+        if (failCount >= MAX_TOOL_VARIANT_FAILURES) {
+            blocked.push({
+                call,
+                failCount,
+                error: `Tool "${call.function.name}" has failed ${failCount} times this turn with different arguments. The target likely does not exist. Stop trying variations and report the issue to the user.`,
+            });
+        }
+        else {
+            allowed.push(call);
+        }
+    }
+    return { allowed, blocked };
+}
+export function variantBlockNudge() {
+    return {
+        role: "user",
+        content: "Tool calls were blocked because the tool has failed too many times with different arguments. " +
+            "The resource you are looking for does not exist. Stop trying variations and tell the user what happened.",
+    };
+}
+export function recordToolFailureResult(input) {
+    if (input.ok && !input.softEmpty)
+        return;
+    const prev = input.toolFailureCounts.get(input.toolName) ?? 0;
+    input.toolFailureCounts.set(input.toolName, prev + 1);
+}
+export function newVariantFailureNudges(input) {
+    const nudges = [];
+    for (const [toolName, count] of input.toolFailureCounts) {
+        if (count >= MAX_TOOL_VARIANT_FAILURES && (input.snapshot.get(toolName) ?? 0) < MAX_TOOL_VARIANT_FAILURES) {
+            nudges.push({
+                role: "user",
+                content: `Tool "${toolName}" has now failed/returned empty results ${count} times with different arguments. ` +
+                    `The target clearly does not exist. Do NOT call "${toolName}" again. ` +
+                    "Report the result to the user immediately.",
+            });
+        }
+    }
+    return nudges;
+}

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

@@ -0,0 +1,11 @@
+import type { TurnEvent } from "../types.js";
+import type { ToolExecutionResultPort } from "../../runtime/ports/index.js";
+type ToolResultEvent = Extract<TurnEvent, {
+    type: "tool_result";
+}>;
+type ToolMediaResultEvent = Extract<TurnEvent, {
+    type: "media_result";
+}>;
+export declare function createToolResultEvent(turnId: string, result: ToolExecutionResultPort): ToolResultEvent;
+export declare function createToolMediaResultEvents(turnId: string, result: ToolExecutionResultPort): ToolMediaResultEvent[];
+export {};

package/dist/agent/tool-loop/tool-result-events.js

@@ -0,0 +1,59 @@
+export function createToolResultEvent(turnId, result) {
+    const rawOutput = typeof result.message?.content === "string"
+        ? result.message.content
+        : "";
+    const outputPreview = rawOutput ? rawOutput.slice(0, 2000) : undefined;
+    const details = result.details;
+    const stdout = typeof details?.stdout === "string" ? details.stdout.slice(0, 8000) : undefined;
+    const stderr = typeof details?.stderr === "string" ? details.stderr.slice(0, 4000) : undefined;
+    const exitCode = typeof details?.exitCode === "number" ? details.exitCode : undefined;
+    return {
+        type: "tool_result",
+        turnId,
+        callId: result.callId,
+        name: result.toolName,
+        ok: result.ok,
+        error: result.error,
+        outputPreview,
+        durationMs: result.durationMs,
+        exitCode,
+        stdout,
+        stderr,
+        details,
+    };
+}
+export function createToolMediaResultEvents(turnId, result) {
+    if (!result.ok)
+        return [];
+    const details = result.details;
+    if (!details)
+        return [];
+    const mediaType = mediaTypeFromDetails(details);
+    if (!mediaType)
+        return [];
+    const mediaUrls = Array.isArray(details.mediaUrls)
+        ? details.mediaUrls.filter((url) => typeof url === "string" && url.trim().length > 0)
+        : [];
+    return mediaUrls.map((url) => ({
+        type: "media_result",
+        turnId,
+        mediaType,
+        url,
+        model: typeof details.model === "string" ? details.model : undefined,
+        provider: typeof details.provider === "string" ? details.provider : undefined,
+        durationSeconds: typeof details.durationMs === "number" ? details.durationMs / 1000 : undefined,
+        taskId: typeof details.taskId === "string" ? details.taskId : undefined,
+    }));
+}
+function mediaTypeFromDetails(details) {
+    const detailType = typeof details.type === "string" ? details.type : "";
+    if (!detailType)
+        return null;
+    if (detailType === "three_d_generate")
+        return "3d";
+    const baseType = detailType.split("_")[0];
+    if (baseType === "image" || baseType === "tts" || baseType === "video" || baseType === "music") {
+        return baseType;
+    }
+    return null;
+}

package/dist/agent/tool-loop/tool-result-events.test.d.ts

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

package/dist/agent/tool-loop/tool-result-events.test.js

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { createToolMediaResultEvents } from "./tool-result-events.js";
+describe("createToolMediaResultEvents", () => {
+    it("emits persisted image media as a first-class turn side event", () => {
+        const events = createToolMediaResultEvents("turn-1", {
+            callId: "call-1",
+            toolName: "image_generate",
+            ok: true,
+            message: {},
+            details: {
+                type: "image_generate",
+                model: "doubao-seedream-4-5",
+                provider: "volcengine",
+                mediaUrls: ["file:///workspace/.qlogicagent/sessions/session-1/media/image_1.jpeg"],
+            },
+        });
+        expect(events).toEqual([
+            {
+                type: "media_result",
+                turnId: "turn-1",
+                mediaType: "image",
+                url: "file:///workspace/.qlogicagent/sessions/session-1/media/image_1.jpeg",
+                model: "doubao-seedream-4-5",
+                provider: "volcengine",
+                durationSeconds: undefined,
+                taskId: undefined,
+            },
+        ]);
+    });
+});

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

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

package/dist/agent/tool-loop.contract.test.js

@@ -0,0 +1,254 @@
+import { describe, expect, it, vi } from "vitest";
+import { executeToolLoop } from "./tool-loop.js";
+import { StreamingToolExecutor } from "../runtime/execution/streaming-tool-executor.js";
+class ScriptedTransport {
+    rounds;
+    requests = [];
+    constructor(rounds) {
+        this.rounds = rounds;
+    }
+    async *stream(request) {
+        this.requests.push(request);
+        const round = this.rounds.shift();
+        if (!round)
+            throw new Error("unexpected LLM round");
+        for (const chunk of round)
+            yield chunk;
+    }
+}
+const log = {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+};
+function tool(name = "read") {
+    return {
+        type: "function",
+        function: {
+            name,
+            description: `${name} tool`,
+            parameters: {
+                type: "object",
+                properties: { path: { type: "string" } },
+            },
+        },
+    };
+}
+function runtimePorts(overrides = {}) {
+    return {
+        createContentReplacementState: () => ({}),
+        enforceToolResultBudget: async (messages) => ({ messages, newlyReplacedCount: 0 }),
+        getActiveContextCompressionEngine: () => null,
+        compressMessages: (messages) => ({ messages, droppedCount: 0, strategy: "none" }),
+        getBudgetContinuationMessage: (usagePct) => `Continue; ${Math.round(usagePct)}% budget used.`,
+        createStreamingToolExecutor: (config) => new StreamingToolExecutor(config),
+        resolveToolEligibility: (tools) => ({ eligibleTools: tools, blockedTools: [] }),
+        ...overrides,
+    };
+}
+async function collect(events) {
+    const out = [];
+    for await (const event of events)
+        out.push(event);
+    return out;
+}
+describe("executeToolLoop architecture contract", () => {
+    it("executes an LLM tool call through runtime ports and feeds the result into the next round", async () => {
+        const transport = new ScriptedTransport([
+            [
+                { type: "tool_call_delta", index: 0, id: "call-read", name: "read", arguments: "{\"path\":\"README.md\"}" },
+                { type: "done", finishReason: "tool_calls" },
+            ],
+            [
+                { type: "delta", text: "README says hello." },
+                { type: "usage", promptTokens: 10, completionTokens: 4 },
+                { type: "done", finishReason: "stop" },
+            ],
+        ]);
+        const invoker = {
+            invoke: vi.fn(async (_turnId, name, args) => ({
+                result: `${name}(${JSON.parse(args).path}) => hello`,
+            })),
+        };
+        const events = await collect(executeToolLoop({
+            turnId: "turn-1",
+            sessionId: "session-1",
+            messages: [{ role: "user", content: "Read README.md" }],
+            tools: [tool("read")],
+            model: "test-model",
+            apiKey: "test-key",
+            maxRounds: 3,
+            runtimePorts: runtimePorts(),
+        }, transport, invoker, log));
+        expect(invoker.invoke).toHaveBeenCalledWith("turn-1", "read", "{\"path\":\"README.md\"}", expect.any(AbortSignal));
+        expect(events.map((event) => event.type)).toEqual([
+            "tool_call",
+            "tool_result",
+            "delta",
+            "end",
+        ]);
+        expect(events.find((event) => event.type === "end")).toMatchObject({
+            content: "README says hello.",
+            usage: { inputTokens: 10, outputTokens: 4 },
+        });
+        expect(transport.requests).toHaveLength(2);
+        expect(transport.requests[1]?.messages.some((message) => message.role === "tool" && "tool_call_id" in message && message.tool_call_id === "call-read")).toBe(true);
+    });
+    it("does not stream or carry assistant preambles from tool-call rounds", async () => {
+        const transport = new ScriptedTransport([
+            [
+                { type: "delta", text: "I will search first. " },
+                { type: "tool_call_delta", index: 0, id: "call-search", name: "web_search", arguments: "{\"query\":\"Shanghai family trip\"}" },
+                { type: "done", finishReason: "tool_calls" },
+            ],
+            [
+                { type: "delta", text: "Here is the final answer." },
+                { type: "done", finishReason: "stop" },
+            ],
+        ]);
+        const invoker = {
+            invoke: vi.fn(async () => ({ result: "No results found for: \"Shanghai family trip\"" })),
+        };
+        const events = await collect(executeToolLoop({
+            turnId: "turn-preamble",
+            sessionId: "session-1",
+            messages: [{ role: "user", content: "Plan Shanghai with kids" }],
+            tools: [tool("web_search")],
+            model: "test-model",
+            apiKey: "test-key",
+            maxRounds: 3,
+            runtimePorts: runtimePorts(),
+        }, transport, invoker, log));
+        expect(events.filter((event) => event.type === "delta").map((event) => event.text).join("")).toBe("Here is the final answer.");
+        expect(transport.requests[1]?.messages).toContainEqual(expect.objectContaining({
+            role: "assistant",
+            content: null,
+            tool_calls: expect.any(Array),
+        }));
+        expect(events.find((event) => event.type === "end")).toMatchObject({
+            content: "Here is the final answer.",
+        });
+    });
+    it("treats empty web_search results as failures and blocks repeated search variants", async () => {
+        const transport = new ScriptedTransport([
+            [
+                { type: "tool_call_delta", index: 0, id: "call-search-1", name: "web_search", arguments: "{\"query\":\"Shanghai family trip 2026\"}" },
+                { type: "done", finishReason: "tool_calls" },
+            ],
+            [
+                { type: "tool_call_delta", index: 0, id: "call-search-2", name: "web_search", arguments: "{\"query\":\"Shanghai kids attractions 2026\"}" },
+                { type: "done", finishReason: "tool_calls" },
+            ],
+            [
+                { type: "tool_call_delta", index: 0, id: "call-search-3", name: "web_search", arguments: "{\"query\":\"Shanghai family itinerary 2026\"}" },
+                { type: "done", finishReason: "tool_calls" },
+            ],
+            [
+                { type: "delta", text: "Search did not return usable results; here is a general answer." },
+                { type: "done", finishReason: "stop" },
+            ],
+        ]);
+        const invoker = {
+            invoke: vi.fn(async (_turnId, _name, args) => ({
+                result: `No results found for: "${JSON.parse(args).query}"`,
+            })),
+        };
+        const events = await collect(executeToolLoop({
+            turnId: "turn-web-empty",
+            sessionId: "session-1",
+            messages: [{ role: "user", content: "Plan Shanghai with kids" }],
+            tools: [tool("web_search")],
+            model: "test-model",
+            apiKey: "test-key",
+            maxRounds: 5,
+            runtimePorts: runtimePorts(),
+        }, transport, invoker, log));
+        expect(invoker.invoke).toHaveBeenCalledTimes(2);
+        expect(events).toContainEqual(expect.objectContaining({
+            type: "tool_result",
+            callId: "call-search-3",
+            ok: false,
+        }));
+        expect(events.find((event) => event.type === "end")).toMatchObject({
+            content: "Search did not return usable results; here is a general answer.",
+        });
+    });
+    it("emits policy-blocked tools before falling back to a single no-tool LLM round", async () => {
+        const transport = new ScriptedTransport([
+            [
+                { type: "delta", text: "I cannot write files in this policy." },
+                { type: "done", finishReason: "stop" },
+            ],
+        ]);
+        const invoker = { invoke: vi.fn() };
+        const events = await collect(executeToolLoop({
+            turnId: "turn-2",
+            sessionId: "session-1",
+            messages: [{ role: "user", content: "Write a file" }],
+            tools: [tool("write")],
+            model: "test-model",
+            apiKey: "test-key",
+            runtimePorts: runtimePorts({
+                resolveToolEligibility: () => ({
+                    eligibleTools: [],
+                    blockedTools: [{ toolName: "write" }],
+                }),
+            }),
+        }, transport, invoker, log));
+        expect(invoker.invoke).not.toHaveBeenCalled();
+        expect(events[0]).toMatchObject({
+            type: "tool_blocked",
+            name: "write",
+            reason: "blocked-by-policy",
+        });
+        expect(transport.requests[0]).not.toHaveProperty("tools");
+        expect(transport.requests[0]).not.toHaveProperty("toolChoice");
+    });
+    it("does not pass assistantId into tool eligibility or change the offered tool set", async () => {
+        const transport = new ScriptedTransport([
+            [
+                { type: "delta", text: "Ready." },
+                { type: "done", finishReason: "stop" },
+            ],
+        ]);
+        const resolveToolEligibility = vi.fn((tools, context) => ({
+            eligibleTools: tools,
+            blockedTools: [],
+            approvalRequiredTools: [],
+            eligibilityByName: new Map(),
+            context,
+        }));
+        const events = await collect(executeToolLoop({
+            turnId: "turn-assistant",
+            sessionId: "session-1",
+            messages: [{ role: "user", content: "Read README.md" }],
+            tools: [tool("read")],
+            model: "test-model",
+            apiKey: "test-key",
+            assistantId: "builtin.code",
+            runtimePorts: runtimePorts({ resolveToolEligibility }),
+        }, transport, { invoke: vi.fn() }, log));
+        expect(resolveToolEligibility).toHaveBeenCalledWith([tool("read")], undefined);
+        expect(events.some((event) => event.type === "tool_blocked")).toBe(false);
+        expect(transport.requests[0]?.tools?.map((entry) => entry.function.name)).toEqual(["read"]);
+    });
+    it("surfaces a silently closed LLM stream instead of ending with an empty answer", async () => {
+        const transport = new ScriptedTransport([[]]);
+        const events = await collect(executeToolLoop({
+            turnId: "turn-empty-stream",
+            sessionId: "session-1",
+            messages: [{ role: "user", content: "Say hi" }],
+            tools: [],
+            model: "test-model",
+            apiKey: "test-key",
+            runtimePorts: runtimePorts(),
+        }, transport, { invoke: vi.fn() }, log));
+        expect(events).toHaveLength(1);
+        expect(events[0]).toMatchObject({
+            type: "error",
+            code: "RETRYABLE_TRANSIENT",
+        });
+        expect(events[0].error).toMatch(/stream closed before a terminal event/i);
+    });
+});