Skip to content

Commit 4ccb8a0

Browse files
authored
docs(specs): 102-schema-deferred — deferred-schema serialization for the direct tools/list surface (#1035)
* docs(specs): 102-schema-deferred — deferred-schema direct tools/list spec Related #971 Speckit stage-1 spec for schema-deferred serialization of the direct enumeration surface: tools/list keeps all names + descriptions (with Spec 085 compact signatures appended), strips inputSchema, exposes describe_tool on the direct surface, and extends pre-dispatch validation + self-healing errors to direct dispatch. Opt-in, no new routing_mode. 3 NEEDS CLARIFICATION markers: config axis (one-axis vs dedicated key), outputSchema stripping, describe_tool batch cap. * docs(specs): 102-schema-deferred — correct surface/visibility facts from cross-model review Cross-model review (opencode gpt-5.6-sol) plus code verification found the stage-1 spec asserted several things about existing behavior that are not true, and left three implementable gaps. Spec-only; no code changes. Factual corrections: - FR-003: /mcp/p/<slug> serves retrieve_tools mode, not direct — there is no profile-scoped direct surface. Enumerate the real direct-serving routes (/mcp/all, /mcp under routing_mode:direct, and the legacy /v1/tool_code and /v1/tool-code aliases wired to the same handler). - FR-010/SC-004: the frozen tool-surface goldens do NOT cover direct mode (it is deliberately excluded — its listing is a live upstream projection). The delta therefore regenerates nothing; the goldens must stay byte-identical and a NEW gate must pin the direct surface's built-in set. - FR-011/Edge Cases: direct dispatch never parses the display name — each handler closes over its original (server, tool) pair. "Same first-__ parse as dispatch" is unachievable; resolution must go through the registration mapping. Added the display-name collision case. - FR-014: the config-reloaded branch does not rebuild the direct surface today; that wiring is new work, plus a no-op-when-unchanged requirement. - FR-005: the signature cache's only accessor compiles on miss, so "no per-request compilation" needs a new non-compiling lookup. - FR-007: no routing-mode server carries MCP instructions today; the channel must be chosen, not left as "and/or". - FR-001: the axis also has a --tool-response-mode flag and a MCPPROXY_TOOL_RESPONSE_MODE env alias; both move under either resolution. Gaps closed: - FR-011: direct-surface resolution must also gate on the operation-permission tier (the existing resolver does not), or a read-scoped token could describe a destructive tool hidden from its own tools/list; and must collapse existence-confirming reason codes to not_found per this session's listing. - FR-017 (new): one authoritative direct-surface catalog snapshot shared by listing, signature, describe_tool and validation. Today the listing is live-discovery while describe/signature are index-backed, so a tool pending tool-level approval is listed but has no schema, no signature and no way to recover either — strictly worse than full mode. - FR-018 (new): the direct tool set is replaced wholesale on every upstream refresh, so describe_tool must be composed into construction or it is silently dropped. - FR-009: describe_tool's prose says "found via retrieve_tools" and is byte-pinned by the goldens; resolve rather than inherit. - SC-007 added; SC-005 given explicit no-widening assertions. The three deliberate [NEEDS CLARIFICATION] markers are unchanged. Related #971 * docs(specs): 102-schema-deferred — split describe_tool disclosure by mode Round-2 cross-model review caught a contradiction introduced by round 1: FR-011 told describe_tool to answer a listed pending-approval tool with its reason code, while US2 scenario 5, FR-017 and SC-007 all required every listed tool to be describable. Both cannot hold — a non-agent session's direct listing deliberately retains pending/changed/quarantined/disabled tools, since the callability filter narrows only agent-token sessions. Resolved by splitting the rule along the axis describe_tool already has: - invisible to this session → plain not_found in BOTH definition and check mode; - visible to this session → definition mode returns the snapshot-backed definition (withholding it buys no confidentiality once the tool is listed, and under deferral the listing no longer carries the schema itself), while check:true returns the informative availability verdict, which is exactly what check mode exists for. US2 scenario 5, SC-007 and the FR-017 membership bullet now say "definition mode" explicitly so the two modes cannot be conflated again. Related #971 * docs(specs): 102-schema-deferred — align catalog-divergence edge case with the mode split Round-3 cross-model review found the edge case still described the pre-fix outcome ("no way to recover either — describe_tool not_found") in a way that read as specified behavior, contradicting US2 scenario 5, FR-011, FR-017 and SC-007. Reworded to mark it explicitly as the naive outcome FR-017 and FR-011 prevent, and to state what the spec actually requires: a listed pending or changed tool resolves to its snapshot-backed definition in definition mode and to a pending_approval/changed verdict under check:true, with only the signature (not the schema) degraded until the tool is approved and indexed. Related #971
1 parent 7b118d1 commit 4ccb8a0

1 file changed

Lines changed: 197 additions & 0 deletions

File tree

0 commit comments

Comments
 (0)