//! The context compiler's MCP tools — an *extension* of the one existing
//! server (never a second server): a second `#[tool_router]` block whose
//! router is combined with the main one in `McpServer::new`.
//!
//! Wire shapes reuse the domain types from [`crate::context`] directly
//! (`CompileRequest` *is* the tool input, `CompiledContext` the output) —
//! the only DTOs here are the thin request envelopes of the seven smaller
//! tools. Same conventions as every other tool: `spawn_blocking` around the
//! sync service, errors mapped through the transport-neutral category.
use std::sync::Arc;
use rmcp::handler::server::wrapper::{Json, Parameters};
use rmcp::model::ErrorCode;
use rmcp::{tool, tool_router, ErrorData};
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::Value;
use super::{join_error, to_error, McpServer};
use crate::context::wire::stringify_id_fields;
use crate::context::{
fragment_id, segment_transcript, suggest_token_budget, CompilePolicy, CompileRequest,
CompiledContext, ContextCompiler, ContextDecision, ContextFragment, ContextSavings,
LoadedWorkingContext, MediaRef, SegmentFormat, SegmentKind, SegmentationPolicy,
SuggestedBudget, WorkingContext, WorkingContextSession,
};
/// Serialize `payload`, opt-in rewriting every id field into decimal-string
/// form ([`CompilePolicy::ids_as_strings`]) — the shared response-side half
/// of the wire-compat contract, reused by both `compile_context` and
/// `explain_compilation` so the id rewrite is expressed exactly once.
fn to_wire_value<T: serde::Serialize>(
payload: &T,
ids_as_strings: bool,
) -> Result<Value, ErrorData> {
let mut value = serde_json::to_value(payload).map_err(|err| {
ErrorData::internal_error(
format!("Failed to serialize structured content: {err}"),
None,
)
})?;
if ids_as_strings {
stringify_id_fields(&mut value);
}
Ok(value)
}
fn segment_for_compilation(
text: &str,
policy: &SegmentationPolicy,
) -> Result<(Vec<ContextFragment>, SegmentationReport), ErrorData> {
let outcome = segment_transcript(text, policy).map_err(to_error)?;
let segments = outcome
.segments
.iter()
.enumerate()
.map(|(index, segment)| SegmentInfo {
index,
turn: segment.turn,
role: segment.role.clone(),
kind: segment.kind,
byte_start: segment.byte_start,
byte_end: segment.byte_end,
fragment_id: fragment_id(&segment.fragment.content),
})
.collect();
let fragments = outcome
.segments
.into_iter()
.map(|segment| segment.fragment)
.collect();
let report = SegmentationReport {
format_detected: outcome.format_detected,
segments,
merged_segments: outcome.merged_segments,
};
Ok((fragments, report))
}
/// The advertised-schema half of the [`CompilePolicy::ids_as_strings`]
/// contract: the response may carry each [`ID_KEYS`] field as an integer OR
/// a decimal string, and the official MCP SDKs validate `structuredContent`
/// against the advertised `outputSchema` (spec 2025-06-18) — so those
/// fields must be typed `["integer", "string"]`, or every opted-in response
/// would fail client-side validation for exactly the clients the option
/// exists for.
pub(super) use crate::schema::wire_safe_output_schema;
/// Input-side counterpart: `fragments[].id` accepts an integer or a decimal
/// string ([`crate::context::wire::deserialize_optional_id`]), so the
/// advertised input schema announces the string form — a client generating
/// requests from the schema must be able to discover it.
///
/// Le jeu de cles n'est plus fige a `"id"` : il est passe par l'outil, comme
/// dans `mcp.rs`, parce que `save_working_context` porte des ids sous
/// d'autres noms (`fragment_id`, `memory_id`, imbriques dans
/// `WorkingContext`) tandis que `explain_compilation.fragment_id` est un
/// `u64` STRICT qu'annoncer `string` serait une promesse fausse. Un seul
/// constructeur, donc, mais toujours une decision par outil.
pub(super) use crate::schema::wire_safe_input_schema;
// --- Thin request envelopes --------------------------------------------------
/// Input of the `context_savings` tool.
#[derive(Debug, Deserialize, JsonSchema)]
pub(super) struct ContextSavingsParams {
/// Restrict the aggregation to this project facet.
pub project: Option<String>,
}
/// Input of the `explain_compilation` tool.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(transform = crate::schema::strip_int_formats)]
pub(super) struct ExplainCompilationParams {
/// The compile request to explain (compilation is deterministic, so
/// re-submitting the request reproduces the exact decisions).
#[serde(deserialize_with = "super::wire::lenient")]
pub request: CompileRequest,
// Aller-retour casse jusqu'au 2026-07-29, et casse depuis toujours :
// `fragment_id` est le SELECTEUR d'une decision, et la decision d'ou le
// client le tire lui arrive en CHAINE decimale des que la requete porte
// `policy.ids_as_strings` (`fragment_id` est dans
// `context::wire::ID_KEYS`). Ce champ etait un `u64` nu : l'outil
// refusait litteralement les octets qu'il venait d'emettre, et comme un
// `fragment_id` est un FNV-1a 64 — au-dela de 2^53 dans ~99,95 % des cas
// — le repli « renvoyer un nombre » etait deja arrondi chez un client
// JSON a nombres flottants. Les deux formes echouaient : sur un tel
// client, l'outil etait inatteignable par son propre selecteur.
//
// Ce n'etait pas une omission : trois tests et deux jeux de cles d'id
// epinglaient la forme stricte comme voulue. Ce que personne n'avait
// fait, c'est l'aller-retour.
/// The fragment whose decision to return. Looked up by matching
/// `ContextDecision::fragment_id`, UNLESS `fragment_index` is also
/// given (see there) — still required even then, since it is the only
/// disambiguator when `fragment_index` is absent. Accepts a JSON number
/// OR a decimal string, so a `fragment_id` received under
/// [`CompilePolicy::ids_as_strings`] can be relayed back unchanged.
#[serde(deserialize_with = "crate::model::deserialize_id")]
pub fragment_id: u64,
/// Optional, 0-based position of the fragment in `request.fragments`.
/// When given, TAKES PRIORITY over `fragment_id` for locating the
/// decision: `compile_context` records exactly one decision per input
/// fragment, in order, so `decisions[fragment_index]` is unambiguous
/// even when several fragments are byte-identical and therefore share
/// the same content-addressed `fragment_id` — a plain `fragment_id`
/// lookup always returns the FIRST such decision (the deduplication
/// survivor), never a dropped twin's. Absent (the default): behavior is
/// unchanged, the decision is found by `fragment_id` alone.
#[serde(
default,
skip_serializing_if = "Option::is_none",
deserialize_with = "super::wire::lenient"
)]
pub fragment_index: Option<usize>,
}
/// Input of the `retrieve_context_source` tool.
#[derive(Debug, Deserialize, JsonSchema)]
pub(super) struct RetrieveContextSourceParams {
/// A `ctx://source/<hash>` handle from a compiled context.
pub handle: String,
}
/// Output of the `retrieve_context_source` tool.
#[derive(Debug, serde::Serialize, JsonSchema)]
pub(super) struct RetrieveContextSourceResult {
/// The handle that was resolved.
pub handle: String,
/// The original fragment content, byte for byte.
pub content: String,
/// The original media payload, when the fragment carried one (US-009,
/// PR2). Absent for every text-only source — the exact pre-PR2 shape.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub media: Option<MediaRef>,
}
/// Input of the `save_working_context` tool.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(transform = crate::schema::strip_int_formats)]
pub(super) struct SaveWorkingContextParams {
/// Project facet this working context belongs to (matches `remember`'s
/// `project` metadata convention).
pub project: String,
/// Session identifier — pick something stable for the agent run you want
/// to resume later (e.g. a conversation id).
pub session: String,
/// The distilled state to persist: goal, active constraints, verified
/// facts, open hypotheses, decisions taken, exact evidence, and pending
/// actions.
#[serde(deserialize_with = "super::wire::lenient")]
pub working: WorkingContext,
}
/// Output of the `save_working_context` tool.
#[derive(Debug, serde::Serialize, JsonSchema)]
#[schemars(transform = crate::schema::strip_int_formats)]
pub(super) struct SaveWorkingContextResult {
/// Id of the stored system fact backing this working context.
pub id: u64,
/// Decimal-string twin of `id`, same contract as
/// [`crate::mcp::dto::RememberResult::id_str`]: the id is content-addressed
/// (FNV-1a 64), so it is past 2^53 and a float-lossy JSON client rounds
/// `id` on arrival. This was the ONE tool handing back an id without its
/// twin while `forget`/`feedback` accept only the decimal string — the
/// caller had no way to build the form the schema demands.
pub id_str: String,
}
/// Input of the `load_working_context` tool.
#[derive(Debug, Deserialize, JsonSchema)]
pub(super) struct LoadWorkingContextParams {
/// Project facet the working context was saved under.
pub project: String,
/// Session identifier the working context was saved under.
pub session: String,
}
/// Input of the `list_working_contexts` tool.
#[derive(Debug, Deserialize, JsonSchema)]
pub(super) struct ListWorkingContextsParams {
/// Project facet to list saved working-context sessions for (same
/// convention as `save_working_context`'s `project`).
pub project: String,
}
/// Output of the `list_working_contexts` tool.
#[derive(Debug, serde::Serialize, JsonSchema)]
pub(super) struct ListWorkingContextsResult {
/// Every session saved under this project, most-recently-saved first.
/// Empty (not an error) when the project never saved anything.
pub sessions: Vec<WorkingContextSession>,
}
/// Input of the `compile_transcript` tool.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(transform = crate::schema::strip_int_formats)]
pub(super) struct CompileTranscriptParams {
/// What the agent is working on — drives relevance scoring, exactly like
/// `compile_context`'s `query`.
pub query: String,
/// The raw transcript text (plain, marker-based, or JSONL). Exactly one
/// of `transcript` or `path` must be set.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub transcript: Option<String>,
/// Read the transcript from this absolute filesystem path instead of
/// inline `transcript` — the same `VELESDB_MEMORY_INGEST_ROOTS`
/// allowlist and security pipeline as a `compile_context` fragment's
/// `path` (V2b-1), except capped at
/// [`crate::limits::MAX_TRANSCRIPT_BYTES`] (8 MiB) instead of the
/// ordinary 1 MiB fragment ceiling — the transcript is segmented into
/// sub-1-MiB pieces immediately after this read.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub path: Option<String>,
/// Hard token ceiling for the assembled content, same as
/// `compile_context`'s `token_budget`.
#[serde(deserialize_with = "super::wire::lenient")]
pub token_budget: u64,
/// Project facet, recorded in provenance.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub project: Option<String>,
/// Target model name, for cost insights.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub target_model: Option<String>,
/// Per-request compile policy override, same as `compile_context`'s
/// `policy`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub policy: Option<CompilePolicy>,
/// Tuning knobs for the transcript segmentation step itself (format,
/// merge threshold, system-turn caching). `None` uses
/// [`SegmentationPolicy::default`].
#[serde(
default,
skip_serializing_if = "Option::is_none",
deserialize_with = "super::wire::lenient"
)]
pub segmentation: Option<SegmentationPolicy>,
}
/// One entry of [`SegmentationReport::segments`] — the audit trail of how
/// `compile_transcript` cut the transcript up, independent of what
/// `compile_context` then did with the resulting fragments.
#[derive(Debug, serde::Serialize, serde::Deserialize, JsonSchema)]
#[schemars(transform = crate::schema::strip_int_formats)]
pub(super) struct SegmentInfo {
/// Position of this segment in `segmentation.segments`, in transcript
/// order.
pub index: usize,
/// Which turn (0-based) this segment belongs to.
pub turn: usize,
/// The turn's role, when one was determined. `null` for a `plain`
/// transcript with no matching marker at all.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub role: Option<String>,
/// `"body"`, `"code"`, or `"log"`.
pub kind: SegmentKind,
/// Start byte offset (inclusive) in the original transcript. For a
/// `jsonl` transcript this is a slice of the raw JSON line's span, not
/// an offset into the decoded `content` — a JSONL line's decoded text
/// has no byte-exact mapping back into the raw (JSON-escaped) source
/// bytes, so when a single line's decoded content is re-split (over
/// [`crate::limits::MAX_FRAGMENT_BYTES`]) each child's range is a
/// proportional, non-overlapping share of the line's raw range rather
/// than a byte-precise one. Every segment's range is still distinct and
/// non-overlapping (see [`SegmentationReport::segments`]'s struct docs).
pub byte_start: usize,
/// End byte offset (exclusive) in the original transcript. Same caveat
/// as `byte_start`.
pub byte_end: usize,
/// The id this segment's fragment carries into `context.decisions` —
/// content-addressed, same formula as every other `compile_context`
/// fragment with no caller-supplied `id`.
pub fragment_id: u64,
}
/// The segmentation audit trail returned alongside `context`.
#[derive(Debug, serde::Serialize, serde::Deserialize, JsonSchema)]
pub(super) struct SegmentationReport {
/// `"plain"` or `"jsonl"` — the format actually used, never `"auto"`
/// even when the request asked for it.
pub format_detected: SegmentFormat,
/// Every segment, in transcript order, with byte ranges that partition
/// the transcript exactly — no gaps, no overlaps, even for a `jsonl`
/// line whose decoded `content` alone exceeds
/// [`crate::limits::MAX_FRAGMENT_BYTES`] (1 MiB) and gets re-split into
/// several segments (`compile_context` still gets sub-1-MiB fragments):
/// each child's range is a proportional, non-overlapping share of the
/// original JSON line's raw span rather than a byte-exact one, since a
/// JSONL line's decoded text has no byte-aligned mapping back into the
/// raw (JSON-escaped) source bytes (see `resplit_body` in
/// `context::segment`). An extreme edge case (one transcript line over
/// 1 MiB of decoded content), but even then every segment keeps a
/// distinct, non-overlapping range.
pub segments: Vec<SegmentInfo>,
/// How many segments [`SegmentationPolicy::min_segment_bytes`] merging
/// eliminated.
pub merged_segments: usize,
}
/// Output of the `compile_transcript` tool.
#[derive(Debug, serde::Serialize, serde::Deserialize, JsonSchema)]
pub(super) struct CompileTranscriptResult {
/// The compiled context — byte-compatible with `compile_context`'s
/// output.
pub context: CompiledContext,
/// How the transcript was cut into fragments before compilation.
pub segmentation: SegmentationReport,
}
/// Input of the `suggest_budget` tool.
#[derive(Debug, Deserialize, JsonSchema)]
pub(super) struct SuggestBudgetParams {
/// The model name to look up in the static window table (e.g.
/// `"claude-sonnet-4-5"`). Matched case-insensitively.
pub target_model: String,
/// Tokens to reserve for the response, subtracted from the model's
/// window (default `0`) — mirrors
/// [`CompilePolicy::response_reserve_tokens`].
#[serde(
default,
skip_serializing_if = "Option::is_none",
deserialize_with = "super::wire::lenient"
)]
pub reserve_tokens: Option<u64>,
}
#[tool_router(router = context_tool_router, vis = "pub(super)")]
impl McpServer {
/// Resolve every `path`-carrying fragment of `fragments` against this
/// server's configured ingest roots (V2b-1), turning `path` into
/// ordinary `content` in place before the request reaches the compiler
/// — the adapter-side pre-pass `context::ingest` describes. A no-op
/// when no fragment carries a `path`. Shared by `compile_context` and
/// `explain_compilation`, the only two tools that accept a `path`
/// fragment.
#[cfg(not(target_arch = "wasm32"))]
fn resolve_ingest(&self, fragments: &mut [ContextFragment]) -> Result<(), ErrorData> {
crate::context::ingest::resolve_fragments(fragments, self.ingest_roots.as_ref())
.map_err(to_error)
}
/// This crate never targets `wasm32` with the `mcp` feature on (the
/// server pulls in `rmcp`/`tokio`), so this arm exists only to keep the
/// call site uniform if that ever changes — a `path` fragment simply
/// reports the same "ingestion disabled" error the pure compiler core
/// would (see `context::validate`), since there is no adapter here to
/// resolve it.
#[cfg(target_arch = "wasm32")]
fn resolve_ingest(&self, fragments: &mut [ContextFragment]) -> Result<(), ErrorData> {
if fragments.iter().any(|f| f.path.is_some()) {
return Err(to_error(crate::error::MemoryError::IngestDisabled));
}
Ok(())
}
/// Resolve a `compile_transcript` `path` field against this server's
/// configured ingest roots (V2b-2) — the same security pipeline as
/// [`Self::resolve_ingest`], but through
/// [`crate::context::ingest::resolve_transcript_path`] so the byte cap
/// is [`crate::limits::MAX_TRANSCRIPT_BYTES`], not the ordinary 1 MiB
/// fragment ceiling.
#[cfg(not(target_arch = "wasm32"))]
fn resolve_transcript_path(&self, path: &str) -> Result<String, ErrorData> {
let roots = self
.ingest_roots
.as_ref()
.filter(|roots| roots.is_enabled())
.ok_or_else(|| to_error(crate::error::MemoryError::IngestDisabled))?;
crate::context::ingest::resolve_transcript_path(path, roots).map_err(to_error)
}
/// `mcp` never targets `wasm32` (see [`Self::resolve_ingest`]'s wasm
/// arm) — kept for call-site uniformity.
#[cfg(target_arch = "wasm32")]
fn resolve_transcript_path(&self, _path: &str) -> Result<String, ErrorData> {
Err(to_error(crate::error::MemoryError::IngestDisabled))
}
/// The text `compile_transcript` will segment: exactly one of `transcript`
/// (inline) or `path` (ingested through the allowlist), and never empty.
///
/// The emptiness check runs AFTER `path` is resolved, rather than being
/// folded into the match, so an inline empty string and a `path` that
/// resolves to an empty file are rejected identically — the ingest
/// pipeline itself happily reads a zero-byte file, so this is the one
/// place that catches "nothing to compile" whatever the source.
fn resolve_transcript_text(
&self,
transcript: Option<String>,
path: Option<String>,
) -> Result<String, ErrorData> {
let text = match (transcript, path) {
(Some(text), None) => text,
(None, Some(path)) => self.resolve_transcript_path(&path)?,
_ => {
return Err(ErrorData::new(
ErrorCode::INVALID_PARAMS,
"exactly one of `transcript` or `path` must be set".to_owned(),
None,
));
}
};
if text.is_empty() {
return Err(ErrorData::new(
ErrorCode::INVALID_PARAMS,
"the transcript is empty — `transcript` must be non-empty text, or `path` must \
point to a non-empty file"
.to_owned(),
None,
));
}
Ok(text)
}
#[tool(
name = "compile_context",
description = "Compile context fragments into a token-budgeted, provenance-audited prompt context — deterministically, with no LLM call. Duplicates are dropped, repeated log lines collapse, code/URLs/numbers/negative constraints survive verbatim, over-budget content becomes retrievable ctx://source/ handles instead of silently vanishing, and `memory_scope` pulls relevant stored memories into the result. Each fragment's own `metadata` is capped at 64 KiB serialized. A fragment may set `path` (an absolute filesystem path) instead of inline `content` to ingest a file by reference — `path` is exclusive and cannot be combined with `content` or `media`, while `content` and `media` MAY travel together (the content is then the image's caption, and the only text lexical relevance can read); a fragment carrying none of the three is refused. Path ingestion requires the server to be started with VELESDB_MEMORY_INGEST_ROOTS set to an allowlist of directories, and the resolved file must be plain UTF-8 text under 1 MiB. Returns the assembled content plus one auditable decision per fragment (rule id, reason, risk), the sources, the retrieval handles, token-savings insights, and `warnings` — a mechanical shortlist of externalized fragments relevant enough to the query that they are worth a second look. An empty `warnings` is NOT a clean bill of health: only `retrieve` decisions at or above a relevance floor ever qualify, so a `preserve` fragment the packer could only fit partially, and an abstracted one, are real losses that never appear there — `decisions` stays the exhaustive record, and `risk` is the cheap second signal. `policy.slim_response` (default false) empties `sections`/`decisions` from the response — keep it off when you need the audit trail, or re-compile without it later (compilation is deterministic). `policy.ids_as_strings` (default false) rewrites every id field of the response into a decimal string, for MCP clients without u64-safe JSON number parsing.",
input_schema = wire_safe_input_schema::<CompileRequest>(&["id"]),
output_schema = wire_safe_output_schema::<CompiledContext>()
)]
async fn compile_context(
&self,
Parameters(mut request): Parameters<CompileRequest>,
) -> Result<Json<Value>, ErrorData> {
self.resolve_ingest(&mut request.fragments)?;
let ids_as_strings = request.policy.as_ref().is_some_and(|p| p.ids_as_strings);
let service = Arc::clone(&self.service);
let compiled = tokio::task::spawn_blocking(move || {
service.run(|current| {
current.compile_context(&ContextCompiler::new(CompilePolicy::default()), &request)
})
})
.await
.map_err(join_error)?
.map_err(to_error)?;
Ok(Json(to_wire_value(&compiled, ids_as_strings)?))
}
/// **Error taxonomy (issue #1516, m2 — refines the PR #1500 review
/// note):** a genuine budget/cap breach — oversized fence, too many
/// fragments after merging, transcript over
/// [`crate::limits::MAX_TRANSCRIPT_BYTES`] — surfaces as
/// [`crate::error::MemoryError::ContextOverLimit`]. A forced `jsonl`
/// format that fails to parse is a FORMAT failure, not a size breach, so
/// it surfaces as the distinct
/// [`crate::error::MemoryError::SegmentationError`] instead — no longer
/// the misleading "over limit" wording. Both variants still map to the
/// same `INVALID_PARAMS`-category MCP code (`ContextOverLimit` and
/// `SegmentationError` are both [`crate::error::ErrorCategory::InvalidInput`]),
/// so this only changes how a caller who inspects `MemoryError`
/// programmatically (e.g. via the Rust crate directly, not over MCP)
/// tells the two apart.
#[tool(
name = "compile_transcript",
description = "One-call shortcut over compile_context for a raw agent-session transcript: deterministically segments it into turns (plain marker-based — System:/User:/Human:/Assistant:/AI:/Tool:/### User/### Assistant — or JSONL, one line per turn) and, within each turn, into code/log/body sub-segments (fenced code blocks stay atomic; runs of 8+ log-like lines collapse the same way abstract.log_dedup would), then compiles the result exactly like compile_context. Exactly one of `transcript` (inline) or `path` (an absolute filesystem path, same VELESDB_MEMORY_INGEST_ROOTS allowlist as compile_context's `path` fragments but capped at 8 MiB) must be set. `segmentation.format` forces plain or jsonl instead of auto-detecting; a forced jsonl format that fails to parse is a hard error, never a silent fallback. The first turn is tagged cache-eligible when it looks like a system prompt (segmentation.cache_system_turn, default true). Returns `context` (byte-compatible with compile_context's output) plus `segmentation` — the detected format and one audit entry (turn, role, kind, byte range, fragment_id) per segment, so a caller can see exactly how the transcript was cut before trusting the compiled result.",
input_schema = wire_safe_input_schema::<CompileTranscriptParams>(&[]),
output_schema = wire_safe_output_schema::<CompileTranscriptResult>()
)]
async fn compile_transcript(
&self,
Parameters(params): Parameters<CompileTranscriptParams>,
) -> Result<Json<Value>, ErrorData> {
let CompileTranscriptParams {
query,
transcript,
path,
token_budget,
project,
target_model,
policy,
segmentation,
} = params;
let transcript_text = self.resolve_transcript_text(transcript, path)?;
let segmentation_policy = segmentation.unwrap_or_default();
let (fragments, report) = segment_for_compilation(&transcript_text, &segmentation_policy)?;
let ids_as_strings = policy.as_ref().is_some_and(|p| p.ids_as_strings);
let request = CompileRequest {
query,
fragments,
project,
target_model,
token_budget,
memory_scope: None,
policy,
};
let service = Arc::clone(&self.service);
let compiled = tokio::task::spawn_blocking(move || {
service.run(|current| {
current.compile_context(&ContextCompiler::new(CompilePolicy::default()), &request)
})
})
.await
.map_err(join_error)?
.map_err(to_error)?;
let result = CompileTranscriptResult {
context: compiled,
segmentation: report,
};
Ok(Json(to_wire_value(&result, ids_as_strings)?))
}
#[tool(
name = "context_savings",
// Sans declaration explicite, rmcp derive un schema de sortie qui
// conserve des $ref qu'un client aveugle aux $defs ne resout pas —
// or les SDK MCP valident structuredContent contre ce schema.
output_schema = wire_safe_output_schema::<ContextSavings>(),
description = "Aggregate the token (and cost) savings of past compile_context calls, optionally per project. Figures are local estimates recorded per compilation (metadata only, never content); `truncated` reports when the sweep hit the recall cap."
)]
async fn context_savings(
&self,
Parameters(params): Parameters<ContextSavingsParams>,
) -> Result<Json<ContextSavings>, ErrorData> {
let service = Arc::clone(&self.service);
let savings = tokio::task::spawn_blocking(move || {
service.run(|current| current.context_savings(params.project.as_deref()))
})
.await
.map_err(join_error)?
.map_err(to_error)?;
Ok(Json(savings))
}
#[tool(
name = "explain_compilation",
description = "Explain why one fragment of a compile_context request was preserved, abstracted, externalized, dropped, or cached. Compilation is deterministic, so the request is re-compiled (with event/source recording off) and the fragment's exact decision (rule id, reason, relevance, risk, handle) is returned — no server-side state needed. Caveat: with a memory_scope the re-compile recalls from CURRENT memory, so decisions about pulled memories reflect the memory as it is now, not as it was; a `path` fragment is likewise re-read from disk, so the decision reflects the file's CURRENT content, not necessarily what the original compile_context call saw. Pass `fragment_index` (0-based position in request.fragments) instead of relying on `fragment_id` alone when fragments are byte-identical — a shared content-addressed id otherwise always resolves to the deduplication survivor's decision. `policy.ids_as_strings` on the request rewrites the response's id fields into decimal strings, like compile_context.",
input_schema = wire_safe_input_schema::<ExplainCompilationParams>(&["id", "fragment_id"]),
output_schema = wire_safe_output_schema::<ContextDecision>()
)]
async fn explain_compilation(
&self,
Parameters(params): Parameters<ExplainCompilationParams>,
) -> Result<Json<Value>, ErrorData> {
let service = Arc::clone(&self.service);
let ExplainCompilationParams {
mut request,
fragment_id,
fragment_index,
} = params;
self.resolve_ingest(&mut request.fragments)?;
let ids_as_strings = request.policy.as_ref().is_some_and(|p| p.ids_as_strings);
// The selection logic itself (record-off recompile + select by
// index/id) lives in the memory bridge now, shared with the Node and
// Python bindings — this tool only resolves `path` ingestion (a
// server-config concern) and maps the result onto the wire.
let decision = tokio::task::spawn_blocking(move || {
service
.run(|current| current.explain_compilation(&request, fragment_id, fragment_index))
})
.await
.map_err(join_error)?
.map_err(to_error)?;
Ok(Json(to_wire_value(&decision, ids_as_strings)?))
}
#[tool(
name = "retrieve_context_source",
// Sans declaration explicite, rmcp derive un schema de sortie qui
// conserve des $ref qu'un client aveugle aux $defs ne resout pas —
// or les SDK MCP valident structuredContent contre ce schema.
output_schema = wire_safe_output_schema::<RetrieveContextSourceResult>(),
description = "Fetch back the exact original content behind a ctx://source/<hash> handle from a compiled context — what compile_context externalized or partially packed is recoverable, not lost."
)]
async fn retrieve_context_source(
&self,
Parameters(params): Parameters<RetrieveContextSourceParams>,
) -> Result<Json<RetrieveContextSourceResult>, ErrorData> {
let service = Arc::clone(&self.service);
let RetrieveContextSourceParams { handle } = params;
let lookup = handle.clone();
let source = tokio::task::spawn_blocking(move || {
service.run(|current| current.retrieve_context_source(&lookup))
})
.await
.map_err(join_error)?
.map_err(to_error)?;
Ok(Json(RetrieveContextSourceResult {
handle,
content: source.content,
media: source.media,
}))
}
#[tool(
name = "save_working_context",
// Sans declaration explicite, rmcp derive un schema de sortie qui
// conserve des $ref qu'un client aveugle aux $defs ne resout pas —
// or les SDK MCP valident structuredContent contre ce schema.
output_schema = wire_safe_output_schema::<SaveWorkingContextResult>(),
description = "Persist this session's distilled working state (goal, active constraints, verified facts, open hypotheses, decisions, exact evidence, pending actions) under a project + session id — so a LATER session (a fresh agent run, a new conversation, a resumed process) can pick up exactly where this one left off instead of re-deriving context from scratch. Call this near the end of a session, or whenever the working state changes meaningfully. Saving again under the same project+session replaces the previous state (idempotent upsert) — so an entirely empty `working` is REFUSED rather than allowed to wipe what a previous save stored; fill at least one field. Serialized size is capped at 1 MiB. Returns the stored fact's id. IF THIS CALL TIMES OUT, THE SAVE MAY NOT HAVE HAPPENED — a timeout is not a slow success, and over the HTTP transport it usually means the request never reached this tool at all. Do not assume it was written: call `list_working_contexts` and check that this session's `saved_at` actually advanced, then re-send the identical call if it did not. Re-sending is safe — the write is an upsert on project + session, so it replaces rather than duplicates.",
input_schema = wire_safe_input_schema::<SaveWorkingContextParams>(&["fragment_id", "memory_id"])
)]
async fn save_working_context(
&self,
Parameters(params): Parameters<SaveWorkingContextParams>,
) -> Result<Json<SaveWorkingContextResult>, ErrorData> {
let service = Arc::clone(&self.service);
let SaveWorkingContextParams {
project,
session,
working,
} = params;
let id = tokio::task::spawn_blocking(move || {
service.run(|current| current.save_working_context(&project, &session, &working))
})
.await
.map_err(join_error)?
.map_err(to_error)?;
Ok(Json(SaveWorkingContextResult {
id,
id_str: id.to_string(),
}))
}
#[tool(
name = "load_working_context",
// Sans declaration explicite, rmcp derive un schema de sortie qui
// conserve des $ref qu'un client aveugle aux $defs ne resout pas —
// or les SDK MCP valident structuredContent contre ce schema.
output_schema = wire_safe_output_schema::<LoadedWorkingContext>(),
description = "Resume a session: load back the working context previously saved by save_working_context under the same project + session id — the goal, constraints, verified facts, open hypotheses, decisions, exact evidence, and pending actions a PRIOR session left off with. Call this at the START of a new session before doing anything else, so work continues instead of restarting. `found: false` (with `working: null`) means nothing was ever saved under that exact project + session — not an error, but check `other_sessions`: if it lists a similarly-named session, `session` was likely a typo, not a genuinely fresh start. `other_sessions` is always filled in, on a hit too: if it lists a session that looks more like the one you meant, you may have just resumed the WRONG session. Use `list_working_contexts` to browse a project's sessions up front."
)]
async fn load_working_context(
&self,
Parameters(params): Parameters<LoadWorkingContextParams>,
) -> Result<Json<Value>, ErrorData> {
let LoadWorkingContextParams { project, session } = params;
let service = Arc::clone(&self.service);
// L'enveloppe entiere — `found`, `working`, `other_sessions` — est
// composee par le pont, pas ici : les deux regles de politique
// ("lister meme sur un hit", "ne jamais reemettre la session
// demandee") sont les memes pour cet outil et pour les trois
// bindings, et une regle recopiee par surface diverge en silence.
let loaded = tokio::task::spawn_blocking(move || {
service.run(|current| current.resume_working_context(&project, &session))
})
.await
.map_err(join_error)?
.map_err(to_error)?;
// Les ids sortent en CHAINE decimale, sans option, contrairement au
// compilateur ou `ids_as_strings` est un choix de l'appelant.
//
// Ici il n'y a pas de choix a offrir : cet outil est la moitie
// LECTURE d'un aller-retour dont la moitie ECRITURE
// (`save_working_context`) n'annonce plus qu'une forme, la chaine —
// depuis que le schema d'entree ne peut plus publier d'union. Rendre
// un nombre la ou le jumeau n'accepte qu'une chaine oblige le client
// a convertir ; et sur un client JSON a nombres flottants, la valeur
// est deja arrondie a la LECTURE, donc il reecrit un id faux avec
// l'exactitude apparente d'une chaine. Un contexte de travail existe
// pour survivre a une perte de contexte : sa trace de provenance ne
// peut pas se rompre en silence entre deux sessions.
//
// Le schema de sortie annonce deja `["integer", "string"]` sur ces
// champs (`widen_id_properties`), donc emettre la branche chaine est
// valide au sens du schema publie : aucun SDK ne rejette la reponse.
let mut value = serde_json::to_value(loaded).map_err(|err| {
ErrorData::internal_error(
format!("Failed to serialize structured content: {err}"),
None,
)
})?;
stringify_id_fields(&mut value);
Ok(Json(value))
}
#[tool(
name = "list_working_contexts",
// Same reason as the four tools wired in `mcp.rs`: an rmcp-derived
// output schema keeps `$ref`s a `$defs`-blind client cannot resolve.
output_schema = wire_safe_output_schema::<ListWorkingContextsResult>(),
description = "List every session saved under a project via save_working_context, most-recently-saved first — so an agent can discover what is resumable before guessing a session id at load_working_context, or recover from a typo. Empty (not an error) when the project never saved anything."
)]
async fn list_working_contexts(
&self,
Parameters(params): Parameters<ListWorkingContextsParams>,
) -> Result<Json<ListWorkingContextsResult>, ErrorData> {
let service = Arc::clone(&self.service);
let ListWorkingContextsParams { project } = params;
let sessions = tokio::task::spawn_blocking(move || {
service.run(|current| current.list_working_contexts(&project))
})
.await
.map_err(join_error)?
.map_err(to_error)?;
Ok(Json(ListWorkingContextsResult { sessions }))
}
#[tool(
name = "suggest_budget",
// Sans declaration explicite, rmcp derive un schema de sortie qui
// conserve des $ref qu'un client aveugle aux $defs ne resout pas —
// or les SDK MCP valident structuredContent contre ce schema.
output_schema = wire_safe_output_schema::<SuggestedBudget>(),
description = "Suggest a starting token_budget for compile_context, for a named target model — looked up in a static, committed model-name to context-window table (dated \"as of\", NEVER a network call). Pass `reserve_tokens` (default 0) to reserve room for the response, mirroring compile_context's own `policy.response_reserve_tokens`. `window`/`suggested_budget` come back null when the model is not in the table — an honest \"unknown\", never a guess; extend the table in a new release instead of relying on this for an unlisted model."
)]
async fn suggest_budget(
&self,
Parameters(params): Parameters<SuggestBudgetParams>,
) -> Result<Json<SuggestedBudget>, ErrorData> {
let SuggestBudgetParams {
target_model,
reserve_tokens,
} = params;
Ok(Json(suggest_token_budget(
&target_model,
reserve_tokens.unwrap_or(0),
)))
}
}
#[cfg(test)]
#[path = "context_tools_tests.rs"]
mod tests;