atom-agent 0.3.0 → 1.1.0

package/dist/context-manager.js

@@ -0,0 +1,564 @@
+// ContextManager — the single place that answers, for one model:
+//   - How much context is available?      (budget())
+//   - How much is currently used?         (usage())
+//   - Should we compact?                  (needsCompaction())
+//   - What messages should be sent?       (trimForSend())
+//
+// Budget derivation (no fixed-200K assumption): the history allowance comes
+// from the model's ACTUAL verified context window:
+//
+//   available history = window − system prompt − tool definitions
+//                       − expected output reserve − safety margin
+//
+// measured in tokens via the shared 4ch/token estimator. A model with a 1M
+// window therefore gets ~1M of usable history instead of ~50K tokens.
+//
+// Hard safety ceiling (configurable, never primary): env ATOM_MAX_HISTORY_*
+// and atom.json maxHistory* still resolve through historyCharSource /
+// historyMessageSource. The ceiling only ever CAPS the derived budget — with
+// nothing configured it never binds for known-window models. Models with NO
+// verified window keep the legacy 200K-char / 100-message behavior exactly
+// (a window is never invented; auto-compact stays off for them).
+//
+// Layering: this module owns measurement + budget math. It imports
+// context-windows (metadata) and config (file fallback) at runtime, and
+// zen.js types ONLY (no runtime cycle — zen.ts imports this module for its
+// loop trim). The agent loop, compaction mechanics, and providers are
+// untouched: truncateHistory/shouldAutoCompact/compactPct keep working via
+// re-exports from their original modules.
+//
+// Prompt-caching foundation (NOT implemented): all inputs here are explicit
+// values (system/tools/history split, measured sizes, stable options), so a
+// future cache layer can key stable prefixes (system + tools) without
+// re-architecting call sites. No cache state lives here yet by design.
+import { contextWindowFor } from "./context-windows.js";
+import { loadAtomConfig } from "./config.js";
+// ---- Units ----
+// Shared chars-per-token estimator (opencode's 4ch/token preflight
+// heuristic). Floors to whole tokens; never used for billed spend, only for
+// sizing decisions and display.
+export const CHARS_PER_TOKEN = 4;
+export function estimateTokensForChars(chars) {
+    const c = Number.isFinite(chars) && chars > 0 ? Math.floor(chars) : 0;
+    return Math.floor(c / CHARS_PER_TOKEN);
+}
+// Deterministic size of one message: string content counts as-is, anything
+// else counts stringified; assistant tool_calls and tool ids count too (they
+// ride on every POST). History chars = the sum over all messages.
+export function messageChars(m) {
+    let n = 0;
+    const content = m.content;
+    if (typeof content === "string") {
+        n += content.length;
+    }
+    else if (content !== null && content !== undefined) {
+        n += JSON.stringify(content).length;
+    }
+    if (m.role === "assistant") {
+        if (m.tool_calls !== undefined)
+            n += JSON.stringify(m.tool_calls).length;
+    }
+    else if (m.role === "tool") {
+        n += m.tool_call_id.length;
+    }
+    return n;
+}
+export function historyChars(history) {
+    const state = ledgerFor(history);
+    if (state)
+        return state.chars;
+    let total = 0;
+    for (const m of history)
+        total += messageChars(m);
+    return total;
+}
+// Load = last POST's reported prompt_tokens when available, else the
+// 4ch/token estimate of the sent history chars.
+export function computeContextLoad(lastPromptTokens, sentHistoryChars) {
+    if (typeof lastPromptTokens === "number" &&
+        Number.isFinite(lastPromptTokens) &&
+        lastPromptTokens >= 0) {
+        return Math.floor(lastPromptTokens);
+    }
+    return estimateTokensForChars(sentHistoryChars);
+}
+// ---- Safety-ceiling sources (env > atom.json > compiled default) ----
+export const MAX_HISTORY_MESSAGES = 100;
+export const MAX_HISTORY_CHARS = 200_000;
+function clampInt(n, min, max) {
+    return Math.min(Math.max(Math.floor(n), min), max);
+}
+function envInt(raw) {
+    if (raw === undefined)
+        return undefined;
+    const text = raw.trim();
+    if (!/^\d+$/.test(text))
+        return undefined;
+    const n = Number(text);
+    return Number.isFinite(n) ? Math.floor(n) : undefined;
+}
+// Message-count ceiling source. `explicit` tells whether a human configured
+// it (env or file) as opposed to the compiled default.
+export function historyMessageSource() {
+    const env = envInt(process.env.ATOM_MAX_HISTORY_MESSAGES);
+    if (env !== undefined)
+        return { value: clampInt(env, 10, 1000), explicit: true };
+    const file = loadAtomConfig().config.maxHistoryMessages;
+    if (file !== undefined)
+        return { value: file, explicit: true };
+    return { value: MAX_HISTORY_MESSAGES, explicit: false };
+}
+// Char-count safety ceiling source. Same explicit contract.
+export function historyCharSource() {
+    const env = envInt(process.env.ATOM_MAX_HISTORY_CHARS);
+    if (env !== undefined)
+        return { value: clampInt(env, 10_000, 2_000_000), explicit: true };
+    const file = loadAtomConfig().config.maxHistoryChars;
+    if (file !== undefined)
+        return { value: file, explicit: true };
+    return { value: MAX_HISTORY_CHARS, explicit: false };
+}
+// Legacy accessors (env → file → default). Kept for the loop's legacy path
+// and existing callers; the manager uses the sources above so it can tell
+// configured ceilings apart from defaults.
+export function historyMessageBudget() {
+    return historyMessageSource().value;
+}
+export function historyCharBudget() {
+    return historyCharSource().value;
+}
+// ---- Compaction threshold (moved here: the manager owns "should compact") ----
+export const COMPACT_PCT_DEFAULT = 0.83;
+function clampPctPercent(n) {
+    return Math.min(Math.max(n, 50), 95) / 100;
+}
+// Auto-compact threshold as a fraction (default 0.83). Precedence: env
+// ATOM_COMPACT_PCT percent (e.g. "83", clamped 50–95) → atom.json compactPct
+// → default; invalid/unset falls through.
+export function compactPct() {
+    const raw = process.env.ATOM_COMPACT_PCT;
+    if (raw !== undefined) {
+        const text = raw.trim();
+        if (/^\d+(\.\d+)?$/.test(text)) {
+            const n = Number(text);
+            if (Number.isFinite(n))
+                return clampPctPercent(n);
+        }
+    }
+    const file = loadAtomConfig().config.compactPct;
+    if (file !== undefined)
+        return file / 100;
+    return COMPACT_PCT_DEFAULT;
+}
+export function shouldAutoCompact(load, model, pctOverride) {
+    const window = contextWindowFor(model);
+    if (window === undefined)
+        return false; // never invent a window
+    const pct = typeof pctOverride === "number" && Number.isFinite(pctOverride)
+        ? pctOverride
+        : compactPct();
+    return load / window >= pct;
+}
+// Searchable text for todo matching: message content plus the assistant's
+// tool_calls payload (todowrite CALLS carry the list, tool RESULTS echo it).
+// Tool call ids are NOT searched — they are pairing keys, not goal text, so
+// a todo that reads like an id can never false-pin a turn.
+function todoHaystack(m) {
+    let hay = "";
+    const content = m.content;
+    if (typeof content === "string")
+        hay += content;
+    if (m.role === "assistant" && m.tool_calls !== undefined) {
+        try {
+            hay += JSON.stringify(m.tool_calls);
+        }
+        catch {
+            // unstringifiable payload pins nothing
+        }
+    }
+    return hay;
+}
+function turnMentionsTodo(history, start, end, needles) {
+    for (let i = start; i < end; i++) {
+        const hay = todoHaystack(history[i]);
+        if (hay.length === 0)
+            continue;
+        for (const n of needles) {
+            if (n.length > 0 && hay.includes(n))
+                return true;
+        }
+    }
+    return false;
+}
+// Drop oldest user-turns until history fits BOTH caps (message count AND
+// total chars, each plus the caller's `reserve` headroom for a message it is
+// about to push). A user turn = the `user` message plus all following
+// messages up to (excluding) the next `user` message, so assistant
+// tool_calls always stay paired with their tool results across all three
+// wire formats. NEVER drops history[0] (system prompt), the first user turn
+// (the task prompt — the goal a long run must never forget), any turn that
+// still quotes a CURRENT open todo, or the latest turn (the one being
+// sent/built). Budget-aware edge: when the pinned content alone (first turn
+// + todo turns + latest) already exceeds a cap, there is nothing left to
+// drop — stop and still send (same never-drop-the-live-turn principle).
+// Mutates `history` in place via splice (so caller indices captured after
+// this call stay valid) and, when at least one turn dropped, fires ONE
+// `notify` (the caller surfaces it dim in the TUI); silence otherwise.
+// Returns what was dropped.
+export function truncateHistoryWithCaps(history, caps, opts) {
+    const result = { droppedTurns: 0, droppedMessages: 0 };
+    if (history.length <= 1)
+        return result;
+    const maxMessages = caps.maxMessages;
+    const maxChars = caps.maxChars;
+    const reserve = opts?.reserve;
+    const needles = opts?.todoNeedles ?? [];
+    const roomMessages = reserve?.messages !== undefined && Number.isFinite(reserve.messages)
+        ? Math.max(0, Math.floor(reserve.messages))
+        : 0;
+    const roomChars = reserve?.chars !== undefined && Number.isFinite(reserve.chars)
+        ? Math.max(0, reserve.chars)
+        : 0;
+    for (;;) {
+        const over = history.length + roomMessages > maxMessages ||
+            historyChars(history) + roomChars > maxChars;
+        if (!over)
+            break;
+        // Turn boundaries over history[1..]: each turn starts at a `user`
+        // message (the oldest slice starts at 1 even when it isn't one, matching
+        // the pre-pin drop unit). Whole-turn drops keep assistant/tool pairing.
+        const starts = [1];
+        for (let i = 2; i < history.length; i++) {
+            if (history[i]?.role === "user")
+                starts.push(i);
+        }
+        // Oldest NON-pinned, non-latest turn goes first: the first turn (task
+        // prompt) and any turn still quoting a current open todo stay, and the
+        // latest turn is never dropped. No candidate means pinned content alone
+        // is over budget — stop and send it as-is (see edge above).
+        let drop = -1;
+        for (let t = 0; t < starts.length; t++) {
+            if (t === starts.length - 1)
+                continue; // latest turn
+            if (t === 0)
+                continue; // task prompt
+            const end = t + 1 < starts.length ? starts[t + 1] : history.length;
+            if (needles.length > 0 && turnMentionsTodo(history, starts[t], end, needles))
+                continue;
+            drop = t;
+            break;
+        }
+        if (drop === -1)
+            break;
+        const end = drop + 1 < starts.length ? starts[drop + 1] : history.length;
+        const removed = history.splice(starts[drop], end - starts[drop]);
+        result.droppedTurns += 1;
+        result.droppedMessages += removed.length;
+    }
+    if (result.droppedTurns > 0) {
+        try {
+            opts?.notify?.(`(history truncated: dropped ${result.droppedTurns} oldest turn(s))`);
+        }
+        catch {
+            // observer errors never break the loop
+        }
+    }
+    return result;
+}
+// ---- Budget derivation ----
+// Expected completion/output reserve: one full summary-sized generation must
+// always fit alongside history (mirrors the compaction output cap).
+export const OUTPUT_RESERVE_TOKENS = 4096;
+// Safety headroom below the raw window: the trim cap never plans to use the
+// last 5% (auto-compact at ~83% fires long before this matters — the margin
+// is the last defense, not the trigger).
+export const SAFETY_MARGIN_PCT = 0.05;
+// Default safety ceiling when nothing is configured AND no window is known
+// (the legacy 200K-char budget, preserved byte-for-byte as fallback).
+export const HARD_CEILING_FLOOR_CHARS = 200_000;
+export function createContextManager(opts) {
+    const model = opts.model;
+    const toolsChars = opts.toolsChars ?? 0;
+    const reserveTokens = opts.outputReserveTokens ?? OUTPUT_RESERVE_TOKENS;
+    const marginPct = opts.safetyMarginPct ?? SAFETY_MARGIN_PCT;
+    const pct = opts.compactPct ?? compactPct();
+    function ceilingChars() {
+        if (opts.hardCeilingChars !== undefined) {
+            return { value: opts.hardCeilingChars, explicit: opts.hardCeilingExplicit ?? true };
+        }
+        return historyCharSource();
+    }
+    function budget(history) {
+        const window = contextWindowFor(model);
+        const stats = ledgerStats(history);
+        const systemTokens = estimateTokensForChars(stats.systemChars);
+        const toolsTokens = estimateTokensForChars(Math.max(0, Math.floor(toolsChars)));
+        const margin = window !== undefined ? Math.floor(window * marginPct) : 0;
+        const historyTokens = window !== undefined
+            ? Math.max(0, window - systemTokens - toolsTokens - reserveTokens - margin)
+            : undefined;
+        const historyCharsCap = historyTokens !== undefined ? historyTokens * CHARS_PER_TOKEN : undefined;
+        const ceil = ceilingChars();
+        const ceilMsgs = opts.hardCeilingMessages ?? historyMessageSource().value;
+        // The ceiling only ever CAPS: with nothing configured the derived budget
+        // rules (large windows stay usable); an explicit ceiling still binds as
+        // the safety net it is. Unknown windows fall back to the legacy floor.
+        const effectiveMaxChars = historyCharsCap !== undefined
+            ? ceil.explicit
+                ? Math.min(historyCharsCap, ceil.value)
+                : historyCharsCap
+            : ceil.explicit
+                ? ceil.value
+                : HARD_CEILING_FLOOR_CHARS;
+        return {
+            windowTokens: window,
+            systemTokens,
+            toolsTokens,
+            outputReserveTokens: reserveTokens,
+            safetyMarginTokens: margin,
+            historyTokens,
+            historyChars: historyCharsCap,
+            hardCeilingChars: ceil.value,
+            hardCeilingExplicit: ceil.explicit,
+            hardCeilingMessages: ceilMsgs,
+            effectiveMaxChars,
+            effectiveMaxMessages: ceilMsgs,
+        };
+    }
+    function usage(history, lastPromptTokens) {
+        const s = ledgerStats(history);
+        const loadTokens = computeContextLoad(lastPromptTokens, s.chars);
+        const window = contextWindowFor(model);
+        return {
+            historyChars: s.chars,
+            historyMessages: s.messages,
+            userTurns: s.userMessages,
+            loadTokens,
+            loadPct: window !== undefined ? Math.round((100 * loadTokens) / window) : undefined,
+        };
+    }
+    function needsCompaction(loadTokens) {
+        return shouldAutoCompact(loadTokens, model, pct);
+    }
+    function trimForSend(history, notify, reserve, todoNeedles = []) {
+        const b = budget(history);
+        return truncateHistoryWithCaps(history, { maxMessages: b.effectiveMaxMessages, maxChars: b.effectiveMaxChars }, { notify, reserve, todoNeedles });
+    }
+    return { model, budget, usage, needsCompaction, trimForSend };
+}
+const ledgerByRaw = new WeakMap();
+const ledgerByProxy = new WeakMap();
+const footprints = new WeakMap();
+function bucketOf(role) {
+    return role === "system" || role === "user" || role === "assistant" || role === "tool"
+        ? role
+        : "other";
+}
+function footprintOf(m) {
+    if (typeof m !== "object" || m === null)
+        return { chars: 0, role: "other" };
+    const cached = footprints.get(m);
+    if (cached)
+        return cached;
+    const fp = {
+        chars: messageChars(m),
+        role: bucketOf(m.role),
+    };
+    footprints.set(m, fp);
+    return fp;
+}
+function addFootprint(state, m) {
+    if (typeof m !== "object" || m === null)
+        return;
+    const fp = footprintOf(m);
+    state.chars += fp.chars;
+    if (fp.role === "system")
+        state.systemChars += fp.chars;
+    else if (fp.role === "user")
+        state.userMessages += 1;
+    else if (fp.role === "assistant")
+        state.assistantMessages += 1;
+    else if (fp.role === "tool") {
+        state.toolMessages += 1;
+        state.toolChars += fp.chars;
+    }
+}
+function removeFootprint(state, m) {
+    if (typeof m !== "object" || m === null)
+        return;
+    const fp = footprintOf(m);
+    state.chars -= fp.chars;
+    if (fp.role === "system")
+        state.systemChars -= fp.chars;
+    else if (fp.role === "user")
+        state.userMessages -= 1;
+    else if (fp.role === "assistant")
+        state.assistantMessages -= 1;
+    else if (fp.role === "tool") {
+        state.toolMessages -= 1;
+        state.toolChars -= fp.chars;
+    }
+}
+function isArrayIndex(prop) {
+    if (typeof prop !== "string")
+        return false;
+    if (!/^(0|[1-9]\d*)$/.test(prop))
+        return false;
+    return Number(prop) < 4294967295;
+}
+function toArrayLength(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0)
+        return 0;
+    return Math.min(Math.floor(n), 4294967295);
+}
+function snapshotOf(state) {
+    return {
+        messages: state.messages,
+        chars: state.chars,
+        tokens: estimateTokensForChars(state.chars),
+        systemChars: state.systemChars,
+        toolChars: state.toolChars,
+        userMessages: state.userMessages,
+        assistantMessages: state.assistantMessages,
+        toolMessages: state.toolMessages,
+    };
+}
+// Wrap a history array for incremental accounting (idempotent — wrapping an
+// already-tracked array returns it as-is). ALWAYS use the return value: the
+// caller must drop its raw reference so every later mutation flows through
+// the proxy traps.
+export function trackHistory(history) {
+    if (ledgerByProxy.has(history))
+        return history;
+    const rebound = ledgerByRaw.get(history);
+    if (rebound)
+        return rebound.proxy;
+    const state = {
+        proxy: [],
+        messages: 0,
+        chars: 0,
+        systemChars: 0,
+        toolChars: 0,
+        userMessages: 0,
+        assistantMessages: 0,
+        toolMessages: 0,
+    };
+    for (const m of history)
+        addFootprint(state, m);
+    state.messages = history.length;
+    const proxy = new Proxy(history, {
+        set(target, prop, value) {
+            if (prop === "length") {
+                const newLen = toArrayLength(value);
+                const oldLen = target.length;
+                if (newLen < oldLen) {
+                    for (let i = newLen; i < oldLen; i++)
+                        removeFootprint(state, target[i]);
+                }
+                const ok = Reflect.set(target, prop, value);
+                state.messages = target.length;
+                return ok;
+            }
+            if (isArrayIndex(prop)) {
+                const i = Number(prop);
+                if (i < target.length)
+                    removeFootprint(state, target[i]);
+                addFootprint(state, value);
+            }
+            const ok = Reflect.set(target, prop, value);
+            state.messages = target.length;
+            return ok;
+        },
+        deleteProperty(target, prop) {
+            if (isArrayIndex(prop)) {
+                const i = Number(prop);
+                if (i < target.length)
+                    removeFootprint(state, target[i]);
+            }
+            return Reflect.deleteProperty(target, prop);
+        },
+        defineProperty(target, prop, descriptor) {
+            if (prop === "length" || isArrayIndex(prop)) {
+                const had = typeof prop === "string" && isArrayIndex(prop) && Number(prop) < target.length
+                    ? target[Number(prop)]
+                    : undefined;
+                const ok = Reflect.defineProperty(target, prop, descriptor);
+                if (had !== undefined)
+                    removeFootprint(state, had);
+                if ("value" in descriptor)
+                    addFootprint(state, descriptor.value);
+                state.messages = target.length;
+                return ok;
+            }
+            return Reflect.defineProperty(target, prop, descriptor);
+        },
+    });
+    state.proxy = proxy;
+    ledgerByRaw.set(history, state);
+    ledgerByProxy.set(proxy, state);
+    return proxy;
+}
+function ledgerFor(history) {
+    return ledgerByProxy.get(history) ?? ledgerByRaw.get(history);
+}
+// O(1) snapshot of a TRACKED array. Untracked arrays (tests, transient
+// copies) fall back to an exact full scan — always correct, just O(n).
+export function ledgerStats(history) {
+    const state = ledgerFor(history);
+    if (state)
+        return snapshotOf(state);
+    return scanHistory(history);
+}
+// Independent O(n) reference implementation (never touches the footprint
+// cache, so cache bugs cannot hide from it). Holes (deleted indices) count
+// as empty: the pre-ledger messageChars crashes on them, but tracked arrays
+// can hold holes after `delete`, so the reference must stay total. Tests
+// diff stats() against this after every op sequence.
+export function scanHistory(history) {
+    let chars = 0;
+    let systemChars = 0;
+    let toolChars = 0;
+    let user = 0;
+    let assistant = 0;
+    let tool = 0;
+    for (const m of history) {
+        if (m === undefined)
+            continue;
+        const c = messageChars(m);
+        chars += c;
+        const role = m?.role;
+        if (role === "user")
+            user += 1;
+        else if (role === "assistant")
+            assistant += 1;
+        else if (role === "tool") {
+            tool += 1;
+            toolChars += c;
+        }
+        else if (role === "system")
+            systemChars += c;
+    }
+    return {
+        messages: history.length,
+        chars,
+        tokens: estimateTokensForChars(chars),
+        systemChars,
+        toolChars,
+        userMessages: user,
+        assistantMessages: assistant,
+        toolMessages: tool,
+    };
+}
+// Full independent verification: true when the incremental counters exactly
+// match a fresh scan. Tests assert this; prod hot paths never pay for it.
+export function verifyLedger(history) {
+    const live = ledgerStats(history);
+    const ref = scanHistory(history);
+    const mismatches = [];
+    Object.keys(ref).forEach((k) => {
+        if (live[k] !== ref[k])
+            mismatches.push(`${k}: ledger=${live[k]} scan=${ref[k]}`);
+    });
+    return { ok: mismatches.length === 0, mismatches };
+}