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

package/dist/application.js

@@ -983,6 +983,8 @@ export async function createApplication(options = {}) {
                     case "limits.maxTurns":
                     case "limits.maxOutputTokens":
                     case "limits.maxContextChars":
+                    case "limits.firstTokenTimeoutMs":
+                    case "limits.firstTokenRetries":
                     case "limits.timeoutMs": {
                         const patch = limitLeaf(key.slice("limits.".length));
                         config.limits = { ...config.limits, ...patch };

package/dist/config.d.ts

@@ -175,6 +175,8 @@ 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>;
         maxContextChars: z.ZodDefault<z.ZodNumber>;
         maxOutputTokens: z.ZodDefault<z.ZodNumber>;
         maxTokens: z.ZodOptional<z.ZodNumber>;
@@ -270,6 +272,8 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     limits: {
         maxTurns: number;
         timeoutMs: number;
+        firstTokenTimeoutMs: number;
+        firstTokenRetries: number;
         maxContextChars: number;
         maxOutputTokens: number;
         maxTokens?: number | undefined;
@@ -442,6 +446,8 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     limits: {
         maxTurns: number;
         timeoutMs: number;
+        firstTokenTimeoutMs: number;
+        firstTokenRetries: number;
         maxContextChars: number;
         maxOutputTokens: number;
         maxTokens?: number | undefined;
@@ -555,6 +561,8 @@ declare const SETTABLE_KEYS: {
     readonly "limits.maxOutputTokens": z.ZodDefault<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 "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,7 +173,20 @@ 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),
         maxContextChars: z.number().int().positive().default(800000),
         /**
          * Per-call output token budget for one agent turn. 4096 starves reasoning-heavy models,
@@ -185,7 +198,9 @@ const configObjectSchema = z
     })
         .default(() => ({
         maxTurns: 100,
-        timeoutMs: 300000,
+        timeoutMs: 600000,
+        firstTokenTimeoutMs: 90000,
+        firstTokenRetries: 1,
         maxContextChars: 800000,
         maxOutputTokens: 16384,
     })),
@@ -686,6 +701,8 @@ 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,
     "pluginHooks.timeoutMs": SETTABLE_SECTIONS.pluginHooks.shape.timeoutMs,
     "tui.paddingX": SETTABLE_SECTIONS.tui.shape.paddingX,
     "tui.contentPaddingX": SETTABLE_SECTIONS.tui.shape.contentPaddingX,

package/dist/core/runner.d.ts

@@ -24,6 +24,10 @@ export interface RunnerOptions {
     workspace: string;
     maxTurns?: number;
     timeoutMs?: number;
+    /** See `RunnerSettingsPatch.firstTokenTimeoutMs`. */
+    firstTokenTimeoutMs?: number;
+    /** See `RunnerSettingsPatch.firstTokenRetries`. */
+    firstTokenRetries?: number;
     maxContextChars?: number;
     maxOutputTokens?: number;
     maxTokens?: number;
@@ -70,6 +74,17 @@ 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;
 }
 /**
  * Per-run overrides used by embedders and child sessions. Callers must only NARROW: `policy`
@@ -97,6 +112,10 @@ 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;
     /** 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. */

package/dist/core/runner.js

@@ -1,5 +1,21 @@
 import { isEphemeralRunEventType, textProjection, textResult, } from "@alisio/sdk";
 import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, reduceMessagesToBudget, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
+import { isTimeoutReason, providerLabel, RunTimeoutError } from "./timeout.js";
+/** Pause before a silent request is sent again; short, and cut off by a stop or the run limit. */
+const FIRST_TOKEN_RETRY_PAUSE_MS = 250;
+function abortableDelay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+    });
+}
 /**
  * Default cumulative token budget for one run: several context windows (each turn re-sends the
  * context), clamped; 1M tokens when the window is unknown.
@@ -593,7 +609,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 +673,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 +712,21 @@ export class AgentRunner {
         const limit = o.maxContextChars ?? 800_000;
         let tokens = 0, lastText = "", acquired = false;
         const usageTotal = { input: 0, output: 0 };
-        const timeout = AbortSignal.timeout(options.timeoutMs ?? o.timeoutMs ?? 300_000);
+        const runTimeoutMs = options.timeoutMs ?? o.timeoutMs ?? 300_000;
+        const firstTokenMs = options.firstTokenTimeoutMs ?? o.firstTokenTimeoutMs ?? 0;
+        const firstTokenRetries = firstTokenMs > 0 ? Math.max(0, options.firstTokenRetries ?? o.firstTokenRetries ?? 0) : 0;
+        const runStartedAt = Date.now();
+        const timeout = AbortSignal.timeout(runTimeoutMs);
         const combined = AbortSignal.any([controller.signal, timeout, ...(signal ? [signal] : [])]);
+        // What the run was doing, so a timeout can say where it was stuck (see `RunTimeoutError`).
+        let stage = "other";
+        let stageTool;
+        let modelId;
+        let providerName;
+        let requests = 0;
+        let silentTimedOut = false;
+        /** Sends of the request that is (or was last) waiting for its first token. */
+        let silentAttempts = 0;
         const context = options.context ?? o.context;
         const workspace = options.workspace ?? o.workspace;
         const pathAccess = o.pathAccess;
@@ -712,6 +753,8 @@ export class AgentRunner {
                 throw new Error("Session provider/workspace mismatch");
             // The session records the model; switching models is explicit via setModel.
             const model = session.model;
+            modelId = model;
+            providerName = providerLabel(provider.id);
             combined.throwIfAborted();
             if (o.extensions && o.store.messages(sessionId).length === 0) {
                 // New session: extensions may inject budgeted context once, persisted with the session.
@@ -822,39 +865,104 @@ export class AgentRunner {
                 // display-only extension of the persisted transcript and never reach a model prompt
                 // (raw image bytes included). The store keeps the rich parts for TUI replay.
                 const providerMessages = messages.map((m) => m.role === "tool" ? { ...m, result: textProjection(m.result) } : m);
-                const requested = Date.now();
+                let requested = Date.now();
                 let firstDelta;
-                for await (const e of provider.stream({
-                    instructions,
-                    messages: providerMessages,
-                    tools,
-                    maxOutputTokens: options.maxOutputTokens ?? o.maxOutputTokens ?? 4096,
-                    signal: combined,
-                    model,
-                    sessionId,
-                    ...(o.nativeTools?.length ? { nativeTools: o.nativeTools } : {}),
-                    ...((options.reasoningEffort ?? o.reasoningEffort)
-                        ? { reasoningEffort: options.reasoningEffort ?? o.reasoningEffort }
-                        : {}),
-                })) {
-                    combined.throwIfAborted();
-                    if (e.type !== "completed")
-                        firstDelta ??= Date.now();
-                    if (e.type === "text_delta")
-                        emit("text_delta", { delta: e.delta });
-                    else if (e.type === "reasoning_delta")
-                        emit("reasoning_delta", { delta: e.delta });
-                    else {
-                        if (completion)
-                            throw new Error("Provider emitted multiple completions");
-                        completion = e.message;
-                        truncated = e.message.truncated === true;
-                        usage = e.usage;
-                        tokens += (e.usage?.input ?? 0) + (e.usage?.output ?? 0);
-                        usageTotal.input += e.usage?.input ?? 0;
-                        usageTotal.output += e.usage?.output ?? 0;
+                stage = "waiting_model";
+                requests++;
+                silentAttempts = 0;
+                // The same request is sent again only while the provider stayed completely silent until
+                // `firstTokenTimeoutMs`. Nothing was received, appended or accounted for the aborted
+                // attempt, so the retry reuses the exact same inputs inside this turn.
+                for (;;) {
+                    silentAttempts++;
+                    silentTimedOut = false;
+                    requested = Date.now();
+                    // A request that stays completely silent can be stopped early (`firstTokenTimeoutMs`).
+                    const silent = new AbortController();
+                    let silentTimer = firstTokenMs > 0
+                        ? setTimeout(() => {
+                            silentTimedOut = true;
+                            silent.abort();
+                        }, firstTokenMs)
+                        : undefined;
+                    const stopSilentTimer = () => {
+                        if (silentTimer)
+                            clearTimeout(silentTimer);
+                        silentTimer = undefined;
+                    };
+                    let failure;
+                    try {
+                        for await (const e of provider.stream({
+                            instructions,
+                            messages: providerMessages,
+                            tools,
+                            maxOutputTokens: options.maxOutputTokens ?? o.maxOutputTokens ?? 4096,
+                            signal: firstTokenMs > 0 ? AbortSignal.any([combined, silent.signal]) : combined,
+                            model,
+                            sessionId,
+                            ...(o.nativeTools?.length ? { nativeTools: o.nativeTools } : {}),
+                            ...((options.reasoningEffort ?? o.reasoningEffort)
+                                ? { reasoningEffort: options.reasoningEffort ?? o.reasoningEffort }
+                                : {}),
+                        })) {
+                            combined.throwIfAborted();
+                            stopSilentTimer();
+                            if (stage === "waiting_model")
+                                stage = "streaming";
+                            if (e.type !== "completed")
+                                firstDelta ??= Date.now();
+                            if (e.type === "text_delta")
+                                emit("text_delta", { delta: e.delta });
+                            else if (e.type === "reasoning_delta")
+                                emit("reasoning_delta", { delta: e.delta });
+                            else {
+                                if (completion)
+                                    throw new Error("Provider emitted multiple completions");
+                                completion = e.message;
+                                truncated = e.message.truncated === true;
+                                usage = e.usage;
+                                tokens += (e.usage?.input ?? 0) + (e.usage?.output ?? 0);
+                                usageTotal.input += e.usage?.input ?? 0;
+                                usageTotal.output += e.usage?.output ?? 0;
+                            }
+                        }
                     }
+                    catch (error) {
+                        failure = error;
+                    }
+                    finally {
+                        stopSilentTimer();
+                    }
+                    const silentFailure = silentTimedOut &&
+                        firstDelta === undefined &&
+                        !completion &&
+                        !combined.aborted &&
+                        silentAttempts <= firstTokenRetries;
+                    if (!silentFailure) {
+                        if (failure !== undefined)
+                            throw failure;
+                        break;
+                    }
+                    // Do not start an attempt the whole-run limit could not let finish.
+                    const retryPauseMs = FIRST_TOKEN_RETRY_PAUSE_MS;
+                    if (runTimeoutMs - (Date.now() - runStartedAt) < retryPauseMs + firstTokenMs) {
+                        if (failure !== undefined)
+                            throw failure;
+                        break;
+                    }
+                    // From here the silence is handled: a later stop or run timeout is judged on its own.
+                    silentTimedOut = false;
+                    emit("request_retry", {
+                        attempt: silentAttempts,
+                        of: firstTokenRetries,
+                        reason: "first_token_timeout",
+                        afterMs: Date.now() - requested,
+                    });
+                    await abortableDelay(retryPauseMs, combined);
+                    combined.throwIfAborted();
+                    stage = "waiting_model";
                 }
+                stage = "other";
                 if (!completion)
                     throw new Error("Provider stream ended without a completed response");
                 const durationMs = Date.now() - requested;
@@ -944,6 +1052,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 +1084,8 @@ export class AgentRunner {
                     if (c && r)
                         o.store.append(sessionId, { role: "tool", callId: c.id, result: r });
                 }
+                stage = "other";
+                stageTool = undefined;
                 if (tokens >= budget)
                     throw new Error("Token budget exhausted");
             }
@@ -986,6 +1098,24 @@ export class AgentRunner {
             return { sessionId, text: lastText, status: "turns-exceeded", usage: usageTotal };
         }
         catch (error) {
+            const timedOut = silentTimedOut
+                ? { kind: "first_token", ms: firstTokenMs, attempts: Math.max(1, silentAttempts) }
+                : combined.aborted && isTimeoutReason(combined.reason)
+                    ? { kind: "run", ms: runTimeoutMs }
+                    : undefined;
+            if (timedOut && !(combined.aborted && !isTimeoutReason(combined.reason))) {
+                const failure = new RunTimeoutError({
+                    ...timedOut,
+                    ...(modelId ? { model: modelId } : {}),
+                    ...(providerName ? { provider: providerName } : {}),
+                    stage,
+                    ...(stage === "tool" && stageTool ? { tool: stageTool } : {}),
+                    ...(requests <= 1 ? { firstRequest: true } : {}),
+                });
+                emit("run_failed", { error: failure.message, code: "timeout", timeout: failure.info });
+                finish("failed", failure.message);
+                throw failure;
+            }
             // On cancellation report the abort reason, not the transport's secondary error.
             const cause = combined.aborted ? (combined.reason ?? error) : error;
             const message = cause instanceof Error ? cause.message : String(cause);

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/core",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.23",
   "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.19",
     "@mixmark-io/domino": "2.2.0",
     "@modelcontextprotocol/client": "2.1.0",
     "ajv": "8.20.0",