@sema-ai/core 1.275.1

package/dist/core/consolidate-scope.d.ts

@@ -0,0 +1,94 @@
+import type { MemoryStore } from "./memory.js";
+import { type ConsolidationLLM, type ConsolidationStats } from "./runner/memory-consolidation.js";
+/**
+ * design/84 Seam B (M6+M10) — **cursor-incremental scope consolidation**. A thin function over the pure
+ * {@link runMemoryConsolidation}: it reads the scope's persisted cursor, feeds ONLY the notes appended
+ * AFTER it (the incremental batch) into one reconcile pass, then — IFF the whole pass succeeds — advances
+ * the cursor to the high-water mark it observed. This is the externally-triggerable periodic path (a
+ * deployment's timer / N-session gate fires it); the TRIGGER and any cross-process LOCK live OUTSIDE this
+ * function (the deployment shell's exec/persist axes — see {@link ConsolidateScopeOptions.acquire}).
+ *
+ * **Cursor marker semantics (no-miss / no-dup):** the cursor is an OPAQUE ordering marker the STORE defines
+ * (this core never parses it). In the three reference stores it is a note **id** — `uuidv7`, which is
+ * lexicographically time-sortable, so "after the cursor" is a string `>` comparison and the high-water mark
+ * is the lexicographic MAX. Each pass:
+ *  - reads `cursor = getConsolidationCursor(scope)` (undefined ⇒ whole scope pending),
+ *  - lists the scope's note headers (stable store ordering) and keeps those with `id > cursor` AND not
+ *    already `consolidationGenerated` (a prior pass's own output — excluded so it is never re-merged),
+ *  - reconciles that incremental batch via `runMemoryConsolidation` (which itself re-excludes
+ *    `consolidationGenerated` + this-batch ids from each note's candidate set),
+ *  - advances the cursor to the high-water mark of the fed batch ∪ `stats.addedIds`, but capped STRICTLY
+ *    BELOW the smallest note this pass FAILED to process (`stats.failedIds`) — a contiguous successful-prefix
+ *    marker, not the plain max (the MAJOR1 BLOCKER: a single max marker cannot keep a sub-max failed note
+ *    pending; see {@link cappedHighWater}).
+ * No-dup: a note with `id <= cursor` is never re-fed. No-miss: a note appended after the advance, or one at/
+ * above a failure floor this pass, keeps `id > cursor` (uuidv7 monotonic) and is picked up by a later pass. A
+ * pass's own ADDs carry `consolidationGenerated:true` AND (when below the failure floor) are folded into the
+ * high-water mark, so they are excluded twice over.
+ *
+ * **Whole-pass advance (decision 3):** the cursor advances (up to the success boundary) ONLY when the pass
+ * returns (no throw). A pass that THROWS (LLM hard failure) does NOT advance at all — the batch is fully
+ * retried next time. A pass that returns with per-note failures advances only past the contiguous successful
+ * prefix below the smallest failure (fail-open: at worst a near-duplicate survives an extra pass, never data
+ * loss; consistent with the memory-store contract).
+ *
+ * **No-op safety (the BLOCKER §2 closes):** when the store lacks the cursor pair
+ * ({@link supportsPeriodicConsolidation} false) this is a NO-OP that calls `onWarn` — it NEVER degrades into a
+ * full re-consolidation of the whole scope (which would re-merge already-consolidated notes forever). It is
+ * also a no-op when the store can't consolidate at all ({@link supportsConsolidation} false) or the manifest
+ * surface ({@link MemoryStore.listStructuredNotes}) is absent.
+ */
+export interface ConsolidateScopeDeps {
+    store: MemoryStore;
+    llm: ConsolidationLLM;
+    /** Routes diagnostics (skipped decisions, no-op-because-unsupported, lock-busy) — same sink as the Runner's
+     *  `onError(phase:"memory")`. Never throws back into this function. */
+    onWarn?: (err: unknown) => void;
+    /**
+     * design/84 Seam B (TOC profile) — OPTIONAL cross-process consolidation lock. When provided,
+     * {@link consolidateScope} acquires it for `scope` before the pass and releases it after; a `release` of
+     * `undefined` (lock busy) makes the pass a NO-OP (another process is already consolidating this scope).
+     * The implementation (writeThenLink + stale-PID prune) lives in the deployment shell (`stores/file`), NOT
+     * core — core only DEFINES the injection point (the constitutional persist/exec-axis split).
+     */
+    acquire?: (scope: string) => Promise<(() => void) | undefined> | (() => void) | undefined;
+}
+/** Tuning for one {@link consolidateScope} pass (mirrors the inline consolidation settings; all optional). */
+export interface ConsolidateScopeOptions {
+    band?: {
+        lo: number;
+        hi: number;
+    };
+    searchLimit?: number;
+    /** Cap on notes fed into ONE pass (token bound). The cursor advances only past the contiguous SUCCESSFUL
+     *  prefix of the FED batch (the first `maxNotes` pending) — never past the un-fed tail beyond the cap, and
+     *  never past a note this pass FAILED to process — so a backlog larger than `maxNotes`, and any failed note,
+     *  keep `id > cursor` and drain over successive passes without ever re-feeding the notes already handled. */
+    maxNotes?: number;
+}
+/**
+ * Run ONE cursor-incremental consolidation pass for `scope` (design/84 Seam B). Returns the pass stats
+ * (or `undefined` when it was a no-op: unsupported store, empty incremental batch, or lock busy). Never
+ * throws for a no-op reason; a hard LLM failure inside `runMemoryConsolidation` propagates (the caller's
+ * fire-and-forget envelope catches it) and the cursor is left UN-advanced (the batch retries next pass).
+ */
+export declare function consolidateScope(scope: string, deps: ConsolidateScopeDeps, opts?: ConsolidateScopeOptions): Promise<ConsolidationStats | undefined>;
+/**
+ * design/84 Seam B (切片 4) — advance ONLY the cursor after an INLINE (task-end) consolidation pass has
+ * already run, so a later periodic {@link consolidateScope} starts from the inline-processed high-water mark
+ * (it does NOT re-consolidate the notes the inline pass just handled). The inline path consolidates the
+ * notes the model saved THIS task (the newest, highest-id notes); advancing the cursor over the PROCESSED
+ * ids ∪ addedIds makes inline and periodic share ONE cursor.
+ *
+ * **MAJOR1 BLOCKER:** the advance caps STRICTLY BELOW the smallest FAILED note (`failedIds`). A single
+ * max-marker cursor cannot keep a sub-max failed note pending, so a low-id note whose handling failed must
+ * stop the cursor below it even when a higher-id sibling succeeded — otherwise the failed note (id <= the
+ * plain max) would lose `id > cursor` and be exiled from consolidation forever. Pass the pass's
+ * `stats.consolidatedIds` (processed), `stats.addedIds`, and `stats.failedIds`.
+ *
+ * No-op when the store lacks the cursor pair (back-compat: an old store keeps the pure-inline behavior).
+ * Never throws — a cursor-advance failure routes to `onWarn` (the inline notes are already durable; the
+ * worst case is the next periodic pass re-sees them, which `runMemoryConsolidation` handles idempotently).
+ */
+export declare function advanceCursorAfterInline(store: MemoryStore, scope: string, seenNoteIds: ReadonlyArray<string | undefined>, addedIds: ReadonlyArray<string>, failedIds?: ReadonlyArray<string>, onWarn?: (err: unknown) => void): Promise<void>;
+//# sourceMappingURL=consolidate-scope.d.ts.map

package/dist/core/consolidate-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consolidate-scope.d.ts","sourceRoot":"","sources":["../../src/core/consolidate-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAoB,MAAM,aAAa,CAAC;AAEjE,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EAIxB,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,WAAW,CAAC;IACnB,GAAG,EAAE,gBAAgB,CAAC;IACtB;2EACuE;IACvE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IAChC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CAC3F;AAED,8GAA8G;AAC9G,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;iHAG6G;IAC7G,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAkCD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,oBAAoB,EAC1B,IAAI,GAAE,uBAA4B,GACjC,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CA2FzC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,EAC9C,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,EAC/B,SAAS,GAAE,aAAa,CAAC,MAAM,CAAM,EACrC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAC9B,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/core/consolidate-scope.js

@@ -0,0 +1,158 @@
+import { supportsConsolidation, supportsPeriodicConsolidation } from "./memory.js";
+import { runMemoryConsolidation, DEFAULT_CONSOLIDATION_BAND, DEFAULT_CONSOLIDATION_SEARCH_LIMIT, DEFAULT_CONSOLIDATION_MAX_NOTES, } from "./runner/memory-consolidation.js";
+/** Lexicographic max of two opaque markers (uuidv7 ids sort by time). `undefined` < any string. */
+function maxMarker(a, b) {
+    return a === undefined || b > a ? b : a;
+}
+/**
+ * design/84 Seam B (MAJOR1 BLOCKER) — the cursor's new high-water mark = the largest `seen` id that is
+ * still SAFE to advance past, i.e. STRICTLY BELOW the smallest FAILED id. A single max-marker cursor cannot
+ * express "skip the middle, keep a low one pending", so when a low-id note fails while a higher-id note
+ * succeeds, advancing to the plain max would exile the low note from consolidation forever (it'd no longer
+ * satisfy `id > cursor`). Capping below the smallest failure keeps the failed note — and every id at/above
+ * it — pending for the next pass (retried), while still advancing the contiguous successful prefix.
+ *
+ * `seen` = every id this pass observed that is eligible to move the cursor (the fed batch ∪ this pass's own
+ * ADD ids). `failed` = the ids this pass did NOT process to completion. No failure ⇒ the plain max of seen
+ * (existing behavior). Returns `undefined` only when there is nothing below the floor to advance to (the
+ * caller then leaves the cursor untouched).
+ */
+function cappedHighWater(seen, failed) {
+    let floor; // smallest failed id (exclusive upper bound for the cursor)
+    for (const id of failed)
+        if (floor === undefined || id < floor)
+            floor = id;
+    let hw;
+    for (const id of seen) {
+        if (floor !== undefined && id >= floor)
+            continue; // at/above a failure ⇒ keep pending, do not advance past
+        hw = maxMarker(hw, id);
+    }
+    return hw;
+}
+/**
+ * Run ONE cursor-incremental consolidation pass for `scope` (design/84 Seam B). Returns the pass stats
+ * (or `undefined` when it was a no-op: unsupported store, empty incremental batch, or lock busy). Never
+ * throws for a no-op reason; a hard LLM failure inside `runMemoryConsolidation` propagates (the caller's
+ * fire-and-forget envelope catches it) and the cursor is left UN-advanced (the batch retries next pass).
+ */
+export async function consolidateScope(scope, deps, opts = {}) {
+    const { store, onWarn } = deps;
+    // Gate 1 — the cursor pair. Missing ⇒ NO-OP (never a silent full re-consolidation; the §2 BLOCKER).
+    if (!supportsPeriodicConsolidation(store)) {
+        onWarn?.(new Error("consolidateScope: store does not implement the consolidation cursor pair " +
+            "(getConsolidationCursor/setConsolidationCursor) — skipped (no-op), NOT degraded to a full re-consolidation"));
+        return undefined;
+    }
+    // Gate 2 — the id-addressable trio + the manifest. Without them there is nothing to incrementally read/merge.
+    if (!supportsConsolidation(store) || typeof store.listStructuredNotes !== "function") {
+        onWarn?.(new Error("consolidateScope: store is not id-addressable / has no manifest — skipped (no-op)"));
+        return undefined;
+    }
+    // Optional cross-process lock (TOC). A busy lock ⇒ another process owns this scope's pass ⇒ no-op.
+    const release = deps.acquire ? await deps.acquire(scope) : () => { };
+    if (release === undefined) {
+        onWarn?.(new Error(`consolidateScope: scope "${scope}" is locked by another consolidation — skipped (no-op)`));
+        return undefined;
+    }
+    try {
+        const cursor = await store.getConsolidationCursor(scope);
+        const headers = await store.listStructuredNotes(scope);
+        // Incremental batch: notes appended AFTER the cursor (id > cursor by string order), excluding a prior
+        // pass's own output (consolidationGenerated) so it is never re-merged. The cursor advance still observes
+        // those excluded ids (below), so they don't reopen the window.
+        // Sort the pending headers by their opaque ordering marker (id) so "the first maxNotes" is the OLDEST
+        // post-cursor notes — capping then advances the cursor only past those, and the NEXT pass picks up the
+        // tail (no-miss). listStructuredNotes is documented to use the store's stable ordering, but sort here so
+        // the cap is deterministic across stores regardless of their list order.
+        const pending = headers
+            .filter((h) => !h.consolidationGenerated && (cursor === undefined || h.id > cursor))
+            .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        if (pending.length === 0) {
+            return undefined; // nothing new since the last pass — no-op (do NOT touch the cursor)
+        }
+        // Fetch the bodies for the incremental batch (capped) and feed them as the "new facts" to reconcile
+        // against the rest of the scope. `runMemoryConsolidation` excludes these ids + consolidationGenerated
+        // from each note's candidate set, so an incremental note never reconciles against itself.
+        const maxNotes = opts.maxNotes ?? DEFAULT_CONSOLIDATION_MAX_NOTES;
+        const batch = pending.slice(0, maxNotes);
+        const batchIds = batch.map((h) => h.id);
+        const records = await store.getByIds(scope, batchIds);
+        const byId = new Map(records.map((r) => [r.id, r]));
+        // Preserve store ordering; drop any id the store no longer returns (raced delete) — fail-open.
+        const notes = batchIds
+            .map((id) => byId.get(id))
+            .filter((r) => r !== undefined)
+            .map((r) => ({ id: r.id, text: r.text }));
+        let stats;
+        if (notes.length > 0) {
+            stats = await runMemoryConsolidation({
+                store,
+                scope,
+                notes,
+                band: opts.band ?? { lo: DEFAULT_CONSOLIDATION_BAND.lo, hi: DEFAULT_CONSOLIDATION_BAND.hi },
+                searchLimit: opts.searchLimit ?? DEFAULT_CONSOLIDATION_SEARCH_LIMIT,
+                maxNotes,
+                llm: deps.llm,
+                onWarn,
+            });
+        }
+        // The new high-water mark caps STRICTLY BELOW the smallest FAILED note (MAJOR1 BLOCKER): a low-id note
+        // whose handling failed inside `runMemoryConsolidation` must stay `id > cursor` so the next pass retries
+        // it, even when a higher-id sibling succeeded. `seen` = the FED batch ids ∪ this pass's own ADD ids (the
+        // ADDs carry `consolidationGenerated`, so they're excluded as candidates anyway, but advancing past them
+        // — when below the failure floor — keeps the window from reopening). `failed` = stats.failedIds. A
+        // raced-delete note (in batchIds but dropped from the fed `notes`) is neither failed nor pending (it no
+        // longer exists), so it doesn't block the cursor. No failure ⇒ the plain max over the fed batch (the
+        // no-miss guarantee: a > maxNotes backlog tail keeps id > cursor and drains over successive passes).
+        const seen = [...batchIds, ...(stats?.addedIds ?? [])];
+        const highWater = cappedHighWater(seen, stats?.failedIds ?? []);
+        // Whole-pass success boundary ⇒ advance the cursor (decision 3). A throw above skips this (batch retried
+        // next pass). highWater is undefined only when EVERY fed note failed (nothing safe to advance past).
+        if (highWater !== undefined && highWater !== cursor && (cursor === undefined || highWater > cursor)) {
+            await store.setConsolidationCursor(scope, highWater);
+        }
+        return stats ?? { tokens: 0, costMicroUsd: 0, applied: 0, addedIds: [], consolidatedIds: [], failedIds: [] };
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * design/84 Seam B (切片 4) — advance ONLY the cursor after an INLINE (task-end) consolidation pass has
+ * already run, so a later periodic {@link consolidateScope} starts from the inline-processed high-water mark
+ * (it does NOT re-consolidate the notes the inline pass just handled). The inline path consolidates the
+ * notes the model saved THIS task (the newest, highest-id notes); advancing the cursor over the PROCESSED
+ * ids ∪ addedIds makes inline and periodic share ONE cursor.
+ *
+ * **MAJOR1 BLOCKER:** the advance caps STRICTLY BELOW the smallest FAILED note (`failedIds`). A single
+ * max-marker cursor cannot keep a sub-max failed note pending, so a low-id note whose handling failed must
+ * stop the cursor below it even when a higher-id sibling succeeded — otherwise the failed note (id <= the
+ * plain max) would lose `id > cursor` and be exiled from consolidation forever. Pass the pass's
+ * `stats.consolidatedIds` (processed), `stats.addedIds`, and `stats.failedIds`.
+ *
+ * No-op when the store lacks the cursor pair (back-compat: an old store keeps the pure-inline behavior).
+ * Never throws — a cursor-advance failure routes to `onWarn` (the inline notes are already durable; the
+ * worst case is the next periodic pass re-sees them, which `runMemoryConsolidation` handles idempotently).
+ */
+export async function advanceCursorAfterInline(store, scope, seenNoteIds, addedIds, failedIds = [], onWarn) {
+    if (!supportsPeriodicConsolidation(store))
+        return; // pure-inline back-compat path
+    try {
+        const cursor = await store.getConsolidationCursor(scope);
+        const seen = [
+            ...seenNoteIds.filter((id) => typeof id === "string" && Boolean(id)),
+            ...addedIds,
+        ];
+        // Cap below the smallest failed id; never move the cursor backward (seen ids may straddle the cursor).
+        const capped = cappedHighWater(seen, failedIds);
+        const highWater = cursor === undefined ? capped : maxMarker(cursor, capped ?? cursor);
+        if (highWater !== undefined && highWater !== cursor) {
+            await store.setConsolidationCursor(scope, highWater);
+        }
+    }
+    catch (err) {
+        onWarn?.(err);
+    }
+}
+//# sourceMappingURL=consolidate-scope.js.map

package/dist/core/consolidate-scope.js.map

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

package/dist/core/context-edit.d.ts

@@ -0,0 +1,82 @@
+import type { AgentMessage } from "../internal/harness.js";
+import type { Model } from "../internal/llm.js";
+/**
+ * Fraction of the window at which we start clearing stale tool results (lighter than the guard trim).
+ * Exported as the single source for the compaction-threshold clamp (design/64 §26.4 fix 2): compaction
+ * must trigger AT OR BELOW this point, or every request inside the clearStale band breaks the prefix
+ * cache at the clearing frontier (~0.7W re-prefilled per request — the "death band").
+ */
+export declare const EDIT_FRACTION = 0.7;
+/**
+ * checklist #54 (CC microCompact.ts:41-50 `COMPACTABLE_TOOLS` parity): the INCLUSION whitelist of
+ * tools whose results may be content-cleared by the stale-result pass. CC's set is exactly
+ * { Read, Bash, PowerShell (SHELL_TOOL_NAMES), Grep, Glob, WebSearch, WebFetch, Edit, Write } —
+ * cheap-to-regenerate I/O. Everything else is PRESERVED: expensive/decision-bearing results
+ * (Agent subagent reports, Task* registry state, TodoWrite acks, Monitor, MCP tools, custom
+ * ToolSpecs) survive to the harder defenses (compaction summarizes them instead of blanking them).
+ * PowerShell is kept for CC fidelity even though sema does not mount it. Overridable per call via
+ * {@link ContextEditOptions.compactableTools} for custom-tool-heavy embedders.
+ */
+export declare const COMPACTABLE_TOOLS: ReadonlySet<string>;
+export interface ContextEditOptions {
+    /** Start clearing once estimated context tokens exceed this. */
+    budgetTokens: number;
+    /** Always keep the content of this many most-recent tool results. Default 3. */
+    keepRecentToolResults?: number;
+    /**
+     * roadmap #6② (CC contentReplacementState parity): when set, a result's FULL TEXT is offloaded to
+     * the store before its content is cleared, and the marker carries the ReadToolResult ref — a
+     * cleared result becomes pageable instead of gone-from-view. `persist` must be idempotent per ref
+     * (the store's write-once put) because clearing re-runs on every request build. Absent ⇒ the bare
+     * marker (pre-#6 behavior; the durable session still holds the full result either way).
+     */
+    offload?: {
+        /** Write-once persist; the returned ref goes into the marker. Sync (in-memory) or async stores both fit. */
+        persist: (toolCallId: string, fullText: string) => string;
+    };
+    /**
+     * design/123 D3 (codex-B1 = fable-M5) — ANCHORED accounting start: `estimateContextTokens(messages,
+     * charsPerToken).tokens` for the SAME message array. When set, the trigger gate AND the internal
+     * bookkeeping start from this usage-anchored value instead of the pure structural sum (which
+     * underestimates code by ~25% and CJK by 60–75% — the defense would self-certify and pass
+     * over-window requests). Bookkeeping semantics (pinned): clearing a message AFTER the usage anchor
+     * decrements by its structural delta; clearing a message AT/BEFORE the anchor decrements ZERO —
+     * the anchor usage was billed with that content included and does not shrink on a request-view
+     * edit (the clear only pays off on the NEXT request, after a fresh anchor lands), so the defense
+     * keeps clearing deeper until the anchored total is met or nothing clearable remains.
+     * Absent ⇒ legacy structural gate + accounting (byte-identical behavior).
+     */
+    anchoredTotalTokens?: number;
+    /** design/123 D2 — structural coefficient (`Model.charsPerToken`); default 4. */
+    charsPerToken?: number;
+    /**
+     * checklist #54 — which tools' results are clearable. Defaults to {@link COMPACTABLE_TOOLS}
+     * (CC microCompact.ts:41-50). A result whose `toolName` is not in the set is NEVER cleared by
+     * this pass, no matter how far over budget the request is — expensive subagent reports and
+     * registry state are compaction's job, not a blanking marker's.
+     */
+    compactableTools?: ReadonlySet<string>;
+}
+/**
+ * Context-editing (the lightest, safest compaction; Anthropic reports ~29% improvement alone):
+ * when context exceeds the budget, replace the CONTENT of older tool-result messages with a short
+ * marker, keeping the turn structure (tool_call/tool_result pairing) intact. The most recent
+ * `keepRecentToolResults` results are preserved.
+ *
+ * Request-only and non-destructive: returns a new array; the durable session keeps the full results.
+ * Older results are cleared first, stopping as soon as the budget is met.
+ */
+/**
+ * audit A-1 (view-level heal for HISTORICAL pollution): drop synthetic EMPTY failure assistants —
+ * stopReason aborted/error with no tool calls and no non-whitespace text/thinking. Sessions persisted
+ * before 1.92.0 may carry one parked between an interrupted tool batch and its reconcile tool_results
+ * (`A(tu×3), TR1, TR2, A(aborted,""), TR3`) — an API-invalid sequence on strict providers, and
+ * append-only sessions cannot be rewritten. Dropping the junk from the REQUEST VIEW restores a legal
+ * transcript (TR3 rejoins its batch). Deterministic ⇒ byte-stable per request ⇒ prefix-cache safe.
+ * New sessions never contain these (the loop exits cleanly on abort; the harness skips persisting them).
+ */
+export declare function dropEmptyFailureAssistants(messages: AgentMessage[]): AgentMessage[];
+export declare function clearStaleToolResults(messages: AgentMessage[], opts: ContextEditOptions): AgentMessage[];
+/** The token budget at which context-editing begins for a model (below the harder guard trim). */
+export declare function editBudget(model: Model): number;
+//# sourceMappingURL=context-edit.d.ts.map

package/dist/core/context-edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-edit.d.ts","sourceRoot":"","sources":["../../src/core/context-edit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAUhD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAUhD,CAAC;AAEH,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE;QACR,4GAA4G;QAC5G,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;KAC3D,CAAC;IACF;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACxC;AAUD;;;;;;;;GAQG;AACH;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAUnF;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,EAAE,EACxB,IAAI,EAAE,kBAAkB,GACvB,YAAY,EAAE,CAwEhB;AAED,kGAAkG;AAClG,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAG/C"}

package/dist/core/context-edit.js

@@ -0,0 +1,149 @@
+import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens, estimateTokens } from "../internal/harness.js";
+import { isToolResult } from "./message-utils.js";
+const CLEARED_MARKER = "[tool result cleared to save context]";
+/** roadmap #6②: the recoverable variant — the full content was offloaded first, so the marker
+ *  carries the ref the model can page back via ReadToolResult. Kept deterministic (the ref derives
+ *  from sessionId+toolCallId), so the per-request re-clear is byte-stable = prefix-cache safe. */
+const clearedWithRef = (ref) => `[tool result cleared to save context — full content persisted; call ReadToolResult with ref "${ref}" to read it back]`;
+/**
+ * Fraction of the window at which we start clearing stale tool results (lighter than the guard trim).
+ * Exported as the single source for the compaction-threshold clamp (design/64 §26.4 fix 2): compaction
+ * must trigger AT OR BELOW this point, or every request inside the clearStale band breaks the prefix
+ * cache at the clearing frontier (~0.7W re-prefilled per request — the "death band").
+ */
+export const EDIT_FRACTION = 0.7;
+/**
+ * checklist #54 (CC microCompact.ts:41-50 `COMPACTABLE_TOOLS` parity): the INCLUSION whitelist of
+ * tools whose results may be content-cleared by the stale-result pass. CC's set is exactly
+ * { Read, Bash, PowerShell (SHELL_TOOL_NAMES), Grep, Glob, WebSearch, WebFetch, Edit, Write } —
+ * cheap-to-regenerate I/O. Everything else is PRESERVED: expensive/decision-bearing results
+ * (Agent subagent reports, Task* registry state, TodoWrite acks, Monitor, MCP tools, custom
+ * ToolSpecs) survive to the harder defenses (compaction summarizes them instead of blanking them).
+ * PowerShell is kept for CC fidelity even though sema does not mount it. Overridable per call via
+ * {@link ContextEditOptions.compactableTools} for custom-tool-heavy embedders.
+ */
+export const COMPACTABLE_TOOLS = new Set([
+    "Read",
+    "Bash",
+    "PowerShell",
+    "Grep",
+    "Glob",
+    "WebSearch",
+    "WebFetch",
+    "Edit",
+    "Write",
+]);
+function isCleared(m) {
+    const content = m.content;
+    if (!Array.isArray(content) || content.length !== 1)
+        return false;
+    const text = content[0].text;
+    // Both marker variants count as already-cleared (re-clearing a ref marker would drop its ref).
+    return text === CLEARED_MARKER || (typeof text === "string" && text.startsWith("[tool result cleared to save context —"));
+}
+/**
+ * Context-editing (the lightest, safest compaction; Anthropic reports ~29% improvement alone):
+ * when context exceeds the budget, replace the CONTENT of older tool-result messages with a short
+ * marker, keeping the turn structure (tool_call/tool_result pairing) intact. The most recent
+ * `keepRecentToolResults` results are preserved.
+ *
+ * Request-only and non-destructive: returns a new array; the durable session keeps the full results.
+ * Older results are cleared first, stopping as soon as the budget is met.
+ */
+/**
+ * audit A-1 (view-level heal for HISTORICAL pollution): drop synthetic EMPTY failure assistants —
+ * stopReason aborted/error with no tool calls and no non-whitespace text/thinking. Sessions persisted
+ * before 1.92.0 may carry one parked between an interrupted tool batch and its reconcile tool_results
+ * (`A(tu×3), TR1, TR2, A(aborted,""), TR3`) — an API-invalid sequence on strict providers, and
+ * append-only sessions cannot be rewritten. Dropping the junk from the REQUEST VIEW restores a legal
+ * transcript (TR3 rejoins its batch). Deterministic ⇒ byte-stable per request ⇒ prefix-cache safe.
+ * New sessions never contain these (the loop exits cleanly on abort; the harness skips persisting them).
+ */
+export function dropEmptyFailureAssistants(messages) {
+    const isJunk = (m) => {
+        if (m.role !== "assistant")
+            return false;
+        const a = m;
+        if (a.stopReason !== "aborted" && a.stopReason !== "error")
+            return false;
+        return a.content.every((c) => c.type === "text" ? (c.text ?? "").trim() === "" : c.type === "thinking" ? (c.thinking ?? "").trim() === "" : false);
+    };
+    return messages.some(isJunk) ? messages.filter((m) => !isJunk(m)) : messages;
+}
+export function clearStaleToolResults(messages, opts) {
+    const cpt = opts.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+    // design/123 D3: trigger + internal accounting start from the ANCHORED estimate when provided
+    // (billed truth), else the legacy structural sum. `anchorIdx` marks the usage-anchor message:
+    // clearing at/before it decrements 0 (see ContextEditOptions.anchoredTotalTokens).
+    const anchored = opts.anchoredTotalTokens !== undefined;
+    let total;
+    let anchorIdx = -1;
+    if (anchored) {
+        total = opts.anchoredTotalTokens;
+        anchorIdx = estimateContextTokens(messages, cpt).lastUsageIndex ?? -1;
+    }
+    else {
+        total = 0;
+        for (const m of messages) {
+            total += estimateTokens(m, cpt);
+        }
+    }
+    if (total <= opts.budgetTokens) {
+        return messages;
+    }
+    const keep = opts.keepRecentToolResults ?? 3;
+    // checklist #54 (CC microCompact.ts:226-241 `collectCompactableToolIds`): only results from
+    // whitelisted tools are candidates. The keep-recent window is computed over the CANDIDATES
+    // (CC microCompact.ts:461-463: `keepSet = compactableIds.slice(-keepRecent)`) — a
+    // non-compactable result neither clears nor consumes a keep slot.
+    const compactable = opts.compactableTools ?? COMPACTABLE_TOOLS;
+    const toolResultIdx = messages.flatMap((m, i) => isToolResult(m) && !isCleared(m) && compactable.has(m.toolName ?? "") ? [i] : []);
+    const clearable = toolResultIdx.slice(0, Math.max(0, toolResultIdx.length - keep)); // all but the last `keep`
+    if (clearable.length === 0) {
+        return messages;
+    }
+    const out = messages.slice();
+    let current = total;
+    for (const idx of clearable) {
+        if (current <= opts.budgetTokens) {
+            break;
+        }
+        const before = estimateTokens(out[idx], cpt);
+        // roadmap #6②: offload-then-clear — the marker becomes pageable (ReadToolResult ref) instead of
+        // a dead end. Best-effort: a throwing persist falls back to the bare marker, never fails the
+        // request build. Only text is offloaded (images have their own aggregate media cap).
+        let marker = CLEARED_MARKER;
+        if (opts.offload) {
+            const msg = out[idx];
+            const fullText = Array.isArray(msg.content)
+                ? msg.content
+                    .filter((c) => c?.type === "text" && typeof c.text === "string")
+                    .map((c) => c.text)
+                    .join("\n")
+                : "";
+            if (msg.toolCallId && fullText.trim().length > 0) {
+                try {
+                    marker = clearedWithRef(opts.offload.persist(msg.toolCallId, fullText));
+                }
+                catch {
+                    marker = CLEARED_MARKER;
+                }
+            }
+        }
+        const cleared = {
+            ...out[idx],
+            content: [{ type: "text", text: marker }],
+        };
+        out[idx] = cleared;
+        // Anchored coordinate (design/123 D3): a pre-anchor clear does NOT reduce the anchored total —
+        // decrement 0 and keep clearing deeper; only post-anchor content decrements structurally.
+        current -= idx > anchorIdx ? before - estimateTokens(cleared, cpt) : 0;
+    }
+    return out;
+}
+/** The token budget at which context-editing begins for a model (below the harder guard trim). */
+export function editBudget(model) {
+    const window = model.contextTokens ?? model.contextWindow;
+    return Math.floor(window * EDIT_FRACTION);
+}
+//# sourceMappingURL=context-edit.js.map

package/dist/core/context-edit.js.map

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

package/dist/core/context-guard.d.ts

@@ -0,0 +1,43 @@
+import type { AgentMessage } from "../internal/harness.js";
+import type { Model } from "../internal/llm.js";
+/**
+ * Last-resort, in-task context trim. Proper compaction (LLM summary) runs *between* tasks;
+ * this prevents a single task whose internal tool-loop balloons from overflowing the window.
+ *
+ * Keeps all summary messages (compaction/branch) and the most recent messages that fit the
+ * budget, dropping older regular messages at a safe boundary (never starting on an orphan
+ * toolResult). Returns the original array when already within budget.
+ *
+ * design/123 D3 (codex-B1 = fable-M5) — anchored accounting: when `anchoredTotalTokens`
+ * (= `estimateContextTokens(messages, charsPerToken).tokens` for the SAME array) is provided, the
+ * trigger gate and the internal bookkeeping start from the usage-anchored value instead of the
+ * structural sum (which underestimates code/CJK and lets over-window requests through). Dropping a
+ * message AFTER the usage anchor reduces the accounted total by its structural estimate; dropping a
+ * message AT/BEFORE the anchor reduces it by ZERO (the anchor usage was billed with that content —
+ * a request-view drop only pays off on the NEXT request), so the trim keeps cutting deeper until
+ * the anchored total meets the budget or only the minimal tail is left. Absent ⇒ legacy structural
+ * behavior, byte-identical. `charsPerToken` (design/123 D2): structural coefficient, default 4.
+ */
+export declare function trimToBudget(messages: AgentMessage[], budgetTokens: number, anchoredTotalTokens?: number, charsPerToken?: number): AgentMessage[];
+/**
+ * design/123 D3 belt (invariant-level, live-caught 16k 400s): the FINAL request view must never
+ * contain a toolResult whose tool-call assistant is absent — strict gateways hard-400 on it
+ * ("Messages with role 'tool' must be a response to a preceding message with 'tool_calls'"). Every
+ * individual producer is turn-aligned (findCutPoint never cuts on a toolResult; trimToBudget
+ * turn-aligns its floor), but NO pipeline combination may ship an orphan, so the prepare-task
+ * context hook sweeps its output through this last. Deterministic ⇒ byte-stable per request ⇒
+ * prefix-cache safe. Returns the SAME array when clean (zero-cost fast path); `dropped` carries a
+ * diagnostic per removed orphan (toolCallId + neighbor roles) for onError attribution.
+ */
+export declare function dropOrphanToolResults(messages: AgentMessage[]): {
+    messages: AgentMessage[];
+    dropped: Array<{
+        toolCallId: string;
+        index: number;
+        prevRole: string;
+        nextRole: string;
+    }>;
+};
+/** Budget the in-task guard targets for a model. */
+export declare function guardBudget(model: Model): number;
+//# sourceMappingURL=context-guard.d.ts.map

package/dist/core/context-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-guard.d.ts","sourceRoot":"","sources":["../../src/core/context-guard.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAYhD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,YAAY,EAAE,EACxB,YAAY,EAAE,MAAM,EACpB,mBAAmB,CAAC,EAAE,MAAM,EAC5B,aAAa,CAAC,EAAE,MAAM,GACrB,YAAY,EAAE,CA4FhB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG;IAC/D,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3F,CAkCA;AAED,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAGhD"}