@corenel/harness 0.7.5 → 0.9.0

package/dist/conversation.d.ts

@@ -14,5 +14,20 @@ export interface ConversationTurn {
     messages: ChatCompletionMessageParam[];
     /** Token/cost/latency for the assistant response, once the turn settles. */
     stats?: TurnStats;
+    /** Set on a COMPACTION SEAM: the checkpoint body the summarizer produced for
+     * the stretch this seam replaced. Carried on the turn rather than left to a
+     * file because the question a seam raises ("what did it keep?") is a question
+     * about the conversation in front of you, and because the file only exists
+     * for a run that had a session to write beside. Absent on every other turn. */
+    checkpoint?: string;
 }
+/** Is this turn a COMPACTION SEAM rather than something said?
+ *
+ * Recognized by the marker the harness writes into the window, so a surface
+ * cannot look for one string while the loop writes another. Lives here, beside
+ * the type, because three consumers need it now -- the transcript draws the
+ * seam, the context panel counts seams and must keep them OUT of the window it
+ * reports (a seam is an unsent note; counting it would inflate the very number
+ * the panel exists to give), and the runtime writes them. */
+export declare function isCheckpointTurn(t: ConversationTurn): boolean;
 //# sourceMappingURL=conversation.d.ts.map

package/dist/conversation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../conversation.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAEpF,qFAAqF;AACrF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;+EAC+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB"}
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../conversation.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAGpF,qFAAqF;AACrF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;+EAC+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;mFAI+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;6DAO6D;AAC7D,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAG7D"}

package/dist/conversation.js

@@ -1,2 +1,14 @@
-export {};
+import { CHECKPOINT_MARKER } from './core/compactHistory.js';
+/** Is this turn a COMPACTION SEAM rather than something said?
+ *
+ * Recognized by the marker the harness writes into the window, so a surface
+ * cannot look for one string while the loop writes another. Lives here, beside
+ * the type, because three consumers need it now -- the transcript draws the
+ * seam, the context panel counts seams and must keep them OUT of the window it
+ * reports (a seam is an unsent note; counting it would inflate the very number
+ * the panel exists to give), and the runtime writes them. */
+export function isCheckpointTurn(t) {
+    const first = t.messages[0];
+    return typeof first?.content === 'string' && first.content.startsWith(CHECKPOINT_MARKER);
+}
 //# sourceMappingURL=conversation.js.map

package/dist/conversation.js.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../conversation.ts"],"names":[],"mappings":""}
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../conversation.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AA0B1D;;;;;;;6DAO6D;AAC7D,MAAM,UAAU,gBAAgB,CAAC,CAAmB;IAClD,MAAM,KAAK,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5B,OAAO,OAAO,KAAK,EAAE,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;AAC3F,CAAC"}

package/dist/core/compactHistory.d.ts

@@ -0,0 +1,84 @@
+import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
+export interface CompactHistoryOptions {
+    /** Summarizes the collapsed stretch. Injected so the partitioning is testable
+     * without a model call. */
+    summarize: (collapsed: ChatCompletionMessageParam[]) => Promise<string>;
+    /** Produces the one-line referent for a preserved user message: what it was
+     * answering. `answered` is the nearest preceding assistant turn, or null when
+     * the user opened the conversation. Omit to preserve user messages bare. */
+    anchor?: (user: ChatCompletionMessageParam, answered: ChatCompletionMessageParam | null) => Promise<string>;
+    /** Byte size past which a user message's own content is offloaded rather than
+     * kept inline. Requires `offload`. */
+    offloadOverBytes?: number;
+    /** Records oversized user content and returns the pointer to leave in its
+     * place — the same treatment rung 1 gives an oversized tool result. */
+    offload?: (content: string) => Promise<string>;
+}
+export interface CompactHistoryResult {
+    /** The rebuilt message array to send from here on. */
+    messages: ChatCompletionMessageParam[];
+    /** The durable checkpoint body, destined for a file in the project. */
+    checkpoint: string;
+}
+/** The marker every checkpoint message starts with, so a later pass can
+ * recognize one it already wrote instead of collapsing it again. */
+export declare const CHECKPOINT_MARKER = "[checkpoint] ";
+/** The marker every anchor message starts with. An anchor is context ABOUT the
+ * user message that follows it, not something the assistant said. */
+export declare const ANCHOR_MARKER = "[anchor] ";
+/** Window fill ratio at which history compaction becomes worth its cost.
+ * High on purpose: see the one-shot reasoning at the top of this file. */
+export declare const COMPACT_AT_FILL = 0.86;
+/** Whether compacting now is worth rewriting the cached prefix. Two gates: the
+ * window is genuinely close to full, AND there is bulk to remove. A compaction
+ * that reduces nothing still invalidates the whole prefix, so "nothing to
+ * collapse" is a refusal, not a no-op. */
+export declare function shouldCompact(fill: number, messages: ChatCompletionMessageParam[]): boolean;
+/** Fill must fall back below this before compaction re-arms. */
+export declare const REARM_BELOW_FILL = 0.6;
+/** How much the window must refill, ABOVE where the last compaction left it,
+ * for another compaction to be worth its cost. */
+export declare const REARM_ON_REGROWTH = 0.1;
+/** The latch's state between turns.
+ *
+ * `floor` is the fill measured just after the last compaction -- how far down
+ * it actually got. Null means either nothing has compacted yet or the next
+ * usage reading has not arrived, and the gate falls back to the absolute rule
+ * until it has. It is deliberately taken from a REAL reading rather than
+ * estimateFill: it is compared against real readings, and mixing an estimate
+ * into one side of that comparison would bias every re-arm after it. */
+export interface CompactGate {
+    armed: boolean;
+    floor: number | null;
+}
+/** The gate's state the moment a compaction has run: shut, and waiting for the
+ * next usage reading to tell it how far down that compaction got. */
+export declare function afterCompaction(): CompactGate;
+/** Window fill ratio read from the messages themselves.
+ *
+ * For the one turn where no usage reading exists: `fill` comes from the
+ * PREVIOUS response, so it is 0 on turn 1 and the gate could never fire before
+ * the first request. A run resuming an already-oversized conversation
+ * therefore put it on the wire uncompacted and took the fatal 400 immediately
+ * -- the case that needs rung 2 most was the case it could not run in.
+ *
+ * Reads low: the request also carries tool schemas, which are not visible
+ * here. That is the right direction to be wrong in, since the cost of reading
+ * high is a compaction nobody needed. */
+export declare function estimateFill(messages: ChatCompletionMessageParam[], contextWindow: number | undefined): number;
+export declare function compactionDecision(fill: number, messages: ChatCompletionMessageParam[], gate: CompactGate): {
+    compact: boolean;
+    next: CompactGate;
+};
+export declare function compactHistory(messages: ChatCompletionMessageParam[], opts: CompactHistoryOptions): Promise<CompactHistoryResult>;
+/** An anchor or checkpoint a compaction wrote — bookkeeping ABOUT the
+ * conversation rather than part of it. Exported because a caller that has to
+ * tell "what this run added" from "what a rewrite inserted" cannot do it by
+ * position: a rewrite puts fresh objects into the array at arbitrary places. */
+export declare const isCompactionMarker: typeof isOwnMarker;
+/** An anchor or checkpoint this module wrote on an earlier pass. Dropped and
+ * rewritten each time rather than accumulated: the newest checkpoint already
+ * subsumes what the older ones recorded. */
+declare function isOwnMarker(m: ChatCompletionMessageParam): boolean;
+export {};
+//# sourceMappingURL=compactHistory.d.ts.map

package/dist/core/compactHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compactHistory.d.ts","sourceRoot":"","sources":["../../core/compactHistory.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAGpF,MAAM,WAAW,qBAAqB;IACpC;+BAC2B;IAC3B,SAAS,EAAE,CAAC,SAAS,EAAE,0BAA0B,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxE;;gFAE4E;IAC5E,MAAM,CAAC,EAAE,CACP,IAAI,EAAE,0BAA0B,EAChC,QAAQ,EAAE,0BAA0B,GAAG,IAAI,KACxC,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB;0CACsC;IACtC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;2EACuE;IACvE,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;oEACoE;AACpE,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD;qEACqE;AACrE,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC;0EAC0E;AAC1E,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;0CAG0C;AAC1C,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,0BAA0B,EAAE,GAAG,OAAO,CAG3F;AAED,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC;kDACkD;AAClD,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;;wEAOwE;AACxE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;qEACqE;AACrE,wBAAgB,eAAe,IAAI,WAAW,CAE7C;AAyBD;;;;;;;;;;yCAUyC;AACzC,wBAAgB,YAAY,CAAC,QAAQ,EAAE,0BAA0B,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK9G;AA+BD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,0BAA0B,EAAE,EACtC,IAAI,EAAE,WAAW,GAChB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAQzC;AAED,wBAAsB,cAAc,CAClC,QAAQ,EAAE,0BAA0B,EAAE,EACtC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CA8C/B;AAeD;;;gFAGgF;AAChF,eAAO,MAAM,kBAAkB,oBAAc,CAAC;AAY9C;;4CAE4C;AAC5C,iBAAS,WAAW,CAAC,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAG3D"}

package/dist/core/compactHistory.js

@@ -0,0 +1,206 @@
+/* Rung 2 of the context ladder: one-shot history compaction.
+ *
+ * Rung 1 (compression.ts) offloads ONE oversized tool result at a time and is
+ * lossless. This is the other half: when the window is genuinely close to full,
+ * collapse the conversation's bulk in a single structural step.
+ *
+ * It is deliberately NOT incremental. Every form of history compression
+ * invalidates the provider's cached prefix — the cache is a prefix, so touching
+ * any byte of it recomputes everything after it at full price. A compactor that
+ * trims a little each turn therefore pays full reprocessing every turn and saves
+ * almost nothing. One shot, high threshold, large payoff. */
+import { isContextNote } from './contextPressure.js';
+/** The marker every checkpoint message starts with, so a later pass can
+ * recognize one it already wrote instead of collapsing it again. */
+export const CHECKPOINT_MARKER = '[checkpoint] ';
+/** The marker every anchor message starts with. An anchor is context ABOUT the
+ * user message that follows it, not something the assistant said. */
+export const ANCHOR_MARKER = '[anchor] ';
+/** Window fill ratio at which history compaction becomes worth its cost.
+ * High on purpose: see the one-shot reasoning at the top of this file. */
+export const COMPACT_AT_FILL = 0.86;
+/** Whether compacting now is worth rewriting the cached prefix. Two gates: the
+ * window is genuinely close to full, AND there is bulk to remove. A compaction
+ * that reduces nothing still invalidates the whole prefix, so "nothing to
+ * collapse" is a refusal, not a no-op. */
+export function shouldCompact(fill, messages) {
+    if (fill < COMPACT_AT_FILL)
+        return false;
+    return messages.some((m) => m.role !== 'system' && m.role !== 'user');
+}
+/** Fill must fall back below this before compaction re-arms. */
+export const REARM_BELOW_FILL = 0.6;
+/** How much the window must refill, ABOVE where the last compaction left it,
+ * for another compaction to be worth its cost. */
+export const REARM_ON_REGROWTH = 0.1;
+/** The gate's state the moment a compaction has run: shut, and waiting for the
+ * next usage reading to tell it how far down that compaction got. */
+export function afterCompaction() {
+    return { armed: false, floor: null };
+}
+/* ~4 characters per token, matching estimateFactTokens in memory/tier.ts and
+ * the chars/4 fallback in @corenel/ui-kit. A BPE count is not worth a
+ * dependency for a number whose whole job is to be approximately right. */
+function messageChars(m) {
+    let n = 0;
+    const content = m.content;
+    if (typeof content === 'string')
+        n += content.length;
+    else if (Array.isArray(content)) {
+        for (const part of content) {
+            const text = part.text;
+            if (typeof text === 'string')
+                n += text.length;
+        }
+    }
+    /* Tool-call arguments ARE the bulk of an agent conversation and live beside
+     * `content`, not in it. Leaving them out would make this read near zero on
+     * exactly the histories it exists to catch. */
+    const calls = m.tool_calls;
+    if (Array.isArray(calls)) {
+        for (const c of calls)
+            n += (c.function?.name?.length ?? 0) + (c.function?.arguments?.length ?? 0);
+    }
+    return n;
+}
+/** Window fill ratio read from the messages themselves.
+ *
+ * For the one turn where no usage reading exists: `fill` comes from the
+ * PREVIOUS response, so it is 0 on turn 1 and the gate could never fire before
+ * the first request. A run resuming an already-oversized conversation
+ * therefore put it on the wire uncompacted and took the fatal 400 immediately
+ * -- the case that needs rung 2 most was the case it could not run in.
+ *
+ * Reads low: the request also carries tool schemas, which are not visible
+ * here. That is the right direction to be wrong in, since the cost of reading
+ * high is a compaction nobody needed. */
+export function estimateFill(messages, contextWindow) {
+    if (!contextWindow || contextWindow <= 0)
+        return 0;
+    let chars = 0;
+    for (const m of messages)
+        chars += messageChars(m);
+    return Math.min(1, chars / 4 / contextWindow);
+}
+/* The gate, with hysteresis.
+ *
+ * `shouldCompact` alone says "the window is full and there is bulk" — which
+ * stays TRUE on the turn after a compaction, and the one after that. A real
+ * run against a live model compacted over and over for exactly that reason,
+ * paying a full cached-prefix rewrite each time: the trickle failure this
+ * module's own header argues against, reintroduced by the missing edge.
+ *
+ * So the gate is a latch, not a predicate. It fires once at COMPACT_AT_FILL,
+ * disarms, and re-arms only once another compaction would be worth its cost.
+ *
+ * RE-ARMING ON PROGRESS, NOT ON A MARK. The first version re-armed only below
+ * REARM_BELOW_FILL, which assumed a compaction always drains past that mark.
+ * Nothing guarantees it: this codebase keeps EVERY user message verbatim, so a
+ * compaction's floor is system + all user turns + the checkpoint, and in a long
+ * conversation with large pastes that clears 0.6 easily. Landing anywhere in
+ * [0.6, 0.86) left the latch stuck SHUT FOREVER -- fill only grows from there,
+ * so it could never fall back under the mark, and the run compacted exactly
+ * once before marching into the wall it was supposed to prevent. Silently: a
+ * gate that never fires looks identical to a conversation that never got big.
+ *
+ * So the question is not "how full is the window" but "has it grown enough
+ * since the last compaction to have something new to collapse". Growth of
+ * REARM_ON_REGROWTH past that floor means yes, whatever the absolute level.
+ * The drained-window rule is kept alongside it: it is the cheapest possible
+ * signal and stays correct. Between the marks, with nothing new accumulated,
+ * the gate still does nothing -- which remains the right answer, because a
+ * second compaction so soon has almost nothing left to remove and would charge
+ * a full prefix rewrite to discover that. */
+export function compactionDecision(fill, messages, gate) {
+    if (!gate.armed) {
+        const drained = fill < REARM_BELOW_FILL;
+        const regrown = gate.floor !== null && fill >= gate.floor + REARM_ON_REGROWTH;
+        return { compact: false, next: { ...gate, armed: drained || regrown } };
+    }
+    if (!shouldCompact(fill, messages))
+        return { compact: false, next: gate };
+    return { compact: true, next: afterCompaction() };
+}
+export async function compactHistory(messages, opts) {
+    // A trailing assistant message that has asked for tools but not yet been
+    // answered is held back from the collapse: the loop appends its `tool`
+    // results next, and those results need this parent to exist or the provider
+    // rejects the request with a fatal 400.
+    const tail = messages.length ? messages[messages.length - 1] : undefined;
+    const pending = tail && isUnansweredToolCall(tail) ? tail : null;
+    const body = pending ? messages.slice(0, -1) : messages;
+    const system = body.filter((m) => m.role === 'system');
+    /* A stale pressure notice is DROPPED, not summarized. "Context is 80% full"
+     * is a fact about the window this compaction is in the middle of emptying,
+     * and letting it into the summarizer's input would write it into the
+     * checkpoint as though it were something that happened in the conversation.
+     * The agent gets a fresh one on the next crossing if it earns it. */
+    const collapsed = body.filter((m) => m.role !== 'system' && m.role !== 'user' && !isContextNote(m));
+    const kept = [];
+    let answered = null;
+    for (const m of body) {
+        /* Skip THIS MODULE'S OWN messages, both as anchor candidates and as
+         * things to re-anchor. An anchor is an assistant message with string
+         * content, so a naive walk picks up the previous compaction's anchors and
+         * anchors those — a real run produced
+         * "[anchor] answering: [anchor] answering: [anchor] answering: ...".
+         * These are bookkeeping about the conversation, not part of it. */
+        if (isOwnMarker(m) || isContextNote(m))
+            continue;
+        if (m.role === 'assistant' && typeof m.content === 'string')
+            answered = m;
+        if (m.role !== 'user')
+            continue;
+        if (opts.anchor) {
+            kept.push({ role: 'assistant', content: `${ANCHOR_MARKER}${await opts.anchor(m, answered)}` });
+        }
+        kept.push(await offloadIfOversized(m, opts));
+    }
+    const summary = await opts.summarize(collapsed);
+    return {
+        messages: [
+            ...system,
+            { role: 'assistant', content: `${CHECKPOINT_MARKER}${summary}` },
+            ...kept,
+            ...(pending ? [pending] : []),
+        ],
+        checkpoint: summary,
+    };
+}
+/** A user turn's DECISION text is small and stays verbatim; a pasted log is
+ * bulk and gets rung 1's treatment. Anything that is not oversized plain text
+ * is returned untouched. */
+async function offloadIfOversized(m, opts) {
+    const limit = opts.offloadOverBytes;
+    if (!opts.offload || limit === undefined)
+        return m;
+    if (typeof m.content !== 'string' || m.content.length <= limit)
+        return m;
+    return { ...m, content: await opts.offload(m.content) };
+}
+/** An anchor or checkpoint a compaction wrote — bookkeeping ABOUT the
+ * conversation rather than part of it. Exported because a caller that has to
+ * tell "what this run added" from "what a rewrite inserted" cannot do it by
+ * position: a rewrite puts fresh objects into the array at arbitrary places. */
+export const isCompactionMarker = isOwnMarker;
+/* A context-pressure notice (core/contextPressure.ts) is bookkeeping too, and
+ * a STALE one: it says the window was 80% full, which a compaction has just
+ * made false. So the collapse above drops it -- but it is deliberately NOT
+ * folded into `isCompactionMarker`. That predicate makes the loop's
+ * `appendedFromTail` walk STOP, and a pressure notice sits in the middle of a
+ * run's own appended messages rather than at the head of the kept region:
+ * conflating them silently truncates every `appended` count taken after a
+ * notice fired, and the host then persists a partial tail. One predicate, two
+ * very different jobs -- loop.contextPressure.test.ts pins the difference. */
+/** An anchor or checkpoint this module wrote on an earlier pass. Dropped and
+ * rewritten each time rather than accumulated: the newest checkpoint already
+ * subsumes what the older ones recorded. */
+function isOwnMarker(m) {
+    if (m.role !== 'assistant' || typeof m.content !== 'string')
+        return false;
+    return m.content.startsWith(ANCHOR_MARKER) || m.content.startsWith(CHECKPOINT_MARKER);
+}
+function isUnansweredToolCall(m) {
+    return m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length > 0;
+}
+//# sourceMappingURL=compactHistory.js.map

package/dist/core/compactHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compactHistory.js","sourceRoot":"","sources":["../../core/compactHistory.ts"],"names":[],"mappings":"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"}

package/dist/core/contextPressure.d.ts

@@ -0,0 +1,45 @@
+import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
+/** Marks a note this module appended. Same shape as CHECKPOINT_MARKER/
+ * ANCHOR_MARKER so the compactor can recognise and drop it. */
+export declare const CONTEXT_MARKER = "[context] ";
+/** Fill ratios worth interrupting for, ascending.
+ *
+ * 0.6 is where behavior should start bending (read narrower, summarize).
+ * 0.8 is where new exploration should stop. 0.9 is the last useful warning --
+ * COMPACT_AT_FILL is 0.86, so by 0.9 either compaction is not configured or it
+ * ran and did not get far enough, and both mean answer now. */
+export declare const PRESSURE_BANDS: readonly [0.6, 0.8, 0.9];
+export type PressureBand = (typeof PRESSURE_BANDS)[number];
+/** How far fill must fall BELOW a band before that band counts as un-crossed
+ * and may announce again. Without it, a run hovering at 0.79/0.81 re-announces
+ * on every other turn -- the notice becomes noise and costs tokens each time. */
+export declare const PRESSURE_HYSTERESIS = 0.05;
+/** The highest band already announced; 0 before any. */
+export interface PressureGate {
+    crossed: number;
+}
+export declare const initialPressureGate: PressureGate;
+/**
+ * Decide whether this turn should announce context pressure.
+ *
+ * `band` is non-null at most once per crossing. After a compaction drains the
+ * window, the gate falls back to whatever band the new fill sits in, so
+ * climbing into 80% a second time is news a second time -- which is right: it
+ * is a different 80%, reached after the history was already collapsed once.
+ */
+export declare function pressureDecision(fill: number, gate: PressureGate): {
+    band: PressureBand | null;
+    next: PressureGate;
+};
+/** What the agent is told at each band. Each one names a CHANGE IN BEHAVIOR,
+ * not just a number -- a percentage with no instruction attached is something
+ * to acknowledge and then ignore. */
+export declare function pressureMessage(band: PressureBand, fill: number): string;
+/** The static line the loop adds to the system prompt once per run. Empty when
+ * the host did not resolve a window -- an invented number is worse than none. */
+export declare function contextWindowLine(contextWindow: number | undefined): string;
+/** True for a note this module appended. */
+export declare function isContextNote(m: ChatCompletionMessageParam): boolean;
+/** The history message carrying a pressure notice. */
+export declare function contextNote(band: PressureBand, fill: number): ChatCompletionMessageParam;
+//# sourceMappingURL=contextPressure.d.ts.map

package/dist/core/contextPressure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextPressure.d.ts","sourceRoot":"","sources":["../../core/contextPressure.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAEpF;+DAC+D;AAC/D,eAAO,MAAM,cAAc,eAAe,CAAC;AAE3C;;;;;+DAK+D;AAC/D,eAAO,MAAM,cAAc,0BAA2B,CAAC;AACvD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D;;iFAEiF;AACjF,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAAG,OAAO,EAAE,MAAM,CAAA;CAAE;AAEjD,eAAO,MAAM,mBAAmB,EAAE,YAA6B,CAAC;AAQhE;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG;IAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,CAOpH;AAED;;qCAEqC;AACrC,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAUxE;AAED;iFACiF;AACjF,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAG3E;AAED,4CAA4C;AAC5C,wBAAgB,aAAa,CAAC,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAEpE;AAED,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,0BAA0B,CAExF"}

package/dist/core/contextPressure.js

@@ -0,0 +1,69 @@
+/** Marks a note this module appended. Same shape as CHECKPOINT_MARKER/
+ * ANCHOR_MARKER so the compactor can recognise and drop it. */
+export const CONTEXT_MARKER = '[context] ';
+/** Fill ratios worth interrupting for, ascending.
+ *
+ * 0.6 is where behavior should start bending (read narrower, summarize).
+ * 0.8 is where new exploration should stop. 0.9 is the last useful warning --
+ * COMPACT_AT_FILL is 0.86, so by 0.9 either compaction is not configured or it
+ * ran and did not get far enough, and both mean answer now. */
+export const PRESSURE_BANDS = [0.6, 0.8, 0.9];
+/** How far fill must fall BELOW a band before that band counts as un-crossed
+ * and may announce again. Without it, a run hovering at 0.79/0.81 re-announces
+ * on every other turn -- the notice becomes noise and costs tokens each time. */
+export const PRESSURE_HYSTERESIS = 0.05;
+export const initialPressureGate = { crossed: 0 };
+function highestBandAtOrBelow(fill, slack = 0) {
+    let best = 0;
+    for (const b of PRESSURE_BANDS)
+        if (fill >= b - slack)
+            best = b;
+    return best;
+}
+/**
+ * Decide whether this turn should announce context pressure.
+ *
+ * `band` is non-null at most once per crossing. After a compaction drains the
+ * window, the gate falls back to whatever band the new fill sits in, so
+ * climbing into 80% a second time is news a second time -- which is right: it
+ * is a different 80%, reached after the history was already collapsed once.
+ */
+export function pressureDecision(fill, gate) {
+    const current = highestBandAtOrBelow(fill);
+    if (current > gate.crossed)
+        return { band: current, next: { crossed: current } };
+    // Not a new crossing. Hold the gate where it is unless fill has fallen a
+    // clear margin below it, in which case drop to the band it really sits in.
+    const held = highestBandAtOrBelow(fill, PRESSURE_HYSTERESIS);
+    return { band: null, next: { crossed: Math.min(gate.crossed, held) } };
+}
+/** What the agent is told at each band. Each one names a CHANGE IN BEHAVIOR,
+ * not just a number -- a percentage with no instruction attached is something
+ * to acknowledge and then ignore. */
+export function pressureMessage(band, fill) {
+    const pct = Math.round(fill * 100);
+    switch (band) {
+        case 0.6:
+            return `${CONTEXT_MARKER}Context is ${pct}% full. Read files in ranges rather than whole, summarize tool output rather than quoting it back, and stop re-reading things already in this conversation.`;
+        case 0.8:
+            return `${CONTEXT_MARKER}Context is ${pct}% full. Finish the task in progress and report it; start no new exploration, and open nothing large. If the work does not fit, say what is left rather than beginning it.`;
+        case 0.9:
+            return `${CONTEXT_MARKER}Context is ${pct}% full. Stop gathering and answer now with what you already have, naming what you did not get to. Further reading will be lost.`;
+    }
+}
+/** The static line the loop adds to the system prompt once per run. Empty when
+ * the host did not resolve a window -- an invented number is worse than none. */
+export function contextWindowLine(contextWindow) {
+    if (!contextWindow || contextWindow <= 0)
+        return '';
+    return `Your context window is ${contextWindow.toLocaleString('en-US')} tokens. You will be told when it is filling up.`;
+}
+/** True for a note this module appended. */
+export function isContextNote(m) {
+    return m.role === 'assistant' && typeof m.content === 'string' && m.content.startsWith(CONTEXT_MARKER);
+}
+/** The history message carrying a pressure notice. */
+export function contextNote(band, fill) {
+    return { role: 'assistant', content: pressureMessage(band, fill) };
+}
+//# sourceMappingURL=contextPressure.js.map

package/dist/core/contextPressure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextPressure.js","sourceRoot":"","sources":["../../core/contextPressure.ts"],"names":[],"mappings":"AAgCA;+DAC+D;AAC/D,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC;AAE3C;;;;;+DAK+D;AAC/D,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAGvD;;iFAEiF;AACjF,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAKxC,MAAM,CAAC,MAAM,mBAAmB,GAAiB,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AAEhE,SAAS,oBAAoB,CAAC,IAAY,EAAE,KAAK,GAAG,CAAC;IACnD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,cAAc;QAAE,IAAI,IAAI,IAAI,CAAC,GAAG,KAAK;YAAE,IAAI,GAAG,CAAC,CAAC;IAChE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,IAAkB;IAC/D,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,IAAI,EAAE,OAAuB,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;IACjG,yEAAyE;IACzE,2EAA2E;IAC3E,MAAM,IAAI,GAAG,oBAAoB,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;IAC7D,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;AACzE,CAAC;AAED;;qCAEqC;AACrC,MAAM,UAAU,eAAe,CAAC,IAAkB,EAAE,IAAY;IAC9D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;IACnC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,GAAG;YACN,OAAO,GAAG,cAAc,cAAc,GAAG,6JAA6J,CAAC;QACzM,KAAK,GAAG;YACN,OAAO,GAAG,cAAc,cAAc,GAAG,2KAA2K,CAAC;QACvN,KAAK,GAAG;YACN,OAAO,GAAG,cAAc,cAAc,GAAG,iIAAiI,CAAC;IAC/K,CAAC;AACH,CAAC;AAED;iFACiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,aAAiC;IACjE,IAAI,CAAC,aAAa,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACpD,OAAO,0BAA0B,aAAa,CAAC,cAAc,CAAC,OAAO,CAAC,kDAAkD,CAAC;AAC3H,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,aAAa,CAAC,CAA6B;IACzD,OAAO,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACzG,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,WAAW,CAAC,IAAkB,EAAE,IAAY;IAC1D,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;AACrE,CAAC"}

package/dist/core/loop.d.ts

@@ -40,6 +40,17 @@ export interface RunAgentArgs {
     describePermissionDenial?: (toolName: string) => string;
     /** Context-compression config (rung-1 offload). Omit to disable. */
     compression?: CompressionConfig;
+    /** Rung-2 history compaction. Omit and history is never compacted — the run
+     * then behaves exactly as it did before this existed, which is to say it
+     * runs until the provider rejects an oversized request with a fatal 400.
+     * `summarize` is a host concern because it costs a model call; the host also
+     * decides where `onCheckpoint` persists the body (a file the user can edit,
+     * not an invisible blob). */
+    compaction?: {
+        summarize: (collapsed: ChatCompletionMessageParam[]) => Promise<string>;
+        anchor?: (user: ChatCompletionMessageParam, answered: ChatCompletionMessageParam | null) => Promise<string>;
+        onCheckpoint?: (checkpoint: string) => void | Promise<void>;
+    };
     /** Intra-run self-healing budget (stream-retry + tool-steer). Omit for defaults. */
     recovery?: Partial<RecoveryConfig>;
     /** Optional output-token ceiling forwarded to the model on every turn (reasoning
@@ -73,6 +84,20 @@ export interface RunAgentResult {
     text: string;
     usage: Usage;
     stopReason: string;
+    /** How many messages at the TAIL of `messages` this run added.
+     *
+     * A caller stitching the new messages onto its own transcript cannot compute
+     * this from what it sent: rung-2 compaction rewrites `messages` in place and
+     * the rewrite is SHORTER than the input -- that is the point of it -- so an
+     * absolute offset into the result runs off the end and the caller silently
+     * keeps nothing. The browser runtime did exactly that, and dropped the reply
+     * of every run that compacted.
+     *
+     * Counted from the tail by object identity, so no future `messages.push` can
+     * forget to maintain it. A run whose earlier messages were collapsed into a
+     * checkpoint reports only what survives: those messages are genuinely gone
+     * from the array, and the seam in the transcript is what stands in for them. */
+    appended: number;
 }
 /** The most tools one request may carry.
  *

package/dist/core/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../core/loop.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,0BAA0B,EAAsB,MAAM,mCAAmC,CAAC;AACxG,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAA4B,MAAM,mBAAmB,CAAC;AAE7G,OAAO,EACY,KAAK,cAAc,EAErC,MAAM,YAAY,CAAC;AAMpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAA0D,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAIhH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd;kDAC8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;;kFAG8E;IAC9E,aAAa,CAAC,EAAE,SAAS,EAAE,CAAC;IAC5B;oFACgF;IAChF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;;;;;;;;6EAQyE;IACzE,wBAAwB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACxD,oEAAoE;IACpE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACnC;0FACsF;IACtF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;yEAOqE;IACrE,aAAa,CAAC,EAAE,MAAM,0BAA0B,EAAE,CAAC;IACnD;;4DAEwD;IACxD,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC;IACpC;;;0EAGsE;IACtE,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACpD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;gEAWgE;AAChE,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAwa1E"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../core/loop.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,0BAA0B,EAAsB,MAAM,mCAAmC,CAAC;AACxG,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAA4B,MAAM,mBAAmB,CAAC;AAE7G,OAAO,EACY,KAAK,cAAc,EAErC,MAAM,YAAY,CAAC;AAMpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAA0D,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAMhH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd;kDAC8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;;kFAG8E;IAC9E,aAAa,CAAC,EAAE,SAAS,EAAE,CAAC;IAC5B;oFACgF;IAChF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;;;;;;;;6EAQyE;IACzE,wBAAwB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACxD,oEAAoE;IACpE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC;;;;;iCAK6B;IAC7B,UAAU,CAAC,EAAE;QACX,SAAS,EAAE,CAAC,SAAS,EAAE,0BAA0B,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;QACxE,MAAM,CAAC,EAAE,CACP,IAAI,EAAE,0BAA0B,EAChC,QAAQ,EAAE,0BAA0B,GAAG,IAAI,KACxC,OAAO,CAAC,MAAM,CAAC,CAAC;QACrB,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAC7D,CAAC;IACF,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACnC;0FACsF;IACtF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;yEAOqE;IACrE,aAAa,CAAC,EAAE,MAAM,0BAA0B,EAAE,CAAC;IACnD;;4DAEwD;IACxD,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC;IACpC;;;0EAGsE;IACtE,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACpD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;oFAYgF;IAChF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;gEAWgE;AAChE,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAykB1E"}