Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

feat: per-handoff LLM generation tracing and prompt-prefix stability metric (#102)

Sol Aitken20ea7ef82c7d
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 8ee040b9..c1026814 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.12.0",
+ "version": "1.13.0",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index abb55da4..915cf669 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.12.0",
+ "version": "1.13.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"hooks": "./hooks/hooks.json",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bfc7314d..287a5639 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,79 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.13.0] - 2026-06-16
+
+### Added
+
+- **Per-handoff LLM generation tracing (`generation_report`).** An
+ additive, opt-in, fail-open way to record the real LLM usage an agent
+ performs on behalf of a brain handoff, without the kernel ever calling
+ an LLM. Open Second Brain owns sequencing and the atomic commit; the
+ calling agent owns generation, so tracing is an INBOUND path: after the
+ agent fulfils a write-session step, a context-pack consume, or a
+ dream-stage proposal, it optionally reports back the usage and Open
+ Second Brain stores it as a `generation_report` continuity record.
+ - **Inbound report surface (`brain_generation_reports` action `record`,
+ `o2b brain generation-reports record`).** Gated (default off) by a
+ per-call `enable` flag or the `generation_trace_enabled` config /
+ `OPEN_SECOND_BRAIN_GENERATION_TRACE_ENABLED` env. With the gate off no
+ payload is built and nothing is written; a throwing build is swallowed
+ so tracing never fails the primary operation (`emitGatedTelemetry`).
+ - **Payload-safe by construction.** The handoff prompt is hashed and
+ counted but never persisted - only `prompt_hash` (SHA-256 hex) and
+ `prompt_chars`, plus token counts, reach disk, and the whole payload
+ still passes `safeContinuityPayload` redaction. The local token
+ estimate (`local_estimate.input_tokens`) is always present; the
+ agent-reported `usage` block is present only when supplied and absent
+ is reported as absent, never fabricated.
+ - **Memory to trace linkage.** `sourceRefs` join each report to the
+ handoff ref (write-session session id, context-receipt id, or dream
+ run id) and the memory paths involved, lifted to first-class
+ `handoffKind` / `handoffRef` read-model fields. The `summary` read
+ (`brain_generation_reports` action `summary`,
+ `o2b brain generation-reports summary`) rolls up call counts,
+ per-handoff-kind breakdown, the local estimate, reported usage, and a
+ per-path map so a memory path resolves back to the reports that
+ produced or consumed it.
+ - **Read surfaces.** `o2b brain generation-reports list|summary|show`
+ and the matching `brain_generation_reports` actions (`list` and
+ `summary`; `show` is CLI-only). The kernel never
+ adds an outbound `fetch`/provider HTTP call - a grep-guarded
+ regression test pins this, and a persisted-file assertion confirms no
+ raw prompt survives. Default behaviour is byte-identical: the
+ write-session envelope, context_receipt, dream_stage metric, and
+ recall_telemetry keep their current shapes when the gate is off.
+ Documented in `docs/observability.md`, `docs/cli-reference.md`, and
+ `docs/mcp.md`.
+- **Structural prompt-prefix stability (`prompt_prefix` metric).** A
+ deterministic prefix layer plus a run-level metric that reports how
+ stable the prompt preamble was across the repeated generation handoffs
+ of one brain operation. Open Second Brain cannot port Hindsight's
+ provider prompt-prefix caching verbatim - the kernel never calls an
+ LLM, so it has no outbound request to cache - but it can guarantee the
+ precondition a provider prefix cache rewards: a byte-stable, cache-
+ eligible prefix across a pass.
+ - **Deterministic prefix helper (`src/core/brain/prompt-prefix.ts`).**
+ `deterministicPrefix` certifies a stable preamble (`prefix`, full
+ SHA-256 `hash`, code-point `chars`) from stable inputs only - no
+ clock, no random, sorted keys via `canonicalSegment`. The decision-
+ panel builder routes its shared `Decision topic:` frame through it;
+ the bytes of the persona and synthesis prompts are unchanged.
+ - **Run-level `prompt_prefix` metric.** A decision-panel commit (opt-in
+ `promptPrefixMetric`) and a context-pack consume (opt-in
+ `promptPrefix`) emit one record under
+ `Brain/metrics/prompt_prefix.jsonl` carrying `kind`, `prefix_hash`,
+ `prefix_chars`, `call_count`, and `stable_count`. The reader is
+ surface-agnostic (no `metrics.ts` change), exactly like `dream_stage`.
+ - **Stability, not cache-hit rate.** The metric measures STRUCTURAL
+ prefix stability (what the kernel handed the agent), never a
+ provider's cache-hit rate (which the kernel cannot observe). The raw
+ prompt is never stored - only its hash and length. Emission is opt-in
+ and fail-soft; with the gate off no record is written and the panel
+ commit, write-session envelope, and context_pack report are
+ byte-identical. Documented in `docs/metrics.md` and
+ `docs/observability.md`.
+
## [1.12.0] - 2026-06-15
### Added
@@ -5540,6 +5613,7 @@ plugin config (vault field)`, and exits with a clear
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
+[Unreleased]: https://github.com/itechmeat/open-second-brain/compare/v1.12.0...HEAD
[1.12.0]: https://github.com/itechmeat/open-second-brain/compare/v1.11.0...v1.12.0
[1.11.0]: https://github.com/itechmeat/open-second-brain/compare/v1.10.0...v1.11.0
[1.10.0]: https://github.com/itechmeat/open-second-brain/compare/v1.9.0...v1.10.0
diff --git a/docs/brainstorm/hindsight-brain-loop-ops/cli-output/claude.md b/docs/brainstorm/hindsight-brain-loop-ops/cli-output/claude.md
new file mode 100644
index 00000000..498d8671
--- /dev/null
+++ b/docs/brainstorm/hindsight-brain-loop-ops/cli-output/claude.md
@@ -0,0 +1,32 @@
+## Variant 1: Extend continuity + metrics layers (reuse-first)
+Approach: Treat both cards as additive surfaces on the infrastructure that already exists. Tracing becomes a new opt-in inbound continuity kind, `generation_report`, that the agent posts back after fulfilling any handoff (write-session submit, context-pack consume, dream proposal), carrying agent-reported usage (provider/model, real input/output/cached/total tokens, finish reason, latency) plus the local token estimate for comparison. Caching becomes a deterministic prefix-construction rule in the existing prompt builders plus a `prompt_prefix` metric surface that reports prefix-stability across repeated calls.
+Trade-offs:
+- Smallest blast radius: no new store, no new module, no new lifecycle. Both cards are pure additive surfaces under rules already audited (gate pattern, `safeContinuityPayload`, content-hash dedup).
+- Memory <-> trace linkage falls out of `sourceRefs` (paths/ids the kernel already knows); honest by construction, since the kernel never invents an LLM message id.
+- The asymmetry is surfaced cleanly: estimate is always present, real usage is present only when the inbound report arrives, and absent is reported as absent.
+- Weaker uniformity: each of the three seams wires the inbound report itself, so there is mild duplication and no single "generation trace" abstraction to grow into later.
+Complexity: small
+Risk: low
+
+## Variant 2: Write-session engine as the canonical trace unit
+Approach: Anchor both cards on the write-session lifecycle, the one seam that already has a durable record, audit event, attempts, and terminal transitions. Tracing extends the submit path with an opt-in agent-reported usage block and records latency/attempts into the existing `write-session` audit event, with `session_id <-> target_path` as the memory link. Caching adds a deterministic, separately hashed `cache_prefix` segment to the envelope plus advisory cache-control hints the agent may honour.
+Trade-offs:
+- Highest-fidelity trace where it matters most: the write-session already models open -> needs-llm-step -> submit -> terminal, so usage, attempts, and latency attach to a real state machine rather than a fresh log line.
+- Reuses the existing chokepoint (`appendLogEvent`), so audit ordering and the one-event-per-terminal-transition guarantee are preserved for free.
+- Coverage gap: context-pack and dream handoffs are not write-sessions, so they get little or no tracing and no shared prefix builder; the release covers one seam deeply and two shallowly.
+- Modifying the submit path and envelope risks shape drift on a load-bearing record; needs careful flag-gating to keep default bytes identical.
+Complexity: medium
+Risk: medium
+
+## Variant 3: Dedicated generation-observability module
+Approach: Introduce `src/core/brain/generation/` as a unified seam that all three handoffs (write-session, context-pack, dream) describe themselves through, emitting one "generation handoff descriptor" and accepting one opt-in inbound "generation report" via a new CLI verb and MCP tool. The module owns a single deterministic prefix builder shared by all three seams and a `prompt_prefix` metric surface, giving one consistent trace ledger and one caching guarantee across the whole brain loop.
+Trade-offs:
+- Most coherent long-term shape: one abstraction, one reader, uniform linkage and prefix construction across every generation point.
+- Best leverage for future handoff shapes, which only need to implement the descriptor rather than wire telemetry themselves.
+- Largest change for a release the operator deliberately scoped to two minor, closely related tasks; it adds a new module, a new inbound path, and refactors three seams at once.
+- Higher regression surface and review cost; risks introducing a parallel store/abstraction the brief explicitly cautions against, and front-loads design the two cards do not yet require.
+Complexity: large
+Risk: high
+
+## Recommended: Variant 1
+Rationale: It satisfies every binding constraint with the least new surface area: opt-in, fail-open, payload-safe, additive-only, and byte-identical by default, all by reusing the continuity gate and the metrics layer rather than inventing a parallel store. It answers the key design question honestly: the traced unit is the agent's inbound generation report keyed by the paths/ids the kernel already owns, and caching is delivered structurally as a byte-stable prefix with a stability metric, never as a provider call. It covers all three handoff shapes without committing to a premature abstraction, which is the right altitude for a release deliberately scoped to two minor, closely related cards. Variant 2 leaves context-pack and dream under-covered, and Variant 3's uniformity is not yet earned and carries regression and parallel-store risk that this scope does not justify.
diff --git a/docs/brainstorm/hindsight-brain-loop-ops/cli-output/prompt.md b/docs/brainstorm/hindsight-brain-loop-ops/cli-output/prompt.md
new file mode 100644
index 00000000..6c039b14
--- /dev/null
+++ b/docs/brainstorm/hindsight-brain-loop-ops/cli-output/prompt.md
@@ -0,0 +1,311 @@
+You are a senior backend architect advising on a brainstorm for the
+**Open Second Brain** project. Read the full brief below, then produce
+exactly THREE distinct architectural variants and exactly ONE
+recommendation. No code. Nothing outside the requested sections.
+
+================================================================
+OUTPUT FORMAT (strict)
+================================================================
+
+Produce this structure and ONLY this structure:
+
+## Variant 1: <short name>
+Approach: <2-3 sentences>
+Trade-offs:
+- <bullet>
+- <bullet>
+- <bullet>
+Complexity: small|medium|large
+Risk: low|medium|high
+
+## Variant 2: <short name>
+Approach: ...
+Trade-offs: ...
+Complexity: ...
+Risk: ...
+
+## Variant 3: <short name>
+Approach: ...
+Trade-offs: ...
+Complexity: ...
+Risk: ...
+
+## Recommended: Variant N
+Rationale: <3-5 sentences>
+
+The three variants must be genuinely distinct architectural shapes
+(not three flavours of the same idea). Each must cover BOTH in-scope
+cards as a single coherent release (the release ships both together
+on one feature branch).
+
+================================================================
+PROJECT CONTEXT
+================================================================
+
+- Project: Open Second Brain (https://github.com/itechmeat/open-second-brain)
+- Language/runtime: TypeScript, runs on the Bun runtime. ESM modules.
+ Package manager: bun. Linter: oxlint. Formatter: oxfmt. Tests: `bun test`
+ via `scripts/test`. Typecheck: `tsc --noEmit`.
+- Current version: 1.12.0.
+- Distribution: a CLI (`o2b`) and an MCP server consumed by AI agents
+ (Hermes Agent, Claude Code, Codex, Cursor, opencode, Grok Build, and
+ others). The agent is the LLM; Open Second Brain is the deterministic
+ memory/coordination layer.
+
+THE DOMINANT ARCHITECTURAL INVARIANT (read carefully):
+
+ The Open Second Brain kernel NEVER calls an LLM. The calling agent
+ owns all generation. Open Second Brain owns sequencing, deterministic
+ computation, validation, and the atomic commit. This invariant is
+ load-bearing and intentional; the whole safety model rests on it.
+
+This means the two in-scope cards (which originate in the Hindsight
+project, where the brain ITSELF makes LLM calls for retain /
+consolidate / reflect) cannot be ported verbatim. They must be
+re-shaped so that Open Second Brain delivers the same OPERATIONAL VALUE
+(request observability + prompt-cost efficiency) WITHOUT the kernel
+ever calling an LLM. The variants you propose must respect this.
+
+================================================================
+THE TWO IN-SCOPE CARDS (release: "Hindsight brain-loop ops")
+================================================================
+
+--- CARD t_281c3edc ---
+Title: [upstream:hindsight] Per-bank LLM request tracing via OTel GenAI recorder
+
+What Hindsight did:
+- Records every LLM call (success/failure) into a new llm_requests table
+ per bank when HINDSIGHT_API_LLM_TRACE_ENABLED=true.
+- Captures input messages, model output, token usage
+ (input/output/cached/total), finish reason, provider/model/scope,
+ timing, caller metadata.
+- GET /v1/default/banks/{bank}/llm-requests (+ /stats) read API.
+- Control-plane "LLM Requests" tab: list, filters, detail dialog,
+ Calls/Tokens chart.
+- Memory <-> trace bidirectional navigation (memory detail shows
+ "Created by" / "Consolidated by" trace links).
+
+Why useful for Open Second Brain:
+- Open Second Brain has no LLM request tracing. Calls go through the
+ agent's providers with no persistent audit log tied to brain
+ operations. Per-agent / per-session LLM tracing with token usage,
+ latency, and memory linkage would give operators full observability
+ into what the brain asked, what it got, and which memories were
+ involved.
+
+Status in Open Second Brain:
+- No LLM request tracing table, no OTel GenAI recorder, no memory<->
+ trace navigation exists. The kernel does not call providers.
+
+--- CARD t_d8c1f7d9 ---
+Title: [upstream:hindsight] LLM prompt-prefix caching for retain/consolidate/reflect
+
+What Hindsight did:
+- v0.8.0 added provider prompt-prefix caching for retain, consolidation,
+ and reflect operations (bank-agnostic, default-on). Caches the common
+ prompt prefixes across repeated LLM calls within these operations.
+
+Why useful for Open Second Brain:
+- Open Second Brain's brain operations (dream stages, context packing,
+ write-session generation steps) produce repeated structured prompts.
+ Prompt-prefix caching would reduce API cost and latency for providers
+ that support it (OpenAI, Anthropic, etc.). A bank-agnostic design
+ works across memory partitions.
+
+Status in Open Second Brain:
+- No prompt-prefix caching layer exists. The codegraph query for
+ "prompt prefix caching retain consolidate reflect" returned no results.
+ src/core/brain/dream.ts makes repeated generation handoffs;
+ src/core/brain/context-pack.ts has no prompt-caching layer.
+
+================================================================
+THE GENERATION SEAM IN OPEN SECOND BRAIN
+================================================================
+
+Because the kernel never calls an LLM, the place where "LLM usage"
+actually happens is the HANDOFF from Open Second Brain to the agent.
+There are three handoff shapes, all deterministic and file/JSON based:
+
+1. Write-session engine (src/core/brain/write-session/engine.ts,
+ types.ts, store.ts, validate.ts, panel.ts).
+ - Lifecycle: open -> `needs-llm-step` envelope -> submit ->
+ `done` | `needs-correction` | `needs-review` | `failed`.
+ - The envelope (WriteSessionEnvelope) carries: status, session_id,
+ kind (artifact | panel), step, prompt, schema_hints, errors,
+ attempts_left, expires_at, target_path, existing (collision info).
+ - The session record (WriteSessionRecord) persists: id, kind, status,
+ step, agent, createdAt, updatedAt, expiresAt, attempts, retryCap,
+ targetPath, intent (create | overwrite | merge), requireReview,
+ prompt, schemaType, topic, personas, responses, pendingArtifact,
+ lastErrors, failReason. Stored as JSON at Brain/.sessions/write/<id>.json.
+ - Every terminal transition appends exactly one `write-session` audit
+ event through the log chokepoint (appendLogEvent in log.ts).
+ - HARD RULE: OSB never generates content; every artifact byte comes
+ from the caller. Fail-closed: nothing lands unless validation clean.
+
+2. Context pack / pre-compress pack (src/core/brain/context-pack.ts,
+ pre-compress-pack.ts).
+ - Produces the context text the agent consumes before answering /
+ compressing. Emits a `context_receipt` continuity record
+ (opt-in) listing the items served, their token estimates, tier,
+ trim state, and the final-text hash.
+ - Token counts here are local estimates (token-footprint.ts), NOT
+ provider-reported usage.
+
+3. Dream stages (src/core/brain/dream.ts, dream-stage.ts,
+ dream-refresh.ts, dream-plan.ts).
+ - Deterministic proposal/synthesis passes. The kernel does NOT call
+ an LLM; where generation is needed, Open Second Brain emits a
+ structured proposal/handoff the agent fulfils. dream stages emit
+ a `dream_stage` metric record (Brain/metrics/dream_stage.jsonl).
+
+================================================================
+EXISTING OBSERVABILITY SURFACES (reuse candidates)
+================================================================
+
+- Brain log: Brain/log/<date>.md + JSONL sidecar (appendLogEvent).
+ Kinds include dream, feedback, write-session, etc.
+- Continuity store: Brain/log/continuity/<month>.jsonl, envelope
+ {schema: "o2b.continuity.v1", id, kind, createdAt, sourceRefs,
+ payload, private, redacted}. Existing kinds: recall_telemetry,
+ context_receipt, gate_telemetry, session_turn, session_summary_node,
+ pre_compact_extract, source_invalidation.
+ - All opt-in telemetry routes through emitGatedTelemetry(gate, build):
+ gate off => the build thunk is NEVER invoked; a throwing thunk is
+ swallowed => the primary operation still completes.
+ - Payload safety: <private> regions stripped, secrets redacted, raw
+ prompts NEVER stored (only SHA-256 prefix + length for gate telemetry).
+ - Record id = sha-256 over kind + createdAt + sourceRefs + payload
+ (content-hash dedup). Additive optional fields do NOT bump schema
+ version; renames/removals bump to o2b.continuity.v2.
+- Metrics layer: Brain/metrics/<surface>.jsonl, envelope
+ {schema: "o2b.metrics.v1", surface, run_at, payload}. Run-level only
+ (one line per pass), O_APPEND, payloads < ~4 KiB. Existing surfaces:
+ index, bridge_discovery, communities, recall_benchmark, self_tuning,
+ dream_stage.
+- Write-session audit event already records session lifecycle; it does
+ NOT record token usage, latency, or the agent's actual model/provider.
+- Readers: brain_recall_telemetry / brain_context_receipts MCP tools,
+ o2b brain recall-telemetry, o2b brain context-receipts CLI.
+
+================================================================
+RELATED FILES / GREP ANCHORS
+================================================================
+
+- src/core/brain/write-session/{engine,types,store,validate,panel}.ts
+- src/core/brain/context-pack.ts, pre-compress-pack.ts, context-receipts.ts
+- src/core/brain/dream.ts, dream-stage.ts, dream-refresh.ts, dream-plan.ts
+- src/core/brain/continuity/{store,types,emit,redaction,read-model}.ts
+- src/core/brain/log.ts, types.ts (BRAIN_LOG_EVENT_KIND)
+- src/core/brain/metrics.ts
+- src/core/brain/token-footprint.ts
+- src/cli/brain/verbs/write-session.ts (CLI envelope surface)
+- src/mcp/brain/ (MCP tool registrations)
+- docs/observability.md, docs/metrics.md (the on-disk contracts)
+
+================================================================
+CONSTRAINTS (all binding)
+================================================================
+
+1. The kernel never calls an LLM. No new direct provider calls,
+ OpenTelemetry GenAI recorder around LLM calls, or fetch() to a model
+ endpoint inside src/core. Generation stays agent-owned.
+2. Every new telemetry/observability surface must be OPT-IN (per-call
+ option or config key, default off) and FAIL-OPEN: a telemetry
+ problem must never fail the primary operation. Reuse the
+ emitGatedTelemetry gate pattern; never construct a payload on the
+ no-consumer path.
+3. Payload safety: raw prompts are NEVER persisted to disk in
+ plaintext. Use SHA-256 prefix + length, hashes, redacted metadata,
+ and counters. Reuse safeContinuityPayload / context-receipt hashing.
+4. Additive-only schema evolution: new continuity kinds / metric
+ surfaces / optional payload fields do not break existing readers.
+ Unknown kinds/fields are skipped. New surface names are lowercase
+ snake_case, max 64 chars.
+5. Default behaviour is byte-identical when no new option is supplied.
+ Existing reads (write-session envelope, context_receipt, dream_stage
+ metric, recall_telemetry) must not change shape unless a flag is set.
+6. Language-agnostic. No hardcoded natural-language keyword lists,
+ stop-words, or per-language phrase tables (project rule, PR #84).
+7. SOLID / KISS / DRY. No misleading fallbacks (absent data is reported
+ as absent, never fabricated). No hardcoded provider names that imply
+ OSB calls them directly. English-only strings, abstract over any
+ language.
+8. Token usage the kernel can know: only LOCAL estimates
+ (token-footprint.ts). Real provider-reported token usage is NOT
+ available to the kernel unless the agent reports it back (an opt-in
+ inbound path). Surface this asymmetry honestly in the variants.
+
+================================================================
+KEY DESIGN QUESTION THE VARIANTS MUST ANSWER
+================================================================
+
+Both cards are about the LLM-usage layer of the brain loop, but the
+kernel makes no LLM calls. So the variants must decide:
+
+(A) For LLM-request TRACING: what is the Open Second Brain unit being
+ traced? Options include but are not limited to: the write-session
+ generation step lifecycle (envelope -> submit -> terminal, with
+ attempts, latency, and the agent-reported usage), the context-pack
+ / dream handoff, or a new opt-in inbound "generation report" the
+ agent sends back. How is it stored (new continuity kind? new metric
+ surface? a new Brain/ directory?), how is it read (CLI verb + MCP
+ tool), and how does memory <-> trace linkage work when the kernel
+ only knows paths/ids, not LLM message ids?
+
+(B) For prompt-prefix CACHING: since OSB cannot cache on a provider it
+ does not call, the value must be delivered structurally. Options
+ include but are not limited to: a deterministic-prefix construction
+ in the write-session prompt builder + context-pack so the prefix
+ the agent forwards to its provider is byte-stable across repeated
+ calls (cache-friendly), plus an opt-in metric that reports prefix
+ stability. Or: advisory cache-control hints emitted in the handoff
+ that the agent MAY honour. How much is structural guarantee vs
+ advisory, and how is it measured without the kernel seeing the
+ provider's cache stats?
+
+The three variants should differ in WHERE the shared seam lives
+(write-session engine vs a new generation-observability module vs
+extending continuity/metrics layers), how invasive the change is, and
+how honestly they handle the kernel-cannot-see-real-usage asymmetry.
+
+Prefer variants that reuse existing observability infrastructure
+(continuity records, metrics layer, write-session audit) over
+inventing parallel stores, and that keep both cards small and
+low-risk (the operator scoped this release to 2 minor, closely related
+tasks deliberately).
+
+================================================================
+GIT LOG (recent main history)
+================================================================
+
+9c1d48f feat: CodeGraph and MCP operational readability (v1.12.0) (#101)
+c2c3ff4 feat: Session Knowledge Synthesis Suite - structured session
+ summaries, idea-lineage, episodic note history (v1.11.0) (#100)
+56dd3dd fix(hermes): bridge EOF - byte streams, stderr drain, retry loop (#92)
+35b824e feat: Recall & Working-Memory Quality Suite - selectable profiles,
+ usage decay, co-occurrence, file-context (v1.10.0) (#99)
+929d54c feat: Brain Portability & Interop Suite - bank export/import, page
+ contract, brain_create_note, in-process SDK (v1.9.0) (#98)
+7cdbfc0 feat: Indexer Durability & Resilience Suite - cooperative abort,
+ graceful watch shutdown, resumable reindex (v1.8.0) (#97)
+8b679fe feat: Knowledge Provenance Suite (v1.7.0) (#96)
+6e59a42 feat: Vault Integrity & Trust Suite (v1.6.0) (#95)
+e4df212 feat: Search & Recall Quality Suite (v1.5.0) (#93)
+0340560 feat: Continuity, Hygiene & Freshness Suite (v1.3.0) (#87)
+8972f13 refactor: SOLID/DRY decomposition (v1.2.0) (#86)
+
+================================================================
+ACTIVE ENGINEERING CONVENTIONS
+================================================================
+
+- New telemetry is opt-in, fail-open, payload-safe (hashes not raw text).
+- Every release lands as additive, option-gated surfaces; defaults stay
+ byte-identical. CHANGELOG follows Keep a Changelog; SemVer.
+- CLI verbs live under src/cli/brain/verbs/; MCP tools under
+ src/mcp/brain/; core logic under src/core/brain/. Wrappers are thin
+ delegations over a core module. Tests: focused unit + CLI/MCP parity.
+- Version is bumped only via `bun run scripts/sync-version.ts` (single
+ source: package.json version, mirrored to plugin manifests).
+
+Now produce the three variants and the single recommendation.
diff --git a/docs/brainstorm/hindsight-brain-loop-ops/design.md b/docs/brainstorm/hindsight-brain-loop-ops/design.md
new file mode 100644
index 00000000..ac141a8b
--- /dev/null
+++ b/docs/brainstorm/hindsight-brain-loop-ops/design.md
@@ -0,0 +1,326 @@
+# Hindsight brain-loop ops design
+
+Branch: `feat/hindsight-brain-loop-ops`
+Variants: `docs/brainstorm/hindsight-brain-loop-ops/variants.md`
+Plan: `docs/brainstorm/hindsight-brain-loop-ops/plan.md`
+
+## Problem
+
+Two upstream Hindsight features address the LLM-usage layer of the
+brain loop: per-operation LLM request tracing (token usage, latency,
+model, and memory linkage), and provider prompt-prefix caching for
+repeated operations (retain / consolidate / reflect). Both are written
+for a brain that calls an LLM itself.
+
+Open Second Brain has a load-bearing invariant the Hindsight brain does
+not: the kernel never calls an LLM. The calling agent owns all
+generation; Open Second Brain owns sequencing, deterministic
+computation, validation, and the atomic commit. So neither feature can
+be ported verbatim. Today Open Second Brain has no persistent record of
+the LLM usage the agent performs on behalf of brain operations, and no
+structural guarantee that the prompts it hands the agent have a stable,
+cacheable prefix across repeated calls.
+
+The release must therefore deliver the OPERATIONAL VALUE of both
+features (request observability and prompt-cost efficiency) without the
+kernel ever calling an LLM, without persisting raw prompt text, and
+without changing any default behaviour.
+
+## Scope
+
+- Add an opt-in, fail-open inbound tracing surface: the agent reports
+ back the real usage of a generation it performed for a brain handoff
+ (write-session step, context-pack consume, or dream-stage proposal),
+ and Open Second Brain stores it as an additive continuity record
+ correlated to the paths and ids it already owns. Cover t_281c3edc.
+- Add a structural prompt-prefix stability layer: a deterministic
+ prefix construction in the existing prompt builders plus a run-level
+ metric that reports prefix stability across repeated calls. Cover
+ t_d8c1f7d9.
+- Add read surfaces (CLI verb and MCP tool) for the tracing records so
+ operators and agents can list and summarise generation usage with
+ memory linkage.
+- Document and test both surfaces through focused unit, CLI, and MCP
+ coverage.
+
+## Out of scope
+
+- The kernel calling an LLM, an OpenTelemetry GenAI recorder around LLM
+ calls, or any direct provider HTTP call inside `src/core`.
+- Persisting raw prompt text or model output. Only hashes, lengths,
+ redacted metadata, and counts are stored.
+- Inferring provider cache-hit rates. The release measures prefix
+ STABILITY (structural), which is all the kernel can know; it does not
+ claim to measure provider cache performance.
+- A new `src/core/brain/generation/` seam that refactors write-session,
+ context-pack, and dream behind one abstraction (Variant 3, deferred).
+- A control-plane UI tab. Open Second Brain is vault-Markdown-first; the
+ read surface is a CLI verb and an MCP tool, not a dashboard.
+- Changing the default shape of the write-session envelope, the
+ context_receipt record, the dream_stage metric, or recall_telemetry
+ when no new option is supplied.
+
+## Chosen approach
+
+Use Variant 1: Extend continuity + metrics layers (reuse-first).
+
+Both cards land as two opt-in, additive surfaces on infrastructure the
+project already audits.
+
+Tracing (t_281c3edc) becomes a new opt-in inbound continuity kind,
+`generation_report`. After the agent fulfils a generation handoff it
+optionally posts back the real usage (provider, model, finish reason,
+latency, input/output/cached/total tokens) plus the handoff reference.
+Open Second Brain stores this as a continuity record whose `sourceRefs`
+are the paths and ids the kernel already owns (the write-session
+session id, the context-receipt id, the dream run id, and the memory
+paths involved), so memory <-> trace linkage is a `sourceRefs` join the
+read-model already performs. The local token estimate
+(`token-footprint.ts`) is always attached for comparison, and real
+usage is present only when the inbound report arrives; absent is
+reported as absent. The whole surface is gated by `emitGatedTelemetry`
+(opt-in, fail-open) and payload-safe through `safeContinuityPayload`,
+so no raw prompt or output is ever persisted.
+
+Caching (t_d8c1f7d9) becomes a structural prefix-stability guarantee
+plus a run-level metric. A small pure helper (`src/core/brain/prompt-prefix.ts`)
+defines the deterministic-prefix contract the write-session prompt
+builder and the context-pack builder already nearly satisfy: the prefix
+is a function of stable inputs only (no timestamps, no random, sorted
+keys), so the same inputs produce byte-identical prefix bytes across
+repeated calls, which is exactly what a provider prefix cache rewards.
+A new run-level metric surface, `prompt_prefix`
+(`Brain/metrics/prompt_prefix.jsonl`), reports per-pass prefix
+stability: the prefix hash, prefix length, the number of calls in the
+pass, and how many reused the same prefix. This measures what the
+kernel can know (structural stability), honestly distinct from what it
+cannot (provider cache-hit rate).
+
+We agree with the consultant recommendation. Variant 1 is the only
+variant that covers all three handoff shapes, honours every binding
+constraint, and stays within the operator's deliberate "two minor,
+closely related, low-risk tasks" scope. Variant 2 leaves context-pack
+and dream under-covered, and Variant 3 front-loads an abstraction the
+two cards do not yet earn.
+
+## Design decisions
+
+1. The traced unit is the agent's inbound report, not an LLM call the
+ kernel makes.
+ - The kernel cannot observe an LLM call it never makes. Tracing is
+ therefore an opt-in INBOUND path: the agent reports back after it
+ generates. The kernel keys the report by the handoff ref and the
+ paths/ids it already owns, never inventing an LLM message id.
+ - Honest asymmetry: the local estimate is always present; real usage
+ is present only when the agent reports it. A missing real-usage
+ block is normal, not a failure.
+
+2. Reuse the continuity store and metrics layer; do not add a parallel
+ store or a new module.
+ - `generation_report` is a new continuity kind under the existing
+ `o2b.continuity.v1` envelope, dedup id, payload-safety, and
+ read-model. No new directory, no new lifecycle.
+ - `prompt_prefix` is a new metrics surface under the existing
+ `o2b.metrics.v1` envelope (run-level, O_APPEND, < 4 KiB).
+ - Both reuse `emitGatedTelemetry` so the gate-off path never
+ constructs a payload and a throwing build is swallowed.
+
+3. Opt-in, fail-open, payload-safe by construction.
+ - Tracing is gated by a per-call option (MCP/CLI param) and/or a
+ config key (default off). When off, no payload object is built.
+ - Caching is default-on structurally (the prefix builders already
+ produce stable output in practice) but the METRIC is opt-in
+ (default off), so default behaviour is byte-identical.
+ - No raw prompt or model output is stored: `prompt_hash` (sha-256
+ prefix) and `prompt_chars` only; counts and metadata only for
+ usage. `safeContinuityPayload` strips `<private>` regions and
+ redacts secret-shaped tokens.
+
+4. Additive-only schema evolution.
+ - `generation_report` is an additive kind; existing readers skip
+ unknown kinds. Its payload fields are additive-optional. Renames
+ or removals would bump to `o2b.continuity.v2`; this release adds
+ none.
+ - `prompt_prefix` is an additive metrics surface; consumers ignore
+ unknown surface files. Payload fields are additive-optional.
+
+5. Default behaviour is byte-identical.
+ - With tracing off and the metric off, the write-session envelope,
+ the context_receipt record, the dream_stage metric, and
+ recall_telemetry keep their current shapes exactly.
+ - The prefix-stability guarantee is non-observable to existing
+ consumers (it constrains builder internals, not output shape) and
+ is locked by a regression test that asserts byte-stable prefixes
+ for the same inputs.
+
+6. Language-agnostic and provider-agnostic.
+ - No natural-language keyword lists anywhere. The prefix contract is
+ structural (ordering, hashing), independent of any language.
+ - Provider and model are opaque agent-reported strings; the kernel
+ never branches on them and never implies it calls them.
+
+## Report contracts
+
+### generation_report continuity record
+
+Envelope: `o2b.continuity.v1`. `kind: "generation_report"`. `id` is the
+sha-256 content-hash over `kind + createdAt + sourceRefs + payload`
+(existing `recordId` rule). Stored under
+`Brain/log/continuity/<month>.jsonl`.
+
+`sourceRefs` join the report to vault artifacts: for a write-session
+step, the session id and the `target_path`; for a context-pack consume,
+the context-receipt id and the surfaced item paths; for a dream-stage
+proposal, the dream `run_id` and the affected preference paths.
+
+`payload` (all usage and report fields optional except `handoff` and
+`local_estimate`):
+
+```
+{
+ handoff: { kind: "write_session" | "context_pack" | "dream_stage", ref: <id> },
+ agent: <string>,
+ scope: <optional string>,
+ provider: <optional, agent-reported>,
+ model: <optional, agent-reported>,
+ finish_reason: <optional>,
+ latency_ms: <optional>,
+ prompt_hash: <sha-256 prefix of the handoff prompt>,
+ prompt_chars: <number>,
+ local_estimate: { input_tokens: <token-footprint estimate, always present> },
+ usage: { // agent-reported, all optional
+ input_tokens?, output_tokens?, cached_tokens?, total_tokens?
+ }
+}
+```
+
+Read surface: `o2b brain generation-reports list|summary` and MCP
+`brain_generation_reports` (action `list` | `summary`). `summary`
+aggregates calls, total/estimated tokens, and the per-handoff-kind
+breakdown, and joins `sourceRefs` so a memory path links back to the
+generation reports that produced or consumed it. Unknown payload fields
+are ignored.
+
+### prompt_prefix metric record
+
+Envelope: `o2b.metrics.v1`. `surface: "prompt_prefix"`. One line per
+generation pass (run-level), under `Brain/metrics/prompt_prefix.jsonl`.
+
+```
+{
+ schema: "o2b.metrics.v1",
+ surface: "prompt_prefix",
+ run_at: <ISO>,
+ payload: {
+ handoff: { kind: "write_session" | "context_pack" | "dream_stage" },
+ prefix_hash: <sha-256 of the deterministic prefix>,
+ prefix_chars: <number>,
+ call_count: <number of calls in the pass>,
+ stable_count: <number of calls whose prefix matched prefix_hash>,
+ run_ref: <optional id of the pass, e.g. dream run_id>
+ }
+}
+```
+
+Read surface: the existing `listMetrics` reader
+(`src/core/brain/metrics.ts`) returns the new surface with no code
+change beyond registration; no new CLI verb is required for the metric
+(the metrics reader already covers arbitrary surfaces).
+
+### prompt-prefix helper contract
+
+`src/core/brain/prompt-prefix.ts` exposes pure functions:
+
+- `deterministicPrefix(inputs): { prefix: string, hash: string, chars: number }`
+ - Builds the stable prefix from inputs only (no `Date.now`, no random,
+ sorted keys, stable whitespace). The same inputs always yield the
+ same bytes.
+- `isStable(current, prior): boolean`
+ - True when `current.hash === prior.hash` for the same handoff kind.
+
+The write-session prompt construction (`personaPrompt` / `synthesisPrompt`
+in `write-session/panel.ts`, surfaced on the `needs-llm-step` envelope
+emitted by `write-session/engine.ts`) and the context-pack builder
+(`packContext` in `context-pack.ts`) route their stable preamble segment
+through this helper. A regression test asserts byte-stable prefixes for
+identical inputs across repeated calls.
+
+## File changes
+
+Expected implementation touchpoints:
+
+- `src/core/brain/continuity/types.ts` - document the new
+ `generation_report` kind (additive; no envelope version bump).
+- `src/core/brain/continuity/emit.ts` (or the write/ingest helper) -
+ `emitGenerationReport(vault, input)` gated by `emitGatedTelemetry`.
+- `src/core/brain/continuity/read-model.ts` - lift the new kind's
+ handoff ref into a first-class field for the join, additive.
+- `src/core/brain/continuity/redaction.ts` - ensure `generation_report`
+ payload passes `safeContinuityPayload` (prompt_hash only, no raw
+ prompt; usage counts only).
+- `src/core/brain/prompt-prefix.ts` - new pure helper (deterministic
+ prefix + stability check).
+- `src/core/brain/write-session/panel.ts` (and `engine.ts` where the
+ `needs-llm-step` envelope is built) - route the generation prompt
+ preamble (`personaPrompt` / `synthesisPrompt` output) through
+ `deterministicPrefix`. NOTE: no prompt builder lives in `validate.ts`;
+ its only prompt is `buildCorrectionPrompt`, which is unrelated and
+ must NOT be touched.
+- `src/core/brain/context-pack.ts` - route the stable preamble segment
+ of `packContext`'s output through `deterministicPrefix`.
+- `src/core/brain/metrics.ts` - NO change for the metric itself: the
+ reader is surface-agnostic (`appendMetric` validates the surface name
+ by regex and writes `Brain/metrics/<surface>.jsonl`; `listMetrics`
+ auto-discovers all `*.jsonl` files). The `prompt_prefix` emission
+ point lives at the call site that runs a generation pass (see
+ t_d8c1f7d9 plan), exactly as `dream-stage.ts` already emits
+ `dream_stage` with no registration.
+- `src/cli/brain/verbs/generation-reports.ts` - new CLI verb
+ `o2b brain generation-reports list|summary`.
+- `src/cli/brain/verbs/index.ts`, `src/cli/brain/help-text.ts`,
+ `src/cli/command-manifest.ts` - register the new verb, help, command
+ manifest.
+- `src/mcp/brain/` - add the `brain_generation_reports` tool (action
+ `list` | `summary`) to the most fitting existing tool module by
+ cohesion (e.g. `analytics-tools.ts` or `health-tools.ts`) or a new
+ `generation-tools.ts`, and register it in the MCP manifest. There is
+ no single "generation/observability" module today.
+- Inbound report write path: a CLI verb (e.g.
+ `o2b brain generation-report` or an MCP tool action) the agent calls
+ to post the usage back, gated opt-in.
+- Tests:
+ `tests/core/brain/continuity-generation-report.test.ts`,
+ `tests/core/brain/prompt-prefix.test.ts`,
+ `tests/cli/brain-generation-reports.test.ts`,
+ MCP parity test for `brain_generation_reports`, and a regression test
+ asserting default byte-identical output when no option is set.
+- `docs/observability.md` - document the `generation_report` continuity
+ kind and its fail-open/payload-safety rules.
+- `docs/metrics.md` - document the `prompt_prefix` surface and payload.
+- `docs/cli-reference.md`, `docs/mcp.md` - document the new verb and
+ tool.
+- `CHANGELOG.md` - Keep a Changelog entry.
+
+## Risks
+
+- Tracing can drift toward the kernel calling an LLM. Mitigation: the
+ inbound report is the only path; a regression test pins that no
+ `fetch`/provider call is added under `src/core` for this feature.
+- Raw prompt text could leak into a record. Mitigation: only
+ `prompt_hash` + `prompt_chars` are stored; `safeContinuityPayload`
+ redaction and a test that asserts no raw prompt survives to disk.
+- The prefix-stability guarantee could be claimed as provider
+ cache-hit measurement. Mitigation: the metric and docs name it
+ "stability" (structural), explicitly distinct from provider
+ cache-hit rate the kernel cannot observe.
+- Default output could drift when the prefix builder is wired in.
+ Mitigation: the builder only constrains internal ordering, not output
+ shape; a regression test asserts byte-identical envelopes and
+ receipts when no option is set.
+- New CLI/MCP surface area increases documentation burden. Mitigation:
+ keep wrappers thin, reuse the metrics reader for the metric surface,
+ and document the structured record once.
+- The two cards touch overlapping files (continuity, metrics, prompt
+ builders). Mitigation: drive them one at a time on the shared branch
+ per the plan, with the tracing card landing first so the prefix
+ helper can reuse its prompt_hash convention.
diff --git a/docs/brainstorm/hindsight-brain-loop-ops/plan.md b/docs/brainstorm/hindsight-brain-loop-ops/plan.md
new file mode 100644
index 00000000..30e3ef2b
--- /dev/null
+++ b/docs/brainstorm/hindsight-brain-loop-ops/plan.md
@@ -0,0 +1,167 @@
+# Hindsight brain-loop ops implementation plan
+
+Branch: `feat/hindsight-brain-loop-ops`
+Design: `docs/brainstorm/hindsight-brain-loop-ops/design.md`
+Release scope (ships together): t_281c3edc (LLM request tracing) and
+t_d8c1f7d9 (prompt-prefix caching).
+
+Cards are driven ONE AT A TIME on this shared branch. Each worker must
+build on (git aware) the commits the previously-driven in-scope card
+already landed, and must not duplicate or conflict with the sibling
+task. Follow each section under TDD.
+
+## t_281c3edc - [upstream:hindsight] Per-bank LLM request tracing via OTel GenAI recorder
+
+### Files
+
+- `src/core/brain/continuity/types.ts` - document the new
+ `generation_report` continuity kind (additive; no envelope version
+ bump).
+- `src/core/brain/continuity/emit.ts` or a new
+ `src/core/brain/continuity/generation-report.ts` -
+ `emitGenerationReport(vault, input)` gated by `emitGatedTelemetry`
+ (opt-in; the build thunk is never invoked on the gate-off path).
+- `src/core/brain/continuity/read-model.ts` - lift the new kind's
+ handoff ref into a first-class join field (additive).
+- `src/core/brain/continuity/redaction.ts` - route the new payload
+ through `safeContinuityPayload`; store `prompt_hash` + `prompt_chars`
+ and usage counts only, never raw prompt or model output.
+- Inbound report write path (CLI verb and/or MCP tool action) the agent
+ calls to post usage back after fulfilling a write-session step, a
+ context-pack consume, or a dream-stage proposal.
+- `src/cli/brain/verbs/generation-reports.ts` - new read verb
+ `o2b brain generation-reports list|summary`.
+- `src/cli/brain/verbs/index.ts`, `src/cli/brain/help-text.ts`,
+ `src/cli/command-manifest.ts` - register the verb, help, manifest.
+- `src/mcp/brain/` (current observability/generation tool module) -
+ register `brain_generation_reports` (action `list` | `summary`).
+- `docs/observability.md` - document the `generation_report` kind and
+ its fail-open / payload-safety rules.
+- `docs/cli-reference.md`, `docs/mcp.md` - document the new verb/tool.
+- `CHANGELOG.md` - entry.
+- Tests: `tests/core/brain/continuity-generation-report.test.ts`,
+ `tests/cli/brain-generation-reports.test.ts`, MCP parity test for
+ `brain_generation_reports`, no-consumer regression test (gate off =>
+ no payload built), and a test asserting no raw prompt text reaches
+ disk.
+
+### Acceptance
+
+A focused test suite passes that proves:
+
+- Emitting a `generation_report` with the gate ON writes one continuity
+ record under `Brain/log/continuity/<month>.jsonl` with envelope
+ `o2b.continuity.v1`, `kind: "generation_report"`, and a content-hash
+ `id` (same inputs => same id).
+- With the gate OFF, no payload object is built and no record is
+ written (the `emitGatedTelemetry` no-consumer guarantee).
+- The record carries `prompt_hash` and `prompt_chars` and usage counts
+ only; an assertion reads the persisted file and confirms no raw
+ prompt or model output is stored.
+- `local_estimate.input_tokens` is always present; the agent-reported
+ `usage` block is optional and its absence is reported as absent, not
+ fabricated.
+- `sourceRefs` join the report to the handoff target (write-session
+ session id, context-receipt id, or dream run id) and the memory
+ paths involved, so `summary` links a memory path back to its
+ generation reports.
+- A throwing build thunk is swallowed and the primary operation
+ completes normally (fail-open).
+- With the feature off, existing continuity records, the write-session
+ envelope, the context_receipt record, and recall_telemetry keep their
+ current shapes byte-for-byte.
+- No `fetch`/provider HTTP call was added under `src/core` for this
+ feature (grep-guarded regression test).
+
+Suggested verification command for the worker:
+
+```bash
+bun test tests/core/brain/continuity-generation-report.test.ts tests/cli/brain-generation-reports.test.ts <new MCP parity test>
+bun run typecheck
+bun run lint
+```
+
+### Depends on
+
+No sibling task needs to land first. Build this card FIRST on the
+branch: it establishes the `prompt_hash` convention, the inbound-report
+write path, and the read surface that the prompt-prefix card reuses.
+
+## t_d8c1f7d9 - [upstream:hindsight] LLM prompt-prefix caching for retain/consolidate/reflect
+
+### Files
+
+- `src/core/brain/prompt-prefix.ts` - new pure helper:
+ `deterministicPrefix(inputs)` returning `{ prefix, hash, chars }`
+ (stable inputs only: no `Date.now`, no random, sorted keys) and
+ `isStable(current, prior)` (true when hashes match for the same
+ handoff kind).
+- `src/core/brain/write-session/panel.ts` (and `engine.ts` where the
+ `needs-llm-step` envelope is built) - route the generation prompt
+ preamble (`personaPrompt` / `synthesisPrompt`) through
+ `deterministicPrefix`. NOTE: no prompt builder lives in `validate.ts`
+ (only `buildCorrectionPrompt`, unrelated and out of scope); the design
+ was corrected in Phase 1 review to point at the real builders.
+- `src/core/brain/context-pack.ts` - route the stable preamble segment
+ of `packContext`'s output through `deterministicPrefix`.
+- `src/core/brain/metrics.ts` - NO change for the metric itself: the
+ reader is surface-agnostic. The emission point calls
+ `appendMetric(vault, { surface: "prompt_prefix", runAt, payload })`
+ and `listMetrics` discovers it automatically. This mirrors how
+ `dream-stage.ts` already emits the `dream_stage` surface with no
+ registration anywhere.
+- Emission point for the run-level `prompt_prefix` metric (a dream pass
+ or write-session batch emits one record per pass), opt-in via the
+ existing metrics fail-soft path. Lives at the call site that runs a
+ generation pass, NOT in `metrics.ts`.
+- `docs/metrics.md` - document the `prompt_prefix` surface, payload,
+ and the explicit "stability (structural), not provider cache-hit
+ rate" framing.
+- `docs/observability.md` - cross-reference the prefix-stability layer
+ if needed.
+- `CHANGELOG.md` - entry.
+- Tests: `tests/core/brain/prompt-prefix.test.ts`,
+ `tests/core/brain/metrics-prompt-prefix.test.ts`, and a regression
+ test asserting byte-stable prefixes for identical inputs across
+ repeated calls plus byte-identical default write-session envelope and
+ context_receipt when no option is set.
+
+### Acceptance
+
+A focused test suite passes that proves:
+
+- `deterministicPrefix` returns byte-identical `prefix` and `hash` for
+ identical inputs across repeated calls, and differs predictably when
+ inputs change.
+- Routing the write-session prompt preamble and the context-pack
+ preamble through the helper does not change the default
+ `WriteSessionEnvelope` or `context_receipt` shape when no option is
+ set (byte-identical regression).
+- A generation pass with the metric ON writes one run-level
+ `prompt_prefix` record under `Brain/metrics/prompt_prefix.jsonl` with
+ envelope `o2b.metrics.v1`, carrying `prefix_hash`, `prefix_chars`,
+ `call_count`, and `stable_count`.
+- With the metric OFF, no `prompt_prefix` record is written and the
+ pass output is byte-identical to today.
+- The metric and docs name the measure "stability" (structural) and do
+ not claim provider cache-hit measurement the kernel cannot observe.
+- `listMetrics(vault, { surface: "prompt_prefix" })` returns the new
+ surface with no `metrics.ts` change (the reader is surface-agnostic;
+ emission via `appendMetric` is sufficient, exactly as for
+ `dream_stage`).
+
+Suggested verification command for the worker:
+
+```bash
+bun test tests/core/brain/prompt-prefix.test.ts tests/core/brain/metrics-prompt-prefix.test.ts
+bun run typecheck
+bun run lint
+```
+
+### Depends on
+
+Run AFTER `t_281c3edc` on the same branch. The prefix helper reuses
+the `prompt_hash` convention the tracing card established, and the
+run-level metric emission can reuse the same fail-soft metrics path.
+The implementation must build on the tracing card's commits (git aware)
+and must not re-introduce a parallel store or a new architectural seam.
diff --git a/docs/brainstorm/hindsight-brain-loop-ops/variants.md b/docs/brainstorm/hindsight-brain-loop-ops/variants.md
new file mode 100644
index 00000000..03a3d945
--- /dev/null
+++ b/docs/brainstorm/hindsight-brain-loop-ops/variants.md
@@ -0,0 +1,121 @@
+# Hindsight brain-loop ops variants
+
+Branch: `feat/hindsight-brain-loop-ops`
+In-scope cards: t_281c3edc (LLM request tracing), t_d8c1f7d9 (prompt-prefix caching).
+
+## Consultant variants
+
+The variants below were produced by the consultant (claude-opus-4-8)
+from the brief at `cli-output/prompt.md`. They are reproduced verbatim
+from `cli-output/claude.md`.
+
+## Variant 1: Extend continuity + metrics layers (reuse-first)
+Approach: Treat both cards as additive surfaces on the infrastructure
+that already exists. Tracing becomes a new opt-in inbound continuity
+kind, `generation_report`, that the agent posts back after fulfilling
+any handoff (write-session submit, context-pack consume, dream
+proposal), carrying agent-reported usage (provider/model, real
+input/output/cached/total tokens, finish reason, latency) plus the
+local token estimate for comparison. Caching becomes a deterministic
+prefix-construction rule in the existing prompt builders plus a
+`prompt_prefix` metric surface that reports prefix-stability across
+repeated calls.
+Trade-offs:
+- Smallest blast radius: no new store, no new module, no new lifecycle.
+ Both cards are pure additive surfaces under rules already audited
+ (gate pattern, `safeContinuityPayload`, content-hash dedup).
+- Memory <-> trace linkage falls out of `sourceRefs` (paths/ids the
+ kernel already knows); honest by construction, since the kernel never
+ invents an LLM message id.
+- The asymmetry is surfaced cleanly: estimate is always present, real
+ usage is present only when the inbound report arrives, and absent is
+ reported as absent.
+- Weaker uniformity: each of the three seams wires the inbound report
+ itself, so there is mild duplication and no single "generation trace"
+ abstraction to grow into later.
+Complexity: small
+Risk: low
+
+## Variant 2: Write-session engine as the canonical trace unit
+Approach: Anchor both cards on the write-session lifecycle, the one
+seam that already has a durable record, audit event, attempts, and
+terminal transitions. Tracing extends the submit path with an opt-in
+agent-reported usage block and records latency/attempts into the
+existing `write-session` audit event, with `session_id <->
+target_path` as the memory link. Caching adds a deterministic,
+separately hashed `cache_prefix` segment to the envelope plus advisory
+cache-control hints the agent may honour.
+Trade-offs:
+- Highest-fidelity trace where it matters most: the write-session
+ already models open -> needs-llm-step -> submit -> terminal, so usage,
+ attempts, and latency attach to a real state machine rather than a
+ fresh log line.
+- Reuses the existing chokepoint (`appendLogEvent`), so audit ordering
+ and the one-event-per-terminal-transition guarantee are preserved for
+ free.
+- Coverage gap: context-pack and dream handoffs are not write-sessions,
+ so they get little or no tracing and no shared prefix builder; the
+ release covers one seam deeply and two shallowly.
+- Modifying the submit path and envelope risks shape drift on a
+ load-bearing record; needs careful flag-gating to keep default bytes
+ identical.
+Complexity: medium
+Risk: medium
+
+## Variant 3: Dedicated generation-observability module
+Approach: Introduce `src/core/brain/generation/` as a unified seam that
+all three handoffs (write-session, context-pack, dream) describe
+themselves through, emitting one "generation handoff descriptor" and
+accepting one opt-in inbound "generation report" via a new CLI verb and
+MCP tool. The module owns a single deterministic prefix builder shared
+by all three seams and a `prompt_prefix` metric surface, giving one
+consistent trace ledger and one caching guarantee across the whole brain
+loop.
+Trade-offs:
+- Most coherent long-term shape: one abstraction, one reader, uniform
+ linkage and prefix construction across every generation point.
+- Best leverage for future handoff shapes, which only need to implement
+ the descriptor rather than wire telemetry themselves.
+- Largest change for a release the operator deliberately scoped to two
+ minor, closely related tasks; it adds a new module, a new inbound
+ path, and refactors three seams at once.
+- Higher regression surface and review cost; risks introducing a
+ parallel store/abstraction the brief explicitly cautions against, and
+ front-loads design the two cards do not yet require.
+Complexity: large
+Risk: high
+
+## Recommended: Variant 1
+Rationale: It satisfies every binding constraint with the least new
+surface area: opt-in, fail-open, payload-safe, additive-only, and
+byte-identical by default, all by reusing the continuity gate and the
+metrics layer rather than inventing a parallel store. It answers the
+key design question honestly: the traced unit is the agent's inbound
+generation report keyed by the paths/ids the kernel already owns, and
+caching is delivered structurally as a byte-stable prefix with a
+stability metric, never as a provider call. It covers all three handoff
+shapes without committing to a premature abstraction, which is the right
+altitude for a release deliberately scoped to two minor, closely related
+cards. Variant 2 leaves context-pack and dream under-covered, and
+Variant 3's uniformity is not yet earned and carries regression and
+parallel-store risk that this scope does not justify.
+
+## Final decision
+
+Chosen variant: Variant 1, Extend continuity + metrics layers
+(reuse-first).
+
+I agree with the consultant recommendation. The operator scoped this
+release to two minor, closely related tasks and asked for it to stay
+deliberately small and low-risk, which Variant 1 honours directly: it
+adds two opt-in, fail-open, additive surfaces on infrastructure the
+project already audits (the continuity gate and the metrics layer)
+instead of a new module or a modified load-bearing record. It also maps
+both Hindsight features onto Open Second Brain's "kernel never calls an
+LLM, the agent owns generation" model without distortion: tracing is the
+agent's inbound usage report keyed by paths and ids the kernel already
+knows, and caching is a structural, byte-stable prefix plus a stability
+metric rather than a provider call the kernel cannot make. Variant 2's
+coverage gap (context-pack and dream get little tracing) and Variant 3's
+premature, high-regression abstraction are both poor fits for this
+scope.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index bfb5954b..f23cc41e 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -68,6 +68,7 @@ o2b brain import-session Replay signals from a registered agent session .js
o2b brain session-hook Internal hook bridge: read one lifecycle payload from stdin, capture prompt markers / brain_feedback, append lifecycle audit/log rows
o2b brain context-receipts List/show opt-in prompt context receipt continuity records (since v0.29.0)
o2b brain recall-telemetry List/summarise opt-in recall telemetry continuity records (since v0.29.0)
+o2b brain generation-reports Record/list/summarise opt-in inbound LLM generation traces (prompt hash + token counts only; kernel never calls an LLM)
o2b brain context-presets Show/suggest/diff read-only context budget presets (since v0.29.0)
o2b brain pre-compact-extract Extract decision/commitment/outcome/rule/open-question continuity records from bounded text (since v0.29.0)
o2b brain session-grep Search imported session recall raw turns and summary nodes (since v0.29.0)
@@ -110,6 +111,7 @@ o2b brain unlinked Raw-text mentions outside `[[...]]` (Unicode-aware
o2b brain context-pack Existing budgeted context pack; add --receipt to emit a context receipt, --telemetry to emit redacted recall telemetry, --cache-stable for stable ordering diagnostics, and --dedup-repeated for repeated-context reference hints
o2b brain context-receipts list [--trigger context_pack|pre_compress] [--host <name>] [--session-id <id>] [--limit <n>] [--json]; show <receipt-id> [--json]
o2b brain recall-telemetry list|summary [--mode search|context_pack|pre_compress] [--status ok|empty|error|timeout] [--host <name>] [--since <iso>] [--until <iso>] [--limit <n>] [--json]
+o2b brain generation-reports record <write_session|context_pack|dream_stage> --ref <id> --agent <name> --prompt <text> [--enable] [--provider <p>] [--model <m>] [--finish-reason <r>] [--latency-ms <n>] [--input-tokens <n>] [--output-tokens <n>] [--cached-tokens <n>] [--total-tokens <n>] [--scope <s>] [--source <id[=path]>...] [--created-at <iso>] [--json]; list|summary [--handoff <kind>] [--agent <name>] [--since <iso>] [--until <iso>] [--limit <n>] [--json]; show <report-id> [--json] - record is gated (default off) by --enable or generation_trace_enabled; stores prompt_hash + counts only
o2b brain context-presets show [tight-context|long-context] --json; suggest --model <name> --context-window <tokens> --json; diff <preset-id> [current-value flags] [--override <path>...] --json
o2b brain pre-compact-extract --session-id <id> --turn-start <id> --turn-end <id> --text <bounded-text> [--host <name>] [--max-chars <n>] [--json]
o2b brain import-session <path> --recall [--recall-session-id <id>] [--recall-summary-group-size <n>] [--json]
diff --git a/docs/mcp.md b/docs/mcp.md
index 4d45fec4..4ba4d029 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -49,6 +49,7 @@ flags for a narrower per-process full server.
| `brain_context_pack` | Budgeted context slice; pass `lanes: true` to return directives, constraints, and consider lanes. Filtered items include `safety.reasons`. | `max_tokens` |
| `brain_context_receipts` | List or show opt-in prompt context receipt continuity records with budgets, hashes, source refs, safety/redaction metadata, and item IDs. | `operation` |
| `brain_recall_telemetry` | List or summarise opt-in recall telemetry records for search, context-pack, and pre-compress calls. | `operation` |
+| `brain_generation_reports` | Inbound, opt-in LLM generation tracing: `record` posts a generation's usage for a handoff (gated, default off; stores prompt hash + token counts only); `list`/`summary` read records and join them to memory paths. Kernel never calls an LLM. | `action` |
| `brain_context_presets` | Show, suggest, or diff read-only context budget presets (`tight-context`, `long-context`) without writing config. | `operation` |
| `brain_pre_compact_extract` | Extract decision/commitment/outcome/rule/open-question records from bounded text into continuity storage. | `session_id`, `turn_start`, `turn_end`, `text` |
| `brain_hygiene` | Memory hygiene: `scan` findings (conflicts, dedup, freshness, usefulness), `apply` selected ids, `refresh` stale pages. Resolver command comes from `_brain.yaml` only. | `mode` |
@@ -105,8 +106,12 @@ weights (applied to ranking only when `search_learned_weights_enabled` is on).
`brain_context_pack` accepts opt-in `receipt`, `telemetry`, `cache_stable`, and
`dedup_repeated` diagnostics; `brain_pre_compress_pack` accepts opt-in `receipt`
and `telemetry`. `brain_context_receipts` supports `operation: "list"|"show"`;
-`brain_recall_telemetry` supports `operation: "list"|"summary"`; and
-`brain_context_presets` supports `operation: "show"|"suggest"|"diff"`.
+`brain_recall_telemetry` supports `operation: "list"|"summary"`;
+`brain_context_presets` supports `operation: "show"|"suggest"|"diff"`; and
+`brain_generation_reports` supports `action: "record"|"list"|"summary"` -
+`record` is gated (default off) by a per-call `enable` flag or the
+`generation_trace_enabled` config and persists only `prompt_hash` plus token
+counts, never the prompt.
`brain_pre_compact_extract` writes idempotent typed continuity records after
deterministic media/base64 sanitization. `brain_session_grep`,
`brain_session_describe`, and `brain_session_expand` inspect the opt-in session
diff --git a/docs/metrics.md b/docs/metrics.md
index 982311f6..4d348458 100644
--- a/docs/metrics.md
+++ b/docs/metrics.md
@@ -63,6 +63,7 @@ writes, and a metric record is a summary, not a report.
| `recall_benchmark` | `o2b brain benchmark run`, MCP `brain_benchmark` | `total`, `k`, `expand`, `hit_at_k`, `mrr`, `misses` |
| `self_tuning` | `o2b brain tune run`, MCP `brain_tune` | `chosen`, `evaluated`, `best_mrr`, `dataset_hash` |
| `dream_stage` | `o2b brain dream stage` / `apply`, MCP `brain_dream` (since 1.0.0) | `action` (`stage`/`apply`), `run_id`, `proposals`, `sources`, `changed`; apply adds `new_unconfirmed`, `confirmed`, `retired` counts |
+| `prompt_prefix` | decision-panel commit (opt-in `promptPrefixMetric`), context-pack consume (opt-in `promptPrefix`) | `kind` (`write_session`/`context_pack`), `prefix_hash` (sha-256 of the stable preamble), `prefix_chars`, `call_count`, `stable_count` |
Payload fields marked "(lane runs)" appear only on maintenance-lane
emissions. All fields are additive-optional from a consumer's point
@@ -80,3 +81,22 @@ of view: render what is present, ignore what is unknown.
- Metric emission is fail-soft everywhere: a metrics-layer problem
never fails the pass that produced the numbers, so gaps in a file
mean the run failed or predates the layer - not data corruption.
+
+## `prompt_prefix`: stability, not provider cache-hit rate
+
+The `prompt_prefix` surface measures STRUCTURAL prefix stability - how
+many generation handoffs in one pass led with byte-identical preamble
+bytes (`stable_count` of `call_count`). It deliberately does NOT claim
+to measure a provider's cache-hit rate: the kernel never calls an LLM,
+so it cannot observe whether a provider actually reused a cached prefix.
+What it can guarantee, and what this metric reports, is that the kernel
+handed the agent a stable, cache-eligible prefix across the pass - the
+precondition a provider prefix cache rewards. The raw prompt is never
+stored; only the sha-256 hash and the code-point length of the prefix.
+
+The genuine multi-call pass is the decision panel (every persona step
+and the synthesis share the `Decision topic:` frame, so a fully stable
+pass reports `stable_count == call_count == personas + 1`). A
+context-pack consume is a single-call pass over its stable request
+preamble. Both surfaces are opt-in and default off; the pass output is
+byte-identical when the gate is unset.
diff --git a/docs/observability.md b/docs/observability.md
index b944df8c..e3e14858 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -10,6 +10,9 @@ Open Second Brain records what it did - learning events, recall decisions, serve
| Continuity store | `Brain/log/continuity/<month>.jsonl` | `appendContinuityRecord()` in `src/core/brain/continuity/store.ts` | one JSON record per line |
| Session lifecycle audit | `Brain/log/session-lifecycle/` | `captureSessionLifecycleEvent()` in `src/core/brain/session-lifecycle.ts` | JSONL audit rows |
| Bench runs | `<runs-dir>/<run-id>/` (default `.open-second-brain/bench-runs/`, gitignored) | `runMemoryBench()` in `src/core/bench/phases.ts` | `checkpoint.json`, per-question results, `report.json` |
+| Metrics | `Brain/metrics/<surface>.jsonl` | `appendMetric()` in `src/core/brain/metrics.ts` | one run-level JSON record per line (see `docs/metrics.md`) |
+
+The `prompt_prefix` metric surface measures STRUCTURAL prompt-prefix stability (whether the kernel handed the agent a byte-stable, cache-eligible preamble across a generation pass), never a provider's cache-hit rate the kernel cannot observe. It stores only the SHA-256 hash and length of the prefix, never the raw prompt - the same payload-safety rule as `generation_report`. See `docs/metrics.md`.
## Brain log events
@@ -33,6 +36,7 @@ Every continuity record shares one envelope: `schema`, `id`, `kind`, `createdAt`
| `recall_telemetry` | opt-in per call (`telemetry` option/param) | `packContext` (`mode: context_pack`), `buildPreCompressPack` (`mode: pre_compress`), `brain_search` MCP handler (`mode: search`), `brain_query` MCP handler (`mode: query`, since v0.40.0 - payload carries the query kind only, never the supplied preference id / topic / timestamp) |
| `context_receipt` | opt-in per call (`receipt` option/param) | `packContext`, `buildPreCompressPack` |
| `gate_telemetry` | config key `recall_gate_telemetry` (default off) | `brain_recall_gate` MCP handler |
+| `generation_report` | opt-in per call (`enable`) or config key `generation_trace_enabled` (default off) | inbound agent report after a generation handoff (`brain_generation_reports` action `record`, `o2b brain generation-reports record`) |
| `session_turn`, `session_summary_node` | always-on within its operation | session-recall import (`src/core/brain/session-recall.ts`) - the write IS the operation |
| `pre_compact_extract` | always-on within its operation | explicit pre-compact extraction (`src/core/brain/pre-compact-extract.ts`) |
| `source_invalidation` | always-on within its operation | source drift detection (`appendContinuitySourceInvalidation`) |
@@ -56,6 +60,7 @@ Since v0.39.0 every new continuity record is stamped `schema: "o2b.continuity.v1
| `createdAt` | every continuity record | ordering key (store sorts by `createdAt`, then `id`) |
| `sourceRefs[].id` / `.path` | continuity records | joins records to vault artifacts |
| `session_id`, `turn_id` | payloads of session-scoped kinds; lifted by the read-model | yes - the cross-surface session join |
+| `handoffKind`, `handoffRef` | `generation_report` payload `handoff`; lifted by the read-model | yes - joins a generation report to the write-session / context-receipt / dream run it traced |
| `timestamp` + `agent` | Brain log events | per-event attribution |
Multi-agent vaults attribute writers via per-agent identity (`brain_agent_query`); continuity records do not yet thread parent/child agent ids - if delegated-subagent correlation becomes needed, it lands as an additive payload field (no version bump).
@@ -68,6 +73,7 @@ Every continuity payload passes `safeContinuityPayload()` (`src/core/brain/conti
- Secret-shaped tokens are redacted to `***REDACTED***`; the record is flagged `redacted: true`.
- The sanitized payload is deep-frozen; nothing mutates it after the flags are computed.
- `gate_telemetry` never stores the raw prompt by construction - only a SHA-256 prefix (`prompt_hash`) and the length (`prompt_chars`). The test suite asserts this against the persisted files, not just returned values.
+- `generation_report` follows the same rule: the handoff prompt is hashed and counted but never persisted - only `prompt_hash` (full SHA-256 hex) and `prompt_chars` land on disk, plus token counts. The kernel never calls an LLM; the report is the agent's INBOUND record after it performed a generation for a brain handoff, so the local token estimate (`local_estimate.input_tokens`) is always present while the agent-reported `usage` block is present only when supplied - absent is reported as absent, never fabricated. A grep-guarded regression test pins that no `fetch`/provider HTTP call exists under `src/core` for this feature, and a persisted-file assertion confirms no raw prompt survives.
- Read-side consumers (trajectory export, bench) get the masking policy from the read-model: records flagged `private` are dropped by default and kept only on explicit request; masked text is never un-masked.
## Fail-open rules
@@ -83,6 +89,7 @@ No-consumer regression tests cover each gated surface, so a future call site can
- `brain_recall_telemetry` (MCP) and `o2b brain recall-telemetry list|summary|gate-list|gate-summary` aggregate recall and gate records.
- `brain_context_receipts` and `o2b brain context-receipts` inspect served-context receipts.
+- `brain_generation_reports` (MCP, actions `record`/`list`/`summary`) and `o2b brain generation-reports record|list|summary|show` post and read inbound LLM generation traces. `summary` rolls up call counts, the always-present local token estimate, agent-reported usage where present, and a per-path linkage map so a memory path resolves back to the generation reports that produced or consumed it.
- `o2b brain continuity export --format atof|atif` renders the store as standard trajectory formats (ATOF JSONL event stream; ATIF v1.7 one document per session) for replay and eval tooling. Read-only; `private` records never reach an export file. Mapping decisions: `docs/brainstorm/memory-observability-suite/atof-atif-mapping.md`.
- `o2b brain bench memory` measures recall quality over disposable fixture vaults and reports quality, latency, and context cost as separate families (`o2b.bench.v1` report schema).
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 4da4d171..cf987d99 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,7 +2,7 @@
"id": "open-second-brain",
"name": "Open Second Brain",
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",
- "version": "1.12.0",
+ "version": "1.13.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index b60d874e..3aa8130b 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.12.0",
+ "version": "1.13.0",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
diff --git a/plugin.yaml b/plugin.yaml
index d6da66d0..579b01e4 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.12.0"
+version: "1.13.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index d52ac527..b3dcf8fd 100644
--- a/plugins/codex/.codex-plugin/plugin.json
+++ b/plugins/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.12.0",
+ "version": "1.13.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"author": {
"name": "Open Second Brain contributors",
diff --git a/plugins/hermes/_schemas.py b/plugins/hermes/_schemas.py
index 4528ef62..829edabb 100644
--- a/plugins/hermes/_schemas.py
+++ b/plugins/hermes/_schemas.py
@@ -160,7 +160,14 @@ STATIC_TOOL_SCHEMAS: tuple[dict[str, Any], ...] = (
'this call.'},
'telemetry_host': {'type': 'string', 'maxLength': 200},
'session_id': {'type': 'string', 'maxLength': 512},
- 'turn_id': {'type': 'string', 'maxLength': 512}},
+ 'turn_id': {'type': 'string', 'maxLength': 512},
+ 'agent_scope': {'type': 'string',
+ 'description': 'Optional owner scope: with '
+ 'owner_scoped_facts on, an '
+ 'owner-tagged fact returns only '
+ 'to its own scope; ownerless '
+ 'facts always match. Absent = '
+ 'no filtering.'}},
'additionalProperties': False}},
{'name': 'brain_search',
'description': 'Full-text search across the vault. Optional semantic layer when configured. '
@@ -206,6 +213,44 @@ STATIC_TOOL_SCHEMAS: tuple[dict[str, Any], ...] = (
'limit': {'type': 'integer', 'minimum': 1, 'maximum': 50},
'semantic': {'type': 'boolean'},
'keyword_only': {'type': 'boolean'},
+ 'profile': {'type': 'string',
+ 'enum': ['fast', 'balanced', 'thorough'],
+ 'description': 'Named recall profile '
+ '(fast|balanced|thorough): a fixed '
+ 'knob preset, preferred over '
+ 'persisted self-tuning. Absent '
+ 'leaves ranking unchanged.'},
+ 'explain': {'type': 'boolean',
+ 'description': 'Include a structured '
+ 'score_breakdown (per-layer numeric '
+ 'components) on each result. '
+ 'Default false.'},
+ 'trust': {'type': 'boolean',
+ 'description': 'Stamp each result with inline trust '
+ 'metadata (age_days, superseded, '
+ 'conflict), computed at read time. '
+ 'Default false.'},
+ 'threshold': {'type': 'number',
+ 'minimum': 0,
+ 'maximum': 1,
+ 'description': 'Relevance floor in [0,1] on the '
+ 'final score; drops weaker hits '
+ 'so an irrelevant query returns '
+ 'no match. Default 0 (disabled).'},
+ 'rerank': {'type': 'boolean',
+ 'description': 'Re-order the threshold-qualified '
+ 'results by core textual relevance '
+ '(keyword + semantic). Default '
+ 'false.'},
+ 'reinforce': {'type': 'array',
+ 'maxItems': 50,
+ 'items': {'type': 'string',
+ 'minLength': 1,
+ 'maxLength': 512},
+ 'description': 'Paths proven useful: recorded to '
+ 'the reinforce ledger and lifted '
+ '(bounded) before the top_k cut. '
+ 'Default absent.'},
'record_access': {'type': 'boolean',
'description': 'Record the surfaced paths as '
'one activation access event '
@@ -239,7 +284,14 @@ STATIC_TOOL_SCHEMAS: tuple[dict[str, Any], ...] = (
'match, tagged pages only when '
'this scope includes one of '
'their values.',
- 'items': {'type': 'string'}}},
+ 'items': {'type': 'string'}},
+ 'agent_scope': {'type': 'string',
+ 'description': 'Optional agent-ownership '
+ 'scope; shared (ownerless) '
+ 'pages always match, '
+ 'owner-tagged pages only their '
+ 'owner. Absent = no ownership '
+ 'filtering.'}},
'required': ['query'],
'additionalProperties': False}},
{'name': 'brain_recall_gate',
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index d6da66d0..579b01e4 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.12.0"
+version: "1.13.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/pyproject.toml b/pyproject.toml
index d0bc14c8..1b22c1a5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
# CLI entry points (those moved to `package.json` `bin`).
[project]
name = "open-second-brain"
-version = "1.12.0"
+version = "1.13.0"
description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/src/cli/brain.ts b/src/cli/brain.ts
index de60a345..00e7e98f 100644
--- a/src/cli/brain.ts
+++ b/src/cli/brain.ts
@@ -99,6 +99,7 @@ import {
cmdBrainContextPresets,
cmdBrainPreCompactExtract,
cmdBrainRecallTelemetry,
+ cmdBrainGenerationReports,
cmdBrainSkillProposals,
cmdBrainProceduralMemory,
cmdBrainProceduralGraph,
@@ -320,6 +321,8 @@ export async function handleBrainSubcommand(argv: ReadonlyArray<string>): Promis
return await cmdBrainPreCompactExtract(rest);
case "recall-telemetry":
return await cmdBrainRecallTelemetry(rest);
+ case "generation-reports":
+ return await cmdBrainGenerationReports(rest);
case "skill-proposals":
return await cmdBrainSkillProposals(rest);
case "procedural-memory":
diff --git a/src/cli/brain/help-text.ts b/src/cli/brain/help-text.ts
index 4385bb3e..71c44937 100644
--- a/src/cli/brain/help-text.ts
+++ b/src/cli/brain/help-text.ts
@@ -82,6 +82,7 @@ Brain verbs (observing memory):
context-presets Show/suggest/diff read-only context budget presets
pre-compact-extract Extract typed continuity records from bounded text
recall-telemetry List/summarize opt-in recall telemetry records
+ generation-reports Record/list/summarize opt-in LLM generation traces
skill-proposals Learn/list/review deterministic skill proposals
procedural-memory Reconcile/list procedural memory index and usage
procedural-graph Rebuild/show procedural graph and hint projections
@@ -558,6 +559,12 @@ export const VERB_HELP: Record<string, string> = {
"usage: o2b brain recall-telemetry list [--mode search|context_pack|pre_compress] [--status ok|empty|error|timeout] [--host <name>] [--since <iso>] [--until <iso>] [--limit <n>] [--vault <path>] [--json]\n" +
" o2b brain recall-telemetry summary [same filters] [--vault <path>] [--json]\n" +
"Read opt-in recall telemetry continuity records and aggregate coverage gaps.\n",
+ "generation-reports":
+ "usage: o2b brain generation-reports record <write_session|context_pack|dream_stage> --ref <id> --agent <name> --prompt <text> [--enable] [--provider <p>] [--model <m>] [--finish-reason <r>] [--latency-ms <n>] [--input-tokens <n>] [--output-tokens <n>] [--cached-tokens <n>] [--total-tokens <n>] [--scope <s>] [--source <id[=path]>...] [--created-at <iso>] [--vault <path>] [--json]\n" +
+ " o2b brain generation-reports list [--handoff <kind>] [--agent <name>] [--since <iso>] [--until <iso>] [--limit <n>] [--vault <path>] [--json]\n" +
+ " o2b brain generation-reports summary [same filters] [--vault <path>] [--json]\n" +
+ " o2b brain generation-reports show <report-id> [--vault <path>] [--json]\n" +
+ "Inbound, opt-in LLM generation tracing. record is gated (default off) by --enable or generation_trace_enabled; only prompt_hash + counts are stored, never the prompt.\n",
"skill-proposals":
"usage: o2b brain skill-proposals <learn|list|accept|reject> [args]\n" +
"Deterministic proposal queue lifecycle.\n" +
diff --git a/src/cli/brain/verbs/generation-reports.ts b/src/cli/brain/verbs/generation-reports.ts
new file mode 100644
index 00000000..259d4c5d
--- /dev/null
+++ b/src/cli/brain/verbs/generation-reports.ts
@@ -0,0 +1,271 @@
+import { resolveGenerationTraceEnabled } from "../../../core/config.ts";
+import {
+ emitGenerationReport,
+ getGenerationReport,
+ isGenerationHandoffKind,
+ listGenerationReports,
+ summarizeGenerationReports,
+ type GenerationHandoffKind,
+ type GenerationReportFilter,
+ type GenerationUsage,
+} from "../../../core/brain/generation-reports.ts";
+import type { ContinuitySourceRef } from "../../../core/brain/continuity/types.ts";
+import { CliError, brainVerbContext, parse } from "../helpers.ts";
+
+export async function cmdBrainGenerationReports(argv: string[]): Promise<number> {
+ const subcommand = argv[0];
+ const rest = argv.slice(1);
+ if (subcommand === "record") return recordReport(rest);
+ if (subcommand === "list") return listReports(rest);
+ if (subcommand === "summary") return summarizeReports(rest);
+ if (subcommand === "show") return showReport(rest);
+ throw new CliError("brain generation-reports: expected record, list, summary, or show");
+}
+
+function recordReport(argv: string[]): number {
+ const { flags, positional } = parse(argv, {
+ vault: { type: "string" },
+ json: { type: "boolean" },
+ enable: { type: "boolean" },
+ ref: { type: "string" },
+ agent: { type: "string" },
+ prompt: { type: "string" },
+ scope: { type: "string" },
+ provider: { type: "string" },
+ model: { type: "string" },
+ "finish-reason": { type: "string" },
+ "latency-ms": { type: "string" },
+ "input-tokens": { type: "string" },
+ "output-tokens": { type: "string" },
+ "cached-tokens": { type: "string" },
+ "total-tokens": { type: "string" },
+ source: { type: "string-array" },
+ "created-at": { type: "string" },
+ });
+ const ctx = brainVerbContext(flags);
+ const label = "brain generation-reports record";
+
+ const handoffKind = handoffKindArg(positional[0], label);
+ const ref = requireString(flags["ref"], "--ref", label);
+ const agent = requireString(flags["agent"], "--agent", label);
+ const prompt = requireString(flags["prompt"], "--prompt", label);
+
+ // Opt-in gate: a per-call --enable wins, else the config gate. Off => nothing written.
+ const enabled = flags["enable"] === true || resolveGenerationTraceEnabled(ctx.config);
+
+ const usage = buildUsage(flags, label);
+ const record = emitGenerationReport(
+ ctx.vault,
+ {
+ handoff: { kind: handoffKind, ref },
+ agent,
+ prompt,
+ ...(strOrUndef(flags["scope"]) !== undefined ? { scope: strOrUndef(flags["scope"]) } : {}),
+ ...(strOrUndef(flags["provider"]) !== undefined
+ ? { provider: strOrUndef(flags["provider"]) }
+ : {}),
+ ...(strOrUndef(flags["model"]) !== undefined ? { model: strOrUndef(flags["model"]) } : {}),
+ ...(strOrUndef(flags["finish-reason"]) !== undefined
+ ? { finishReason: strOrUndef(flags["finish-reason"]) }
+ : {}),
+ ...(intArg(flags["latency-ms"], "--latency-ms", label) !== undefined
+ ? { latencyMs: intArg(flags["latency-ms"], "--latency-ms", label) }
+ : {}),
+ ...(usage !== undefined ? { usage } : {}),
+ ...(sourceRefArgs(flags["source"], label).length > 0
+ ? { sourceRefs: sourceRefArgs(flags["source"], label) }
+ : {}),
+ ...(strOrUndef(flags["created-at"]) !== undefined
+ ? { createdAt: strOrUndef(flags["created-at"]) }
+ : {}),
+ },
+ enabled,
+ );
+
+ if (flags["json"]) {
+ process.stdout.write(
+ JSON.stringify(
+ {
+ recorded: record !== null,
+ ...(record !== null ? { id: record.id } : { reason: "disabled" }),
+ },
+ null,
+ 2,
+ ) + "\n",
+ );
+ return 0;
+ }
+ if (record === null) {
+ process.stdout.write("generation trace disabled; nothing recorded\n");
+ return 0;
+ }
+ process.stdout.write(`recorded generation report ${record.id}\n`);
+ return 0;
+}
+
+function listReports(argv: string[]): number {
+ const { flags } = parseReadFlags(argv);
+ const vault = brainVerbContext(flags).vault;
+ const reports = listGenerationReports(vault, readFilter(flags, "brain generation-reports list"));
+
+ if (flags["json"]) {
+ process.stdout.write(JSON.stringify({ total: reports.length, reports }, null, 2) + "\n");
+ return 0;
+ }
+ process.stdout.write(`${reports.length} generation report(s):\n`);
+ for (const report of reports) {
+ const payload = report.payload;
+ const handoff = (payload["handoff"] ?? {}) as Record<string, unknown>;
+ const usage = payload["usage"] as Record<string, unknown> | undefined;
+ process.stdout.write(
+ ` ${report.createdAt} ${report.id} ${handoff["kind"] ?? "unknown"} agent=${payload["agent"] ?? "-"} reported_tokens=${usage?.["total_tokens"] ?? "-"}\n`,
+ );
+ }
+ return 0;
+}
+
+function summarizeReports(argv: string[]): number {
+ const { flags } = parseReadFlags(argv);
+ const vault = brainVerbContext(flags).vault;
+ const summary = summarizeGenerationReports(
+ vault,
+ readFilter(flags, "brain generation-reports summary"),
+ );
+ if (flags["json"]) {
+ process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+ return 0;
+ }
+ process.stdout.write(`reports: ${summary.total}\n`);
+ process.stdout.write(`by handoff kind: ${JSON.stringify(summary.by_handoff_kind)}\n`);
+ process.stdout.write(`local estimate tokens: ${summary.local_estimate_tokens}\n`);
+ process.stdout.write(
+ `reported (${summary.reported_count}): ${JSON.stringify(summary.reported_tokens)}\n`,
+ );
+ process.stdout.write(`linked paths: ${Object.keys(summary.by_path).length}\n`);
+ return 0;
+}
+
+function showReport(argv: string[]): number {
+ const { flags, positional } = parse(argv, {
+ vault: { type: "string" },
+ json: { type: "boolean" },
+ });
+ const id = strOrUndef(positional[0]);
+ if (id === undefined) throw new CliError("brain generation-reports show: report id is required");
+ const vault = brainVerbContext(flags).vault;
+ const report = getGenerationReport(vault, id);
+ if (report === null) {
+ throw new CliError(`brain generation-reports show: report not found: ${id}`);
+ }
+ process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+ return 0;
+}
+
+function parseReadFlags(argv: string[]): {
+ readonly flags: Record<string, string | boolean | string[] | undefined>;
+} {
+ return parse(argv, {
+ vault: { type: "string" },
+ json: { type: "boolean" },
+ handoff: { type: "string" },
+ agent: { type: "string" },
+ since: { type: "string" },
+ until: { type: "string" },
+ limit: { type: "string" },
+ });
+}
+
+function readFilter(
+ flags: Record<string, string | boolean | string[] | undefined>,
+ label: string,
+): GenerationReportFilter {
+ const handoffRaw = strOrUndef(flags["handoff"]);
+ if (handoffRaw !== undefined && !isGenerationHandoffKind(handoffRaw)) {
+ throw new CliError(`${label}: --handoff must be write_session, context_pack, or dream_stage`);
+ }
+ const limit = intArg(flags["limit"], "--limit", label);
+ return {
+ ...(handoffRaw !== undefined ? { handoffKind: handoffRaw as GenerationHandoffKind } : {}),
+ ...(strOrUndef(flags["agent"]) !== undefined ? { agent: strOrUndef(flags["agent"]) } : {}),
+ ...(strOrUndef(flags["since"]) !== undefined ? { since: strOrUndef(flags["since"]) } : {}),
+ ...(strOrUndef(flags["until"]) !== undefined ? { until: strOrUndef(flags["until"]) } : {}),
+ ...(limit !== undefined ? { limit } : {}),
+ };
+}
+
+function buildUsage(
+ flags: Record<string, string | boolean | string[] | undefined>,
+ label: string,
+): GenerationUsage | undefined {
+ const input = intArg(flags["input-tokens"], "--input-tokens", label);
+ const output = intArg(flags["output-tokens"], "--output-tokens", label);
+ const cached = intArg(flags["cached-tokens"], "--cached-tokens", label);
+ const total = intArg(flags["total-tokens"], "--total-tokens", label);
+ const usage: GenerationUsage = {
+ ...(input !== undefined ? { inputTokens: input } : {}),
+ ...(output !== undefined ? { outputTokens: output } : {}),
+ ...(cached !== undefined ? { cachedTokens: cached } : {}),
+ ...(total !== undefined ? { totalTokens: total } : {}),
+ };
+ return Object.keys(usage).length > 0 ? usage : undefined;
+}
+
+function sourceRefArgs(
+ raw: string | boolean | string[] | undefined,
+ label: string,
+): ReadonlyArray<ContinuitySourceRef> {
+ if (!Array.isArray(raw)) return [];
+ return raw.map((entry) => {
+ const trimmed = entry.trim();
+ if (trimmed.length === 0) throw new CliError(`${label}: --source entry must not be empty`);
+ // Form: "<id>" or "<id>=<path>".
+ const eq = trimmed.indexOf("=");
+ if (eq < 0) return { id: trimmed };
+ const id = trimmed.slice(0, eq).trim();
+ const path = trimmed.slice(eq + 1).trim();
+ if (id.length === 0) throw new CliError(`${label}: --source id must not be empty`);
+ return path.length > 0 ? { id, path } : { id };
+ });
+}
+
+function handoffKindArg(raw: string | undefined, label: string): GenerationHandoffKind {
+ const value = strOrUndef(raw);
+ if (value === undefined) {
+ throw new CliError(
+ `${label}: handoff kind is required (write_session|context_pack|dream_stage)`,
+ );
+ }
+ if (!isGenerationHandoffKind(value)) {
+ throw new CliError(`${label}: unknown handoff kind '${value}'`);
+ }
+ return value;
+}
+
+function requireString(
+ raw: string | boolean | string[] | undefined,
+ flag: string,
+ label: string,
+): string {
+ const value = strOrUndef(raw);
+ if (value === undefined) throw new CliError(`${label}: ${flag} is required`);
+ return value;
+}
+
+function intArg(
+ raw: string | boolean | string[] | undefined,
+ flag: string,
+ label: string,
+): number | undefined {
+ const value = strOrUndef(raw);
+ if (value === undefined) return undefined;
+ if (!/^[0-9]+$/.test(value)) {
+ throw new CliError(`${label}: ${flag} must be a non-negative integer`);
+ }
+ return Number.parseInt(value, 10);
+}
+
+function strOrUndef(value: string | boolean | string[] | undefined): string | undefined {
+ if (typeof value !== "string") return undefined;
+ const trimmed = value.trim();
+ return trimmed.length > 0 ? trimmed : undefined;
+}
diff --git a/src/cli/brain/verbs/index.ts b/src/cli/brain/verbs/index.ts
index cb3191f1..83a884a6 100644
--- a/src/cli/brain/verbs/index.ts
+++ b/src/cli/brain/verbs/index.ts
@@ -83,6 +83,7 @@ export { cmdBrainContextReceipts } from "./context-receipts.ts";
export { cmdBrainContextPresets } from "./context-presets.ts";
export { cmdBrainPreCompactExtract } from "./pre-compact-extract.ts";
export { cmdBrainRecallTelemetry } from "./recall-telemetry.ts";
+export { cmdBrainGenerationReports } from "./generation-reports.ts";
export { cmdBrainSkillProposals } from "./skill-proposals.ts";
export { cmdBrainProceduralMemory } from "./procedural-memory.ts";
export { cmdBrainProceduralGraph } from "./procedural-graph.ts";
diff --git a/src/cli/command-manifest.ts b/src/cli/command-manifest.ts
index 94043ed5..e5f23f65 100644
--- a/src/cli/command-manifest.ts
+++ b/src/cli/command-manifest.ts
@@ -130,6 +130,17 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({
command("secret", "Capability-gated secret custody: set, list, rm, run"),
command("maintenance", "Quiet-window, lease-guarded heavy maintenance lane"),
command("audit", "Render mutation audit trail"),
+ command(
+ "generation-reports",
+ "Record/list/summarize opt-in inbound LLM generation traces",
+ [],
+ [
+ command("record", "Record one gated inbound generation report"),
+ command("list", "List generation report records"),
+ command("summary", "Summarize generation usage with memory linkage"),
+ command("show", "Show one generation report record"),
+ ],
+ ),
command("morning-brief", "Render session-start summary"),
command("codec", "Compress or expand session prose"),
command("sources", "Show signal source dashboard"),
diff --git a/src/core/brain/context-pack.ts b/src/core/brain/context-pack.ts
index 28210282..66738ed5 100644
--- a/src/core/brain/context-pack.ts
+++ b/src/core/brain/context-pack.ts
@@ -31,6 +31,13 @@ import { normalizeForDedup } from "./text/normalize.ts";
import { applyCharBudget, type CharBudgetDegradationMode } from "./recall-budget.ts";
import { emitContextReceipt, type ContextReceiptOptions } from "./context-receipts.ts";
import { emitGatedTelemetry } from "./continuity/emit.ts";
+import {
+ canonicalSegment,
+ deterministicPrefix,
+ emitPromptPrefixMetric,
+ summarizePrefixPass,
+} from "./prompt-prefix.ts";
+import { isoSecond } from "./time.ts";
import { emitRecallTelemetry, type RecallTelemetryOptions } from "./recall-telemetry.ts";
import {
applyContextTransforms,
@@ -115,6 +122,13 @@ export interface ContextPackOptions {
readonly receipt?: ContextReceiptOptions;
/** Opt-in telemetry for recall coverage and gap diagnostics. */
readonly telemetry?: RecallTelemetryOptions;
+ /**
+ * Opt-in: emit one run-level `prompt_prefix` metric for this pack's
+ * stable request preamble (Hindsight brain-loop ops, t_d8c1f7d9).
+ * Omitted/false keeps the report and any receipt byte-identical and
+ * writes no metric.
+ */
+ readonly promptPrefix?: boolean;
/** Opt-in post-selection context transforms. Defaults preserve legacy order and bodies. */
readonly transforms?: ContextTransformOptions;
/** Optional declarative attention-flow ids to include as a synthetic context item. */
@@ -463,6 +477,35 @@ function finalizeContextPackReport(
}),
);
if (telemetry) enriched = { ...enriched, telemetryId: telemetry.id };
+ // Structural prefix-stability metric (opt-in, fail-soft). The pack's
+ // cacheable preamble is its stable request framing - byte-identical
+ // for an identical request, which is what a provider prefix cache
+ // rewards. Built only when the gate is on, so neither the summary nor
+ // its hash is computed on the default (no-consumer) path.
+ if (opts.promptPrefix) {
+ emitPromptPrefixMetric(
+ vault,
+ {
+ runAt: isoSecond(new Date()),
+ summary: summarizePrefixPass({
+ kind: "context_pack",
+ prefixes: [
+ deterministicPrefix({
+ kind: "context_pack",
+ segments: [
+ canonicalSegment({
+ lanes: String(opts.includeLanes === true),
+ max_tokens: String(report.maxTokens),
+ query: opts.query ?? "",
+ }),
+ ],
+ }),
+ ],
+ }),
+ },
+ opts.promptPrefix,
+ );
+ }
return Object.freeze(enriched);
}
diff --git a/src/core/brain/continuity/read-model.ts b/src/core/brain/continuity/read-model.ts
index aeac237f..573a0a1c 100644
--- a/src/core/brain/continuity/read-model.ts
+++ b/src/core/brain/continuity/read-model.ts
@@ -35,6 +35,9 @@ export interface NormalizedContinuityRecord {
/** Correlation ids lifted out of the payload when present. */
readonly sessionId?: string;
readonly turnId?: string;
+ /** Generation-report handoff lifted to a first-class join field. */
+ readonly handoffKind?: string;
+ readonly handoffRef?: string;
}
export interface ContinuityReadModelFilter {
@@ -63,6 +66,9 @@ export function normalizeContinuityRecord(raw: unknown): NormalizedContinuityRec
: [];
const sessionId = readString(payload["session_id"]);
const turnId = readString(payload["turn_id"]);
+ const handoff = isPlainObject(payload["handoff"]) ? payload["handoff"] : undefined;
+ const handoffKind = handoff !== undefined ? readString(handoff["kind"]) : undefined;
+ const handoffRef = handoff !== undefined ? readString(handoff["ref"]) : undefined;
return Object.freeze({
schema: schema ?? CONTINUITY_SCHEMA_VERSION,
legacy: schema === undefined,
@@ -75,6 +81,8 @@ export function normalizeContinuityRecord(raw: unknown): NormalizedContinuityRec
redacted: record["redacted"] === true,
...(sessionId !== undefined ? { sessionId } : {}),
...(turnId !== undefined ? { turnId } : {}),
+ ...(handoffKind !== undefined ? { handoffKind } : {}),
+ ...(handoffRef !== undefined ? { handoffRef } : {}),
});
}
diff --git a/src/core/brain/continuity/types.ts b/src/core/brain/continuity/types.ts
index 53acf145..5a3c64a3 100644
--- a/src/core/brain/continuity/types.ts
+++ b/src/core/brain/continuity/types.ts
@@ -17,6 +17,7 @@ export type ContinuityRecordKind =
| "session_turn"
| "session_summary_node"
| "session_summary_digest"
+ | "generation_report"
| "source_invalidation";
export type ContinuityPayload = Readonly<Record<string, unknown>>;
diff --git a/src/core/brain/generation-reports.ts b/src/core/brain/generation-reports.ts
new file mode 100644
index 00000000..7fb27de6
--- /dev/null
+++ b/src/core/brain/generation-reports.ts
@@ -0,0 +1,250 @@
+/**
+ * Per-handoff LLM generation tracing (Hindsight brain-loop ops,
+ * t_281c3edc).
+ *
+ * Open Second Brain's kernel never calls an LLM - the calling agent
+ * owns all generation. So tracing cannot wrap an outbound request the
+ * kernel makes; instead it is an opt-in INBOUND path: after the agent
+ * fulfils a generation handoff (a write-session step, a context-pack
+ * consume, or a dream-stage proposal) it optionally reports back the
+ * real usage. Open Second Brain stores that as an additive
+ * `generation_report` continuity record correlated to the paths and ids
+ * it already owns, so memory <-> trace linkage is a `sourceRefs` join
+ * the read-model already performs.
+ *
+ * Honest asymmetry: the local token estimate is always present (derived
+ * from the prompt the kernel handed the agent); the agent-reported
+ * `usage` block is present only when the inbound report carries it. A
+ * missing usage block is normal, not a failure.
+ *
+ * Payload-safe by construction: the raw prompt is hashed and counted but
+ * never stored - only `prompt_hash` (full sha-256 hex) and `prompt_chars`
+ * land on disk, and the whole payload still passes `safeContinuityPayload`
+ * redaction. The surface is gated by `emitGatedTelemetry` (opt-in,
+ * fail-open): with the gate off no payload is built, and a throwing build
+ * never fails the primary operation.
+ */
+
+import { createHash } from "node:crypto";
+
+import { emitGatedTelemetry } from "./continuity/emit.ts";
+import { appendContinuityRecord, listContinuityRecords } from "./continuity/store.ts";
+import type { ContinuityRecord, ContinuitySourceRef } from "./continuity/types.ts";
+import { estimateTokens } from "./text/tokenizer.ts";
+
+export const GENERATION_HANDOFF_KINDS = ["write_session", "context_pack", "dream_stage"] as const;
+
+export type GenerationHandoffKind = (typeof GENERATION_HANDOFF_KINDS)[number];
+
+export function isGenerationHandoffKind(value: unknown): value is GenerationHandoffKind {
+ return (
+ typeof value === "string" && (GENERATION_HANDOFF_KINDS as ReadonlyArray<string>).includes(value)
+ );
+}
+
+/** Agent-reported token usage; every field optional and reported as absent when missing. */
+export interface GenerationUsage {
+ readonly inputTokens?: number;
+ readonly outputTokens?: number;
+ readonly cachedTokens?: number;
+ readonly totalTokens?: number;
+}
+
+export interface GenerationReportInput {
+ readonly handoff: { readonly kind: GenerationHandoffKind; readonly ref: string };
+ readonly agent: string;
+ readonly scope?: string;
+ readonly provider?: string;
+ readonly model?: string;
+ readonly finishReason?: string;
+ readonly latencyMs?: number;
+ /**
+ * The exact prompt the kernel handed the agent for this handoff. Used
+ * ONLY to derive `prompt_hash`, `prompt_chars`, and the local token
+ * estimate - never persisted as raw text.
+ */
+ readonly prompt: string;
+ readonly usage?: GenerationUsage;
+ /** Artifact join refs (memory paths, ids) beyond the handoff ref itself. */
+ readonly sourceRefs?: ReadonlyArray<ContinuitySourceRef>;
+ readonly createdAt?: string;
+}
+
+/**
+ * Emit a `generation_report` continuity record, gated and fail-open.
+ *
+ * `gate` doubles as the opt-in switch: with `false | null | undefined`
+ * the build thunk never runs (no payload, no hash, no write) and the
+ * function returns `null`. A throwing build (e.g. a non-string prompt)
+ * is swallowed and reported as `null` so tracing can never fail the
+ * primary brain operation.
+ */
+export function emitGenerationReport<G>(
+ vault: string,
+ input: GenerationReportInput,
+ gate: G | false | null | undefined,
+): ContinuityRecord | null {
+ return emitGatedTelemetry(gate, () => {
+ const createdAt = input.createdAt ?? new Date().toISOString();
+ const prompt = input.prompt;
+ if (typeof prompt !== "string") {
+ throw new TypeError("generation report prompt must be a string");
+ }
+ const payload: Record<string, unknown> = {
+ handoff: { kind: input.handoff.kind, ref: input.handoff.ref },
+ agent: input.agent,
+ ...(input.scope !== undefined ? { scope: input.scope } : {}),
+ ...(input.provider !== undefined ? { provider: input.provider } : {}),
+ ...(input.model !== undefined ? { model: input.model } : {}),
+ ...(input.finishReason !== undefined ? { finish_reason: input.finishReason } : {}),
+ ...(input.latencyMs !== undefined ? { latency_ms: input.latencyMs } : {}),
+ prompt_hash: sha256(prompt),
+ prompt_chars: [...prompt].length,
+ local_estimate: { input_tokens: estimateTokens(prompt) },
+ ...(usagePayload(input.usage) !== undefined ? { usage: usagePayload(input.usage) } : {}),
+ };
+ return appendContinuityRecord(vault, {
+ kind: "generation_report",
+ createdAt,
+ sourceRefs: buildSourceRefs(input),
+ payload,
+ });
+ });
+}
+
+function buildSourceRefs(input: GenerationReportInput): ReadonlyArray<ContinuitySourceRef> {
+ const refs: ContinuitySourceRef[] = [{ id: input.handoff.ref, kind: input.handoff.kind }];
+ for (const ref of input.sourceRefs ?? []) {
+ if (ref.id === input.handoff.ref) continue;
+ refs.push(ref);
+ }
+ return Object.freeze(refs);
+}
+
+function usagePayload(usage: GenerationUsage | undefined): Record<string, number> | undefined {
+ if (usage === undefined) return undefined;
+ const out: Record<string, number> = {};
+ if (typeof usage.inputTokens === "number") out["input_tokens"] = usage.inputTokens;
+ if (typeof usage.outputTokens === "number") out["output_tokens"] = usage.outputTokens;
+ if (typeof usage.cachedTokens === "number") out["cached_tokens"] = usage.cachedTokens;
+ if (typeof usage.totalTokens === "number") out["total_tokens"] = usage.totalTokens;
+ return Object.keys(out).length > 0 ? out : undefined;
+}
+
+export interface GenerationReportFilter {
+ readonly handoffKind?: GenerationHandoffKind;
+ readonly agent?: string;
+ readonly since?: string;
+ readonly until?: string;
+ readonly limit?: number;
+}
+
+/** List `generation_report` records newest-first, after applying filters. */
+export function listGenerationReports(
+ vault: string,
+ filter: GenerationReportFilter = {},
+): ReadonlyArray<ContinuityRecord> {
+ let records = listContinuityRecords(vault, {
+ kind: "generation_report",
+ ...(filter.since !== undefined ? { since: filter.since } : {}),
+ ...(filter.until !== undefined ? { until: filter.until } : {}),
+ }).filter((record) => matchesFilter(record, filter));
+ records = records.toReversed();
+ if (filter.limit !== undefined) records = records.slice(0, Math.max(0, Math.floor(filter.limit)));
+ return Object.freeze(records);
+}
+
+function matchesFilter(record: ContinuityRecord, filter: GenerationReportFilter): boolean {
+ const payload = record.payload;
+ const handoff = isPlainObject(payload["handoff"]) ? payload["handoff"] : {};
+ if (filter.handoffKind !== undefined && handoff["kind"] !== filter.handoffKind) return false;
+ if (filter.agent !== undefined && payload["agent"] !== filter.agent) return false;
+ return true;
+}
+
+export interface GenerationReportSummary {
+ readonly total: number;
+ readonly by_handoff_kind: Readonly<Record<string, number>>;
+ /** Sum of the always-present local token estimates. */
+ readonly local_estimate_tokens: number;
+ /** Sum of agent-reported usage where present (absent reports contribute nothing). */
+ readonly reported_tokens: {
+ readonly input: number;
+ readonly output: number;
+ readonly cached: number;
+ readonly total: number;
+ };
+ /** How many records carried an agent-reported usage block. */
+ readonly reported_count: number;
+ /** Memory-path linkage: each source path maps back to the report ids that touched it. */
+ readonly by_path: Readonly<Record<string, ReadonlyArray<string>>>;
+}
+
+/** Aggregate generation reports: counts, token rollups, and per-path linkage. */
+export function summarizeGenerationReports(
+ vault: string,
+ filter: GenerationReportFilter = {},
+): GenerationReportSummary {
+ const records = listGenerationReports(vault, filter);
+ const byKind: Record<string, number> = {};
+ const reported = { input: 0, output: 0, cached: 0, total: 0 };
+ const byPath: Record<string, string[]> = {};
+ let localEstimate = 0;
+ let reportedCount = 0;
+
+ for (const record of records) {
+ const payload = record.payload;
+ const handoff = isPlainObject(payload["handoff"]) ? payload["handoff"] : {};
+ const kind = typeof handoff["kind"] === "string" ? handoff["kind"] : "unknown";
+ byKind[kind] = (byKind[kind] ?? 0) + 1;
+
+ const estimate = isPlainObject(payload["local_estimate"]) ? payload["local_estimate"] : {};
+ if (typeof estimate["input_tokens"] === "number") localEstimate += estimate["input_tokens"];
+
+ if (isPlainObject(payload["usage"])) {
+ reportedCount += 1;
+ const usage = payload["usage"];
+ reported.input += numberOr0(usage["input_tokens"]);
+ reported.output += numberOr0(usage["output_tokens"]);
+ reported.cached += numberOr0(usage["cached_tokens"]);
+ reported.total += numberOr0(usage["total_tokens"]);
+ }
+
+ const seenPaths = new Set<string>();
+ for (const ref of record.sourceRefs) {
+ if (typeof ref.path !== "string" || ref.path.length === 0) continue;
+ if (seenPaths.has(ref.path)) continue; // one record contributes its id once per path
+ seenPaths.add(ref.path);
+ (byPath[ref.path] ??= []).push(record.id);
+ }
+ }
+
+ return Object.freeze({
+ total: records.length,
+ by_handoff_kind: Object.freeze(byKind),
+ local_estimate_tokens: localEstimate,
+ reported_tokens: Object.freeze(reported),
+ reported_count: reportedCount,
+ by_path: Object.freeze(byPath),
+ });
+}
+
+export function getGenerationReport(vault: string, id: string): ContinuityRecord | null {
+ return (
+ listContinuityRecords(vault, { kind: "generation_report" }).find(
+ (record) => record.id === id,
+ ) ?? null
+ );
+}
+
+function sha256(text: string): string {
+ return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+function numberOr0(value: unknown): number {
+ return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+ return value !== null && typeof value === "object" && !Array.isArray(value);
+}
diff --git a/src/core/brain/prompt-prefix.ts b/src/core/brain/prompt-prefix.ts
new file mode 100644
index 00000000..e040c82e
--- /dev/null
+++ b/src/core/brain/prompt-prefix.ts
@@ -0,0 +1,149 @@
+/**
+ * Structural prompt-prefix stability (Hindsight brain-loop ops,
+ * t_d8c1f7d9).
+ *
+ * Upstream Hindsight ships provider prompt-prefix caching for its
+ * retain / consolidate / reflect operations - it caches the common
+ * leading bytes across the repeated LLM calls those operations make.
+ * Open Second Brain cannot port that verbatim: the kernel never calls
+ * an LLM, the calling agent owns all generation. So there is no
+ * outbound request for the kernel to attach a provider cache hint to.
+ *
+ * What the kernel CAN own is the other half of the contract a provider
+ * prefix cache rewards: a byte-stable prompt prefix across the repeated
+ * generation handoffs a single brain operation hands the agent (the
+ * persona + synthesis steps of a decision panel, a context-pack
+ * consume). `deterministicPrefix` makes that prefix explicit and
+ * measurable; `summarizePrefixPass` reduces a pass of handoffs to the
+ * run-level shape the `prompt_prefix` metric records.
+ *
+ * Honest scope: this measures prefix STABILITY (structural - whether
+ * the kernel handed byte-identical prefixes across a pass), NOT the
+ * provider's cache-hit rate, which the kernel never observes. The
+ * metric is opt-in and fail-soft, exactly like every other surface in
+ * `metrics.ts`; with the gate off no record is written and the pass
+ * output is byte-identical to today.
+ */
+
+import { createHash } from "node:crypto";
+
+import { emitGatedTelemetry } from "./continuity/emit.ts";
+import { appendMetric } from "./metrics.ts";
+import { type GenerationHandoffKind } from "./generation-reports.ts";
+
+/** Metric surface name for the run-level prefix-stability record. */
+export const PROMPT_PREFIX_SURFACE = "prompt_prefix";
+
+export interface PrefixInput {
+ /** Which generation handoff this prefix primes. */
+ readonly kind: GenerationHandoffKind;
+ /**
+ * Ordered, stable text segments forming the cacheable preamble. The
+ * determinism contract: every segment must be stable for identical
+ * inputs - no `Date.now`, no random, no per-call-varying value. When
+ * a segment is derived from a record, build it with `canonicalSegment`
+ * so key order never perturbs the bytes.
+ */
+ readonly segments: ReadonlyArray<string>;
+}
+
+export interface PromptPrefix {
+ readonly kind: GenerationHandoffKind;
+ /** The exact stable preamble bytes the caller prepends to its prompt. */
+ readonly prefix: string;
+ /** Full sha-256 hex of `prefix`. */
+ readonly hash: string;
+ /** Code-point count of `prefix`. */
+ readonly chars: number;
+}
+
+/**
+ * Render a record of fields into a single stable segment: keys are
+ * sorted so the same field set yields byte-identical bytes regardless
+ * of insertion order. Values must themselves be stable.
+ */
+export function canonicalSegment(fields: Readonly<Record<string, string>>): string {
+ return Object.keys(fields)
+ .toSorted()
+ .map((key) => `${key}=${fields[key]}`)
+ .join("\n");
+}
+
+/**
+ * Certify a stable prompt prefix: the joined segment bytes plus their
+ * sha-256 hash and code-point length. Pure and deterministic - identical
+ * inputs always return byte-identical `prefix` and `hash`.
+ */
+export function deterministicPrefix(input: PrefixInput): PromptPrefix {
+ const prefix = input.segments.join("");
+ return Object.freeze({
+ kind: input.kind,
+ prefix,
+ hash: createHash("sha256").update(prefix, "utf8").digest("hex"),
+ chars: [...prefix].length,
+ });
+}
+
+/** True when two prefixes are interchangeable: same handoff kind, same hash. */
+export function isStable(current: PromptPrefix, prior: PromptPrefix): boolean {
+ return current.kind === prior.kind && current.hash === prior.hash;
+}
+
+export interface PromptPrefixPass {
+ readonly kind: GenerationHandoffKind;
+ /** One prefix per generation call in the pass, in call order. */
+ readonly prefixes: ReadonlyArray<PromptPrefix>;
+}
+
+export interface PromptPrefixSummary {
+ readonly kind: GenerationHandoffKind;
+ /** Hash of the pass's head prefix (the cacheable candidate); "" for an empty pass. */
+ readonly prefix_hash: string;
+ readonly prefix_chars: number;
+ readonly call_count: number;
+ /** How many calls reused the head prefix's bytes (the cache-eligible count). */
+ readonly stable_count: number;
+}
+
+/**
+ * Reduce a pass of generation handoffs to its run-level prefix-stability
+ * shape. `stable_count` counts the calls whose prefix matches the head
+ * call's - the bytes a provider prefix cache could reuse across the
+ * pass. An empty pass reports zeros and an empty hash.
+ */
+export function summarizePrefixPass(pass: PromptPrefixPass): PromptPrefixSummary {
+ const calls = pass.prefixes;
+ const head = calls[0];
+ return Object.freeze({
+ kind: pass.kind,
+ prefix_hash: head ? head.hash : "",
+ prefix_chars: head ? head.chars : 0,
+ call_count: calls.length,
+ stable_count: head ? calls.filter((p) => isStable(p, head)).length : 0,
+ });
+}
+
+/**
+ * Append one run-level `prompt_prefix` metric record, gated and
+ * fail-soft. With the gate off (`false | null | undefined`) nothing is
+ * built or written; a throwing append never fails the primary operation.
+ */
+export function emitPromptPrefixMetric<G>(
+ vault: string,
+ input: { readonly runAt: string; readonly summary: PromptPrefixSummary },
+ gate: G | false | null | undefined,
+): void {
+ emitGatedTelemetry(gate, () => {
+ appendMetric(vault, {
+ surface: PROMPT_PREFIX_SURFACE,
+ runAt: input.runAt,
+ payload: {
+ kind: input.summary.kind,
+ prefix_hash: input.summary.prefix_hash,
+ prefix_chars: input.summary.prefix_chars,
+ call_count: input.summary.call_count,
+ stable_count: input.summary.stable_count,
+ },
+ });
+ });
+}
diff --git a/src/core/brain/write-session/panel.ts b/src/core/brain/write-session/panel.ts
index 4f97fc5e..729914b4 100644
--- a/src/core/brain/write-session/panel.ts
+++ b/src/core/brain/write-session/panel.ts
@@ -28,6 +28,13 @@ import { createWriteSession, saveWriteSession } from "./store.ts";
import { loadPersonas } from "./personas.ts";
import { inspectExistingTarget, validateTargetPath } from "./validate.ts";
import { formatFrontmatter, slugify } from "../../vault.ts";
+import {
+ deterministicPrefix,
+ emitPromptPrefixMetric,
+ summarizePrefixPass,
+ type PromptPrefix,
+} from "../prompt-prefix.ts";
+import { isoSecond } from "../time.ts";
import type {
WriteSessionEnvelope,
WriteSessionError,
@@ -107,6 +114,12 @@ export interface SubmitPanelStepInput {
readonly sessionId: string;
readonly text: string;
readonly now?: string;
+ /**
+ * Opt-in: when the synthesis step commits, emit one run-level
+ * `prompt_prefix` metric for the whole panel pass. Omitted/false keeps
+ * the commit byte-identical and writes no metric.
+ */
+ readonly promptPrefixMetric?: boolean;
}
/** Submit the current panel step (persona answer or synthesis). */
@@ -148,6 +161,10 @@ export function submitToPanelSession(
);
}
const note = renderPanelNote(session, text, now);
+ // The synthesis is the last generation handoff of the pass; every
+ // persona step and the synthesis shared `panelPrefix(topic)`, so the
+ // pass is byte-stable by construction. Record it (opt-in, fail-soft).
+ emitPanelPrefixMetric(vault, session, now, input.promptPrefixMetric);
if (session.requireReview) {
const parked: WriteSessionRecord = Object.freeze({
...session,
@@ -199,6 +216,8 @@ export interface DispatchSubmitInput {
readonly sessionId: string;
readonly text: string;
readonly now?: string;
+ /** Forwarded to the panel flow; ignored for artifact sessions. */
+ readonly promptPrefixMetric?: boolean;
}
/**
@@ -210,13 +229,43 @@ export function dispatchSubmit(vault: string, input: DispatchSubmitInput): Write
const now = resolveNow(input.now);
const session = loadLiveSession(vault, input.sessionId, now);
if (session.kind === "panel") {
- return submitToPanelSession(vault, { sessionId: input.sessionId, text: input.text, now });
+ return submitToPanelSession(vault, {
+ sessionId: input.sessionId,
+ text: input.text,
+ now,
+ promptPrefixMetric: input.promptPrefixMetric,
+ });
}
return submitToSession(vault, { sessionId: input.sessionId, artifact: input.text, now });
}
// ----- internals -------------------------------------------------------------
+/**
+ * Emit one run-level `prompt_prefix` metric for a completed panel pass.
+ * Every step (persona answers + synthesis) shared `panelPrefix(topic)`,
+ * so the pass is fully stable by construction: `call_count` and
+ * `stable_count` both equal personas + 1. Opt-in and fail-soft.
+ */
+function emitPanelPrefixMetric(
+ vault: string,
+ session: WriteSessionRecord,
+ now: string,
+ gate: boolean | undefined,
+): void {
+ if (!gate) return;
+ const prefix = panelPrefix(session.topic);
+ const prefixes = Array.from({ length: session.personas.length + 1 }, () => prefix);
+ emitPromptPrefixMetric(
+ vault,
+ {
+ runAt: isoSecond(new Date(now)),
+ summary: summarizePrefixPass({ kind: "write_session", prefixes }),
+ },
+ gate,
+ );
+}
+
function selectPersonas(
loaded: ReadonlyArray<WriteSessionPersona>,
requested: ReadonlyArray<string> | undefined,
@@ -272,8 +321,25 @@ function nextStep(session: WriteSessionRecord, current: string): string {
return index >= 0 && index < steps.length - 1 ? steps[index + 1]! : SYNTHESIS_STEP;
}
+/**
+ * The cacheable preamble shared by every generation step of one panel
+ * pass: persona answers and the synthesis all lead with the same
+ * topic frame, so a provider prefix cache could reuse these bytes
+ * across the whole deliberation. Routed through `deterministicPrefix`
+ * to make that stability explicit; the bytes are unchanged.
+ */
+function panelPrefix(topic: string | null): PromptPrefix {
+ return deterministicPrefix({
+ kind: "write_session",
+ segments: [`Decision topic: ${topic}`, "\n\n"],
+ });
+}
+
function personaPrompt(persona: WriteSessionPersona, topic: string): string {
- return `Decision topic: ${topic}\n\nAnswer as the '${persona.slug}' panelist (${persona.lens}).\n${persona.prompt}`;
+ return (
+ panelPrefix(topic).prefix +
+ `Answer as the '${persona.slug}' panelist (${persona.lens}).\n${persona.prompt}`
+ );
}
function synthesisPrompt(session: WriteSessionRecord): string {
@@ -281,7 +347,7 @@ function synthesisPrompt(session: WriteSessionRecord): string {
.map((p) => `### ${p.lens} (${p.slug})\n${session.responses[`persona:${p.slug}`] ?? ""}`)
.join("\n\n");
return (
- `Decision topic: ${session.topic}\n\n` +
+ panelPrefix(session.topic).prefix +
`Every panelist has answered:\n\n${answers}\n\n` +
"Synthesize the deliberation into a recommendation: state the decision, the strongest supporting argument per lens, the unresolved tensions, and the conditions that would reverse it."
);
diff --git a/src/core/config.ts b/src/core/config.ts
index 851f6eb8..694fc6df 100644
--- a/src/core/config.ts
+++ b/src/core/config.ts
@@ -366,6 +366,20 @@ export function resolveRecallGateTelemetry(configPath?: string): boolean {
return raw === "true" || raw === "1";
}
+/**
+ * Generation-report tracing gate (Hindsight brain-loop ops, t_281c3edc).
+ * Default OFF: the inbound `generation_report` continuity path stays
+ * dormant unless `generation_trace_enabled: "true"`, when an agent's
+ * post-handoff usage report lands as a continuity record (prompt hash
+ * and counts only, never the prompt). A per-call option can still enable
+ * a single report when the config gate is off.
+ */
+export function resolveGenerationTraceEnabled(configPath?: string): boolean {
+ const env = process.env["OPEN_SECOND_BRAIN_GENERATION_TRACE_ENABLED"]?.trim();
+ const raw = env || discoverConfig(configPath).data["generation_trace_enabled"]?.trim();
+ return raw === "true" || raw === "1";
+}
+
/**
* Optional external judge command for the memory benchmark (Memory
* Observability Suite, t_882c396a). Unset (the default) means the
diff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.ts
index f2761999..204448d5 100644
--- a/src/mcp/brain-tools.ts
+++ b/src/mcp/brain-tools.ts
@@ -32,6 +32,7 @@ import { RESEARCH_TOOLS } from "./brain/research-tools.ts";
import { DERIVE_TOOLS } from "./brain/derive-tools.ts";
import { NOTES_TOOLS } from "./brain/notes-tools.ts";
import { SYNTHESIS_TOOLS } from "./brain/synthesis-tools.ts";
+import { GENERATION_TOOLS } from "./brain/generation-tools.ts";
import type { ToolDefinition } from "./tools.ts";
export { vaultRelativeSafe } from "./brain/shared.ts";
@@ -59,4 +60,5 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
...DERIVE_TOOLS,
...NOTES_TOOLS,
...SYNTHESIS_TOOLS,
+ ...GENERATION_TOOLS,
]);
diff --git a/src/mcp/brain/generation-tools.ts b/src/mcp/brain/generation-tools.ts
new file mode 100644
index 00000000..84895f8a
--- /dev/null
+++ b/src/mcp/brain/generation-tools.ts
@@ -0,0 +1,278 @@
+/**
+ * `brain_generation_reports` - inbound, opt-in LLM generation tracing
+ * (Hindsight brain-loop ops, t_281c3edc).
+ *
+ * Open Second Brain's kernel never calls an LLM; the agent owns
+ * generation. After it fulfils a handoff (write-session step,
+ * context-pack consume, or dream-stage proposal) it can report the real
+ * usage back through action `record`, which lands as a `generation_report`
+ * continuity record correlated to the paths and ids the kernel owns.
+ * Actions `list` and `summary` read the records and join them to memory
+ * paths. `record` is gated (default off): a per-call `enable` flag or the
+ * `generation_trace_enabled` config opens it; otherwise nothing is built
+ * or written. Only `prompt_hash` + counts are stored, never the prompt.
+ *
+ * Registration happens through the brain-tools aggregator, which
+ * preserves the public BRAIN_TOOLS surface.
+ */
+
+import { resolveGenerationTraceEnabled } from "../../core/config.ts";
+import {
+ emitGenerationReport,
+ isGenerationHandoffKind,
+ listGenerationReports,
+ summarizeGenerationReports,
+ type GenerationHandoffKind,
+ type GenerationReportFilter,
+ type GenerationUsage,
+} from "../../core/brain/generation-reports.ts";
+import type { ContinuitySourceRef } from "../../core/brain/continuity/types.ts";
+import { INVALID_PARAMS, MCPError } from "../protocol.ts";
+import type { ServerContext, ToolDefinition } from "../tools.ts";
+import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
+import { coercePositiveInteger, optionalStringArg, requiredStringArg } from "./shared.ts";
+
+const TOOL = "brain_generation_reports";
+
+async function toolBrainGenerationReports(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const action = optionalStringArg(TOOL, args, "action");
+ if (action === "record") return recordAction(ctx, args);
+ if (action === "list") {
+ const reports = listGenerationReports(ctx.vault, readFilter(args));
+ return { vault_path: ctx.vault, total: reports.length, reports };
+ }
+ if (action === "summary") {
+ return { ...summarizeGenerationReports(ctx.vault, readFilter(args)) };
+ }
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: action must be record, list, or summary`);
+}
+
+function recordAction(ctx: ServerContext, args: Record<string, unknown>): Record<string, unknown> {
+ const handoffKind = handoffKindArg(args["handoff_kind"]);
+ const ref = requiredStringArg(TOOL, args, "ref");
+ const agent = requiredStringArg(TOOL, args, "agent");
+ const prompt = requiredStringArg(TOOL, args, "prompt");
+
+ // Opt-in: per-call enable wins, else the config gate. Off => nothing written.
+ const enabled =
+ args["enable"] === true || resolveGenerationTraceEnabled(ctx.configPath ?? undefined);
+
+ const record = emitGenerationReport(
+ ctx.vault,
+ {
+ handoff: { kind: handoffKind, ref },
+ agent,
+ prompt,
+ ...(optionalStringArg(TOOL, args, "scope") !== undefined
+ ? { scope: optionalStringArg(TOOL, args, "scope") }
+ : {}),
+ ...(optionalStringArg(TOOL, args, "provider") !== undefined
+ ? { provider: optionalStringArg(TOOL, args, "provider") }
+ : {}),
+ ...(optionalStringArg(TOOL, args, "model") !== undefined
+ ? { model: optionalStringArg(TOOL, args, "model") }
+ : {}),
+ ...(optionalStringArg(TOOL, args, "finish_reason") !== undefined
+ ? { finishReason: optionalStringArg(TOOL, args, "finish_reason") }
+ : {}),
+ ...(coercePositiveInteger(TOOL, "latency_ms", args["latency_ms"]) !== undefined
+ ? { latencyMs: coercePositiveInteger(TOOL, "latency_ms", args["latency_ms"]) }
+ : {}),
+ ...(usageArg(args["usage"]) !== undefined ? { usage: usageArg(args["usage"]) } : {}),
+ ...(sourceRefArgs(args["source_refs"]).length > 0
+ ? { sourceRefs: sourceRefArgs(args["source_refs"]) }
+ : {}),
+ ...(optionalStringArg(TOOL, args, "created_at") !== undefined
+ ? { createdAt: optionalStringArg(TOOL, args, "created_at") }
+ : {}),
+ },
+ enabled,
+ );
+
+ return record !== null
+ ? { vault_path: ctx.vault, recorded: true, id: record.id }
+ : { vault_path: ctx.vault, recorded: false, reason: "disabled" };
+}
+
+function readFilter(args: Record<string, unknown>): GenerationReportFilter {
+ const handoff = optionalStringArg(TOOL, args, "handoff_kind");
+ if (handoff !== undefined && !isGenerationHandoffKind(handoff)) {
+ throw new MCPError(
+ INVALID_PARAMS,
+ `${TOOL}: handoff_kind must be write_session, context_pack, or dream_stage`,
+ );
+ }
+ const limit = coercePositiveInteger(TOOL, "limit", args["limit"]);
+ return {
+ ...(handoff !== undefined ? { handoffKind: handoff as GenerationHandoffKind } : {}),
+ ...(optionalStringArg(TOOL, args, "agent") !== undefined
+ ? { agent: optionalStringArg(TOOL, args, "agent") }
+ : {}),
+ ...(optionalStringArg(TOOL, args, "since") !== undefined
+ ? { since: optionalStringArg(TOOL, args, "since") }
+ : {}),
+ ...(optionalStringArg(TOOL, args, "until") !== undefined
+ ? { until: optionalStringArg(TOOL, args, "until") }
+ : {}),
+ ...(limit !== undefined ? { limit } : {}),
+ };
+}
+
+function handoffKindArg(raw: unknown): GenerationHandoffKind {
+ if (typeof raw !== "string" || raw.trim().length === 0) {
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: handoff_kind is required for record`);
+ }
+ const value = raw.trim();
+ if (!isGenerationHandoffKind(value)) {
+ throw new MCPError(
+ INVALID_PARAMS,
+ `${TOOL}: handoff_kind must be write_session, context_pack, or dream_stage`,
+ );
+ }
+ return value;
+}
+
+function usageArg(raw: unknown): GenerationUsage | undefined {
+ if (raw === undefined || raw === null) return undefined;
+ if (typeof raw !== "object" || Array.isArray(raw)) {
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: usage must be an object`);
+ }
+ const obj = raw as Record<string, unknown>;
+ const usage: GenerationUsage = {
+ ...(numberArg(obj["input_tokens"], "usage.input_tokens") !== undefined
+ ? { inputTokens: numberArg(obj["input_tokens"], "usage.input_tokens") }
+ : {}),
+ ...(numberArg(obj["output_tokens"], "usage.output_tokens") !== undefined
+ ? { outputTokens: numberArg(obj["output_tokens"], "usage.output_tokens") }
+ : {}),
+ ...(numberArg(obj["cached_tokens"], "usage.cached_tokens") !== undefined
+ ? { cachedTokens: numberArg(obj["cached_tokens"], "usage.cached_tokens") }
+ : {}),
+ ...(numberArg(obj["total_tokens"], "usage.total_tokens") !== undefined
+ ? { totalTokens: numberArg(obj["total_tokens"], "usage.total_tokens") }
+ : {}),
+ };
+ return Object.keys(usage).length > 0 ? usage : undefined;
+}
+
+function numberArg(raw: unknown, key: string): number | undefined {
+ if (raw === undefined || raw === null) return undefined;
+ if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: ${key} must be a non-negative integer`);
+ }
+ return raw;
+}
+
+function sourceRefArgs(raw: unknown): ReadonlyArray<ContinuitySourceRef> {
+ if (raw === undefined || raw === null) return [];
+ if (!Array.isArray(raw)) {
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: source_refs must be an array`);
+ }
+ return raw.map((entry, index) => {
+ if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: source_refs[${index}] must be an object`);
+ }
+ const obj = entry as Record<string, unknown>;
+ const id = obj["id"];
+ if (typeof id !== "string" || id.trim().length === 0) {
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: source_refs[${index}].id must be a string`);
+ }
+ const ref: ContinuitySourceRef = {
+ id: id.trim(),
+ ...(typeof obj["path"] === "string" && obj["path"].trim().length > 0
+ ? { path: obj["path"].trim() }
+ : {}),
+ ...(typeof obj["kind"] === "string" && obj["kind"].trim().length > 0
+ ? { kind: obj["kind"].trim() }
+ : {}),
+ };
+ return ref;
+ });
+}
+
+export const GENERATION_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
+ {
+ name: TOOL,
+ previewBudget: MCP_PREVIEW_BUDGET,
+ description:
+ "Inbound, opt-in LLM generation tracing; the kernel never calls an LLM. action=record posts a generation's usage for a handoff, gated default-off via enable or generation_trace_enabled, storing prompt_hash + token counts only, never the prompt. action=list/summary read and join to memory paths.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ action: {
+ type: "string",
+ enum: ["record", "list", "summary"],
+ description: "record an inbound report, or list/summary the stored reports.",
+ },
+ handoff_kind: {
+ type: "string",
+ enum: ["write_session", "context_pack", "dream_stage"],
+ description:
+ "record: which handoff this generation fulfilled. Also filters list/summary.",
+ },
+ ref: {
+ type: "string",
+ description: "record: the handoff id (session id, receipt id, run id).",
+ },
+ agent: {
+ type: "string",
+ description: "record: reporting agent; also filters list/summary.",
+ },
+ prompt: {
+ type: "string",
+ description:
+ "record: the exact handoff prompt. Hashed and counted only - never stored as raw text.",
+ },
+ enable: {
+ type: "boolean",
+ description: "record: open the gate for this single call even if the config gate is off.",
+ },
+ scope: { type: "string", description: "record: optional scope label." },
+ provider: { type: "string", description: "record: opaque agent-reported provider." },
+ model: { type: "string", description: "record: opaque agent-reported model." },
+ finish_reason: { type: "string", description: "record: optional finish reason." },
+ latency_ms: { type: "integer", minimum: 1, description: "record: optional latency in ms." },
+ usage: {
+ type: "object",
+ description:
+ "record: optional agent-reported token usage (input_tokens, output_tokens, cached_tokens, total_tokens).",
+ properties: {
+ input_tokens: { type: "integer", minimum: 0 },
+ output_tokens: { type: "integer", minimum: 0 },
+ cached_tokens: { type: "integer", minimum: 0 },
+ total_tokens: { type: "integer", minimum: 0 },
+ },
+ additionalProperties: false,
+ },
+ source_refs: {
+ type: "array",
+ description:
+ "record: artifact join refs ({id, path?, kind?}) - e.g. the memory paths this generation produced or consumed.",
+ items: {
+ type: "object",
+ properties: {
+ id: { type: "string" },
+ path: { type: "string" },
+ kind: { type: "string" },
+ },
+ required: ["id"],
+ additionalProperties: false,
+ },
+ },
+ created_at: {
+ type: "string",
+ description: "record: optional ISO timestamp (defaults to now).",
+ },
+ since: { type: "string", description: "list/summary: inclusive ISO lower bound." },
+ until: { type: "string", description: "list/summary: inclusive ISO upper bound." },
+ limit: { type: "integer", minimum: 1, description: "list: maximum record count." },
+ },
+ required: ["action"],
+ additionalProperties: false,
+ },
+ handler: toolBrainGenerationReports,
+ },
+]);
diff --git a/tests/cli/brain-dream-stage.test.ts b/tests/cli/brain-dream-stage.test.ts
index 0850d6cb..7680f52f 100644
--- a/tests/cli/brain-dream-stage.test.ts
+++ b/tests/cli/brain-dream-stage.test.ts
@@ -76,6 +76,8 @@ test("full stage -> validate -> apply cycle via the CLI", async () => {
"dream",
"validate",
stagedOut.run_id,
+ "--now",
+ "2026-06-05T12:00:00Z",
"--vault",
vault,
"--json",
@@ -88,6 +90,8 @@ test("full stage -> validate -> apply cycle via the CLI", async () => {
"dream",
"apply",
stagedOut.run_id,
+ "--now",
+ "2026-06-05T12:00:00Z",
"--vault",
vault,
"--json",
diff --git a/tests/cli/brain-generation-reports.test.ts b/tests/cli/brain-generation-reports.test.ts
new file mode 100644
index 00000000..2df52503
--- /dev/null
+++ b/tests/cli/brain-generation-reports.test.ts
@@ -0,0 +1,133 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { listGenerationReports } from "../../src/core/brain/generation-reports.ts";
+import { runCli } from "../helpers/run-cli.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-generation-reports-cli-"));
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+test("record is gated: without --enable nothing is written", async () => {
+ const res = await runCli([
+ "brain",
+ "generation-reports",
+ "record",
+ "write_session",
+ "--ref",
+ "ws-1",
+ "--agent",
+ "tester",
+ "--prompt",
+ "do the thing",
+ "--vault",
+ vault,
+ "--json",
+ ]);
+ expect(res.returncode).toBe(0);
+ expect(JSON.parse(res.stdout)).toMatchObject({ recorded: false, reason: "disabled" });
+ expect(listGenerationReports(vault)).toHaveLength(0);
+});
+
+test("record --enable writes one report; list and summary read it back", async () => {
+ const rec = await runCli([
+ "brain",
+ "generation-reports",
+ "record",
+ "write_session",
+ "--enable",
+ "--ref",
+ "ws-7",
+ "--agent",
+ "tester",
+ "--provider",
+ "anthropic",
+ "--model",
+ "claude-opus-4-7",
+ "--prompt",
+ "synthesize secret token=sk-keep-out",
+ "--input-tokens",
+ "100",
+ "--total-tokens",
+ "150",
+ "--source",
+ "pref-foo=Brain/preferences/pref-foo.md",
+ "--created-at",
+ "2026-06-15T09:00:00Z",
+ "--vault",
+ vault,
+ "--json",
+ ]);
+ expect(rec.returncode).toBe(0);
+ const recJson = JSON.parse(rec.stdout);
+ expect(recJson.recorded).toBe(true);
+ expect(recJson.id).toStartWith("ctn_");
+ // The raw prompt must not leak into CLI output.
+ expect(rec.stdout).not.toContain("sk-keep-out");
+
+ const list = await runCli([
+ "brain",
+ "generation-reports",
+ "list",
+ "--handoff",
+ "write_session",
+ "--vault",
+ vault,
+ "--json",
+ ]);
+ expect(list.returncode).toBe(0);
+ const listJson = JSON.parse(list.stdout);
+ expect(listJson.total).toBe(1);
+ expect(listJson.reports[0].payload).toMatchObject({
+ handoff: { kind: "write_session", ref: "ws-7" },
+ agent: "tester",
+ provider: "anthropic",
+ usage: { input_tokens: 100, total_tokens: 150 },
+ });
+ expect(JSON.stringify(listJson)).not.toContain("sk-keep-out");
+
+ const summary = await runCli([
+ "brain",
+ "generation-reports",
+ "summary",
+ "--vault",
+ vault,
+ "--json",
+ ]);
+ expect(summary.returncode).toBe(0);
+ const summaryJson = JSON.parse(summary.stdout);
+ expect(summaryJson).toMatchObject({
+ total: 1,
+ by_handoff_kind: { write_session: 1 },
+ reported_count: 1,
+ });
+ expect(summaryJson.by_path["Brain/preferences/pref-foo.md"]).toEqual([listJson.reports[0].id]);
+});
+
+test("record rejects an unknown handoff kind", async () => {
+ const res = await runCli([
+ "brain",
+ "generation-reports",
+ "record",
+ "not_a_kind",
+ "--enable",
+ "--ref",
+ "x",
+ "--agent",
+ "a",
+ "--prompt",
+ "p",
+ "--vault",
+ vault,
+ ]);
+ expect(res.returncode).not.toBe(0);
+});
diff --git a/tests/core/brain/continuity-generation-report.test.ts b/tests/core/brain/continuity-generation-report.test.ts
new file mode 100644
index 00000000..f0beffd8
--- /dev/null
+++ b/tests/core/brain/continuity-generation-report.test.ts
@@ -0,0 +1,193 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { listContinuityRecords } from "../../../src/core/brain/continuity/store.ts";
+import {
+ emitGenerationReport,
+ listGenerationReports,
+ summarizeGenerationReports,
+} from "../../../src/core/brain/generation-reports.ts";
+import { estimateTokens } from "../../../src/core/brain/text/tokenizer.ts";
+import { continuityLogPath } from "../../../src/core/brain/continuity/store.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-generation-report-"));
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+const PROMPT =
+ "Synthesize the persona for [[pref-keep-short]] using secret token=sk-do-not-store-1234";
+
+describe("generation_report continuity kind", () => {
+ test("gate ON writes one record with envelope, kind, and content-hash id", () => {
+ const record = emitGenerationReport(
+ vault,
+ {
+ handoff: { kind: "write_session", ref: "ws_session-1" },
+ agent: "claude-vps-agent",
+ provider: "anthropic",
+ model: "claude-opus-4-7",
+ finishReason: "stop",
+ latencyMs: 1234,
+ prompt: PROMPT,
+ usage: { inputTokens: 900, outputTokens: 120, cachedTokens: 800, totalTokens: 1020 },
+ sourceRefs: [
+ { id: "ws_session-1", kind: "write_session" },
+ { id: "pref-keep-short", path: "Brain/preferences/pref-keep-short.md" },
+ ],
+ createdAt: "2026-06-15T10:00:00Z",
+ },
+ true,
+ );
+
+ expect(record).not.toBeNull();
+ expect(record!.id).toStartWith("ctn_");
+ expect(record!.schema).toBe("o2b.continuity.v1");
+ expect(record!.kind).toBe("generation_report");
+
+ const stored = listContinuityRecords(vault, { kind: "generation_report" });
+ expect(stored).toHaveLength(1);
+ expect(stored[0]!.id).toBe(record!.id);
+
+ // Identical inputs => identical dedup id.
+ const again = emitGenerationReport(
+ vault,
+ {
+ handoff: { kind: "write_session", ref: "ws_session-1" },
+ agent: "claude-vps-agent",
+ provider: "anthropic",
+ model: "claude-opus-4-7",
+ finishReason: "stop",
+ latencyMs: 1234,
+ prompt: PROMPT,
+ usage: { inputTokens: 900, outputTokens: 120, cachedTokens: 800, totalTokens: 1020 },
+ sourceRefs: [
+ { id: "ws_session-1", kind: "write_session" },
+ { id: "pref-keep-short", path: "Brain/preferences/pref-keep-short.md" },
+ ],
+ createdAt: "2026-06-15T10:00:00Z",
+ },
+ true,
+ );
+ expect(again!.id).toBe(record!.id);
+ });
+
+ test("gate OFF builds no payload and writes nothing", () => {
+ for (const gate of [false, null, undefined] as const) {
+ const record = emitGenerationReport(
+ vault,
+ {
+ handoff: { kind: "dream_stage", ref: "dream-1" },
+ agent: "a",
+ prompt: PROMPT,
+ createdAt: "2026-06-15T10:00:00Z",
+ },
+ gate,
+ );
+ expect(record).toBeNull();
+ }
+ expect(listContinuityRecords(vault, { kind: "generation_report" })).toHaveLength(0);
+ });
+
+ test("stores prompt_hash + prompt_chars + usage counts only; never raw prompt or output", () => {
+ emitGenerationReport(
+ vault,
+ {
+ handoff: { kind: "context_pack", ref: "ctn_receipt-1" },
+ agent: "a",
+ prompt: PROMPT,
+ usage: { inputTokens: 10, outputTokens: 5 },
+ createdAt: "2026-06-15T11:00:00Z",
+ },
+ true,
+ );
+ const payload = listContinuityRecords(vault, { kind: "generation_report" })[0]!.payload;
+ expect(payload["prompt_hash"]).toMatch(/^[a-f0-9]{64}$/);
+ expect(payload["prompt_chars"]).toBe([...PROMPT].length);
+
+ // The raw prompt text must not survive to disk anywhere.
+ const onDisk = readFileSync(continuityLogPath(vault, "2026-06"), "utf8");
+ expect(onDisk).not.toContain("Synthesize the persona");
+ expect(onDisk).not.toContain("sk-do-not-store-1234");
+ });
+
+ test("local_estimate.input_tokens always present; usage absent reported as absent", () => {
+ emitGenerationReport(
+ vault,
+ {
+ handoff: { kind: "write_session", ref: "ws-x" },
+ agent: "a",
+ prompt: PROMPT,
+ createdAt: "2026-06-15T12:00:00Z",
+ },
+ true,
+ );
+ const payload = listGenerationReports(vault)[0]!.payload;
+ expect((payload["local_estimate"] as Record<string, unknown>)["input_tokens"]).toBe(
+ estimateTokens(PROMPT),
+ );
+ expect(payload["usage"]).toBeUndefined();
+ });
+
+ test("sourceRefs join report to handoff ref and memory paths", () => {
+ emitGenerationReport(
+ vault,
+ {
+ handoff: { kind: "write_session", ref: "ws_session-7" },
+ agent: "a",
+ prompt: "short",
+ sourceRefs: [{ id: "pref-foo", path: "Brain/preferences/pref-foo.md" }],
+ createdAt: "2026-06-15T13:00:00Z",
+ },
+ true,
+ );
+ const record = listGenerationReports(vault)[0]!;
+ const ids = record.sourceRefs.map((ref) => ref.id);
+ expect(ids).toContain("ws_session-7");
+ expect(ids).toContain("pref-foo");
+
+ const summary = summarizeGenerationReports(vault);
+ expect(summary.total).toBe(1);
+ expect(summary.by_handoff_kind["write_session"]).toBe(1);
+ expect(summary.local_estimate_tokens).toBe(estimateTokens("short"));
+ // memory-path linkage: a path resolves back to the report ids.
+ expect(summary.by_path["Brain/preferences/pref-foo.md"]).toEqual([record.id]);
+ });
+
+ test("no fetch/provider HTTP call is added under src/core for this feature", () => {
+ // The kernel never calls an LLM: tracing is inbound-only. Guard the
+ // feature source so a future edit cannot smuggle in an outbound call.
+ const source = readFileSync(
+ join(import.meta.dir, "../../../src/core/brain/generation-reports.ts"),
+ "utf8",
+ );
+ expect(source).not.toMatch(/\bfetch\s*\(/);
+ expect(source).not.toMatch(/https?:\/\//);
+ expect(source).not.toMatch(/XMLHttpRequest|node:http|undici/);
+ });
+
+ test("fail-open: a throwing build is swallowed (gate carries options)", () => {
+ // A non-string prompt would throw inside the build thunk; the emit
+ // wrapper must swallow it and return null, never propagate.
+ const record = emitGenerationReport(
+ vault,
+ {
+ handoff: { kind: "write_session", ref: "ws-bad" },
+ agent: "a",
+ // @ts-expect-error deliberately invalid to force a throw inside the thunk
+ prompt: 123,
+ createdAt: "2026-06-15T14:00:00Z",
+ },
+ true,
+ );
+ expect(record).toBeNull();
+ expect(listContinuityRecords(vault, { kind: "generation_report" })).toHaveLength(0);
+ });
+});
diff --git a/tests/core/brain/metrics-prompt-prefix.test.ts b/tests/core/brain/metrics-prompt-prefix.test.ts
new file mode 100644
index 00000000..584d7945
--- /dev/null
+++ b/tests/core/brain/metrics-prompt-prefix.test.ts
@@ -0,0 +1,155 @@
+/**
+ * Prompt-prefix metric wiring (Hindsight brain-loop ops, t_d8c1f7d9).
+ *
+ * The genuine multi-call generation pass in Open Second Brain is the
+ * decision panel: every persona step and the synthesis lead with the
+ * same `Decision topic:` frame, so the pass is byte-stable by
+ * construction. A context-pack consume is a single-call pass over its
+ * stable request preamble. Both routes:
+ * - keep the default output byte-identical (no metric, no option), and
+ * - emit exactly one run-level `prompt_prefix` record when opted in.
+ */
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ openPanelSession,
+ submitToPanelSession,
+} from "../../../src/core/brain/write-session/panel.ts";
+import { DEFAULT_PERSONAS } from "../../../src/core/brain/write-session/personas.ts";
+import { packContext } from "../../../src/core/brain/context-pack.ts";
+import { listMetrics, METRICS_SCHEMA_VERSION } from "../../../src/core/brain/metrics.ts";
+import { PROMPT_PREFIX_SURFACE } from "../../../src/core/brain/prompt-prefix.ts";
+
+const NOW = "2026-06-04T10:00:00.000Z";
+const TOPIC = "Adopt the new sync engine";
+const PERSONA_TEXTS = [
+ "Technically feasible with bounded effort.",
+ "Strategically sound.",
+ "Risk is acceptable.",
+ "Users benefit immediately.",
+];
+
+let tmp: string;
+let vault: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-prefix-metric-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+function metricPath(): string {
+ return join(vault, "Brain", "metrics", `${PROMPT_PREFIX_SURFACE}.jsonl`);
+}
+
+function openPanel() {
+ return openPanelSession(vault, { agent: "fixture-agent", topic: TOPIC, now: NOW });
+}
+
+/** Drive the four persona steps; returns the synthesis-step envelope. */
+function drivePersonas(sessionId: string) {
+ let env;
+ for (const text of PERSONA_TEXTS) {
+ env = submitToPanelSession(vault, { sessionId, text, now: NOW });
+ }
+ return env!;
+}
+
+// ----- byte-identity (the default path is unchanged) -------------------------
+
+test("the persona prompt is byte-identical to the pre-routing literal", () => {
+ const env = openPanel();
+ const p = DEFAULT_PERSONAS[0]!;
+ const expected = `Decision topic: ${TOPIC}\n\nAnswer as the '${p.slug}' panelist (${p.lens}).\n${p.prompt}`;
+ expect(env.prompt).toBe(expected);
+});
+
+test("the synthesis prompt keeps the shared prefix and synthesis tail", () => {
+ const open = openPanel();
+ const synth = drivePersonas(open.session_id);
+ expect(synth.step).toBe("synthesis");
+ const answers = DEFAULT_PERSONAS.map(
+ (p, i) => `### ${p.lens} (${p.slug})\n${PERSONA_TEXTS[i]}`,
+ ).join("\n\n");
+ const expected =
+ `Decision topic: ${TOPIC}\n\n` +
+ `Every panelist has answered:\n\n${answers}\n\n` +
+ "Synthesize the deliberation into a recommendation: state the decision, the strongest supporting argument per lens, the unresolved tensions, and the conditions that would reverse it.";
+ expect(synth.prompt).toBe(expected);
+});
+
+test("committing a panel without the gate writes no prompt_prefix metric", () => {
+ const open = openPanel();
+ drivePersonas(open.session_id);
+ const committed = submitToPanelSession(vault, {
+ sessionId: open.session_id,
+ text: "Adopt it under the stated guardrails.",
+ now: NOW,
+ });
+ expect(committed.status).toBe("done");
+ expect(existsSync(metricPath())).toBe(false);
+});
+
+// ----- opt-in emission -------------------------------------------------------
+
+test("a panel pass with the gate on writes one run-level prompt_prefix record", () => {
+ const open = openPanel();
+ drivePersonas(open.session_id);
+ const committed = submitToPanelSession(vault, {
+ sessionId: open.session_id,
+ text: "Adopt it under the stated guardrails.",
+ now: NOW,
+ promptPrefixMetric: true,
+ });
+ expect(committed.status).toBe("done");
+
+ const lines = readFileSync(metricPath(), "utf8")
+ .split("\n")
+ .filter((l) => l.trim().length > 0);
+ expect(lines).toHaveLength(1);
+ const record = JSON.parse(lines[0]!);
+ expect(record.schema).toBe(METRICS_SCHEMA_VERSION);
+ expect(record.surface).toBe(PROMPT_PREFIX_SURFACE);
+ expect(record.payload.kind).toBe("write_session");
+ // Four personas + synthesis, all sharing the same topic prefix.
+ expect(record.payload.call_count).toBe(DEFAULT_PERSONAS.length + 1);
+ expect(record.payload.stable_count).toBe(DEFAULT_PERSONAS.length + 1);
+ expect(record.payload.prefix_hash).toMatch(/^[0-9a-f]{64}$/);
+ expect(record.payload.prefix_chars).toBe([...`Decision topic: ${TOPIC}\n\n`].length);
+});
+
+test("context-pack default path is byte-identical and writes no metric", () => {
+ writeFileSync(
+ join(vault, "Brain", "preferences", "pref-x.md"),
+ ["---", "id: pref-x", "topic: T", "principle: P", "tier: core", "---", "", "body"].join("\n"),
+ );
+ const baseline = packContext(vault, { maxTokens: 1000, query: "T" });
+ const again = packContext(vault, { maxTokens: 1000, query: "T" });
+ expect(again).toEqual(baseline);
+ expect(existsSync(metricPath())).toBe(false);
+});
+
+test("context-pack with the gate on emits a single-call prompt_prefix pass", () => {
+ writeFileSync(
+ join(vault, "Brain", "preferences", "pref-x.md"),
+ ["---", "id: pref-x", "topic: T", "principle: P", "tier: core", "---", "", "body"].join("\n"),
+ );
+ const withGate = packContext(vault, { maxTokens: 1000, query: "T", promptPrefix: true });
+ const withoutGate = packContext(vault, { maxTokens: 1000, query: "T" });
+ // The report itself is unchanged by the opt-in metric.
+ expect(withGate).toEqual(withoutGate);
+
+ const records = listMetrics(vault, { surface: PROMPT_PREFIX_SURFACE });
+ expect(records).toHaveLength(1);
+ expect(records[0]!.payload.kind).toBe("context_pack");
+ expect(records[0]!.payload.call_count).toBe(1);
+ expect(records[0]!.payload.stable_count).toBe(1);
+});
diff --git a/tests/core/brain/prompt-prefix.test.ts b/tests/core/brain/prompt-prefix.test.ts
new file mode 100644
index 00000000..7c330fff
--- /dev/null
+++ b/tests/core/brain/prompt-prefix.test.ts
@@ -0,0 +1,177 @@
+/**
+ * Structural prompt-prefix stability (Hindsight brain-loop ops,
+ * t_d8c1f7d9): the kernel never calls an LLM, so it cannot attach a
+ * provider cache hint to an outbound request. What it CAN guarantee is
+ * the byte-stable prompt prefix a provider cache rewards. These tests
+ * cover the pure helpers and the gated, fail-soft metric emit.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ PROMPT_PREFIX_SURFACE,
+ canonicalSegment,
+ deterministicPrefix,
+ emitPromptPrefixMetric,
+ isStable,
+ summarizePrefixPass,
+} from "../../../src/core/brain/prompt-prefix.ts";
+import { METRICS_SCHEMA_VERSION, listMetrics } from "../../../src/core/brain/metrics.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-prompt-prefix-"));
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+describe("deterministicPrefix", () => {
+ test("byte-identical prefix and hash for identical inputs", () => {
+ const a = deterministicPrefix({
+ kind: "write_session",
+ segments: ["Decision topic: X", "\n\n"],
+ });
+ const b = deterministicPrefix({
+ kind: "write_session",
+ segments: ["Decision topic: X", "\n\n"],
+ });
+ expect(a.prefix).toBe("Decision topic: X\n\n");
+ expect(a.hash).toBe(b.hash);
+ expect(a.prefix).toBe(b.prefix);
+ expect(a.chars).toBe(b.chars);
+ // 64 hex chars = full sha-256.
+ expect(a.hash).toMatch(/^[0-9a-f]{64}$/);
+ });
+
+ test("differs predictably when inputs change", () => {
+ const a = deterministicPrefix({ kind: "write_session", segments: ["topic A"] });
+ const b = deterministicPrefix({ kind: "write_session", segments: ["topic B"] });
+ expect(a.hash).not.toBe(b.hash);
+ });
+
+ test("chars counts code points, not UTF-16 units", () => {
+ const p = deterministicPrefix({ kind: "context_pack", segments: ["💡"] });
+ expect(p.chars).toBe(1);
+ });
+});
+
+describe("canonicalSegment", () => {
+ test("key order does not perturb the bytes", () => {
+ const a = canonicalSegment({ b: "2", a: "1", c: "3" });
+ const b = canonicalSegment({ c: "3", a: "1", b: "2" });
+ expect(a).toBe(b);
+ expect(a).toBe("a=1\nb=2\nc=3");
+ });
+});
+
+describe("isStable", () => {
+ test("true only when kind and hash both match", () => {
+ const base = deterministicPrefix({ kind: "write_session", segments: ["X"] });
+ const same = deterministicPrefix({ kind: "write_session", segments: ["X"] });
+ const otherText = deterministicPrefix({ kind: "write_session", segments: ["Y"] });
+ const otherKind = deterministicPrefix({ kind: "context_pack", segments: ["X"] });
+ expect(isStable(base, same)).toBe(true);
+ expect(isStable(base, otherText)).toBe(false);
+ expect(isStable(base, otherKind)).toBe(false);
+ });
+});
+
+describe("summarizePrefixPass", () => {
+ test("all calls share the head prefix => full stability", () => {
+ const p = deterministicPrefix({ kind: "write_session", segments: ["Decision topic: X\n\n"] });
+ const summary = summarizePrefixPass({ kind: "write_session", prefixes: [p, p, p, p, p] });
+ expect(summary).toEqual({
+ kind: "write_session",
+ prefix_hash: p.hash,
+ prefix_chars: p.chars,
+ call_count: 5,
+ stable_count: 5,
+ });
+ });
+
+ test("counts only the calls reusing the head prefix", () => {
+ const head = deterministicPrefix({ kind: "write_session", segments: ["A"] });
+ const drift = deterministicPrefix({ kind: "write_session", segments: ["B"] });
+ const summary = summarizePrefixPass({
+ kind: "write_session",
+ prefixes: [head, head, drift, head],
+ });
+ expect(summary.call_count).toBe(4);
+ expect(summary.stable_count).toBe(3);
+ expect(summary.prefix_hash).toBe(head.hash);
+ });
+
+ test("empty pass reports zeros and an empty hash", () => {
+ const summary = summarizePrefixPass({ kind: "context_pack", prefixes: [] });
+ expect(summary).toEqual({
+ kind: "context_pack",
+ prefix_hash: "",
+ prefix_chars: 0,
+ call_count: 0,
+ stable_count: 0,
+ });
+ });
+});
+
+describe("emitPromptPrefixMetric", () => {
+ const summary = {
+ kind: "write_session" as const,
+ prefix_hash: "abc",
+ prefix_chars: 7,
+ call_count: 5,
+ stable_count: 5,
+ };
+ const runAt = "2026-06-05T10:00:00Z";
+
+ test("gate on writes one run-level prompt_prefix record", () => {
+ emitPromptPrefixMetric(vault, { runAt, summary }, true);
+ const path = join(vault, "Brain", "metrics", `${PROMPT_PREFIX_SURFACE}.jsonl`);
+ expect(existsSync(path)).toBe(true);
+ const lines = readFileSync(path, "utf8")
+ .split("\n")
+ .filter((l) => l.trim().length > 0);
+ expect(lines).toHaveLength(1);
+ expect(JSON.parse(lines[0]!)).toEqual({
+ schema: METRICS_SCHEMA_VERSION,
+ surface: PROMPT_PREFIX_SURFACE,
+ run_at: runAt,
+ payload: {
+ kind: "write_session",
+ prefix_hash: "abc",
+ prefix_chars: 7,
+ call_count: 5,
+ stable_count: 5,
+ },
+ });
+ });
+
+ test("listMetrics discovers the surface with no metrics.ts change", () => {
+ emitPromptPrefixMetric(vault, { runAt, summary }, true);
+ const records = listMetrics(vault, { surface: PROMPT_PREFIX_SURFACE });
+ expect(records).toHaveLength(1);
+ expect(records[0]!.surface).toBe(PROMPT_PREFIX_SURFACE);
+ expect(records[0]!.payload.call_count).toBe(5);
+ });
+
+ test("gate off writes nothing", () => {
+ emitPromptPrefixMetric(vault, { runAt, summary }, false);
+ emitPromptPrefixMetric(vault, { runAt, summary }, undefined);
+ emitPromptPrefixMetric(vault, { runAt, summary }, null);
+ expect(existsSync(join(vault, "Brain", "metrics"))).toBe(false);
+ });
+
+ test("a bad runAt is swallowed (fail-soft), never throwing", () => {
+ expect(() =>
+ emitPromptPrefixMetric(vault, { runAt: "not-a-timestamp", summary }, true),
+ ).not.toThrow();
+ expect(existsSync(join(vault, "Brain", "metrics", `${PROMPT_PREFIX_SURFACE}.jsonl`))).toBe(
+ false,
+ );
+ });
+});
diff --git a/tests/mcp/brain-tools-parity.test.ts b/tests/mcp/brain-tools-parity.test.ts
index 93ba3977..c167d4a3 100644
--- a/tests/mcp/brain-tools-parity.test.ts
+++ b/tests/mcp/brain-tools-parity.test.ts
@@ -12,7 +12,9 @@
* added `brain_intake_entities`, `brain_ingest_source`,
* `brain_research_report`, and `brain_derive_fact` (Knowledge Provenance
* suite); the codegraph-and-MCP operational-readability release added
- * `brain_codegraph_report` (read-only codegraph partner report).
+ * `brain_codegraph_report` (read-only codegraph partner report); the
+ * Hindsight brain-loop ops release added `brain_generation_reports`
+ * (inbound, opt-in LLM generation tracing).
*/
import { describe, expect, test } from "bun:test";
@@ -45,6 +47,7 @@ const FROZEN_BRAIN_TOOL_NAMES = [
"brain_entity",
"brain_feedback",
"brain_foresight",
+ "brain_generation_reports",
"brain_health",
"brain_hygiene",
"brain_idea_discovery",
diff --git a/tests/mcp/dream-stage-tool.test.ts b/tests/mcp/dream-stage-tool.test.ts
index 564db4f5..dd7165a2 100644
--- a/tests/mcp/dream-stage-tool.test.ts
+++ b/tests/mcp/dream-stage-tool.test.ts
@@ -104,10 +104,18 @@ test("full staged cycle through tools/call", async () => {
const runId = staged.structured!["run_id"] as string;
expect(runId).toMatch(/^stage-/);
- const validated = await call(server, { action: "validate", run_id: runId });
+ const validated = await call(server, {
+ action: "validate",
+ run_id: runId,
+ now: "2026-06-05T12:00:00Z",
+ });
expect(validated.structured!["valid"]).toBe(true);
- const applied = await call(server, { action: "apply", run_id: runId });
+ const applied = await call(server, {
+ action: "apply",
+ run_id: runId,
+ now: "2026-06-05T12:00:00Z",
+ });
expect(applied.structured!["applied"]).toBe(true);
expect(applied.structured!["new_unconfirmed"]).toEqual(["pref-mcp-cycle"]);
diff --git a/tests/mcp/generation-reports-tool.test.ts b/tests/mcp/generation-reports-tool.test.ts
new file mode 100644
index 00000000..9e4270ab
--- /dev/null
+++ b/tests/mcp/generation-reports-tool.test.ts
@@ -0,0 +1,155 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { listGenerationReports } from "../../src/core/brain/generation-reports.ts";
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
+import { buildToolTable } from "../../src/mcp/tools.ts";
+
+let tmp: string;
+let vault: string;
+let configHome: string;
+let configPath: string;
+const savedEnv: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-generation-reports-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ configHome = mkdtempSync(join(tmpdir(), "o2b-mcp-generation-reports-cfg-"));
+ configPath = join(configHome, "config.yaml");
+ for (const key of [
+ "VAULT_AGENT_NAME",
+ "VAULT_TIMEZONE",
+ "VAULT_DIR",
+ "OPEN_SECOND_BRAIN_CONFIG",
+ "OPEN_SECOND_BRAIN_GENERATION_TRACE_ENABLED",
+ ]) {
+ savedEnv[key] = process.env[key];
+ delete process.env[key];
+ }
+ process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+ for (const [key, value] of Object.entries(savedEnv)) {
+ if (value === undefined) delete process.env[key];
+ else process.env[key] = value;
+ }
+});
+
+async function initialize(server: MCPServer): Promise<void> {
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "initialize",
+ params: {
+ protocolVersion: PROTOCOL_VERSION,
+ capabilities: {},
+ clientInfo: { name: "generation-reports-test", version: "0" },
+ },
+ });
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ method: "notifications/initialized",
+ });
+}
+
+async function call(
+ server: MCPServer,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const response = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: { name: "brain_generation_reports", arguments: args },
+ })) as { result: { content: ReadonlyArray<{ type: string; text: string }> } };
+ return JSON.parse(response.result.content[0]!.text);
+}
+
+describe("brain_generation_reports tool registration", () => {
+ test("registered in the full tool table, absent from writer-only", () => {
+ expect(
+ buildToolTable("full").find((tool) => tool.name === "brain_generation_reports"),
+ ).toBeDefined();
+ expect(
+ buildToolTable("writer").find((tool) => tool.name === "brain_generation_reports"),
+ ).toBeUndefined();
+ });
+});
+
+describe("brain_generation_reports tool", () => {
+ test("record is gated off by default and writes nothing", async () => {
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const res = await call(server, {
+ action: "record",
+ handoff_kind: "write_session",
+ ref: "ws-1",
+ agent: "tester",
+ prompt: "do the thing",
+ });
+ expect(res).toMatchObject({ recorded: false, reason: "disabled" });
+ expect(listGenerationReports(vault)).toHaveLength(0);
+ });
+
+ test("record with enable writes one report; list and summary read it back", async () => {
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ const rec = await call(server, {
+ action: "record",
+ handoff_kind: "context_pack",
+ ref: "ctn_receipt-1",
+ agent: "tester",
+ enable: true,
+ prompt: "consume context secret token=sk-keep-out",
+ usage: { input_tokens: 50, output_tokens: 20 },
+ source_refs: [{ id: "pref-foo", path: "Brain/preferences/pref-foo.md" }],
+ created_at: "2026-06-15T08:00:00Z",
+ });
+ expect(rec["recorded"]).toBe(true);
+ expect(rec["id"]).toStartWith("ctn_");
+
+ const list = await call(server, { action: "list", handoff_kind: "context_pack" });
+ expect(list["total"]).toBe(1);
+ const report = (list["reports"] as Array<Record<string, unknown>>)[0]!;
+ expect(report["payload"]).toMatchObject({
+ handoff: { kind: "context_pack", ref: "ctn_receipt-1" },
+ agent: "tester",
+ usage: { input_tokens: 50, output_tokens: 20 },
+ });
+ // The raw prompt must never appear in the tool output.
+ expect(JSON.stringify(list)).not.toContain("sk-keep-out");
+ expect(JSON.stringify(list)).not.toContain("consume context");
+
+ const summary = await call(server, { action: "summary" });
+ expect(summary).toMatchObject({
+ total: 1,
+ by_handoff_kind: { context_pack: 1 },
+ reported_count: 1,
+ });
+ expect(
+ (summary["by_path"] as Record<string, unknown>)["Brain/preferences/pref-foo.md"],
+ ).toEqual([report["id"]]);
+ });
+
+ test("rejects an unknown action and an unknown handoff_kind", async () => {
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ const badAction = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 10,
+ method: "tools/call",
+ params: { name: "brain_generation_reports", arguments: { action: "delete" } },
+ })) as { result?: { isError?: boolean }; error?: unknown };
+ expect(badAction.error ?? badAction.result?.isError).toBeTruthy();
+ });
+});
diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.ts
index 98bff85b..0dda3179 100644
--- a/tests/mcp/mcp.test.ts
+++ b/tests/mcp/mcp.test.ts
@@ -262,6 +262,8 @@ describe("tool listing", () => {
"brain_truth",
"brain_dead_ends",
"brain_foresight",
+ // Hindsight brain-loop ops: inbound, opt-in LLM generation tracing.
+ "brain_generation_reports",
// Write-Time Integrity & Governance Suite.
"brain_labels",
"brain_tiers",
@@ -548,7 +550,8 @@ describe("stdio loop", () => {
// (Session Knowledge Synthesis Suite, v1.11.0) = 81.
// + brain_codegraph_report (CodeGraph & MCP Operational Readability,
// v1.12.0) = 82.
- expect(list.result.tools.length).toBe(82);
+ // + brain_generation_reports (Hindsight brain-loop ops) = 83.
+ expect(list.result.tools.length).toBe(83);
});
test("returns parse error for invalid JSON", async () => {
diff --git a/tests/mcp/removed-tools.test.ts b/tests/mcp/removed-tools.test.ts
index dbc39a2a..4178da8c 100644
--- a/tests/mcp/removed-tools.test.ts
+++ b/tests/mcp/removed-tools.test.ts
@@ -143,5 +143,6 @@ test("the shadow surface is gone: no hidden tools, removed names unlisted", asyn
// + brain_session_summary, brain_idea_lineage, brain_note_history
// (Session Knowledge Synthesis Suite) = 81.
// + brain_codegraph_report (CodeGraph & MCP Operational Readability) = 82.
- expect(list.result.tools.length).toBe(82);
+ // + brain_generation_reports (Hindsight brain-loop ops) = 83.
+ expect(list.result.tools.length).toBe(83);
});