@alisio/core 0.1.0-alpha.21 → 0.1.0-alpha.23

package/dist/core/runner.js

@@ -1,5 +1,21 @@
 import { isEphemeralRunEventType, textProjection, textResult, } from "@alisio/sdk";
 import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, reduceMessagesToBudget, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
+import { isTimeoutReason, providerLabel, RunTimeoutError } from "./timeout.js";
+/** Pause before a silent request is sent again; short, and cut off by a stop or the run limit. */
+const FIRST_TOKEN_RETRY_PAUSE_MS = 250;
+function abortableDelay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+    });
+}
 /**
  * Default cumulative token budget for one run: several context windows (each turn re-sends the
  * context), clamped; 1M tokens when the window is unknown.
@@ -17,7 +33,19 @@ const MAX_INJECT_CHARS = 24_000;
  * fails with an actionable error instead of silently losing the whole history.
  */
 const MIN_MESSAGE_BUDGET_FLOOR = 4_000;
-const allowed = (policy, effect) => effect === "read" || effect === "internal" || !!policy[effect];
+const allowed = (policy, effect) => effect === "read" ||
+    effect === "internal" ||
+    ((effect === "write" || effect === "process" || effect === "external") && !!policy[effect]);
+/** A tool's capability is pre-allowed by the policy alone (`--allow-analysis`). */
+const capabilityAllowed = (policy, tool) => tool.capability === "analysis.run" && !!policy.analysis;
+/** First 40 lines of a script input, for capability approvals. */
+const scriptPreview = (input) => typeof input.code === "string" ? input.code.split(/\r?\n/).slice(0, 40).join("\n") : undefined;
+/** A short id for a tool call the user started from a UI (alphanumeric, 9 characters). */
+const uiCallId = () => {
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    const bytes = crypto.getRandomValues(new Uint8Array(9));
+    return Array.from(bytes, (b) => alphabet[b % alphabet.length]).join("");
+};
 export class AgentRunner {
     options;
     /** Sessions with an active run or compaction (one at a time per session). */
@@ -80,8 +108,11 @@ export class AgentRunner {
             }
         };
     }
-    /** Tools offered to the model under the current policy (and optional run narrowing). */
-    availableTools(run = {}) {
+    /**
+     * Tools offered to the model under the current policy (and optional run narrowing). With a
+     * session, a capability tool is also offered when that session's root holds a persisted grant.
+     */
+    availableTools(run = {}, sessionId) {
         const o = this.options;
         const policy = run.policy ?? o.policy;
         const approvals = !!o.approve && run.approvals !== false;
@@ -91,6 +122,12 @@ export class AgentRunner {
             const effect = t.effect ?? "external";
             if (allowed(policy, effect))
                 return true;
+            if (t.capability) {
+                if (capabilityAllowed(policy, t))
+                    return true;
+                if (sessionId && o.capabilities?.granted(t.capability, sessionId))
+                    return true;
+            }
             return approvals && (effect === "write" || effect === "process" || effect === "external");
         });
     }
@@ -310,6 +347,355 @@ export class AgentRunner {
             throw error;
         }
     }
+    /**
+     * Gates and executes one tool call: external-directory paths, the capability/effect gate with
+     * its approval, the call journal, artifact publishing and the result bound. Shared by model
+     * runs and `runToolCall`, so a call started from a UI passes exactly the same gates.
+     */
+    async executeCall(scope, p) {
+        const o = this.options;
+        const { sessionId, runId, emit, workspace, policy, approvals, options } = scope;
+        const combined = scope.signal;
+        const pathAccess = o.pathAccess;
+        const { call } = p;
+        let result;
+        const started = Date.now();
+        // `effect` rides along so the TUI can group consecutive calls by capability kind
+        // (read batches, write batches, commands…) without a name heuristic. Additive field.
+        emit("tool_started", {
+            name: call.name,
+            id: call.id,
+            arguments: call.arguments,
+            effect: p.tool?.effect ?? "external",
+        });
+        try {
+            combined.throwIfAborted();
+            if (p.error)
+                throw new Error(p.error);
+            if (!p.tool || !p.input)
+                throw new Error("Invalid tool");
+            const effect = p.tool.effect ?? "external";
+            // External-directory prerequisite: declared paths are resolved (and, outside every
+            // allowed root, approved for the containing directory) BEFORE the effect gate, so a
+            // write still needs its own write policy and a read never hard-throws first. The
+            // resolved map keeps "allow once" scoped to this one call, with no shared mutable
+            // state that parallel read batches could race on.
+            const resolved = new Map();
+            if (pathAccess)
+                for (const declared of p.tool.paths?.(p.input) ?? [])
+                    if (!resolved.has(declared)) {
+                        const target = await pathAccess.resolve(declared, {
+                            workspace,
+                            session: sessionId,
+                            ...(options.label ? { label: options.label } : {}),
+                            signal: combined,
+                        });
+                        // Key both the declared input and its resolved form: a write resolves the
+                        // input once, then re-checks the already-absolute path, and neither lookup may
+                        // ask a second time for an "allow once" decision.
+                        resolved.set(declared, target);
+                        resolved.set(target, target);
+                    }
+            scope.guard?.(effect);
+            if (options.toolFilter && !options.toolFilter(p.tool))
+                throw new Error(`Tool ${call.name} is not available in this session`);
+            const capability = p.tool.capability;
+            const gate = o.capabilities;
+            if (capability && (allowed(policy, effect) || capabilityAllowed(policy, p.tool))) {
+                // A broad process grant or --allow-analysis: allowed, audited as a flag decision.
+                gate?.record({
+                    capability,
+                    sessionId,
+                    scope: "once",
+                    decision: "allow",
+                    source: "flag",
+                    callId: call.id,
+                    runId,
+                    ...(options.correlationId !== undefined ? { correlationId: options.correlationId } : {}),
+                });
+            }
+            else if (capability && gate?.granted(capability, sessionId)) {
+                // A persisted "allow for this session" grant of the root session.
+            }
+            else if (!allowed(policy, effect)) {
+                if (!o.approve ||
+                    !approvals ||
+                    (effect !== "write" && effect !== "process" && effect !== "external"))
+                    throw new Error(`Capability denied: ${capability ?? effect}`);
+                const preview = capability
+                    ? (scriptPreview(p.input) ?? (await gate?.preview?.(p.input, sessionId)))
+                    : undefined;
+                emit("approval_requested", {
+                    id: call.id,
+                    name: call.name,
+                    effect,
+                    ...(options.label ? { label: options.label } : {}),
+                    ...(capability ? { capability } : {}),
+                });
+                const decision = await o.approve({
+                    call,
+                    effect,
+                    input: p.input,
+                    signal: combined,
+                    session: sessionId,
+                    ...(options.label ? { label: options.label } : {}),
+                    ...(capability ? { capability } : {}),
+                    ...(preview !== undefined ? { preview } : {}),
+                    ...(capability && gate?.runtime ? { runtime: gate.runtime } : {}),
+                });
+                combined.throwIfAborted();
+                const persisted = !!capability && !!gate && decision === "session";
+                if (capability && gate)
+                    gate.record({
+                        capability,
+                        sessionId,
+                        scope: decision === "session" ? "session" : "once",
+                        decision: decision === "deny" ? "deny" : "allow",
+                        source: gate.source ?? "tui",
+                        callId: call.id,
+                        runId,
+                        ...(options.correlationId !== undefined
+                            ? { correlationId: options.correlationId }
+                            : {}),
+                    });
+                emit("approval_resolved", {
+                    id: call.id,
+                    name: call.name,
+                    effect,
+                    decision,
+                    ...(capability ? { capability } : {}),
+                    ...(persisted ? { persisted: true } : {}),
+                });
+                if (decision === "deny")
+                    throw new Error(`Capability ${capability ?? effect} denied by the user for this call`);
+                // A capability grant never widens the effect: only effect approvals do.
+                if (decision === "session" && !capability)
+                    policy[effect] = true;
+            }
+            o.store.beginCall(sessionId, call, { runId, effect });
+            const publisher = o.artifacts?.({ sessionId, runId, callId: call.id }, (published) => emit("artifact_published", {
+                artifact: published.artifact,
+                path: published.path,
+                callId: call.id,
+                ...(published.executionId ? { executionId: published.executionId } : {}),
+            }));
+            /**
+             * `analysis.install`: always asks, `once` only, and no flag or earlier grant covers it. Where
+             * nobody can be asked (headless, no approval handler) the answer is `deny`.
+             */
+            const approveInstall = async (install) => {
+                if (!o.approve || !approvals)
+                    return "deny";
+                const installCall = { ...call, id: `${call.id}:install` };
+                emit("approval_requested", {
+                    id: installCall.id,
+                    name: call.name,
+                    effect: "process",
+                    ...(options.label ? { label: options.label } : {}),
+                    capability: "analysis.install",
+                    install,
+                });
+                let decision = "deny";
+                try {
+                    decision = await o.approve({
+                        call: installCall,
+                        effect: "process",
+                        input: { extras: install.extras },
+                        signal: combined,
+                        session: sessionId,
+                        ...(options.label ? { label: options.label } : {}),
+                        capability: "analysis.install",
+                        install,
+                    });
+                }
+                finally {
+                    combined.throwIfAborted();
+                }
+                // A `session` answer is treated as `once`: an installation permission is never stored.
+                const allowedNow = decision !== "deny";
+                gate?.record({
+                    capability: "analysis.install",
+                    sessionId,
+                    scope: "once",
+                    decision: allowedNow ? "allow" : "deny",
+                    source: gate.source ?? "tui",
+                    callId: call.id,
+                    runId,
+                    ...(options.correlationId !== undefined ? { correlationId: options.correlationId } : {}),
+                });
+                emit("approval_resolved", {
+                    id: installCall.id,
+                    name: call.name,
+                    effect: "process",
+                    decision: allowedNow ? "once" : "deny",
+                    capability: "analysis.install",
+                });
+                return allowedNow ? "once" : "deny";
+            };
+            result = await p.tool.execute(p.input, {
+                signal: combined,
+                workspace,
+                session: sessionId,
+                runId,
+                callId: call.id,
+                ...(publisher ? { artifacts: publisher } : {}),
+                approveInstall,
+                emit: (data) => emit("tool_progress", { id: call.id, data }),
+                ...(options.label ? { label: options.label } : {}),
+                ...(pathAccess
+                    ? {
+                        resolvePath: (path) => {
+                            const known = resolved.get(path);
+                            return known !== undefined
+                                ? Promise.resolve(known)
+                                : pathAccess.resolve(path, {
+                                    workspace,
+                                    session: sessionId,
+                                    ...(options.label ? { label: options.label } : {}),
+                                    signal: combined,
+                                });
+                        },
+                    }
+                    : {}),
+            });
+            // The bound applies to what the model sees (the text projection): display-only
+            // ui/image parts are bounded by their producers and must not push text over it.
+            const projected = textProjection(result);
+            if (JSON.stringify(projected).length > 48_000)
+                result = textResult(`${JSON.stringify(projected).slice(0, 40_000)}\n[tool output truncated]`, result.isError);
+            result = scope.amend?.(result, effect) ?? result;
+            o.store.endCall(sessionId, call, result);
+        }
+        catch (error) {
+            result = textResult(error instanceof Error ? error.message : String(error), true);
+            // A cancellation after execution may have left effects; journal remains pending.
+            if (!combined.aborted)
+                o.store.endCall(sessionId, call, result);
+        }
+        emit("tool_completed", {
+            id: call.id,
+            name: call.name,
+            isError: result.isError ?? false,
+            durationMs: Date.now() - started,
+            preview: result.content
+                .filter((part) => part.type === "text")
+                .map((c) => c.text)
+                .join("\n")
+                .slice(0, 2_000),
+        });
+        return result;
+    }
+    /**
+     * Runs ONE tool call without a model (spec §20 `runToolCall`): an action the user started from
+     * a UI, such as copying an artifact into the workspace. It is a real run of the session
+     * (`run_started` → `tool_*` → `run_completed`, journaled) and the call passes exactly the gates
+     * of a model call (`write` approval, capabilities, paths). The transcript stays valid for every
+     * provider: a user note (shown as `display`), an assistant message with the call, the tool
+     * result and a short assistant summary.
+     */
+    async runToolCall(sessionId, name, input, options = {}) {
+        const controller = this.claim(sessionId);
+        const runId = options.runId ?? crypto.randomUUID();
+        const o = this.options, emit = this.emitter(sessionId, { runId, correlationId: options.correlationId });
+        const finish = (status, error) => {
+            try {
+                o.store.endRun?.(runId, {
+                    status,
+                    usage: { input: 0, output: 0 },
+                    ...(error ? { error } : {}),
+                });
+            }
+            catch {
+                /* A journal write failure cannot invalidate an executed run. */
+            }
+        };
+        const runTimeoutMs = options.timeoutMs ?? o.timeoutMs ?? 300_000;
+        const timeout = AbortSignal.timeout(runTimeoutMs);
+        const combined = AbortSignal.any([
+            controller.signal,
+            timeout,
+            ...(options.signal ? [options.signal] : []),
+        ]);
+        const workspace = options.workspace ?? o.workspace;
+        let acquired = false;
+        try {
+            o.store.beginRun?.({
+                id: runId,
+                session: sessionId,
+                status: "running",
+                model: o.store.get(sessionId).model,
+                ...(options.correlationId !== undefined ? { correlationId: options.correlationId } : {}),
+            });
+            o.store.acquire(sessionId);
+            acquired = true;
+            o.store.reconcile(sessionId);
+            const session = o.store.get(sessionId);
+            if (session.workspace !== workspace)
+                throw new Error("Session workspace mismatch");
+            combined.throwIfAborted();
+            const call = { id: uiCallId(), name, arguments: JSON.stringify(input) };
+            let prepared;
+            try {
+                prepared = {
+                    call,
+                    tool: o.registry.get(name),
+                    input: o.registry.parse(name, call.arguments),
+                };
+            }
+            catch (error) {
+                prepared = { call, error: String(error) };
+            }
+            const note = `The user ran the ${name} tool from the interface.`;
+            o.store.append(sessionId, { role: "user", text: note, display: options.display ?? note });
+            emit("run_started", { model: session.model });
+            o.store.append(sessionId, { role: "assistant", text: "", calls: [call] });
+            const result = await this.executeCall({
+                sessionId,
+                runId,
+                emit,
+                signal: combined,
+                workspace,
+                policy: options.policy ?? o.policy,
+                approvals: !!o.approve && options.approvals !== false,
+                options,
+            }, prepared);
+            o.store.append(sessionId, { role: "tool", callId: call.id, result });
+            const first = textProjection(result)
+                .content.map((part) => (part.type === "text" ? part.text : ""))
+                .join(" ")
+                .replace(/\s*\n\s*/g, " ")
+                .trim()
+                .slice(0, 300);
+            const text = `${name} ${result.isError ? "failed" : "finished"}${first ? `: ${first}` : ""}`;
+            o.store.append(sessionId, { role: "assistant", text, calls: [] });
+            emit("run_completed", { tokens: 0, text });
+            finish("completed");
+            return { runId, status: "completed", result };
+        }
+        catch (error) {
+            if (combined.aborted && isTimeoutReason(combined.reason)) {
+                const failure = new RunTimeoutError({
+                    kind: "run",
+                    ms: runTimeoutMs,
+                    stage: "tool",
+                    tool: name,
+                });
+                emit("run_failed", { error: failure.message, code: "timeout", timeout: failure.info });
+                finish("failed", failure.message);
+                throw failure;
+            }
+            const cause = combined.aborted ? (combined.reason ?? error) : error;
+            const message = cause instanceof Error ? cause.message : String(cause);
+            emit(combined.aborted ? "run_cancelled" : "run_failed", { error: message });
+            finish(combined.aborted ? "cancelled" : "failed", message);
+            throw error;
+        }
+        finally {
+            if (acquired)
+                o.store.release(sessionId);
+            this.active.delete(sessionId);
+        }
+    }
     async run(sessionId, prompt, signal, options = {}) {
         const controller = this.claim(sessionId);
         const runId = options.runId ?? crypto.randomUUID();
@@ -326,8 +712,21 @@ export class AgentRunner {
         const limit = o.maxContextChars ?? 800_000;
         let tokens = 0, lastText = "", acquired = false;
         const usageTotal = { input: 0, output: 0 };
-        const timeout = AbortSignal.timeout(options.timeoutMs ?? o.timeoutMs ?? 300_000);
+        const runTimeoutMs = options.timeoutMs ?? o.timeoutMs ?? 300_000;
+        const firstTokenMs = options.firstTokenTimeoutMs ?? o.firstTokenTimeoutMs ?? 0;
+        const firstTokenRetries = firstTokenMs > 0 ? Math.max(0, options.firstTokenRetries ?? o.firstTokenRetries ?? 0) : 0;
+        const runStartedAt = Date.now();
+        const timeout = AbortSignal.timeout(runTimeoutMs);
         const combined = AbortSignal.any([controller.signal, timeout, ...(signal ? [signal] : [])]);
+        // What the run was doing, so a timeout can say where it was stuck (see `RunTimeoutError`).
+        let stage = "other";
+        let stageTool;
+        let modelId;
+        let providerName;
+        let requests = 0;
+        let silentTimedOut = false;
+        /** Sends of the request that is (or was last) waiting for its first token. */
+        let silentAttempts = 0;
         const context = options.context ?? o.context;
         const workspace = options.workspace ?? o.workspace;
         const pathAccess = o.pathAccess;
@@ -354,6 +753,8 @@ export class AgentRunner {
                 throw new Error("Session provider/workspace mismatch");
             // The session records the model; switching models is explicit via setModel.
             const model = session.model;
+            modelId = model;
+            providerName = providerLabel(provider.id);
             combined.throwIfAborted();
             if (o.extensions && o.store.messages(sessionId).length === 0) {
                 // New session: extensions may inject budgeted context once, persisted with the session.
@@ -394,6 +795,7 @@ export class AgentRunner {
                 text: prompt,
                 ...(options.display ? { display: options.display } : {}),
                 ...(options.attachments?.length ? { attachments: options.attachments } : {}),
+                ...(options.datasets?.length ? { datasets: options.datasets } : {}),
             });
             emit("run_started", { model });
             const budget = options.maxTokens ?? o.maxTokens ?? defaultTokenBudget(o.contextWindow?.(model));
@@ -407,7 +809,7 @@ export class AgentRunner {
                         o.store.append(sessionId, { role: "user", text: queued });
                 let instructions = await withPersona();
                 let messages = o.store.messages(sessionId);
-                const tools = this.availableTools(options);
+                const tools = this.availableTools(options, sessionId);
                 const toolsText = this.toolsText(tools);
                 const chars = () => instructions.length + JSON.stringify(messages).length + toolsText.length;
                 // REDUCIBLE content only (instructions + transcript). The fixed tool catalog
@@ -463,39 +865,104 @@ export class AgentRunner {
                 // display-only extension of the persisted transcript and never reach a model prompt
                 // (raw image bytes included). The store keeps the rich parts for TUI replay.
                 const providerMessages = messages.map((m) => m.role === "tool" ? { ...m, result: textProjection(m.result) } : m);
-                const requested = Date.now();
+                let requested = Date.now();
                 let firstDelta;
-                for await (const e of provider.stream({
-                    instructions,
-                    messages: providerMessages,
-                    tools,
-                    maxOutputTokens: options.maxOutputTokens ?? o.maxOutputTokens ?? 4096,
-                    signal: combined,
-                    model,
-                    sessionId,
-                    ...(o.nativeTools?.length ? { nativeTools: o.nativeTools } : {}),
-                    ...((options.reasoningEffort ?? o.reasoningEffort)
-                        ? { reasoningEffort: options.reasoningEffort ?? o.reasoningEffort }
-                        : {}),
-                })) {
-                    combined.throwIfAborted();
-                    if (e.type !== "completed")
-                        firstDelta ??= Date.now();
-                    if (e.type === "text_delta")
-                        emit("text_delta", { delta: e.delta });
-                    else if (e.type === "reasoning_delta")
-                        emit("reasoning_delta", { delta: e.delta });
-                    else {
-                        if (completion)
-                            throw new Error("Provider emitted multiple completions");
-                        completion = e.message;
-                        truncated = e.message.truncated === true;
-                        usage = e.usage;
-                        tokens += (e.usage?.input ?? 0) + (e.usage?.output ?? 0);
-                        usageTotal.input += e.usage?.input ?? 0;
-                        usageTotal.output += e.usage?.output ?? 0;
+                stage = "waiting_model";
+                requests++;
+                silentAttempts = 0;
+                // The same request is sent again only while the provider stayed completely silent until
+                // `firstTokenTimeoutMs`. Nothing was received, appended or accounted for the aborted
+                // attempt, so the retry reuses the exact same inputs inside this turn.
+                for (;;) {
+                    silentAttempts++;
+                    silentTimedOut = false;
+                    requested = Date.now();
+                    // A request that stays completely silent can be stopped early (`firstTokenTimeoutMs`).
+                    const silent = new AbortController();
+                    let silentTimer = firstTokenMs > 0
+                        ? setTimeout(() => {
+                            silentTimedOut = true;
+                            silent.abort();
+                        }, firstTokenMs)
+                        : undefined;
+                    const stopSilentTimer = () => {
+                        if (silentTimer)
+                            clearTimeout(silentTimer);
+                        silentTimer = undefined;
+                    };
+                    let failure;
+                    try {
+                        for await (const e of provider.stream({
+                            instructions,
+                            messages: providerMessages,
+                            tools,
+                            maxOutputTokens: options.maxOutputTokens ?? o.maxOutputTokens ?? 4096,
+                            signal: firstTokenMs > 0 ? AbortSignal.any([combined, silent.signal]) : combined,
+                            model,
+                            sessionId,
+                            ...(o.nativeTools?.length ? { nativeTools: o.nativeTools } : {}),
+                            ...((options.reasoningEffort ?? o.reasoningEffort)
+                                ? { reasoningEffort: options.reasoningEffort ?? o.reasoningEffort }
+                                : {}),
+                        })) {
+                            combined.throwIfAborted();
+                            stopSilentTimer();
+                            if (stage === "waiting_model")
+                                stage = "streaming";
+                            if (e.type !== "completed")
+                                firstDelta ??= Date.now();
+                            if (e.type === "text_delta")
+                                emit("text_delta", { delta: e.delta });
+                            else if (e.type === "reasoning_delta")
+                                emit("reasoning_delta", { delta: e.delta });
+                            else {
+                                if (completion)
+                                    throw new Error("Provider emitted multiple completions");
+                                completion = e.message;
+                                truncated = e.message.truncated === true;
+                                usage = e.usage;
+                                tokens += (e.usage?.input ?? 0) + (e.usage?.output ?? 0);
+                                usageTotal.input += e.usage?.input ?? 0;
+                                usageTotal.output += e.usage?.output ?? 0;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        failure = error;
                     }
+                    finally {
+                        stopSilentTimer();
+                    }
+                    const silentFailure = silentTimedOut &&
+                        firstDelta === undefined &&
+                        !completion &&
+                        !combined.aborted &&
+                        silentAttempts <= firstTokenRetries;
+                    if (!silentFailure) {
+                        if (failure !== undefined)
+                            throw failure;
+                        break;
+                    }
+                    // Do not start an attempt the whole-run limit could not let finish.
+                    const retryPauseMs = FIRST_TOKEN_RETRY_PAUSE_MS;
+                    if (runTimeoutMs - (Date.now() - runStartedAt) < retryPauseMs + firstTokenMs) {
+                        if (failure !== undefined)
+                            throw failure;
+                        break;
+                    }
+                    // From here the silence is handled: a later stop or run timeout is judged on its own.
+                    silentTimedOut = false;
+                    emit("request_retry", {
+                        attempt: silentAttempts,
+                        of: firstTokenRetries,
+                        reason: "first_token_timeout",
+                        afterMs: Date.now() - requested,
+                    });
+                    await abortableDelay(retryPauseMs, combined);
+                    combined.throwIfAborted();
+                    stage = "waiting_model";
                 }
+                stage = "other";
                 if (!completion)
                     throw new Error("Provider stream ended without a completed response");
                 const durationMs = Date.now() - requested;
@@ -556,137 +1023,38 @@ export class AgentRunner {
                 if (paths.length)
                     contextUpdate = await context.beforePaths(paths, sessionId);
                 let pendingUpdate = contextUpdate;
-                const execute = async (p) => {
-                    const { call } = p;
-                    let result;
-                    const started = Date.now();
-                    // `effect` rides along so the TUI can group consecutive calls by capability kind
-                    // (read batches, write batches, commands…) without a name heuristic. Additive field.
-                    emit("tool_started", {
-                        name: call.name,
-                        id: call.id,
-                        arguments: call.arguments,
-                        effect: p.tool?.effect ?? "external",
-                    });
-                    try {
-                        combined.throwIfAborted();
-                        if (p.error)
-                            throw new Error(p.error);
-                        if (!p.tool || !p.input)
-                            throw new Error("Invalid tool");
-                        const effect = p.tool.effect ?? "external";
-                        // External-directory prerequisite: declared paths are resolved (and, outside every
-                        // allowed root, approved for the containing directory) BEFORE the effect gate, so a
-                        // write still needs its own write policy and a read never hard-throws first. The
-                        // resolved map keeps "allow once" scoped to this one call, with no shared mutable
-                        // state that parallel read batches could race on.
-                        const resolved = new Map();
-                        if (pathAccess)
-                            for (const declared of p.tool.paths?.(p.input) ?? [])
-                                if (!resolved.has(declared)) {
-                                    const target = await pathAccess.resolve(declared, {
-                                        workspace,
-                                        session: sessionId,
-                                        ...(options.label ? { label: options.label } : {}),
-                                        signal: combined,
-                                    });
-                                    // Key both the declared input and its resolved form: a write resolves the
-                                    // input once, then re-checks the already-absolute path, and neither lookup may
-                                    // ask a second time for an "allow once" decision.
-                                    resolved.set(declared, target);
-                                    resolved.set(target, target);
-                                }
+                const scope = {
+                    sessionId,
+                    runId,
+                    emit,
+                    signal: combined,
+                    workspace,
+                    policy,
+                    approvals,
+                    options,
+                    guard: (effect) => {
                         if (contextUpdate && effect !== "read")
                             throw new Error(`Context changed; reconsider this call before retrying.\n${contextUpdate}`);
                         if (tokens >= budget)
                             throw new Error("Token budget exhausted; tool was not executed");
-                        if (options.toolFilter && !options.toolFilter(p.tool))
-                            throw new Error(`Tool ${call.name} is not available in this session`);
-                        if (!allowed(policy, effect)) {
-                            if (!o.approve ||
-                                !approvals ||
-                                (effect !== "write" && effect !== "process" && effect !== "external"))
-                                throw new Error(`Capability denied: ${effect}`);
-                            emit("approval_requested", {
-                                id: call.id,
-                                name: call.name,
-                                effect,
-                                ...(options.label ? { label: options.label } : {}),
-                            });
-                            const decision = await o.approve({
-                                call,
-                                effect,
-                                input: p.input,
-                                signal: combined,
-                                session: sessionId,
-                                ...(options.label ? { label: options.label } : {}),
-                            });
-                            combined.throwIfAborted();
-                            emit("approval_resolved", { id: call.id, name: call.name, effect, decision });
-                            if (decision === "deny")
-                                throw new Error(`Capability ${effect} denied by the user for this call`);
-                            if (decision === "session")
-                                policy[effect] = true;
-                        }
-                        o.store.beginCall(sessionId, call, { runId, effect });
-                        result = await p.tool.execute(p.input, {
-                            signal: combined,
-                            workspace,
-                            session: sessionId,
-                            emit: (data) => emit("tool_progress", { id: call.id, data }),
-                            ...(options.label ? { label: options.label } : {}),
-                            ...(pathAccess
-                                ? {
-                                    resolvePath: (path) => {
-                                        const known = resolved.get(path);
-                                        return known !== undefined
-                                            ? Promise.resolve(known)
-                                            : pathAccess.resolve(path, {
-                                                workspace,
-                                                session: sessionId,
-                                                ...(options.label ? { label: options.label } : {}),
-                                                signal: combined,
-                                            });
-                                    },
-                                }
-                                : {}),
-                        });
-                        // The bound applies to what the model sees (the text projection): display-only
-                        // ui/image parts are bounded by their producers and must not push text over it.
-                        const projected = textProjection(result);
-                        if (JSON.stringify(projected).length > 48_000)
-                            result = textResult(`${JSON.stringify(projected).slice(0, 40_000)}\n[tool output truncated]`, result.isError);
-                        if (pendingUpdate && effect === "read") {
-                            result = {
-                                ...result,
-                                content: [
-                                    ...result.content,
-                                    { type: "text", text: `\n<instructions>\n${pendingUpdate}\n</instructions>` },
-                                ],
-                            };
-                            pendingUpdate = undefined;
-                        }
-                        o.store.endCall(sessionId, call, result);
-                    }
-                    catch (error) {
-                        result = textResult(error instanceof Error ? error.message : String(error), true);
-                        // A cancellation after execution may have left effects; journal remains pending.
-                        if (!combined.aborted)
-                            o.store.endCall(sessionId, call, result);
-                    }
-                    emit("tool_completed", {
-                        id: call.id,
-                        name: call.name,
-                        isError: result.isError ?? false,
-                        durationMs: Date.now() - started,
-                        preview: result.content
-                            .filter((part) => part.type === "text")
-                            .map((c) => c.text)
-                            .join("\n")
-                            .slice(0, 2_000),
-                    });
-                    return result;
+                    },
+                    amend: (result, effect) => {
+                        if (!pendingUpdate || effect !== "read")
+                            return result;
+                        const update = pendingUpdate;
+                        pendingUpdate = undefined;
+                        return {
+                            ...result,
+                            content: [
+                                ...result.content,
+                                { type: "text", text: `\n<instructions>\n${update}\n</instructions>` },
+                            ],
+                        };
+                    },
                 };
+                stage = "tool";
+                stageTool = prepared[0]?.call.name;
+                const execute = (p) => this.executeCall(scope, p);
                 const results = [];
                 // Bounded parallel batches for consecutive read or explicitly concurrent tools.
                 const parallel = (p) => !!p?.tool && (p.tool.effect === "read" || p.tool.concurrent === true);
@@ -716,6 +1084,8 @@ export class AgentRunner {
                     if (c && r)
                         o.store.append(sessionId, { role: "tool", callId: c.id, result: r });
                 }
+                stage = "other";
+                stageTool = undefined;
                 if (tokens >= budget)
                     throw new Error("Token budget exhausted");
             }
@@ -728,6 +1098,24 @@ export class AgentRunner {
             return { sessionId, text: lastText, status: "turns-exceeded", usage: usageTotal };
         }
         catch (error) {
+            const timedOut = silentTimedOut
+                ? { kind: "first_token", ms: firstTokenMs, attempts: Math.max(1, silentAttempts) }
+                : combined.aborted && isTimeoutReason(combined.reason)
+                    ? { kind: "run", ms: runTimeoutMs }
+                    : undefined;
+            if (timedOut && !(combined.aborted && !isTimeoutReason(combined.reason))) {
+                const failure = new RunTimeoutError({
+                    ...timedOut,
+                    ...(modelId ? { model: modelId } : {}),
+                    ...(providerName ? { provider: providerName } : {}),
+                    stage,
+                    ...(stage === "tool" && stageTool ? { tool: stageTool } : {}),
+                    ...(requests <= 1 ? { firstRequest: true } : {}),
+                });
+                emit("run_failed", { error: failure.message, code: "timeout", timeout: failure.info });
+                finish("failed", failure.message);
+                throw failure;
+            }
             // On cancellation report the abort reason, not the transport's secondary error.
             const cause = combined.aborted ? (combined.reason ?? error) : error;
             const message = cause instanceof Error ? cause.message : String(cause);