@arnilo/prism 0.0.18 → 0.0.20

package/dist/skill-load.js

@@ -0,0 +1,112 @@
+import { estimateTextBytes } from "./context-budget.js";
+import { HARD_MAX_SKILL_INSTRUCTION_BYTES } from "./skill-disclosure.js";
+export const DEFAULT_LOAD_SKILL_TOOL_NAME = "load_skill";
+export const SKILL_LOAD_ERROR_CODE = "skill_load_failed";
+export const MAX_LOAD_SKILL_RESULT_BYTES = 512;
+export class SkillLoadError extends Error {
+    code = SKILL_LOAD_ERROR_CODE;
+    constructor(message) {
+        super(message);
+        this.name = "SkillLoadError";
+    }
+}
+export function isSkillLoadError(error) {
+    return error instanceof Error && error.code === SKILL_LOAD_ERROR_CODE;
+}
+export function resolveSkillLoad(options) {
+    const name = options.name.trim();
+    if (!name)
+        throw new SkillLoadError("Skill name is required");
+    let skill;
+    try {
+        skill = options.registry.resolve(name);
+    }
+    catch {
+        throw new SkillLoadError(`Unknown skill: ${name}`);
+    }
+    if (options.activeSkillNames && !options.activeSkillNames.includes(skill.name)) {
+        throw new SkillLoadError(`Skill ${skill.name} is not active for this run`);
+    }
+    const toolNames = new Set((options.tools ?? []).map((tool) => tool.name));
+    const missingTool = skill.toolNames?.find((toolName) => !toolNames.has(toolName));
+    if (missingTool)
+        throw new SkillLoadError(`Skill ${skill.name} requires inactive tool: ${missingTool}`);
+    if (!skill.instructions?.trim())
+        throw new SkillLoadError(`Skill ${skill.name} has no instructions to load`);
+    const bytes = estimateTextBytes(skill.instructions);
+    if (bytes > HARD_MAX_SKILL_INSTRUCTION_BYTES) {
+        throw new SkillLoadError(`Skill ${skill.name} instructions exceed hard cap (${HARD_MAX_SKILL_INSTRUCTION_BYTES} bytes)`);
+    }
+    if (options.loaded?.has(skill.name))
+        throw new SkillLoadError(`Skill ${skill.name} is already loaded`);
+    return skill;
+}
+function skillLoadMetadata(context) {
+    const metadata = context.metadata;
+    if (!metadata || typeof metadata !== "object")
+        return undefined;
+    return metadata;
+}
+function capLoadSkillText(text) {
+    const bytes = estimateTextBytes(text);
+    if (bytes <= MAX_LOAD_SKILL_RESULT_BYTES)
+        return text;
+    const suffix = "…";
+    let end = MAX_LOAD_SKILL_RESULT_BYTES - new TextEncoder().encode(suffix).length;
+    const encoded = new TextEncoder().encode(text);
+    while (end > 0 && (encoded[end] & 0xc0) === 0x80)
+        end--;
+    return new TextDecoder().decode(encoded.slice(0, end)) + suffix;
+}
+export function createLoadSkillTool(options) {
+    const toolName = options.name ?? DEFAULT_LOAD_SKILL_TOOL_NAME;
+    return {
+        name: toolName,
+        description: "Load the full instructions for an active skill by exact name.",
+        parameters: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Exact skill name from the catalog." },
+            },
+            required: ["name"],
+        },
+        execute(args, context) {
+            const fail = (reason, text) => {
+                const bounded = capLoadSkillText(text);
+                return {
+                    toolCallId: context.toolCallId,
+                    name: toolName,
+                    value: { ok: false, reason, text: bounded },
+                    content: [{ type: "text", text: bounded }],
+                };
+            };
+            const name = typeof args.name === "string" ? args.name : "";
+            const metadata = skillLoadMetadata(context);
+            const loaded = metadata?.loadedSkills ?? options.loaded;
+            if (!loaded)
+                return fail("no_loaded_set", "Skill load state is unavailable for this session.");
+            try {
+                const skill = resolveSkillLoad({
+                    registry: options.registry,
+                    name,
+                    tools: metadata?.activeTools ?? options.tools,
+                    loaded,
+                    activeSkillNames: metadata?.activeSkillNames,
+                });
+                loaded.add(skill.name);
+                const text = capLoadSkillText(`Loaded skill ${skill.name} for this session.`);
+                return {
+                    toolCallId: context.toolCallId,
+                    name: toolName,
+                    value: { ok: true, name: skill.name, text },
+                    content: [{ type: "text", text }],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "Skill load failed";
+                return fail("skill_load_failed", message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=skill-load.js.map

package/dist/tool-result-fold.d.ts

@@ -0,0 +1,40 @@
+import type { Message, ToolResult } from "./contracts.js";
+export declare const DEFAULT_TOOL_RESULT_FOLD_MIN_AGE_TURNS = 2;
+export declare const DEFAULT_TOOL_RESULT_FOLD_MIN_BYTES = 4096;
+export declare const DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES = 512;
+export declare const HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES = 4096;
+export declare const TOOL_RESULT_FOLD_TURN_METADATA_KEY: "prismToolResultTurn";
+export interface ToolResultFoldInput {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly text: string;
+}
+export interface ToolResultFoldOptions {
+    readonly minAgeTurns?: number;
+    readonly minBytes?: number;
+    readonly maxSummaryBytes?: number;
+    readonly summarize: (input: ToolResultFoldInput) => Promise<string> | string;
+}
+export interface ResolvedToolResultFoldOptions {
+    readonly minAgeTurns: number;
+    readonly minBytes: number;
+    readonly maxSummaryBytes: number;
+    readonly summarize: (input: ToolResultFoldInput) => Promise<string> | string;
+}
+export interface FoldToolResultsContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly signal?: AbortSignal;
+}
+/** Run overrides agent; disabled when neither supplies `summarize`. */
+export declare function resolveToolResultFold(run?: ToolResultFoldOptions, agent?: ToolResultFoldOptions): ResolvedToolResultFoldOptions | undefined;
+/** Projection-only fold for history tool messages; does not mutate the input array. */
+export declare function foldToolResultHistory(history: readonly Message[], options: ResolvedToolResultFoldOptions, context: FoldToolResultsContext): Promise<readonly Message[]>;
+/** Projection-only fold for in-flight tool results before message conversion. */
+export declare function foldToolResults(results: readonly ToolResult[], options: ResolvedToolResultFoldOptions, context: FoldToolResultsContext): Promise<readonly ToolResult[]>;
+export declare function formatFoldedToolResult(summary: string): string;
+export declare function foldedToolResultHeader(toolName: string, toolCallId: string, summary: string): string;

package/dist/tool-result-fold.js

@@ -0,0 +1,164 @@
+import { estimateTextBytes } from "./context-budget.js";
+export const DEFAULT_TOOL_RESULT_FOLD_MIN_AGE_TURNS = 2;
+export const DEFAULT_TOOL_RESULT_FOLD_MIN_BYTES = 4_096;
+export const DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES = 512;
+export const HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES = 4_096;
+export const TOOL_RESULT_FOLD_TURN_METADATA_KEY = "prismToolResultTurn";
+/** Run overrides agent; disabled when neither supplies `summarize`. */
+export function resolveToolResultFold(run, agent) {
+    const options = run ?? agent;
+    if (!options?.summarize)
+        return undefined;
+    const minAgeTurns = options.minAgeTurns ?? DEFAULT_TOOL_RESULT_FOLD_MIN_AGE_TURNS;
+    const minBytes = options.minBytes ?? DEFAULT_TOOL_RESULT_FOLD_MIN_BYTES;
+    const maxSummaryBytes = options.maxSummaryBytes ?? DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES;
+    assertPositiveInt(minAgeTurns, "minAgeTurns", 1, 1_024);
+    assertPositiveInt(minBytes, "minBytes", 1, 32 * 1024 * 1024);
+    assertPositiveInt(maxSummaryBytes, "maxSummaryBytes", 1, HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES);
+    return { minAgeTurns, minBytes, maxSummaryBytes, summarize: options.summarize };
+}
+/** Projection-only fold for history tool messages; does not mutate the input array. */
+export async function foldToolResultHistory(history, options, context) {
+    if (history.length === 0)
+        return history;
+    const turns = inferToolResultTurns(history);
+    const out = [];
+    for (let index = 0; index < history.length; index += 1) {
+        const message = history[index];
+        const folded = await foldToolResultMessage(message, options, {
+            ...context,
+            toolResultTurn: turns[index] ?? context.turn,
+        });
+        out.push(folded);
+    }
+    return out;
+}
+/** Projection-only fold for in-flight tool results before message conversion. */
+export async function foldToolResults(results, options, context) {
+    if (results.length === 0)
+        return results;
+    const out = [];
+    for (const result of results) {
+        const folded = await foldToolResultValue(result, options, { ...context, toolResultTurn: context.turn });
+        out.push(folded);
+    }
+    return out;
+}
+async function foldToolResultMessage(message, options, context) {
+    if (message.role !== "tool")
+        return message;
+    const block = message.content.find((part) => part.type === "tool_result");
+    if (!block || block.type !== "tool_result")
+        return message;
+    const text = toolResultText(block.result, block.error, message.content);
+    const folded = await maybeFold({
+        options,
+        context,
+        toolCallId: block.toolCallId,
+        toolName: block.name,
+        text,
+        apply: (summary) => ({
+            ...message,
+            content: message.content.map((part) => part.type === "tool_result"
+                ? { ...part, result: foldedToolResultHeader(block.name, block.toolCallId, summary), error: undefined }
+                : part),
+            metadata: { ...message.metadata, prismFolded: true },
+        }),
+    });
+    return folded ?? message;
+}
+async function foldToolResultValue(result, options, context) {
+    const text = toolResultText(result.value, result.error, result.content);
+    const folded = await maybeFold({
+        options,
+        context,
+        toolCallId: result.toolCallId,
+        toolName: result.name,
+        text,
+        apply: (summary) => ({
+            ...result,
+            value: foldedToolResultHeader(result.name, result.toolCallId, summary),
+            error: undefined,
+            metadata: { ...result.metadata, prismFolded: true },
+        }),
+    });
+    return folded ?? result;
+}
+async function maybeFold(input) {
+    const age = input.context.turn - input.context.toolResultTurn;
+    if (age < input.options.minAgeTurns)
+        return undefined;
+    if (estimateTextBytes(input.text) < input.options.minBytes)
+        return undefined;
+    throwIfAborted(input.context.signal);
+    try {
+        const summary = await input.options.summarize({
+            sessionId: input.context.sessionId,
+            runId: input.context.runId,
+            turn: input.context.toolResultTurn,
+            toolCallId: input.toolCallId,
+            toolName: input.toolName,
+            text: input.text,
+        });
+        return input.apply(capSummaryBytes(String(summary), input.options.maxSummaryBytes));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function formatFoldedToolResult(summary) {
+    return summary;
+}
+export function foldedToolResultHeader(toolName, toolCallId, summary) {
+    return `Tool result ${toolName} [${toolCallId}]: ${summary}`;
+}
+function toolResultText(result, error, extra) {
+    const parts = [JSON.stringify(error ?? result ?? null)];
+    for (const block of extra ?? []) {
+        if (block.type === "text" && "text" in block && typeof block.text === "string")
+            parts.push(block.text);
+    }
+    return parts.join("\n");
+}
+function capSummaryBytes(summary, maxBytes) {
+    const bytes = estimateTextBytes(summary);
+    if (bytes <= maxBytes)
+        return summary;
+    const encoded = new TextEncoder().encode(summary);
+    const suffix = new TextEncoder().encode("…");
+    let end = Math.max(0, maxBytes - suffix.length);
+    while (end > 0 && (encoded[end] & 0xc0) === 0x80)
+        end--;
+    return new TextDecoder().decode(encoded.slice(0, end)) + "…";
+}
+function inferToolResultTurns(history) {
+    const turns = new Array(history.length).fill(1);
+    let providerTurn = 0;
+    let toolTurn = 1;
+    for (let index = 0; index < history.length; index += 1) {
+        const message = history[index];
+        const stamped = readToolResultTurn(message.metadata);
+        if (message.role === "assistant") {
+            providerTurn += 1;
+            toolTurn = providerTurn;
+        }
+        if (message.role === "tool") {
+            turns[index] = stamped ?? toolTurn;
+        }
+    }
+    return turns;
+}
+function readToolResultTurn(metadata) {
+    const value = metadata?.[TOOL_RESULT_FOLD_TURN_METADATA_KEY];
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+function assertPositiveInt(value, name, min, max) {
+    if (!Number.isSafeInteger(value) || value < min || value > max) {
+        throw new TypeError(`toolResultFold.${name} must be a safe integer from ${min} to ${max}`);
+    }
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason instanceof Error ? signal.reason : new Error("Tool result fold aborted");
+}
+//# sourceMappingURL=tool-result-fold.js.map

package/docs/0.1.0-readiness.md

@@ -1,12 +1,12 @@
 # 0.1.0 / 1.0 Readiness Gates
 
-Status: **0.0.18** is the current release line (Phase 1 restore integrity); **1.0** readiness remains operator-gated, not automatic.
+Status: **0.0.20** is the current release line (Phase 3 skills progressive disclosure); **1.0** readiness remains operator-gated, not automatic.
 
 This page distills runnable readiness gates into one command-per-gate table. The
 **Last evidence** column records the 2026-07-26 **0.0.16** baseline snapshot
 (Phase 11, Node v24.18.0, Linux x86_64). Treat it as historical floor evidence,
 not the current release tag. Re-run each gate on the target release tree before
-cutting 0.0.18 / 1.0. The decision to cut 1.0 stays with the operator after
+cutting 0.0.19 / 1.0. The decision to cut 1.0 stays with the operator after
 operator-gated legs run in a protected environment and Phase 12 demand evidence
 exists.
 
@@ -14,13 +14,13 @@ Evidence trail: [`docs/review-coverage-2026-07-26-phase-11.md`](./review-coverag
 (addenda 0–9), [`docs/release-and-install.md`](./release-and-install.md),
 [`docs/migration.md`](./migration.md), [`docs/performance.md`](./performance.md).
 
-## Current line (0.0.18)
+## Current line (0.0.20)
 
 | Item | Status |
 |---|---|
-| Published graph | **44** publishable manifests at **0.0.18** (`docs/release-and-install.md`) |
-| Phase 1 integrity | `repo_search` literal-only, atomic write/edit, `cache_aware` default layout, oldest-first history eviction, MCP SDK 1.30.0, README/readiness alignment |
-| Docs tripwires | `node --test dist/__tests__/docs.test.js` — migration section `0.0.17 → 0.0.18` documents intentional breaks |
+| Published graph | **44** publishable manifests at **0.0.20** (`docs/release-and-install.md`) |
+| Phase 3 progressive disclosure | `skillsDisclosure`, `load_skill`, empty registry default + `activateAllSkills`, priority budget demotion, optional `toolResultFold` |
+| Docs tripwires | `node --test dist/__tests__/docs.test.js` — migration section `0.0.19 → 0.0.20 skills and context progressive disclosure` documents intentional breaks |
 | Readiness table below | **0.0.16 measured values** — refresh evidence columns when 1.0 RC gates are recorded |
 
 ## Gate table
@@ -63,7 +63,9 @@ signatures can drift on a TypeScript bump without any real API change).
 
 `docs/migration.md` carries release migration sections tripwired by
 `docs.test.ts` (headings and key phrases). A missing or gutted section fails
-the suite. **0.0.18** adds intentional pre-1.0 breaks (`repo_search` literal-only,
+the suite. **0.0.19** adds observational-memory lifecycle and nested settings in
+`@arnilo/prism-compaction-observational-memory` — see `0.0.18 → 0.0.19 observational memory lifecycle`.
+**0.0.18** adds intentional pre-1.0 breaks (`repo_search` literal-only,
 `cache_aware` default layout, oldest-first history eviction, atomic write/edit
 durability, MCP SDK bump) — see `0.0.17 → 0.0.18 restore integrity`.
 
@@ -133,7 +135,7 @@ Exact prerequisites that must be satisfied before cutting 1.0:
    checked-in baseline.
 7. **Phase 12 demand evidence** (below) recorded for any capability that 1.0
    is expected to anchor.
-8. **0.0.18+ integrity gates green** on the release candidate (docs suite,
+8. **0.0.19+ lifecycle gates green** on the release candidate (docs suite,
    MCP SDK advisory cleared, coding-tool durability fixes, layout/eviction defaults).
 
 ## Phase 12 demand-evidence entry criteria

package/docs/agent-session-runtime.md

@@ -51,6 +51,8 @@ string | Message | readonly Message[]
 
 `RunOptions.model` can override the request model for a run. Model overrides append a `model_change` entry. `AgentConfig.inputLayout` selects the default input assembly layout (`"cache_aware"` by default, or opt-in `"legacy"`); `RunOptions.inputLayout` wins for one run. `AgentConfig.providerOptions`/`RunOptions.providerOptions` supply generic provider request options; `timeoutMs`, `maxRetries`, and `maxRetryDelayMs` are deprecated inert provider-level hints in first-party providers. Use `RunOptions.signal`/host abort controllers for timeouts and `AgentConfig.retry`/`RunOptions.retry` for retry. `AgentConfig.providerRequestPolicies`/`RunOptions.providerRequestPolicies` run before `AIProvider.generate()` and before `provider_request` middleware. `AgentConfig.systemPrompt` and `RunOptions.systemPrompt` add explicit layered system prompt contributions; `RunOptions.systemPrompt: false` disables configured prompt layers for that run while keeping `AgentConfig.instructions` as the base path. `RunOptions.compaction` can enable auto-compaction for that run or use `false` to disable configured auto-compaction. `RunOptions.retry` can enable provider-turn retry for that run or use `false` to disable configured retry. `RunOptions.metadata` is merged with agent/session metadata for assembly, provider requests, and tool contexts. Deprecated `RunOptions.maxToolRounds` narrows `limits.maxToolRounds`. `RunOptions.signal` is bridged into the per-run abort signal passed to assembly, providers, tools, auto-compaction, and retry backoff.
 
+`RunOptions.activeSkills` selects named skills from a configured `SkillRegistry`; `RunOptions.skills` replaces a plain `Skill[]` config for one run. When `AgentConfig.skills` is a registry and neither is set, **no skills activate** unless `activateAllSkills: true` (run or agent). `skillsDisclosure` (`"progressive"` default, `"eager"` opt-in; run wins) controls catalog vs full instruction bodies; the session-owned `LoadedSkillSet` is populated by `load_skill` when the host registers `createLoadSkillTool`. `toolResultFold` (off unless the host supplies `summarize`) optionally folds aged large tool results in provider input only. See [Context and skills](context-and-skills.md).
+
 ## Outputs / response / events
 
 `session.run()` / `session.prompt()` resolve to an `AgentRunResult` with `sessionId`, `runId`, `status`, `text`, `content`, optional `message`/`usage`/`leafId`, and terminal `error`/`abortReason` when applicable. Callers may ignore the return value. Failed and aborted runs still emit their terminal events, then reject with `AgentRunError` whose `.result` carries the same shape.

package/docs/compaction-observational-memory.md

@@ -8,6 +8,21 @@ Current status: ledger/projection/render/recall utilities, explicit worker runti
 
 This package is distinct from `@arnilo/prism-memory` working/semantic memory: observational memory compresses and recalls source-backed observations/reflections; semantic memory retrieves embeddings; working memory stores the current structured profile/state. Hosts may compose both.
 
+## Four-layer provider context
+
+Observational memory composes four independent layers for long sessions (Mastra-style):
+
+| Layer | What it holds | How it is produced |
+| --- | --- | --- |
+| **Recent exact messages** | Last `context.recentMessages` user/assistant/tool entries in branch order (optional `recentMessageMaxTokens` trim, oldest first) | `buildObservationalMemoryContextBlocks()` → `recent-messages` ContextBlock; aligned with compaction `keepRecentEntries` |
+| **Observation log** | Source-backed facts with 12-hex ids and `sourceEntryIds` | Observer worker on eligible unscanned `message` entries after `observation.messageTokens`; coverage advances even on empty passes |
+| **Reflections** | Higher-level summaries over observation ids | Reflector worker on observations after last reflection coverage when `reflection.observationTokens` met |
+| **Raw-source retrieval** | Exact branch messages behind a memory id or cursor page | `recallObservationalMemory()` / `recallObservationalMemoryBranchPage()` / `createRecallMemoryTool()` — exact-id or cursor paging only; no semantic search |
+
+Activation is explicit: `createObservationalMemory().attach()` coordinates post-run observe/reflect/drop and `context.compactAfterTokens` compaction. Import and extension `setup` start nothing. Recall, commands, and utilities fail closed on invalid ids, wrong `sessionId`, ambiguous tool input, or oversized pages. Pass `secrets` for exact-value redaction in render/recall/worker paths. Branch isolation: hosts supply current-branch `appendEntry` and `getEntries`; mismatched store/session pairs fail closed after append.
+
+See `examples/observational-memory-lifecycle.ts` for attach → turn → projection/recall/page without live credentials.
+
 ## When to use it
 
 Use it when a host wants to opt in to long-session memory that records observations/reflections as session custom entries, renders prepared memory during compaction, and supports exact-id recall.
@@ -20,7 +35,7 @@ Memory records use `SessionEntry.kind: "custom"` with `entry.data.type` markers:
 
 | Type | Payload |
 | --- | --- |
-| `om.observations.recorded` | `{ observations, coversUpToId? }` |
+| `om.observations.recorded` | `{ observations, coversUpToId? }` — successful observer runs append coverage even when `observations` is empty. |
 | `om.reflections.recorded` | `{ reflections, coversUpToId? }` |
 | `om.observations.dropped` | `{ observationIds, coversUpToId? }` |
 | `om.folded` | Compaction `data.memory` folded details. |
@@ -38,6 +53,10 @@ Worker limits are finite positive safe integers:
 | `maxWorkerResultBytes` | 64 KiB | 1 MiB | Full tool result and replayed value/error payload |
 | `maxWorkerMessageBytes` | 1 MiB | 8 MiB | System/prompt plus assistant-call/tool-result transcript |
 | `maxWorkerErrorBytes` | 1 KiB | 8 KiB | Provider/tool/runtime error text after exact known-secret redaction |
+| Rendered memory projection | — | 256 KiB | `renderObservationalMemory()` / context block text |
+| Folded compaction payload | — | 512 KiB | `data.memory` JSON; strategy trims lowest-relevance observations before failing |
+| Recent-message window | — | 512 KiB | `renderRecentMessageWindow()` hard cap |
+| Recall page size | 20 | 100 | `retrieval.pageLimit` / recall tool `limit` |
 
 Direct `runObserver()` / `runReflector()` / `runDropper()` calls retain required `maxTurns` and accept the corresponding shorter worker fields (`maxToolCalls`, `maxResultBytes`, etc.). Named default/hard constants and `resolveMemoryWorkerLimits()` are exported.
 
@@ -48,20 +67,26 @@ Key exports:
 | Export | Purpose |
 | --- | --- |
 | `foldObservationalMemoryLedger()` | Fold custom memory entries into observations, reflections, drops, and coverage markers. |
+| `isEligibleObservationSourceEntry()` / `eligibleObservationSources()` | Select user/assistant/tool `message` entries for observer input. |
+| `unscannedEntries()` / `observationsUncoveredByReflection()` | Dual coverage helpers for observation scan and reflection windows. |
 | `buildObservationalMemoryProjection()` | Build active/full/folded projections from current branch entries. |
+| `buildObservationalMemoryContextBlocks()` | Render observational-memory + recent-messages context blocks for provider input. |
+| `selectRecentMessageEntries()` / `renderRecentMessageWindow()` | Bounded exact recent-message suffix; count via `keepRecentEntries`, optional token trim via `estimateEntryTokens`. |
 | `createFoldedMemoryDetails()` | Create JSON details for compaction `data.memory`. |
 | `renderObservationalMemory()` | Render reflections and observations into a prepared memory summary. |
 | `recallObservationalMemory()` | Recover source evidence for a known observation/reflection id from supplied current-branch entries. |
+| `recallObservationalMemoryBranchPage()` | Page eligible user/assistant/tool messages around a cursor entry id (`forward`/`backward`, optional `detail: summary|full`). |
 | `createMemoryId()` / `isMemoryId()` | Create/check 12-character ids. |
 | `resolveObservationalMemorySettings()` | Merge `observational-memory` settings with defaults and overrides. |
-| `createObservationalMemoryRuntime()` | Explicitly run observer/reflector/dropper workers for a supplied session, owned append callback, and provider. |
+| `createObservationalMemory()` / `attach()` | One activation wires post-run observe/reflect/drop and `compactAfterTokens` compaction; returns proxied session, runtime, context provider, and strategy. |
+| `createObservationalMemoryRuntime()` | Low-level explicit flush for advanced hosts or tests. |
 | `createObservationalMemoryCompactionStrategy()` | Render existing folded memory as a standard Prism compaction summary with `data.memory`. |
 | `createObservationalMemoryExtension()` | Inert extension helper that registers the strategy contribution unless disabled. |
-| `createRecallMemoryTool()` | Optional exact-id `recall` tool factory backed by host-supplied current-branch entries. |
+| `createRecallMemoryTool()` | Optional `recall` tool factory: exact id lookup or current-branch message paging via host-supplied entries. |
 | `createMemoryStatusCommand()` / `createMemoryViewCommand()` | Optional `om:status` and `om:view` command factories. |
 | `createObservationalMemoryCommands()` | Convenience factory returning status and view commands. |
 
-Pure utilities create no events, workers, tools, commands, credentials, or provider requests. `createObservationalMemoryRuntime()` runs workers only when the host explicitly constructs it and calls `flush()`. The compaction strategy is O(n) over supplied entries and makes no provider call. Tool and command factories are inert until a host registers/selects them.
+Pure utilities create no events, workers, tools, commands, credentials, or provider requests. `createObservationalMemoryExtension()` and import alone start nothing. `createObservationalMemory().attach()` runs workers only after proxied `run`/`prompt`/`stream`/`compact` complete (or after `wrapResumeRun` / `wrapResumeStream`). `createObservationalMemoryRuntime().flush()` remains for manual/advanced use. Attached `contextProvider` renders two blocks each turn: `observational-memory` (active reflections/observations aligned to the recent-message boundary) and `recent-messages` (last `keepRecentEntries` message entries in branch order, optionally trimmed by `recentMessageMaxTokens` using `estimateEntryTokens`; oldest dropped first). Compaction uses the same `keepRecentEntries` setting. Observer input includes only eligible `message` entries (`user`, `assistant`, `tool`); memory/compaction/bookkeeping entries advance `coversUpToId` scan coverage without entering the observer prompt. Successful observer/reflector runs append coverage markers even when they record zero facts. Reflection uses only active observations recorded after the last `om.reflections.recorded` entry unless `flush({ fullReflectionRebuild: true })`. Attached `flush()` skips with `run_active` while a proxied run is in flight. The compaction strategy is O(n) over supplied entries and makes no provider call. Tool and command factories are inert until a host registers/selects them.
 
 ## Request/response example
 
@@ -74,6 +99,7 @@ Pure utilities create no events, workers, tools, commands, credentials, or provi
 ```ts
 import {
   buildObservationalMemoryProjection,
+  createObservationalMemory,
   createObservationalMemoryCompactionStrategy,
   createObservationalMemoryExtension,
   createObservationalMemoryCommands,
@@ -83,6 +109,18 @@ import {
   renderObservationalMemory,
 } from "@arnilo/prism-compaction-observational-memory";
 
+const om = createObservationalMemory({
+  observation: { provider: observerProvider, model: observerModel, messageTokens: 10_000 },
+  reflection: { provider: reflectorProvider, model: reflectorModel, observationTokens: 20_000 },
+  context: { compactAfterTokens: 81_000, recentMessages: 8 },
+  retrieval: { pageLimit: 20 },
+});
+const attached = om.attach(session, {
+  appendEntry: (entry, options) => store.append(entry, options),
+  sessionModel: agent.config.model,
+});
+await attached.session.run("Continue from prior work");
+
 const entries = await session.entries();
 const projection = buildObservationalMemoryProjection(entries);
 const summary = renderObservationalMemory(projection.reflections, projection.observations);
@@ -111,13 +149,19 @@ await kernel.load([createObservationalMemoryExtension({ recallTool: { getEntries
 
 ## Extension and configuration notes
 
-Settings are read from the `observational-memory` key only when a host calls `resolveObservationalMemorySettings()` or `runtime.flush()`. Defaults are `observeAfterTokens: 10000`, `reflectAfterTokens: 20000`, `compactAfterTokens: 81000`, `observationsPoolMaxTokens: 20000`, `observationsPoolTargetTokens: 10000`, `agentMaxTurns: 16`, `passive: false`, and `debugLog: false`. `agentMaxTurns` now rejects non-integer/non-finite/out-of-range input (hard 64) instead of flooring/falling back. Runtime `maxWorkerTurns` takes precedence.
+Settings resolve to nested `observation` / `reflection` / `dropper` / `context` / `retrieval` groups via `resolveObservationalMemorySettings()`. Defaults: `observation.messageTokens: 10000`, `reflection.observationTokens: 20000`, `context.compactAfterTokens: 81000`, `context.recentMessages: 8`, `context.observationsPoolMaxTokens: 20000`, `dropper.targetTokens: 10000` (from `context.observationsPoolTargetTokens`), `retrieval.pageLimit: 20`, `agentMaxTurns: 16`, `passive: false`, `debugLog: false`. Optional `context.recentMessageMaxTokens` trims the recent-message context window (oldest first) after the count limit.
+
+Legacy flat keys still map for pre-1.0 hosts (`observeAfterTokens` → `observation.messageTokens`, `reflectAfterTokens` → `reflection.observationTokens`, `compactAfterTokens` → `context.compactAfterTokens`, `keepRecentEntries` → `context.recentMessages`, flat `workerModel` → all workers when nested models absent). Conflicting flat+nested values throw.
+
+Observer/reflector/dropper may use separate providers, models, instructions, thinking levels, credentials, and `requireExplicitModel`. `dropper.policy: "lowest-relevance"` drops deterministically without a model call; default is `"model"`. Top-level `workerProvider` / `workerModel` remain as deprecated aliases.
+
+Token counting uses `estimateEntryTokens()` / `estimateMessageTokens()`.
 
-The runtime requires host-supplied `session`, an `appendEntry` callback bound to that session's owning store/branch, and `workerProvider`. Model selection uses [use-case model selection](use-case-model-selection.md): pass optional `workerModel` (or settings `workerModel`) to override, and `sessionModel: agent.config.model` so workers fall back to the session model when no worker model is configured. `requireExplicitModel: true` restores the historical `missing_model` skip when no explicit worker model is set. It no longer accepts a separate `store` option because mismatched session/store pairs can append memory entries outside the active branch. After each memory append, the runtime checks the appended entry is visible at the session leaf and fails closed/restores the previous checkout if the callback points elsewhere. Optional credential resolution is explicit; missing requested credentials skip worker execution. Default credential requests use the **resolved** model's provider id.
+The runtime requires host-supplied `session`, an `appendEntry` callback bound to that session's owning store/branch, and at least one worker provider (`observation.provider` or legacy `workerProvider`). Model selection uses [use-case model selection](use-case-model-selection.md): pass per-worker `model` (or settings `observation.model` / `reflection.model` / `dropper.model`) to override, and `sessionModel: agent.config.model` so workers fall back to the session model when no worker model is configured. `requireExplicitModel: true` restores the historical `missing_model` skip when no explicit worker model is set. It no longer accepts a separate `store` option because mismatched session/store pairs can append memory entries outside the active branch. After each memory append, the runtime checks the appended entry is visible at the session leaf and fails closed/restores the previous checkout if the callback points elsewhere. Optional credential resolution is explicit; missing requested credentials skip worker execution. Default credential requests use the **resolved** model's provider id.
 
-`createObservationalMemoryCompactionStrategy()` keeps recent message entries like the default compaction strategy, renders existing observations/reflections as the summary, and returns a standard Prism compaction entry. Its `data` includes `throughEntryId`, `keepEntryIds`, `strategy`, `trigger`, and `memory: { type: "om.folded", version: 1, fullFold, observations, reflections, droppedObservationIds }`. When active observations exceed `observationsPoolMaxTokens`, it performs a full fold into `data.memory`.
+`createObservationalMemoryCompactionStrategy()` keeps recent message entries like the default compaction strategy, renders existing observations/reflections as the summary, and returns a standard Prism compaction entry. Its `data` includes `throughEntryId`, `keepEntryIds`, `strategy`, `trigger`, and `memory: { type: "om.folded", version: 1, fullFold, observations, reflections, droppedObservationIds }`. When active observations exceed `context.observationsPoolMaxTokens`, it performs a full fold and synchronously trims lowest-relevance observations until the folded payload fits hard byte/token caps (or throws a typed error).
 
-`createRecallMemoryTool()` requires `args.id` to match `^[a-f0-9]{12}$`; invalid ids fail before entry lookup. Recall returns text and structured details for observations/reflections, dropped observations, supporting observations, source entries, and missing source ids. It does not search by topic.
+`createRecallMemoryTool()` accepts either `{ id }` for exact memory recall or `{ cursor, limit?, direction?, detail? }` for current-branch raw-message paging (default limit 20, hard cap 100). Reflection recall resolves supporting observations from the full ledger and reports `droppedSupportingObservationIds` / `missingSupportingObservationIds`; dropped supports still return available raw sources. Invalid ids, ambiguous requests, wrong `sessionId`, missing cursors, non-message cursors, and oversized pages fail closed. It does not search by topic.
 
 `createMemoryStatusCommand()` reports recorded/dropped/active/visible observations, recorded/visible reflections, pool token counts, and optional runtime in-flight/last-error state. `createMemoryViewCommand()` renders visible memory by default or full active recorded memory with `{ mode: "full" }`; other modes return `Usage: /om:view [full]`.