@sema-agent/core 5.64.0 → 6.0.0

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

@@ -67,6 +67,32 @@ export declare function contextEditFrontier(window: number): number;
  * re-run when the frontier pass is off → in-turn forced compaction behind the adopt seam → trim
  * demoted to the disaster-only last resort), so the default configuration never hands an
  * under-20k refusal straight to a message-dropping trim.
+ *
+ * WHOLE-MACHINE CROSS-CHECK against the 2.1.250 corpus (design/374 slice 4 — the "the knob number
+ * was copied, the machine was not" disease is checked by naming the machine's parts, not the one
+ * number). CC's four load-bearing parts, each against its 250 coordinate, all verified present here:
+ *   ① the ≥20000-token minimum-savings gate — {@link MIN_CLEAR_SAVINGS_TOKENS} vs `Mnn`
+ *      (cli250.js:41714, `BBn`: `if (tokensSaved < Mnn) return null`). CC gates TWICE (execution +
+ *      before asking the server to reject); sema has one point because the "ask for the rejection"
+ *      half needs a cooperating server (see ④).
+ *   ② the nine-member clearable whitelist — {@link COMPACTABLE_TOOLS} vs `eQt` (cli250.js:41714),
+ *      re-resolved member-by-member off the 250 corpus, byte-identical (see that constant).
+ *   ③ cleared-but-recoverable — CC replaces the content with a POINTER, not a void
+ *      (`<persisted-output>Tool result saved to: {path}\n\nUse Read to view</persisted-output>`,
+ *      cli250.js:40044), which is what makes a keep window of 5 survivable at all. Ours is the same
+ *      construction in this engine's carrier: the full text is offloaded first and the marker
+ *      carries the store ref ({@link ContextEditOptions.offload} → {@link clearOneResult}), read
+ *      back through ReadToolResult instead of a filesystem path (registered divergence D-9). The
+ *      runner wires it on BOTH arms by default — the frontier pass and the MC-R rejection arm share
+ *      one persist closure — so the shipped default clears to a pointer, never to a dead end.
+ *   ④ the TRIGGER — CC's client machine fires ONLY on the server's `context_hint` 422/424 refusal
+ *      (cli250.js:58375; `tengu_time_based_microcompact` is a historical event name, its `trigger`
+ *      is the constant `"context_hint"`). Under BYOM there is no such server, so the ask half is
+ *      unportable and the refusal half is aligned on wire truth (the MC-R arm classifies the
+ *      provider's own context-overflow refusal) — registered divergence D-3. sema additionally
+ *      keeps a PROACTIVE frontier trigger CC's client does not have, anchored to Anthropic's
+ *      platform context-management policy rather than to CC-CLI — registered divergence D-1, and
+ *      re-stated at {@link clearStaleToolResults}'s ANCHOR paragraph.
  */
 export type ContextEditMachine = "legacy" | "cc";
 /**
@@ -82,8 +108,10 @@ export type ContextEditMachine = "legacy" | "cc";
  *    exactly the terminal-batch shape that needs it. This is why the slice-3 "keep default 3→5"
  *    flip rides the MACHINE default, not this constant: painting 5 onto the opt-out machine would
  *    recreate the probed failure inside the escape hatch.
- *  - CC machine (the default since slice 3): 5 (2.1.223 `uAp`; same value on CC 88's
- *    `timeBasedMCConfig` — stable across both corpus generations). The #384 adjudication adopted 5
+ *  - CC machine (the default since slice 3): 5 (2.1.223 `uAp`; 2.1.250 `var k = 5` at the call site
+ *    cli250.js:58375, and 2.1.245 carries the same value — zero drift across 245→250; same value
+ *    again on CC 88's `timeBasedMCConfig`, i.e. stable across all three corpus generations, and it
+ *    is a hard-coded constant upstream, not a setting). The #384 adjudication adopted 5
  *    CONDITIONAL on the whole machine coming with it (20k gate + deep clear + re-ordered
  *    backstops); the cc machine carries that condition, and slice 3's backstop re-ordering
  *    completed it — 5 is now the effective default keep, and the 200k probe above is answered by
@@ -92,7 +120,8 @@ export type ContextEditMachine = "legacy" | "cc";
  */
 export declare const DEFAULT_KEEP_RECENT_TOOL_RESULTS = 3;
 export declare const CC_DEFAULT_KEEP_RECENT_TOOL_RESULTS = 5;
-/** design/374 §3.1 — CC's minimum-savings gate (`vUs` :397773): the cc machine refuses to clear at
+/** design/374 §3.1 — CC's minimum-savings gate (`vUs` :397773; 2.1.250 `Mnn` cli250.js:41714, same
+ *  value): the cc machine refuses to clear at
  *  all unless the structural estimate of what WOULD be cleared reaches this many tokens. Rationale
  *  (independent of "CC does it"): every clear breaks the provider prefix cache once, so a clear that
  *  saves less than the re-prefill it causes is a net loss; the gate prices that trade. The LEGACY
@@ -105,7 +134,18 @@ export declare const MIN_KEEP_RECENT_TOOL_RESULTS = 1;
  * 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
+ * cheap-to-regenerate I/O.
+ *
+ * RE-VERIFIED against the 2.1.250 corpus (design/374 slice 4, member-by-member — a set is exactly
+ * the shape where "the count still matches" is not evidence): `eQt = new Set([wt, ...VD, Yo, Xo,
+ * yO, Yr, tn, er])` at cli250.js:41714, whose aliases resolve to `wt`="Read", `VD`=[`Xe`="Bash",
+ * `Nt`="PowerShell"], `Yo`="Grep", `Xo`="Glob", `yO`="WebSearch", `Yr`="WebFetch", `tn`="Edit",
+ * `er`="Write" — nine members, byte-identical to the set below, zero drift from the 223 reading.
+ * The exclusion side is the load-bearing half and is unchanged too: everything NOT here is
+ * PRESERVED (Agent/Task/Skill/ToolSearch/TodoWrite/Monitor/SendMessage/NotebookEdit and ALL MCP
+ * tools are never content-cleared by this pass, upstream or here).
+ *
+ * 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
@@ -184,7 +224,9 @@ export interface ContextEditOptions {
      * Absent ⇒ legacy structural gate + accounting (byte-identical behavior).
      */
     anchoredTotalTokens?: number;
-    /** design/123 D2 — structural coefficient (`Model.charsPerToken`); default 4. */
+    /** design/123 D2 — structural coefficient (`Model.charsPerToken`); default 3 (design/374 slice 4;
+     *  it was 4 before). Note this does NOT reach the cc machine's ≥20k gate, which is CC-exactly
+     *  hard-coded to 4 — see {@link structuralClearSavings}. */
     charsPerToken?: number;
     /**
      * checklist #54 — which tools' results are clearable. Defaults to {@link COMPACTABLE_TOOLS}

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

@@ -16,7 +16,7 @@ import type { Model } from "../internal/llm.js";
  * 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.
+ * behavior, byte-identical. `charsPerToken` (design/123 D2): structural coefficient, default 3 (design/374 slice 4).
  */
 export declare function trimToBudget(messages: AgentMessage[], budgetTokens: number, anchoredTotalTokens?: number, charsPerToken?: number): AgentMessage[];
 /**

package/dist/core/file-history-retention.d.ts

@@ -0,0 +1,106 @@
+/**
+ * design/381 §片2 — the engine's OWN bound on file-history growth, and the door its one knob passes
+ * through.
+ *
+ * The hole this closes: `FileHistoryStore.reap` is a complete, contract-tested GC verb that nothing
+ * in the engine ever called. Every turn of a wired session commits one more boundary, each boundary
+ * is a complete mapping over the tracked set, and no seat anywhere dropped the old ones — so a long
+ * session's history grew without bound, silently, which is precisely the shape the bad-value
+ * loudness rule exists to forbid (a limit nobody states is still a limit; it is just the disk's).
+ * The bundled backends therefore carry the bound THEMSELVES: each one commits a boundary and then
+ * trims its scope back to the retention bound, and a host that wants the GC schedule for itself
+ * says so (`keep: "unbounded"`) rather than discovering the default by running out of disk.
+ *
+ * PROVENANCE OF THE DEFAULT (not a taste call, and not a JSDoc-only constraint): the reference
+ * implementation caps its own file-history at the newest 100 snapshots and evicts the rest — CC
+ * 2.1.250 holds the cap as a module constant (`R1e = 100`) and applies it in the snapshot reducer
+ * (`if (E.length > R1e) R = E.slice(-R1e), <evict>(E.slice(0, E.length - R1e), R, …).catch(…)`),
+ * i.e. keep the newest N by commit order, hand the evicted ones to a best-effort eviction pass, and
+ * never let that pass fail the turn that triggered it. Its eviction unlinks a backup only when no
+ * surviving snapshot references it AND its version is not 1 — the same v1-permanence law this
+ * store's `reap` already implements. design/381 §片2 carries the number over as "边界上限(默认
+ * 100,store 旋钮)", which is the shape below: engine default, store-level, host-overridable.
+ *
+ * @see {@link import("./retention-policy.js").assertRetentionPolicy} — the sibling row stores' door.
+ *   This one is separate because its admissible range is different (see {@link refuseRetentionPolicy}).
+ */
+export declare const DEFAULT_FILE_HISTORY_BOUNDARY_KEEP = 100;
+/**
+ * The file-history retention knob, as a deployment writes it. ONE knob on purpose — the graph has
+ * exactly one unbounded dimension (boundaries per scope); version records and blobs are already
+ * bounded by it, because `reap` drops every version no surviving boundary references (v1 and the
+ * base-unavailable markers excepted, which are per tracked file, not per turn).
+ *
+ * Absent ⇒ {@link DEFAULT_FILE_HISTORY_BOUNDARY_KEEP}. Every other reading of a badly-formed value
+ * is a REFUSAL at construction, never a quiet fallback — see {@link resolveFileHistoryRetention}.
+ */
+export interface FileHistoryRetentionPolicy {
+    /**
+     * How many of a scope's NEWEST boundaries survive each retention pass. A whole number `>= 1`, or
+     * the literal `"unbounded"` to switch the store's self-trim OFF and take the GC schedule over
+     * (the host then owns calling {@link import("./file-history-store.js").FileHistoryStore.reap};
+     * nothing else collects boundaries).
+     *
+     * `0` is REFUSED rather than accepted as "keep nothing": a boundary is minted by the very commit
+     * that would then reap it, so a store configured that way would answer `ok` to every `snapshot`
+     * and `false` to every `canRestore` — a rewind seat that is on, reports success, and can never
+     * restore anything. `"unbounded"` is the ONE spelling of "do not trim"; omitting the knob is NOT
+     * that spelling — it selects the engine default and therefore trims (cross-review round 3 caught
+     * this said the opposite here and in the refusal text, which would have sent an operator who
+     * wanted everything kept down the path that deletes).
+     */
+    keep?: number | "unbounded";
+}
+/**
+ * The retention door: resolve a deployment's policy to a boundary cap, or REFUSE loudly.
+ *
+ * Returns the cap (a whole number `>= 1`), or `null` for the explicit `"unbounded"` opt-out. Called
+ * at CONSTRUCTION by every bundled backend, so a malformed policy fails where the operator wired it
+ * rather than mid-session inside a GC pass they cannot see.
+ *
+ * The three ways a value can be bad each get their own named exit — none of them falls back to the
+ * default, because a retention knob that quietly became a different number is the failure this whole
+ * seam exists to remove:
+ *  1. GARBAGE — the policy is not a knob bag, a knob is misspelled, or `keep` is not a whole number
+ *     (NaN from a `Number(cfg.keep)` on a missing field, `Infinity`, `2.5`, `"100"`, `null`).
+ *  2. OUT OF RANGE — a negative `keep`. (Reached by the same route as NaN in the sibling stores'
+ *     history: `slice(Math.max(0, keep))` turns both into `slice(0)` = delete everything.)
+ *  3. CONTRADICTORY — `keep: 0`, well-formed and in the range its siblings accept, but self-cancelling
+ *     here; refused with the ONE spelling of "do not trim" named, and with what omission really does
+ *     said out loud so the remediation cannot be followed into the opposite outcome.
+ *
+ * @param label the seam the operator configured, so the refusal names it.
+ */
+export declare function resolveFileHistoryRetention(label: string, policy: FileHistoryRetentionPolicy | undefined): number | null;
+/**
+ * Which boundaries survive the pass that `justCommitted`'s commit triggered — the SELECTION half,
+ * shared so the two bundled backends (and an out-of-tree twin) cannot drift on which boundary dies.
+ *
+ * Returns `null` when the scope is still within its bound, which is the answer the caller wants
+ * cheaply: no `reap` call at all, so a session under the cap pays one directory listing per turn and
+ * nothing else. Otherwise returns the keep set for
+ * {@link import("./file-history-store.js").FileHistoryStore.reap} — the newest `keep` ids, with
+ * `justCommitted` PINNED into it unconditionally.
+ *
+ * The pin is not belt-and-braces. `orderedOldestFirst` is whatever commit order its backend can
+ * PROVE, and the two bundled ones prove different amounts: the in-memory reference reads an
+ * insertion-ordered map (exact), while the durable one reads each boundary's own publication stamp,
+ * falling back to file mtime for records written before that field or rebuilt from an import, and
+ * to the entry id for ties. A clock stepped backwards, or a host minting non-monotonic ids of its
+ * own, can still invert two neighbours there.
+ * An ordering that is off by one place costs a different-but-equally-legal retention choice; an
+ * ordering that put the JUST-COMMITTED boundary at the bottom would cost this turn its rewind seat.
+ * Pinning makes the second outcome unreachable by construction rather than by trusting the clock.
+ *
+ * One more place the order is only as good as its source, said plainly rather than assumed away: an
+ * envelope round trip (`exportHistory` → `importHistory`) writes boundaries in CANONICAL — i.e.
+ * lexicographic — entry-id order, so a scope rebuilt from one has entry-id order where it used to
+ * have commit order. For engine-minted uuidv7 ids those are the same order; for a foreign graph's
+ * ids they need not be, and such a scope's oldest-first reading is by id. The consequence is again
+ * only WHICH legal boundary is retained, and the just-committed pin still holds.
+ *
+ * @param orderedOldestFirst every committed boundary id in the scope, oldest first.
+ * @param justCommitted the boundary whose commit triggered the pass.
+ * @param keep the resolved cap (`>= 1`).
+ */
+export declare function fileHistoryBoundariesToKeep(orderedOldestFirst: readonly string[], justCommitted: string, keep: number): string[] | null;

package/dist/core/file-history-retention.js

@@ -0,0 +1,36 @@
+import { refuseRetentionPolicy } from "./retention-policy.js";
+export const DEFAULT_FILE_HISTORY_BOUNDARY_KEEP = 100;
+const KNOWN_KNOBS = new Set(["keep"]);
+export function resolveFileHistoryRetention(label, policy) {
+    if (policy === undefined)
+        return DEFAULT_FILE_HISTORY_BOUNDARY_KEEP;
+    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+        refuseRetentionPolicy(label, "retention", policy, `an object of retention knobs (${[...KNOWN_KNOBS].join(", ")}) or omitted`);
+    }
+    const unknown = Object.keys(policy).filter((k) => !KNOWN_KNOBS.has(k));
+    if (unknown.length > 0) {
+        const first = unknown[0];
+        refuseRetentionPolicy(label, `retention.${first}`, policy[first], `omitted — ${JSON.stringify(first)} is not a retention knob (the only knob is "keep"), and a misspelled one would leave the engine default in force while the operator believes their own number is`);
+    }
+    const keep = policy.keep;
+    if (keep === undefined)
+        return DEFAULT_FILE_HISTORY_BOUNDARY_KEEP;
+    if (keep === "unbounded")
+        return null;
+    if (keep === 0) {
+        refuseRetentionPolicy(label, "retention.keep", keep, `at least 1 boundary — a cap of 0 would reap the boundary its own commit just minted, leaving a rewind seat that answers ok to every snapshot and false to every canRestore; write "unbounded" to mean "do not trim" (omitting the knob does NOT mean that — it selects the engine default of ${DEFAULT_FILE_HISTORY_BOUNDARY_KEEP})`);
+    }
+    if (typeof keep !== "number" || !Number.isInteger(keep) || keep < 1) {
+        refuseRetentionPolicy(label, "retention.keep", keep, `a whole number of boundaries, 1 or more, or the literal "unbounded"`);
+    }
+    return keep;
+}
+export function fileHistoryBoundariesToKeep(orderedOldestFirst, justCommitted, keep) {
+    if (orderedOldestFirst.length <= keep)
+        return null;
+    const survivors = new Set([justCommitted]);
+    for (let i = orderedOldestFirst.length - 1; i >= 0 && survivors.size < keep; i--) {
+        survivors.add(orderedOldestFirst[i]);
+    }
+    return [...survivors];
+}