castle-web-cli 0.4.78 → 0.4.80

package/dist/native/loop.js

@@ -0,0 +1,698 @@
+// The native agent loop: runAgentNative(opts) is the Path-B counterpart to
+// agent.ts's runAgentCli -- same normalized hooks in, same CliRunResult-
+// shaped payload out (see native/types.ts for the exact field mapping this
+// implies once wired together). One call = one turn: build [system, user],
+// stream an assistant message, execute any tool_calls, append tool results,
+// repeat until the model replies with no tool_calls, the run times out, or
+// the iteration cap trips.
+//
+// Turns are stateless by design (mirrors agent.ts: a fresh prompt is
+// rebuilt every turn) -- the message array built here lives only for the
+// duration of this one call and is discarded when it resolves.
+//
+// Observability: when opts.logPath is set, every run appends structured
+// JSONL events (init/assistant/tool_result/eviction/retry/result -- see
+// createRunLogger) to the SAME file locations the CLI backends use for their
+// raw stream logs, so "check the logs" works identically across backends.
+import * as fs from "fs";
+import * as path from "path";
+import { streamChatCompletion, } from "./openrouter.js";
+import { toolSchemasForRole, executeTool, activityLabelForCall, } from "./tools.js";
+// Safety valve against a model that never stops calling tools -- distinct
+// from timeoutMs, which bounds wall-clock time regardless of iteration count.
+const MAX_ITERATIONS = 40;
+const TOUCHED_FILE_LIMIT = 10;
+function touchedFileList(files) {
+    const sorted = [...files].sort();
+    if (sorted.length <= TOUCHED_FILE_LIMIT)
+        return sorted;
+    return [...sorted.slice(0, TOUCHED_FILE_LIMIT), `+${sorted.length - TOUCHED_FILE_LIMIT} more`];
+}
+// playtest frames never hit the TOUCHED_FILE_LIMIT truncation above (a run
+// is capped at PLAYTEST_MAX_CALLS_PER_RUN calls x PLAYTEST_MAX_SHOTS frames
+// each -- at most 24 -- small enough to list in full for the task card).
+function playtestFrameList(frames) {
+    return [...frames].sort();
+}
+// -- run logging ----------------------------------------------------------------
+// Structured JSONL, one event per line, appended (task retry attempts share
+// one log.jsonl, same as the CLI backends). Bulky free-text fields (tool
+// args/results) are truncated to LOG_FIELD_CAP chars -- the log is for
+// diagnosing a bad run's shape, not replaying its full payloads. Assistant
+// message text is NOT truncated: it is the narrative the user saw and is
+// already bounded by the model's own output.
+const LOG_FIELD_CAP = 2_000;
+function truncateForLog(raw) {
+    if (raw.length <= LOG_FIELD_CAP)
+        return raw;
+    return `${raw.slice(0, LOG_FIELD_CAP)}... (+${raw.length - LOG_FIELD_CAP} chars)`;
+}
+// Best-effort by design: a logging hiccup (disk full, bad path) must cost the
+// log, never the run.
+function createRunLogger(logPath) {
+    if (!logPath)
+        return { write: () => { }, end: () => Promise.resolve() };
+    let stream = null;
+    try {
+        stream = fs.createWriteStream(logPath, { flags: "a" });
+        stream.on("error", () => {
+            stream = null;
+        });
+    }
+    catch {
+        stream = null;
+    }
+    return {
+        write(entry) {
+            try {
+                stream?.write(JSON.stringify({ at: new Date().toISOString(), ...entry }) + "\n");
+            }
+            catch {
+                /* never fail the run over logging */
+            }
+        },
+        end() {
+            return new Promise((resolve) => {
+                try {
+                    if (stream)
+                        stream.end(() => resolve());
+                    else
+                        resolve();
+                }
+                catch {
+                    resolve();
+                }
+            });
+        },
+    };
+}
+// -- image attachments ------------------------------------------------------------
+const ATTACHMENT_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+// The initial user message: plain string without attachments; with them, an
+// array of one text part + one image_url part per image (base64 data URI --
+// OpenRouter forwards data URIs to any provider). A missing/unreadable/
+// non-image attachment fails the RUN, loudly -- these files were saved by the
+// serve itself at enqueue, so a failure here is a real bug, and silently
+// dropping an image the user pasted would be worse than an error message.
+function buildUserContent(cwd, prompt, attachments) {
+    if (!attachments || attachments.length === 0)
+        return { content: prompt };
+    const parts = [{ type: "text", text: prompt }];
+    for (const rel of attachments) {
+        const mime = ATTACHMENT_MIME[path.extname(rel).toLowerCase()];
+        if (!mime) {
+            return { content: prompt, error: `attachment is not a supported image type: ${rel}` };
+        }
+        try {
+            const data = fs.readFileSync(path.resolve(cwd, rel));
+            parts.push({ type: "image_url", image_url: { url: `data:${mime};base64,${data.toString("base64")}` } });
+        }
+        catch (e) {
+            return {
+                content: prompt,
+                error: `could not read attachment ${rel}: ${e instanceof Error ? e.message : String(e)}`,
+            };
+        }
+    }
+    return { content: parts };
+}
+// -- context growth management -------------------------------------------------
+// A long task otherwise grows the message array until the model's context
+// limit kills the run mid-flight. Crude-but-effective policy, checked before
+// every request: approximate the transcript's token count (chars / 4), and
+// when it exceeds the budget, evict the OLDEST tool-result contents first --
+// each replaced by a short stub that keeps the tool_call_id pairing intact,
+// so no provider ever sees an orphaned/missing tool result. The synthetic
+// user messages carrying view_image results evict the same way (they are
+// tool payloads in all but role). Never evicted: the system message, the
+// INITIAL user prompt (with its attachments), assistant text/tool_calls,
+// the most recent KEEP_RECENT_TOOL_RESULTS results (the model's working
+// set), and already-stubbed entries. Deliberately conservative: if evicting every
+// eligible result still leaves us over budget, we proceed anyway and let the
+// provider be the final arbiter.
+//
+// Budget: 100k approx-tokens (400k chars) by default -- comfortably inside
+// every model we'd route (128k contexts and up) while leaving output
+// headroom. CASTLE_SMITH_CONTEXT_TOKENS overrides it (tests / bigger-context
+// models), same env-override pattern as CASTLE_OPENROUTER_URL; read per run,
+// not hoisted, for the same reason.
+const APPROX_CHARS_PER_TOKEN = 4;
+const DEFAULT_CONTEXT_TOKEN_BUDGET = 100_000;
+const KEEP_RECENT_TOOL_RESULTS = 4;
+// Flat per-image estimate: vision encoders bill roughly 1-2k tokens per
+// image regardless of file size, so counting base64 length like text would
+// wildly overshoot and evict the whole transcript for one screenshot.
+const IMAGE_PART_TOKEN_ESTIMATE = 1_500;
+const EVICTION_STUB_PREFIX = "[result evicted to save context: ";
+function contextTokenBudget() {
+    return Number(process.env.CASTLE_SMITH_CONTEXT_TOKENS) || DEFAULT_CONTEXT_TOKEN_BUDGET;
+}
+function approxMessageTokens(m) {
+    let chars = 0;
+    if (typeof m.content === "string")
+        chars += m.content.length;
+    let imageTokens = 0;
+    if (Array.isArray(m.content)) {
+        for (const part of m.content) {
+            if (part.type === "text")
+                chars += part.text.length;
+            else
+                imageTokens += IMAGE_PART_TOKEN_ESTIMATE;
+        }
+    }
+    for (const tc of m.tool_calls ?? []) {
+        chars += tc.function.name.length + tc.function.arguments.length;
+    }
+    // Small flat overhead per message for role/ids/JSON scaffolding.
+    return Math.ceil(chars / APPROX_CHARS_PER_TOKEN) + imageTokens + 8;
+}
+function approxTranscriptTokens(messages) {
+    return messages.reduce((sum, m) => sum + approxMessageTokens(m), 0);
+}
+// Mutates `messages` in place; returns what was evicted (for the run log).
+// `labels` maps tool_call_id -> a short human label ("read_file game.js")
+// recorded when the call executed. `imageLabels` marks the synthetic
+// user messages carrying view_image results (see runToolCalls) -- they are
+// tool-result payloads in all but role, so they evict exactly like text
+// results: the image_url part (the ~1,500-token payload) is dropped and the
+// message content becomes a text stub, keeping message order intact. The
+// last-KEEP_RECENT window is counted over BOTH kinds together, oldest first.
+function evictOldToolResults(messages, labels, imageLabels) {
+    const budget = contextTokenBudget();
+    if (approxTranscriptTokens(messages) <= budget)
+        return [];
+    const evictable = messages.filter((m) => (m.role === "tool" && typeof m.content === "string" && !m.content.startsWith(EVICTION_STUB_PREFIX)) ||
+        // An already-evicted image message has string content, so this array
+        // check also keeps it from being re-evicted.
+        (imageLabels.has(m) && Array.isArray(m.content)));
+    const evicted = [];
+    const cutoff = evictable.length - KEEP_RECENT_TOOL_RESULTS;
+    for (let i = 0; i < cutoff; i++) {
+        if (approxTranscriptTokens(messages) <= budget)
+            break;
+        const m = evictable[i];
+        const imageLabel = imageLabels.get(m);
+        if (imageLabel && Array.isArray(m.content)) {
+            // Weight ~= what leaves the request payload (the base64 URI).
+            const chars = m.content.reduce((sum, part) => sum + (part.type === "image_url" ? part.image_url.url.length : part.text.length), 0);
+            m.content = `${EVICTION_STUB_PREFIX}${imageLabel}, ${((chars * 0.75) / 1024).toFixed(1)}KB image]`;
+            evicted.push({ label: imageLabel, chars });
+        }
+        else {
+            const chars = m.content.length;
+            const label = labels.get(m.tool_call_id ?? "") ?? "tool result";
+            m.content = `${EVICTION_STUB_PREFIX}${label}, ${(chars / 1024).toFixed(1)}KB]`;
+            evicted.push({ label, chars });
+        }
+    }
+    return evicted;
+}
+// -- usage ----------------------------------------------------------------------
+// Per-run usage is the SUM over every request the tool loop made -- each
+// iteration re-sends the whole growing transcript, so summing is what makes
+// the run's numbers comparable to the cumulative usage the claude CLI
+// reports for a whole run (and makes cache_read growth across iterations
+// visible instead of hidden).
+function addUsage(total, next) {
+    if (!next)
+        return total;
+    if (!total)
+        return { ...next };
+    const out = { ...total };
+    for (const key of [
+        "input_tokens",
+        "output_tokens",
+        "cache_creation_input_tokens",
+        "cache_read_input_tokens",
+    ]) {
+        const v = next[key];
+        if (typeof v === "number")
+            out[key] = (out[key] ?? 0) + v;
+    }
+    return out;
+}
+// -- reasoning effort + output cap ----------------------------------------------
+// Motivating incident (2026-07, real run, google/gemini-3.5-flash, task
+// role): after a playtest tool result carrying 3 screenshot images, the
+// model silently generated for 4m51s before replying, with the run's total
+// output (67,601 tokens) dwarfing every visible assistant text summed
+// together (well under 10K) -- roughly 55-60K tokens of HIDDEN reasoning on
+// that one multimodal iteration, and the eventual reply began with
+// degenerate text. Usage was only logged once per whole run at the time, so
+// pinning the spiral to a single iteration took manual forensics (see the
+// per-iteration "usage" log event below, added for exactly this reason).
+//
+// Two independent guards against a repeat: cap how hard a model is allowed
+// to "think" per role (reasoning.effort), and cap how much any one
+// completion call can generate at all (max_tokens), so a model that ignores
+// the effort hint (or a provider that doesn't honor it) still can't run away
+// indefinitely.
+//
+// Per-role effort table, not a single global default, so tuning one role
+// (or adding a third) is a one-line change instead of a call-site hunt.
+// Router turns are short read-only planning/dispatch steps -- "medium" is
+// already generous for that. Task turns do the real problem-solving, but
+// give them the LOWER "low" effort specifically because they are the ones
+// that see playtest screenshots (the multimodal case that triggered the
+// incident above) -- "low" still lets a model reason, just not runaway.
+const REASONING_EFFORT = {
+    router: "medium",
+    task: "low",
+};
+// Hard per-completion-call output cap (OpenAI-shaped `max_tokens`, sent to
+// every request regardless of role). Reasoning tokens count against this on
+// most providers (see openrouter.ts's request-body comment), so this is the
+// backstop for a model that ignores REASONING_EFFORT entirely.
+//
+// Sized so it can NEVER clip a legitimate large file write delivered via a
+// tool-call's arguments: task agents write whole files up to ~16KB, which
+// is only ~4-5K tokens, and tool-call argument tokens count as regular
+// output (not reasoning) -- so even a multi-file batch in one turn stays
+// well under this cap. 16384 leaves generous headroom above that while still
+// bounding a runaway generation to well under a minute instead of ~5.
+const MAX_COMPLETION_TOKENS = 16_384;
+// Short system framing establishing tool-use expectations; the actual
+// persona/rules/deck context live in `opts.prompt` (the "user" message,
+// already built by buildRouterPrompt/buildTaskPrompt) exactly as they do for
+// the CLI backends today -- this loop does not duplicate them.
+const ROLE_FRAMING = {
+    router: [
+        "You are an autonomous coding agent running in a tool-calling loop.",
+        "You have READ-ONLY tools: read_file, list_files, grep, view_image. You cannot write, edit, or run commands.",
+        "If the instructions below require making a change, follow them exactly as written (e.g. dispatching a background task) rather than attempting the change yourself.",
+        // Smith-specific because it names the exact "== deck source ==" heading
+        // buildRouterPrompt (agent-prompts.ts) emits for its deckContents section
+        // -- cursor/claude never get that section (they read files with their
+        // own tools), so telling them to look for it would be pointing at
+        // nothing. Motivating incident: small/greenfield-deck router turns
+        // routinely re-read a file whose full contents were already inlined, or
+        // spent a whole turn on tool calls when the prompt already had every
+        // fact needed for a reply.
+        "If the prompt below has a \"== deck source ==\" section, those ARE the complete current contents of the deck's text files right now -- do not re-read those files with read_file or grep. If everything you need for your reply is already in the prompt (rules, deck source, transcript, task board), skip tool calls entirely and reply directly.",
+        "Reply with your final message text once you are done; do not narrate tool calls in that text.",
+    ].join(" "),
+    // The view_image nudge lives HERE (smith-only framing), not in the shared
+    // buildTaskPrompt text the CLI backends also see -- CLI agents view images
+    // with their own Read tool and naming a smith-specific tool there would
+    // misdirect them.
+    task: [
+        "You are an autonomous coding agent running in a tool-calling loop, with full tool access: read_file, write_file, edit_file, list_files, grep, bash, view_image, playtest, restart.",
+        "Use your tools to actually make the changes described below -- do not just describe what you would do.",
+        // Names the exact "Deck source" heading buildTaskPrompt (agent-prompts.ts)
+        // emits for its deckContents section -- smith-only, same as the router's
+        // equivalent nudge above, for the same reason (cursor/claude read files
+        // themselves and never see this section). Motivating incident: smith
+        // task agents re-reading a file whose full contents were already
+        // inlined at task start, paying a redundant tool round trip for
+        // something already sitting in context.
+        "If the prompt below has a \"Deck source\" section, those ARE the complete current contents of the deck's text files as of task start -- do not re-read those files with read_file before editing them, edit them directly. If the whole task is already satisfied by what's in the prompt, you may skip straight to editing/writing without a preliminary read.",
+        "If your task references an image file path (e.g. a user attachment under .castle/agent/attachments/), look at it with view_image before building.",
+        "After you change behavior or visuals, playtest the deck before reporting done -- SEE it running rather than trusting a read of the code (a frozen animation or a silently broken interaction reads fine as source but is obvious in a screenshot). Use actions when the task is specifically about interactivity (movement, input handling, collisions). If a playtest result warns the capture was starved (barely rendering), that is a capture failure, not proof the game is broken -- retry it once rather than concluding the game is broken from it.",
+        // The view_image nudge above and this one share the same reasoning for
+        // living HERE rather than in buildTaskPrompt's shared text: that text
+        // also renders for cursor/claude, whose tasks reload the deck by
+        // actually running `npm run restart` in a real shell (they have no
+        // native restart tool, and naming one there would misdirect them into
+        // hallucinating a tool call that doesn't exist for their backend).
+        "Prefer the restart tool over running `npm run restart` in bash -- it does the same reload in this same process, instantly, without spawning a node process just to send one message.",
+        "Work to completion, then reply with your final message text.",
+    ].join(" "),
+};
+function buildSystemMessage(opts) {
+    const parts = [ROLE_FRAMING[opts.role]];
+    if (opts.systemReminder)
+        parts.push(opts.systemReminder);
+    return parts.join("\n\n");
+}
+function parseToolArgs(raw) {
+    if (!raw || !raw.trim())
+        return { args: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        return { args: {}, error: `malformed tool-call arguments JSON: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { args: {}, error: "tool-call arguments must be a JSON object" };
+    }
+    return { args: parsed };
+}
+// Short "tool + primary arg" label used in eviction stubs and log lines,
+// e.g. "read_file game.js", "bash npm run restart".
+function toolCallLabel(name, args) {
+    const detail = typeof args.path === "string"
+        ? args.path
+        : typeof args.command === "string"
+            ? args.command.trim().split(/\s+/).slice(0, 4).join(" ")
+            : typeof args.pattern === "string"
+                ? args.pattern
+                : "";
+    return detail ? `${name} ${detail}` : name;
+}
+// Tools that must NOT run concurrently with anything else in their batch:
+// bash can have arbitrary side effects (start a server, install deps, run a
+// build another call depends on) and playtest ties up the serve's one shared
+// browser. restart must observe every write that came before it in the SAME
+// batch (models commonly emit "write_file A, write_file B, restart" in one
+// turn) and nothing after it should start before the reload it triggers --
+// without a barrier here it would run concurrently with its own batch's
+// writes, and only looks safe today because those writes happen to execute
+// synchronously ahead of it; an async write tool would let restart race the
+// very writes it's meant to reload. Every other tool call in the loop's set
+// (read/write/edit/list_files/grep/view_image) only touches the filesystem,
+// so distinct calls are safe to run at once -- see groupToolCalls below.
+const BARRIER_TOOLS = new Set(["bash", "playtest", "restart"]);
+// Splits one assistant turn's tool_calls into ordered groups: each maximal
+// run of non-barrier calls is one group (executed concurrently -- see
+// runToolCalls), and each barrier call gets its own singleton group (run
+// alone, blocking the group after it). Models commonly emit dependent
+// batches like "write fileA, write fileB, then bash to run them" -- the
+// writes are safe to parallelize, but nothing after the bash call should
+// start before it resolves, and the bash call itself shouldn't race the
+// writes it depends on.
+function groupToolCalls(toolCalls) {
+    const groups = [];
+    let current = [];
+    for (const call of toolCalls) {
+        if (BARRIER_TOOLS.has(call.function?.name ?? "")) {
+            if (current.length > 0)
+                groups.push(current);
+            current = [];
+            groups.push([call]);
+        }
+        else {
+            current.push(call);
+        }
+    }
+    if (current.length > 0)
+        groups.push(current);
+    return groups;
+}
+// Executes one tool call and reports its own activity label -- everything
+// error handling and result-shape wise is identical to the old sequential
+// loop; only the caller (runToolCalls) changed, to run several of these
+// concurrently within a group. Bookkeeping shared across calls (filesTouched,
+// the labels map, the log) is intentionally NOT touched in here -- the
+// caller applies it after Promise.all resolves, walking the group in its
+// ORIGINAL order, so concurrent completion order never affects what lands in
+// the message array or the log.
+async function runOneToolCall(call, role, ctx, onActivity) {
+    const name = call.function?.name ?? "";
+    const { args, error } = parseToolArgs(call.function?.arguments ?? "");
+    onActivity?.(error ? "Working" : activityLabelForCall(name, args));
+    const result = error ? { ok: false, output: `Error: ${error}` } : await executeTool(name, args, role, ctx);
+    // A richer completion label (e.g. playtest's frame/console summary),
+    // shown as its OWN feed line right before the generic activity clears. Two
+    // calls finishing close together can interleave these live labels -- a
+    // cosmetic race in the feed line, not in anything that reaches the model.
+    if (result.activitySummary)
+        onActivity?.(result.activitySummary);
+    onActivity?.(null);
+    return { call, name, args, result };
+}
+async function runToolCalls(toolCalls, role, ctx, filesTouched, playtestFrames, labels, imageLabels, log, onActivity) {
+    const results = [];
+    // Images a call produced this batch (view_image, playtest, ...). Delivered
+    // as synthetic role:"user" messages AFTER all the batch's tool results --
+    // role:"tool" content is text-only in practice across OpenRouter's
+    // providers (see the delivery note on viewImageRun in tools.ts), and every
+    // tool_call_id must be answered contiguously after the assistant turn, so
+    // the images can't interleave with the results either.
+    const imageMessages = [];
+    for (const group of groupToolCalls(toolCalls)) {
+        // Promise.all resolves its array in the SAME order as the input array
+        // regardless of which call actually finished first, so a singleton group
+        // (every barrier call, and the common case of one plain tool call) costs
+        // nothing extra by going through this same path.
+        const resolved = await Promise.all(group.map((call) => runOneToolCall(call, role, ctx, onActivity)));
+        for (const { call, name, args, result } of resolved) {
+            labels.set(call.id, toolCallLabel(name, args));
+            if (result.filesTouched)
+                for (const f of result.filesTouched)
+                    filesTouched.add(f);
+            if (result.playtestFrames)
+                for (const f of result.playtestFrames)
+                    playtestFrames.add(f);
+            log.write({
+                type: "tool_result",
+                id: call.id,
+                name,
+                ok: result.ok,
+                output: truncateForLog(result.output),
+                ...(result.images && result.images.length > 0
+                    ? {
+                        imageCount: result.images.length,
+                        imageChars: result.images.reduce((sum, img) => sum + img.dataUrl.length, 0),
+                    }
+                    : {}),
+            });
+            // A dedicated event for a successful playtest call, separate from the
+            // generic tool_result above -- args + frame paths + the short digest
+            // summary in one line, so a run's playtest activity can be grepped for
+            // without wading through every other tool's truncated output.
+            if (name === "playtest" && result.ok) {
+                log.write({
+                    type: "playtest",
+                    id: call.id,
+                    args,
+                    frames: result.playtestFrames ?? [],
+                    summary: result.activitySummary ?? "",
+                });
+            }
+            results.push({ role: "tool", tool_call_id: call.id, content: result.output });
+            for (const img of result.images ?? []) {
+                const imageMessage = {
+                    role: "user",
+                    content: [
+                        { type: "text", text: `Image from ${img.label}:` },
+                        { type: "image_url", image_url: { url: img.dataUrl } },
+                    ],
+                };
+                imageLabels.set(imageMessage, img.label);
+                imageMessages.push(imageMessage);
+            }
+        }
+    }
+    return [...results, ...imageMessages];
+}
+export async function runAgentNative(opts) {
+    const log = createRunLogger(opts.logPath);
+    const toolSchemas = toolSchemasForRole(opts.role);
+    log.write({
+        type: "init",
+        role: opts.role,
+        model: opts.model,
+        tools: toolSchemas.map((t) => t.function.name),
+        promptChars: opts.prompt.length,
+        ...(opts.attachments && opts.attachments.length > 0 ? { attachments: opts.attachments } : {}),
+    });
+    try {
+        const result = await runLoop(opts, toolSchemas, log);
+        log.write({
+            type: "result",
+            ok: !result.error && !result.crashed,
+            ...(result.error ? { error: result.error } : {}),
+            ...(result.crashed ? { crashed: true } : {}),
+            ...(result.usage ? { usage: result.usage } : {}),
+            ...(result.filesTouched && result.filesTouched.length > 0
+                ? { filesTouched: result.filesTouched }
+                : {}),
+            ...(result.playtestFrames && result.playtestFrames.length > 0
+                ? { playtestFrames: result.playtestFrames }
+                : {}),
+        });
+        return result;
+    }
+    finally {
+        await log.end();
+    }
+}
+async function runLoop(opts, toolSchemas, log) {
+    const controller = new AbortController();
+    // The only two things that ever abort `controller`; once aborted, whichever
+    // of these fired first determines the final error wording below (there is
+    // no third case, so we don't need a separate "was it external" flag).
+    let timeoutFired = false;
+    const timer = setTimeout(() => {
+        timeoutFired = true;
+        controller.abort();
+    }, opts.timeoutMs);
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            controller.abort();
+        else
+            opts.signal.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    const userContent = buildUserContent(opts.cwd, opts.prompt, opts.attachments);
+    if (userContent.error) {
+        clearTimeout(timer);
+        return { text: "", error: userContent.error };
+    }
+    const messages = [
+        { role: "system", content: buildSystemMessage(opts) },
+        { role: "user", content: userContent.content },
+    ];
+    const toolCtx = {
+        deckDir: opts.cwd,
+        signal: controller.signal,
+        restart: opts.restart,
+        // Fresh per run: the PLAYTEST_MAX_CALLS_PER_RUN budget resets every
+        // runAgentNative call (one task attempt), never persisted across retries.
+        playtest: opts.playtest
+            ? {
+                executor: opts.playtest.executor,
+                serveUrl: opts.playtest.serveUrl,
+                framesDir: opts.playtest.framesDir,
+                callCount: { value: 0 },
+                // First-run browser-download surfacing: every progress label is a
+                // live activity line AND a task feed row (see runTaskAgentIn's
+                // onActivity handler in agent.ts) -- an unexplained ~90s stall
+                // looks like a crash, so the download announces itself. The
+                // lifecycle additionally gets structured transcript events and a
+                // completion feed row with elapsed time.
+                onProgress: (label) => opts.onActivity?.(label),
+                onInstallEvent: (evt) => {
+                    log.write({ type: "browser-install", ...evt });
+                    if (evt.phase === "finished") {
+                        opts.onActivity?.(`Playtest browser downloaded in ${Math.max(1, Math.round(evt.elapsedMs / 1000))}s`);
+                    }
+                    else if (evt.phase === "failed") {
+                        opts.onActivity?.(`Playtest browser download failed after ${Math.max(1, Math.round(evt.elapsedMs / 1000))}s`);
+                    }
+                },
+            }
+            : undefined,
+    };
+    const filesTouched = new Set();
+    const playtestFrames = new Set();
+    const toolLabels = new Map();
+    // Synthetic view_image carrier messages, by identity -- see runToolCalls
+    // and evictOldToolResults.
+    const imageLabels = new Map();
+    let finalText = "";
+    let totalUsage;
+    // Once our own timeout/external-abort fires, whatever streamChatCompletion
+    // reports is moot -- the abort IS the reason for stopping, so we always
+    // attribute the final error to it (rather than a network error that might
+    // just be the abort surfacing as a fetch failure).
+    const abortResult = () => {
+        if (!controller.signal.aborted)
+            return null;
+        return {
+            text: finalText,
+            error: timeoutFired ? "agent run timed out" : "agent run stopped",
+            usage: totalUsage,
+            filesTouched: touchedFileList(filesTouched),
+            playtestFrames: playtestFrameList(playtestFrames),
+        };
+    };
+    try {
+        for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
+            const aborted = abortResult();
+            if (aborted)
+                return aborted;
+            const evicted = evictOldToolResults(messages, toolLabels, imageLabels);
+            if (evicted.length > 0) {
+                log.write({
+                    type: "eviction",
+                    evicted: evicted.map((e) => e.label),
+                    freedChars: evicted.reduce((sum, e) => sum + e.chars, 0),
+                });
+            }
+            const iterationStartedAt = Date.now();
+            const streamResult = await streamChatCompletion({
+                apiKey: opts.apiKey,
+                model: opts.model,
+                messages,
+                tools: toolSchemas,
+                reasoningEffort: REASONING_EFFORT[opts.role],
+                maxTokens: MAX_COMPLETION_TOKENS,
+                signal: controller.signal,
+                onDelta: opts.onDelta,
+                onThinking: opts.onThinking,
+                onRetry: (info) => log.write({ type: "retry", ...info }),
+            });
+            const wallMs = Date.now() - iterationStartedAt;
+            totalUsage = addUsage(totalUsage, streamResult.usage);
+            // One line per iteration (completion call), additive to -- and never
+            // replacing -- the end-of-run aggregate `result` event's summed usage
+            // (see addUsage above). This is the observability the incident this
+            // file cites was missing: with usage logged only once per whole run,
+            // attributing a spike to ONE iteration required manual forensics.
+            // Logged unconditionally (even on a crashed/errored/aborted call) so
+            // wallMs alone still flags a slow iteration when no usage came back.
+            log.write({
+                type: "usage",
+                iteration,
+                input_tokens: streamResult.usage?.input_tokens,
+                output_tokens: streamResult.usage?.output_tokens,
+                cache_read_input_tokens: streamResult.usage?.cache_read_input_tokens,
+                cache_creation_input_tokens: streamResult.usage?.cache_creation_input_tokens,
+                reasoning_tokens: streamResult.reasoningTokens,
+                wallMs,
+            });
+            const abortedAfter = abortResult();
+            if (abortedAfter)
+                return abortedAfter;
+            if (!streamResult.message) {
+                return {
+                    text: finalText,
+                    error: streamResult.error ?? "openrouter stream ended without a final response",
+                    usage: totalUsage,
+                    filesTouched: touchedFileList(filesTouched),
+                    playtestFrames: playtestFrameList(playtestFrames),
+                    crashed: streamResult.crashed,
+                };
+            }
+            finalText = streamResult.message.content;
+            const toolCalls = streamResult.message.tool_calls ?? [];
+            log.write({
+                type: "assistant",
+                iteration,
+                text: streamResult.message.content,
+                ...(toolCalls.length > 0
+                    ? {
+                        toolCalls: toolCalls.map((tc) => ({
+                            id: tc.id,
+                            name: tc.function.name,
+                            args: truncateForLog(tc.function.arguments),
+                        })),
+                    }
+                    : {}),
+            });
+            if (toolCalls.length === 0) {
+                return {
+                    text: finalText,
+                    usage: totalUsage,
+                    filesTouched: touchedFileList(filesTouched),
+                    playtestFrames: playtestFrameList(playtestFrames),
+                };
+            }
+            messages.push({
+                role: "assistant",
+                content: streamResult.message.content || null,
+                tool_calls: toolCalls,
+            });
+            const toolResults = await runToolCalls(toolCalls, opts.role, toolCtx, filesTouched, playtestFrames, toolLabels, imageLabels, log, opts.onActivity);
+            messages.push(...toolResults);
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return {
+        text: finalText,
+        error: "agent exceeded the maximum number of tool-call iterations",
+        usage: totalUsage,
+        filesTouched: touchedFileList(filesTouched),
+        playtestFrames: playtestFrameList(playtestFrames),
+    };
+}