@alisio/core 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/application.js

@@ -13,6 +13,7 @@ import { createArtifactPublisher } from "./artifacts/publisher.js";
 import { ArtifactStore } from "./artifacts/store.js";
 import { configFile, configHome, loadConfigWithProvenance, overridesSavedProviderProfile, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, stateHome, } from "./config.js";
 import { completeText } from "./core/compaction.js";
+import { DEFAULT_MAX_OUTPUT_TOKENS } from "./core/output-limit.js";
 import { ToolRegistry } from "./core/registry.js";
 import { AgentRunner } from "./core/runner.js";
 import { HerdrBridge } from "./integrations/herdr.js";
@@ -638,6 +639,39 @@ export async function createApplication(options = {}) {
                 return {};
             }
         };
+        /**
+         * The maximum output a model's catalog declares (`ModelInfo.maxOutputTokens`), for the budget
+         * of each request. Looks in the active provider's catalog first (loading it once, bounded, if
+         * the first request comes before it); then in the catalogs of the configured profiles that
+         * were already listed, taking the smallest declaration when several providers list the same
+         * model id so a derived budget never exceeds any of them. Unknown stays unknown.
+         */
+        const declaredOutputLimit = async (model) => {
+            if (!models.has(model)) {
+                const loading = ensureModels();
+                if (loading) {
+                    let timer;
+                    await Promise.race([
+                        loading.catch(() => undefined),
+                        new Promise((resolve) => {
+                            timer = setTimeout(resolve, 2_000);
+                        }),
+                    ]);
+                    if (timer)
+                        clearTimeout(timer);
+                }
+            }
+            const own = models.get(model)?.maxOutputTokens;
+            if (own !== undefined)
+                return own;
+            const declared = catalogCache
+                ? availableProviderModels(catalogCache.value)
+                    .filter((entry) => entry.model.id === model)
+                    .map((entry) => entry.model.maxOutputTokens)
+                    .filter((value) => typeof value === "number" && value > 0)
+                : [];
+            return declared.length ? Math.min(...declared) : undefined;
+        };
         const runner = new AgentRunner({
             provider,
             providerFor,
@@ -650,6 +684,14 @@ export async function createApplication(options = {}) {
             compaction: config.compaction,
             extensions: plugins,
             contextWindow,
+            modelOutputLimit: declaredOutputLimit,
+            fallbackMaxOutputTokens: DEFAULT_MAX_OUTPUT_TOKENS,
+            effortLevels: (model) => {
+                const known = models.get(model)?.effort;
+                if (!known)
+                    void ensureModels();
+                return known;
+            },
             ...(options.approve && !options.readOnly ? { approve: options.approve } : {}),
             pathAccess,
             ...(analysisEnabled
@@ -983,6 +1025,9 @@ export async function createApplication(options = {}) {
                     case "limits.maxTurns":
                     case "limits.maxOutputTokens":
                     case "limits.maxContextChars":
+                    case "limits.firstTokenTimeoutMs":
+                    case "limits.firstTokenRetries":
+                    case "limits.truncationRecoveries":
                     case "limits.timeoutMs": {
                         const patch = limitLeaf(key.slice("limits.".length));
                         config.limits = { ...config.limits, ...patch };

package/dist/config.d.ts

@@ -175,8 +175,11 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     limits: z.ZodDefault<z.ZodObject<{
         maxTurns: z.ZodDefault<z.ZodNumber>;
         timeoutMs: z.ZodDefault<z.ZodNumber>;
+        firstTokenTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        firstTokenRetries: z.ZodDefault<z.ZodNumber>;
+        truncationRecoveries: z.ZodDefault<z.ZodNumber>;
         maxContextChars: z.ZodDefault<z.ZodNumber>;
-        maxOutputTokens: z.ZodDefault<z.ZodNumber>;
+        maxOutputTokens: z.ZodOptional<z.ZodNumber>;
         maxTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     analysis: z.ZodDefault<z.ZodObject<{
@@ -270,8 +273,11 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     limits: {
         maxTurns: number;
         timeoutMs: number;
+        firstTokenTimeoutMs: number;
+        firstTokenRetries: number;
+        truncationRecoveries: number;
         maxContextChars: number;
-        maxOutputTokens: number;
+        maxOutputTokens?: number | undefined;
         maxTokens?: number | undefined;
     };
     analysis: {
@@ -442,8 +448,11 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     limits: {
         maxTurns: number;
         timeoutMs: number;
+        firstTokenTimeoutMs: number;
+        firstTokenRetries: number;
+        truncationRecoveries: number;
         maxContextChars: number;
-        maxOutputTokens: number;
+        maxOutputTokens?: number | undefined;
         maxTokens?: number | undefined;
     };
     analysis: {
@@ -552,9 +561,12 @@ declare const SETTABLE_KEYS: {
     readonly "context.claudeMdFallback": z.ZodDefault<z.ZodBoolean>;
     readonly "context.maxBytes": z.ZodDefault<z.ZodNumber>;
     readonly "limits.maxTurns": z.ZodDefault<z.ZodNumber>;
-    readonly "limits.maxOutputTokens": z.ZodDefault<z.ZodNumber>;
+    readonly "limits.maxOutputTokens": z.ZodOptional<z.ZodNumber>;
     readonly "limits.maxContextChars": z.ZodDefault<z.ZodNumber>;
     readonly "limits.timeoutMs": z.ZodDefault<z.ZodNumber>;
+    readonly "limits.firstTokenTimeoutMs": z.ZodDefault<z.ZodNumber>;
+    readonly "limits.firstTokenRetries": z.ZodDefault<z.ZodNumber>;
+    readonly "limits.truncationRecoveries": z.ZodDefault<z.ZodNumber>;
     readonly "pluginHooks.timeoutMs": z.ZodDefault<z.ZodNumber>;
     readonly "tui.paddingX": z.ZodDefault<z.ZodNumber>;
     readonly "tui.contentPaddingX": z.ZodDefault<z.ZodNumber>;

package/dist/config.js

@@ -173,21 +173,47 @@ const configObjectSchema = z
     limits: z
         .object({
         maxTurns: z.number().int().min(1).max(100).default(100),
-        timeoutMs: z.number().int().min(100).default(300000),
+        timeoutMs: z.number().int().min(100).default(600000),
+        /**
+         * Stop a model request that stays completely silent (no text, reasoning or tool-call
+         * delta) this long, so a queued or stuck provider is cut after 90 s instead of the
+         * whole-run `timeoutMs`. 0 disables it (models that do not stream their reasoning can stay
+         * silent for minutes: raise or disable it for those).
+         */
+        firstTokenTimeoutMs: z.number().int().min(0).default(90000),
+        /**
+         * How many times the SAME request is sent again after it stayed silent for
+         * `firstTokenTimeoutMs` (a stalled connection usually answers on the next try). 0
+         * disables the retry. Never counts as a turn.
+         */
+        firstTokenRetries: z.number().int().min(0).max(3).default(1),
+        /**
+         * How many times a turn is requested again after the model's response was cut off by
+         * `maxOutputTokens` before it was usable (no text and no tool call, or a tool call with
+         * incomplete arguments). The truncated calls are never executed. 0 disables the
+         * recovery. Never counts as a turn.
+         */
+        truncationRecoveries: z.number().int().min(0).max(5).default(2),
         maxContextChars: z.number().int().positive().default(800000),
         /**
-         * Per-call output token budget for one agent turn. 4096 starves reasoning-heavy models,
-         * which can spend the whole budget on `reasoning_content` before any usable text arrives.
+         * Per-call output token budget for one agent turn. Deliberately WITHOUT a schema default:
+         * when unset, the budget of each request is the model catalog's declared maximum (capped
+         * at 65536) or 16384 (see `core/output-limit.ts`), so "set by the user" stays
+         * distinguishable from "defaulted". A value set here always wins. 4096 starves
+         * reasoning-heavy models, which can spend the whole budget on `reasoning_content`
+         * before any usable text arrives.
          */
-        maxOutputTokens: z.number().int().positive().default(16384),
+        maxOutputTokens: z.number().int().positive().optional(),
         /** Cumulative tokens per run; default is proportional to the context window. */
         maxTokens: z.number().int().positive().optional(),
     })
         .default(() => ({
         maxTurns: 100,
-        timeoutMs: 300000,
+        timeoutMs: 600000,
+        firstTokenTimeoutMs: 90000,
+        firstTokenRetries: 1,
+        truncationRecoveries: 2,
         maxContextChars: 800000,
-        maxOutputTokens: 16384,
     })),
     /**
      * Python analysis and downloadable artifacts. `enabled: false` registers none of the
@@ -686,6 +712,9 @@ const SETTABLE_KEYS = {
     "limits.maxOutputTokens": SETTABLE_SECTIONS.limits.shape.maxOutputTokens,
     "limits.maxContextChars": SETTABLE_SECTIONS.limits.shape.maxContextChars,
     "limits.timeoutMs": SETTABLE_SECTIONS.limits.shape.timeoutMs,
+    "limits.firstTokenTimeoutMs": SETTABLE_SECTIONS.limits.shape.firstTokenTimeoutMs,
+    "limits.firstTokenRetries": SETTABLE_SECTIONS.limits.shape.firstTokenRetries,
+    "limits.truncationRecoveries": SETTABLE_SECTIONS.limits.shape.truncationRecoveries,
     "pluginHooks.timeoutMs": SETTABLE_SECTIONS.pluginHooks.shape.timeoutMs,
     "tui.paddingX": SETTABLE_SECTIONS.tui.shape.paddingX,
     "tui.contentPaddingX": SETTABLE_SECTIONS.tui.shape.contentPaddingX,

package/dist/core/output-limit.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The output-token budget of one model request.
+ *
+ * Priority: a value the user set explicitly (`limits.maxOutputTokens` in any config layer,
+ * `/settings`, a per-run option) always wins, even above the model's declared maximum (they asked
+ * for it, and a provider that rejects it says so); otherwise the maximum the model's catalog
+ * declares (`ModelInfo.maxOutputTokens`), capped at `MAX_AUTO_OUTPUT_TOKENS`; otherwise
+ * `DEFAULT_MAX_OUTPUT_TOKENS`. The value is resolved for the model of each request, so switching
+ * model within a session changes it.
+ */
+/** Output budget used when neither the user nor the model catalog says anything. */
+export declare const DEFAULT_MAX_OUTPUT_TOKENS = 16384;
+/**
+ * Upper bound of a budget taken from a model's declared maximum. Catalogs declare the model's
+ * hard limit (hundreds of thousands of tokens for some reasoning models), which is far more than
+ * a single agent turn should be allowed to stream; an explicit user value is never capped by it.
+ */
+export declare const MAX_AUTO_OUTPUT_TOKENS = 65536;
+/** Where the effective budget came from. */
+export type OutputLimitSource = "user" | "model" | "default";
+export interface OutputLimit {
+    value: number;
+    source: OutputLimitSource;
+}
+export declare function resolveMaxOutputTokens(input: {
+    /** Set by the user (config, settings or a per-run option); `undefined` when only defaulted. */
+    explicit?: number | undefined;
+    /** `ModelInfo.maxOutputTokens` of the model of the request, when its catalog declares one. */
+    declared?: number | undefined;
+    /** Used when nothing else applies; `DEFAULT_MAX_OUTPUT_TOKENS` unless the host knows better. */
+    fallback?: number | undefined;
+}): OutputLimit;
+/** A short English phrase for messages and logs. */
+export declare function describeOutputLimitSource(source: OutputLimitSource | undefined): string;

package/dist/core/output-limit.js

@@ -0,0 +1,39 @@
+/**
+ * The output-token budget of one model request.
+ *
+ * Priority: a value the user set explicitly (`limits.maxOutputTokens` in any config layer,
+ * `/settings`, a per-run option) always wins, even above the model's declared maximum (they asked
+ * for it, and a provider that rejects it says so); otherwise the maximum the model's catalog
+ * declares (`ModelInfo.maxOutputTokens`), capped at `MAX_AUTO_OUTPUT_TOKENS`; otherwise
+ * `DEFAULT_MAX_OUTPUT_TOKENS`. The value is resolved for the model of each request, so switching
+ * model within a session changes it.
+ */
+/** Output budget used when neither the user nor the model catalog says anything. */
+export const DEFAULT_MAX_OUTPUT_TOKENS = 16_384;
+/**
+ * Upper bound of a budget taken from a model's declared maximum. Catalogs declare the model's
+ * hard limit (hundreds of thousands of tokens for some reasoning models), which is far more than
+ * a single agent turn should be allowed to stream; an explicit user value is never capped by it.
+ */
+export const MAX_AUTO_OUTPUT_TOKENS = 65_536;
+const positive = (value) => typeof value === "number" && Number.isFinite(value) && value >= 1;
+export function resolveMaxOutputTokens(input) {
+    if (positive(input.explicit))
+        return { value: Math.floor(input.explicit), source: "user" };
+    if (positive(input.declared))
+        return { value: Math.min(Math.floor(input.declared), MAX_AUTO_OUTPUT_TOKENS), source: "model" };
+    return {
+        value: positive(input.fallback) ? Math.floor(input.fallback) : DEFAULT_MAX_OUTPUT_TOKENS,
+        source: "default",
+    };
+}
+/** A short English phrase for messages and logs. */
+export function describeOutputLimitSource(source) {
+    if (source === "user")
+        return "set by you";
+    if (source === "model")
+        return "from the model catalog";
+    if (source === "default")
+        return "default";
+    return "current limit";
+}

package/dist/core/runner.d.ts

@@ -24,8 +24,35 @@ export interface RunnerOptions {
     workspace: string;
     maxTurns?: number;
     timeoutMs?: number;
+    /** See `RunnerSettingsPatch.firstTokenTimeoutMs`. */
+    firstTokenTimeoutMs?: number;
+    /** See `RunnerSettingsPatch.firstTokenRetries`. */
+    firstTokenRetries?: number;
+    /** See `RunnerSettingsPatch.truncationRecoveries`. */
+    truncationRecoveries?: number;
+    /**
+     * Reasoning effort levels a model advertises (`ModelInfo.effort`), when known. Lets a recovery
+     * from an exhausted reasoning budget request one level lower; without it effort is unchanged.
+     */
+    effortLevels?: (model: string) => {
+        supportedLevels: string[];
+        defaultLevel?: string;
+    } | undefined;
     maxContextChars?: number;
+    /**
+     * Output-token budget the USER set (`limits.maxOutputTokens`). Left unset, the budget of each
+     * request is the model's declared maximum (`modelOutputLimit`, capped), else
+     * `fallbackMaxOutputTokens`. See `resolveMaxOutputTokens`.
+     */
     maxOutputTokens?: number;
+    /**
+     * The maximum output a model's catalog declares (`ModelInfo.maxOutputTokens`), when known.
+     * May be async (a catalog still loading); a failure counts as unknown. Called for the model
+     * of every request, so a model switch changes the budget.
+     */
+    modelOutputLimit?: (model: string) => number | undefined | Promise<number | undefined>;
+    /** Budget when neither the user nor the catalog says anything (4096 for bare embedders). */
+    fallbackMaxOutputTokens?: number;
     maxTokens?: number;
     onEvent?: (event: RunEvent) => void;
     readConcurrency?: number;
@@ -70,6 +97,22 @@ export interface RunnerSettingsPatch {
     maxContextChars?: number;
     /** Per-run timeout in milliseconds; the next run honors it. */
     timeoutMs?: number;
+    /**
+     * Stop a model request that stays completely silent (no text, reasoning or tool-call delta)
+     * for this many milliseconds. `0` or unset disables it: only the run timeout applies.
+     */
+    firstTokenTimeoutMs?: number;
+    /**
+     * How many times the same request is sent again after a silent timeout (`firstTokenTimeoutMs`).
+     * `0` or unset disables it. A retry is not a turn; it only happens while nothing at all was
+     * received for the request.
+     */
+    firstTokenRetries?: number;
+    /**
+     * How many times a turn is requested again after the response was cut off by the output-token
+     * limit before it was usable. `0` or unset disables it. A recovery is not a turn.
+     */
+    truncationRecoveries?: number;
 }
 /**
  * Per-run overrides used by embedders and child sessions. Callers must only NARROW: `policy`
@@ -97,6 +140,12 @@ export interface RunOptions {
     /** Per-call output token budget for this run; beats the runner-level budget when set. */
     maxOutputTokens?: number;
     timeoutMs?: number;
+    /** Silent-request limit for this run; beats the runner-level `firstTokenTimeoutMs`. */
+    firstTokenTimeoutMs?: number;
+    /** Silent-request retries for this run; beats the runner-level `firstTokenRetries`. */
+    firstTokenRetries?: number;
+    /** Output-truncation recoveries for this run; beats the runner-level `truncationRecoveries`. */
+    truncationRecoveries?: number;
     /** Reasoning effort level for this run; beats the runner-level default when set. */
     reasoningEffort?: string;
     /** Run id to use for this run's events (e.g. preassigned by an embedder); a UUID otherwise. */
@@ -183,6 +232,8 @@ export declare class AgentRunner {
         contextWindow?: number;
         reasoningEffort?: string;
     }>;
+    /** The output-token budget for `model`: user value, else catalog maximum, else fallback. */
+    private outputLimit;
     /** Change the model used by subsequent turns of a session; recorded in the store. */
     setModel(sessionId: string, model: string): void;
     /** Manually compact a session outside a run. */

package/dist/core/runner.js

@@ -1,5 +1,25 @@
 import { isEphemeralRunEventType, textProjection, textResult, } from "@alisio/sdk";
 import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, reduceMessagesToBudget, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
+import { resolveMaxOutputTokens } from "./output-limit.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.
@@ -195,11 +215,21 @@ export class AgentRunner {
             instructions: await o.context.instructions(sessionId),
             messages: o.store.messages(sessionId),
             maxContextChars: o.maxContextChars ?? 800_000,
-            maxOutputTokens: o.maxOutputTokens ?? 4096,
+            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();
@@ -593,7 +623,8 @@ export class AgentRunner {
                 /* A journal write failure cannot invalidate an executed run. */
             }
         };
-        const timeout = AbortSignal.timeout(options.timeoutMs ?? o.timeoutMs ?? 300_000);
+        const runTimeoutMs = options.timeoutMs ?? o.timeoutMs ?? 300_000;
+        const timeout = AbortSignal.timeout(runTimeoutMs);
         const combined = AbortSignal.any([
             controller.signal,
             timeout,
@@ -656,6 +687,17 @@ export class AgentRunner {
             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 });
@@ -684,8 +726,27 @@ 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 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;
@@ -712,6 +773,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.
@@ -822,38 +885,170 @@ 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();
+                // 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;
-                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 }
-                        : {}),
-                })) {
+                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 !== "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";
+                }
+                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");
@@ -891,7 +1086,8 @@ export class AgentRunner {
                         // The adapter kept a usable answer, but the token budget cut it off.
                         emit("response_truncated", {
                             turn: turn + 1,
-                            maxOutputTokens: options.maxOutputTokens ?? o.maxOutputTokens ?? 4096,
+                            maxOutputTokens: outputLimit.value,
+                            source: outputLimit.source,
                         });
                         final.truncated = true;
                     }
@@ -944,6 +1140,8 @@ export class AgentRunner {
                         };
                     },
                 };
+                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.
@@ -974,6 +1172,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");
             }
@@ -986,6 +1186,33 @@ 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;
+            }
+            if (error instanceof RunTruncationError) {
+                emit("run_failed", {
+                    error: error.message,
+                    code: "output_truncated",
+                    truncation: error.info,
+                });
+                finish("failed", error.message);
+                throw error;
+            }
             // 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);

package/dist/core/timeout.d.ts

@@ -0,0 +1,15 @@
+import type { RunTimeoutInfo } from "@alisio/sdk";
+/** A run stopped by a time limit; the message says which limit, which model and what to do. */
+export declare class RunTimeoutError extends Error {
+    readonly info: RunTimeoutInfo;
+    constructor(info: RunTimeoutInfo);
+}
+/** `AbortSignal.timeout` aborts with a `TimeoutError`; an explicit `abort()` does not. */
+export declare function isTimeoutReason(reason: unknown): boolean;
+/**
+ * A short, human label for a provider id: the host of an OpenAI-compatible endpoint
+ * (`openai-compatible:chat:https://api.example.com/v1` → `api.example.com`), else the id itself.
+ */
+export declare function providerLabel(id: string | undefined): string | undefined;
+/** Plain-text message of a timeout (TUI, headless, logs, the `runs.error` column). English only. */
+export declare function describeTimeout(info: RunTimeoutInfo): string;

package/dist/core/timeout.js

@@ -0,0 +1,61 @@
+/** A run stopped by a time limit; the message says which limit, which model and what to do. */
+export class RunTimeoutError extends Error {
+    info;
+    constructor(info) {
+        super(describeTimeout(info));
+        this.name = "RunTimeoutError";
+        this.info = info;
+    }
+}
+/** `AbortSignal.timeout` aborts with a `TimeoutError`; an explicit `abort()` does not. */
+export function isTimeoutReason(reason) {
+    return (typeof reason === "object" &&
+        reason !== null &&
+        reason.name === "TimeoutError");
+}
+/**
+ * A short, human label for a provider id: the host of an OpenAI-compatible endpoint
+ * (`openai-compatible:chat:https://api.example.com/v1` → `api.example.com`), else the id itself.
+ */
+export function providerLabel(id) {
+    if (!id)
+        return undefined;
+    const url = /(https?:\/\/[^\s]+)/.exec(id)?.[1];
+    if (url)
+        try {
+            return new URL(url).host;
+        }
+        catch {
+            /* fall through to the raw id */
+        }
+    return id;
+}
+const seconds = (ms) => Math.round(ms / 1000);
+/** Plain-text message of a timeout (TUI, headless, logs, the `runs.error` column). English only. */
+export function describeTimeout(info) {
+    const who = info.model
+        ? `The model ${info.model}${info.provider ? ` (${info.provider})` : ""}`
+        : "The model";
+    const limit = `${seconds(info.ms)} s`;
+    if (info.kind === "first_token" && info.attempts && info.attempts > 1)
+        return (`${who} did not respond after ${info.attempts} attempts of ${limit} each: no tokens were received, so the run was stopped. ` +
+            "Retry, switch to another model, or raise or disable limits.firstTokenTimeoutMs (0 disables it); " +
+            "limits.firstTokenRetries sets how many times a silent request is sent again.");
+    if (info.kind === "first_token")
+        return (`${who} sent nothing within ${limit} of the request, so the run was stopped. ` +
+            "Retry, switch to another model, or raise or disable limits.firstTokenTimeoutMs (0 disables it).");
+    if (info.stage === "waiting_model")
+        return info.firstRequest
+            ? `${who} did not respond within ${limit}: no tokens were received. ` +
+                "Retry, switch to another model, or raise limits.timeoutMs."
+            : `The run reached its ${limit} limit while waiting for ${info.model ? `the model ${info.model}` : "the model"}` +
+                `${info.provider ? ` (${info.provider})` : ""}. ` +
+                "Everything produced so far is kept: prompt again to continue, switch model, or raise limits.timeoutMs.";
+    const doing = info.stage === "tool" && info.tool
+        ? `while running ${info.tool}`
+        : info.stage === "streaming"
+            ? "while the model was answering"
+            : "";
+    return (`The run reached its ${limit} limit${doing ? ` ${doing}` : ""}. ` +
+        "Everything produced so far is kept: prompt again to continue, or raise limits.timeoutMs.");
+}

package/dist/core/truncation.d.ts

@@ -0,0 +1,30 @@
+import { type RunTruncationInfo, type ToolCall } from "@alisio/sdk";
+/**
+ * Recovery from a model response that the output-token limit (`limits.maxOutputTokens`) cut
+ * off before it was usable. Provider-agnostic: the runner decides from the completed message
+ * (`truncated: true`) or from the typed `OutputTruncatedError` signal, never from SDK types.
+ */
+/** The run failed because every response was cut off; carries the numbers for the UIs. */
+export declare class RunTruncationError extends Error {
+    readonly code = "output_truncated";
+    readonly info: RunTruncationInfo;
+    constructor(info: RunTruncationInfo);
+}
+/** Plain-text failure message (TUI, headless, logs). English only; the web localizes it. */
+export declare function describeTruncation(info: RunTruncationInfo): string;
+/** Whether a provider failure means "the response was cut off by the output-token limit". */
+export declare function isOutputTruncationError(error: unknown): boolean;
+/**
+ * Whether a tool call of a truncated response cannot be trusted: missing id or name, or
+ * arguments that are not a complete JSON object. Empty arguments only count as incomplete for
+ * the LAST call (the one being streamed when the limit hit); an earlier call with no arguments
+ * is how a provider reports a call without parameters.
+ */
+export declare function incompleteCalls(calls: ToolCall[]): boolean;
+/** What the model is told on the request that follows a truncated response. */
+export declare const TRUNCATION_NOTICE: string;
+/**
+ * One step below `current` among the model's supported levels, or `undefined` when that cannot
+ * be decided cleanly (unknown level names, no current level, or already the lowest).
+ */
+export declare function lowerEffort(current: string | undefined, supported: readonly string[] | undefined): string | undefined;

package/dist/core/truncation.js

@@ -0,0 +1,83 @@
+import { OUTPUT_TRUNCATED_CODE } from "@alisio/sdk";
+import { describeOutputLimitSource } from "./output-limit.js";
+/**
+ * Recovery from a model response that the output-token limit (`limits.maxOutputTokens`) cut
+ * off before it was usable. Provider-agnostic: the runner decides from the completed message
+ * (`truncated: true`) or from the typed `OutputTruncatedError` signal, never from SDK types.
+ */
+/** The run failed because every response was cut off; carries the numbers for the UIs. */
+export class RunTruncationError extends Error {
+    code = OUTPUT_TRUNCATED_CODE;
+    info;
+    constructor(info) {
+        super(describeTruncation(info));
+        this.name = "RunTruncationError";
+        this.info = info;
+    }
+}
+/** Plain-text failure message (TUI, headless, logs). English only; the web localizes it. */
+export function describeTruncation(info) {
+    const who = info.model ? `The model ${info.model}` : "The model";
+    const times = info.attempts === 1 ? "once" : `${info.attempts} times`;
+    return (`${who} was cut off ${times} by the output-token limit (${info.maxOutputTokens} tokens, ${describeOutputLimitSource(info.source)}) ` +
+        "before it produced a usable response, so the run was stopped. " +
+        "Raise limits.maxOutputTokens (/settings or the config file), lower the reasoning effort (/effort), " +
+        "or ask for the result in smaller parts.");
+}
+/**
+ * COMPATIBILITY: provider plugins published before the typed signal (for example
+ * `@alisio/plugin-deepseek` 0.1.1) throw a plain `Error` with this text when a response is cut
+ * off before any visible text. It is the only place the text is matched; new providers should
+ * yield `completed` with `truncated: true` or throw `OutputTruncatedError` from `@alisio/sdk`.
+ */
+const LEGACY_TRUNCATION_TEXT = "cut off by max output tokens before any usable content";
+/** Whether a provider failure means "the response was cut off by the output-token limit". */
+export function isOutputTruncationError(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const { code, message } = error;
+    return (code === OUTPUT_TRUNCATED_CODE ||
+        (typeof message === "string" && message.includes(LEGACY_TRUNCATION_TEXT)));
+}
+/**
+ * Whether a tool call of a truncated response cannot be trusted: missing id or name, or
+ * arguments that are not a complete JSON object. Empty arguments only count as incomplete for
+ * the LAST call (the one being streamed when the limit hit); an earlier call with no arguments
+ * is how a provider reports a call without parameters.
+ */
+export function incompleteCalls(calls) {
+    return calls.some((call, index) => {
+        if (!call.id || !call.name)
+            return true;
+        const raw = call.arguments.trim();
+        if (!raw)
+            return index === calls.length - 1;
+        try {
+            const parsed = JSON.parse(raw);
+            return typeof parsed !== "object" || parsed === null || Array.isArray(parsed);
+        }
+        catch {
+            return true;
+        }
+    });
+}
+/** What the model is told on the request that follows a truncated response. */
+export const TRUNCATION_NOTICE = "Your previous reply was cut off by the output-token limit, so it was discarded. " +
+    "Do not repeat what you already produced. Work in smaller steps: write long files in several parts " +
+    "(for example save the script or data to files in several tool calls, or build the dashboard with " +
+    "the compact alisio_runtime.html and svg helpers), keep your reasoning short, and continue from where you stopped.";
+const EFFORT_RANK = ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+/**
+ * One step below `current` among the model's supported levels, or `undefined` when that cannot
+ * be decided cleanly (unknown level names, no current level, or already the lowest).
+ */
+export function lowerEffort(current, supported) {
+    if (!current || !supported?.length)
+        return undefined;
+    const rank = (level) => EFFORT_RANK.indexOf(level);
+    if (rank(current) < 0 || supported.some((level) => rank(level) < 0))
+        return undefined;
+    const lower = [...supported].filter((level) => rank(level) < rank(current));
+    lower.sort((a, b) => rank(b) - rank(a));
+    return lower[0];
+}

package/dist/index.d.ts

@@ -27,6 +27,7 @@ export { BUILTIN_COMMANDS, type BuiltinCommand, CommandCatalog, type CommandExec
 export { type Config, type ConfigLoadResult, type ConfigProvenance, configFile, configHome, configSchema, isSettableSettingKey, type LoadedConfig, loadConfig, loadConfigWithProvenance, type McpServerSource, OCI_IMAGE_PATTERN, overridesSavedProviderProfile, type SettableSettingInfo, type SettableSettingKey, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, settableSettings, stateHome, } from "./config.ts";
 export { type ContextBudget, checkpointInstructions, completeText, effectiveContextBudget, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, renderCheckpoint, serializeForSummary, shouldCompact, shouldCompactContext, summarize, } from "./core/compaction.ts";
 export type { ApprovalDecision, ApprovalHandler, ApprovalRequest, ArtifactPublisherFactory, BeginRunInput, CapabilityGate, ContextSource, CoreArtifactPublisher, EndRunInput, EventPage, HookFailure, MessagePage, PageOptions, Policy, PublishedArtifactInfo, RunnerExtensions, RunRecord, RunStatus, Session, SessionStore, StoredEvent, TerminalRunStatus, ToolCallMeta, } from "./core/contracts.ts";
+export { DEFAULT_MAX_OUTPUT_TOKENS, describeOutputLimitSource, MAX_AUTO_OUTPUT_TOKENS, type OutputLimit, type OutputLimitSource, resolveMaxOutputTokens, } from "./core/output-limit.ts";
 export { ToolRegistry } from "./core/registry.ts";
 export { AgentRunner, type CompactionResult, defaultTokenBudget, type RunnerOptions, type RunnerSettingsPatch, type RunOptions, } from "./core/runner.ts";
 export { type ExtensionConflict, ExtensionRegistry } from "./extensions/registry.ts";

package/dist/index.js

@@ -26,6 +26,7 @@ export { ArtifactRejected, ArtifactStore, readHead as readArtifactHead, slugify
 export { BUILTIN_COMMANDS, CommandCatalog, } from "./commands/catalog.js";
 export { configFile, configHome, configSchema, isSettableSettingKey, loadConfig, loadConfigWithProvenance, OCI_IMAGE_PATTERN, overridesSavedProviderProfile, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, settableSettings, stateHome, } from "./config.js";
 export { checkpointInstructions, completeText, effectiveContextBudget, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, renderCheckpoint, serializeForSummary, shouldCompact, shouldCompactContext, summarize, } from "./core/compaction.js";
+export { DEFAULT_MAX_OUTPUT_TOKENS, describeOutputLimitSource, MAX_AUTO_OUTPUT_TOKENS, resolveMaxOutputTokens, } from "./core/output-limit.js";
 export { ToolRegistry } from "./core/registry.js";
 export { AgentRunner, defaultTokenBudget, } from "./core/runner.js";
 export { ExtensionRegistry } from "./extensions/registry.js";

package/dist/tools/analysis.js

@@ -125,6 +125,7 @@ function pythonRunDescription(deps) {
         "data_inspect) to $ALISIO_INPUT_DIR/<name>.sqlite: alisio_runtime.datasets.open(name) returns a",
         "read-only sqlite3 connection (table `data` or `s_<sheet>`). HTML is shown offline: embed data and scripts",
         "inline (no fetch, no CDN). Nothing is published when the script fails unless publishOnError.",
+        "Keep each call's code short: the model's output is capped per response, so split large scripts or dashboards into several calls or files.",
         "To run an earlier analysis again unchanged (same script, inputs checked by hash, new artifacts) pass rerunOf: an artifact or execution id of this session, instead of code.",
         container ? CONTAINER_NOTE : NOT_SANDBOXED,
         ...(deps.startup.candidates || container

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/core",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.24",
   "description": "Embeddable provider-agnostic Alisio agent core: tool loop, context compaction, local tools, MCP, plugin host and SQLite session store. Runs on Node >=22.16 and Bun.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "node": ">=22.16"
   },
   "dependencies": {
-    "@alisio/sdk": "0.1.0-alpha.18",
+    "@alisio/sdk": "0.1.0-alpha.20",
     "@mixmark-io/domino": "2.2.0",
     "@modelcontextprotocol/client": "2.1.0",
     "ajv": "8.20.0",