@arnilo/prism 0.5.6 → 0.7.0

package/dist/content.js

@@ -1,7 +1,13 @@
 import { lookup as dnsLookup } from "node:dns/promises";
 import { isIP } from "node:net";
+import { assertSsrfAllowedUrl, isAllowedByCidr, isBlockedIp, MediaContentError, normalizeHostname, } from "./media-types.js";
 import { pinnedFetch } from "./pinned-fetch.js";
 import { assertPermission } from "./security.js";
+// SSRF policy, host/address types, `MediaContentError`, and the URL gate live in the leaf
+// module shared with `pinned-fetch.ts` (plan 070 Task 10); re-exported here so the
+// `@arnilo/prism` surface and the error-class identity are unchanged. `normalizeHostname`
+// is imported for internal use only — it is public through `pinned-fetch.ts`, not here.
+export { assertSsrfAllowedUrl, MediaContentError } from "./media-types.js";
 /** Known model input capability tags for `ModelCapabilities.input`. */
 export const MODEL_INPUT_CAPABILITIES = ["text", "image", "audio", "file", "document", "video"];
 /** Default per-item media byte ceiling (10 MB; aligns with coding-agent image bounds). */
@@ -26,14 +32,6 @@ export class UnsupportedModalityError extends Error {
         this.model = model.model;
     }
 }
-export class MediaContentError extends Error {
-    code;
-    constructor(code, message, options) {
-        super(message, options);
-        this.name = "MediaContentError";
-        this.code = code;
-    }
-}
 export function contentBlockInputModality(block) {
     switch (block.type) {
         case "image":
@@ -90,41 +88,6 @@ export function assertMediaBlocksWithinBounds(blocks, bounds = {}) {
         }
     }
 }
-export function assertSsrfAllowedUrl(url, policy = {}) {
-    let parsed;
-    try {
-        parsed = new URL(url);
-    }
-    catch {
-        throw new MediaContentError("ssrf_denied", "Media URL is not a valid absolute URL");
-    }
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-        throw new MediaContentError("unsupported_url_scheme", `Media URL scheme ${parsed.protocol} is not allowed`);
-    }
-    if (parsed.username || parsed.password) {
-        throw new MediaContentError("ssrf_denied", "Media URL must not embed credentials");
-    }
-    const hostname = normalizeHostname(parsed.hostname);
-    if (policy.allowedHostnames?.length) {
-        if (!policy.allowedHostnames.some((allowed) => hostname === normalizeHostname(allowed))) {
-            throw new MediaContentError("ssrf_denied", `Media URL host ${hostname} is not allow-listed`);
-        }
-        return;
-    }
-    if (policy.denyPrivateHosts === false)
-        return;
-    if (hostname === "localhost" ||
-        hostname.endsWith(".localhost") ||
-        hostname.endsWith(".local") ||
-        hostname === "metadata" ||
-        hostname === "metadata.google.internal" ||
-        hostname === "instance-data") {
-        throw new MediaContentError("ssrf_denied", `Media URL host ${hostname} is not allowed`);
-    }
-    if (isBlockedIp(hostname)) {
-        throw new MediaContentError("ssrf_denied", `Media URL host ${hostname} is not allowed`);
-    }
-}
 export function sniffMediaMimeType(bytes) {
     if (startsWith(bytes, [0x25, 0x50, 0x44, 0x46, 0x2d]))
         return "application/pdf";
@@ -364,7 +327,9 @@ async function resolvePublicAddress(hostname, resolver, signal, policy) {
     if (addresses.length > 32)
         throw new MediaContentError("fetch_failed", "Media hostname resolved to too many addresses");
     if (policy?.denyPrivateHosts !== false && !policy?.allowedHostnames?.length) {
-        if (addresses.some(({ address }) => isBlockedIp(normalizeHostname(address)))) {
+        // An allow-listed CIDR covers resolved answers too, but only the private-IP block.
+        const blocked = addresses.some(({ address }) => isBlockedIp(normalizeHostname(address)) && !isAllowedByCidr(address, policy?.allowedCidrs));
+        if (blocked) {
             throw new MediaContentError("ssrf_denied", `Media URL host ${hostname} resolved to a private address`);
         }
     }
@@ -450,61 +415,6 @@ function mediaTypesCompatible(declared, sniffed) {
         return true;
     return false;
 }
-function normalizeHostname(hostname) {
-    const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
-    return normalized.endsWith(".") ? normalized.slice(0, -1) : normalized;
-}
-function isBlockedIp(hostname) {
-    const normalized = normalizeHostname(hostname);
-    const family = isIP(normalized);
-    if (family === 4)
-        return isBlockedIpv4(normalized);
-    if (family === 6)
-        return isBlockedIpv6(normalized);
-    return false;
-}
-function isBlockedIpv4(address) {
-    const [a, b] = address.split(".").map(Number);
-    return (a === 0 ||
-        a === 10 ||
-        a === 127 ||
-        (a === 100 && b >= 64 && b <= 127) ||
-        (a === 169 && b === 254) ||
-        (a === 172 && b >= 16 && b <= 31) ||
-        (a === 192 && (b === 0 || b === 168)) ||
-        (a === 198 && (b === 18 || b === 19 || b === 51)) ||
-        (a === 203 && b === 0) ||
-        a >= 224);
-}
-function isBlockedIpv6(address) {
-    const words = parseIpv6Words(address);
-    if (!words)
-        return true;
-    if (words.every((word) => word === 0) || (words.slice(0, 7).every((word) => word === 0) && words[7] === 1))
-        return true;
-    if ((words[0] & 0xfe00) === 0xfc00)
-        return true;
-    if ((words[0] & 0xffc0) === 0xfe80 || (words[0] & 0xffc0) === 0xfec0)
-        return true;
-    if ((words[0] & 0xff00) === 0xff00)
-        return true;
-    if (words[0] === 0x2001 && words[1] === 0x0db8)
-        return true;
-    const mapped = words.slice(0, 5).every((word) => word === 0) && (words[5] === 0 || words[5] === 0xffff);
-    return mapped && isBlockedIpv4(`${words[6] >> 8}.${words[6] & 0xff}.${words[7] >> 8}.${words[7] & 0xff}`);
-}
-function parseIpv6Words(address) {
-    const parts = address.split("::");
-    if (parts.length > 2)
-        return undefined;
-    const left = parts[0] ? parts[0].split(":") : [];
-    const right = parts[1] ? parts[1].split(":") : [];
-    const missing = 8 - left.length - right.length;
-    if (missing < 0 || (parts.length === 1 && missing !== 0))
-        return undefined;
-    const words = [...left, ...Array.from({ length: missing }, () => "0"), ...right].map((part) => Number.parseInt(part, 16));
-    return words.length === 8 && words.every((word) => Number.isInteger(word) && word >= 0 && word <= 0xffff) ? words : undefined;
-}
 function startsWith(bytes, prefix) {
     if (bytes.length < prefix.length)
         return false;

package/dist/context-budget.d.ts

@@ -1,10 +1,21 @@
 import type { ContextBlock, InputAssemblyLayout, Message, ProviderRequest, Skill, ToolDefinition } from "./contracts.js";
-import { type LoadedSkillSet, type SkillsDisclosure } from "./skill-disclosure.js";
+import { type LoadedSkillSet, type SkillRenderContext, type SkillsDisclosure } from "./skill-disclosure.js";
+/**
+ * Host-supplied token estimator. Budget-only: it never reaches billing, provider
+ * usage, or the wire — it decides what the assembler evicts and nothing else.
+ */
+export type TokenEstimator = (text: string) => number;
 /** Assembler-time input budget. At least one max required when present. */
 export interface ContextBudget {
     readonly maxInputTokens?: number;
     readonly maxInputBytes?: number;
     readonly reportOmissions?: boolean;
+    /**
+     * Overrides the built-in UTF-16/4 heuristic for eviction accounting. Must return a
+     * non-negative finite token count (a NaN/negative/absent return fails the assembly
+     * closed with a `TypeError`). Byte caps are estimator-independent and always enforced.
+     */
+    readonly tokenEstimator?: TokenEstimator;
 }
 export type ContextBudgetOmissionKind = "skills" | "skill_body" | "context" | "history" | "tool_results" | "summaries" | "attachments" | "tools";
 export interface ContextBudgetOmission {
@@ -43,7 +54,7 @@ export declare function isContextBudgetError(error: unknown): error is ContextBu
 /** UTF-16 code units / 4. Estimate only — not billing. */
 export declare function estimateTextTokens(text: string): number;
 export declare function estimateTextBytes(text: string): number;
-export declare function estimateMessageTokens(message: Message): number;
+export declare function estimateMessageTokens(message: Message, estimateTokens?: TokenEstimator): number;
 export declare function estimateMessageBytes(message: Message): number;
 export declare function estimateAssemblyTokens(messages: readonly Message[]): number;
 export declare function resolveContextBudget(budget: ContextBudget): Required<Pick<ContextBudget, "reportOmissions">> & ContextBudget;
@@ -65,3 +76,22 @@ export declare function applyContextBudget(options: {
     readonly demotedSkillBodies: readonly string[];
     readonly report: ContextBudgetReport;
 };
+/** Everything the assembler will send, in the order it will send it. */
+export interface MeasureInputCostOptions {
+    readonly groups: ContextBudgetMessageGroups;
+    readonly context?: readonly ContextBlock[];
+    readonly skills?: readonly Skill[];
+    readonly tools?: readonly ToolDefinition[];
+    readonly skillContext?: SkillRenderContext;
+    readonly demotedBodies?: ReadonlySet<string>;
+    readonly estimateTokens?: TokenEstimator;
+}
+/**
+ * One O(n) cost measurement of the whole request (groups, context, skills, tool declarations).
+ * Shared with the attention-compiler gate, which measures once per turn and then subtracts a
+ * per-mutation delta instead of re-measuring — the same trick `applyContextBudget` uses.
+ */
+export declare function measureInputCost(options: MeasureInputCostOptions): {
+    tokens: number;
+    bytes: number;
+};

package/dist/context-budget.js

@@ -22,8 +22,8 @@ export function estimateTextTokens(text) {
 export function estimateTextBytes(text) {
     return Buffer.byteLength(text, "utf8");
 }
-export function estimateMessageTokens(message) {
-    return estimateTextTokens(messageText(message));
+export function estimateMessageTokens(message, estimateTokens = estimateTextTokens) {
+    return estimateTokens(messageText(message));
 }
 export function estimateMessageBytes(message) {
     return estimateTextBytes(messageText(message));
@@ -41,6 +41,9 @@ export function resolveContextBudget(budget) {
         assertPositiveCap(budget.maxInputTokens, "maxInputTokens", HARD_MAX_CONTEXT_BUDGET_TOKENS);
     if (hasBytes)
         assertPositiveCap(budget.maxInputBytes, "maxInputBytes", HARD_MAX_CONTEXT_BUDGET_BYTES);
+    if (budget.tokenEstimator !== undefined && typeof budget.tokenEstimator !== "function") {
+        throw new TypeError("contextBudget.tokenEstimator must be a function");
+    }
     return { ...budget, reportOmissions: budget.reportOmissions === true };
 }
 export function getContextBudgetReport(request) {
@@ -49,6 +52,7 @@ export function getContextBudgetReport(request) {
 }
 export function applyContextBudget(options) {
     const budget = resolveContextBudget(options.budget);
+    const estimateTokens = resolveTokenEstimator(budget);
     const layout = options.layout ?? "cache_aware";
     const groups = {
         instructions: [...options.groups.instructions],
@@ -67,9 +71,9 @@ export function applyContextBudget(options) {
     const historyCursor = { index: 0 };
     // Measure once, then subtract each dropped item's own estimate (dropNext computes it
     // with the same estimators) — avoids an O(n²) re-scan of the full keep-set per drop.
-    const kept = measureAll(groups, context, skills, tools, skillContext, demotedBodies);
+    const kept = measureInputCost({ groups, context, skills, tools, skillContext, demotedBodies, estimateTokens });
     while (overBudget(kept, budget)) {
-        const drop = dropNext(groups, context, skills, layout, skillContext, demotedBodies, historyCursor);
+        const drop = dropNext(groups, context, skills, layout, skillContext, demotedBodies, historyCursor, estimateTokens);
         if (!drop) {
             throw new ContextBudgetError();
         }
@@ -97,7 +101,7 @@ export function applyContextBudget(options) {
         },
     };
 }
-function dropNext(groups, context, skills, layout, skillContext, demotedBodies, historyCursor) {
+function dropNext(groups, context, skills, layout, skillContext, demotedBodies, historyCursor, estimateTokens) {
     // ponytail: drop droppable groups in layout order; within history, advance a cursor and slice once.
     // cache_aware keeps attachments longer so stable prefix stays intact while budget still allows it.
     const order = layout === "cache_aware"
@@ -106,19 +110,19 @@ function dropNext(groups, context, skills, layout, skillContext, demotedBodies,
     for (const kind of order) {
         if (kind === "tool_results" && groups.toolResults.length > 0) {
             const message = groups.toolResults.pop();
-            return omission("tool_results", message.id ?? toolResultId(message), message);
+            return omission("tool_results", message.id ?? toolResultId(message), message, estimateTokens);
         }
         if (kind === "history" && historyCursor.index < groups.history.length) {
             const message = groups.history[historyCursor.index++];
-            return omission("history", message.id, message);
+            return omission("history", message.id, message, estimateTokens);
         }
         if (kind === "summaries" && groups.summaries.length > 0) {
             const message = groups.summaries.pop();
-            return omission("summaries", message.id, message);
+            return omission("summaries", message.id, message, estimateTokens);
         }
         if (kind === "attachments" && groups.attachments.length > 0) {
             const message = groups.attachments.pop();
-            return omission("attachments", message.id, message);
+            return omission("attachments", message.id, message, estimateTokens);
         }
         if (kind === "context" && context.length > 0) {
             const index = pickVictimIndex(context, (block) => block.priority ?? 0);
@@ -127,7 +131,7 @@ function dropNext(groups, context, skills, layout, skillContext, demotedBodies,
             return {
                 kind: "context",
                 id: block.id ?? block.title,
-                tokenEstimate: estimateTextTokens(text),
+                tokenEstimate: estimateTokens(text),
                 byteLength: estimateTextBytes(text),
             };
         }
@@ -142,7 +146,7 @@ function dropNext(groups, context, skills, layout, skillContext, demotedBodies,
                 return {
                     kind: "skill_body",
                     id: skill.name,
-                    tokenEstimate: estimateTextTokens(beforeText) - estimateTextTokens(afterText),
+                    tokenEstimate: estimateTokens(beforeText) - estimateTokens(afterText),
                     byteLength: estimateTextBytes(beforeText) - estimateTextBytes(afterText),
                 };
             }
@@ -152,31 +156,59 @@ function dropNext(groups, context, skills, layout, skillContext, demotedBodies,
             return {
                 kind: "skills",
                 id: skill.name,
-                tokenEstimate: estimateTextTokens(text),
+                tokenEstimate: estimateTokens(text),
                 byteLength: estimateTextBytes(text),
             };
         }
     }
     return undefined;
 }
-function omission(kind, id, message) {
+function omission(kind, id, message, estimateTokens) {
     return {
         kind,
         id,
-        tokenEstimate: estimateMessageTokens(message),
+        tokenEstimate: estimateMessageTokens(message, estimateTokens),
         byteLength: estimateMessageBytes(message),
     };
 }
+/**
+ * One O(n) cost measurement of the whole request (groups, context, skills, tool declarations).
+ * Shared with the attention-compiler gate, which measures once per turn and then subtracts a
+ * per-mutation delta instead of re-measuring — the same trick `applyContextBudget` uses.
+ */
+export function measureInputCost(options) {
+    return measureAll(options.groups, options.context ?? [], options.skills ?? [], options.tools, options.skillContext ?? {}, options.demotedBodies ?? EMPTY_DEMOTED_BODIES, options.estimateTokens ?? estimateTextTokens);
+}
+const EMPTY_DEMOTED_BODIES = new Set();
+/**
+ * Resolves the budget's estimator, validating each return value: a host estimator that
+ * yields NaN/negative/non-finite tokens would make every eviction decision unsound, so it
+ * fails the assembly closed instead of silently keeping or dropping the wrong content.
+ */
+function resolveTokenEstimator(budget) {
+    const estimator = budget.tokenEstimator;
+    if (estimator === undefined)
+        return estimateTextTokens;
+    if (typeof estimator !== "function")
+        throw new TypeError("contextBudget.tokenEstimator must be a function");
+    return (text) => {
+        const tokens = estimator(text);
+        if (typeof tokens !== "number" || !Number.isFinite(tokens) || tokens < 0) {
+            throw new TypeError("contextBudget.tokenEstimator must return a non-negative finite number of tokens");
+        }
+        return tokens;
+    };
+}
 function toolResultId(message) {
     const block = message.content.find((part) => part.type === "tool_result");
     return block && block.type === "tool_result" ? block.toolCallId : undefined;
 }
-function measureAll(groups, context, skills, tools, skillContext, demotedBodies) {
+function measureAll(groups, context, skills, tools, skillContext, demotedBodies, estimateTokens) {
     const renderContext = withDemoted(skillContext, demotedBodies);
     let tokens = 0;
     let bytes = 0;
     const addMessage = (message) => {
-        tokens += estimateMessageTokens(message);
+        tokens += estimateMessageTokens(message, estimateTokens);
         bytes += estimateMessageBytes(message);
     };
     for (const message of groups.instructions)
@@ -193,17 +225,17 @@ function measureAll(groups, context, skills, tools, skillContext, demotedBodies)
         addMessage(message);
     for (const block of context) {
         const text = `${block.title ? `${block.title}:\n` : "Context:\n"}${contextBlockText(block)}`;
-        tokens += estimateTextTokens(text);
+        tokens += estimateTokens(text);
         bytes += estimateTextBytes(text);
     }
     for (const skill of skills) {
         const text = skillPromptText(skill, renderContext) ?? "";
-        tokens += estimateTextTokens(text);
+        tokens += estimateTokens(text);
         bytes += estimateTextBytes(text);
     }
     if (tools?.length) {
         const text = `Available tools:\n${tools.map((tool) => `- ${tool.name}${tool.description ? `: ${tool.description}` : ""}`).join("\n")}`;
-        tokens += estimateTextTokens(text);
+        tokens += estimateTokens(text);
         bytes += estimateTextBytes(text);
     }
     return { tokens, bytes };

package/dist/contracts-core/agent.d.ts

@@ -33,6 +33,8 @@ export interface AgentDefinition {
     readonly metadata?: Readonly<Record<string, unknown>>;
     /** Optional escape hatch. When present, overrides declarative resolution. */
     create?(config?: AgentConfig): Promise<Agent> | Agent;
+    /** Opt-in attention compiler for the agent this definition resolves to (plan 074 C1). */
+    readonly attentionCompiler?: import("./attention.js").AttentionCompilerSetting;
 }
 /** Input to {@link resolveAgentDefinition}. All fields are optional; the host
  *  controls scope by which registries it passes. */
@@ -64,6 +66,9 @@ export interface AgentConfig {
     readonly toolsSearch?: import("../tool-search.js").ToolsSearchOptions;
     /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
     readonly toolResultFold?: import("../tool-result-fold.js").ToolResultFoldOptions;
+    /** Opt-in attention compiler (plan 074): `true` for defaults, an object to tune ratios/depth.
+     *  Omitted keeps today's request bytes; per-run options may only relax this setting. */
+    readonly attentionCompiler?: import("./attention.js").AttentionCompilerSetting;
     readonly inputBuilder?: InputBuilder;
     readonly promptBuilder?: PromptBuilder;
     readonly middleware?: MiddlewareRegistry;
@@ -116,6 +121,8 @@ export interface SecureAgentOptions extends Omit<AgentConfig, "tools" | "validat
     readonly limits: RunLimits;
     readonly definitionRevision: string;
     readonly runState: Omit<AgentRunStateOptions, "definitionRevision" | "interruptBeforeTool">;
+    /** Optional host composition readiness assertions evaluated on creation. */
+    readonly composition?: import("../host-composition.js").HostCompositionOptions;
 }
 export interface Agent {
     readonly config: AgentConfig;
@@ -127,7 +134,18 @@ export interface AgentSessionConfig {
     readonly store?: SessionStore;
     readonly leafId?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /**
+     * TTL of the in-memory `session.snapshot()` branch cache in milliseconds.
+     * Default `DEFAULT_SNAPSHOT_CACHE_TTL_MS`; `0` disables the cache (every snapshot read
+     * rebuilds from the store); at most `HARD_MAX_SNAPSHOT_CACHE_TTL_MS`. The cache is always
+     * invalidated by a new leaf or a mutation, so the TTL only bounds staleness-free reuse.
+     */
+    readonly snapshotCacheTtlMs?: number;
 }
+/** Default `session.snapshot()` branch-cache TTL (milliseconds). */
+export declare const DEFAULT_SNAPSHOT_CACHE_TTL_MS = 1000;
+/** Upper bound for `AgentSessionConfig.snapshotCacheTtlMs` (milliseconds). */
+export declare const HARD_MAX_SNAPSHOT_CACHE_TTL_MS = 30000;
 export interface AgentSessionForkOptions {
     readonly leafId?: string;
 }

package/dist/contracts-core/agent.js

@@ -1,6 +1,9 @@
 /** Contracts-core agent family (0.2.5 plan 025 Task 1 split).
  * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
-export {};
+/** Default `session.snapshot()` branch-cache TTL (milliseconds). */
+export const DEFAULT_SNAPSHOT_CACHE_TTL_MS = 1_000;
+/** Upper bound for `AgentSessionConfig.snapshotCacheTtlMs` (milliseconds). */
+export const HARD_MAX_SNAPSHOT_CACHE_TTL_MS = 30_000;
 /** Directory-name spelling for discovered contribution kinds. Maps to a
  *  {@link ManifestContributionDeclaration} kind for non-skill kinds:
  *  `context` → `contextProvider`, `instructions` → `systemPromptContribution`. */

package/dist/contracts-core/attention.d.ts

@@ -0,0 +1,66 @@
+/** Attention Compiler contracts (plan 074 Tasks 2–5). Opt-in per-turn gate that measures the
+ *  assembled input and mutates a history clone only after a host ratio of the model input
+ *  cap. `resolveRunAttentionCompiler` turns the agent setting plus an optional run overlay
+ *  into the frozen handle the session hands to assembly; nothing declared here runs on its
+ *  own, and omitting the option keeps today's request bytes. */
+import type { CompactionTrigger } from "./compaction.js";
+import type { ModelConfig } from "./content.js";
+/** Input-cap resolution inputs shared by the compiler and `input_ratio` compaction triggers. */
+export interface AttentionInputCapOptions {
+    /** Host cap; when set it wins over `model.limits.contextWindow` (C2). */
+    readonly maxInputTokens?: number;
+    /** Output + next-turn headroom subtracted from the window (default 1024). */
+    readonly reserveTokens?: number;
+}
+export interface AttentionCompilerOptions extends AttentionInputCapOptions {
+    /** Fraction of `inputCap` that triggers mutation; in `(0, 1)` (default 0.75). */
+    readonly triggerRatio?: number;
+    /** Where compaction should fire relative to `triggerRatio`; must exceed it (default 0.9). */
+    readonly compactRatio?: number;
+    /** Newest thinking-bearing assistant turns kept intact (default 1). */
+    readonly thinkingKeepTurns?: number;
+    /** Newest tool results kept full (default 3). */
+    readonly keepLast?: number;
+    /** Tool names whose results are never stubbed, whatever the ratio. */
+    readonly excludeTools?: readonly string[];
+}
+/** Where the compiler is switched on: `true` uses the defaults, an object tunes them, `false`
+ *  (or omitted) leaves requests byte-for-byte as they are without the compiler. On
+ *  `RunOptions` the same shape is an overlay: `false` disables, `true` is a no-op, and an
+ *  object may only *relax* the agent setting (see `resolveRunAttentionCompiler`). */
+export type AttentionCompilerSetting = boolean | AttentionCompilerOptions;
+export interface AttentionCompilerContext {
+    /** Model limits used to resolve the input cap; ignored when `maxInputTokens` is set. */
+    readonly model?: Pick<ModelConfig, "limits">;
+    /** Validated at create so an unknown trigger type fails at config time, not on turn one. */
+    readonly compactionTrigger?: CompactionTrigger;
+}
+/** Validated, frozen configuration returned by `createAttentionCompiler`. */
+export interface AttentionCompiler {
+    readonly inputCap: number;
+    readonly reserveTokens: number;
+    readonly triggerRatio: number;
+    readonly compactRatio: number;
+    readonly thinkingKeepTurns: number;
+    readonly keepLast: number;
+    readonly excludeTools: readonly string[];
+}
+/** One mutated turn. Under-ratio turns emit nothing and produce no report (C14). */
+export interface AttentionReport {
+    /** Estimated tokens measured before this turn's mutation — the value compared to the ratio. */
+    readonly used: number;
+    /** Estimated tokens of the same request after this turn's mutation: the cost curve is `used` → `usedAfter`. */
+    readonly usedAfter: number;
+    readonly inputCap: number;
+    readonly triggerRatio: number;
+    /** Thinking turns absent from this request; rows re-applied from the sticky frontier count again. */
+    readonly droppedThinkingTurns: number;
+    /** Tool results stubbed in this request; rows re-applied from the sticky frontier count again. */
+    readonly stubbedToolResults: number;
+    /** Payload bytes the stubs took out of this request (never the stub text itself). */
+    readonly stubbedBytes: number;
+    /** True when the gate stopped with eligible rows left: the sticky frontier is partial. */
+    readonly truncated: boolean;
+    readonly runId?: string;
+    readonly sessionId?: string;
+}

package/dist/contracts-core/attention.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=attention.js.map

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

@@ -21,15 +21,74 @@ export interface CompactionResult {
     readonly entries?: readonly SessionEntry[];
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
+/** Inputs a compaction trigger decides on. Estimates and ids only — never raw payloads. */
+export interface CompactionTriggerContext {
+    readonly sessionId: string;
+    readonly entryCount: number;
+    readonly estimatedInputTokens: number;
+    readonly inputCapTokens: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+}
+/** Host-programmable compact-when gate (plan 074 C11). Omitted → `thresholdEntries` only. */
+export type CompactionTrigger = {
+    readonly type: "threshold_entries";
+    readonly entries: number;
+} | {
+    readonly type: "input_ratio";
+    readonly ratio: number;
+} | {
+    readonly type: "custom";
+    readonly shouldCompact: (context: CompactionTriggerContext) => boolean | Promise<boolean>;
+};
+/** Validate a host trigger at config time, so an unknown `type` fails at create (C11). */
+export declare function assertCompactionTrigger(trigger: CompactionTrigger): CompactionTrigger;
 export interface CompactionOptions {
     readonly strategy?: CompactionStrategy;
     readonly thresholdEntries?: number;
+    /** Replaces the `thresholdEntries` gate when set; omitted keeps today's entry-count gate. */
+    readonly trigger?: CompactionTrigger;
     readonly keepRecentEntries?: number;
     readonly maxSummaryChars?: number;
     readonly secrets?: readonly (string | undefined)[];
     readonly metadata?: Readonly<Record<string, unknown>>;
     readonly signal?: AbortSignal;
 }
+/** Legacy gates a compaction decision can fall back to when no `trigger` is configured. */
+export interface ResolveShouldCompactOptions {
+    /** Host trigger; when set it replaces the legacy gates below. */
+    readonly trigger?: CompactionTrigger;
+    /** Session gate: compact when the branch holds more than this many entries. */
+    readonly thresholdEntries?: number;
+    /** Attach-loop gate: compact when the estimated input is at or above this many tokens. */
+    readonly compactAfterTokens?: number;
+}
+/** Everything a compaction decision reads. Estimates only — never raw payloads. */
+export interface ResolveShouldCompactInput {
+    readonly sessionId: string;
+    readonly entryCount: number;
+    /** Estimated tokens of the would-be input; called at most once, and only when a ratio or custom trigger reads it. */
+    readonly estimateInputTokens: () => number;
+    /** Resolved input cap (the attention compiler's `resolveInputCap`); called at most once, and only when a ratio or custom trigger reads it. */
+    readonly resolveInputCapTokens: () => number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+    /** Receives the failure behind a fail-closed `false`. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * The single compact-when decision used by `autoCompact` and by host attach loops that gate their
+ * own post-run compaction (plan 074 C11).
+ *
+ * Precedence: an explicit `trigger` replaces the legacy gates. Only the token gates below a `trigger`
+ * replace are lazy — a `threshold_entries` trigger, or a `custom` callback that only reads counts,
+ * never pays for the token estimate or the input cap.
+ *
+ * Failure policy: a malformed trigger throws (`assertCompactionTrigger`, config error), while a
+ * throwing `custom.shouldCompact` — including a callback that reads an unresolvable cap — decides
+ * `false` and reports through `onError`, so a host bug can never compact on a guess.
+ */
+export declare function resolveShouldCompact(options: ResolveShouldCompactOptions, input: ResolveShouldCompactInput): Promise<boolean>;
 export interface CompactionMiddlewarePayload {
     readonly context: CompactionContext;
     readonly result: CompactionResult;

package/dist/contracts-core/compaction.js

@@ -1,2 +1,78 @@
-export {};
+/** Validate a host trigger at config time, so an unknown `type` fails at create (C11). */
+export function assertCompactionTrigger(trigger) {
+    if (typeof trigger !== "object" || trigger === null) {
+        throw new TypeError("compaction trigger must be an object");
+    }
+    switch (trigger.type) {
+        case "threshold_entries":
+            if (!Number.isSafeInteger(trigger.entries) || trigger.entries < 1) {
+                throw new TypeError("compaction trigger threshold_entries.entries must be a positive safe integer");
+            }
+            return trigger;
+        case "input_ratio":
+            if (!Number.isFinite(trigger.ratio) || trigger.ratio <= 0 || trigger.ratio >= 1) {
+                throw new TypeError("compaction trigger input_ratio.ratio must be a number in (0, 1)");
+            }
+            return trigger;
+        case "custom":
+            if (typeof trigger.shouldCompact !== "function") {
+                throw new TypeError("compaction trigger custom.shouldCompact must be a function");
+            }
+            return trigger;
+        default:
+            throw new TypeError(`unknown compaction trigger type: ${String(trigger.type)}`);
+    }
+}
+/**
+ * The single compact-when decision used by `autoCompact` and by host attach loops that gate their
+ * own post-run compaction (plan 074 C11).
+ *
+ * Precedence: an explicit `trigger` replaces the legacy gates. Only the token gates below a `trigger`
+ * replace are lazy — a `threshold_entries` trigger, or a `custom` callback that only reads counts,
+ * never pays for the token estimate or the input cap.
+ *
+ * Failure policy: a malformed trigger throws (`assertCompactionTrigger`, config error), while a
+ * throwing `custom.shouldCompact` — including a callback that reads an unresolvable cap — decides
+ * `false` and reports through `onError`, so a host bug can never compact on a guess.
+ */
+export async function resolveShouldCompact(options, input) {
+    let estimated;
+    let cap;
+    const estimateOnce = () => (estimated ??= input.estimateInputTokens());
+    const capOnce = () => (cap ??= input.resolveInputCapTokens());
+    const trigger = options.trigger;
+    if (trigger === undefined) {
+        if (options.thresholdEntries !== undefined)
+            return input.entryCount > options.thresholdEntries;
+        if (options.compactAfterTokens !== undefined)
+            return estimateOnce() >= options.compactAfterTokens;
+        return false;
+    }
+    assertCompactionTrigger(trigger);
+    if (trigger.type === "threshold_entries")
+        return input.entryCount > trigger.entries;
+    if (trigger.type === "input_ratio")
+        return estimateOnce() >= trigger.ratio * capOnce();
+    // Getter-backed so a callback that only reads counts never forces cap resolution, which throws
+    // when the active model declares no context window.
+    const context = {
+        sessionId: input.sessionId,
+        entryCount: input.entryCount,
+        get estimatedInputTokens() {
+            return estimateOnce();
+        },
+        get inputCapTokens() {
+            return capOnce();
+        },
+        ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    };
+    try {
+        return (await trigger.shouldCompact(context)) === true;
+    }
+    catch (error) {
+        input.onError?.(error);
+        return false;
+    }
+}
 //# sourceMappingURL=compaction.js.map