@alisio/core 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/core/compaction.d.ts

@@ -44,6 +44,59 @@ export interface CompactionPlan {
     kept: Message[];
 }
 export declare function planCompaction(messages: Message[], options?: CompactionOptions): CompactionPlan | undefined;
+/** Marker appended to message content cut by the context-budget reduction. */
+export declare const TRUNCATION_MARKER = "\u2026 [truncated by context budget]";
+/** Default per-message cap for kept tool result text after a failed compaction. */
+export declare const MAX_TOOL_RESULT_CHARS = 8000;
+/** Default per-message cap for kept user/assistant text after a failed compaction. */
+export declare const MAX_TEXT_CHARS = 16000;
+export interface MessageReductionOptions {
+    /** Keep at most this many characters of text per tool result (default 8_000). */
+    maxToolResultChars?: number;
+    /** Keep at most this many characters per user/assistant text (default 16_000). */
+    maxTextChars?: number;
+}
+export interface MessageReduction {
+    messages: Message[];
+    /** Number of messages whose content was truncated. */
+    truncated: number;
+}
+/**
+ * Cuts oversized retained content so the session fits the context-budget hard limit after a
+ * compaction could not. Only message CONTENT changes (user/assistant `text` and the text parts
+ * of tool results); roles, call IDs, order and message boundaries stay identical, so the
+ * transcript remains valid and replayable and a tool call is never separated from its results.
+ * Checkpoint summaries (`summary: true`) are bounded by design and never truncated.
+ */
+export declare function reduceMessageSizes(messages: Message[], options?: MessageReductionOptions): MessageReduction;
+export interface BudgetReductionOptions extends MessageReductionOptions {
+    /**
+     * Descending per-round caps for tool result text, replacing the default
+     * 8192 → 4096 → 2048 → 1024 → 512 sequence.
+     */
+    toolCapRounds?: number[];
+    /**
+     * Descending per-round caps for user/assistant text, replacing the default
+     * 16384 → 8192 → 4096 → 2048 → 1024 sequence.
+     */
+    textCapRounds?: number[];
+}
+/**
+ * Budget-based reduction: iteratively clips the LARGEST retained content (tool results in
+ * practice, then long texts) in descending cap rounds until the serialized transcript fits
+ * `targetChars` or the minimum caps are reached. Unlike `reduceMessageSizes` (which only clips
+ * messages whose INDIVIDUAL size exceeds its cap), this also handles sessions with many MEDIUM
+ * tool results (for example MCP outputs of a few thousand characters each) that stay under the
+ * per-message caps but together exhaust the context budget.
+ *
+ * The invariants match `reduceMessageSizes`: only message content changes (roles, call IDs,
+ * order and message boundaries stay identical, so a tool call is never separated from its
+ * results), checkpoint summaries are never truncated, and every cut carries the
+ * `… [truncated by context budget]` marker. Within a round the most expensive messages are
+ * clipped first (ties by position), so the smallest number of changes achieves the target; the
+ * order and the round caps make the result a deterministic total order of the input.
+ */
+export declare function reduceMessagesToBudget(messages: Message[], targetChars: number, options?: BudgetReductionOptions): MessageReduction;
 /**
  * Plain-text transcript used as summarizer input. Provider continuation data (for example
  * encrypted reasoning) is opaque and is intentionally not included.

package/dist/core/compaction.js

@@ -91,6 +91,155 @@ export function planCompaction(messages, options = {}) {
     return { cut, summarized: messages.slice(0, cut), kept: messages.slice(cut) };
 }
 const clip = (text, max) => text.length > max ? `${text.slice(0, max)}… [truncated]` : text;
+/** Marker appended to message content cut by the context-budget reduction. */
+export const TRUNCATION_MARKER = "… [truncated by context budget]";
+/** Default per-message cap for kept tool result text after a failed compaction. */
+export const MAX_TOOL_RESULT_CHARS = 8_000;
+/** Default per-message cap for kept user/assistant text after a failed compaction. */
+export const MAX_TEXT_CHARS = 16_000;
+/**
+ * Cuts ONE message's content down to the given per-message caps. Returns the same reference when
+ * nothing changes, so callers can detect a no-op by identity. See `reduceMessageSizes` for the
+ * invariants (roles/callIds/boundaries untouched, summaries never truncated).
+ */
+function clampMessage(message, maxToolResultChars, maxTextChars) {
+    if (message.role === "user") {
+        if (message.summary || message.text.length <= maxTextChars)
+            return message;
+        return { ...message, text: `${message.text.slice(0, maxTextChars)}\n${TRUNCATION_MARKER}` };
+    }
+    if (message.role === "assistant") {
+        if (message.text.length <= maxTextChars)
+            return message;
+        return { ...message, text: `${message.text.slice(0, maxTextChars)}\n${TRUNCATION_MARKER}` };
+    }
+    let used = 0;
+    let changed = false;
+    const content = message.result.content.map((part) => {
+        const room = maxToolResultChars - used;
+        const text = room <= 0
+            ? TRUNCATION_MARKER
+            : part.text.length > room
+                ? `${part.text.slice(0, room)}\n${TRUNCATION_MARKER}`
+                : part.text;
+        if (text !== part.text) {
+            changed = true;
+            used = maxToolResultChars;
+        }
+        else
+            used += part.text.length;
+        return { type: "text", text };
+    });
+    return changed ? { ...message, result: { ...message.result, content } } : message;
+}
+/**
+ * Cuts oversized retained content so the session fits the context-budget hard limit after a
+ * compaction could not. Only message CONTENT changes (user/assistant `text` and the text parts
+ * of tool results); roles, call IDs, order and message boundaries stay identical, so the
+ * transcript remains valid and replayable and a tool call is never separated from its results.
+ * Checkpoint summaries (`summary: true`) are bounded by design and never truncated.
+ */
+export function reduceMessageSizes(messages, options = {}) {
+    const maxToolResultChars = options.maxToolResultChars ?? MAX_TOOL_RESULT_CHARS;
+    const maxTextChars = options.maxTextChars ?? MAX_TEXT_CHARS;
+    let truncated = 0;
+    const reduced = messages.map((m) => {
+        const cut = clampMessage(m, maxToolResultChars, maxTextChars);
+        if (cut === m)
+            return m;
+        truncated++;
+        return cut;
+    });
+    return truncated ? { messages: reduced, truncated } : { messages, truncated: 0 };
+}
+/** Descending per-round tool-result caps used by `reduceMessagesToBudget` by default. */
+const DEFAULT_TOOL_CAP_ROUNDS = [MAX_TOOL_RESULT_CHARS, 4_096, 2_048, 1_024, 512];
+/** Descending per-round user/assistant text caps used by `reduceMessagesToBudget` by default. */
+const DEFAULT_TEXT_CAP_ROUNDS = [MAX_TEXT_CHARS, 8_192, 4_096, 2_048, 1_024];
+/** A strictly descending cap sequence starting at `start`, followed by the smaller defaults. */
+function capRounds(start, defaults) {
+    return [start, ...defaults.filter((c) => c < start)];
+}
+/**
+ * Budget-based reduction: iteratively clips the LARGEST retained content (tool results in
+ * practice, then long texts) in descending cap rounds until the serialized transcript fits
+ * `targetChars` or the minimum caps are reached. Unlike `reduceMessageSizes` (which only clips
+ * messages whose INDIVIDUAL size exceeds its cap), this also handles sessions with many MEDIUM
+ * tool results (for example MCP outputs of a few thousand characters each) that stay under the
+ * per-message caps but together exhaust the context budget.
+ *
+ * The invariants match `reduceMessageSizes`: only message content changes (roles, call IDs,
+ * order and message boundaries stay identical, so a tool call is never separated from its
+ * results), checkpoint summaries are never truncated, and every cut carries the
+ * `… [truncated by context budget]` marker. Within a round the most expensive messages are
+ * clipped first (ties by position), so the smallest number of changes achieves the target; the
+ * order and the round caps make the result a deterministic total order of the input.
+ */
+export function reduceMessagesToBudget(messages, targetChars, options = {}) {
+    const target = Math.max(1, Math.floor(targetChars));
+    const toolCapRounds = options.toolCapRounds ??
+        capRounds(options.maxToolResultChars ?? MAX_TOOL_RESULT_CHARS, DEFAULT_TOOL_CAP_ROUNDS);
+    const textCapRounds = options.textCapRounds ??
+        capRounds(options.maxTextChars ?? MAX_TEXT_CHARS, DEFAULT_TEXT_CAP_ROUNDS);
+    const rounds = Math.max(toolCapRounds.length, textCapRounds.length);
+    // Working transcript; `messages` keeps the untouched originals for re-clipping each round.
+    const working = [...messages];
+    const sizeOf = (m) => JSON.stringify(m).length;
+    const sizes = working.map(sizeOf);
+    // Serialized array length == sum of message lengths + n-1 commas + 2 brackets (+n+1 total).
+    let size = sizes.reduce((a, b) => a + b, 0) + working.length + 1;
+    if (size <= target)
+        return { messages, truncated: 0 };
+    const clipped = new Set();
+    for (let round = 0; round < rounds && size > target; round++) {
+        const toolCap = toolCapRounds[Math.min(round, toolCapRounds.length - 1)];
+        const textCap = textCapRounds[Math.min(round, textCapRounds.length - 1)];
+        if (toolCap === undefined || textCap === undefined)
+            break;
+        let shrank = true;
+        while (size > target && shrank) {
+            shrank = false;
+            // Largest (by current serialized size) clip-able message first; ties by position.
+            let best = -1, bestSize = -1;
+            for (let i = 0; i < working.length; i++) {
+                const current = sizes[i];
+                if (current === undefined || current <= bestSize)
+                    continue;
+                const m = messages[i];
+                if (!m)
+                    continue;
+                const over = m.role === "user"
+                    ? !m.summary && m.text.length > textCap
+                    : m.role === "assistant"
+                        ? m.text.length > textCap
+                        : m.role === "tool" &&
+                            m.result.content.reduce((a, p) => a + p.text.length, 0) > toolCap;
+                if (over) {
+                    best = i;
+                    bestSize = current;
+                }
+            }
+            if (best < 0)
+                break;
+            const original = messages[best];
+            const oldSize = sizes[best];
+            if (!original || oldSize === undefined)
+                break;
+            // Re-clip from the ORIGINAL content so earlier markers are never embedded mid-result.
+            const cut = clampMessage(original, toolCap, textCap);
+            const newSize = sizeOf(cut);
+            const delta = oldSize - newSize;
+            sizes[best] = newSize;
+            if (delta <= 0)
+                continue; // already at this round's caps; no room to shrink further
+            working[best] = cut;
+            clipped.add(best);
+            size -= delta;
+            shrank = true;
+        }
+    }
+    return clipped.size ? { messages: working, truncated: clipped.size } : { messages, truncated: 0 };
+}
 /**
  * Plain-text transcript used as summarizer input. Provider continuation data (for example
  * encrypted reasoning) is opaque and is intentionally not included.

package/dist/core/contracts.d.ts

@@ -56,6 +56,12 @@ export interface SessionStore {
      * rest verbatim and in order. Callers must never split a tool call from its results.
      */
     compact(id: string, replaced: number, summary: Message): void;
+    /**
+     * Atomically replace the whole active history with `messages` (like `compact` without a
+     * summary): used after a context-budget reduction so the persisted transcript matches what
+     * was actually sent. Callers must never split a tool call from its results.
+     */
+    overwrite(id: string, messages: Message[]): void;
     acquire(id: string): void;
     release(id: string): void;
     beginCall(session: string, call: ToolCall): void;

package/dist/core/runner.js

@@ -1,5 +1,5 @@
 import { textResult, } from "@alisio/sdk";
-import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
+import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, reduceMessagesToBudget, 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.
@@ -11,6 +11,12 @@ export function defaultTokenBudget(contextWindow) {
 }
 /** Extension output appended to history is capped regardless of what hooks return. */
 const MAX_INJECT_CHARS = 24_000;
+/**
+ * Floor for the post-compaction transcript target: retained messages are never reduced below
+ * this many characters, so a pathological session (instructions + tools alone crowding out the
+ * limit) fails with an actionable error instead of silently losing the whole history.
+ */
+const MIN_MESSAGE_BUDGET_FLOOR = 4_000;
 const allowed = (policy, effect) => effect === "read" || effect === "internal" || !!policy[effect];
 export class AgentRunner {
     options;
@@ -263,6 +269,7 @@ export class AgentRunner {
     async run(sessionId, prompt, signal, options = {}) {
         const controller = this.claim(sessionId);
         const o = this.options, emit = this.emitter(sessionId);
+        const limit = o.maxContextChars ?? 160_000;
         let tokens = 0, lastText = "", acquired = false;
         const usageTotal = { input: 0, output: 0 };
         const timeout = AbortSignal.timeout(options.timeoutMs ?? o.timeoutMs ?? 300_000);
@@ -351,13 +358,32 @@ export class AgentRunner {
                 // 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)) {
+                    shouldCompactContext(used(), chars(), o.contextWindow?.(model), limit, compaction.threshold ?? 0.85)) {
                     await this.compactLocked(sessionId, emit, model, combined, "auto");
                     instructions = await withPersona();
                     messages = o.store.messages(sessionId);
                 }
-                if (chars() > (o.maxContextChars ?? 160_000))
-                    throw new Error("Context budget exceeded and compaction could not reduce it; start a new session.");
+                // A compaction that still leaves the session over the hard limit (typically a kept tail
+                // holding huge tool outputs) is reduced in place instead of failing outright: retained
+                // content is clipped against a TOTAL character target for the transcript
+                // (`limit − instructions − tools`), largest items first, tool results before texts, in
+                // descending cap rounds. That also covers sessions with many MEDIUM results (e.g. MCP
+                // outputs of a few thousand chars each) that individually stay under the per-message
+                // caps; roles/callIds/boundaries stay untouched, so the transcript remains valid and
+                // replayable. Only if even the reduction floor cannot fit (instructions + tools alone
+                // crowd out the limit) the run fails with an actionable error; the reduction is
+                // persisted either way, so the session stays usable for later prompts.
+                if (chars() > limit) {
+                    const targetChars = Math.max(MIN_MESSAGE_BUDGET_FLOOR, limit - instructions.length - toolsText.length);
+                    const reduction = reduceMessagesToBudget(messages, targetChars);
+                    if (reduction.truncated > 0) {
+                        o.store.overwrite(sessionId, reduction.messages);
+                        messages = reduction.messages;
+                        emit("context_reduced", { messages: reduction.truncated });
+                    }
+                    if (chars() > limit)
+                        throw new Error(`Context budget exceeded and compaction could not reduce it (approximately ${chars()} characters; limit ${limit}). Run /compact, trim large tool outputs, or start a new session.`);
+                }
                 let completion;
                 let truncated = false;
                 let usage;

package/dist/runtime/store.d.ts

@@ -25,6 +25,7 @@ export declare class SQLiteStore implements SessionStore {
     append(id: string, message: Message): void;
     setModel(id: string, model: string): void;
     compact(id: string, replaced: number, summary: Message): void;
+    overwrite(id: string, messages: Message[]): void;
     acquire(id: string): void;
     release(id: string): void;
     beginCall(id: string, call: ToolCall): void;

package/dist/runtime/store.js

@@ -168,6 +168,15 @@ export class SQLiteStore {
                 this.db.prepare("INSERT INTO messages(session,body) VALUES(?,?)").run(id, row.body);
         });
     }
+    overwrite(id, messages) {
+        this.db.transaction(() => {
+            // Retire the active rows (originals stay marked compacted for auditing), then rewrite
+            // the reduced transcript in the same order.
+            this.db.prepare("UPDATE messages SET compacted=1 WHERE session=? AND compacted=0").run(id);
+            for (const message of messages)
+                this.append(id, message);
+        });
+    }
     acquire(id) {
         this.db.transaction(() => {
             this.get(id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/core",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "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",