@alisio/core 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/application.d.ts

@@ -167,6 +167,12 @@ export declare function createApplication(options?: AppOptions): Promise<{
     runner: AgentRunner;
     herdr: HerdrBridge;
     contextWindow: (model: string) => number | undefined;
+    /** Effective context budget + compaction point shared by the runner and the TUI bar. */
+    contextBudget: (model: string) => {
+        total: number;
+        basis: "window" | "chars";
+        compactionAt: number;
+    };
     loadModels: (signal: AbortSignal) => Promise<ModelInfo[]>;
     /** Creates a provider for validation/model discovery without changing the active provider. */
     probeProvider(id: string, profile: Record<string, import("@alisio/sdk").ProviderConfigurationValue>, credentials: Record<string, string>, signal: AbortSignal): Promise<ModelInfo[]>;

package/dist/application.js

@@ -635,6 +635,8 @@ export async function createApplication(options = {}) {
             runner,
             herdr,
             contextWindow,
+            /** Effective context budget + compaction point shared by the runner and the TUI bar. */
+            contextBudget: (model) => runner.contextBudget(model),
             loadModels,
             /** Creates a provider for validation/model discovery without changing the active provider. */
             async probeProvider(id, profile, credentials, signal) {

package/dist/config.d.ts

@@ -149,6 +149,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         auto: z.ZodDefault<z.ZodBoolean>;
         threshold: z.ZodDefault<z.ZodNumber>;
         keepTurns: z.ZodDefault<z.ZodNumber>;
+        maxOutputTokens: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
     websearch: z.ZodDefault<z.ZodObject<{
         provider: z.ZodOptional<z.ZodEnum<{
@@ -206,6 +207,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         auto: boolean;
         threshold: number;
         keepTurns: number;
+        maxOutputTokens: number;
     };
     websearch: {
         provider?: "brave" | "duckduckgo-instant" | "native" | "searxng" | "serpapi" | "tavily" | undefined;
@@ -337,6 +339,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         auto: boolean;
         threshold: number;
         keepTurns: number;
+        maxOutputTokens: number;
     };
     websearch: {
         provider?: "brave" | "duckduckgo-instant" | "native" | "searxng" | "serpapi" | "tavily" | undefined;

package/dist/config.js

@@ -122,9 +122,14 @@ const configObjectSchema = z
         auto: z.boolean().default(true),
         threshold: z.number().min(0.1).max(0.99).default(0.85),
         keepTurns: z.number().int().min(0).max(20).default(2),
+        /**
+         * Output token budget for the summarizer call. Larger than the agent-loop budget on
+         * purpose: a truncated summary is kept as partial, never re-run.
+         */
+        maxOutputTokens: z.number().int().positive().default(16_000),
     })
         .strict()
-        .default(() => ({ auto: true, threshold: 0.85, keepTurns: 2 })),
+        .default(() => ({ auto: true, threshold: 0.85, keepTurns: 2, maxOutputTokens: 16_000 })),
     websearch: z
         .object({
         provider: z

package/dist/core/compaction.d.ts

@@ -2,6 +2,36 @@ import type { CompactionCheckpoint, CompletionRequest, Message, ModelProvider }
 /** Rough provider-agnostic estimate: ~4 characters per token. */
 export declare function estimateTokens(value: string | Message[]): number;
 export declare function shouldCompact(used: number, window: number | undefined, threshold: number): boolean;
+/**
+ * Declared context windows above this many tokens are treated as unknown for auto-compaction and
+ * for the context bar: a `window * threshold` trigger would dwarf the char-budget fallback and
+ * hide real pressure (e.g. an 8M-token window with a default 160k-char budget would never even
+ * reach 2% before running out of space). Documented in docs/compaction.md.
+ */
+export declare const MAX_TRUSTED_WINDOW = 2000000;
+export interface ContextBudget {
+    /** Effective total in tokens the context bar and auto-compaction measure against. */
+    total: number;
+    /** What the total is derived from: the model window, or the char-budget fallback. */
+    basis: "window" | "chars";
+}
+/**
+ * The single effective budget shared by the runner's auto-compaction and the TUI context bar.
+ * A known window (>= 1 token and <= MAX_TRUSTED_WINDOW) is used directly; otherwise the char
+ * budget is converted to estimated tokens (about 4 characters per token) so the bar fills where
+ * the char fallback actually compacts instead of showing an almost-empty bar next to an early
+ * compaction (the DeepSeek ~1M-window vs 160k-char budget mismatch).
+ */
+export declare function effectiveContextBudget(window: number | undefined, maxContextChars: number): ContextBudget;
+/**
+ * Whether to auto-compact before the next model call. Uses ONE effective budget: a known window
+ * triggers at `used >= window * threshold`; an unknown or guard-bounded window falls back to the
+ * char budget (`estimatedChars / 4 >= maxContextChars / 4`, keeping the old ~4-characters-per-token
+ * protection). `used` (provider-reported when available) feeds the window branch and the context
+ * bar; `estimatedChars` is the raw character count of the next request and feeds the fallback, so
+ * a provider's token report can never push an unknown-window session into needless compaction.
+ */
+export declare function shouldCompactContext(used: number, estimatedChars: number, window: number | undefined, maxContextChars: number, threshold: number): boolean;
 export interface CompactionOptions {
     /** Recent user turns kept verbatim. */
     keepTurns?: number;
@@ -31,6 +61,11 @@ export interface CheckpointOutput {
     text: string;
 }
 export declare function parseCheckpointOutput(raw: string, fields?: string[]): CheckpointOutput;
+export interface TextCompletion {
+    text: string;
+    /** Provider reported an output-token cut (finish "length"): text may be partial. */
+    truncated: boolean;
+}
 export declare function summarize(provider: ModelProvider, request: {
     instructions: string;
     messages: Message[];
@@ -39,7 +74,7 @@ export declare function summarize(provider: ModelProvider, request: {
     maxOutputTokens: number;
     signal: AbortSignal;
     sessionId?: string;
-}): Promise<string>;
+}): Promise<TextCompletion>;
 /** Narrow provider-agnostic completion used by compaction and the plugin model service. */
 export declare function completeText(provider: ModelProvider, request: CompletionRequest & {
     signal: AbortSignal;

package/dist/core/compaction.js

@@ -7,6 +7,39 @@ export function estimateTokens(value) {
 export function shouldCompact(used, window, threshold) {
     return !!window && window > 0 && used >= window * threshold;
 }
+/**
+ * Declared context windows above this many tokens are treated as unknown for auto-compaction and
+ * for the context bar: a `window * threshold` trigger would dwarf the char-budget fallback and
+ * hide real pressure (e.g. an 8M-token window with a default 160k-char budget would never even
+ * reach 2% before running out of space). Documented in docs/compaction.md.
+ */
+export const MAX_TRUSTED_WINDOW = 2_000_000;
+/**
+ * The single effective budget shared by the runner's auto-compaction and the TUI context bar.
+ * A known window (>= 1 token and <= MAX_TRUSTED_WINDOW) is used directly; otherwise the char
+ * budget is converted to estimated tokens (about 4 characters per token) so the bar fills where
+ * the char fallback actually compacts instead of showing an almost-empty bar next to an early
+ * compaction (the DeepSeek ~1M-window vs 160k-char budget mismatch).
+ */
+export function effectiveContextBudget(window, maxContextChars) {
+    if (window !== undefined && window > 0 && window <= MAX_TRUSTED_WINDOW)
+        return { total: window, basis: "window" };
+    return { total: Math.max(1, Math.round(maxContextChars / 4)), basis: "chars" };
+}
+/**
+ * Whether to auto-compact before the next model call. Uses ONE effective budget: a known window
+ * triggers at `used >= window * threshold`; an unknown or guard-bounded window falls back to the
+ * char budget (`estimatedChars / 4 >= maxContextChars / 4`, keeping the old ~4-characters-per-token
+ * protection). `used` (provider-reported when available) feeds the window branch and the context
+ * bar; `estimatedChars` is the raw character count of the next request and feeds the fallback, so
+ * a provider's token report can never push an unknown-window session into needless compaction.
+ */
+export function shouldCompactContext(used, estimatedChars, window, maxContextChars, threshold) {
+    const budget = effectiveContextBudget(window, maxContextChars);
+    if (budget.basis === "window")
+        return used >= budget.total * threshold;
+    return estimatedChars / 4 >= budget.total;
+}
 /**
  * Indexes where history can be split without separating an assistant tool call from its
  * results: every call before the index is answered before the index, and the kept part
@@ -154,26 +187,41 @@ export async function summarize(provider, request) {
     const focus = request.focus?.trim()
         ? `\n\nAdditional focus requested by the user: ${request.focus.trim()}`
         : "";
-    const text = await completeText(provider, {
-        system: request.instructions,
-        messages: [
-            {
-                role: "user",
-                text: `Checkpoint this session transcript.${focus}\n\n<transcript>\n${serializeForSummary(request.messages)}\n</transcript>`,
-            },
-        ],
-        maxTokens: request.maxOutputTokens,
-        signal: request.signal,
-        ...(request.model ? { model: request.model } : {}),
-        ...(request.sessionId ? { sessionId: request.sessionId } : {}),
-    });
-    if (!text)
+    let completion;
+    try {
+        completion = await completeTextWithMeta(provider, {
+            system: request.instructions,
+            messages: [
+                {
+                    role: "user",
+                    text: `Checkpoint this session transcript.${focus}\n\n<transcript>\n${serializeForSummary(request.messages)}\n</transcript>`,
+                },
+            ],
+            maxTokens: request.maxOutputTokens,
+            signal: request.signal,
+            ...(request.model ? { model: request.model } : {}),
+            ...(request.sessionId ? { sessionId: request.sessionId } : {}),
+        });
+    }
+    catch (error) {
+        // The adapters report an empty "length" cut with a message about max output tokens.
+        if (!request.signal.aborted && String(error).includes("max output tokens"))
+            throw new Error("Compaction summary was cut off before any usable text was produced; raise compaction.maxOutputTokens");
+        throw error;
+    }
+    if (completion.truncated && !completion.text)
+        throw new Error("Compaction summary was cut off before any usable text was produced; raise compaction.maxOutputTokens");
+    if (!completion.text)
         throw new Error("Summarizer returned an empty summary");
-    return text;
+    return completion;
 }
 /** Narrow provider-agnostic completion used by compaction and the plugin model service. */
 export async function completeText(provider, request) {
-    let text = "", completed = false;
+    return (await completeTextWithMeta(provider, request)).text;
+}
+/** Like `completeText`, but also reports whether the provider cut the response by tokens. */
+async function completeTextWithMeta(provider, request) {
+    let text = "", completed = false, truncated = false;
     for await (const event of provider.stream({
         instructions: request.system,
         messages: request.messages.map((m) => m.role === "user"
@@ -188,6 +236,7 @@ export async function completeText(provider, request) {
         request.signal.throwIfAborted();
         if (event.type === "completed") {
             completed = true;
+            truncated = event.message.truncated === true;
             text = event.message.text || text;
         }
         else if (event.type === "text_delta")
@@ -195,7 +244,7 @@ export async function completeText(provider, request) {
     }
     if (!completed)
         throw new Error("Completion ended without a completed response");
-    return text.trim();
+    return { text: text.trim(), truncated };
 }
 export function summaryMessage(body, replaced) {
     return {

package/dist/core/runner.d.ts

@@ -6,6 +6,11 @@ export interface CompactionSettings {
     auto?: boolean;
     threshold?: number;
     keepTurns?: number;
+    /**
+     * Per-call output token budget for the summarizer. Defaults to 4096 when unset; never falls
+     * back to the agent-loop `maxOutputTokens`. A truncated summary is accepted as partial.
+     */
+    maxOutputTokens?: number;
 }
 export interface RunnerOptions {
     /** Provider bound to this persisted session. */
@@ -23,7 +28,8 @@ export interface RunnerOptions {
     maxTokens?: number;
     onEvent?: (event: RunEvent) => void;
     readConcurrency?: number;
-    /** Context window in tokens for a model, when known. Unknown disables auto compaction. */
+    /** Context window in tokens for a model, when known. Drives auto-compaction at `threshold`; when
+     *  unknown (or absurdly large, see `MAX_TRUSTED_WINDOW`) the char budget falls back. */
     contextWindow?: (model: string) => number | undefined;
     compaction?: CompactionSettings;
     /** When set, write/process tools not allowed by the policy are offered and ask first. */
@@ -101,6 +107,17 @@ export declare class AgentRunner {
     private toolsText;
     /** Estimated tokens the next request of a session would send. */
     estimateContext(sessionId: string): Promise<number>;
+    /**
+     * The effective context budget a session's auto-compaction and the TUI context bar both use:
+     * the model window when known (and not beyond `MAX_TRUSTED_WINDOW`), otherwise the char budget
+     * converted to estimated tokens. `compactionAt` is the percentage of `total` where auto
+     * compaction triggers, so the bar turns red exactly where the engine compacts.
+     */
+    contextBudget(model: string): {
+        total: number;
+        basis: "window" | "chars";
+        compactionAt: number;
+    };
     /** 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,5 @@
 import { textResult, } from "@alisio/sdk";
-import { checkpointInstructions, estimateTokens, parseCheckpointOutput, planCompaction, shouldCompact, summarize, summaryMessage, } from "./compaction.js";
+import { checkpointInstructions, effectiveContextBudget, estimateTokens, parseCheckpointOutput, planCompaction, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
 /**
  * Default cumulative token budget for one run: several context windows (each turn re-sends the
  * context), clamped; 1M tokens when the window is unknown.
@@ -111,6 +111,21 @@ export class AgentRunner {
             estimateTokens(this.options.store.messages(sessionId)) +
             estimateTokens(this.toolsText(this.availableTools())));
     }
+    /**
+     * The effective context budget a session's auto-compaction and the TUI context bar both use:
+     * the model window when known (and not beyond `MAX_TRUSTED_WINDOW`), otherwise the char budget
+     * converted to estimated tokens. `compactionAt` is the percentage of `total` where auto
+     * compaction triggers, so the bar turns red exactly where the engine compacts.
+     */
+    contextBudget(model) {
+        const budget = effectiveContextBudget(this.options.contextWindow?.(model), this.options.maxContextChars ?? 160_000);
+        return {
+            ...budget,
+            compactionAt: budget.basis === "window"
+                ? Math.round((this.options.compaction?.threshold ?? 0.85) * 100)
+                : 100,
+        };
+    }
     /** Change the model used by subsequent turns of a session; recorded in the store. */
     setModel(sessionId, model) {
         const id = model.trim();
@@ -183,12 +198,12 @@ export class AgentRunner {
             reportFailures(contribution.failures);
             const fields = Object.fromEntries(Object.entries(contribution.fields).map(([name, f]) => [name, f.description]));
             const provider = await (o.providerFor?.(o.store.get(sessionId)) ?? o.provider);
-            const raw = await summarize(provider, {
+            const { text: raw, truncated: summaryTruncated } = await summarize(provider, {
                 instructions: checkpointInstructions(contribution.instructions, fields),
                 messages: plan.summarized,
                 focus,
                 model,
-                maxOutputTokens: o.maxOutputTokens ?? 4096,
+                maxOutputTokens: o.compaction?.maxOutputTokens ?? 4096,
                 signal,
                 sessionId,
             });
@@ -230,6 +245,7 @@ export class AgentRunner {
                 summarizedTokens: estimateTokens(plan.summarized),
                 checkpointTokens: estimateTokens(summary.text),
                 plugins: after.reports,
+                ...(summaryTruncated ? { partial: true } : {}),
             });
             return { replaced: plan.cut, before, after: afterTokens, summary };
         }
@@ -327,10 +343,12 @@ export class AgentRunner {
                         ? last.tokens + estimateTokens(messages.slice(last.count))
                         : estimateTokens(instructions) + estimateTokens(messages) + estimateTokens(toolsText);
                 };
-                const overChars = chars() > (o.maxContextChars ?? 160_000);
-                const overWindow = compaction.auto !== false &&
-                    shouldCompact(used(), o.contextWindow?.(model), compaction.threshold ?? 0.85);
-                if (overWindow || (overChars && compaction.auto !== false)) {
+                // One effective budget: a known window triggers at `used >= window * threshold`; an
+                // unknown (or absurdly large, see MAX_TRUSTED_WINDOW) window falls back to the char
+                // estimate (`chars / 4 >= maxContextChars / 4`). `maxContextChars` below stays as the
+                // post-compaction hard limit.
+                if (compaction.auto !== false &&
+                    shouldCompactContext(used(), chars(), o.contextWindow?.(model), o.maxContextChars ?? 160_000, compaction.threshold ?? 0.85)) {
                     await this.compactLocked(sessionId, emit, model, combined, "auto");
                     instructions = await withPersona();
                     messages = o.store.messages(sessionId);
@@ -338,6 +356,7 @@ export class AgentRunner {
                 if (chars() > (o.maxContextChars ?? 160_000))
                     throw new Error("Context budget exceeded and compaction could not reduce it; start a new session.");
                 let completion;
+                let truncated = false;
                 let usage;
                 for await (const e of provider.stream({
                     instructions,
@@ -358,6 +377,7 @@ export class AgentRunner {
                         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;
@@ -389,7 +409,19 @@ export class AgentRunner {
                     ...(usage ? { usage } : {}),
                 });
                 if (!completion.calls.length) {
-                    emit("run_completed", { tokens, text: lastText });
+                    const final = {
+                        tokens,
+                        text: lastText,
+                    };
+                    if (truncated) {
+                        // The adapter kept a usable answer, but the token budget cut it off.
+                        emit("response_truncated", {
+                            turn: turn + 1,
+                            maxOutputTokens: o.maxOutputTokens ?? 4096,
+                        });
+                        final.truncated = true;
+                    }
+                    emit("run_completed", final);
                     return { sessionId, text: lastText, status: "completed", usage: usageTotal };
                 }
                 const prepared = completion.calls.map((call) => {

package/dist/index.d.ts

@@ -2,7 +2,7 @@
 export * from "@alisio/sdk";
 export { type AppOptions, type BuiltinContext, type BuiltinPlugin, createApplication, enabledBuiltins, type PluginCatalogEntry, type PluginCatalogStatus, } from "./application.ts";
 export { type Config, type ConfigLoadResult, type ConfigProvenance, configFile, configHome, configSchema, type LoadedConfig, loadConfig, loadConfigWithProvenance, type McpServerSource, overridesSavedProviderProfile, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, stateHome, } from "./config.ts";
-export { checkpointInstructions, completeText, estimateTokens, parseCheckpointOutput, planCompaction, renderCheckpoint, serializeForSummary, shouldCompact, } from "./core/compaction.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, ContextSource, HookFailure, Policy, RunnerExtensions, Session, SessionStore, } from "./core/contracts.ts";
 export { ToolRegistry } from "./core/registry.ts";
 export { AgentRunner, type CompactionResult, defaultTokenBudget, type RunnerOptions, type RunOptions, } from "./core/runner.ts";

package/dist/index.js

@@ -2,7 +2,7 @@
 export * from "@alisio/sdk";
 export { createApplication, enabledBuiltins, } from "./application.js";
 export { configFile, configHome, configSchema, loadConfig, loadConfigWithProvenance, overridesSavedProviderProfile, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, stateHome, } from "./config.js";
-export { checkpointInstructions, completeText, estimateTokens, parseCheckpointOutput, planCompaction, renderCheckpoint, serializeForSummary, shouldCompact, } from "./core/compaction.js";
+export { checkpointInstructions, completeText, effectiveContextBudget, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, renderCheckpoint, serializeForSummary, shouldCompact, shouldCompactContext, summarize, } from "./core/compaction.js";
 export { ToolRegistry } from "./core/registry.js";
 export { AgentRunner, defaultTokenBudget, } from "./core/runner.js";
 export { ExtensionRegistry } from "./extensions/registry.js";

package/package.json

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