@arnilo/prism 0.0.1

package/docs/cli-rpc.md

@@ -0,0 +1,140 @@
+# CLI/RPC
+
+## What it does
+
+The `prism` bin is a thin adapter over `AgentSession`:
+
+- `prism -p "prompt"`: print assistant text deltas.
+- `prism --mode json -p "prompt"`: write one normalized event envelope per line.
+- `prism --mode rpc`: read LF-delimited JSON requests from stdin and write correlated JSON responses/events to stdout.
+
+It does not add a TUI, app tools, provider globals, extension discovery, resource discovery, or credential storage.
+
+## When to use it
+
+Use the CLI for terminal smoke tests, scriptable JSON event streams, and simple non-Node clients that can speak newline-delimited JSON.
+
+Use the SDK directly when an app needs custom providers, tools, resources, credentials, trust prompts, or UI behavior.
+
+## Inputs / request
+
+CLI flags:
+
+| Flag | Purpose |
+| --- | --- |
+| `-p`, `--prompt <text>` | Prompt for print/json modes. |
+| `--mode print\|json\|rpc` | Select output/protocol mode. Defaults to `print`. |
+| `--provider <name>` | Explicit provider id. The built-in `mock` id is only a smoke-test provider. |
+| `--model <name>` | Explicit model name. |
+| `--session <id>` | Session id. |
+| `--config <path>` | Explicit config path recorded by the adapter; not auto-loaded. |
+| `--resource <uri>` | Explicit resource URI recorded by the adapter; not auto-loaded. |
+| `--extension <name>` | Explicit extension name recorded by the adapter; not auto-loaded/imported. |
+| `--tool <name>` | Explicit tool name recorded by the adapter; not auto-enabled. |
+| `--system <text>` | System instructions. |
+| `--context <text>` | Context text reserved for host adapters. |
+| `--compact <entries>` | Auto-compaction threshold for the run. |
+| `--max-tool-rounds <n>` | Maximum runtime tool rounds. |
+| `--help` | Print usage. |
+
+RPC request envelope:
+
+```ts
+{ id: string | number; command: string; params?: Record<string, unknown> }
+```
+
+Supported command names: `prompt`, `steer`, `followUp`, `abort`, `state`, `messages`, `setModel`, `compact`, `switchSession`, `forkSession`, `cloneSession`, and `command`.
+
+## Outputs / response / events
+
+Print mode writes only assistant text deltas to stdout. Errors write a short line to stderr and return non-zero.
+
+JSON mode writes newline-delimited event envelopes:
+
+```ts
+{ type: "event"; sessionId?: string; runId?: string; event: AgentEvent }
+```
+
+RPC writes responses and async events:
+
+```ts
+{ id: string | number | null; ok: true; result?: unknown }
+{ id: string | number | null; ok: false; error: ErrorInfo }
+{ type: "event"; id: string | number; sessionId?: string; runId?: string; event: AgentEvent }
+```
+
+Invalid CLI flags return exit code `2`. Invalid JSON, missing ids, unknown RPC commands, unsupported `steer`, unknown command contributions, and runtime failures return `ok: false` response envelopes without executing unknown tools or commands.
+
+## Request/response example
+
+```json
+{"id":"1","command":"prompt","params":{"input":"Hi"}}
+{"type":"event","id":"1","sessionId":"s1","runId":"run_1","event":{"type":"message_delta"}}
+{"id":"1","ok":true,"result":{"sessionId":"s1"}}
+```
+
+## Active run behavior
+
+`prompt` and `followUp` start an asynchronous run and write their final response only when the run finishes. While a run is active, the RPC loop continues to read and respond to other requests:
+
+- `abort` cancels the active run for the current session and responds immediately.
+- `state`, `messages`, `setModel`, `switchSession`, `forkSession`, `cloneSession`, and registered `command` requests are processed immediately.
+- `compact` is fail-closed: if the current session has an active run, it returns `ok: false` because the session rejects compaction during a run.
+- A second `prompt` or `followUp` for the same session while it already has an active run returns `ok: false` immediately instead of blocking the input loop.
+
+Events streamed during a run keep the original prompt request id, even when an `abort` with a different request id cancels the run. The completion or error response for the prompt also uses the original prompt request id.
+
+```json
+{"id":"run-1","command":"prompt","params":{"input":"Hi"}}
+{"id":"abort-1","command":"abort","params":{"reason":"stop"}}
+{"type":"event","id":"run-1","sessionId":"s1","runId":"run_1","event":{"type":"error","error":{"message":"Agent run aborted"}}}
+{"id":"abort-1","ok":true,"result":{"sessionId":"s1"}}
+{"id":"run-1","ok":false,"error":{"message":"Agent run aborted"}}
+```
+
+## Implementation example
+
+```sh
+prism --provider mock --model demo -p "Hi"
+prism --provider mock --mode json -p "Hi"
+printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' | prism --provider mock --mode rpc
+```
+
+Programmatic hosts should use the public runtime directly:
+
+```ts
+import { createAgent, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerTextDelta("Hello"), providerDone()]),
+});
+await agent.createSession({ id: "s1" }).run("Hi");
+```
+
+## Extension and configuration notes
+
+CLI/RPC are adapters over `AgentSession`. They do not scan packages, import extensions, read config files, fetch resources, resolve credentials, or register tools unless a host adapter explicitly wires those primitives in.
+
+RPC `command` executes only explicitly registered `CommandDefinition` values. `setModel` stores a model override for later prompt/follow-up calls. `compact`, `switchSession`, `forkSession`, and `cloneSession` call the existing session APIs.
+
+## Security and performance notes
+
+- No built-in app tools ship in core.
+- No hidden provider, credential, extension, resource, config, settings, or tool globals are created.
+- No full TUI or sandbox is provided or implied.
+- JSONL is processed line by line with Node stdlib; no parser dependency, worker, watcher, or queue is added.
+- Unknown or malformed CLI/RPC input fails closed.
+- Do not put resolved credential values, tokens, headers, or secrets in prompts, CLI flags, config, events, or docs examples.
+
+## Related APIs
+
+- [Agent/session runtime](agent-session-runtime.md): runtime API used by CLI/RPC.
+- [Contribution registries](contribution-registries.md): command contributions are inert until explicitly wired.
+- [Configuration and manifests](configuration-and-manifests.md): config data stays separate from CLI/RPC execution.
+- [Node filesystem config loader](node-filesystem-config.md): optional explicit config file loading for Node hosts.
+- [Resource loading](resource-loading.md): explicit resource loading primitives.
+- [Credentials and redaction](credentials-and-redaction.md): secret redaction helpers and credential boundaries.
+- [Observational memory compaction package](compaction-observational-memory.md): optional `om:status` and `om:view` command factories for explicitly wired hosts.
+
+The CLI records flags but does not auto-load project-local resources, extensions, tools, or config. Hosts must make explicit trust and permission decisions before wiring any future local loading.

package/docs/compaction-and-retry.md

@@ -0,0 +1,177 @@
+# Compaction and retry policies
+
+## What it does
+
+Compaction helpers summarize older branch history without deleting raw session entries. Retry helpers retry transient provider-turn failures before any assistant output is observed.
+
+Current APIs:
+
+- `createDefaultCompactionStrategy(options?)`
+- `isCompactionEntryData(value)`
+- `CompactionEntryData`
+- `CompactionOptions`
+- `DefaultCompactionStrategyOptions`
+- `AgentSession.compact(options?)`
+- `AgentConfig.compaction` / `RunOptions.compaction`
+- `createDefaultRetryPolicy(options?)`
+- `isTransientErrorInfo(error)`
+- `waitForRetry(decision, signal?)`
+- `RetryPolicy`, `RetryContext`, `RetryDecision`, `RetryOptions`, `RetryMiddlewarePayload`
+- `AgentConfig.retry` / `RunOptions.retry`
+
+## When to use it
+
+Use compaction when a host wants provider input rebuilt from a summary plus recent messages while preserving the full branch in the session store. Use `session.compact()` for explicit compaction or `thresholdEntries` for opt-in auto-compaction before provider input.
+
+Do not use it as vector memory, semantic search, provider-backed summarization, a store rewrite, a database migration, CLI/RPC command, provider-specific HTTP adapter, or whole-run retry loop.
+
+## Inputs / request
+
+```ts
+createDefaultCompactionStrategy(options?: DefaultCompactionStrategyOptions): CompactionStrategy
+```
+
+`DefaultCompactionStrategyOptions`:
+
+| Field | Purpose |
+| --- | --- |
+| `name` | Optional strategy name; defaults to `default-compaction`. |
+| `keepRecentEntries` | Number of recent message entries to keep in provider context; defaults to `8`. |
+| `maxSummaryChars` | Maximum summary length; defaults to `4000`. |
+| `secrets` | Exact known secret strings to redact from generated summaries. |
+
+`CompactionOptions` can be placed on `AgentConfig.compaction`, `RunOptions.compaction`, or passed to `session.compact(options?)`:
+
+| Field | Purpose |
+| --- | --- |
+| `strategy` | Optional `CompactionStrategy`; defaults to `createDefaultCompactionStrategy()`. |
+| `thresholdEntries` | Enables auto-compaction when current branch entries exceed this count. Omit it for no auto-compaction. |
+| `keepRecentEntries` | Number of recent message entries kept in provider context. |
+| `maxSummaryChars` | Maximum default summary length. |
+| `secrets` | Exact known secret strings to redact from summaries/events/store text. |
+| `metadata` | Explicit host metadata passed to the compaction strategy only. |
+| `signal` | Optional manual compaction abort signal. |
+
+`RunOptions.compaction: false` disables configured auto-compaction for that run. `CompactionContext` also accepts optional `keepRecentEntries`, `trigger`, and `secrets`. Context values override or add to strategy defaults for that compaction call.
+
+Retry policy setup:
+
+```ts
+createDefaultRetryPolicy(options?: DefaultRetryPolicyOptions): RetryPolicy
+```
+
+`RetryOptions` can be placed on `AgentConfig.retry` or `RunOptions.retry`:
+
+| Field | Purpose |
+| --- | --- |
+| `policy` | Optional `RetryPolicy`; defaults to `createDefaultRetryPolicy(options)`. |
+| `maxAttempts` | Total provider-turn attempts; defaults to `3`. |
+| `baseDelayMs` | First retry delay; defaults to `100`. |
+| `maxDelayMs` | Backoff cap; defaults to `1000`. |
+| `secrets` | Exact known secret strings to redact from retry errors/events. |
+| `metadata` | Explicit host metadata for retry policy context. |
+
+`RunOptions.retry: false` disables configured retry for that run. Default classification retries generic transient codes/messages such as `ETIMEDOUT`, `ECONNRESET`, `429`, `500`, `502`, `503`, `504`, `timeout`, `rate_limit`, and `temporarily_unavailable`; aborts and non-transient errors fail closed.
+
+`CompactionEntryData` is stored in `SessionEntry.data` for compaction entries:
+
+| Field | Purpose |
+| --- | --- |
+| `throughEntryId` | Last older branch entry covered by the summary. |
+| `keepEntryIds` | Recent message entry ids to keep as raw provider context. |
+| `strategy` | Strategy that produced the entry. |
+| `trigger` | `manual`, `auto`, or a host-defined trigger string. |
+
+## Outputs / response / events
+
+`createDefaultCompactionStrategy().compact(context)` returns a `CompactionResult` with:
+
+- `summary`: a conservative text summary of older user/assistant text, summary entries, model changes, labels, and tool-call/result labels.
+- `entries`: one `kind: "compaction"` session entry whose parent is the current branch leaf.
+
+`session.compact(options?)` emits `compaction_started`, runs the strategy on the current branch, runs `middleware.run("compaction", { context, result })` when middleware is configured, appends one standard `kind: "compaction"` entry under the current leaf, emits `compaction_finished`, and returns the appended result. Manual compaction rejects while a run is active.
+
+Auto-compaction checks at most once per `run()`, after input/model-change entries are appended and before provider input assembly. It runs only when `AgentConfig.compaction` or `RunOptions.compaction` supplies `thresholdEntries`, and it is skipped by `RunOptions.compaction: false`.
+
+`rebuildSessionContext()` detects the latest compaction entry on a branch. Its returned `entries` still contains the raw full branch, while `messages` contains only messages after the compaction boundary plus `keepEntryIds`, and `summaries` contains the compaction summary plus later summary entries.
+
+Provider-turn retry wraps only the current provider request after input assembly. It emits `retry_scheduled`, waits with native abort-aware timers, and retries only if the failure happened before `message_started`, `message_delta`, or tool-call output was emitted. It does not retry missing providers, aborts, tool dispatch failures, unknown tools, validation failures, or post-output provider failures.
+
+## Request/response example
+
+```json
+{
+  "kind": "compaction",
+  "summary": "user: older question\nassistant: older answer",
+  "data": {
+    "throughEntryId": "entry_10",
+    "keepEntryIds": ["entry_11", "entry_12"],
+    "strategy": "default-compaction",
+    "trigger": "manual"
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createDefaultCompactionStrategy, createDefaultRetryPolicy, rebuildSessionContext } from "@arnilo/prism";
+
+const strategy = createDefaultCompactionStrategy({
+  keepRecentEntries: 4,
+  maxSummaryChars: 2000,
+  secrets: [apiKey],
+});
+
+const result = await strategy.compact({
+  sessionId: "s1",
+  entries: await store.list("s1"),
+  trigger: "manual",
+});
+
+for (const entry of result.entries ?? []) await store.append(entry);
+const snapshot = rebuildSessionContext(await store.list("s1"));
+
+const agent = createAgent({
+  model,
+  provider,
+  compaction: { strategy, thresholdEntries: 40, keepRecentEntries: 8 },
+  retry: { policy: createDefaultRetryPolicy({ maxAttempts: 3, baseDelayMs: 50 }) },
+});
+const session = agent.createSession({ id: "s1" });
+await session.run("hello", { compaction: { thresholdEntries: 20 } });
+await session.compact({ keepRecentEntries: 4 });
+```
+
+## Extension and configuration notes
+
+Retry policies are ordinary `RetryPolicy` implementations and can be registered as `retryPolicy` contributions. Hosts must still pass the selected policy/config to `createAgent()` or `session.run()`. Retry middleware receives `{ context, decision }` before a retry is scheduled and can reduce delay or stop retrying.
+
+Compaction strategies are ordinary `CompactionStrategy` implementations. Extensions can register strategies through the existing compaction strategy contribution registry, but registration is inert until a host explicitly selects and passes a strategy to runtime code. Extensions can also register `compaction` middleware; the runtime calls it only when the agent/session has that middleware registry configured.
+
+The default strategy does not call a provider. Hosts that need model-generated summaries can use the optional [`@arnilo/prism-compaction-llm` package](compaction-llm.md). Hosts that need prepared source-backed memory without a compaction-time model call can use [`@arnilo/prism-compaction-observational-memory`](compaction-observational-memory.md).
+
+## Security and performance notes
+
+- Raw session entries are never deleted or rewritten by these helpers or by runtime compaction.
+- Default compaction is O(n) over supplied branch entries and uses only arrays/strings.
+- Runtime compaction context excludes provider requests, provider objects, credential resolvers, resolved credentials, settings, and hidden metadata.
+- The default summary excludes metadata, provider requests, provider objects, credential resolvers, resolved credentials, settings, and full tool result values.
+- Redaction only removes exact known secret strings passed in `secrets`.
+- Default retry uses native abort-aware timers only when a retry is scheduled; no worker, queue, network probe, or dependency is used.
+- Retry context excludes provider request messages/content, provider objects, credentials, credential resolvers, and settings.
+
+## Related APIs
+
+- [LLM compaction package](compaction-llm.md): optional provider-backed compaction preparation helpers.
+- [Observational memory compaction package](compaction-observational-memory.md): optional source-backed memory ledger, worker runtime, fast no-model compaction strategy, projection, render, and recall utilities.
+- [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.
+- [Middleware hooks](middleware-hooks.md): `compaction` and `retry` middleware payload timing.
+- [Contribution registries](contribution-registries.md): compaction strategy and retry policy contributions.
+- [Configuration and manifests](configuration-and-manifests.md): `compactionStrategy` and `retryPolicy` manifest contribution kinds.
+- [Provider layer](provider-layer.md): safe provider error codes used by retry classification.
+- [Credentials and redaction](credentials-and-redaction.md): exact secret redaction helper used by default compaction and retry error handling.
+
+Runtime redaction composes with compaction and retry secret lists: configured redactors apply at session serialization boundaries, while compaction/retry `secrets` still redact their local summaries and errors.

package/docs/compaction-llm.md

@@ -0,0 +1,108 @@
+# LLM compaction package
+
+## What it does
+`@arnilo/prism-compaction-llm` is an optional provider-backed compaction package. It prepares branch history, calls an explicit summary provider/model, and returns a standard Prism `CompactionStrategy`. The core default compaction remains local and conservative.
+
+## When to use it
+Use it when a host wants model-generated summaries while preserving raw append-only session history. Do not use it as a core default, provider SDK loader, hidden credential discovery layer, vector memory, or store rewrite.
+
+## Inputs / request
+Key exports:
+
+| Export | Purpose |
+| --- | --- |
+| `createLlmCompactionStrategy(options)` | Returns a provider-backed `CompactionStrategy`. |
+| `createLlmCompactionExtension(options)` | Registers the strategy into an explicit extension kernel compaction registry. |
+| `prepareLlmCompaction(context, options?)` | Splits branch entries into summary input, kept suffix, optional split-turn prefix, file details, and compaction data. |
+| `findLlmCompactionCutPoint(entries, options?)` | Finds the last entry covered by a summary using approximate token budgets. |
+| `serializeCompactionConversation(entries, options?)` | Serializes entries with role labels and tool-result truncation, then redacts known secrets. |
+| `collectFileOperations(messages)` / `formatFileOperations(details)` | Extracts and formats `read`, `write`, and `edit` tool-call paths. |
+| `estimateTextTokens`, `estimateMessageTokens`, `estimateEntryTokens` | Cheap chars/4 token estimates. |
+| prompt constants | Structured markdown summary prompts for host override/reference. |
+
+`LlmCompactionStrategyOptions`:
+
+| Field | Purpose |
+| --- | --- |
+| `provider` / `summaryProvider` | Explicit `AIProvider`, or factory receiving a resolved credential. |
+| `model` / `summaryModel` | Explicit summary `ModelConfig`. |
+| `credential`, `credentialRequest` | Optional per-call credential resolution for provider factories. |
+| `providerOptions` | Generic `ProviderRequest.options`, including cache fields. |
+| `providerRequestPolicies` | Optional Prism provider request policies applied before the summary call. |
+| `customInstructions` | Additional summary focus appended to prompts. |
+| `thinkingLevel` | Passed as `ProviderRequest.options.extra.thinkingLevel`. |
+| `reserveTokens` | Output budget basis; defaults to `16384`. |
+| `keepRecentTokens` | Approximate recent-token budget; defaults to `20000`. |
+| `maxSummaryTokens` / `maxOutputTokens` | Sets generic `model.parameters.maxTokens` and truncates oversized collected summaries. |
+| `maxToolResultChars` | Tool-result JSON truncation limit; defaults to `2000`. |
+| `trackFileOperations`, `includeFileOperations` | Control file path extraction and final summary blocks. |
+| `secrets` | Exact strings to redact from serialized prompts and final summaries. |
+
+## Outputs / response / events
+`createLlmCompactionStrategy().compact(context)` returns a `CompactionResult` with `summary` and one `kind: "compaction"` entry. The entry data includes core `CompactionEntryData` plus `firstKeptEntryId`, token estimates, optional split-turn flag, and optional `readFiles`/`modifiedFiles` lists.
+
+Provider `error` events, empty summaries, or abort signals throw before returning a result, so the runtime appends no compaction entry.
+
+## Request/response example
+```json
+{
+  "throughEntryId": "entry_10",
+  "keepEntryIds": ["entry_11", "entry_12"],
+  "strategy": "llm-compaction",
+  "firstKeptEntryId": "entry_11",
+  "estimatedTokensBefore": 12000,
+  "estimatedTokensAfter": 1900
+}
+```
+
+## Implementation example
+```ts
+import { createLlmCompactionStrategy } from "@arnilo/prism-compaction-llm";
+
+const strategy = createLlmCompactionStrategy({
+  provider: summaryProvider,
+  model: { provider: "mock", model: "cheap-summary" },
+  keepRecentTokens: 20_000,
+  reserveTokens: 16_384,
+  providerOptions: { cacheRetention: "short" },
+  customInstructions: "Focus on current files and failing tests.",
+});
+
+await session.compact({ strategy, secrets: [apiKey] });
+```
+
+Credential factory example:
+
+```ts
+const strategy = createLlmCompactionStrategy({
+  summaryProvider: (apiKey) => createProvider({ apiKey }),
+  credential: credentials,
+  credentialRequest: { provider: "example", name: "apiKey" },
+  summaryModel: { provider: "example", model: "cheap-summary" },
+});
+```
+
+## Extension and configuration notes
+This package is inert until imported. Direct strategy use works with `session.compact({ strategy })` and opt-in auto-compaction through existing `thresholdEntries` when the host selects the strategy.
+
+```ts
+import { createAgent, createExtensionKernel } from "@arnilo/prism";
+import { createLlmCompactionExtension } from "@arnilo/prism-compaction-llm";
+
+const kernel = createExtensionKernel();
+await kernel.load([createLlmCompactionExtension({ provider: summaryProvider, model: summaryModel })]);
+const strategy = kernel.registries.compactionStrategies.resolve("llm-compaction");
+
+const agent = createAgent({ model, provider, compaction: { strategy, thresholdEntries: 40 } });
+```
+
+Registration only contributes an inert strategy. The host must resolve and pass it to runtime config.
+
+## Security and performance notes
+Preparation is O(n) over branch entries and uses only arrays, strings, and JSON serialization. The strategy makes only the needed provider call(s): one history summary plus one split-turn prefix summary when needed. It does not discover credentials, read files, start background jobs, or add provider SDK dependencies. Redaction is exact-string only; pass every known secret that may appear in history or provider output.
+
+## Related APIs
+- [Compaction and retry policies](compaction-and-retry.md): core compaction strategy surface.
+- [Agent/session runtime](agent-session-runtime.md): `AgentSession.compact()` and opt-in auto-compaction.
+- [Provider layer](provider-layer.md): mock providers and provider request contracts.
+- [Credentials and redaction](credentials-and-redaction.md): exact known-secret redaction behavior.

package/docs/compaction-observational-memory.md

@@ -0,0 +1,123 @@
+# Observational memory compaction package
+
+## What it does
+
+`@arnilo/prism-compaction-observational-memory` is an optional package for source-backed observational memory and fast compaction.
+
+Current status: ledger/projection/render/recall utilities, explicit worker runtime, fast compaction strategy, inert extension helper, recall tool, and status/view command factories are available.
+
+## 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.
+
+Use `createObservationalMemoryCompactionStrategy()` when compaction should render prepared memory without a model call. Prism core still does not select this package by default.
+
+## Inputs / request
+
+Memory records use `SessionEntry.kind: "custom"` with `entry.data.type` markers:
+
+| Type | Payload |
+| --- | --- |
+| `om.observations.recorded` | `{ observations, coversUpToId? }` |
+| `om.reflections.recorded` | `{ reflections, coversUpToId? }` |
+| `om.observations.dropped` | `{ observationIds, coversUpToId? }` |
+| `om.folded` | Compaction `data.memory` folded details. |
+
+Ids are known, source-backed 12-character lowercase hex strings matching `^[a-f0-9]{12}$`.
+
+## Outputs / response / events
+
+Key exports:
+
+| Export | Purpose |
+| --- | --- |
+| `foldObservationalMemoryLedger()` | Fold custom memory entries into observations, reflections, drops, and coverage markers. |
+| `buildObservationalMemoryProjection()` | Build active/full/folded projections from current branch entries. |
+| `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. |
+| `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/store/provider. |
+| `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. |
+| `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.
+
+## Request/response example
+
+```json
+{"id":"aaaaaaaaaaaa","kind":"observation","found":true}
+```
+
+## Implementation example
+
+```ts
+import {
+  buildObservationalMemoryProjection,
+  createObservationalMemoryCompactionStrategy,
+  createObservationalMemoryExtension,
+  createObservationalMemoryCommands,
+  createObservationalMemoryRuntime,
+  createRecallMemoryTool,
+  recallObservationalMemory,
+  renderObservationalMemory,
+} from "@arnilo/prism-compaction-observational-memory";
+
+const entries = await session.entries();
+const projection = buildObservationalMemoryProjection(entries);
+const summary = renderObservationalMemory(projection.reflections, projection.observations);
+const evidence = recallObservationalMemory(entries, "aaaaaaaaaaaa");
+
+const memory = createObservationalMemoryRuntime({
+  session,
+  store,
+  workerProvider,
+  workerModel: { provider: "mock", model: "memory" },
+});
+await memory.flush();
+await session.compact({ strategy: createObservationalMemoryCompactionStrategy({ keepRecentEntries: 8 }) });
+
+const getEntries = (sessionId: string) => sessions.get(sessionId)?.entries() ?? [];
+const recallTool = createRecallMemoryTool({ getEntries, secrets: [apiKey] });
+const commands = createObservationalMemoryCommands({ getEntries });
+
+await kernel.load([createObservationalMemoryExtension({ recallTool: { getEntries }, commands: { 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`.
+
+The runtime requires host-supplied `session`, matching `store`, `workerProvider`, and `workerModel`. Optional credential resolution is explicit; missing requested credentials skip worker execution.
+
+`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`.
+
+`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.
+
+`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]`.
+
+`createObservationalMemoryExtension()` registers only inert contributions. It does not start workers, compact sessions, read settings, resolve credentials, call providers, or execute tools/commands during setup.
+
+## Security and performance notes
+
+- Recall is exact-id only; there is no semantic search, vector store, or transcript browser.
+- Recall tool and commands only see current-branch entries supplied by the host callback.
+- Invalid or missing ids fail closed; invalid recall tool ids skip entry lookup.
+- Utilities and fast compaction are O(n) over supplied entries and use no provider, network, filesystem, timer, worker, credential, or settings access.
+- Workers serialize only supplied branch entries, enforce `agentMaxTurns`, and run one consolidation pipeline at a time per runtime.
+- Compaction preserves raw history; Prism appends one standard compaction entry and rebuilds provider context from its summary plus kept recent messages.
+- Pass known secrets to render/recall/runtime/tool/command helpers to redact exact values from prompts, records, structured results, and text output.
+- Live tests are opt-in with `PRISM_LIVE_OBSERVATIONAL_MEMORY_TESTS=1`.
+
+## Related APIs
+
+- [Compaction and retry policies](compaction-and-retry.md): replaceable compaction strategy boundary.
+- [LLM compaction package](compaction-llm.md): existing optional compaction-package pattern.
+- [Session stores and branching](session-stores-and-branching.md): branch entries that observational memory reads and appends to.
+- [Extensions](extensions.md): inert registration pattern for optional package contributions.
+- [Tools](tools.md): host activation and dispatch for optional recall tool contributions.
+- [CLI/RPC](cli-rpc.md): command contributions through explicitly wired RPC hosts.