@arnilo/prism 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+## [0.7.0] - 2026-09-15 (extended line: plans 072, 073, 074, 075, 077, 078)
+
+> **Channels are not in this cut.** Plan 079 (Telegram/Signal adapters) was reassigned to **0.8.0** so the 0.7.0 cut stops waiting on it; nothing in this release mentions or ships a channel adapter.
+
+### Added
+- **Execution timeline (plan 072).** `@arnilo/prism-core/governance/observability` ships one frozen, JSON-serializable view-model for what a run did: `projectAgentTimeline` (live `AgentEvent[]`), `projectTraceTimeline` (persisted `EvaluationTrace`), `projectWorkflowTimeline` (workflow events plus optional checkpoint), incremental `createTimelineFolder` / `createWorkflowTimelineFolder` folders for SSE/cockpit updates, and `summarizeTimeline` / `summarizeSession` rollups (tool counts capped at 64, no double counting across runs). See [docs/execution-timeline.md](docs/execution-timeline.md).
+- **Workflow graph view-model (plan 072).** `serializeWorkflowGraph`, `workflowGraphToMermaid`, `workflowGraphToDot`, `projectWorkflowGraphRun`, and `createWorkflowGraphRunFolder` render a workflow DAG and overlay live or checkpoint run state (`WorkflowGraphRunView`) without executing it.
+- **Trajectory and outcome evals (plan 072).** Scorers (`defineScorer`, pairwise preferences, model-judge budgets), `runScenario`, `runExperiment`, `runWorkflowExperiment`, dataset items with expected trajectories, trials, manifests, comparisons, and thresholds — with `runComparison` / `datasetFromRuns` curation over recorded runs.
+- **Eval primitives match their contracts (plan 073 Tasks 30–31).** Injection/timeline holes closed, deterministic `mulberry32` sampling, `collectWhileRunning`, and host-activity eval packs (coding, browser, memory, voice invariants) over the true primitives.
+- **Attention compiler (plan 074, opt-in).** `createAttentionCompiler` / `resolveInputCap` / `compileAttention` / `createAttentionTruncationTrigger`: a per-turn gate that measures the assembled input against a host ratio of the model input cap and, only past the ratio, mutates a **history clone** oldest thinking blocks first, then fold-eligible tool results — keeping cache prefixes, the session store, and the observational-memory ledger untouched, and raising `AttentionBudgetError` rather than silently dropping context. Wired through `AgentConfig`, `AgentDefinition`, and `RunOptions` (run overlay narrows), plus `attention_compiled` telemetry and an `attention` timeline step; sticky frontier persists through `persistSessionState`. See [docs/attention-compiler.md](docs/attention-compiler.md).
+- **Memory fabric subpath (plan 075, opt-in).** `@arnilo/prism-memory/fabric` adds typed notes (`fact`, `procedure`, `file`, `working`, `episode`) with links, validity windows, time/tool recall, conversation search, and opt-in consolidation/linker/evolution workers over the stores a host already configured. Inert until `fabric.attach(session)`; no new package, provider, database, or mandatory dependency. See [docs/memory-fabric.md](docs/memory-fabric.md).
+- **Work-scope memory index (plan 077, opt-in).** `createWorkScopeController` appends `om.scope.*` entries to one observational-memory ledger; `foldWorkScopeMap`, `projectWorkMemory`, and `withWorkScope` project the outline to a host-selected working set (leaf `self+ancestors` by default), auto-bind new observations to the leaf, and skip the observation dropper while any host scope exists. Caps fail closed (256 scopes, depth 8, 4,096 binds, 512-char labels). See [docs/compaction-observational-memory.md](docs/compaction-observational-memory.md).
+- **Host-owned subagent spawn (plan 078, opt-in).** `createSpawnAgentTool` turns the supervisor's host-owned child catalog into a non-exclusive `spawn_agent` whose closed schema exposes only allow-listed child ids, input, an optional thread id, and `mode: "sync" | "async"`; `createWaitAgentTool` / `createCancelAgentTool` join or abort async handles from `delegateAsync()`. Child identity narrows from the parent, results and errors are redacted, child slots are reserved atomically (after a before-hook narrows limits), and parent-run abort cancels running children. `createWorktreeChildFactory` gives each child its own linked git worktree and cleans it up on every terminal outcome (including a suspended child that later resumes), while `observeSupervisorLifecycle` bridges `delegation_*` events to redacted coding `subagent_started` / `subagent_stopped` lifecycle events. See [docs/supervisors.md](docs/supervisors.md).
+- **Governed host completeness (plan 073).** Governed provider invocation with aggregate task/tenant accounting across every paid work kind (enterprise migration `006_aggregate_budgets`); durable business-action drafts with editable approvals; Docker process sessions and coherent workspace recovery; incremental Drive knowledge synchronization; snapshot/reconnect lifecycle with a hosted E2B sandbox; fair worker admission and operator routes; cross-layer memory lineage with correction and revocation; semantic artifact review with evidence-backed citations; import-fidelity reports with optional OCR; monotonic per-run tool narrowing with remote invalidation; native Bedrock `Converse`/`ConverseStream`; and governed realtime voice orchestration. New pages: [docs/execution-timeline.md](docs/execution-timeline.md), [docs/host-compositions.md](docs/host-compositions.md), [docs/hosted-sandboxes.md](docs/hosted-sandboxes.md), [docs/knowledge-sync.md](docs/knowledge-sync.md), [docs/realtime-voice.md](docs/realtime-voice.md), [docs/attention-compiler.md](docs/attention-compiler.md), [docs/memory-fabric.md](docs/memory-fabric.md).
+- **Examples.** Runnable demos for the new surfaces: `examples/execution-timeline.ts`, `examples/behavior-evaluation.ts`, `examples/coding-browser-evaluation.ts`, `examples/attention-compiler.ts`, `examples/memory-fabric.ts`, `examples/work-scopes-coding-loop.ts`, `examples/spawn-agent-tool.ts`, `examples/governed-provider.ts`, `examples/docker-process-session.ts`, `examples/drive-rag-sync.ts`, `examples/hosted-sandbox.ts`, `examples/scanned-document-rag.ts`, and `examples/realtime-voice-host.ts`.
+
+### Changed
+- **Lockstep `0.6.0` → `0.7.0`.** All ten publishable manifests move together with `^0.7.0` internal ranges; the lockfile, the `src/index.ts` version constant, the docs index banner, the release-workflow tag lists, and the generated package-truth artifact agree (enforced by `scripts/version-literal-gate.test.mjs`).
+- **Compat baselines regenerated** (`--update-baseline`): **469 added declarations, zero removals**. The additions are the new subpath APIs above plus members added to existing declaration groups; no export was renamed or dropped.
+- **Release budgets rebaselined with recorded reasons**: root packed/unpacked/fileCount moved for the new dist modules, templates, and docs pages, and per-package export ceilings carry the 0.7.0 addition list. Startup and timing ceilings are unchanged.
+- **Migration guide for 0.6.0 hosts**: [docs/migrate-to-0.7.md](docs/migrate-to-0.7.md) (per-item actions for the ACP/model-router refusals, every tightening, the opt-in activation steps, and rollback), indexed from [docs/migration.md](docs/migration.md) and [docs/index.md](docs/index.md).
+- **Options index and peer matrix** cover the new surfaces: [docs/options-index.md](docs/options-index.md) routes `AttentionCompilerOptions`/`AttentionInputCapOptions`/`AttentionCompileOptions`/`AttentionTruncationTriggerOptions`, the fabric and work-scope option objects, and the supervisor/spawn/worktree/lifecycle options to their owning pages (gated by `scripts/live-doc-check.test.mjs`).
+
+### Fixed
+- **Task-scoped enterprise budgets failed on their first insert.** Migration `006_aggregate_budgets`' insert bound one JavaScript `Date` to both a `timestamptz` column and interval arithmetic, so PostgreSQL refused the statement with `42P08 inconsistent types deduced for parameter $8`; the parameter is now explicitly `::timestamptz` (found by the protected PostgreSQL leg, not by hermetic doubles).
+- **A serialization failure inside the budget upsert was swallowed.** The read-then-insert path caught *every* error from the `SELECT … FOR UPDATE` probe and then issued SQL against an aborted transaction (`25P02`), which defeated the retry loop; only a genuinely missing row is recoverable by inserting now.
+- **Serializable retry policy was too small for concurrent writers.** Budget/rate rewrites on one row now retry up to 12 times with full-jitter exponential backoff (capped at 250 ms), so a 16-client burst converges instead of exhausting three near-instant attempts with `ERR_PRISM_ENTERPRISE_POSTGRES_RETRYABLE`.
+- **Integration tests were stale against migration 006** (expected five migrations) and `scripts/phase27-release.test.mjs` still asserted that no `006_` migration existed; both now check the append-only list including `006_aggregate_budgets`.
+
+### Security
+- **ACP MCP destination matching (Trap A).** `mcp.allow` entries now match by WHATWG origin plus path-segment subtree: origin lookalikes (`mcp.example.com.attacker.invalid`) and sibling path prefixes (`/mcp-other`) no longer match, and allow entries carrying userinfo, query, fragment, or ambiguous encoded path forms fail `ConfigError` at parse time.
+- **Model-router facade fails closed (Trap B).** `router.providerSource(model)` throws `ERR_PRISM_MODEL_ROUTER_ASYNC_REQUIRED` / `ERR_PRISM_MODEL_ROUTER_ASYNC_STATE` instead of handing back a provider that bypasses budgets, rate limits, circuits, fallbacks, selection policies, or durable state; `isProviderSourceEligible` lets a host check first.
+- **ACP launcher requires a real provider (Trap C/R05).** No silent `createMockProvider()` fallback; mock mode is an explicit opt-in.
+- **Per-run tool narrowing is monotonic (R11)** and remote invalidation is honored; child agents cannot widen the tenant, account, user, or scopes of the parent identity (`narrowIdentity` + `assertIdentityPropagation`).
+
+### Notes
+- **Protected PostgreSQL leg now green on 0.7.0 code**: `PRISM_TEST_POSTGRES_URL=… npm run test:postgres` passes core (72), memory (457), and the phase conformance legs (11) against `pgvector/pgvector:pg16`, the same image the release workflow uses. The three fixes above are what that leg caught.
+- **Node floor is unchanged** at `>=22` (Node 22/24 supported).
+
 ## [0.6.0] - 2026-09-12 (plans 070, 071)
 
 > **0.5.7 was never published.** This release folds that cut's content (durable concurrent tool rounds, strict-provider tool results, host-tunable knobs, peer/options truth, the dependency refresh, and the module splits) together with the 0.6.0 changes below, so a host on 0.5.6 upgrades once. See [docs/migrate-to-0.6.md](docs/migrate-to-0.6.md).
@@ -129,27 +168,27 @@
 ### Added
 - **OKF adoption (`@arnilo/prism-wiki`)**: wiki-init/refresh/lint emit and validate
   OKF v0.2 bundles (Karpathy prompt retained). See `docs/wiki.md`.
-- **DOCS-1 (Clay integration findings)**: three integrator contracts, in place on
+- **DOCS-1 (integration findings)**: three integrator contracts, in place on
   the pages that own them — resume-aware workflow nodes (`ctx.resume` or silent
   re-suspend) in `docs/workflows.md`; supervisor child factories return `Agent`
   not `AgentSession` (`SupervisorError: child "<id>" factory must return an
   Agent, got <type>`) plus durable-store nested approvals in `docs/supervisors.md`;
   task-boundary `session.compact()` fails closed during an active run in
   `docs/compaction-and-retry.md`. Each block links `examples/autonomous-coding-loop.ts`.
-- **FEATURE-2 (Clay integration findings)**: documented bounded iterate-until-done
+- **FEATURE-2 (integration findings)**: documented bounded iterate-until-done
   host-loop pattern in `docs/workflows.md` — one `runWorkflow` per iteration,
   iteration state in workflow inputs, explicit termination predicate and budgets,
   typed `BudgetExhaustedError` (fail-closed, never a hang), `replayWorkflow` per
   iteration run id. Seeded by `examples/autonomous-coding-loop.ts`. Plan 045 `loop`
   node remains the future in-graph primitive; this intake ships the docs+example
   minimum only.
-- **FEATURE-6 (Clay integration findings)**: composite `examples/autonomous-coding-loop.ts`
+- **FEATURE-6 (integration findings)**: composite `examples/autonomous-coding-loop.ts`
   conformance reference — goal → roadmap → per-task supervisor children (per-child
   models) → `runCodingGoalVerify`-style validation → observational-memory attach +
   task-boundary compact + recall → human gate with simulated restart → host-side
   bounded iterate-until-done with deterministic budget exhaustion. Mock providers
   only; no credentials or network.
-- **FEATURE-3 (Clay integration findings)**: host-opt-in command driver hooks.
+- **FEATURE-3 (integration findings)**: host-opt-in command driver hooks.
   `CommandExecutionContext` gains an optional `drivers?: CommandDrivers`
   (`startRun` / `startWorkflow` / `steer` — typed minimal handles returning
   `AgentRunResult`-shaped results / workflow run id + status) so a contributed
@@ -159,7 +198,7 @@
   the context shape unchanged (no key, no allocation). Drivers are
   host-injected capabilities, never package-supplied.
 ### Fixed
-- **FEATURE-1 (Clay integration findings)**: `resolveAgentDefinition` no longer
+- **FEATURE-1 (integration findings)**: `resolveAgentDefinition` no longer
   throws `Agent "<name>" has no model` when the declarative definition omits
   `model` but `context.overrides.model` supplies one — the fallback is a
   single `??` at `buildBaseConfig`, the `create()` path is unchanged, and a

package/README.md

@@ -162,16 +162,16 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 
 | package | version | notes |
 | --- | --- | --- |
-| `@arnilo/prism` | 0.6.0 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-coding-tools` | 0.6.0 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.6.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
-| `@arnilo/prism-providers` | 0.6.0 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.6.0 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.6.0 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-mcp` | 0.6.0 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.6.0 | capability — memory plus /rag, /compaction/*, /graft, /wiki subpaths |
-| `@arnilo/prism-office` | 0.6.0 | capability — /documents, /sheets, /diagrams subpaths |
-| `@arnilo/prism-web-tools` | 0.6.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
+| `@arnilo/prism` | 0.7.0 | core — runtime, CLI/RPC, templates, docs |
+| `@arnilo/prism-coding-tools` | 0.7.0 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
+| `@arnilo/prism-core` | 0.7.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
+| `@arnilo/prism-providers` | 0.7.0 | family — all provider adapters as `/<adapter>` subpaths |
+| `@arnilo/prism-acp-agent` | 0.7.0 | capability — ACP adapter |
+| `@arnilo/prism-ag-ui` | 0.7.0 | capability — AG-UI/A2A/A2UI adapter |
+| `@arnilo/prism-mcp` | 0.7.0 | capability — MCP client/server/OAuth interop |
+| `@arnilo/prism-memory` | 0.7.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
+| `@arnilo/prism-office` | 0.7.0 | capability — /documents, /sheets, /diagrams subpaths |
+| `@arnilo/prism-web-tools` | 0.7.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
 <!-- generated:package-truth:inventory end -->
 
 ## Scripts

package/dist/agent-definitions.js

@@ -34,6 +34,7 @@ function buildBaseConfig(def, context) {
         ...(def.context !== undefined && { context: resolveContextProviders(def.name, def.context, context) }),
         ...(def.systemPrompt !== undefined && { systemPrompt: def.systemPrompt }),
         ...(def.instructions !== undefined && { instructions: def.instructions }),
+        ...(def.attentionCompiler !== undefined && { attentionCompiler: def.attentionCompiler }),
         ...(def.loop !== undefined && { loop: def.loop }),
         ...(def.metadata !== undefined && { metadata: def.metadata }),
     };

package/dist/agent-run-lifecycle.js

@@ -1,4 +1,5 @@
 import { assertValidAgentRunResume, pendingDecisionsOf, resolveRunDecisions } from "./agent-approval.js";
+import { parseAttentionStickyFrontier } from "./attention-compiler.js";
 import { agentFingerprint, loadAgentRunState, publicState, saveAgentRunState } from "./agent-run-state.js";
 import { RuntimeAgentSession, throwIfAbortedSignal } from "./agent-session.js";
 import { AgentRunStateError } from "./contracts.js";
@@ -96,6 +97,9 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
         throw new AgentRunStateError("Stale or non-suspended agent run resume");
     }
     const session = new RuntimeAgentSession({ agent, id: state.sessionId, leafId: state.leafId });
+    // Plan 078 Task 7: hand the reconstructed session to an observer (supervisor child-event pump)
+    // before any event flows. Called for every resume outcome; a throw fails closed.
+    options.onSession?.(session);
     // Opt-in session-state restore (plan 015 Task 4): names only; bodies re-resolve from
     // the live registry the next time the model (re)loads them via load_skill.
     if (options.persistSessionState && state.sessionState?.loadedSkillNames) {
@@ -105,6 +109,13 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     if (options.persistSessionState && state.sessionState?.activatedToolNames) {
         session.restoreActivatedTools(state.sessionState.activatedToolNames);
     }
+    // Plan 074 P3: restore sticky attention mutations (already validated at load) so the first
+    // turn after a resume keeps its stubs instead of re-deciding them from the ratio.
+    if (options.persistSessionState && state.sessionState?.attentionSticky) {
+        const frontier = parseAttentionStickyFrontier(state.sessionState.attentionSticky);
+        if (frontier)
+            session.restoreAttentionSticky(frontier);
+    }
     // Plan 018 Task 6 (closeout `checkpoint-bodies`): restore exact instructions so the
     // resumed session renders them registry-independently (no load_skill round-trip).
     if (options.persistSessionState && options.includeSkillBodies && state.sessionState?.loadedSkillBodies) {

package/dist/agent-run-state.d.ts

@@ -1,4 +1,5 @@
 import type { Agent, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, CheckpointRecord, CheckpointStore, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
+import { type PersistedAttentionStickyFrontier } from "./attention-compiler.js";
 import type { SecretRedactor } from "./redaction.js";
 import { type LoadedSkillBodiesEntry } from "./skill-load.js";
 export declare const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
@@ -46,7 +47,12 @@ export interface StoredAgentRunState extends AgentRunState {
         readonly loadedSkillBodies?: readonly LoadedSkillBodiesEntry[];
         /** Plan 041: tools activated via `search_tools` (names only; inert for absent tools on restore). */
         readonly activatedToolNames?: readonly string[];
+        /** Plan 074 P3: sticky attention mutations (thinking hashes + tool-call ids), so a durable
+         *  resume keeps its stubs instead of re-deciding on the first turn. Validated on load. */
+        readonly attentionSticky?: PersistedAttentionStickyFrontier;
     };
+    /** Per-run allow-list (Task 21). Absent = full registered set (legacy checkpoints). */
+    readonly toolNames?: readonly string[];
 }
 /** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */
 export declare const MAX_PERSISTED_SKILL_NAMES = 64;

package/dist/agent-run-state.js

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
 import { AgentLoopStateError, AgentRunStateError } from "./contracts.js";
+import { parseAttentionStickyFrontier } from "./attention-compiler.js";
 import { validateLoadedSkillBodies } from "./skill-load.js";
+import { HARD_RUN_TOOL_NAMES } from "./tools.js";
 export const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
 export const AGENT_RUN_STATE_SCHEMA_VERSION = 1;
 export const DEFAULT_MAX_AGENT_RUN_STATE_BYTES = 256 * 1024;
@@ -128,7 +130,7 @@ export async function saveAgentRunState(input) {
     return { record, state: { ...bounded, version: record.version } };
 }
 export function publicState(state) {
-    const { input: _input, pending: _pending, pendingCalls: _pendingCalls, nestedRuns: _nestedRuns, interruptBeforeTool: _interruptBeforeTool, counters: _counters, deadlineAt: _deadlineAt, ...publicValue } = state;
+    const { input: _input, pending: _pending, pendingCalls: _pendingCalls, nestedRuns: _nestedRuns, interruptBeforeTool: _interruptBeforeTool, counters: _counters, deadlineAt: _deadlineAt, toolNames: _toolNames, ...publicValue } = state;
     return publicValue;
 }
 export function initialAgentRunState(input) {
@@ -203,6 +205,16 @@ export function parseAgentRunState(value, version) {
             !("snapshot" in state.loopState))) {
         throw new AgentRunStateError("Malformed agent run loop state");
     }
+    if (state.toolNames !== undefined) {
+        if (!Array.isArray(state.toolNames) || state.toolNames.length > HARD_RUN_TOOL_NAMES) {
+            throw new AgentRunStateError(`Run toolNames exceed ${HARD_RUN_TOOL_NAMES} entries`);
+        }
+        for (const name of state.toolNames) {
+            if (typeof name !== "string" || name.length === 0 || name.length > MAX_PERSISTED_SKILL_NAME_CHARS) {
+                throw new AgentRunStateError("Malformed agent run toolNames");
+            }
+        }
+    }
     // Load bounds against the hard cap, not the default: the configured maxStateBytes is a
     // save-side policy knob, while the load-side bound is only a DoS ceiling. States saved
     // with a raised maxStateBytes must remain resumable.
@@ -261,15 +273,23 @@ function validateSessionState(sessionState) {
         }
     }
     const activated = sessionState.activatedToolNames;
-    if (activated === undefined)
-        return;
-    if (!Array.isArray(activated) || activated.length > MAX_PERSISTED_ACTIVATED_TOOL_NAMES) {
-        throw new AgentRunStateError(`Activated-tool names exceed ${MAX_PERSISTED_ACTIVATED_TOOL_NAMES} entries`);
-    }
-    for (const name of activated) {
-        if (typeof name !== "string" || name.length > MAX_PERSISTED_SKILL_NAME_CHARS) {
-            throw new AgentRunStateError(`Activated-tool name exceeds ${MAX_PERSISTED_SKILL_NAME_CHARS} chars`);
+    if (activated !== undefined) {
+        if (!Array.isArray(activated) || activated.length > MAX_PERSISTED_ACTIVATED_TOOL_NAMES) {
+            throw new AgentRunStateError(`Activated-tool names exceed ${MAX_PERSISTED_ACTIVATED_TOOL_NAMES} entries`);
         }
+        for (const name of activated) {
+            if (typeof name !== "string" || name.length > MAX_PERSISTED_SKILL_NAME_CHARS) {
+                throw new AgentRunStateError(`Activated-tool name exceeds ${MAX_PERSISTED_SKILL_NAME_CHARS} chars`);
+            }
+        }
+    }
+    const attention = sessionState.attentionSticky;
+    if (attention === undefined)
+        return;
+    // Both arrays are capped by the parser, and a malformed frontier is dropped rather than
+    // failing the resume: re-deciding a mutation is safe, refusing to resume is not.
+    if (parseAttentionStickyFrontier(attention) === undefined) {
+        throw new AgentRunStateError("Malformed agent run attention frontier");
     }
 }
 //# sourceMappingURL=agent-run-state.js.map

package/dist/agent-session/session/assemble.js

@@ -3,6 +3,7 @@ import { AgentRunSuspended } from "../../agent-approval.js";
 import { resolveLoop, resolveToolConcurrency } from "../../agent-loops.js";
 import { validateRunStateOptions } from "../../agent-run-state.js";
 import { activeTools } from "../../agent-tool-dispatch.js";
+import { resolveRunAttentionCompiler } from "../../attention-compiler.js";
 import { AgentLoopStateError, AgentRunError, AgentRunStateError } from "../../contracts.js";
 import { assertGuardrailsAllowed, runGuardrails } from "../../guardrails.js";
 import { identityTelemetryAttributes, ownershipFromIdentity, resolveRunIdentity } from "../../identity.js";
@@ -16,7 +17,7 @@ import { assertStructuredOutputRequestSupported, resolveRunProviderOptions } fro
 import { composeSystemPrompt, mergeSystemPromptConfig } from "../../system-prompts.js";
 import { resolveToolResultFold } from "../../tool-result-fold.js";
 import { createSearchToolsTool, createToolSearchState, resolveToolsDisclosure } from "../../tool-search.js";
-import { createToolRegistry } from "../../tools.js";
+import { createToolRegistry, selectRunTools } from "../../tools.js";
 import { bridgeAbort, createUsageAccumulator, inputToMessages, isDurableLoop, isSteerSoftInterrupt, mergeGuardrails, throwIfAborted, } from "../helpers.js";
 import { cleanupRun, persistDurable, persistSucceeded, suspendDurable } from "./persist.js";
 import { generateWithRetry, recordProviderUsage } from "./provider-round.js";
@@ -61,7 +62,12 @@ async function assembleRoundContext(params) {
     };
     await session.activeLedger?.appendRun(redactRunLedgerRecord(startRecord, session.activeRedactor));
     await session.rebuildHistory();
-    const { registry: baseRegistry, tools: activeToolList } = activeTools(session.agent.config.tools);
+    const { tools: listed } = activeTools(session.agent.config.tools);
+    const selected = selectRunTools(listed, options.toolNames, resumed?.state?.toolNames);
+    session.activeToolNames = selected.grant;
+    // Run-local snapshot: concurrent runs and MCP refresh must not mutate this registry.
+    const activeToolList = selected.tools;
+    const baseRegistry = createToolRegistry(activeToolList);
     const toolsDisclosure = resolveToolsDisclosure(options.toolsDisclosure, session.agent.config.toolsDisclosure);
     const toolSearch = toolsDisclosure === "search" && activeToolList.length > 0
         ? {
@@ -115,6 +121,26 @@ async function assembleRoundContext(params) {
     const providerOptions = resolveRunProviderOptions(options, session.agent.config);
     assertStructuredOutputRequestSupported(options.model ?? session.agent.config.model, providerOptions);
     const validate = options.validate ?? session.agent.config.validator;
+    // Resolved once per run, before any provider turn: a bad setting or a widening run overlay
+    // fails here rather than on the turn that happens to cross the ratio (plan 074 C12).
+    const attentionCompiler = resolveRunAttentionCompiler(session.agent.config.attentionCompiler, options.attentionCompiler, options.model ?? session.agent.config.model);
+    // Telemetry seam (plan 074 T6): one `attention_compiled` per mutated turn, counts and the
+    // measured ratio inputs only. Under-ratio turns and compiler-off runs emit nothing.
+    const onAttentionReport = attentionCompiler
+        ? (report) => session.emit({
+            type: "attention_compiled",
+            sessionId: session.id,
+            runId,
+            used: report.used,
+            usedAfter: report.usedAfter,
+            inputCap: report.inputCap,
+            triggerRatio: report.triggerRatio,
+            droppedThinkingTurns: report.droppedThinkingTurns,
+            stubbedToolResults: report.stubbedToolResults,
+            stubbedBytes: report.stubbedBytes,
+            truncated: report.truncated,
+        })
+        : undefined;
     const instructionInjectors = options.instructionInjectors ?? session.agent.config.instructionInjectors ?? [];
     const inputLayout = options.inputLayout ?? session.agent.config.inputLayout;
     const loop = resolveLoop(options, session.agent.config);
@@ -183,6 +209,11 @@ async function assembleRoundContext(params) {
                 toolsSearch: session.agent.config.toolsSearch,
                 activatedTools: session.activatedTools,
                 toolResultFold: resolveToolResultFold(options.toolResultFold, session.agent.config.toolResultFold),
+                attentionCompiler,
+                // Session-owned: a stub made earlier stays applied even on a later under-ratio turn, so
+                // the prompt-cache prefix is not rewritten (C10). Undefined when the compiler is off.
+                attentionSticky: attentionCompiler ? session.attentionStickyFor() : undefined,
+                onAttentionReport,
                 loadedSkills: session.loadedSkills,
                 tools,
                 resourceLoader: session.agent.config.resourceLoader,

package/dist/agent-session/session/persist.js

@@ -9,11 +9,14 @@ export async function persistDurable(session, state) {
     const durable = session.activeDurable;
     if (!durable)
         throw new AgentRunStateError("Durable run state is not configured");
+    const withGrant = session.activeToolNames !== undefined ? { ...state, toolNames: session.activeToolNames } : state;
+    const attentionSticky = session.serializedAttentionSticky();
     const persisted = durable.options.persistSessionState
         ? {
-            ...state,
+            ...withGrant,
             sessionState: {
                 loadedSkillNames: session.loadedSkills.list(),
+                ...(attentionSticky ? { attentionSticky } : {}),
                 ...(session.activatedTools.list().length ? { activatedToolNames: session.activatedTools.list() } : {}),
                 ...(durable.options.includeSkillBodies
                     ? {
@@ -24,7 +27,7 @@ export async function persistDurable(session, state) {
                     : {}),
             },
         }
-        : state;
+        : withGrant;
     const saved = await saveAgentRunState({
         checkpoints: durable.options.checkpoints,
         state: persisted,
@@ -155,6 +158,7 @@ export async function cleanupRun(input) {
         session.activeMetadata = undefined;
         session.activePromptVersion = undefined;
         session.activeLimits?.dispose();
+        session.activeToolNames = undefined;
         session.activeLimits = undefined;
         session.activeLimitOutputBuffer = false;
         session.activeRedactor = undefined;

package/dist/agent-session/session/tool-round.js

@@ -278,6 +278,7 @@ export function bindDispatchToolCall(ctx) {
                 ownership: ctx.session.activeOwnership,
                 identity: ctx.session.activeIdentity,
                 guardrails: ctx.session.activeGuardrails,
+                ...(ctx.tools.length > 0 ? { filter: { allow: ctx.tools.map((tool) => tool.name) } } : {}),
                 limitTracker: ctx.limits,
                 beforeExecute: async (mediatedCall) => {
                     const durable = ctx.session.activeDurable;

package/dist/agent-session/session/types.d.ts

@@ -1,6 +1,7 @@
 /** Shared host/round types for runInternal phase split (plan 059). Internal only. */
 import type { ActiveDurableRun } from "../../agent-approval.js";
 import type { PendingToolCall } from "../../agent-run-state.js";
+import type { AttentionStickyFrontier, PersistedAttentionStickyFrontier } from "../../attention-compiler.js";
 import type { Agent, AgentEvent, AgentLoopStrategy, AgentRunResult, AIProvider, ErrorInfo, Guardrails, LoopContext, Message, ModelConfig, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunLedger, RunOptions, SessionEntry, SessionStore, Skill, ToolDefinition, ToolEffectStore, ToolRegistry, Usage } from "../../contracts.js";
 import type { AgentIdentity } from "../../identity.js";
 import type { AgentInput } from "../../input.js";
@@ -47,6 +48,15 @@ export type SessionHost = {
     readonly activatedTools: ActiveToolSet;
     restoredSkillBodies: readonly LoadedSkillBodiesEntry[];
     activeRunSkills: readonly Skill[];
+    /** Names-only grant for this run; undefined means the full registered set. */
+    activeToolNames?: readonly string[];
+    /** Sticky mutation frontier for this session (plan 074 C10); session-owned so it survives
+     *  across turns, runs, and provider rounds. Lazily created on first use. */
+    attentionStickyFor(): AttentionStickyFrontier;
+    /** Plan 074 P3: bounded frontier snapshot for durable checkpoints (undefined before any mutation). */
+    serializedAttentionSticky(): PersistedAttentionStickyFrontier | undefined;
+    /** Plan 074 P3: restore a frontier that was validated when the checkpoint was loaded. */
+    restoreAttentionSticky(persisted: PersistedAttentionStickyFrontier): void;
     invalidateSnapshot(): void;
     resolveRunProvider(options: RunOptions): void;
     emit(event: AgentEvent): void;

package/dist/agent-session/session.d.ts

@@ -1,6 +1,7 @@
 /** session (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
 import { ActiveDurableRun } from "../agent-approval.js";
 import type { PendingToolCall, StoredAgentRunState } from "../agent-run-state.js";
+import { type AttentionStickyFrontier, type PersistedAttentionStickyFrontier } from "../attention-compiler.js";
 import type { Agent, AgentEvent, AgentRunResult, AgentRunState, AgentRunStateOptions, AgentSession, AgentSessionConfig, AIProvider, CompactionOptions, CompactionResult, ErrorInfo, Message, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunDecision, RunOptions, SessionEntry, Skill, SteerOptions, SubscribeOptions, ToolDefinition, ToolEffectStore, Usage } from "../contracts.js";
 import type { AgentIdentity } from "../identity.js";
 import type { AgentInput } from "../input.js";
@@ -48,6 +49,19 @@ export declare class RuntimeAgentSession implements AgentSession {
     restoredSkillBodies: readonly LoadedSkillBodiesEntry[];
     /** Skills of the current run (for the bodies snapshot); replaced at each run start. */
     activeRunSkills: readonly import("../contracts.js").Skill[];
+    /** Per-run tool allow-list (Task 21); undefined means the full registered set. */
+    activeToolNames?: readonly string[];
+    /** Sticky frontier for this session (plan 074 C10); created on first use, so a session whose
+     *  agents never enable the compiler allocates nothing. Mutations stay applied once made, so a
+     *  later under-ratio turn re-applies them instead of rewriting the prompt-cache prefix. */
+    private attentionSticky?;
+    attentionStickyFor(): AttentionStickyFrontier;
+    /** Plan 074 P3: bounded snapshot for a durable checkpoint; `undefined` when the session never
+     *  mutated anything, so a compiler-off (or never-over-ratio) session persists nothing extra. */
+    serializedAttentionSticky(): PersistedAttentionStickyFrontier | undefined;
+    /** Plan 074 P3: restore a frontier validated at checkpoint load, so a resumed run keeps its
+     *  stubs instead of re-deciding its first turn from the ratio. */
+    restoreAttentionSticky(persisted: PersistedAttentionStickyFrontier): void;
     /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
     restoreLoadedSkills(names: readonly string[]): void;
     /** Plan 041: re-add persisted activated-tool names (names only; inert for absent tools). */

package/dist/agent-session/session.js

@@ -1,7 +1,9 @@
 /** session (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
 import { policyList } from "../agent-tool-dispatch.js";
+import { createAttentionStickyFrontier, resolveInputCap, restoreAttentionStickyFrontier, serializeAttentionStickyFrontier, } from "../attention-compiler.js";
 import { createDefaultCompactionStrategy, isCompactionEntryData } from "../compaction.js";
-import { DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_SNAPSHOT_CACHE_TTL_MS, HARD_MAX_SNAPSHOT_CACHE_TTL_MS, } from "../contracts.js";
+import { estimateAssemblyTokens, estimateTextTokens } from "../context-budget.js";
+import { DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_SNAPSHOT_CACHE_TTL_MS, HARD_MAX_SNAPSHOT_CACHE_TTL_MS, resolveShouldCompact, } from "../contracts.js";
 import { GuardrailError, runGuardrails } from "../guardrails.js";
 import { applyDefaultProviderRequestOptions, createProviderRequestPolicyChain, normalizeProviderRequestPolicyResult, } from "../provider-request-policy.js";
 import { redactAgentEvent, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry } from "../redaction.js";
@@ -53,6 +55,28 @@ export class RuntimeAgentSession {
     restoredSkillBodies = [];
     /** Skills of the current run (for the bodies snapshot); replaced at each run start. */
     activeRunSkills = [];
+    /** Per-run tool allow-list (Task 21); undefined means the full registered set. */
+    activeToolNames;
+    /** Sticky frontier for this session (plan 074 C10); created on first use, so a session whose
+     *  agents never enable the compiler allocates nothing. Mutations stay applied once made, so a
+     *  later under-ratio turn re-applies them instead of rewriting the prompt-cache prefix. */
+    attentionSticky;
+    attentionStickyFor() {
+        this.attentionSticky ??= createAttentionStickyFrontier();
+        return this.attentionSticky;
+    }
+    /** Plan 074 P3: bounded snapshot for a durable checkpoint; `undefined` when the session never
+     *  mutated anything, so a compiler-off (or never-over-ratio) session persists nothing extra. */
+    serializedAttentionSticky() {
+        return this.attentionSticky && this.attentionSticky.thinking.size + this.attentionSticky.toolCallIds.size > 0
+            ? serializeAttentionStickyFrontier(this.attentionSticky)
+            : undefined;
+    }
+    /** Plan 074 P3: restore a frontier validated at checkpoint load, so a resumed run keeps its
+     *  stubs instead of re-deciding its first turn from the ratio. */
+    restoreAttentionSticky(persisted) {
+        this.attentionSticky = restoreAttentionStickyFrontier(persisted);
+    }
     /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
     restoreLoadedSkills(names) {
         for (const name of names)
@@ -393,10 +417,23 @@ export class RuntimeAgentSession {
     }
     async autoCompact(runId, options, signal, inputMessages) {
         const compaction = mergeCompaction(this.agent.config.compaction, options.compaction);
-        if (!compaction || compaction.thresholdEntries === undefined)
+        if (!compaction || (compaction.trigger === undefined && compaction.thresholdEntries === undefined))
             return;
         const snapshot = await this.snapshot();
-        if (snapshot.entries.length <= compaction.thresholdEntries || snapshot.entries.at(-1)?.kind === "compaction")
+        // A branch that just compacted keeps its fresh summary: no second pass over the same entries.
+        if (snapshot.entries.at(-1)?.kind === "compaction")
+            return;
+        const shouldCompact = await resolveShouldCompact({ trigger: compaction.trigger, thresholdEntries: compaction.thresholdEntries }, {
+            sessionId: this.id,
+            entryCount: snapshot.entries.length,
+            // Estimates of the branch the run is about to send: messages plus carried summaries.
+            estimateInputTokens: () => estimateAssemblyTokens(snapshot.messages) + snapshot.summaries.reduce((sum, summary) => sum + estimateTextTokens(summary), 0),
+            // Same cap helper the attention compiler resolves its `inputCap` with.
+            resolveInputCapTokens: () => resolveInputCap(undefined, options.model ?? this.agent.config.model),
+            metadata: compaction.metadata,
+            signal,
+        });
+        if (!shouldCompact)
             return;
         await this.compactBranch(compaction, runId, signal, "auto");
         const compacted = await this.snapshot();

package/dist/artifacts.d.ts

@@ -8,12 +8,26 @@ import type { OwnershipScope } from "./contracts.js";
 export type ArtifactApprovalState = "pending" | "approved" | "rejected";
 /** A resolved decision on one revision (pending is the absence of a decision). */
 export type ArtifactDecisionState = Exclude<ArtifactApprovalState, "pending">;
+/** Optional host semantic verdict. Never treated as citation integrity or proof. */
+export type CitationSupport = "unverified" | "supported" | "unsupported" | "uncertain";
 /** Bounded citation / data-source reference. Host resolves the body; Prism stores the ref only. */
 export interface ArtifactCitation {
     readonly uri: string;
     readonly title?: string;
-    /** Data-source kind (e.g. "web", "database", "upload"); host-defined, bounded. */
+    /** Data-source kind (e.g. "web", "database", "upload", "rag"); host-defined, bounded. */
     readonly kind?: string;
+    readonly sourceId?: string;
+    readonly revision?: string;
+    /** SHA-256 hex of the retrieved source snapshot (optional `sha256:` prefix). */
+    readonly contentHash?: string;
+    readonly retrievedAt?: string;
+    readonly excerpt?: string;
+    readonly span?: {
+        readonly start: number;
+        readonly end: number;
+    };
+    readonly tenantId?: string;
+    readonly support?: CitationSupport;
 }
 /** One immutable revision of an artifact. `uri`/`hash` reference host-owned content. */
 export interface ArtifactRevision {
@@ -43,6 +57,8 @@ export interface ArtifactApproval {
     /** Change-request / rejection note. */
     readonly note?: string;
     readonly decidedAt: string;
+    /** SHA-256 of bound citation sourceId/revision/contentHash tuples at decision time. */
+    readonly evidenceDigest?: string;
 }
 /**
  * Durable artifact record. Stored as a versioned checkpoint value; the checkpoint version
@@ -130,3 +146,25 @@ export declare class ArtifactError extends Error {
 export declare function artifactCheckpointKey(threadId: string, artifactId: string): string;
 /** Current review state: the decision on the latest revision, or pending when undecided. */
 export declare function artifactApprovalState(record: ArtifactRecord): ArtifactApprovalState;
+export declare const HARD_CITATION_EXCERPT_BYTES = 8192;
+export type CitationIntegrityReason = "ok" | "missing_source" | "hash_mismatch" | "span_mismatch" | "revoked_acl" | "revision_changed" | "excerpt_too_large" | "cross_tenant";
+export interface CitationLiveSource {
+    readonly contentHash: string;
+    readonly revision: string;
+    readonly body?: string;
+    readonly tenantId?: string;
+    readonly authorized?: boolean;
+}
+export interface CitationIntegrityResult {
+    readonly ok: boolean;
+    readonly reason: CitationIntegrityReason;
+}
+/** Deterministic source existence / hash / span / ACL check. Ignores `support`. */
+export declare function checkCitationIntegrity(citation: ArtifactCitation, live?: CitationLiveSource, options?: {
+    readonly boundRevision?: string;
+    readonly maxExcerptBytes?: number;
+}): CitationIntegrityResult;
+/** Stable digest of citation identity tuples. Source body changes after approval fail this digest only when citations themselves change; live hash is `checkCitationIntegrity`. */
+export declare function citationBindingDigest(citations: readonly ArtifactCitation[] | undefined): string;
+/** True when the approval digest still matches the revision and (if given) live sources pass integrity. */
+export declare function approvalEvidenceIntact(approval: ArtifactApproval, revision: ArtifactRevision, liveSources?: Readonly<Record<string, CitationLiveSource>>): CitationIntegrityResult;

package/dist/artifacts.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 /** Well-known error codes for ArtifactBodyStore failures. */
 export const ARTIFACT_BODY_ERROR_CODES = {
     OWNERSHIP: "ERR_PRISM_ARTIFACT_BODY_OWNERSHIP",
@@ -41,4 +42,76 @@ export function artifactApprovalState(record) {
     const decision = record.approvals.find((approval) => approval.version === latest.version);
     return decision?.state ?? "pending";
 }
+export const HARD_CITATION_EXCERPT_BYTES = 8192;
+function normalizeCitationHash(value) {
+    const raw = value.startsWith("sha256:") ? value.slice("sha256:".length) : value;
+    return raw.trim().toLowerCase();
+}
+/** Deterministic source existence / hash / span / ACL check. Ignores `support`. */
+export function checkCitationIntegrity(citation, live, options) {
+    const maxExcerpt = options?.maxExcerptBytes ?? HARD_CITATION_EXCERPT_BYTES;
+    if (citation.excerpt !== undefined && Buffer.byteLength(citation.excerpt, "utf8") > maxExcerpt) {
+        return { ok: false, reason: "excerpt_too_large" };
+    }
+    if (!live)
+        return { ok: false, reason: "missing_source" };
+    if (live.authorized === false)
+        return { ok: false, reason: "revoked_acl" };
+    if (citation.tenantId && live.tenantId && citation.tenantId !== live.tenantId) {
+        return { ok: false, reason: "cross_tenant" };
+    }
+    if (!citation.contentHash)
+        return { ok: false, reason: "missing_source" };
+    if (normalizeCitationHash(citation.contentHash) !== normalizeCitationHash(live.contentHash)) {
+        return { ok: false, reason: "hash_mismatch" };
+    }
+    if (citation.revision !== undefined && citation.revision !== live.revision) {
+        return { ok: false, reason: "revision_changed" };
+    }
+    if (options?.boundRevision !== undefined && options.boundRevision !== live.revision) {
+        return { ok: false, reason: "revision_changed" };
+    }
+    if (citation.span) {
+        const { start, end } = citation.span;
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end <= start) {
+            return { ok: false, reason: "span_mismatch" };
+        }
+        if (live.body !== undefined) {
+            const sliced = live.body.slice(start, end);
+            if (citation.excerpt !== undefined && sliced !== citation.excerpt) {
+                return { ok: false, reason: "span_mismatch" };
+            }
+        }
+    }
+    else if (citation.excerpt !== undefined && live.body !== undefined && citation.excerpt !== live.body) {
+        return { ok: false, reason: "span_mismatch" };
+    }
+    return { ok: true, reason: "ok" };
+}
+/** Stable digest of citation identity tuples. Source body changes after approval fail this digest only when citations themselves change; live hash is `checkCitationIntegrity`. */
+export function citationBindingDigest(citations) {
+    const rows = (citations ?? [])
+        .map((citation) => `${citation.sourceId ?? ""}|${citation.revision ?? ""}|${citation.contentHash ? normalizeCitationHash(citation.contentHash) : ""}`)
+        .sort();
+    return createHash("sha256").update(JSON.stringify(rows)).digest("hex");
+}
+/** True when the approval digest still matches the revision and (if given) live sources pass integrity. */
+export function approvalEvidenceIntact(approval, revision, liveSources) {
+    if (approval.evidenceDigest !== undefined && approval.evidenceDigest !== citationBindingDigest(revision.citations)) {
+        return { ok: false, reason: "revision_changed" };
+    }
+    if (liveSources === undefined)
+        return { ok: true, reason: "ok" };
+    for (const citation of revision.citations ?? []) {
+        if (!citation.sourceId && !citation.contentHash)
+            continue;
+        const live = citation.sourceId ? liveSources[citation.sourceId] : undefined;
+        const result = checkCitationIntegrity(citation, live, {
+            ...(citation.revision === undefined ? {} : { boundRevision: citation.revision }),
+        });
+        if (!result.ok)
+            return result;
+    }
+    return { ok: true, reason: "ok" };
+}
 //# sourceMappingURL=artifacts.js.map