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.jsonindex 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.jsonindex 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.mdindex 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.0diff --git a/docs/brainstorm/hindsight-brain-loop-ops/cli-output/claude.md b/docs/brainstorm/hindsight-brain-loop-ops/cli-output/claude.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 .jso2b brain session-hook Internal hook bridge: read one lifecycle payload from stdin, capture prompt markers / brain_feedback, append lifecycle audit/log rowso2b 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-awareo2b 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 hintso2b 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 onlyo2b brain context-presets show [tight-context|long-context] --json; suggest --model <name> --context-window <tokens> --json; diff <preset-id> [current-value flags] [--override <path>...] --jsono2b 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.mdindex 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 afterdeterministic media/base64 sanitization. `brain_session_grep`,`brain_session_describe`, and `brain_session_expand` inspect the opt-in sessiondiff --git a/docs/metrics.md b/docs/metrics.mdindex 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-laneemissions. 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 problemnever fails the pass that produced the numbers, so gaps in a filemean 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.mdindex 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.jsonindex 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.jsonindex 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.yamlindex 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: truediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex 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.pyindex 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.yamlindex 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: truediff --git a/pyproject.toml b/pyproject.tomlindex 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.tsindex 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>): Promisreturn 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.tsindex 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 presetspre-compact-extract Extract typed continuity records from bounded textrecall-telemetry List/summarize opt-in recall telemetry records+ generation-reports Record/list/summarize opt-in LLM generation tracesskill-proposals Learn/list/review deterministic skill proposalsprocedural-memory Reconcile/list procedural memory index and usageprocedural-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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): NormalizedContinuityRecredacted: 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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): Writeconst 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.tsindex 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 thediff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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);});