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: MCP context economy - preview budget, artifact fetch, recall hint (#45)
Sol Aitken5fa7eb05709a
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 1bed927a..7b22a411 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.17.0",+ "version": "0.18.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 39fc89ba..94a160bc 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.17.0",+ "version": "0.18.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 10e923cb..0b419c10 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,36 @@ 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).+## [0.18.0] - 2026-05-28++MCP context economy. Large tool results no longer flood the calling+agent's context window: budgeted tools return a bounded preview inline and+park the full payload in a vault-local artifact the agent can fetch on+demand. Search results also gain a one-line recall hint.++### Added++- Per-tool MCP preview budget. When a budgeted tool's serialized result+ exceeds its character budget, the JSON-RPC `tools/call` response returns+ a valid-JSON preview envelope (`preview_truncated`, `bytes_preview`,+ `full_chars`, `artifact_id`, `note`) in `content[0].text` while+ `structuredContent` stays the full, contract-validated object. Tools+ with no budget, and the CLI, are unaffected.+- `brain_artifact_get` MCP tool to fetch the complete payload of a+ preview-truncated result by its `artifact_id`. Read-only, full scope.+- Vault-local artifact store under `Brain/.artifacts/<run-id>/`, with+ secret redaction, path-safety, content-hashed ids, and best-effort TTL+ pruning of stale run directories on server start.+- `recall_hint` on `brain_search` results: a computed, never-stored+ one-line summary of the recalled set (count, per-type breakdown, top+ hit) built from a single language-agnostic template.++### Changed++- `redactRawOutput` accepts an optional `maxInput` so the artifact store+ can scrub secrets without inheriting the receipt-oriented 256 KiB+ truncation cap, preserving full payloads for later fetch.+## [0.17.0] - 2026-05-28Brain Lifecycle Review Suite. Open Second Brain now adds read-only review@@ -3185,6 +3215,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.+[0.18.0]: https://github.com/itechmeat/open-second-brain/compare/v0.17.0...v0.18.0[0.17.0]: https://github.com/itechmeat/open-second-brain/compare/v0.16.0...v0.17.0[0.16.0]: https://github.com/itechmeat/open-second-brain/compare/v0.15.0...v0.16.0[0.15.0]: https://github.com/itechmeat/open-second-brain/compare/v0.14.1...v0.15.0diff --git a/README.md b/README.mdindex f5a63db7..bf403e99 100644--- a/README.md+++ b/README.md@@ -112,7 +112,7 @@ The capabilities you actually feel day to day:| 9 | Hybrid search that explains itself | `o2b search "<query>" --property type=decision --property status=open` β SQLite + FTS5 and an optional semantic layer, fused and then sharpened by a recall-quality suite: MMR diversity so near-duplicates do not crowd the top, link-graph traversal that surfaces notes one hop from a hit, entity-boosting for proper-noun precision, and header-anchored chunking so a mid-document chunk keeps its section context. Every result carries a `why_retrieved` breakdown of the layers that ranked it. || 10 | Pay Memory β audit every paid action | When the agent spends money (Solana-Foundation `pay`, third-party APIs) every receipt lands in `Brain/payments/<date>/`. Spending policy, approval gate, daily Telegram report. The agent never holds wallet keys. |-These are the headline capabilities. The full surface also includes: importing Claude Code memory directories, daily logging-discipline cron with a complexity-to-thinking warning, cross-project pointers for shared vaults, transient pinned session context through `brain_pinned_context` / `Brain/pinned.md`, source-agent query and comparison (`brain_agent_query`, `brain_agent_diff`, `o2b brain agent-query`, `o2b brain agent-diff`), the codegraph partner skill, vault hygiene lints, per-MOC coverage audit, concept synthesis, an operator dashboard, configurable Markdown-link presentation output, MCP output-contract checks for core agent-facing tools, private-region stripping with `<private>...</private>`, the v0.12.0 Brain Integrity Suite (content-hash drift detection, durable workrun checkpoints, destructive-from-confirmed retire gate, and the `brain_review_candidates` MCP tool that previews what the next dream pass would do without writing anything), the v0.13.0 Hybrid Search and Recall Quality suite (explainable recall, MMR diversity, link-graph traversal, entity-boosted retrieval, header-anchored chunking), the v0.14.0 Semantic Brain Health and Self-Maintenance suite (cross-preference contradiction detection, concept-gap and stale-claim surfacing, per-preference edit-history, a clean/watch/investigate reconciliation verdict via `brain_health`, and dependency-ordered `doctor --remediate`), and the v0.17.0 Brain Lifecycle Review Suite (`intent-review`, `retention`, `monthly`, lifecycle schemas, and discipline complexity ratio). Browse [`docs/cli-reference.md`](docs/cli-reference.md) for every verb and [`docs/how-it-works.md`](docs/how-it-works.md) for the mental model.+These are the headline capabilities. The full surface also includes: importing Claude Code memory directories, daily logging-discipline cron with a complexity-to-thinking warning, cross-project pointers for shared vaults, transient pinned session context through `brain_pinned_context` / `Brain/pinned.md`, source-agent query and comparison (`brain_agent_query`, `brain_agent_diff`, `o2b brain agent-query`, `o2b brain agent-diff`), the codegraph partner skill, vault hygiene lints, per-MOC coverage audit, concept synthesis, an operator dashboard, configurable Markdown-link presentation output, MCP output-contract checks for core agent-facing tools, private-region stripping with `<private>...</private>`, the v0.12.0 Brain Integrity Suite (content-hash drift detection, durable workrun checkpoints, destructive-from-confirmed retire gate, and the `brain_review_candidates` MCP tool that previews what the next dream pass would do without writing anything), the v0.13.0 Hybrid Search and Recall Quality suite (explainable recall, MMR diversity, link-graph traversal, entity-boosted retrieval, header-anchored chunking), the v0.14.0 Semantic Brain Health and Self-Maintenance suite (cross-preference contradiction detection, concept-gap and stale-claim surfacing, per-preference edit-history, a clean/watch/investigate reconciliation verdict via `brain_health`, and dependency-ordered `doctor --remediate`), the v0.17.0 Brain Lifecycle Review Suite (`intent-review`, `retention`, `monthly`, lifecycle schemas, and discipline complexity ratio), and the v0.18.0 MCP context economy (a per-tool preview budget that returns a bounded inline preview and parks the full payload in a vault-local artifact the agent fetches on demand with `brain_artifact_get`, plus a `recall_hint` one-liner on search results). Browse [`docs/cli-reference.md`](docs/cli-reference.md) for every verb and [`docs/how-it-works.md`](docs/how-it-works.md) for the mental model.## CLIdiff --git a/docs/brainstorm/mcp-context-economy/cli-output/claude.md b/docs/brainstorm/mcp-context-economy/cli-output/claude.mdnew file mode 100644index 00000000..e7b8f234--- /dev/null+++ b/docs/brainstorm/mcp-context-economy/cli-output/claude.md@@ -0,0 +1,35 @@+### Variant 1: Single-seam byte budget+- **Approach**: Add an optional `preview_chars` field to `ToolDefinition` and put all logic in `toolResult(tool, structured)`. After serializing, if the JSON string exceeds the tool's budget, write the full bytes to `Brain/.artifacts/<run-id>/<artifact_id>` (atomic write + standard redaction), and replace `content[0].text` with a small valid-JSON envelope `{preview: "<head slice>", artifact_id, full_chars}`. `structuredContent` is left fully intact, so no outputSchema contract changes; a sibling `brain_artifact_get` reads back the bytes. Unit 2's recall hint is a shared `deriveRecallHint(resultSet)` helper called inside `brain_search`/`brain_query`, returning one English-template string folded into the result object before serialization.+- **Trade-offs**:+ - Pro: Smallest possible footprint β one chokepoint, one new tool, one new field; everything else untouched.+ - Pro: Opt-in-safe by construction β budget only engages when text exceeds it, and structuredContent never changes shape.+ - Pro: Truncation is content-agnostic, so it works uniformly across all ~27 tools with zero per-tool code.+ - Con: The preview is a dumb head-slice of serialized JSON β semantically arbitrary (may cut mid-record), not a curated summary.+ - Con: Full payload still lives in `structuredContent`, so harnesses that inject structuredContent (not text) see no savings.+- **Complexity**: small+- **Risk**: low++### Variant 2: Declarative per-tool preview projection+- **Approach**: Same chokepoint mechanics, but `ToolDefinition` also carries an optional deterministic `previewProjection` β a pure spec (keep/drop fields, cap arrays to N, replace heavy arrays with counts) that produces a smaller *structured* object from the full one. When over budget, `toolResult` emits the projected object as the preview (still valid, schema-shaped data), archives the full object to the artifact, and stamps `artifact_id`/`full_chars`. The recall hint is itself expressed as a projection-friendly field so `brain_search`'s preview leads with "N confirmed / M signals, top rule X" while the full results defer to the artifact.+- **Trade-offs**:+ - Pro: Previews are meaningful and machine-valid β the agent sees the most useful slice (counts, top-K, the hint), not a truncated string.+ - Pro: Each tool declares its own intent; budget engagement is explicit opt-in per tool.+ - Con: Authoring a projection for each large tool spreads work across many definitions and adds per-tool tests.+ - Con: Projections must be kept consistent with `outputSchema` (preview must validate as a sub-shape), adding contract-maintenance surface.+ - Con: More moving parts than strictly needed for an MVP "bounded preview."+- **Complexity**: medium+- **Risk**: medium++### Variant 3: Extracted artifact-store service + pluggable budget middleware+- **Approach**: Factor a dedicated artifact-store module (run-id lifecycle, TTL/on-shutdown cleanup, `ensureInsideVault` validation, redaction) consumed by both the write path and `brain_artifact_get`, and introduce a thin budget middleware in `buildToolTable` that wraps handler output before `toolResult` with a swappable truncation strategy (head-slice today, projection or structuredContent-trimming later behind a flag). The recall hint becomes one registered strategy/derivation in the same middleware pipeline rather than inline handler code.+- **Trade-offs**:+ - Pro: Cleanest separation of concerns and the most extensible β artifact lifecycle and truncation policy each evolve independently.+ - Pro: A single place to later add cursor pagination, structuredContent trimming, or per-scope policies.+ - Con: Largest surface area for an MVP; introduces a middleware abstraction the codebase doesn't currently have.+ - Con: Two seams (middleware + chokepoint) risk double-processing or ordering bugs versus the proven single `toolResult` seam.+ - Con: Over-engineered relative to the stated minimum viable shape.+- **Complexity**: large+- **Risk**: medium++### Recommended: Variant 1+**Rationale**: It matches the stated minimum viable shape exactly, exploits the single existing serialization chokepoint, and preserves every `structuredContent`/outputSchema contract by only trimming the context-flooding `content[0].text` β satisfying the "opt-in-safe" and "no broken contracts" constraints with the least code and the lowest risk. Variant 2's semantic previews and Variant 3's middleware are real future improvements, but the projection spec and artifact-store extraction can be layered onto Variant 1's seam later without rework, so paying for them now buys complexity the first release doesn't need. Unit 2's recall hint is thin enough to ride along identically under any variant, so it shouldn't drive the choice.diff --git a/docs/brainstorm/mcp-context-economy/cli-output/prompt.md b/docs/brainstorm/mcp-context-economy/cli-output/prompt.mdnew file mode 100644index 00000000..6642e3b4--- /dev/null+++ b/docs/brainstorm/mcp-context-economy/cli-output/prompt.md@@ -0,0 +1,61 @@+You are brainstorming architectural variants for the following task. Do not write code. Do not write a final design. Only produce variants and a recommendation.++# Task++Ship one cohesive "MCP context economy" capability for Open Second Brain, composed of two atomic units that release together:++## Unit 1 (primary, architectural) β MCP tool-result preview budget with full-artifact fetch path++Open Second Brain's MCP tools (brain_search, brain_context_pack, brain_digest, brain_query, brain_timeline, brain_concept_synthesis, second_brain_status, ~27 brain_* tools total) can return large payloads when the vault is dense. Returning the full payload inline burns the calling agent's context window for content it may not need. We want a per-tool preview budget: the agent sees a bounded preview by default, and the full oversized output stays reachable through a follow-up tool call. This is a preview budget, not a capability cutoff β no information is lost, only deferred.++Minimum viable shape: a preview_chars budget per tool definition (default e.g. 2000) at the MCP layer; when the serialized result exceeds it, the response carries {preview, artifact_id, full_chars} and a sibling tool brain_artifact_get(artifact_id) returns the full bytes. Artifacts live under Brain/.artifacts/<run-id>/<artifact_id> with a TTL or on-shutdown cleanup. Reuses existing fs primitives.++## Unit 2 (secondary, thin) β Auto-recall hint text on search results++brain_search / brain_query return raw FTS5 + embedding results. Add a lightweight, computed-at-recall-time hint string that guides the downstream agent on how/why the recalled set is relevant (e.g. "N confirmed preferences and M signals matched; highest-confidence rule is X"). The hint is computed from the result set, never stored, and complements the existing per-result reasons[] (why_retrieved) array. Cosmetic-but-cheap polish layered over already-structured results.++# Project context++Project: Open Second Brain β an Obsidian-native, plain-Markdown memory layer for AI agents. Language: TypeScript. Runtime: Bun. MCP server speaks JSON-RPC 2.0 over the 2025-06-18 protocol.++Recent commits (default branch):+- v0.17.0 β Brain Lifecycle Review Suite (read-only review surfaces)+- v0.16.0 β Agent boundary control surfaces: pinned context, Markdown links, MCP output contracts+- v0.15.0 β Cross-agent query foundation++Key architecture facts the variants must respect:+- The single serialization chokepoint is toolResult(tool, structured) in src/mcp/server.ts. It runs assertOutputContract, then JSON.stringify(structured, sortedReplacer, 2) into content[0].text, and also attaches the raw object as structuredContent. Every tool output flows through this one function (both the JSON-RPC tools/call path and the CLI bridge callTool).+- Tool definitions are ToolDefinition in src/mcp/tools.ts with {name, description, inputSchema, outputSchema?, handler}. Tools are assembled in buildToolTable(scope).+- Brain paths are centralized in src/core/brain/paths.ts (BRAIN_ROOT_REL = "Brain", existing .snapshots/ dir with run-id pattern, strict slug/run-id validation via ensureInsideVault). Atomic writes via src/core/fs-atomic.ts (atomicWriteFileSync). Redaction via src/core/redactor.ts.+- brain_search already truncates per-result content to 600 chars and returns {results[], warnings[], total} with per-result reasons[].+- The MCP envelope distinguishes the human/agent-facing content[0].text (what floods context) from the machine-readable structuredContent (the raw object).++Conventions:+- Mirrors a legacy Python implementation in places; deterministic, no LLM inside algorithms.+- Plain Markdown in the vault; no daemon, no hidden state outside the vault.+- TDD is mandatory; every unit ships with tests first.+- Output contracts (JSON Schema outputSchema) are validated at the MCP boundary.++Constraints:+- No new runtime dependencies unless strongly justified (current deps: proper-lockfile; optional: sqlite-vec).+- Do not break existing outputSchema contracts for tools (existing clients rely on structuredContent shape).+- Must be language-agnostic by construction β no hardcoded natural-language phrase tables for any specific human language. Any recall-hint text must be built from a single English template/derivation, not per-locale strings.+- Artifact storage must not leak outside the vault root and must redact secrets the same way other Brain writers do.+- The preview seam must be opt-in-safe: tools whose output is always small should be unaffected; a tool with no declared budget must behave exactly as today.++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++### Recommended: Variant N+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/mcp-context-economy/design.md b/docs/brainstorm/mcp-context-economy/design.mdnew file mode 100644index 00000000..e7137e34--- /dev/null+++ b/docs/brainstorm/mcp-context-economy/design.md@@ -0,0 +1,74 @@+# MCP context economy - preview-budget tool results + recall hints++**Status:** draft+**Author:** claude-vps-agent (via feature-release-playbook)+**Audience:** implementation++## Problem statement++Open Second Brain exposes ~27 `brain_*` MCP tools. Several return large payloads when the vault is dense (`brain_search`, `brain_context_pack`, `brain_digest`, `brain_timeline`, `brain_concept_synthesis`, `brain_operator_summary`, `second_brain_status`, the weekly/monthly synthesis tools). The full payload is serialized into the MCP envelope's `content[0].text`, which the calling agent's host injects into the model context - flooding the context window with content the agent often does not need beyond the first few records. There is no way to get a bounded preview with the full result reachable on demand.++Separately, `brain_search`/`brain_query` return ranked results with no top-level cue about how the recalled set should be read, leaving the agent to infer relevance from raw rows.++## Scope++- A per-tool, opt-in `previewBudget` (character count) on `ToolDefinition`. Over-budget tool results, **on the MCP JSON-RPC path only**, return a bounded, valid-JSON preview envelope in `content[0].text` plus an `artifact_id`.+- A vault-local artifact store under `Brain/.artifacts/<run-id>/` that holds the full serialized payload (atomic write, secret-redacted, path-safe), with best-effort TTL pruning of stale run directories.+- A new read-only MCP tool `brain_artifact_get(artifact_id)` that returns the full stored bytes.+- A computed-at-recall-time `recall_hint` string on `brain_search` derived from result counts via a single English template - no stored text, no per-language tables. (Scoped to `brain_search` only: `brain_query` is a preference/topic aggregation, not a ranked result set, so the ranked-hint shape - searchType / score / top hit - does not fit it.)+- Budgets wired onto the known-large tools; agent-facing `instructions` updated to describe the preview/fetch protocol.++## Out of scope++- Semantic / projected previews (Variant 2) and a generalized budget middleware (Variant 3) - explicitly deferred; the chosen seam can host them later without rework.+- Cursor pagination of large results.+- Trimming `structuredContent` (kept full to preserve `outputSchema` contracts and programmatic consumers).+- Any budgeting on the CLI bridge - operator CLI output stays full.++## Chosen approach++Variant 1 (single-seam byte budget), refined per the orchestrator decision in `variants.md`:++The MCP dispatch path (`MCPServer.handleToolsCall`) validates the handler's full output against `outputSchema` (unchanged), serializes it, and if the serialized text exceeds the tool's `previewBudget`, it (a) writes the full text to the artifact store, and (b) returns an envelope whose `content[0].text` is a valid-JSON object `{preview_truncated: true, artifact_id, full_chars, bytes_preview, note}` where `bytes_preview` is the head slice of the full text capped to the budget (a string field, so the envelope always parses) and `note` is a fixed English instruction pointing the agent at `brain_artifact_get`. `structuredContent` remains the full, schema-valid object. The CLI bridge (`callTool` -> `toolResult`) is untouched and always returns the full payload.++`brain_artifact_get` resolves `artifact_id` through path-safety validation and returns the stored full text. Unknown / expired ids return a tool-level error envelope.++`recall_hint` is produced by a pure `deriveRecallHint(results, total)` helper and added as an optional top-level field (additive, non-breaking schema change).++## Design decisions++- **Seam at the MCP dispatch, not `toolResult`.** Budget is an agent-context concern; the CLI must print full output. Putting the wrap in `handleToolsCall` cleanly separates the two consumers of `toolResult`.+- **Preview is a JSON envelope with a string head-slice**, not a raw mid-record cut - always parseable, satisfies the "valid JSON" expectation of MCP text content.+- **`structuredContent` stays full** - zero `outputSchema` breakage, programmatic consumers unaffected. The artifact exists for text-only agents that only saw the preview.+- **Opt-in per tool.** A tool with no `previewBudget` behaves exactly as today (constraint). Budgets are applied only to the enumerated large tools.+- **Artifact id = short SHA-256 of the full text.** Deterministic, dedupes identical payloads, trivially testable, no clock/RNG dependence in the id itself.+- **Run id is per server process.** Generated at `MCPServer` construction (injectable for tests). Artifacts grouped under `Brain/.artifacts/<run-id>/` so a process's outputs prune together.+- **TTL pruning is best-effort at store construction** - delete run directories whose mtime is older than the TTL (default 24h). No daemon, matches the "no hidden process" convention. `Brain/.artifacts` is a dot-directory, so the vault walker already excludes it from indexing/search (same treatment as `Brain/.snapshots`).+- **Redaction reuses `redactRawOutput`** so stored artifacts never persist secret-shaped tokens that a tool happened to surface.+- **Recall hint built from numbers + a single English template.** Language-agnostic by construction; no locale tables. Absent (field omitted) when there are zero results.++## File changes++New:+- `src/mcp/artifact-store.ts` - write/read/prune, content-hash id, path-safety, redaction.+- `src/mcp/preview-budget.ts` - `buildPreviewEnvelope(fullText, budget, artifactId)` and the over-budget decision.+- `src/core/search/recall-hint.ts` - `deriveRecallHint`.+- Tests: `tests/mcp/artifact-store.test.ts`, `tests/mcp/preview-budget.test.ts`, `tests/mcp/artifact-get.test.ts`, `tests/mcp/preview-budget-dispatch.test.ts`, `tests/core/search/recall-hint.test.ts`.++Modified:+- `src/core/brain/paths.ts` - `BRAIN_ARTIFACTS_REL` + dir constructor + run-id/artifact-id validation.+- `src/mcp/tools.ts` - `previewBudget?: number` on `ToolDefinition`; register `brain_artifact_get`.+- `src/mcp/server.ts` - budget wrap in `handleToolsCall`; artifact store on the server instance.+- `src/mcp/brain-tools.ts` - `brain_artifact_get` handler; budgets on large brain tools.+- `src/mcp/search-tools.ts` - `recall_hint` on `brain_search` output + schema; budget.+- `src/mcp/pay-memory-tools.ts` - budgets where outputs can be large.+- `src/mcp/instructions.ts` - document the preview/fetch protocol for agents.+- `README.md`, `CHANGELOG.md`, `docs/` as needed.+- Existing tests touching tool tables / envelope shape, updated for the new tool + optional field.++## Risks and open questions++- **Risk: an over-budget envelope confuses an agent that expected the full text.** Mitigated by `instructions.ts` describing the protocol and by keeping `structuredContent` full.+- **Risk: artifact directory growth.** Mitigated by TTL pruning at construction; dot-dir excluded from sync/index. Acceptable since artifacts are ephemeral session scratch.+- **Open question: default budget value.** Start at 2000 chars per the source issue; confirm against real tool outputs during QA.+- **Open question: which exact tools opt in.** Resolve by measuring serialized sizes during implementation; enable on the demonstrably-large ones, leave small status/echo tools unbudgeted.diff --git a/docs/brainstorm/mcp-context-economy/plan.md b/docs/brainstorm/mcp-context-economy/plan.mdnew file mode 100644index 00000000..32749f8d--- /dev/null+++ b/docs/brainstorm/mcp-context-economy/plan.md@@ -0,0 +1,31 @@+# MCP context economy - implementation plan++Five atomic units, each TDD (failing test first), each its own conventional commit+on `feat/mcp-context-economy`. Order matters: store -> seam -> fetch tool -> wiring -> hint.++## Tasks++### Task 1: Artifact store+- **Files**: `src/core/brain/paths.ts` (add `BRAIN_ARTIFACTS_REL`, dir ctor, id validation), `src/mcp/artifact-store.ts`, `tests/mcp/artifact-store.test.ts`.+- **Acceptance**: store writes full text atomically under `Brain/.artifacts/<run-id>/<artifact-id>.json`; `read(id)` round-trips; content-hash id is stable for identical input; traversal / malformed ids rejected; secret-shaped tokens redacted before persist; `prune(ttl)` removes stale run dirs and keeps fresh ones.+- **Depends on**: none.++### Task 2: Preview-budget seam (MCP dispatch)+- **Files**: `src/mcp/preview-budget.ts`, `src/mcp/tools.ts` (`previewBudget?` on `ToolDefinition`), `src/mcp/server.ts` (wrap in `handleToolsCall`, store on instance + injectable run-id), `tests/mcp/preview-budget.test.ts`, `tests/mcp/preview-budget-dispatch.test.ts`.+- **Acceptance**: a tool with a small `previewBudget` and an over-budget result returns `content[0].text` = valid JSON `{preview_truncated:true, artifact_id, full_chars, bytes_preview}`, `bytes_preview.length <= budget`, `structuredContent` is the full object, and the artifact holds the full text; an under-budget result is byte-identical to today; a tool with no budget is byte-identical to today; the CLI bridge (`callTool`) always returns full text regardless of budget.+- **Depends on**: Task 1.++### Task 3: brain_artifact_get tool+- **Files**: `src/mcp/brain-tools.ts` (handler), `src/mcp/tools.ts` (register), `src/mcp/instructions.ts` (protocol docs), `tests/mcp/artifact-get.test.ts`.+- **Acceptance**: `brain_artifact_get(artifact_id)` returns `{artifact_id, full_chars, content}` for a stored id; unknown / expired id returns a tool-level error envelope (not a thrown 500); traversal id rejected; tool present in `tools/list` under full scope.+- **Depends on**: Task 1, Task 2.++### Task 4: Wire budgets onto large tools+- **Files**: `src/mcp/search-tools.ts`, `src/mcp/brain-tools.ts`, `src/mcp/tools.ts`, `src/mcp/pay-memory-tools.ts`.+- **Acceptance**: the enumerated large tools (`brain_search`, `brain_context_pack`, `brain_digest`, `brain_timeline`, `brain_concept_synthesis`, `brain_operator_summary`, `brain_weekly_synthesis`, `brain_monthly_review`, `brain_daily_brief`, `second_brain_status`, `second_brain_query`) carry a `previewBudget`; small status/echo tools do not; a table-level test asserts the exact opted-in set so the list stays intentional.+- **Depends on**: Task 2.++### Task 5: Recall hint+- **Files**: `src/core/search/recall-hint.ts`, `src/mcp/search-tools.ts` (add `recall_hint` to output + `SEARCH_OUTPUT_SCHEMA`), `tests/core/search/recall-hint.test.ts`. Scoped to `brain_search` only - `brain_query`/`second_brain_query` are aggregations, not ranked result sets, so the ranked-hint shape does not fit them (see design doc).+- **Acceptance**: `deriveRecallHint` returns one English-template string built from counts (total, per-`searchType`, top score); field omitted when zero results; never reads or stores natural-language phrase tables; existing `brain_search` consumers still validate (additive optional field).+- **Depends on**: none (independent; sequenced last to keep search-tools edits together).diff --git a/docs/brainstorm/mcp-context-economy/variants.md b/docs/brainstorm/mcp-context-economy/variants.mdnew file mode 100644index 00000000..66e730b1--- /dev/null+++ b/docs/brainstorm/mcp-context-economy/variants.md@@ -0,0 +1,50 @@+# MCP context economy - brainstorm variants (audit trail)++Primary consultant: Claude Code CLI (`claude -p`), exit 0, 3 parseable variants.+Fallback consultant (Codex): not invoked - primary succeeded with >= 2 variants.++## Consultant output (verbatim)++### Variant 1: Single-seam byte budget+- **Approach**: Add an optional `preview_chars` field to `ToolDefinition` and put all logic in `toolResult(tool, structured)`. After serializing, if the JSON string exceeds the tool's budget, write the full bytes to `Brain/.artifacts/<run-id>/<artifact_id>` (atomic write + standard redaction), and replace `content[0].text` with a small valid-JSON envelope `{preview: "<head slice>", artifact_id, full_chars}`. `structuredContent` is left fully intact, so no outputSchema contract changes; a sibling `brain_artifact_get` reads back the bytes. Unit 2's recall hint is a shared `deriveRecallHint(resultSet)` helper called inside `brain_search`/`brain_query`, returning one English-template string folded into the result object before serialization.+- **Trade-offs**:+ - Pro: Smallest possible footprint - one chokepoint, one new tool, one new field; everything else untouched.+ - Pro: Opt-in-safe by construction - budget only engages when text exceeds it, and structuredContent never changes shape.+ - Pro: Truncation is content-agnostic, so it works uniformly across all ~27 tools with zero per-tool code.+ - Con: The preview is a dumb head-slice of serialized JSON - semantically arbitrary (may cut mid-record), not a curated summary.+ - Con: Full payload still lives in `structuredContent`, so harnesses that inject structuredContent (not text) see no savings.+- **Complexity**: small+- **Risk**: low++### Variant 2: Declarative per-tool preview projection+- **Approach**: Same chokepoint mechanics, but `ToolDefinition` also carries an optional deterministic `previewProjection` - a pure spec (keep/drop fields, cap arrays to N, replace heavy arrays with counts) that produces a smaller structured object from the full one. When over budget, `toolResult` emits the projected object as the preview (still valid, schema-shaped data), archives the full object to the artifact, and stamps `artifact_id`/`full_chars`. The recall hint is itself expressed as a projection-friendly field so `brain_search`'s preview leads with "N confirmed / M signals, top rule X" while the full results defer to the artifact.+- **Trade-offs**:+ - Pro: Previews are meaningful and machine-valid - the agent sees the most useful slice (counts, top-K, the hint), not a truncated string.+ - Pro: Each tool declares its own intent; budget engagement is explicit opt-in per tool.+ - Con: Authoring a projection for each large tool spreads work across many definitions and adds per-tool tests.+ - Con: Projections must be kept consistent with `outputSchema` (preview must validate as a sub-shape), adding contract-maintenance surface.+ - Con: More moving parts than strictly needed for an MVP "bounded preview."+- **Complexity**: medium+- **Risk**: medium++### Variant 3: Extracted artifact-store service + pluggable budget middleware+- **Approach**: Factor a dedicated artifact-store module (run-id lifecycle, TTL/on-shutdown cleanup, `ensureInsideVault` validation, redaction) consumed by both the write path and `brain_artifact_get`, and introduce a thin budget middleware in `buildToolTable` that wraps handler output before `toolResult` with a swappable truncation strategy (head-slice today, projection or structuredContent-trimming later behind a flag). The recall hint becomes one registered strategy/derivation in the same middleware pipeline rather than inline handler code.+- **Trade-offs**:+ - Pro: Cleanest separation of concerns and the most extensible - artifact lifecycle and truncation policy each evolve independently.+ - Pro: A single place to later add cursor pagination, structuredContent trimming, or per-scope policies.+ - Con: Largest surface area for an MVP; introduces a middleware abstraction the codebase doesn't currently have.+ - Con: Two seams (middleware + chokepoint) risk double-processing or ordering bugs versus the proven single `toolResult` seam.+ - Con: Over-engineered relative to the stated minimum viable shape.+- **Complexity**: large+- **Risk**: medium++### Recommended: Variant 1+**Rationale**: It matches the stated minimum viable shape exactly, exploits the single existing serialization chokepoint, and preserves every `structuredContent`/outputSchema contract by only trimming the context-flooding `content[0].text` - satisfying the "opt-in-safe" and "no broken contracts" constraints with the least code and the lowest risk. Variant 2's semantic previews and Variant 3's middleware are real future improvements, but the projection spec and artifact-store extraction can be layered onto Variant 1's seam later without rework, so paying for them now buys complexity the first release doesn't need. Unit 2's recall hint is thin enough to ride along identically under any variant, so it shouldn't drive the choice.++## Orchestrator decision++Accepted: Variant 1 (single-seam byte budget), with two project-context refinements that do not change the variant's shape:++1. **Apply the budget only on the MCP JSON-RPC path (`handleToolsCall`), not on the CLI bridge (`callTool`).** The budget exists to protect a calling agent's context window over MCP. The CLI is operator-facing and must keep printing full output. Splitting the seam this way keeps `toolResult` (used by the CLI bridge) returning the full payload, while the MCP dispatch path wraps over-budget results.++2. **The preview lives in `content[0].text` as a valid-JSON envelope whose head-slice is a string field** (`{preview_truncated, artifact_id, full_chars, bytes_preview}`), so the envelope is always parseable even when the slice cuts mid-record - addressing the consultant's first Con. `structuredContent` stays the full, schema-valid object, so programmatic consumers and `outputSchema` contracts are untouched - and the still-written artifact lets a text-only agent fetch the full bytes via `brain_artifact_get`. The consultant's second Con (structuredContent-injecting hosts see no savings) is accepted: the primary consumers (Claude Code, Hermes) inject `content` text, not `structuredContent`, so the flooding vector is the one we bound.diff --git a/openclaw.plugin.json b/openclaw.plugin.jsonindex 07fd195d..576335e9 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": "0.17.0",+ "version": "0.18.0","activation": { "onStartup": true },"skills": ["./skills"],"contracts": {diff --git a/openclaw/index.js b/openclaw/index.jsindex a6f75516..8766a758 100644--- a/openclaw/index.js+++ b/openclaw/index.js@@ -2322,6 +2322,7 @@ var BRAIN_PREFERENCES_REL = posix2.join(BRAIN_ROOT_REL, "preferences");var BRAIN_RETIRED_REL = posix2.join(BRAIN_ROOT_REL, "retired");var BRAIN_LOG_REL = posix2.join(BRAIN_ROOT_REL, "log");var BRAIN_SNAPSHOTS_REL = posix2.join(BRAIN_ROOT_REL, ".snapshots");+var BRAIN_ARTIFACTS_REL = posix2.join(BRAIN_ROOT_REL, ".artifacts");var BRAIN_INDEX_FILE = "_INDEX.md";var BRAIN_INDEX_REL = posix2.join(BRAIN_ROOT_REL, BRAIN_INDEX_FILE);@@ -2524,10 +2525,11 @@ function stripPrivateRegions(text) {}return output;}-function redactRawOutput(text) {+function redactRawOutput(text, opts = {}) {if (!text)return text;- let out = text.length > MAX_REDACTOR_INPUT ? text.slice(0, MAX_REDACTOR_INPUT) + TRUNCATION_MARKER : text;+ const maxInput = opts.maxInput ?? MAX_REDACTOR_INPUT;+ let out = text.length > maxInput ? text.slice(0, maxInput) + TRUNCATION_MARKER : text;out = stripPrivateRegions(out);out = out.replace(JSON_ENTRY_RE, (_match, keyPart, value) => {if (value.startsWith('"'))diff --git a/package.json b/package.jsonindex a893f114..1d42dca4 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.17.0",+ "version": "0.18.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 632ece03..852ba174 100644--- a/plugin.yaml+++ b/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "0.17.0"+version: "0.18.0"description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."author: "OpenSecondBrain contributors"kind: standalonediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex 0c51c227..355fc741 100644--- a/plugins/codex/.codex-plugin/plugin.json+++ b/plugins/codex/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.17.0",+ "version": "0.18.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/plugin.yaml b/plugins/hermes/plugin.yamlindex e799d9e4..11afb390 100644--- a/plugins/hermes/plugin.yaml+++ b/plugins/hermes/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "0.17.0"+version: "0.18.0"description: "Hermes adapter for OpenSecondBrain vault health checks and optional MCP tool server."author: "OpenSecondBrain contributors"kind: standalonediff --git a/pyproject.toml b/pyproject.tomlindex f6e2a681..eb08905a 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 = "0.17.0"+version = "0.18.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/core/brain/paths.ts b/src/core/brain/paths.tsindex 33c79e6f..10281bcf 100644--- a/src/core/brain/paths.ts+++ b/src/core/brain/paths.ts@@ -47,6 +47,12 @@ export const BRAIN_PREFERENCES_REL = posix.join(BRAIN_ROOT_REL, "preferences");export const BRAIN_RETIRED_REL = posix.join(BRAIN_ROOT_REL, "retired");export const BRAIN_LOG_REL = posix.join(BRAIN_ROOT_REL, "log");export const BRAIN_SNAPSHOTS_REL = posix.join(BRAIN_ROOT_REL, ".snapshots");+/**+ * Ephemeral MCP tool-result artifacts (v0.18.0). Dot-directory so the+ * vault walker excludes it from search/indexing exactly like+ * `.snapshots`; never backed up, pruned by TTL on server startup.+ */+export const BRAIN_ARTIFACTS_REL = posix.join(BRAIN_ROOT_REL, ".artifacts");/** Brain-internal artefact filenames at the root of `Brain/`. */export const BRAIN_CONFIG_FILE = "_brain.yaml";@@ -207,6 +213,28 @@ export function snapshotPath(vault: string, runId: string): string {return ensureInsideVault(join(brainDirs(vault).snapshots, `${id}.tar.zst`), vault);}+/** Artifacts root: `Brain/.artifacts/`. */+export function brainArtifactsDir(vault: string): string {+ return ensureInsideVault(join(vault, BRAIN_ARTIFACTS_REL), vault);+}++/** Per-run artifact directory: `Brain/.artifacts/<run_id>/`. */+export function artifactRunDir(vault: string, runId: string): string {+ const id = validateRunId(runId);+ return ensureInsideVault(join(brainArtifactsDir(vault), id), vault);+}++/**+ * Single artifact path: `Brain/.artifacts/<run_id>/<artifact_id>.json`.+ * Both ids go through {@link validateRunId} (the same filesystem-safety+ * contract: no separators, no traversal, no Windows reservation), so a+ * malicious `artifact_id` from an MCP argument cannot escape the run dir.+ */+export function artifactPath(vault: string, runId: string, artifactId: string): string {+ const aid = validateRunId(artifactId);+ return ensureInsideVault(join(artifactRunDir(vault, runId), `${aid}.json`), vault);+}+// ----- Validators -----------------------------------------------------------/**diff --git a/src/core/redactor.ts b/src/core/redactor.tsindex c809a9bc..69efd322 100644--- a/src/core/redactor.ts+++ b/src/core/redactor.ts@@ -139,13 +139,25 @@ export function stripPrivateRegions(text: string): string {return output;}-export function redactRawOutput(text: string): string {+export interface RedactRawOutputOptions {+ /**+ * Maximum input length before the truncation guard fires. Defaults to+ * {@link MAX_REDACTOR_INPUT} (256 KiB) - the right cap for receipts,+ * where a multi-megabyte payload is a runaway log pipe. Callers that+ * must redact-without-losing-data (the MCP artifact store, whose whole+ * job is to preserve the full payload for later fetch) pass+ * `Number.POSITIVE_INFINITY` to disable truncation while still scrubbing+ * secrets.+ */+ readonly maxInput?: number;+}++export function redactRawOutput(text: string, opts: RedactRawOutputOptions = {}): string {if (!text) return text;+ const maxInput = opts.maxInput ?? MAX_REDACTOR_INPUT;let out =- text.length > MAX_REDACTOR_INPUT- ? text.slice(0, MAX_REDACTOR_INPUT) + TRUNCATION_MARKER- : text;+ text.length > maxInput ? text.slice(0, maxInput) + TRUNCATION_MARKER : text;out = stripPrivateRegions(out);diff --git a/src/core/search/recall-hint.ts b/src/core/search/recall-hint.tsnew file mode 100644index 00000000..bb548964--- /dev/null+++ b/src/core/search/recall-hint.ts@@ -0,0 +1,60 @@+/**+ * Recall hint for brain_search results (v0.18.0).+ *+ * A computed-at-recall-time, never-stored summary that tells the calling+ * agent how to read the recalled set: how many matched, the per-type+ * breakdown, and the top hit. It complements each result's `reasons[]`+ * (why_retrieved) with a one-line orientation over the whole set.+ *+ * Language-agnostic by construction: the string is built from a single+ * English template plus numbers and identifiers already present in the+ * data (search type, score, title). There is no per-locale phrase table -+ * the project ships one authoring language and translation, if ever+ * wanted, is a host concern, not a stored taxonomy.+ */++const MAX_TITLE_CHARS = 80;++export interface RecallHintInput {+ readonly searchType: string;+ readonly score: number;+ readonly title: string | null;+}++function trimTitle(title: string | null): string {+ if (!title) return "(untitled)";+ if (title.length <= MAX_TITLE_CHARS) return title;+ return title.slice(0, MAX_TITLE_CHARS - 1) + "β¦";+}++/**+ * Build the recall hint, or `null` when there is nothing to summarise.+ * `results` is assumed already ranked (best first), matching the search+ * pipeline's output order.+ */+export function deriveRecallHint(+ results: ReadonlyArray<RecallHintInput>,+ total: number,+): string | null {+ if (results.length === 0) return null;++ const counts = new Map<string, number>();+ for (const r of results) {+ counts.set(r.searchType, (counts.get(r.searchType) ?? 0) + 1);+ }+ const breakdown = [...counts.entries()]+ .toSorted((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))+ .map(([type, n]) => `${n} ${type}`)+ .join(", ");++ const top = results[0]!;+ // `total` is the corpus match count and should be >= the returned slice;+ // guard against a caller passing a smaller total so the string never+ // reads "Recalled 10 of 3".+ const denom = Math.max(total, results.length);+ return (+ `Recalled ${results.length} of ${denom} matches (${breakdown}). ` ++ `Top hit "${trimTitle(top.title)}" (${top.searchType}, score ${top.score.toFixed(2)}). ` ++ `See each result's reasons[] for why it surfaced.`+ );+}diff --git a/src/mcp/artifact-store.ts b/src/mcp/artifact-store.tsnew file mode 100644index 00000000..a1184c2a--- /dev/null+++ b/src/mcp/artifact-store.ts@@ -0,0 +1,133 @@+/**+ * Vault-local artifact store for the MCP tool-result preview budget+ * (v0.18.0).+ *+ * When an MCP tool result exceeds its preview budget, the full+ * serialized payload is parked here so a text-only agent can pull it+ * back through `brain_artifact_get` instead of having it flood the+ * context window inline. Artifacts are ephemeral session scratch:+ *+ * Brain/.artifacts/<run-id>/<artifact-id>.json+ *+ * Design notes:+ * - One store per MCP server process; the `runId` groups a process's+ * outputs so they prune together.+ * - `artifactId` is a short SHA-256 of the persisted text - deterministic,+ * dedupes identical payloads, depends on no clock or RNG.+ * - The text is run through `redactRawOutput` before it touches disk, so+ * a tool that happened to surface a secret-shaped token never persists+ * it. The returned `text`/`fullChars` reflect the redacted bytes so the+ * caller's preview slice stays consistent with what was stored.+ * - Path construction funnels through `artifactPath` (β `ensureInsideVault`),+ * so a malformed `artifactId` from an MCP argument cannot traverse out.+ * - Pruning is best-effort and synchronous at construction time: no+ * daemon, matching the "no hidden process" convention. The dot-directory+ * is excluded from the vault walker exactly like `Brain/.snapshots`.+ */++import { createHash } from "node:crypto";+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";++import {+ artifactPath,+ artifactRunDir,+ brainArtifactsDir,+} from "../core/brain/paths.ts";+import { atomicWriteFileSync } from "../core/fs-atomic.ts";+import { redactRawOutput } from "../core/redactor.ts";++/** Length of the hex artifact id derived from the SHA-256 digest. */+const ARTIFACT_ID_HEX_LEN = 16;++export interface StoredArtifact {+ /** Content-hash id used to fetch the artifact back. */+ readonly artifactId: string;+ /** Run directory the artifact lives under. */+ readonly runId: string;+ /** Absolute path of the persisted file. */+ readonly path: string;+ /** Character count of the persisted (redacted) text. */+ readonly fullChars: number;+ /** The persisted (redacted) text, for the caller's preview slice. */+ readonly text: string;+}++export interface ArtifactStoreOptions {+ readonly vault: string;+ readonly runId: string;+}++export class ArtifactStore {+ private readonly vault: string;+ readonly runId: string;++ constructor(opts: ArtifactStoreOptions) {+ this.vault = opts.vault;+ this.runId = opts.runId;+ }++ /**+ * Persist `fullText` (after redaction) and return its metadata. Writing+ * the same content twice is idempotent: the content-hash id is stable+ * and the atomic write simply re-lands identical bytes.+ */+ put(fullText: string): StoredArtifact {+ // Scrub secrets but never truncate: the artifact IS the recoverable+ // full payload, so the receipt-oriented 256 KiB context cap must not+ // apply here, or large results would be silently clipped on disk.+ const text = redactRawOutput(fullText, { maxInput: Number.POSITIVE_INFINITY });+ const artifactId = createHash("sha256")+ .update(text, "utf8")+ .digest("hex")+ .slice(0, ARTIFACT_ID_HEX_LEN);+ const path = artifactPath(this.vault, this.runId, artifactId);+ mkdirSync(artifactRunDir(this.vault, this.runId), { recursive: true });+ atomicWriteFileSync(path, text);+ return { artifactId, runId: this.runId, path, fullChars: text.length, text };+ }++ /**+ * Read the full text for `artifactId` within this store's run. Returns+ * `null` when the id is well-formed but absent. Throws when the id is+ * malformed (path-traversal attempt) - the caller turns that into a+ * tool-level error envelope.+ */+ get(artifactId: string): string | null {+ const path = artifactPath(this.vault, this.runId, artifactId);+ if (!existsSync(path)) return null;+ return readFileSync(path, "utf8");+ }++ /**+ * Best-effort prune of run directories whose mtime is older than+ * `ttlMs`. Returns the count of directories removed. Never throws on a+ * single bad entry - pruning is a housekeeping convenience, not a+ * correctness requirement.+ */+ prune(ttlMs: number): number {+ const root = brainArtifactsDir(this.vault);+ if (!existsSync(root)) return 0;+ const cutoff = Date.now() - ttlMs;+ let removed = 0;+ let entries: string[];+ try {+ entries = readdirSync(root);+ } catch {+ return 0;+ }+ for (const entry of entries) {+ const dir = `${root}/${entry}`;+ try {+ const st = statSync(dir);+ if (!st.isDirectory()) continue;+ if (st.mtimeMs < cutoff) {+ rmSync(dir, { recursive: true, force: true });+ removed += 1;+ }+ } catch {+ // Entry vanished or is unreadable; skip it.+ }+ }+ return removed;+ }+}diff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.tsindex fb74a05d..4e5dc473 100644--- a/src/mcp/brain-tools.ts+++ b/src/mcp/brain-tools.ts@@ -112,6 +112,7 @@ import {import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "./protocol.ts";import type { ServerContext, ToolDefinition } from "./tools.ts";+import { MCP_PREVIEW_BUDGET } from "./preview-budget.ts";import {coerceStr,coerceStrList,@@ -1740,6 +1741,7 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([},{name: "brain_monthly_review",+ previewBudget: MCP_PREVIEW_BUDGET,description:"Read-only monthly synthesis over Brain timeline activity: event count, status transitions, retirements, contradictions, and neglected areas.",inputSchema: {@@ -1865,6 +1867,7 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([},{name: "brain_digest",+ previewBudget: MCP_PREVIEW_BUDGET,description:"Render a human-readable summary of Brain activity in the last 24h (default) or a custom window. Read-only.",inputSchema: {@@ -2060,6 +2063,7 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([},{name: "brain_context_pack",+ previewBudget: MCP_PREVIEW_BUDGET,description:"Return the highest-tier, most recent vault slice that fits under `max_tokens`. Ordered core β supporting β peripheral, newest first; stops adding pages when the next page would exceed the budget. Read-only.",inputSchema: {@@ -2106,6 +2110,7 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([},{name: "brain_concept_synthesis",+ previewBudget: MCP_PREVIEW_BUDGET,description:"Concept-scoped cluster: target note + every artifact that wikilinks to it (depth-1), optionally including unlinked-mention rows. Deterministic JSON envelope, no LLM call inside. Read-only.",inputSchema: {@@ -2145,6 +2150,7 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([},{name: "brain_timeline",+ previewBudget: MCP_PREVIEW_BUDGET,description:"Chronological list of Brain events filtered by any combination of pref_id, topic, kind, since, until, limit. Returns the canonical TimelineIndex projection. Read-only.",inputSchema: {@@ -2214,6 +2220,7 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([},{name: "brain_daily_brief",+ previewBudget: MCP_PREVIEW_BUDGET,description:"Deterministic daily brief: events grouped by kind, status transitions, vault delta (newPromotions / newRetired / newFeedback / evidenceApplied / evidenceViolated), and deduplicated artifact wikilinks. Read-only.",inputSchema: {@@ -2230,6 +2237,7 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([},{name: "brain_weekly_synthesis",+ previewBudget: MCP_PREVIEW_BUDGET,description:"Deterministic 7-day synthesis: events grouped by kind, status transitions, retired-in-window list, contradictions (signal-suppressed + apply-evidence violated), vault delta, and source pointers. Read-only.",inputSchema: {@@ -2247,6 +2255,7 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([},{name: "brain_operator_summary",+ previewBudget: MCP_PREVIEW_BUDGET,description:"Aggregate operator dashboard: trust verdict, doctor + dream counts, verification delta, ranked maintenance actions, and instruction-file ceiling warnings. Read-only.",inputSchema: {diff --git a/src/mcp/instructions.ts b/src/mcp/instructions.tsindex 7c2c4f2e..bd3821b7 100644--- a/src/mcp/instructions.ts+++ b/src/mcp/instructions.ts@@ -111,6 +111,13 @@ export function buildInstructions(opts: BuildInstructionsOpts | string): string"Other tools: second_brain_status (config status), " +"vault_health (verify vault), second_brain_query (list vault pages " +"by title - read-only).\n\n" ++ "Preview budget: large tool results may come back as a preview " ++ "envelope - a JSON object with `preview_truncated: true`, " ++ "`bytes_preview` (a head slice), `full_chars`, and an `artifact_id`. " ++ "The full payload is not lost: call brain_artifact_get with that " ++ "`artifact_id` to retrieve the complete result. Only fetch the full " ++ "payload when the preview is insufficient - that is the point of the " ++ "budget, to keep your context lean by default.\n\n" +"Pay Memory tools record paid agent actions as inspectable Markdown:\n" +" - payment_memory_init bootstraps the layout and writes the " +"spending policy template (run once per vault).\n" +diff --git a/src/mcp/preview-budget.ts b/src/mcp/preview-budget.tsnew file mode 100644index 00000000..901574ab--- /dev/null+++ b/src/mcp/preview-budget.ts@@ -0,0 +1,90 @@+/**+ * MCP tool-result preview budget (v0.18.0).+ *+ * The single decision the seam makes: given the serialized text a tool+ * would otherwise return inline, and that tool's optional character+ * budget, either pass the text through unchanged or park the full+ * payload in the artifact store and return a small, valid-JSON preview+ * envelope in its place.+ *+ * Kept free of MCP-envelope and server concerns so it is trivially+ * unit-testable: it takes the serialized string, the budget, and a+ * `put`-only view of the artifact store.+ */++import type { StoredArtifact } from "./artifact-store.ts";++/**+ * Shared default preview budget in characters (v0.18.0). Roughly ~500+ * tokens of inline preview - enough to judge a result set, small enough+ * that a dense vault's full payload never silently floods the context.+ * Tools opt in by setting `previewBudget` to this constant.+ */+export const MCP_PREVIEW_BUDGET = 2000;++/** Envelope substituted for an over-budget tool result in `content[0].text`. */+export interface PreviewEnvelope {+ readonly preview_truncated: true;+ readonly artifact_id: string;+ readonly full_chars: number;+ readonly bytes_preview: string;+ readonly note: string;+}++export interface BudgetOutcome {+ /** Text to place in `content[0].text`. */+ readonly text: string;+ /** Whether the payload was parked in an artifact. */+ readonly truncated: boolean;+ /** Artifact id when truncated, else null. */+ readonly artifactId: string | null;+}++/** A `put`-only view of the artifact store - all the budget seam needs. */+export interface ArtifactSink {+ put(fullText: string): StoredArtifact;+}++/**+ * Single English, language-agnostic instruction folded into every+ * preview envelope. Built from a fixed template, never from a per-locale+ * phrase table.+ */+function previewNote(artifactId: string): string {+ return (+ `Result truncated to protect context. This is a head preview only; ` ++ `call brain_artifact_get with artifact_id "${artifactId}" for the full payload.`+ );+}++export function applyPreviewBudget(+ serialized: string,+ budget: number | undefined,+ store: ArtifactSink,+): BudgetOutcome {+ // No budget, or an explicitly unbounded one, means never truncate.+ if (budget === undefined || budget === Number.POSITIVE_INFINITY) {+ return { text: serialized, truncated: false, artifactId: null };+ }+ // Normalize before comparing/slicing: a negative or non-finite budget+ // would otherwise make `slice` leak nearly the whole payload (slice(0, -1))+ // and defeat the context-protection goal. Clamp to a finite int >= 0.+ const safeBudget = Number.isFinite(budget) && budget > 0 ? Math.floor(budget) : 0;+ if (serialized.length <= safeBudget) {+ return { text: serialized, truncated: false, artifactId: null };+ }++ const stored = store.put(serialized);+ const envelope: PreviewEnvelope = {+ preview_truncated: true,+ artifact_id: stored.artifactId,+ full_chars: stored.fullChars,+ bytes_preview: stored.text.slice(0, safeBudget),+ note: previewNote(stored.artifactId),+ };+ return {+ text: JSON.stringify(envelope, null, 2),+ truncated: true,+ artifactId: stored.artifactId,+ };+}diff --git a/src/mcp/search-tools.ts b/src/mcp/search-tools.tsindex 7899984f..d9621601 100644--- a/src/mcp/search-tools.ts+++ b/src/mcp/search-tools.ts@@ -16,6 +16,8 @@ import { withTimeout } from "../core/search/with-timeout.ts";import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "./protocol.ts";import type { ServerContext, ToolDefinition } from "./tools.ts";import { coerceBoolOptional, coerceStringOptional } from "./coerce.ts";+import { MCP_PREVIEW_BUDGET } from "./preview-budget.ts";+import { deriveRecallHint } from "../core/search/recall-hint.ts";const MCP_LIMIT_MAX = 50;const MCP_CONTENT_MAX = 600;@@ -75,6 +77,7 @@ const SEARCH_OUTPUT_SCHEMA: NonNullable<ToolDefinition["outputSchema"]> = {},warnings: { type: "array", items: { type: "string" } },total: { type: "integer" },+ recall_hint: { type: "string" },},};@@ -200,6 +203,7 @@ async function toolBrainSearch(throw new MCPError(INTERNAL_ERROR, e instanceof Error ? e.message : String(e));}+ const recallHint = deriveRecallHint(outcome.results, outcome.total);return {results: outcome.results.map((r: BrainSearchResult) => ({path: r.path,@@ -213,6 +217,7 @@ async function toolBrainSearch(})),warnings: outcome.warnings,total: outcome.total,+ ...(recallHint !== null ? { recall_hint: recallHint } : {}),};}@@ -223,6 +228,7 @@ export const SEARCH_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze(["Full-text search across the vault. Optional semantic layer when configured. Read-only.",inputSchema: SEARCH_INPUT_SCHEMA,outputSchema: SEARCH_OUTPUT_SCHEMA,+ previewBudget: MCP_PREVIEW_BUDGET,handler: toolBrainSearch,},]);diff --git a/src/mcp/server.ts b/src/mcp/server.tsindex d83776b9..49d12bf7 100644--- a/src/mcp/server.ts+++ b/src/mcp/server.ts@@ -26,6 +26,11 @@ import {type ToolScope,} from "./tools.ts";import { assertOutputContract } from "./output-contract.ts";+import { ArtifactStore } from "./artifact-store.ts";+import { applyPreviewBudget } from "./preview-budget.ts";++/** TTL after which a prior process's artifact run directory is pruned. */+const ARTIFACT_TTL_MS = 24 * 60 * 60 * 1000;export interface MCPServerOptions {readonly vault: string;@@ -36,6 +41,12 @@ export interface MCPServerOptions {export interface MCPServerRuntimeOptions {readonly serverName?: string;readonly scope?: ToolScope;+ /**+ * Run id grouping this process's preview artifacts under+ * `Brain/.artifacts/<run-id>/`. Defaults to a per-process id;+ * injectable so tests get a deterministic directory.+ */+ readonly artifactRunId?: string;}export interface JsonRpcRequest {@@ -59,6 +70,7 @@ export class MCPServer {readonly tools: ReadonlyArray<ToolDefinition>;private readonly serverName: string;private readonly scope: ToolScope;+ private readonly artifactStore: ArtifactStore;constructor(opts: MCPServerOptions, runtimeOpts: MCPServerRuntimeOptions = {}) {this.vault = opts.vault;@@ -67,10 +79,25 @@ export class MCPServer {this.serverName = runtimeOpts.serverName ?? SERVER_NAME;this.scope = runtimeOpts.scope ?? "full";this.tools = buildToolTable(this.scope);+ const runId =+ runtimeOpts.artifactRunId ?? `run-${process.pid}-${Date.now().toString(36)}`;+ this.artifactStore = new ArtifactStore({ vault: this.vault, runId });+ // Best-effort housekeeping: clear prior processes' stale artifacts.+ // Never fatal - a missing/unwritable vault just yields zero pruned.+ try {+ this.artifactStore.prune(ARTIFACT_TTL_MS);+ } catch {+ // ignore+ }}get context(): ServerContext {- return { vault: this.vault, configPath: this.configPath, repoRoot: this.repoRoot };+ return {+ vault: this.vault,+ configPath: this.configPath,+ repoRoot: this.repoRoot,+ artifactStore: this.artifactStore,+ };}/** Public method for CLI tool-call bridge β the legacy code reached into `_tools`. */@@ -202,7 +229,7 @@ export class MCPServer {const args = argsRaw as Record<string, unknown>;try {const structured = await tool.handler(this.context, args);- return toolResult(tool, structured);+ return buildMcpToolResult(tool, structured, this.artifactStore);} catch (exc) {if (exc instanceof MCPError) throw exc;const message = (exc as Error).message ?? String(exc);@@ -224,6 +251,30 @@ function toolResult(tool: ToolDefinition, structured: unknown): Record<string, u};}+/**+ * MCP `tools/call` result builder. Identical to {@link toolResult} for+ * tools with no `previewBudget` or small outputs, but when a budgeted+ * tool's serialized output exceeds the budget it parks the full payload+ * in `store` and swaps `content[0].text` for a bounded preview envelope.+ * `structuredContent` is always the full, contract-validated object, so+ * programmatic consumers and `outputSchema` are untouched. Exported for+ * direct unit testing of the seam.+ */+export function buildMcpToolResult(+ tool: ToolDefinition,+ structured: unknown,+ store: ArtifactStore,+): Record<string, unknown> {+ assertOutputContract(tool.name, tool.outputSchema, structured);+ const serialized = JSON.stringify(structured, sortedReplacer, 2);+ const outcome = applyPreviewBudget(serialized, tool.previewBudget, store);+ return {+ content: [{ type: "text", text: outcome.text }],+ structuredContent: structured,+ isError: false,+ };+}+function toolError(message: string): Record<string, unknown> {return {content: [{ type: "text", text: message }],diff --git a/src/mcp/tools.ts b/src/mcp/tools.tsindex 09f736a4..66c47b5c 100644--- a/src/mcp/tools.ts+++ b/src/mcp/tools.ts@@ -33,11 +33,19 @@ import { listVaultPages } from "../core/vault.ts";import { INVALID_PARAMS, METHOD_NOT_FOUND, MCPError } from "./protocol.ts";import { coerceStr, coerceInt } from "./coerce.ts";import type { OutputSchema } from "./output-contract.ts";+import type { ArtifactStore } from "./artifact-store.ts";+import { MCP_PREVIEW_BUDGET } from "./preview-budget.ts";export interface ServerContext {readonly vault: string;readonly configPath: string | null;readonly repoRoot: string | null;+ /**+ * Per-process preview-artifact store (v0.18.0). Present on the live MCP+ * server context; `brain_artifact_get` reads parked tool-result payloads+ * back through it. Optional so manually-built contexts stay valid.+ */+ readonly artifactStore?: ArtifactStore;}export interface ToolDefinition {@@ -45,6 +53,15 @@ export interface ToolDefinition {readonly description: string;readonly inputSchema: Record<string, unknown>;readonly outputSchema?: OutputSchema;+ /**+ * Optional MCP preview budget in characters (v0.18.0). When set and+ * the serialized result exceeds it, the JSON-RPC `tools/call` path+ * parks the full payload in the artifact store and returns a bounded+ * preview envelope in `content[0].text` instead, leaving+ * `structuredContent` intact. A tool with no budget is never truncated+ * - opt-in only. The CLI bridge ignores the budget entirely.+ */+ readonly previewBudget?: number;readonly handler: (ctx: ServerContext,args: Record<string, unknown>,@@ -177,6 +194,38 @@ async function toolVaultHealth(};}+async function toolArtifactGet(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ const artifactId = coerceStr(args, "artifact_id", true) as string;+ if (!ctx.artifactStore) {+ throw new Error("artifact store unavailable in this context");+ }+ let content: string | null;+ try {+ content = ctx.artifactStore.get(artifactId);+ } catch (err) {+ // Malformed id (path-traversal attempt) β invalid params.+ throw new MCPError(INVALID_PARAMS, (err as Error)?.message ?? String(err));+ }+ if (content === null) {+ // Well-formed but absent / expired β tool-level error envelope.+ throw new Error(`unknown or expired artifact_id: ${artifactId}`);+ }+ return { artifact_id: artifactId, full_chars: content.length, content };+}++const ARTIFACT_GET_OUTPUT_SCHEMA: OutputSchema = {+ type: "object",+ required: ["artifact_id", "full_chars", "content"],+ properties: {+ artifact_id: { type: "string" },+ full_chars: { type: "integer" },+ content: { type: "string" },+ },+};+export type ToolScope = "full" | "writer";// The set is named after the original payload (mutating writers). As@@ -198,6 +247,7 @@ export function buildToolTable(scope: ToolScope = "full"): ToolDefinition[] {name: "second_brain_status",description: "Report Open Second Brain configuration and vault status.",inputSchema: { type: "object", properties: {}, additionalProperties: false },+ previewBudget: MCP_PREVIEW_BUDGET,handler: toolStatus,},{@@ -219,6 +269,7 @@ export function buildToolTable(scope: ToolScope = "full"): ToolDefinition[] {},additionalProperties: false,},+ previewBudget: MCP_PREVIEW_BUDGET,handler: toolQuery,},// `second_brain_capture` and `event_log_append` were retired from@@ -241,6 +292,24 @@ export function buildToolTable(scope: ToolScope = "full"): ToolDefinition[] {},handler: toolVaultHealth,},+ {+ name: "brain_artifact_get",+ description:+ "Fetch the full payload of a previously preview-truncated tool result by its artifact_id. Read-only.",+ inputSchema: {+ type: "object",+ properties: {+ artifact_id: {+ type: "string",+ description: "The artifact_id returned in a preview-truncated tool result envelope.",+ },+ },+ required: ["artifact_id"],+ additionalProperties: false,+ },+ outputSchema: ARTIFACT_GET_OUTPUT_SCHEMA,+ handler: toolArtifactGet,+ },...PAY_MEMORY_TOOLS,];if (scope === "full") return all;diff --git a/tests/core/search/recall-hint.test.ts b/tests/core/search/recall-hint.test.tsnew file mode 100644index 00000000..360ee57f--- /dev/null+++ b/tests/core/search/recall-hint.test.ts@@ -0,0 +1,51 @@+import { describe, expect, test } from "bun:test";++import { deriveRecallHint } from "../../../src/core/search/recall-hint.ts";++describe("deriveRecallHint", () => {+ test("returns null when there are no results", () => {+ expect(deriveRecallHint([], 0)).toBeNull();+ });++ test("summarises count, type breakdown, and the top hit", () => {+ const hint = deriveRecallHint(+ [+ { searchType: "semantic", score: 0.91, title: "Pref A" },+ { searchType: "semantic", score: 0.71, title: "Pref B" },+ { searchType: "keyword", score: 0.4, title: "Pref C" },+ ],+ 12,+ )!;+ expect(hint).toContain("3 of 12");+ expect(hint).toContain("2 semantic");+ expect(hint).toContain("1 keyword");+ expect(hint).toContain("Pref A");+ expect(hint).toContain("0.91");+ expect(hint).toContain("reasons");+ });++ test("is deterministic for the same input", () => {+ const input = [{ searchType: "keyword", score: 0.5, title: "X" }];+ expect(deriveRecallHint(input, 1)).toBe(deriveRecallHint(input, 1));+ });++ test("trims an overlong title rather than dumping it whole", () => {+ const long = "Z".repeat(500);+ const hint = deriveRecallHint([{ searchType: "keyword", score: 0.5, title: long }], 1)!;+ expect(hint.length).toBeLessThan(300);+ expect(hint).toContain("β¦");+ });++ test("orders the breakdown by descending count", () => {+ const hint = deriveRecallHint(+ [+ { searchType: "keyword", score: 0.4, title: "a" },+ { searchType: "semantic", score: 0.9, title: "b" },+ { searchType: "semantic", score: 0.8, title: "c" },+ { searchType: "semantic", score: 0.7, title: "d" },+ ],+ 4,+ )!;+ expect(hint.indexOf("3 semantic")).toBeLessThan(hint.indexOf("1 keyword"));+ });+});diff --git a/tests/mcp/artifact-get.test.ts b/tests/mcp/artifact-get.test.tsnew file mode 100644index 00000000..514a35bc--- /dev/null+++ b/tests/mcp/artifact-get.test.ts@@ -0,0 +1,74 @@+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 { MCPServer } from "../../src/mcp/server.ts";+import { ArtifactStore } from "../../src/mcp/artifact-store.ts";++let tmp: string;+let vault: string;+let server: MCPServer;+const RUN_ID = "run-fetch";++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-artifact-get-"));+ vault = join(tmp, "vault");+ mkdirSync(vault, { recursive: true });+ server = new MCPServer({ vault }, { artifactRunId: RUN_ID });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++async function call(args: Record<string, unknown>) {+ return server.handleRequest({+ jsonrpc: "2.0",+ id: 1,+ method: "tools/call",+ params: { name: "brain_artifact_get", arguments: args },+ });+}++describe("brain_artifact_get", () => {+ test("returns the full stored payload for a known id", async () => {+ // Stage an artifact under the same vault + runId the server uses.+ const helper = new ArtifactStore({ vault, runId: RUN_ID });+ const payload = JSON.stringify({ rows: Array.from({ length: 100 }, (_, i) => i) });+ const stored = helper.put(payload);++ const result = await server.callTool("brain_artifact_get", {+ artifact_id: stored.artifactId,+ });+ const sc = result["structuredContent"] as Record<string, unknown>;+ expect(sc["artifact_id"]).toBe(stored.artifactId);+ expect(sc["full_chars"]).toBe(payload.length);+ expect(sc["content"]).toBe(payload);+ });++ test("unknown id yields a tool-level error envelope, not a thrown 500", async () => {+ const res = await call({ artifact_id: "deadbeefdeadbeef" });+ expect(res).not.toBeNull();+ const result = res!.result as Record<string, unknown>;+ expect(result["isError"]).toBe(true);+ });++ test("a path-traversal id is rejected", async () => {+ const res = await call({ artifact_id: "../../etc/passwd" });+ expect(res).not.toBeNull();+ // Either a JSON-RPC error frame or a tool-level error envelope is fine,+ // as long as it is not a successful fetch.+ const errored =+ res!.error !== undefined ||+ (res!.result as Record<string, unknown> | undefined)?.["isError"] === true;+ expect(errored).toBe(true);+ });++ test("is advertised in full scope but not in writer scope", () => {+ const full = new MCPServer({ vault }, { scope: "full" });+ const writer = new MCPServer({ vault }, { scope: "writer" });+ expect(full.tools.some((t) => t.name === "brain_artifact_get")).toBe(true);+ expect(writer.tools.some((t) => t.name === "brain_artifact_get")).toBe(false);+ });+});diff --git a/tests/mcp/artifact-store.test.ts b/tests/mcp/artifact-store.test.tsnew file mode 100644index 00000000..0698c42b--- /dev/null+++ b/tests/mcp/artifact-store.test.ts@@ -0,0 +1,94 @@+import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { existsSync, mkdirSync, mkdtempSync, rmSync, utimesSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { ArtifactStore } from "../../src/mcp/artifact-store.ts";+import { brainArtifactsDir } from "../../src/core/brain/paths.ts";++let tmp: string;+let vault: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-artifact-store-"));+ vault = join(tmp, "vault");+ mkdirSync(vault, { recursive: true });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++describe("ArtifactStore", () => {+ test("put round-trips the full text through get", () => {+ const store = new ArtifactStore({ vault, runId: "run-1" });+ const text = "x".repeat(5000);+ const stored = store.put(text);+ expect(stored.fullChars).toBe(5000);+ expect(store.get(stored.artifactId)).toBe(text);+ });++ test("put stores the artifact under Brain/.artifacts/<runId>/ inside the vault", () => {+ const store = new ArtifactStore({ vault, runId: "run-1" });+ const stored = store.put("hello");+ expect(stored.path.startsWith(join(brainArtifactsDir(vault), "run-1"))).toBe(true);+ expect(existsSync(stored.path)).toBe(true);+ });++ test("identical input yields a stable artifact id; different input differs", () => {+ const store = new ArtifactStore({ vault, runId: "run-1" });+ const a = store.put("same payload");+ const b = store.put("same payload");+ const c = store.put("other payload");+ expect(a.artifactId).toBe(b.artifactId);+ expect(a.artifactId).not.toBe(c.artifactId);+ });++ test("get returns null for a well-formed but unknown id", () => {+ const store = new ArtifactStore({ vault, runId: "run-1" });+ expect(store.get("deadbeefdeadbeef")).toBeNull();+ });++ test("get rejects a path-traversal id", () => {+ const store = new ArtifactStore({ vault, runId: "run-1" });+ expect(() => store.get("../../etc/passwd")).toThrow();+ });++ test("put redacts secret-shaped tokens before persisting", () => {+ const store = new ArtifactStore({ vault, runId: "run-1" });+ const stored = store.put('{"api_key": "SECRET-TOKEN-123456"}');+ const back = store.get(stored.artifactId)!;+ expect(back).not.toContain("SECRET-TOKEN-123456");+ expect(back).toContain("***REDACTED***");+ // fullChars reflects the persisted (redacted) length, not the raw input.+ expect(stored.fullChars).toBe(back.length);+ });++ test("stores the full payload even when it exceeds the redactor's context cap", () => {+ // The whole point of the artifact path is that brain_artifact_get can+ // recover the COMPLETE payload. The receipt redactor caps input at+ // 256 KiB for context protection; the artifact store must not inherit+ // that cap or large results would be silently truncated on disk.+ const store = new ArtifactStore({ vault, runId: "run-1" });+ const big = "q".repeat(300 * 1024);+ const stored = store.put(big);+ expect(stored.fullChars).toBe(big.length);+ expect(store.get(stored.artifactId)).toBe(big);+ });++ test("prune removes run directories older than the TTL and keeps fresh ones", () => {+ const oldStore = new ArtifactStore({ vault, runId: "run-old" });+ oldStore.put("old payload");+ const freshStore = new ArtifactStore({ vault, runId: "run-fresh" });+ freshStore.put("fresh payload");++ const oldDir = join(brainArtifactsDir(vault), "run-old");+ const past = new Date(Date.now() - 72 * 3600 * 1000);+ utimesSync(oldDir, past, past);++ const removed = freshStore.prune(24 * 3600 * 1000);+ expect(removed).toBe(1);+ expect(existsSync(oldDir)).toBe(false);+ expect(existsSync(join(brainArtifactsDir(vault), "run-fresh"))).toBe(true);+ });+});diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.tsindex 105311dd..1b8239b0 100644--- a/tests/mcp/mcp.test.ts+++ b/tests/mcp/mcp.test.ts@@ -177,6 +177,8 @@ describe("tool listing", () => {"second_brain_status","second_brain_query","vault_health",+ // Preview-budget artifact fetch (added in v0.18.0).+ "brain_artifact_get",// Brain (brain_note added in v0.10.8 Β§32B,// brain_context added in v0.10.10,// brain_context_pack added in v0.10.15,@@ -460,8 +462,9 @@ describe("stdio loop", () => {// brain_stale_scan / brain_daily_brief / brain_weekly_synthesis// added v0.10.18; brain_agent_query / brain_agent_diff added in// v0.15.0; brain_pinned_context added in v0.16.0; lifecycle review- // tools added in v0.17.0) + 8 Pay Memory + 1 Search = 39.- expect(list.result.tools.length).toBe(39);+ // tools added in v0.17.0) + 8 Pay Memory + 1 Search+ // + brain_artifact_get (v0.18.0) = 40.+ expect(list.result.tools.length).toBe(40);});test("returns parse error for invalid JSON", async () => {diff --git a/tests/mcp/preview-budget-dispatch.test.ts b/tests/mcp/preview-budget-dispatch.test.tsnew file mode 100644index 00000000..47bb2608--- /dev/null+++ b/tests/mcp/preview-budget-dispatch.test.ts@@ -0,0 +1,78 @@+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 { buildMcpToolResult } from "../../src/mcp/server.ts";+import { ArtifactStore } from "../../src/mcp/artifact-store.ts";+import type { ToolDefinition } from "../../src/mcp/tools.ts";++let tmp: string;+let vault: string;+let store: ArtifactStore;++function tool(overrides: Partial<ToolDefinition>): ToolDefinition {+ return {+ name: "synthetic_tool",+ description: "test",+ inputSchema: { type: "object", properties: {}, additionalProperties: false },+ handler: () => ({}),+ ...overrides,+ };+}++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-budget-dispatch-"));+ vault = join(tmp, "vault");+ mkdirSync(vault, { recursive: true });+ store = new ArtifactStore({ vault, runId: "run-dispatch" });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++describe("buildMcpToolResult preview budget", () => {+ test("over-budget output: content is a preview envelope, structuredContent stays full", () => {+ const structured = { rows: Array.from({ length: 200 }, (_, i) => ({ i, pad: "x".repeat(40) })) };+ const result = buildMcpToolResult(tool({ previewBudget: 300 }), structured, store);++ const content = result["content"] as Array<{ type: string; text: string }>;+ const env = JSON.parse(content[0]!.text);+ expect(env.preview_truncated).toBe(true);+ expect(typeof env.artifact_id).toBe("string");++ // structuredContent is untouched - full object, same identity.+ expect(result["structuredContent"]).toBe(structured);+ expect(result["isError"]).toBe(false);++ // The full payload is fetchable from the store.+ const back = store.get(env.artifact_id);+ expect(back).not.toBeNull();+ expect(JSON.parse(back!).rows).toHaveLength(200);+ });++ test("under-budget output is byte-identical to the plain serialization", () => {+ const structured = { ok: true, n: 3 };+ const budgeted = buildMcpToolResult(tool({ previewBudget: 10_000 }), structured, store);+ const content = budgeted["content"] as Array<{ type: string; text: string }>;+ expect(JSON.parse(content[0]!.text)).toEqual(structured);+ expect(content[0]!.text).not.toContain("preview_truncated");+ });++ test("a tool with no budget is never truncated regardless of size", () => {+ const structured = { rows: Array.from({ length: 500 }, (_, i) => ({ i, pad: "y".repeat(40) })) };+ const result = buildMcpToolResult(tool({}), structured, store);+ const content = result["content"] as Array<{ type: string; text: string }>;+ expect(content[0]!.text).not.toContain("preview_truncated");+ expect(JSON.parse(content[0]!.text).rows).toHaveLength(500);+ });++ test("output-contract violations still throw before any truncation", () => {+ const badTool = tool({+ previewBudget: 10,+ outputSchema: { type: "object", required: ["must_have"], properties: {} },+ });+ expect(() => buildMcpToolResult(badTool, { other: 1 }, store)).toThrow(/must_have/);+ });+});diff --git a/tests/mcp/preview-budget-wiring.test.ts b/tests/mcp/preview-budget-wiring.test.tsnew file mode 100644index 00000000..d3b3f07f--- /dev/null+++ b/tests/mcp/preview-budget-wiring.test.ts@@ -0,0 +1,52 @@+import { describe, expect, test } from "bun:test";++import { buildToolTable } from "../../src/mcp/tools.ts";+import { MCP_PREVIEW_BUDGET } from "../../src/mcp/preview-budget.ts";++/**+ * The exact set of tools that opt into the preview budget. Kept explicit+ * so adding/removing a budget is a deliberate, reviewed change rather+ * than an accident of a default.+ */+const BUDGETED = new Set<string>([+ "brain_search",+ "brain_context_pack",+ "brain_digest",+ "brain_timeline",+ "brain_concept_synthesis",+ "brain_operator_summary",+ "brain_weekly_synthesis",+ "brain_monthly_review",+ "brain_daily_brief",+ "second_brain_status",+ "second_brain_query",+]);++describe("preview-budget wiring", () => {+ test("exactly the enumerated large tools carry the shared budget", () => {+ const table = buildToolTable("full");+ const withBudget = new Set<string>();+ for (const tool of table) {+ if (tool.previewBudget !== undefined) {+ withBudget.add(tool.name);+ expect(tool.previewBudget).toBe(MCP_PREVIEW_BUDGET);+ }+ }+ expect([...withBudget].toSorted()).toEqual([...BUDGETED].toSorted());+ });++ test("small status/echo and writer tools stay unbudgeted", () => {+ const table = buildToolTable("full");+ const byName = new Map(table.map((t) => [t.name, t]));+ for (const name of [+ "brain_feedback",+ "brain_note",+ "brain_apply_evidence",+ "brain_artifact_get",+ "vault_health",+ "brain_doctor",+ ]) {+ expect(byName.get(name)?.previewBudget).toBeUndefined();+ }+ });+});diff --git a/tests/mcp/preview-budget.test.ts b/tests/mcp/preview-budget.test.tsnew file mode 100644index 00000000..4cb2d324--- /dev/null+++ b/tests/mcp/preview-budget.test.ts@@ -0,0 +1,97 @@+import { describe, expect, test } from "bun:test";++import { applyPreviewBudget } from "../../src/mcp/preview-budget.ts";+import type { StoredArtifact } from "../../src/mcp/artifact-store.ts";++/** Minimal stand-in for ArtifactStore.put used by applyPreviewBudget. */+function fakeStore(redact: (s: string) => string = (s) => s) {+ const writes: string[] = [];+ return {+ writes,+ put(fullText: string): StoredArtifact {+ const text = redact(fullText);+ writes.push(text);+ return {+ artifactId: "abc123",+ runId: "run-test",+ path: "/dev/null",+ fullChars: text.length,+ text,+ };+ },+ };+}++describe("applyPreviewBudget", () => {+ test("passes text through unchanged when under budget", () => {+ const store = fakeStore();+ const out = applyPreviewBudget("small", 100, store);+ expect(out.truncated).toBe(false);+ expect(out.text).toBe("small");+ expect(out.artifactId).toBeNull();+ expect(store.writes).toHaveLength(0);+ });++ test("passes text through unchanged when budget is undefined (opt-in only)", () => {+ const store = fakeStore();+ const big = "x".repeat(10_000);+ const out = applyPreviewBudget(big, undefined, store);+ expect(out.truncated).toBe(false);+ expect(out.text).toBe(big);+ expect(store.writes).toHaveLength(0);+ });++ test("over budget: stores full text and returns a valid-JSON preview envelope", () => {+ const store = fakeStore();+ const big = "y".repeat(5000);+ const out = applyPreviewBudget(big, 200, store);++ expect(out.truncated).toBe(true);+ expect(out.artifactId).toBe("abc123");+ expect(store.writes).toEqual([big]);++ // content text must itself be parseable JSON even though the slice+ // would have cut mid-record.+ const env = JSON.parse(out.text);+ expect(env.preview_truncated).toBe(true);+ expect(env.artifact_id).toBe("abc123");+ expect(env.full_chars).toBe(5000);+ expect(env.bytes_preview.length).toBeLessThanOrEqual(200);+ expect(typeof env.note).toBe("string");+ expect(env.note).toContain("brain_artifact_get");+ });++ test("preview is sliced from the redacted text, not the raw input", () => {+ const store = fakeStore((s) => s.replace("SECRET-TOKEN-XYZ", "***REDACTED***"));+ const raw = "SECRET-TOKEN-XYZ " + "z".repeat(5000);+ const out = applyPreviewBudget(raw, 100, store);+ const env = JSON.parse(out.text);+ expect(env.bytes_preview).not.toContain("SECRET-TOKEN-XYZ");+ expect(env.bytes_preview).toContain("***REDACTED***");+ });++ test("a negative or non-finite budget is normalized, not slice-abused", () => {+ const big = "y".repeat(5000);+ for (const bad of [-1, Number.NaN, Number.POSITIVE_INFINITY]) {+ const store = fakeStore();+ const out = applyPreviewBudget(big, bad, store);+ // Infinity must NOT truncate (budget never exceeded); negative/NaN+ // clamp to 0 so the preview can't leak nearly the whole payload.+ if (bad === Number.POSITIVE_INFINITY) {+ expect(out.truncated).toBe(false);+ expect(out.text).toBe(big);+ } else {+ expect(out.truncated).toBe(true);+ const env = JSON.parse(out.text);+ expect(env.bytes_preview).toBe("");+ }+ }+ });++ test("the preview envelope is far smaller than the original payload", () => {+ const store = fakeStore();+ const big = "w".repeat(50_000);+ const out = applyPreviewBudget(big, 2000, store);+ expect(out.text.length).toBeLessThan(big.length / 10);+ });+});