@arnilo/prism 0.8.0 → 0.9.0

package/dist/testing/session-store-conformance.js

@@ -113,6 +113,54 @@ async function assertSessionStoreSearchSessions(store) {
     await reject(() => search({ limit: Number.NaN }), (error) => error instanceof TypeError, "searchSessions must reject NaN limit");
     await reject(() => search({ limit: HARD_MAX_SESSION_SEARCH_LIMIT + 1 }), (error) => error instanceof TypeError, "searchSessions must reject oversize limit");
     await reject(() => search({ query: "x".repeat(HARD_MAX_SESSION_SEARCH_QUERY_BYTES + 1) }), (error) => error instanceof TypeError, "searchSessions must reject oversize query string");
+    await reject(() => search({ kind: "not-an-entry-kind" }), (error) => error instanceof TypeError, "searchSessions must reject an unknown kind");
+    // Query round-trip: a written message must be findable and the hit must point at it.
+    const searchSessionId = "conformance-search";
+    const token = "zzconformancesearchtoken";
+    const matchedEntry = {
+        id: "conformance-search-entry",
+        sessionId: searchSessionId,
+        timestamp: "2026-01-01T00:00:05.000Z",
+        kind: "message",
+        runId: "conformance-run",
+        message: { role: "user", content: [{ type: "text", text: `${token} body text` }] },
+    };
+    await store.append(matchedEntry);
+    const found = await search({ query: token, limit: 5 });
+    const hit = found.items.find((item) => item.sessionId === searchSessionId);
+    if (!hit) {
+        throw new Error("searchSessions must find a session by matching message text");
+    }
+    if (hit.entryId !== matchedEntry.id) {
+        throw new Error(`searchSessions must point at the matched entry; got ${String(hit.entryId)}`);
+    }
+    if (hit.runId !== matchedEntry.runId) {
+        throw new Error("searchSessions must carry the matched entry runId");
+    }
+    if (typeof hit.snippet !== "string" || !hit.snippet.includes(token)) {
+        throw new Error("searchSessions snippet must contain the matched text");
+    }
+    if (!Number.isSafeInteger(hit.turn) || hit.turn < 1) {
+        throw new Error("searchSessions must carry a 1-based matched-entry turn index");
+    }
+    const annotationOnly = await search({ query: token, kind: "summary", limit: 5 });
+    if (annotationOnly.items.some((item) => item.sessionId === searchSessionId)) {
+        throw new Error("searchSessions kind filter must exclude non-matching entry kinds");
+    }
+    // One hit per session: a second matching entry must not add a second row for the same session.
+    await store.append({
+        id: "conformance-search-entry-2",
+        parentId: matchedEntry.id,
+        sessionId: searchSessionId,
+        timestamp: "2026-01-01T00:00:06.000Z",
+        kind: "summary",
+        summary: `${token} recap`,
+    });
+    const deduped = await search({ query: token, limit: 5 });
+    const sessionHits = deduped.items.filter((item) => item.sessionId === searchSessionId);
+    if (sessionHits.length !== 1) {
+        throw new Error(`searchSessions must return one hit per session; got ${sessionHits.length}`);
+    }
     const empty = await search(resolveSessionSearchQuery({
         workspaceRoot: "__prism_conformance_empty__",
         limit: 5,

package/dist/tools.d.ts

@@ -58,6 +58,11 @@ export declare function createToolRegistry(tools?: readonly ToolDefinition[], op
 export declare function filterTools(tools: readonly ToolDefinition[], filter?: ToolFilterInput): readonly ToolDefinition[];
 /** Cap matches tool-search index; run allow-lists never exceed the disclosed set. */
 export declare const HARD_RUN_TOOL_NAMES = 1024;
+/** Restrictive clamp: keep listed order; names outside the grant are dropped (not thrown). */
+export declare function clampTurnToolNames(listed: readonly ToolDefinition[], requested: readonly string[]): {
+    readonly tools: readonly ToolDefinition[];
+    readonly dropped: readonly string[];
+};
 /**
  * Per-run allow-list. Omitted grant → unchanged list. Checkpointed grant cannot widen.
  * Fresh unknown names fail closed; resume drops names the current registry no longer has.

package/dist/tools.js

@@ -61,15 +61,15 @@ export function filterTools(tools, filter) {
 /** Cap matches tool-search index; run allow-lists never exceed the disclosed set. */
 export const HARD_RUN_TOOL_NAMES = 1024;
 const MAX_RUN_TOOL_NAME_CHARS = 256;
-function assertRunToolNames(names) {
+function assertRunToolNames(names, label = "RunOptions.toolNames") {
     if (names.length > HARD_RUN_TOOL_NAMES) {
-        throw new TypeError(`RunOptions.toolNames exceeds ${HARD_RUN_TOOL_NAMES} entries`);
+        throw new TypeError(`${label} exceeds ${HARD_RUN_TOOL_NAMES} entries`);
     }
     const out = [];
     const seen = new Set();
     for (const name of names) {
         if (typeof name !== "string" || name.length === 0 || name.length > MAX_RUN_TOOL_NAME_CHARS) {
-            throw new TypeError(`RunOptions.toolNames entries must be non-empty strings of at most ${MAX_RUN_TOOL_NAME_CHARS} characters`);
+            throw new TypeError(`${label} entries must be non-empty strings of at most ${MAX_RUN_TOOL_NAME_CHARS} characters`);
         }
         if (!seen.has(name)) {
             seen.add(name);
@@ -78,6 +78,14 @@ function assertRunToolNames(names) {
     }
     return out;
 }
+/** Restrictive clamp: keep listed order; names outside the grant are dropped (not thrown). */
+export function clampTurnToolNames(listed, requested) {
+    const names = assertRunToolNames(requested, "toolNarrowing");
+    const grant = new Set(listed.map((tool) => tool.name));
+    const dropped = names.filter((name) => !grant.has(name));
+    const allow = names.filter((name) => grant.has(name));
+    return { tools: allow.length === 0 ? [] : filterTools(listed, { allow }), dropped };
+}
 /**
  * Per-run allow-list. Omitted grant → unchanged list. Checkpointed grant cannot widen.
  * Fresh unknown names fail closed; resume drops names the current registry no longer has.

package/dist/usage-estimation.d.ts

@@ -0,0 +1,29 @@
+/** Model-family chars/token tables and the family text estimator (plan 091 Task 1).
+ *
+ * Pure and O(text length): no network, no I/O, no content retention. These are
+ * heuristics, not tokenizers — harnesses universally approximate. Reported usage
+ * always wins; estimates exist so missing usage is never shown as zero.
+ *
+ * Ratio provenance: `openai` is calibrated against `o200k_base` counts on the
+ * in-repo fixtures (`src/__tests__/usage-estimation.test.ts`); the other families
+ * use their published tokenizer guidance ranges and are intentionally rounded
+ * toward over-counting, because an overestimated context meter is safe while an
+ * underestimated one under-compacts. `unknown` is the most conservative table so
+ * an unidentified model can never look smaller than a known one.
+ */
+import type { ModelFamily, TokenEstimateConfidence } from "./contracts-core/usage.js";
+/** Row of {@link MODEL_FAMILY_TOKENS}: prose chars per token, chat-template
+ *  tokens added once per message, and the confidence label for the table. */
+export interface ModelFamilyTokens {
+    readonly charsPerToken: number;
+    readonly perMessageOverhead: number;
+    readonly confidence: TokenEstimateConfidence;
+}
+/** Per-family chars/token tables (plan 091 Task 1). Estimates only, never billing. */
+export declare const MODEL_FAMILY_TOKENS: Readonly<Record<ModelFamily, ModelFamilyTokens>>;
+/** Resolve a model id (e.g. `"claude-sonnet-4.5"`), provider id, or family name
+ *  to a table key. Unmatched input is `"unknown"` — never a throw. */
+export declare function resolveModelFamily(model?: string): ModelFamily;
+/** Estimate tokens for one flattened text under a family's ratios. The message
+ *  level (`estimateMessageTokens`) owns per-message overhead; this is text-only. */
+export declare function estimateTextTokensForFamily(text: string, modelFamily?: string): number;

package/dist/usage-estimation.js

@@ -0,0 +1,79 @@
+/** CJK ideographs/kana/hangul tokenize near 1.5 chars/token in modern family tokenizers. */
+const CJK_CHARS_PER_TOKEN = 1.5;
+/** Fenced code tokenizes worse than prose: code ratio = prose ratio * this factor. */
+const CODE_RATIO_FACTOR = 0.88;
+/** Per-family chars/token tables (plan 091 Task 1). Estimates only, never billing. */
+export const MODEL_FAMILY_TOKENS = {
+    anthropic: { charsPerToken: 3.7, perMessageOverhead: 4, confidence: "medium" },
+    openai: { charsPerToken: 5.0, perMessageOverhead: 3, confidence: "medium" },
+    google: { charsPerToken: 3.9, perMessageOverhead: 4, confidence: "medium" },
+    deepseek: { charsPerToken: 3.8, perMessageOverhead: 4, confidence: "medium" },
+    "openrouter-generic": { charsPerToken: 4.4, perMessageOverhead: 4, confidence: "medium" },
+    mistral: { charsPerToken: 3.9, perMessageOverhead: 3, confidence: "medium" },
+    unknown: { charsPerToken: 3.5, perMessageOverhead: 6, confidence: "low" },
+};
+/** Model-id patterns per family. Family names themselves also resolve (see `resolveModelFamily`). */
+const FAMILY_PATTERNS = [
+    ["anthropic", /claude|anthropic/i],
+    ["openai", /gpt-|openai|chatgpt|codex|^o[1-9]/i],
+    ["google", /gemini|gemma|palm|google/i],
+    ["deepseek", /deepseek/i],
+    ["mistral", /mistral|mixtral|codestral|magistral|devstral|pixtral|ministral/i],
+    ["openrouter-generic", /openrouter/i],
+];
+/** Resolve a model id (e.g. `"claude-sonnet-4.5"`), provider id, or family name
+ *  to a table key. Unmatched input is `"unknown"` — never a throw. */
+export function resolveModelFamily(model) {
+    if (typeof model !== "string")
+        return "unknown";
+    const id = model.trim();
+    if (id in MODEL_FAMILY_TOKENS)
+        return id;
+    for (const [family, pattern] of FAMILY_PATTERNS) {
+        if (pattern.test(id))
+            return family;
+    }
+    return "unknown";
+}
+/** Estimate tokens for one flattened text under a family's ratios. The message
+ *  level (`estimateMessageTokens`) owns per-message overhead; this is text-only. */
+export function estimateTextTokensForFamily(text, modelFamily) {
+    const { charsPerToken } = MODEL_FAMILY_TOKENS[resolveModelFamily(modelFamily)];
+    let cjk = 0;
+    for (let index = 0; index < text.length;) {
+        const codePoint = text.codePointAt(index) ?? 0; // unreachable 0: index < length; avoids a non-null assertion
+        if (isCjkCodePoint(codePoint))
+            cjk += 1;
+        index += codePoint > 0xffff ? 2 : 1;
+    }
+    const code = fencedChars(text);
+    const other = Math.max(0, text.length - cjk - code);
+    return Math.ceil(cjk / CJK_CHARS_PER_TOKEN + code / (charsPerToken * CODE_RATIO_FACTOR) + other / charsPerToken);
+}
+/** Length of the characters enclosed by ``` fence pairs (unclosed fence runs to the end). */
+function fencedChars(text) {
+    let total = 0;
+    let index = text.indexOf("```");
+    while (index !== -1) {
+        const end = text.indexOf("```", index + 3);
+        if (end === -1) {
+            total += text.length - index;
+            break;
+        }
+        total += end + 3 - index;
+        index = text.indexOf("```", end + 3);
+    }
+    return total;
+}
+/** Han, kana, hangul, CJK punctuation/fullwidth, and ext-B+ ideograph ranges. */
+function isCjkCodePoint(codePoint) {
+    return ((codePoint >= 0x3000 && codePoint <= 0x303f) ||
+        (codePoint >= 0x3040 && codePoint <= 0x30ff) ||
+        (codePoint >= 0x3400 && codePoint <= 0x4dbf) ||
+        (codePoint >= 0x4e00 && codePoint <= 0x9fff) ||
+        (codePoint >= 0xac00 && codePoint <= 0xd7af) ||
+        (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+        (codePoint >= 0xff00 && codePoint <= 0xffef) ||
+        (codePoint >= 0x20000 && codePoint <= 0x2fa1f));
+}
+//# sourceMappingURL=usage-estimation.js.map

package/docs/agent-events.md

@@ -24,6 +24,8 @@ Event records preserve emission order within a run because the runtime drains pe
 
 `AgentEventSource` (`createMemoryAgentEventSource` / `persistence.events` on PostgreSQL) appends, pages, and subscribes with opaque ownership-bound cursors. `subscribe` registers wake interest before replaying history so replay-to-live handoff has no gap. Delivery is at-least-once; consumers dedupe `record.id`. PostgreSQL uses transactional sequence allocation plus `LISTEN`/`NOTIFY` wakeups with polling fallback. Transport adapters (server SSE `Last-Event-ID`, AG-UI, A2A `afterEventId`) map source envelopes only — they do not invent private replay loops. This is not exactly-once.
 
+Exactly three event types are terminal — `agent_finished`, `agent_denied`, and `error` — and one exported predicate answers the question for every consumer: `isTerminalAgentEventType(type)`. The memory, NATS, and Postgres sources, AG-UI replay, the A2A stream break, AG-UI `filterRun`, and conversation replay all route through it, so pages, subscriptions, and replays end on the same set. Attribution records such as `run_limit_exceeded` and `budget_exhausted` are not terminal (see [run limit events](#run-limit-events)).
+
 ### Placement (FR-7 answer, 0.0.26)
 
 The durable `AgentEventSource` **stays in `@arnilo/prism-core/sessions/postgres`** for the 0.0.26 line and is importable from the package root (FR-6):
@@ -72,12 +74,15 @@ The `AgentEvent` union (grouped by concern):
 | --- | --- |
 | Agent lifecycle | `agent_started`, `agent_suspended`, `agent_resumed`, `agent_denied`, `agent_finished` |
 | Turns | `turn_started`, `turn_finished` |
+| Deterministic turns | `deterministic_turn` |
 | Provider turns | `provider_turn_started`, `provider_turn_finished` |
 | Assistant messages | `message_started`, `message_delta`, `message_finished` |
 | Delegated agents | `delegated_agent_step` |
 | Tool execution | `tool_execution_started`, `tool_execution_progress`, `tool_execution_finished`, `tool_execution_error`, `tool_execution_blocked` |
+| Tool narrowing | `tool_narrowing_clamped` |
 | Guardrails | `guardrail_decision` |
 | Queue/subscribers | `queue_updated`, `event_subscriber_overflow`, `steer_rejected` |
+| Run limits | `run_limit_exceeded`, `budget_exhausted` |
 | Compaction | `compaction_started`, `compaction_finished` |
 | Retry | `retry_scheduled` |
 | Artifacts | `artifact_validation_started`, `artifact_validation_finished`, `artifact_revision_started`, `artifact_finished`, `artifact_failed` |
@@ -107,6 +112,8 @@ Adapters should call `createDelegatedAgentStep({ sessionId, runId, adapterId, ex
 
 Coding hosts call `observeSupervisorLifecycle(supervisor, { onEvent, delegatedAgentStep })` to turn supervisor milestones into `subagent_started` / `subagent_stopped` coding lifecycle events. Both carry only redacted `childId`, `delegationId`, and `depth`; stopped events add terminal `AgentRunStatus`. Supplying `delegatedAgentStep` emits the bounded `delegated_agent_step` records AG-UI already maps. Child inputs, outputs, paths, and delegation error text never cross either bridge.
 
+Supervisor child reporting is opt-in per child (`SupervisorChild.policy.report` ceiling; a request can only lower it). With `report: "milestones"` the supervisor publishes `child_milestone` (`childId`, `delegationId`, `depth`, `turn`, redacted `childEvent`) at the configured `milestone.everyTurns` cadence or host predicate; with `report: "stream"` it publishes `delegation_child_event` for every per-turn provider/tool/turn child event (never per-token `message_delta`). Both are redacted, count/byte-capped, and rate-coalesced (`delegation_child_events_coalesced` reports dropped events); the cap marker is `delegation_child_events_capped`. `child_failed` carries failure attribution for any child that died on an error or a limit: the redacted `reason`, the terminal `status`/`stopReason`, and the plan-086/087 `RunLimitBreach` in `limit` when a configured ceiling fired. Host cancels, policy denials, and hook rejections are not failures and never emit it. Hosts that want recovery counters rather than events read `supervisor.summary()` (`attempts`, `retries`, `failures`, `failureRadius`, `outcome` per child). Child events stay on the supervisor stream unless the host passes `childEventSink`, which receives the identical payload tagged with `child: { childId, delegationId, depth }` (`ChildEventOrigin`) for routing onto a parent session stream; they are not native `AgentEvent`s of the parent session, and hosts that surface them there re-attach the parent `sessionId`/`runId` themselves if needed.
+
 `message_delta.content.type === "tool_call_delta"` carries `{ index, id?, name?, argumentsText? }`. Treat it as a streaming fragment. The runtime reconstructs and persists a final `tool_call` before executing tools. Deltas missing `id`/`name` at stream end fail the provider turn with `ErrorInfo.code: "incomplete_delta"` (typed `ProviderTransportError`); they never throw a bare `Error`. Malformed JSON with id+name present recovers as a blocked tool result (`invalid_json_arguments`) instead.
 
 Tool execution events:
@@ -118,6 +125,7 @@ Tool execution events:
 | `tool_execution_finished` | `sessionId`, `runId`, `result: ToolResult`, `metadata: ToolExecutionMetadata` |
 | `tool_execution_error` | `sessionId`, `runId`, `call: ToolCallContent`, `error: ErrorInfo`, `metadata: ToolExecutionMetadata` |
 | `tool_execution_blocked` | `sessionId`, `runId`, `toolCallId`, `name`, `reason: string`, `error: ErrorInfo`, `metadata: ToolExecutionMetadata` |
+| `tool_narrowing_clamped` | `sessionId`, `runId`, `turn`, `dropped: readonly string[]` (names the host returned outside the run grant; no tool args) |
 
 Guardrail events:
 
@@ -139,12 +147,71 @@ Queue / subscriber / compaction / retry / provider events:
 | `attention_compiled` | `sessionId`, `runId?`, `used: number`, `usedAfter: number`, `inputCap: number`, `triggerRatio: number`, `droppedThinkingTurns: number`, `stubbedToolResults: number`, `stubbedBytes: number`, `truncated: boolean` — one per mutated turn of the opt-in [attention compiler](attention-compiler.md); counts only, never message text |
 | `retry_scheduled` | `sessionId`, `runId`, `attempt: number`, `delayMs: number`, `error: ErrorInfo` |
 
+### Run limit events
+
+Terminal attribution — see [Runs and usage § Run limits](runs-and-usage.md#run-limits).
+
+| Variant | Fields |
+| --- | --- |
+| `run_limit_exceeded` | `sessionId`, `runId`, `breach: RunLimitBreach` (`limit`, `maximum`, `observed`, optional `currency`) — emitted once, when an axis first exceeds its cap |
+| `budget_exhausted` | `sessionId`, `runId`, `limit: RunLimitName`, `consumed: { turns, inputTokens, providerAttempts, requestBytes }`, `closestOtherAxes: [{ axis, usedRatio }]`, `recentToolCalls: [{ id, name, argHash }]` |
+
+`budget_exhausted` is the terminal attribution for a run that died on a limit: it is emitted once per
+limit death, before the terminal `error` event and the finish `RunRecord`. A limit death therefore
+delivers three records in order — `run_limit_exceeded` (breach), `budget_exhausted` (attribution),
+then the terminal `error` — and a page, subscription, or replay stays open across the first two:
+keep reading until the stream ends rather than stopping at the first breach record. `limit` names the axis that fired
+(`maxTurns`, `maxInputTokens`, `maxCost`, …). `closestOtherAxes` is the three other finite product
+axes with the highest `used / cap` ratio, so a host can answer "how close was everything else";
+request/response byte axes stay out because their caps are per-frame, and `usedRatio` is clamped to
+`[0, 1]`. `recentToolCalls` holds the last ten host tool calls dispatched in this run (in dispatch
+order, reset at run start and after a durable resume) as id, name, and `argHash` —
+`sha256:<64 hex>` over the canonicalized arguments, never the arguments themselves. `consumed`
+counters are the run-lifetime tracker snapshot at exhaustion. Events stay counts and hashes only, so
+no new redaction class is introduced. Both events project onto the [execution timeline](execution-timeline.md)
+as `timeline.exhaustion` plus the `turns[i].stopReason` badges, with a one-line summary on
+`summarizeTimeline().exhaustion`.
+
 Provider turn events (metadata only — see [Observability](observability.md)):
 
 | Variant | Fields |
 | --- | --- |
+| `deterministic_turn` | `sessionId`, `runId`, `turn`, `middleware` — host middleware answered this turn without a provider request ([Middleware hooks](middleware-hooks.md#no-model-turns-beforeproviderturn)). Carries no `usage` key: provider accounting stays absent, never zero-filled. The same provenance reaches the persisted transcript as `message.metadata.deterministic = { middleware }` on the assistant `message_finished` message. |
 | `provider_turn_started` | `sessionId`, `runId`, `turn`, `metadata: ProviderTurnMetadata` |
-| `provider_turn_finished` | `sessionId`, `runId`, `turn`, `metadata` (includes `latencyMs` on finish), `usage?`, `error?` |
+| `provider_turn_finished` | `sessionId`, `runId`, `turn`, `metadata` (includes `latencyMs`, `stopReason`, `budgets`, `tools`, and provider-reported `cache` metrics on finish), `usage?`, `error?` |
+
+`provider_turn_finished.metadata.stopReason` names why that provider turn stopped, from one closed
+taxonomy. Adapters map native wire values (`finish_reason`, `stop_reason`, `finishReason`, Converse
+`stopReason`) through the shared `mapProviderStopReason` table, so a new provider value degrades to
+`unknown` instead of failing a run; the normalized `done` provider event carries the same mapped
+value when the adapter saw a native reason.
+
+| `stopReason` | Meaning |
+| --- | --- |
+| `end_turn` | Model finished its answer (native `stop`, `end_turn`, `stop_sequence`, `STOP`, `completed`) |
+| `tool_calls` | Turn requested host tools; also what a generic `end_turn` becomes when the turn produced tool calls |
+| `max_output_tokens` | Output truncated at the provider's token cap (native `length`, `max_tokens`, `MAX_TOKENS`) |
+| `content_filter` | Provider safety/refusal path (native `content_filter`, `refusal`, `SAFETY`, `guardrail_intervened`) |
+| `abort` | The run or turn was aborted (host abort, steer soft interrupt) |
+| `provider_error` | The turn failed with a provider error |
+| `unknown` | Unmapped or absent native reason |
+
+`provider_turn_finished.metadata.budgets` is an O(1) snapshot from the run limit tracker:
+`{ inputTokens?, inputCap?, runInputBudget?, runInputUsed, turns, maxTurns }` — current-turn
+provider-reported input tokens against the resolved per-request input cap, cumulative run input
+against `limits.maxInputTokens`, and provider turns against `limits.maxTurns` (`null` when
+disabled). Optional fields are absent when the provider reported no usage or no input cap can be
+derived; hosts that ignore the fields are unaffected.
+
+`provider_turn_started` / `provider_turn_finished` metadata includes `tools: { count, idsHash }` for the
+effective menu sent on that request (after run scoping, per-turn `toolNarrowing`, and disclosure).
+`idsHash` is `sha256:` plus 64 lowercase hex over `JSON.stringify(names)` in request order. Count and
+hash only — never tool args, schemas, or descriptions. Identical consecutive subsets keep the same hash.
+
+`provider_turn_finished.metadata.cache` is present only when the provider reported
+`cacheReadTokens` or `cacheWriteTokens`: `{ cacheReadTokens?, cacheWriteTokens?, hitRate? }`.
+`hitRate` is cache reads divided by reported input tokens. Unknown cache usage is absent, never
+zero-filled; it contains counts only, never cache keys or prompt content.
 
 Artifact validation/refinement events (emitted only by `generateValidateReviseLoop`; `singleShotLoop` emits zero artifact events):
 

package/docs/agent-session-runtime.md

@@ -12,6 +12,7 @@ The agent/session runtime adds the minimal shared SDK surface for running provid
 - `session.prompt(input, options)` → `AgentRunResult`
 - `session.stream(input, options)` → owned-run `AsyncIterable<AgentEvent>`
 - `session.compact(options?)`
+- `session.contextMeter()` → `ContextMeter` (latest provider-turn input tokens, reported or labeled estimate, with cap/budget/ratio)
 - `session.subscribe(options?)`
 - `session.abort()`
 - `session.entries()`

package/docs/attention-compiler.md

@@ -48,16 +48,17 @@ await session.run("cheap run", { attentionCompiler: { triggerRatio: 0.95, compac
 The agent setting is resolved with the run's model at run start, before any provider turn, so a malformed setting or a widening overlay fails the run immediately instead of on the turn that crosses the ratio:
 
 - **Allowed in the overlay:** `triggerRatio` / `compactRatio` at or above the agent setting, `keepLast` / `thinkingKeepTurns` at or below it, and extra `excludeTools` (unioned with the agent list, never removed).
-- **Rejected:** a lower gate ratio, more protected rows, and `maxInputTokens` / `reserveTokens` — cap inputs are agent-config only, because moving the cap moves the gate itself. Raising `triggerRatio` at or above the agent's `compactRatio` needs `compactRatio` raised in the same overlay.
+- **Rejected:** a lower gate ratio, more protected rows, and `maxInputTokens` / `reserveTokens` / `trigger` — cap inputs and fold axes are agent-config only, because moving either moves the gate itself. Raising `triggerRatio` at or above the agent's `compactRatio` needs `compactRatio` raised in the same overlay.
 - **Enabling from a run is rejected:** a run may disable or relax the compiler, never switch it on where the agent config left it off.
 
-The **sticky frontier is session-owned and created lazily** the first time an enabled run assembles a request: one `{ thinking, toolCallIds }` set pair per session, shared across runs, provider rounds, and branches, so a stub or strip made once stays applied even on a later under-ratio turn. It lives in memory only — a resumed process simply re-decides from the ratio it sees.
+The **sticky frontier is session-owned and created lazily** the first time an enabled run assembles a request: one `{ thinking, toolCallIds }` set pair per session, shared across runs, provider rounds, and branches, so a stub or strip made once stays applied even on a later under-ratio turn. A durable run with `persistSessionState: true` writes its bounded snapshot into the checkpoint and restores it on resume, so a resumed process keeps its stubs instead of re-deciding its first turn from the ratio.
 
 `AttentionCompilerOptions` (all optional):
 
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `triggerRatio` | `number` | `0.75` | Fraction of `inputCap` that enables mutation; must be in `(0, 1)` (exclusive). |
+| `triggerRatio` | `number` | `0.75` | Fraction of `inputCap` that enables mutation; must be in `(0, 1)` (exclusive). The reference ratio the report carries and `compactRatio` is checked against. |
+| `trigger` | `AttentionTriggerInput` | — | Fold axes (plan 086 T2). **Replaces** the `triggerRatio` axis when set; omitted keeps it alone, so behavior is unchanged. See [Trigger axes](#trigger-axes). |
 | `compactRatio` | `number` | `0.9` | Where compaction should fire relative to the compiler; must exceed `triggerRatio`. |
 | `thinkingKeepTurns` | `number` | `1` | Newest thinking-bearing assistant turns kept intact. |
 | `keepLast` | `number` | `3` | Newest tool results kept full. |
@@ -71,8 +72,9 @@ The **sticky frontier is session-owned and created lazily** the first time an en
 | --- | --- | --- |
 | `model` | `{ limits?: ModelLimits }` | Source of `contextWindow` / `maxOutputTokens` when `maxInputTokens` is absent. |
 | `compactionTrigger` | `CompactionTrigger` | Optional: validated here so an unknown trigger `type` fails at create time, not on the first turn. An `input_ratio` trigger must exceed `triggerRatio`. |
+| `runInputBudget` | `number \| null` | Cumulative run input budget the `run_input_ratio` axis folds against — pass the resolved `RunLimits.maxInputTokens`. `null` or omitted means the run declares no budget, so that axis falls back to the input cap. Distinct from `maxInputTokens`, which caps a single request. |
 
-**Public surface.** `createAttentionCompiler(options?: AttentionCompilerOptions, context?)` is the factory; `AttentionCompilerOptions` carries the gate ratios, sticky-stage tuning (`thinkingKeepTurns`, `keepLast`), `excludeTools`, and `reserveTokens`. `resolveInputCap(options?: AttentionInputCapOptions, model?)` is the cap resolver, `compileAttention(options: AttentionCompileOptions)` is the per-turn call `assembleProviderInput` makes (`AttentionCompileOptions` also carries `fold`, `frontier`, `redactor`, `signal`, and the `turn`/`sessionId`/`runId` telemetry ids), and `createAttentionTruncationTrigger(options?: AttentionTruncationTriggerOptions)` builds the host-programmable compaction trigger.
+**Public surface.** `createAttentionCompiler(options?: AttentionCompilerOptions, context?)` is the factory; `AttentionCompilerOptions` carries the gate ratios, the optional `trigger` axes, sticky-stage tuning (`thinkingKeepTurns`, `keepLast`), `excludeTools`, and `reserveTokens`. `resolveInputCap(options?: AttentionInputCapOptions, model?)` is the cap resolver, `compileAttention(options: AttentionCompileOptions)` is the per-turn call `assembleProviderInput` makes (`AttentionCompileOptions` also carries `fold`, `frontier`, `redactor`, `signal`, `runInputTokens`, and the `turn`/`sessionId`/`runId` telemetry ids), and `createAttentionTruncationTrigger(options?: AttentionTruncationTriggerOptions)` builds the host-programmable compaction trigger. The frozen handle carries the normalized `trigger` axes, the resolved `runInputBudget`, and `durable`, so a caller can never resolve one and evaluate against another.
 
 Input cap resolution: `maxInputTokens` when set, otherwise `contextWindow - (maxOutputTokens ?? 0) - reserveTokens`. Both `resolveInputCap(options?, model?)` and the compiler fail closed with a `TypeError` when neither source is present, when a declared limit is malformed, or when the computed cap is not positive.
 
@@ -82,10 +84,56 @@ Turn options, passed to `assembleProviderInput`:
 | --- | --- | --- |
 | `attentionCompiler` | `AttentionCompilerOptions \| AttentionCompiler` | Raw options are validated for that call; a resolved handle reuses one validation. The session passes the run's resolved handle so a tuning typo fails before the first provider turn. |
 | `attentionSticky` | `AttentionStickyFrontier` | `{ thinking, toolCallIds }` sets from `createAttentionStickyFrontier()`. The session supplies its own; a direct `assembleProviderInput` caller owns it, and omitting it makes each call mutate for its turn only. |
+| `runInputTokens` | `number` | Run input tokens already charged by provider usage this run (default 0), so the cumulative `run_input_ratio` axis can project this turn onto the spend. The session passes the run limit counter. |
 | `onAttentionReport` | `(report: AttentionReport) => void` | Called once per **mutated** turn, before `input_assembly` middleware; silent under the ratio. The session uses it to emit `attention_compiled`. |
 
 `attentionCompiler` and `contextBudget` are **mutually exclusive** — a compiler-on turn that is still over throws `AttentionBudgetError` rather than evicting through the budget, so passing both fails closed with a `TypeError`.
 
+### Trigger axes
+
+`trigger` replaces `triggerRatio` as the gate (plan 086 T2). It takes one axis, one predicate function, or an array of them; an array is **any-of**, and the first axis that fires is the one attributed on the report.
+
+| Kind | Fires when | Folds to | Fails closed? |
+| --- | --- | --- | --- |
+| `{ kind: "input_ratio", ratio }` | the assembled request reaches `ratio × inputCap` — the legacy `triggerRatio` axis | `ratio × inputCap` | yes |
+| `{ kind: "run_input_ratio", ratio }` | `runInputTokens + estimatedInputTokens` reaches `ratio × runInputBudget`, so a run capped below the model window folds before the cap kills it | every eligible row (a cumulative gate has no per-request target) | **no** — the spend is already booked; folding only slows the counter, and the run limit owns the cap |
+| `{ kind: "token_floor", tokens }` | the assembled request reaches `tokens` tokens, whatever the cap | `tokens` | yes |
+| `{ kind: "predicate", shouldFold }` (or a bare function) | `shouldFold(state)` returns `true` | every eligible row | yes |
+
+```ts
+// The synapta Plan 118 shape: a 1M-window model under a 500k run input cap, where the legacy
+// 0.75 × window gate (745k) could never open before the run died at its cap.
+const compiler = createAttentionCompiler(
+  { trigger: { kind: "run_input_ratio", ratio: 0.75 }, keepLast: 3 },
+  { model, runInputBudget: 500_000 },
+);
+
+// Any-of, attributed in order: the floor is reported when both would fire.
+createAttentionCompiler({ trigger: [{ kind: "token_floor", tokens: 120_000 }, { kind: "input_ratio", ratio: 0.9 }] }, { model });
+
+// Host predicate: synchronous, evaluated at most twice per turn (once to decide, once to
+// confirm the stages settled it) with a frozen `AttentionTriggerState`.
+createAttentionCompiler(
+  { trigger: (state) => state.estimatedInputTokens > 150_000 && state.turn > 5 },
+  { model },
+);
+```
+
+`AttentionTriggerState` is frozen and carries estimates only: `estimatedInputTokens` (this turn's assembled request), `inputCapTokens`, `runInputBudgetTokens` (absent when the run declares none), `runInputTokens` (charged spend so far), and `turn`. A predicate that returns a non-boolean — including a `Promise` from an `async` function — fails closed with a `TypeError` naming the option, rather than silently never firing.
+
+Predicate axes run **host-supplied code**, under the same trust as `CompactionTrigger.custom`: the compiler passes host data in and takes a boolean out, never credentials or payloads. Keep them synchronous and side-effect free; they see token estimates and ids, never message text.
+
+Rules that hold for every axis:
+
+- **Config-time validation.** Unknown kinds, a ratio outside `(0, 1)`, a non-positive `token_floor.tokens`, an empty array, and a predicate that is not a function all throw a `TypeError` naming the option (`attentionCompiler.trigger`, or `attentionCompiler.trigger[1]` inside an array).
+- **Gate is agent-config only.** A run overlay may not set `trigger`, `maxInputTokens`, or `reserveTokens` — the gate and the cap move together, so moving either belongs in the agent config.
+- **One evaluation per turn.** The axes are evaluated at turn start against the measured request and once more after the stages. The per-row loop then compares numbers, so a predicate costs two calls a turn no matter how many rows are eligible.
+- **Sticky and monotonic as ever.** An axis only decides *whether* to fold; the stages still stop as soon as a target is reached, and mutations stay applied on later under-gate turns.
+- **`run_input_ratio` needs its budget.** With `compactAfterTokens`-style run limits declared (`RunLimits.maxInputTokens`, which defaults to `40_000` and kills the run cumulatively), pass the resolved value as `runInputBudget`. Without one the axis is the per-request `input_ratio` comparison.
+- **`triggerRatio` stays the reference.** Omitted alongside `trigger`, it takes the first `input_ratio` axis's ratio so `compactRatio` and the report still describe the real fold point; with no `input_ratio` axis it keeps the default `0.75` as the compaction reference.
+
+Runnable end to end: [`examples/attention-budget-axes.ts`](../examples/attention-budget-axes.ts) runs the scenario both axes exist for — a 1M window, a 500k run budget, 24 provider turns. The window axis would need 743k tokens and never gets near (`maxUsed` ≈ 7k, so it never fires); cumulative spend crosses 1 % of the budget on turn 6, the gate opens there, and the run finishes having spent 36k of its 500k with the newest 2 rows raw and every older body a stub. `src/__tests__/attention-compiler-budget.test.ts` asserts the same numbers, including that the first fold could only be explained by carried-over spend.
+
 ## Outputs / response / events
 
 `createAttentionCompiler` returns an `AttentionCompiler`: `inputCap`, `reserveTokens`, `triggerRatio`, `compactRatio`, `thinkingKeepTurns`, `keepLast`, and a frozen, de-duplicated `excludeTools`. It performs no I/O and calls no provider.
@@ -97,10 +145,12 @@ Turn options, passed to `assembleProviderInput`:
 | `used` | `number` | Estimated tokens measured before this turn's mutation. |
 | `usedAfter` | `number` | Estimated tokens of the same request after the mutation, so `used` → `usedAfter` is the per-turn cost curve. |
 | `inputCap` | `number` | Resolved cap the ratio was compared against. |
-| `triggerRatio` | `number` | Configured ratio. |
+| `triggerRatio` | `number` | Configured ratio — the reference axis, whether or not a `trigger` replaced the gate. |
+| `firedAxis` | `AttentionTriggerKind?` | Axis that opened the gate on this turn, in configured order; absent on an under-gate turn. Plan 087 attribution reads this. |
 | `droppedThinkingTurns` | `number` | Thinking turns absent from this request — rows re-applied from the sticky frontier count again. |
 | `stubbedToolResults` | `number` | Tool results stubbed in this request — re-applied rows count again. |
 | `stubbedBytes` | `number` | Payload bytes those stubs took out of the request (message bytes minus the stub header). |
+| `newFoldedBodies` | `number` | Folded bodies this turn added to the ledger: the `summarize` calls the cache saved, and the durable-fold checkpoint signal. `0` on a turn that only re-applied stored bodies. |
 | `truncated` | `boolean` | `true` when the gate stopped with eligible rows left, so the sticky frontier is partial. |
 | `runId` / `sessionId` | `string?` | Owning run/session when known. |
 
@@ -119,7 +169,7 @@ Tool result read_file [call_1]: omitted 41_982 bytes (sha256 3f9a1c2b4d5e6f70a1b
 
 Never stubbed: rows named in `excludeTools`, tool **errors**, results stamped as a decision/approval payload (`approval`, `approvalId`, `prismApproval`, `decision`, `decisions`, `pendingDecisions`, `elicitation` metadata), rows the host fold's own age/byte gates exclude, and any row whose stub would cost more than the payload it replaces. When `toolResultFold.summarize` is configured, that function produces the stub body for the rows the compiler picked (capped by its `maxSummaryBytes`); otherwise the deterministic digest above is used.
 
-`compileAttention({ compiler, groups, context?, skills?, tools?, fold?, frontier?, redactor?, signal?, turn?, sessionId?, runId? })` is what `assembleProviderInput` calls; it returns `{ groups, mutated, report }`. Under the ratio it returns the **same groups object** it was given; when it mutates it returns new `history` / `toolResults` arrays and never writes into the caller's arrays.
+`compileAttention({ compiler, groups, context?, skills?, tools?, fold?, frontier?, attentionFold?, redactor?, signal?, turn?, runInputTokens?, sessionId?, runId? })` is what `assembleProviderInput` calls; it returns `{ groups, mutated, report }`. Under the ratio it returns the **same groups object** it was given; when it mutates it returns new `history` / `toolResults` arrays and never writes into the caller's arrays.
 
 Errors:
 
@@ -137,6 +187,7 @@ Errors:
   "keepLast": 3,
   "excludeTools": ["submit_payment"],
   "reserveTokens": 1024,
+  "durable": false,
   "compaction": {
     "trigger": {
       "type": "custom",
@@ -244,11 +295,40 @@ See [Compaction and retry policies](compaction-and-retry.md) for the trigger uni
 - `excludeTools` is fail closed: entries are validated as non-empty bounded strings, de-duplicated, and frozen; a named tool is never stubbed even when the request stays over the ratio.
 - The compiler never orchestrates other levers: `toolResultFold.summarize` still wins for fold-eligible rows when a host supplies it, `applyContextBudget` keeps working unchanged for compiler-off agents, and compaction stays a task-boundary operation (`session.compact()` still throws while a run is in flight).
 - Sticky means sticky: a stripped thinking turn is never restored and a stubbed call id is never un-stubbed, even on a later under-ratio turn — restoring either would rewrite the cached prefix. Pass no `attentionSticky` for one-shot assemblies.
-- The frontier is bounded (256 thinking keys, 256 tool-call ids, newest kept) and lives on the session, so it survives turns and runs. A durable run with `persistSessionState: true` also writes it into the checkpoint (`sessionState.attentionSticky`) and restores it on resume, so a resumed run keeps its stubs instead of re-deciding its first turn from the ratio; a malformed or hand-edited frontier is dropped entry by entry, never fatal to a resume.
+- The frontier is bounded (256 thinking keys, 256 tool-call ids, newest kept) and lives on the session, so it survives turns and runs. A durable run with `persistSessionState: true`, or any run with `durable: true`, also writes it into the checkpoint (`sessionState.attentionSticky`) and restores it on resume, so a resumed run keeps its stubs instead of re-deciding its first turn from the ratio; a malformed or hand-edited frontier is dropped entry by entry, never fatal to a resume.
 - A compiler-on turn assembles from the default message groups (instructions, summaries, history, input, attachments, tool results) exactly like a `contextBudget` turn, so a custom `inputBuilder` is not consulted while the compiler is on.
 - Compaction timing is programmable per agent through `CompactionOptions.trigger` (`threshold_entries` | `input_ratio` | `custom`); omitting it keeps today's `thresholdEntries` gate. `assertCompactionTrigger(trigger)` validates a trigger independently of the compiler.
 - The gate is opt-in per agent/run; omit the option for current assembly bytes.
 
+### Durable folding
+
+`durable: true` puts the fold state on disk (plan 086 T3), so a run that dies mid-investigation resumes
+with the rows it had already folded instead of re-deciding them from the ratio.
+
+```ts
+const agent = createAgent({
+  // ...
+  attentionCompiler: {
+    trigger: { kind: "run_input_ratio", ratio: 0.75 },
+    keepLast: 2,
+    durable: true,
+  },
+  runState: { checkpoints, definitionRevision: "1" }, // the write target; `persistSessionState` not required
+  toolResultFold: { summarize: hostSummarize },        // optional: bodies become durable too
+});
+
+// After a crash the worker resumes where the fold left off:
+await resumeAgentRun(agent, { runId, sessionId }, { decision: "continue", expectedVersion }, { checkpoints, definitionRevision: "1" });
+```
+
+- **One write per fold, never per turn.** The checkpoint is written after the turn's request is assembled and before the provider sees it, only on turns that added folded bodies. A turn that re-applies what the ledger already holds writes nothing.
+- **The fold ledger.** Each folded body is stored once, keyed by tool call id (newest 64, 4 KiB each), and re-applied on every later turn: the host `summarize` runs once per row instead of once per turn, and a sticky row stays byte-identical for the provider cache. Bodies are already redacted and capped by the fold that produced them.
+- **Independent of `persistSessionState`.** That option governs skill and tool-activation state. `durable` is its own opt-in for the fold ledger plus its sticky frontier (`sessionState.attentionFold` / `attentionSticky`), because a resumed run needs both: the frontier decides *what* stays folded, the ledger decides *what body* it was folded to.
+- **Restore is fault-tolerant.** A malformed ledger shape starts from an empty ledger, and a malformed entry is dropped one by one — the row simply re-folds on the next over-gate turn. A hand-edited checkpoint never blocks a resume.
+- **Sizing.** Off by default. On, it costs one checkpoint write per fold turn plus `bodies × (body ≤ maxSummaryBytes)` bytes in the run state (default cap: 64 bodies), and it makes the fold the run's first crash-recovery point when `checkpointPolicy` is `"decision"`.
+- **Requires a durable run.** `durable: true` without `runState` (a checkpoint store) throws `AgentRunStateError` at run start, before the first provider turn. A run overlay may not set `durable`.
+- **Still projection-only.** Durability changes *where the projection is remembered*, not what the store holds: the session store, observational-memory ledger, and semantic stores keep every original payload for recall, branching, and audit.
+
 ## Security and performance notes
 
 - Validation is synchronous with no provider I/O, and the returned handle plus `excludeTools` are frozen.
@@ -264,9 +344,10 @@ See [Compaction and retry policies](compaction-and-retry.md) for the trigger uni
 
 - [`assembleProviderInput`](input-and-prompt-assembly.md): the compose path the compiler pre-passes when enabled.
 - [`toolResultFold`](input-and-prompt-assembly.md): host summarizer that wins over the deterministic stub for eligible rows.
-- [`CompactionOptions`](compaction-and-retry.md): `trigger` is the host compact-when seam; `thresholdEntries` remains the default gate.
+- [`CompactionOptions`](compaction-and-retry.md): `trigger` is the host compact-when seam; `thresholdEntries` remains the default gate. For fold state that outlives a crash, see [Durable folding](#durable-folding).
 - [`observational-memory`](compaction-observational-memory.md): host `shouldCompact` / trigger overrides `compactAfterTokens` for post-run compaction.
 - [`provider caching`](provider-caching.md): why mutations are monotonic and in-place.
 - [`AttentionReport` measurements](_evidence/phase74-attention-measurements.md): the hermetic fixture behind the savings, cache, resume, and truncation numbers.
+- Example: [`examples/attention-budget-axes.ts`](../examples/attention-budget-axes.ts) — budget-capped long run where only the cumulative axis can open the gate.
 - [Memory fabric](memory-fabric.md): a context source whose blocks are measured like any other (`working-memory` / `semantic-memory` tags, no layer id).
 - [`thinking and reasoning`](thinking-and-reasoning.md): the `thinking` blocks the first stage strips.

package/docs/coding-agent-tools.md

@@ -610,7 +610,7 @@ Every configurable value is a positive safe integer (context may be zero); Prism
 - [Language intelligence](language-intelligence.md): optional host-activated LSP contract (`createLanguageIntelligence`) — symbols/definitions/references/diagnostics/hover/rename.
 - [Process sessions](process-sessions.md): optional managed long-running processes (`createProcessSessions`) — start/output/input/wait/signal/kill/release.
 - [Forge integration](forge-integration.md): optional GitHub adapter (`createGitHubForge`) — issue context, authenticated push, PR create/update, review comments, checks, bounded handoff reconcile; effect-store idempotency, no duplicate PRs/comments on retry, tokens never in argv/logs/events.
-- [Tools](tools.md): the host-owned tool harness — `createToolRegistry`, `dispatchToolCall`, filtering, and the `ToolDefinition` contract these factories satisfy.
+- [Tools](tools.md): the host-owned tool harness — `createToolRegistry`, `dispatchToolCall`, filtering, `toolNarrowing` per-turn menus, and the `ToolDefinition` contract these factories satisfy.
 - [Public contracts](public-contracts.md): `ToolDefinition`, `ToolResult`, `ToolExecutionContext`, `ContentBlock`, and `JsonObject` shapes.
 - [Host security guide](host-security.md): fail-closed checklist for permission policies, tool validation, and trust boundaries that must gate these tools.
 - [Tool conformance](tool-conformance.md): assertions for the tool-dispatch blocked-reason matrix these tools participate in.

package/docs/compaction-and-retry.md

@@ -203,7 +203,7 @@ The default strategy does not call a provider. Hosts that need model-generated s
 - [Session stores and branching](session-stores-and-branching.md): branch entries, compaction entries, and `rebuildSessionContext()` behavior.
 - [Input and prompt assembly](input-and-prompt-assembly.md): compacted summaries become default summary messages for provider input.
 - [Agent/session runtime](agent-session-runtime.md): `session.compact()`, opt-in auto-compaction, `RunOptions.retry`, and `retry_scheduled` runtime behavior.
-- [Attention compiler](attention-compiler.md): resolves the same input cap and shrinks an over-ratio request before compaction is considered.
+- [Attention compiler](attention-compiler.md): resolves the same input cap and shrinks an over-ratio request before compaction is considered; with `attention.compiler.durable` the fold ledger and frontier are checkpointed per fold, so a run that dies mid-investigation resumes already folded instead of replaying the pre-fold tail.
 - Example: [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) — task-boundary compact after each iteration.
 - [Middleware hooks](middleware-hooks.md): `compaction` and `retry` middleware payload timing.
 - [Contribution registries](contribution-registries.md): compaction strategy and retry policy contributions.