@sema-agent/core 5.55.0 → 5.57.0

package/dist/brain/route-conformance.js

@@ -0,0 +1,136 @@
+export const ROUTE_ADJUDICATION_CONFORMANCE_CORPUS = [
+    {
+        name: "per-model-on-root",
+        intent: "a per-model credential is paired by construction, on the deployment root",
+        model: { id: "m-main", baseUrl: "https://gw.example.com" },
+        credential: { source: "per-model", apiKey: "k-main" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "per-model" },
+    },
+    {
+        name: "per-model-off-root",
+        intent: "a per-model credential is paired by construction even off the deployment root (the resolver was asked about THIS entry)",
+        model: { id: "m-third", baseUrl: "https://third-party.example.net/v1" },
+        credential: { source: "per-model", apiKey: "k-third" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "per-model" },
+    },
+    {
+        name: "per-model-headers-borne",
+        intent: "an entry-declared auth header is a per-model credential (headers-borne)",
+        model: { id: "m-hdr", baseUrl: "https://third-party.example.net" },
+        credential: { source: "per-model", headersBorne: true, carrierBag: "model" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "per-model" },
+    },
+    {
+        name: "per-model-empty-string-key",
+        intent: "an empty-string per-model key is a PRESENT credential (fails closed at emit, never falls to the deployment key)",
+        model: { id: "m-degraded", baseUrl: "https://third-party.example.net" },
+        credential: { source: "per-model", apiKey: "" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "per-model" },
+    },
+    {
+        name: "deployment-paired",
+        intent: "the main-gateway pass: entry URL === declared config root, deployment credential allowed",
+        model: { id: "m-main", baseUrl: "https://gw.example.com" },
+        credential: { source: "deployment-config", apiKey: "k-gw" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "paired" },
+    },
+    {
+        name: "deployment-paired-empty-entry",
+        intent: "an entry with an empty baseUrl targets the config root — deployment credential paired",
+        model: { id: "m-implicit", baseUrl: "" },
+        credential: { source: "deployment-config", apiKey: "k-gw" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "paired" },
+    },
+    {
+        name: "deployment-paired-slash-normalized",
+        intent: "trailing slashes do not break the pairing (both halves normalize before compare)",
+        model: { id: "m-main", baseUrl: "https://gw.example.com/" },
+        credential: { source: "deployment-config", apiKey: "k-gw" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "paired" },
+    },
+    {
+        name: "deployment-mismatch",
+        intent: "THE torn pair: deployment credential + entry URL off the declared root = refusal, not a silently-followed key",
+        model: { id: "m-third", baseUrl: "https://third-party.example.net/v1" },
+        credential: { source: "deployment-config", apiKey: "k-gw" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: false, code: "route.credential_mismatch" },
+        leg: "named",
+    },
+    {
+        name: "deployment-mismatch-path-differs",
+        intent: "a differing path is a differing root (no prefix leniency — the credential goes to the exact declared root only)",
+        model: { id: "m-path", baseUrl: "https://gw.example.com/other" },
+        credential: { source: "deployment-config", apiKey: "k-gw" },
+        config: { baseUrl: "https://gw.example.com/v1" },
+        expect: { ok: false, code: "route.credential_mismatch" },
+        leg: "named",
+    },
+    {
+        name: "deployment-mismatch-derived-leg",
+        intent: "the same torn pair on a DERIVED model: same verdict; the engine disposes of it as fallback-to-primary + notice",
+        model: { id: "m-summarize", baseUrl: "https://third-party.example.net" },
+        credential: { source: "deployment-config", apiKey: "k-gw" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: false, code: "route.credential_mismatch" },
+        leg: "derived",
+    },
+    {
+        name: "deployment-headers-borne-mismatch",
+        intent: "a deployment auth HEADER is the same fallback arm: off the declared root it is refused, not sent",
+        model: { id: "m-third", baseUrl: "https://third-party.example.net" },
+        credential: { source: "deployment-config", headersBorne: true, carrierBag: "config" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: false, code: "route.credential_mismatch" },
+        leg: "named",
+    },
+    {
+        name: "deployment-unpinned",
+        intent: "the quick-start posture: config key with NO declared config root stays allowed (single-endpoint form: key on config, URL on the model) — surfaced as unpinned, not refused",
+        model: { id: "m-quickstart", baseUrl: "https://api.example.com/v1" },
+        credential: { source: "deployment-config", apiKey: "k-quickstart" },
+        config: {},
+        expect: { ok: true, posture: "unpinned" },
+    },
+    {
+        name: "absent-keyless-on-root",
+        intent: "a keyless deployment on its own root has nothing to protect — allowed",
+        model: { id: "m-local", baseUrl: "http://127.0.0.1:8000/v1" },
+        credential: { source: "absent" },
+        config: { baseUrl: "http://127.0.0.1:8000/v1" },
+        expect: { ok: true, posture: "keyless" },
+    },
+    {
+        name: "absent-keyless-undeclared",
+        intent: "keyless with no declared config root (URL only on the model) — allowed",
+        model: { id: "m-local", baseUrl: "http://127.0.0.1:8000/v1" },
+        credential: { source: "absent" },
+        config: {},
+        expect: { ok: true, posture: "keyless" },
+    },
+    {
+        name: "absent-missing-off-root",
+        intent: "an entry declaring its OWN URL away from a DECLARED deployment root with no credential anywhere is a configuration hole — loud refusal beats an unauthenticated request to a third-party host",
+        model: { id: "m-third", baseUrl: "https://third-party.example.net" },
+        credential: { source: "absent" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: false, code: "route.credential_missing" },
+        leg: "named",
+    },
+    {
+        name: "absent-missing-derived-leg",
+        intent: "the same hole on a DERIVED model: same verdict; engine disposition is fallback-to-primary + notice",
+        model: { id: "m-summarize", baseUrl: "https://third-party.example.net" },
+        credential: { source: "absent" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: false, code: "route.credential_missing" },
+        leg: "derived",
+    },
+];

package/dist/brain/routing.js

@@ -15,13 +15,17 @@ function errorMessage(model, text) {
 }
 export function createRoutingBrain(routes, opts = {}) {
     const by = opts.by ?? "provider";
-    const stream = (model, context, options) => {
+    const resolveTarget = (model) => {
         const key = by === "api" ? model.api : model.provider;
         const routed = Object.hasOwn(routes, key) ? routes[key] : undefined;
         const matched = routed !== null && typeof routed === "object" && typeof routed.stream === "function"
             ? routed
             : undefined;
-        const target = matched ?? opts.fallback;
+        return matched ?? opts.fallback;
+    };
+    const stream = (model, context, options) => {
+        const key = by === "api" ? model.api : model.provider;
+        const target = resolveTarget(model);
         if (!target) {
             const out = createAssistantMessageEventStream();
             out.push({
@@ -33,5 +37,6 @@ export function createRoutingBrain(routes, opts = {}) {
         }
         return target.stream(model, context, options);
     };
-    return { stream };
+    const adjudicateRoute = (model, perModelAuth) => resolveTarget(model)?.adjudicateRoute?.(model, perModelAuth);
+    return { stream, adjudicateRoute };
 }

package/dist/core/auto-compaction.d.ts

@@ -383,7 +383,12 @@ export interface MaybeCompactOptions {
      * compaction is FORCED through the real `generateSummary` LLM path even if the provider would hit — this
      * bounds summary drift from indefinite reuse. The caller owns the counter via {@link onCompaction}
      * (`reused`) and feeds it back via this option; core treats `summaryProvider` as if absent for that one
-     * boundary when `consecutiveProviderReuse >= maxConsecutiveProviderReuse`. Default `3` (CC parity).
+     * boundary when `consecutiveProviderReuse >= maxConsecutiveProviderReuse`. Default `3`, a
+     * SEMA choice — the earlier "(CC parity)" label was unsupported and is withdrawn (anchoring
+     * re-check 2026-08-23: CC 2.1.223 has no external summary provider and no reuse concept at all;
+     * its three 3s are the PTL retry cap `b$d`, the consecutive-compaction-failure breaker `C$d` and
+     * the rapid-refill trip `Q3u`, none of them this). 3 is picked for the same reason those are: a
+     * small bound on how long a degraded path may keep answering before the real one is forced.
      * `0`/undefined with no `consecutiveProviderReuse` = provider always consulted (no forced refresh).
      */
     maxConsecutiveProviderReuse?: number;
@@ -618,9 +623,17 @@ export declare function maybeCompact(opts: MaybeCompactOptions): Promise<{
  *      (clamped ≥0, so ≤0 means "freed nothing") — orthogonal to rule 2/3's threshold test, which
  *      misses this shape because the bloated post (44609) can still sit UNDER the threshold (44800),
  *      so rule 3 alone would re-enable the force and repeat the negative-yield pass every boundary.
- *      SEMA-ONLY DEFENSE, not a CC port: CC's full compact keeps tail 0 and monotonically shrinks
- *      (capture §A4), and CC has no request-layer trim, so this regime cannot exist there — it is a
- *      derived interaction of our trim seam × keep-tail × attachment mass. Scoped to trim-forced
+ *      SEMA-ONLY DEFENSE, not a CC port — but the ORIGINAL justification for that label was wrong
+ *      on both of its premises, and the corrected pair still supports it. (a) "CC's full compact
+ *      keeps tail 0 and monotonically shrinks" describes the `GNo` branch, which a LOCAL threshold
+ *      compaction never reaches (CC 2.1.223 `y9s` :432704 routes local passes to the reactive
+ *      pipeline, which preserves the last group verbatim — `YMo` :399971, `s = 1` :399982); CC's
+ *      default posture therefore has a keep-tail, exactly as ours does. (b) "CC has no
+ *      request-layer trim" holds only for the MAIN conversation request: CC does own a
+ *      keep-the-newest-groups-that-fit primitive (`UPb` :645223), whose only caller is the
+ *      prompt-hook evaluator's own transcript window, not a main-lane request. What actually makes
+ *      this regime ours is the third factor — the trim seam feeding a deceived usage anchor, and
+ *      attachment mass re-entering after the fold — not the absence of a keep-tail. Scoped to trim-forced
  *      passes only (`trimForced`), so Seam C reused-summary landings (freed≈0 by design) on the
  *      natural/manual paths never trip it. Release path unchanged: backoff gates only the FORCE, a
  *      later natural landing that posts under threshold (rule 3, non-trim-forced) turns it back off.

package/dist/core/auto-compaction.js

@@ -196,6 +196,9 @@ export async function maybeCompact(opts) {
         if (prep.value.elidedMessages !== undefined && prep.value.elidedMessages > 0) {
             details.elidedMessages = prep.value.elidedMessages;
         }
+        if (prep.value.carriedUnsummarizedMessages !== undefined && prep.value.carriedUnsummarizedMessages > 0) {
+            details.unsummarizedMessages = prep.value.carriedUnsummarizedMessages;
+        }
     }
     else {
         let summaryModel = opts.compactionModel ?? opts.model;

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

@@ -14,11 +14,18 @@ export declare const EDIT_FRACTION = 0.7;
  *   effectiveWindow = autocompactWindow − min(maxOutputTokens, 20000)   (CC `Nye`, cap `uMd`)
  *   trigger         = effectiveWindow − 13000                           (CC `dSo`, buffer `rMd`)
  * i.e. trigger = W − 33000 for every model whose max output is ≥ 20k: a 200k window triggers at
- * 167000 (83.5% of nominal), a 1M window at 967000. (CC additionally ships a sonnet-5-only 1M
- * autocompact-window special of 967000 via dynamic config, making ITS 1M trigger 934000; that is a
- * per-model config delivery, not geometry — an embedder reproduces it EXACTLY via
- * `model.autoCompactTokens = 967000`, which lowers only this trigger-side window while the guard
- * and physical request budgeting stay on the 1M window — CC's dual-window shape.) We take the
+ * 167000 (83.5% of nominal), a 1M window at 967000.
+ *
+ * 1M DIVERGENCE, stated as fact rather than as an equivalence (anchoring re-check 2026-08-23): CC
+ * carries a MODEL-DEFAULT autocompact-window table (2.1.223 `j3u` :242918 — `claude-sonnet-5`
+ * default 967000, and since 223 a surface dimension: `remote_cowork` / `local-agent` 500000), so a
+ * 1M sonnet-5 gets 967000 as its window and 934000 as its trigger WITHOUT anyone configuring
+ * anything. We ship no such table: a model declaring only `contextWindow: 1e6` triggers at 967000
+ * here, 33000 LATER than CC. `model.autoCompactTokens = 967000` reproduces CC's number — but that
+ * is an EMBEDDER action against CC's product default, not the same posture, and the choice not to
+ * follow 934000 is deliberate (design/146 §1.3 argues against living on that thin a cushion). The
+ * knob itself is real and unchanged: `autoCompactTokens` lowers only this trigger-side window while
+ * the guard and physical request budgeting stay on the 1M window — CC's dual-window shape. We take the
  * 20000 cap branch unconditionally (flat 33000), i.e. the `min(maxOutputTokens, 20000)` branch is
  * deliberately NOT ported: the deduction is exact parity only for models with max output ≥ 20k. A
  * model with a smaller max output would deduct less in CC (trigger LATER); we deduct the full
@@ -51,11 +58,53 @@ export declare function contextEditFrontier(window: number): number;
  * 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.
  */
+/**
+ * How many most-recent CANDIDATE tool results keep their content when the stale-result pass runs.
+ *
+ * 3, UNCHANGED — and the fact that CC's corresponding number is 5 (2.1.223 `uAp`, and the same value
+ * on CC 88's `timeBasedMCConfig`, so it is stable across both corpus generations) is deliberately NOT
+ * adopted here. Two reasons, in order of weight:
+ *
+ *  1. MEASURED: widening the window removes this pass's only lever in the shape where a terminal
+ *     parallel batch holds exactly as many large results as the window keeps. Probed on a 200k model
+ *     with a 140k usage anchor and five 36k-char Bash results: at 3 the pass clears two and the
+ *     request lands at ~167k, UNDER the 177k request guard; at 5 nothing is clearable, the request
+ *     stays at 185k, and the guard cannot recover it either — `trimToBudget` must turn-align back to
+ *     the emitting assistant, so the whole batch is retained. The window is count-based on both
+ *     sides (CC's `slice(-keepRecent)` too), so this ceiling exists at every value; 5 simply widens
+ *     the band that reaches it.
+ *  2. SEAT: the two numbers do not govern the same machine. CC's keep-recent clear runs ONLY on the
+ *     `context_hint` rejection leg — gated off by default — and behind a hard "saves ≥ 20000 tokens
+ *     or don't bother" test, with request REFUSAL as the real backstop. Ours is on by default, is
+ *     the only reduction between the frontier and the guard, and its backstop drops messages instead
+ *     of refusing. Copying a constant across that difference is the "same name, different question"
+ *     mistake, not parity.
+ *
+ * So the VALUE is an open adjudication (recorded with the probe above), while the two things CC
+ * unambiguously answers — the floor and the candidate-scoped window — are followed exactly.
+ */
+export declare const DEFAULT_KEEP_RECENT_TOOL_RESULTS = 3;
+/** Minimum kept results — CC `EUs` :397710 `Math.max(1, keepRecent)`. See
+ *  {@link ContextEditOptions.keepRecentToolResults} for why both degenerate ends are unusable. */
+export declare const MIN_KEEP_RECENT_TOOL_RESULTS = 1;
 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. */
+    /**
+     * Always keep the content of this many most-recent CANDIDATE tool results (candidates = results
+     * from {@link compactableTools}). Default {@link DEFAULT_KEEP_RECENT_TOOL_RESULTS} = 3 — see that
+     * constant for why CC's 5 is not adopted here.
+     *
+     * Floored at 1, which IS CC's rule (`EUs` `Math.max(1, keepRecent)`), whose own source note gives
+     * the reason: 0 leaves the model with zero working tool context, and in CC's `slice(-0)` spelling
+     * it degenerates the other way into keeping everything — two unusable extremes for one value.
+     * Ours degenerated identically (a 0 or negative `keep` cleared EVERY candidate). Values that are
+     * not a non-negative safe integer are REFUSED rather than floored: a NaN used to make this whole
+     * defense silently inert (`slice(0, NaN)` = clear nothing), which is the one outcome a context
+     * defense must never reach quietly, and there is no config door upstream to announce at — this
+     * option only ever arrives as a direct argument from an embedder.
+     */
     keepRecentToolResults?: number;
     /**
      * roadmap #6② (CC contentReplacementState parity): when set, a result's FULL TEXT is offloaded to

package/dist/core/context-edit.js

@@ -27,6 +27,17 @@ export const COMPACTION_TRIGGER_BUFFER_TOKENS = 13000;
 export function contextEditFrontier(window) {
     return Math.max(window - (CONTEXT_OUTPUT_RESERVE_TOKENS + COMPACTION_TRIGGER_BUFFER_TOKENS), Math.floor(window * EDIT_FRACTION));
 }
+export const DEFAULT_KEEP_RECENT_TOOL_RESULTS = 3;
+export const MIN_KEEP_RECENT_TOOL_RESULTS = 1;
+function resolveKeepRecentToolResults(value) {
+    if (value === undefined)
+        return DEFAULT_KEEP_RECENT_TOOL_RESULTS;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`keepRecentToolResults must be a non-negative safe integer (got ${String(value)}); ` +
+            `omit it for the default ${DEFAULT_KEEP_RECENT_TOOL_RESULTS}`);
+    }
+    return Math.max(MIN_KEEP_RECENT_TOOL_RESULTS, value);
+}
 export const COMPACTABLE_TOOLS = new Set([
     "Read",
     "Bash",
@@ -74,7 +85,7 @@ export function clearStaleToolResults(messages, opts) {
     if (total <= opts.budgetTokens) {
         return messages;
     }
-    const keep = opts.keepRecentToolResults ?? 3;
+    const keep = resolveKeepRecentToolResults(opts.keepRecentToolResults);
     const compactable = opts.compactableTools ?? COMPACTABLE_TOOLS;
     const toolResultCandidates = messages.flatMap((m, i) => isToolResult(m) && !isCleared(m) && compactable.has(m.toolName) ? [{ idx: i, target: m }] : []);
     const clearable = toolResultCandidates.slice(0, Math.max(0, toolResultCandidates.length - keep));