@alisio/core 0.1.0-alpha.9 → 0.1.1

package/dist/core/runner.js

@@ -1,5 +1,27 @@
-import { textResult, } from "@alisio/sdk";
+import { isEphemeralRunEventType, textProjection, textResult, } from "@alisio/sdk";
 import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, reduceMessagesToBudget, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
+import { EXIT_PLAN_TOOL, optInAllows } from "./opt-in.js";
+import { resolveMaxOutputTokens } from "./output-limit.js";
+import { attachRunStats } from "./run-stats.js";
+import { isTimeoutReason, providerLabel, RunTimeoutError } from "./timeout.js";
+import { incompleteCalls, isOutputTruncationError, lowerEffort, RunTruncationError, TRUNCATION_NOTICE, } from "./truncation.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;
+/** Pause before a cut-off turn is requested again; short, and cut off by a stop or the run limit. */
+const TRUNCATION_RETRY_PAUSE_MS = 100;
+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.
@@ -13,11 +35,23 @@ export function defaultTokenBudget(contextWindow) {
 const MAX_INJECT_CHARS = 24_000;
 /**
  * Floor for the post-compaction transcript target: retained messages are never reduced below
- * this many characters, so a pathological session (instructions + tools alone crowding out the
- * limit) fails with an actionable error instead of silently losing the whole history.
+ * this many characters, so a pathological session (instructions alone crowding out the limit)
+ * 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). */
@@ -37,6 +71,20 @@ export class AgentRunner {
     get approvals() {
         return !!this.options.approve;
     }
+    /**
+     * Sets which effects run without asking (a permission mode). The policy object is mutated in
+     * place because the application and the runner share it; `analysis` is never touched. Takes
+     * effect from the next tool call, so it also drops "allow for this session" widenings.
+     */
+    setPolicy(next) {
+        const policy = this.options.policy;
+        if (next.write !== undefined)
+            policy.write = next.write;
+        if (next.process !== undefined)
+            policy.process = next.process;
+        if (next.external !== undefined)
+            policy.external = next.external;
+    }
     /**
      * Live-update runnable settings so the next `run`/`compact` call honors them without restarting
      * Alisio. Every patch field is merged over the current options; unrelated settings are kept.
@@ -49,8 +97,9 @@ export class AgentRunner {
             ...(compaction ? { compaction: { ...this.options.compaction, ...compaction } } : {}),
         };
     }
-    emitter(sessionId) {
-        const runId = crypto.randomUUID();
+    emitter(sessionId, run = {}) {
+        const runId = run.runId ?? crypto.randomUUID();
+        const correlationId = run.correlationId;
         let seq = 0;
         return (type, data) => {
             const event = {
@@ -62,8 +111,15 @@ export class AgentRunner {
                 timestamp: new Date().toISOString(),
                 data,
             };
-            if (type !== "text_delta" && type !== "tool_progress" && type !== "reasoning_delta")
-                this.options.store.event(sessionId, runId, type, data);
+            if (!isEphemeralRunEventType(type)) {
+                const persisted = correlationId !== undefined
+                    ? this.options.store.event(sessionId, runId, type, data, { correlationId })
+                    : this.options.store.event(sessionId, runId, type, data);
+                if (typeof persisted === "number")
+                    event.eventId = String(persisted);
+            }
+            if (correlationId !== undefined)
+                event.correlationId = correlationId;
             try {
                 this.options.onEvent?.(event);
             }
@@ -72,17 +128,28 @@ 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;
         return o.registry.list().filter((t) => {
             if (run.toolFilter && !run.toolFilter(t))
                 return false;
+            if (!optInAllows(t.name, run.optInTools))
+                return false;
             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");
         });
     }
@@ -147,6 +214,40 @@ export class AgentRunner {
             };
         return { total: undefined, basis: "unknown", compactionAt: 100 };
     }
+    /**
+     * What a tool-less side call about a session needs (for example a `/btw` side question): the
+     * session's provider and model, its system instructions, its ACTIVE history and the current
+     * limits. Claims no lock and writes nothing, so it is safe while a run is active.
+     */
+    async sideContext(sessionId) {
+        const o = this.options;
+        const session = o.store.get(sessionId);
+        const provider = await (o.providerFor?.(session) ?? o.provider);
+        const window = o.contextWindow?.(session.model);
+        return {
+            provider,
+            model: session.model,
+            ...(window !== undefined && window > 0 && window <= MAX_TRUSTED_WINDOW
+                ? { contextWindow: window }
+                : {}),
+            instructions: await o.context.instructions(sessionId),
+            messages: o.store.messages(sessionId),
+            maxContextChars: o.maxContextChars ?? 800_000,
+            maxOutputTokens: (await this.outputLimit(session.model)).value,
+            timeoutMs: o.timeoutMs ?? 300_000,
+            ...(o.reasoningEffort ? { reasoningEffort: o.reasoningEffort } : {}),
+        };
+    }
+    /** The output-token budget for `model`: user value, else catalog maximum, else fallback. */
+    async outputLimit(model, perRun) {
+        const o = this.options;
+        const declared = await Promise.resolve(o.modelOutputLimit?.(model)).catch(() => undefined);
+        return resolveMaxOutputTokens({
+            explicit: perRun ?? o.maxOutputTokens,
+            declared,
+            fallback: o.fallbackMaxOutputTokens ?? 4096,
+        });
+    }
     /** Change the model used by subsequent turns of a session; recorded in the store. */
     setModel(sessionId, model) {
         const id = model.trim();
@@ -278,16 +379,402 @@ 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)) ||
+                !optInAllows(p.tool.name, options.optInTools))
+                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 }),
+                // Only the built-in plan tool reports its durable events (never a plugin tool).
+                ...(p.tool.name === EXIT_PLAN_TOOL
+                    ? {
+                        emitEvent: (type, data) => emit(type, 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 o = this.options, emit = this.emitter(sessionId);
-        const limit = o.maxContextChars ?? 160_000;
-        let tokens = 0, lastText = "", acquired = false;
+        const runId = options.runId ?? crypto.randomUUID();
+        const o = this.options, emit = this.emitter(sessionId, { runId, correlationId: options.correlationId });
+        /** Run journal (v4 stores only): an auxiliary record that never changes the run outcome. */
+        const finish = (status, error) => {
+            try {
+                o.store.endRun?.(runId, { status, usage: usageTotal, ...(error ? { error } : {}) });
+            }
+            catch {
+                /* A journal write failure cannot invalidate an executed run. */
+            }
+        };
+        const limit = o.maxContextChars ?? 800_000;
+        let tokens = 0, toolCalls = 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 truncationRecoveries = Math.max(0, options.truncationRecoveries ?? o.truncationRecoveries ?? 0);
+        /** Responses of this run cut off by the output limit (the first plus every recovery). */
+        let truncations = 0;
+        /** Continuation notice and lowered effort for the request that follows a cut-off response. */
+        let recoveryNotice;
+        let recoveryEffort;
+        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;
         const policy = options.policy ?? o.policy;
         const approvals = !!o.approve && options.approvals !== false;
         const withPersona = async () => {
@@ -295,6 +782,13 @@ export class AgentRunner {
             return options.instructions ? `${base}\n\n${options.instructions}` : base;
         };
         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);
@@ -304,6 +798,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.
@@ -344,11 +840,13 @@ 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));
             const compaction = o.compaction ?? {};
-            for (let turn = 0; turn < (options.maxTurns ?? o.maxTurns ?? 20); turn++) {
+            const maxTurns = options.maxTurns ?? o.maxTurns ?? 100;
+            for (let turn = 0; turn < maxTurns; turn++) {
                 combined.throwIfAborted();
                 // Input queued while the run was working (e.g. a parent's message to a child).
                 if (turn > 0)
@@ -356,9 +854,17 @@ 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
+                // (`toolsText`) is a deployment reality — a huge MCP catalog with dozens of tools is
+                // part of every request regardless of history, so it is deliberately excluded from the
+                // post-compaction hard cap: counting it would reduce a small transcript to near-nothing
+                // and still fake-fail. Oversized catalogs are a `/plugins` decision, not session growth;
+                // auto-compaction above still measures the FULL request (`chars()`), because window
+                // thresholds protect what the model really sees, tools included.
+                const charsConversation = () => instructions.length + JSON.stringify(messages).length;
                 const used = () => {
                     const last = this.reported.get(sessionId);
                     return last && last.count <= messages.length
@@ -375,58 +881,203 @@ export class AgentRunner {
                     instructions = await withPersona();
                     messages = o.store.messages(sessionId);
                 }
-                // A compaction that still leaves the session over the hard limit (typically a kept tail
-                // holding huge tool outputs) is reduced in place instead of failing outright: retained
-                // content is clipped against a TOTAL character target for the transcript
-                // (`limit − instructions − tools`), largest items first, tool results before texts, in
-                // descending cap rounds. That also covers sessions with many MEDIUM results (e.g. MCP
-                // outputs of a few thousand chars each) that individually stay under the per-message
-                // caps; roles/callIds/boundaries stay untouched, so the transcript remains valid and
-                // replayable. Only if even the reduction floor cannot fit (instructions + tools alone
-                // crowd out the limit) the run fails with an actionable error; the reduction is
-                // persisted either way, so the session stays usable for later prompts.
-                if (chars() > limit) {
-                    const targetChars = Math.max(MIN_MESSAGE_BUDGET_FLOOR, limit - instructions.length - toolsText.length);
+                // A compaction that still leaves the session over the hard limit is reduced in place
+                // instead of failing outright: retained content is clipped against a TOTAL character
+                // target for the transcript (`limit − instructions`), largest items first, tool results
+                // before texts, in descending cap rounds. That also covers sessions with many MEDIUM
+                // results (e.g. MCP outputs of a few thousand chars each) that individually stay under
+                // the per-message caps; roles/callIds/boundaries stay untouched, so the transcript
+                // remains valid and replayable. The hard cap measures ONLY reducible content
+                // (`charsConversation`): the fixed tool catalog (see above) never triggers the error on
+                // its own. The reduction is persisted either way, so the session stays usable for later
+                // prompts. Only if even the reduction floor cannot fit (instructions alone crowd out the
+                // limit) the run fails with an actionable error.
+                if (charsConversation() > limit) {
+                    const targetChars = Math.max(MIN_MESSAGE_BUDGET_FLOOR, limit - instructions.length);
                     const reduction = reduceMessagesToBudget(messages, targetChars);
                     if (reduction.truncated > 0) {
                         o.store.overwrite(sessionId, reduction.messages);
                         messages = reduction.messages;
                         emit("context_reduced", { messages: reduction.truncated });
                     }
-                    if (chars() > limit)
-                        throw new Error(`Context budget exceeded and compaction could not reduce it (approximately ${chars()} characters; limit ${limit}). Run /compact, trim large tool outputs, or start a new session.`);
+                    if (charsConversation() > limit)
+                        throw new Error(`Context budget exceeded and compaction could not reduce it (approximately ${charsConversation()} characters of conversation; limit ${limit}). Run /compact, trim large tool outputs, start a new session, or disable unneeded MCP servers with /plugins.`);
                 }
                 let completion;
                 let truncated = false;
                 let usage;
-                for await (const e of provider.stream({
-                    instructions,
-                    messages,
-                    tools,
-                    maxOutputTokens: o.maxOutputTokens ?? 4096,
-                    signal: combined,
-                    model,
-                    sessionId,
-                    ...(o.nativeTools?.length ? { nativeTools: o.nativeTools } : {}),
-                })) {
+                // Providers only ever see the text projection of tool results: ui/image parts are a
+                // 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);
+                // After a cut-off response the request carries a transient continuation notice (never
+                // persisted: the stored transcript only ever holds what the model really answered).
+                if (recoveryNotice)
+                    providerMessages.push({ role: "user", text: recoveryNotice });
+                const requestEffort = recoveryEffort ?? options.reasoningEffort ?? o.reasoningEffort;
+                recoveryNotice = undefined;
+                recoveryEffort = undefined;
+                // Resolved for the model of THIS request (a catalog may still be loading on the first).
+                const outputLimit = await this.outputLimit(model, options.maxOutputTokens);
+                combined.throwIfAborted();
+                /** The provider threw the "cut off by the output limit" signal instead of completing. */
+                let cutByError = false;
+                let requested = Date.now();
+                let firstDelta;
+                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: outputLimit.value,
+                            signal: firstTokenMs > 0 ? AbortSignal.any([combined, silent.signal]) : combined,
+                            model,
+                            sessionId,
+                            ...(o.nativeTools?.length ? { nativeTools: o.nativeTools } : {}),
+                            ...(requestEffort ? { reasoningEffort: requestEffort } : {}),
+                        })) {
+                            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) {
+                            // A response cut off before anything usable is recovered like a truncated one.
+                            if (!completion && !combined.aborted && isOutputTruncationError(failure)) {
+                                cutByError = true;
+                                break;
+                            }
+                            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();
-                    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";
+                }
+                stage = "other";
+                // A response cut off by the output limit that cannot be used as it is: no visible text
+                // and no tool call, or a tool call whose arguments are incomplete. Complete calls of a
+                // cut response, and a cut response with usable text, keep their normal handling below.
+                let cut;
+                if (cutByError)
+                    cut = "empty_response";
+                else if (!completion)
+                    throw new Error("Provider stream ended without a completed response");
+                else if (truncated) {
+                    if (incompleteCalls(completion.calls))
+                        cut = "tool_call_cut";
+                    else if (!completion.text.trim() && !completion.calls.length)
+                        cut = "empty_response";
+                }
+                if (cut) {
+                    const maxOutputTokens = outputLimit.value;
+                    truncations++;
+                    // Visible text is kept as a normal assistant message; the cut calls are discarded:
+                    // never executed, never persisted (they would have no result), no provider data.
+                    const keep = completion?.text ?? "";
+                    if (keep.trim()) {
+                        o.store.append(sessionId, { role: "assistant", text: keep, calls: [] });
+                        lastText = keep;
                     }
+                    if (truncations > truncationRecoveries)
+                        throw new RunTruncationError({
+                            attempts: truncations,
+                            maxOutputTokens,
+                            source: outputLimit.source,
+                            ...(modelId ? { model: modelId } : {}),
+                        });
+                    // Reasoning exhausted the budget (nothing at all came out): ask for less of it once.
+                    const levels = o.effortLevels?.(model);
+                    const lowered = truncations === 1 && cut === "empty_response"
+                        ? lowerEffort(requestEffort ?? levels?.defaultLevel, levels?.supportedLevels)
+                        : undefined;
+                    emit("truncation_recovery", {
+                        attempt: truncations,
+                        of: truncationRecoveries,
+                        reason: cut,
+                        maxOutputTokens,
+                        ...(lowered ? { effort: lowered } : {}),
+                    });
+                    recoveryNotice = TRUNCATION_NOTICE;
+                    recoveryEffort = lowered;
+                    await abortableDelay(TRUNCATION_RETRY_PAUSE_MS, combined);
+                    combined.throwIfAborted();
+                    // The recovery is not a turn.
+                    turn--;
+                    continue;
                 }
                 if (!completion)
                     throw new Error("Provider stream ended without a completed response");
+                const durationMs = Date.now() - requested;
                 const ids = completion.calls.map((c) => c.id);
                 const previousIds = new Set(messages.flatMap((m) => (m.role === "assistant" ? m.calls.map((c) => c.id) : [])));
                 if (ids.some((id) => previousIds.has(id)))
@@ -448,6 +1099,8 @@ export class AgentRunner {
                     calls: completion.calls.length,
                     model,
                     ...(usage ? { usage } : {}),
+                    durationMs,
+                    ...(firstDelta !== undefined ? { ttftMs: firstDelta - requested } : {}),
                 });
                 if (!completion.calls.length) {
                     const final = {
@@ -458,13 +1111,16 @@ export class AgentRunner {
                         // The adapter kept a usable answer, but the token budget cut it off.
                         emit("response_truncated", {
                             turn: turn + 1,
-                            maxOutputTokens: o.maxOutputTokens ?? 4096,
+                            maxOutputTokens: outputLimit.value,
+                            source: outputLimit.source,
                         });
                         final.truncated = true;
                     }
                     emit("run_completed", final);
-                    return { sessionId, text: lastText, status: "completed", usage: usageTotal };
+                    finish("completed");
+                    return { sessionId, text: lastText, status: "completed", usage: usageTotal, toolCalls };
                 }
+                toolCalls += completion.calls.length;
                 const prepared = completion.calls.map((call) => {
                     try {
                         const tool = o.registry.get(call.name), input = o.registry.parse(call.name, call.arguments);
@@ -481,90 +1137,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();
-                    emit("tool_started", { name: call.name, id: call.id, arguments: call.arguments });
-                    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";
+                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);
-                        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 } : {}),
-                        });
-                        if (JSON.stringify(result).length > 48_000)
-                            result = textResult(`${JSON.stringify(result).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
-                            .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);
@@ -594,17 +1198,55 @@ 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");
             }
-            throw new Error("Maximum turns reached");
+            // Turn cap reached. This is NOT a failure: everything produced up to this point stays in
+            // the transcript and the run returns a successful-but-marked partial result, so the user
+            // can simply prompt again to continue in the same session. The real hard stops remain the
+            // token budget (`maxTokens`) and the timeout; the turn count is a safety rail.
+            emit("run_turns_exceeded", { turns: maxTurns, maxTurns });
+            finish("turns_exceeded");
+            return { sessionId, text: lastText, status: "turns-exceeded", usage: usageTotal, toolCalls };
         }
         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);
+                attachRunStats(failure, { usage: { ...usageTotal }, toolCalls });
+                throw failure;
+            }
+            if (error instanceof RunTruncationError) {
+                emit("run_failed", {
+                    error: error.message,
+                    code: "output_truncated",
+                    truncation: error.info,
+                });
+                finish("failed", error.message);
+                attachRunStats(error, { usage: { ...usageTotal }, toolCalls });
+                throw error;
+            }
             // On cancellation report the abort reason, not the transport's secondary error.
             const cause = combined.aborted ? (combined.reason ?? error) : error;
-            emit(combined.aborted ? "run_cancelled" : "run_failed", {
-                error: cause instanceof Error ? cause.message : String(cause),
-            });
+            const message = cause instanceof Error ? cause.message : String(cause);
+            emit(combined.aborted ? "run_cancelled" : "run_failed", { error: message });
+            finish(combined.aborted ? "cancelled" : "failed", message);
+            attachRunStats(error, { usage: { ...usageTotal }, toolCalls });
             throw error;
         }
         finally {