diff --git a/.github/workflows/bench-results-untracked.yml b/.github/workflows/bench-results-untracked.yml new file mode 100644 index 000000000..fa6288a46 --- /dev/null +++ b/.github/workflows/bench-results-untracked.yml @@ -0,0 +1,40 @@ +name: Bench Results Untracked + +# SC-011 / Spec 065 CN-003: benchmark reports are published as CI artifacts and +# Cloudflare Pages deployments, never committed. bench/results/ is gitignored, +# but .gitignore does not protect a file that is ALREADY tracked (a `git add -f`, +# a rename into the directory, or an ignore rule added after the fact), so the +# rule needs a check that runs on every pull request. +# +# It deliberately does not live in bench.yml: that workflow triggers only on v* +# tags and workflow_dispatch, so it can never block the PR that adds a report. + +on: + pull_request: + +permissions: + contents: read + +jobs: + no-tracked-reports: + name: No benchmark report is tracked + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + # `git ls-files`, NOT `git status --porcelain`: porcelain omits ignored + # files, so it would stay silent about exactly the failure this guards โ€” + # a report that is tracked in the index while bench/results/ is ignored. + - name: Assert no report is tracked under bench/results + run: | + tracked="$(git ls-files bench/results)" + if [ -n "$tracked" ]; then + echo "::error::Benchmark reports must never be committed (SC-011, Spec 065 CN-003)." + echo "The following files are tracked under bench/results/:" + echo "$tracked" + echo "" + echo "To fix: git rm --cached and keep bench/results/ gitignored." + echo "Reports are published as CI artifacts and Cloudflare Pages deployments instead." + fi + test -z "$(git ls-files bench/results)" diff --git a/.github/workflows/bench.yml b/.github/workflows/bench.yml index 2f7be7dd9..e88ac18a9 100644 --- a/.github/workflows/bench.yml +++ b/.github/workflows/bench.yml @@ -58,6 +58,30 @@ jobs: - name: Set up uv (uvx-launched MCP reference servers) uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + # tiktoken (bench/tokens.go) fetches its BPE vocabulary from a remote host + # the first time an encoding is loaded, unless TIKTOKEN_CACHE_DIR points at + # a directory that already holds it. Naming the directory does not fill it, + # so the restore below is the half that actually buys offline reproduction: + # on a hit the vocabulary is on disk before the first bench run, on a miss + # the run fetches it once and the post-job save publishes it for next time. + # Kept under RUNNER_TEMP so the vocabulary never lands in the working tree + # that Cloudflare Pages publishes. + - name: Configure tiktoken vocabulary cache + run: | + mkdir -p "$RUNNER_TEMP/tiktoken" + echo "TIKTOKEN_CACHE_DIR=$RUNNER_TEMP/tiktoken" >> "$GITHUB_ENV" + + # Keyed on bench/tokens.go because that file pins the encoding name + # (DefaultEncoding = cl100k_base); the prefix restore-key still serves an + # unrelated edit to that file, at worst re-fetching one vocabulary. + - name: Restore tiktoken vocabulary cache + uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: ${{ runner.temp }}/tiktoken + key: ${{ runner.os }}-tiktoken-${{ hashFiles('bench/tokens.go') }} + restore-keys: | + ${{ runner.os }}-tiktoken- + - name: Build mcpproxy (personal edition) run: go build -o mcpproxy ./cmd/mcpproxy @@ -249,6 +273,22 @@ jobs: - name: Set up uv (ToolRet parquet fetch) uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + # Same tiktoken vocabulary cache as the dashboard job above (this job also + # runs the bench binary, so it needs the vocabulary on disk); see there for + # why naming the directory is not enough on its own. + - name: Configure tiktoken vocabulary cache + run: | + mkdir -p "$RUNNER_TEMP/tiktoken" + echo "TIKTOKEN_CACHE_DIR=$RUNNER_TEMP/tiktoken" >> "$GITHUB_ENV" + + - name: Restore tiktoken vocabulary cache + uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: ${{ runner.temp }}/tiktoken + key: ${{ runner.os }}-tiktoken-${{ hashFiles('bench/tokens.go') }} + restore-keys: | + ${{ runner.os }}-tiktoken- + # Pinned HF revisions live inside the script; bumping a pin is a # reviewed event. Cache lands in bench/results/cache/toolret//. - name: Fetch ToolRet at pinned revisions diff --git a/ROADMAP.md b/ROADMAP.md index 3a15f6fd3..8bb2da01a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -65,8 +65,8 @@ graph LR classDef in_progress fill:#1f6feb,stroke:#0b3d91,color:#ffffff; classDef todo fill:#6e7781,stroke:#3d4248,color:#ffffff; class sandbox_isolation,scanner_v2,analytics_dashboard,scanner_simplification,schema_deferred done; - class ux_audit,action_log_transparency,telemetry_identity,telemetry_v7_churn in_progress; - class tpa_db,remote_access_tunnel,token_bench,tool_graph todo; + class ux_audit,action_log_transparency,token_bench,telemetry_identity,telemetry_v7_churn in_progress; + class tpa_db,remote_access_tunnel,tool_graph todo; ``` **Independent epics** (15) โ€” no cross-epic prerequisites; each stands alone: @@ -198,6 +198,38 @@ graph LR +
+๐Ÿ”ต Token-efficiency benchmark: measured savings, published results โ€” In progress ยท P1 + +> Measure the real token cost of every routing/savings mode combination โ€” baseline, compact signatures (spec 085), deferred schemas (spec 102), optimistic calling via self-healing pre-dispatch validation, code_execution (spec 096) and stored scripts (spec 097) โ€” on replayed real sessions and on public benchmarks, then publish the results on mcpproxy.app/blog. Every savings number we quote today is an estimate; this turns them into reproducible measurements. Sequenced after schema-deferred so the newest mode is in the matrix. Spec 103 landed 2026-08-31 (#1137 spec+plan, #1139 tasks) after 13 cross-model review rounds; three of its findings changed the design rather than the wording: a recording carries no prompt/conversation/completion oracle so replay CANNOT show agent behaviour (US1 deterministic cost vs US2 live loop are now separate stories); replay needs a FLEET INPUT because the export has no fleet snapshot; and bodies-off yields menu costs plus one cross-mode delta, never an absolute workload cost. The matrix is 5 distinct behaviours, not a 3x2x2 product. + +Spec: [103-token-bench](./specs/103-token-bench/) ยท PR: #1141 + +```mermaid +graph LR + token_bench_harness["Replay harness: activity-log sessions re-runโ€ฆ"] + token_bench_public["Run public suites locally (ฯ„-bench / BFCL / Mโ€ฆ"] + token_bench_blog["Publish results + methodology on mcpproxy.appโ€ฆ"] + token_bench_telemetry["Heartbeat v10: per-tool_response_mode token cโ€ฆ"] + + token_bench_harness --> token_bench_public + token_bench_public --> token_bench_blog + + classDef in_progress fill:#1f6feb,stroke:#0b3d91,color:#ffffff; + classDef todo fill:#6e7781,stroke:#3d4248,color:#ffffff; + class token_bench_harness in_progress; + class token_bench_public,token_bench_blog,token_bench_telemetry todo; +``` + +| Task | Status | Refs | +| --- | --- | --- | +| Replay harness: activity-log sessions re-run under each mode combo; tokens per completed task + first-call success + retries | ๐Ÿ”ต In progress | #1141 | +| Run public suites locally (ฯ„-bench / BFCL / MCP-specific โ€” final list verified by a research pass) and record reproducible results | โšช Todo | โ€” | +| Publish results + methodology on mcpproxy.app/blog | โšช Todo | โ€” | +| Heartbeat v10: per-tool_response_mode token counters for real-world cohort validation | โšช Todo | โ€” | + +
+
๐Ÿ”ต Telemetry identity & data quality (machine_id + CI-filter hardening) โ€” In progress ยท P1 @@ -349,36 +381,6 @@ graph LR
-
-โšช Token-efficiency benchmark: measured savings, published results โ€” Todo ยท P1 - -> Measure the real token cost of every routing/savings mode combination โ€” baseline, compact signatures (spec 085), deferred schemas (spec 102), optimistic calling via self-healing pre-dispatch validation, code_execution (spec 096) and stored scripts (spec 097) โ€” on replayed real sessions and on public benchmarks, then publish the results on mcpproxy.app/blog. Every savings number we quote today is an estimate; this turns them into reproducible measurements. Sequenced after schema-deferred so the newest mode is in the matrix. Spec 103 landed 2026-08-31 (#1137 spec+plan, #1139 tasks) after 13 cross-model review rounds; three of its findings changed the design rather than the wording: a recording carries no prompt/conversation/completion oracle so replay CANNOT show agent behaviour (US1 deterministic cost vs US2 live loop are now separate stories); replay needs a FLEET INPUT because the export has no fleet snapshot; and bodies-off yields menu costs plus one cross-mode delta, never an absolute workload cost. The matrix is 5 distinct behaviours, not a 3x2x2 product. - -Spec: [103-token-bench](./specs/103-token-bench/) - -```mermaid -graph LR - token_bench_harness["Replay harness: activity-log sessions re-runโ€ฆ"] - token_bench_public["Run public suites locally (ฯ„-bench / BFCL / Mโ€ฆ"] - token_bench_blog["Publish results + methodology on mcpproxy.appโ€ฆ"] - token_bench_telemetry["Heartbeat v10: per-tool_response_mode token cโ€ฆ"] - - token_bench_harness --> token_bench_public - token_bench_public --> token_bench_blog - - classDef todo fill:#6e7781,stroke:#3d4248,color:#ffffff; - class token_bench_harness,token_bench_public,token_bench_blog,token_bench_telemetry todo; -``` - -| Task | Status | Refs | -| --- | --- | --- | -| Replay harness: activity-log sessions re-run under each mode combo; tokens per completed task + first-call success + retries | โšช Todo | โ€” | -| Run public suites locally (ฯ„-bench / BFCL / MCP-specific โ€” final list verified by a research pass) and record reproducible results | โšช Todo | โ€” | -| Publish results + methodology on mcpproxy.app/blog | โšช Todo | โ€” | -| Heartbeat v10: per-tool_response_mode token counters for real-world cohort validation | โšช Todo | โ€” | - -
-
โšช Windows native tray app โ€” Todo ยท P2 ยท MCP-43 @@ -770,12 +772,12 @@ graph LR | Web UI + macOS app UX audit | In progress | P0 | โ€” | | | | Release qualification gate (auto-QA matrix blocks the tag) | In progress | P0 | โ€” | [081-release-qa-gate](./specs/081-release-qa-gate/) | | | Action log / transparency โ€” info at a glance | In progress | P1 | โ€” | | | +| Token-efficiency benchmark: measured savings, published results | In progress | P1 | 33/64 (52%) | [103-token-bench](./specs/103-token-bench/) | #1141 | | Telemetry identity & data quality (machine_id + CI-filter hardening) | In progress | P1 | โ€” | | | | Telemetry v7: honest funnel + churn instrumentation | In progress | P1 | โ€” | [080-telemetry-v7-churn](./specs/080-telemetry-v7-churn/) | | | Planning/docs truth automation | In progress | P2 | โ€” | | | | Discovery-quality eval harness (Spec 065 second half) | In progress | P3 | โ€” | [065-evaluation-foundation](./specs/065-evaluation-foundation/) | | | tpa-db: versioned TPA signature database for the offline scanner | Todo | P1 | โ€” | [101-tpa-db](./specs/101-tpa-db/) | | -| Token-efficiency benchmark: measured savings, published results | Todo | P1 | 0/64 (0%) | [103-token-bench](./specs/103-token-bench/) | | | Windows native tray app `MCP-43` | Todo | P2 | โ€” | | | | Remote access tunnel (feature-flagged MVP, spec 089) | Todo | P2 | โ€” | [089-remote-access-tunnel](./specs/089-remote-access-tunnel/) | | | Tool co-occurrence graph (experimental, feature-flagged) | Todo | P2 | โ€” | | | @@ -912,4 +914,4 @@ Legend: `shipped` โ‰ฅ95% checked ยท `in-flight` 1โ€“94% ยท `drafted` 0% ยท `โ€”` | [100-prompt-rugpull-baseline](./specs/100-prompt-rugpull-baseline/) | โ€” | โ€” | | [101-tpa-db](./specs/101-tpa-db/) | โ€” | โ€” | | [102-schema-deferred](./specs/102-schema-deferred/) | `shipped` | 89/89 (100%) | -| [103-token-bench](./specs/103-token-bench/) | `drafted` | 0/64 (0%) | +| [103-token-bench](./specs/103-token-bench/) | `in-flight` | 33/64 (52%) | diff --git a/bench/README.md b/bench/README.md index 36f958486..4bb7bafb9 100644 --- a/bench/README.md +++ b/bench/README.md @@ -325,6 +325,160 @@ flip-gate metrics under `flip_gates` in `live_report.json` (FR-018): go run ./bench/cmd/bench -live -flip-gates -proxy http://127.0.0.1:8092 -api-key eval-corpus-snapshot ``` +## Real-workload replay + agent loop (Spec 103) + +Everything above scores a **frozen corpus**. Spec 103 adds the two entry points +that score a **real workload**: a deterministic *replay* of recorded activity +(no model spend, US1) and a live *agent loop* under a pinned model (US2). The +replay entry point lands with US1; the agent loop is gated on an operator +decision (pinned model + spend ceiling) and is tracked under "not yet built" +below until that is made. + +Both cross the **five-cell mode matrix** โ€” `retrieve_full`, `retrieve_compact`, +`direct_full`, `direct_deferred`, `code_exec`. The three axes (routing mode ร— +response mode ร— schema detail) have twelve combinations, but only five are +distinct behaviours; the other seven are configurable, redundant, and reported +as skip rows naming the cell they collapse onto. + +### Replay โ€” recompute a recorded workload (deterministic, no model spend) + +**1. Export a real workload**, from a machine that has been using mcpproxy for +real work: + +```bash +mcpproxy activity export --format json > ~/replay-corpus.jsonl +``` + +CSV is not a valid input: it drops `work_session_id`, the byte fields and the +call arguments, so it can neither group units of work nor account tokens. + +**2. Recompute across the matrix. A fleet input is MANDATORY** โ€” a menu cost is +a property of the tool definitions the agent was shown, and the activity export +carries no fleet snapshot. The recording contributes the *call shape* (sequence, +tool mix, call counts); it does not contribute fleet size. A recording-only +invocation is a **hard error, not a degraded run**. + +```bash +# Frozen fleet (reproducible): +go run ./bench/cmd/bench \ + -replay ~/replay-corpus.jsonl \ + -corpus-v2 specs/083-discovery-profiler/datasets/corpus_v2.tools.json \ + -out bench/results + +# ...or read today's fleet from a live proxy instead: +go run ./bench/cmd/bench -replay ~/replay-corpus.jsonl \ + -proxy http://127.0.0.1:8092 -api-key "$KEY" -out bench/results +``` + +Either way the workload is scored against the **supplied** fleet, not the fleet +as it stood when the session was recorded. That is internally valid across cells +and is *not* a historical reconstruction โ€” the report says so on every figure. + +**3. Bodies-off is the DEFAULT, and it decides which figures exist.** The export +path does not mask (masking is wired into the list and detail handlers only), so +a bodies-on export is raw and unmasked by design. Bodies-on is therefore a +separate, explicit opt-in that prints a warning, and content is tokenized inside +the loader โ€” only counts cross the boundary, never text. + +| | bodies-off (default) | bodies-on (opt-in) | +|---|---|---| +| Menu cost, all five cells | **measured** (from the fleet input) | measured | +| Absolute complete-workload cost | **unavailable for every cell** โ€” reported unavailable, never as zero | measurable where bodies survive | +| `direct_full` vs `direct_deferred` delta | **measured** โ€” their call responses are identical and cancel | measured | +| `retrieve_full` / `retrieve_compact` / `code_exec` deltas | unavailable โ€” the mode changes the response body itself | measured | +| Response cost generally | `estimated` at best (`request_bytes`/`response_bytes` are **byte lengths**, not token counts) | measured | + +**4. Read the exclusion report before the headline.** Truncated, +bodies-missing, sensitive and unreplayable records are each detected and +**counted**; a truncated record never contributes silently. A corpus that is 80% +truncated yields a real number over a small slice, and the report says so. +Two caveats worth internalizing: `has_sensitive_data` is derived from detection +metadata added *asynchronously* after persistence, so exclude-by-flag is a +best-effort reducer and never a guarantee; and the activity log stores the FULL +pre-truncation `retrieve_tools` response while the agent consumed truncated +text, so a truncated record tokenized as-is **overstates** cost. + +**5. Verify determinism** (SC-002) โ€” two runs are byte-identical once the +wall-clock stamp is removed: + +```bash +CORPUS=specs/083-discovery-profiler/datasets/corpus_v2.tools.json +go run ./bench/cmd/bench -replay ~/replay-corpus.jsonl -corpus-v2 $CORPUS -out /tmp/run-a +go run ./bench/cmd/bench -replay ~/replay-corpus.jsonl -corpus-v2 $CORPUS -out /tmp/run-b +diff <(jq 'del(.generated_at)' /tmp/run-a/report.json) \ + <(jq 'del(.generated_at)' /tmp/run-b/report.json) \ + && echo "byte-identical modulo generated_at (SC-002)" +``` + +**6. Delete the input when you are finished.** + +```bash +rm -f ~/replay-corpus.jsonl +``` + +A replay input is raw user traffic. Keep it **outside the repository**, never +commit it, and delete it when the run is done โ€” it is gitignored nowhere +precisely because it should never be inside the repo in the first place. + +### Agent loop โ€” tokens per *completed* task (costs model spend) + +The replay half is a **counterfactual** over recorded traffic: what the same +call shape would have cost per cell. It is not observed agent behaviour, and no +replay figure may be published without that label. The agent loop is the half +that observes behaviour, and it is the only part that costs spend. + +- **One instance, whole matrix.** All three routing-mode servers are mounted at + startup, so a cell is selected by **endpoint URL**; only the two serialization + axes need config, and both hot-reload. Enable code execution if `code_exec` is + in scope โ€” without it that cell is degenerate and is skipped with a reason. +- **Stand up the full fleet**, even when running one service's tasks. A single + server's toolset is too small a fleet for proxy modes to differ from baseline, + and the full fleet is also the honest **baseline arm**: same agent, same + tasks, all tools loaded directly. +- **k โ‰ฅ 4 runs per cell.** A single agentic run is noise; every + model-dependent figure is an average over at least four runs with its spread, + or it is not a headline. +- **Four figures per cell**: tokens per completed task, completion rate, + first-attempt success and retry rate. The retry classification rule + (corrective vs infrastructure) must be applied **identically to the baseline + arm and the proxy arms**, or the comparison is biased toward whichever arm + carries richer error signal. +- **Accounting sources are never summed.** Deterministic figures come from the + local tiktoken estimator; live figures come from provider-reported usage. A + cross-source aggregate is withheld with a stated reason instead โ€” and a mode + that costs less while completing less is marked a **regression**, whatever its + token figure says. + +### Offline prerequisite (both halves) + +`tiktoken` downloads its vocabulary on first use unless the cache directory is +both named **and populated**: + +```bash +export TIKTOKEN_CACHE_DIR="$HOME/.cache/tiktoken" +go run ./bench/cmd/bench -corpus-v2 specs/083-discovery-profiler/datasets/corpus_v2.tools.json \ + -out /tmp/warm # warms the cache; needs network exactly once +``` + +Setting the variable only *names* a cache; it does not fill one. A genuinely +offline reproduction needs the cache pre-populated โ€” warm it once with network +access, or restore a known-good copy (which is what `.github/workflows/bench.yml` +does via its `actions/cache` step). + +### Before publishing a replay or agent-loop number + +1. Recompute the achievable ceiling **for each fleet shape**; never carry a + previous fleet's ceiling forward. +2. Quote the fleet shape beside every percentage. +3. Confirm no report is tracked: + ```bash + test -z "$(git ls-files bench/results)" && echo "clean (SC-011)" + ``` + Use `git ls-files`, **not** `git status --porcelain` โ€” porcelain does not + list ignored files and would stay silent about an already-tracked report. + `.github/workflows/bench-results-untracked.yml` runs this same assertion on + every pull request. + ## What is scoped but not yet built (follow-ups) These require decisions and/or other roles, so they are tracked as child issues diff --git a/bench/cmd/bench/main.go b/bench/cmd/bench/main.go index 01a44cca9..5d951bfea 100644 --- a/bench/cmd/bench/main.go +++ b/bench/cmd/bench/main.go @@ -28,6 +28,18 @@ // full-menu count (joined to live tools by id โ€” GET /api/v1/tools can serve // stub schemas), and -expected-tools surfaces corpus drift (FR-021). // +// Replay mode (Spec 103 US1) recomputes cost over a REAL recorded workload: +// an activity export plus a MANDATORY fleet input, deterministic, no model +// spend: +// +// go run ./bench/cmd/bench -replay /path/outside/the/repo/activity.jsonl \ +// -corpus-v2 specs/083-discovery-profiler/datasets/corpus_v2.tools.json -out bench/results +// +// The fleet input is not optional. A menu is a property of the tool +// definitions and the activity export carries no fleet snapshot, so a +// recording on its own computes nothing โ€” `-replay` without `-corpus-v2` or +// `-livemcptool` is an error, not a degraded run. +// // A LAP lint artifact (`uvx --from lap-score==0.8.0 lap lint --json`) merges // into either report via -lap-json. Reports land in bench/results/ // (gitignored โ€” reports are never committed, per the Spec 065 CN-003 rule). @@ -47,6 +59,7 @@ import ( "github.com/smart-mcp-proxy/mcpproxy-go/bench" "github.com/smart-mcp-proxy/mcpproxy-go/bench/arms" "github.com/smart-mcp-proxy/mcpproxy-go/bench/corpusio" + "github.com/smart-mcp-proxy/mcpproxy-go/bench/replaycorpus" ) // toonResultsArmName is the pseudo-arm selectable via -arms: fixture-driven @@ -73,8 +86,25 @@ func main() { lapJSON := flag.String("lap-json", "", "path to a LAP lint artifact (lap.json) to merge as the independent verdict") resultFixtures := flag.String("result-fixtures", "specs/083-discovery-profiler/datasets/result_fixtures_v1.json", "tool-result fixture set for the toon_results arm") expectedTools := flag.Int("expected-tools", 0, "live mode: expected upstream tool count (from the frozen corpus); a differing live catalog is surfaced as a corpus-drift warning (FR-021)") + + // Spec 103 US1 replay flags (T028). The fleet input is supplied through + // the EXISTING corpus flags (-corpus-v2 / -livemcptool) rather than a new + // one: a replay fleet is a tool corpus, and a second way to name one would + // be a second loader to keep honest. + replayPath := flag.String("replay", "", "path to an activity JSONL export (mcpproxy activity export --format json) to recompute cost over; REQUIRES a fleet input (-corpus-v2 or -livemcptool) โ€” a recording alone computes nothing. The file must live OUTSIDE this repository and is never committed") + replayBodies := flag.Bool("replay-bodies-on-unmasked", false, "replay: read recorded request/response bodies. OFF by default. The activity export path does NOT mask, so this reads raw unmasked user traffic; bodies are tokenized inside the loader and only counts leave it") flag.Parse() + // -live and -replay are different measurements over different inputs, and + // -live is checked first. Accepting both would silently run live mode and + // discard -replay with no output and no warning โ€” a benchmark that quietly + // measures something other than what was asked for is worse than one that + // refuses, so refuse. + if *live && *replayPath != "" { + fmt.Fprintln(os.Stderr, "error: -live and -replay are mutually exclusive; -live measures a running proxy, -replay recomputes cost over a recording. Pick one.") + os.Exit(2) + } + if *live { // In live mode -corpus-v2 is the schema SOURCE for the naive // full-menu count (GET /api/v1/tools can serve stub schemas). @@ -90,6 +120,21 @@ func main() { }) return } + // Replay is checked BEFORE the profiler branch: it consumes -corpus-v2 as + // its fleet input, so the profiler check would otherwise swallow the run. + // It is a top-level branch rather than an OfflineSection because replay + // crosses the mode matrix โ€” it is not one more corpus. + if *replayPath != "" { + runReplay(replayCLIOptions{ + recording: *replayPath, + bodiesOn: *replayBodies, + encoding: *encoding, + outDir: *outDir, + corpusV2Path: *corpusV2Path, + livemcptoolPath: *livemcptoolPath, + }) + return + } if *armsFlag != "" || *corpusV2Path != "" || *toolretDir != "" || *livemcptoolPath != "" { runProfiler(profilerOptions{ encoding: *encoding, @@ -421,6 +466,138 @@ func printArmRows(r *bench.ReportV2) { } } +// replayCLIOptions carries the Spec 103 replay flag values. +type replayCLIOptions struct { + recording string + bodiesOn bool + encoding string + outDir string + corpusV2Path string + livemcptoolPath string +} + +// runReplay is the Spec 103 US1 entry point: recompute per-cell menu cost and +// the direct-cell cross-mode delta over a real recorded workload. +// +// The fleet input is loaded here, but the RULE that one is required lives in +// bench.RunReplay, which returns ErrReplayFleetRequired for a nil fleet. That +// keeps one statement of the rule rather than two that can drift: the CLI +// merely reports it. +func runReplay(opts replayCLIOptions) { + tk, err := bench.NewTokenizer(opts.encoding) + if err != nil { + log.Fatalf("bench: %v", err) + } + + fleet, fleetID := loadReplayFleet(opts.corpusV2Path, opts.livemcptoolPath) + + // Resolve exactly the arms the matrix needs to price a menu. A missing arm + // is fatal rather than a skipped row: an absent cell reads as "not + // applicable" when the truth would be "we could not measure it". + armsByName := make(map[string]bench.EncodingArm) + for _, name := range bench.ReplayArmNames() { + arm, rerr := arms.Resolve(name) + if rerr != nil { + log.Fatalf("bench: replay needs the %q arm to price a mode cell's menu: %v", name, rerr) + } + armsByName[name] = arm + } + + bodies := replaycorpus.BodiesOff + if opts.bodiesOn { + bodies = replaycorpus.BodiesOnUnmasked + } + + block, err := bench.RunReplay(tk, bench.ReplayOptions{ + RecordingPath: opts.recording, + Fleet: fleet, + FleetID: fleetID, + Bodies: bodies, + Encoding: opts.encoding, + Arms: armsByName, + Warnf: func(format string, args ...any) { fmt.Fprintf(os.Stderr, "bench: "+format+"\n", args...) }, + }) + if err != nil { + log.Fatalf("bench: %v", err) + } + + report := bench.ReplayReport(tk, block) + if err := report.ValidateAdditiveBlocks(); err != nil { + log.Fatalf("bench: %v", err) + } + printReplay(block) + + jsonPath, htmlPath, err := report.WriteReports(opts.outDir) + if err != nil { + log.Fatalf("bench: %v", err) + } + fmt.Fprintf(os.Stdout, "wrote %s and %s\n", jsonPath, htmlPath) + fmt.Fprintf(os.Stderr, "bench: the replay input is raw recorded traffic โ€” delete %s when this run is finished\n", opts.recording) +} + +// loadReplayFleet resolves the fleet input from the existing corpus flags. +// +// Neither flag returns a nil fleet on purpose: the refusal belongs to +// bench.RunReplay, whose error explains WHY a recording alone computes +// nothing. Supplying both is refused here, because silently preferring one +// would make the reported fleet shape a coin toss. +func loadReplayFleet(corpusV2Path, livemcptoolPath string) (*bench.Corpus, string) { + if corpusV2Path != "" && livemcptoolPath != "" { + log.Fatalf("bench: replay takes ONE fleet input; -corpus-v2 and -livemcptool were both given, and every figure is quoted for exactly one fleet shape") + } + switch { + case corpusV2Path != "": + corpus, err := bench.LoadCorpusV2(corpusV2Path) + if err != nil { + log.Fatalf("bench: %v", err) + } + return corpus, corpus.Version + case livemcptoolPath != "": + snapshotPath := livemcptoolPath + if st, err := os.Stat(snapshotPath); err == nil && st.IsDir() { + snapshotPath = filepath.Join(snapshotPath, "tools.json") + } + corpus, _, _, err := corpusio.LoadLiveMCPTool(snapshotPath) + if err != nil { + log.Fatalf("bench: %v", err) + } + return corpus, corpus.Version + default: + return nil, "" + } +} + +// printReplay summarizes the block on stdout, EXCLUSIONS FIRST. +// +// The order is the point (FR-003, SC-008): a reader meets what did not count +// before they meet the headline, so a number computed over a third of the +// supplied sessions cannot be read as a number over all of them. The +// counterfactual label leads, for the same reason. +func printReplay(b *bench.ReplayBlock) { + fmt.Fprintf(os.Stdout, "mcpproxy replay (%s over the %s fleet, %d tools)\n", + b.AccountingSource.Identity, b.FleetShape.ID, b.FleetShape.ToolCount) + fmt.Fprintf(os.Stdout, " %s\n", b.Counterfactual) + fmt.Fprintf(os.Stdout, " sessions: %d supplied, %d used, bodies %s\n", + b.SessionsSupplied, b.SessionsUsed, map[bool]string{true: "ON (raw, unmasked)", false: "off"}[b.BodiesIncluded]) + if len(b.Exclusions) == 0 { + fmt.Fprintf(os.Stdout, " exclusions: none\n") + } + for _, ex := range b.Exclusions { + fmt.Fprintf(os.Stdout, " excluded/flagged %-14s %d\n", ex.Reason, ex.Sessions) + } + for _, cell := range b.Cells { + fmt.Fprintf(os.Stdout, " %-18s menu %7d tokens %d recorded calls [%s]\n", + cell.CellID, cell.MenuTokens, cell.Calls, cell.Provenance) + if cell.AbsoluteWorkloadWithheld { + fmt.Fprintf(os.Stdout, " absolute complete-workload cost WITHHELD: %s\n", cell.WithheldReason) + } + } + if d := b.DirectDelta; d != nil { + fmt.Fprintf(os.Stdout, " delta %s -> %s: %d tokens (%.1f%%) [%s]\n", + d.FromCellID, d.ToCellID, d.DeltaTokens, d.DeltaPct, d.Provenance) + } +} + // liveOptions carries the live-mode flag values. type liveOptions struct { proxy string diff --git a/bench/modematrix.go b/bench/modematrix.go new file mode 100644 index 000000000..0a58c2436 --- /dev/null +++ b/bench/modematrix.go @@ -0,0 +1,508 @@ +// modematrix.go โ€” the Spec 103 mode matrix +// (specs/103-token-bench/contracts/mode-matrix.md, FR-015/016/017). +// +// The matrix is what an agent actually sees, crossed over the three +// configuration axes that determine it: routing mode, discovery-surface +// serialization, and direct-surface serialization. The naive product is +// 3 x 2 x 2 = 12 combinations, but only 5 of them are distinct BEHAVIOURS โ€” +// on each surface one or both serialization axes have no consumer, so the +// other 7 configurations produce a run identical to one of the 5. +// +// Those 7 are the reason this file exists as data rather than as a loop. They +// are configurable and behaviourally redundant, NOT impossible: calling them +// impossible would be wrong, and rendering them as zeros would be worse, +// because a zero reads as "measured, and it cost nothing". Each is emitted as +// a skip row naming the cell it collapses onto and the reason code for the +// collapse (FR-017). +// +// This file composes; it does not reimplement. Cell tool catalogs come from +// ProxyToolsForMode (proxytools.go, itself derived from the production tool +// builders), the arm that renders a cell's menu is named for resolution +// through the existing bench/arms registry โ€” bench cannot import bench/arms, +// since arms imports bench โ€” and skip rows go through the existing +// SkippedArmResult constructor rather than a second skip shape. +package bench + +import ( + "fmt" + "strings" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" +) + +// Cell identifiers. These are a stability contract (FR-028): a report key that +// changed between releases would silently break comparability with every +// earlier run, so these strings are frozen even if the internal naming moves. +const ( + // CellBaseline is the FR-020 denominator, not an mcpproxy mode: the same + // agent doing the same tasks with every upstream tool loaded inline. + CellBaseline = "baseline" + // CellRetrieveFull is the default: retrieve_tools surface, schema-bearing + // discovery entries. + CellRetrieveFull = "retrieve_full" + // CellRetrieveCompact is the Spec 085 compact discovery serialization. + CellRetrieveCompact = "retrieve_compact" + // CellDirectFull is the direct enumeration surface with full schemas. + CellDirectFull = "direct_full" + // CellDirectDeferred is the Spec 102 deferred-schema direct surface. + CellDirectDeferred = "direct_deferred" + // CellCodeExec is the code-execution surface, which forces full discovery. + CellCodeExec = "code_exec" +) + +// Serialization-axis values. SerializationNotApplicable is deliberately its own +// value rather than an empty string or a default: contract rule 3 requires an +// ignored axis to be recorded as not-applicable, because recording it as +// "full" would imply a measurement of a serialization that was never in play. +const ( + SerializationFull = config.ToolResponseModeFull + SerializationCompact = config.ToolResponseModeCompact + SerializationDeferred = config.DirectToolResponseModeDeferred + SerializationNotApplicable = "not_applicable" +) + +// Skip reason codes (contract "The other 7 combinations" + "a degenerate +// configuration"). They are distinct because they describe different things: +// an axis with no consumer on that surface, a surface that actively overrides +// the axis, and a configuration in which the surface can discover tools and +// call none of them. +const ( + // SkipReasonAxisIgnored: the configured axis governs a different surface, + // so this combination runs identically to the cell it collapses onto. + SkipReasonAxisIgnored = "axis-ignored" + // SkipReasonForcedFull: the code-execution surface overwrites the response + // mode with full and blanks the detail parameter. An override, not an + // ignored axis, hence its own code. + SkipReasonForcedFull = "forced-full" + // SkipReasonDegenerate: code_execution with enable_code_execution:false. + // Not part of the product at all โ€” nothing is callable, so there is no + // behaviour to collapse onto. + SkipReasonDegenerate = "degenerate" +) + +// Capability identifiers (FR-016). These are binary conditions applied to the +// cells where each is available โ€” measure a cell with the condition on and +// with it off โ€” NOT a fourth axis of the product. +const ( + // CapabilityBatching is describe_tool's batch form (up to 5 ids in one + // call, Spec 085). Registered on the retrieve_tools surface and, since + // Spec 102, on the direct surface; deliberately absent from the + // code-execution surface, where a compact response would reference a + // second stage that does not exist there. + CapabilityBatching = "batching" + // CapabilityStoredScripts is Spec 097 stored-script execution, a + // code_execution feature with no analogue on the other surfaces. + CapabilityStoredScripts = "stored_scripts" + // CapabilityValidateBeforeDispatch is Spec 085 FR-013 pre-dispatch + // argument validation with its self-healing invalid_params error. It runs + // on the call_tool_* variants and, since Spec 102 US3, on direct dispatch; + // the code-execution surface dispatches from the sandbox and does not. + CapabilityValidateBeforeDispatch = "validate_before_dispatch" +) + +// Endpoint paths for the routing-mode axis. +// +// These are mounted permanently at startup and stay mounted regardless of +// config (internal/server/server.go, the "Routing mode dedicated endpoints" +// block): each endpoint always serves its own routing mode. That is what makes +// the routing axis free of config changes and restarts โ€” and it is why two +// cells that differ only in serialization legitimately share one URL. +const ( + EndpointRetrieveTools = "/mcp/call" + EndpointDirect = "/mcp/all" + EndpointCodeExec = "/mcp/code" +) + +// ModeCell is one point in the matrix: either one of the 5 distinct +// behaviours, the baseline denominator, or a skip row standing in for a +// configurable-but-redundant combination. +// +// A cell is (URL, serialization-config), NOT a URL alone. The routing axis is +// chosen by endpoint; the two serialization axes are config. Both of those +// hot-reload โ€” tool_response_mode is read from the live snapshot on every call +// and direct_tool_response_mode is rebuilt on config.reloaded โ€” so the whole +// matrix crosses on ONE long-lived proxy instance, with a config apply between +// serialization cells rather than a restart. +type ModeCell struct { + // ID is the stable report key (FR-028). + ID string `json:"id"` + // RoutingMode is the production routing-mode identifier + // (config.RoutingMode*). Empty for the baseline, which is served by no + // mcpproxy surface. + RoutingMode string `json:"routing_mode,omitempty"` + // Endpoint is the mounted path this cell is measured through. Empty for + // the baseline and for skip rows. + Endpoint string `json:"endpoint,omitempty"` + // DiscoverySerialization is full / compact / not-applicable. + DiscoverySerialization string `json:"discovery_serialization"` + // DirectSerialization is full / deferred / not-applicable. + DirectSerialization string `json:"direct_serialization"` + // Capabilities lists the FR-016 binary conditions available on this cell. + Capabilities []string `json:"capabilities,omitempty"` + // Skipped marks the configurable-but-redundant and degenerate rows. + Skipped bool `json:"skipped"` + // SkipReasonCodes holds one or more of the reason codes above. It is a + // slice because one combination genuinely carries two: + // code_execution x compact x deferred is forced-full AND axis-ignored. + SkipReasonCodes []string `json:"skip_reason_codes,omitempty"` + // CollapsesOnto names the valid cell a redundant combination runs + // identically to. Empty for valid cells and for the degenerate row, which + // collapses onto nothing. + CollapsesOnto string `json:"collapses_onto,omitempty"` +} + +// CapabilityCondition is one FR-016 binary toggle together with the cells it +// applies to. The enumeration is part of the contract: the report must say +// which rows a capability was measured on, so a reader never has to guess +// whether an absent figure means "off" or "not available here". +type CapabilityCondition struct { + ID string `json:"id"` + AppliesTo []string `json:"applies_to"` +} + +// Combination is a configured (routing mode, discovery serialization, direct +// serialization) triple plus the one config flag that can make the +// code-execution surface degenerate. It is what an operator can actually set; +// ResolveCombination maps it to the behaviour that would actually run. +type Combination struct { + RoutingMode string + ToolResponseMode string + DirectToolResponseMode string + EnableCodeExecution bool +} + +// modeCells is the frozen table of the 5 distinct behaviours, in contract-table +// order. Declared as a package-level value and copied out by ModeCells so a +// caller cannot mutate the matrix other runs are compared against. +var modeCells = []ModeCell{ + { + ID: CellRetrieveFull, + RoutingMode: ModeRetrieveTools, + Endpoint: EndpointRetrieveTools, + DiscoverySerialization: SerializationFull, + DirectSerialization: SerializationNotApplicable, + Capabilities: []string{CapabilityBatching, CapabilityValidateBeforeDispatch}, + }, + { + ID: CellRetrieveCompact, + RoutingMode: ModeRetrieveTools, + Endpoint: EndpointRetrieveTools, + DiscoverySerialization: SerializationCompact, + DirectSerialization: SerializationNotApplicable, + Capabilities: []string{CapabilityBatching, CapabilityValidateBeforeDispatch}, + }, + { + ID: CellDirectFull, + RoutingMode: config.RoutingModeDirect, + Endpoint: EndpointDirect, + DiscoverySerialization: SerializationNotApplicable, + DirectSerialization: SerializationFull, + Capabilities: []string{CapabilityBatching, CapabilityValidateBeforeDispatch}, + }, + { + ID: CellDirectDeferred, + RoutingMode: config.RoutingModeDirect, + Endpoint: EndpointDirect, + DiscoverySerialization: SerializationNotApplicable, + DirectSerialization: SerializationDeferred, + Capabilities: []string{CapabilityBatching, CapabilityValidateBeforeDispatch}, + }, + { + ID: CellCodeExec, + RoutingMode: ModeCodeExecution, + Endpoint: EndpointCodeExec, + // Full here is an OVERRIDE, not a default: the surface overwrites the + // response mode and does not expose the detail parameter at all. + DiscoverySerialization: SerializationFull, + DirectSerialization: SerializationNotApplicable, + Capabilities: []string{CapabilityStoredScripts}, + }, +} + +// baselineCell is the FR-020 denominator. It is kept OUT of modeCells because +// it is not an mcpproxy mode and must never be counted as one of the five: it +// is the same agent doing the same tasks with every upstream tool inline, and +// it is what every published percentage is measured against. +var baselineCell = ModeCell{ + ID: CellBaseline, + RoutingMode: ModeBaseline, + DiscoverySerialization: SerializationNotApplicable, + DirectSerialization: SerializationNotApplicable, +} + +// ModeCells returns the 5 distinct mcpproxy behaviours in contract order. +func ModeCells() []ModeCell { + out := make([]ModeCell, len(modeCells)) + for i, c := range modeCells { + out[i] = c.clone() + } + return out +} + +// BaselineCell returns the FR-020 denominator cell. +func BaselineCell() ModeCell { return baselineCell.clone() } + +// AllCells returns the baseline followed by the 5 mcpproxy cells โ€” the full +// row set a comparison report renders, denominator first. +func AllCells() []ModeCell { + return append([]ModeCell{BaselineCell()}, ModeCells()...) +} + +// CellByID looks up a valid cell (the baseline included) by its stable id. +// Skip rows are not addressable this way: they are outcomes of a +// configuration, not cells of the matrix. +func CellByID(id string) (ModeCell, bool) { + if id == CellBaseline { + return BaselineCell(), true + } + for _, c := range modeCells { + if c.ID == id { + return c.clone(), true + } + } + return ModeCell{}, false +} + +// clone deep-copies the mutable slice fields so callers cannot alias the +// package-level table. +func (c ModeCell) clone() ModeCell { + out := c + if c.Capabilities != nil { + out.Capabilities = append([]string(nil), c.Capabilities...) + } + if c.SkipReasonCodes != nil { + out.SkipReasonCodes = append([]string(nil), c.SkipReasonCodes...) + } + return out +} + +// redundantCombination is one row of the contract's collapse table. +type redundantCombination struct { + routingMode string + toolResponseMode string + directToolResponseMode string + collapsesOnto string + reasonCodes []string +} + +// redundantCombinations is the contract's collapse table verbatim: the 7 +// configurations of the 3-axis product that are configurable and redundant. +// +// The pattern behind the table, stated once so the rows are checkable rather +// than magic: tool_response_mode is resolved by effectiveToolResponseMode and +// consumed only by the retrieve_tools handler, so no other surface reads it; +// direct_tool_response_mode is resolved by effectiveDirectToolResponseMode and +// every one of its call sites concerns the direct listing, so no other surface +// reads it either; and the code-execution surface additionally overrides +// tool_response_mode to full outright. +var redundantCombinations = []redundantCombination{ + {ModeRetrieveTools, config.ToolResponseModeFull, config.DirectToolResponseModeDeferred, CellRetrieveFull, []string{SkipReasonAxisIgnored}}, + {ModeRetrieveTools, config.ToolResponseModeCompact, config.DirectToolResponseModeDeferred, CellRetrieveCompact, []string{SkipReasonAxisIgnored}}, + {config.RoutingModeDirect, config.ToolResponseModeCompact, config.DirectToolResponseModeFull, CellDirectFull, []string{SkipReasonAxisIgnored}}, + {config.RoutingModeDirect, config.ToolResponseModeCompact, config.DirectToolResponseModeDeferred, CellDirectDeferred, []string{SkipReasonAxisIgnored}}, + {ModeCodeExecution, config.ToolResponseModeCompact, config.DirectToolResponseModeFull, CellCodeExec, []string{SkipReasonForcedFull}}, + {ModeCodeExecution, config.ToolResponseModeFull, config.DirectToolResponseModeDeferred, CellCodeExec, []string{SkipReasonAxisIgnored}}, + {ModeCodeExecution, config.ToolResponseModeCompact, config.DirectToolResponseModeDeferred, CellCodeExec, []string{SkipReasonForcedFull, SkipReasonAxisIgnored}}, +} + +// validCombinations maps the 5 configurations that ARE the distinct behaviours +// to their cell ids. Together with redundantCombinations it covers all 12 +// points of the product exactly once. +var validCombinations = map[string]string{ + combinationKey(ModeRetrieveTools, config.ToolResponseModeFull, config.DirectToolResponseModeFull): CellRetrieveFull, + combinationKey(ModeRetrieveTools, config.ToolResponseModeCompact, config.DirectToolResponseModeFull): CellRetrieveCompact, + combinationKey(config.RoutingModeDirect, config.ToolResponseModeFull, config.DirectToolResponseModeFull): CellDirectFull, + combinationKey(config.RoutingModeDirect, config.ToolResponseModeFull, config.DirectToolResponseModeDeferred): CellDirectDeferred, + combinationKey(ModeCodeExecution, config.ToolResponseModeFull, config.DirectToolResponseModeFull): CellCodeExec, +} + +// combinationKey builds the stable identifier of one configured combination. +// It doubles as the id of the skip row a redundant combination produces, so a +// reader of the report can see exactly which configuration was collapsed. +func combinationKey(routingMode, toolResponseMode, directToolResponseMode string) string { + return routingMode + "+" + toolResponseMode + "+" + directToolResponseMode +} + +// degenerateCodeExecID is the id of the degenerate skip row. The serialization +// axes are deliberately absent from it: with the surface disabled nothing is +// callable, so no serialization choice can change the outcome and all such +// configurations are one degenerate behaviour, not four. +const degenerateCodeExecID = "code_execution+disabled" + +// RedundantCombinations returns the 7 skip rows of the collapse table, in +// contract order. They exist so the report can show that these configurations +// were considered and understood โ€” reported as skipped with a reason, never as +// a zero and never as a missing row (FR-017). +func RedundantCombinations() []ModeCell { + out := make([]ModeCell, 0, len(redundantCombinations)) + for _, rc := range redundantCombinations { + out = append(out, rc.cell()) + } + return out +} + +// cell renders one collapse-table row as a skip ModeCell. The configured +// serialization values are preserved verbatim rather than normalized to +// not-applicable: the point of the row is to record what the operator asked +// for and why it did not produce its own measurement. +func (rc redundantCombination) cell() ModeCell { + return ModeCell{ + ID: combinationKey(rc.routingMode, rc.toolResponseMode, rc.directToolResponseMode), + RoutingMode: rc.routingMode, + DiscoverySerialization: rc.toolResponseMode, + DirectSerialization: rc.directToolResponseMode, + Skipped: true, + SkipReasonCodes: append([]string(nil), rc.reasonCodes...), + CollapsesOnto: rc.collapsesOnto, + } +} + +// ResolveCombination maps a configured combination to the behaviour that would +// actually run: either one of the 5 distinct cells, or a skip row naming the +// cell it collapses onto (or, for the degenerate configuration, naming +// nothing, because there is nothing equivalent to collapse onto). +// +// An unrecognized combination โ€” an axis value that is not a production +// constant โ€” also yields a skip row rather than an error or a silent default, +// on the same principle: the matrix never invents a measurement it did not take. +func ResolveCombination(comb Combination) ModeCell { + // The degenerate verdict is checked FIRST and outranks redundancy. With + // enable_code_execution false the surface can discover tools and call none + // of them, so no serialization choice can make it equivalent to code_exec. + if comb.RoutingMode == ModeCodeExecution && !comb.EnableCodeExecution { + return ModeCell{ + ID: degenerateCodeExecID, + RoutingMode: comb.RoutingMode, + DiscoverySerialization: comb.ToolResponseMode, + DirectSerialization: comb.DirectToolResponseMode, + Skipped: true, + SkipReasonCodes: []string{SkipReasonDegenerate}, + } + } + + key := combinationKey(comb.RoutingMode, comb.ToolResponseMode, comb.DirectToolResponseMode) + if id, ok := validCombinations[key]; ok { + cell, found := CellByID(id) + if found { + return cell + } + } + for _, rc := range redundantCombinations { + if combinationKey(rc.routingMode, rc.toolResponseMode, rc.directToolResponseMode) == key { + return rc.cell() + } + } + + return ModeCell{ + ID: key, + RoutingMode: comb.RoutingMode, + DiscoverySerialization: comb.ToolResponseMode, + DirectSerialization: comb.DirectToolResponseMode, + Skipped: true, + SkipReasonCodes: []string{SkipReasonDegenerate}, + } +} + +// SkipReasonText renders a skip row's reason as the single string the existing +// report shape carries, naming both the code(s) and the cell collapsed onto. +// Contract rule 4 requires a skipped row to carry a reason AND its collapse +// target; the shape it must fit into (ArmResult.SkipReason) is one string, so +// they are joined here rather than by inventing a second skip shape. +func (c ModeCell) SkipReasonText() string { + if !c.Skipped { + return "" + } + codes := strings.Join(c.SkipReasonCodes, "+") + if c.CollapsesOnto != "" { + return codes + ": collapses onto " + c.CollapsesOnto + } + if len(c.SkipReasonCodes) == 1 && c.SkipReasonCodes[0] == SkipReasonDegenerate { + return codes + ": the surface can discover tools and call none of them, so there is no equivalent cell" + } + return codes +} + +// SkipRow renders this cell as the report's EXISTING skipped-row shape +// (ArmResult.Skipped / SkipReason via SkippedArmResult). Reusing that +// constructor is deliberate: a second skip shape would give consumers two +// places to look for "why is this row empty", and the whole point of FR-017 is +// that the answer is always in exactly one place. +func (c ModeCell) SkipRow(corpusID string) ArmResult { + return SkippedArmResult(c.ID, corpusID, c.SkipReasonText()) +} + +// EndpointURL resolves this cell's mounted MCP endpoint against a base URL +// (T015). The routing-mode axis needs no config change and no restart โ€” all +// three routing-mode servers are built at startup and all three endpoints stay +// mounted regardless of config โ€” so moving between routing modes is nothing +// more than changing this URL. +// +// The two serialization cells that share an endpoint are NOT an error: a cell +// is (URL, serialization-config), and the serialization half is applied by a +// hot config reload on the same long-lived instance. +// +// The returned URL is what NewMCPRetrieveCaller (mcpcaller.go) takes, so the +// transport is composed rather than rebuilt per cell. +func (c ModeCell) EndpointURL(baseURL string) (string, error) { + if baseURL == "" { + return "", fmt.Errorf("mode cell %q: base URL is required to address an endpoint", c.ID) + } + if c.Endpoint == "" { + return "", fmt.Errorf("mode cell %q has no mcpproxy endpoint", c.ID) + } + return strings.TrimRight(baseURL, "/") + c.Endpoint, nil +} + +// ProxyTools returns the built-in mcpproxy tool definitions that occupy the +// agent's context window in this cell's routing mode, delegating to +// ProxyToolsForMode so the catalog stays derived from the production tool +// builders and can never drift from what the server really registers. +// +// The direct routing mode returns none: its context cost is the rendered +// upstream catalog itself, which is measured by the cell's encoding arm rather +// than by a fixed built-in list. +func (c ModeCell) ProxyTools() []Tool { + return ProxyToolsForMode(c.RoutingMode) +} + +// ArmName names the existing encoding arm that renders this cell's tool menu, +// for resolution through the bench/arms registry by a caller that may import +// it (package bench cannot: arms imports bench). Returning a NAME rather than +// an arm is what keeps every serialization in the one place it is already +// implemented instead of being re-derived here. +func (c ModeCell) ArmName() string { + switch c.ID { + case CellRetrieveCompact: + return "compact_sig" + case CellDirectDeferred: + return "direct_deferred" + default: + // baseline, retrieve_full, direct_full and code_exec all render full, + // schema-bearing definitions โ€” code_exec because that surface forces + // full, not because it defaults to it. + return "baseline_json" + } +} + +// capabilityConditions is the FR-016 enumeration: each binary toggle with the +// cells it is available on, in matrix order. Availability is decided by where +// the production surface actually registers the capability, not by where it +// would be useful โ€” a capability that is unavailable and one that is available +// but unhelpful are different findings, and the report must not conflate them. +var capabilityConditions = []CapabilityCondition{ + {ID: CapabilityBatching, AppliesTo: []string{CellRetrieveFull, CellRetrieveCompact, CellDirectFull, CellDirectDeferred}}, + {ID: CapabilityStoredScripts, AppliesTo: []string{CellCodeExec}}, + {ID: CapabilityValidateBeforeDispatch, AppliesTo: []string{CellRetrieveFull, CellRetrieveCompact, CellDirectFull, CellDirectDeferred}}, +} + +// CapabilityConditions returns the FR-016 binary conditions with their +// applicable rows enumerated. They are conditions over existing cells, not a +// fourth axis: turning one on does not create a new cell, it re-measures the +// cells listed here. +func CapabilityConditions() []CapabilityCondition { + out := make([]CapabilityCondition, len(capabilityConditions)) + for i, c := range capabilityConditions { + out[i] = CapabilityCondition{ID: c.ID, AppliesTo: append([]string(nil), c.AppliesTo...)} + } + return out +} diff --git a/bench/modematrix_test.go b/bench/modematrix_test.go new file mode 100644 index 000000000..f5c204fe3 --- /dev/null +++ b/bench/modematrix_test.go @@ -0,0 +1,493 @@ +package bench + +import ( + "reflect" + "sort" + "strings" + "testing" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" +) + +// Spec 103 US? โ€” T012/T013: the mode matrix +// (specs/103-token-bench/contracts/mode-matrix.md). +// +// The contract's load-bearing claim is arithmetic: the naive 3-axis product is +// 3 routing modes x 2 discovery serializations x 2 direct serializations = 12 +// combinations, and those 12 collapse onto 5 distinct behaviours. The other 7 +// are configurable and behaviourally redundant โ€” NOT impossible โ€” so each must +// surface as a skip row naming the cell it collapses onto, never as a zero and +// never as a missing row (FR-017). +// +// These tests pin all three halves of that claim: the 5 cells and their +// not-applicable axes, the 7 collapses with their reason codes, and the FR-016 +// capability toggles as binary conditions over the cells where each is +// available rather than as a fourth axis. + +// allValidCellIDs is the expected cell-id set in contract-table order. Cell ids +// are a stability contract (FR-028): a run from a later release must remain +// comparable to an earlier one, so this list is deliberately hard-coded rather +// than derived from the implementation. +var allValidCellIDs = []string{ + CellRetrieveFull, + CellRetrieveCompact, + CellDirectFull, + CellDirectDeferred, + CellCodeExec, +} + +func TestModeCellsAreExactlyFiveDistinctBehaviours(t *testing.T) { + cells := ModeCells() + if len(cells) != 5 { + t.Fatalf("ModeCells() returned %d cells, want exactly 5 distinct behaviours", len(cells)) + } + + seen := map[string]bool{} + for i, c := range cells { + if c.ID != allValidCellIDs[i] { + t.Errorf("cell %d: id = %q, want %q (cell ids are stable, FR-028)", i, c.ID, allValidCellIDs[i]) + } + if seen[c.ID] { + t.Errorf("cell id %q appears twice; the 5 cells must be distinct", c.ID) + } + seen[c.ID] = true + if c.Skipped { + t.Errorf("cell %q is a valid cell and must not be marked skipped", c.ID) + } + if c.CollapsesOnto != "" { + t.Errorf("cell %q is a valid cell and must not collapse onto %q", c.ID, c.CollapsesOnto) + } + } +} + +func TestBaselineIsNotAnMcpproxyMode(t *testing.T) { + b := BaselineCell() + if b.ID != CellBaseline { + t.Fatalf("BaselineCell().ID = %q, want %q", b.ID, CellBaseline) + } + for _, c := range ModeCells() { + if c.ID == CellBaseline { + t.Fatalf("baseline must not appear among the 5 mcpproxy cells") + } + } + if b.Endpoint != "" { + t.Errorf("baseline endpoint = %q, want empty: baseline loads every upstream tool inline, it is served by no mcpproxy surface", b.Endpoint) + } + if _, err := b.EndpointURL("http://127.0.0.1:8080"); err == nil { + t.Errorf("BaselineCell().EndpointURL() returned no error; the baseline has no endpoint to address") + } +} + +// TestIgnoredAxesAreNotApplicableNeverDefaults pins contract rule 3: an axis +// with no consumer on a cell's surface is recorded as not-applicable, never as +// its default value โ€” a default would imply a measurement that was never taken. +func TestIgnoredAxesAreNotApplicableNeverDefaults(t *testing.T) { + want := map[string]struct{ discovery, direct string }{ + CellRetrieveFull: {SerializationFull, SerializationNotApplicable}, + CellRetrieveCompact: {SerializationCompact, SerializationNotApplicable}, + CellDirectFull: {SerializationNotApplicable, SerializationFull}, + CellDirectDeferred: {SerializationNotApplicable, SerializationDeferred}, + // code_exec is the one cell where "full" is an override, not a default: + // the surface overwrites the response mode and blanks the detail param. + CellCodeExec: {SerializationFull, SerializationNotApplicable}, + } + for _, c := range ModeCells() { + w, ok := want[c.ID] + if !ok { + t.Fatalf("unexpected cell %q", c.ID) + } + if c.DiscoverySerialization != w.discovery { + t.Errorf("cell %q: discovery serialization = %q, want %q", c.ID, c.DiscoverySerialization, w.discovery) + } + if c.DirectSerialization != w.direct { + t.Errorf("cell %q: direct serialization = %q, want %q", c.ID, c.DirectSerialization, w.direct) + } + } +} + +// TestProductIsTwelveCombinationsFiveDistinct walks the FULL naive product and +// asserts the collapse arithmetic end to end: 12 configurable combinations, +// 5 distinct behaviours, 7 skip rows. +func TestProductIsTwelveCombinationsFiveDistinct(t *testing.T) { + routing := []string{config.RoutingModeRetrieveTools, config.RoutingModeDirect, config.RoutingModeCodeExecution} + discovery := []string{config.ToolResponseModeFull, config.ToolResponseModeCompact} + direct := []string{config.DirectToolResponseModeFull, config.DirectToolResponseModeDeferred} + + distinct := map[string]bool{} + skips := 0 + total := 0 + for _, r := range routing { + for _, d := range discovery { + for _, dd := range direct { + total++ + got := ResolveCombination(Combination{ + RoutingMode: r, + ToolResponseMode: d, + DirectToolResponseMode: dd, + // code_execution is enabled throughout: the degenerate + // configuration is a separate case, tested below. + EnableCodeExecution: true, + }) + if got.Skipped { + skips++ + if got.CollapsesOnto == "" { + t.Errorf("%s/%s/%s: skipped row carries no collapse target", r, d, dd) + } + if _, ok := CellByID(got.CollapsesOnto); !ok { + t.Errorf("%s/%s/%s: collapses onto unknown cell %q", r, d, dd, got.CollapsesOnto) + } + continue + } + distinct[got.ID] = true + } + } + } + + if total != 12 { + t.Fatalf("walked %d combinations, want 12", total) + } + if len(distinct) != 5 { + t.Errorf("resolved %d distinct behaviours (%v), want 5", len(distinct), sortedKeys(distinct)) + } + if skips != 7 { + t.Errorf("produced %d skip rows, want 7", skips) + } +} + +// TestRedundantCombinationsNameTheirCollapse pins the contract's collapse table +// row for row, including the one combination that carries TWO reason codes. +func TestRedundantCombinationsNameTheirCollapse(t *testing.T) { + cases := []struct { + routing, discovery, direct string + collapsesOnto string + reasons []string + }{ + {config.RoutingModeRetrieveTools, "full", "deferred", CellRetrieveFull, []string{SkipReasonAxisIgnored}}, + {config.RoutingModeRetrieveTools, "compact", "deferred", CellRetrieveCompact, []string{SkipReasonAxisIgnored}}, + {config.RoutingModeDirect, "compact", "full", CellDirectFull, []string{SkipReasonAxisIgnored}}, + {config.RoutingModeDirect, "compact", "deferred", CellDirectDeferred, []string{SkipReasonAxisIgnored}}, + {config.RoutingModeCodeExecution, "compact", "full", CellCodeExec, []string{SkipReasonForcedFull}}, + {config.RoutingModeCodeExecution, "full", "deferred", CellCodeExec, []string{SkipReasonAxisIgnored}}, + {config.RoutingModeCodeExecution, "compact", "deferred", CellCodeExec, []string{SkipReasonForcedFull, SkipReasonAxisIgnored}}, + } + + if got := len(RedundantCombinations()); got != len(cases) { + t.Fatalf("RedundantCombinations() returned %d rows, want %d", got, len(cases)) + } + + for _, tc := range cases { + name := tc.routing + "/" + tc.discovery + "/" + tc.direct + got := ResolveCombination(Combination{ + RoutingMode: tc.routing, + ToolResponseMode: tc.discovery, + DirectToolResponseMode: tc.direct, + EnableCodeExecution: true, + }) + if !got.Skipped { + t.Errorf("%s: want a skip row, got valid cell %q", name, got.ID) + continue + } + if got.CollapsesOnto != tc.collapsesOnto { + t.Errorf("%s: collapses onto %q, want %q", name, got.CollapsesOnto, tc.collapsesOnto) + } + if strings.Join(got.SkipReasonCodes, "+") != strings.Join(tc.reasons, "+") { + t.Errorf("%s: reason codes %v, want %v", name, got.SkipReasonCodes, tc.reasons) + } + } +} + +// TestDegenerateCodeExecutionConfiguration: code_execution with +// enable_code_execution:false is not part of the product โ€” the surface can +// discover tools and call none of them โ€” so it is skipped as `degenerate` and +// collapses onto nothing. +func TestDegenerateCodeExecutionConfiguration(t *testing.T) { + got := ResolveCombination(Combination{ + RoutingMode: config.RoutingModeCodeExecution, + ToolResponseMode: config.ToolResponseModeFull, + DirectToolResponseMode: config.DirectToolResponseModeFull, + EnableCodeExecution: false, + }) + if !got.Skipped { + t.Fatalf("code_execution with enable_code_execution:false resolved to valid cell %q, want a skip row", got.ID) + } + if len(got.SkipReasonCodes) != 1 || got.SkipReasonCodes[0] != SkipReasonDegenerate { + t.Errorf("reason codes = %v, want [%s]", got.SkipReasonCodes, SkipReasonDegenerate) + } + if got.CollapsesOnto != "" { + t.Errorf("collapses onto %q, want empty: a degenerate configuration is not a redundant one", got.CollapsesOnto) + } + + // The degenerate verdict outranks redundancy: with the surface disabled the + // serialization axes cannot change anything. + also := ResolveCombination(Combination{ + RoutingMode: config.RoutingModeCodeExecution, + ToolResponseMode: config.ToolResponseModeCompact, + DirectToolResponseMode: config.DirectToolResponseModeDeferred, + EnableCodeExecution: false, + }) + if len(also.SkipReasonCodes) != 1 || also.SkipReasonCodes[0] != SkipReasonDegenerate { + t.Errorf("disabled code_execution with redundant axes: reason codes = %v, want [%s]", also.SkipReasonCodes, SkipReasonDegenerate) + } +} + +// TestSkipRowReusesExistingArmResultShape pins contract rule 4: skip rows go +// through the EXISTING skipped-row shape (ArmResult.Skipped/SkipReason via +// SkippedArmResult), and the rendered reason names both the code and the cell +// collapsed onto so a reader never has to infer a zero. +func TestSkipRowReusesExistingArmResultShape(t *testing.T) { + skip := ResolveCombination(Combination{ + RoutingMode: config.RoutingModeCodeExecution, + ToolResponseMode: config.ToolResponseModeCompact, + DirectToolResponseMode: config.DirectToolResponseModeDeferred, + EnableCodeExecution: true, + }) + row := skip.SkipRow("corpus_v2@test") + + if !row.Skipped { + t.Errorf("ArmResult.Skipped = false, want true") + } + if row.Arm != skip.ID { + t.Errorf("ArmResult.Arm = %q, want the cell id %q", row.Arm, skip.ID) + } + if row.CorpusID != "corpus_v2@test" { + t.Errorf("ArmResult.CorpusID = %q, want %q", row.CorpusID, "corpus_v2@test") + } + for _, code := range skip.SkipReasonCodes { + if !strings.Contains(row.SkipReason, code) { + t.Errorf("SkipReason %q does not name reason code %q", row.SkipReason, code) + } + } + if !strings.Contains(row.SkipReason, skip.CollapsesOnto) { + t.Errorf("SkipReason %q does not name the cell it collapses onto (%q)", row.SkipReason, skip.CollapsesOnto) + } + + // Identical to the existing constructor: no second skip shape exists. + if want := SkippedArmResult(skip.ID, "corpus_v2@test", skip.SkipReasonText()); !reflect.DeepEqual(row, want) { + t.Errorf("SkipRow() = %+v, want SkippedArmResult(...) = %+v", row, want) + } +} + +// --- T015: endpoint mapping ------------------------------------------------- + +// TestCellEndpointURL pins contract rule 1/2: the routing-mode axis is selected +// by URL alone โ€” all three routing-mode endpoints stay mounted regardless of +// config โ€” while the serialization axes are config, which is why two cells can +// legitimately share one URL. +func TestCellEndpointURL(t *testing.T) { + const base = "http://127.0.0.1:18080" + want := map[string]string{ + CellRetrieveFull: base + "/mcp/call", + CellRetrieveCompact: base + "/mcp/call", + CellDirectFull: base + "/mcp/all", + CellDirectDeferred: base + "/mcp/all", + CellCodeExec: base + "/mcp/code", + } + for _, c := range ModeCells() { + got, err := c.EndpointURL(base) + if err != nil { + t.Fatalf("cell %q: EndpointURL: %v", c.ID, err) + } + if got != want[c.ID] { + t.Errorf("cell %q: endpoint URL = %q, want %q", c.ID, got, want[c.ID]) + } + } + + // A trailing slash on the base must not double up. + got, err := ModeCells()[0].EndpointURL(base + "/") + if err != nil { + t.Fatalf("EndpointURL with trailing slash: %v", err) + } + if got != want[CellRetrieveFull] { + t.Errorf("trailing-slash base produced %q, want %q", got, want[CellRetrieveFull]) + } + + if _, err := ModeCells()[0].EndpointURL(""); err == nil { + t.Errorf("EndpointURL(\"\") returned no error; a cell cannot be addressed without a base URL") + } +} + +// TestSerializationCellsShareOneEndpoint states the operational consequence +// tested above as its own claim: the matrix crosses on ONE long-lived instance, +// with a config apply โ€” not a restart โ€” between serialization cells. +func TestSerializationCellsShareOneEndpoint(t *testing.T) { + pairs := [][2]string{ + {CellRetrieveFull, CellRetrieveCompact}, + {CellDirectFull, CellDirectDeferred}, + } + for _, p := range pairs { + a, _ := CellByID(p[0]) + b, _ := CellByID(p[1]) + if a.Endpoint != b.Endpoint { + t.Errorf("cells %q and %q differ only in serialization config, so they must share endpoint %q vs %q", p[0], p[1], a.Endpoint, b.Endpoint) + } + if a.DiscoverySerialization == b.DiscoverySerialization && a.DirectSerialization == b.DirectSerialization { + t.Errorf("cells %q and %q share an endpoint AND a serialization: they are not distinct", p[0], p[1]) + } + } +} + +// TestCellProxyToolsComposeExistingCatalog: the matrix must not re-derive a +// serialization or a tool catalog. A cell's built-in proxy tools come from +// ProxyToolsForMode (proxytools.go), which itself derives from the production +// tool builders. +func TestCellProxyToolsComposeExistingCatalog(t *testing.T) { + c, ok := CellByID(CellRetrieveFull) + if !ok { + t.Fatalf("CellByID(%q) not found", CellRetrieveFull) + } + got := c.ProxyTools() + want := ProxyToolsForMode(ModeRetrieveTools) + if len(got) == 0 { + t.Fatalf("cell %q has no proxy tools; the catalog was not composed", c.ID) + } + if len(got) != len(want) { + t.Fatalf("cell %q proxy tools = %d, want %d (ProxyToolsForMode)", c.ID, len(got), len(want)) + } + for i := range got { + if got[i].ToolID != want[i].ToolID { + t.Errorf("proxy tool %d = %q, want %q", i, got[i].ToolID, want[i].ToolID) + } + } +} + +// --- T013: FR-016 capability conditions ------------------------------------ + +// TestCapabilityConditionsAreBinaryNotAnAxis pins contract rule 5: batching, +// stored scripts and validate-before-dispatch are binary conditions applied to +// the cells where each is available, and the report enumerates the applicable +// rows. They multiply nothing: the matrix stays 5 cells with or without them. +func TestCapabilityConditionsAreBinaryNotAnAxis(t *testing.T) { + conds := CapabilityConditions() + if len(conds) != 3 { + t.Fatalf("CapabilityConditions() returned %d conditions, want 3 (batching, stored scripts, validate-before-dispatch)", len(conds)) + } + + wantApplies := map[string][]string{ + // describe_tool (batch <=5 ids) is registered on the retrieve_tools + // surface (Spec 085) and the direct surface (Spec 102), and is + // deliberately absent from the code-execution surface. + CapabilityBatching: {CellRetrieveFull, CellRetrieveCompact, CellDirectFull, CellDirectDeferred}, + // Stored scripts are a code_execution feature and exist nowhere else. + CapabilityStoredScripts: {CellCodeExec}, + // Pre-dispatch argument validation runs on the call_tool_* variants + // (Spec 085 FR-013) and on direct dispatch (Spec 102 US3); the + // code-execution surface dispatches from the sandbox and does not. + CapabilityValidateBeforeDispatch: {CellRetrieveFull, CellRetrieveCompact, CellDirectFull, CellDirectDeferred}, + } + + seen := map[string]bool{} + for _, c := range conds { + want, ok := wantApplies[c.ID] + if !ok { + t.Errorf("unexpected capability %q", c.ID) + continue + } + if seen[c.ID] { + t.Errorf("capability %q enumerated twice", c.ID) + } + seen[c.ID] = true + if len(c.AppliesTo) == 0 { + t.Errorf("capability %q applies to no cell; a condition with no rows is not measurable", c.ID) + } + if strings.Join(c.AppliesTo, ",") != strings.Join(want, ",") { + t.Errorf("capability %q applies to %v, want %v", c.ID, c.AppliesTo, want) + } + for _, id := range c.AppliesTo { + if _, ok := CellByID(id); !ok { + t.Errorf("capability %q names unknown cell %q", c.ID, id) + } + if id == CellBaseline { + t.Errorf("capability %q applies to the baseline; the baseline is not an mcpproxy surface", c.ID) + } + } + } + + if len(ModeCells()) != 5 { + t.Errorf("capability conditions changed the cell count; they are conditions, not a fourth axis") + } +} + +// TestCellCapabilitiesAgreeWithConditions: the per-cell view and the +// per-capability enumeration are two renderings of one fact and must not drift. +func TestCellCapabilitiesAgreeWithConditions(t *testing.T) { + fromConditions := map[string]map[string]bool{} + for _, cond := range CapabilityConditions() { + for _, cellID := range cond.AppliesTo { + if fromConditions[cellID] == nil { + fromConditions[cellID] = map[string]bool{} + } + fromConditions[cellID][cond.ID] = true + } + } + + for _, c := range ModeCells() { + fromCell := map[string]bool{} + for _, capID := range c.Capabilities { + if fromCell[capID] { + t.Errorf("cell %q lists capability %q twice", c.ID, capID) + } + fromCell[capID] = true + } + want := fromConditions[c.ID] + if len(fromCell) != len(want) { + t.Errorf("cell %q capabilities %v disagree with the enumeration %v", c.ID, sortedKeys(fromCell), sortedKeys(want)) + continue + } + for capID := range want { + if !fromCell[capID] { + t.Errorf("cell %q is missing capability %q that the enumeration claims", c.ID, capID) + } + } + } + + if caps := BaselineCell().Capabilities; len(caps) != 0 { + t.Errorf("baseline capabilities = %v, want none", caps) + } +} + +func sortedKeys(m map[string]bool) []string { + out := make([]string, 0, len(m)) + for k := range m { + out = append(out, k) + } + sort.Strings(out) + return out +} + +// TestBenchModeConstantsMatchProductionRoutingModes guards the string identity +// the cell table leans on: bench's own mode names (tokens.go) and the +// production routing modes (internal/config) are the same strings, which is +// why a cell's RoutingMode can be handed straight to ProxyToolsForMode. If +// either side is ever renamed, this fails here rather than silently resolving +// every cell to an empty proxy catalog. +func TestBenchModeConstantsMatchProductionRoutingModes(t *testing.T) { + if ModeRetrieveTools != config.RoutingModeRetrieveTools { + t.Errorf("ModeRetrieveTools = %q, config.RoutingModeRetrieveTools = %q", ModeRetrieveTools, config.RoutingModeRetrieveTools) + } + if ModeCodeExecution != config.RoutingModeCodeExecution { + t.Errorf("ModeCodeExecution = %q, config.RoutingModeCodeExecution = %q", ModeCodeExecution, config.RoutingModeCodeExecution) + } +} + +// TestCellArmNamesNameExistingArms pins the composition seam: a cell says WHICH +// existing encoding arm renders its menu and the caller resolves that name +// through the bench/arms registry, so no serialization is re-derived here. +// (The names are string literals because package bench cannot import +// bench/arms โ€” arms imports bench.) +func TestCellArmNamesNameExistingArms(t *testing.T) { + want := map[string]string{ + CellBaseline: "baseline_json", + CellRetrieveFull: "baseline_json", + CellRetrieveCompact: "compact_sig", + CellDirectFull: "baseline_json", + CellDirectDeferred: "direct_deferred", + // The code-execution surface forces full serialization, so it renders + // with the full arm โ€” an override, not a default. + CellCodeExec: "baseline_json", + } + for _, c := range AllCells() { + if got := c.ArmName(); got != want[c.ID] { + t.Errorf("cell %q: ArmName = %q, want %q", c.ID, got, want[c.ID]) + } + } +} diff --git a/bench/replay.go b/bench/replay.go new file mode 100644 index 000000000..9134568c7 --- /dev/null +++ b/bench/replay.go @@ -0,0 +1,721 @@ +// replay.go โ€” Spec 103 US1: deterministic cost recomputation over a REAL +// recorded workload (specs/103-token-bench/contracts/replay-input.md). +// +// What replay is. An operator exports their own activity log +// (`mcpproxy activity export --format json`) and supplies a fleet. Replay then +// prices, per mode cell, the tool menu that fleet would put in the agent's +// context, and reports the recorded call shape it was priced against. It costs +// nothing to run, spends no model tokens, and replaces frozen-corpus numbers +// with numbers from a fleet somebody actually uses. +// +// # A fleet input is MANDATORY +// +// A menu is a property of the TOOL DEFINITIONS the agent was shown, and the +// activity export carries no fleet snapshot โ€” not even implicitly, because +// under the direct routing mode the menu is the whole upstream fleet rather +// than a fixed built-in list. So a recording on its own can compute nothing at +// all. That is why `-replay ` without a fleet is ErrReplayFleetRequired +// and not a degraded run: there is no reduced figure to degrade TO, and a run +// that quietly produced menu-less output would be a report with no menu cost +// in it, which is the only thing US1 exists to produce. +// +// # What bodies-off can and cannot yield +// +// The default posture reads no request or response bodies (privacy: the +// activity EXPORT path does not mask, so an export is raw user traffic). That +// posture fixes what is knowable, per the contract's table: +// +// - MENU COST is measured for every cell, from the fleet input. +// - ABSOLUTE COMPLETE-WORKLOAD COST is available for NO cell, because a +// complete workload includes every consumed response and that text is +// absent. It is reported as withheld WITH a reason โ€” never as a zero, +// which would read as "measured, and it cost nothing". +// - The CROSS-MODE DELTA between direct_full and direct_deferred IS +// measurable, because those two cells serve identical call responses and +// the response term cancels out of the difference. That delta is the +// honest bodies-off headline. The retrieve cells get no such delta: their +// serialization axis changes the RESPONSE body, which is exactly the text +// bodies-off does not have. +// +// Byte lengths do NOT rescue this. `request_bytes` / `response_bytes` are +// pre-truncation BYTE measurements, and the loader deliberately reports them +// as Cost{Basis: CostEstimated, Bytes: n} with NO token count: converting +// bytes to tokens would require a fudge factor nobody sanctioned. So a +// response figure is emitted only when every contributing response was +// genuinely tokenized (bodies-on), and otherwise not at all. +// +// # Every figure is a counterfactual +// +// FR-004 is the spec's most load-bearing constraint and the easiest to lose in +// a headline: a replay recomputes a RECORDED call shape against the SUPPLIED +// fleet. No agent ran under these modes; no model was asked. And because the +// fleet comes from the fleet input rather than the recording, the figures score +// recorded work against TODAY's fleet, not the fleet as it stood when the +// session was recorded โ€” internally valid across modes, not a historical +// reconstruction. ValidateCounterfactual refuses to let a block carrying +// figures leave without saying so. +// +// # Determinism +// +// Two runs over the same inputs must be byte-identical (SC-002), so replay +// reports pin GeneratedAt to ReplayGeneratedAt rather than stamping the wall +// clock. Nothing else here reads a clock, sorts a map, or depends on iteration +// order; the loader already orders sessions deterministically. +package bench + +import ( + "errors" + "fmt" + "sort" + "strings" + + "github.com/smart-mcp-proxy/mcpproxy-go/bench/replaycorpus" + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" +) + +// ErrReplayFleetRequired is the T019 hard error. It is a sentinel rather than +// a formatted string so a caller (and a test) can assert the RULE, not the +// wording: a recording-only invocation is an error, not a degraded run. +var ErrReplayFleetRequired = errors.New("replay requires a fleet input as well as a recording") + +// ReplayGeneratedAt is the pinned generated_at stamp of every replay report +// (T029). SC-002 asks for byte-identical output across runs, and a wall-clock +// stamp defeats that check on its own, silently โ€” a diff that always differs +// in one line trains a reader to ignore diffs. The value is a real RFC 3339 +// timestamp so the report still validates against the schema's date-time +// format, and an obviously synthetic one so nobody mistakes it for a run time. +const ReplayGeneratedAt = "1970-01-01T00:00:00Z" + +// ReplayCounterfactualLabel is the FR-004 label carried by every replay block. +// +// It states three things a reader needs at once, because dropping any one of +// them turns the figures into a claim the data cannot support: that this is a +// counterfactual, that no agent behaviour was observed, and that recorded work +// is scored against the supplied fleet rather than the fleet of the day. +const ReplayCounterfactualLabel = "COUNTERFACTUAL โ€” not observed agent behaviour. " + + "These figures recompute a RECORDED call shape (call sequence, tool mix and call counts, taken from an activity export) " + + "against the SUPPLIED FLEET under each mode cell. No agent ran under these modes and no model was asked, " + + "so nothing here measures how an agent behaves. The fleet comes from the fleet input, not from the recording, " + + "so a replay scores recorded work against TODAY's fleet rather than the fleet as it stood when the session was recorded: " + + "internally valid across modes, not a historical reconstruction." + +// replayDroppingReasons are the exclusion reasons that REMOVE a session from +// the replay. They alone account for SessionsSupplied minus SessionsUsed; +// truncated and bodies_missing are reported as flags on sessions that still +// contributed, and unattributed counts records that never became a session at +// all. Keeping the two kinds distinguishable is what makes the accounting +// checkable rather than merely present. +var replayDroppingReasons = []string{ReplayExclusionSensitive, ReplayExclusionUnreplayable} + +// replayExclusionOrder fixes the row order of the exclusion table: what was +// DROPPED first, then what was flagged, then what never reached a session. +// Deterministic, and it also puts the consequential rows where a reader meets +// them before the headline. +var replayExclusionOrder = []string{ + ReplayExclusionSensitive, + ReplayExclusionUnreplayable, + ReplayExclusionTruncated, + ReplayExclusionBodiesMissed, + ReplayExclusionUnattributed, +} + +// ReplayOptions configures one replay run. +type ReplayOptions struct { + // RecordingPath is the activity JSONL export. It must live OUTSIDE the + // repository working tree โ€” the loader refuses an in-tree path, because a + // replay input is raw recorded traffic and must never be committed. + RecordingPath string + + // Fleet is the MANDATORY fleet input: the tool definitions the menu cost + // is computed from. Either a frozen corpus (the committed corpora already + // serve this) or a snapshot of a live proxy's catalog. + Fleet *Corpus + + // FleetID names the fleet shape every figure is quoted for (IC-004). + // Empty falls back to the corpus version. + FleetID string + + // Bodies is the loader's privacy posture. The ZERO VALUE is bodies-off, + // which is the safe default and the one this file's contract is written + // for; bodies-on is an explicit opt-in that warns. + Bodies replaycorpus.BodyPolicy + + // Encoding is the tiktoken encoding the loader counts bodies with on a + // bodies-on run. Empty means the loader default. + Encoding string + + // Arms resolves the encoding arms named by the mode matrix, keyed by arm + // name. Package bench cannot import bench/arms (arms imports bench), so + // arms arrive here as structural EncodingArm values the way armrun.go + // takes them. ReplayArmNames lists exactly what must be present. + Arms map[string]EncodingArm + + // Warnf receives the loader's operator-facing warnings. Nil means stderr. + Warnf func(format string, args ...any) +} + +// ReplayArmNames returns the arm names a replay needs resolved, in a stable +// order. It is smaller than the set of arms the mode matrix names, and +// deliberately so โ€” see replayMenuArmName for why the discovery-serialization +// arm never prices a menu. +func ReplayArmNames() []string { + seen := map[string]bool{} + var names []string + for _, cell := range ModeCells() { + name := replayMenuArmName(cell) + if !seen[name] { + seen[name] = true + names = append(names, name) + } + } + sort.Strings(names) + return names +} + +// FleetResolver builds the loader's replayability predicate from a fleet +// input: does the (server, tool) a record names still exist in the fleet this +// replay scores against? +// +// It answers true for mcpproxy's OWN built-in tools regardless of the fleet. +// A recording of a proxy session is full of retrieve_tools / call_tool_* / +// describe_tool records, and those are not upstream tools โ€” treating them as +// vanished would mark essentially every real recording unreplayable and empty +// the report, which is a wiring bug dressed as a data finding. +// +// It is exported because a caller assembling its own load (a test, or a future +// bodies-on path) must be able to wire the SAME predicate: the loader treats a +// nil resolver as "replayability was never evaluated", and a replay that +// silently took that branch would report "nothing was unreplayable" when it +// meant "nobody looked". +func FleetResolver(fleet *Corpus) func(serverName, toolName string) bool { + if fleet == nil { + return nil + } + inFleet := make(map[string]bool, len(fleet.Tools)*2) + for _, tl := range fleet.Tools { + inFleet[fleetKey(tl.Server, tl.Name)] = true + if tl.ToolID != "" { + inFleet[strings.ToLower(tl.ToolID)] = true + } + } + builtin := make(map[string]bool) + for _, mode := range []string{ModeRetrieveTools, ModeCodeExecution} { + for _, tl := range ProxyToolsForMode(mode) { + builtin[strings.ToLower(tl.Name)] = true + } + } + return func(serverName, toolName string) bool { + server, tool := splitToolIdentity(serverName, toolName) + if builtin[strings.ToLower(tool)] { + return true + } + if inFleet[fleetKey(server, tool)] { + return true + } + return inFleet[strings.ToLower(server+":"+tool)] + } +} + +func fleetKey(server, tool string) string { + return strings.ToLower(server) + "\x00" + strings.ToLower(tool) +} + +// splitToolIdentity recovers (server, tool) when the record carried the two +// fused into the tool name. Both proxy surfaces are in play in a real export: +// ":" on the retrieve_tools surface and "__" on +// the direct one. +func splitToolIdentity(serverName, toolName string) (server, tool string) { + if serverName != "" { + return serverName, toolName + } + if idx := strings.Index(toolName, "__"); idx > 0 { + return toolName[:idx], toolName[idx+2:] + } + if idx := strings.Index(toolName, ":"); idx > 0 { + return toolName[:idx], toolName[idx+1:] + } + return serverName, toolName +} + +// RunReplay loads a recording, prices every mode cell's menu against the +// supplied fleet, and returns the report block. +// +// The fleet check comes FIRST, before the recording is even opened: refusing +// early is what makes the refusal a rule about the invocation rather than an +// accident of whichever file happened to be readable. +func RunReplay(tk *Tokenizer, opts ReplayOptions) (*ReplayBlock, error) { + if tk == nil { + return nil, errors.New("replay: a tokenizer is required") + } + if opts.Fleet == nil || len(opts.Fleet.Tools) == 0 { + return nil, fmt.Errorf("%w: a menu is a property of the tool definitions and the activity export carries no fleet snapshot, "+ + "so a recording on its own computes nothing โ€” pass a frozen corpus or a live-proxy catalog "+ + "(this is an error, not a degraded run)", ErrReplayFleetRequired) + } + if opts.RecordingPath == "" { + return nil, errors.New("replay: a recording path is required (mcpproxy activity export --format json)") + } + if err := requireReplayArms(opts.Arms); err != nil { + return nil, err + } + + corpus, err := replaycorpus.LoadFile(opts.RecordingPath, replaycorpus.Options{ + Bodies: opts.Bodies, + Encoding: opts.Encoding, + Warnf: opts.Warnf, + FleetResolver: FleetResolver(opts.Fleet), + }) + if err != nil { + return nil, fmt.Errorf("replay: load recording: %w", err) + } + // A replay ALWAYS supplies a fleet, so the loader must always have been + // able to evaluate replayability. False here is not a fact about the data; + // it means this function failed to pass the resolver, and the difference + // between "nothing was unreplayable" and "nobody looked" would then be + // invisible in the report. + if !corpus.FleetChecked { + return nil, errors.New("replay: internal wiring error โ€” the loader ran without a fleet resolver, " + + "so 'unreplayable' was never evaluated and its absence would be reported as a clean result") + } + + return buildReplayBlock(tk, corpus, opts) +} + +// requireReplayArms fails loudly on a missing arm. A cell whose arm could not +// be resolved must not quietly vanish from the report: an absent row reads as +// "not applicable", while the truth is "we could not measure it". +func requireReplayArms(available map[string]EncodingArm) error { + var missing []string + for _, name := range ReplayArmNames() { + if available[name] == nil { + missing = append(missing, name) + } + } + if len(missing) > 0 { + return fmt.Errorf("replay: no encoding arm supplied for %s โ€” every mode cell must be priced or the row would be silently absent", + strings.Join(missing, ", ")) + } + return nil +} + +// buildReplayBlock assembles the report block from a loaded corpus. +func buildReplayBlock(tk *Tokenizer, corpus *replaycorpus.Corpus, opts ReplayOptions) (*ReplayBlock, error) { + used, exclusions := partitionReplaySessions(corpus) + + calls := 0 + for _, session := range used { + // AllCalls, never Calls: code-execution sub-calls hang off their + // parent's SubCalls and are absent from Calls by design, so a sum over + // Calls undercounts every sandbox-issued call in the recording. + calls += len(session.AllCalls()) + } + responseTokens := measuredResponseTokens(used) + + shape, err := replayFleetShape(tk, opts) + if err != nil { + return nil, err + } + + cells := make([]ReplayCellCost, 0, len(ModeCells())) + menuByCell := make(map[string]int, len(cells)) + for _, cell := range ModeCells() { + menu, err := replayMenuTokens(tk, cell, opts.Fleet, opts.Arms) + if err != nil { + return nil, err + } + menuByCell[cell.ID] = menu + row := ReplayCellCost{ + CellID: cell.ID, + // Measured: the menu is counted by the pinned deterministic + // tokenizer over real tool definitions from the fleet input. + // (The delta row below is `computed` โ€” arithmetic over two of + // these โ€” and carries its own badge for exactly that reason.) + Provenance: ProvenanceMeasured, + Calls: calls, + MenuTokens: menu, + // True for EVERY cell, always. See withheldWorkloadReason. + AbsoluteWorkloadWithheld: true, + WithheldReason: withheldWorkloadReason(cell, opts.Bodies), + } + if responseTokens != nil && isDirectCell(cell) { + // Only the two direct cells serve identical call responses, so a + // measured response total from one recording is meaningful for + // them alone. It is still NOT a complete workload โ€” hence the + // withheld flag above stays set. + total := *responseTokens + row.ResponseTokens = &total + } + cells = append(cells, row) + } + + block := &ReplayBlock{ + AccountingSource: AccountingSource{Kind: AccountingKindTokenizer, Identity: tk.encoding}, + Counterfactual: ReplayCounterfactualLabel, + BodiesIncluded: opts.Bodies == replaycorpus.BodiesOnUnmasked, + FleetShape: shape, + SessionsSupplied: len(corpus.Sessions), + SessionsUsed: len(used), + Exclusions: exclusions, + LoaderAccounting: loaderAccounting(&corpus.Exclusions), + Cells: cells, + DirectDelta: replayDirectDelta(menuByCell), + SensitiveFlagBestEffort: true, + } + + // Emission-time validation, not a rendering concern: a block that escaped + // unlabelled or unbalanced would carry its defect into every downstream + // consumer, and the caveat is the first thing a summary drops. + if err := block.ValidateCounterfactual(); err != nil { + return nil, err + } + if err := block.ValidateExclusionBalance(); err != nil { + return nil, err + } + return block, nil +} + +// partitionReplaySessions splits the loaded sessions into those that +// contribute and the exclusion accounting for everything that does not. +// +// The two kinds of row are kept apart on purpose. A session is DROPPED for +// sensitivity or unreplayability, and those two counts explain +// supplied-minus-used exactly, because each dropped session is attributed to +// one primary reason. Truncation and missing bodies do not drop a session: +// bodies-off no response figure is emitted at all, so a truncated record has +// nothing to understate โ€” but it is still counted and reported, because +// understating cost in the project's favour is the failure this whole feature +// exists to prevent, and silence is how it would happen. +func partitionReplaySessions(corpus *replaycorpus.Corpus) ([]*replaycorpus.ReplaySession, []ReplayExclusion) { + counts := map[string]int{} + used := make([]*replaycorpus.ReplaySession, 0, len(corpus.Sessions)) + + for _, session := range corpus.Sessions { + flags := session.Usability + if flags.Truncated { + counts[ReplayExclusionTruncated]++ + } + if flags.BodiesMissing { + counts[ReplayExclusionBodiesMissed]++ + } + switch { + case flags.Sensitive: + // Privacy outranks everything: a session flagged sensitive is not + // priced, whatever else is true of it. + counts[ReplayExclusionSensitive]++ + case flags.Unreplayable: + counts[ReplayExclusionUnreplayable]++ + default: + used = append(used, session) + } + } + + // Records the loader dropped before they could join any unit of work: + // non-call activity (quarantine changes, policy decisions), records with + // no tool name, and records with no work session to belong to. They are + // counted in RECORDS rather than sessions โ€” they never became a session, + // so no session count exists for them โ€” and the dashboard says so. + counts[ReplayExclusionUnattributed] = corpus.Exclusions.TotalDropped() + + rows := make([]ReplayExclusion, 0, len(replayExclusionOrder)) + for _, reason := range replayExclusionOrder { + if counts[reason] > 0 { + rows = append(rows, ReplayExclusion{Reason: reason, Sessions: counts[reason]}) + } + } + return used, rows +} + +// loaderAccounting carries the loader's own exclusion detail through to the +// report, alongside the session-level rows above. +// +// The session rows answer "how many units of work did not make it in". They +// cannot answer "what was dropped from a unit that DID make it in", and that +// second question has teeth: a withheld response cost collapses a cell's +// response total to nil, and without a row saying why, the reader sees a +// missing figure with no explanation. SC-008 asks that nothing be counted +// silently; a suppressed cost inside an admitted session is exactly the kind +// of silence it means. OrphanedSubCalls is here for the same reason โ€” those +// records ARE counted in the workload, but their attribution to a parent was +// lost, and a total that hides that is a total the reader cannot audit. +func loaderAccounting(rep *replaycorpus.ExclusionReport) *ReplayLoaderAccounting { + if rep == nil { + return nil + } + acc := &ReplayLoaderAccounting{ + RecordsDropped: rep.TotalDropped(), + CostsWithheld: rep.TotalWithheld(), + RecordsFlagged: rep.TotalFlagged(), + OrphanedSubCalls: rep.OrphanedSubCalls, + } + for _, r := range rep.DroppedRows() { + acc.Dropped = append(acc.Dropped, ReplayLoaderReason{Reason: string(r.Reason), Count: r.Count}) + } + for _, r := range rep.WithheldRows() { + acc.Withheld = append(acc.Withheld, ReplayLoaderReason{Reason: string(r.Reason), Count: r.Count}) + } + for _, r := range rep.FlaggedRows() { + acc.Flagged = append(acc.Flagged, ReplayLoaderReason{Reason: string(r.Reason), Count: r.Count}) + } + if acc.RecordsDropped == 0 && acc.CostsWithheld == 0 && acc.RecordsFlagged == 0 && acc.OrphanedSubCalls == 0 { + return nil + } + return acc +} + +// measuredResponseTokens sums response cost across the contributing sessions, +// and returns nil unless EVERY contributing response was genuinely tokenized. +// +// The all-or-nothing rule is the point. Cost.Tokens is populated only for +// CostMeasured; CostEstimated carries a pre-truncation BYTE length and no +// token count on purpose, and CostUnavailable carries zero for both plus a +// reason. Summing naively would let an unavailable cost fall through as a +// zero and understate the total โ€” the one direction of error this benchmark +// must not make. +func measuredResponseTokens(sessions []*replaycorpus.ReplaySession) *int { + total := 0 + seen := 0 + for _, session := range sessions { + for _, call := range session.AllCalls() { + if call.ResponseCost.Basis != replaycorpus.CostMeasured { + return nil + } + total += call.ResponseCost.Tokens + seen++ + } + } + if seen == 0 { + return nil + } + return &total +} + +// isDirectCell reports whether a cell is served by the direct enumeration +// surface โ€” the only pair whose call responses are identical, and therefore +// the only pair a cross-mode comparison can cancel the response term out of. +func isDirectCell(cell ModeCell) bool { return cell.RoutingMode == config.RoutingModeDirect } + +// withheldWorkloadReason states, per cell, why no absolute complete-workload +// figure is available โ€” and, for the cells that have no cross-mode delta +// either, why that is so. A withheld figure must always carry its reason: +// rendering it as a zero would read as "measured, and it cost nothing". +func withheldWorkloadReason(cell ModeCell, bodies replaycorpus.BodyPolicy) string { + // The reason MUST track the posture. A bodies-on run does carry response + // text, so telling the reader it is "absent" while the same row shows a + // response figure states a false premise next to the number that + // contradicts it. The figure is still not a complete workload โ€” a + // recording is a sample of one agent's traffic, not the whole of what a + // mode would cost โ€” but the reason for withholding is different, and + // saying so is the difference between an honest caveat and a wrong one. + base := "an absolute complete-workload cost includes every consumed response, and that text is absent from a bodies-off replay" + if bodies != replaycorpus.BodiesOff { + base = "this replay carries response bodies, so a response total is measurable โ€” but it is still not an absolute " + + "complete-workload cost: it prices the recorded traffic, not the workload a mode would incur in general, and any " + + "record whose cost was withheld or estimated is excluded from it" + } + if isDirectCell(cell) { + return base + "; the comparable figure for this cell is the " + CellDirectFull + " <-> " + CellDirectDeferred + + " delta, whose identical call responses cancel out of the comparison" + } + return base + "; no cross-mode delta is available for this cell either, because its serialization changes the response body โ€” " + + "the very text a bodies-off replay does not carry" +} + +// replayMenuArmName picks the arm that prices a cell's menu. +// +// Only the DIRECT cells use their own arm, and the reason is worth stating +// because the alternative looks more consistent and is wrong. The +// discovery-serialization axis (`tool_response_mode`: full vs compact) +// governs the retrieve_tools RESPONSE โ€” it is resolved by +// effectiveToolResponseMode, whose only production consumer is the +// retrieve_tools handler. It does not touch the built-in tool LISTING those +// cells put in the agent's context, which is served in full either way. So +// pricing retrieve_compact's menu with the compact arm would invent a saving +// the wire does not deliver. +// +// The consequence is deliberate and is itself a finding: bodies-off, +// retrieve_full and retrieve_compact have IDENTICAL menu cost, because the +// axis that separates them lives entirely in responses. +func replayMenuArmName(cell ModeCell) string { + if isDirectCell(cell) { + return cell.ArmName() + } + return baselineArmName +} + +// replayMenuTools returns what actually occupies the agent's context in a cell. +// +// Under the direct routing mode that is the WHOLE upstream fleet, enumerated; +// under the other modes it is mcpproxy's built-in catalog for that mode, and +// the fleet stays out of context โ€” which is the entire proposition being +// measured. +// +// One modelling gap, stated rather than hidden: the direct surface also +// registers describe_tool, which this menu does not include. It is one +// definition against the whole fleet and identical in both direct cells, so it +// cancels from the delta's numerator โ€” but savings is a ratio, so omitting it +// shrinks the denominator and biases the delta PERCENTAGE slightly upward. +// Treat the delta as a comparative instrument, not an absolute wire model. +func replayMenuTools(cell ModeCell, fleet *Corpus) []Tool { + if isDirectCell(cell) { + return fleet.Tools + } + return cell.ProxyTools() +} + +func replayMenuTokens(tk *Tokenizer, cell ModeCell, fleet *Corpus, available map[string]EncodingArm) (int, error) { + name := replayMenuArmName(cell) + arm := available[name] + if arm == nil { + return 0, fmt.Errorf("replay: mode cell %q needs the %q arm, which was not supplied", cell.ID, name) + } + tools := replayMenuTools(cell, fleet) + if len(tools) == 0 { + return 0, fmt.Errorf("replay: mode cell %q has an empty menu โ€” a zero menu cost would read as a measurement", cell.ID) + } + text, err := arm.EncodeListing(tools) + if err != nil { + return 0, fmt.Errorf("replay: mode cell %q: encode menu with arm %q: %w", cell.ID, name, err) + } + return tk.Count(text), nil +} + +// replayDirectDelta produces the honest bodies-off headline, or nothing. +// +// Nothing is the right answer when either direct cell is missing: a delta +// against an absent term is not a smaller delta, it is not a delta. +func replayDirectDelta(menuByCell map[string]int) *ReplayDirectDelta { + full, okFull := menuByCell[CellDirectFull] + deferred, okDeferred := menuByCell[CellDirectDeferred] + if !okFull || !okDeferred || full <= 0 { + return nil + } + delta := full - deferred + return &ReplayDirectDelta{ + FromCellID: CellDirectFull, + ToCellID: CellDirectDeferred, + // Computed, not measured: arithmetic over two measured menu costs. + Provenance: ProvenanceComputed, + DeltaTokens: delta, + DeltaPct: float64(delta) / float64(full) * 100, + } +} + +// replayFleetShape describes the fleet every figure is quoted for (IC-004). +// A saving quoted without its fleet shape is a saving quoted at an unstated +// fleet size, which is how spec 102 over-projected from a single corpus. +// +// The per-tool distribution is measured with the baseline arm โ€” the canonical +// full-definition rendering โ€” so mean and p95 are comparable with every other +// definition-size figure the benchmark publishes. +// It deliberately takes no recording: the shape describes the FLEET a figure +// is quoted for, and folding the recording into it would let a small recording +// look like a small fleet. +func replayFleetShape(tk *Tokenizer, opts ReplayOptions) (FleetShape, error) { + id := opts.FleetID + if id == "" { + id = opts.Fleet.Version + } + shape := FleetShape{ID: id, ToolCount: len(opts.Fleet.Tools)} + + arm := opts.Arms[baselineArmName] + if arm == nil { + return shape, fmt.Errorf("replay: the %q arm is required to describe the fleet shape", baselineArmName) + } + sizes := make([]int, 0, len(opts.Fleet.Tools)) + total := 0 + for _, tl := range opts.Fleet.Tools { + text, err := arm.EncodeTool(tl) + if err != nil { + return shape, fmt.Errorf("replay: fleet shape: encode tool %s: %w", tl.ToolID, err) + } + n := tk.Count(text) + sizes = append(sizes, n) + total += n + } + if len(sizes) > 0 { + shape.MeanDefinitionTokens = float64(total) / float64(len(sizes)) + sort.Ints(sizes) + shape.P95DefinitionTokens = intPercentile(sizes, 95) + } + return shape, nil +} + +// ValidateCounterfactual refuses a block that carries figures without its +// FR-004 label (T030/T031). +// +// It checks the label's SUBSTANCE, not merely its presence, because the +// failure mode is not an empty string โ€” it is a well-meaning summary that +// replaces the caveat with something that reads better and claims more. A +// label must name itself a counterfactual and say the behaviour was not +// observed; a block with no figures needs no label at all. +func (b *ReplayBlock) ValidateCounterfactual() error { + if b == nil { + return errors.New("replay block: nil block cannot carry the FR-004 counterfactual label") + } + if len(b.Cells) == 0 && b.DirectDelta == nil { + return nil + } + label := strings.ToLower(strings.TrimSpace(b.Counterfactual)) + if label == "" { + return errors.New("replay block: figures were emitted without the FR-004 counterfactual label โ€” " + + "a replay recomputes recorded traffic and must never be presented as observed agent behaviour") + } + for _, marker := range []string{"counterfactual", "not observed"} { + if !strings.Contains(label, marker) { + return fmt.Errorf("replay block: the counterfactual label must state %q; got %q", marker, b.Counterfactual) + } + } + return nil +} + +// ValidateExclusionBalance asserts the FR-003 accounting closes: the sessions +// that were dropped account exactly for supplied minus used. +// +// Without this the exclusion table is decorative โ€” present, plausible, and +// free to disagree with the numbers beside it. SC-008 asks for every exclusion +// to be counted, and a count nobody reconciles is how one goes missing. +func (b *ReplayBlock) ValidateExclusionBalance() error { + if b == nil { + return errors.New("replay block: nil block has no exclusion accounting") + } + dropping := map[string]bool{} + for _, reason := range replayDroppingReasons { + dropping[reason] = true + } + dropped := 0 + for _, ex := range b.Exclusions { + if dropping[ex.Reason] { + dropped += ex.Sessions + } + } + if want := b.SessionsSupplied - b.SessionsUsed; dropped != want { + return fmt.Errorf("replay block: %d sessions supplied minus %d used = %d, but the dropping exclusions account for %d", + b.SessionsSupplied, b.SessionsUsed, want, dropped) + } + return nil +} + +// ReplayReport wraps a replay block in the v2 report envelope. +// +// GeneratedAt is PINNED here rather than stamped (T029): a replay report's +// value is that two runs over the same inputs are byte-identical, and a +// wall-clock field defeats that check quietly. Corpora and Arms are present +// but empty โ€” replay measures no encoding arms over a corpus; it crosses the +// mode matrix, which is why it is a block rather than one more OfflineSection. +func ReplayReport(tk *Tokenizer, block *ReplayBlock) *ReportV2 { + return &ReportV2{ + ReportVersion: ReportVersion2, + GeneratedAt: ReplayGeneratedAt, + Tokenizer: TokenizerInfo{Name: tk.encoding, Caveat: TokenizerCaveatText}, + Corpora: []CorpusDescriptor{}, + Arms: []ArmResult{}, + Replay: block, + Provenance: map[string]string{ + // Section-level badges. The menu costs are measured; the delta is + // arithmetic over them and carries its own per-row badge, which is + // the whole reason per-row provenance exists (FR-013). + "replay": ProvenanceMeasured, + "replay_direct_delta": ProvenanceComputed, + }, + } +} diff --git a/bench/replay_test.go b/bench/replay_test.go new file mode 100644 index 000000000..f9e414130 --- /dev/null +++ b/bench/replay_test.go @@ -0,0 +1,596 @@ +package bench + +// replay_test.go โ€” Spec 103 US1 (T019/T020/T021/T030). +// +// These tests exist to hold four boundaries that the spec was corrected +// repeatedly to get right, and each of which is easy to cross by accident: +// +// 1. A recording alone computes NOTHING. A menu is a property of tool +// definitions and the activity export carries no fleet snapshot, so +// `-replay ` without a fleet input is a hard error, never a +// degraded run (T019). +// 2. No cell has an absolute complete-workload cost with bodies off, because +// complete workload includes every consumed response and that text is +// absent. Only the direct_full <-> direct_deferred delta survives, because +// their call responses are identical and cancel out of the comparison +// (T020). +// 3. Two runs over the same inputs are byte-identical once generated_at is +// pinned (T021, SC-002). +// 4. No replay figure may be emitted without its counterfactual label; FR-004 +// forbids presenting a replay as observed agent behaviour (T030). +// +// The arms are fakes, as in armrun_test.go: package bench cannot import +// bench/arms (arms imports bench), so an arm reaches replay as a structural +// EncodingArm and the tests supply their own. + +import ( + "encoding/json" + "errors" + "fmt" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/smart-mcp-proxy/mcpproxy-go/bench/replaycorpus" + "github.com/smart-mcp-proxy/mcpproxy-go/internal/contracts" +) + +// newFakeDeferred stands in for the direct_deferred arm: a strictly smaller +// rendering than the baseline, so the direct delta is non-zero and signed the +// way a real deferral is. +func newFakeDeferred() *fakeArm { + return &fakeArm{name: "direct_deferred", encode: func(t Tool) (string, error) { return t.Name, nil }} +} + +// newFakeCompactSig stands in for the compact_sig arm. Replay must NOT use it +// to price a menu โ€” the compact axis governs retrieve_tools RESPONSES, not the +// built-in tool listing โ€” but it has to be resolvable, because the mode matrix +// names it as retrieve_compact's arm. +func newFakeCompactSig() *fakeArm { + return &fakeArm{name: "compact_sig", encode: func(t Tool) (string, error) { return t.Name + "()", nil }} +} + +func replayArms() map[string]EncodingArm { + return map[string]EncodingArm{ + "baseline_json": newFakeBaseline(), + "direct_deferred": newFakeDeferred(), + "compact_sig": newFakeCompactSig(), + } +} + +// replayRecords is the fixture recording. It deliberately contains one of +// every shape the accounting has to survive: +// +// - ws-1: two top-level calls, one of which issued a sandbox SUB-CALL that +// carries no work_session_id of its own and joins by parent_id. A sum over +// session.Calls would miss it; only AllCalls sees it. +// - ws-2: a call against a tool that is not in the supplied fleet, so the +// session is unreplayable and must be dropped AND counted. +// - ws-3: a sensitive-flagged call, dropped and counted. +// - a quarantine_change record, which is not a call at all and must not +// inflate any unit of work. +func replayRecords() []contracts.ActivityRecord { + at := func(sec int) time.Time { return time.Date(2026, 3, 1, 12, 0, sec, 0, time.UTC) } + return []contracts.ActivityRecord{ + { + ID: "a1", Type: contracts.ActivityTypeToolCall, Timestamp: at(1), + WorkSessionID: "ws-1", RequestID: "req-1", + ServerName: "fs", ToolName: "read_file", Status: "success", + RequestBytes: 120, ResponseBytes: 4000, + }, + { + ID: "a2", Type: contracts.ActivityTypeToolCall, Timestamp: at(2), + WorkSessionID: "ws-1", RequestID: "req-2", + ServerName: "git", ToolName: "git_log", Status: "success", + RequestBytes: 90, ResponseBytes: 2200, + }, + { + // Sandbox sub-call: no work session of its own, joins via parent_id, + // and records both byte counts as zero the way production does. + ID: "a3", Type: contracts.ActivityTypeToolCall, Timestamp: at(3), + RequestID: "req-3", ParentID: "req-2", + ServerName: "time", ToolName: "get_current_time", Status: "success", + }, + { + ID: "a4", Type: contracts.ActivityTypeToolCall, Timestamp: at(4), + WorkSessionID: "ws-2", RequestID: "req-4", + ServerName: "gone", ToolName: "vanished", Status: "success", + RequestBytes: 10, ResponseBytes: 20, + }, + { + ID: "a5", Type: contracts.ActivityTypeToolCall, Timestamp: at(5), + WorkSessionID: "ws-3", RequestID: "req-5", + ServerName: "fs", ToolName: "read_file", Status: "success", + RequestBytes: 10, ResponseBytes: 20, HasSensitiveData: true, + }, + { + ID: "a6", Type: contracts.ActivityTypeQuarantineChange, Timestamp: at(6), + WorkSessionID: "ws-1", + }, + } +} + +// writeReplayRecording writes the fixture as activity JSONL into t.TempDir(). +// The directory matters: the loader refuses an input path inside the +// repository working tree, because replay inputs are raw recorded traffic and +// must never be committed. +func writeReplayRecording(t *testing.T, records []contracts.ActivityRecord) string { + t.Helper() + path := filepath.Join(t.TempDir(), "activity.jsonl") + var buf strings.Builder + for i := range records { + line, err := json.Marshal(records[i]) + if err != nil { + t.Fatalf("marshal record %d: %v", i, err) + } + buf.Write(line) + buf.WriteByte('\n') + } + if err := os.WriteFile(path, []byte(buf.String()), 0o600); err != nil { + t.Fatalf("write recording: %v", err) + } + return path +} + +func replayOptions(t *testing.T) ReplayOptions { + t.Helper() + return ReplayOptions{ + RecordingPath: writeReplayRecording(t, replayRecords()), + Fleet: runnerCorpus(), + FleetID: "corpus_test@1", + Arms: replayArms(), + Warnf: func(string, ...any) {}, + } +} + +// T019 โ€” a recording-only invocation is an ERROR, not a degraded run. Without +// a fleet there is no menu to cost, so there is nothing to degrade to. +func TestRunReplay_RecordingWithoutFleetIsHardError(t *testing.T) { + tk := runnerTokenizer(t) + opts := replayOptions(t) + opts.Fleet = nil + + block, err := RunReplay(tk, opts) + if err == nil { + t.Fatal("replay with no fleet input must fail: a menu is a property of the tool definitions, and the export carries no fleet snapshot") + } + if !errors.Is(err, ErrReplayFleetRequired) { + t.Fatalf("want ErrReplayFleetRequired, got %v", err) + } + if block != nil { + t.Fatalf("a refused replay must return no block, got %+v", block) + } +} + +// A fleet with no tools is the same failure wearing a different hat. +func TestRunReplay_EmptyFleetIsHardError(t *testing.T) { + tk := runnerTokenizer(t) + opts := replayOptions(t) + opts.Fleet = &Corpus{Version: "empty"} + + if _, err := RunReplay(tk, opts); !errors.Is(err, ErrReplayFleetRequired) { + t.Fatalf("want ErrReplayFleetRequired for an empty fleet, got %v", err) + } +} + +// T020 โ€” bodies off, NO cell may report an absolute complete-workload cost, +// and the only cross-mode figure produced is the direct_full <-> direct_deferred +// delta. +func TestRunReplay_NoAbsoluteWorkloadCostBodiesOff(t *testing.T) { + tk := runnerTokenizer(t) + block, err := RunReplay(tk, replayOptions(t)) + if err != nil { + t.Fatalf("RunReplay: %v", err) + } + + if block.BodiesIncluded { + t.Fatal("bodies-off is the default posture; the block must say so") + } + if len(block.Cells) != len(ModeCells()) { + t.Fatalf("want one row per mode cell (%d), got %d", len(ModeCells()), len(block.Cells)) + } + for _, cell := range block.Cells { + if !cell.AbsoluteWorkloadWithheld { + t.Errorf("cell %s: an absolute complete-workload cost is NOT available bodies-off โ€” every consumed response is missing", cell.CellID) + } + if strings.TrimSpace(cell.WithheldReason) == "" { + t.Errorf("cell %s: a withheld figure must carry its reason, never render as zero", cell.CellID) + } + if cell.ResponseTokens != nil { + t.Errorf("cell %s: response tokens must be absent bodies-off (byte lengths are not token counts), got %d", cell.CellID, *cell.ResponseTokens) + } + if cell.MenuTokens <= 0 { + t.Errorf("cell %s: menu cost IS measurable from the fleet input and must be populated", cell.CellID) + } + if cell.Provenance != ProvenanceMeasured { + t.Errorf("cell %s: menu cost is counted by the deterministic tokenizer over the supplied fleet, want %q, got %q", cell.CellID, ProvenanceMeasured, cell.Provenance) + } + } + + if block.DirectDelta == nil { + t.Fatal("the direct_full <-> direct_deferred delta IS measurable bodies-off (identical call responses cancel) and is the honest headline") + } + if block.DirectDelta.FromCellID != CellDirectFull || block.DirectDelta.ToCellID != CellDirectDeferred { + t.Errorf("delta must be %s -> %s, got %s -> %s", CellDirectFull, CellDirectDeferred, block.DirectDelta.FromCellID, block.DirectDelta.ToCellID) + } + if block.DirectDelta.Provenance != ProvenanceComputed { + t.Errorf("the delta is arithmetic over two measured menu costs, want %q, got %q", ProvenanceComputed, block.DirectDelta.Provenance) + } + if block.DirectDelta.DeltaTokens <= 0 { + t.Errorf("fixture deferral renders strictly less than the baseline; want a positive delta, got %d", block.DirectDelta.DeltaTokens) + } + + // The retrieve cells must state that no cross-mode delta is available to + // them either โ€” their serialization changes the RESPONSE body, which is + // exactly the text bodies-off does not have. + for _, cell := range block.Cells { + if cell.CellID != CellRetrieveFull && cell.CellID != CellRetrieveCompact { + continue + } + if !strings.Contains(cell.WithheldReason, "delta") { + t.Errorf("cell %s: the withheld reason must say why no cross-mode delta is available, got %q", cell.CellID, cell.WithheldReason) + } + } +} + +// Sub-calls hang off their parent and are absent from session.Calls by design. +// A replay that walked Calls would silently undercount the recorded workload. +func TestRunReplay_CountsSubCalls(t *testing.T) { + tk := runnerTokenizer(t) + block, err := RunReplay(tk, replayOptions(t)) + if err != nil { + t.Fatalf("RunReplay: %v", err) + } + for _, cell := range block.Cells { + if cell.Calls != 3 { + t.Fatalf("cell %s: want 3 recorded calls (2 top-level + 1 sandbox sub-call), got %d", cell.CellID, cell.Calls) + } + } +} + +// Every exclusion is counted and reported (FR-003, SC-008), and the sessions +// that were DROPPED account exactly for supplied minus used. +func TestRunReplay_ExclusionsAccountForEverySession(t *testing.T) { + tk := runnerTokenizer(t) + block, err := RunReplay(tk, replayOptions(t)) + if err != nil { + t.Fatalf("RunReplay: %v", err) + } + + if block.SessionsSupplied != 3 { + t.Errorf("want 3 supplied sessions (ws-1, ws-2, ws-3), got %d", block.SessionsSupplied) + } + if block.SessionsUsed != 1 { + t.Errorf("want 1 used session (ws-1), got %d", block.SessionsUsed) + } + if err := block.ValidateExclusionBalance(); err != nil { + t.Errorf("exclusion accounting does not balance: %v", err) + } + + counts := map[string]int{} + for _, ex := range block.Exclusions { + counts[ex.Reason] = ex.Sessions + } + if counts[ReplayExclusionSensitive] != 1 { + t.Errorf("want 1 session dropped as sensitive, got %d", counts[ReplayExclusionSensitive]) + } + if counts[ReplayExclusionUnreplayable] != 1 { + t.Errorf("want 1 session dropped as unreplayable, got %d", counts[ReplayExclusionUnreplayable]) + } + if counts[ReplayExclusionBodiesMissed] != 3 { + t.Errorf("bodies-off flags every supplied session; want 3, got %d", counts[ReplayExclusionBodiesMissed]) + } + if counts[ReplayExclusionUnattributed] != 1 { + t.Errorf("the quarantine_change record belongs to no unit of work; want 1, got %d", counts[ReplayExclusionUnattributed]) + } + if !block.SensitiveFlagBestEffort { + t.Error("the sensitive flag is derived from detection metadata written asynchronously AFTER persistence; the report must restate that it is a reducer, not a guarantee") + } +} + +// Replay ALWAYS has a fleet input, so the loader must always have been able to +// evaluate replayability. FleetChecked == false is a bug in this package's own +// wiring, not a property of the data โ€” and it would silently turn "nothing was +// unreplayable" into "replayability was never evaluated". +func TestRunReplay_AlwaysResolvesTheFleet(t *testing.T) { + opts := replayOptions(t) + corpus, err := replaycorpus.LoadFile(opts.RecordingPath, replaycorpus.Options{ + FleetResolver: FleetResolver(opts.Fleet), + Warnf: func(string, ...any) {}, + }) + if err != nil { + t.Fatalf("LoadFile: %v", err) + } + if !corpus.FleetChecked { + t.Fatal("FleetResolver must be wired for every replay load; an unchecked fleet reports 'nothing unreplayable' when it means 'never evaluated'") + } +} + +// T021 โ€” two runs over the same inputs are byte-identical (SC-002). The whole +// point of pinning generated_at is that this check means something. +func TestRunReplay_ByteIdenticalAcrossRuns(t *testing.T) { + tk := runnerTokenizer(t) + opts := replayOptions(t) + + render := func() []byte { + block, err := RunReplay(tk, opts) + if err != nil { + t.Fatalf("RunReplay: %v", err) + } + report := ReplayReport(tk, block) + data, err := json.MarshalIndent(report, "", " ") + if err != nil { + t.Fatalf("marshal: %v", err) + } + return data + } + + first, second := render(), render() + if string(first) != string(second) { + t.Fatal("two replay runs over identical inputs must be byte-identical") + } + if !strings.Contains(string(first), `"generated_at": "`+ReplayGeneratedAt+`"`) { + t.Fatalf("replay reports must pin generated_at to %q so SC-002's determinism check is meaningful; got:\n%s", ReplayGeneratedAt, first) + } + if ReplayGeneratedAt == GeneratedAtNow() { + t.Fatal("the pinned stamp must not be a wall-clock time") + } +} + +// T030 โ€” no replay figure may be emitted without the counterfactual marker. +func TestReplayBlock_RefusesFigureWithoutCounterfactualMarker(t *testing.T) { + tk := runnerTokenizer(t) + block, err := RunReplay(tk, replayOptions(t)) + if err != nil { + t.Fatalf("RunReplay: %v", err) + } + if err := block.ValidateCounterfactual(); err != nil { + t.Fatalf("a block built by RunReplay must already carry its label: %v", err) + } + + stripped := *block + stripped.Counterfactual = "" + if err := stripped.ValidateCounterfactual(); err == nil { + t.Fatal("a block carrying cells or a delta must be refused without its counterfactual label (FR-004)") + } + + mislabelled := *block + mislabelled.Counterfactual = "measured over a live agent session" + if err := mislabelled.ValidateCounterfactual(); err == nil { + t.Fatal("a label that presents replay as observed behaviour must be refused (FR-004)") + } +} + +// T031's substance: the label must say the three things a reader needs โ€” that +// the figures are a counterfactual, that no agent behaviour was observed, and +// that the recorded work is scored against the SUPPLIED fleet rather than the +// fleet as it stood when the session was recorded. +func TestReplayCounterfactualLabel_SaysWhatItMustSay(t *testing.T) { + label := strings.ToLower(ReplayCounterfactualLabel) + for _, want := range []string{"counterfactual", "not observed", "recorded", "supplied fleet"} { + if !strings.Contains(label, want) { + t.Errorf("the counterfactual label must mention %q; got: %s", want, ReplayCounterfactualLabel) + } + } +} + +// The replay block must satisfy the same emission-time contract as every other +// additive block: a populated accounting source and a provenance on every row. +func TestRunReplay_BlockPassesAdditiveBlockValidation(t *testing.T) { + tk := runnerTokenizer(t) + block, err := RunReplay(tk, replayOptions(t)) + if err != nil { + t.Fatalf("RunReplay: %v", err) + } + if block.AccountingSource.Kind != AccountingKindTokenizer { + t.Errorf("replay is counted by the deterministic tokenizer, want kind %q, got %q", AccountingKindTokenizer, block.AccountingSource.Kind) + } + if err := ReplayReport(tk, block).ValidateAdditiveBlocks(); err != nil { + t.Fatalf("ValidateAdditiveBlocks: %v", err) + } +} + +// The mode matrix names an arm per cell; a missing arm is a wiring bug and +// must fail loudly rather than quietly omitting a row. +func TestRunReplay_MissingArmIsAnError(t *testing.T) { + tk := runnerTokenizer(t) + opts := replayOptions(t) + delete(opts.Arms, "direct_deferred") + + if _, err := RunReplay(tk, opts); err == nil { + t.Fatal("a cell whose arm was not supplied must fail the run, not disappear from the report") + } +} + +// The fleet input decides the menu for the DIRECT cells (there the menu is the +// whole upstream fleet) and the built-in proxy catalog for the others. The +// discovery-serialization axis is invisible bodies-off, because it governs +// retrieve_tools RESPONSES rather than the built-in listing โ€” so the two +// retrieve cells must cost the same, and that sameness is a finding, not a bug. +func TestRunReplay_MenuCostsFollowTheSurface(t *testing.T) { + tk := runnerTokenizer(t) + block, err := RunReplay(tk, replayOptions(t)) + if err != nil { + t.Fatalf("RunReplay: %v", err) + } + menu := map[string]int{} + for _, cell := range block.Cells { + menu[cell.CellID] = cell.MenuTokens + } + if menu[CellRetrieveFull] != menu[CellRetrieveCompact] { + t.Errorf("the compact axis governs retrieve_tools responses, not the built-in menu; want equal menu costs, got %d vs %d", + menu[CellRetrieveFull], menu[CellRetrieveCompact]) + } + if menu[CellDirectDeferred] >= menu[CellDirectFull] { + t.Errorf("deferred direct rendering must cost less than full: %d vs %d", menu[CellDirectDeferred], menu[CellDirectFull]) + } + if block.FleetShape.ToolCount != len(runnerCorpus().Tools) { + t.Errorf("the fleet shape travels with every figure; want %d tools, got %d", len(runnerCorpus().Tools), block.FleetShape.ToolCount) + } +} + +// T032 โ€” the dashboard must render the replay block, and must put the +// exclusion report BEFORE the headline. Ordering is not decoration here: a +// figure computed over a third of the supplied sessions reads as a figure over +// all of them unless the reader meets the exclusions first. +func TestReplayDashboard_RendersExclusionsBeforeTheHeadline(t *testing.T) { + tk := runnerTokenizer(t) + block, err := RunReplay(tk, replayOptions(t)) + if err != nil { + t.Fatalf("RunReplay: %v", err) + } + path := filepath.Join(t.TempDir(), "dashboard.html") + if err := ReplayReport(tk, block).WriteHTML(path); err != nil { + t.Fatalf("WriteHTML: %v", err) + } + raw, err := os.ReadFile(path) //nolint:gosec // test-owned temp path + if err != nil { + t.Fatalf("read dashboard: %v", err) + } + html := string(raw) + + for _, want := range []string{ + "What did not count", + "Per-cell cost", + "COUNTERFACTUAL", + "not observed agent behaviour", + "today's fleet, not the fleet as it stood when the sessions were recorded", + "withheld", + CellDirectDeferred, + } { + if !strings.Contains(html, want) { + t.Errorf("dashboard is missing %q", want) + } + } + + exclusions := strings.Index(html, "What did not count") + headline := strings.Index(html, "Per-cell cost") + if exclusions < 0 || headline < 0 || exclusions > headline { + t.Errorf("the exclusion report must be readable BEFORE the per-cell headline (exclusions at %d, headline at %d)", exclusions, headline) + } + if strings.Contains(html, "http://") || strings.Contains(html, "https://") { + t.Error("the dashboard must stay self-contained: no external resource loads") + } +} + +// The replay block must validate against the reviewed contract schema, not +// merely against this package's own expectations. The schema has no +// additionalProperties:false and cannot require a field to be non-empty, so +// this check catches the shape errors the Go types cannot โ€” a reason outside +// the closed exclusion enum above all. +func TestReplayReport_SchemaValidationPython(t *testing.T) { + python, err := exec.LookPath("python3") + if err != nil { + t.Skip("python3 not available") + } + if err := exec.Command(python, "-c", "import jsonschema").Run(); err != nil { + t.Skip("python3 jsonschema module not available") + } + + tk := runnerTokenizer(t) + block, err := RunReplay(tk, replayOptions(t)) + if err != nil { + t.Fatalf("RunReplay: %v", err) + } + dir := t.TempDir() + reportPath, err := ReplayReport(tk, block).WriteJSON(dir) + if err != nil { + t.Fatalf("WriteJSON: %v", err) + } + schemaPath := filepath.Clean("../specs/083-discovery-profiler/contracts/report-v2.schema.json") + + script := fmt.Sprintf(` +import json, jsonschema +schema = json.load(open(%q)) +report = json.load(open(%q)) +jsonschema.validate(report, schema) +`, schemaPath, reportPath) + if out, err := exec.Command(python, "-c", script).CombinedOutput(); err != nil { + t.Fatalf("jsonschema validation failed: %v\n%s", err, out) + } +} + +// The withheld reason must track the POSTURE, not just the cell. +// +// This is the defect the adversarial verification pass caught: the reason was a +// pure function of the cell, so a bodies-on run printed "that text is absent +// from a bodies-off replay" in the very row that carried a response figure +// proving otherwise. A caveat that states a false premise is worse than none โ€” +// a reader who checks it against the number loses trust in both. +func TestRunReplay_WithheldReasonTracksTheBodiesPosture(t *testing.T) { + tk := runnerTokenizer(t) + off, err := RunReplay(tk, replayOptions(t)) + if err != nil { + t.Fatalf("bodies-off replay: %v", err) + } + for _, cell := range off.Cells { + if !strings.Contains(cell.WithheldReason, "absent from a bodies-off replay") { + t.Errorf("cell %s: bodies-off reason must say the text is absent, got %q", cell.CellID, cell.WithheldReason) + } + } + + optsOn := replayOptions(t) + optsOn.Bodies = replaycorpus.BodiesOnUnmasked + on, err := RunReplay(tk, optsOn) + if err != nil { + t.Fatalf("bodies-on replay: %v", err) + } + for _, cell := range on.Cells { + if strings.Contains(cell.WithheldReason, "absent from a bodies-off replay") { + t.Errorf("cell %s: a bodies-on run must NOT claim the response text is absent; got %q", cell.CellID, cell.WithheldReason) + } + if !cell.AbsoluteWorkloadWithheld { + t.Errorf("cell %s: an absolute complete-workload cost stays withheld even bodies-on", cell.CellID) + } + if strings.TrimSpace(cell.WithheldReason) == "" { + t.Errorf("cell %s: a withheld figure must always carry a reason", cell.CellID) + } + } +} + +// SC-008: a cost suppressed INSIDE an admitted session must still be reported. +// +// The session-level exclusion rows cannot express this โ€” they only count units +// of work that never got in. Without the loader-level accounting a withheld +// response cost collapses a cell's response total to nil and nothing anywhere +// says why, which is the silent accounting the criterion forbids. +func TestRunReplay_SurfacesLoaderLevelAccounting(t *testing.T) { + tk := runnerTokenizer(t) + at := func(sec int) time.Time { return time.Date(2026, 3, 1, 12, 0, sec, 0, time.UTC) } + records := append(replayRecords(), contracts.ActivityRecord{ + // An internal record whose stored response is LARGER than the one the + // agent consumed: admitted to its session, but its cost is withheld + // because tokenizing the stored text would overstate what was paid. + ID: "a-trunc", + Type: contracts.ActivityType("internal_tool_call"), + Timestamp: at(7), + WorkSessionID: "ws-1", + ToolName: "retrieve_tools", + Status: "success", + Response: "a stored response larger than the agent received", + ResponseTruncated: true, + ResponseBytes: 4096, + }) + + opts := replayOptions(t) + opts.RecordingPath = writeReplayRecording(t, records) + opts.Bodies = replaycorpus.BodiesOnUnmasked + + block, err := RunReplay(tk, opts) + if err != nil { + t.Fatalf("RunReplay: %v", err) + } + acc := block.LoaderAccounting + if acc == nil { + t.Fatal("loader accounting must be reported when the loader withheld, dropped or flagged anything") + } + if acc.CostsWithheld == 0 { + t.Errorf("a truncated internal record must be counted as a withheld cost, got %+v", acc) + } + if len(acc.Withheld) == 0 { + t.Error("a withheld cost must carry its reason, not just a total โ€” the total alone is not actionable") + } +} diff --git a/bench/replaycorpus/doc.go b/bench/replaycorpus/doc.go new file mode 100644 index 000000000..503a98172 --- /dev/null +++ b/bench/replaycorpus/doc.go @@ -0,0 +1,42 @@ +// Package replaycorpus loads exported mcpproxy activity JSONL +// (`mcpproxy activity export --format json`) into grouped units of work for the +// token benchmark's deterministic replay (Spec 103, US1). It groups records by +// work session, joins code-execution sub-calls to the call that issued them, +// and classifies every record's usability ONCE, at load. +// +// Two invariants define this package and must survive every future change: +// +// 1. IT IMPORTS NOTHING FROM `bench`. The sibling loader `bench/corpusio` +// imports `bench`, and `bench/replay.go` โ€” the consumer of this package โ€” +// lives in `bench`. If this package mirrored corpusio, that import would be +// a cycle and replay could not use it at all. So the replay domain types +// (ReplayCall, ReplaySession, Cost, Flags) are DEFINED HERE rather than +// borrowed, and the tokenizer is the tiktoken library used directly rather +// than bench.Tokenizer. Adding a `bench` import here does not produce a +// compile error in this package โ€” it breaks `bench/replay.go`, one package +// away, which is why the rule is stated rather than merely enforced by the +// build. +// +// 2. NO CONTENT CROSSES THIS BOUNDARY โ€” ONLY COUNTS. Replay inputs are raw +// recorded user traffic, and the activity EXPORT PATH DOES NOT MASK: +// maskActivityPayloads is wired into the list and detail handlers only, so a +// bodies-on export is unmasked by design. Therefore no exported type in this +// package has a field that holds a request body, a response body, arguments, +// or metadata; bodies exist only as local variables inside the load call +// that reads them. That is also why tokenization happens HERE +// (tokenize.go) rather than in the scoring layer: handing bodies out to be +// counted elsewhere would defeat the invariant, and the two cannot both +// hold. Bodies-off is the zero value, so an operator who never thinks about +// the flag gets the safe behaviour (privacy.go). +// +// A third rule is a property of the data rather than of the package, and +// flags.go is where it lives: A TRUNCATED RECORD MUST NEVER CONTRIBUTE +// SILENTLY. Understating cost is the one direction of error the whole benchmark +// exists to prevent, so a truncated record either carries an explicitly +// annotated estimate derived from its pre-truncation byte length, or is +// excluded and counted. Every exclusion is counted and reportable (FR-002, +// FR-003, SC-008): silence is never success. +// +// The binding contract for the input shape is +// specs/103-token-bench/contracts/replay-input.md. +package replaycorpus diff --git a/bench/replaycorpus/flags.go b/bench/replaycorpus/flags.go new file mode 100644 index 000000000..670840fdd --- /dev/null +++ b/bench/replaycorpus/flags.go @@ -0,0 +1,401 @@ +package replaycorpus + +import ( + "sort" + "time" +) + +// ExclusionReason names one reason a record, or one cost component of a record, +// could not contribute to a replay figure. It is a CLOSED vocabulary and a +// string type so a report can print it verbatim and so rows sort +// deterministically โ€” a replay report has to be byte-reproducible (SC-002), and +// a map's iteration order is not. +type ExclusionReason string + +const ( + // ReasonNotACall marks a record that is not a tool call at all โ€” a + // quarantine change, a policy decision, a server change. The activity log + // is wider than tool calls, so these arrive in every export and are + // dropped rather than counted as zero-cost calls. + ReasonNotACall ExclusionReason = "not_a_call" + + // ReasonMissingTool marks a call record with no tool name. It cannot be + // resolved against any mode's tool surface, so it can carry no menu cost. + ReasonMissingTool ExclusionReason = "missing_tool_name" + + // ReasonUnattributed marks a record with no work_session_id and no parent + // to inherit one from. The work session is the unit of work for US1, so an + // unattributed record belongs to no unit and is reported as such rather + // than being folded into an arbitrary one. + ReasonUnattributed ExclusionReason = "unattributed" + + // ReasonOrphanedSubCall marks a sub-call whose parent fell outside the + // exported window AND which carries no work_session_id of its own, so + // there is no unit of work left to attribute it to. + // + // It is separated from ReasonUnattributed on purpose. Both are records + // with no session, but they tell the operator different things: an + // unattributed record never had a session, whereas this one had a parent + // that the EXPORT WINDOW cut off. The second is fixable โ€” re-export with a + // wider window and the record comes back โ€” and folding it into the first + // would hide the one exclusion reason the operator can actually act on. + ReasonOrphanedSubCall ExclusionReason = "orphaned_sub_call" + + // ReasonTruncated marks a record whose stored response was cut at capture. + // It is a FLAG, not a drop: the record still contributes its call shape and + // an annotated byte-length estimate. It is counted so that no truncated + // record can contribute without the report saying so. + ReasonTruncated ExclusionReason = "truncated" + + // ReasonBodiesMissing marks a record loaded with bodies off โ€” the default. + // The content is absent, so no response cost is measurable, only estimated. + ReasonBodiesMissing ExclusionReason = "bodies_missing" + + // ReasonSensitive marks a record carrying the sensitive-data flag. This is + // a BEST-EFFORT reducer, never a guarantee: there is no persisted + // sensitivity field, the flag is derived at export from detection metadata + // added asynchronously AFTER the record is first persisted, so a freshly + // exported record may be sensitive and not yet flagged. Anything relying on + // it must say so (Principle IV, contracts/replay-input.md ยง4). + ReasonSensitive ExclusionReason = "sensitive" + + // ReasonUnreplayable marks a call whose tool no longer resolves against the + // supplied fleet. Only ever set when a fleet resolver was supplied โ€” with + // no fleet to resolve against, "unreplayable" would be an assertion the + // loader has no basis for. + ReasonUnreplayable ExclusionReason = "unreplayable" + + // ReasonNoByteCounts marks a response cost withheld because the record + // carries no pre-truncation byte length. Zero bytes means UNKNOWN, not + // free; treating it as free would silently understate the workload. + ReasonNoByteCounts ExclusionReason = "no_byte_counts" + + // ReasonInternalNoByteCounts is ReasonNoByteCounts for the specific, known + // gap: the internal tool-call emission never populates the byte fields, so + // EVERY built-in call (retrieve_tools above all) is unaccountable with + // bodies off. It has its own name because it is a systematic gap an + // operator should see as one line, not as noise inside a general bucket. + ReasonInternalNoByteCounts ExclusionReason = "internal_no_byte_counts" + + // ReasonSubCallZeroBytes is the second known gap: a code-execution sub-call + // records BOTH byte counts as zero (internal/server/mcp_code_execution.go), + // so a sandbox's sub-calls cannot use the byte-length estimate either. + ReasonSubCallZeroBytes ExclusionReason = "sub_call_zero_bytes" + + // ReasonTruncatedRetrieveOverstates is the asymmetry that makes truncated + // built-in records worse than useless. For an ordinary upstream call, + // truncation cuts the STORED text while the agent consumed the whole thing, + // so the pre-truncation byte length is an honest estimate. For + // retrieve_tools it is the other way round: the log stores the FULL + // response while the agent consumed the cut text, so both the stored text + // and the byte length describe something LARGER than what was paid for. + // Counting either would overstate mcpproxy's cost โ€” flattering, and still + // wrong โ€” so the cost is withheld and counted. The alternative permitted by + // the contract is to re-apply the recorded truncation limit before + // counting; that needs a limit the export does not carry, so exclusion is + // what is implementable here. + ReasonTruncatedRetrieveOverstates ExclusionReason = "truncated_retrieve_tools_overstates" +) + +// ExclusionRow is one line of an exclusion report: a reason and how many times +// it fired. Rows are what a report renders; the maps behind them are what the +// loader accumulates. +type ExclusionRow struct { + Reason ExclusionReason `json:"reason"` + Count int `json:"count"` +} + +// ExclusionReport accounts for everything that did NOT contribute, in three +// distinct senses that a single counter would blur: +// +// - Dropped โ€” records that entered no session at all. +// - Withheld โ€” RESPONSE costs suppressed on records that WERE admitted. Only +// the response side is counted: a request cost withheld on the same record +// has the same cause, is visible on the call's RequestCost, and counting it +// too would make "12 withheld" mean neither 12 records nor 12 responses. +// - Flagged โ€” records admitted and counted, but carrying a usability flag a +// report must surface beside the figure they contributed to. +// +// The distinction is load-bearing for FR-003/SC-008: "12 exclusions" means +// nothing if a dropped record, a suppressed response cost and a truncation +// annotation are all folded into one number. +type ExclusionReport struct { + Dropped map[ExclusionReason]int `json:"dropped,omitempty"` + Withheld map[ExclusionReason]int `json:"withheld,omitempty"` + Flagged map[ExclusionReason]int `json:"flagged,omitempty"` + + // OrphanedSubCalls counts sub-calls whose parent_id resolved to no + // request_id in the export โ€” typically because the parent code_execution + // fell outside the exported window. + // + // Two outcomes, and this counter spans BOTH so the attribution loss is + // visible either way: + // - the sub-call carries its own work_session_id: it is KEPT at top + // level, because dropping it would understate the workload; + // - it does not: there is no unit of work left to attribute it to, so it + // is dropped under ReasonOrphanedSubCall โ€” which is a DIFFERENT and + // more actionable reason than ReasonUnattributed, since a wider export + // window would recover it. + // Sandbox sub-calls commonly fall in the second case: they inherit their + // session from the parent, so losing the parent loses the session too. + OrphanedSubCalls int `json:"orphaned_sub_calls,omitempty"` +} + +func (r *ExclusionReport) drop(reason ExclusionReason) { bump(&r.Dropped, reason) } +func (r *ExclusionReport) withhold(reason ExclusionReason) { bump(&r.Withheld, reason) } +func (r *ExclusionReport) flag(reason ExclusionReason) { bump(&r.Flagged, reason) } + +func bump(m *map[ExclusionReason]int, reason ExclusionReason) { + if *m == nil { + *m = make(map[ExclusionReason]int) + } + (*m)[reason]++ +} + +// DroppedRows returns the dropped-record counts sorted by reason. +func (r *ExclusionReport) DroppedRows() []ExclusionRow { return rows(r.Dropped) } + +// WithheldRows returns the withheld cost-component counts sorted by reason. +func (r *ExclusionReport) WithheldRows() []ExclusionRow { return rows(r.Withheld) } + +// FlaggedRows returns the admitted-but-flagged counts sorted by reason. +func (r *ExclusionReport) FlaggedRows() []ExclusionRow { return rows(r.Flagged) } + +// TotalDropped is how many records entered no session. +func (r *ExclusionReport) TotalDropped() int { return total(r.Dropped) } + +// TotalWithheld is how many cost components were suppressed. +func (r *ExclusionReport) TotalWithheld() int { return total(r.Withheld) } + +// TotalFlagged is how many usability flags were raised across admitted records. +func (r *ExclusionReport) TotalFlagged() int { return total(r.Flagged) } + +func rows(m map[ExclusionReason]int) []ExclusionRow { + out := make([]ExclusionRow, 0, len(m)) + for reason, count := range m { + out = append(out, ExclusionRow{Reason: reason, Count: count}) + } + sort.Slice(out, func(i, j int) bool { return out[i].Reason < out[j].Reason }) + return out +} + +func total(m map[ExclusionReason]int) int { + sum := 0 + for _, count := range m { + sum += count + } + return sum +} + +// Flags is the usability classification of a call or a session, computed once +// at load and never re-derived downstream. A session's flags are the union of +// its calls': one truncated call makes the whole unit of work suspect, because +// the unit's total is what a report quotes. +type Flags struct { + Truncated bool `json:"truncated,omitempty"` + BodiesMissing bool `json:"bodies_missing,omitempty"` + Sensitive bool `json:"sensitive,omitempty"` + Unreplayable bool `json:"unreplayable,omitempty"` +} + +// Usable reports whether nothing is wrong with this call or session. It is +// deliberately strict โ€” a caller that wants to use a partly-flagged session +// must look at WHICH flag is set and say so in its report, rather than +// consulting one boolean. +func (f Flags) Usable() bool { return f == Flags{} } + +// Reasons lists the set flags as exclusion reasons, in a fixed order, so a +// report can print why a session is not usable without re-deriving anything. +func (f Flags) Reasons() []ExclusionReason { + var out []ExclusionReason + if f.Truncated { + out = append(out, ReasonTruncated) + } + if f.BodiesMissing { + out = append(out, ReasonBodiesMissing) + } + if f.Sensitive { + out = append(out, ReasonSensitive) + } + if f.Unreplayable { + out = append(out, ReasonUnreplayable) + } + return out +} + +func (f *Flags) merge(other Flags) { + f.Truncated = f.Truncated || other.Truncated + f.BodiesMissing = f.BodiesMissing || other.BodiesMissing + f.Sensitive = f.Sensitive || other.Sensitive + f.Unreplayable = f.Unreplayable || other.Unreplayable +} + +// CostBasis is the provenance of one cost figure. The three values must never +// be presented interchangeably: FR-013 requires measured and estimated figures +// to coexist inside one block, which only works if each carries its own basis. +type CostBasis string + +const ( + // CostMeasured means the text was tokenized inside this package. Only + // reachable with bodies on. + CostMeasured CostBasis = "measured" + + // CostEstimated means the figure is derived from a pre-truncation BYTE + // LENGTH. Byte lengths are not token counts; this is an estimate and must + // be labelled as one wherever it appears. + CostEstimated CostBasis = "estimated" + + // CostUnavailable means no honest figure exists. It is reported as + // unavailable with a Reason โ€” never as zero, which would read as a free + // call and understate the workload. + CostUnavailable CostBasis = "unavailable" +) + +// Cost is one accounted cost component of a call: its request, or its response. +type Cost struct { + Basis CostBasis `json:"basis"` + + // Tokens is populated only when Basis is CostMeasured. An estimate carries + // no token count on purpose: converting bytes to tokens here would hide the + // conversion's assumptions inside a number that looks measured. + Tokens int `json:"tokens,omitempty"` + + // Bytes is the pre-truncation byte LENGTH, populated for measured and + // estimated figures alike so a report can show the basis it worked from. + Bytes int `json:"bytes,omitempty"` + + // Truncated marks an estimate taken from a record whose stored content was + // cut. This is the annotation that keeps FR-002 honest: a truncated record + // may contribute, but never silently. + Truncated bool `json:"truncated,omitempty"` + + // Reason explains a CostUnavailable figure. Empty otherwise. + Reason ExclusionReason `json:"reason,omitempty"` +} + +// ReplayCall is one recorded tool call. It carries identity, sizes and derived +// measurements โ€” and, by construction, NO content: see the package doc's second +// invariant. +type ReplayCall struct { + ID string `json:"id"` + RequestID string `json:"request_id,omitempty"` + ParentID string `json:"parent_id,omitempty"` + ServerName string `json:"server_name,omitempty"` + ToolName string `json:"tool_name,omitempty"` + Status string `json:"status,omitempty"` + Timestamp time.Time `json:"timestamp"` + + // Internal marks a built-in proxy tool call (retrieve_tools, call_tool_*, + // code_execution) as opposed to an upstream one. It decides which + // byte-coverage gap applies and whether the truncation asymmetry bites. + Internal bool `json:"internal,omitempty"` + + // RequestBytes and ResponseBytes are byte LENGTHS measured pre-truncation, + // NOT token counts. Zero means unknown, not free. + RequestBytes int `json:"request_bytes,omitempty"` + ResponseBytes int `json:"response_bytes,omitempty"` + + Flags Flags `json:"flags,omitempty"` + RequestCost Cost `json:"request_cost"` + ResponseCost Cost `json:"response_cost"` + + // SubCalls are the calls a code_execution sandbox issued, joined by + // parent_id. They live here and NOT in their session's top-level Calls, so + // that a naive sum over Calls cannot double-count them. + SubCalls []*ReplayCall `json:"sub_calls,omitempty"` +} + +// classify computes the usability flags for one call and records them in the +// exclusion report. It runs exactly once, during load; nothing downstream +// re-derives a flag, because a second derivation is a second chance to disagree +// with the first. +func (c *ReplayCall) classify(rec *decodedRecord, opts *Options, rep *ExclusionReport) { + if rec.truncated { + c.Flags.Truncated = true + rep.flag(ReasonTruncated) + } + if opts.Bodies == BodiesOff { + c.Flags.BodiesMissing = true + rep.flag(ReasonBodiesMissing) + } + if rec.sensitive { + c.Flags.Sensitive = true + rep.flag(ReasonSensitive) + } + // Only assertable against a supplied fleet. With no resolver the honest + // answer is "not checked", not "replayable". + if opts.FleetResolver != nil && !opts.FleetResolver(c.ServerName, c.ToolName) { + c.Flags.Unreplayable = true + rep.flag(ReasonUnreplayable) + } +} + +// responseCost decides what, if anything, this record's response may contribute, +// and records any withholding. The ordering of the branches IS the policy: +// +// 1. A flagged-sensitive body is never tokenized, whatever the body policy. +// 2. A truncated built-in response is excluded outright โ€” both its stored text +// and its byte length describe more than the agent consumed. +// 3. An untruncated body, with bodies on, is measured. +// 4. Anything else falls back to the pre-truncation byte length as an +// explicitly annotated estimate. +// 5. With no byte length there is no honest figure: unavailable, and counted +// under the specific gap that caused it. +func responseCost(rec *decodedRecord, isSubCall bool, opts *Options, count func(string) int, rep *ExclusionReport) Cost { + bodiesOn := opts.Bodies == BodiesOnUnmasked + + if rec.sensitive && bodiesOn { + rep.withhold(ReasonSensitive) + return Cost{Basis: CostUnavailable, Reason: ReasonSensitive} + } + if rec.truncated && rec.internal { + rep.withhold(ReasonTruncatedRetrieveOverstates) + return Cost{Basis: CostUnavailable, Reason: ReasonTruncatedRetrieveOverstates} + } + if bodiesOn && !rec.truncated && rec.response != "" { + return Cost{Basis: CostMeasured, Tokens: count(rec.response), Bytes: len(rec.response)} + } + if rec.responseBytes > 0 { + return Cost{Basis: CostEstimated, Bytes: rec.responseBytes, Truncated: rec.truncated} + } + reason := byteGapReason(rec, isSubCall) + rep.withhold(reason) + return Cost{Basis: CostUnavailable, Reason: reason} +} + +// requestCost is responseCost for the arguments side. It is simpler because the +// truncation asymmetry does not apply โ€” arguments are recorded whole โ€” but it +// obeys the same sensitive-body and unknown-bytes rules. +// It does not bump the exclusion report โ€” see ExclusionReport.Withheld for why +// the response side is the one that is counted โ€” but an unavailable request +// cost still carries its Reason, so nothing about it is silent. +func requestCost(rec *decodedRecord, isSubCall bool, opts *Options, count func(string) int) Cost { + bodiesOn := opts.Bodies == BodiesOnUnmasked + + if rec.sensitive && bodiesOn { + return Cost{Basis: CostUnavailable, Reason: ReasonSensitive} + } + if bodiesOn && rec.arguments != "" { + return Cost{Basis: CostMeasured, Tokens: count(rec.arguments), Bytes: len(rec.arguments)} + } + if rec.requestBytes > 0 { + return Cost{Basis: CostEstimated, Bytes: rec.requestBytes} + } + return Cost{Basis: CostUnavailable, Reason: byteGapReason(rec, isSubCall)} +} + +// byteGapReason names WHICH known gap left this record without a byte length. +// The two systematic gaps get their own names so an operator reading the +// exclusion report sees "every built-in call" and "every sandbox sub-call" as +// two facts about the recording pipeline, rather than one undifferentiated pile +// that looks like data loss. +func byteGapReason(rec *decodedRecord, isSubCall bool) ExclusionReason { + switch { + case isSubCall: + return ReasonSubCallZeroBytes + case rec.internal: + return ReasonInternalNoByteCounts + default: + return ReasonNoByteCounts + } +} diff --git a/bench/replaycorpus/flags_test.go b/bench/replaycorpus/flags_test.go new file mode 100644 index 000000000..df189f662 --- /dev/null +++ b/bench/replaycorpus/flags_test.go @@ -0,0 +1,256 @@ +package replaycorpus + +import ( + "fmt" + "strings" + "testing" +) + +// record builds one JSONL line from the fields a flag test cares about. +func record(t *testing.T, fields map[string]any) string { + t.Helper() + base := map[string]any{ + "id": "rec-1", + "type": "tool_call", + "server_name": "github", + "tool_name": "list_issues", + "status": "success", + "work_session_id": "ws-1", + "request_id": "req-1", + "timestamp": "2026-08-01T10:00:00Z", + } + for k, v := range fields { + base[k] = v + } + return marshalLine(t, base) +} + +func firstCall(t *testing.T, c *Corpus) *ReplayCall { + t.Helper() + if len(c.Sessions) != 1 { + t.Fatalf("len(Sessions) = %d, want 1", len(c.Sessions)) + } + all := c.Sessions[0].AllCalls() + if len(all) == 0 { + t.Fatal("session has no calls") + } + return all[0] +} + +// A truncated record must never contribute silently (FR-002, SC-008). With a +// pre-truncation byte length it contributes an ANNOTATED estimate; without one +// it contributes nothing and is counted. It is never measured. +func TestTruncatedRecordNeverContributesSilently_WithBytes(t *testing.T) { + c := loadString(t, record(t, map[string]any{ + "response_truncated": true, + "response_bytes": 8192, + }), testOptions(t.TempDir())) + + call := firstCall(t, c) + if !call.Flags.Truncated { + t.Error("call is not flagged truncated") + } + if !c.Sessions[0].Usability.Truncated { + t.Error("session is not flagged truncated") + } + if call.ResponseCost.Basis != CostEstimated { + t.Fatalf("ResponseCost.Basis = %s, want %s", call.ResponseCost.Basis, CostEstimated) + } + if !call.ResponseCost.Truncated { + t.Error("the estimate is not annotated as coming from a truncated record") + } + if call.ResponseCost.Tokens != 0 { + t.Errorf("an estimate must carry no token count, got %d", call.ResponseCost.Tokens) + } + if got := c.Exclusions.Flagged[ReasonTruncated]; got != 1 { + t.Errorf("Flagged[%s] = %d, want 1", ReasonTruncated, got) + } +} + +func TestTruncatedRecordNeverContributesSilently_WithoutBytes(t *testing.T) { + c := loadString(t, record(t, map[string]any{ + "response_truncated": true, + }), testOptions(t.TempDir())) + + call := firstCall(t, c) + if call.ResponseCost.Basis != CostUnavailable { + t.Fatalf("ResponseCost.Basis = %s, want %s", call.ResponseCost.Basis, CostUnavailable) + } + if c.Exclusions.Withheld[ReasonNoByteCounts] != 1 { + t.Errorf("Withheld[%s] = %d, want 1", ReasonNoByteCounts, c.Exclusions.Withheld[ReasonNoByteCounts]) + } + if c.Exclusions.TotalWithheld() == 0 { + t.Error("withholding a response cost was not counted anywhere") + } +} + +// Known byte-coverage gap 1: the internal retrieve_tools emission carries no +// byte counts at all, so bodies-off it falls to exclusion accounting โ€” never to +// a zero that would read as a free call. +func TestInternalRetrieveToolsHasNoByteCounts(t *testing.T) { + c := loadString(t, record(t, map[string]any{ + "id": "rt-1", + "type": "internal_tool_call", + "tool_name": "retrieve_tools", + "server_name": "", + }), testOptions(t.TempDir())) + + call := firstCall(t, c) + if call.ResponseCost.Basis != CostUnavailable { + t.Fatalf("Basis = %s, want %s", call.ResponseCost.Basis, CostUnavailable) + } + if call.ResponseCost.Reason != ReasonInternalNoByteCounts { + t.Errorf("Reason = %s, want %s", call.ResponseCost.Reason, ReasonInternalNoByteCounts) + } + if c.Exclusions.Withheld[ReasonInternalNoByteCounts] != 1 { + t.Errorf("the gap was not counted: %+v", c.Exclusions.Withheld) + } +} + +// Known byte-coverage gap 2: code-execution sub-calls emit BOTH byte counts as +// zero, so a sub-call is unaccountable bodies-off for a different reason and +// must be reported under its own name. +func TestCodeExecutionSubCallZeroBytesIsExcluded(t *testing.T) { + parent := record(t, map[string]any{ + "id": "p", "type": "internal_tool_call", "tool_name": "code_execution", + "server_name": "", "request_id": "req-parent", + }) + sub := record(t, map[string]any{ + "id": "s", "request_id": "req-sub", "parent_id": "req-parent", + "request_bytes": 0, "response_bytes": 0, + }) + c := loadString(t, parent+"\n"+sub, testOptions(t.TempDir())) + + subCall := c.Sessions[0].Calls[0].SubCalls[0] + if subCall.ResponseCost.Basis != CostUnavailable { + t.Fatalf("Basis = %s, want %s", subCall.ResponseCost.Basis, CostUnavailable) + } + if subCall.ResponseCost.Reason != ReasonSubCallZeroBytes { + t.Errorf("Reason = %s, want %s", subCall.ResponseCost.Reason, ReasonSubCallZeroBytes) + } + if c.Exclusions.Withheld[ReasonSubCallZeroBytes] == 0 { + t.Errorf("the sub-call gap was not counted: %+v", c.Exclusions.Withheld) + } +} + +func TestBodiesMissingIsFlaggedWhenBodiesOff(t *testing.T) { + c := loadString(t, record(t, map[string]any{"response_bytes": 10}), testOptions(t.TempDir())) + call := firstCall(t, c) + if !call.Flags.BodiesMissing { + t.Error("bodies-off load did not flag bodies_missing on the call") + } + if !c.Sessions[0].Usability.BodiesMissing { + t.Error("bodies-off load did not flag bodies_missing on the session") + } + if c.Exclusions.Flagged[ReasonBodiesMissing] != 1 { + t.Errorf("bodies_missing was not counted: %+v", c.Exclusions.Flagged) + } +} + +func TestSensitiveIsFlaggedAndCounted(t *testing.T) { + c := loadString(t, record(t, map[string]any{ + "has_sensitive_data": true, + "response_bytes": 100, + }), testOptions(t.TempDir())) + + call := firstCall(t, c) + if !call.Flags.Sensitive { + t.Error("call is not flagged sensitive") + } + if !c.Sessions[0].Usability.Sensitive { + t.Error("session is not flagged sensitive") + } + if c.Exclusions.Flagged[ReasonSensitive] != 1 { + t.Errorf("sensitive was not counted: %+v", c.Exclusions.Flagged) + } +} + +func TestUnreplayableToolIsFlaggedAndCounted(t *testing.T) { + opts := testOptions(t.TempDir()) + opts.FleetResolver = func(server, tool string) bool { return server == "github" && tool == "list_issues" } + + c := loadString(t, record(t, map[string]any{"tool_name": "gone_tool"}), opts) + call := firstCall(t, c) + if !call.Flags.Unreplayable { + t.Error("call referencing a tool absent from the fleet is not flagged unreplayable") + } + if !c.Sessions[0].Usability.Unreplayable { + t.Error("session is not flagged unreplayable") + } + if c.Exclusions.Flagged[ReasonUnreplayable] != 1 { + t.Errorf("unreplayable was not counted: %+v", c.Exclusions.Flagged) + } + if !c.FleetChecked { + t.Error("FleetChecked is false although a resolver was supplied") + } +} + +func TestUnreplayableIsNotClaimedWithoutAFleetInput(t *testing.T) { + c := loadString(t, record(t, map[string]any{"tool_name": "gone_tool"}), testOptions(t.TempDir())) + if c.FleetChecked { + t.Error("FleetChecked is true although no resolver was supplied") + } + if firstCall(t, c).Flags.Unreplayable { + t.Error("unreplayable was asserted without a fleet to resolve against") + } +} + +func TestExclusionRowsAreDeterministic(t *testing.T) { + rep := ExclusionReport{ + Dropped: map[ExclusionReason]int{ + ReasonUnattributed: 2, + ReasonNotACall: 1, + ReasonMissingTool: 3, + }, + } + want := fmt.Sprint(rep.DroppedRows()) + for i := 0; i < 20; i++ { + if got := fmt.Sprint(rep.DroppedRows()); got != want { + t.Fatalf("DroppedRows() is not deterministic: %s != %s", got, want) + } + } + rows := rep.DroppedRows() + for i := 1; i < len(rows); i++ { + if rows[i-1].Reason >= rows[i].Reason { + t.Fatalf("rows are not sorted by reason: %v", rows) + } + } +} + +func TestUsabilityFlagsAreComputedOnceAtLoad(t *testing.T) { + // Flags are data on the loaded value, not a re-derivation: reading them + // twice cannot change them, and nothing downstream needs the record to + // re-classify (data-model.md, "computed once at load"). + c := loadString(t, record(t, map[string]any{"response_truncated": true, "response_bytes": 5}), testOptions(t.TempDir())) + before := c.Sessions[0].Usability + + // Assert the EXPECTED initial state before testing stability. Without this + // the test is vacuous: delete load-time classification entirely and + // before == after == Flags{}, so "nothing changed" still passes and the + // test reports green on a loader that classifies nothing at all. + if !before.Truncated { + t.Fatalf("load-time classification must already have set Truncated, got %+v", before) + } + + _ = c.Sessions[0].AllCalls() + if c.Sessions[0].Usability != before { + t.Error("usability flags changed after a downstream read") + } +} + +func TestFlagsUsableReportsTheReasons(t *testing.T) { + f := Flags{Truncated: true, Sensitive: true} + if f.Usable() { + t.Error("Usable() is true for a truncated, sensitive session") + } + reasons := f.Reasons() + if len(reasons) != 2 { + t.Fatalf("Reasons() = %v, want 2 entries", reasons) + } + if !strings.Contains(fmt.Sprint(reasons), string(ReasonTruncated)) { + t.Errorf("Reasons() = %v, missing %s", reasons, ReasonTruncated) + } + if (Flags{}).Usable() != true { + t.Error("a clean session is not Usable()") + } +} diff --git a/bench/replaycorpus/group.go b/bench/replaycorpus/group.go new file mode 100644 index 000000000..37feea295 --- /dev/null +++ b/bench/replaycorpus/group.go @@ -0,0 +1,156 @@ +package replaycorpus + +import ( + "sort" + "time" +) + +// ReplaySession is one unit of real recorded work: everything that shares a +// work_session_id (spec 082 โ€” one client, one project, across reconnects). +// That, not the transport session, is the unit US1 scores, because a transport +// session is regenerated on every reconnect and would split one piece of work +// into several. +type ReplaySession struct { + WorkSessionID string `json:"work_session_id"` + + // Calls holds the TOP-LEVEL calls only. Code-execution sub-calls hang off + // their parent's SubCalls, so summing over Calls cannot double-count them + // and AllCalls is the single way to see every record exactly once. + Calls []*ReplayCall `json:"calls"` + + // Usability is the union of the calls' flags, computed once at load. It is + // a union because a report quotes the SESSION total: one truncated call + // makes that total suspect, so the session has to say so. + Usability Flags `json:"usability,omitempty"` + + CallCount int `json:"call_count"` + SubCallCount int `json:"sub_call_count,omitempty"` + + FirstSeen time.Time `json:"first_seen"` + LastSeen time.Time `json:"last_seen"` +} + +// Span is the wall-clock extent of the session, first record to last. +func (s *ReplaySession) Span() time.Duration { return s.LastSeen.Sub(s.FirstSeen) } + +// AllCalls returns every call in the session โ€” parents followed by their +// sub-calls โ€” each exactly once. It is the accessor anything that sums or +// counts should use: walking Calls alone misses sandbox sub-calls, and walking +// a flattened list built by hand is how they come to be counted twice. +func (s *ReplaySession) AllCalls() []*ReplayCall { + out := make([]*ReplayCall, 0, s.CallCount+s.SubCallCount) + for _, call := range s.Calls { + out = append(out, call) + out = append(out, call.SubCalls...) + } + return out +} + +// group assembles decoded calls into sessions. +// +// The join is the delicate part. A code-execution sub-call is recorded with the +// issuing call's request_id in its parent_id, and โ€” being issued inside a +// sandbox rather than by the client โ€” it may carry no work_session_id of its +// own. So the pass has to run in two stages: index every call by request_id +// first, then attach children, because the export is not guaranteed to present +// a parent before its children. A child that finds its parent is attributed to +// the PARENT's session and appears only under it; a child that does not is kept +// at top level and counted as orphaned, since dropping it would understate the +// workload and silently promoting it would misattribute it. +func group(calls []*ReplayCall, sessions map[string]string, rep *ExclusionReport) []*ReplaySession { + byRequestID := make(map[string]*ReplayCall, len(calls)) + for _, call := range calls { + if call.RequestID == "" { + continue + } + // First wins: a duplicate request_id is not expected, and preferring + // the first keeps the result a function of input order alone. + if _, exists := byRequestID[call.RequestID]; !exists { + byRequestID[call.RequestID] = call + } + } + + topLevel := make([]*ReplayCall, 0, len(calls)) + owner := make(map[*ReplayCall]string, len(calls)) + orphaned := make(map[*ReplayCall]bool) + for _, call := range calls { + if call.ParentID != "" { + if parent, ok := byRequestID[call.ParentID]; ok && parent != call { + parent.SubCalls = append(parent.SubCalls, call) + continue + } + // The parent fell outside the exported window. Keep the call at + // top level if it can stand alone; remember that it is an orphan + // either way, so a drop below is attributed to the export window + // rather than to the record simply having no session. + rep.OrphanedSubCalls++ + orphaned[call] = true + } + topLevel = append(topLevel, call) + owner[call] = sessions[call.ID] + } + + grouped := make(map[string]*ReplaySession) + var order []string + for _, call := range topLevel { + workSessionID := owner[call] + if workSessionID == "" { + // No work session, and no parent to inherit one from: the record + // belongs to no unit of work. Reported, not folded in. + // + // An orphan lands here whenever the export window cut its parent, + // which is the common case for sandbox sub-calls: they inherit + // their session from the parent, so losing one loses the other. + // It gets its own reason because it is the actionable one โ€” a + // wider re-export brings the record back. + if orphaned[call] { + rep.drop(ReasonOrphanedSubCall) + } else { + rep.drop(ReasonUnattributed) + } + continue + } + session, ok := grouped[workSessionID] + if !ok { + session = &ReplaySession{WorkSessionID: workSessionID} + grouped[workSessionID] = session + order = append(order, workSessionID) + } + session.Calls = append(session.Calls, call) + } + + out := make([]*ReplaySession, 0, len(order)) + for _, workSessionID := range order { + session := grouped[workSessionID] + finalize(session) + out = append(out, session) + } + // Deterministic ordering: a replay report must be byte-reproducible + // (SC-002), so the session list cannot depend on map iteration. Earliest + // first, id as the tie-break. + sort.SliceStable(out, func(i, j int) bool { + if !out[i].FirstSeen.Equal(out[j].FirstSeen) { + return out[i].FirstSeen.Before(out[j].FirstSeen) + } + return out[i].WorkSessionID < out[j].WorkSessionID + }) + return out +} + +// finalize computes the derived counts, the span and the union of flags for one +// assembled session. +func finalize(s *ReplaySession) { + s.CallCount = len(s.Calls) + for _, call := range s.Calls { + s.SubCallCount += len(call.SubCalls) + } + for _, call := range s.AllCalls() { + s.Usability.merge(call.Flags) + if s.FirstSeen.IsZero() || call.Timestamp.Before(s.FirstSeen) { + s.FirstSeen = call.Timestamp + } + if call.Timestamp.After(s.LastSeen) { + s.LastSeen = call.Timestamp + } + } +} diff --git a/bench/replaycorpus/load.go b/bench/replaycorpus/load.go new file mode 100644 index 000000000..04529fe0d --- /dev/null +++ b/bench/replaycorpus/load.go @@ -0,0 +1,317 @@ +package replaycorpus + +import ( + "bufio" + "encoding/json" + "fmt" + "io" + "os" + "path/filepath" + "strings" + "time" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/contracts" +) + +// Options configures a load. Its ZERO VALUE is the safe, documented default: +// bodies off, no fleet resolution claimed, warnings to stderr, the repository +// root discovered from the working directory. +type Options struct { + // Bodies selects whether recorded request and response bodies are read. + // The zero value is BodiesOff โ€” see BodyPolicy for why that direction. + Bodies BodyPolicy + + // Encoding is the tiktoken encoding used to count bodies on a bodies-on + // load. Empty means DefaultEncoding. Ignored with bodies off, where there + // is nothing to count. + Encoding string + + // Warnf receives operator-facing warnings. Nil means stderr. Every warning + // is also appended to Corpus.Warnings, so a caller that renders a report + // does not have to intercept the printing to know a warning fired. + Warnf func(format string, args ...any) + + // FleetResolver answers whether a recorded (server, tool) still exists in + // the fleet a replay will score against. Nil means NO FLEET WAS SUPPLIED, + // and the loader then refuses to assert either replayability or its + // absence โ€” Corpus.FleetChecked says which happened. A replay run needs a + // fleet input regardless (a recording-only invocation computes nothing); + // this field is how that fleet reaches the usability classification. + FleetResolver func(serverName, toolName string) bool + + // repoRoot overrides the discovered repository working tree. Unexported + // because it exists for tests, which must exercise the refusal without + // writing a file into the real checkout to be refused. + repoRoot string + + // counter overrides the tiktoken counter. Unexported for the reason given + // in tokenize.go: an exported hook would hand body text to a caller outside + // this package, which is the invariant tokenizing here protects. + counter tokenCounter +} + +// Corpus is the loader's whole output: grouped sessions, the accounting for +// everything that did not contribute, and the posture the load ran under. It +// carries counts and identities โ€” never content. +type Corpus struct { + Sessions []*ReplaySession `json:"sessions"` + Exclusions ExclusionReport `json:"exclusions"` + + // Bodies and Encoding record the posture this corpus was produced under, so + // a report can state it rather than assume it. Encoding is empty with + // bodies off, where nothing was tokenized. + Bodies BodyPolicy `json:"bodies"` + Encoding string `json:"encoding,omitempty"` + + // RecordsRead is every line decoded, including those later dropped. It is + // the denominator an exclusion report is read against. + RecordsRead int `json:"records_read"` + + // FleetChecked reports whether a fleet resolver was supplied. False means + // the `unreplayable` flag was never evaluated โ€” not that nothing was + // unreplayable. + FleetChecked bool `json:"fleet_checked"` + + // Warnings mirrors everything sent to Options.Warnf. + Warnings []string `json:"warnings,omitempty"` +} + +// TotalCalls counts every call in every session, sub-calls included, each once. +func (c *Corpus) TotalCalls() int { + total := 0 + for _, session := range c.Sessions { + total += session.CallCount + session.SubCallCount + } + return total +} + +// LoadFile loads a replay input from disk. +// +// The path is refused BEFORE it is opened if it lies inside the repository +// working tree, and refused if it names a CSV export. Both checks precede I/O +// on purpose: the first is a privacy rule that must not depend on the file +// existing, and the second saves an operator from a confusing parse error when +// the real problem is the export format. +func LoadFile(path string, opts Options) (*Corpus, error) { + repoRoot := opts.repoRoot + if repoRoot == "" { + wd, err := os.Getwd() + if err != nil { + return nil, fmt.Errorf("resolve working directory to locate the repository root: %w", err) + } + repoRoot = detectRepositoryRoot(wd) + } + if err := assertOutsideRepository(path, repoRoot); err != nil { + return nil, err + } + if strings.EqualFold(filepath.Ext(path), ".csv") { + return nil, csvRejection("input path names a .csv file") + } + + f, err := os.Open(path) //nolint:gosec // operator-supplied replay input, refused above if inside the checkout + if err != nil { + return nil, fmt.Errorf("open replay input %q: %w", path, err) + } + defer f.Close() //nolint:errcheck // read-only + + return Load(f, opts) +} + +// Load decodes activity JSONL from r. +// +// It is the boundary the package doc's second invariant is stated about: bodies +// read here exist only as locals inside this call and the helpers it hands them +// to, and what it returns holds counts alone. +func Load(r io.Reader, opts Options) (*Corpus, error) { + corpus := &Corpus{Bodies: opts.Bodies, FleetChecked: opts.FleetResolver != nil} + warn := func(format string, args ...any) { + corpus.Warnings = append(corpus.Warnings, fmt.Sprintf(format, args...)) + if opts.Warnf != nil { + opts.Warnf(format, args...) + return + } + fmt.Fprintf(os.Stderr, format+"\n", args...) + } + + counter, err := resolveCounter(&opts) + if err != nil { + return nil, err + } + if opts.Bodies == BodiesOnUnmasked { + corpus.Encoding = encodingName(&opts) + warn("%s", bodiesOnWarning) + } + + buffered := bufio.NewReader(r) + if err := rejectCSVContent(buffered); err != nil { + return nil, err + } + + // A json.Decoder rather than a line scanner: a bodies-on record can be + // megabytes, and a scanner would fail on its buffer limit rather than on + // anything wrong with the input. + dec := json.NewDecoder(buffered) + var calls []*ReplayCall + sessionOf := make(map[string]string) + + for { + var rec contracts.ActivityRecord + if err := dec.Decode(&rec); err != nil { + if err == io.EOF { + break + } + return nil, fmt.Errorf("decode activity JSONL at record %d: %w", corpus.RecordsRead+1, err) + } + corpus.RecordsRead++ + + decoded, ok := admit(&rec, &corpus.Exclusions) + if !ok { + continue + } + call := newCall(decoded, &opts, counter, &corpus.Exclusions) + calls = append(calls, call) + sessionOf[call.ID] = rec.WorkSessionID + } + + if corpus.RecordsRead == 0 { + warn("replay: input contained no activity records โ€” a replay over an empty recording computes nothing") + } + corpus.Sessions = group(calls, sessionOf, &corpus.Exclusions) + return corpus, nil +} + +// resolveCounter picks the tokenizer for this load. Bodies off gets a counter +// that cannot be used, rather than a real one: constructing the tiktoken +// encoding would reach for a vocabulary the default posture never needs, and an +// offline bodies-off run must not fail on a download it has no use for. +func resolveCounter(opts *Options) (tokenCounter, error) { + if opts.counter != nil { + return opts.counter, nil + } + if opts.Bodies != BodiesOnUnmasked { + return noBodyCounter{}, nil + } + return newTokenCounter(encodingName(opts)) +} + +func encodingName(opts *Options) string { + if opts.Encoding != "" { + return opts.Encoding + } + return DefaultEncoding +} + +// rejectCSVContent sniffs the first non-blank byte. A JSONL export always +// starts an object; anything else is the CSV projection, whose header line +// would otherwise surface as an opaque JSON syntax error. +func rejectCSVContent(r *bufio.Reader) error { + for { + b, err := r.Peek(1) + if err != nil { + return nil // empty or unreadable input: let the decoder report it + } + if b[0] == ' ' || b[0] == '\t' || b[0] == '\r' || b[0] == '\n' { + if _, err := r.Discard(1); err != nil { + return nil + } + continue + } + if b[0] != '{' { + return csvRejection("input does not begin with a JSON object") + } + return nil + } +} + +// decodedRecord is the transient carrier for one record's content and derived +// booleans. It exists so bodies stay confined to the load call: it is never +// stored on a ReplayCall, never returned, and goes out of scope as soon as the +// call's costs are computed. +type decodedRecord struct { + id string + requestID string + parentID string + serverName string + toolName string + status string + timestamp time.Time + internal bool + truncated bool + sensitive bool + requestBytes int + responseBytes int + + // arguments and response are the only fields holding recorded content. + // Nothing copies them onward. + arguments string + response string +} + +// admit decides whether a record is a call this loader can account for, and +// records the drop when it is not. The activity log is wider than tool calls โ€” +// quarantine changes, policy decisions and server changes all arrive in an +// export โ€” and folding those into a session as zero-cost calls would inflate +// the call count of every unit of work. +func admit(rec *contracts.ActivityRecord, report *ExclusionReport) (*decodedRecord, bool) { + switch string(rec.Type) { + case "tool_call", "internal_tool_call": + default: + report.drop(ReasonNotACall) + return nil, false + } + if rec.ToolName == "" { + report.drop(ReasonMissingTool) + return nil, false + } + + decoded := &decodedRecord{ + id: rec.ID, + requestID: rec.RequestID, + parentID: rec.ParentID, + serverName: rec.ServerName, + toolName: rec.ToolName, + status: rec.Status, + timestamp: rec.Timestamp, + internal: string(rec.Type) == "internal_tool_call", + truncated: rec.ResponseTruncated, + sensitive: rec.HasSensitiveData, + requestBytes: rec.RequestBytes, + responseBytes: rec.ResponseBytes, + response: rec.Response, + } + if len(rec.Arguments) > 0 { + // Marshalled here, not carried as a map: a map would keep the recorded + // values alive on a struct, and Go's map marshalling sorts keys, so the + // counted text is also deterministic across runs (SC-002). + if encoded, err := json.Marshal(rec.Arguments); err == nil { + decoded.arguments = string(encoded) + } + } + return decoded, true +} + +// newCall converts an admitted record into a ReplayCall, classifying it and +// pricing both cost components once. This is where content stops: everything +// after this point sees counts. +func newCall(rec *decodedRecord, opts *Options, counter tokenCounter, report *ExclusionReport) *ReplayCall { + call := &ReplayCall{ + ID: rec.id, + RequestID: rec.requestID, + ParentID: rec.parentID, + ServerName: rec.serverName, + ToolName: rec.toolName, + Status: rec.status, + Timestamp: rec.timestamp, + Internal: rec.internal, + RequestBytes: rec.requestBytes, + ResponseBytes: rec.responseBytes, + } + call.classify(rec, opts, report) + + // A record with a parent_id is a sandbox sub-call, which is the one case + // where both byte counts being zero has a known cause worth naming. + isSubCall := rec.parentID != "" + call.RequestCost = requestCost(rec, isSubCall, opts, counter.Count) + call.ResponseCost = responseCost(rec, isSubCall, opts, counter.Count, report) + return call +} diff --git a/bench/replaycorpus/load_test.go b/bench/replaycorpus/load_test.go new file mode 100644 index 000000000..246e5dd59 --- /dev/null +++ b/bench/replaycorpus/load_test.go @@ -0,0 +1,309 @@ +package replaycorpus + +import ( + "errors" + "go/parser" + "go/token" + "path/filepath" + "strconv" + "strings" + "testing" + "time" +) + +// testOptions returns Options that never reach the network or the real +// repository root: every test in this package runs offline, so the tiktoken +// vocabulary download and the working-tree probe are both replaced. +func testOptions(root string) Options { + return Options{ + Warnf: func(string, ...any) {}, + repoRoot: root, + counter: countingStub{}, + } +} + +// countingStub is a deterministic stand-in for the tiktoken counter. It also +// records every string it was handed, which is what the privacy tests use to +// prove tokenization happened INSIDE this package. +type countingStub struct{ seen *[]string } + +func (c countingStub) Count(text string) int { + if c.seen != nil { + *c.seen = append(*c.seen, text) + } + return len(strings.Fields(text)) +} + +const ( + jsonlToolCall = `{"id":"01","type":"tool_call","server_name":"github","tool_name":"create_issue","status":"success","work_session_id":"ws-1","request_id":"req-1","timestamp":"2026-08-01T10:00:00Z","request_bytes":120,"response_bytes":4096}` + jsonlSecond = `{"id":"02","type":"tool_call","server_name":"github","tool_name":"list_issues","status":"success","work_session_id":"ws-1","request_id":"req-2","timestamp":"2026-08-01T10:00:05Z","request_bytes":30,"response_bytes":900}` + jsonlOther = `{"id":"03","type":"tool_call","server_name":"slack","tool_name":"post","status":"error","work_session_id":"ws-2","request_id":"req-3","timestamp":"2026-08-01T11:00:00Z","request_bytes":10,"response_bytes":20}` +) + +func loadString(t *testing.T, jsonl string, opts Options) *Corpus { + t.Helper() + c, err := Load(strings.NewReader(jsonl), opts) + if err != nil { + t.Fatalf("Load: %v", err) + } + return c +} + +func TestLoad_DecodesJSONL(t *testing.T) { + c := loadString(t, jsonlToolCall+"\n"+jsonlSecond+"\n", testOptions(t.TempDir())) + if c.RecordsRead != 2 { + t.Fatalf("RecordsRead = %d, want 2", c.RecordsRead) + } + if len(c.Sessions) != 1 { + t.Fatalf("len(Sessions) = %d, want 1", len(c.Sessions)) + } + s := c.Sessions[0] + if s.WorkSessionID != "ws-1" { + t.Errorf("WorkSessionID = %q, want ws-1", s.WorkSessionID) + } + if s.CallCount != 2 { + t.Errorf("CallCount = %d, want 2", s.CallCount) + } + if got := s.Calls[0].ToolName; got != "create_issue" { + t.Errorf("Calls[0].ToolName = %q, want create_issue", got) + } + if got := s.Calls[0].ServerName; got != "github" { + t.Errorf("Calls[0].ServerName = %q, want github", got) + } + if s.Calls[0].RequestBytes != 120 || s.Calls[0].ResponseBytes != 4096 { + t.Errorf("byte lengths not carried: %+v", s.Calls[0]) + } + if want := 5 * time.Second; s.Span() != want { + t.Errorf("Span() = %v, want %v", s.Span(), want) + } +} + +func TestLoad_RejectsCSVByContent(t *testing.T) { + csv := "id,type,server_name,tool_name,status\n01,tool_call,github,create_issue,success\n" + _, err := Load(strings.NewReader(csv), testOptions(t.TempDir())) + if !errors.Is(err, ErrCSVInput) { + t.Fatalf("err = %v, want ErrCSVInput", err) + } + // The message must say WHY, not just "unsupported": an operator who reached + // for CSV needs to know the export drops the fields replay depends on. + for _, want := range []string{"work_session_id", "--format json"} { + if !strings.Contains(err.Error(), want) { + t.Errorf("error %q does not mention %q", err, want) + } + } +} + +func TestLoadFile_RejectsCSVByExtension(t *testing.T) { + // The repository root is elsewhere, so the CSV refusal is what this test + // actually exercises rather than the working-tree refusal. + path := filepath.Join(t.TempDir(), "activity.csv") + writeFile(t, path, jsonlToolCall+"\n") // JSON content, CSV name: still refused + _, err := LoadFile(path, testOptions(t.TempDir())) + if !errors.Is(err, ErrCSVInput) { + t.Fatalf("err = %v, want ErrCSVInput", err) + } +} + +func TestLoad_GroupsByWorkSessionID(t *testing.T) { + c := loadString(t, strings.Join([]string{jsonlToolCall, jsonlOther, jsonlSecond}, "\n"), testOptions(t.TempDir())) + if len(c.Sessions) != 2 { + t.Fatalf("len(Sessions) = %d, want 2", len(c.Sessions)) + } + // Deterministic order: earliest first record wins, ties broken by id. + if c.Sessions[0].WorkSessionID != "ws-1" || c.Sessions[1].WorkSessionID != "ws-2" { + t.Fatalf("session order = %q, %q; want ws-1, ws-2", + c.Sessions[0].WorkSessionID, c.Sessions[1].WorkSessionID) + } + if c.Sessions[0].CallCount != 2 || c.Sessions[1].CallCount != 1 { + t.Errorf("call counts = %d, %d; want 2, 1", c.Sessions[0].CallCount, c.Sessions[1].CallCount) + } +} + +func TestLoad_JoinsCodeExecutionSubCalls(t *testing.T) { + parent := `{"id":"10","type":"internal_tool_call","tool_name":"code_execution","status":"success","work_session_id":"ws-1","request_id":"req-parent","timestamp":"2026-08-01T10:00:00Z"}` + // Sub-calls carry no work_session_id of their own โ€” they are attributed + // through the parent, which is the whole point of the join. + sub1 := `{"id":"11","type":"tool_call","server_name":"github","tool_name":"list_issues","status":"success","parent_id":"req-parent","request_id":"req-sub-1","timestamp":"2026-08-01T10:00:01Z"}` + sub2 := `{"id":"12","type":"tool_call","server_name":"github","tool_name":"get_issue","status":"success","parent_id":"req-parent","request_id":"req-sub-2","timestamp":"2026-08-01T10:00:02Z"}` + + c := loadString(t, strings.Join([]string{parent, sub1, sub2}, "\n"), testOptions(t.TempDir())) + if len(c.Sessions) != 1 { + t.Fatalf("len(Sessions) = %d, want 1", len(c.Sessions)) + } + s := c.Sessions[0] + // Not double-counted: the sub-calls must NOT also appear at top level. + if s.CallCount != 1 { + t.Errorf("CallCount = %d, want 1 (sub-calls hang off the parent)", s.CallCount) + } + if s.SubCallCount != 2 { + t.Errorf("SubCallCount = %d, want 2", s.SubCallCount) + } + if got := len(s.Calls[0].SubCalls); got != 2 { + t.Fatalf("len(SubCalls) = %d, want 2", got) + } + // Not orphaned: every record is reachable exactly once. + all := s.AllCalls() + if len(all) != 3 { + t.Fatalf("len(AllCalls()) = %d, want 3", len(all)) + } + seen := map[string]int{} + for _, call := range all { + seen[call.ID]++ + } + for _, id := range []string{"10", "11", "12"} { + if seen[id] != 1 { + t.Errorf("record %s appears %d times, want exactly 1", id, seen[id]) + } + } + if c.Exclusions.OrphanedSubCalls != 0 { + t.Errorf("OrphanedSubCalls = %d, want 0", c.Exclusions.OrphanedSubCalls) + } +} + +func TestLoad_OrphanedSubCallIsKeptAndCounted(t *testing.T) { + // The parent code_execution is outside the exported window. Dropping the + // sub-call would understate the workload; silently promoting it without + // saying so would misattribute it. It is kept AND counted. + orphan := `{"id":"20","type":"tool_call","server_name":"github","tool_name":"list_issues","status":"success","work_session_id":"ws-9","parent_id":"req-missing","request_id":"req-sub","timestamp":"2026-08-01T10:00:01Z","response_bytes":50}` + c := loadString(t, orphan, testOptions(t.TempDir())) + if c.Exclusions.OrphanedSubCalls != 1 { + t.Fatalf("OrphanedSubCalls = %d, want 1", c.Exclusions.OrphanedSubCalls) + } + if len(c.Sessions) != 1 || c.Sessions[0].CallCount != 1 { + t.Fatalf("orphan was not kept at top level: %+v", c.Sessions) + } +} + +func TestLoad_UnattributedRecordIsDroppedAndCounted(t *testing.T) { + noSession := `{"id":"30","type":"tool_call","server_name":"github","tool_name":"list_issues","status":"success","request_id":"req-x","timestamp":"2026-08-01T10:00:00Z"}` + c := loadString(t, noSession, testOptions(t.TempDir())) + if len(c.Sessions) != 0 { + t.Fatalf("len(Sessions) = %d, want 0", len(c.Sessions)) + } + if got := c.Exclusions.Dropped[ReasonUnattributed]; got != 1 { + t.Fatalf("Dropped[%s] = %d, want 1", ReasonUnattributed, got) + } + if c.Exclusions.TotalDropped() != 1 { + t.Errorf("TotalDropped() = %d, want 1", c.Exclusions.TotalDropped()) + } +} + +func TestLoad_NonCallRecordIsDroppedAndCounted(t *testing.T) { + quarantine := `{"id":"40","type":"quarantine_change","server_name":"evil","status":"approved","work_session_id":"ws-1","timestamp":"2026-08-01T10:00:00Z"}` + c := loadString(t, quarantine, testOptions(t.TempDir())) + if len(c.Sessions) != 0 { + t.Fatalf("len(Sessions) = %d, want 0", len(c.Sessions)) + } + if got := c.Exclusions.Dropped[ReasonNotACall]; got != 1 { + t.Errorf("Dropped[%s] = %d, want 1", ReasonNotACall, got) + } +} + +func TestLoad_MalformedLineIsAnError(t *testing.T) { + _, err := Load(strings.NewReader(jsonlToolCall+"\nnot json\n"), testOptions(t.TempDir())) + if err == nil { + t.Fatal("want an error for malformed JSONL, got nil") + } + if !strings.Contains(err.Error(), "record 2") { + t.Errorf("error %q does not locate the bad record", err) + } +} + +func TestLoad_EmptyInputIsWarnedNotSilent(t *testing.T) { + c := loadString(t, "", testOptions(t.TempDir())) + if c.RecordsRead != 0 { + t.Fatalf("RecordsRead = %d, want 0", c.RecordsRead) + } + if len(c.Warnings) == 0 { + t.Error("an empty export produced no warning โ€” silence is never success") + } +} + +// TestPackageImportsNothingFromBench guards the invariant that gives this +// package its existence (see doc.go, invariant 1). Violating it does NOT break +// this package's build โ€” it breaks bench/replay.go, one package away, with an +// import cycle โ€” so the rule needs a test that fails HERE, where the mistake +// would be made. +func TestPackageImportsNothingFromBench(t *testing.T) { + const benchPkg = "github.com/smart-mcp-proxy/mcpproxy-go/bench" + + fset := token.NewFileSet() + pkgs, err := parser.ParseDir(fset, ".", nil, parser.ImportsOnly) + if err != nil { + t.Fatalf("parse package: %v", err) + } + for name, pkg := range pkgs { + for path, file := range pkg.Files { + for _, imp := range file.Imports { + value, err := strconv.Unquote(imp.Path.Value) + if err != nil { + t.Fatalf("%s: unquote import %s: %v", path, imp.Path.Value, err) + } + if value == benchPkg || strings.HasPrefix(value, benchPkg+"/") { + t.Errorf("%s (package %s) imports %q โ€” bench/replay.go could then not import this package without a cycle", path, name, value) + } + } + } + } +} + +// An orphaned sub-call with no session of its own must be dropped under its +// OWN reason, not folded into "unattributed". +// +// Both are records with no unit of work, but only one is actionable: an +// unattributed record never had a session, whereas an orphan had a parent that +// the EXPORT WINDOW cut off โ€” and a wider re-export brings it back. Merging +// them hides the one exclusion an operator can do something about. +// +// This case is the common one for sandbox sub-calls, which inherit their +// session from the parent: losing the parent loses the session too. +func TestGroup_OrphanedSubCallWithoutSessionGetsItsOwnReason(t *testing.T) { + // A sub-call whose parent_id resolves to nothing in this export, and which + // carries no work_session_id of its own. + line := `{"id":"c1","type":"tool_call","timestamp":"2026-03-01T12:00:01Z",` + + `"parent_id":"parent-outside-window","server_name":"s","tool_name":"t","status":"success"}` + + corpus, err := Load(strings.NewReader(line+"\n"), Options{}) + if err != nil { + t.Fatalf("Load: %v", err) + } + + if corpus.Exclusions.OrphanedSubCalls != 1 { + t.Errorf("the orphan must be counted so the attribution loss stays visible, got %d", + corpus.Exclusions.OrphanedSubCalls) + } + if got := corpus.Exclusions.Dropped[ReasonOrphanedSubCall]; got != 1 { + t.Errorf("a dropped orphan must carry ReasonOrphanedSubCall, got %d", got) + } + if got := corpus.Exclusions.Dropped[ReasonUnattributed]; got != 0 { + t.Errorf("an orphan must NOT be reported as merely unattributed โ€” that hides the "+ + "actionable cause (a too-narrow export window); got %d", got) + } +} + +// An orphan that CAN stand alone is kept, not dropped: dropping it would +// understate the workload. Only the attribution is lost, and the counter says so. +func TestGroup_OrphanedSubCallWithSessionIsKept(t *testing.T) { + line := `{"id":"c1","type":"tool_call","timestamp":"2026-03-01T12:00:01Z",` + + `"parent_id":"parent-outside-window","work_session_id":"ws-1",` + + `"server_name":"s","tool_name":"t","status":"success"}` + + corpus, err := Load(strings.NewReader(line+"\n"), Options{}) + if err != nil { + t.Fatalf("Load: %v", err) + } + + if corpus.Exclusions.OrphanedSubCalls != 1 { + t.Errorf("the orphan must still be counted, got %d", corpus.Exclusions.OrphanedSubCalls) + } + if len(corpus.Sessions) != 1 { + t.Fatalf("an orphan with its own session must be KEPT โ€” dropping it understates the "+ + "workload; got %d sessions", len(corpus.Sessions)) + } + if n := corpus.TotalCalls(); n != 1 { + t.Errorf("the kept orphan must contribute to the workload, got %d calls", n) + } + if corpus.Exclusions.TotalDropped() != 0 { + t.Errorf("nothing should be dropped here, got %d", corpus.Exclusions.TotalDropped()) + } +} diff --git a/bench/replaycorpus/privacy.go b/bench/replaycorpus/privacy.go new file mode 100644 index 000000000..484fed7e9 --- /dev/null +++ b/bench/replaycorpus/privacy.go @@ -0,0 +1,120 @@ +package replaycorpus + +import ( + "errors" + "fmt" + "os" + "path/filepath" + "strings" +) + +// BodyPolicy decides whether a load reads recorded request and response bodies. +// +// The zero value is BodiesOff, and that is the whole design: an operator who +// constructs Options without thinking about this field gets the safe behaviour, +// and bodies-on is reachable only by naming it. Defaulting the other way would +// mean a forgotten flag silently loads raw, unmasked user traffic. +type BodyPolicy int + +const ( + // BodiesOff loads sizes, statuses and identities only. This is the default + // and the documented posture: it yields menu costs and the cross-mode delta + // between the two direct cells, and NO absolute workload cost โ€” which is + // reported as unavailable, never as zero. + BodiesOff BodyPolicy = iota + + // BodiesOnUnmasked loads recorded bodies so response cost can be measured + // rather than estimated. The name says "unmasked" because that is the fact + // an operator must weigh: the activity EXPORT PATH DOES NOT MASK โ€” + // maskActivityPayloads is wired into the list and detail handlers only โ€” so + // a bodies-on export is raw traffic, by design, as the compliance surface. + // Selecting it prints a warning; the bodies still never leave this package. + BodiesOnUnmasked +) + +// String renders the policy for a report or a warning line. +func (p BodyPolicy) String() string { + if p == BodiesOnUnmasked { + return "bodies_on_unmasked" + } + return "bodies_off" +} + +// bodiesOnWarning is printed once per bodies-on load. It names the unmasked +// export path explicitly, because "you asked for bodies" is not the part an +// operator needs to hear โ€” "the export never masked them" is. +const bodiesOnWarning = "replay: bodies-on requested โ€” the activity export path does NOT mask payloads (masking is wired into the list and detail handlers only), so this input is raw unmasked user traffic; bodies are tokenized inside the loader and only counts leave it, and the input file should be deleted when the run is finished" + +// ErrInsideRepository is returned for an input path inside the repository +// working tree. +var ErrInsideRepository = errors.New("replay input is inside the repository working tree") + +// ErrCSVInput is returned for a CSV export, by name or by content. +var ErrCSVInput = errors.New("csv activity export is not a valid replay input") + +// csvRejection explains what the CSV export drops, because an operator who +// reached for CSV needs to know why JSONL is not merely preferred: the CSV +// projection carries no work_session_id, no arguments, no response and no byte +// fields, so it can neither group units of work nor account any cost. +func csvRejection(where string) error { + return fmt.Errorf("%w (%s): the CSV projection drops work_session_id, arguments, response and every byte field, so it can neither group units of work nor account tokens โ€” re-export with `mcpproxy activity export --format json`", ErrCSVInput, where) +} + +// assertOutsideRepository refuses an input path inside the repository working +// tree, BEFORE any file I/O โ€” so a path that does not even exist is still +// refused for the right reason rather than reported as missing. +// +// Why this is enforced in code and not left to documentation: replay inputs are +// raw recorded user traffic, and the one irreversible mistake available here is +// dropping such a file somewhere `git add -A` will sweep it up. A convention +// cannot prevent that; a refused load can. repoRoot is resolved from the +// process's working directory when Options does not override it. +func assertOutsideRepository(path, repoRoot string) error { + if repoRoot == "" { + return nil // no working tree found; nothing to be inside of + } + abs, err := filepath.Abs(path) + if err != nil { + return fmt.Errorf("resolve replay input path %q: %w", path, err) + } + root, err := filepath.Abs(repoRoot) + if err != nil { + return fmt.Errorf("resolve repository root %q: %w", repoRoot, err) + } + if !isInside(abs, root) { + return nil + } + return fmt.Errorf("%w (%s): replay inputs are raw recorded traffic, live outside the checkout and are never committed โ€” move the export elsewhere and delete it when the run is finished", ErrInsideRepository, abs) +} + +// isInside reports whether path is root or sits beneath it. +func isInside(path, root string) bool { + rel, err := filepath.Rel(root, path) + if err != nil { + return false + } + return rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator)) +} + +// detectRepositoryRoot walks up from dir looking for a `.git` entry and returns +// the directory holding it, or "" if there is none. It checks for EXISTENCE, +// not for a directory: in a git worktree โ€” which is how this repo's agent +// sessions run โ€” `.git` is a file containing a gitdir pointer, and a +// directory-only check would silently decide the worktree is not a repository +// and wave the refusal through. +func detectRepositoryRoot(dir string) string { + dir, err := filepath.Abs(dir) + if err != nil { + return "" + } + for { + if _, err := os.Lstat(filepath.Join(dir, ".git")); err == nil { + return dir + } + parent := filepath.Dir(dir) + if parent == dir { + return "" + } + dir = parent + } +} diff --git a/bench/replaycorpus/privacy_test.go b/bench/replaycorpus/privacy_test.go new file mode 100644 index 000000000..d5cc275da --- /dev/null +++ b/bench/replaycorpus/privacy_test.go @@ -0,0 +1,274 @@ +package replaycorpus + +import ( + "encoding/json" + "errors" + "os" + "path/filepath" + "reflect" + "strings" + "testing" +) + +func writeFile(t *testing.T, path, content string) { + t.Helper() + if err := os.WriteFile(path, []byte(content), 0o600); err != nil { + t.Fatalf("write %s: %v", path, err) + } +} + +func marshalLine(t *testing.T, fields map[string]any) string { + t.Helper() + b, err := json.Marshal(fields) + if err != nil { + t.Fatalf("marshal: %v", err) + } + return string(b) +} + +// secretBody is a string that exists nowhere else, so finding it anywhere in +// the loaded corpus proves content escaped the loader. +const secretBody = "ZZ-CANARY-BODY-TEXT-must-not-escape-ZZ" + +func bodiesOnRecord(t *testing.T, fields map[string]any) string { + t.Helper() + base := map[string]any{ + "id": "b-1", + "type": "tool_call", + "server_name": "github", + "tool_name": "list_issues", + "status": "success", + "work_session_id": "ws-1", + "request_id": "req-1", + "timestamp": "2026-08-01T10:00:00Z", + "response": secretBody + " one two three", + "arguments": map[string]any{"query": secretBody}, + "response_bytes": 60, + "request_bytes": 40, + } + for k, v := range fields { + base[k] = v + } + return marshalLine(t, base) +} + +// assertNoText walks EVERY string reachable from v โ€” exported or not, through +// pointers, slices, maps and structs โ€” looking for needle. json.Marshal alone +// would miss an unexported field, which is exactly where a body would hide. +func assertNoText(t *testing.T, v any, needle string) { + t.Helper() + seen := map[uintptr]bool{} + var walk func(rv reflect.Value, path string) + walk = func(rv reflect.Value, path string) { + switch rv.Kind() { + case reflect.String: + if strings.Contains(rv.String(), needle) { + t.Errorf("body text escaped the loader at %s: %q", path, rv.String()) + } + case reflect.Ptr, reflect.Interface: + if rv.IsNil() { + return + } + if rv.Kind() == reflect.Ptr { + if seen[rv.Pointer()] { + return + } + seen[rv.Pointer()] = true + } + walk(rv.Elem(), path) + case reflect.Slice, reflect.Array: + for i := 0; i < rv.Len(); i++ { + walk(rv.Index(i), path+"[]") + } + case reflect.Map: + for _, k := range rv.MapKeys() { + walk(k, path+".key") + walk(rv.MapIndex(k), path+"[k]") + } + case reflect.Struct: + for i := 0; i < rv.NumField(); i++ { + walk(rv.Field(i), path+"."+rv.Type().Field(i).Name) + } + default: + } + } + walk(reflect.ValueOf(v), "corpus") +} + +func TestBodiesOffIsTheDefault(t *testing.T) { + // The zero value of Options must be the safe one: an operator who forgets + // to think about the flag gets bodies-off, not an unmasked raw load. + if (Options{}).Bodies != BodiesOff { + t.Fatal("the zero value of Options is not bodies-off") + } + opts := testOptions(t.TempDir()) + if opts.Bodies != BodiesOff { + t.Fatal("test options are not bodies-off") + } + c := loadString(t, bodiesOnRecord(t, nil), opts) + if c.Bodies != BodiesOff { + t.Errorf("Corpus.Bodies = %s, want %s", c.Bodies, BodiesOff) + } + assertNoText(t, c, secretBody) + if len(c.Warnings) != 0 { + t.Errorf("a bodies-off load warned unnecessarily: %v", c.Warnings) + } +} + +func TestBodiesOnRequiresExplicitOptInAndWarns(t *testing.T) { + var warnings []string + opts := testOptions(t.TempDir()) + opts.Bodies = BodiesOnUnmasked + opts.Warnf = func(format string, args ...any) { + warnings = append(warnings, format) + } + c := loadString(t, bodiesOnRecord(t, nil), opts) + + if len(warnings) == 0 { + t.Fatal("bodies-on printed no warning") + } + joined := strings.ToLower(strings.Join(warnings, " ") + " " + strings.Join(c.Warnings, " ")) + // The warning has to say the thing that makes bodies-on dangerous: the + // export path does not mask, so this is raw traffic. + for _, want := range []string{"mask", "unmask"} { + if strings.Contains(joined, want) { + return + } + } + t.Errorf("bodies-on warning does not say the export is unmasked: %v", warnings) +} + +func TestNoBodyTextEscapesOnABodiesOnLoad(t *testing.T) { + opts := testOptions(t.TempDir()) + opts.Bodies = BodiesOnUnmasked + c := loadString(t, bodiesOnRecord(t, nil), opts) + assertNoText(t, c, secretBody) +} + +func TestTokenizationHappensInsideTheLoaderAndOnlyCountsCross(t *testing.T) { + var seen []string + opts := testOptions(t.TempDir()) + opts.Bodies = BodiesOnUnmasked + opts.counter = countingStub{seen: &seen} + + c := loadString(t, bodiesOnRecord(t, nil), opts) + call := firstCall(t, c) + + if call.ResponseCost.Basis != CostMeasured { + t.Fatalf("ResponseCost.Basis = %s, want %s", call.ResponseCost.Basis, CostMeasured) + } + if call.ResponseCost.Tokens != 4 { + t.Errorf("ResponseCost.Tokens = %d, want 4", call.ResponseCost.Tokens) + } + if call.RequestCost.Basis != CostMeasured { + t.Errorf("RequestCost.Basis = %s, want %s", call.RequestCost.Basis, CostMeasured) + } + // The body reached the tokenizer, and the tokenizer is inside this package. + if len(seen) == 0 || !strings.Contains(strings.Join(seen, " "), secretBody) { + t.Fatalf("the body never reached the in-package tokenizer: %v", seen) + } + // And nothing but counts came back out. + assertNoText(t, c, secretBody) +} + +// The log stores the FULL pre-truncation retrieve_tools response while the +// agent consumed the cut text. Tokenizing it as-is OVERSTATES what mcpproxy +// cost โ€” the one direction of error this benchmark exists to prevent. +func TestTruncatedRetrieveToolsIsNeverTokenized(t *testing.T) { + var seen []string + opts := testOptions(t.TempDir()) + opts.Bodies = BodiesOnUnmasked + opts.counter = countingStub{seen: &seen} + + c := loadString(t, bodiesOnRecord(t, map[string]any{ + "type": "internal_tool_call", + "tool_name": "retrieve_tools", + // Arguments carry no canary: they are recorded whole and are legitimately + // tokenized. It is the RESPONSE that must never be counted here. + "arguments": map[string]any{"query": "plain"}, + "server_name": "", + "response_truncated": true, + "response_bytes": 9999, + }), opts) + + call := firstCall(t, c) + if call.ResponseCost.Basis != CostUnavailable { + t.Fatalf("Basis = %s, want %s (tokenizing would overstate)", call.ResponseCost.Basis, CostUnavailable) + } + if call.ResponseCost.Reason != ReasonTruncatedRetrieveOverstates { + t.Errorf("Reason = %s, want %s", call.ResponseCost.Reason, ReasonTruncatedRetrieveOverstates) + } + if c.Exclusions.Withheld[ReasonTruncatedRetrieveOverstates] != 1 { + t.Errorf("the exclusion was not counted: %+v", c.Exclusions.Withheld) + } + // The pre-truncation byte length describes the stored text, not what the + // agent paid, so it must not be used as an estimate either. + if call.ResponseCost.Tokens != 0 || call.ResponseCost.Bytes != 0 { + t.Errorf("an excluded cost still carries figures: %+v", call.ResponseCost) + } + if strings.Contains(strings.Join(seen, " "), secretBody) { + t.Error("the truncated retrieve_tools response was tokenized anyway") + } +} + +func TestSensitiveBodyIsNeverTokenized(t *testing.T) { + var seen []string + opts := testOptions(t.TempDir()) + opts.Bodies = BodiesOnUnmasked + opts.counter = countingStub{seen: &seen} + + c := loadString(t, bodiesOnRecord(t, map[string]any{"has_sensitive_data": true}), opts) + call := firstCall(t, c) + if call.ResponseCost.Basis == CostMeasured { + t.Error("a flagged-sensitive body was tokenized") + } + if strings.Contains(strings.Join(seen, " "), secretBody) { + t.Error("a flagged-sensitive body reached the tokenizer") + } + if c.Exclusions.Withheld[ReasonSensitive] == 0 { + t.Errorf("the sensitive withholding was not counted: %+v", c.Exclusions.Withheld) + } +} + +func TestLoadFileRefusesAPathInsideTheRepository(t *testing.T) { + root := t.TempDir() + writeFile(t, filepath.Join(root, ".git"), "gitdir: elsewhere\n") + inside := filepath.Join(root, "bench", "input.jsonl") + if err := os.MkdirAll(filepath.Dir(inside), 0o755); err != nil { + t.Fatal(err) + } + // Deliberately NOT created: the refusal must precede any file I/O, so a + // path that does not exist still fails with the privacy error. + _, err := LoadFile(inside, testOptions(root)) + if !errors.Is(err, ErrInsideRepository) { + t.Fatalf("err = %v, want ErrInsideRepository", err) + } + if !strings.Contains(err.Error(), "never committed") { + t.Errorf("error %q does not explain why", err) + } +} + +func TestLoadFileRefusesTheRealRepositoryWorkingTree(t *testing.T) { + // No repoRoot override: this exercises the real detection, from the test + // binary's working directory (bench/replaycorpus) up to the checkout. + opts := Options{Warnf: func(string, ...any) {}, counter: countingStub{}} + _, err := LoadFile("activity.jsonl", opts) + if !errors.Is(err, ErrInsideRepository) { + t.Fatalf("err = %v, want ErrInsideRepository", err) + } +} + +func TestLoadFileAcceptsAPathOutsideTheRepository(t *testing.T) { + repo := t.TempDir() + writeFile(t, filepath.Join(repo, ".git"), "gitdir: elsewhere\n") + outside := filepath.Join(t.TempDir(), "activity.jsonl") + writeFile(t, outside, jsonlToolCall+"\n") + + c, err := LoadFile(outside, testOptions(repo)) + if err != nil { + t.Fatalf("LoadFile: %v", err) + } + if c.RecordsRead != 1 { + t.Errorf("RecordsRead = %d, want 1", c.RecordsRead) + } +} diff --git a/bench/replaycorpus/tokenize.go b/bench/replaycorpus/tokenize.go new file mode 100644 index 000000000..c1414d6c2 --- /dev/null +++ b/bench/replaycorpus/tokenize.go @@ -0,0 +1,55 @@ +package replaycorpus + +import ( + "fmt" + + "github.com/pkoukk/tiktoken-go" +) + +// DefaultEncoding is the tiktoken encoding used to count recorded bodies. It +// matches the rest of the benchmark (bench.DefaultEncoding) so a replay figure +// and a corpus figure are commensurable โ€” but it is DUPLICATED here rather than +// imported, because this package must not import `bench` (package doc, +// invariant 1). The duplication is one string; the cycle would be structural. +const DefaultEncoding = "cl100k_base" + +// tokenCounter is the seam through which bodies are turned into counts. It is +// UNEXPORTED, and Options holds it in an unexported field, on purpose: an +// exported hook would let a caller outside this package receive body text, +// which is precisely the invariant tokenization-inside-the-loader exists to +// protect (package doc, invariant 2). Tests substitute a deterministic stub so +// the suite never reaches the network for a vocabulary. +type tokenCounter interface { + Count(text string) int +} + +// tiktokenCounter is the real counter: the same cl100k_base encoding the rest +// of the harness uses, reached directly rather than through bench.Tokenizer. +type tiktokenCounter struct { + enc *tiktoken.Tiktoken +} + +func newTokenCounter(encoding string) (tokenCounter, error) { + enc, err := tiktoken.GetEncoding(encoding) + if err != nil { + // tiktoken fetches its vocabulary over the network unless + // TIKTOKEN_CACHE_DIR names a POPULATED cache, so this is the error an + // offline first run hits. Say so, rather than leaving the operator to + // guess why a local file needed the internet. + return nil, fmt.Errorf("load tiktoken encoding %q (bodies-on replay needs a populated TIKTOKEN_CACHE_DIR to run offline): %w", encoding, err) + } + return &tiktokenCounter{enc: enc}, nil +} + +// Count returns the number of tokens in text. The text is a parameter and never +// a field: nothing in this type retains what it counted. +func (c *tiktokenCounter) Count(text string) int { + return len(c.enc.Encode(text, nil, nil)) +} + +// noBodyCounter is the counter installed for a bodies-off load. Reaching it is +// a bug โ€” bodies-off has no text to count โ€” so it returns zero rather than +// pulling a vocabulary down for a call that should never happen. +type noBodyCounter struct{} + +func (noBodyCounter) Count(string) int { return 0 } diff --git a/bench/report.go b/bench/report.go index b234123c5..be948ddaa 100644 --- a/bench/report.go +++ b/bench/report.go @@ -188,6 +188,60 @@ const dashboardV2HTML = ` {{end}}{{end}}

Provenance badges: measured observed over the real protocol/corpus · computed arithmetic over measured inputs · estimated model with documented assumptions.

+{{if .Replay}} +

Replay — a recorded workload, recomputed{{with prov .Provenance "replay"}}{{.}}{{end}}

+
⚠️ {{.Replay.Counterfactual}}
+

accounting source {{.Replay.AccountingSource.Kind}} · {{.Replay.AccountingSource.Identity}} · recorded bodies {{if .Replay.BodiesIncluded}}ON — raw and unmasked (the activity export path does not mask){{else}}off (default posture){{end}} · fleet shape {{.Replay.FleetShape.ID}}, {{.Replay.FleetShape.ToolCount}} tools{{if .Replay.FleetShape.MeanDefinitionTokens}}, mean {{f1 .Replay.FleetShape.MeanDefinitionTokens}} tokens per definition, p95 {{.Replay.FleetShape.P95DefinitionTokens}}{{end}}

+ +

What did not count

+

{{.Replay.SessionsSupplied}}sessions supplied{{.Replay.SessionsUsed}}sessions used

+{{if .Replay.Exclusions}} + + + + {{range .Replay.Exclusions}} + + + + + + {{end}} + +
ReasonCountEffect
{{.Reason}}{{.Sessions}}{{if eq .Reason "sensitive"}}sessions DROPPED — not priced at all{{else if eq .Reason "unreplayable"}}sessions DROPPED — a recorded tool is absent from the supplied fleet{{else if eq .Reason "bodies_missing"}}sessions flagged — still counted for call shape, but no response figure is derivable from them{{else if eq .Reason "truncated"}}sessions flagged — a stored response was cut, so its text describes more than the agent consumed{{else}}RECORDS dropped before reaching any unit of work (non-call activity, no tool name, or no work session){{end}}
+

Read this table BEFORE the numbers below. The two DROPPED rows account exactly for sessions supplied minus sessions used; the flagged rows describe sessions that still contributed. The unattributed row counts RECORDS rather than sessions — those records never became a session, so no session count exists for them.

+{{else}} +

No sessions were dropped and no records fell outside a unit of work.

+{{end}} +{{if .Replay.SensitiveFlagBestEffort}} +

The sensitive-data flag is a best-effort REDUCER, never a guarantee: it is derived from detection metadata written asynchronously AFTER a record is persisted, so a freshly exported record may be sensitive and not yet flagged.

+{{end}} + +

Per-cell cost

+ + + + {{range .Replay.Cells}} + + + + + + + + + {{end}} + +
Mode cellMenu tokensRecorded callsResponse tokensAbsolute complete-workload costProvenance
{{.CellID}}{{.MenuTokens}}{{.Calls}}{{if .ResponseTokens}}{{.ResponseTokens}}{{else}}—{{end}}{{if .AbsoluteWorkloadWithheld}}withheld — {{.WithheldReason}}{{else}}available{{end}}{{.Provenance}}
+{{if .Replay.DirectDelta}} +

Cross-mode delta{{with .Replay.DirectDelta}}{{.Provenance}}{{end}}

+{{with .Replay.DirectDelta}} +

{{.DeltaTokens}}tokens{{f1 .DeltaPct}}%of the {{.FromCellID}} menu

+

This is the honest bodies-off headline: {{.FromCellID}} and {{.ToCellID}} serve IDENTICAL call responses, so the response term cancels out of the difference and the delta survives without the response text. No such delta exists for the retrieve cells — their serialization changes the response body, which is exactly the text a bodies-off replay does not carry.

+{{end}} +{{end}} +

Every figure above scores the recorded call shape against the SUPPLIED fleet — today's fleet, not the fleet as it stood when the sessions were recorded. It is internally valid across mode cells and is not a historical reconstruction. generated_at is pinned rather than stamped so two runs over the same inputs are byte-identical.

+{{end}} + {{if .Corpora}}

Corpora{{with prov .Provenance "corpora"}}{{.}}{{end}}

diff --git a/bench/reportv2.go b/bench/reportv2.go index 78f0a798e..05adaf4f5 100644 --- a/bench/reportv2.go +++ b/bench/reportv2.go @@ -229,6 +229,381 @@ type SubsetInfo struct { Size int `json:"size"` } +// --- Spec 103 additive blocks (contracts/report-v2-additions.md) --- +// +// The replay, agent-loop and payload-decomposition blocks are ADDITIVE +// optional members of this same v2 envelope: ReportVersion2 stays 2 and no +// existing field changes meaning. That rule is what forces the two shapes +// below to exist rather than reusing what is already here. +// +// Why a per-BLOCK accounting source. The envelope carries ONE tokenizer +// identity (TokenizerInfo) for the whole document. Once provider-reported +// usage enters the same document, that field would silently claim the entire +// report was tokenizer-counted. Narrowing it to "the deterministic sections +// only" is a meaning change, and a meaning change requires a version bump โ€” +// which this feature must not do. So the document-level field keeps its +// meaning intact (it names the deterministic estimator, still true of every +// section that has one) and each new block names its own source explicitly. A +// reader never has to infer scope from a document-level field. +// +// Why a per-ROW provenance. ReportV2.Provenance is section-level: one badge +// per section key. FR-013 lets measured and estimated figures coexist INSIDE +// one block, which a single badge cannot express. The concrete failure it +// prevents: RetryRateForArm returns 0.0 for an unknown arm, indistinguishable +// from a measured 0.0, so one table can mix a measured rate with a defaulted +// one under a single badge. Every new row type therefore carries its own +// provenance, constrained to the same three values as the section map. + +// Accounting-source kinds. Figures from different kinds are NEVER summed: a +// cross-source aggregate is withheld with a stated reason (data-model.md +// invariant 2), reusing the harness's withhold-rather-than-compute pattern. +const ( + // AccountingKindTokenizer marks figures counted by the pinned + // deterministic estimator named in the document-level TokenizerInfo. + AccountingKindTokenizer = "deterministic-tokenizer" + // AccountingKindProvider marks figures taken from provider-reported + // usage, which requires a pinned model to be interpretable at all. + AccountingKindProvider = "provider-usage" +) + +// Exclusion reason codes for replay sessions (FR-003). Every supplied session +// that does not reach a figure is counted under exactly one of these โ€” silence +// is never success (data-model.md invariant 3). +const ( + ReplayExclusionTruncated = "truncated" + ReplayExclusionBodiesMissed = "bodies_missing" + ReplayExclusionSensitive = "sensitive" + ReplayExclusionUnreplayable = "unreplayable" + ReplayExclusionUnattributed = "unattributed" +) + +// Spec-102 verdicts (FR-025). The verdict is stated explicitly per fleet +// shape; an absent verdict is not "confirmed by default". +const ( + Spec102Confirmed = "confirmed" + Spec102Corrected = "corrected" +) + +// AccountingSource names where one block's numbers came from. It is +// deliberately a value, not a string: a provider-sourced block is only +// interpretable with the model pinned alongside the provider, and squeezing +// both into one enum string would make the "never sum across sources" +// comparison a string-parsing exercise. +type AccountingSource struct { + // Kind is AccountingKindTokenizer or AccountingKindProvider. + Kind string `json:"kind"` + // Identity names the estimator ("cl100k_base") or the provider. + Identity string `json:"identity"` + // Model pins the model for provider-sourced figures. Mandatory for + // AccountingKindProvider, empty otherwise โ€” usage numbers from an + // unpinned model are not comparable to any later run. + Model string `json:"model,omitempty"` +} + +// IsZero reports whether the source was never populated. A block with a zero +// source cannot enter any aggregate (data-model.md: accounting_source is +// mandatory), so emission-time validation rejects it rather than defaulting. +func (a AccountingSource) IsZero() bool { + return a.Kind == "" && a.Identity == "" && a.Model == "" +} + +// FleetShape is the tool count and definition-size distribution a figure holds +// for. Every published percentage carries one (IC-004): a saving quoted +// without its fleet shape is a saving quoted at an unstated fleet size, which +// is how spec 102 over-projected from a single corpus. +type FleetShape struct { + ID string `json:"id"` + ToolCount int `json:"tool_count"` + MeanDefinitionTokens float64 `json:"mean_definition_tokens,omitempty"` + P95DefinitionTokens int `json:"p95_definition_tokens,omitempty"` +} + +// ReplayExclusion counts the supplied sessions dropped for one reason (FR-003, +// SC-008). Reasons are the Replay* constants above. +type ReplayExclusion struct { + Reason string `json:"reason"` + Sessions int `json:"sessions"` +} + +// ReplayCellCost is one mode cell's recomputed cost over the recorded +// workload. Bodies-off it carries a MEASURED menu cost and, at best, an +// ESTIMATED response cost derived from pre-truncation byte LENGTHS โ€” which is +// exactly the mix that per-row provenance exists to express. +// ReplayLoaderReason is one reason code and its count, as the loader recorded +// it. The reason strings are the loader's own vocabulary rather than the +// report's closed enum: they name causes the report-level enum has no term for +// (a truncated internal response that would overstate, a byte-gap record), and +// flattening them into the closed set would destroy the very distinction that +// makes them actionable. +type ReplayLoaderReason struct { + Reason string `json:"reason"` + Count int `json:"count"` +} + +// ReplayLoaderAccounting is the loader-level companion to ReplayBlock.Exclusions. +// +// The three buckets are deliberately separate rather than one total. A dropped +// record never entered a unit of work; a withheld cost was suppressed on a +// record that DID contribute; a flagged record contributed and was counted but +// carries a usability caveat. "12 exclusions" spanning all three is +// uninterpretable, and an uninterpretable count satisfies the letter of +// "everything is counted" while destroying its purpose. +type ReplayLoaderAccounting struct { + RecordsDropped int `json:"records_dropped"` + Dropped []ReplayLoaderReason `json:"dropped,omitempty"` + CostsWithheld int `json:"costs_withheld"` + Withheld []ReplayLoaderReason `json:"withheld,omitempty"` + RecordsFlagged int `json:"records_flagged"` + Flagged []ReplayLoaderReason `json:"flagged,omitempty"` + // OrphanedSubCalls counts sub-calls whose parent fell outside the exported + // window. They ARE counted in the workload, at top level; what was lost is + // their attribution to a parent. Reported because a total that hides it + // cannot be audited. + OrphanedSubCalls int `json:"orphaned_sub_calls,omitempty"` +} + +type ReplayCellCost struct { + CellID string `json:"cell_id"` + // Provenance is measured/computed/estimated for THIS row. + Provenance string `json:"provenance"` + Calls int `json:"calls"` + // MenuTokens is the tool-surface cost of what the agent was shown under + // this cell, computed from the supplied fleet input. + MenuTokens int `json:"menu_tokens"` + // ResponseTokens is present only when a response figure could be + // produced at all; bodies-off it is an estimate from byte lengths, never + // a measurement, and a pointer so a genuine 0 is distinguishable from + // "not computed". + ResponseTokens *int `json:"response_tokens,omitempty"` + // AbsoluteWorkloadWithheld records that no absolute complete-workload + // figure is available for this cell. Bodies-off that is true of EVERY + // cell, because complete workload includes every consumed response and + // that text is absent. It is reported as unavailable, never as zero. + AbsoluteWorkloadWithheld bool `json:"absolute_workload_withheld,omitempty"` + WithheldReason string `json:"withheld_reason,omitempty"` +} + +// ReplayDirectDelta is the honest bodies-off headline: the cross-mode delta +// between the two direct cells, whose identical call responses cancel out of +// the comparison. It is a row in its own right and carries its own provenance +// (computed โ€” it is arithmetic over two measured menu costs). +type ReplayDirectDelta struct { + FromCellID string `json:"from_cell_id"` + ToCellID string `json:"to_cell_id"` + Provenance string `json:"provenance"` + DeltaTokens int `json:"delta_tokens"` + DeltaPct float64 `json:"delta_pct"` +} + +// ReplayBlock is the deterministic recomputation over a real recorded workload +// (US1). It is a COUNTERFACTUAL: recorded call shape scored against the +// SUPPLIED fleet, not the fleet as it stood when the session was recorded, and +// never observed agent behaviour (FR-004). No recorded content reaches this +// struct โ€” only counts, sizes and derived measurements (FR-006). +type ReplayBlock struct { + AccountingSource AccountingSource `json:"accounting_source"` + // Counterfactual is the mandatory FR-004 label. It is a required field + // rather than a rendering concern so a figure cannot be emitted without + // it and then lose the caveat downstream. + Counterfactual string `json:"counterfactual"` + // BodiesIncluded records whether the export carried response bodies. + // False is the default and the safe mode; true is an explicit opt-in + // over raw unmasked traffic (the export path does not mask). + BodiesIncluded bool `json:"bodies_included"` + FleetShape FleetShape `json:"fleet_shape"` + // SessionsSupplied/SessionsUsed plus Exclusions are the FR-003 accounting: + // supplied minus used must be explained by the exclusion counts. + SessionsSupplied int `json:"sessions_supplied"` + SessionsUsed int `json:"sessions_used"` + Exclusions []ReplayExclusion `json:"exclusions,omitempty"` + // LoaderAccounting is the loader's own exclusion detail: what was dropped + // before joining a unit of work, what had its cost withheld INSIDE an + // admitted unit, what was admitted but flagged, and how many sub-calls + // lost their parent. The session rows above cannot express any of that, + // and a withheld cost that collapses a response total with no row saying + // why is precisely the silent accounting SC-008 forbids. + LoaderAccounting *ReplayLoaderAccounting `json:"loader_accounting,omitempty"` + Cells []ReplayCellCost `json:"cells,omitempty"` + // DirectDelta is absent when only one direct cell was measured. + DirectDelta *ReplayDirectDelta `json:"direct_delta,omitempty"` + // SensitiveFlagBestEffort restates, in the report itself, that the + // sensitive-data flag is derived from detection metadata written + // asynchronously AFTER persistence: its absence does not prove a record + // is clean. It is a reducer, never a guarantee (Principle IV). + SensitiveFlagBestEffort bool `json:"sensitive_flag_best_effort,omitempty"` +} + +// AgentLoopCell is one mode cell measured over a live agent loop (US2). Its +// numbers come from provider-reported usage, so they may never be summed with +// the deterministic blocks' figures. +type AgentLoopCell struct { + CellID string `json:"cell_id"` + // Provenance is measured for a cell backed by real runs; a row still + // carrying an assumed default stays estimated and must be rendered as + // such beside its measured neighbours (FR-013). + Provenance string `json:"provenance"` + // Runs and SpreadPct are the FR-021 consistency requirement: a + // model-dependent figure needs at least four runs plus a spread before + // it may be a headline. + Runs int `json:"runs"` + SpreadPct float64 `json:"spread_pct"` + // PartialRuns counts runs that did not finish. They are excluded from + // the figures above and reported, never silently absorbed (FR-032). + PartialRuns int `json:"partial_runs,omitempty"` + // TokensPerCompletedTask is the FR-018 headline, and CompletionRatePct + // travels with it at equal prominence โ€” a cheap mode that finishes + // fewer tasks is not a saving. + TokensPerCompletedTask float64 `json:"tokens_per_completed_task"` + CompletionRatePct float64 `json:"completion_rate_pct"` + FirstAttemptSuccessPct float64 `json:"first_attempt_success_pct"` + // Corrective and infrastructure retries are counted separately: only the + // first kind says anything about how well the mode serves the agent. + RetriesCorrective int `json:"retries_corrective"` + RetriesInfrastructure int `json:"retries_infrastructure"` + // Input/output/cache-read consumption stays split (FR-014); collapsing + // them hides the cache behaviour that dominates a long agent loop. + InputTokens int `json:"input_tokens"` + OutputTokens int `json:"output_tokens"` + CacheReadTokens int `json:"cache_read_tokens"` + // Headline is false whenever the FR-021 bar is unmet; the row is still + // published, just not as a headline. + Headline bool `json:"headline"` + // Regression marks a cell whose completion rate falls more than the + // stated threshold below the baseline's. Such a cell must never be + // described as a saving regardless of its token cost (FR-019). + Regression bool `json:"regression,omitempty"` + // Withheld carries a figure that cannot be computed honestly โ€” a + // cross-source aggregate above all โ€” with the reason stated. + Withheld bool `json:"withheld,omitempty"` + WithheldReason string `json:"withheld_reason,omitempty"` +} + +// AgentLoopBlock is the live measured block (US2). Its AccountingSource is +// provider-usage plus the pinned model, which is why the block-level field +// exists: this block and the deterministic ones sit in one document and must +// stay separable. +type AgentLoopBlock struct { + AccountingSource AccountingSource `json:"accounting_source"` + // Suite and SuiteVersion pin the task suite so a later run is comparable + // to an earlier one (FR-028). + Suite string `json:"suite,omitempty"` + SuiteVersion string `json:"suite_version,omitempty"` + FleetShape FleetShape `json:"fleet_shape"` + Cells []AgentLoopCell `json:"cells,omitempty"` +} + +// PayloadDecompositionRow attributes tool-definition cost for ONE fleet shape +// (FR-024/025). +type PayloadDecompositionRow struct { + FleetShape FleetShape `json:"fleet_shape"` + Provenance string `json:"provenance"` + // The four attributions, as percentages of the definition payload. + ShareNamesPct float64 `json:"share_names_pct"` + ShareDescriptionsPct float64 `json:"share_descriptions_pct"` + ShareAnnotationsPct float64 `json:"share_annotations_pct"` + ShareSchemasPct float64 `json:"share_schemas_pct"` + // AchievableCeilingPct is recomputed for THIS shape. Carrying a + // previously published ceiling forward is precisely the error spec 102 + // made when it projected from a single corpus. + AchievableCeilingPct float64 `json:"achievable_ceiling_pct"` + // Spec102Verdict is an explicit confirmed/corrected call on spec 102's + // conclusion, with the delta when corrected. + Spec102Verdict string `json:"spec102_verdict"` + Spec102DeltaPct *float64 `json:"spec102_delta_pct,omitempty"` +} + +// PayloadDecompositionBlock holds one row per fleet shape (at least two, per +// FR-024) so the reader can see how the attribution moves with fleet size +// rather than trusting a single-corpus projection. +type PayloadDecompositionBlock struct { + AccountingSource AccountingSource `json:"accounting_source"` + Shapes []PayloadDecompositionRow `json:"shapes,omitempty"` +} + +// IsValidProvenance reports whether s is one of the three closed-enum values +// shared by the section-level map and every per-row provenance field. +func IsValidProvenance(s string) bool { + return s == ProvenanceMeasured || s == ProvenanceComputed || s == ProvenanceEstimated +} + +// ValidateAdditiveBlocks enforces, at emission time, the two properties the +// JSON schema cannot: that every present block names a populated accounting +// source, and that every row of every block carries a provenance from the +// closed enum. +// +// The schema declares these blocks but has no additionalProperties:false and +// cannot require a field to be non-empty, so a block whose accounting source +// was never set would validate silently โ€” which is the exact failure the +// contract calls out ("a field that exists but is never set does not satisfy +// the contract"). Callers that build a report should run this before writing. +func (r *ReportV2) ValidateAdditiveBlocks() error { + checkSource := func(block string, src AccountingSource) error { + if src.IsZero() { + return fmt.Errorf("%s block: accounting_source is unset", block) + } + switch src.Kind { + case AccountingKindTokenizer, AccountingKindProvider: + default: + return fmt.Errorf("%s block: accounting_source.kind %q not in {%s,%s}", + block, src.Kind, AccountingKindTokenizer, AccountingKindProvider) + } + if src.Identity == "" { + return fmt.Errorf("%s block: accounting_source.identity is empty", block) + } + if src.Kind == AccountingKindProvider && src.Model == "" { + return fmt.Errorf("%s block: provider-sourced figures need a pinned model", block) + } + return nil + } + checkRow := func(block, row string, provenance string) error { + if provenance == "" { + return fmt.Errorf("%s block: %s has no provenance", block, row) + } + if !IsValidProvenance(provenance) { + return fmt.Errorf("%s block: %s provenance %q not in {%s,%s,%s}", + block, row, provenance, ProvenanceMeasured, ProvenanceComputed, ProvenanceEstimated) + } + return nil + } + + if b := r.Replay; b != nil { + if err := checkSource("replay", b.AccountingSource); err != nil { + return err + } + for i := range b.Cells { + if err := checkRow("replay", fmt.Sprintf("cells[%d] (%s)", i, b.Cells[i].CellID), b.Cells[i].Provenance); err != nil { + return err + } + } + if b.DirectDelta != nil { + if err := checkRow("replay", "direct_delta", b.DirectDelta.Provenance); err != nil { + return err + } + } + } + if b := r.AgentLoop; b != nil { + if err := checkSource("agent_loop", b.AccountingSource); err != nil { + return err + } + for i := range b.Cells { + if err := checkRow("agent_loop", fmt.Sprintf("cells[%d] (%s)", i, b.Cells[i].CellID), b.Cells[i].Provenance); err != nil { + return err + } + } + } + if b := r.PayloadDecomposition; b != nil { + if err := checkSource("payload_decomposition", b.AccountingSource); err != nil { + return err + } + for i := range b.Shapes { + if err := checkRow("payload_decomposition", fmt.Sprintf("shapes[%d] (%s)", i, b.Shapes[i].FleetShape.ID), b.Shapes[i].Provenance); err != nil { + return err + } + } + } + return nil +} + // ReportV2 is the versioned report envelope (research D12). Additive over the // v1 report: existing consumers are unaffected (reports are never committed, // Spec 065 CN-003). @@ -245,7 +620,14 @@ type ReportV2 struct { Latency *LatencyV2 `json:"latency,omitempty"` Lap *LapVerdict `json:"lap,omitempty"` Subset *SubsetInfo `json:"subset,omitempty"` - Provenance map[string]string `json:"provenance"` + // Spec 103 blocks. Additive and optional: omitted they do not appear at + // all, so existing offline reports and their consumers are byte- + // unaffected and no report_version bump is needed. Each names its own + // accounting source rather than borrowing the document-level Tokenizer. + Replay *ReplayBlock `json:"replay,omitempty"` + AgentLoop *AgentLoopBlock `json:"agent_loop,omitempty"` + PayloadDecomposition *PayloadDecompositionBlock `json:"payload_decomposition,omitempty"` + Provenance map[string]string `json:"provenance"` } // WriteJSON writes the v2 report as indented JSON into dir/report.json. diff --git a/bench/reportv2_test.go b/bench/reportv2_test.go index 103cc467c..8748b913a 100644 --- a/bench/reportv2_test.go +++ b/bench/reportv2_test.go @@ -298,3 +298,484 @@ func TestReportV2_WriteJSONDeterministic(t *testing.T) { t.Error("ReportV2 marshaling is not deterministic") } } + +// --- Spec 103 additive blocks: replay / agent_loop / payload_decomposition --- +// +// These blocks are additive optional members of the SAME v2 envelope +// (specs/103-token-bench/contracts/report-v2-additions.md): no report_version +// bump, and the document-level Tokenizer field keeps its existing meaning. +// What the tests below pin is the pair of properties that make the additions +// honest โ€” a populated per-block accounting_source, so a reader never has to +// infer a figure's scope from the document-level tokenizer, and a per-ROW +// provenance value, because FR-013 lets measured and estimated figures coexist +// inside one block where the section-level badge can only say one thing. + +// sampleReplayBlock is a bodies-off replay block: menu cost per cell plus the +// direct-cell delta, with the absolute workload figure explicitly withheld +// (never zero) and the exclusion accounting populated. +func sampleReplayBlock() *ReplayBlock { + estimatedResponse := 12500 + return &ReplayBlock{ + AccountingSource: AccountingSource{Kind: AccountingKindTokenizer, Identity: "cl100k_base"}, + Counterfactual: "cost recomputation over recorded traffic scored against the supplied fleet; not observed agent behaviour", + BodiesIncluded: false, + FleetShape: FleetShape{ + ID: "corpus_v2@2026-07-14", ToolCount: 45, + MeanDefinitionTokens: 444.4, P95DefinitionTokens: 900, + }, + SessionsSupplied: 12, + SessionsUsed: 9, + Exclusions: []ReplayExclusion{ + {Reason: ReplayExclusionTruncated, Sessions: 2}, + {Reason: ReplayExclusionSensitive, Sessions: 1}, + }, + Cells: []ReplayCellCost{ + { + CellID: "direct_full", Provenance: ProvenanceMeasured, + Calls: 30, MenuTokens: 20000, + AbsoluteWorkloadWithheld: true, + WithheldReason: "bodies-off: consumed response text is absent", + }, + { + CellID: "direct_deferred", Provenance: ProvenanceEstimated, + Calls: 30, MenuTokens: 6000, ResponseTokens: &estimatedResponse, + AbsoluteWorkloadWithheld: true, + WithheldReason: "bodies-off: consumed response text is absent", + }, + }, + DirectDelta: &ReplayDirectDelta{ + FromCellID: "direct_full", ToCellID: "direct_deferred", + Provenance: ProvenanceComputed, DeltaTokens: -14000, DeltaPct: -70.0, + }, + } +} + +// sampleAgentLoopBlock is a live block: provider-reported usage against a +// pinned model, one headline-eligible cell and one that is not (runs < 4). +func sampleAgentLoopBlock() *AgentLoopBlock { + return &AgentLoopBlock{ + AccountingSource: AccountingSource{ + Kind: AccountingKindProvider, Identity: "anthropic", Model: "claude-opus-4-5-20260101", + }, + Suite: "mcpmark", + SuiteVersion: "v0.3.1", + FleetShape: FleetShape{ID: "corpus_v2@2026-07-14", ToolCount: 45}, + Cells: []AgentLoopCell{ + { + CellID: "baseline", Provenance: ProvenanceMeasured, Runs: 5, SpreadPct: 8.4, + TokensPerCompletedTask: 41000, CompletionRatePct: 92.0, FirstAttemptSuccessPct: 71.0, + RetriesCorrective: 6, RetriesInfrastructure: 1, + InputTokens: 180000, OutputTokens: 12000, CacheReadTokens: 60000, + Headline: true, + }, + { + CellID: "retrieve_compact", Provenance: ProvenanceEstimated, Runs: 2, SpreadPct: 21.0, + TokensPerCompletedTask: 18000, CompletionRatePct: 74.0, FirstAttemptSuccessPct: 55.0, + RetriesCorrective: 11, RetriesInfrastructure: 0, PartialRuns: 1, + InputTokens: 70000, OutputTokens: 9000, CacheReadTokens: 21000, + Headline: false, Regression: true, + }, + }, + } +} + +// samplePayloadDecomposition attributes definition cost across two fleet +// shapes, each with its own recomputed ceiling and spec-102 verdict. +func samplePayloadDecomposition() *PayloadDecompositionBlock { + delta := -12.5 + return &PayloadDecompositionBlock{ + AccountingSource: AccountingSource{Kind: AccountingKindTokenizer, Identity: "cl100k_base"}, + Shapes: []PayloadDecompositionRow{ + { + FleetShape: FleetShape{ID: "corpus_v2@2026-07-14", ToolCount: 45}, + Provenance: ProvenanceMeasured, + ShareNamesPct: 3.1, + ShareDescriptionsPct: 21.4, + ShareAnnotationsPct: 1.5, + ShareSchemasPct: 74.0, + AchievableCeilingPct: 68.2, + Spec102Verdict: Spec102Confirmed, + }, + { + FleetShape: FleetShape{ID: "fleet_527@2026-08-01", ToolCount: 527}, + Provenance: ProvenanceMeasured, + ShareNamesPct: 2.2, + ShareDescriptionsPct: 30.8, + ShareAnnotationsPct: 0.9, + ShareSchemasPct: 66.1, + AchievableCeilingPct: 55.7, + Spec102Verdict: Spec102Corrected, + Spec102DeltaPct: &delta, + }, + }, + } +} + +// sampleReportV2WithBlocks is the sample envelope carrying all three additive +// blocks โ€” the fixture the schema and accounting assertions run against. +func sampleReportV2WithBlocks() *ReportV2 { + r := sampleReportV2() + r.Replay = sampleReplayBlock() + r.AgentLoop = sampleAgentLoopBlock() + r.PayloadDecomposition = samplePayloadDecomposition() + return r +} + +// TestReportV2_AdditiveBlocksAreAdditive guards the contract's versioning +// rule: the new blocks must not change the envelope's version and must not +// narrow the document-level tokenizer identity, either of which would be a +// meaning change requiring a report_version bump. +func TestReportV2_AdditiveBlocksAreAdditive(t *testing.T) { + if ReportVersion2 != 2 { + t.Fatalf("ReportVersion2 = %d, want 2 โ€” the additive blocks must not bump the version", ReportVersion2) + } + r := sampleReportV2WithBlocks() + if r.ReportVersion != 2 { + t.Errorf("report_version = %d, want 2", r.ReportVersion) + } + if r.Tokenizer.Name == "" || len(r.Tokenizer.Caveat) < 10 { + t.Error("document-level tokenizer identity must stay intact and populated") + } + + // Omitted blocks must vanish entirely, so existing consumers and the + // existing offline reports are byte-unaffected. + bare, err := json.Marshal(sampleReportV2()) + if err != nil { + t.Fatalf("marshal bare report: %v", err) + } + var doc map[string]interface{} + if err := json.Unmarshal(bare, &doc); err != nil { + t.Fatalf("unmarshal bare report: %v", err) + } + for _, key := range []string{"replay", "agent_loop", "payload_decomposition"} { + if _, ok := doc[key]; ok { + t.Errorf("block %q present in a report that never set it โ€” must be omitempty", key) + } + } +} + +// TestReportV2_BlocksCarryPopulatedAccountingSource asserts every emitted +// block names its own accounting source. A field that exists but is never set +// does not satisfy the contract, so this checks the marshaled document rather +// than only the struct definition. +func TestReportV2_BlocksCarryPopulatedAccountingSource(t *testing.T) { + data, err := json.Marshal(sampleReportV2WithBlocks()) + if err != nil { + t.Fatalf("marshal: %v", err) + } + var doc map[string]interface{} + if err := json.Unmarshal(data, &doc); err != nil { + t.Fatalf("unmarshal: %v", err) + } + + for _, key := range []string{"replay", "agent_loop", "payload_decomposition"} { + block, ok := doc[key].(map[string]interface{}) + if !ok { + t.Errorf("block %q missing from the emitted report", key) + continue + } + src, ok := block["accounting_source"].(map[string]interface{}) + if !ok { + t.Errorf("block %q has no accounting_source object", key) + continue + } + kind, _ := src["kind"].(string) + if kind != AccountingKindTokenizer && kind != AccountingKindProvider { + t.Errorf("block %q accounting_source.kind = %q, not in {%s,%s}", + key, kind, AccountingKindTokenizer, AccountingKindProvider) + } + if identity, _ := src["identity"].(string); identity == "" { + t.Errorf("block %q accounting_source.identity is empty โ€” an unpopulated field does not satisfy the contract", key) + } + if kind == AccountingKindProvider { + if model, _ := src["model"].(string); model == "" { + t.Errorf("block %q is provider-sourced but pins no model", key) + } + } + } +} + +// TestReportV2_NewRowsCarryProvenance asserts the per-ROW provenance FR-013 +// needs: every row of every new block carries a value from the closed enum, +// and a block may legitimately mix them (the sample replay block does). +func TestReportV2_NewRowsCarryProvenance(t *testing.T) { + data, err := json.Marshal(sampleReportV2WithBlocks()) + if err != nil { + t.Fatalf("marshal: %v", err) + } + var doc map[string]interface{} + if err := json.Unmarshal(data, &doc); err != nil { + t.Fatalf("unmarshal: %v", err) + } + + valid := map[string]bool{ + ProvenanceMeasured: true, ProvenanceComputed: true, ProvenanceEstimated: true, + } + rowSets := []struct { + block string + rows string + }{ + {"replay", "cells"}, + {"agent_loop", "cells"}, + {"payload_decomposition", "shapes"}, + } + for _, rs := range rowSets { + block, ok := doc[rs.block].(map[string]interface{}) + if !ok { + t.Errorf("block %q missing", rs.block) + continue + } + rows, _ := block[rs.rows].([]interface{}) + if len(rows) == 0 { + t.Errorf("block %q has no %s rows to check", rs.block, rs.rows) + continue + } + for i, row := range rows { + obj, _ := row.(map[string]interface{}) + p, _ := obj["provenance"].(string) + if !valid[p] { + t.Errorf("%s.%s[%d].provenance = %q, not in {measured,computed,estimated}", rs.block, rs.rows, i, p) + } + } + } + + // The direct-cell delta is a row too โ€” it is computed from two measured + // menu costs and must say so. + replay, _ := doc["replay"].(map[string]interface{}) + delta, ok := replay["direct_delta"].(map[string]interface{}) + if !ok { + t.Fatal("replay.direct_delta missing") + } + if p, _ := delta["provenance"].(string); !valid[p] { + t.Errorf("replay.direct_delta.provenance = %q, not in the closed enum", p) + } + + // FR-013 concretely: measured and estimated coexist inside ONE block, + // which the section-level Provenance map cannot express. + cells, _ := replay["cells"].([]interface{}) + seen := map[string]bool{} + for _, c := range cells { + obj, _ := c.(map[string]interface{}) + p, _ := obj["provenance"].(string) + seen[p] = true + } + if !seen[ProvenanceMeasured] || !seen[ProvenanceEstimated] { + t.Error("the replay sample must mix measured and estimated rows โ€” that mix is exactly what per-row provenance exists for") + } +} + +// TestReportV2_ValidateAdditiveBlocks exercises the emission-time guard: an +// unset accounting source or an out-of-enum row provenance is an error, not a +// silently-valid document (the schema has no additionalProperties:false and +// cannot catch an unset optional field). +func TestReportV2_ValidateAdditiveBlocks(t *testing.T) { + if err := sampleReportV2WithBlocks().ValidateAdditiveBlocks(); err != nil { + t.Fatalf("fully-populated sample rejected: %v", err) + } + // A report with no new blocks at all is valid โ€” they are optional. + if err := sampleReportV2().ValidateAdditiveBlocks(); err != nil { + t.Fatalf("report without additive blocks rejected: %v", err) + } + + t.Run("unset accounting source", func(t *testing.T) { + r := sampleReportV2WithBlocks() + r.Replay.AccountingSource = AccountingSource{} + if err := r.ValidateAdditiveBlocks(); err == nil { + t.Error("a block with an unset accounting_source must be rejected") + } + }) + + t.Run("provider source without pinned model", func(t *testing.T) { + r := sampleReportV2WithBlocks() + r.AgentLoop.AccountingSource.Model = "" + if err := r.ValidateAdditiveBlocks(); err == nil { + t.Error("a provider-sourced block without a pinned model must be rejected") + } + }) + + t.Run("row provenance outside the enum", func(t *testing.T) { + r := sampleReportV2WithBlocks() + r.AgentLoop.Cells[0].Provenance = "assumed" + if err := r.ValidateAdditiveBlocks(); err == nil { + t.Error("a row provenance outside {measured,computed,estimated} must be rejected") + } + }) + + t.Run("row provenance unset", func(t *testing.T) { + r := sampleReportV2WithBlocks() + r.PayloadDecomposition.Shapes[1].Provenance = "" + if err := r.ValidateAdditiveBlocks(); err == nil { + t.Error("a row with no provenance must be rejected") + } + }) +} + +// TestReportV2_SchemaDeclaresNewBlocks reads the contract schema file itself. +// The schema has no additionalProperties:false, so an UNDECLARED block would +// validate silently and the python validation below would pass vacuously โ€” +// this test is what makes that validation meaningful. +func TestReportV2_SchemaDeclaresNewBlocks(t *testing.T) { + raw, err := os.ReadFile(filepath.Clean("../specs/083-discovery-profiler/contracts/report-v2.schema.json")) + if err != nil { + t.Fatalf("read schema: %v", err) + } + var schema map[string]interface{} + if err := json.Unmarshal(raw, &schema); err != nil { + t.Fatalf("parse schema: %v", err) + } + props, _ := schema["properties"].(map[string]interface{}) + + for _, blockKey := range []string{"replay", "agent_loop", "payload_decomposition"} { + block, ok := props[blockKey].(map[string]interface{}) + if !ok { + t.Errorf("schema does not declare the %q block", blockKey) + continue + } + required, _ := block["required"].([]interface{}) + var hasSource bool + for _, r := range required { + if s, _ := r.(string); s == "accounting_source" { + hasSource = true + } + } + if !hasSource { + t.Errorf("schema block %q does not require accounting_source", blockKey) + } + } + + // The row-provenance enum must be closed in the schema, not merely a + // string, or the contract file stops being the reviewed oracle. + defs, _ := schema["$defs"].(map[string]interface{}) + prov, ok := defs["provenance"].(map[string]interface{}) + if !ok { + t.Fatal("schema $defs.provenance missing โ€” the row-level enum must be declared once and reused") + } + enum, _ := prov["enum"].([]interface{}) + got := map[string]bool{} + for _, v := range enum { + s, _ := v.(string) + got[s] = true + } + for _, want := range []string{"measured", "computed", "estimated"} { + if !got[want] { + t.Errorf("schema $defs.provenance enum missing %q", want) + } + } + if len(enum) != 3 { + t.Errorf("schema $defs.provenance enum has %d values, want exactly 3 (closed enum)", len(enum)) + } +} + +// TestReportV2_NewBlocksSchemaValidationPython validates the sample WITH the +// new blocks against the real contract schema (python3+jsonschema when +// available). Paired with TestReportV2_SchemaDeclaresNewBlocks above, which +// proves the validation is not vacuous. +func TestReportV2_NewBlocksSchemaValidationPython(t *testing.T) { + python, err := exec.LookPath("python3") + if err != nil { + t.Skip("python3 not available") + } + if err := exec.Command(python, "-c", "import jsonschema").Run(); err != nil { + t.Skip("python3 jsonschema module not available") + } + + data, err := json.Marshal(sampleReportV2WithBlocks()) + if err != nil { + t.Fatalf("marshal: %v", err) + } + dir := t.TempDir() + reportPath := filepath.Join(dir, "report.json") + if err := os.WriteFile(reportPath, data, 0o644); err != nil { + t.Fatalf("write report: %v", err) + } + schemaPath := filepath.Clean("../specs/083-discovery-profiler/contracts/report-v2.schema.json") + + script := fmt.Sprintf(` +import json, jsonschema +schema = json.load(open(%q)) +report = json.load(open(%q)) +jsonschema.Draft202012Validator(schema).validate(report) +print("VALID") +`, schemaPath, reportPath) + out, err := exec.Command(python, "-c", script).CombinedOutput() + if err != nil { + t.Fatalf("jsonschema validation of the additive blocks failed: %v\n%s", err, out) + } +} + +// TestReportV2_SchemaRejectsMalformedBlocks is the negative half of the schema +// gate. A declaration that never rejects anything is decoration: because the +// schema has no additionalProperties:false, a validation run over a +// well-formed sample would pass identically whether or not the blocks were +// declared. These mutations must each be REFUSED by the contract file. +func TestReportV2_SchemaRejectsMalformedBlocks(t *testing.T) { + python, err := exec.LookPath("python3") + if err != nil { + t.Skip("python3 not available") + } + if err := exec.Command(python, "-c", "import jsonschema").Run(); err != nil { + t.Skip("python3 jsonschema module not available") + } + schemaPath := filepath.Clean("../specs/083-discovery-profiler/contracts/report-v2.schema.json") + + cases := []struct { + name string + mutate func(*ReportV2) + }{ + {"replay without accounting source", func(r *ReportV2) { + r.Replay.AccountingSource = AccountingSource{} + }}, + {"provider block without pinned model", func(r *ReportV2) { + r.AgentLoop.AccountingSource.Model = "" + }}, + {"row provenance outside the enum", func(r *ReportV2) { + r.Replay.Cells[0].Provenance = "assumed" + }}, + {"withheld absolute workload without a reason", func(r *ReportV2) { + r.Replay.Cells[0].WithheldReason = "" + }}, + {"headline claimed on fewer than four runs", func(r *ReportV2) { + r.AgentLoop.Cells[0].Runs = 2 + }}, + {"spec102 correction without its delta", func(r *ReportV2) { + r.PayloadDecomposition.Shapes[1].Spec102DeltaPct = nil + }}, + {"decomposition over a single fleet shape", func(r *ReportV2) { + r.PayloadDecomposition.Shapes = r.PayloadDecomposition.Shapes[:1] + }}, + {"replay missing its counterfactual label", func(r *ReportV2) { + r.Replay.Counterfactual = "" + }}, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + r := sampleReportV2WithBlocks() + tc.mutate(r) + data, err := json.Marshal(r) + if err != nil { + t.Fatalf("marshal: %v", err) + } + reportPath := filepath.Join(t.TempDir(), "report.json") + if err := os.WriteFile(reportPath, data, 0o644); err != nil { + t.Fatalf("write report: %v", err) + } + script := fmt.Sprintf(` +import json, jsonschema, sys +schema = json.load(open(%q)) +report = json.load(open(%q)) +try: + jsonschema.Draft202012Validator(schema).validate(report) +except jsonschema.ValidationError as e: + print("REJECTED:", e.message) + sys.exit(0) +print("ACCEPTED") +sys.exit(1) +`, schemaPath, reportPath) + out, err := exec.Command(python, "-c", script).CombinedOutput() + if err != nil { + t.Errorf("schema accepted a document it must reject (%s):\n%s", tc.name, out) + } + }) + } +} diff --git a/internal/contracts/activity.go b/internal/contracts/activity.go index a93525365..263ff11d3 100644 --- a/internal/contracts/activity.go +++ b/internal/contracts/activity.go @@ -50,6 +50,20 @@ type ActivityRecord struct { ParentID string `json:"parent_id,omitempty"` // Correlation id of the parent call (the code_execution whose sandbox issued this sub-call) Metadata map[string]interface{} `json:"metadata,omitempty" swaggertype:"object"` // Additional context-specific data + // Byte sizes measured pre-truncation, mirroring storage.ActivityRecord + // (Spec 069 A1). They are the only cost signal a bodies-off export carries: + // with payloads suppressed there is no text left to measure, so a consumer + // accounting for a record it cannot read has nothing else to go on. They are + // byte LENGTHS, not token counts โ€” the basis for an explicit estimate, never + // a measured figure (spec 103, contracts/replay-input.md). + // + // Zero means UNKNOWN, not free: legacy records predate the measurement and + // code-execution sub-calls record both as zero. Hence omitempty โ€” an absent + // key tells a consumer to fall to exclusion accounting, whereas a present + // zero would read as a costless call and silently understate the workload. + RequestBytes int `json:"request_bytes,omitempty"` // JSON-serialized request arguments size in bytes + ResponseBytes int `json:"response_bytes,omitempty"` // Raw upstream response size in bytes before truncation + // Sensitive data detection fields (Spec 026) HasSensitiveData bool `json:"has_sensitive_data"` // Whether sensitive data was detected DetectionTypes []string `json:"detection_types,omitempty"` // List of detection types found diff --git a/internal/httpapi/activity.go b/internal/httpapi/activity.go index 944f60f0d..c564998fa 100644 --- a/internal/httpapi/activity.go +++ b/internal/httpapi/activity.go @@ -471,6 +471,13 @@ func storageToContractActivityForExport(a *storage.ActivityRecord, includeBodies RequestID: a.RequestID, ParentID: a.ParentID, Metadata: a.Metadata, + // Pre-truncation byte lengths (Spec 069 A1). Copied unconditionally, + // NOT under includeBodies: they are sizes, not content, and the + // bodies-off export is exactly the case where they are the only cost + // signal left (spec 103). Gating them on the bodies flag would leave the + // default export with nothing to account a suppressed payload by. + RequestBytes: a.RequestBytes, + ResponseBytes: a.ResponseBytes, // Sensitive data detection fields (Spec 026) HasSensitiveData: hasSensitiveData, DetectionTypes: detectionTypes, diff --git a/internal/httpapi/activity_test.go b/internal/httpapi/activity_test.go index fbf6fdd02..1ee8b311f 100644 --- a/internal/httpapi/activity_test.go +++ b/internal/httpapi/activity_test.go @@ -854,3 +854,65 @@ func keysOf(m map[string]interface{}) []string { } return keys } + +// The pre-truncation byte lengths are the only cost signal a bodies-off export +// carries: with payloads suppressed there is no text left to measure, so a +// consumer that has to account for a record it cannot read (spec 103's replay +// loader) has nothing but these two numbers. They are byte LENGTHS, not token +// counts โ€” they support an explicit estimate, never a measured figure โ€” but +// without them a truncated record can only be dropped, and dropped records +// understate a workload silently. They must therefore survive the export +// projection in BOTH modes: bodies-off is the default and the one that needs +// them most. +func TestActivityExport_CarriesPreTruncationByteLengths(t *testing.T) { + record := &storage.ActivityRecord{ + ID: "activity-byte-lengths", + Type: "tool_call", + ServerName: "github", + ToolName: "create_issue", + Status: "success", + Timestamp: time.Now(), + RequestBytes: 1234, + ResponseBytes: 98765, + } + + withoutBodies := storageToContractActivityForExport(record, false) + assert.Equal(t, 1234, withoutBodies.RequestBytes, + "bodies-off export must still carry the request byte length") + assert.Equal(t, 98765, withoutBodies.ResponseBytes, + "bodies-off export must still carry the pre-truncation response byte length") + + withBodies := storageToContractActivityForExport(record, true) + assert.Equal(t, 1234, withBodies.RequestBytes) + assert.Equal(t, 98765, withBodies.ResponseBytes) + + // The wire names are fixed by contracts/replay-input.md and mirror the + // storage record's own tags, so a consumer reads one vocabulary end to end. + raw, err := json.Marshal(withoutBodies) + require.NoError(t, err) + var wire map[string]interface{} + require.NoError(t, json.Unmarshal(raw, &wire)) + assert.Equal(t, float64(1234), wire["request_bytes"]) + assert.Equal(t, float64(98765), wire["response_bytes"]) +} + +// Zero means "unknown" on the storage record (legacy rows, and the code +// execution sub-call path which records both counts as zero), so the fields are +// omitempty: an absent key tells the loader to fall to exclusion accounting, +// while a present zero would read as a free call and silently understate cost. +func TestActivityExport_OmitsUnknownByteLengths(t *testing.T) { + record := &storage.ActivityRecord{ + ID: "activity-legacy-no-bytes", + Type: "tool_call", + Status: "success", + Timestamp: time.Now(), + } + + raw, err := json.Marshal(storageToContractActivityForExport(record, false)) + require.NoError(t, err) + + var wire map[string]interface{} + require.NoError(t, json.Unmarshal(raw, &wire)) + assert.NotContains(t, wire, "request_bytes", "unknown must be absent, not zero") + assert.NotContains(t, wire, "response_bytes", "unknown must be absent, not zero") +} diff --git a/internal/runtime/activity_service.go b/internal/runtime/activity_service.go index 002bac090..2e0f23274 100644 --- a/internal/runtime/activity_service.go +++ b/internal/runtime/activity_service.go @@ -852,6 +852,12 @@ func (s *ActivityService) handleInternalToolCall(evt Event) { // Extract content trust metadata if present (Spec 035) contentTrust := getStringPayload(evt.Payload, "content_trust") + // Spec 103: the recorded response can be larger than the one the agent + // received (retrieve_tools stores the full pre-truncation text). Carry the + // flag onto the record so a cost recomputation can exclude it instead of + // tokenizing text the agent never paid for. + responseTruncated := getBoolPayload(evt.Payload, "response_truncated") + metadata := map[string]interface{}{ "internal_tool_name": internalToolName, } @@ -877,20 +883,21 @@ func (s *ActivityService) handleInternalToolCall(evt Event) { metadata = s.withClientInfo(metadata, sessionID) record := &storage.ActivityRecord{ - Type: storage.ActivityTypeInternalToolCall, - Source: storage.ActivitySourceMCP, - ToolName: internalToolName, - ServerName: targetServer, - Arguments: arguments, - Response: responseStr, - Status: status, - ErrorMessage: errorMsg, - DurationMs: durationMs, - Metadata: metadata, - Timestamp: evt.Timestamp, - SessionID: sessionID, - WorkSessionID: s.resolveWorkSession(sessionID), - RequestID: requestID, + Type: storage.ActivityTypeInternalToolCall, + Source: storage.ActivitySourceMCP, + ToolName: internalToolName, + ServerName: targetServer, + Arguments: arguments, + Response: responseStr, + Status: status, + ErrorMessage: errorMsg, + DurationMs: durationMs, + Metadata: metadata, + Timestamp: evt.Timestamp, + SessionID: sessionID, + WorkSessionID: s.resolveWorkSession(sessionID), + RequestID: requestID, + ResponseTruncated: responseTruncated, } // Extract user identity from auth metadata injected into arguments (server edition) diff --git a/internal/runtime/event_bus.go b/internal/runtime/event_bus.go index 17ca7db80..bf03eb53a 100644 --- a/internal/runtime/event_bus.go +++ b/internal/runtime/event_bus.go @@ -596,6 +596,23 @@ func (r *Runtime) EmitActivitySystemStop(reason, signal string, uptimeSeconds in // arguments contains the input parameters, response contains the output // intent is the intent declaration metadata func (r *Runtime) EmitActivityInternalToolCall(internalToolName, targetServer, targetTool, toolVariant, sessionID, requestID, status, errorMsg string, durationMs int64, arguments map[string]interface{}, response interface{}, intent map[string]interface{}, contentTrust string) { + r.EmitActivityInternalToolCallTruncated(internalToolName, targetServer, targetTool, toolVariant, sessionID, requestID, status, errorMsg, durationMs, arguments, response, intent, contentTrust, false) +} + +// EmitActivityInternalToolCallTruncated is EmitActivityInternalToolCall for a +// built-in whose RECORDED response is larger than the one the agent received. +// +// The non-internal path has carried this since Spec 024 (see the +// "response_truncated" key in EmitActivityToolCallCompleted); the internal path +// did not, and that asymmetry is a correctness problem rather than a cosmetic +// one. retrieve_tools deliberately writes its FULL pre-truncation response to +// the activity log while the agent consumed only the cut text, so a record that +// does not say it was truncated is indistinguishable from a complete one. +// Anything recomputing cost from the log then tokenizes text the agent never +// paid for and OVERSTATES what mcpproxy cost โ€” the one direction of error the +// Spec 103 token benchmark exists to prevent, and one that cannot be detected +// after the fact. +func (r *Runtime) EmitActivityInternalToolCallTruncated(internalToolName, targetServer, targetTool, toolVariant, sessionID, requestID, status, errorMsg string, durationMs int64, arguments map[string]interface{}, response interface{}, intent map[string]interface{}, contentTrust string, responseTruncated bool) { payload := map[string]any{ "internal_tool_name": internalToolName, "session_id": sessionID, @@ -625,6 +642,10 @@ func (r *Runtime) EmitActivityInternalToolCall(internalToolName, targetServer, t if contentTrust != "" { payload["content_trust"] = contentTrust } + // Always set, never omitempty-style conditional: absent and false must not be + // the same wire state here, because a consumer reading "no key" as "not + // truncated" is exactly the silent understatement this flag prevents. + payload["response_truncated"] = responseTruncated r.publishEvent(newEvent(EventTypeActivityInternalToolCall, payload)) } diff --git a/internal/server/mcp.go b/internal/server/mcp.go index 7d4839823..1f88b8859 100644 --- a/internal/server/mcp.go +++ b/internal/server/mcp.go @@ -807,9 +807,37 @@ func mintActivityRequestID(serverName, toolName string) string { // targetServer and targetTool are used for call_tool_* handlers // arguments contains the input parameters, response contains the output // intent is the intent declaration metadata +// +// This is the whole-response form: the built-in returned to the agent exactly +// the text it recorded. Handlers that SHAPE their text before returning it โ€” +// today only retrieve_tools, which is subject to tool_response_limit โ€” must use +// emitActivityInternalToolCallTruncated instead, so the record says so. func (p *MCPProxyServer) emitActivityInternalToolCall(internalToolName, targetServer, targetTool, toolVariant, sessionID, requestID, status, errorMsg string, durationMs int64, arguments map[string]interface{}, response interface{}, intent map[string]interface{}, contentTrust string) { + p.emitActivityInternalToolCallTruncated(internalToolName, targetServer, targetTool, toolVariant, sessionID, requestID, status, errorMsg, durationMs, arguments, response, intent, contentTrust, false) +} + +// emitActivityInternalToolCallTruncated is emitActivityInternalToolCall for a +// handler whose recorded response is LARGER than what the agent received, +// mirroring the responseTruncated argument the non-internal path already +// carries through emitActivityToolCallCompleted. +// +// Why the flag has to reach the record and not just the log (Spec 103): the +// activity log deliberately stores the FULL pre-truncation retrieve_tools +// response while the agent only ever consumed the cut text. A record that does +// not say it was truncated is indistinguishable from a complete one, so anything +// that recomputes cost from the log โ€” the token benchmark's replay loader is the +// motivating consumer โ€” tokenizes text the agent never paid for and OVERSTATES +// what mcpproxy cost. That is the one direction of error the benchmark exists to +// prevent, and it is not detectable after the fact. +// +// The flag reaches the stored record through Runtime.EmitActivityInternalToolCallTruncated +// (internal/runtime/event_bus.go), which carries "response_truncated" in the +// event payload, and ActivityService.handleInternalToolCall, which reads it back +// onto ActivityRecord.ResponseTruncated โ€” the same two hops the non-internal +// path has always used. +func (p *MCPProxyServer) emitActivityInternalToolCallTruncated(internalToolName, targetServer, targetTool, toolVariant, sessionID, requestID, status, errorMsg string, durationMs int64, arguments map[string]interface{}, response interface{}, intent map[string]interface{}, contentTrust string, responseTruncated bool) { if p.mainServer != nil && p.mainServer.runtime != nil { - p.mainServer.runtime.EmitActivityInternalToolCall(internalToolName, targetServer, targetTool, toolVariant, sessionID, requestID, status, errorMsg, durationMs, arguments, response, intent, contentTrust) + p.mainServer.runtime.EmitActivityInternalToolCallTruncated(internalToolName, targetServer, targetTool, toolVariant, sessionID, requestID, status, errorMsg, durationMs, arguments, response, intent, contentTrust, responseTruncated) } } @@ -2060,8 +2088,10 @@ func (p *MCPProxyServer) handleRetrieveToolsWithMode(ctx context.Context, reques // Emit success event with args and response (Spec 024). The FULL response // goes to the activity log โ€” truncation only shapes what the agent sees - // (same order handleReadCache uses). - p.emitActivityInternalToolCall("retrieve_tools", "", "", "", sessionID, requestID, "success", "", time.Since(startTime).Milliseconds(), activityArgs, response, nil, "") + // (same order handleReadCache uses). Which is exactly why wasTruncated has + // to travel with it: the stored response is not what the agent paid for, and + // nothing downstream can tell the two apart without the flag (Spec 103). + p.emitActivityInternalToolCallTruncated("retrieve_tools", "", "", "", sessionID, requestID, "success", "", time.Since(startTime).Milliseconds(), activityArgs, response, nil, "", wasTruncated) return mcp.NewToolResultText(text), nil } diff --git a/internal/server/mcp_activity_truncation_test.go b/internal/server/mcp_activity_truncation_test.go new file mode 100644 index 000000000..c504acabb --- /dev/null +++ b/internal/server/mcp_activity_truncation_test.go @@ -0,0 +1,171 @@ +package server + +import ( + "context" + "testing" + "time" + + "github.com/mark3labs/mcp-go/mcp" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "go.uber.org/zap" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/cache" + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" + "github.com/smart-mcp-proxy/mcpproxy-go/internal/index" + "github.com/smart-mcp-proxy/mcpproxy-go/internal/runtime" + "github.com/smart-mcp-proxy/mcpproxy-go/internal/secret" + "github.com/smart-mcp-proxy/mcpproxy-go/internal/storage" + "github.com/smart-mcp-proxy/mcpproxy-go/internal/truncate" + "github.com/smart-mcp-proxy/mcpproxy-go/internal/upstream" +) + +// Spec 103 (T005). The activity log stores the FULL pre-truncation +// retrieve_tools response while the agent only ever received the truncated +// text. If the record does not say it was truncated, a truncated record is +// indistinguishable from a complete one โ€” and the benchmark loader, which +// tokenizes the stored response to recompute what a workload cost, would +// tokenize text the agent never paid for and OVERSTATE the cost. Overstating +// mcpproxy's own cost is the one direction of error the benchmark cannot be +// allowed to make silently, so the flag has to reach the record, not just the +// log line. +// +// The proxy is wired to a REAL Runtime with its ActivityService running rather +// than to a stub emitter: what matters is the record an operator would later +// export, and only the real service builds that record. + +// newTruncatingRetrieveToolsProxy builds a runtime-backed proxy whose response +// limit is small enough that a two-tool discovery response is guaranteed to +// exceed it. The shared createTestProxyWithRuntime helper pins the truncator to +// an unlimited one, which is the opposite of what this test needs. +func newTruncatingRetrieveToolsProxy(t *testing.T, responseLimit int) (*MCPProxyServer, *runtime.Runtime) { + t.Helper() + + logger := zap.NewNop() + + cfg := config.DefaultConfig() + cfg.DataDir = t.TempDir() + cfg.Listen = "127.0.0.1:0" + cfg.ToolsLimit = 20 + cfg.ToolResponseLimit = responseLimit + cfg.Servers = []*config.ServerConfig{{Name: "github", Enabled: true}} + + rt, err := runtime.New(cfg, "", logger) + require.NoError(t, err) + t.Cleanup(func() { _ = rt.Close() }) + + sm := rt.StorageManager() + require.NotNil(t, sm, "runtime must expose a storage manager") + + idx, err := index.NewManager(t.TempDir(), logger) + require.NoError(t, err) + t.Cleanup(func() { _ = idx.Close() }) + + um := upstream.NewManager(logger, cfg, nil, secret.NewResolver(), nil) + + cm, err := cache.NewManager(sm.GetDB(), logger) + require.NoError(t, err) + t.Cleanup(func() { cm.Close() }) + + tr := truncate.NewTruncator(responseLimit) + + mainSrv := &Server{runtime: rt} + proxy := NewMCPProxyServer(sm, idx, um, cm, func() *truncate.Truncator { return tr }, + logger, mainSrv, false, cfg, rt.SignatureCache()) + + // The service is what turns an emitted event into a persisted record; + // production starts it the same way (internal/runtime/lifecycle.go). + go rt.ActivityService().Start(rt.AppContext(), rt) + + return proxy, rt +} + +// awaitRetrieveToolsActivity polls until the retrieve_tools record lands. +// Emission publishes onto the event bus synchronously but the service drains it +// on its own goroutine, so a bare read after the handler returns is a race. +func awaitRetrieveToolsActivity(t *testing.T, sm *storage.Manager) *storage.ActivityRecord { + t.Helper() + + deadline := time.Now().Add(5 * time.Second) + for { + records, _, err := sm.ListActivities(storage.ActivityFilter{Limit: 50}) + require.NoError(t, err) + for _, rec := range records { + if rec.Type == storage.ActivityTypeInternalToolCall && rec.ToolName == "retrieve_tools" { + return rec + } + } + if time.Now().After(deadline) { + t.Fatal("no retrieve_tools activity record was persisted within 5s") + } + time.Sleep(10 * time.Millisecond) + } +} + +// TestRetrieveTools_TruncatedResponseIsFlaggedOnTheActivityRecord is the +// guard: a retrieve_tools call whose response was cut must leave a record that +// SAYS it was cut. +func TestRetrieveTools_TruncatedResponseIsFlaggedOnTheActivityRecord(t *testing.T) { + // Small enough that two indexed tools with real schemas cannot fit, large + // enough that the truncator's own banner still has room. + proxy, rt := newTruncatingRetrieveToolsProxy(t, 400) + + require.NoError(t, proxy.storage.SaveUpstreamServer(&config.ServerConfig{Name: "github", Enabled: true})) + for _, tool := range []string{"create_issue", "create_pull_request"} { + require.NoError(t, proxy.index.IndexTool(&config.ToolMetadata{ + Name: tool, + ServerName: "github", + Description: "Create a GitHub " + tool + " with a title, a body, labels, assignees and milestones", + ParamsJSON: `{"type":"object","properties":{"title":{"type":"string","description":"the title"},"body":{"type":"string","description":"the body"},"labels":{"type":"array","items":{"type":"string"}}}}`, + Hash: "hash-" + tool, + })) + } + + req := mcp.CallToolRequest{} + req.Params.Arguments = map[string]interface{}{ + "query": "create", "limit": float64(20), "detail": config.ToolResponseModeFull, + } + result, err := proxy.handleRetrieveTools(context.Background(), req) + require.NoError(t, err) + require.NotNil(t, result) + + rec := awaitRetrieveToolsActivity(t, rt.StorageManager()) + + // Premise check. If the response were NOT actually cut, the assertion + // below would be asserting nothing โ€” and this test's whole value is that + // it fails when the flag is missing, not when the fixture stops truncating. + require.Less(t, len(resultText(t, result)), len(rec.Response), + "fixture must actually truncate: the agent's text has to be shorter than the stored full response") + + assert.True(t, rec.ResponseTruncated, + "the truncated retrieve_tools response must be flagged on the activity record; "+ + "without the flag a benchmark loader tokenizes the stored FULL response and overstates agent cost") +} + +// TestRetrieveTools_UntruncatedResponseIsNotFlagged is the other half of the +// contract: the flag must mean something. A blanket true would let the loader +// exclude every retrieve_tools record and lose the whole discovery surface from +// the accounting. +func TestRetrieveTools_UntruncatedResponseIsNotFlagged(t *testing.T) { + proxy, rt := newTruncatingRetrieveToolsProxy(t, 0) // 0 = unlimited + + require.NoError(t, proxy.storage.SaveUpstreamServer(&config.ServerConfig{Name: "github", Enabled: true})) + require.NoError(t, proxy.index.IndexTool(&config.ToolMetadata{ + Name: "create_issue", + ServerName: "github", + Description: "Create a GitHub issue with a title and body", + ParamsJSON: `{"type":"object","properties":{"title":{"type":"string"}}}`, + Hash: "hash-create-issue", + })) + + req := mcp.CallToolRequest{} + req.Params.Arguments = map[string]interface{}{ + "query": "create issue", "limit": float64(20), "detail": config.ToolResponseModeFull, + } + _, err := proxy.handleRetrieveTools(context.Background(), req) + require.NoError(t, err) + + rec := awaitRetrieveToolsActivity(t, rt.StorageManager()) + assert.False(t, rec.ResponseTruncated, + "a complete response must not be flagged truncated, or the loader excludes everything") +} diff --git a/oas/docs.go b/oas/docs.go index ee5b3a2dd..530e07a6a 100644 --- a/oas/docs.go +++ b/oas/docs.go @@ -6,7 +6,7 @@ import "github.com/swaggo/swag/v2" const docTemplate = `{ "schemes": {{ marshal .Schemes }}, - "components": {"schemas":{"config.ConcurrencyDefaults":{"description":"ServerConcurrencyDefaults is scope (b) of FR-020: the blanket per-server\ndefault set inherited by every server that does not override a setting.\nAbsent (the default) = no per-server limiting unless a server configures\nit explicitly. File/API-configured only โ€” no env scheme (FR-022).","properties":{"max_concurrent_requests":{"type":"integer"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"}},"type":"object"},"config.Config":{"properties":{"activity_cleanup_interval_min":{"description":"Background cleanup interval in minutes (default: 60)","type":"integer"},"activity_max_records":{"description":"Max records before pruning (default: 100000)","type":"integer"},"activity_max_response_size":{"description":"Response truncation limit in bytes (default: 65536)","type":"integer"},"activity_max_size_mb":{"description":"Max total activity-log size in MB before pruning oldest (default: 256, 0=disabled)","type":"integer"},"activity_retention_days":{"description":"Activity logging settings (RFC-003)","type":"integer"},"aggregate_upstream_prompts":{"description":"AggregateUpstreamPrompts, when true, aggregates every connected upstream\nserver's advertised MCP prompts into mcpproxy's own prompts/list\n(exposed as \"\u003cserver\u003e__\u003cprompt\u003e\"). OFF by default: users are safe by\ndefault and opt in deliberately. EnablePrompts still governs the built-in\nprompts + the prompts capability; this flag gates ONLY the upstream\naggregation performed by RefreshPrompts. Hot-reloadable.","type":"boolean"},"allow_private_registry_fetch":{"description":"AllowPrivateRegistryFetch opts out of the registry SSRF guard (MCP-1076,\nCWE-918). By default (false) registry fetches refuse any host that is โ€” or\nresolves to โ€” a non-routable address (loopback, RFC1918/CGNAT private,\nlink-local incl. the 169.254.169.254 cloud-metadata endpoint), so a\nmalicious or typo'd registry source cannot turn the daemon into a\nrequest-forgery vector against internal services.\n\nThis opt-out is BLANKET (all-or-nothing): setting it true disables the\nguard for EVERY non-routable range at once โ€” loopback, RFC1918/CGNAT\nprivate, link-local AND the 169.254.169.254 cloud-metadata endpoint. There\nis no way to allow only loopback; enabling it for a localhost dev registry\nalso re-opens the cloud-metadata SSRF vector. Set true ONLY when you\nintentionally run a trusted registry mirror on an internal/private address,\nideally on a host with no cloud-metadata exposure. The change takes effect\nonly on daemon (re)start or config reload.","type":"boolean"},"allow_server_add":{"type":"boolean"},"allow_server_remove":{"type":"boolean"},"api_key":{"description":"Security settings","type":"string"},"call_tool_timeout":{"type":"string"},"check_server_repo":{"description":"Repository detection settings","type":"boolean"},"code_execution_max_parallel":{"description":"Default concurrency for call_tools() batches (1-32, default: 8)","type":"integer"},"code_execution_max_tool_calls":{"description":"Max tool calls per execution (0 = unlimited, default: 0)","type":"integer"},"code_execution_pool_size":{"description":"JavaScript runtime pool size (default: 10)","type":"integer"},"code_execution_timeout_ms":{"description":"Timeout in milliseconds (default: 120000, max: 600000)","type":"integer"},"data_dir":{"type":"string"},"debug_search":{"type":"boolean"},"direct_tool_response_mode":{"description":"DirectToolResponseMode selects the serialization of the DIRECT\nenumeration surface (Spec 102). Valid values: \"\" (= full), \"full\"\n(default: today's schema-bearing entries), \"deferred\" (description +\ncompact signature, with a minimal permissive input schema; upstream\ninputSchema and outputSchema are stripped and recovered on demand via\ndescribe_tool).\n\nDeliberately NOT an extension of tool_response_mode: reusing that axis\nwould silently change /mcp/all output for every deployment already\nrunning compact, which FR-015 forbids. Serialization-only โ€” it never\nchanges WHICH tools are listed, only how (FR-008). Hot-reloadable.","type":"string"},"disable_management":{"type":"boolean"},"docker_isolation":{"$ref":"#/components/schemas/config.DockerIsolationConfig"},"docker_recovery":{"$ref":"#/components/schemas/config.DockerRecoveryConfig"},"enable_code_execution":{"description":"Code execution settings","type":"boolean"},"enable_prompts":{"description":"Prompts settings","type":"boolean"},"enable_socket":{"description":"Enable Unix socket/named pipe for local IPC (default: true)","type":"boolean"},"enable_tray":{"description":"Deprecated: EnableTray is unused and has no runtime effect. Kept for backward compatibility.","type":"boolean"},"environment":{"$ref":"#/components/schemas/secureenv.EnvConfig"},"features":{"$ref":"#/components/schemas/config.FeatureFlags"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned stdio upstream servers (MCP-2769). OFF by\ndefault: proxy URLs commonly embed credentials (http://user:pass@proxy), so\nforwarding them to every upstream is a credential-leak risk. When enabled,\nvalues are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"health_check_interval":{"description":"Discovery \u0026 health-check cadence (spec 074, #608). Both are *Duration\ntri-state pointers: nil = inherit the built-in default; a pointer to 0s =\nthe loop is disabled; a positive value = that interval. Defaults live only\nin the resolvers (ResolveHealthCheckInterval / ResolveToolDiscoveryInterval)\nso an unset key behaves exactly as before this feature (SC-005). Validated\nin Validate(): health-check โˆˆ {0} โˆช [5s,1h]; tool-discovery โˆˆ {0} โˆช [30s,24h].","type":"string"},"http_idle_timeout":{"description":"HTTPIdleTimeout caps how long an idle keep-alive connection is kept open.\nUnset = 180s. \"0s\" removes the dedicated idle deadline, but net/http then\nfalls back to ReadTimeout โ€” idle is fully unbounded only when\nhttp_read_timeout is also \"0s\". Requires a restart.","type":"string"},"http_read_timeout":{"description":"HTTPReadTimeout caps how long reading a whole request (headers + body)\nmay take. Unset = 120s; \"0s\" disables it. Requires a restart.","type":"string"},"http_write_timeout":{"description":"HTTPWriteTimeout caps how long producing a whole response may take on\nnon-streaming endpoints (REST, Web UI, health). Unset = 120s; \"0s\"\ndisables it globally. MCP and SSE /events routes are exempt by design.","type":"string"},"init_timeout":{"description":"InitTimeout is the global default deadline for an upstream's MCP\n` + "`" + `initialize` + "`" + ` handshake (MCP-3322 / GH #760). *Duration tri-state: nil =\ninherit the built-in 30s default; a positive value = that deadline. A\nper-server InitTimeout overrides this. Resolved by ResolveInitTimeout;\nvalidated to {0} โˆช [1s, 30m] in Validate(). Servers doing legitimate\nfirst-run warmup (cache/index build) before answering ` + "`" + `initialize` + "`" + ` can\nraise this so they are not killed mid-startup.","type":"string"},"instructions":{"description":"Instructions text returned in the MCP initialize response to guide AI agents.\nWhen empty, a built-in default is used that explains retrieve_tools workflow.","type":"string"},"intent_declaration":{"$ref":"#/components/schemas/config.IntentDeclarationConfig"},"listen":{"type":"string"},"logging":{"$ref":"#/components/schemas/config.LogConfig"},"max_concurrent_requests":{"description":"Concurrency limits (spec 093, GH #955). Scope (a) of FR-020: the GLOBAL\nAGGREGATE limiter โ€” one proxy-wide cap on concurrently running upstream\ntool calls, with its own bounded wait queue. Tri-state pointers: absent =\nthe limiter does not exist (default, zero behavior change); an explicit 0\nmax also disables it; positive = that cap. This scope is NEVER a\nper-server inheritance source โ€” per-server values come from\nServerConcurrencyDefaults / the per-server overrides โ€” but a server's\neffective concurrency is bounded by BOTH its own limiter and this one.\nResolved by ResolveGlobalConcurrency; hot-reloadable; overridable via\nMCPPROXY_MAX_CONCURRENT_REQUESTS / _QUEUE_SIZE / _QUEUE_TIMEOUT (FR-022).","type":"integer"},"max_result_size_chars":{"description":"Advertised on every tool as ` + "`" + `_meta.anthropic/maxResultSizeChars` + "`" + `; raises Claude Code's inline-response ceiling from 50k to up to 500k chars. Set to 0 to disable.","type":"integer"},"mcpServers":{"items":{"$ref":"#/components/schemas/config.ServerConfig"},"type":"array","uniqueItems":false},"oauth_expiry_warning_hours":{"description":"Health status settings","type":"number"},"observability":{"$ref":"#/components/schemas/config.ObservabilityConfig"},"output_sanitisation":{"$ref":"#/components/schemas/config.OutputSanitisationConfig"},"output_validation":{"$ref":"#/components/schemas/config.OutputValidationConfig"},"profiles":{"description":"Profiles are optional named, server-scoped views exposed at /mcp/p/\u003cname\u003e\n(Spec 057). Absent/empty is fully supported โ€” /mcp is unchanged and configs\nwithout this key serialize byte-identically (SC-004).","items":{"$ref":"#/components/schemas/config.ProfileConfig"},"type":"array","uniqueItems":false},"quarantine_enabled":{"description":"QuarantineEnabled controls whether quarantine is active. It gates two\nthings together:\n 1. Server-level auto-quarantine for newly added servers (issue #370).\n When true, servers added via the upstream_servers MCP tool or the\n REST API default to quarantined=true; when false, they default to\n quarantined=false. Explicit per-request values always win.\n 2. Tool-level quarantine (Spec 032): per-tool SHA-256 approval of\n tool descriptions/schemas.\nWhen nil (default), quarantine is enabled (secure by default). Set to\nexplicit false to opt out of both. Per-server SkipQuarantine still\napplies for the tool-level check on individual servers.","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"read_only_mode":{"type":"boolean"},"registries":{"description":"Registries configuration for MCP server discovery","items":{"$ref":"#/components/schemas/config.RegistryEntry"},"type":"array","uniqueItems":false},"registries_locked":{"description":"RegistriesLocked is an enterprise stub knob (MCP-866): when true, runtime\nadditions of custom registries (e.g. ` + "`" + `registry add-source` + "`" + `, the REST/MCP\nadd-source surface) are rejected so an administrator can pin the discovery\nsources. Built-in defaults are unaffected. Documented but otherwise inert\nbeyond the add-source rejection.","type":"boolean"},"require_mcp_auth":{"description":"Require authentication on /mcp endpoint (default: false)","type":"boolean"},"reveal_secret_headers":{"description":"RevealSecretHeaders, when true, disables the redaction of the\nsecret-bearing server fields โ€” sensitive header values (Authorization,\nX-API-Key, Cookie, โ€ฆ), env-var secrets, and URL query credentials โ€” in\nresponses from the ` + "`" + `upstream_servers` + "`" + ` MCP tool, the ` + "`" + `/api/v1/servers` + "`" + `\nREST API, and the SSE event stream. It also lets URL secrets echoed\ninto last_error / health.detail through unscrubbed.\n\nDefault false โ€” sensitive values are surfaced masked as\n` + "`" + `โ€ขโ€ขโ€ขโ€ข\u003clast2\u003e (\u003cN\u003e chars)` + "`" + ` (error strings use ` + "`" + `***REDACTED***` + "`" + `) so an\nMCP agent cannot read Bearer tokens / API keys / URL secrets out of\nanother upstream's config (PR #425, issue #872). ${env:โ€ฆ}/${keyring:โ€ฆ}\nreferences are labels, not secrets, and pass through unchanged.\n\nThe Web UI / macOS tray edit forms work without seeing the real\nvalues: PATCH /api/v1/servers/{id} deep-merges (omitted keys are\npreserved, see ` + "`" + `headers_remove` + "`" + ` / ` + "`" + `env_remove` + "`" + ` for explicit\ndeletes), so clients compute a diff and only send the keys that\nactually changed. Redacted-but-unchanged values never round-trip\nโ€” the backend keeps the real string. Set this to true if a\ndownstream tool genuinely needs raw values in the response.","type":"boolean"},"routing_mode":{"description":"Routing mode (Spec 031): how MCP tools are exposed to clients\nValid values: \"retrieve_tools\" (default), \"direct\", \"code_execution\"","type":"string"},"security":{"$ref":"#/components/schemas/config.SecurityConfig"},"sensitive_data_detection":{"$ref":"#/components/schemas/config.SensitiveDataDetectionConfig"},"server_concurrency_defaults":{"$ref":"#/components/schemas/config.ConcurrencyDefaults"},"telemetry":{"$ref":"#/components/schemas/config.TelemetryConfig"},"tls":{"$ref":"#/components/schemas/config.TLSConfig"},"tokenizer":{"$ref":"#/components/schemas/config.TokenizerConfig"},"tool_discovery_interval":{"type":"string"},"tool_response_limit":{"type":"integer"},"tool_response_mode":{"description":"Tool response mode (Spec 085): how retrieve_tools serializes results.\nValid values: \"\" (= full), \"full\" (default: today's schema-bearing\nentries), \"compact\" (signature + first-sentence entries). Orthogonal to\nrouting_mode โ€” routing_mode selects the tool SURFACE, this selects the\nSERIALIZATION within the retrieve_tools surface. Serialization-only: it\nnever affects the query, ranking, or result set. Hot-reloadable.","type":"string"},"tool_response_session_risk_warning":{"description":"ToolResponseSessionRiskWarning controls whether the prose ` + "`" + `warning` + "`" + ` field\nis included in the ` + "`" + `session_risk` + "`" + ` object returned by ` + "`" + `retrieve_tools` + "`" + `.\nThe structured fields (level, lethal_trifecta, has_open_world_tools, etc.)\nare always included. Default: false (quiet for LLM clients) โ€” see issue #406.\nMost tools lack annotations, so the MCP-spec defaults treat them as fully\npermissive across all three risk axes, which makes the prose warning fire\non almost every call and wastes tokens.","type":"boolean"},"tools_limit":{"type":"integer"},"toon_min_savings_pct":{"description":"ToonMinSavingsPct is the minimum byte-savings percentage (validated\n1-90; 0/unset โ†’ 15) the complete TOON emission (marker + hint + body)\nmust achieve over the exact passthrough emission for adaptive mode to\nencode a block. Byte savings approximate token savings for the tabular\npayload class; the spec-083 profiler reports true token deltas.\nGlobal-only (no per-server override, FR-001).","type":"integer"},"toon_output":{"description":"ToonOutput selects the TOON encoding mode for call_tool_* result text\nblocks (spec 084): \"off\" (default โ€” responses byte-identical to\npre-feature behavior), \"adaptive\" (encode only tabular-uniform payloads\nthat beat compact JSON by ToonMinSavingsPct), or \"always\"\n(benchmark/debug only โ€” encodes every JSON-parseable block and can\nINCREASE token cost). Per-server override: ServerConfig.ToonOutput.\nResolved by ResolveToonOutput; hot-reloadable.","type":"string"},"top_k":{"description":"Deprecated: TopK is superseded by ToolsLimit and has no runtime effect. Kept for backward compatibility.","type":"integer"},"tray_endpoint":{"description":"Tray endpoint override (unix:// or npipe://)","type":"string"},"trusted_hosts":{"description":"TrustedHosts lists non-loopback Host header values accepted on loopback\nlisteners (GH #898). DNS-rebinding protection rejects requests whose Host\nheader is not a loopback address when mcpproxy listens on loopback; a\nreverse proxy (nginx โ†’ 127.0.0.1) forwarding the public domain in Host\ntrips it. Entries are hostnames, case-insensitive; an entry without a\nport matches any port, with a port it must match exactly; a leading dot\n(\".example.com\") is a subdomain wildcard. The single entry \"*\" disables\nHost and Origin validation entirely. The same list also validates the\nOrigin header when present (MCP spec DNS-rebinding defense). Empty\n(default) keeps full protection. Env override: MCPPROXY_TRUSTED_HOSTS\n(comma-separated).","items":{"type":"string"},"type":"array","uniqueItems":false},"update_check":{"$ref":"#/components/schemas/config.UpdateCheckConfig"}},"type":"object"},"config.CustomPattern":{"properties":{"category":{"description":"Category (defaults to \"custom\")","type":"string"},"keywords":{"description":"Keywords to match (mutually exclusive with Regex)","items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"description":"Unique identifier for this pattern","type":"string"},"regex":{"description":"Regex pattern (mutually exclusive with Keywords)","type":"string"},"severity":{"description":"Risk level: critical, high, medium, low","type":"string"}},"type":"object"},"config.DeepScanConfig":{"description":"DeepScan is the opt-in \"deep scan\" layer (Spec 077 US3). It subsumes the\ndeprecated top-level scanner_fetch_package_source / scanner_disable_no_new_privileges\nkeys (migrated on load) and gates the heavy Docker-based scanners + source\nextraction. Disabled by default (FR-006): only the deterministic in-process\nbaseline scanner runs. A deep-scan failure NEVER changes the baseline verdict\n(FR-007/FR-008).","properties":{"disable_no_new_privileges":{"description":"DisableNoNewPrivileges, when true, omits the ` + "`" + `--security-opt\nno-new-privileges` + "`" + ` flag from scanner container runs (snap-docker/AppArmor\nescape hatch). Absorbs the deprecated top-level\nscanner_disable_no_new_privileges. Default false.","type":"boolean"},"enabled":{"description":"Enabled is the master opt-in for the heavy layer (FR-006). Default false.","type":"boolean"},"fetch_package_source":{"description":"FetchPackageSource controls whether the scanner fetches the PUBLISHED\nsource of package-runner servers (npx/uvx) โ€” without executing it โ€” when\nno local source is available. Absorbs the deprecated top-level\nscanner_fetch_package_source. Default (nil) is ENABLED within deep scan.","type":"boolean"},"scanners":{"description":"Scanners optionally restricts which deep scanners may run under the\numbrella (by scanner id). Empty โ‡’ all enabled deep scanners are eligible.","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.DockerIsolationConfig":{"description":"Docker isolation settings","properties":{"cpu_limit":{"description":"CPU limit for containers","type":"string"},"default_images":{"additionalProperties":{"type":"string"},"description":"Map of runtime type to Docker image","type":"object"},"enable_cache_volume":{"description":"Mount shared cache volumes for faster restarts (default: true)","type":"boolean"},"enabled":{"description":"Global enable/disable for Docker isolation (legacy; superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments","items":{"type":"string"},"type":"array","uniqueItems":false},"log_driver":{"description":"Docker log driver (default: json-file)","type":"string"},"log_max_files":{"description":"Maximum number of log files (default: 3)","type":"string"},"log_max_size":{"description":"Maximum size of log files (default: 100m)","type":"string"},"memory_limit":{"description":"Memory limit for containers","type":"string"},"mode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true โ‡’ docker, false โ‡’ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"network_mode":{"description":"Docker network mode (default: bridge)","type":"string"},"registry":{"description":"Custom registry (defaults to docker.io)","type":"string"},"timeout":{"description":"Container startup timeout","type":"string"}},"type":"object"},"config.DockerRecoveryConfig":{"description":"Docker recovery settings","properties":{"enabled":{"description":"Enable Docker recovery monitoring (default: true)","type":"boolean"},"max_retries":{"description":"Maximum retry attempts (0 = unlimited)","type":"integer"},"notify_on_failure":{"description":"Show notification on recovery failure (default: true)","type":"boolean"},"notify_on_retry":{"description":"Show notification on each retry (default: false)","type":"boolean"},"notify_on_start":{"description":"Show notification when recovery starts (default: true)","type":"boolean"},"notify_on_success":{"description":"Show notification on successful recovery (default: true)","type":"boolean"},"persistent_state":{"description":"Save recovery state across restarts (default: true)","type":"boolean"}},"type":"object"},"config.FeatureFlags":{"description":"Deprecated: Features flags are unused and have no runtime effect. Kept for backward compatibility.","properties":{"enable_async_storage":{"type":"boolean"},"enable_caching":{"type":"boolean"},"enable_contract_tests":{"type":"boolean"},"enable_debug_logging":{"description":"Development features","type":"boolean"},"enable_docker_isolation":{"type":"boolean"},"enable_event_bus":{"type":"boolean"},"enable_health_checks":{"type":"boolean"},"enable_metrics":{"type":"boolean"},"enable_oauth":{"description":"Security features","type":"boolean"},"enable_observability":{"description":"Observability features","type":"boolean"},"enable_quarantine":{"type":"boolean"},"enable_runtime":{"description":"Runtime features","type":"boolean"},"enable_search":{"description":"Storage features","type":"boolean"},"enable_sse":{"type":"boolean"},"enable_tracing":{"type":"boolean"},"enable_tray":{"type":"boolean"},"enable_web_ui":{"description":"UI features","type":"boolean"}},"type":"object"},"config.IntentDeclarationConfig":{"description":"Intent declaration settings (Spec 018)","properties":{"strict_server_validation":{"description":"StrictServerValidation controls whether server annotation mismatches\ncause rejection (true) or just warnings (false).\nDefault: true (reject mismatches)","type":"boolean"}},"type":"object"},"config.IsolationConfig":{"description":"Per-server isolation settings","properties":{"enabled":{"description":"Enable Docker isolation for this server (nil = inherit global; legacy, superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments for this server","items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"description":"Custom Docker image (overrides default)","type":"string"},"log_driver":{"description":"Docker log driver override for this server","type":"string"},"log_max_files":{"description":"Maximum number of log files override","type":"string"},"log_max_size":{"description":"Maximum size of log files override","type":"string"},"mode":{"$ref":"#/components/schemas/config.IsolationMode"},"network_mode":{"description":"Custom network mode for this server","type":"string"},"working_dir":{"description":"Custom working directory in container","type":"string"}},"type":"object"},"config.IsolationMode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true โ‡’ docker, false โ‡’ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"config.LogConfig":{"description":"Logging configuration","properties":{"compress":{"type":"boolean"},"enable_console":{"type":"boolean"},"enable_file":{"type":"boolean"},"filename":{"type":"string"},"json_format":{"type":"boolean"},"level":{"type":"string"},"log_dir":{"description":"Custom log directory","type":"string"},"max_age":{"description":"days","type":"integer"},"max_backups":{"description":"number of backup files","type":"integer"},"max_size":{"description":"MB","type":"integer"}},"type":"object"},"config.MetricsExporterConfig":{"description":"Metrics gates the Prometheus /metrics scrape endpoint (MCP-32). Disabled\nby default โ€” operators opt in for k8s/enterprise deployments.","properties":{"enabled":{"description":"Enabled exposes /metrics on the existing HTTP listener when true.","type":"boolean"}},"type":"object"},"config.OAuthConfig":{"description":"OAuth configuration (keep even when empty to signal OAuth requirement)","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"description":"Additional OAuth parameters (e.g., RFC 8707 resource)","type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_uri":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ObservabilityConfig":{"description":"Observability settings (Spec 069): usage aggregate cache/persistence cadence.","properties":{"metrics":{"$ref":"#/components/schemas/config.MetricsExporterConfig"},"tracing":{"$ref":"#/components/schemas/config.TracingExporterConfig"},"usage_cache_ttl":{"description":"UsageCacheTTL bounds the freshness of the usage endpoint's read cache for\nwide windows (FR-005). Default 5s.","type":"string"},"usage_persist_interval":{"description":"UsagePersistInterval is how often the actor-owned usage aggregate snapshot\nis flushed to storage. Default 30s.","type":"string"}},"type":"object"},"config.OutputSanitisationConfig":{"description":"Output sanitisation settings (Spec 054 Track B)","properties":{"max_redactions":{"description":"cap on redactions per response; default 100","type":"integer"},"response_action":{"description":"\"spotlight\" | \"redact\" | \"block\"; default \"spotlight\"","type":"string"},"spotlight_untrusted":{"description":"wrap untrusted output in spotlight markers; default true","type":"boolean"},"strip_classes":{"description":"classes to strip: ansi/c0c1/bidi/zero_width","items":{"type":"string"},"type":"array","uniqueItems":false},"strip_control_chars":{"description":"strip control-character classes; default false","type":"boolean"}},"type":"object"},"config.OutputValidationConfig":{"description":"Output-schema validation settings (Spec 056)","properties":{"max_bytes":{"description":"structured payload byte cap; default 5\u003c\u003c20","type":"integer"},"max_depth":{"description":"nesting depth cap; default 64","type":"integer"},"missing_structured_content":{"description":"\"allow\" | \"block\"; default \"allow\"","type":"string"},"mode":{"description":"\"off\" | \"warn\" | \"strict\"; default \"warn\"","type":"string"}},"type":"object"},"config.ProfileConfig":{"properties":{"name":{"description":"URL slug, validated","type":"string"},"servers":{"description":"references to mcpServers[].name","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.RegistryEntry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag for this registry (MCP-866):\nRegistryProvenanceOfficial for built-in defaults, RegistryProvenanceCustom\nfor user-added registries. It is authoritatively (re)computed by the\nregistries merge from whether the ID is a shipped default โ€” a user cannot\nclaim \"official\" by writing it into their config.","type":"string"},"requires_key":{"description":"RequiresKey marks a registry that needs an API key to be queried. When\ntrue and no key is configured, the registry is skipped/marked unavailable\nrather than failing the whole search (FR-008).","type":"boolean"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"type":"string"}},"type":"object"},"config.SecurityConfig":{"description":"Security scanner settings (Spec 039)","properties":{"auto_baseline_scan":{"description":"AutoBaselineScan is the kill-switch for the AUTOMATIC, informational\nPass-1 baseline scan: the free in-process TPA scan mcpproxy runs for every\nnewly admitted server (any trust mode) and, once per installation, over\npre-existing servers that have never been scanned.\n\nInformational ONLY: the resulting verdict populates the security badge and\nthe scan summary, and NEVER gates quarantine or approval. The\ntrust_mode:\"scan\" admission gate is a separate path and is unaffected by\nthis flag.\n\nDefault (nil) is ENABLED. Set to false to suppress every automatic scan\n(manual scans keep working). Env override: MCPPROXY_AUTO_BASELINE_SCAN,\nwhich wins over this field on every path.","type":"boolean"},"deep_scan":{"$ref":"#/components/schemas/config.DeepScanConfig"},"integrity_check_interval":{"type":"string"},"integrity_check_on_restart":{"type":"boolean"},"runtime_read_only":{"type":"boolean"},"runtime_tmpfs_size":{"type":"string"},"scan_timeout_default":{"type":"string"},"scanner_disable_no_new_privileges":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.DisableNoNewPrivileges\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.IsDisableNoNewPrivileges. Cleared after migration.\n\nScannerDisableNoNewPrivileges, when true, omits the\n` + "`" + `--security-opt no-new-privileges` + "`" + ` flag from scanner container runs.\n\nBackground: snap-installed Docker on Ubuntu confines dockerd under the\n` + "`" + `snap.docker.dockerd` + "`" + ` AppArmor profile. When runc tries to transition\nthe container into the inner ` + "`" + `docker-default` + "`" + ` profile to exec the\nentrypoint, AppArmor refuses the transition because NO_NEW_PRIVS\nforbids privilege/profile changes on exec โ€” the result is EPERM\n(\"operation not permitted\") and every scanner fails immediately.\n\nSet this to true ONLY on hosts hitting that incompatibility. Scanner\ncontainers still run with read-only rootfs, tmpfs /tmp, no-network by\ndefault, and read-only source mounts, so the marginal isolation loss\nis small. The preferred fix remains replacing snap docker with a\ndistro-packaged docker.","type":"boolean"},"scanner_fetch_package_source":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.FetchPackageSource\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.EffectiveFetchPackageSource. Cleared after migration.\n\nScannerFetchPackageSource controls whether the scanner fetches the\nPUBLISHED source of package-runner servers (npx/uvx) โ€” without executing\nit โ€” when no local source is available (no Docker container, no local\npackage cache, no working_dir). This is the primary quarantine/scan\ntarget: a quarantined-on-add server is never run locally, so without this\nthe scan degrades to tool-definitions-only (no real source-level\nanalysis). See MCP-2206.\n\nFetching uses ` + "`" + `npm pack --ignore-scripts` + "`" + ` (npm) and ` + "`" + `uv pip download` + "`" + ` /\n` + "`" + `pip download` + "`" + ` with ` + "`" + `--only-binary=:all:` + "`" + ` (Python), which only download +\nunpack archives and NEVER run install, build, or setup.py โ€” a scanner must\nnot execute the untrusted code it is scanning. The Python\n` + "`" + `--only-binary=:all:` + "`" + ` flag is required because downloading an sdist would\ninvoke its build backend (setup.py); packages with no wheel fall back to\ntool-definitions-only instead. Extraction is hardened against path\ntraversal and decompression bombs.\n\nDefault (nil) is ENABLED. Set to false on air-gapped deployments to\nforbid the scanner's network egress; such servers then fall back to the\ntool-definitions-only scan with no regression.","type":"boolean"},"scanner_registry_url":{"type":"string"},"tpa_bundle_path":{"description":"TPABundlePath is the filesystem path to the tpa-db scanner-bundle.json\nthe offline TPA scanner runs (spec 086 FR-019: the signature-DB location\nMUST be configuration-driven, not hardcoded). Empty (the default) runs the\ncorpus embedded in this build.\n\nEnv override: MCPPROXY_TPA_BUNDLE_PATH. Hot-reloadable โ€” the path is\nre-read on every config.reloaded event via\nscanner.Service.ApplySecurityConfig, so a corpus refresh needs no restart.\nA configured bundle that fails to read/parse/version-check/compile is\nREFUSED and the previously active corpus stays live (fail-closed, never\nfail-empty); the reason is logged and surfaced in the security overview's\nsignature_bundle.load_error.","type":"string"}},"type":"object"},"config.SensitiveDataDetectionConfig":{"description":"Sensitive data detection settings (Spec 026)","properties":{"categories":{"additionalProperties":{"type":"boolean"},"description":"Enable/disable specific detection categories","type":"object"},"custom_patterns":{"description":"User-defined detection patterns","items":{"$ref":"#/components/schemas/config.CustomPattern"},"type":"array","uniqueItems":false},"enabled":{"description":"Enable sensitive data detection (default: true)","type":"boolean"},"entropy_threshold":{"description":"Shannon entropy threshold for high-entropy detection (default: 4.5)","type":"number"},"max_payload_size_kb":{"description":"Max size to scan before truncating (default: 1024)","type":"integer"},"scan_requests":{"description":"Scan tool call arguments (default: true)","type":"boolean"},"scan_responses":{"description":"Scan tool responses (default: true)","type":"boolean"},"sensitive_keywords":{"description":"Keywords to flag","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ServerConfig":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve tool\nchanges/additions (disabling per-server rug-pull protection). Supersedes\nskip_quarantine. MCP-2930 only ACCEPTS, persists, and migrates this flag โ€” it\nis NOT yet consulted at runtime; auto-approval is still governed by\nSkipQuarantine until the trust-baseline behavior change (MCP-2931) migrates the\nruntime consumers onto it.\nTri-state pointer (mirrors QuarantineEnabled): nil = unset (inherit/migrate\nfrom legacy skip_quarantine), explicit true/false = honored as-is so an\nexplicit auto_approve_tool_changes:false overrides a legacy skip_quarantine:true.\nRead via IsAutoApproveToolChanges().","type":"boolean"},"command":{"type":"string"},"created":{"type":"string"},"disabled_tools":{"description":"Denylist: these tools are hidden; mutually exclusive with enabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"},"enabled_tools":{"description":"Allowlist: only these tools are exposed; mutually exclusive with disabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts overrides whether this server's advertised MCP prompts are\naggregated into mcpproxy's prompts/list. nil (default) inherits the\ndefault-aggregate behavior (included if the server advertises\nCapabilities.Prompts); false excludes it regardless of capability.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"description":"For HTTP servers","type":"object"},"health_check_interval":{"description":"Per-server discovery \u0026 health-check overrides (spec 074). Same *Duration\ntri-state as the global keys: nil = inherit the global value (or default),\npointer to 0s = disabled for this server, positive = that interval.\nHealthCheckInterval is fully wired into the per-server health loop;\nToolDiscoveryInterval is accepted/validated and round-trips for\nforward-compat, but the periodic index sweep is governed by the global\ncadence in this iteration (see spec 074 plan ยงC).","type":"string"},"init_timeout":{"description":"InitTimeout overrides the global init_timeout for this server's MCP\n` + "`" + `initialize` + "`" + ` handshake deadline (MCP-3322 / GH #760). *Duration tri-state:\nnil = inherit the global value (or 30s default), positive = that deadline.\nResolved by Config.ResolveInitTimeout; validated to {0} โˆช [1s, 30m]. Raise\nthis for upstreams that do legitimate first-run warmup (e.g. caching many\nchannels/users) before responding to ` + "`" + `initialize` + "`" + `.","type":"string"},"isolation":{"$ref":"#/components/schemas/config.IsolationConfig"},"launcher_wait_timeout":{"description":"LauncherWaitTimeout caps how long mcpproxy will wait for a locally-launched\nHTTP/SSE upstream's URL to become reachable after Spawn(). Only consulted\nwhen the server is configured with both Command and an HTTP/SSE URL โ€” i.e.,\nmcpproxy starts the process AND connects via network. Stdio servers ignore\nthis field. Zero or unset โ†’ 30s default.","type":"string"},"max_concurrent_requests":{"description":"Per-server concurrency overrides โ€” scope (c) of FR-020 (spec 093, #955).\nTri-state per setting, exactly like HealthCheckInterval: absent = inherit\nthe per-server default set (server_concurrency_defaults), explicit 0 =\ndisable that setting for this server (0 max = no per-server limiter at\nall; 0 queue_size = no pending capacity, shed immediately at the cap),\npositive = override. The global aggregate limiter is never inherited from\nhere โ€” it applies on top, so effective concurrency is min(per-server,\nglobal). Resolved by Config.ResolveServerConcurrency.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/config.OAuthConfig"},"protocol":{"description":"stdio, http, sse, streamable-http, auto","type":"string"},"quarantined":{"description":"Security quarantine status","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets a disconnected server","type":"boolean"},"shared":{"description":"Server edition: shared with all users","type":"boolean"},"skip_quarantine":{"description":"SkipQuarantine is DEPRECATED (MCP-2930): use AutoApproveToolChanges instead.\nKept for back-compat parsing; on config load a legacy skip_quarantine:true is\nmigrated to auto_approve_tool_changes:true only when the new field is unset\n(see normalizeServerQuarantineFlags).","type":"boolean"},"source_registry_id":{"description":"SourceRegistryID records which registry this server was added from (empty\nfor manually-configured servers). MCP-866: surfaced in the approval /\nquarantine view so a reviewer can see a server's origin.","type":"string"},"source_registry_provenance":{"description":"SourceRegistryProvenance records the source registry's provenance at add\ntime (RegistryProvenanceOfficial / RegistryProvenanceCustom). It is purely\ninformational (MCP-1072) โ€” surfaced so a reviewer can see a server's origin\nโ€” and no longer gates quarantine or skip_quarantine.","type":"string"},"tool_discovery_interval":{"type":"string"},"toon_output":{"description":"ToonOutput overrides the global toon_output mode for this server's\ntools (spec 084, FR-001). Plain string, not a pointer: \"\"/absent =\ninherit the global value; \"off\"|\"adaptive\"|\"always\" = override (\"off\"\nis the explicit force-off). Resolved by Config.ResolveToonOutput.","type":"string"},"trust_mode":{"description":"TrustMode is the per-server trust tier: auto|scan|manual. Supersedes\nauto_approve_tool_changes (spec 086). An empty value is derived from the\nlegacy fields at load via normalizeServerQuarantineFlags; the single\nresolution point is EffectiveTrustMode(), which treats an empty or\nunrecognized value as manual (secure by default). Read via\nEffectiveTrustMode(), never the raw string.","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"working_dir":{"description":"Working directory for stdio servers","type":"string"}},"type":"object"},"config.TLSConfig":{"description":"TLS configuration","properties":{"certs_dir":{"description":"Directory for certificates","type":"string"},"enabled":{"description":"Enable HTTPS","type":"boolean"},"hsts":{"description":"Enable HTTP Strict Transport Security","type":"boolean"},"require_client_cert":{"description":"Enable mTLS","type":"boolean"}},"type":"object"},"config.TelemetryConfig":{"description":"Telemetry settings (Spec 036)","properties":{"anonymous_id":{"description":"Auto-generated UUIDv4","type":"string"},"anonymous_id_created_at":{"description":"Spec 042 (Tier 2) additions โ€” all default-zero, all backwards-compatible.","type":"string"},"enabled":{"description":"Default: true (opt-out)","type":"boolean"},"endpoint":{"description":"Override for testing","type":"string"},"last_reported_version":{"description":"Upgrade funnel","type":"string"},"last_startup_outcome":{"description":"success|port_conflict|db_locked|...","type":"string"},"notice_shown":{"description":"First-run notice flag","type":"boolean"}},"type":"object"},"config.TokenizerConfig":{"description":"Tokenizer configuration for token counting","properties":{"default_model":{"description":"Default model for tokenization (e.g., \"gpt-4\")","type":"string"},"enabled":{"description":"Enable token counting","type":"boolean"},"encoding":{"description":"Default encoding (e.g., \"cl100k_base\")","type":"string"}},"type":"object"},"config.TracingExporterConfig":{"description":"Tracing gates the OpenTelemetry OTLP trace exporter (MCP-32). Disabled by\ndefault.","properties":{"enabled":{"description":"Enabled turns on OTLP trace export for tool calls and upstream hops.","type":"boolean"},"endpoint":{"description":"Endpoint is the collector address as host:port (no scheme), e.g.\n\"localhost:4318\" for http or \"localhost:4317\" for grpc.","type":"string"},"protocol":{"description":"Protocol selects the OTLP transport: \"http\" or \"grpc\".","type":"string"},"sample_rate":{"description":"SampleRate is the head-based trace sampling ratio in [0,1]. Default 0.1.","type":"number"}},"type":"object"},"config.UpdateCheckConfig":{"description":"Update-check settings (Spec 079 FR-012): config-file control of the\nbackground upgrade-awareness checker (internal/updatecheck). nil =\nenabled on the stable channel (existing default behavior). The existing\nenvironment switches keep working and WIN over these keys (FR-014):\nMCPPROXY_DISABLE_AUTO_UPDATE=true force-disables even when\nenabled=true, and MCPPROXY_ALLOW_PRERELEASE_UPDATES=true force-selects\nthe rc channel even when channel=stable.","properties":{"channel":{"description":"Channel selects which releases are offered as updates: \"stable\"\n(default; prereleases never offered) or \"rc\" (prereleases included).\nEmpty resolves to stable. Validated in ValidateDetailed.\n\nNOTE: for a RELEASED build the running binary's own version is\nauthoritative and overrides this field โ€” a stable build is never\noffered an RC (even with channel=rc), and an RC build always tracks the\nrc channel. This field only takes effect on dev/unstamped builds. See\ninternal/updatecheck.Checker.IncludePrereleases.","type":"string"},"enabled":{"description":"Enabled gates all update checking. Tri-state: nil/absent = enabled\n(default true, matching pre-079 behavior). When false, no network\ncheck is performed and no upgrade nudge appears on any surface\n(FR-015) โ€” /api/v1/info omits the update object entirely.","type":"boolean"}},"type":"object"},"configimport.FailedServer":{"properties":{"details":{"type":"string"},"error":{"type":"string"},"name":{"type":"string"}},"type":"object"},"configimport.ImportSummary":{"properties":{"failed":{"type":"integer"},"imported":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"configimport.SkippedServer":{"properties":{"name":{"type":"string"},"reason":{"description":"\"already_exists\", \"filtered_out\", \"invalid_name\"","type":"string"}},"type":"object"},"connect.ConnectResult":{"description":"The full result; its action mirrors the top-level one","properties":{"action":{"description":"\"created\", \"updated\", \"already_exists\", \"removed\", \"not_found\"","type":"string"},"backup_path":{"type":"string"},"client":{"type":"string"},"config_path":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.APIResponse":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ActivityDetailResponse":{"properties":{"activity":{"$ref":"#/components/schemas/contracts.ActivityRecord"}},"type":"object"},"contracts.ActivityListResponse":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/contracts.ActivityRecord"},"type":"array","uniqueItems":false},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.ActivityRecord":{"properties":{"arguments":{"description":"Tool call arguments","type":"object"},"detection_types":{"description":"List of detection types found","items":{"type":"string"},"type":"array","uniqueItems":false},"duration_ms":{"description":"Execution duration in milliseconds","type":"integer"},"error_message":{"description":"Error details if status is \"error\"","type":"string"},"has_sensitive_data":{"description":"Sensitive data detection fields (Spec 026)","type":"boolean"},"id":{"description":"Unique identifier (ULID format)","type":"string"},"max_severity":{"description":"Highest severity level detected (critical, high, medium, low)","type":"string"},"metadata":{"description":"Additional context-specific data","type":"object"},"parent_id":{"description":"Correlation id of the parent call (the code_execution whose sandbox issued this sub-call)","type":"string"},"request_id":{"description":"HTTP request ID for correlation","type":"string"},"response":{"description":"Tool response (potentially truncated)","type":"string"},"response_truncated":{"description":"True if response was truncated","type":"boolean"},"server_name":{"description":"Name of upstream MCP server","type":"string"},"session_id":{"description":"MCP transport session ID (regenerated on every reconnect)","type":"string"},"source":{"$ref":"#/components/schemas/contracts.ActivitySource"},"status":{"description":"Result status: \"success\", \"error\", \"blocked\", \"rejected\"","type":"string"},"timestamp":{"description":"When activity occurred","type":"string"},"tool_name":{"description":"Name of tool called","type":"string"},"type":{"$ref":"#/components/schemas/contracts.ActivityType"},"work_session_id":{"description":"Spec 082: one client, one project, across reconnects","type":"string"}},"type":"object"},"contracts.ActivitySource":{"description":"How activity was triggered: \"mcp\", \"cli\", \"api\"","type":"string","x-enum-varnames":["ActivitySourceMCP","ActivitySourceCLI","ActivitySourceAPI"]},"contracts.ActivitySummaryResponse":{"properties":{"blocked_count":{"description":"Count of blocked activities","type":"integer"},"call_count":{"description":"CallCount is how many of those records are CALLS THE USER MADE, as\ndefined once in storage.CountsAsCall and shared with the usage aggregate\nbehind the Usage tab (audit finding F1, #1046). TotalCount answers \"how\nmany rows does the Activity Log have\"; CallCount answers \"how many calls\nwere there\". They are different questions โ€” quarantine auto-approvals,\nsystem start, security scans and management chatter are events, not calls\nโ€” and printing either one under the other's label is how the same instance\ncame to report 51 calls on one screen and 19 on another.","type":"integer"},"call_error_count":{"description":"CallErrorCount is the failures within CallCount, so an error RATE computed\nfrom this response has one denominator. It is not ErrorCount: a policy\nblock is a failed call but carries status \"blocked\", and a shed call is an\nerror in neither sense because it never ran.","type":"integer"},"end_time":{"description":"End of the period (RFC3339)","type":"string"},"error_count":{"description":"Count of error activities","type":"integer"},"other_count":{"description":"OtherCount is every record whose status is outside the four-value\nvocabulary above, so that\n\n\tsuccess + error + blocked + rejected + other == total\n\nholds by construction. The status field is a CLOSED vocabulary for tool\ncalls, but the activity log is wider than tool calls: a quarantine change\nstores its ACTION there (\"approved\", \"auto_approved\"), a policy decision\nstores its DECISION (\"allow\"). Those rows were counted in the total and in\nnone of the four buckets, so the Activity Log's own status tiles summed to\nless than the denominator printed beside them โ€” 15+4+0+0 under a \"42\"\n(audit finding F2, #1046). The residual now has a name and a tile.","type":"integer"},"period":{"description":"Time period (1h, 24h, 7d, 30d)","type":"string"},"rejected_count":{"description":"RejectedCount is the number of calls shed by a concurrency limiter before\nthey reached an upstream (spec 093). Counted separately from errors: it is\nproxy backpressure, not an upstream fault, and it is the signal an\noperator right-sizes max_concurrent_requests against.","type":"integer"},"start_time":{"description":"Start of the period (RFC3339)","type":"string"},"success_count":{"description":"Count of successful activities","type":"integer"},"top_servers":{"description":"Top servers by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopServer"},"type":"array","uniqueItems":false},"top_tools":{"description":"Top tools by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopTool"},"type":"array","uniqueItems":false},"total_count":{"description":"Total activity count","type":"integer"}},"type":"object"},"contracts.ActivityTopServer":{"properties":{"count":{"description":"Activity count","type":"integer"},"name":{"description":"Server name","type":"string"}},"type":"object"},"contracts.ActivityTopTool":{"properties":{"count":{"description":"Activity count","type":"integer"},"server":{"description":"Server name","type":"string"},"tool":{"description":"Tool name","type":"string"}},"type":"object"},"contracts.ActivityType":{"description":"Type of activity","type":"string","x-enum-varnames":["ActivityTypeToolCall","ActivityTypePolicyDecision","ActivityTypeQuarantineChange","ActivityTypeServerChange"]},"contracts.AddFromRegistryRequest":{"properties":{"enabled":{"description":"defaults to true when nil","type":"boolean"},"env":{"additionalProperties":{"type":"string"},"description":"overrides + required-input values","type":"object"},"name":{"description":"optional name override","type":"string"}},"type":"object"},"contracts.AddRegistrySourceRequest":{"properties":{"id":{"description":"derived from the host when empty","type":"string"},"name":{"description":"defaults to the id","type":"string"},"protocol":{"description":"defaults to modelcontextprotocol/registry","type":"string"},"url":{"description":"required https registry URL","type":"string"}},"type":"object"},"contracts.ConfigApplyResult":{"properties":{"applied_immediately":{"type":"boolean"},"changed_fields":{"items":{"type":"string"},"type":"array","uniqueItems":false},"requires_restart":{"type":"boolean"},"restart_reason":{"type":"string"},"success":{"type":"boolean"},"validation_errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DCRStatus":{"properties":{"attempted":{"type":"boolean"},"error":{"type":"string"},"status_code":{"type":"integer"},"success":{"type":"boolean"}},"type":"object"},"contracts.DeepScanDescriptor":{"description":"DeepScan reports the opt-in \"deep scan\" layer status (Spec 077 US3),\nSEPARATELY from the baseline verdict above. Always emitted on a computed\nsummary โ€” when deep scan is off (the default) it reports enabled=false\nplus any enabled-but-skipped Docker scanners. It never influences Status.","properties":{"available":{"type":"boolean"},"enabled":{"type":"boolean"},"ran":{"type":"boolean"},"scanners_failed":{"items":{"$ref":"#/components/schemas/contracts.DeepScanScannerFailure"},"type":"array","uniqueItems":false},"skipped_scanners":{"description":"SkippedScanners lists Docker scanners the user enabled that are skipped\nbecause security.deep_scan.enabled is false (informational).","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DeepScanScannerFailure":{"properties":{"id":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"contracts.DeprecatedConfigWarning":{"properties":{"field":{"type":"string"},"message":{"type":"string"},"replacement":{"type":"string"}},"type":"object"},"contracts.Diagnostic":{"description":"Spec 044 โ€” structured diagnostic error and stable error code. Both\nare populated when the server is in a failed state and the error\nhas been classified by internal/diagnostics. Healthy servers omit\nthese fields.","properties":{"cause":{"type":"string"},"code":{"type":"string"},"detected_at":{"type":"string"},"docs_url":{"type":"string"},"fix_steps":{"items":{"$ref":"#/components/schemas/contracts.DiagnosticFixStep"},"type":"array","uniqueItems":false},"severity":{"type":"string"},"user_message":{"type":"string"}},"type":"object"},"contracts.DiagnosticFixStep":{"properties":{"command":{"type":"string"},"destructive":{"type":"boolean"},"fixer_key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"}},"type":"object"},"contracts.Diagnostics":{"properties":{"deprecated_configs":{"description":"Deprecated config fields found","items":{"$ref":"#/components/schemas/contracts.DeprecatedConfigWarning"},"type":"array","uniqueItems":false},"docker_status":{"$ref":"#/components/schemas/contracts.DockerStatus"},"missing_secrets":{"description":"Renamed to avoid conflict","items":{"$ref":"#/components/schemas/contracts.MissingSecretInfo"},"type":"array","uniqueItems":false},"oauth_issues":{"description":"OAuth parameter mismatches","items":{"$ref":"#/components/schemas/contracts.OAuthIssue"},"type":"array","uniqueItems":false},"oauth_required":{"items":{"$ref":"#/components/schemas/contracts.OAuthRequirement"},"type":"array","uniqueItems":false},"runtime_warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false},"timestamp":{"type":"string"},"total_issues":{"type":"integer"},"upstream_errors":{"items":{"$ref":"#/components/schemas/contracts.UpstreamError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DockerStatus":{"properties":{"available":{"type":"boolean"},"error":{"type":"string"},"version":{"type":"string"}},"type":"object"},"contracts.EditRegistrySourceRequest":{"properties":{"name":{"description":"new display name","type":"string"},"servers_url":{"description":"explicit servers-collection URL","type":"string"},"url":{"description":"new base/servers https URL","type":"string"}},"type":"object"},"contracts.ErrorResponse":{"properties":{"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.FindingCounts":{"properties":{"dangerous":{"description":"Tool poisoning, active prompt injection","type":"integer"},"info":{"description":"Low-severity CVEs, informational","type":"integer"},"total":{"type":"integer"},"warning":{"description":"Rug pull, supply chain CVEs with exploits","type":"integer"}},"type":"object"},"contracts.GetConfigResponse":{"properties":{"config":{"description":"The configuration object","type":"object"},"config_path":{"description":"Path to config file","type":"string"}},"type":"object"},"contracts.GetRegistriesResponse":{"properties":{"registries":{"items":{"$ref":"#/components/schemas/contracts.Registry"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerLogsResponse":{"properties":{"count":{"type":"integer"},"logs":{"items":{"$ref":"#/components/schemas/contracts.LogEntry"},"type":"array","uniqueItems":false},"server_name":{"type":"string"}},"type":"object"},"contracts.GetServerToolCallsResponse":{"properties":{"server_name":{"type":"string"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerToolsResponse":{"properties":{"count":{"type":"integer"},"server_name":{"type":"string"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GetServersResponse":{"properties":{"servers":{"items":{"$ref":"#/components/schemas/contracts.Server"},"type":"array","uniqueItems":false},"stats":{"$ref":"#/components/schemas/contracts.ServerStats"}},"type":"object"},"contracts.GetSessionDetailResponse":{"properties":{"session":{"$ref":"#/components/schemas/contracts.MCPSession"}},"type":"object"},"contracts.GetSessionsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"sessions":{"items":{"$ref":"#/components/schemas/contracts.MCPSession"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetToolCallDetailResponse":{"properties":{"tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"}},"type":"object"},"contracts.GetToolCallsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GlobalToolsResponse":{"properties":{"failed_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"partial":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/contracts.GlobalToolsStats"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GlobalToolsStats":{"properties":{"disabled":{"type":"integer"},"enabled":{"type":"integer"},"pending_approval":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.HealthStatus":{"description":"Unified health status calculated by the backend","properties":{"action":{"description":"Action is the suggested fix action: \"login\", \"restart\", \"enable\", \"approve\", \"view_logs\", \"set_secret\", \"configure\", \"edit_url\", or \"\" (none)","type":"string"},"admin_state":{"description":"AdminState indicates the admin state: \"enabled\", \"disabled\", or \"quarantined\"","type":"string"},"detail":{"description":"Detail is an optional longer explanation of the status","type":"string"},"level":{"description":"Level indicates the health level: \"healthy\", \"degraded\", or \"unhealthy\"","type":"string"},"summary":{"description":"Summary is a human-readable status message (e.g., \"Connected (5 tools)\")","type":"string"}},"type":"object"},"contracts.InfoEndpoints":{"description":"Available API endpoints","properties":{"http":{"description":"HTTP endpoint address (e.g., \"127.0.0.1:8080\")","type":"string"},"socket":{"description":"Unix socket path (empty if disabled)","type":"string"}},"type":"object"},"contracts.InfoResponse":{"properties":{"endpoints":{"$ref":"#/components/schemas/contracts.InfoEndpoints"},"launched_by":{"description":"LaunchedBy is the durable launch provenance of the running core (Spec\n092 FR-001a): \"tray\" when a tray spawned it, \"installer\" when the macOS\nPKG postinstall did, \"\" when user-launched or unknown. Always present\n(possibly empty) so a tray can distinguish \"old core, not mine\" from\n\"old core I may supersede\".","type":"string"},"listen_addr":{"description":"Listen address (e.g., \"127.0.0.1:8080\")","type":"string"},"pid":{"description":"PID is the operating-system process id of the running core (Spec 092\nFR-002). A tray that merely ATTACHED to a core holds no Process handle\nfor it, so without this there is no mechanism at all to stop a stale\ncore โ€” the consent action would have nothing to act on and could only\nprint instructions. Paired with LaunchedBy it is what lets a newer tray\nsupersede a core an older tray started.","type":"integer"},"update":{"$ref":"#/components/schemas/contracts.UpdateInfo"},"update_policy":{"$ref":"#/components/schemas/contracts.UpdatePolicy"},"version":{"description":"Current MCPProxy version","type":"string"},"web_ui_url":{"description":"URL to access the web control panel","type":"string"}},"type":"object"},"contracts.IsolationConfig":{"properties":{"cpu_limit":{"type":"string"},"enabled":{"type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"memory_limit":{"type":"string"},"network_mode":{"type":"string"},"timeout":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationDefaults":{"description":"IsolationDefaults exposes the resolved baseline values that\nwould apply when no per-server override is set. Populated on\nlist/get responses; never consumed on PATCH requests.","properties":{"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"network_mode":{"type":"string"},"runtime_type":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.LogEntry":{"properties":{"fields":{"type":"object"},"level":{"type":"string"},"message":{"type":"string"},"server":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.MCPSession":{"properties":{"client_name":{"type":"string"},"client_version":{"type":"string"},"end_time":{"type":"string"},"experimental":{"items":{"type":"string"},"type":"array","uniqueItems":false},"has_roots":{"description":"MCP Client Capabilities","type":"boolean"},"has_sampling":{"type":"boolean"},"id":{"type":"string"},"last_activity":{"type":"string"},"start_time":{"type":"string"},"status":{"type":"string"},"tool_call_count":{"type":"integer"},"total_tokens":{"type":"integer"},"work_session_id":{"type":"string"},"workspace_name":{"description":"Workspace / work session (Spec 082). WorkspaceName is the project's\nbasename โ€” the full local path is never exposed. WorkSessionID groups the\nreconnects that make up one stretch of user work.","type":"string"}},"type":"object"},"contracts.MetadataStatus":{"properties":{"authorization_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"error":{"type":"string"},"found":{"type":"boolean"},"url_checked":{"type":"string"}},"type":"object"},"contracts.MissingSecretInfo":{"properties":{"secret_name":{"type":"string"},"used_by":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.NPMPackageInfo":{"properties":{"exists":{"type":"boolean"},"install_cmd":{"type":"string"}},"type":"object"},"contracts.OAuthConfig":{"properties":{"auth_url":{"type":"string"},"client_id":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_port":{"type":"integer"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false},"token_expires_at":{"description":"When the OAuth token expires","type":"string"},"token_url":{"type":"string"},"token_valid":{"description":"Whether token is currently valid","type":"boolean"}},"type":"object"},"contracts.OAuthErrorDetails":{"description":"Structured discovery/failure details","properties":{"authorization_server_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"dcr_status":{"$ref":"#/components/schemas/contracts.DCRStatus"},"protected_resource_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"server_url":{"type":"string"}},"type":"object"},"contracts.OAuthFlowError":{"properties":{"correlation_id":{"description":"Flow tracking ID for log correlation","type":"string"},"debug_hint":{"description":"CLI command for log lookup","type":"string"},"details":{"$ref":"#/components/schemas/contracts.OAuthErrorDetails"},"error_code":{"description":"Machine-readable error code (e.g., OAUTH_NO_METADATA)","type":"string"},"error_type":{"description":"Category of OAuth runtime failure","type":"string"},"message":{"description":"Human-readable error description","type":"string"},"request_id":{"description":"HTTP request ID (from PR #237)","type":"string"},"server_name":{"description":"Server that failed OAuth","type":"string"},"success":{"description":"Always false","type":"boolean"},"suggestion":{"description":"Actionable remediation hint","type":"string"}},"type":"object"},"contracts.OAuthIssue":{"properties":{"documentation_url":{"type":"string"},"error":{"type":"string"},"issue":{"type":"string"},"missing_params":{"items":{"type":"string"},"type":"array","uniqueItems":false},"resolution":{"type":"string"},"server_name":{"type":"string"}},"type":"object"},"contracts.OAuthRequirement":{"properties":{"expires_at":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"state":{"type":"string"}},"type":"object"},"contracts.OAuthStartResponse":{"properties":{"auth_url":{"description":"Authorization URL (always included for manual use)","type":"string"},"browser_error":{"description":"Error message if browser launch failed","type":"string"},"browser_opened":{"description":"Whether browser launch succeeded","type":"boolean"},"correlation_id":{"description":"UUID for tracking this flow","type":"string"},"message":{"description":"Human-readable status message","type":"string"},"server_name":{"description":"Name of the server being authenticated","type":"string"},"success":{"description":"Always true for successful start","type":"boolean"}},"type":"object"},"contracts.PreflightPolicy":{"properties":{"exclude_destructive":{"type":"boolean"},"exclude_open_world":{"type":"boolean"},"read_only_only":{"type":"boolean"}},"type":"object"},"contracts.PreflightReason":{"type":"string","x-enum-varnames":["PreflightReasonServerInitializing","PreflightReasonServerUnhealthy","PreflightReasonServerDisabled","PreflightReasonServerQuarantined","PreflightReasonToolPendingApproval","PreflightReasonToolChanged","PreflightReasonToolBlockedByUser","PreflightReasonOAuthRequired","PreflightReasonHashMismatch","PreflightReasonServerNotInScope","PreflightReasonToolDeniedByConfig","PreflightReasonMissingAnnotation","PreflightReasonPolicyFiltered","PreflightReasonNotFound","PreflightReasonServerNotConfigured"]},"contracts.PreflightRequest":{"properties":{"policy":{"$ref":"#/components/schemas/contracts.PreflightPolicy"},"profile":{"description":"Profile evaluates under a named profile's server scope. Unknown: 400.","type":"string"},"tools":{"description":"Tools is 1..100 entries BEFORE dedup; duplicates are collapsed, and\nduplicate ids carrying different pins are a validation error.","items":{"$ref":"#/components/schemas/contracts.PreflightToolRef"},"type":"array","uniqueItems":false},"wait_ms":{"description":"WaitMS polls local state for up to this many milliseconds (cap 10000)\nwhile every failure is retryable-class.","type":"integer"}},"type":"object"},"contracts.PreflightResponse":{"properties":{"checked_at":{"type":"string"},"tools":{"description":"Tools are ordered by first occurrence of each unique id in the request.","items":{"$ref":"#/components/schemas/contracts.PreflightToolResult"},"type":"array","uniqueItems":false},"verdict":{"$ref":"#/components/schemas/contracts.PreflightVerdict"},"waited_ms":{"description":"WaitedMS is present when wait_ms was requested (0 when the wait\nsemaphore was exhausted and the request resolved immediately).","type":"integer"}},"type":"object"},"contracts.PreflightStatus":{"type":"string","x-enum-varnames":["PreflightStatusReady","PreflightStatusUnavailable"]},"contracts.PreflightToolRef":{"properties":{"id":{"description":"ID is a canonical \"\u003cserver\u003e:\u003ctool\u003e\" id. A malformed id is answered with a\nper-ID not_found carrying a format hint, never a request-level error.","type":"string"},"pin_hash":{"description":"PinHash is \"sha256/v{N}:{hex}\" โ€” the schema version is embedded so a\nproxy-side hash-algorithm bump is distinguishable from upstream drift.","type":"string"}},"type":"object"},"contracts.PreflightToolResult":{"properties":{"action":{"type":"string"},"detail":{"type":"string"},"did_you_mean":{"description":"DidYouMean carries up to 3 nearest caller-visible ids on not_found. It\nnever crosses a scope boundary and never names a quarantined server's\ntools.","items":{"type":"string"},"type":"array","uniqueItems":false},"hash":{"description":"Hash is the tool's current pin (\"sha256/v{N}:{hex}\") โ€” operator tier,\nready results only. Never disclosed to an agent token.","type":"string"},"id":{"type":"string"},"reason":{"$ref":"#/components/schemas/contracts.PreflightReason"},"remediation":{"type":"string"},"retryable":{"type":"boolean"},"status":{"$ref":"#/components/schemas/contracts.PreflightStatus"}},"type":"object"},"contracts.PreflightVerdict":{"type":"string","x-enum-varnames":["PreflightVerdictReady","PreflightVerdictDegradedRetryable","PreflightVerdictBlocked","PreflightVerdictUnknownIDs"]},"contracts.QuarantineStats":{"description":"Tool quarantine metrics for this server","properties":{"blocked_count":{"description":"Number of disabled (blocked) tools","type":"integer"},"changed_count":{"description":"Number of tools whose description/schema changed since approval","type":"integer"},"pending_count":{"description":"Number of newly discovered tools awaiting approval","type":"integer"}},"type":"object"},"contracts.RefreshRegistryResponse":{"properties":{"cleared":{"description":"number of cached entries dropped","type":"integer"},"registry_id":{"type":"string"}},"type":"object"},"contracts.Registry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag (MCP-866): \"official/trusted\" for built-in\ndefaults, \"custom/unverified\" for user-added registries.","type":"string"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"trusted":{"description":"Trusted indicates whether this is an official, shipped-by-default\nregistry. Trust is derived from membership in the default set, never\nfrom self-assertion in config.","type":"boolean"},"url":{"type":"string"}},"type":"object"},"contracts.RegistryCacheInfo":{"properties":{"age_seconds":{"type":"number"},"stale":{"type":"boolean"}},"type":"object"},"contracts.RegistryUnavailable":{"properties":{"reason":{"type":"string"}},"type":"object"},"contracts.ReplayToolCallRequest":{"properties":{"arguments":{"description":"Modified arguments for replay","type":"object"}},"type":"object"},"contracts.ReplayToolCallResponse":{"properties":{"error":{"description":"Error if replay failed","type":"string"},"new_call_id":{"description":"ID of the newly created call","type":"string"},"new_tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"replayed_from":{"description":"Original call ID","type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.RepositoryInfo":{"description":"Detected package info","properties":{"npm":{"$ref":"#/components/schemas/contracts.NPMPackageInfo"}},"type":"object"},"contracts.RepositoryServer":{"properties":{"connect_url":{"description":"Alternative connection URL","type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"install_cmd":{"description":"Installation command","type":"string"},"name":{"type":"string"},"registry":{"description":"Which registry this came from","type":"string"},"repository_info":{"$ref":"#/components/schemas/contracts.RepositoryInfo"},"source_code_url":{"description":"Source repository URL","type":"string"},"updated_at":{"type":"string"},"url":{"description":"MCP endpoint for remote servers only","type":"string"}},"type":"object"},"contracts.SearchRegistryServersResponse":{"properties":{"cache":{"$ref":"#/components/schemas/contracts.RegistryCacheInfo"},"query":{"type":"string"},"registry_id":{"type":"string"},"servers":{"items":{"$ref":"#/components/schemas/contracts.RepositoryServer"},"type":"array","uniqueItems":false},"tag":{"type":"string"},"total":{"type":"integer"},"unavailable":{"$ref":"#/components/schemas/contracts.RegistryUnavailable"}},"type":"object"},"contracts.SearchResult":{"properties":{"matches":{"type":"integer"},"score":{"type":"number"},"snippet":{"type":"string"},"tool":{"$ref":"#/components/schemas/contracts.Tool"}},"type":"object"},"contracts.SearchToolsResponse":{"properties":{"query":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/contracts.SearchResult"},"type":"array","uniqueItems":false},"took":{"type":"string"},"total":{"type":"integer"}},"type":"object"},"contracts.SecurityScanSummary":{"description":"Latest security scan results summary","properties":{"deep_scan":{"$ref":"#/components/schemas/contracts.DeepScanDescriptor"},"finding_counts":{"$ref":"#/components/schemas/contracts.FindingCounts"},"last_scan_at":{"type":"string"},"risk_score":{"description":"0-100","type":"integer"},"scanners_failed":{"type":"integer"},"scanners_run":{"description":"Scanner coverage for the primary (baseline) scan pass โ€” informational only.\nSpec 077 US3 (FR-008/FR-014): Status is derived SOLELY from the\ndeterministic baseline findings; a failed Docker deep scanner no longer\ndowngrades a clean verdict. That failure is surfaced via DeepScan instead.","type":"integer"},"scanners_total":{"type":"integer"},"status":{"description":"\"clean\", \"warnings\", \"dangerous\", \"failed\", \"not_scanned\", \"scanning\"","type":"string"}},"type":"object"},"contracts.Server":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"authenticated":{"description":"OAuth authentication status","type":"boolean"},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges mirrors config.ServerConfig.AutoApproveToolChanges\n(MCP-2930): the per-server intent to auto-approve new/changed tools past\nthe trust baseline. Tri-state *bool โ€” nil means \"never set\" (omitted from\nthe payload), so the Web UI toggle (MCP-2932) can distinguish unset from\nan explicit false. Read-only on the GET path; PATCH/POST accept it via\nAddServerRequest.","type":"boolean"},"command":{"type":"string"},"connected":{"type":"boolean"},"connected_at":{"type":"string"},"connecting":{"type":"boolean"},"created":{"type":"string"},"diagnostic":{"$ref":"#/components/schemas/contracts.Diagnostic"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"error_code":{"type":"string"},"expose_prompts":{"description":"ExposePrompts mirrors config.ServerConfig.ExposePrompts (F9): the per-server\nprompt-aggregation override. Tri-state *bool โ€” nil/omitted means \"inherit\ndefault aggregation\". Surfaced on GET so a caller that PATCHed the override\ncan read it back; PATCH/POST accept it via AddServerRequest.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"health":{"$ref":"#/components/schemas/contracts.HealthStatus"},"id":{"type":"string"},"init_timeout":{"description":"InitTimeout mirrors config.ServerConfig.InitTimeout (MCP-3322 / GH #760):\nthe per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override. Serialized as\na duration string (e.g. \"120s\"); nil/omitted means \"inherit the global\ndefault\". Surfaced on the GET path so clients can read back a configured\noverride; PATCH/POST accept it via AddServerRequest.","type":"string"},"isolation":{"$ref":"#/components/schemas/contracts.IsolationConfig"},"isolation_defaults":{"$ref":"#/components/schemas/contracts.IsolationDefaults"},"last_error":{"type":"string"},"last_reconnect_at":{"type":"string"},"last_retry_time":{"type":"string"},"max_concurrent_requests":{"description":"Spec 093 (GH #955) โ€” per-server concurrency overrides, scope (c) of\nFR-020. Each setting is tri-state: nil (omitted) means \"inherit\nserver_concurrency_defaults\", 0 disables that setting for this server,\npositive overrides it. Surfaced on the GET path so a caller can read back\nwhat it set; PATCH/POST accept them via AddServerRequest. The effective\nconcurrency for a server is additionally bounded by the global aggregate\nlimiter, which is NOT an inheritance source for these fields.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/contracts.OAuthConfig"},"oauth_status":{"description":"OAuth status: \"authenticated\", \"expired\", \"error\", \"none\"","type":"string"},"protocol":{"type":"string"},"quarantine":{"$ref":"#/components/schemas/contracts.QuarantineStats"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_count":{"type":"integer"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets this disconnected server","type":"boolean"},"retry_count":{"type":"integer"},"security_scan":{"$ref":"#/components/schemas/contracts.SecurityScanSummary"},"should_retry":{"type":"boolean"},"source_registry_id":{"description":"MCP-901 โ€” registry provenance of an upstream that was added from a\nregistry. SourceRegistryID names the source registry (empty for\nmanually-configured servers); SourceRegistryProvenance is the trust tag\nrecorded at add time (\"official/trusted\" or \"custom/unverified\"). Both\nare projected from config.ServerConfig so the approval/quarantine view\ncan render an \"added from \u003cregistry\u003e ยท unverified\" origin badge. Optional\nand omitted when empty โ€” clients that pre-date this treat them as absent.","type":"string"},"source_registry_provenance":{"type":"string"},"status":{"type":"string"},"token_expires_at":{"description":"When the OAuth token expires (ISO 8601)","type":"string"},"tool_count":{"type":"integer"},"tool_list_token_size":{"description":"Token size for this server's tools","type":"integer"},"trust_mode":{"description":"TrustMode mirrors config.ServerConfig.TrustMode (spec 086): the per-server\ntrust tier (\"auto\"/\"scan\"/\"manual\"). Surfaced on the GET path so clients can\nread back the persisted mode; PATCH/POST accept it via AddServerRequest.\nOmitted when empty (server predates the field / relies on legacy flags).","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"user_logged_out":{"description":"True if user explicitly logged out (prevents auto-reconnection)","type":"boolean"},"working_dir":{"type":"string"}},"type":"object"},"contracts.ServerActionResponse":{"properties":{"action":{"type":"string"},"async":{"type":"boolean"},"server":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ServerStats":{"properties":{"connected_servers":{"type":"integer"},"docker_containers":{"type":"integer"},"quarantined_servers":{"type":"integer"},"token_metrics":{"$ref":"#/components/schemas/contracts.ServerTokenMetrics"},"total_servers":{"type":"integer"},"total_tools":{"type":"integer"}},"type":"object"},"contracts.ServerTokenMetrics":{"properties":{"average_query_result_size":{"description":"Typical retrieve_tools output (tokens)","type":"integer"},"per_server_tool_list_sizes":{"additionalProperties":{"type":"integer"},"description":"Token size per server","type":"object"},"saved_tokens":{"description":"Difference","type":"integer"},"saved_tokens_percentage":{"description":"Percentage saved","type":"number"},"total_server_tool_list_size":{"description":"All upstream tools combined (tokens)","type":"integer"}},"type":"object"},"contracts.SuccessResponse":{"properties":{"data":{"type":"object"},"success":{"type":"boolean"}},"type":"object"},"contracts.TokenMetrics":{"description":"Token usage metrics (nil for older records)","properties":{"encoding":{"description":"Encoding used (e.g., cl100k_base)","type":"string"},"estimated_cost":{"description":"Optional cost estimate","type":"number"},"input_tokens":{"description":"Tokens in the request","type":"integer"},"model":{"description":"Model used for tokenization","type":"string"},"output_tokens":{"description":"Tokens in the response","type":"integer"},"total_tokens":{"description":"Total tokens (input + output)","type":"integer"},"truncated_tokens":{"description":"Tokens removed by truncation","type":"integer"},"was_truncated":{"description":"Whether response was truncated","type":"boolean"}},"type":"object"},"contracts.Tool":{"properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"approval_status":{"type":"string"},"config_denied":{"description":"ConfigDenied is true when the tool is denied by the server's static\nenabled_tools / disabled_tools config. The user cannot override this toggle.","type":"boolean"},"description":{"type":"string"},"disabled":{"description":"Disabled mirrors ToolApprovalRecord.Disabled so per-tool enable state is\navailable without a second round-trip to the approvals endpoint. Absent\nin the JSON when false (default) to keep responses compact.","type":"boolean"},"hash":{"description":"Hash is the tool's current stored hash rendered in the preflight pin\nformat \"sha256/v{N}:{hex}\" (Spec 098 FR-011), where N is the approval\nrecord's HashSchemaVersion. It is the authoring surface for\n` + "`" + `POST /api/v1/preflight` + "`" + ` pins and ` + "`" + `mcpproxy tools preflight --pin` + "`" + `:\ncopy the value straight into a pin.\n\nDisclosure is OPERATOR TIER ONLY โ€” same rule as the preflight per-tool\nresult. The field is omitted for agent-token callers and for tools with\nno stored hash (no approval record yet, or a record written before\nhashes existed).","type":"string"},"held_reason":{"description":"HeldReason, HeldVerdict and HeldSignals mirror the same-named fields on\nstorage.ToolApprovalRecord: the offline-scan evidence that made\ntrust_mode: scan hold this tool for review (spec 086 FR-018). HeldSignals\nnames the matched deterministic check ids, e.g.\n\"tpa.TPA-2026-0001.hidden_instruction\", so a reviewer can see WHY the tool\nis held. All three are omitted for tools that are not held by the scan gate\n(including every record written before the field existed).","type":"string"},"held_signals":{"items":{"type":"string"},"type":"array","uniqueItems":false},"held_verdict":{"type":"string"},"last_used":{"type":"string"},"name":{"type":"string"},"schema":{"type":"object"},"server_name":{"type":"string"},"usage":{"type":"integer"}},"type":"object"},"contracts.ToolAnnotation":{"description":"Tool behavior hints snapshot","properties":{"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"},"readOnlyHint":{"type":"boolean"},"title":{"type":"string"}},"type":"object"},"contracts.ToolCallRecord":{"description":"The new tool call record","properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"arguments":{"description":"Tool arguments","type":"object"},"config_path":{"description":"Active config file path","type":"string"},"duration":{"description":"Duration in nanoseconds","type":"integer"},"error":{"description":"Error message (failure only)","type":"string"},"execution_type":{"description":"\"direct\" or \"code_execution\"","type":"string"},"id":{"description":"Unique identifier","type":"string"},"mcp_client_name":{"description":"MCP client name from InitializeRequest","type":"string"},"mcp_client_version":{"description":"MCP client version","type":"string"},"mcp_session_id":{"description":"MCP session identifier","type":"string"},"metrics":{"$ref":"#/components/schemas/contracts.TokenMetrics"},"parent_call_id":{"description":"Links nested calls to parent code_execution","type":"string"},"request_id":{"description":"Request correlation ID","type":"string"},"response":{"description":"Tool response (success only)","type":"object"},"server_id":{"description":"Server identity hash","type":"string"},"server_name":{"description":"Human-readable server name","type":"string"},"timestamp":{"description":"When the call was made","type":"string"},"tool_name":{"description":"Tool name (without server prefix)","type":"string"}},"type":"object"},"contracts.UpdateInfo":{"description":"Update information (if available)","properties":{"available":{"description":"Whether an update is available","type":"boolean"},"behind_summary":{"description":"Spec 079 FR-002 โ€” how far behind the running build is. All four are\nadditive (FR-021) and absent when the delta could not be resolved, in\nwhich case every surface renders its pre-delta wording.","type":"string"},"check_error":{"description":"Error message if update check failed","type":"string"},"checked_at":{"description":"When the update check was performed","type":"string"},"install_channel":{"description":"Detected install channel (homebrew, dmg, deb, rpm, docker, go-install, windows-installer, tarball, unknown) โ€” Spec 079 FR-008","type":"string"},"is_prerelease":{"description":"Whether the latest version is a prerelease","type":"boolean"},"latest_version":{"description":"Latest version available (e.g., \"v1.2.3\")","type":"string"},"nudges_suppressed":{"description":"UI surfaces must stay quiet (CI / non-interactive context); machine-readable fields still report the facts โ€” Spec 079 FR-019","type":"boolean"},"release_url":{"description":"URL to the release page","type":"string"},"releases_behind":{"description":"Releases on the offered channel between the running and offered versions","type":"integer"},"releases_behind_saturated":{"description":"ReleasesBehind is a lower bound: the running build predates the scanned release window","type":"boolean"},"update_command":{"description":"One-line update command for the channel; only set when an update is available and the channel has one โ€” Spec 079 FR-009","type":"string"},"weeks_behind":{"description":"Whole weeks between the two releases' publish dates; 0 is a real value, absent means unknown","type":"integer"}},"type":"object"},"contracts.UpdatePolicy":{"description":"UpdatePolicy is the effective, hot-reloadable update policy (Spec 092\nFR-015). Always present: the ` + "`" + `update` + "`" + ` object above is omitted both when\nupdate checking is disabled AND when no check has produced a result\nyet, so its absence cannot tell a client whether it is allowed to run\nits own (e.g. Sparkle feed) check. This field states the answer.","properties":{"channel":{"description":"Channel is the tracked release channel: \"stable\" or \"rc\".","type":"string"},"enabled":{"description":"Enabled is the effective automatic-check kill switch: update_check.enabled\nwith MCPPROXY_DISABLE_AUTO_UPDATE=true winning over it. A user-initiated\n\"Check for Updates\" stays available regardless.","type":"boolean"},"nudges_suppressed":{"description":"NudgesSuppressed asks UI surfaces to stay quiet (CI / non-interactive)\nwhile machine-readable fields keep reporting the facts.","type":"boolean"}},"type":"object"},"contracts.UpstreamError":{"properties":{"error_message":{"type":"string"},"server_name":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.UsageAggregateResponse":{"properties":{"freshness_ms":{"description":"age of the underlying snapshot in ms","type":"integer"},"generated_at":{"type":"string"},"other":{"$ref":"#/components/schemas/contracts.UsageOtherBucket"},"timeline":{"items":{"$ref":"#/components/schemas/contracts.UsageTimeBucket"},"type":"array","uniqueItems":false},"token_source":{"description":"\"bytes\" (size-based proxy, FR-006)","type":"string"},"tokens_saved":{"description":"echoed from ServerTokenMetrics (FR-007)","type":"integer"},"tokens_saved_percentage":{"type":"number"},"tools":{"items":{"$ref":"#/components/schemas/contracts.UsageToolStat"},"type":"array","uniqueItems":false},"total_calls":{"description":"TotalCalls and TotalErrors are the headline counts for the window: the sum\nof the timeline this same response carries, so the tiles and the histogram\nunder them cannot disagree. They are NOT the sum of Tools โ€” that list is\nlifetime-cumulative, upstream-only and truncated to top-N, and summing it\nclient-side is what made the Usage tab print a third number for the same\n24 hours (audit finding F1, #1046). The population is\nstorage.CountsAsCall, shared with ActivitySummaryResponse.CallCount.\n\nTwo bounds on how exactly this matches the Activity Log's own count.\nBoth are bounded and disclosed, unlike the population mismatch they\nreplace, which was unbounded and silent:\n\n - Window granularity is the timeline's: whole hour buckets, so the span\n is the requested window rounded up to a bucket edge.\n - This response is served from a snapshot behind a short read cache\n (observability.usage_cache_ttl, 5s by default) so the endpoint never\n scans the activity log per request, while the summary endpoint counts\n live. Calls that land inside that window appear on the Activity Log\n first. FreshnessMs and GeneratedAt say how old the figures are, and\n the Usage tab prints it (\"Updated 3s ago\").","type":"integer"},"total_errors":{"type":"integer"},"window":{"type":"string"}},"type":"object"},"contracts.UsageOtherBucket":{"description":"present only when the list was truncated to top-N","properties":{"calls":{"type":"integer"},"tools_folded":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageTimeBucket":{"properties":{"calls":{"type":"integer"},"errors":{"type":"integer"},"start":{"type":"string"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageToolStat":{"properties":{"avg_req_bytes":{"description":"null when no sized request calls","type":"integer"},"avg_resp_bytes":{"description":"null when sized_calls == 0 (only legacy 0-byte calls)","type":"integer"},"blocked":{"type":"integer"},"calls":{"type":"integer"},"error_rate":{"type":"number"},"errors":{"type":"integer"},"last_used":{"type":"string"},"p50_exceeds":{"type":"boolean"},"p50_ms":{"description":"P50Ms and P95Ms are read off a fixed latency histogram, so they are BUCKET\nBOUNDS, not measured durations: the true percentile is at or below the\nvalue, and a client must render it as a bound (\"โ‰ค 5 ms\"). P50Exceeds /\nP95Exceeds flip that reading for the unbounded overflow bucket, where the\nvalue is the last bound and the truth is above it (\"\u003e 10 s\").","type":"integer"},"p95_exceeds":{"type":"boolean"},"p95_ms":{"type":"integer"},"rejected":{"description":"spec 093: shed by a concurrency limit; never executed, so excluded from calls/latency","type":"integer"},"server":{"type":"string"},"sized_calls":{"description":"calls with known response size (basis for avg_resp_bytes)","type":"integer"},"tool":{"type":"string"},"total_req_bytes":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.ValidateConfigResponse":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false},"valid":{"type":"boolean"}},"type":"object"},"contracts.ValidationError":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"data":{"properties":{"data":{"$ref":"#/components/schemas/contracts.InfoResponse"}},"type":"object"},"httpapi.AddServerRequest":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve\nnew/changed tools past the trust baseline (MCP-2930). Tri-state *bool:\na nil pointer means \"leave unchanged\" on PATCH; a present value\n(including false) is applied. Mirrors config.ServerConfig's *bool\nsemantics โ€” do NOT collapse to a plain bool, or an omitted field would\nsilently reset a previously-set value.","type":"boolean"},"command":{"type":"string"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts is the per-server override for prompt aggregation (F9):\nwhether this server's advertised MCP prompts are merged into mcpproxy's\nprompts/list. Tri-state *bool mirroring config.ServerConfig.ExposePrompts โ€”\na nil pointer means \"leave unchanged\" on PATCH (and \"inherit the default\naggregate behavior\" on create); a present value (including false) is applied.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"init_timeout":{"description":"InitTimeout is the per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override\n(MCP-3322 / GH #760), serialized as a duration string (e.g. \"120s\"). A nil\npointer means \"leave unchanged\" on PATCH; a present value is applied.\nMirrors config.ServerConfig.InitTimeout's *Duration tri-state.","type":"string"},"isolation":{"$ref":"#/components/schemas/httpapi.IsolationRequest"},"max_concurrent_requests":{"description":"MaxConcurrentRequests / QueueSize / QueueTimeout are the per-server\nconcurrency overrides (spec 093 / GH #955, FR-020 scope (c)). Each is\ntri-state: a nil pointer means \"leave unchanged\" on PATCH and \"inherit\nserver_concurrency_defaults\" on create; an explicit 0 disables that\nsetting for this server; a positive value overrides it. Do NOT collapse\nthem to plain values โ€” an omitted field would then silently reset a\nconfigured limit.","type":"integer"},"name":{"type":"string"},"protocol":{"type":"string"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"type":"boolean"},"trust_mode":{"description":"TrustMode is the per-server trust tier (spec 086): \"auto\", \"scan\", or\n\"manual\". Empty means \"leave unchanged\" on PATCH (and inherit the migrated\ndefault on create). A non-empty value is applied to ServerConfig.TrustMode\nand resolved by EffectiveTrustMode (an unrecognized value fails closed to\nmanual). This is the REST seam for changing the trust tier via\nPOST/PATCH /api/v1/servers.","type":"string"},"url":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.CanonicalConfigPath":{"properties":{"description":{"description":"Brief description","type":"string"},"exists":{"description":"Whether the file exists","type":"boolean"},"format":{"description":"Format identifier (e.g., \"claude_desktop\")","type":"string"},"name":{"description":"Display name (e.g., \"Claude Desktop\")","type":"string"},"os":{"description":"Operating system (darwin, windows, linux)","type":"string"},"path":{"description":"Full path to the config file","type":"string"}},"type":"object"},"httpapi.CanonicalConfigPathsResponse":{"properties":{"os":{"description":"Current operating system","type":"string"},"paths":{"description":"List of canonical config paths","items":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPath"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ConnectConflictResponse":{"properties":{"action":{"description":"already_exists | precondition_failed","type":"string"},"data":{"$ref":"#/components/schemas/connect.ConnectResult"},"error":{"description":"Human-readable message","type":"string"},"success":{"description":"Always false","type":"boolean"}},"type":"object"},"httpapi.ConnectRequest":{"properties":{"force":{"description":"Overwrite existing entry","type":"boolean"},"precondition_token":{"description":"PreconditionToken is the opaque token from the preview this write was\nconfirmed against (Spec 091 FR-005). When present, the core rechecks it\nat write time and responds 409 with action \"precondition_failed\" โ€”\nwriting nothing โ€” if the config or the entry MCPProxy would write has\ndrifted since; the caller then re-previews instead of retrying. Absent\nmeans exactly the pre-091 behavior. A replace-classified flow sends this\nTOGETHER with force=true: the token, not the absence of force, is the\noverwrite safety.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.ImportFromPathRequest":{"properties":{"format":{"description":"Optional format hint","type":"string"},"path":{"description":"File path to import from","type":"string"},"rename":{"additionalProperties":{"type":"string"},"description":"Rename maps a server name โ†’ new name. Applied after parsing so the\ncaller can disambiguate cross-source name collisions (Spec 046 v2 โ€”\ne.g. \"mcpproxy\" โ†’ \"mcpproxy_claude_code\"). Keys are matched against\neither the raw source name (OriginalName) or the sanitized name shown\nin the preview (Server.Name); these differ for names that need\nsanitizing (e.g. \"Figma Desktop\" โ†’ \"Figma_Desktop\"). Keys not present\nin the imported set are ignored.","type":"object"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportRequest":{"properties":{"content":{"description":"Raw JSON or TOML content","type":"string"},"format":{"description":"Optional format hint","type":"string"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportResponse":{"properties":{"failed":{"items":{"$ref":"#/components/schemas/configimport.FailedServer"},"type":"array","uniqueItems":false},"format":{"type":"string"},"format_name":{"type":"string"},"imported":{"items":{"$ref":"#/components/schemas/httpapi.ImportedServerResponse"},"type":"array","uniqueItems":false},"skipped":{"items":{"$ref":"#/components/schemas/configimport.SkippedServer"},"type":"array","uniqueItems":false},"summary":{"$ref":"#/components/schemas/configimport.ImportSummary"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportedServerResponse":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"command":{"type":"string"},"fields_skipped":{"items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"type":"string"},"original_name":{"type":"string"},"protocol":{"type":"string"},"source_format":{"type":"string"},"url":{"type":"string"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.IsolationRequest":{"description":"Isolation carries per-server Docker isolation overrides (image,\nnetwork_mode, extra_args, working_dir, enabled). A nil pointer\nmeans \"do not touch isolation config\"; an empty-but-present\nobject on PATCH intentionally clears the overrides.","properties":{"enabled":{"type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"network_mode":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.OnboardingMarkRequest":{"properties":{"connect_step_status":{"description":"ConnectStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value. The stored enum is wider (Spec 080\nFR-001): a \"skipped\" request for a previously untouched connect step\nis upgraded server-side to \"completed_external\" when the install\nshows positive evidence of an external connection (Spec 080 FR-002).\n\"completed_external\" is NOT accepted from clients โ€” it must never be\npersisted without that server-verified evidence (edge case: \"never\nguess completed_external without positive evidence\").","type":"string"},"engaged":{"description":"Engaged marks the wizard as engaged (completed or explicitly skipped).\nOnce true, the wizard does not auto-show again.","type":"boolean"},"mark_shown":{"description":"MarkShown records the wizard's first display time if not already set.","type":"boolean"},"server_step_status":{"description":"ServerStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value.","type":"string"}},"type":"object"},"httpapi.SetActiveProfileRequest":{"properties":{"active_profile":{"type":"string"},"profile":{"type":"string"}},"type":"object"},"httpapi.UndoConnectRequest":{"properties":{"backup_name":{"description":"BackupName is the bare filename (filepath.Base) of the backup returned as\nbackup_path by the preceding connect โ€” a name, never a path. Undo resolves\nthe full path server-side by joining it with the client's own config\ndirectory, so a client-supplied value can never contribute a directory\ncomponent (traversal is impossible by construction). Empty means the\nconnect created the file (no prior file existed), so undo removes it.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.UpdateFailureRequest":{"properties":{"stage":{"description":"Stage is the failure stage of the update session.","enum":["appcast","download","install","other"],"type":"string"}},"type":"object"},"management.BulkOperationResult":{"properties":{"errors":{"additionalProperties":{"type":"string"},"description":"Map of server name to error message","type":"object"},"failed":{"description":"Number of failed operations","type":"integer"},"successful":{"description":"Number of successful operations","type":"integer"},"total":{"description":"Total servers processed","type":"integer"}},"type":"object"},"observability.HealthResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"observability.HealthStatus":{"properties":{"error":{"type":"string"},"latency":{"type":"string"},"name":{"type":"string"},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"}},"type":"object"},"observability.ReadinessResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"ready\" or \"not_ready\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"secureenv.EnvConfig":{"description":"Environment configuration for secure variable filtering","properties":{"allowed_system_vars":{"items":{"type":"string"},"type":"array","uniqueItems":false},"custom_vars":{"additionalProperties":{"type":"string"},"type":"object"},"enhance_path":{"description":"Enable PATH enhancement for Launchd scenarios","type":"boolean"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned upstream servers (MCP-2769). It is OFF by\ndefault and deliberately kept out of the AllowedSystemVars default list:\nproxy URLs frequently carry credentials (http://user:pass@proxy), so\nforwarding them to every stdio upstream is a credential-leak risk. When\nenabled, values are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"inherit_system_safe":{"type":"boolean"}},"type":"object"},"telemetry.FeedbackContext":{"properties":{"arch":{"type":"string"},"connected_server_count":{"type":"integer"},"edition":{"type":"string"},"os":{"type":"string"},"routing_mode":{"type":"string"},"server_count":{"type":"integer"},"version":{"type":"string"}},"type":"object"},"telemetry.FeedbackRequest":{"properties":{"category":{"description":"bug, feature, other","type":"string"},"context":{"$ref":"#/components/schemas/telemetry.FeedbackContext"},"email":{"type":"string"},"message":{"type":"string"}},"type":"object"},"telemetry.FeedbackResponse":{"properties":{"error":{"type":"string"},"issue_url":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"API key authentication via query parameter. Use ?apikey=your-key","in":"query","name":"apikey","type":"apiKey"}}}, + "components": {"schemas":{"config.ConcurrencyDefaults":{"description":"ServerConcurrencyDefaults is scope (b) of FR-020: the blanket per-server\ndefault set inherited by every server that does not override a setting.\nAbsent (the default) = no per-server limiting unless a server configures\nit explicitly. File/API-configured only โ€” no env scheme (FR-022).","properties":{"max_concurrent_requests":{"type":"integer"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"}},"type":"object"},"config.Config":{"properties":{"activity_cleanup_interval_min":{"description":"Background cleanup interval in minutes (default: 60)","type":"integer"},"activity_max_records":{"description":"Max records before pruning (default: 100000)","type":"integer"},"activity_max_response_size":{"description":"Response truncation limit in bytes (default: 65536)","type":"integer"},"activity_max_size_mb":{"description":"Max total activity-log size in MB before pruning oldest (default: 256, 0=disabled)","type":"integer"},"activity_retention_days":{"description":"Activity logging settings (RFC-003)","type":"integer"},"aggregate_upstream_prompts":{"description":"AggregateUpstreamPrompts, when true, aggregates every connected upstream\nserver's advertised MCP prompts into mcpproxy's own prompts/list\n(exposed as \"\u003cserver\u003e__\u003cprompt\u003e\"). OFF by default: users are safe by\ndefault and opt in deliberately. EnablePrompts still governs the built-in\nprompts + the prompts capability; this flag gates ONLY the upstream\naggregation performed by RefreshPrompts. Hot-reloadable.","type":"boolean"},"allow_private_registry_fetch":{"description":"AllowPrivateRegistryFetch opts out of the registry SSRF guard (MCP-1076,\nCWE-918). By default (false) registry fetches refuse any host that is โ€” or\nresolves to โ€” a non-routable address (loopback, RFC1918/CGNAT private,\nlink-local incl. the 169.254.169.254 cloud-metadata endpoint), so a\nmalicious or typo'd registry source cannot turn the daemon into a\nrequest-forgery vector against internal services.\n\nThis opt-out is BLANKET (all-or-nothing): setting it true disables the\nguard for EVERY non-routable range at once โ€” loopback, RFC1918/CGNAT\nprivate, link-local AND the 169.254.169.254 cloud-metadata endpoint. There\nis no way to allow only loopback; enabling it for a localhost dev registry\nalso re-opens the cloud-metadata SSRF vector. Set true ONLY when you\nintentionally run a trusted registry mirror on an internal/private address,\nideally on a host with no cloud-metadata exposure. The change takes effect\nonly on daemon (re)start or config reload.","type":"boolean"},"allow_server_add":{"type":"boolean"},"allow_server_remove":{"type":"boolean"},"api_key":{"description":"Security settings","type":"string"},"call_tool_timeout":{"type":"string"},"check_server_repo":{"description":"Repository detection settings","type":"boolean"},"code_execution_max_parallel":{"description":"Default concurrency for call_tools() batches (1-32, default: 8)","type":"integer"},"code_execution_max_tool_calls":{"description":"Max tool calls per execution (0 = unlimited, default: 0)","type":"integer"},"code_execution_pool_size":{"description":"JavaScript runtime pool size (default: 10)","type":"integer"},"code_execution_timeout_ms":{"description":"Timeout in milliseconds (default: 120000, max: 600000)","type":"integer"},"data_dir":{"type":"string"},"debug_search":{"type":"boolean"},"direct_tool_response_mode":{"description":"DirectToolResponseMode selects the serialization of the DIRECT\nenumeration surface (Spec 102). Valid values: \"\" (= full), \"full\"\n(default: today's schema-bearing entries), \"deferred\" (description +\ncompact signature, with a minimal permissive input schema; upstream\ninputSchema and outputSchema are stripped and recovered on demand via\ndescribe_tool).\n\nDeliberately NOT an extension of tool_response_mode: reusing that axis\nwould silently change /mcp/all output for every deployment already\nrunning compact, which FR-015 forbids. Serialization-only โ€” it never\nchanges WHICH tools are listed, only how (FR-008). Hot-reloadable.","type":"string"},"disable_management":{"type":"boolean"},"docker_isolation":{"$ref":"#/components/schemas/config.DockerIsolationConfig"},"docker_recovery":{"$ref":"#/components/schemas/config.DockerRecoveryConfig"},"enable_code_execution":{"description":"Code execution settings","type":"boolean"},"enable_prompts":{"description":"Prompts settings","type":"boolean"},"enable_socket":{"description":"Enable Unix socket/named pipe for local IPC (default: true)","type":"boolean"},"enable_tray":{"description":"Deprecated: EnableTray is unused and has no runtime effect. Kept for backward compatibility.","type":"boolean"},"environment":{"$ref":"#/components/schemas/secureenv.EnvConfig"},"features":{"$ref":"#/components/schemas/config.FeatureFlags"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned stdio upstream servers (MCP-2769). OFF by\ndefault: proxy URLs commonly embed credentials (http://user:pass@proxy), so\nforwarding them to every upstream is a credential-leak risk. When enabled,\nvalues are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"health_check_interval":{"description":"Discovery \u0026 health-check cadence (spec 074, #608). Both are *Duration\ntri-state pointers: nil = inherit the built-in default; a pointer to 0s =\nthe loop is disabled; a positive value = that interval. Defaults live only\nin the resolvers (ResolveHealthCheckInterval / ResolveToolDiscoveryInterval)\nso an unset key behaves exactly as before this feature (SC-005). Validated\nin Validate(): health-check โˆˆ {0} โˆช [5s,1h]; tool-discovery โˆˆ {0} โˆช [30s,24h].","type":"string"},"http_idle_timeout":{"description":"HTTPIdleTimeout caps how long an idle keep-alive connection is kept open.\nUnset = 180s. \"0s\" removes the dedicated idle deadline, but net/http then\nfalls back to ReadTimeout โ€” idle is fully unbounded only when\nhttp_read_timeout is also \"0s\". Requires a restart.","type":"string"},"http_read_timeout":{"description":"HTTPReadTimeout caps how long reading a whole request (headers + body)\nmay take. Unset = 120s; \"0s\" disables it. Requires a restart.","type":"string"},"http_write_timeout":{"description":"HTTPWriteTimeout caps how long producing a whole response may take on\nnon-streaming endpoints (REST, Web UI, health). Unset = 120s; \"0s\"\ndisables it globally. MCP and SSE /events routes are exempt by design.","type":"string"},"init_timeout":{"description":"InitTimeout is the global default deadline for an upstream's MCP\n` + "`" + `initialize` + "`" + ` handshake (MCP-3322 / GH #760). *Duration tri-state: nil =\ninherit the built-in 30s default; a positive value = that deadline. A\nper-server InitTimeout overrides this. Resolved by ResolveInitTimeout;\nvalidated to {0} โˆช [1s, 30m] in Validate(). Servers doing legitimate\nfirst-run warmup (cache/index build) before answering ` + "`" + `initialize` + "`" + ` can\nraise this so they are not killed mid-startup.","type":"string"},"instructions":{"description":"Instructions text returned in the MCP initialize response to guide AI agents.\nWhen empty, a built-in default is used that explains retrieve_tools workflow.","type":"string"},"intent_declaration":{"$ref":"#/components/schemas/config.IntentDeclarationConfig"},"listen":{"type":"string"},"logging":{"$ref":"#/components/schemas/config.LogConfig"},"max_concurrent_requests":{"description":"Concurrency limits (spec 093, GH #955). Scope (a) of FR-020: the GLOBAL\nAGGREGATE limiter โ€” one proxy-wide cap on concurrently running upstream\ntool calls, with its own bounded wait queue. Tri-state pointers: absent =\nthe limiter does not exist (default, zero behavior change); an explicit 0\nmax also disables it; positive = that cap. This scope is NEVER a\nper-server inheritance source โ€” per-server values come from\nServerConcurrencyDefaults / the per-server overrides โ€” but a server's\neffective concurrency is bounded by BOTH its own limiter and this one.\nResolved by ResolveGlobalConcurrency; hot-reloadable; overridable via\nMCPPROXY_MAX_CONCURRENT_REQUESTS / _QUEUE_SIZE / _QUEUE_TIMEOUT (FR-022).","type":"integer"},"max_result_size_chars":{"description":"Advertised on every tool as ` + "`" + `_meta.anthropic/maxResultSizeChars` + "`" + `; raises Claude Code's inline-response ceiling from 50k to up to 500k chars. Set to 0 to disable.","type":"integer"},"mcpServers":{"items":{"$ref":"#/components/schemas/config.ServerConfig"},"type":"array","uniqueItems":false},"oauth_expiry_warning_hours":{"description":"Health status settings","type":"number"},"observability":{"$ref":"#/components/schemas/config.ObservabilityConfig"},"output_sanitisation":{"$ref":"#/components/schemas/config.OutputSanitisationConfig"},"output_validation":{"$ref":"#/components/schemas/config.OutputValidationConfig"},"profiles":{"description":"Profiles are optional named, server-scoped views exposed at /mcp/p/\u003cname\u003e\n(Spec 057). Absent/empty is fully supported โ€” /mcp is unchanged and configs\nwithout this key serialize byte-identically (SC-004).","items":{"$ref":"#/components/schemas/config.ProfileConfig"},"type":"array","uniqueItems":false},"quarantine_enabled":{"description":"QuarantineEnabled controls whether quarantine is active. It gates two\nthings together:\n 1. Server-level auto-quarantine for newly added servers (issue #370).\n When true, servers added via the upstream_servers MCP tool or the\n REST API default to quarantined=true; when false, they default to\n quarantined=false. Explicit per-request values always win.\n 2. Tool-level quarantine (Spec 032): per-tool SHA-256 approval of\n tool descriptions/schemas.\nWhen nil (default), quarantine is enabled (secure by default). Set to\nexplicit false to opt out of both. Per-server SkipQuarantine still\napplies for the tool-level check on individual servers.","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"read_only_mode":{"type":"boolean"},"registries":{"description":"Registries configuration for MCP server discovery","items":{"$ref":"#/components/schemas/config.RegistryEntry"},"type":"array","uniqueItems":false},"registries_locked":{"description":"RegistriesLocked is an enterprise stub knob (MCP-866): when true, runtime\nadditions of custom registries (e.g. ` + "`" + `registry add-source` + "`" + `, the REST/MCP\nadd-source surface) are rejected so an administrator can pin the discovery\nsources. Built-in defaults are unaffected. Documented but otherwise inert\nbeyond the add-source rejection.","type":"boolean"},"require_mcp_auth":{"description":"Require authentication on /mcp endpoint (default: false)","type":"boolean"},"reveal_secret_headers":{"description":"RevealSecretHeaders, when true, disables the redaction of the\nsecret-bearing server fields โ€” sensitive header values (Authorization,\nX-API-Key, Cookie, โ€ฆ), env-var secrets, and URL query credentials โ€” in\nresponses from the ` + "`" + `upstream_servers` + "`" + ` MCP tool, the ` + "`" + `/api/v1/servers` + "`" + `\nREST API, and the SSE event stream. It also lets URL secrets echoed\ninto last_error / health.detail through unscrubbed.\n\nDefault false โ€” sensitive values are surfaced masked as\n` + "`" + `โ€ขโ€ขโ€ขโ€ข\u003clast2\u003e (\u003cN\u003e chars)` + "`" + ` (error strings use ` + "`" + `***REDACTED***` + "`" + `) so an\nMCP agent cannot read Bearer tokens / API keys / URL secrets out of\nanother upstream's config (PR #425, issue #872). ${env:โ€ฆ}/${keyring:โ€ฆ}\nreferences are labels, not secrets, and pass through unchanged.\n\nThe Web UI / macOS tray edit forms work without seeing the real\nvalues: PATCH /api/v1/servers/{id} deep-merges (omitted keys are\npreserved, see ` + "`" + `headers_remove` + "`" + ` / ` + "`" + `env_remove` + "`" + ` for explicit\ndeletes), so clients compute a diff and only send the keys that\nactually changed. Redacted-but-unchanged values never round-trip\nโ€” the backend keeps the real string. Set this to true if a\ndownstream tool genuinely needs raw values in the response.","type":"boolean"},"routing_mode":{"description":"Routing mode (Spec 031): how MCP tools are exposed to clients\nValid values: \"retrieve_tools\" (default), \"direct\", \"code_execution\"","type":"string"},"security":{"$ref":"#/components/schemas/config.SecurityConfig"},"sensitive_data_detection":{"$ref":"#/components/schemas/config.SensitiveDataDetectionConfig"},"server_concurrency_defaults":{"$ref":"#/components/schemas/config.ConcurrencyDefaults"},"telemetry":{"$ref":"#/components/schemas/config.TelemetryConfig"},"tls":{"$ref":"#/components/schemas/config.TLSConfig"},"tokenizer":{"$ref":"#/components/schemas/config.TokenizerConfig"},"tool_discovery_interval":{"type":"string"},"tool_response_limit":{"type":"integer"},"tool_response_mode":{"description":"Tool response mode (Spec 085): how retrieve_tools serializes results.\nValid values: \"\" (= full), \"full\" (default: today's schema-bearing\nentries), \"compact\" (signature + first-sentence entries). Orthogonal to\nrouting_mode โ€” routing_mode selects the tool SURFACE, this selects the\nSERIALIZATION within the retrieve_tools surface. Serialization-only: it\nnever affects the query, ranking, or result set. Hot-reloadable.","type":"string"},"tool_response_session_risk_warning":{"description":"ToolResponseSessionRiskWarning controls whether the prose ` + "`" + `warning` + "`" + ` field\nis included in the ` + "`" + `session_risk` + "`" + ` object returned by ` + "`" + `retrieve_tools` + "`" + `.\nThe structured fields (level, lethal_trifecta, has_open_world_tools, etc.)\nare always included. Default: false (quiet for LLM clients) โ€” see issue #406.\nMost tools lack annotations, so the MCP-spec defaults treat them as fully\npermissive across all three risk axes, which makes the prose warning fire\non almost every call and wastes tokens.","type":"boolean"},"tools_limit":{"type":"integer"},"toon_min_savings_pct":{"description":"ToonMinSavingsPct is the minimum byte-savings percentage (validated\n1-90; 0/unset โ†’ 15) the complete TOON emission (marker + hint + body)\nmust achieve over the exact passthrough emission for adaptive mode to\nencode a block. Byte savings approximate token savings for the tabular\npayload class; the spec-083 profiler reports true token deltas.\nGlobal-only (no per-server override, FR-001).","type":"integer"},"toon_output":{"description":"ToonOutput selects the TOON encoding mode for call_tool_* result text\nblocks (spec 084): \"off\" (default โ€” responses byte-identical to\npre-feature behavior), \"adaptive\" (encode only tabular-uniform payloads\nthat beat compact JSON by ToonMinSavingsPct), or \"always\"\n(benchmark/debug only โ€” encodes every JSON-parseable block and can\nINCREASE token cost). Per-server override: ServerConfig.ToonOutput.\nResolved by ResolveToonOutput; hot-reloadable.","type":"string"},"top_k":{"description":"Deprecated: TopK is superseded by ToolsLimit and has no runtime effect. Kept for backward compatibility.","type":"integer"},"tray_endpoint":{"description":"Tray endpoint override (unix:// or npipe://)","type":"string"},"trusted_hosts":{"description":"TrustedHosts lists non-loopback Host header values accepted on loopback\nlisteners (GH #898). DNS-rebinding protection rejects requests whose Host\nheader is not a loopback address when mcpproxy listens on loopback; a\nreverse proxy (nginx โ†’ 127.0.0.1) forwarding the public domain in Host\ntrips it. Entries are hostnames, case-insensitive; an entry without a\nport matches any port, with a port it must match exactly; a leading dot\n(\".example.com\") is a subdomain wildcard. The single entry \"*\" disables\nHost and Origin validation entirely. The same list also validates the\nOrigin header when present (MCP spec DNS-rebinding defense). Empty\n(default) keeps full protection. Env override: MCPPROXY_TRUSTED_HOSTS\n(comma-separated).","items":{"type":"string"},"type":"array","uniqueItems":false},"update_check":{"$ref":"#/components/schemas/config.UpdateCheckConfig"}},"type":"object"},"config.CustomPattern":{"properties":{"category":{"description":"Category (defaults to \"custom\")","type":"string"},"keywords":{"description":"Keywords to match (mutually exclusive with Regex)","items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"description":"Unique identifier for this pattern","type":"string"},"regex":{"description":"Regex pattern (mutually exclusive with Keywords)","type":"string"},"severity":{"description":"Risk level: critical, high, medium, low","type":"string"}},"type":"object"},"config.DeepScanConfig":{"description":"DeepScan is the opt-in \"deep scan\" layer (Spec 077 US3). It subsumes the\ndeprecated top-level scanner_fetch_package_source / scanner_disable_no_new_privileges\nkeys (migrated on load) and gates the heavy Docker-based scanners + source\nextraction. Disabled by default (FR-006): only the deterministic in-process\nbaseline scanner runs. A deep-scan failure NEVER changes the baseline verdict\n(FR-007/FR-008).","properties":{"disable_no_new_privileges":{"description":"DisableNoNewPrivileges, when true, omits the ` + "`" + `--security-opt\nno-new-privileges` + "`" + ` flag from scanner container runs (snap-docker/AppArmor\nescape hatch). Absorbs the deprecated top-level\nscanner_disable_no_new_privileges. Default false.","type":"boolean"},"enabled":{"description":"Enabled is the master opt-in for the heavy layer (FR-006). Default false.","type":"boolean"},"fetch_package_source":{"description":"FetchPackageSource controls whether the scanner fetches the PUBLISHED\nsource of package-runner servers (npx/uvx) โ€” without executing it โ€” when\nno local source is available. Absorbs the deprecated top-level\nscanner_fetch_package_source. Default (nil) is ENABLED within deep scan.","type":"boolean"},"scanners":{"description":"Scanners optionally restricts which deep scanners may run under the\numbrella (by scanner id). Empty โ‡’ all enabled deep scanners are eligible.","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.DockerIsolationConfig":{"description":"Docker isolation settings","properties":{"cpu_limit":{"description":"CPU limit for containers","type":"string"},"default_images":{"additionalProperties":{"type":"string"},"description":"Map of runtime type to Docker image","type":"object"},"enable_cache_volume":{"description":"Mount shared cache volumes for faster restarts (default: true)","type":"boolean"},"enabled":{"description":"Global enable/disable for Docker isolation (legacy; superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments","items":{"type":"string"},"type":"array","uniqueItems":false},"log_driver":{"description":"Docker log driver (default: json-file)","type":"string"},"log_max_files":{"description":"Maximum number of log files (default: 3)","type":"string"},"log_max_size":{"description":"Maximum size of log files (default: 100m)","type":"string"},"memory_limit":{"description":"Memory limit for containers","type":"string"},"mode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true โ‡’ docker, false โ‡’ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"network_mode":{"description":"Docker network mode (default: bridge)","type":"string"},"registry":{"description":"Custom registry (defaults to docker.io)","type":"string"},"timeout":{"description":"Container startup timeout","type":"string"}},"type":"object"},"config.DockerRecoveryConfig":{"description":"Docker recovery settings","properties":{"enabled":{"description":"Enable Docker recovery monitoring (default: true)","type":"boolean"},"max_retries":{"description":"Maximum retry attempts (0 = unlimited)","type":"integer"},"notify_on_failure":{"description":"Show notification on recovery failure (default: true)","type":"boolean"},"notify_on_retry":{"description":"Show notification on each retry (default: false)","type":"boolean"},"notify_on_start":{"description":"Show notification when recovery starts (default: true)","type":"boolean"},"notify_on_success":{"description":"Show notification on successful recovery (default: true)","type":"boolean"},"persistent_state":{"description":"Save recovery state across restarts (default: true)","type":"boolean"}},"type":"object"},"config.FeatureFlags":{"description":"Deprecated: Features flags are unused and have no runtime effect. Kept for backward compatibility.","properties":{"enable_async_storage":{"type":"boolean"},"enable_caching":{"type":"boolean"},"enable_contract_tests":{"type":"boolean"},"enable_debug_logging":{"description":"Development features","type":"boolean"},"enable_docker_isolation":{"type":"boolean"},"enable_event_bus":{"type":"boolean"},"enable_health_checks":{"type":"boolean"},"enable_metrics":{"type":"boolean"},"enable_oauth":{"description":"Security features","type":"boolean"},"enable_observability":{"description":"Observability features","type":"boolean"},"enable_quarantine":{"type":"boolean"},"enable_runtime":{"description":"Runtime features","type":"boolean"},"enable_search":{"description":"Storage features","type":"boolean"},"enable_sse":{"type":"boolean"},"enable_tracing":{"type":"boolean"},"enable_tray":{"type":"boolean"},"enable_web_ui":{"description":"UI features","type":"boolean"}},"type":"object"},"config.IntentDeclarationConfig":{"description":"Intent declaration settings (Spec 018)","properties":{"strict_server_validation":{"description":"StrictServerValidation controls whether server annotation mismatches\ncause rejection (true) or just warnings (false).\nDefault: true (reject mismatches)","type":"boolean"}},"type":"object"},"config.IsolationConfig":{"description":"Per-server isolation settings","properties":{"enabled":{"description":"Enable Docker isolation for this server (nil = inherit global; legacy, superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments for this server","items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"description":"Custom Docker image (overrides default)","type":"string"},"log_driver":{"description":"Docker log driver override for this server","type":"string"},"log_max_files":{"description":"Maximum number of log files override","type":"string"},"log_max_size":{"description":"Maximum size of log files override","type":"string"},"mode":{"$ref":"#/components/schemas/config.IsolationMode"},"network_mode":{"description":"Custom network mode for this server","type":"string"},"working_dir":{"description":"Custom working directory in container","type":"string"}},"type":"object"},"config.IsolationMode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true โ‡’ docker, false โ‡’ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"config.LogConfig":{"description":"Logging configuration","properties":{"compress":{"type":"boolean"},"enable_console":{"type":"boolean"},"enable_file":{"type":"boolean"},"filename":{"type":"string"},"json_format":{"type":"boolean"},"level":{"type":"string"},"log_dir":{"description":"Custom log directory","type":"string"},"max_age":{"description":"days","type":"integer"},"max_backups":{"description":"number of backup files","type":"integer"},"max_size":{"description":"MB","type":"integer"}},"type":"object"},"config.MetricsExporterConfig":{"description":"Metrics gates the Prometheus /metrics scrape endpoint (MCP-32). Disabled\nby default โ€” operators opt in for k8s/enterprise deployments.","properties":{"enabled":{"description":"Enabled exposes /metrics on the existing HTTP listener when true.","type":"boolean"}},"type":"object"},"config.OAuthConfig":{"description":"OAuth configuration (keep even when empty to signal OAuth requirement)","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"description":"Additional OAuth parameters (e.g., RFC 8707 resource)","type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_uri":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ObservabilityConfig":{"description":"Observability settings (Spec 069): usage aggregate cache/persistence cadence.","properties":{"metrics":{"$ref":"#/components/schemas/config.MetricsExporterConfig"},"tracing":{"$ref":"#/components/schemas/config.TracingExporterConfig"},"usage_cache_ttl":{"description":"UsageCacheTTL bounds the freshness of the usage endpoint's read cache for\nwide windows (FR-005). Default 5s.","type":"string"},"usage_persist_interval":{"description":"UsagePersistInterval is how often the actor-owned usage aggregate snapshot\nis flushed to storage. Default 30s.","type":"string"}},"type":"object"},"config.OutputSanitisationConfig":{"description":"Output sanitisation settings (Spec 054 Track B)","properties":{"max_redactions":{"description":"cap on redactions per response; default 100","type":"integer"},"response_action":{"description":"\"spotlight\" | \"redact\" | \"block\"; default \"spotlight\"","type":"string"},"spotlight_untrusted":{"description":"wrap untrusted output in spotlight markers; default true","type":"boolean"},"strip_classes":{"description":"classes to strip: ansi/c0c1/bidi/zero_width","items":{"type":"string"},"type":"array","uniqueItems":false},"strip_control_chars":{"description":"strip control-character classes; default false","type":"boolean"}},"type":"object"},"config.OutputValidationConfig":{"description":"Output-schema validation settings (Spec 056)","properties":{"max_bytes":{"description":"structured payload byte cap; default 5\u003c\u003c20","type":"integer"},"max_depth":{"description":"nesting depth cap; default 64","type":"integer"},"missing_structured_content":{"description":"\"allow\" | \"block\"; default \"allow\"","type":"string"},"mode":{"description":"\"off\" | \"warn\" | \"strict\"; default \"warn\"","type":"string"}},"type":"object"},"config.ProfileConfig":{"properties":{"name":{"description":"URL slug, validated","type":"string"},"servers":{"description":"references to mcpServers[].name","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.RegistryEntry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag for this registry (MCP-866):\nRegistryProvenanceOfficial for built-in defaults, RegistryProvenanceCustom\nfor user-added registries. It is authoritatively (re)computed by the\nregistries merge from whether the ID is a shipped default โ€” a user cannot\nclaim \"official\" by writing it into their config.","type":"string"},"requires_key":{"description":"RequiresKey marks a registry that needs an API key to be queried. When\ntrue and no key is configured, the registry is skipped/marked unavailable\nrather than failing the whole search (FR-008).","type":"boolean"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"type":"string"}},"type":"object"},"config.SecurityConfig":{"description":"Security scanner settings (Spec 039)","properties":{"auto_baseline_scan":{"description":"AutoBaselineScan is the kill-switch for the AUTOMATIC, informational\nPass-1 baseline scan: the free in-process TPA scan mcpproxy runs for every\nnewly admitted server (any trust mode) and, once per installation, over\npre-existing servers that have never been scanned.\n\nInformational ONLY: the resulting verdict populates the security badge and\nthe scan summary, and NEVER gates quarantine or approval. The\ntrust_mode:\"scan\" admission gate is a separate path and is unaffected by\nthis flag.\n\nDefault (nil) is ENABLED. Set to false to suppress every automatic scan\n(manual scans keep working). Env override: MCPPROXY_AUTO_BASELINE_SCAN,\nwhich wins over this field on every path.","type":"boolean"},"deep_scan":{"$ref":"#/components/schemas/config.DeepScanConfig"},"integrity_check_interval":{"type":"string"},"integrity_check_on_restart":{"type":"boolean"},"runtime_read_only":{"type":"boolean"},"runtime_tmpfs_size":{"type":"string"},"scan_timeout_default":{"type":"string"},"scanner_disable_no_new_privileges":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.DisableNoNewPrivileges\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.IsDisableNoNewPrivileges. Cleared after migration.\n\nScannerDisableNoNewPrivileges, when true, omits the\n` + "`" + `--security-opt no-new-privileges` + "`" + ` flag from scanner container runs.\n\nBackground: snap-installed Docker on Ubuntu confines dockerd under the\n` + "`" + `snap.docker.dockerd` + "`" + ` AppArmor profile. When runc tries to transition\nthe container into the inner ` + "`" + `docker-default` + "`" + ` profile to exec the\nentrypoint, AppArmor refuses the transition because NO_NEW_PRIVS\nforbids privilege/profile changes on exec โ€” the result is EPERM\n(\"operation not permitted\") and every scanner fails immediately.\n\nSet this to true ONLY on hosts hitting that incompatibility. Scanner\ncontainers still run with read-only rootfs, tmpfs /tmp, no-network by\ndefault, and read-only source mounts, so the marginal isolation loss\nis small. The preferred fix remains replacing snap docker with a\ndistro-packaged docker.","type":"boolean"},"scanner_fetch_package_source":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.FetchPackageSource\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.EffectiveFetchPackageSource. Cleared after migration.\n\nScannerFetchPackageSource controls whether the scanner fetches the\nPUBLISHED source of package-runner servers (npx/uvx) โ€” without executing\nit โ€” when no local source is available (no Docker container, no local\npackage cache, no working_dir). This is the primary quarantine/scan\ntarget: a quarantined-on-add server is never run locally, so without this\nthe scan degrades to tool-definitions-only (no real source-level\nanalysis). See MCP-2206.\n\nFetching uses ` + "`" + `npm pack --ignore-scripts` + "`" + ` (npm) and ` + "`" + `uv pip download` + "`" + ` /\n` + "`" + `pip download` + "`" + ` with ` + "`" + `--only-binary=:all:` + "`" + ` (Python), which only download +\nunpack archives and NEVER run install, build, or setup.py โ€” a scanner must\nnot execute the untrusted code it is scanning. The Python\n` + "`" + `--only-binary=:all:` + "`" + ` flag is required because downloading an sdist would\ninvoke its build backend (setup.py); packages with no wheel fall back to\ntool-definitions-only instead. Extraction is hardened against path\ntraversal and decompression bombs.\n\nDefault (nil) is ENABLED. Set to false on air-gapped deployments to\nforbid the scanner's network egress; such servers then fall back to the\ntool-definitions-only scan with no regression.","type":"boolean"},"scanner_registry_url":{"type":"string"},"tpa_bundle_path":{"description":"TPABundlePath is the filesystem path to the tpa-db scanner-bundle.json\nthe offline TPA scanner runs (spec 086 FR-019: the signature-DB location\nMUST be configuration-driven, not hardcoded). Empty (the default) runs the\ncorpus embedded in this build.\n\nEnv override: MCPPROXY_TPA_BUNDLE_PATH. Hot-reloadable โ€” the path is\nre-read on every config.reloaded event via\nscanner.Service.ApplySecurityConfig, so a corpus refresh needs no restart.\nA configured bundle that fails to read/parse/version-check/compile is\nREFUSED and the previously active corpus stays live (fail-closed, never\nfail-empty); the reason is logged and surfaced in the security overview's\nsignature_bundle.load_error.","type":"string"}},"type":"object"},"config.SensitiveDataDetectionConfig":{"description":"Sensitive data detection settings (Spec 026)","properties":{"categories":{"additionalProperties":{"type":"boolean"},"description":"Enable/disable specific detection categories","type":"object"},"custom_patterns":{"description":"User-defined detection patterns","items":{"$ref":"#/components/schemas/config.CustomPattern"},"type":"array","uniqueItems":false},"enabled":{"description":"Enable sensitive data detection (default: true)","type":"boolean"},"entropy_threshold":{"description":"Shannon entropy threshold for high-entropy detection (default: 4.5)","type":"number"},"max_payload_size_kb":{"description":"Max size to scan before truncating (default: 1024)","type":"integer"},"scan_requests":{"description":"Scan tool call arguments (default: true)","type":"boolean"},"scan_responses":{"description":"Scan tool responses (default: true)","type":"boolean"},"sensitive_keywords":{"description":"Keywords to flag","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ServerConfig":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve tool\nchanges/additions (disabling per-server rug-pull protection). Supersedes\nskip_quarantine. MCP-2930 only ACCEPTS, persists, and migrates this flag โ€” it\nis NOT yet consulted at runtime; auto-approval is still governed by\nSkipQuarantine until the trust-baseline behavior change (MCP-2931) migrates the\nruntime consumers onto it.\nTri-state pointer (mirrors QuarantineEnabled): nil = unset (inherit/migrate\nfrom legacy skip_quarantine), explicit true/false = honored as-is so an\nexplicit auto_approve_tool_changes:false overrides a legacy skip_quarantine:true.\nRead via IsAutoApproveToolChanges().","type":"boolean"},"command":{"type":"string"},"created":{"type":"string"},"disabled_tools":{"description":"Denylist: these tools are hidden; mutually exclusive with enabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"},"enabled_tools":{"description":"Allowlist: only these tools are exposed; mutually exclusive with disabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts overrides whether this server's advertised MCP prompts are\naggregated into mcpproxy's prompts/list. nil (default) inherits the\ndefault-aggregate behavior (included if the server advertises\nCapabilities.Prompts); false excludes it regardless of capability.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"description":"For HTTP servers","type":"object"},"health_check_interval":{"description":"Per-server discovery \u0026 health-check overrides (spec 074). Same *Duration\ntri-state as the global keys: nil = inherit the global value (or default),\npointer to 0s = disabled for this server, positive = that interval.\nHealthCheckInterval is fully wired into the per-server health loop;\nToolDiscoveryInterval is accepted/validated and round-trips for\nforward-compat, but the periodic index sweep is governed by the global\ncadence in this iteration (see spec 074 plan ยงC).","type":"string"},"init_timeout":{"description":"InitTimeout overrides the global init_timeout for this server's MCP\n` + "`" + `initialize` + "`" + ` handshake deadline (MCP-3322 / GH #760). *Duration tri-state:\nnil = inherit the global value (or 30s default), positive = that deadline.\nResolved by Config.ResolveInitTimeout; validated to {0} โˆช [1s, 30m]. Raise\nthis for upstreams that do legitimate first-run warmup (e.g. caching many\nchannels/users) before responding to ` + "`" + `initialize` + "`" + `.","type":"string"},"isolation":{"$ref":"#/components/schemas/config.IsolationConfig"},"launcher_wait_timeout":{"description":"LauncherWaitTimeout caps how long mcpproxy will wait for a locally-launched\nHTTP/SSE upstream's URL to become reachable after Spawn(). Only consulted\nwhen the server is configured with both Command and an HTTP/SSE URL โ€” i.e.,\nmcpproxy starts the process AND connects via network. Stdio servers ignore\nthis field. Zero or unset โ†’ 30s default.","type":"string"},"max_concurrent_requests":{"description":"Per-server concurrency overrides โ€” scope (c) of FR-020 (spec 093, #955).\nTri-state per setting, exactly like HealthCheckInterval: absent = inherit\nthe per-server default set (server_concurrency_defaults), explicit 0 =\ndisable that setting for this server (0 max = no per-server limiter at\nall; 0 queue_size = no pending capacity, shed immediately at the cap),\npositive = override. The global aggregate limiter is never inherited from\nhere โ€” it applies on top, so effective concurrency is min(per-server,\nglobal). Resolved by Config.ResolveServerConcurrency.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/config.OAuthConfig"},"protocol":{"description":"stdio, http, sse, streamable-http, auto","type":"string"},"quarantined":{"description":"Security quarantine status","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets a disconnected server","type":"boolean"},"shared":{"description":"Server edition: shared with all users","type":"boolean"},"skip_quarantine":{"description":"SkipQuarantine is DEPRECATED (MCP-2930): use AutoApproveToolChanges instead.\nKept for back-compat parsing; on config load a legacy skip_quarantine:true is\nmigrated to auto_approve_tool_changes:true only when the new field is unset\n(see normalizeServerQuarantineFlags).","type":"boolean"},"source_registry_id":{"description":"SourceRegistryID records which registry this server was added from (empty\nfor manually-configured servers). MCP-866: surfaced in the approval /\nquarantine view so a reviewer can see a server's origin.","type":"string"},"source_registry_provenance":{"description":"SourceRegistryProvenance records the source registry's provenance at add\ntime (RegistryProvenanceOfficial / RegistryProvenanceCustom). It is purely\ninformational (MCP-1072) โ€” surfaced so a reviewer can see a server's origin\nโ€” and no longer gates quarantine or skip_quarantine.","type":"string"},"tool_discovery_interval":{"type":"string"},"toon_output":{"description":"ToonOutput overrides the global toon_output mode for this server's\ntools (spec 084, FR-001). Plain string, not a pointer: \"\"/absent =\ninherit the global value; \"off\"|\"adaptive\"|\"always\" = override (\"off\"\nis the explicit force-off). Resolved by Config.ResolveToonOutput.","type":"string"},"trust_mode":{"description":"TrustMode is the per-server trust tier: auto|scan|manual. Supersedes\nauto_approve_tool_changes (spec 086). An empty value is derived from the\nlegacy fields at load via normalizeServerQuarantineFlags; the single\nresolution point is EffectiveTrustMode(), which treats an empty or\nunrecognized value as manual (secure by default). Read via\nEffectiveTrustMode(), never the raw string.","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"working_dir":{"description":"Working directory for stdio servers","type":"string"}},"type":"object"},"config.TLSConfig":{"description":"TLS configuration","properties":{"certs_dir":{"description":"Directory for certificates","type":"string"},"enabled":{"description":"Enable HTTPS","type":"boolean"},"hsts":{"description":"Enable HTTP Strict Transport Security","type":"boolean"},"require_client_cert":{"description":"Enable mTLS","type":"boolean"}},"type":"object"},"config.TelemetryConfig":{"description":"Telemetry settings (Spec 036)","properties":{"anonymous_id":{"description":"Auto-generated UUIDv4","type":"string"},"anonymous_id_created_at":{"description":"Spec 042 (Tier 2) additions โ€” all default-zero, all backwards-compatible.","type":"string"},"enabled":{"description":"Default: true (opt-out)","type":"boolean"},"endpoint":{"description":"Override for testing","type":"string"},"last_reported_version":{"description":"Upgrade funnel","type":"string"},"last_startup_outcome":{"description":"success|port_conflict|db_locked|...","type":"string"},"notice_shown":{"description":"First-run notice flag","type":"boolean"}},"type":"object"},"config.TokenizerConfig":{"description":"Tokenizer configuration for token counting","properties":{"default_model":{"description":"Default model for tokenization (e.g., \"gpt-4\")","type":"string"},"enabled":{"description":"Enable token counting","type":"boolean"},"encoding":{"description":"Default encoding (e.g., \"cl100k_base\")","type":"string"}},"type":"object"},"config.TracingExporterConfig":{"description":"Tracing gates the OpenTelemetry OTLP trace exporter (MCP-32). Disabled by\ndefault.","properties":{"enabled":{"description":"Enabled turns on OTLP trace export for tool calls and upstream hops.","type":"boolean"},"endpoint":{"description":"Endpoint is the collector address as host:port (no scheme), e.g.\n\"localhost:4318\" for http or \"localhost:4317\" for grpc.","type":"string"},"protocol":{"description":"Protocol selects the OTLP transport: \"http\" or \"grpc\".","type":"string"},"sample_rate":{"description":"SampleRate is the head-based trace sampling ratio in [0,1]. Default 0.1.","type":"number"}},"type":"object"},"config.UpdateCheckConfig":{"description":"Update-check settings (Spec 079 FR-012): config-file control of the\nbackground upgrade-awareness checker (internal/updatecheck). nil =\nenabled on the stable channel (existing default behavior). The existing\nenvironment switches keep working and WIN over these keys (FR-014):\nMCPPROXY_DISABLE_AUTO_UPDATE=true force-disables even when\nenabled=true, and MCPPROXY_ALLOW_PRERELEASE_UPDATES=true force-selects\nthe rc channel even when channel=stable.","properties":{"channel":{"description":"Channel selects which releases are offered as updates: \"stable\"\n(default; prereleases never offered) or \"rc\" (prereleases included).\nEmpty resolves to stable. Validated in ValidateDetailed.\n\nNOTE: for a RELEASED build the running binary's own version is\nauthoritative and overrides this field โ€” a stable build is never\noffered an RC (even with channel=rc), and an RC build always tracks the\nrc channel. This field only takes effect on dev/unstamped builds. See\ninternal/updatecheck.Checker.IncludePrereleases.","type":"string"},"enabled":{"description":"Enabled gates all update checking. Tri-state: nil/absent = enabled\n(default true, matching pre-079 behavior). When false, no network\ncheck is performed and no upgrade nudge appears on any surface\n(FR-015) โ€” /api/v1/info omits the update object entirely.","type":"boolean"}},"type":"object"},"configimport.FailedServer":{"properties":{"details":{"type":"string"},"error":{"type":"string"},"name":{"type":"string"}},"type":"object"},"configimport.ImportSummary":{"properties":{"failed":{"type":"integer"},"imported":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"configimport.SkippedServer":{"properties":{"name":{"type":"string"},"reason":{"description":"\"already_exists\", \"filtered_out\", \"invalid_name\"","type":"string"}},"type":"object"},"connect.ConnectResult":{"description":"The full result; its action mirrors the top-level one","properties":{"action":{"description":"\"created\", \"updated\", \"already_exists\", \"removed\", \"not_found\"","type":"string"},"backup_path":{"type":"string"},"client":{"type":"string"},"config_path":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.APIResponse":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ActivityDetailResponse":{"properties":{"activity":{"$ref":"#/components/schemas/contracts.ActivityRecord"}},"type":"object"},"contracts.ActivityListResponse":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/contracts.ActivityRecord"},"type":"array","uniqueItems":false},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.ActivityRecord":{"properties":{"arguments":{"description":"Tool call arguments","type":"object"},"detection_types":{"description":"List of detection types found","items":{"type":"string"},"type":"array","uniqueItems":false},"duration_ms":{"description":"Execution duration in milliseconds","type":"integer"},"error_message":{"description":"Error details if status is \"error\"","type":"string"},"has_sensitive_data":{"description":"Sensitive data detection fields (Spec 026)","type":"boolean"},"id":{"description":"Unique identifier (ULID format)","type":"string"},"max_severity":{"description":"Highest severity level detected (critical, high, medium, low)","type":"string"},"metadata":{"description":"Additional context-specific data","type":"object"},"parent_id":{"description":"Correlation id of the parent call (the code_execution whose sandbox issued this sub-call)","type":"string"},"request_bytes":{"description":"Byte sizes measured pre-truncation, mirroring storage.ActivityRecord\n(Spec 069 A1). They are the only cost signal a bodies-off export carries:\nwith payloads suppressed there is no text left to measure, so a consumer\naccounting for a record it cannot read has nothing else to go on. They are\nbyte LENGTHS, not token counts โ€” the basis for an explicit estimate, never\na measured figure (spec 103, contracts/replay-input.md).\n\nZero means UNKNOWN, not free: legacy records predate the measurement and\ncode-execution sub-calls record both as zero. Hence omitempty โ€” an absent\nkey tells a consumer to fall to exclusion accounting, whereas a present\nzero would read as a costless call and silently understate the workload.","type":"integer"},"request_id":{"description":"HTTP request ID for correlation","type":"string"},"response":{"description":"Tool response (potentially truncated)","type":"string"},"response_bytes":{"description":"Raw upstream response size in bytes before truncation","type":"integer"},"response_truncated":{"description":"True if response was truncated","type":"boolean"},"server_name":{"description":"Name of upstream MCP server","type":"string"},"session_id":{"description":"MCP transport session ID (regenerated on every reconnect)","type":"string"},"source":{"$ref":"#/components/schemas/contracts.ActivitySource"},"status":{"description":"Result status: \"success\", \"error\", \"blocked\", \"rejected\"","type":"string"},"timestamp":{"description":"When activity occurred","type":"string"},"tool_name":{"description":"Name of tool called","type":"string"},"type":{"$ref":"#/components/schemas/contracts.ActivityType"},"work_session_id":{"description":"Spec 082: one client, one project, across reconnects","type":"string"}},"type":"object"},"contracts.ActivitySource":{"description":"How activity was triggered: \"mcp\", \"cli\", \"api\"","type":"string","x-enum-varnames":["ActivitySourceMCP","ActivitySourceCLI","ActivitySourceAPI"]},"contracts.ActivitySummaryResponse":{"properties":{"blocked_count":{"description":"Count of blocked activities","type":"integer"},"call_count":{"description":"CallCount is how many of those records are CALLS THE USER MADE, as\ndefined once in storage.CountsAsCall and shared with the usage aggregate\nbehind the Usage tab (audit finding F1, #1046). TotalCount answers \"how\nmany rows does the Activity Log have\"; CallCount answers \"how many calls\nwere there\". They are different questions โ€” quarantine auto-approvals,\nsystem start, security scans and management chatter are events, not calls\nโ€” and printing either one under the other's label is how the same instance\ncame to report 51 calls on one screen and 19 on another.","type":"integer"},"call_error_count":{"description":"CallErrorCount is the failures within CallCount, so an error RATE computed\nfrom this response has one denominator. It is not ErrorCount: a policy\nblock is a failed call but carries status \"blocked\", and a shed call is an\nerror in neither sense because it never ran.","type":"integer"},"end_time":{"description":"End of the period (RFC3339)","type":"string"},"error_count":{"description":"Count of error activities","type":"integer"},"other_count":{"description":"OtherCount is every record whose status is outside the four-value\nvocabulary above, so that\n\n\tsuccess + error + blocked + rejected + other == total\n\nholds by construction. The status field is a CLOSED vocabulary for tool\ncalls, but the activity log is wider than tool calls: a quarantine change\nstores its ACTION there (\"approved\", \"auto_approved\"), a policy decision\nstores its DECISION (\"allow\"). Those rows were counted in the total and in\nnone of the four buckets, so the Activity Log's own status tiles summed to\nless than the denominator printed beside them โ€” 15+4+0+0 under a \"42\"\n(audit finding F2, #1046). The residual now has a name and a tile.","type":"integer"},"period":{"description":"Time period (1h, 24h, 7d, 30d)","type":"string"},"rejected_count":{"description":"RejectedCount is the number of calls shed by a concurrency limiter before\nthey reached an upstream (spec 093). Counted separately from errors: it is\nproxy backpressure, not an upstream fault, and it is the signal an\noperator right-sizes max_concurrent_requests against.","type":"integer"},"start_time":{"description":"Start of the period (RFC3339)","type":"string"},"success_count":{"description":"Count of successful activities","type":"integer"},"top_servers":{"description":"Top servers by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopServer"},"type":"array","uniqueItems":false},"top_tools":{"description":"Top tools by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopTool"},"type":"array","uniqueItems":false},"total_count":{"description":"Total activity count","type":"integer"}},"type":"object"},"contracts.ActivityTopServer":{"properties":{"count":{"description":"Activity count","type":"integer"},"name":{"description":"Server name","type":"string"}},"type":"object"},"contracts.ActivityTopTool":{"properties":{"count":{"description":"Activity count","type":"integer"},"server":{"description":"Server name","type":"string"},"tool":{"description":"Tool name","type":"string"}},"type":"object"},"contracts.ActivityType":{"description":"Type of activity","type":"string","x-enum-varnames":["ActivityTypeToolCall","ActivityTypePolicyDecision","ActivityTypeQuarantineChange","ActivityTypeServerChange"]},"contracts.AddFromRegistryRequest":{"properties":{"enabled":{"description":"defaults to true when nil","type":"boolean"},"env":{"additionalProperties":{"type":"string"},"description":"overrides + required-input values","type":"object"},"name":{"description":"optional name override","type":"string"}},"type":"object"},"contracts.AddRegistrySourceRequest":{"properties":{"id":{"description":"derived from the host when empty","type":"string"},"name":{"description":"defaults to the id","type":"string"},"protocol":{"description":"defaults to modelcontextprotocol/registry","type":"string"},"url":{"description":"required https registry URL","type":"string"}},"type":"object"},"contracts.ConfigApplyResult":{"properties":{"applied_immediately":{"type":"boolean"},"changed_fields":{"items":{"type":"string"},"type":"array","uniqueItems":false},"requires_restart":{"type":"boolean"},"restart_reason":{"type":"string"},"success":{"type":"boolean"},"validation_errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DCRStatus":{"properties":{"attempted":{"type":"boolean"},"error":{"type":"string"},"status_code":{"type":"integer"},"success":{"type":"boolean"}},"type":"object"},"contracts.DeepScanDescriptor":{"description":"DeepScan reports the opt-in \"deep scan\" layer status (Spec 077 US3),\nSEPARATELY from the baseline verdict above. Always emitted on a computed\nsummary โ€” when deep scan is off (the default) it reports enabled=false\nplus any enabled-but-skipped Docker scanners. It never influences Status.","properties":{"available":{"type":"boolean"},"enabled":{"type":"boolean"},"ran":{"type":"boolean"},"scanners_failed":{"items":{"$ref":"#/components/schemas/contracts.DeepScanScannerFailure"},"type":"array","uniqueItems":false},"skipped_scanners":{"description":"SkippedScanners lists Docker scanners the user enabled that are skipped\nbecause security.deep_scan.enabled is false (informational).","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DeepScanScannerFailure":{"properties":{"id":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"contracts.DeprecatedConfigWarning":{"properties":{"field":{"type":"string"},"message":{"type":"string"},"replacement":{"type":"string"}},"type":"object"},"contracts.Diagnostic":{"description":"Spec 044 โ€” structured diagnostic error and stable error code. Both\nare populated when the server is in a failed state and the error\nhas been classified by internal/diagnostics. Healthy servers omit\nthese fields.","properties":{"cause":{"type":"string"},"code":{"type":"string"},"detected_at":{"type":"string"},"docs_url":{"type":"string"},"fix_steps":{"items":{"$ref":"#/components/schemas/contracts.DiagnosticFixStep"},"type":"array","uniqueItems":false},"severity":{"type":"string"},"user_message":{"type":"string"}},"type":"object"},"contracts.DiagnosticFixStep":{"properties":{"command":{"type":"string"},"destructive":{"type":"boolean"},"fixer_key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"}},"type":"object"},"contracts.Diagnostics":{"properties":{"deprecated_configs":{"description":"Deprecated config fields found","items":{"$ref":"#/components/schemas/contracts.DeprecatedConfigWarning"},"type":"array","uniqueItems":false},"docker_status":{"$ref":"#/components/schemas/contracts.DockerStatus"},"missing_secrets":{"description":"Renamed to avoid conflict","items":{"$ref":"#/components/schemas/contracts.MissingSecretInfo"},"type":"array","uniqueItems":false},"oauth_issues":{"description":"OAuth parameter mismatches","items":{"$ref":"#/components/schemas/contracts.OAuthIssue"},"type":"array","uniqueItems":false},"oauth_required":{"items":{"$ref":"#/components/schemas/contracts.OAuthRequirement"},"type":"array","uniqueItems":false},"runtime_warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false},"timestamp":{"type":"string"},"total_issues":{"type":"integer"},"upstream_errors":{"items":{"$ref":"#/components/schemas/contracts.UpstreamError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DockerStatus":{"properties":{"available":{"type":"boolean"},"error":{"type":"string"},"version":{"type":"string"}},"type":"object"},"contracts.EditRegistrySourceRequest":{"properties":{"name":{"description":"new display name","type":"string"},"servers_url":{"description":"explicit servers-collection URL","type":"string"},"url":{"description":"new base/servers https URL","type":"string"}},"type":"object"},"contracts.ErrorResponse":{"properties":{"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.FindingCounts":{"properties":{"dangerous":{"description":"Tool poisoning, active prompt injection","type":"integer"},"info":{"description":"Low-severity CVEs, informational","type":"integer"},"total":{"type":"integer"},"warning":{"description":"Rug pull, supply chain CVEs with exploits","type":"integer"}},"type":"object"},"contracts.GetConfigResponse":{"properties":{"config":{"description":"The configuration object","type":"object"},"config_path":{"description":"Path to config file","type":"string"}},"type":"object"},"contracts.GetRegistriesResponse":{"properties":{"registries":{"items":{"$ref":"#/components/schemas/contracts.Registry"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerLogsResponse":{"properties":{"count":{"type":"integer"},"logs":{"items":{"$ref":"#/components/schemas/contracts.LogEntry"},"type":"array","uniqueItems":false},"server_name":{"type":"string"}},"type":"object"},"contracts.GetServerToolCallsResponse":{"properties":{"server_name":{"type":"string"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerToolsResponse":{"properties":{"count":{"type":"integer"},"server_name":{"type":"string"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GetServersResponse":{"properties":{"servers":{"items":{"$ref":"#/components/schemas/contracts.Server"},"type":"array","uniqueItems":false},"stats":{"$ref":"#/components/schemas/contracts.ServerStats"}},"type":"object"},"contracts.GetSessionDetailResponse":{"properties":{"session":{"$ref":"#/components/schemas/contracts.MCPSession"}},"type":"object"},"contracts.GetSessionsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"sessions":{"items":{"$ref":"#/components/schemas/contracts.MCPSession"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetToolCallDetailResponse":{"properties":{"tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"}},"type":"object"},"contracts.GetToolCallsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GlobalToolsResponse":{"properties":{"failed_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"partial":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/contracts.GlobalToolsStats"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GlobalToolsStats":{"properties":{"disabled":{"type":"integer"},"enabled":{"type":"integer"},"pending_approval":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.HealthStatus":{"description":"Unified health status calculated by the backend","properties":{"action":{"description":"Action is the suggested fix action: \"login\", \"restart\", \"enable\", \"approve\", \"view_logs\", \"set_secret\", \"configure\", \"edit_url\", or \"\" (none)","type":"string"},"admin_state":{"description":"AdminState indicates the admin state: \"enabled\", \"disabled\", or \"quarantined\"","type":"string"},"detail":{"description":"Detail is an optional longer explanation of the status","type":"string"},"level":{"description":"Level indicates the health level: \"healthy\", \"degraded\", or \"unhealthy\"","type":"string"},"summary":{"description":"Summary is a human-readable status message (e.g., \"Connected (5 tools)\")","type":"string"}},"type":"object"},"contracts.InfoEndpoints":{"description":"Available API endpoints","properties":{"http":{"description":"HTTP endpoint address (e.g., \"127.0.0.1:8080\")","type":"string"},"socket":{"description":"Unix socket path (empty if disabled)","type":"string"}},"type":"object"},"contracts.InfoResponse":{"properties":{"endpoints":{"$ref":"#/components/schemas/contracts.InfoEndpoints"},"launched_by":{"description":"LaunchedBy is the durable launch provenance of the running core (Spec\n092 FR-001a): \"tray\" when a tray spawned it, \"installer\" when the macOS\nPKG postinstall did, \"\" when user-launched or unknown. Always present\n(possibly empty) so a tray can distinguish \"old core, not mine\" from\n\"old core I may supersede\".","type":"string"},"listen_addr":{"description":"Listen address (e.g., \"127.0.0.1:8080\")","type":"string"},"pid":{"description":"PID is the operating-system process id of the running core (Spec 092\nFR-002). A tray that merely ATTACHED to a core holds no Process handle\nfor it, so without this there is no mechanism at all to stop a stale\ncore โ€” the consent action would have nothing to act on and could only\nprint instructions. Paired with LaunchedBy it is what lets a newer tray\nsupersede a core an older tray started.","type":"integer"},"update":{"$ref":"#/components/schemas/contracts.UpdateInfo"},"update_policy":{"$ref":"#/components/schemas/contracts.UpdatePolicy"},"version":{"description":"Current MCPProxy version","type":"string"},"web_ui_url":{"description":"URL to access the web control panel","type":"string"}},"type":"object"},"contracts.IsolationConfig":{"properties":{"cpu_limit":{"type":"string"},"enabled":{"type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"memory_limit":{"type":"string"},"network_mode":{"type":"string"},"timeout":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationDefaults":{"description":"IsolationDefaults exposes the resolved baseline values that\nwould apply when no per-server override is set. Populated on\nlist/get responses; never consumed on PATCH requests.","properties":{"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"network_mode":{"type":"string"},"runtime_type":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.LogEntry":{"properties":{"fields":{"type":"object"},"level":{"type":"string"},"message":{"type":"string"},"server":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.MCPSession":{"properties":{"client_name":{"type":"string"},"client_version":{"type":"string"},"end_time":{"type":"string"},"experimental":{"items":{"type":"string"},"type":"array","uniqueItems":false},"has_roots":{"description":"MCP Client Capabilities","type":"boolean"},"has_sampling":{"type":"boolean"},"id":{"type":"string"},"last_activity":{"type":"string"},"start_time":{"type":"string"},"status":{"type":"string"},"tool_call_count":{"type":"integer"},"total_tokens":{"type":"integer"},"work_session_id":{"type":"string"},"workspace_name":{"description":"Workspace / work session (Spec 082). WorkspaceName is the project's\nbasename โ€” the full local path is never exposed. WorkSessionID groups the\nreconnects that make up one stretch of user work.","type":"string"}},"type":"object"},"contracts.MetadataStatus":{"properties":{"authorization_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"error":{"type":"string"},"found":{"type":"boolean"},"url_checked":{"type":"string"}},"type":"object"},"contracts.MissingSecretInfo":{"properties":{"secret_name":{"type":"string"},"used_by":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.NPMPackageInfo":{"properties":{"exists":{"type":"boolean"},"install_cmd":{"type":"string"}},"type":"object"},"contracts.OAuthConfig":{"properties":{"auth_url":{"type":"string"},"client_id":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_port":{"type":"integer"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false},"token_expires_at":{"description":"When the OAuth token expires","type":"string"},"token_url":{"type":"string"},"token_valid":{"description":"Whether token is currently valid","type":"boolean"}},"type":"object"},"contracts.OAuthErrorDetails":{"description":"Structured discovery/failure details","properties":{"authorization_server_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"dcr_status":{"$ref":"#/components/schemas/contracts.DCRStatus"},"protected_resource_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"server_url":{"type":"string"}},"type":"object"},"contracts.OAuthFlowError":{"properties":{"correlation_id":{"description":"Flow tracking ID for log correlation","type":"string"},"debug_hint":{"description":"CLI command for log lookup","type":"string"},"details":{"$ref":"#/components/schemas/contracts.OAuthErrorDetails"},"error_code":{"description":"Machine-readable error code (e.g., OAUTH_NO_METADATA)","type":"string"},"error_type":{"description":"Category of OAuth runtime failure","type":"string"},"message":{"description":"Human-readable error description","type":"string"},"request_id":{"description":"HTTP request ID (from PR #237)","type":"string"},"server_name":{"description":"Server that failed OAuth","type":"string"},"success":{"description":"Always false","type":"boolean"},"suggestion":{"description":"Actionable remediation hint","type":"string"}},"type":"object"},"contracts.OAuthIssue":{"properties":{"documentation_url":{"type":"string"},"error":{"type":"string"},"issue":{"type":"string"},"missing_params":{"items":{"type":"string"},"type":"array","uniqueItems":false},"resolution":{"type":"string"},"server_name":{"type":"string"}},"type":"object"},"contracts.OAuthRequirement":{"properties":{"expires_at":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"state":{"type":"string"}},"type":"object"},"contracts.OAuthStartResponse":{"properties":{"auth_url":{"description":"Authorization URL (always included for manual use)","type":"string"},"browser_error":{"description":"Error message if browser launch failed","type":"string"},"browser_opened":{"description":"Whether browser launch succeeded","type":"boolean"},"correlation_id":{"description":"UUID for tracking this flow","type":"string"},"message":{"description":"Human-readable status message","type":"string"},"server_name":{"description":"Name of the server being authenticated","type":"string"},"success":{"description":"Always true for successful start","type":"boolean"}},"type":"object"},"contracts.PreflightPolicy":{"properties":{"exclude_destructive":{"type":"boolean"},"exclude_open_world":{"type":"boolean"},"read_only_only":{"type":"boolean"}},"type":"object"},"contracts.PreflightReason":{"type":"string","x-enum-varnames":["PreflightReasonServerInitializing","PreflightReasonServerUnhealthy","PreflightReasonServerDisabled","PreflightReasonServerQuarantined","PreflightReasonToolPendingApproval","PreflightReasonToolChanged","PreflightReasonToolBlockedByUser","PreflightReasonOAuthRequired","PreflightReasonHashMismatch","PreflightReasonServerNotInScope","PreflightReasonToolDeniedByConfig","PreflightReasonMissingAnnotation","PreflightReasonPolicyFiltered","PreflightReasonNotFound","PreflightReasonServerNotConfigured"]},"contracts.PreflightRequest":{"properties":{"policy":{"$ref":"#/components/schemas/contracts.PreflightPolicy"},"profile":{"description":"Profile evaluates under a named profile's server scope. Unknown: 400.","type":"string"},"tools":{"description":"Tools is 1..100 entries BEFORE dedup; duplicates are collapsed, and\nduplicate ids carrying different pins are a validation error.","items":{"$ref":"#/components/schemas/contracts.PreflightToolRef"},"type":"array","uniqueItems":false},"wait_ms":{"description":"WaitMS polls local state for up to this many milliseconds (cap 10000)\nwhile every failure is retryable-class.","type":"integer"}},"type":"object"},"contracts.PreflightResponse":{"properties":{"checked_at":{"type":"string"},"tools":{"description":"Tools are ordered by first occurrence of each unique id in the request.","items":{"$ref":"#/components/schemas/contracts.PreflightToolResult"},"type":"array","uniqueItems":false},"verdict":{"$ref":"#/components/schemas/contracts.PreflightVerdict"},"waited_ms":{"description":"WaitedMS is present when wait_ms was requested (0 when the wait\nsemaphore was exhausted and the request resolved immediately).","type":"integer"}},"type":"object"},"contracts.PreflightStatus":{"type":"string","x-enum-varnames":["PreflightStatusReady","PreflightStatusUnavailable"]},"contracts.PreflightToolRef":{"properties":{"id":{"description":"ID is a canonical \"\u003cserver\u003e:\u003ctool\u003e\" id. A malformed id is answered with a\nper-ID not_found carrying a format hint, never a request-level error.","type":"string"},"pin_hash":{"description":"PinHash is \"sha256/v{N}:{hex}\" โ€” the schema version is embedded so a\nproxy-side hash-algorithm bump is distinguishable from upstream drift.","type":"string"}},"type":"object"},"contracts.PreflightToolResult":{"properties":{"action":{"type":"string"},"detail":{"type":"string"},"did_you_mean":{"description":"DidYouMean carries up to 3 nearest caller-visible ids on not_found. It\nnever crosses a scope boundary and never names a quarantined server's\ntools.","items":{"type":"string"},"type":"array","uniqueItems":false},"hash":{"description":"Hash is the tool's current pin (\"sha256/v{N}:{hex}\") โ€” operator tier,\nready results only. Never disclosed to an agent token.","type":"string"},"id":{"type":"string"},"reason":{"$ref":"#/components/schemas/contracts.PreflightReason"},"remediation":{"type":"string"},"retryable":{"type":"boolean"},"status":{"$ref":"#/components/schemas/contracts.PreflightStatus"}},"type":"object"},"contracts.PreflightVerdict":{"type":"string","x-enum-varnames":["PreflightVerdictReady","PreflightVerdictDegradedRetryable","PreflightVerdictBlocked","PreflightVerdictUnknownIDs"]},"contracts.QuarantineStats":{"description":"Tool quarantine metrics for this server","properties":{"blocked_count":{"description":"Number of disabled (blocked) tools","type":"integer"},"changed_count":{"description":"Number of tools whose description/schema changed since approval","type":"integer"},"pending_count":{"description":"Number of newly discovered tools awaiting approval","type":"integer"}},"type":"object"},"contracts.RefreshRegistryResponse":{"properties":{"cleared":{"description":"number of cached entries dropped","type":"integer"},"registry_id":{"type":"string"}},"type":"object"},"contracts.Registry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag (MCP-866): \"official/trusted\" for built-in\ndefaults, \"custom/unverified\" for user-added registries.","type":"string"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"trusted":{"description":"Trusted indicates whether this is an official, shipped-by-default\nregistry. Trust is derived from membership in the default set, never\nfrom self-assertion in config.","type":"boolean"},"url":{"type":"string"}},"type":"object"},"contracts.RegistryCacheInfo":{"properties":{"age_seconds":{"type":"number"},"stale":{"type":"boolean"}},"type":"object"},"contracts.RegistryUnavailable":{"properties":{"reason":{"type":"string"}},"type":"object"},"contracts.ReplayToolCallRequest":{"properties":{"arguments":{"description":"Modified arguments for replay","type":"object"}},"type":"object"},"contracts.ReplayToolCallResponse":{"properties":{"error":{"description":"Error if replay failed","type":"string"},"new_call_id":{"description":"ID of the newly created call","type":"string"},"new_tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"replayed_from":{"description":"Original call ID","type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.RepositoryInfo":{"description":"Detected package info","properties":{"npm":{"$ref":"#/components/schemas/contracts.NPMPackageInfo"}},"type":"object"},"contracts.RepositoryServer":{"properties":{"connect_url":{"description":"Alternative connection URL","type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"install_cmd":{"description":"Installation command","type":"string"},"name":{"type":"string"},"registry":{"description":"Which registry this came from","type":"string"},"repository_info":{"$ref":"#/components/schemas/contracts.RepositoryInfo"},"source_code_url":{"description":"Source repository URL","type":"string"},"updated_at":{"type":"string"},"url":{"description":"MCP endpoint for remote servers only","type":"string"}},"type":"object"},"contracts.SearchRegistryServersResponse":{"properties":{"cache":{"$ref":"#/components/schemas/contracts.RegistryCacheInfo"},"query":{"type":"string"},"registry_id":{"type":"string"},"servers":{"items":{"$ref":"#/components/schemas/contracts.RepositoryServer"},"type":"array","uniqueItems":false},"tag":{"type":"string"},"total":{"type":"integer"},"unavailable":{"$ref":"#/components/schemas/contracts.RegistryUnavailable"}},"type":"object"},"contracts.SearchResult":{"properties":{"matches":{"type":"integer"},"score":{"type":"number"},"snippet":{"type":"string"},"tool":{"$ref":"#/components/schemas/contracts.Tool"}},"type":"object"},"contracts.SearchToolsResponse":{"properties":{"query":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/contracts.SearchResult"},"type":"array","uniqueItems":false},"took":{"type":"string"},"total":{"type":"integer"}},"type":"object"},"contracts.SecurityScanSummary":{"description":"Latest security scan results summary","properties":{"deep_scan":{"$ref":"#/components/schemas/contracts.DeepScanDescriptor"},"finding_counts":{"$ref":"#/components/schemas/contracts.FindingCounts"},"last_scan_at":{"type":"string"},"risk_score":{"description":"0-100","type":"integer"},"scanners_failed":{"type":"integer"},"scanners_run":{"description":"Scanner coverage for the primary (baseline) scan pass โ€” informational only.\nSpec 077 US3 (FR-008/FR-014): Status is derived SOLELY from the\ndeterministic baseline findings; a failed Docker deep scanner no longer\ndowngrades a clean verdict. That failure is surfaced via DeepScan instead.","type":"integer"},"scanners_total":{"type":"integer"},"status":{"description":"\"clean\", \"warnings\", \"dangerous\", \"failed\", \"not_scanned\", \"scanning\"","type":"string"}},"type":"object"},"contracts.Server":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"authenticated":{"description":"OAuth authentication status","type":"boolean"},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges mirrors config.ServerConfig.AutoApproveToolChanges\n(MCP-2930): the per-server intent to auto-approve new/changed tools past\nthe trust baseline. Tri-state *bool โ€” nil means \"never set\" (omitted from\nthe payload), so the Web UI toggle (MCP-2932) can distinguish unset from\nan explicit false. Read-only on the GET path; PATCH/POST accept it via\nAddServerRequest.","type":"boolean"},"command":{"type":"string"},"connected":{"type":"boolean"},"connected_at":{"type":"string"},"connecting":{"type":"boolean"},"created":{"type":"string"},"diagnostic":{"$ref":"#/components/schemas/contracts.Diagnostic"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"error_code":{"type":"string"},"expose_prompts":{"description":"ExposePrompts mirrors config.ServerConfig.ExposePrompts (F9): the per-server\nprompt-aggregation override. Tri-state *bool โ€” nil/omitted means \"inherit\ndefault aggregation\". Surfaced on GET so a caller that PATCHed the override\ncan read it back; PATCH/POST accept it via AddServerRequest.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"health":{"$ref":"#/components/schemas/contracts.HealthStatus"},"id":{"type":"string"},"init_timeout":{"description":"InitTimeout mirrors config.ServerConfig.InitTimeout (MCP-3322 / GH #760):\nthe per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override. Serialized as\na duration string (e.g. \"120s\"); nil/omitted means \"inherit the global\ndefault\". Surfaced on the GET path so clients can read back a configured\noverride; PATCH/POST accept it via AddServerRequest.","type":"string"},"isolation":{"$ref":"#/components/schemas/contracts.IsolationConfig"},"isolation_defaults":{"$ref":"#/components/schemas/contracts.IsolationDefaults"},"last_error":{"type":"string"},"last_reconnect_at":{"type":"string"},"last_retry_time":{"type":"string"},"max_concurrent_requests":{"description":"Spec 093 (GH #955) โ€” per-server concurrency overrides, scope (c) of\nFR-020. Each setting is tri-state: nil (omitted) means \"inherit\nserver_concurrency_defaults\", 0 disables that setting for this server,\npositive overrides it. Surfaced on the GET path so a caller can read back\nwhat it set; PATCH/POST accept them via AddServerRequest. The effective\nconcurrency for a server is additionally bounded by the global aggregate\nlimiter, which is NOT an inheritance source for these fields.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/contracts.OAuthConfig"},"oauth_status":{"description":"OAuth status: \"authenticated\", \"expired\", \"error\", \"none\"","type":"string"},"protocol":{"type":"string"},"quarantine":{"$ref":"#/components/schemas/contracts.QuarantineStats"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_count":{"type":"integer"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets this disconnected server","type":"boolean"},"retry_count":{"type":"integer"},"security_scan":{"$ref":"#/components/schemas/contracts.SecurityScanSummary"},"should_retry":{"type":"boolean"},"source_registry_id":{"description":"MCP-901 โ€” registry provenance of an upstream that was added from a\nregistry. SourceRegistryID names the source registry (empty for\nmanually-configured servers); SourceRegistryProvenance is the trust tag\nrecorded at add time (\"official/trusted\" or \"custom/unverified\"). Both\nare projected from config.ServerConfig so the approval/quarantine view\ncan render an \"added from \u003cregistry\u003e ยท unverified\" origin badge. Optional\nand omitted when empty โ€” clients that pre-date this treat them as absent.","type":"string"},"source_registry_provenance":{"type":"string"},"status":{"type":"string"},"token_expires_at":{"description":"When the OAuth token expires (ISO 8601)","type":"string"},"tool_count":{"type":"integer"},"tool_list_token_size":{"description":"Token size for this server's tools","type":"integer"},"trust_mode":{"description":"TrustMode mirrors config.ServerConfig.TrustMode (spec 086): the per-server\ntrust tier (\"auto\"/\"scan\"/\"manual\"). Surfaced on the GET path so clients can\nread back the persisted mode; PATCH/POST accept it via AddServerRequest.\nOmitted when empty (server predates the field / relies on legacy flags).","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"user_logged_out":{"description":"True if user explicitly logged out (prevents auto-reconnection)","type":"boolean"},"working_dir":{"type":"string"}},"type":"object"},"contracts.ServerActionResponse":{"properties":{"action":{"type":"string"},"async":{"type":"boolean"},"server":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ServerStats":{"properties":{"connected_servers":{"type":"integer"},"docker_containers":{"type":"integer"},"quarantined_servers":{"type":"integer"},"token_metrics":{"$ref":"#/components/schemas/contracts.ServerTokenMetrics"},"total_servers":{"type":"integer"},"total_tools":{"type":"integer"}},"type":"object"},"contracts.ServerTokenMetrics":{"properties":{"average_query_result_size":{"description":"Typical retrieve_tools output (tokens)","type":"integer"},"per_server_tool_list_sizes":{"additionalProperties":{"type":"integer"},"description":"Token size per server","type":"object"},"saved_tokens":{"description":"Difference","type":"integer"},"saved_tokens_percentage":{"description":"Percentage saved","type":"number"},"total_server_tool_list_size":{"description":"All upstream tools combined (tokens)","type":"integer"}},"type":"object"},"contracts.SuccessResponse":{"properties":{"data":{"type":"object"},"success":{"type":"boolean"}},"type":"object"},"contracts.TokenMetrics":{"description":"Token usage metrics (nil for older records)","properties":{"encoding":{"description":"Encoding used (e.g., cl100k_base)","type":"string"},"estimated_cost":{"description":"Optional cost estimate","type":"number"},"input_tokens":{"description":"Tokens in the request","type":"integer"},"model":{"description":"Model used for tokenization","type":"string"},"output_tokens":{"description":"Tokens in the response","type":"integer"},"total_tokens":{"description":"Total tokens (input + output)","type":"integer"},"truncated_tokens":{"description":"Tokens removed by truncation","type":"integer"},"was_truncated":{"description":"Whether response was truncated","type":"boolean"}},"type":"object"},"contracts.Tool":{"properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"approval_status":{"type":"string"},"config_denied":{"description":"ConfigDenied is true when the tool is denied by the server's static\nenabled_tools / disabled_tools config. The user cannot override this toggle.","type":"boolean"},"description":{"type":"string"},"disabled":{"description":"Disabled mirrors ToolApprovalRecord.Disabled so per-tool enable state is\navailable without a second round-trip to the approvals endpoint. Absent\nin the JSON when false (default) to keep responses compact.","type":"boolean"},"hash":{"description":"Hash is the tool's current stored hash rendered in the preflight pin\nformat \"sha256/v{N}:{hex}\" (Spec 098 FR-011), where N is the approval\nrecord's HashSchemaVersion. It is the authoring surface for\n` + "`" + `POST /api/v1/preflight` + "`" + ` pins and ` + "`" + `mcpproxy tools preflight --pin` + "`" + `:\ncopy the value straight into a pin.\n\nDisclosure is OPERATOR TIER ONLY โ€” same rule as the preflight per-tool\nresult. The field is omitted for agent-token callers and for tools with\nno stored hash (no approval record yet, or a record written before\nhashes existed).","type":"string"},"held_reason":{"description":"HeldReason, HeldVerdict and HeldSignals mirror the same-named fields on\nstorage.ToolApprovalRecord: the offline-scan evidence that made\ntrust_mode: scan hold this tool for review (spec 086 FR-018). HeldSignals\nnames the matched deterministic check ids, e.g.\n\"tpa.TPA-2026-0001.hidden_instruction\", so a reviewer can see WHY the tool\nis held. All three are omitted for tools that are not held by the scan gate\n(including every record written before the field existed).","type":"string"},"held_signals":{"items":{"type":"string"},"type":"array","uniqueItems":false},"held_verdict":{"type":"string"},"last_used":{"type":"string"},"name":{"type":"string"},"schema":{"type":"object"},"server_name":{"type":"string"},"usage":{"type":"integer"}},"type":"object"},"contracts.ToolAnnotation":{"description":"Tool behavior hints snapshot","properties":{"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"},"readOnlyHint":{"type":"boolean"},"title":{"type":"string"}},"type":"object"},"contracts.ToolCallRecord":{"description":"The new tool call record","properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"arguments":{"description":"Tool arguments","type":"object"},"config_path":{"description":"Active config file path","type":"string"},"duration":{"description":"Duration in nanoseconds","type":"integer"},"error":{"description":"Error message (failure only)","type":"string"},"execution_type":{"description":"\"direct\" or \"code_execution\"","type":"string"},"id":{"description":"Unique identifier","type":"string"},"mcp_client_name":{"description":"MCP client name from InitializeRequest","type":"string"},"mcp_client_version":{"description":"MCP client version","type":"string"},"mcp_session_id":{"description":"MCP session identifier","type":"string"},"metrics":{"$ref":"#/components/schemas/contracts.TokenMetrics"},"parent_call_id":{"description":"Links nested calls to parent code_execution","type":"string"},"request_id":{"description":"Request correlation ID","type":"string"},"response":{"description":"Tool response (success only)","type":"object"},"server_id":{"description":"Server identity hash","type":"string"},"server_name":{"description":"Human-readable server name","type":"string"},"timestamp":{"description":"When the call was made","type":"string"},"tool_name":{"description":"Tool name (without server prefix)","type":"string"}},"type":"object"},"contracts.UpdateInfo":{"description":"Update information (if available)","properties":{"available":{"description":"Whether an update is available","type":"boolean"},"behind_summary":{"description":"Spec 079 FR-002 โ€” how far behind the running build is. All four are\nadditive (FR-021) and absent when the delta could not be resolved, in\nwhich case every surface renders its pre-delta wording.","type":"string"},"check_error":{"description":"Error message if update check failed","type":"string"},"checked_at":{"description":"When the update check was performed","type":"string"},"install_channel":{"description":"Detected install channel (homebrew, dmg, deb, rpm, docker, go-install, windows-installer, tarball, unknown) โ€” Spec 079 FR-008","type":"string"},"is_prerelease":{"description":"Whether the latest version is a prerelease","type":"boolean"},"latest_version":{"description":"Latest version available (e.g., \"v1.2.3\")","type":"string"},"nudges_suppressed":{"description":"UI surfaces must stay quiet (CI / non-interactive context); machine-readable fields still report the facts โ€” Spec 079 FR-019","type":"boolean"},"release_url":{"description":"URL to the release page","type":"string"},"releases_behind":{"description":"Releases on the offered channel between the running and offered versions","type":"integer"},"releases_behind_saturated":{"description":"ReleasesBehind is a lower bound: the running build predates the scanned release window","type":"boolean"},"update_command":{"description":"One-line update command for the channel; only set when an update is available and the channel has one โ€” Spec 079 FR-009","type":"string"},"weeks_behind":{"description":"Whole weeks between the two releases' publish dates; 0 is a real value, absent means unknown","type":"integer"}},"type":"object"},"contracts.UpdatePolicy":{"description":"UpdatePolicy is the effective, hot-reloadable update policy (Spec 092\nFR-015). Always present: the ` + "`" + `update` + "`" + ` object above is omitted both when\nupdate checking is disabled AND when no check has produced a result\nyet, so its absence cannot tell a client whether it is allowed to run\nits own (e.g. Sparkle feed) check. This field states the answer.","properties":{"channel":{"description":"Channel is the tracked release channel: \"stable\" or \"rc\".","type":"string"},"enabled":{"description":"Enabled is the effective automatic-check kill switch: update_check.enabled\nwith MCPPROXY_DISABLE_AUTO_UPDATE=true winning over it. A user-initiated\n\"Check for Updates\" stays available regardless.","type":"boolean"},"nudges_suppressed":{"description":"NudgesSuppressed asks UI surfaces to stay quiet (CI / non-interactive)\nwhile machine-readable fields keep reporting the facts.","type":"boolean"}},"type":"object"},"contracts.UpstreamError":{"properties":{"error_message":{"type":"string"},"server_name":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.UsageAggregateResponse":{"properties":{"freshness_ms":{"description":"age of the underlying snapshot in ms","type":"integer"},"generated_at":{"type":"string"},"other":{"$ref":"#/components/schemas/contracts.UsageOtherBucket"},"timeline":{"items":{"$ref":"#/components/schemas/contracts.UsageTimeBucket"},"type":"array","uniqueItems":false},"token_source":{"description":"\"bytes\" (size-based proxy, FR-006)","type":"string"},"tokens_saved":{"description":"echoed from ServerTokenMetrics (FR-007)","type":"integer"},"tokens_saved_percentage":{"type":"number"},"tools":{"items":{"$ref":"#/components/schemas/contracts.UsageToolStat"},"type":"array","uniqueItems":false},"total_calls":{"description":"TotalCalls and TotalErrors are the headline counts for the window: the sum\nof the timeline this same response carries, so the tiles and the histogram\nunder them cannot disagree. They are NOT the sum of Tools โ€” that list is\nlifetime-cumulative, upstream-only and truncated to top-N, and summing it\nclient-side is what made the Usage tab print a third number for the same\n24 hours (audit finding F1, #1046). The population is\nstorage.CountsAsCall, shared with ActivitySummaryResponse.CallCount.\n\nTwo bounds on how exactly this matches the Activity Log's own count.\nBoth are bounded and disclosed, unlike the population mismatch they\nreplace, which was unbounded and silent:\n\n - Window granularity is the timeline's: whole hour buckets, so the span\n is the requested window rounded up to a bucket edge.\n - This response is served from a snapshot behind a short read cache\n (observability.usage_cache_ttl, 5s by default) so the endpoint never\n scans the activity log per request, while the summary endpoint counts\n live. Calls that land inside that window appear on the Activity Log\n first. FreshnessMs and GeneratedAt say how old the figures are, and\n the Usage tab prints it (\"Updated 3s ago\").","type":"integer"},"total_errors":{"type":"integer"},"window":{"type":"string"}},"type":"object"},"contracts.UsageOtherBucket":{"description":"present only when the list was truncated to top-N","properties":{"calls":{"type":"integer"},"tools_folded":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageTimeBucket":{"properties":{"calls":{"type":"integer"},"errors":{"type":"integer"},"start":{"type":"string"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageToolStat":{"properties":{"avg_req_bytes":{"description":"null when no sized request calls","type":"integer"},"avg_resp_bytes":{"description":"null when sized_calls == 0 (only legacy 0-byte calls)","type":"integer"},"blocked":{"type":"integer"},"calls":{"type":"integer"},"error_rate":{"type":"number"},"errors":{"type":"integer"},"last_used":{"type":"string"},"p50_exceeds":{"type":"boolean"},"p50_ms":{"description":"P50Ms and P95Ms are read off a fixed latency histogram, so they are BUCKET\nBOUNDS, not measured durations: the true percentile is at or below the\nvalue, and a client must render it as a bound (\"โ‰ค 5 ms\"). P50Exceeds /\nP95Exceeds flip that reading for the unbounded overflow bucket, where the\nvalue is the last bound and the truth is above it (\"\u003e 10 s\").","type":"integer"},"p95_exceeds":{"type":"boolean"},"p95_ms":{"type":"integer"},"rejected":{"description":"spec 093: shed by a concurrency limit; never executed, so excluded from calls/latency","type":"integer"},"server":{"type":"string"},"sized_calls":{"description":"calls with known response size (basis for avg_resp_bytes)","type":"integer"},"tool":{"type":"string"},"total_req_bytes":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.ValidateConfigResponse":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false},"valid":{"type":"boolean"}},"type":"object"},"contracts.ValidationError":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"data":{"properties":{"data":{"$ref":"#/components/schemas/contracts.InfoResponse"}},"type":"object"},"httpapi.AddServerRequest":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve\nnew/changed tools past the trust baseline (MCP-2930). Tri-state *bool:\na nil pointer means \"leave unchanged\" on PATCH; a present value\n(including false) is applied. Mirrors config.ServerConfig's *bool\nsemantics โ€” do NOT collapse to a plain bool, or an omitted field would\nsilently reset a previously-set value.","type":"boolean"},"command":{"type":"string"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts is the per-server override for prompt aggregation (F9):\nwhether this server's advertised MCP prompts are merged into mcpproxy's\nprompts/list. Tri-state *bool mirroring config.ServerConfig.ExposePrompts โ€”\na nil pointer means \"leave unchanged\" on PATCH (and \"inherit the default\naggregate behavior\" on create); a present value (including false) is applied.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"init_timeout":{"description":"InitTimeout is the per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override\n(MCP-3322 / GH #760), serialized as a duration string (e.g. \"120s\"). A nil\npointer means \"leave unchanged\" on PATCH; a present value is applied.\nMirrors config.ServerConfig.InitTimeout's *Duration tri-state.","type":"string"},"isolation":{"$ref":"#/components/schemas/httpapi.IsolationRequest"},"max_concurrent_requests":{"description":"MaxConcurrentRequests / QueueSize / QueueTimeout are the per-server\nconcurrency overrides (spec 093 / GH #955, FR-020 scope (c)). Each is\ntri-state: a nil pointer means \"leave unchanged\" on PATCH and \"inherit\nserver_concurrency_defaults\" on create; an explicit 0 disables that\nsetting for this server; a positive value overrides it. Do NOT collapse\nthem to plain values โ€” an omitted field would then silently reset a\nconfigured limit.","type":"integer"},"name":{"type":"string"},"protocol":{"type":"string"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"type":"boolean"},"trust_mode":{"description":"TrustMode is the per-server trust tier (spec 086): \"auto\", \"scan\", or\n\"manual\". Empty means \"leave unchanged\" on PATCH (and inherit the migrated\ndefault on create). A non-empty value is applied to ServerConfig.TrustMode\nand resolved by EffectiveTrustMode (an unrecognized value fails closed to\nmanual). This is the REST seam for changing the trust tier via\nPOST/PATCH /api/v1/servers.","type":"string"},"url":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.CanonicalConfigPath":{"properties":{"description":{"description":"Brief description","type":"string"},"exists":{"description":"Whether the file exists","type":"boolean"},"format":{"description":"Format identifier (e.g., \"claude_desktop\")","type":"string"},"name":{"description":"Display name (e.g., \"Claude Desktop\")","type":"string"},"os":{"description":"Operating system (darwin, windows, linux)","type":"string"},"path":{"description":"Full path to the config file","type":"string"}},"type":"object"},"httpapi.CanonicalConfigPathsResponse":{"properties":{"os":{"description":"Current operating system","type":"string"},"paths":{"description":"List of canonical config paths","items":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPath"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ConnectConflictResponse":{"properties":{"action":{"description":"already_exists | precondition_failed","type":"string"},"data":{"$ref":"#/components/schemas/connect.ConnectResult"},"error":{"description":"Human-readable message","type":"string"},"success":{"description":"Always false","type":"boolean"}},"type":"object"},"httpapi.ConnectRequest":{"properties":{"force":{"description":"Overwrite existing entry","type":"boolean"},"precondition_token":{"description":"PreconditionToken is the opaque token from the preview this write was\nconfirmed against (Spec 091 FR-005). When present, the core rechecks it\nat write time and responds 409 with action \"precondition_failed\" โ€”\nwriting nothing โ€” if the config or the entry MCPProxy would write has\ndrifted since; the caller then re-previews instead of retrying. Absent\nmeans exactly the pre-091 behavior. A replace-classified flow sends this\nTOGETHER with force=true: the token, not the absence of force, is the\noverwrite safety.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.ImportFromPathRequest":{"properties":{"format":{"description":"Optional format hint","type":"string"},"path":{"description":"File path to import from","type":"string"},"rename":{"additionalProperties":{"type":"string"},"description":"Rename maps a server name โ†’ new name. Applied after parsing so the\ncaller can disambiguate cross-source name collisions (Spec 046 v2 โ€”\ne.g. \"mcpproxy\" โ†’ \"mcpproxy_claude_code\"). Keys are matched against\neither the raw source name (OriginalName) or the sanitized name shown\nin the preview (Server.Name); these differ for names that need\nsanitizing (e.g. \"Figma Desktop\" โ†’ \"Figma_Desktop\"). Keys not present\nin the imported set are ignored.","type":"object"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportRequest":{"properties":{"content":{"description":"Raw JSON or TOML content","type":"string"},"format":{"description":"Optional format hint","type":"string"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportResponse":{"properties":{"failed":{"items":{"$ref":"#/components/schemas/configimport.FailedServer"},"type":"array","uniqueItems":false},"format":{"type":"string"},"format_name":{"type":"string"},"imported":{"items":{"$ref":"#/components/schemas/httpapi.ImportedServerResponse"},"type":"array","uniqueItems":false},"skipped":{"items":{"$ref":"#/components/schemas/configimport.SkippedServer"},"type":"array","uniqueItems":false},"summary":{"$ref":"#/components/schemas/configimport.ImportSummary"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportedServerResponse":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"command":{"type":"string"},"fields_skipped":{"items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"type":"string"},"original_name":{"type":"string"},"protocol":{"type":"string"},"source_format":{"type":"string"},"url":{"type":"string"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.IsolationRequest":{"description":"Isolation carries per-server Docker isolation overrides (image,\nnetwork_mode, extra_args, working_dir, enabled). A nil pointer\nmeans \"do not touch isolation config\"; an empty-but-present\nobject on PATCH intentionally clears the overrides.","properties":{"enabled":{"type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"network_mode":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.OnboardingMarkRequest":{"properties":{"connect_step_status":{"description":"ConnectStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value. The stored enum is wider (Spec 080\nFR-001): a \"skipped\" request for a previously untouched connect step\nis upgraded server-side to \"completed_external\" when the install\nshows positive evidence of an external connection (Spec 080 FR-002).\n\"completed_external\" is NOT accepted from clients โ€” it must never be\npersisted without that server-verified evidence (edge case: \"never\nguess completed_external without positive evidence\").","type":"string"},"engaged":{"description":"Engaged marks the wizard as engaged (completed or explicitly skipped).\nOnce true, the wizard does not auto-show again.","type":"boolean"},"mark_shown":{"description":"MarkShown records the wizard's first display time if not already set.","type":"boolean"},"server_step_status":{"description":"ServerStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value.","type":"string"}},"type":"object"},"httpapi.SetActiveProfileRequest":{"properties":{"active_profile":{"type":"string"},"profile":{"type":"string"}},"type":"object"},"httpapi.UndoConnectRequest":{"properties":{"backup_name":{"description":"BackupName is the bare filename (filepath.Base) of the backup returned as\nbackup_path by the preceding connect โ€” a name, never a path. Undo resolves\nthe full path server-side by joining it with the client's own config\ndirectory, so a client-supplied value can never contribute a directory\ncomponent (traversal is impossible by construction). Empty means the\nconnect created the file (no prior file existed), so undo removes it.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.UpdateFailureRequest":{"properties":{"stage":{"description":"Stage is the failure stage of the update session.","enum":["appcast","download","install","other"],"type":"string"}},"type":"object"},"management.BulkOperationResult":{"properties":{"errors":{"additionalProperties":{"type":"string"},"description":"Map of server name to error message","type":"object"},"failed":{"description":"Number of failed operations","type":"integer"},"successful":{"description":"Number of successful operations","type":"integer"},"total":{"description":"Total servers processed","type":"integer"}},"type":"object"},"observability.HealthResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"observability.HealthStatus":{"properties":{"error":{"type":"string"},"latency":{"type":"string"},"name":{"type":"string"},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"}},"type":"object"},"observability.ReadinessResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"ready\" or \"not_ready\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"secureenv.EnvConfig":{"description":"Environment configuration for secure variable filtering","properties":{"allowed_system_vars":{"items":{"type":"string"},"type":"array","uniqueItems":false},"custom_vars":{"additionalProperties":{"type":"string"},"type":"object"},"enhance_path":{"description":"Enable PATH enhancement for Launchd scenarios","type":"boolean"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned upstream servers (MCP-2769). It is OFF by\ndefault and deliberately kept out of the AllowedSystemVars default list:\nproxy URLs frequently carry credentials (http://user:pass@proxy), so\nforwarding them to every stdio upstream is a credential-leak risk. When\nenabled, values are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"inherit_system_safe":{"type":"boolean"}},"type":"object"},"telemetry.FeedbackContext":{"properties":{"arch":{"type":"string"},"connected_server_count":{"type":"integer"},"edition":{"type":"string"},"os":{"type":"string"},"routing_mode":{"type":"string"},"server_count":{"type":"integer"},"version":{"type":"string"}},"type":"object"},"telemetry.FeedbackRequest":{"properties":{"category":{"description":"bug, feature, other","type":"string"},"context":{"$ref":"#/components/schemas/telemetry.FeedbackContext"},"email":{"type":"string"},"message":{"type":"string"}},"type":"object"},"telemetry.FeedbackResponse":{"properties":{"error":{"type":"string"},"issue_url":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"API key authentication via query parameter. Use ?apikey=your-key","in":"query","name":"apikey","type":"apiKey"}}}, "info": {"contact":{"name":"MCPProxy Support","url":"https://github.com/smart-mcp-proxy/mcpproxy-go"},"description":"{{escape .Description}}","license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"title":"{{.Title}}","version":"{{.Version}}"}, "externalDocs": {"description":"","url":""}, "paths": {"/api/v1/activity":{"get":{"description":"Returns paginated list of activity records with optional filtering","parameters":[{"description":"Filter by activity type(s), comma-separated for multiple (Spec 024)","in":"query","name":"type","schema":{"enum":["tool_call","policy_decision","quarantine_change","server_change","system_start","system_stop","internal_tool_call","config_change","preflight","prompt_get"],"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"enum":["success","error","blocked","rejected"],"type":"string"}},{"description":"Filter by intent operation type (Spec 018)","in":"query","name":"intent_type","schema":{"enum":["read","write","destructive"],"type":"string"}},{"description":"Filter by HTTP request ID for log correlation (Spec 021)","in":"query","name":"request_id","schema":{"type":"string"}},{"description":"Filter by parent call id โ€” returns the sub-calls one code_execution issued","in":"query","name":"parent_id","schema":{"type":"string"}},{"description":"Include successful call_tool_* internal tool calls (default: false, excluded to avoid duplicates)","in":"query","name":"include_call_tool","schema":{"type":"boolean"}},{"description":"Filter by sensitive data detection (true=has detections, false=no detections)","in":"query","name":"sensitive_data","schema":{"type":"boolean"}},{"description":"Filter by specific detection type (e.g., 'aws_access_key', 'credit_card')","in":"query","name":"detection_type","schema":{"type":"string"}},{"description":"Filter by severity level","in":"query","name":"severity","schema":{"enum":["critical","high","medium","low"],"type":"string"}},{"description":"Filter by agent token name (Spec 028)","in":"query","name":"agent","schema":{"type":"string"}},{"description":"Filter by auth type (Spec 028)","in":"query","name":"auth_type","schema":{"enum":["admin","agent"],"type":"string"}},{"description":"Filter activities after this time (RFC3339)","in":"query","name":"start_time","schema":{"type":"string"}},{"description":"Filter activities before this time (RFC3339)","in":"query","name":"end_time","schema":{"type":"string"}},{"description":"Maximum records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Pagination offset (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Omit arguments, response and metadata except a contextual whitelist (intent.reason, intent.operation_type, decision, reason, client_name, client_version) (default: false). For clients that render summary fields only; has_sensitive_data is still derived before metadata is dropped.","in":"query","name":"exclude_payloads","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"List activity records","tags":["Activity"]}},"/api/v1/activity/export":{"get":{"description":"Exports activity records in JSON Lines or CSV format for compliance","parameters":[{"description":"Export format: json (default) or csv","in":"query","name":"format","schema":{"type":"string"}},{"description":"Filter by activity type","in":"query","name":"type","schema":{"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"type":"string"}},{"description":"Filter by HTTP request ID for log correlation (Spec 021)","in":"query","name":"request_id","schema":{"type":"string"}},{"description":"Filter by parent call id โ€” exports the sub-calls one code_execution issued","in":"query","name":"parent_id","schema":{"type":"string"}},{"description":"Filter activities after this time (RFC3339)","in":"query","name":"start_time","schema":{"type":"string"}},{"description":"Filter activities before this time (RFC3339)","in":"query","name":"end_time","schema":{"type":"string"}},{"description":"Maximum records to export (1-50000, default 10000)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Pagination offset (default 0)","in":"query","name":"offset","schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}}},"description":"Streamed activity records"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Export activity records","tags":["Activity"]}},"/api/v1/activity/summary":{"get":{"description":"Returns aggregated activity statistics for a time period","parameters":[{"description":"Time period: 1h, 24h (default), 7d, 30d","in":"query","name":"period","schema":{"type":"string"}},{"description":"Group by: server, tool (optional)","in":"query","name":"group_by","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity summary statistics","tags":["Activity"]}},"/api/v1/activity/usage":{"get":{"description":"Returns the actor-owned usage aggregate (per-tool rollup + timeline + tokens-saved headline) for the Web UI usage graphs (Spec 069). Served from an in-memory snapshot โ€” never a per-request full-log scan. Per-tool metrics are lifetime-cumulative; ` + "`" + `window` + "`" + ` scopes the timeline and filters the tool list to tools active within the span.","parameters":[{"description":"Time window for timeline + tool-list membership","in":"query","name":"window","schema":{"enum":["24h","7d","all"],"type":"string"}},{"description":"Filter to one server","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter to one tool","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter to tools with activity of this status","in":"query","name":"status","schema":{"enum":["success","error","blocked","rejected"],"type":"string"}},{"description":"Top-N tools by sort key; remainder folded into 'other' (default 20)","in":"query","name":"top","schema":{"type":"integer"}},{"description":"Ranking key for the per-tool list","in":"query","name":"sort","schema":{"enum":["calls","resp_bytes","error_rate","p95"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get usage statistics aggregate","tags":["Activity"]}},"/api/v1/activity/{id}":{"get":{"description":"Returns full details for a single activity record","parameters":[{"description":"Activity record ID (ULID)","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Not Found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity record details","tags":["Activity"]}},"/api/v1/annotations/coverage":{"get":{"description":"Reports how many upstream tools have MCP annotations vs don't, broken down by server","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Annotation coverage report"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get annotation coverage report","tags":["annotations"]}},"/api/v1/code/scripts":{"get":{"description":"List the stored scripts available to the code_execution tool. Scripts are ` + "`" + `\u003cname\u003e.js` + "`" + ` / ` + "`" + `\u003cname\u003e.ts` + "`" + ` files in the ` + "`" + `scripts/` + "`" + ` directory next to the active configuration file. Entries are advisory: ` + "`" + `ok` + "`" + ` scripts are invocable, ` + "`" + `ambiguous` + "`" + ` names have both extensions, and ` + "`" + `invalid` + "`" + ` ones report why (empty, oversized, unreadable, non-regular). Read-only โ€” there is no write surface for stored scripts.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Stored scripts and the directory they were read from"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List stored code-execution scripts","tags":["code"]}},"/api/v1/config":{"get":{"description":"Retrieves the current MCPProxy configuration including all server definitions, global settings, and runtime parameters","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetConfigResponse"}}},"description":"Configuration retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get current configuration","tags":["config"]},"patch":{"description":"Deep-merges only the fields present in the request body onto the live in-memory configuration and routes the result through the existing apply pipeline (validation, change detection, disk persistence, hot-reload). Fields the client omits โ€” including masked secrets such as ` + "`" + `api_key` + "`" + ` and secret request headers โ€” are preserved verbatim. Nested objects are merged recursively; arrays and scalars replace wholesale.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Partial configuration with only the fields to change","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Configuration patch applied (inspect validation_errors for rejected values)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload or empty patch"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to read or apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update configuration","tags":["config"]}},"/api/v1/config/apply":{"post":{"description":"Applies a new MCPProxy configuration. Validates and persists the configuration to disk. Some changes apply immediately, while others may require a restart. Returns detailed information about applied changes and restart requirements.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to apply","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Configuration applied successfully with change details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Apply configuration","tags":["config"]}},"/api/v1/config/docker-isolation":{"patch":{"description":"Convenience endpoint to flip ` + "`" + `docker_isolation.enabled` + "`" + ` without resending the full config. Persists to disk via the existing config writer โ€” the file watcher then hot-reloads the change. Returns the new state and whether a restart is required for existing connections to pick it up.","requestBody":{"content":{"application/json":{"schema":{"properties":{"enabled":{"type":"boolean"}},"type":"object"}}},"description":"New isolation state","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Isolation toggle applied"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Toggle global Docker isolation","tags":["config"]}},"/api/v1/config/validate":{"post":{"description":"Validates a provided MCPProxy configuration without applying it. Checks for syntax errors, invalid server definitions, conflicting settings, and other configuration issues.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to validate","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ValidateConfigResponse"}}},"description":"Configuration validation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Validation failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Validate configuration","tags":["config"]}},"/api/v1/connect":{"get":{"description":"Returns the connection status for all known MCP client applications.\nEach entry indicates whether the client config file exists and whether\nMCPProxy is currently registered in it.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"List of ClientStatus objects"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List client connection status","tags":["connect"]}},"/api/v1/connect/{client}":{"delete":{"description":"Remove the MCPProxy entry from the specified client's configuration file.\nCreates a backup of the existing config before modifying.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional parameters (server_name)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or entry not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disconnect MCPProxy from a client","tags":["connect"]},"get":{"description":"Resolves one client's status by reading its config file on demand.\nThis is the only Connect endpoint that opens a client config file, so\non macOS it is the sole place an App-Data privacy prompt may legitimately\nappear (scoped to this user action). Resolves access_state to\naccessible|absent|denied|malformed and populates remediation when denied.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ClientStatus"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get a single client's connection status (on-demand)","tags":["connect"]},"post":{"description":"Register MCPProxy as an MCP server in the specified client's configuration file.\nCreates a backup of the existing config before modifying.\nOptionally accepts precondition_token from a preview (Spec 091): when supplied,\nthe core rechecks the raw pre-write state and the entry it would write, and\nrefuses a drifted write with 409 before taking any backup. The 409 body's\naction discriminates the two conflict kinds: \"precondition_failed\" (stale\npreview โ€” re-preview, do not retry) vs \"already_exists\" (entry present โ€” pass\nforce=true). force=true never rescues a stale token.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional connection parameters (server_name, force, precondition_token)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectConflictResponse"}}},"description":"Conflict: action=already_exists (use force=true) or action=precondition_failed (preview is stale; re-preview)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Connect MCPProxy to a client","tags":["connect"]}},"/api/v1/connect/{client}/preview":{"get":{"description":"Returns the exact entry a subsequent connect would add to the client's\nconfig โ€” target path, server key, entry name, and entry contents โ€” WITHOUT\nmodifying the file or creating a backup (Spec 078 US1). The embedded API key\nis masked in the payload; contains_api_key flags that a credential is written.\nentry_exists distinguishes a create from an overwrite of a same-named entry.\nReads the config on demand to classify create-vs-overwrite, so on macOS this\nmay raise an App-Data privacy prompt; a denial returns 403 + remediation.\nSpec 091 adds three fields: existing_entry_summary (present only when\nentry_exists โ€” a sanitized, non-secret projection of the entry being replaced:\nits name, type, endpoint with query/userinfo stripped, command, and header and\nenv NAMES, never values); precondition_token (always present โ€” an opaque keyed\ndigest of the raw pre-write state and the pending entry, echoed back on POST\nconnect to detect drift); and connect_refusal (present when the write would\nrefuse regardless of intent, e.g. a non-create-capable client with no config โ€”\ntreat its presence as \"Connect unavailable\").","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}},{"description":"Entry name to preview (defaults to mcpproxy); mirror the value passed to POST connect","in":"query","name":"server_name","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectPreview"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Preview the change a connect would make (no write)","tags":["connect"]}},"/api/v1/connect/{client}/undo":{"post":{"description":"Reverts the connect that produced the named backup (Spec 078 US3):\nrestores the client config byte-for-byte from that backup, or โ€” when\nbackup_name is empty because the connect created the file โ€” deletes the\ncreated file. backup_name is the bare filename of the backup the connect\nreturned (never a path); undo resolves the full path server-side inside\nthe client's own config directory, so a client value cannot escape it.\nRefuses with 409 when the config changed since the connect (undo never\nclobbers later edits; use DELETE /connect/{client} for a surgical entry\nremoval instead). Takes its own safety backup first; its path is returned\nas backup_path in the result.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.UndoConnectRequest"}}},"description":"Undo parameters (server_name, backup_name = the bare filename of the backup the preceding connect returned)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult (action restored|deleted)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (e.g. backup_name is a path, or not a backup of this client's config)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or backup no longer exists"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Config changed since connect; undo refused"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Undo a connect, restoring the pre-connect config","tags":["connect"]}},"/api/v1/diagnostics":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/docker/status":{"get":{"description":"Retrieve current Docker availability and recovery status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Docker status information"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get Docker status","tags":["docker"]}},"/api/v1/doctor":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/feedback":{"post":{"description":"Submit a bug report, feature request, or general feedback","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackRequest"}}},"description":"Feedback request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Bad Request"},"429":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"Submit feedback","tags":["feedback"]}},"/api/v1/index/search":{"get":{"description":"Search across all upstream MCP server tools using BM25 keyword search","parameters":[{"description":"Search query","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"description":"Maximum number of results","in":"query","name":"limit","schema":{"default":10,"maximum":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchToolsResponse"}}},"description":"Search results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing query parameter)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search for tools","tags":["tools"]}},"/api/v1/info":{"get":{"description":"Get essential server metadata including version, web UI URL, endpoint addresses, and update availability\nThis endpoint is designed for tray-core communication and version checking\nUse refresh=true query parameter to force an immediate update check against GitHub\nThe launched_by field reports durable launch provenance (\"tray\", \"installer\", or \"\" for user-launched/unknown)","parameters":[{"description":"Force immediate update check against GitHub","in":"query","name":"refresh","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"Server information with optional update info"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server information","tags":["status"]}},"/api/v1/onboarding/mark":{"post":{"description":"Updates wizard engagement and per-step status. Once engaged is\ntrue, the wizard does not auto-show again, even if state regresses.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.OnboardingMarkRequest"}}},"description":"Mark request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Updated OnboardingStateResponse"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Mark onboarding wizard state (Spec 046)","tags":["onboarding"]}},"/api/v1/onboarding/state":{"get":{"description":"Returns the wizard engagement record alongside live predicates\n(whether any client is connected, whether any server is configured),\nplus a derived ShouldShowWizard flag the frontend can rely on.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"OnboardingStateResponse"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get onboarding wizard state and predicates (Spec 046)","tags":["onboarding"]}},"/api/v1/preflight":{"post":{"description":"Deterministic, side-effect-free availability check for a caller-supplied list of tool IDs (Spec 098). Performs zero upstream calls and mutates no runtime state. HTTP status reports whether the CHECK executed: a fully blocked set is still 200, with the availability verdict in the body. Every executed preflight writes an activity record before the response is returned.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.PreflightRequest"}}},"description":"Tool IDs (1-100 before dedup), optional profile, annotation policy filters and wait budget","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"Preflight verdict and per-tool results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Validation error (malformed, oversized, doubled or unknown-field body; empty or oversized tool list; conflicting duplicate pins; unknown profile; wait_ms out of range)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Missing or invalid credentials"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Runtime unavailable, evaluator infrastructure read failure, or the activity record could not be persisted"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Preflight required tools","tags":["tools"]}},"/api/v1/profiles":{"get":{"description":"List all configured profiles with their effective servers and indexed tool count (Profiles v2). A profile scopes tool discovery and calls to a named subset of upstream servers.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Profile list"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Configuration unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List configured profiles","tags":["profiles"]}},"/api/v1/profiles/active":{"get":{"description":"Get the server-level default active profile used by UI surfaces (Web UI / tray). Empty string means \"all servers\". Note: within a live MCP session, the set_profile tool selection takes precedence over this default.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get the default active profile","tags":["profiles"]},"put":{"description":"Set the server-level default active profile for UI surfaces. The slug must match a configured profile; pass an empty string to clear. This does not affect live MCP sessions, which use the set_profile tool.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.SetActiveProfileRequest"}}},"description":"Profile slug to activate (empty clears)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid request body"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Set the default active profile","tags":["profiles"]}},"/api/v1/registries":{"get":{"description":"Retrieves list of all MCP server registries that can be browsed for discovering and installing new upstream servers. Includes registry metadata, server counts, and API endpoints.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetRegistriesResponse"}}},"description":"Registries retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to list registries"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List available MCP server registries","tags":["registries"]},"post":{"description":"Adds a generic modelcontextprotocol/registry v0.1 https endpoint as a custom registry (MCP-866). The source is always tagged custom/unverified, so every server discovered through it lands quarantined and can never skip quarantine.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddRegistrySourceRequest"}}},"description":"Registry source (https url + optional protocol/id/name)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source added"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/contracts.ErrorResponse"},{"$ref":"#/components/schemas/contracts.ErrorResponse"}]}}},"description":"Forbidden (agent tokens cannot mutate registries)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin | duplicate_registry"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a user-supplied registry source","tags":["registries"]}},"/api/v1/registries/{id}":{"delete":{"description":"Removes a custom/unverified registry previously added via add-source (MCP-1057). Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source removed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove a user-added custom registry source","tags":["registries"]},"put":{"description":"Updates a custom registry previously added via add-source (MCP-1072): name, url, servers-url. Empty fields are left unchanged. Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found; a non-https url yields invalid_registry_url. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.EditRegistrySourceRequest"}}},"description":"Fields to update (name/url/servers_url; empty = unchanged)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required | invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Edit a user-added custom registry source","tags":["registries"]}},"/api/v1/registries/{id}/refresh":{"post":{"description":"Invalidates the cached server lists for a registry so the next search re-fetches fresh data from the source (spec 070 FR-007). Returns how many cache entries were dropped.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.RefreshRegistryResponse"}}},"description":"Registry cache refreshed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh registry cache"}},"summary":"Refresh a registry's cached server list","tags":["registries"]}},"/api/v1/registries/{id}/servers":{"get":{"description":"Searches for MCP servers within a specific registry by keyword or tag. Returns server metadata including installation commands, source code URLs, and npm package information for easy discovery and installation.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Search query keyword","in":"query","name":"q","schema":{"type":"string"}},{"description":"Filter by tag","in":"query","name":"tag","schema":{"type":"string"}},{"description":"Maximum number of results (default 10)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchRegistryServersResponse"}}},"description":"Servers retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to search servers"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search MCP servers in a registry","tags":["registries"]}},"/api/v1/registries/{id}/servers/{serverId}/add":{"post":{"description":"Resolves a registry server reference server-side, re-derives a validated config, and persists it quarantined (spec 070 keystone). The client never sends a config blob โ€” command/args/url and the quarantine flag are derived from the registry entry, not the request.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Server ID within the registry","in":"path","name":"serverId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddFromRegistryRequest"}}},"description":"Optional overrides (name, env, enabled)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server added (quarantined)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"no_install_info | missing_required_input | duplicate_name"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot add servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found | server_not_found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add an upstream server from a registry reference","tags":["registries"]}},"/api/v1/routing":{"get":{"description":"Get the current routing mode and available MCP endpoints.\nrouting_mode is what /mcp is actually serving; pending_routing_mode carries a\nrestart-pending value persisted on disk (empty when there is none).\ntool_response_mode and direct_tool_response_mode report the two serialization axes, resolved.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Routing mode information"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get routing mode information","tags":["status"]}},"/api/v1/secrets":{"post":{"description":"Stores a secret value in the operating system's secure keyring. The secret can then be referenced in configuration using ${keyring:secret-name} syntax. Automatically notifies runtime to restart affected servers.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret stored successfully with reference syntax"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload, missing name/value, or unsupported type"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver not available or failed to store secret"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Store a secret in OS keyring","tags":["secrets"]}},"/api/v1/secrets/{name}":{"delete":{"description":"Deletes a secret from the operating system's secure keyring. Automatically notifies runtime to restart affected servers. Only keyring type is supported for security.","parameters":[{"description":"Name of the secret to delete","in":"path","name":"name","required":true,"schema":{"type":"string"}},{"description":"Secret type (only 'keyring' supported, defaults to 'keyring')","in":"query","name":"type","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Missing secret name or unsupported type"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver not available or failed to delete secret"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Delete a secret from OS keyring","tags":["secrets"]}},"/api/v1/servers":{"get":{"description":"Get a list of all configured upstream MCP servers with their connection status and statistics","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServersResponse"}}},"description":"Server list with statistics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List all upstream MCP servers","tags":["servers"]},"post":{"description":"Add a new MCP upstream server to the configuration. New servers are quarantined by default for security.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.AddServerRequest"}}},"description":"Server configuration","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server added successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid configuration"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Conflict - server with this name already exists"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a new upstream server","tags":["servers"]}},"/api/v1/servers/disable_all":{"post":{"description":"Disable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk disable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable all servers","tags":["servers"]}},"/api/v1/servers/enable_all":{"post":{"description":"Enable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk enable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable all servers","tags":["servers"]}},"/api/v1/servers/import":{"post":{"description":"Import MCP server configurations from a Claude Desktop, Claude Code, Cursor IDE, Codex CLI, or Gemini CLI configuration file","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}},{"description":"Force format (claude-desktop, claude-code, cursor, codex, gemini)","in":"query","name":"format","schema":{"type":"string"}},{"description":"Comma-separated list of server names to import","in":"query","name":"server_names","schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"file"}}},"description":"Configuration file to import","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid file or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from uploaded configuration file","tags":["servers"]}},"/api/v1/servers/import/json":{"post":{"description":"Import MCP server configurations from raw JSON or TOML content (useful for pasting configurations)","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportRequest"}}},"description":"Import request with content","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid content or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from JSON/TOML content","tags":["servers"]}},"/api/v1/servers/import/path":{"post":{"description":"Import MCP server configurations by reading a file from the server's filesystem","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportFromPathRequest"}}},"description":"Import request with file path","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid path or format"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"File not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from a file path","tags":["servers"]}},"/api/v1/servers/import/paths":{"get":{"description":"Returns well-known configuration file paths for supported formats with existence check","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPathsResponse"}}},"description":"Canonical config paths"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get canonical config file paths","tags":["servers"]}},"/api/v1/servers/reconnect":{"post":{"description":"Force reconnection to all upstream MCP servers","parameters":[{"description":"Reason for reconnection","in":"query","name":"reason","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"All servers reconnected successfully"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Reconnect all servers","tags":["servers"]}},"/api/v1/servers/restart_all":{"post":{"description":"Restart all configured upstream MCP servers sequentially with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk restart results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart all servers","tags":["servers"]}},"/api/v1/servers/{id}":{"delete":{"description":"Remove an MCP upstream server from the configuration. This stops the server if running and removes it from config.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server removed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove an upstream server","tags":["servers"]},"patch":{"description":"Update specific fields of an existing upstream MCP server configuration.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.AddServerRequest"}}},"description":"Fields to update (all optional)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server updated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - no fields or invalid body"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/config-to-secret":{"post":{"description":"Atomically reads the real value from the server config, stores it in the OS keyring, and rewrites the config field to ` + "`" + `${keyring:\u003cname\u003e}` + "`" + `. Unblocks the UI's Convert-to-secret affordance for values the API redacts on the read path.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret stored, config updated with reference"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad scope/key/secret_name, or value is already a reference / empty"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server or key not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver or config update failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Convert a header / env value to a keyring secret","tags":["servers"]}},"/api/v1/servers/{id}/disable":{"post":{"description":"Disable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server disabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/discover-tools":{"post":{"description":"Manually trigger tool discovery and indexing for a specific upstream MCP server. This forces an immediate refresh of the server's tool cache.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool discovery triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot discover tools)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to discover tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Discover tools for a specific server","tags":["servers"]}},"/api/v1/servers/{id}/enable":{"post":{"description":"Enable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server enabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/login":{"post":{"description":"Initiate OAuth authentication flow for a specific upstream MCP server. Returns structured OAuth start response with correlation ID for tracking.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthStartResponse"}}},"description":"OAuth login initiated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthFlowError"}}},"description":"OAuth error (client_id required, DCR failed, etc.)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Trigger OAuth login for server","tags":["servers"]}},"/api/v1/servers/{id}/logout":{"post":{"description":"Clear OAuth authentication token and disconnect a specific upstream MCP server. The server will need to re-authenticate before tools can be used again.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"OAuth logout completed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled or read-only mode)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Clear OAuth token and disconnect server","tags":["servers"]}},"/api/v1/servers/{id}/logs":{"get":{"description":"Retrieve log entries for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Number of log lines to retrieve","in":"query","name":"tail","schema":{"default":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerLogsResponse"}}},"description":"Server logs retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server logs","tags":["servers"]}},"/api/v1/servers/{id}/quarantine":{"post":{"description":"Place a specific upstream MCP server in quarantine to prevent tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server quarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Quarantine a server","tags":["servers"]}},"/api/v1/servers/{id}/refresh":{"post":{"description":"Re-discover and re-index a specific upstream MCP server's tools without changing any security state. Alias of discover-tools, named for the upstream_servers 'refresh' operation; use it to make just-approved tools searchable immediately.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool refresh triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot refresh)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Refresh a server's tools","tags":["servers"]}},"/api/v1/servers/{id}/restart":{"post":{"description":"Restart the connection to a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server restarted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/tool-calls":{"get":{"description":"Retrieves tool call history filtered by upstream server ID. Returns recent tool executions for the specified server including timestamps, arguments, results, and errors. Useful for server-specific debugging and monitoring.","parameters":[{"description":"Upstream server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Maximum number of records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolCallsResponse"}}},"description":"Server tool calls retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get server tool calls"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call history for specific server","tags":["tool-calls"]}},"/api/v1/servers/{id}/tools":{"get":{"description":"Retrieve all available tools for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolsResponse"}}},"description":"Server tools retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/block":{"post":{"description":"Atomically approves AND disables the given tools (or all pending/changed tools when block_all=true) for a server. The approve and disable land in a single write per tool, so a tool is never left in the approved+enabled state. The \"blocked\" field counts tools actually blocked.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Block result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Block (approve+disable) tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/disable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/enable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/unquarantine":{"post":{"description":"Remove a specific upstream MCP server from quarantine to allow tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server unquarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Unquarantine a server","tags":["servers"]}},"/api/v1/sessions":{"get":{"description":"Retrieves paginated list of active and recent MCP client sessions. Each session represents a connection from an MCP client to MCPProxy, tracking initialization time, tool calls, and connection status.","parameters":[{"description":"Maximum number of sessions to return (1-100, default 10)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Number of sessions to skip for pagination (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Filter by session status","in":"query","name":"status","schema":{"enum":["active","closed"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionsResponse"}}},"description":"Sessions retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid status filter"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get sessions"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get active MCP sessions","tags":["sessions"]}},"/api/v1/sessions/{id}":{"get":{"description":"Retrieves detailed information about a specific MCP client session including initialization parameters, connection status, tool call count, and activity timestamps.","parameters":[{"description":"Session ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionDetailResponse"}}},"description":"Session details retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Session ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Session not found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get MCP session details by ID","tags":["sessions"]}},"/api/v1/stats/tokens":{"get":{"description":"Retrieve token savings statistics across all servers and sessions","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Token statistics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get token savings statistics","tags":["stats"]}},"/api/v1/status":{"get":{"description":"Get comprehensive server status including running state, listen address, upstream statistics, and timestamp","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server status information"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server status","tags":["status"]}},"/api/v1/telemetry/payload":{"get":{"description":"Render the exact JSON heartbeat payload that mcpproxy would next send to the telemetry endpoint, without making a network call. Counters in the payload reflect the current in-memory state. Spec 042.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Telemetry heartbeat payload"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Telemetry service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Preview next telemetry heartbeat payload","tags":["telemetry"]}},"/api/v1/telemetry/update-failure":{"post":{"description":"Records one terminal update-session failure, identified only by its\nstage (appcast, download, install, other). The body carries no error\ntext, URL, or version โ€” the stage is the only value transmitted.\nReturns 204 both when the occurrence was durably persisted and when\ntelemetry is inactive at event time (config opt-out, environment\nopt-out, CI, or dev build), in which case nothing is recorded.\nCallers cannot and need not distinguish the two.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.UpdateFailureRequest"}}},"description":"Update failure stage","required":true},"responses":{"204":{"description":"Accepted (recorded, or a deliberate no-op while telemetry is inactive)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Malformed body, unknown field, trailing value, or stage outside the closed set"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Persistence failure"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Record a desktop auto-update failure occurrence (Spec 095)","tags":["telemetry"]}},"/api/v1/tool-calls":{"get":{"description":"Retrieves paginated tool call history across all upstream servers or filtered by session ID. Includes execution timestamps, arguments, results, and error information for debugging and auditing.","parameters":[{"description":"Maximum number of records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Number of records to skip for pagination (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Filter tool calls by MCP session ID","in":"query","name":"session_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetToolCallsResponse"}}},"description":"Tool calls retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get tool calls"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call history","tags":["tool-calls"]}},"/api/v1/tool-calls/{id}":{"get":{"description":"Retrieves detailed information about a specific tool call execution including full request arguments, response data, execution time, and any errors encountered.","parameters":[{"description":"Tool call ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetToolCallDetailResponse"}}},"description":"Tool call details retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call not found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call details by ID","tags":["tool-calls"]}},"/api/v1/tool-calls/{id}/replay":{"post":{"description":"Re-executes a previous tool call with optional modified arguments. Useful for debugging and testing tool behavior with different inputs. Creates a new tool call record linked to the original.","parameters":[{"description":"Original tool call ID to replay","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ReplayToolCallRequest"}}},"description":"Optional modified arguments for replay"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ReplayToolCallResponse"}}},"description":"Tool call replayed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call ID required or invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Shed by a concurrency limit (Retry-After header carries the wait hint)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to replay tool call"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Replay a tool call","tags":["tool-calls"]}},"/api/v1/tools":{"get":{"description":"Consolidated, read-only listing of all tools from every configured server (including disabled servers and disabled/config-denied tools), enriched with approval state and 30-day usage. Backs the global Tools page and the CLI global ` + "`" + `tools list` + "`" + ` (spec 050, issue #437).","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GlobalToolsResponse"}}},"description":"All tools across all servers"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Could not enumerate servers"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List every tool across all servers","tags":["tools"]}},"/api/v1/tools/call":{"post":{"description":"Execute a tool on an upstream MCP server (wrapper around MCP tool calls)","requestBody":{"content":{"application/json":{"schema":{"properties":{"arguments":{"type":"object"},"tool_name":{"type":"string"}},"type":"object"}}},"description":"Tool call request with tool name and arguments","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Tool call result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (invalid payload or missing tool name)"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Shed by a concurrency limit (Retry-After header carries the wait hint)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error or tool execution failure"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Call a tool","tags":["tools"]}},"/healthz":{"get":{"description":"Get comprehensive health status including all component health (Kubernetes-compatible liveness probe)","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.HealthResponse"}}},"description":"Service is healthy"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.HealthResponse"}}},"description":"Service is unhealthy"}},"summary":"Get health status","tags":["health"]}},"/readyz":{"get":{"description":"Get readiness status including all component readiness checks (Kubernetes-compatible readiness probe)","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.ReadinessResponse"}}},"description":"Service is ready"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.ReadinessResponse"}}},"description":"Service is not ready"}},"summary":"Get readiness status","tags":["health"]}}}, diff --git a/oas/swagger.yaml b/oas/swagger.yaml index 2232645e8..943b84f39 100644 --- a/oas/swagger.yaml +++ b/oas/swagger.yaml @@ -1289,12 +1289,29 @@ components: description: Correlation id of the parent call (the code_execution whose sandbox issued this sub-call) type: string + request_bytes: + description: |- + Byte sizes measured pre-truncation, mirroring storage.ActivityRecord + (Spec 069 A1). They are the only cost signal a bodies-off export carries: + with payloads suppressed there is no text left to measure, so a consumer + accounting for a record it cannot read has nothing else to go on. They are + byte LENGTHS, not token counts โ€” the basis for an explicit estimate, never + a measured figure (spec 103, contracts/replay-input.md). + + Zero means UNKNOWN, not free: legacy records predate the measurement and + code-execution sub-calls record both as zero. Hence omitempty โ€” an absent + key tells a consumer to fall to exclusion accounting, whereas a present + zero would read as a costless call and silently understate the workload. + type: integer request_id: description: HTTP request ID for correlation type: string response: description: Tool response (potentially truncated) type: string + response_bytes: + description: Raw upstream response size in bytes before truncation + type: integer response_truncated: description: True if response was truncated type: boolean diff --git a/roadmap.yaml b/roadmap.yaml index 182477ccf..cd755268a 100644 --- a/roadmap.yaml +++ b/roadmap.yaml @@ -389,15 +389,17 @@ epics: - id: token-bench title: "Token-efficiency benchmark: measured savings, published results" - status: todo + status: in_progress priority: P1 spec: specs/103-token-bench + pr: "#1141" depends_on: [schema-deferred] note: "Measure the real token cost of every routing/savings mode combination โ€” baseline, compact signatures (spec 085), deferred schemas (spec 102), optimistic calling via self-healing pre-dispatch validation, code_execution (spec 096) and stored scripts (spec 097) โ€” on replayed real sessions and on public benchmarks, then publish the results on mcpproxy.app/blog. Every savings number we quote today is an estimate; this turns them into reproducible measurements. Sequenced after schema-deferred so the newest mode is in the matrix. Spec 103 landed 2026-08-31 (#1137 spec+plan, #1139 tasks) after 13 cross-model review rounds; three of its findings changed the design rather than the wording: a recording carries no prompt/conversation/completion oracle so replay CANNOT show agent behaviour (US1 deterministic cost vs US2 live loop are now separate stories); replay needs a FLEET INPUT because the export has no fleet snapshot; and bodies-off yields menu costs plus one cross-mode delta, never an absolute workload cost. The matrix is 5 distinct behaviours, not a 3x2x2 product." tasks: - id: token-bench-harness title: "Replay harness: activity-log sessions re-run under each mode combo; tokens per completed task + first-call success + retries" - status: todo + status: in_progress + pr: "#1141" depends_on: [] note: "BUILDS ON the existing bench/ harness - do NOT rebuild token counting, encoding arms, break-even or recall. Already shipped there (PRs #747/#748 MCP-42, #851 spec 083): six encoding arms including direct_deferred (spec 102), cl100k_base counting, live response cost, break-even, RecallAtK/NDCGAtK, the v2 report + dashboard, `make bench-discovery` and CI wiring in bench.yml/eval.yml. 2026-08-31 audit correction: the old note claimed this task absorbs discovery-eval-harness because it would measure retrieval recall - recall is ALREADY measured (eval.yml retrieval-d1 + bench/armindex.go), so that is not this task's contribution. GENUINELY OPEN and unique here: (a) activity-log session REPLAY (nothing in bench/ reads the activity log; internal/contracts/activity.go already carries WorkSessionID, ToolName and Response - watch ResponseTruncated, which would undercount tokens); (b) MEASURED first-call success and retry rate โ€” today they are assumed, not observed: bench/session.go defines per-arm literature-derived defaults (armRetryRates, research D8) and bench/report.go only renders and labels them as estimates; (c) tokens-per-SUCCESSFUL-task, which needs a task-completion signal the static harness has no concept of." - id: token-bench-public diff --git a/specs/083-discovery-profiler/contracts/report-v2.schema.json b/specs/083-discovery-profiler/contracts/report-v2.schema.json index fc0af587d..4b79ea4d1 100644 --- a/specs/083-discovery-profiler/contracts/report-v2.schema.json +++ b/specs/083-discovery-profiler/contracts/report-v2.schema.json @@ -3,46 +3,107 @@ "$id": "https://mcpproxy.app/schemas/bench-report-v2.schema.json", "title": "mcp-discovery-bench report v2", "type": "object", - "required": ["report_version", "generated_at", "tokenizer", "corpora", "arms", "provenance"], + "required": [ + "report_version", + "generated_at", + "tokenizer", + "corpora", + "arms", + "provenance" + ], "properties": { - "report_version": { "const": 2 }, - "generated_at": { "type": "string", "format": "date-time" }, + "report_version": { + "const": 2 + }, + "generated_at": { + "type": "string", + "format": "date-time" + }, "tokenizer": { "type": "object", - "required": ["name", "caveat"], + "required": [ + "name", + "caveat" + ], "properties": { - "name": { "type": "string", "examples": ["cl100k_base"] }, - "caveat": { "type": "string", "minLength": 10 } + "name": { + "type": "string", + "examples": [ + "cl100k_base" + ] + }, + "caveat": { + "type": "string", + "minLength": 10 + } } }, "proxy": { "type": "object", "properties": { - "version": { "type": "string" }, - "tool_count": { "type": "integer" }, - "expected_tool_count": { "type": "integer" }, - "tools_limit": { "type": "integer" }, - "routing_mode": { "type": "string" } + "version": { + "type": "string" + }, + "tool_count": { + "type": "integer" + }, + "expected_tool_count": { + "type": "integer" + }, + "tools_limit": { + "type": "integer" + }, + "routing_mode": { + "type": "string" + } } }, "corpora": { "type": "array", "items": { "type": "object", - "required": ["id", "name", "version", "tool_count", "license", "committed"], + "required": [ + "id", + "name", + "version", + "tool_count", + "license", + "committed" + ], "properties": { - "id": { "type": "string" }, - "name": { "type": "string" }, - "version": { "type": "string" }, - "tool_count": { "type": "integer" }, - "license": { "type": "string" }, - "attribution": { "type": "string" }, - "committed": { "type": "boolean" }, + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "version": { + "type": "string" + }, + "tool_count": { + "type": "integer" + }, + "license": { + "type": "string" + }, + "attribution": { + "type": "string" + }, + "committed": { + "type": "boolean" + }, "degenerate_descriptions": { "type": "object", "properties": { - "count": { "type": "integer" }, - "rules": { "type": "array", "items": { "type": "string" } } + "count": { + "type": "integer" + }, + "rules": { + "type": "array", + "items": { + "type": "string" + } + } } } } @@ -52,75 +113,194 @@ "type": "array", "items": { "type": "object", - "required": ["arm", "corpus_id", "skipped"], + "required": [ + "arm", + "corpus_id", + "skipped" + ], "allOf": [ { - "if": { "properties": { "skipped": { "const": false } } }, - "then": { "required": ["index_altering", "total_tokens", "mean_tokens", "p95_tokens", "savings_vs_baseline_pct", "skipped_tools"] } + "if": { + "properties": { + "skipped": { + "const": false + } + } + }, + "then": { + "required": [ + "index_altering", + "total_tokens", + "mean_tokens", + "p95_tokens", + "savings_vs_baseline_pct", + "skipped_tools" + ] + } }, { - "if": { "properties": { "skipped": { "const": true } } }, - "then": { "required": ["skip_reason"] } + "if": { + "properties": { + "skipped": { + "const": true + } + } + }, + "then": { + "required": [ + "skip_reason" + ] + } }, { "if": { - "properties": { "payload_class": { "const": "results" } }, - "required": ["payload_class"] + "properties": { + "payload_class": { + "const": "results" + } + }, + "required": [ + "payload_class" + ] }, - "then": { "required": ["fixture_id", "tabular_count", "non_tabular_count"] } + "then": { + "required": [ + "fixture_id", + "tabular_count", + "non_tabular_count" + ] + } }, { "if": { - "properties": { "index_altering": { "const": true }, "skipped": { "const": false } }, - "required": ["index_altering"] + "properties": { + "index_altering": { + "const": true + }, + "skipped": { + "const": false + } + }, + "required": [ + "index_altering" + ] }, "then": { - "required": ["quality"], + "required": [ + "quality" + ], "$comment": "quality is nullable only when the corpus has no relevance labels; metric_note must then explain the absence (enforced by the Go report validator)" } } ], "properties": { - "arm": { "type": "string", "pattern": "^[a-z0-9_]+$" }, - "corpus_id": { "type": "string" }, - "skipped": { "type": "boolean" }, - "skip_reason": { "type": "string" }, - "lower_bound": { "type": "boolean" }, - "index_altering": { "type": "boolean" }, - "payload_class": { "enum": ["listing", "results"] }, - "fixture_id": { "type": "string" }, - "tabular_count": { "type": "integer" }, - "non_tabular_count": { "type": "integer" }, - "total_tokens": { "type": "integer" }, - "mean_tokens": { "type": "number" }, - "p95_tokens": { "type": "integer" }, - "savings_vs_baseline_pct": { "type": "number" }, - "skipped_tools": { "type": "integer" }, + "arm": { + "type": "string", + "pattern": "^[a-z0-9_]+$" + }, + "corpus_id": { + "type": "string" + }, + "skipped": { + "type": "boolean" + }, + "skip_reason": { + "type": "string" + }, + "lower_bound": { + "type": "boolean" + }, + "index_altering": { + "type": "boolean" + }, + "payload_class": { + "enum": [ + "listing", + "results" + ] + }, + "fixture_id": { + "type": "string" + }, + "tabular_count": { + "type": "integer" + }, + "non_tabular_count": { + "type": "integer" + }, + "total_tokens": { + "type": "integer" + }, + "mean_tokens": { + "type": "number" + }, + "p95_tokens": { + "type": "integer" + }, + "savings_vs_baseline_pct": { + "type": "number" + }, + "skipped_tools": { + "type": "integer" + }, "skip_examples": { "type": "array", "items": { "type": "object", - "properties": { "tool_id": { "type": "string" }, "error": { "type": "string" } } + "properties": { + "tool_id": { + "type": "string" + }, + "error": { + "type": "string" + } + } } }, "heaviest_tools": { "type": "array", "items": { "type": "object", - "properties": { "tool_id": { "type": "string" }, "tokens": { "type": "integer" } } + "properties": { + "tool_id": { + "type": "string" + }, + "tokens": { + "type": "integer" + } + } } }, "quality": { - "type": ["object", "null"], + "type": [ + "object", + "null" + ], "properties": { - "recall_at_1": { "type": "number" }, - "recall_at_3": { "type": "number" }, - "recall_at_5": { "type": "number" }, - "recall_at_10": { "type": "number" }, - "mrr": { "type": "number" }, - "ndcg_at_10": { "type": "number" }, - "map": { "type": "number" }, - "metric_note": { "type": "string" } + "recall_at_1": { + "type": "number" + }, + "recall_at_3": { + "type": "number" + }, + "recall_at_5": { + "type": "number" + }, + "recall_at_10": { + "type": "number" + }, + "mrr": { + "type": "number" + }, + "ndcg_at_10": { + "type": "number" + }, + "map": { + "type": "number" + }, + "metric_note": { + "type": "string" + } } } } @@ -129,24 +309,52 @@ "response_cost": { "type": "object", "properties": { - "p50": { "type": "integer" }, - "p95": { "type": "integer" }, - "max": { "type": "integer" }, - "mean": { "type": "number" }, + "p50": { + "type": "integer" + }, + "p95": { + "type": "integer" + }, + "max": { + "type": "integer" + }, + "mean": { + "type": "number" + }, "per_query": { "type": "array", "items": { "type": "object", - "required": ["query_id", "total_tokens", "components"], + "required": [ + "query_id", + "total_tokens", + "components" + ], "properties": { - "query_id": { "type": "string" }, - "total_tokens": { "type": "integer" }, - "result_count": { "type": "integer" }, - "latency_ms": { "type": "number" }, + "query_id": { + "type": "string" + }, + "total_tokens": { + "type": "integer" + }, + "result_count": { + "type": "integer" + }, + "latency_ms": { + "type": "number" + }, "components": { "type": "object", - "required": ["input_schemas", "descriptions", "usage_instructions", "metadata", "other"], - "additionalProperties": { "type": "integer" } + "required": [ + "input_schemas", + "descriptions", + "usage_instructions", + "metadata", + "other" + ], + "additionalProperties": { + "type": "integer" + } } } } @@ -156,23 +364,46 @@ "break_even": { "type": "object", "properties": { - "naive_full_menu_tokens": { "type": "integer" }, - "proxy_menu_tokens": { "type": "integer" }, - "mean_response_tokens": { "type": "number" }, - "break_even_calls": { "type": "number" }, - "no_break_even": { "type": "boolean" } + "naive_full_menu_tokens": { + "type": "integer" + }, + "proxy_menu_tokens": { + "type": "integer" + }, + "mean_response_tokens": { + "type": "number" + }, + "break_even_calls": { + "type": "number" + }, + "no_break_even": { + "type": "boolean" + } } }, "session_estimates": { "type": "array", "items": { "type": "object", - "required": ["arm", "calls_per_session", "retry_rate", "estimated_tokens"], + "required": [ + "arm", + "calls_per_session", + "retry_rate", + "estimated_tokens" + ], "properties": { - "arm": { "type": "string" }, - "calls_per_session": { "type": "integer" }, - "retry_rate": { "type": "number" }, - "estimated_tokens": { "type": "integer" } + "arm": { + "type": "string" + }, + "calls_per_session": { + "type": "integer" + }, + "retry_rate": { + "type": "number" + }, + "estimated_tokens": { + "type": "integer" + } } } }, @@ -180,46 +411,606 @@ "type": "object", "description": "Client-measured latency (FR-023). Two distinct surfaces, never conflated: the flat p50_ms..max_ms fields summarize the REST GET /api/v1/index/search calls (kept for backward compatibility; mirrored in rest_search), while mcp_discovery aggregates the MCP retrieve_tools calls timed by the discovery-response rows.", "properties": { - "p50_ms": { "type": "number" }, - "p95_ms": { "type": "number" }, - "p99_ms": { "type": "number" }, - "max_ms": { "type": "number" }, - "rest_search": { "$ref": "#/$defs/latency_aggregate" }, - "mcp_discovery": { "$ref": "#/$defs/latency_aggregate" } + "p50_ms": { + "type": "number" + }, + "p95_ms": { + "type": "number" + }, + "p99_ms": { + "type": "number" + }, + "max_ms": { + "type": "number" + }, + "rest_search": { + "$ref": "#/$defs/latency_aggregate" + }, + "mcp_discovery": { + "$ref": "#/$defs/latency_aggregate" + } } }, "lap": { "type": "object", - "required": ["executed"], + "required": [ + "executed" + ], "properties": { - "executed": { "type": "boolean" }, - "skip_reason": { "type": "string" }, - "version": { "type": "string" }, - "menu_tokens": { "type": "integer" }, - "in_house_menu_tokens": { "type": "integer" }, - "divergence_pct": { "type": "number" }, - "grade": { "type": "string" }, - "artifact_path": { "type": "string" } + "executed": { + "type": "boolean" + }, + "skip_reason": { + "type": "string" + }, + "version": { + "type": "string" + }, + "menu_tokens": { + "type": "integer" + }, + "in_house_menu_tokens": { + "type": "integer" + }, + "divergence_pct": { + "type": "number" + }, + "grade": { + "type": "string" + }, + "artifact_path": { + "type": "string" + } } }, "subset": { "type": "object", - "properties": { "seed": { "type": "integer" }, "size": { "type": "integer" } } + "properties": { + "seed": { + "type": "integer" + }, + "size": { + "type": "integer" + } + } + }, + "replay": { + "type": "object", + "description": "Spec 103 US1: deterministic cost recomputation over a real recorded workload. Additive and optional โ€” its presence does not change report_version, and it names its OWN accounting source rather than inheriting the document-level tokenizer.", + "required": [ + "accounting_source", + "counterfactual", + "bodies_included", + "fleet_shape", + "sessions_supplied", + "sessions_used" + ], + "properties": { + "accounting_source": { + "$ref": "#/$defs/accounting_source" + }, + "counterfactual": { + "type": "string", + "minLength": 10, + "$comment": "FR-004: replay is a counterfactual over recorded traffic scored against the SUPPLIED fleet, never observed agent behaviour. Required so a figure cannot be emitted without its label." + }, + "bodies_included": { + "type": "boolean" + }, + "sensitive_flag_best_effort": { + "type": "boolean" + }, + "fleet_shape": { + "$ref": "#/$defs/fleet_shape" + }, + "sessions_supplied": { + "type": "integer" + }, + "sessions_used": { + "type": "integer" + }, + "exclusions": { + "type": "array", + "$comment": "FR-003 / SC-008: supplied minus used is explained here, one count per reason. Silence is never success.", + "items": { + "type": "object", + "required": [ + "reason", + "sessions" + ], + "properties": { + "reason": { + "enum": [ + "truncated", + "bodies_missing", + "sensitive", + "unreplayable", + "unattributed" + ] + }, + "sessions": { + "type": "integer" + } + } + } + }, + "cells": { + "type": "array", + "items": { + "type": "object", + "required": [ + "cell_id", + "provenance", + "calls", + "menu_tokens" + ], + "allOf": [ + { + "if": { + "properties": { + "absolute_workload_withheld": { + "const": true + } + }, + "required": [ + "absolute_workload_withheld" + ] + }, + "then": { + "required": [ + "withheld_reason" + ], + "$comment": "An unavailable absolute workload figure is reported as withheld WITH a reason, never as zero." + } + } + ], + "properties": { + "cell_id": { + "type": "string" + }, + "provenance": { + "$ref": "#/$defs/provenance" + }, + "calls": { + "type": "integer" + }, + "menu_tokens": { + "type": "integer" + }, + "response_tokens": { + "type": "integer" + }, + "absolute_workload_withheld": { + "type": "boolean" + }, + "withheld_reason": { + "type": "string" + } + } + } + }, + "direct_delta": { + "type": "object", + "description": "The cross-mode delta between the two direct cells, whose identical call responses cancel out of the comparison โ€” the honest bodies-off headline.", + "required": [ + "from_cell_id", + "to_cell_id", + "provenance", + "delta_tokens", + "delta_pct" + ], + "properties": { + "from_cell_id": { + "type": "string" + }, + "to_cell_id": { + "type": "string" + }, + "provenance": { + "$ref": "#/$defs/provenance" + }, + "delta_tokens": { + "type": "integer" + }, + "delta_pct": { + "type": "number" + } + } + }, + "loader_accounting": { + "type": "object", + "description": "Spec 103 US1: the LOADER's own exclusion accounting, distinct from the session-level `exclusions` array. Session rows answer how many units of work did not get in; these answer what was dropped, suppressed or flagged INSIDE the units that did. A withheld cost collapses a cell's response total, and without a row naming the cause the reader sees a missing figure with no explanation โ€” the silent accounting SC-008 forbids.", + "required": [ + "records_dropped", + "costs_withheld", + "records_flagged" + ], + "properties": { + "records_dropped": { + "type": "integer", + "minimum": 0, + "$comment": "Records that never joined a unit of work." + }, + "dropped": { + "type": "array", + "items": { + "type": "object", + "required": [ + "reason", + "count" + ], + "properties": { + "reason": { + "type": "string" + }, + "count": { + "type": "integer", + "minimum": 0 + } + } + } + }, + "costs_withheld": { + "type": "integer", + "minimum": 0, + "$comment": "Costs suppressed on records that DID contribute. Separate from dropped on purpose: merging them yields an uninterpretable total." + }, + "withheld": { + "type": "array", + "items": { + "type": "object", + "required": [ + "reason", + "count" + ], + "properties": { + "reason": { + "type": "string" + }, + "count": { + "type": "integer", + "minimum": 0 + } + } + } + }, + "records_flagged": { + "type": "integer", + "minimum": 0, + "$comment": "Records counted in the workload but carrying a usability caveat." + }, + "flagged": { + "type": "array", + "items": { + "type": "object", + "required": [ + "reason", + "count" + ], + "properties": { + "reason": { + "type": "string" + }, + "count": { + "type": "integer", + "minimum": 0 + } + } + } + }, + "orphaned_sub_calls": { + "type": "integer", + "minimum": 0, + "$comment": "Sub-calls whose parent fell outside the exported window. Counted in the workload at top level; what was lost is the attribution, and a total that hides it cannot be audited." + } + } + } + } + }, + "agent_loop": { + "type": "object", + "description": "Spec 103 US2: live agent-loop measurements. Its accounting_source is provider-reported usage plus a pinned model, and its figures are NEVER summed with tokenizer-sourced ones.", + "required": [ + "accounting_source", + "fleet_shape" + ], + "properties": { + "accounting_source": { + "$ref": "#/$defs/accounting_source" + }, + "suite": { + "type": "string" + }, + "suite_version": { + "type": "string" + }, + "fleet_shape": { + "$ref": "#/$defs/fleet_shape" + }, + "cells": { + "type": "array", + "items": { + "type": "object", + "required": [ + "cell_id", + "provenance", + "runs", + "spread_pct", + "tokens_per_completed_task", + "completion_rate_pct", + "first_attempt_success_pct", + "retries_corrective", + "retries_infrastructure", + "input_tokens", + "output_tokens", + "cache_read_tokens", + "headline" + ], + "allOf": [ + { + "if": { + "properties": { + "headline": { + "const": true + } + }, + "required": [ + "headline" + ] + }, + "then": { + "properties": { + "runs": { + "minimum": 4 + } + }, + "$comment": "FR-021: a model-dependent figure needs at least four runs plus a spread before it may be a headline." + } + } + ], + "properties": { + "cell_id": { + "type": "string" + }, + "provenance": { + "$ref": "#/$defs/provenance" + }, + "runs": { + "type": "integer" + }, + "spread_pct": { + "type": "number" + }, + "partial_runs": { + "type": "integer" + }, + "tokens_per_completed_task": { + "type": "number" + }, + "completion_rate_pct": { + "type": "number" + }, + "first_attempt_success_pct": { + "type": "number" + }, + "retries_corrective": { + "type": "integer" + }, + "retries_infrastructure": { + "type": "integer" + }, + "input_tokens": { + "type": "integer" + }, + "output_tokens": { + "type": "integer" + }, + "cache_read_tokens": { + "type": "integer" + }, + "headline": { + "type": "boolean" + }, + "regression": { + "type": "boolean" + }, + "withheld": { + "type": "boolean" + }, + "withheld_reason": { + "type": "string" + } + } + } + } + } + }, + "payload_decomposition": { + "type": "object", + "description": "Spec 103 US4: tool-definition payload attribution per fleet shape, each with its own recomputed ceiling and an explicit verdict on spec 102.", + "required": [ + "accounting_source", + "shapes" + ], + "properties": { + "accounting_source": { + "$ref": "#/$defs/accounting_source" + }, + "shapes": { + "type": "array", + "minItems": 2, + "$comment": "FR-024: at least two fleet shapes. A single-shape decomposition is exactly the projection spec 102 got wrong.", + "items": { + "type": "object", + "required": [ + "fleet_shape", + "provenance", + "share_names_pct", + "share_descriptions_pct", + "share_annotations_pct", + "share_schemas_pct", + "achievable_ceiling_pct", + "spec102_verdict" + ], + "allOf": [ + { + "if": { + "properties": { + "spec102_verdict": { + "const": "corrected" + } + }, + "required": [ + "spec102_verdict" + ] + }, + "then": { + "required": [ + "spec102_delta_pct" + ], + "$comment": "FR-025: a correction states its delta." + } + } + ], + "properties": { + "fleet_shape": { + "$ref": "#/$defs/fleet_shape" + }, + "provenance": { + "$ref": "#/$defs/provenance" + }, + "share_names_pct": { + "type": "number" + }, + "share_descriptions_pct": { + "type": "number" + }, + "share_annotations_pct": { + "type": "number" + }, + "share_schemas_pct": { + "type": "number" + }, + "achievable_ceiling_pct": { + "type": "number", + "$comment": "Recomputed per fleet shape โ€” never carried forward from a previously published figure." + }, + "spec102_verdict": { + "enum": [ + "confirmed", + "corrected" + ] + }, + "spec102_delta_pct": { + "type": "number" + } + } + } + } + } }, "provenance": { "type": "object", - "additionalProperties": { "enum": ["measured", "computed", "estimated"] } + "$comment": "SECTION-level provenance: one badge per section key. It cannot express FR-013, where measured and estimated figures coexist inside one block โ€” that is what the per-row provenance fields on the spec 103 blocks are for.", + "additionalProperties": { + "$ref": "#/$defs/provenance" + } } }, "$defs": { + "provenance": { + "enum": [ + "measured", + "computed", + "estimated" + ], + "description": "How a figure was arrived at: measured (observed over the real protocol), computed (arithmetic over measured inputs), or estimated (a model with documented assumptions). Declared once and referenced by both the section-level map and every per-row provenance field, so the two can never drift apart." + }, + "accounting_source": { + "type": "object", + "description": "Where one block's numbers came from. Per BLOCK, because the document-level tokenizer field names the deterministic estimator for the whole report and cannot be narrowed without a report_version bump. Figures from different sources are never summed โ€” a cross-source aggregate is withheld with a stated reason.", + "required": [ + "kind", + "identity" + ], + "allOf": [ + { + "if": { + "properties": { + "kind": { + "const": "provider-usage" + } + }, + "required": [ + "kind" + ] + }, + "then": { + "required": [ + "model" + ], + "$comment": "Provider-reported usage is uninterpretable without the model pinned: an unpinned run is not comparable to any later one." + } + } + ], + "properties": { + "kind": { + "enum": [ + "deterministic-tokenizer", + "provider-usage" + ] + }, + "identity": { + "type": "string", + "minLength": 1, + "examples": [ + "cl100k_base", + "anthropic" + ] + }, + "model": { + "type": "string" + } + } + }, + "fleet_shape": { + "type": "object", + "description": "The tool count and definition-size distribution a figure holds for (IC-004). Every published percentage carries one.", + "required": [ + "id", + "tool_count" + ], + "properties": { + "id": { + "type": "string" + }, + "tool_count": { + "type": "integer" + }, + "mean_definition_tokens": { + "type": "number" + }, + "p95_definition_tokens": { + "type": "integer" + } + } + }, "latency_aggregate": { "type": "object", "description": "Nearest-rank percentile summary of client-measured latencies for one measured surface (FR-023).", "properties": { - "p50_ms": { "type": "number" }, - "p95_ms": { "type": "number" }, - "p99_ms": { "type": "number" }, - "max_ms": { "type": "number" } + "p50_ms": { + "type": "number" + }, + "p95_ms": { + "type": "number" + }, + "p99_ms": { + "type": "number" + }, + "max_ms": { + "type": "number" + } } } } diff --git a/specs/103-token-bench/tasks.md b/specs/103-token-bench/tasks.md index 89a9ce2ee..75daea902 100644 --- a/specs/103-token-bench/tasks.md +++ b/specs/103-token-bench/tasks.md @@ -24,13 +24,13 @@ changes in `internal/`. Paths below are repo-relative and exact. **Purpose**: Make the deterministic half reproducible before anything depends on it. -- [ ] T001 Set `TIKTOKEN_CACHE_DIR` in `.github/workflows/bench.yml` AND add a cache +- [x] T001 Set `TIKTOKEN_CACHE_DIR` in `.github/workflows/bench.yml` AND add a cache restore/save step so the vocabulary is present offline โ€” setting the variable alone only names a cache, it does not fill one (research.md "Cross-cutting: reproducibility hazards") -- [ ] T002 [P] Add a PR-triggered required workflow step asserting no report is tracked: +- [x] T002 [P] Add a PR-triggered required workflow step asserting no report is tracked: `test -z "$(git ls-files bench/results)"`. It must NOT live in `.github/workflows/bench.yml`, which triggers only on `v*` tags and `workflow_dispatch` and so cannot block a PR (SC-011) -- [ ] T003 [P] Document the replay + agent-loop entry points in `bench/README.md`, including the +- [x] T003 [P] Document the replay + agent-loop entry points in `bench/README.md`, including the mandatory fleet input and the bodies-off/bodies-on distinction (Principle VI) --- @@ -42,16 +42,16 @@ until this phase completes.** **Production changes (both small, both required before US1 can be honest). Tests first:** -- [ ] T004 Write a FAILING test asserting the export projection carries both byte fields, in +- [x] T004 Write a FAILING test asserting the export projection carries both byte fields, in `internal/httpapi/activity_test.go` (TDD, Principle V โ€” must precede the DTO change below) -- [ ] T005 Write a FAILING test asserting a truncated `retrieve_tools` call produces an activity +- [x] T005 Write a FAILING test asserting a truncated `retrieve_tools` call produces an activity record flagged truncated. Create `internal/server/mcp_activity_truncation_test.go` โ€” no such file exists today (must precede the truncation-propagation task below) -- [ ] T006 Add `RequestBytes` / `ResponseBytes` to the export DTO in +- [x] T006 Add `RequestBytes` / `ResponseBytes` to the export DTO in `internal/contracts/activity.go` and copy them in `storageToContractActivityForExport` in `internal/httpapi/activity.go`. They exist on the storage record as pre-truncation measurements but never reach the export (contracts/replay-input.md). Turns the export-projection test green -- [ ] T007 Propagate the already-computed `wasTruncated` into the internal tool-call activity +- [x] T007 Propagate the already-computed `wasTruncated` into the internal tool-call activity emit: extend `emitActivityInternalToolCall` in `internal/server/mcp.go:810` and pass the value the `retrieve_tools` handler already holds at `internal/server/mcp.go:2019-2035`. **Without this a truncated `retrieve_tools` record cannot be identified and the loader @@ -60,39 +60,39 @@ until this phase completes.** **Report envelope (additive, no `report_version` bump). Tests first:** -- [ ] T008 Write FAILING tests in `bench/reportv2_test.go` asserting: the new blocks validate +- [x] T008 Write FAILING tests in `bench/reportv2_test.go` asserting: the new blocks validate against the schema; every emitted block carries a populated `accounting_source`; and each new row type carries a `provenance` value from the closed enum. A field that exists but is never set does not satisfy the contract -- [ ] T009 Add a `provenance` field to every new row type and constrain it to +- [x] T009 Add a `provenance` field to every new row type and constrain it to `measured|computed|estimated` in `bench/reportv2.go`. Section-level provenance cannot express FR-013, which lets measured and estimated figures coexist in one block -- [ ] T010 Add a per-block `accounting_source` field in `bench/reportv2.go`. **Do NOT narrow +- [x] T010 Add a per-block `accounting_source` field in `bench/reportv2.go`. **Do NOT narrow the existing document-level `Tokenizer` field** โ€” that would be a meaning change requiring a version bump (contracts/report-v2-additions.md). Same file as the provenance task, so not parallel -- [ ] T011 Declare the new optional blocks (`replay`, `agent_loop`, `payload_decomposition`) in +- [x] T011 Declare the new optional blocks (`replay`, `agent_loop`, `payload_decomposition`) in `specs/083-discovery-profiler/contracts/report-v2.schema.json`. The schema has no `additionalProperties: false`, so an undeclared block would validate silently โ€” declare them anyway, the schema file is the reviewed contract **Mode matrix:** -- [ ] T012 Write FAILING tests for the matrix in `bench/modematrix_test.go`: exactly 5 distinct +- [x] T012 Write FAILING tests for the matrix in `bench/modematrix_test.go`: exactly 5 distinct cells; the 7 redundant combinations each produce a skip row naming the cell it collapses onto; `code_execution` + `enable_code_execution:false` yields reason `degenerate` -- [ ] T013 Write FAILING tests in `bench/modematrix_test.go` for the FR-016 capability +- [x] T013 Write FAILING tests in `bench/modematrix_test.go` for the FR-016 capability conditions โ€” batching, stored scripts and validate-before-dispatch as BINARY conditions over the cells where each is available, with the report enumerating applicable rows. Same file as the task above, so not parallel -- [ ] T014 Implement `bench/modematrix.go` per `contracts/mode-matrix.md`, including the FR-016 +- [x] T014 Implement `bench/modematrix.go` per `contracts/mode-matrix.md`, including the FR-016 capability conditions. **Compose existing pieces through structural interfaces โ€” do not re-derive any serialization.** Reuse mode constants and proxy catalogs (`bench/tokens.go`), full rendering (`bench/arms/baseline.go`), compact measurement (`bench/flipgate.go`), deferred-direct rendering (`bench/arms/directdeferred.go`), MCP transport (`bench/mcpcaller.go`). Reuse the existing skip shape (`ArmResult.Skipped`/`SkipReason`, `SkippedArmResult`) -- [ ] T015 Map a cell to its endpoint URL in `bench/modematrix.go`. The routing-mode axis needs +- [x] T015 Map a cell to its endpoint URL in `bench/modematrix.go`. The routing-mode axis needs no config change โ€” all three routing-mode servers are mounted at startup (`internal/server/server.go:2514-2536`). The two serialization axes need config but both hot-reload, so the matrix crosses on one long-lived instance with a config apply between @@ -113,66 +113,66 @@ report beside them โ€” and that two runs are identical modulo `generated_at`. ### Tests for User Story 1 โš ๏ธ (write first, confirm they fail) -- [ ] T016 [P] [US1] Loader tests in `bench/replaycorpus/load_test.go`: JSONL decoding; CSV +- [x] T016 [P] [US1] Loader tests in `bench/replaycorpus/load_test.go`: JSONL decoding; CSV rejected; grouping by `work_session_id`; `parent_id` โ†” `request_id` join for code-execution sub-calls -- [ ] T017 [P] [US1] Usability-flag tests in `bench/replaycorpus/flags_test.go`: truncated, +- [x] T017 [P] [US1] Usability-flag tests in `bench/replaycorpus/flags_test.go`: truncated, bodies-missing, sensitive and unreplayable are each detected, and every exclusion is counted โ€” **assert a truncated record never contributes silently** (FR-002, SC-008) -- [ ] T018 [P] [US1] Privacy tests in `bench/replaycorpus/privacy_test.go`: no body text escapes +- [x] T018 [P] [US1] Privacy tests in `bench/replaycorpus/privacy_test.go`: no body text escapes the package; tokenization happens inside the loader and only counts cross the boundary; **bodies-off is the DEFAULT**; bodies-on requires an explicit opt-in and emits a warning (FR-006, SC-009, contracts/replay-input.md) -- [ ] T019 [US1] In `bench/replay_test.go`: a recording-only invocation (no fleet input) is a +- [x] T019 [US1] In `bench/replay_test.go`: a recording-only invocation (no fleet input) is a hard error, not a degraded run -- [ ] T020 [US1] In `bench/replay_test.go`: no cell reports an absolute complete-workload cost +- [x] T020 [US1] In `bench/replay_test.go`: no cell reports an absolute complete-workload cost bodies-off, and only the `direct_full` vs `direct_deferred` delta is produced. Same file as the task above, so not parallel -- [ ] T021 [US1] In `bench/replay_test.go`: two runs over the same inputs are byte-identical +- [x] T021 [US1] In `bench/replay_test.go`: two runs over the same inputs are byte-identical after `generated_at` is excluded (SC-002). Same file as the task above, so not parallel ### Implementation for User Story 1 -- [ ] T022 [P] [US1] Create `bench/replaycorpus/load.go` โ€” decode `contracts.ActivityRecord` +- [x] T022 [P] [US1] Create `bench/replaycorpus/load.go` โ€” decode `contracts.ActivityRecord` JSONL from `mcpproxy activity export --format json`. **This package MUST import nothing from `bench`**, or `bench/replay.go` cannot import it without a cycle (`bench/corpusio` imports `bench`, which is why mirroring it would fail) -- [ ] T023 [P] [US1] Create `bench/replaycorpus/group.go` โ€” group by `work_session_id`, join +- [x] T023 [P] [US1] Create `bench/replaycorpus/group.go` โ€” group by `work_session_id`, join code-execution sub-calls via `parent_id` โ†” `request_id` so they are neither double-counted nor orphaned -- [ ] T024 [US1] Create `bench/replaycorpus/flags.go` โ€” compute usability flags once at load. +- [x] T024 [US1] Create `bench/replaycorpus/flags.go` โ€” compute usability flags once at load. Handle the two byte-coverage gaps: internal `retrieve_tools` records carry no byte counts, and code-execution sub-calls emit both as zero (`internal/server/mcp_code_execution.go:811-818`); both fall to exclusion accounting -- [ ] T025 [US1] Enforce the privacy posture in `bench/replaycorpus/load.go`: bodies-off by +- [x] T025 [US1] Enforce the privacy posture in `bench/replaycorpus/load.go`: bodies-off by DEFAULT, bodies-on only via explicit opt-in that prints a warning, and refuse an input path inside the repository working tree (replay inputs live outside it and are never committed). Turns the privacy test green -- [ ] T026 [US1] In `bench/replaycorpus/tokenize.go`, tokenize inside the loader for bodies-on +- [x] T026 [US1] In `bench/replaycorpus/tokenize.go`, tokenize inside the loader for bodies-on runs and emit counts only, so no text crosses the boundary. Exclude (or re-apply truncation to) truncated `retrieve_tools` records โ€” the log stores the FULL pre-truncation response while the agent consumed truncated text, so tokenizing it as-is would OVERSTATE cost -- [ ] T027 [US1] Create `bench/replay.go` โ€” per-cell menu cost from the fleet input, plus the +- [x] T027 [US1] Create `bench/replay.go` โ€” per-cell menu cost from the fleet input, plus the direct-cell delta. Reuse `arms.CanonicalToolText` / `CountToolWithSchema` for the tool surface and the `bench/respcost.go` span-partition technique for responses, so components sum exactly. Populate the `replay` block's `accounting_source` as the deterministic tokenizer -- [ ] T028 [US1] Add the `-replay` flag plus a mandatory fleet input to `bench/cmd/bench/main.go` +- [x] T028 [US1] Add the `-replay` flag plus a mandatory fleet input to `bench/cmd/bench/main.go` as a top-level branch beside the profiler check, emitting a `replay` block into `ReportV2` (not an `OfflineSection` โ€” replay crosses the matrix, it is not one more corpus) -- [ ] T029 [US1] Exclude or pin `generated_at` for replay reports in `bench/replay.go` so +- [x] T029 [US1] Exclude or pin `generated_at` for replay reports in `bench/replay.go` so SC-002's determinism check is meaningful -- [ ] T030 [US1] Write a FAILING assertion in `bench/replay_test.go`: no replay figure may be +- [x] T030 [US1] Write a FAILING assertion in `bench/replay_test.go`: no replay figure may be emitted without the counterfactual marker (FR-004) -- [ ] T031 [US1] Label every replay figure as a COUNTERFACTUAL over recorded traffic, not +- [x] T031 [US1] Label every replay figure as a COUNTERFACTUAL over recorded traffic, not observed agent behaviour, in `bench/replay.go` โ€” FR-004 forbids presenting it as observed, and the Replay Boundary is the spec's most load-bearing constraint. Turns the assertion above green -- [ ] T032 [US1] Render the `replay` block in the dashboard template in `bench/report.go`, +- [x] T032 [US1] Render the `replay` block in the dashboard template in `bench/report.go`, showing the exclusion report, the counterfactual label, and that figures are scored against **today's** fleet, not the fleet as recorded -- [ ] T033 [US1] Document in `bench/README.md` how to delete a replay input when finished +- [x] T033 [US1] Document in `bench/README.md` how to delete a replay input when finished (contracts/replay-input.md privacy rule 6) **Checkpoint**: US1 is independently shippable and delivers real-workload numbers with no model spend.