@qvac/harness 0.1.0 → 0.1.1

package/dist-lib/lib/capabilities/completion.js

@@ -0,0 +1,1077 @@
+import process from 'process';
+import { contextCandidates } from "../context-window.js";
+import { errorCode, errorMessage } from "../error-fields.js";
+import { bufferBurst } from "../helpers/buffer-burst.js";
+import { endsTurn, stopAtControlToken, stripControlTokens, truncateAtControlToken } from "../helpers/control-tokens.js";
+import { createMarkupStreamFilter } from "../helpers/markup-stream-filter.js";
+import { AbortedError, raceAbort } from "../helpers/race-abort.js";
+import { createRunOutcomeTracker, degenerateAnswer, unnamedWrites, writeReport } from "../helpers/run-outcome.js";
+import { splitThinking } from "../helpers/thinking.js";
+import { clipRawCall, normalizeToolArgs, recoverMarkupToolCalls, recoverPrintedSkillLoad, recoverSkillNamedCall, stripToolCallMarkup, stripToolResponseBlocks, toolCallMarkup } from "../helpers/tool-call-markup.js";
+import { INTENT_PARAM, INTENT_PARAM_DESCRIPTION, takeToolIntent } from "../helpers/tool-intent.js";
+import { HookPipeline } from "../hooks/pipeline.js";
+import { fallbackToolLabel } from "../helpers/tool-label.js";
+import { hlog } from "../log.js";
+import { resolveLlmGenerationParams } from "../models/llm-presets.js";
+import { customToolDialect } from "../models/model-catalog.js";
+import { isContextOverflowError, isSdkModelWedgedError } from "../models/sdk-faults.js";
+import { annotateLastUserTime, skillsPromptSection, systemPromptParts } from "../prompt.js";
+import { isMetadataMethod } from "../tools/mcp/utils.js";
+import { unquoteArg } from "../tools/model-args.js";
+import { SKILL_TOOL_NAME, WEB_SEARCH_TOOL_NAME } from "./tool-names.js";
+import { promptUsageParts, usageBreakdown } from "./usage-breakdown.js";
+import { collectToolGrants, enabledTools, isSelected, skillIsActive, skillsAreSelected } from "./tool-selection.js";
+import { guardToolCall } from "../tools/outbound-guard.js";
+import { isAvailableState } from "../tools/skills/skill-state-constants.js";
+import { resolveImplicitSkill, resolveSkillMention, skillPreloadMessage } from "../tools/skills/mention.js";
+import { permittedTools } from "../tools/toolsets.js";
+import { promptPrefixHash } from "./prompt-prefix.js";
+import { DIRECT_CALL_ID, loadedSkillFilesFrom, loadedSkillsFrom, TOOL_CONTINUATION_NUDGE, toolResultTurn, withoutSkillLoadTurns } from "./tool-turns.js";
+import { projectVisionHistory, visionHistoryCacheKey } from "./vision-history.js";
+export function imageSettingsFrom(agent) {
+    if (!agent)
+        return undefined;
+    const settings = {};
+    if (agent.imageModelChoice)
+        settings.modelChoice = agent.imageModelChoice;
+    if (agent.imageSteps)
+        settings.steps = agent.imageSteps;
+    if (agent.imageWidth)
+        settings.width = agent.imageWidth;
+    if (agent.imageHeight)
+        settings.height = agent.imageHeight;
+    return Object.keys(settings).length ? settings : undefined;
+}
+const BURST_WINDOW_MS = 100;
+const MAX_TOOL_ROUNDS = 10;
+const RUN_WALL_CLOCK_BUDGET_MS = 30 * 60_000;
+function runWallClockBudgetMs() {
+    const ms = Number(process.env.QVAC_RUN_BUDGET_MS);
+    return ms > 0 ? ms : RUN_WALL_CLOCK_BUDGET_MS;
+}
+const CONTEXT_OVERFLOW_MESSAGE = 'This message is too large for the model context window.';
+const MAX_MUTE_ROUNDS = 1;
+const NARRATED_INTENT = /\b(I['’]ll|I will|Now I|Let me(?! know)|Next,? I)\b[^.!?]*[.!?]?\s*$/i;
+const MAX_WEB_SEARCHES_PER_TURN = 3;
+const MAX_CAPPED_ROUNDS = 1;
+const WEB_SEARCH_LIMIT_MESSAGE = 'Web search limit reached for this question. Answer now from the results already gathered. ' +
+    'If something was not found, say so plainly and mention the most relevant sources. ' +
+    'Do not call web_search again.';
+export function trustedSourcesFrom(history) {
+    const sources = [];
+    for (const entry of history) {
+        const text = String(entry.content ?? '');
+        if (entry.role === 'user')
+            sources.push({ origin: 'user', text });
+        else if (entry.role === 'tool')
+            sources.push({ origin: originOfToolTurn(text), text });
+    }
+    return sources;
+}
+function originOfToolTurn(text) {
+    return text.startsWith(`[Tool: ${SKILL_TOOL_NAME} (`) ? 'skill' : 'tool-result';
+}
+const noop = () => { };
+function intentParameters(tool) {
+    if (tool.autoApprove === true || INTENT_PARAM in tool.parameters.properties) {
+        return tool.parameters;
+    }
+    return {
+        ...tool.parameters,
+        properties: {
+            [INTENT_PARAM]: { type: 'string', description: INTENT_PARAM_DESCRIPTION },
+            ...tool.parameters.properties
+        },
+        required: [INTENT_PARAM, ...(tool.parameters.required ?? [])]
+    };
+}
+export function toSdkTool(tool) {
+    return {
+        type: 'function',
+        name: tool.name,
+        description: tool.description,
+        parameters: intentParameters(tool)
+    };
+}
+function sanitizeTurn(turn) {
+    const stripped = stripControlTokens(turn.content);
+    const content = turn.role === 'assistant' ? stripToolCallMarkup(stripped) : stripped;
+    return content === turn.content ? turn : { ...turn, content };
+}
+function lastUserContent(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const turn = messages[i];
+        if (turn?.role === 'user')
+            return turn.content;
+    }
+    return '';
+}
+function lastUserImages(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const turn = messages[i];
+        if (turn?.role === 'user')
+            return turn.attachments ?? [];
+    }
+    return [];
+}
+function explicitWebSearchQuery(text, tools, { skillPreloaded }) {
+    if (!tools.some((tool) => tool.name === WEB_SEARCH_TOOL_NAME))
+        return null;
+    if (explicitlyDisablesWebSearch(text))
+        return null;
+    const named = /\b(?:search|browse|look\s+up|find)\s+(?:the\s+)?(?:web|internet|online)\b/i.test(text);
+    const freshness = /\b(?:latest|current|recent)\s+(?:news|events)\b/i.test(text) ||
+        /\bwhat(?:'s|\s+is)\s+(?:the\s+)?(?:latest|current|recent)\b/i.test(text);
+    const explicit = named || (freshness && !skillPreloaded);
+    return explicit && text.trim() ? text.trim() : null;
+}
+function explicitlyDisablesWebSearch(text) {
+    return (/\b(?:do\s+not|don't|dont|never)\s+(?:search|browse|look\s+up|find|use)\s+(?:the\s+)?(?:web|internet|online)\b/i.test(text) ||
+        /\b(?:avoid|without)\s+(?:searching|browsing|using)\s+(?:the\s+)?(?:web|internet|online)\b/i.test(text));
+}
+function directToolHistory(history, args, output) {
+    return [
+        ...history,
+        {
+            role: 'assistant',
+            content: toolCallMarkup([{ name: WEB_SEARCH_TOOL_NAME, arguments: args }])
+        },
+        { role: 'tool', content: toolResultTurn(WEB_SEARCH_TOOL_NAME, DIRECT_CALL_ID, output) }
+    ];
+}
+function assistantToolTurn(contentText, calls) {
+    if (!calls.length || contentText.includes('<function='))
+        return contentText;
+    const markup = toolCallMarkup(calls);
+    return contentText ? `${contentText}\n${markup}` : markup;
+}
+function preloadLastUser(messages, name, body) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const turn = messages[i];
+        if (turn?.role !== 'user')
+            continue;
+        const next = [...messages];
+        next[i] = { ...turn, content: skillPreloadMessage(turn.content, name, body) };
+        return next;
+    }
+    return messages;
+}
+function collectStats(state, stats) {
+    if (!stats)
+        return;
+    if (state.ttft === undefined && stats.timeToFirstToken)
+        state.ttft = stats.timeToFirstToken;
+    if (state.promptTokensPerSecond === undefined && stats.promptTokensPerSecond) {
+        state.promptTokensPerSecond = stats.promptTokensPerSecond;
+    }
+    if (stats.generatedTokens) {
+        state.tokens += stats.generatedTokens;
+        if (stats.tokensPerSecond) {
+            state.durationMs += (stats.generatedTokens / stats.tokensPerSecond) * 1000;
+            state.timedTokens += stats.generatedTokens;
+        }
+    }
+    if (stats.promptTokens)
+        state.promptTokens = stats.promptTokens;
+    if (stats.cacheTokens)
+        state.cacheTokens = stats.cacheTokens;
+}
+function metricsEvent(state, usage) {
+    if (!state.tokens)
+        return null;
+    return {
+        type: 'metrics',
+        totalTokens: state.tokens,
+        durationMs: Math.round(state.durationMs),
+        timeToFirstToken: state.ttft,
+        promptTokensPerSecond: state.promptTokensPerSecond,
+        tokensPerSecond: state.durationMs > 0 ? (state.timedTokens / state.durationMs) * 1000 : undefined,
+        promptTokens: state.promptTokens,
+        cacheTokens: state.cacheTokens,
+        ...(state.ctxSize ? { ctxSize: state.ctxSize } : {}),
+        ...(state.backends.length ? { backends: state.backends } : {}),
+        ...(usage ? { usage } : {})
+    };
+}
+const TOOL_DENIED_MESSAGE = 'The user declined this call. Do not retry it or call it with different arguments to get ' +
+    'around the refusal. Tell the user plainly what you could not do, and never present a ' +
+    'result you did not obtain.';
+function deniedResult() {
+    return { error: TOOL_DENIED_MESSAGE, denied: true };
+}
+function denialKey(name, args) {
+    try {
+        return `${name}:${JSON.stringify(args)}`;
+    }
+    catch {
+        return name;
+    }
+}
+function terminalCall(result, outcome, options) {
+    return { result, outcome, executed: options.executed };
+}
+function executedCall(result, outcome) {
+    return terminalCall(result, outcome, { executed: true });
+}
+function guidanceResult(message) {
+    return terminalCall({ error: message, guidance: true }, { kind: 'guidance', message }, {
+        executed: false
+    });
+}
+function blockedResult(result, reason) {
+    return terminalCall(result, { kind: 'blocked', reason }, { executed: false });
+}
+function deniedCall() {
+    return terminalCall(deniedResult(), { kind: 'denied', reason: TOOL_DENIED_MESSAGE }, {
+        executed: false
+    });
+}
+async function executeCall(tool, args, ctx, { approve, signal, denied, sources = [], effect: classified, skipApprovals, onToolActivity, intent, display }) {
+    const validationError = tool.validate?.(args, ctx);
+    if (validationError) {
+        hlog('tool rejected: arguments failed validation', { tool: tool.name });
+        return guidanceResult(validationError);
+    }
+    const refusal = guardToolCall(tool.name, args, sources, {
+        externalWrite: tool.externalWrite === true
+    });
+    if (refusal) {
+        hlog('tool refused: unverifiable value in payload', { tool: tool.name });
+        onToolActivity?.({
+            type: 'tool-activity',
+            name: tool.name,
+            args,
+            resource: tool.resource?.(args) ?? null,
+            effect: tool.effect(args, ctx),
+            decision: 'blocked'
+        });
+        return blockedResult({ error: refusal, guidance: true }, refusal);
+    }
+    const key = denialKey(tool.name, args);
+    if (denied?.has(key)) {
+        hlog('tool denied already, not asking again', { tool: tool.name });
+        return deniedCall();
+    }
+    const effect = classified ?? tool.effect(args, ctx);
+    const resource = tool.resource?.(args) ?? null;
+    const autoRun = effect === 'read' || tool.autoApprove === true || skipApprovals === true;
+    hlog('tool decision', {
+        tool: tool.name,
+        effect,
+        auto: autoRun,
+        asks: Boolean(approve)
+    });
+    const approved = autoRun ||
+        (approve
+            ? await raceAbort(approve({
+                name: tool.name,
+                arguments: args,
+                resource,
+                effect,
+                intent: intent ?? null,
+                display: display ?? null
+            }), signal)
+            : false);
+    hlog(`tool ${approved ? 'approved' : 'denied'}`, { tool: tool.name });
+    const decision = tool.autoApprove === true || effect === 'read'
+        ? 'auto'
+        : skipApprovals === true
+            ? 'skip-all'
+            : approved
+                ? 'allowed'
+                : 'denied';
+    onToolActivity?.({
+        type: 'tool-activity',
+        name: tool.name,
+        args,
+        resource,
+        effect,
+        decision
+    });
+    if (!approved) {
+        denied?.add(key);
+        return deniedCall();
+    }
+    let output;
+    let outcome = { kind: 'success' };
+    try {
+        output = await tool.execute(args, { ...ctx, signal });
+        hlog('tool done', { tool: tool.name });
+    }
+    catch (err) {
+        const message = errorMessage(err);
+        hlog('tool failed', { tool: tool.name, err: message });
+        output = { error: message, code: errorCode(err) };
+        outcome = { kind: 'error', message, error: err };
+    }
+    return executedCall(output, outcome);
+}
+function runToolContext(scope) {
+    const { agent, attach, fetchAttachment, ragSearch, progress, askUser, signal, runBudget } = scope;
+    const image = imageSettingsFrom(agent);
+    return (turnImages = [], ctxSize) => ({
+        agentId: agent?.id ?? null,
+        ctxSize,
+        ...(image ? { image } : {}),
+        ...(turnImages.length ? { turnImages } : {}),
+        ...(attach ? { attach } : {}),
+        ...(fetchAttachment ? { fetchAttachment } : {}),
+        ...(ragSearch ? { ragSearch } : {}),
+        ...(progress ? { progress } : {}),
+        ...(askUser ? { askUser } : {}),
+        ...(signal ? { signal } : {}),
+        ...(runBudget ? { runBudget } : {})
+    });
+}
+function labelOf(name, args, emoji) {
+    const display = { label: fallbackToolLabel(name, args) };
+    return emoji ? { ...display, iconEmoji: emoji } : display;
+}
+async function settleToolCall(pipeline, execution, call) {
+    const folded = await pipeline.runPostToolFold({
+        toolName: call.name,
+        agentId: call.agentId,
+        args: call.args,
+        effect: call.effect ?? 'write',
+        resource: call.resource,
+        toolset: call.tool?.toolset,
+        result: execution.result,
+        outcome: execution.outcome,
+        executed: execution.executed
+    });
+    return {
+        result: folded.result,
+        outcome: folded.outcome ?? execution.outcome
+    };
+}
+function skillInContext(entry) {
+    return entry.status === undefined || isAvailableState(entry.status);
+}
+function unreadySkillState(name, catalog) {
+    const status = catalog.find((entry) => entry.name === name)?.status;
+    return status !== undefined && !isAvailableState(status) ? status : null;
+}
+function blockedSkillMessage(name, catalog, listShown) {
+    if (catalog.some((entry) => entry.name === name)) {
+        return (`skill "${name}" is not enabled for this agent. Do not rebuild what it does with another ` +
+            `tool — answer from what you already have, or tell the user to enable it in Skills.`);
+    }
+    return listShown
+        ? `there is no skill named "${name}". Load one from the skills list you were shown, or ` +
+            `answer from what you already have — do not guess another name.`
+        : `there is no skill named "${name}". You were not shown a skills list, which means no ` +
+            `skill is available this turn — do not guess another name, and answer from what you ` +
+            `already have.`;
+}
+async function resolveToolCalls(toolCalls, enabled, agentId, pipeline, skillNames, signal) {
+    const resolved = [];
+    for (const call of toolCalls) {
+        if (signal?.aborted)
+            throw new AbortedError();
+        const tool = enabled.find((t) => t.name === call.name);
+        if (!tool) {
+            const { args } = takeToolIntent(call.arguments);
+            resolved.push({
+                call,
+                args,
+                ...(call.raw === undefined ? {} : { rawCall: clipRawCall(call.raw) })
+            });
+            continue;
+        }
+        const taken = takeToolIntent(call.arguments);
+        const args = normalizeToolArgs(taken.args, Object.keys(tool.parameters.properties));
+        const { intent } = taken;
+        const fold = await pipeline.runPreToolFold({
+            toolName: tool.name,
+            args,
+            agentId,
+            skillNames,
+            parameters: tool.parameters,
+            signal
+        });
+        resolved.push(fold.ok
+            ? {
+                call,
+                tool,
+                args: fold.args,
+                ...(call.raw === undefined ? {} : { rawCall: clipRawCall(call.raw) }),
+                ...(intent ? { intent } : {})
+            }
+            : {
+                call,
+                tool,
+                args,
+                rejection: fold.rejection,
+                ...(call.raw === undefined ? {} : { rawCall: clipRawCall(call.raw) }),
+                ...(intent ? { intent } : {})
+            });
+    }
+    return resolved;
+}
+function unprovenReplay(state, final) {
+    if (!state.unproven)
+        return null;
+    if (state.stopToken)
+        return endsTurn(state.stopToken) ? state.unproven : null;
+    if (final.stopReason === 'length' || final.stopReason === 'cancelled')
+        return null;
+    return state.unproven;
+}
+async function* runRoundTokens(sdk, result, state, signal, startInThink = false) {
+    const cancelThisRound = () => {
+        if (result.requestId)
+            sdk.cancel?.({ requestId: result.requestId });
+    };
+    signal?.addEventListener('abort', cancelThisRound, { once: true });
+    const tokens = stopAtControlToken(result.tokenStream, (token) => {
+        state.stopToken = token;
+    });
+    let tokenEvents = 0;
+    const events = splitThinking(bufferBurst(tokens, BURST_WINDOW_MS), { startInThink });
+    const thinkingFilter = createMarkupStreamFilter();
+    const contentFilter = createMarkupStreamFilter();
+    try {
+        while (true) {
+            const next = await events.next();
+            if (next.done) {
+                state.unproven = next.value;
+                const thinkingTail = thinkingFilter.flush();
+                if (thinkingTail)
+                    yield { type: 'thinking', text: thinkingTail };
+                const contentTail = contentFilter.flush();
+                if (contentTail)
+                    yield { type: 'content', text: contentTail };
+                break;
+            }
+            if (signal?.aborted)
+                throw new AbortedError();
+            tokenEvents++;
+            if (next.value.type === 'content')
+                state.rawContentText += next.value.text;
+            const filter = next.value.type === 'thinking' ? thinkingFilter : contentFilter;
+            const text = filter.push(next.value.text);
+            if (text)
+                yield { type: next.value.type, text };
+        }
+        hlog('stream ended', { events: tokenEvents, stopToken: state.stopToken });
+        if (state.stopToken)
+            cancelThisRound();
+    }
+    finally {
+        signal?.removeEventListener('abort', cancelThisRound);
+        await events.return(null);
+    }
+}
+const TRUNCATED_FINAL_MS = 2000;
+function truncatedFinal(final, contentText) {
+    const accepted = { contentText, toolCalls: [], raw: { fullText: contentText } };
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(accepted), TRUNCATED_FINAL_MS);
+    });
+    const guarded = final.catch((err) => {
+        if (isSdkModelWedgedError(err))
+            throw err;
+        return accepted;
+    });
+    guarded.catch(noop);
+    return Promise.race([guarded, expired]).finally(() => clearTimeout(timer));
+}
+async function* runRecoveredRound(sdk, args) {
+    const lease = args.acquireRound ? await args.acquireRound() : null;
+    try {
+        return yield* runRecoveredRoundWith(sdk, args, lease?.modelId ?? args.modelId);
+    }
+    finally {
+        lease?.release();
+    }
+}
+async function* runRecoveredRoundWith(sdk, args, modelId) {
+    let lastOverflow = null;
+    for (const candidate of contextCandidates(args.history)) {
+        if (args.signal?.aborted)
+            throw new AbortedError();
+        let contentText = '';
+        let emitted = false;
+        const state = { stopToken: null, unproven: null, rawContentText: '' };
+        const cacheable = candidate.history === args.history;
+        try {
+            const result = sdk.completion({
+                modelId,
+                history: projectVisionHistory(candidate.history),
+                stream: true,
+                tools: args.tools,
+                generationParams: args.generationParams,
+                ...(args.responseFormat ? { responseFormat: args.responseFormat } : {}),
+                toolDialect: args.toolDialect,
+                ...(cacheable && args.cacheKey ? { kvCache: args.cacheKey } : {})
+            });
+            result.final.catch(noop);
+            const startInThink = args.generationParams?.reasoning_budget === -1;
+            for await (const event of runRoundTokens(sdk, result, state, args.signal, startInThink)) {
+                if (event.type === 'content')
+                    contentText += event.text;
+                emitted = true;
+                yield event;
+            }
+            const final = state.stopToken
+                ? await truncatedFinal(result.final, state.rawContentText)
+                : await raceAbort(result.final, args.signal);
+            const replay = unprovenReplay(state, final);
+            hlog('final', {
+                stopReason: final.stopReason,
+                toolCalls: final.toolCalls?.length ?? 0,
+                stopToken: state.stopToken,
+                replay: replay !== null
+            });
+            return {
+                contentText,
+                final,
+                history: candidate.history,
+                cacheable,
+                unproven: state.unproven,
+                replay
+            };
+        }
+        catch (err) {
+            if (!isContextOverflowError(err))
+                throw err;
+            if (emitted)
+                throw new Error(CONTEXT_OVERFLOW_MESSAGE, { cause: err });
+            lastOverflow = err;
+        }
+    }
+    if (lastOverflow)
+        throw new Error(CONTEXT_OVERFLOW_MESSAGE, { cause: lastOverflow });
+    throw new Error('context recovery produced no completion candidate');
+}
+function* reportUnnamedWrites(said, landed) {
+    const unreported = writeReport(unnamedWrites(said, landed));
+    if (unreported)
+        yield { type: 'content', text: unreported };
+}
+export async function* completion(sdk, { modelId, acquireRound, model, agent, ctxSize, cacheKey, thinkingDefault, generationParams: generationParamsOverride, responseFormat, messages: storedMessages, tools: allTools = [], skillCatalog = [], approve, attach, fetchAttachment, ragSearch, progress, askUser, signal, toolConfigs, fsRoots = [], fsWriteRoots = [] }) {
+    const pipeline = new HookPipeline();
+    const agentId = agent?.id ?? null;
+    const tools = permittedTools(allTools, agent?.disabledToolsets);
+    const writableRoots = [
+        ...fsWriteRoots,
+        ...fsRoots.filter((root) => root.kind === 'hyper' && root.writable && !fsWriteRoots.includes(root))
+    ];
+    const messages = storedMessages.map(sanitizeTurn);
+    const stats = { tokens: 0, timedTokens: 0, durationMs: 0, ctxSize, backends: [] };
+    let runOutcome = 'abandoned';
+    let runError;
+    const runOutcomes = createRunOutcomeTracker();
+    const landed = runOutcomes.confirmedWrites;
+    try {
+        if (signal?.aborted)
+            throw new AbortedError();
+        await pipeline.onRunStart({ agentId, messages });
+        const runBudget = {
+            deadlineMs: Date.now() + runWallClockBudgetMs(),
+            outputBytesUsed: 0
+        };
+        const toolContext = runToolContext({
+            agent,
+            attach,
+            fetchAttachment,
+            ragSearch,
+            progress,
+            askUser,
+            signal,
+            runBudget
+        });
+        const turnImages = lastUserImages(messages);
+        const toolsSelected = isSelected(agent?.toolsScope, agent?.enabledTools);
+        const skillsSelected = skillsAreSelected(agent?.skillsScope, Boolean(agent));
+        const inContextSkills = skillCatalog.filter(skillInContext);
+        const mention = resolveSkillMention(lastUserContent(messages), inContextSkills);
+        const loadedSkills = loadedSkillsFrom(messages);
+        const loadedSkillFiles = loadedSkillFilesFrom(messages);
+        const activation = {
+            skillsSelected,
+            enabledSkills: agent?.enabledSkills ?? [],
+            mention: mention?.name ?? null,
+            loadedSkills
+        };
+        const activeSkills = inContextSkills.filter((skill) => skillIsActive(skill.name, activation));
+        const { grantedNames, grantedOwners, grantedOps } = collectToolGrants(activeSkills);
+        const enabled = responseFormat
+            ? []
+            : enabledTools(tools, {
+                toolsSelected,
+                allowlist: agent?.enabledTools ?? [],
+                grantedNames,
+                grantedOwners,
+                hasRoots: fsRoots.length > 0,
+                hasWriteRoots: writableRoots.length > 0,
+                hasActiveSkills: activeSkills.length > 0
+            });
+        const sdkTools = enabled.length ? enabled.map((tool) => toSdkTool(tool)) : undefined;
+        const reasoningEnabled = agent?.reasoning === 'enabled' ? true : agent?.reasoning === 'disabled' ? false : undefined;
+        const deviceReasoning = thinkingDefault === 'enabled' ? true : thinkingDefault === 'disabled' ? false : undefined;
+        const resolvedGenerationParams = resolveLlmGenerationParams(model, reasoningEnabled, deviceReasoning);
+        const generationParams = generationParamsOverride
+            ? { ...resolvedGenerationParams, ...generationParamsOverride }
+            : resolvedGenerationParams;
+        const loadedThisTurn = new Set();
+        let skillIcon = null;
+        const skillEmoji = (name) => skillCatalog.find((entry) => entry.name === name)?.emoji ?? null;
+        const nudgedSkills = new Set();
+        const toolDialect = model ? customToolDialect(model) : undefined;
+        let turns = messages;
+        let preloadedSkill = null;
+        let stubDropped = false;
+        const preload = mention ?? resolveImplicitSkill(lastUserContent(messages), activeSkills);
+        if (preload) {
+            const loader = tools.find((tool) => tool.name === SKILL_TOOL_NAME);
+            const loaded = loader ? await loader.execute({ name: preload.name }, toolContext()) : null;
+            if (loaded && typeof loaded === 'object' && 'content' in loaded) {
+                preloadedSkill = String(loaded.content);
+                const inlined = preloadLastUser(messages, preload.name, preloadedSkill);
+                turns = withoutSkillLoadTurns(inlined, preload.name);
+                stubDropped = turns.length < inlined.length;
+                if (!loadedSkills.has(preload.name)) {
+                    const preloadArgs = { name: preload.name };
+                    const preloadEffect = 'read';
+                    const preloadResource = loader?.resource?.(preloadArgs) ?? null;
+                    yield {
+                        type: 'tool-call',
+                        name: SKILL_TOOL_NAME,
+                        args: preloadArgs,
+                        effect: preloadEffect,
+                        display: labelOf(SKILL_TOOL_NAME, preloadArgs, skillEmoji(preload.name))
+                    };
+                    yield {
+                        type: 'tool-activity',
+                        name: SKILL_TOOL_NAME,
+                        args: { name: preload.name },
+                        resource: null,
+                        effect: 'read',
+                        decision: 'auto'
+                    };
+                    const settled = await settleToolCall(pipeline, executedCall(loaded, { kind: 'success' }), {
+                        agentId,
+                        tool: loader,
+                        name: SKILL_TOOL_NAME,
+                        args: preloadArgs,
+                        effect: preloadEffect,
+                        resource: preloadResource
+                    });
+                    yield {
+                        type: 'tool-result',
+                        name: SKILL_TOOL_NAME,
+                        result: settled.result
+                    };
+                }
+            }
+        }
+        if (preload && preloadedSkill) {
+            loadedSkills.add(preload.name);
+            loadedThisTurn.add(preload.name);
+            skillIcon = skillEmoji(preload.name) ?? skillIcon;
+        }
+        const system = systemPromptParts({
+            bio: agent?.bio,
+            toolNames: enabled.map((tool) => tool.name),
+            skillsSection: skillsPromptSection(activeSkills)
+        });
+        const systemContent = system.text;
+        const promptPrefix = promptPrefixHash({ system: systemContent, tools: sdkTools });
+        const promptParts = promptUsageParts({ system, toolSchemas: sdkTools });
+        let history = annotateLastUserTime(systemContent ? [{ role: 'system', content: systemContent }, ...turns] : turns);
+        let roundCacheKey = stubDropped ? undefined : visionHistoryCacheKey(cacheKey, history);
+        const runUsage = () => usageBreakdown(promptParts, stats.cacheTokens, model);
+        const denied = new Set();
+        let webSearches = 0;
+        const sources = trustedSourcesFrom(messages);
+        if (preloadedSkill)
+            sources.push({ origin: 'skill', text: preloadedSkill });
+        const query = explicitWebSearchQuery(lastUserContent(messages), enabled, {
+            skillPreloaded: preloadedSkill !== null
+        });
+        const webSearch = enabled.find((tool) => tool.name === WEB_SEARCH_TOOL_NAME);
+        if (query && webSearch) {
+            runOutcomes.beginRound();
+            const fold = await pipeline.runPreToolFold({
+                toolName: webSearch.name,
+                args: { query },
+                agentId: agent?.id ?? null,
+                signal
+            });
+            const args = fold.ok ? fold.args : { query };
+            const searchEffect = webSearch.effect(args);
+            const searchResource = webSearch.resource?.(args) ?? null;
+            const searchCallDisplay = labelOf(webSearch.name, args, null);
+            if (signal?.aborted)
+                throw new AbortedError();
+            yield {
+                type: 'tool-call',
+                name: webSearch.name,
+                args,
+                effect: searchEffect,
+                display: searchCallDisplay
+            };
+            let activity = null;
+            const execution = fold.ok
+                ? await executeCall(webSearch, args, toolContext(turnImages, ctxSize), {
+                    approve,
+                    signal,
+                    denied,
+                    skipApprovals: agent?.approvalMode === 'skip-all',
+                    display: searchCallDisplay,
+                    onToolActivity: (a) => (activity = a)
+                })
+                : terminalCall(fold.rejection, { kind: 'guidance', message: fold.rejection.error }, {
+                    executed: false
+                });
+            const settled = await settleToolCall(pipeline, execution, {
+                agentId,
+                tool: webSearch,
+                name: webSearch.name,
+                args,
+                effect: searchEffect,
+                resource: searchResource
+            });
+            const output = settled.result;
+            const executionOutcome = settled.outcome;
+            runOutcomes.record(output, executionOutcome);
+            runOutcomes.finishRound();
+            if (fold.ok)
+                webSearches++;
+            if (!activity && !fold.ok) {
+                activity = {
+                    type: 'tool-activity',
+                    name: webSearch.name,
+                    args,
+                    resource: searchResource,
+                    effect: searchEffect,
+                    decision: 'blocked'
+                };
+            }
+            if (activity)
+                yield activity;
+            yield {
+                type: 'tool-result',
+                name: webSearch.name,
+                result: output
+            };
+            history = directToolHistory(history, args, output);
+        }
+        let outcome = 'exhausted';
+        let said = '';
+        let mute = 0;
+        let narrated = false;
+        let cappedRounds = 0;
+        for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+            if (signal?.aborted)
+                throw new AbortedError();
+            if (Date.now() >= runBudget.deadlineMs) {
+                outcome = 'time-capped';
+                break;
+            }
+            hlog('round start', {
+                round,
+                turns: history.length,
+                tools: sdkTools?.length ?? 0,
+                promptPrefix
+            });
+            const roundStarted = Date.now();
+            const recovered = yield* runRecoveredRound(sdk, {
+                modelId,
+                acquireRound,
+                history,
+                tools: sdkTools,
+                generationParams,
+                responseFormat,
+                toolDialect,
+                cacheKey: roundCacheKey,
+                signal
+            });
+            const final = recovered.final;
+            if (!recovered.cacheable)
+                roundCacheKey = undefined;
+            history = recovered.history;
+            collectStats(stats, final.stats);
+            hlog('round stats', { round, wallMs: Date.now() - roundStarted, ...(final.stats ?? {}) });
+            const markup = stripToolResponseBlocks(truncateAtControlToken(final.raw.fullText) || recovered.unproven || '');
+            let toolCalls = final.toolCalls?.length
+                ? final.toolCalls
+                : recoverMarkupToolCalls(markup, enabled);
+            if (!toolCalls.length && enabled.some((tool) => tool.name === SKILL_TOOL_NAME)) {
+                const rescued = recoverPrintedSkillLoad(markup, SKILL_TOOL_NAME);
+                const rescuedArgs = rescued[0]?.arguments;
+                const alreadyLoaded = rescuedArgs !== undefined &&
+                    (loadedSkillFiles.get(unquoteArg(rescuedArgs.name))?.has(unquoteArg(rescuedArgs.file)) ??
+                        false);
+                if (!alreadyLoaded)
+                    toolCalls = rescued;
+                if (toolCalls.length)
+                    hlog('recovered printed skill load', { round });
+            }
+            if (!toolCalls.length && enabled.some((tool) => tool.name === SKILL_TOOL_NAME)) {
+                toolCalls = recoverSkillNamedCall(markup, inContextSkills
+                    .filter((skill) => !nudgedSkills.has(skill.name))
+                    .map((skill) => skill.name), SKILL_TOOL_NAME);
+                for (const call of toolCalls)
+                    nudgedSkills.add(unquoteArg(call.arguments.name));
+                if (toolCalls.length)
+                    hlog('recovered skill-named call', { round });
+            }
+            if (!toolCalls.length) {
+                const replay = recovered.replay ? stripToolCallMarkup(recovered.replay) : '';
+                if (replay)
+                    yield { type: 'content', text: replay };
+                const spoken = recovered.contentText.trim();
+                if (enabled.length && !narrated && !replay && NARRATED_INTENT.test(spoken)) {
+                    hlog('round narrated a tool call instead of making it', { round });
+                    narrated = true;
+                    history = [
+                        ...history,
+                        { role: 'assistant', content: spoken },
+                        { role: 'user', content: TOOL_CONTINUATION_NUDGE }
+                    ];
+                    continue;
+                }
+                if (replay || spoken) {
+                    said = `${recovered.contentText}\n${replay}`;
+                    outcome = 'answered';
+                    break;
+                }
+                hlog('round produced no answer', { round, mute });
+                if (mute++ < MAX_MUTE_ROUNDS)
+                    continue;
+                outcome = 'mute';
+                break;
+            }
+            mute = 0;
+            narrated = false;
+            const resolved = await resolveToolCalls(toolCalls, enabled, agent?.id ?? null, pipeline, inContextSkills.map((skill) => skill.name), signal);
+            if (signal?.aborted)
+                throw new AbortedError();
+            history = [
+                ...history,
+                {
+                    role: 'assistant',
+                    content: assistantToolTurn(recovered.contentText, resolved.map(({ call, args }) => ({ name: call.name, arguments: args })))
+                }
+            ];
+            let cappedCalls = 0;
+            runOutcomes.beginRound();
+            for (const { call, tool, args, rawCall, rejection, intent } of resolved) {
+                if (signal?.aborted)
+                    throw new AbortedError();
+                const searchCapped = tool?.name === WEB_SEARCH_TOOL_NAME && webSearches >= MAX_WEB_SEARCHES_PER_TURN;
+                const callCtx = {
+                    ...toolContext(turnImages, ctxSize),
+                    skills: [...loadedSkills].filter((name) => !skillsSelected ||
+                        (agent?.enabledSkills ?? []).includes(name) ||
+                        name === mention?.name),
+                    settings: toolConfigs?.[call.name],
+                    toolOps: grantedOps,
+                    fsRoots,
+                    fsWriteRoots: writableRoots,
+                    reportBackend: (use) => stats.backends.push(use)
+                };
+                const skillCall = call.name === SKILL_TOOL_NAME;
+                const effect = tool?.effect(args, callCtx) ?? (skillCall ? 'read' : undefined);
+                const resource = tool?.resource?.(args) ?? null;
+                const skillName = unquoteArg(args?.name ?? args?.skill_name ?? args?.skill);
+                const skillReloaded = tool?.name === SKILL_TOOL_NAME && !args?.file && loadedThisTurn.has(skillName);
+                const silent = searchCapped || skillReloaded;
+                const display = silent
+                    ? undefined
+                    : labelOf(call.name, args, skillCall ? skillEmoji(skillName) : skillIcon);
+                if (!silent) {
+                    yield { type: 'tool-call', name: call.name, args, rawCall, effect, display };
+                }
+                const unreadyState = skillCall ? unreadySkillState(skillName, skillCatalog) : null;
+                const skillBlocked = skillCall && !unreadyState && (!tool || !skillIsActive(skillName, activation));
+                let activity = null;
+                const blockedReason = blockedSkillMessage(skillName, skillCatalog, activeSkills.length > 0);
+                const unreadyReason = `skill "${skillName}" is ${unreadyState ?? 'unavailable'} and cannot be used yet. ` +
+                    `Tell the user to open it in Skills and finish its setup; do not retry.`;
+                let execution;
+                if (skillReloaded) {
+                    execution = terminalCall({
+                        name: skillName,
+                        content: `${skillName} is already loaded. Follow the instructions you were given and do not load it again.`
+                    }, { kind: 'guidance', message: `${skillName} is already loaded.` }, { executed: false });
+                }
+                else if (skillBlocked) {
+                    execution = blockedResult({ error: blockedReason }, blockedReason);
+                }
+                else if (unreadyState) {
+                    execution = blockedResult({ error: unreadyReason }, unreadyReason);
+                }
+                else if (searchCapped) {
+                    execution = terminalCall({ content: WEB_SEARCH_LIMIT_MESSAGE }, { kind: 'success' }, { executed: false });
+                }
+                else if (rejection) {
+                    execution = terminalCall(rejection, { kind: 'guidance', message: rejection.error }, {
+                        executed: false
+                    });
+                }
+                else if (tool) {
+                    execution = await executeCall(tool, args, callCtx, {
+                        approve,
+                        signal,
+                        denied,
+                        sources,
+                        effect,
+                        skipApprovals: agent?.approvalMode === 'skip-all',
+                        intent,
+                        display,
+                        onToolActivity: (event) => {
+                            activity = event;
+                        }
+                    });
+                }
+                else {
+                    execution = blockedResult({ error: `unknown tool: ${call.name}` }, `unknown tool: ${call.name}`);
+                }
+                const settled = await settleToolCall(pipeline, execution, {
+                    agentId,
+                    tool,
+                    name: call.name,
+                    args,
+                    effect,
+                    resource
+                });
+                const output = settled.result;
+                const executionOutcome = settled.outcome;
+                runOutcomes.record(output, executionOutcome);
+                if (searchCapped) {
+                    cappedCalls++;
+                    hlog('web_search capped', { searches: webSearches });
+                }
+                else if (tool?.name === WEB_SEARCH_TOOL_NAME && !rejection)
+                    webSearches++;
+                if (call.name === SKILL_TOOL_NAME &&
+                    output &&
+                    typeof output === 'object' &&
+                    'content' in output) {
+                    loadedSkills.add(skillName);
+                    if ('file' in output && typeof output.file === 'string') {
+                        const files = loadedSkillFiles.get(skillName) ?? new Set();
+                        files.add(output.file);
+                        loadedSkillFiles.set(skillName, files);
+                    }
+                    else {
+                        loadedThisTurn.add(skillName);
+                    }
+                    skillIcon = skillEmoji(skillName) ?? skillIcon;
+                }
+                if (!activity &&
+                    !silent &&
+                    (skillBlocked || Boolean(unreadyState) || Boolean(rejection) || !tool)) {
+                    activity = {
+                        type: 'tool-activity',
+                        name: call.name,
+                        args,
+                        resource,
+                        effect: effect ?? 'write',
+                        decision: 'blocked'
+                    };
+                }
+                if (activity)
+                    yield activity;
+                if (!silent) {
+                    yield {
+                        type: 'tool-result',
+                        name: call.name,
+                        result: output
+                    };
+                }
+                const isCompiledOperation = tool?.compiled === true;
+                const isMutation = effect === 'write' &&
+                    ((tool?.toolset === 'mcp-call' && !isMetadataMethod(args.method)) ||
+                        (isCompiledOperation && tool?.toolset === 'http-request'));
+                if (isMutation && executionOutcome.kind === 'success') {
+                    runOutcomes.confirmWrite(output);
+                }
+                const turn = toolResultTurn(call.name, call.id, output);
+                sources.push({
+                    origin: call.name === SKILL_TOOL_NAME ? 'skill' : 'tool-result',
+                    text: turn
+                });
+                history.push({ role: 'tool', content: turn });
+            }
+            runOutcomes.finishRound();
+            history.push({ role: 'user', content: TOOL_CONTINUATION_NUDGE });
+            if (cappedCalls === resolved.length) {
+                if (cappedRounds++ >= MAX_CAPPED_ROUNDS) {
+                    outcome = 'search-capped';
+                    break;
+                }
+            }
+            else {
+                cappedRounds = 0;
+            }
+        }
+        if (outcome === 'answered') {
+            yield* reportUnnamedWrites(said, landed);
+            const answered = metricsEvent(stats, runUsage());
+            runOutcome = 'done';
+            if (answered)
+                yield answered;
+            return;
+        }
+        if (signal?.aborted)
+            throw new AbortedError();
+        const recovered = yield* runRecoveredRound(sdk, {
+            modelId,
+            acquireRound,
+            history,
+            tools: undefined,
+            generationParams,
+            cacheKey: roundCacheKey,
+            signal
+        });
+        collectStats(stats, recovered.final.stats);
+        const answer = recovered.replay ? stripToolCallMarkup(recovered.replay) : '';
+        if (answer)
+            yield { type: 'content', text: answer };
+        said = `${recovered.contentText}\n${answer}`;
+        if (!said.trim()) {
+            hlog('degenerate wrap-up', { outcome });
+            yield {
+                type: 'content',
+                text: degenerateAnswer(outcome, history, runOutcomes.facts())
+            };
+        }
+        else {
+            yield* reportUnnamedWrites(said, landed);
+        }
+        const metrics = metricsEvent(stats, runUsage());
+        runOutcome = 'done';
+        if (metrics)
+            yield metrics;
+    }
+    catch (err) {
+        const written = writeReport(landed);
+        if (written)
+            yield { type: 'content', text: written };
+        if (err instanceof AbortedError) {
+            runOutcome = 'aborted';
+            yield { type: 'aborted' };
+            return;
+        }
+        runOutcome = 'error';
+        runError = err;
+        throw err;
+    }
+    finally {
+        await pipeline.onRunEnd({
+            agentId: agent?.id ?? null,
+            stats: {
+                totalTokens: stats.tokens,
+                durationMs: Math.round(stats.durationMs),
+                timeToFirstToken: stats.ttft
+            },
+            outcome: runOutcome,
+            error: runError
+        });
+    }
+}