Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
c01cdba
docs(specs): 102-schema-deferred implementation plan
Dumbris Aug 25, 2026
d4efaf9
docs(specs): 102-schema-deferred plan hardening from verified review …
Dumbris Aug 25, 2026
6b61eae
docs(specs): 102-schema-deferred — name the bench arm the SC-001/SC-0…
Dumbris Aug 25, 2026
0aacf12
docs(specs): 102-schema-deferred — pin the exact corpus gate name and…
Dumbris Aug 25, 2026
40747e4
docs(specs): 102-schema-deferred — exact corpus gate name in research.md
Dumbris Aug 25, 2026
de181f8
docs(specs): 102-schema-deferred — FR-018 covers the discovery-error …
Dumbris Aug 25, 2026
7000056
docs(specs): 102-schema-deferred — make the FR-015 byte-stability cap…
Dumbris Aug 25, 2026
daeadfd
docs(specs): 102-schema-deferred — pin what the appended signature ac…
Dumbris Aug 25, 2026
19bd4cd
docs(specs): 102-schema-deferred — one reference wording for the defe…
Dumbris Aug 25, 2026
5a38fe1
docs(specs): 102-schema-deferred — name the single mode-read helper
Dumbris Aug 25, 2026
1ff0ed0
docs(specs): 102-schema-deferred — close the fourth parity leak (defi…
Dumbris Aug 25, 2026
2b1b68d
docs(specs): 102-schema-deferred — name the real injection point for …
Dumbris Aug 25, 2026
05d5da7
docs(specs): 102-schema-deferred — sync the decision table and consti…
Dumbris Aug 25, 2026
1792458
docs(specs): 102-schema-deferred — fix all four cross-model review fi…
Dumbris Aug 25, 2026
1e27e3d
docs(specs): 102-schema-deferred — distinguish a nil catalog from an …
Dumbris Aug 25, 2026
aadb8b3
docs(specs): 102-schema-deferred — reference D14 from the summary and…
Dumbris Aug 25, 2026
b9c1abd
docs(specs): 102-schema-deferred — punctuation after the R4 legend po…
Dumbris Aug 25, 2026
c2bf8f1
docs(specs): 102-schema-deferred — cross-reference R13 from R9's atom…
Dumbris Aug 25, 2026
3d9c28d
docs(specs): 102-schema-deferred — fix all four round-3 cross-model f…
Dumbris Aug 25, 2026
9874151
docs(specs): 102-schema-deferred — R13 ordering table now matches the…
Dumbris Aug 25, 2026
12fca8a
docs(specs): 102-schema-deferred — spell out that the builder must no…
Dumbris Aug 25, 2026
e6defd8
docs(specs): 102-schema-deferred — propagate D13 and D16 into every d…
Dumbris Aug 25, 2026
9d8da18
docs(specs): 102-schema-deferred — declare the FR-017 atomicity narro…
Dumbris Aug 25, 2026
a0d0601
docs(specs): 102-schema-deferred — close same-name origin skew (round…
Dumbris Aug 25, 2026
b8b40d2
docs(specs): 102-schema-deferred — retract the over-broad discriminat…
Dumbris Aug 25, 2026
6fc3f2e
docs(specs): 102-schema-deferred — pin renderedDescription on the cat…
Dumbris Aug 25, 2026
1a80fd6
docs(specs): 102-schema-deferred — group the skew interleavings so th…
Dumbris Aug 25, 2026
3e95e3b
docs(specs): 102-schema-deferred — fix the tier source, the publicati…
Dumbris Aug 25, 2026
606a57d
docs(specs): 102-schema-deferred — enumerate the invisible-change res…
Dumbris Aug 25, 2026
060ffb1
docs(specs): 102-schema-deferred — split the invisible-change proof i…
Dumbris Aug 25, 2026
a3fe1f6
docs(specs): 102-schema-deferred — make the invisible-change partitio…
Dumbris Aug 25, 2026
60e14cc
docs(specs): 102-schema-deferred — fix the input-schema skew test rec…
Dumbris Aug 25, 2026
071bd52
docs(specs): close review gaps in the 102-schema-deferred plan
Dumbris Aug 26, 2026
501bdc6
docs(specs): 102-schema-deferred tasks
Dumbris Aug 26, 2026
b4f9f4b
docs(specs): close cross-model review findings in the 102 task list
Dumbris Aug 26, 2026
631793b
Merge origin/main into 102-schema-deferred-plan
Dumbris Aug 26, 2026
4a683c1
docs(specs): accept the three FR-017 narrowings, amend the atomicity …
Dumbris Aug 27, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,6 @@ tail -f ~/Library/Logs/mcpproxy/main.log # main log (macOS; Linux: ~/.mcpproxy/
- **Windows installer**: [docs/github-actions-windows-wix-research.md](docs/github-actions-windows-wix-research.md). **Prerelease** (`next` branch + `v*-rc.*` tags, opt-in, off stable channels): [docs/prerelease-builds.md](docs/prerelease-builds.md).

## Recent Changes
- 102-schema-deferred: Go 1.25.5 module toolchain (`go.mod`), backend-only + existing only — mark3labs/mcp-go v0.57.0 (tool surface), santhosh-tekuri/jsonschema/v6 (Spec-085 validator reuse), zap, stdlib. **No new dependencies.**
- 098-tools-preflight: Added Go 1.24 module toolchain (repo builds with local Go 1.25) + existing only — chi (httpapi), bbolt (storage), Bleve (index), zap (logging), Cobra (CLI), swaggo/swag v2 (contract regen). **No new dependencies.**
- 097-stored-scripts: Added Go 1.25 (os.Root/Root.ReadFile available — R1) + stdlib only (os.Root). **No new dependencies.**
- 096-batched-call-tools: Added Go 1.24 module toolchain (repo builds with local Go 1.25) + existing only — goja (sandbox), mark3labs/mcp-go (tool surface), zap. **No new dependencies.**
4 changes: 2 additions & 2 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -740,7 +740,7 @@ graph LR
| --- | --- | --- | --- | --- | --- |
| Release qualification gate (auto-QA matrix blocks the tag) | In progress | P0 | — | [081-release-qa-gate](./specs/081-release-qa-gate/) | |
| Analytics dashboard as default page | In progress | P1 | 25/26 (96%) | [069-observability-usage-graphs](./specs/069-observability-usage-graphs/) | |
| Deferred-schema serialization for the direct tools/list surface (spec 102) | In progress | P1 | — | [102-schema-deferred](./specs/102-schema-deferred/) | |
| Deferred-schema serialization for the direct tools/list surface (spec 102) | In progress | P1 | 3/88 (3%) | [102-schema-deferred](./specs/102-schema-deferred/) | |
| 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/) | |
| MCP protocol upgrade to 2026-07-28 revision | In progress | P3 | — | [058-mcp-2026-upgrade](./specs/058-mcp-2026-upgrade/) | #1033 |
Expand Down Expand Up @@ -881,4 +881,4 @@ Legend: `shipped` ≥95% checked · `in-flight` 1–94% · `drafted` 0% · `—`
| [098-tools-preflight](./specs/098-tools-preflight/) | `in-flight` | 26/33 (79%) |
| [099-describe-check-mode](./specs/099-describe-check-mode/) | `in-flight` | 9/10 (90%) |
| [100-prompt-rugpull-baseline](./specs/100-prompt-rugpull-baseline/) | — | — |
| [102-schema-deferred](./specs/102-schema-deferred/) | — | — |
| [102-schema-deferred](./specs/102-schema-deferred/) | `in-flight` | 3/88 (3%) |
161 changes: 161 additions & 0 deletions specs/102-schema-deferred/contracts/direct-deferred-surface.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
# Contract: Deferred Direct Surface

Normative wire-level contract for Spec 102. Where this file and
[spec.md](../spec.md) disagree, the spec wins. Reuses two Spec-085 contracts
verbatim: `specs/085-compact-router/contracts/signature-grammar.md` (signature
rendering) and `.../invalid-params-error.md` (self-healing error body).

## 1. Deferred `tools/list` entry

With `direct_tool_response_mode: "deferred"`, each upstream tool entry on any
direct-serving route (`/mcp/all`; `/mcp`, `/v1/tool_code`, `/v1/tool-code` when
`routing_mode:"direct"`):

```json
{
"name": "github__create_issue",
"description": "[github] Create a new issue in a repository.\ncreate_issue(owner*:str, repo*:str, title*:str, labels?:[str], milestone~)",
"inputSchema": { "type": "object" },
"annotations": { "...unchanged from full mode..." }
}
```

Rules:
- `name`, annotations, membership, count, and ordering source: identical to full
mode for the same session (FR-008/FR-016).
- `description` = full-mode description (`[server] …`, untruncated) + newline +
the **bare tool name** + the compact signature per the 085 grammar (`*`
required — never elided; `~` lossy collapse). The name prefix is normative and
must be prepended by this renderer: `toolsig.Signature.Sig` is the parenthesised
parameter list only (`"(origin*:str, ttl:int=3600, account~:obj)"`,
`internal/toolsig/signature.go:18`) and carries no name.
`toolsig.Signature.Desc` — the first-sentence prefix Spec 085's compact entries
use — is deliberately NOT used here, because deferred entries keep the full
description. On a signature-cache miss the whole suffix (name + signature) is
absent and the entry is otherwise unchanged (never dropped, never delayed —
FR-005).
- `inputSchema` is exactly `{"type":"object"}` — never literal `{}`, never absent,
never carrying upstream properties/required (strict-client safety, FR-004).
Note the mechanism is normative too: `mcp.NewTool` marshals
`{"properties":{},"required":[],"type":"object"}`, which fails this rule and
re-opens the arg-pruning hazard, so deferred entries use
`mcp.NewToolWithRawSchema`. That constructor takes no `ToolOption`s **and
leaves every annotation hint `nil`**, where `mcp.NewTool` seeds
`readOnlyHint=false, destructiveHint=true, idempotentHint=false,
openWorldHint=true` before any option runs — so the deferred renderer MUST seed
those same defaults and only then apply the upstream overrides. Copying only
the upstream hints marshals a different (or empty) `annotations` object for the
same tool and breaks the rule above (research.md R11).
- `outputSchema` is absent (research.md R2).
- Full mode (`"full"`, the default) is byte-identical to pre-feature output modulo
§3's built-in addition (FR-015).

## 2. In-band convention (FR-007)

The direct server's `initialize` result carries `instructions` (today absent on
this server instance), static across both serialization modes, conditionally
phrased. The value is the operator's `instructions` config value when non-empty,
otherwise a **direct-specific default**, followed by a blank line and the
deferral legend. It is deliberately NOT `resolveInstructions`'s built-in
`defaultInstructions`: that text tells agents to "Use 'retrieve_tools'" and to
call `call_tool_read/write/destructive`, none of which exist on this surface
(research.md R4/D11). So an operator's configured instructions are never hidden
here, and the default never advertises a workflow this surface cannot serve.
Reference legend text (final bytes pinned by the direct built-in golden,
captured with an empty `instructions` config):

> Some tool descriptions end with a compact signature `(param*:type, …)`:
> `*` = required, `~` = collapsed/lossy details. When a signature is present the
> listed inputSchema is a placeholder — flat signatures are directly callable;
> for `~`-marked tools call `describe_tool` with the listed tool name to get the
> full schema.

## 3. `describe_tool` on the direct surface (FR-009/FR-011)

- **Definition**: the existing single `buildDescribeToolTool` definition
(surface-neutral prose per research.md R5), listed in BOTH serialization modes,
registered via direct tool-set construction so it survives every refresh
(FR-018).
- **Request**: unchanged shape — `tool_ids` (≤5, or ≤50 with `check:true`),
`check`, `filters`. Accepted id forms on this surface: canonical
`"<server>:<tool>"` AND direct `"<server>__<tool>"`; direct ids resolve through
the registration mapping (first-`__` re-parsing is forbidden).
- **Response**: existing shape (`definitions` + per-id `errors`); definitions
additively carry `"output_schema": {…}` when the tool declares one (all
surfaces).
- **Per-id outcomes** (parity with THIS session's direct `tools/list`):

| Id state for this session | definition mode | `check: true` |
|---|---|---|
| Listed, ready | full definition | `ready` |
| Listed, but pending / changed / tool-level-disabled (non-agent sessions retain **these** — see the note below) | full snapshot-backed definition — a listed tool is never undescribable | `status:"unavailable"` + the evaluator's real `reason` (see the vocabulary note) |
| On a **server-level** quarantined or disabled server | never listed on this surface (see note) → `not_found` | `status:"unavailable"`, `reason:"not_found"` |
| Omitted from this session's listing — any reason: token server scope, operation-permission tier, profile scope, agent callability, or nonexistence | `not_found` + standard remediation | `status:"unavailable"`, `reason:"not_found"` |
| Removed between list and describe | per-id `not_found`, batch not failed | `status:"unavailable"`, `reason:"not_found"` |
| Malformed id | per-id `not_found` + format remediation | `status:"unavailable"`, `reason:"not_found"` |

**Check-mode vocabulary note.** Definition mode and check mode do NOT share an
error vocabulary, and this table's check column uses check mode's own. Check mode
answers `describeCheckPayload{verdict, checked_at, request_id, results[]}` with
each result `{id, status, reason?, retryable?, action?, detail?, remediation?,
did_you_mean?}` (`mcp_describe_check.go:69-87`); a non-ready id is
`status:"unavailable"` carrying one `preflight.Reason`, and the reason constants
are `tool_pending_approval`, `tool_changed`, `tool_blocked_by_user`,
`tool_denied_by_config`, `server_quarantined`, `server_disabled`, `not_found`, …
(`internal/preflight/reasons.go:22-38`) — note the `tool_`/`server_` prefixes.
FR-009 requires this shape to survive verbatim onto the direct surface, so the
direct adapter **projects, never translates**: it decides which ids reach the
evaluator (listing parity) and canonicalizes their form (§3 request rules), and
passes the evaluator's `status`/`reason`/`action`/`retryable` through untouched.
The distinctions the existing vocabulary draws — user-blocked
(`tool_blocked_by_user`) versus config-denied (`tool_denied_by_config`), and
server- versus tool-level states — are preserved exactly. A test asserts a direct
check response is byte-compatible with the retrieve-surface response for the same
underlying tool state.

**Note — server-level vs tool-level states.** The spec's Edge Cases say a
non-agent direct listing "retains tools that are pending, changed, quarantined or
disabled". On this surface that is true only of the **tool-level** states:
`DiscoverTools` drops a server before its tools are ever projected — `if
!snapshot.enabled { continue }` and the quarantined-server skip
(`internal/upstream/manager.go:1128-1138`) — so a tool on a quarantined or
disabled *server* is never in the direct catalog and therefore answers
`not_found` here in both modes, exactly like any other unlisted id. Only
pending / changed / tool-level-disabled entries reach the listing and get the
informative verdict. This narrowing does not weaken FR-011; it is the same
parity rule applied to a state the listing never had.

No reason code, remediation variant, **suggestion**, or timing may confirm the
existence of an id this session's listing omitted. That explicitly covers both
suggestion channels: `did_you_mean` (check mode) and the definition-mode
case-correction hint. Both must be drawn from this session's direct catalog under
the listing-parity gates, or omitted on this surface — the shared preflight
suggestion corpus is server-level-filtered only and is NOT parity by itself
(research.md R10). Remediation strings on this surface must not instruct the agent
to "re-run retrieve_tools": the shared not-found and malformed-id remediations are
rewritten surface-neutral along with the tool prose (research.md R5).

Membership on both sides of this table is decided by the same catalog: the direct
listing filters resolve display names through the catalog's registration mapping,
never by re-parsing on the first `__`, so listing and describe cannot disagree for
a server name containing `__`.

Retrieve_tools-surface semantics are unchanged.

## 4. Pre-dispatch validation (FR-012/FR-013)

Direct-mode calls validate against the catalog entry's stored `paramsJSON` (never
the advertised placeholder), in both serialization modes, after the
profile/token/callability gates and before upstream dispatch. Failure → the
Spec-085 `invalid-params-error.md` body (error, `error_type:"invalid_params"`,
tool, one-line hint, full `input_schema`), with the hint's describe reference
using an id valid on this surface. Fail-open for uncompilable schemas (counted,
logged); non-argument failures keep their existing shapes with no schema attached.

## 5. Rollout (FR-014)

A `direct_tool_response_mode` change via config hot-reload rebuilds the direct
tool set and (via mcp-go `SetTools`) emits `notifications/tools/list_changed` to
connected direct-surface sessions; the tool set (names, count) is identical across
the flip. A config edit that does not change the effective serialization triggers
no rebuild and no notification.
Loading
Loading