@aragon-agent/core 0.2.14 → 0.2.16

package/dist/engine/compaction.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Pure compaction mechanics (context-auto-compaction §3.6.1 / §3.6.2 / §5.3).
+ *
+ * NO I/O, NO CLOCK, NO PROVIDER KNOWLEDGE, NO `node:*` IMPORT. This module is
+ * the engine's whole contribution to compaction: where a history may safely be
+ * cut, which cut to take, and — the one that matters — whether a history the
+ * host handed back is structurally sendable at all.
+ *
+ * WHY THE ENGINE OWNS VALIDATION AND NOTHING ELSE (D-4). A compacted history
+ * that strands a `tool_result` without its `tool_call` is an immediate HTTP 400
+ * on Anthropic: `convertMessages` emits one `user` message carrying a
+ * `tool_use_id` per `tool_result`, and the API rejects a `tool_use_id` with no
+ * `tool_use` before it. That failure is not recoverable by the host and must not
+ * be recoverable BY POLICY — so the engine refuses to adopt an invalid history
+ * and continues with the original. A host bug becomes "compaction did not
+ * happen" rather than "the session is now permanently un-sendable" (R-2).
+ */
+import type { Message } from '../llm/types.js';
+export interface CompactionPlan {
+    /** Head is `[0, cutIndex)`; tail is `[cutIndex, end)`. */
+    cutIndex: number;
+    droppedMessages: number;
+    retainedTurns: number;
+}
+export type HistoryCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'empty' | 'orphan_tool_result' | 'unclosed_tool_call' | 'grew';
+};
+/**
+ * Every index at which the history may be split without stranding a tool call.
+ *
+ * `i` is SAFE iff, walking from 0, the set of open tool calls is empty at the
+ * boundary before `i` AND `messages[i]` is not a `tool_result`.
+ *
+ * A SET-BASED WALK RATHER THAN A ROLE-PATTERN RULE, and that is deliberate: the
+ * history is not always the clean `user -> assistant -> tool_result*` shape the
+ * loop produces. Steering interruption pushes synthesized `tool_result`s for the
+ * REMAINING calls in a batch, CodeAct injects a bare `user` message, and
+ * `/resume` restores whatever a file contained. A rule that encodes the happy
+ * path is a rule that produces an invalid splice on the one history that got
+ * interesting.
+ */
+export declare function findSafeCutIndices(messages: readonly Message[]): number[];
+export interface PlanCompactionOptions {
+    keepRecentTurns: number;
+    /**
+     * Messages at the head that are ALREADY structurally preserved by the host
+     * (the goal anchor, and a prior `<compacted_context>` block right after it).
+     *
+     * THIS PARAMETER IS WHAT MAKES REPEATED COMPACTION TERMINATE CLEANLY (P1-9 /
+     * D-21). Without it the condition would have to be "the best cut is 0 or 1",
+     * which encodes an assumption about what messages 0 and 1 ARE — and after one
+     * compaction they are the anchor and the summary block, so a second pass would
+     * re-summarize a summary with no new material, produce a smaller and lossier
+     * record, and report success.
+     *
+     * The HOST counts it (it is the host that knows what an `<original_task>`
+     * message is) and passes the number; core stays free of any knowledge of the
+     * block format, which is the §1.2 boundary. Hard-coding `1` here, or teaching
+     * this module the tag, are both ways of putting host knowledge in the engine
+     * to save a parameter.
+     */
+    protectedPrefix?: number;
+}
+/**
+ * The largest safe cut that still leaves at least `keepRecentTurns` complete
+ * turns in the tail, or `null` when there is nothing worth dropping.
+ *
+ * `null` — rather than a zero-length head — is what lets §3.8 turn "the recent
+ * turns alone exceed the threshold" into a bounded, loud outcome instead of a
+ * retry loop against a paid API.
+ */
+export declare function planCompaction(messages: readonly Message[], opts: PlanCompactionOptions): CompactionPlan | null;
+export interface ValidateHistoryOptions {
+    /**
+     * The length of the history being REPLACED. Supplied positionally by the loop
+     * so the `grew` rung is live: a compaction that returns more messages than it
+     * was given is not a correctness failure, but it is always a bug, and adopting
+     * it would let a broken compactor amplify the very problem it exists to solve.
+     */
+    previousLength?: number;
+}
+/**
+ * THE GATE (§3.3 step 5). One walk, the same open-set as `findSafeCutIndices`.
+ *
+ * Also exported for the host's IDLE `/compact` path (§4.4 / D-25), which cannot
+ * reach the loop's gate because there is no loop — and D-4 declares that gate
+ * unbypassable.
+ */
+export declare function validateHistory(messages: readonly Message[], opts?: ValidateHistoryOptions): HistoryCheck;
+export interface TailReliefOptions {
+    /** Index the tail starts at; nothing before it is touched. */
+    from: number;
+    /** Clip each oversized `tool_result` body to this many characters. */
+    clipChars: number;
+    /** Stop as soon as the estimate falls below this. */
+    targetTokens: number;
+    /** System prompt, so the estimate is measured the same way everywhere. */
+    systemPrompt: string;
+    /** Appended where text was removed. The host supplies it; core has no glyphs. */
+    marker: (removed: number) => string;
+}
+export interface TailReliefResult {
+    messages: Message[];
+    clippedMessages: number;
+    charsRemoved: number;
+}
+/**
+ * Clip oversized `tool_result` bodies inside a retained tail until the whole
+ * history is projected under `targetTokens` — the last rung of the ladder
+ * (context-auto-compaction-hardening §3.3).
+ *
+ * WHY THIS EXISTS. Every other rung operates on the HEAD: summarize it, retry
+ * the summarization, drop it without a summary. When the TAIL is what does not
+ * fit — `keepRecentTurns` turns carrying several 100 KB tool results — each of
+ * those rungs reports success or `nothing_to_drop` while the history stays
+ * un-sendable, and the run dies with no rung left.
+ *
+ * FOUR RULES, EACH LOAD-BEARING:
+ *
+ *  1. ONLY `tool_result` BODIES ARE ELIGIBLE. Not `user` messages (the anchor
+ *     and the user's own instructions are the last things to damage), not
+ *     `assistant` messages (clipping the model's own reasoning mid-tail produces
+ *     a history that contradicts itself). The size argument is the bound: a tool
+ *     result is capped at 100 KB EACH with several per turn, while an assistant
+ *     message is capped by the turn's `maxOutputTokens`. The tail is blown by
+ *     results, not by calls.
+ *  2. OLDEST FIRST. The newest tool result is the one the next request is most
+ *     likely to be about, so the walk starts at `from` and stops the moment the
+ *     projection is under budget.
+ *  3. STRUCTURE IS NEVER CHANGED. No message is removed, no `toolCallId` is
+ *     touched, no role changes — so `validateHistory` cannot fail on a relieved
+ *     history that was valid before. That is what makes this safe to run AFTER a
+ *     splice, and it is the reason relief CLIPS rather than DROPS.
+ *  4. EVERY CLIP IS ANNOUNCED IN THE TEXT THE MODEL READS, at the exact place
+ *     the data was removed. A model that sees the marker knows the output is
+ *     partial and can re-run the tool; a model handed a silently truncated file
+ *     does not.
+ *
+ * PURE, AND IT DOES NOT MUTATE ITS INPUT. Untouched messages keep their identity
+ * in the returned array, which is what lets a caller assert "nothing before
+ * `from` changed" by reference rather than by deep equality.
+ */
+export declare function relieveTail(messages: readonly Message[], opts: TailReliefOptions): TailReliefResult;

package/dist/engine/compaction.js

@@ -0,0 +1,226 @@
+/**
+ * Pure compaction mechanics (context-auto-compaction §3.6.1 / §3.6.2 / §5.3).
+ *
+ * NO I/O, NO CLOCK, NO PROVIDER KNOWLEDGE, NO `node:*` IMPORT. This module is
+ * the engine's whole contribution to compaction: where a history may safely be
+ * cut, which cut to take, and — the one that matters — whether a history the
+ * host handed back is structurally sendable at all.
+ *
+ * WHY THE ENGINE OWNS VALIDATION AND NOTHING ELSE (D-4). A compacted history
+ * that strands a `tool_result` without its `tool_call` is an immediate HTTP 400
+ * on Anthropic: `convertMessages` emits one `user` message carrying a
+ * `tool_use_id` per `tool_result`, and the API rejects a `tool_use_id` with no
+ * `tool_use` before it. That failure is not recoverable by the host and must not
+ * be recoverable BY POLICY — so the engine refuses to adopt an invalid history
+ * and continues with the original. A host bug becomes "compaction did not
+ * happen" rather than "the session is now permanently un-sendable" (R-2).
+ */
+import { estimatePromptTokens } from '../llm/output-limits.js';
+/**
+ * Every index at which the history may be split without stranding a tool call.
+ *
+ * `i` is SAFE iff, walking from 0, the set of open tool calls is empty at the
+ * boundary before `i` AND `messages[i]` is not a `tool_result`.
+ *
+ * A SET-BASED WALK RATHER THAN A ROLE-PATTERN RULE, and that is deliberate: the
+ * history is not always the clean `user -> assistant -> tool_result*` shape the
+ * loop produces. Steering interruption pushes synthesized `tool_result`s for the
+ * REMAINING calls in a batch, CodeAct injects a bare `user` message, and
+ * `/resume` restores whatever a file contained. A rule that encodes the happy
+ * path is a rule that produces an invalid splice on the one history that got
+ * interesting.
+ */
+export function findSafeCutIndices(messages) {
+    const safe = [];
+    const open = new Set();
+    for (let i = 0; i < messages.length; i += 1) {
+        const m = messages[i];
+        if (open.size === 0 && m.role !== 'tool_result')
+            safe.push(i);
+        if (m.role === 'assistant') {
+            for (const b of m.content)
+                if (b.type === 'tool_call')
+                    open.add(b.toolCallId);
+        }
+        else if (m.role === 'tool_result') {
+            open.delete(m.toolCallId);
+        }
+    }
+    if (open.size === 0)
+        safe.push(messages.length);
+    return safe;
+}
+/** A "turn" is a `user`-role message; `tool_result` is a separate role here. */
+function countTurns(messages, from) {
+    let turns = 0;
+    for (let i = from; i < messages.length; i += 1) {
+        if (messages[i].role === 'user')
+            turns += 1;
+    }
+    return turns;
+}
+/**
+ * The largest safe cut that still leaves at least `keepRecentTurns` complete
+ * turns in the tail, or `null` when there is nothing worth dropping.
+ *
+ * `null` — rather than a zero-length head — is what lets §3.8 turn "the recent
+ * turns alone exceed the threshold" into a bounded, loud outcome instead of a
+ * retry loop against a paid API.
+ */
+export function planCompaction(messages, opts) {
+    const keep = Math.max(1, Math.floor(opts.keepRecentTurns));
+    const protectedPrefix = Math.max(0, Math.floor(opts.protectedPrefix ?? 0));
+    const safe = findSafeCutIndices(messages);
+    for (let i = safe.length - 1; i >= 0; i -= 1) {
+        const cutIndex = safe[i];
+        // The tail must still be a conversation, not an empty suffix.
+        if (cutIndex >= messages.length)
+            continue;
+        const retainedTurns = countTurns(messages, cutIndex);
+        if (retainedTurns < keep)
+            continue;
+        if (cutIndex <= protectedPrefix)
+            return null;
+        return {
+            cutIndex,
+            droppedMessages: cutIndex - protectedPrefix,
+            retainedTurns,
+        };
+    }
+    return null;
+}
+/**
+ * THE GATE (§3.3 step 5). One walk, the same open-set as `findSafeCutIndices`.
+ *
+ * Also exported for the host's IDLE `/compact` path (§4.4 / D-25), which cannot
+ * reach the loop's gate because there is no loop — and D-4 declares that gate
+ * unbypassable.
+ */
+export function validateHistory(messages, opts = {}) {
+    if (!Array.isArray(messages) || messages.length === 0)
+        return { ok: false, reason: 'empty' };
+    if (opts.previousLength !== undefined && messages.length > opts.previousLength) {
+        return { ok: false, reason: 'grew' };
+    }
+    const open = new Set();
+    for (const m of messages) {
+        if (m.role === 'assistant') {
+            for (const b of m.content)
+                if (b.type === 'tool_call')
+                    open.add(b.toolCallId);
+        }
+        else if (m.role === 'tool_result') {
+            if (!open.has(m.toolCallId))
+                return { ok: false, reason: 'orphan_tool_result' };
+            open.delete(m.toolCallId);
+        }
+    }
+    if (open.size > 0)
+        return { ok: false, reason: 'unclosed_tool_call' };
+    return { ok: true };
+}
+/**
+ * Clip oversized `tool_result` bodies inside a retained tail until the whole
+ * history is projected under `targetTokens` — the last rung of the ladder
+ * (context-auto-compaction-hardening §3.3).
+ *
+ * WHY THIS EXISTS. Every other rung operates on the HEAD: summarize it, retry
+ * the summarization, drop it without a summary. When the TAIL is what does not
+ * fit — `keepRecentTurns` turns carrying several 100 KB tool results — each of
+ * those rungs reports success or `nothing_to_drop` while the history stays
+ * un-sendable, and the run dies with no rung left.
+ *
+ * FOUR RULES, EACH LOAD-BEARING:
+ *
+ *  1. ONLY `tool_result` BODIES ARE ELIGIBLE. Not `user` messages (the anchor
+ *     and the user's own instructions are the last things to damage), not
+ *     `assistant` messages (clipping the model's own reasoning mid-tail produces
+ *     a history that contradicts itself). The size argument is the bound: a tool
+ *     result is capped at 100 KB EACH with several per turn, while an assistant
+ *     message is capped by the turn's `maxOutputTokens`. The tail is blown by
+ *     results, not by calls.
+ *  2. OLDEST FIRST. The newest tool result is the one the next request is most
+ *     likely to be about, so the walk starts at `from` and stops the moment the
+ *     projection is under budget.
+ *  3. STRUCTURE IS NEVER CHANGED. No message is removed, no `toolCallId` is
+ *     touched, no role changes — so `validateHistory` cannot fail on a relieved
+ *     history that was valid before. That is what makes this safe to run AFTER a
+ *     splice, and it is the reason relief CLIPS rather than DROPS.
+ *  4. EVERY CLIP IS ANNOUNCED IN THE TEXT THE MODEL READS, at the exact place
+ *     the data was removed. A model that sees the marker knows the output is
+ *     partial and can re-run the tool; a model handed a silently truncated file
+ *     does not.
+ *
+ * PURE, AND IT DOES NOT MUTATE ITS INPUT. Untouched messages keep their identity
+ * in the returned array, which is what lets a caller assert "nothing before
+ * `from` changed" by reference rather than by deep equality.
+ */
+export function relieveTail(messages, opts) {
+    const out = [...messages];
+    const from = Math.max(0, Math.floor(opts.from));
+    const clipChars = Math.max(0, Math.floor(opts.clipChars));
+    let clippedMessages = 0;
+    let charsRemoved = 0;
+    // RE-ESTIMATED AFTER EVERY CLIP rather than decremented, and the cost is not
+    // the reason to worry about it: the array this walks is one retained tail, not
+    // a session. `estimatePromptTokens` rounds, so a hand-rolled running total
+    // would drift from the number the caller's budget check uses — and the whole
+    // point of this function is to land under THAT number.
+    let projected = estimatePromptTokens(out, opts.systemPrompt);
+    for (let i = from; i < out.length; i += 1) {
+        if (projected <= opts.targetTokens)
+            break;
+        const message = out[i];
+        if (message.role !== 'tool_result')
+            continue;
+        const clipped = clipToolResultContent(message.content, clipChars, opts.marker);
+        if (clipped === null)
+            continue;
+        out[i] = { ...message, content: clipped.content };
+        clippedMessages += 1;
+        charsRemoved += clipped.removed;
+        projected = estimatePromptTokens(out, opts.systemPrompt);
+    }
+    return { messages: out, clippedMessages, charsRemoved };
+}
+/**
+ * One `tool_result` body, clipped — or `null` when there was nothing to remove.
+ *
+ * A PART ARRAY IS CLIPPED LONGEST-FIRST, and only its `text` parts. `image`
+ * parts are left alone: the estimator charges them a flat rate that has nothing
+ * to do with their length, so clipping one removes characters without removing
+ * tokens, and re-encoding an image is a different feature.
+ */
+function clipToolResultContent(content, clipChars, marker) {
+    if (typeof content === 'string') {
+        if (content.length <= clipChars)
+            return null;
+        const removed = content.length - clipChars;
+        return { content: content.slice(0, clipChars) + marker(removed), removed };
+    }
+    if (!Array.isArray(content))
+        return null;
+    const order = content
+        .map((part, index) => ({ index, length: part.type === 'text' ? part.text.length : -1 }))
+        .filter((entry) => entry.length > clipChars)
+        .sort((a, b) => b.length - a.length);
+    if (order.length === 0)
+        return null;
+    const parts = [...content];
+    let total = parts.reduce((sum, p) => sum + (p.type === 'text' ? p.text.length : 0), 0);
+    let removed = 0;
+    for (const entry of order) {
+        if (total <= clipChars)
+            break;
+        const part = parts[entry.index];
+        if (part.type !== 'text')
+            continue;
+        const cut = part.text.length - clipChars;
+        parts[entry.index] = { type: 'text', text: part.text.slice(0, clipChars) + marker(cut) };
+        removed += cut;
+        total -= cut;
+    }
+    if (removed === 0)
+        return null;
+    return { content: parts, removed };
+}

package/dist/engine/context-manager.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The injected context-management port (context-auto-compaction §3.2).
+ *
+ * TYPES ONLY, ZERO LOGIC, and the only imports are erased type imports from
+ * `llm/types.js` and `agent-loop.js`. The engine does not know what a context
+ * window IS — `Agent` holds a `ModelRef`, never a `ModelInfo` — and it must not
+ * learn, because `ModelRegistry` lives one layer up and
+ * `no-host-coupling.test.ts` rule 2 forbids this package from reaching for a
+ * host. So the engine gains ONE port it calls at a turn boundary, and every
+ * decision behind it — the threshold, which model summarizes, what the summary
+ * asks for, what happens on failure — is made on the host's side of it (D-2).
+ */
+import type { Message, TokenUsage } from '../llm/types.js';
+import type { ModelRef } from './agent-loop.js';
+/** Why compaction is being considered right now. */
+export type CompactionTrigger = 'pressure' | 'overflow';
+/** What the engine can cheaply tell the host at a turn boundary. */
+export interface CompactionProbe {
+    readonly messageCount: number;
+    /**
+     * Authoritative usage of the most recently COMPLETED turn, or `undefined`
+     * before the first one (a fresh run, or the first turn after `/resume`).
+     *
+     * THE HOST MUST HANDLE `undefined` (§3.4.2). It is not an edge case: the most
+     * dangerous single moment in this feature's life is the first request of a
+     * resumed 180 k-token session, where there is no usage to read and the naive
+     * answer is "0 %".
+     */
+    readonly lastUsage?: TokenUsage;
+    /** 1-based index of the turn that is about to be sent. */
+    readonly turnIndex: number;
+    readonly trigger: CompactionTrigger;
+}
+export interface CompactionContext extends CompactionProbe {
+    /**
+     * A SHALLOW COPY of the engine's history, never the live array (P1-2).
+     *
+     * `MessageManager.getAll()` returns the internal array itself (the "readonly
+     * view" in its doc comment is a TYPE, not a copy). Passing that across the
+     * port would let a host that sorts, splices or truncates it corrupt engine
+     * state in place, BEFORE the structural gate at §3.3 step 5 can look at it —
+     * which would defeat the one job the engine has in this feature. One array
+     * allocation per compaction, i.e. at most `maxPerRun` per run, buys the whole
+     * guarantee.
+     */
+    readonly messages: readonly Message[];
+    readonly systemPrompt: string;
+    readonly model: ModelRef;
+    /**
+     * The run's signal. The host MUST forward it into its own LLM call.
+     *
+     * The engine does not TRUST that it does: `runCompaction` races this promise
+     * against the signal and against a hard ceiling (§3.3), because the watchdog
+     * is paused across the call and a non-settling promise would otherwise hang
+     * the run with the idle detector switched off (P1-3).
+     */
+    readonly signal: AbortSignal;
+}
+export type CompactionOutcome = {
+    action: 'keep';
+    reason: string;
+} | {
+    action: 'replace';
+    messages: Message[];
+    mode: 'summarized' | 'truncated';
+    /** For the event; the engine does not interpret it. */
+    summary?: string;
+    reason?: string;
+};
+export interface ContextManager {
+    /**
+     * SYNCHRONOUS, CHEAP, SIDE-EFFECT FREE. Called once per turn, before the LLM
+     * request is built.
+     *
+     * IT IS SYNCHRONOUS SO THAT "OFF" AND "BELOW THRESHOLD" COST NOTHING (D-3).
+     * A single async port would put an `await` — a microtask tick and a promise
+     * allocation — on every turn of every run for a decision that is `false` more
+     * than 99 % of the time, and would make it impossible to state that a session
+     * below the threshold is byte-identical to a pre-feature build.
+     */
+    shouldCompact(probe: CompactionProbe): boolean;
+    /**
+     * Only called when `shouldCompact` returned `true`.
+     *
+     * MUST NOT THROW. The engine wraps the call defensively anyway (§3.3 step 4),
+     * because a host that breaks its own contract must degrade to "compaction did
+     * not happen", never to "the run died" — but a throwing implementation is a
+     * bug on the host side and is reported as one through `compaction_end.reason`.
+     */
+    compact(ctx: CompactionContext): Promise<CompactionOutcome>;
+}

package/dist/engine/context-manager.js

@@ -0,0 +1,13 @@
+/**
+ * The injected context-management port (context-auto-compaction §3.2).
+ *
+ * TYPES ONLY, ZERO LOGIC, and the only imports are erased type imports from
+ * `llm/types.js` and `agent-loop.js`. The engine does not know what a context
+ * window IS — `Agent` holds a `ModelRef`, never a `ModelInfo` — and it must not
+ * learn, because `ModelRegistry` lives one layer up and
+ * `no-host-coupling.test.ts` rule 2 forbids this package from reaching for a
+ * host. So the engine gains ONE port it calls at a turn boundary, and every
+ * decision behind it — the threshold, which model summarizes, what the summary
+ * asks for, what happens on failure — is made on the host's side of it (D-2).
+ */
+export {};

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export type { ContentPart, TextContentPart, ImageContentPart, ContentBlock, Text
 export { THINKING_BUDGET } from './llm/types.js';
 export type { LLMProvider, LLMRequest, LLMErrorType, } from './llm/provider.js';
 export { LLMError, classifyHttpError, wrapFetchError, } from './llm/provider.js';
-export { DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, ABSOLUTE_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, CONTEXT_SAFETY_MARGIN_TOKENS, resolveOutputTokens, staticCeilingFor, learnModelCeiling, getLearnedCeiling, clearLearnedCeilings, estimatePromptTokens, } from './llm/output-limits.js';
+export { DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, ABSOLUTE_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, CONTEXT_SAFETY_MARGIN_TOKENS, resolveOutputTokens, staticCeilingFor, learnModelCeiling, getLearnedCeiling, clearLearnedCeilings, estimatePromptTokens, CHARS_PER_TOKEN, } from './llm/output-limits.js';
 export type { OutputLimitInput, OutputLimitResolution, CeilingSource, } from './llm/output-limits.js';
 export { classifyOutputLimitFailure, sendWithOutputLimitRecovery, learnTokenField, getLearnedTokenField, clearLearnedTokenFields, } from './llm/output-limit-recovery.js';
 export { RETRY_LIMITS, DEFAULT_RETRY_POLICY, isRetryableError, computeBackoffDelay, parseRetryAfterMs, withRetry, } from './llm/retry.js';
@@ -41,7 +41,7 @@ export { createSkillFindTool } from './skills/skill-find-tool.js';
 export { computeToolPolicy, evaluateToolCall } from './skills/tool-policy.js';
 export { SKILL_CATALOG_MAX_BYTES, SKILL_BODY_MAX_BYTES, SKILL_RESULT_MAX_BYTES, ALWAYS_SKILLS_MAX_BYTES, SKILL_MD_MAX_BYTES, SKILL_DESC_LINE_MAX, SKILL_FILES_MAX, SKILL_FIND_MAX_BYTES, SKILL_NAME_PATTERN, } from './skills/constants.js';
 export type { SkillScope, SkillActivation, SkillFrontmatter, SkillRecord, SkillFileRef, SkillHost, SkillManifest, SkillValidationIssue, SkillCatalogOptions, SkillBodyOptions, SkillFindOptions, SkillIntegrity, SkillUsageStat, SkillUsageMap, SkillInvocationOptions, SkillPlatform, SkillPolicyView, SkillToolPolicyMode, ToolPolicyDecision, ToolPolicyInput, ToolPolicySource, ToolPolicyVerdict, } from './skills/types.js';
-export type { AgentEvent, AgentEventListener, AgentStartEvent, AgentEndEvent, TurnStartEvent, TurnEndEvent, MessageUpdateEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, CodeExecutionStartEvent, CodeExecutionEndEvent, } from './types.js';
+export type { AgentEvent, AgentEventListener, AgentStartEvent, AgentEndEvent, TurnStartEvent, TurnEndEvent, MessageUpdateEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, CodeExecutionStartEvent, CodeExecutionEndEvent, CompactionStartEvent, CompactionEndEvent, } from './types.js';
 export { Agent } from './engine/agent.js';
 export type { AgentConfig, AgentState } from './engine/agent.js';
 export type { ModelRef } from './engine/agent-loop.js';
@@ -49,5 +49,8 @@ export type { CodeActSandbox, CodeActResult } from './engine/agent-loop.js';
 export { MessageManager } from './engine/message-manager.js';
 export { MessageQueueManager } from './engine/steering.js';
 export { IdleWatchdog } from './engine/watchdog.js';
+export { findSafeCutIndices, planCompaction, relieveTail, validateHistory, } from './engine/compaction.js';
+export type { CompactionPlan, HistoryCheck, PlanCompactionOptions, TailReliefOptions, TailReliefResult, ValidateHistoryOptions, } from './engine/compaction.js';
+export type { ContextManager, CompactionProbe, CompactionContext, CompactionOutcome, CompactionTrigger, } from './engine/context-manager.js';
 export type { SandboxConfig, ExecuteOptions, ExecuteResult, ConsoleEntry, SandboxToolCall, } from './sandbox/types.js';
 export { Agent as AragonAgent } from './engine/agent.js';

package/dist/index.js

@@ -11,7 +11,11 @@ export { LLMError, classifyHttpError, wrapFetchError, } from './llm/provider.js'
 // Output-token limits — the authority for "how many tokens may this model
 // produce". Every adapter resolves through here; nothing else spells 64000.
 // ---------------------------------------------------------------------------
-export { DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, ABSOLUTE_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, CONTEXT_SAFETY_MARGIN_TOKENS, resolveOutputTokens, staticCeilingFor, learnModelCeiling, getLearnedCeiling, clearLearnedCeilings, estimatePromptTokens, } from './llm/output-limits.js';
+export { DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, ABSOLUTE_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, CONTEXT_SAFETY_MARGIN_TOKENS, resolveOutputTokens, staticCeilingFor, learnModelCeiling, getLearnedCeiling, clearLearnedCeilings, estimatePromptTokens, 
+// Promoted from module-private for the compaction digest's budget arithmetic
+// (context-auto-compaction P2-3): two chars-per-token constants that must agree
+// and nothing checking that they do is how a budget and an estimate drift.
+CHARS_PER_TOKEN, } from './llm/output-limits.js';
 export { classifyOutputLimitFailure, sendWithOutputLimitRecovery, learnTokenField, getLearnedTokenField, clearLearnedTokenFields, } from './llm/output-limit-recovery.js';
 // ---------------------------------------------------------------------------
 // Retry & exponential backoff — the authority for "a provider call failed, now
@@ -71,6 +75,19 @@ export { Agent } from './engine/agent.js';
 export { MessageManager } from './engine/message-manager.js';
 export { MessageQueueManager } from './engine/steering.js';
 export { IdleWatchdog } from './engine/watchdog.js';
+// ---------------------------------------------------------------------------
+// Context compaction (context-auto-compaction §4.1)
+//
+// THREE PURE FUNCTIONS AND FIVE TYPES. The mechanism is here; the policy — the
+// threshold, the summarizer, the prompt, the failure ladder — belongs to the
+// host, because this package has no `ModelInfo` and must not learn one (D-2).
+//
+// `validateHistory` is public for a specific reason: a host that splices while
+// the agent is IDLE cannot reach the loop's own gate, and D-4 declares that gate
+// unbypassable. Exporting it is what makes honouring D-4 on the manual path cost
+// three lines instead of a second implementation.
+// ---------------------------------------------------------------------------
+export { findSafeCutIndices, planCompaction, relieveTail, validateHistory, } from './engine/compaction.js';
 // Sandbox exports are NOT re-exported here — isolated-vm is incompatible with Electron's V8.
 // Import directly from './sandbox/*.js' when needed (lazy loading only).
 // ---------------------------------------------------------------------------

package/dist/llm/output-limits.d.ts

@@ -96,6 +96,16 @@ export interface OutputLimitResolution {
  * `0` or a negative.
  */
 export declare function resolveOutputTokens(input: OutputLimitInput): OutputLimitResolution;
+/**
+ * Average characters per token across the model families this package speaks to.
+ *
+ * EXPORTED (context-auto-compaction P2-3). It was module-private, which would
+ * have forced the CLI's compaction digest to grow a second copy for its budget
+ * arithmetic — two chars-per-token constants that must agree and nothing
+ * checking that they do is exactly how a digest budget and an occupancy estimate
+ * drift apart. No behaviour change here.
+ */
+export declare const CHARS_PER_TOKEN = 4;
 /**
  * Deliberately crude: ~4 chars/token plus per-message framing. Used ONLY to keep
  * `max_tokens + prompt <= context` on OpenAI, where being 20 % wrong is absorbed

package/dist/llm/output-limits.js

@@ -222,8 +222,16 @@ export function resolveOutputTokens(input) {
 // ---------------------------------------------------------------------------
 // Prompt estimation
 // ---------------------------------------------------------------------------
-/** Average characters per token across the model families this package speaks to. */
-const CHARS_PER_TOKEN = 4;
+/**
+ * Average characters per token across the model families this package speaks to.
+ *
+ * EXPORTED (context-auto-compaction P2-3). It was module-private, which would
+ * have forced the CLI's compaction digest to grow a second copy for its budget
+ * arithmetic — two chars-per-token constants that must agree and nothing
+ * checking that they do is exactly how a digest budget and an occupancy estimate
+ * drift apart. No behaviour change here.
+ */
+export const CHARS_PER_TOKEN = 4;
 /** Role markers, separators and tool-call scaffolding, per message. */
 const PER_MESSAGE_OVERHEAD_TOKENS = 4;
 function partLength(content) {

package/dist/tools/executor.d.ts

@@ -19,6 +19,20 @@ export interface ToolExecutorOptions {
     timeoutOverrides?: Record<string, number>;
     /** Maximum size (in bytes) of combined text output before truncation. Defaults to 100_000 (100 KB). */
     maxOutputSize?: number;
+    /**
+     * How long, after an abort is signalled, a tool has to settle before its
+     * promise is ABANDONED and an error result is returned in its place.
+     * Defaults to 5000.
+     *
+     * THE INVARIANT BEING PROTECTED IS "AN ABORT IS ALWAYS ANSWERABLE", AND AN
+     * INVARIANT THAT DEPENDS ON EVERY TOOL AUTHOR REMEMBERING IS NOT AN
+     * INVARIANT. Step 5 below used to be a bare `await tool.execute(...)`: the
+     * signal was delivered, the tool was free to ignore it, and the loop waited
+     * forever — so the host's "press Esc to stop" did nothing at all in exactly
+     * the situation where a user most needs it. Racing here makes the guarantee a
+     * property of the executor rather than of the toolset it happens to be given.
+     */
+    abortGraceMs?: number;
 }
 /**
  * Executes tool calls with validation, timeout management,
@@ -30,6 +44,7 @@ export declare class ToolExecutor {
     private readonly defaultTimeout;
     private readonly timeoutOverrides;
     private readonly maxOutputSize;
+    private readonly abortGraceMs;
     constructor(registry: ToolRegistry, options?: ToolExecutorOptions);
     /**
      * Execute a tool call end-to-end.