@alisio/core 0.1.0-alpha.23 → 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
@@ -985,6 +1027,7 @@ export async function createApplication(options = {}) {
                     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

@@ -177,8 +177,9 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         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<{
@@ -274,8 +275,9 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         timeoutMs: number;
         firstTokenTimeoutMs: number;
         firstTokenRetries: number;
+        truncationRecoveries: number;
         maxContextChars: number;
-        maxOutputTokens: number;
+        maxOutputTokens?: number | undefined;
         maxTokens?: number | undefined;
     };
     analysis: {
@@ -448,8 +450,9 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         timeoutMs: number;
         firstTokenTimeoutMs: number;
         firstTokenRetries: number;
+        truncationRecoveries: number;
         maxContextChars: number;
-        maxOutputTokens: number;
+        maxOutputTokens?: number | undefined;
         maxTokens?: number | undefined;
     };
     analysis: {
@@ -558,11 +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

@@ -187,12 +187,23 @@ const configObjectSchema = z
          * 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(),
     })
@@ -201,8 +212,8 @@ const configObjectSchema = z
         timeoutMs: 600000,
         firstTokenTimeoutMs: 90000,
         firstTokenRetries: 1,
+        truncationRecoveries: 2,
         maxContextChars: 800000,
-        maxOutputTokens: 16384,
     })),
     /**
      * Python analysis and downloadable artifacts. `enabled: false` registers none of the
@@ -703,6 +714,7 @@ const SETTABLE_KEYS = {
     "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

@@ -28,8 +28,31 @@ export interface RunnerOptions {
     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;
@@ -85,6 +108,11 @@ export interface RunnerSettingsPatch {
      * 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`
@@ -116,6 +144,8 @@ export interface RunOptions {
     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. */
@@ -202,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,8 +1,12 @@
 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)
@@ -211,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();
@@ -715,6 +729,12 @@ export class AgentRunner {
         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] : [])]);
@@ -865,6 +885,18 @@ 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);
+                // 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";
@@ -896,14 +928,12 @@ export class AgentRunner {
                             instructions,
                             messages: providerMessages,
                             tools,
-                            maxOutputTokens: options.maxOutputTokens ?? o.maxOutputTokens ?? 4096,
+                            maxOutputTokens: outputLimit.value,
                             signal: firstTokenMs > 0 ? AbortSignal.any([combined, silent.signal]) : combined,
                             model,
                             sessionId,
                             ...(o.nativeTools?.length ? { nativeTools: o.nativeTools } : {}),
-                            ...((options.reasoningEffort ?? o.reasoningEffort)
-                                ? { reasoningEffort: options.reasoningEffort ?? o.reasoningEffort }
-                                : {}),
+                            ...(requestEffort ? { reasoningEffort: requestEffort } : {}),
                         })) {
                             combined.throwIfAborted();
                             stopSilentTimer();
@@ -939,8 +969,14 @@ export class AgentRunner {
                         !combined.aborted &&
                         silentAttempts <= firstTokenRetries;
                     if (!silentFailure) {
-                        if (failure !== undefined)
+                        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.
@@ -963,6 +999,57 @@ export class AgentRunner {
                     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;
@@ -999,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;
                     }
@@ -1116,6 +1204,15 @@ export class AgentRunner {
                 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/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.23",
+  "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.19",
+    "@alisio/sdk": "0.1.0-alpha.20",
     "@mixmark-io/domino": "2.2.0",
     "@modelcontextprotocol/client": "2.1.0",
     "ajv": "8.20.0",