Repository navigation
Commit 4ccb8a0
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 #9711 parent 7b118d1 commit 4ccb8a0
1 file changed
Lines changed: 197 additions & 0 deletions
0 commit comments