@hmharness/kernel 0.3.0 → 0.4.0

package/dist/context.d.ts

@@ -3,9 +3,36 @@
  * Char-budget context compaction. Long agent runs are dominated by stale
  * tool output; when the transcript exceeds its budget we replace the oldest
  * tool results (never the system prompt, never the task itself, never the
- * recent tail) with a tombstone. Deterministic, no model call, no surprise.
+ * recent tail) with a tombstone. Deterministic baseline, no model call.
+ *
+ * Rolling digest (model-aware context engineering, part 3): with a
+ * `summarize` hook, evicted content is first distilled into a persistent
+ * "[rolling digest]" system note that survives future compactions and
+ * merges with prior digests - the conversation's past shrinks semantically
+ * instead of being dropped. Without the hook, behaviour is byte-identical
+ * to the legacy prune.
  */
 import type { ChatMessage } from './types.ts';
 export declare const DEFAULT_CONTEXT_CHARS = 160000;
 export declare function transcriptChars(messages: ChatMessage[]): number;
+export declare const DIGEST_MARK = "[rolling digest of earlier context]";
 export declare function compactMessages(messages: ChatMessage[], budget?: number): ChatMessage[];
+export interface CompactResult {
+    messages: ChatMessage[];
+    /** Chars of tool output actually evicted this pass (0 = no compaction). */
+    evictedChars: number;
+}
+/** Deterministic prune + tombstone; reports what was evicted so callers can
+ *  feed it to a summarizer. */
+export declare function compactWithEvictions(messages: ChatMessage[], budget?: number): CompactResult;
+/**
+ * Compact with a rolling digest. The digest is ONE system note placed right
+ * after the first user message (inside the protected head), so it survives
+ * every future compaction. Each pass merges: summarize(previous digest body
+ * + newly evicted tool outputs). Summarizer failures degrade silently to
+ * the deterministic prune (the digest just stops growing).
+ */
+export declare function compactWithDigest(messages: ChatMessage[], budget: number, summarize: (input: {
+    previousDigest: string | null;
+    evicted: string[];
+}) => Promise<string>): Promise<ChatMessage[]>;

package/dist/context.js

@@ -18,6 +18,10 @@ function protectedRange(messages) {
         keep.add(i);
     return keep;
 }
+export const DIGEST_MARK = '[rolling digest of earlier context]';
+function findDigest(messages) {
+    return messages.findIndex((m) => m.role === 'system' && typeof m.content === 'string' && m.content.startsWith(DIGEST_MARK));
+}
 export function compactMessages(messages, budget = DEFAULT_CONTEXT_CHARS) {
     if (transcriptChars(messages) <= budget)
         return messages;
@@ -30,3 +34,61 @@ export function compactMessages(messages, budget = DEFAULT_CONTEXT_CHARS) {
     }
     return out;
 }
+/** Deterministic prune + tombstone; reports what was evicted so callers can
+ *  feed it to a summarizer. */
+export function compactWithEvictions(messages, budget = DEFAULT_CONTEXT_CHARS) {
+    if (transcriptChars(messages) <= budget)
+        return { messages, evictedChars: 0 };
+    const keep = protectedRange(messages);
+    const out = messages.map((m) => ({ ...m }));
+    let evicted = 0;
+    for (let i = 0; i < out.length && transcriptChars(out) > budget; i++) {
+        if (keep.has(i) || out[i].role !== 'tool')
+            continue;
+        evicted += out[i].content?.length ?? 0;
+        out[i] = { ...out[i], content: '[context pruned: earlier tool output removed to fit budget]' };
+    }
+    return { messages: out, evictedChars: evicted };
+}
+/**
+ * Compact with a rolling digest. The digest is ONE system note placed right
+ * after the first user message (inside the protected head), so it survives
+ * every future compaction. Each pass merges: summarize(previous digest body
+ * + newly evicted tool outputs). Summarizer failures degrade silently to
+ * the deterministic prune (the digest just stops growing).
+ */
+export async function compactWithDigest(messages, budget, summarize) {
+    const { messages: pruned, evictedChars } = compactWithEvictions(messages, budget);
+    if (evictedChars === 0)
+        return pruned;
+    const digestIdx = findDigest(pruned);
+    const previousDigest = digestIdx >= 0 ? (pruned[digestIdx].content ?? '').slice(DIGEST_MARK.length).trim() : null;
+    const evicted = [];
+    // what was evicted = tombstoned positions vs the input (compare by index)
+    for (let i = 0; i < pruned.length; i++) {
+        if (pruned[i].role === 'tool' && pruned[i].content === '[context pruned: earlier tool output removed to fit budget]'
+            && messages[i]?.role === 'tool' && messages[i].content !== pruned[i].content) {
+            evicted.push(String(messages[i].content).slice(0, 4000));
+        }
+    }
+    if (evicted.length === 0 && previousDigest)
+        return pruned; // nothing new to distill
+    let body;
+    try {
+        body = (await summarize({ previousDigest, evicted })).trim().slice(0, 12_000);
+    }
+    catch {
+        return pruned; // summarizer down -> keep deterministic result
+    }
+    if (!body)
+        return pruned;
+    const note = { role: 'system', content: `${DIGEST_MARK}\n${body}` };
+    if (digestIdx >= 0) {
+        const out = pruned.map((m, i) => (i === digestIdx ? note : m));
+        return out;
+    }
+    // insert after the first user message (protected head)
+    const firstUser = pruned.findIndex((m) => m.role === 'user');
+    const at = firstUser >= 0 ? firstUser + 1 : pruned.length;
+    return [...pruned.slice(0, at), note, ...pruned.slice(at)];
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './types.ts';
 export * from './registry.ts';
 export * from './provider.ts';
+export * from './window.ts';
 export * from './loop.ts';
 export * from './session.ts';
 export * from './config.ts';

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from "./types.js";
 export * from "./registry.js";
 export * from "./provider.js";
+export * from "./window.js";
 export * from "./loop.js";
 export * from "./session.js";
 export * from "./config.js";

package/dist/loop.d.ts

@@ -31,9 +31,18 @@ export declare function runLoop(opts: {
     messages: ChatMessage[];
     ctx: ToolContext;
     maxTurns?: number;
+    /** Explicit transcript budget override (chars). Default: scales with the
+     *  model's context window (window.ts registry / provider.contextWindow). */
     maxContextChars?: number;
     approval?: LoopApproval;
     events?: LoopEvents;
     /** Injectable model call (tests pass a fake; production uses provider.chat). */
     chatImpl?: typeof chat;
+    /** Rolling digest hook (model-aware context engineering): when compaction
+     *  evicts content, it is distilled into a persistent digest note instead
+     *  of being dropped. Absent -> deterministic prune only. */
+    summarizeContext?: (input: {
+        previousDigest: string | null;
+        evicted: string[];
+    }) => Promise<string>;
 }): Promise<LoopResult>;

package/dist/loop.js

@@ -7,18 +7,23 @@
  * no gate configured means deny (safe default). Between turns the
  * transcript is compacted against the context budget.
  */
-import { compactMessages } from "./context.js";
+import { compactMessages, compactWithDigest } from "./context.js";
+import { adaptiveContextChars } from "./window.js";
 import { chat } from "./provider.js";
 export async function runLoop(opts) {
     const { provider, registry, ctx, events } = opts;
     const modelCall = opts.chatImpl ?? chat;
     const maxTurns = opts.maxTurns ?? 25;
+    const budget = opts.maxContextChars ?? adaptiveContextChars(provider);
     const working = [...opts.messages];
     let toolUses = 0;
     const usage = { promptTokens: 0, completionTokens: 0 };
     const tools = registry.toOpenAITools();
     for (let turn = 1; turn <= maxTurns; turn++) {
-        const chatRes = await modelCall(provider, compactMessages(working, opts.maxContextChars), tools, {
+        const compacted = opts.summarizeContext
+            ? await compactWithDigest(working, budget, opts.summarizeContext)
+            : compactMessages(working, budget);
+        const chatRes = await modelCall(provider, compacted, tools, {
             onDelta: events?.onDelta,
         });
         usage.promptTokens += chatRes.usage?.prompt_tokens ?? 0;

package/dist/types.d.ts

@@ -64,6 +64,10 @@ export interface ProviderConfig {
      *  tokenrouter took 84s on an evolve-sized prompt vs the 120s default)
      *  set e.g. 240000 on the evolve/bench routes. */
     timeoutMs?: number;
+    /** Explicit context window (tokens) for this model. Overrides the
+     *  built-in registry; the transcript budget then scales to the window
+     *  (see window.ts) instead of the fixed legacy default. */
+    contextWindow?: number;
 }
 /** User-level configuration (HMH_HOME/config.json). */
 export interface HmhConfig {

package/dist/window.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @hmharness/kernel - window (model-aware context engineering, part 1)
+ * The context budget used to be one fixed char number for every model - a
+ * 128K-window flash model and a 1M-window model got the same 160K chars
+ * (small windows overflow, huge windows waste). This registry maps model
+ * names to their context windows; budgets then scale with the window.
+ *
+ * Layered resolution (first hit wins):
+ *   1. ProviderConfig.contextWindow (explicit, tokens) - the user is right
+ *   2. registry pattern match on the model name - conservative values
+ *   3. unknown -> null (callers fall back to the legacy fixed default)
+ *
+ * Registry values are deliberately CONSERVATIVE (never the vendor max):
+ * a wrong-low budget costs a bit of context; a wrong-high one costs the run.
+ */
+export interface ContextWindowInfo {
+    windowTokens: number | null;
+    source: 'config' | 'registry' | 'unknown';
+}
+export declare function contextWindowFor(p: {
+    model: string;
+    contextWindow?: number;
+}): ContextWindowInfo;
+/** Transcript char budget for a window: ~2.5 chars/token mixed-language
+ *  (ASCII ~4, CJK ~1.2), and only HALF the window may be history - the rest
+ *  belongs to system prompt, injected memory/skills, tool schemas and the
+ *  reply. 128K tokens -> 160K chars, which is exactly the legacy default -
+ *  known-window models scale from there, unknown models keep today's
+ *  behaviour unchanged. */
+export declare const CHARS_PER_TOKEN = 2.5;
+export declare const HISTORY_WINDOW_FRACTION = 0.5;
+export declare const MIN_CONTEXT_CHARS = 40000;
+export declare const MAX_CONTEXT_CHARS = 1000000;
+export declare const LEGACY_DEFAULT_CONTEXT_CHARS = 160000;
+export declare function contextBudgetChars(windowTokens: number | null): number;
+/** One-call helper: provider -> adaptive transcript char budget. */
+export declare function adaptiveContextChars(p: {
+    model: string;
+    contextWindow?: number;
+}): number;

package/dist/window.js

@@ -0,0 +1,47 @@
+/** Ordered [pattern, conservative window tokens]. First match wins. */
+const REGISTRY = [
+    [/claude/i, 200_000],
+    [/gpt-4\.1/i, 1_000_000],
+    [/gpt-5/i, 400_000],
+    [/gpt-4o/i, 128_000],
+    [/\bo[34](-mini)?\b/i, 200_000],
+    [/gemini/i, 1_000_000],
+    [/glm-\d/i, 131_072],
+    [/deepseek/i, 128_000],
+    [/kimi/i, 131_072],
+    [/qwen/i, 131_072],
+    [/llama/i, 128_000],
+    [/doubao/i, 128_000],
+    [/hunyuan|ernie|minimax|step-/i, 128_000],
+];
+export function contextWindowFor(p) {
+    if (typeof p.contextWindow === 'number' && p.contextWindow > 0) {
+        return { windowTokens: p.contextWindow, source: 'config' };
+    }
+    for (const [re, tokens] of REGISTRY) {
+        if (re.test(p.model))
+            return { windowTokens: tokens, source: 'registry' };
+    }
+    return { windowTokens: null, source: 'unknown' };
+}
+/** Transcript char budget for a window: ~2.5 chars/token mixed-language
+ *  (ASCII ~4, CJK ~1.2), and only HALF the window may be history - the rest
+ *  belongs to system prompt, injected memory/skills, tool schemas and the
+ *  reply. 128K tokens -> 160K chars, which is exactly the legacy default -
+ *  known-window models scale from there, unknown models keep today's
+ *  behaviour unchanged. */
+export const CHARS_PER_TOKEN = 2.5;
+export const HISTORY_WINDOW_FRACTION = 0.5;
+export const MIN_CONTEXT_CHARS = 40_000;
+export const MAX_CONTEXT_CHARS = 1_000_000;
+export const LEGACY_DEFAULT_CONTEXT_CHARS = 160_000;
+export function contextBudgetChars(windowTokens) {
+    if (windowTokens === null)
+        return LEGACY_DEFAULT_CONTEXT_CHARS;
+    const raw = windowTokens * CHARS_PER_TOKEN * HISTORY_WINDOW_FRACTION;
+    return Math.round(Math.min(MAX_CONTEXT_CHARS, Math.max(MIN_CONTEXT_CHARS, raw)));
+}
+/** One-call helper: provider -> adaptive transcript char budget. */
+export function adaptiveContextChars(p) {
+    return contextBudgetChars(contextWindowFor(p).windowTokens);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/kernel",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "hmharness kernel: tool registry, provider adapters, the agent loop, session log, config. Zero runtime dependencies (Node >=22 native fetch).",
   "type": "module",
   "main": "dist/index.js",