Repository navigation
Commit f374810
authored
feat(preflight): required-tools preflight — deterministic availability check with reason taxonomy (spec 098) (#996)
Related #969
Implements item 3 of #969 (the reporter-confirmed shape: cron/CI-first, REST+CLI, stat-only): a deterministic, side-effect-free availability check for a caller-supplied list of tool IDs, answering per-ID with a machine-readable reason instead of failing silently at discovery time.
Lands on top of #995 (baseline counters), which shipped one release ahead per the Phase-0 decision.
## What
- **`POST /api/v1/preflight`** — `{tools:[{id, pin_hash?}], profile?, policy?, wait_ms?}` → per-ID verdicts. HTTP 200 whenever the check executed (the verdict is data); 400 validation / 503 runtime-or-persistence failure. Standard `APIResponse` envelope.
- **`mcpproxy tools preflight`** — typed exit codes `0` ready · `10` retryable (backoff) · `11` blocked (page operator) · `12` unknown ID (fix manifest); worst class wins. A cron wrapper branches without parsing JSON.
- **One shared eligibility evaluator** (`internal/preflight`): closed 15-code reason taxonomy with a fixed precedence chain; existence = index ∨ approval record (the runtime de-indexes blocked/pending/changed tools — index absence alone proves nothing); zero upstream I/O and zero runtime mutation, structurally (the evaluator cannot reach a transport; asserted by instrumented-transport + state-snapshot tests).
- **Four-path dispatch consolidation** (FR-002 no-skew): call_tool variants, direct mode, code_execution and stored scripts all consume the same gate. Notable hardening: **scripts previously enforced no per-tool policy at all** — a code_execution/stored script could call a quarantined tool; now refused like every other path.
- **Transparency**: every executed preflight writes a durable activity record (synchronous, before the 200 — persistence failure ⇒ 503), request-ID-correlated and browsable via `mcpproxy activity list --request-id …` and the Web UI.
- **Disclosure tiers**: operator (API key/socket/pipe) gets full diagnosis incl. `sha256/v{N}:{hex}` hash pins; agent tokens get scope-silence (out-of-scope, unconfigured — byte-indistinguishable `not_found`; no hashes; `did_you_mean` never crosses scope). Stale token ProfilePin now intersects to deny-all.
- **Zero MCP-surface change**: `tools/list` byte-identical to merge-base across all three routing modes (golden-snapshot test, goldens captured from origin/main).
## Verification
- **Sabotage E2E matrix** (`testdata/preflight_sabotage_matrix.json`): 23 scenario cells against a real binary + live fixture upstreams — quarantine flip, rug-pull drift, block, config-deny, disable, SIGSTOP/kill, mid-indexing, annotation cells per filter, unknown id/server, hash + schema-version mismatch, PendingAuth, profile scope at both tiers — each asserting exact {reason, retryable, action} + the activity record by request ID; a reflection test forbids enum codes without a cell.
- Full gates: `go test -race ./...` (79 pkgs), server-edition build/tests/lint, 65/65 API E2E, golangci v2 both tag sets, swagger + generate-types idempotent, frontend build + 605 unit tests.
- code_execution + stored scripts: byte-identical transcripts vs main on a 9-probe harness; live no-skew check across all four dispatch paths.
## Review
Spec, plan, and full diff cross-model reviewed (opencode / gpt-5.6-sol): spec 3 rounds → APPROVE; plan 25 findings (12 P1) incorporated → APPROVE; code round 1 = 11 findings (6 P1, all genuine, each fix verified by restoring the old code), round 2 = 1 regression (startup-window 503 → `server_initializing`), round 3 → **APPROVE**.
## Docs
New `docs/features/tools-preflight.md` (taxonomy, precedence, tiers, transparency, cron/GHA/n8n recipes, code-exec composition), REST + CLI references, README "How AI Agents Work Through MCPProxy" section with a preflight-gated automation example.
Known follow-up (deliberately out of scope, pre-existing): `resolveActiveProfile` warn-skips a stale ProfilePin on the live session path — preflight is now stricter than dispatch there; the session path deserves its own reviewed fix.1 parent a3a5e5b commit f374810
95 files changed
Lines changed: 14642 additions & 200 deletions
File tree
- cmd
- generate-types
- mcpproxy
- docs
- api
- features
- frontend
- src
- components
- types
- utils
- views
- tests/unit
- internal
- auth
- cliclient
- contracts
- httpapi
- preflight
- runtime
- serveredition
- api
- auth
- server
- testdata
- toolslist_goldens
- storage
- toolannotations
- oas
- specs/098-tools-preflight
- checklists
- contracts
- verification
- test
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
19 | 19 | | |
20 | 20 | | |
21 | 21 | | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
22 | 28 | | |
23 | 29 | | |
24 | 30 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
158 | 158 | | |
159 | 159 | | |
160 | 160 | | |
| 161 | + | |
161 | 162 | | |
162 | 163 | | |
163 | | - | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
181 | 181 | | |
182 | 182 | | |
183 | 183 | | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
| 209 | + | |
| 210 | + | |
| 211 | + | |
| 212 | + | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
| 217 | + | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
| 228 | + | |
| 229 | + | |
| 230 | + | |
| 231 | + | |
| 232 | + | |
| 233 | + | |
| 234 | + | |
| 235 | + | |
| 236 | + | |
| 237 | + | |
| 238 | + | |
| 239 | + | |
| 240 | + | |
| 241 | + | |
| 242 | + | |
| 243 | + | |
| 244 | + | |
| 245 | + | |
| 246 | + | |
| 247 | + | |
| 248 | + | |
| 249 | + | |
184 | 250 | | |
185 | 251 | | |
186 | 252 | | |
| |||
295 | 361 | | |
296 | 362 | | |
297 | 363 | | |
| 364 | + | |
298 | 365 | | |
299 | 366 | | |
300 | 367 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
799 | 799 | | |
800 | 800 | | |
801 | 801 | | |
| 802 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
114 | 114 | | |
115 | 115 | | |
116 | 116 | | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
117 | 201 | | |
118 | 202 | | |
119 | 203 | | |
| |||
241 | 325 | | |
242 | 326 | | |
243 | 327 | | |
| 328 | + | |
| 329 | + | |
| 330 | + | |
| 331 | + | |
244 | 332 | | |
245 | 333 | | |
246 | 334 | | |
| |||
0 commit comments