flashlite 0.0.0-stage → 0.1.1

package/dist/loop.js

@@ -0,0 +1,442 @@
+// loop.ts — the agent round driver: stream a turn, run tool calls with the permission
+// gate, feed results back, repeat. Dialect-agnostic: it only speaks ChatRequest /
+// AssistantTurn / StreamEvent and an injectable tool executor.
+import { dialectFor } from "./client.js";
+import { effectiveOutputTokens } from "./effort.js";
+import { boundReplay, DEFAULT_TOOL_RESULT_BUDGET_BYTES } from "./contextbudget.js";
+import { checkBudget, estimateTotal } from "./token.js";
+import { recoverLeakedToolCalls } from "./sanitize.js";
+import { createToolCache } from "./toolcache.js";
+function abortError() {
+    return new DOMException('The operation was aborted', 'AbortError');
+}
+function denialResult(call) {
+    return { toolCallId: call.id, content: JSON.stringify({ error: 'Tool call denied by user' }), isError: true };
+}
+function budgetTexts(system, history, tools) {
+    const texts = [system];
+    for (const m of history) {
+        texts.push(m.content);
+        if (m.reasoningContent)
+            texts.push(m.reasoningContent);
+        for (const c of m.toolCalls ?? [])
+            texts.push(c.name + c.argumentsJson);
+        for (const block of m.thinkingBlocks ?? [])
+            texts.push(JSON.stringify(block));
+    }
+    for (const t of tools)
+        texts.push(t.name + t.description + JSON.stringify(t.parameters));
+    return texts;
+}
+export const TOOL_WORKER_CONCURRENCY = 4;
+const MAX_COMPACTION_ATTEMPTS = 3;
+/** Never send unmatched tool blocks, even when loading an older interrupted session. */
+function validToolHistory(history) {
+    let pending = new Set();
+    for (const message of history) {
+        if (message.role === 'tool') {
+            if (!message.toolCallId || !pending.delete(message.toolCallId))
+                return false;
+            continue;
+        }
+        if (pending.size)
+            return false;
+        const calls = message.toolCalls ?? [];
+        if (calls.length && message.role !== 'assistant')
+            return false;
+        for (const call of calls) {
+            if (!call.id.trim() || pending.has(call.id))
+                return false;
+            pending.add(call.id);
+        }
+    }
+    return pending.size === 0;
+}
+function validArguments(call) {
+    if (call.argumentsInvalid)
+        return false;
+    try {
+        const parsed = JSON.parse(call.argumentsJson);
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed);
+    }
+    catch {
+        return false;
+    }
+}
+export async function runAgentTurn(opts) {
+    const dialect = dialectFor(opts.model);
+    const outputReserve = effectiveOutputTokens(dialect, opts.maxTokens, opts.effort);
+    const toolByDef = new Map(opts.tools.map((t) => [t.name, t]));
+    let approveAll = opts.autoApprove;
+    let rounds = 0;
+    let finishSynced = false;
+    let warned80 = false;
+    let warned95 = false;
+    let exactFailed = false;
+    let compactionAttempts = 0;
+    let lastCompactionSize;
+    let recountCompaction = false;
+    let usage;
+    const checkpoint = (reason, calls) => ({
+        stopReason: reason, usage, rounds,
+        interruption: { reason, resumable: true, ...(calls?.length ? { discardedToolCalls: calls } : {}) },
+    });
+    const progress = (phase, call, note) => {
+        // Presentation/logging failures cannot strand committed calls without results.
+        try {
+            opts.onToolProgress?.(phase, call, note, rounds);
+        }
+        catch { /* advisory */ }
+    };
+    const applySteering = () => {
+        const messages = opts.takeSteering?.() ?? [];
+        opts.history.push(...messages);
+        return messages.length > 0;
+    };
+    const MAX_RECOVERY_RESUMES = 3;
+    // Corrupt or unusable provider responses are recoverable: nudge the model to re-issue
+    // instead of dead-ending the turn. Bounded, so a model stuck emitting garbage cannot
+    // spin forever — this does not cap normal turns, only recovery retries.
+    let recoveryResumes = 0;
+    const resumeAfterFailure = (note) => {
+        if (recoveryResumes >= MAX_RECOVERY_RESUMES)
+            return false;
+        recoveryResumes += 1;
+        opts.history.push({ role: 'user', content: note });
+        return true;
+    };
+    const CORRUPT_PROPOSAL_NOTE = 'Your previous tool call was malformed or corrupted and could not be executed. Re-issue it as one well-formed tool call with valid arguments.';
+    const UNUSABLE_RESPONSE_NOTE = 'Your previous response could not be used because it ended unexpectedly. Continue from where you left off.';
+    const toolCache = createToolCache();
+    while (true) {
+        if (opts.signal.aborted)
+            throw abortError();
+        applySteering();
+        if (!validToolHistory(opts.history))
+            return checkpoint('invalid_tool_calls');
+        opts.history.push(...(opts.takeBackground?.() ?? []));
+        const tools = opts.tools;
+        const system = opts.system;
+        const messages = boundReplay(opts.history, opts.toolResultBudgetBytes ?? DEFAULT_TOOL_RESULT_BUDGET_BYTES, opts.elidedResults, { assistantProse: opts.elideAssistantProse });
+        if (opts.contextTokens) {
+            const texts = budgetTexts(system, messages, tools);
+            // Rough fallback only: image tokens vary by provider/resolution, not base64 length.
+            const imageAllowance = messages.reduce((total, m) => total + (m.role === 'user' ? m.images?.length ?? 0 : 0), 0) * 2048;
+            let total = estimateTotal(texts) + imageAllowance + messages.length * 16 + 32;
+            // Exact counting is a separate network round trip. Far from the limit, a
+            // deliberately conservative 2x margin makes the local estimate sufficient.
+            // Count exactly again near the window before compaction or rejection.
+            const needsExactCount = !opts.fastContextCount || (total + outputReserve) * 2 >= opts.contextTokens;
+            if (opts.countTokens && !exactFailed && needsExactCount) {
+                try {
+                    total = await opts.countTokens(opts.model, system, messages, tools, opts.signal);
+                    if (!Number.isFinite(total) || total < 0)
+                        throw new Error('invalid token count');
+                }
+                catch {
+                    if (opts.signal.aborted)
+                        throw abortError();
+                    exactFailed = true; // fall back to the estimate, never retry per turn
+                    total = estimateTotal(texts) + imageAllowance + messages.length * 16 + 32;
+                }
+            }
+            const budget = checkBudget(total, opts.contextTokens);
+            opts.onContextUsage?.(total, opts.contextTokens);
+            // Include provider thinking/output floors, not merely the requested ceiling.
+            const overfull = total + outputReserve > opts.contextTokens;
+            const remainingPercent = Math.max(0, 100 - (total + outputReserve) / opts.contextTokens * 100);
+            if (recountCompaction) {
+                lastCompactionSize = total;
+                recountCompaction = false;
+            }
+            const meaningfulGrowth = lastCompactionSize === undefined ||
+                total >= lastCompactionSize + Math.max(256, Math.ceil(lastCompactionSize * 0.1));
+            if (compactionAttempts < MAX_COMPACTION_ATTEMPTS && meaningfulGrowth &&
+                (opts.autoCompactRemainingPercent ?? 0) > 0 &&
+                remainingPercent <= opts.autoCompactRemainingPercent && opts.compact) {
+                compactionAttempts++;
+                lastCompactionSize = total;
+                let compacted = false;
+                try {
+                    compacted = await opts.compact(opts.history);
+                }
+                catch {
+                    if (opts.signal.aborted)
+                        throw abortError();
+                    // Summary transport/provider failure must not authorize an overfull request.
+                }
+                if (compacted) {
+                    recountCompaction = true;
+                    continue; // re-count before any request; no retry until meaningful new growth
+                }
+            }
+            if (budget.warn95 && !warned95) {
+                warned95 = true;
+                warned80 = true;
+                opts.onBudget?.(95);
+            }
+            else if (budget.warn80 && !warned80) {
+                warned80 = true;
+                opts.onBudget?.(80);
+            }
+            if (overfull)
+                return checkpoint('context_limit');
+        }
+        const req = {
+            model: opts.model,
+            dialect,
+            messages: [...messages], // snapshot — history grows as the round completes
+            system,
+            tools,
+            stream: true,
+            maxTokens: opts.maxTokens,
+            effort: opts.effort,
+        };
+        let streamedText = '';
+        let turn;
+        try {
+            opts.onModelRequest?.();
+            turn = await opts.client.chat(req, (event) => {
+                if (event.kind === 'text')
+                    streamedText += event.text;
+                opts.onEvent(event);
+            }, opts.signal);
+        }
+        catch (error) {
+            // A failed stream may have visible prose, but never a complete tool proposal.
+            if (streamedText)
+                opts.history.push({ role: 'assistant', content: streamedText });
+            throw error;
+        }
+        if (turn.usage) {
+            const cachedInputTokens = (usage?.cachedInputTokens ?? 0) + (turn.usage.cachedInputTokens ?? 0);
+            const anyCached = usage?.cachedInputTokens !== undefined || turn.usage.cachedInputTokens !== undefined;
+            usage = {
+                inputTokens: (usage?.inputTokens ?? 0) + turn.usage.inputTokens,
+                outputTokens: (usage?.outputTokens ?? 0) + turn.usage.outputTokens,
+                ...(anyCached ? { cachedInputTokens } : {}),
+            };
+        }
+        // Routers proxying a model with a different chat template sometimes leak the
+        // native tool-call markup into the text instead of structured tool_calls; recover
+        // it so the turn does not dead-end. Truncated/unknown turns keep the existing
+        // resume path — never execute proposals the provider did not cleanly finish.
+        const leaked = recoverLeakedToolCalls(turn.message);
+        if (leaked.stripped && turn.stopReason === 'stop') {
+            if (leaked.calls.length)
+                turn.stopReason = 'tool_calls';
+            else if (!turn.message.content)
+                turn.stopReason = 'unknown';
+        }
+        const calls = turn.message.toolCalls ?? [];
+        const seenIds = new Set(); // IDs need only disambiguate this contiguous batch.
+        const badIds = calls.some((call) => {
+            if (!call.id.trim() || seenIds.has(call.id))
+                return true;
+            seenIds.add(call.id);
+            return false;
+        });
+        const incomplete = turn.stopReason !== 'tool_calls';
+        const invalidProposal = badIds || (turn.stopReason === 'tool_calls' && calls.length === 0);
+        if ((calls.length && incomplete) || invalidProposal) {
+            // Keep prose only; detached signed thinking/tool blocks are not replayable.
+            if (turn.message.content)
+                opts.history.push({ role: 'assistant', content: turn.message.content });
+            if (opts.signal.aborted)
+                throw abortError();
+            // Truncation by the output limit is not a failure: the prose is already retained, so
+            // resume the turn instead of ending it, letting the model finish and re-issue the tool
+            // calls that were dropped for being incomplete.
+            if (!invalidProposal && turn.stopReason === 'length' && turn.message.content) {
+                continue;
+            }
+            // A corrupt proposal (bad/duplicate ids, or a tool_calls finish with no calls) is
+            // recoverable: have the model re-issue rather than ending the turn here.
+            if (invalidProposal && resumeAfterFailure(CORRUPT_PROPOSAL_NOTE))
+                continue;
+            return checkpoint(invalidProposal ? 'invalid_tool_calls' :
+                turn.stopReason === 'length' ? 'length' : 'unknown', calls);
+        }
+        // A truncated reasoning block may have no valid signature yet.
+        if (turn.stopReason === 'length' || turn.stopReason === 'unknown') {
+            if (turn.message.content)
+                opts.history.push({ role: 'assistant', content: turn.message.content });
+        }
+        else
+            opts.history.push(turn.message);
+        if (turn.stopReason !== 'tool_calls') {
+            if (opts.signal.aborted)
+                throw abortError();
+            if (turn.stopReason === 'length') {
+                // No valid tool calls in the truncated response, but a cut-off final answer can
+                // still be resumed so the model finishes instead of being guillotined.
+                if (turn.message?.content)
+                    continue;
+                return checkpoint('length');
+            }
+            if (turn.stopReason === 'unknown') {
+                if (resumeAfterFailure(UNUSABLE_RESPONSE_NOTE))
+                    continue;
+                return checkpoint('unknown');
+            }
+            if (turn.stopReason === 'stop' && applySteering())
+                continue;
+            if (turn.stopReason === 'stop') {
+                const reports = opts.takeBackground?.() ?? [];
+                if (reports.length) {
+                    opts.history.push(...reports);
+                    continue;
+                }
+            }
+            if (turn.stopReason === 'stop' && !finishSynced && opts.beforeFinish) {
+                finishSynced = true;
+                const messages = await opts.beforeFinish();
+                if (opts.signal.aborted)
+                    throw abortError();
+                if (messages.length) {
+                    opts.history.push(...messages);
+                    continue;
+                }
+            }
+            return { stopReason: turn.stopReason, usage, rounds };
+        }
+        if (opts.maxRounds !== undefined && rounds >= opts.maxRounds) {
+            // The proposal was cleanly completed, but none of these calls are authorized or
+            // recorded. Keep only its prose and require an explicit continuation.
+            opts.history.pop();
+            if (turn.message.content)
+                opts.history.push({ role: 'assistant', content: turn.message.content });
+            return checkpoint('invalid_tool_calls', calls);
+        }
+        rounds++;
+        // File approve-all never authorizes an always-scoped terminal command.
+        const denied = new Set();
+        const cancelled = (call) => ({
+            toolCallId: call.id, content: JSON.stringify({ error: 'Tool call cancelled before execution' }), isError: true,
+        });
+        // Resolve argument validity and read-only cache hits up front (pure lookups). The
+        // permission gate stays just-in-time: nothing here prompts or executes.
+        const precomputed = new Array(calls.length);
+        for (const [i, call] of calls.entries()) {
+            if (opts.signal.aborted) {
+                precomputed[i] = cancelled(call);
+                continue;
+            }
+            if (!validArguments(call)) {
+                precomputed[i] = { toolCallId: call.id, content: 'invalid tool arguments', isError: true };
+                continue;
+            }
+            // An identical read-only call already answered in an earlier round is reused rather
+            // than re-run; nothing new to approve, so it also skips the permission prompt.
+            const cached = toolCache.lookup(call.name, call.arguments);
+            if (cached !== undefined)
+                precomputed[i] = { toolCallId: call.id, content: cached, isError: false };
+        }
+        // Approvals are just-in-time: each call is authorized immediately before it runs, so a
+        // tool may start while later calls still wait. A single lock serializes the prompt
+        // (one modal at a time) while preserving the batch's call order.
+        let approvalLock = Promise.resolve();
+        const authorize = (call) => {
+            const def = toolByDef.get(call.name);
+            const always = def?.approvalScope === 'always';
+            if (!def?.requiresApproval)
+                return Promise.resolve({});
+            const task = approvalLock.then(async () => {
+                if (opts.signal.aborted)
+                    return { result: cancelled(call) };
+                // File approve-all covers implicit file grants only, never an always-scoped command.
+                if (!always && (opts.fileApproval?.() ?? approveAll)) {
+                    return { grant: { generation: opts.fileApprovalGeneration?.() } };
+                }
+                let answer;
+                try {
+                    answer = await opts.ask(call);
+                }
+                catch (err) {
+                    return { result: opts.signal.aborted ? cancelled(call) : {
+                            toolCallId: call.id, content: err instanceof Error ? err.message : 'tool approval failed', isError: true,
+                        } };
+                }
+                if (opts.signal.aborted)
+                    return { result: cancelled(call) };
+                if (always ? answer !== 'yes' : answer === 'no')
+                    return { result: denialResult(call), denied: true };
+                if (!always && answer === 'all') {
+                    approveAll = true;
+                    return { grant: { generation: opts.fileApprovalGeneration?.() } };
+                }
+                return {};
+            });
+            approvalLock = task.then(() => { }, () => { });
+            return task;
+        };
+        for (const call of calls)
+            if (!opts.signal.aborted)
+                progress('start', call);
+        const results = new Array(calls.length);
+        let nextCall = 0;
+        await Promise.all(Array.from({ length: Math.min(TOOL_WORKER_CONCURRENCY, calls.length) }, async () => {
+            while (nextCall < calls.length) {
+                const i = nextCall++;
+                const call = calls[i];
+                if (precomputed[i]) {
+                    results[i] = precomputed[i];
+                    continue;
+                }
+                if (opts.signal.aborted) {
+                    results[i] = cancelled(call);
+                    continue;
+                }
+                const approval = await authorize(call);
+                if (approval.result) {
+                    if (approval.denied)
+                        denied.add(i);
+                    results[i] = approval.result;
+                    continue;
+                }
+                if (opts.signal.aborted) {
+                    results[i] = cancelled(call);
+                    continue;
+                }
+                // Only implicit file-wide grants are revocable here. Explicit per-call yes and
+                // always-scoped command grants keep their separate host authorization semantics.
+                const fileGrant = approval.grant;
+                if (fileGrant && (!(opts.fileApproval?.() ?? approveAll) ||
+                    fileGrant.generation !== opts.fileApprovalGeneration?.())) {
+                    denied.add(i);
+                    results[i] = { toolCallId: call.id, content: JSON.stringify({ error: 'File approval revoked before execution; request approval again' }), isError: true };
+                    continue;
+                }
+                try {
+                    results[i] = await opts.execute(call, opts.signal);
+                }
+                catch (err) {
+                    results[i] = { toolCallId: call.id, content: err instanceof Error ? err.message : 'tool execution failed', isError: true };
+                }
+                // Remember read-only results for later identical calls; any mutating tool clears the cache.
+                toolCache.record(call.name, call.arguments, results[i].content, results[i].isError === true);
+            }
+        }));
+        // Pair every recorded call before propagating abort, including approval cancellation.
+        for (const [i, result] of results.entries()) {
+            const call = calls[i];
+            opts.history.push({
+                role: 'tool',
+                content: result.content,
+                toolCallId: call.id,
+                isError: result.isError,
+            });
+            try {
+                opts.onToolResult?.(call, result);
+            }
+            catch { /* presentation is advisory */ }
+            progress(denied.has(i) ? 'denied' : result.isError ? 'error' : 'done', call, result.isError ? result.content : undefined);
+        }
+        try {
+            opts.onToolBatchComplete?.();
+        }
+        catch { /* presentation is advisory */ }
+        if (opts.signal.aborted)
+            throw abortError();
+    }
+}