fix(coding-agent): follow local schema refs in tool search and codemode summaries (#11850)

Fixes #11803.

**Problem**

`tool_search` builds a tool's search text from its parameter schema but
never followed `$ref`. MCP servers (Pydantic, FastMCP) often put nested
models in `$defs`:

```json
{ "properties": { "options": { "$ref": "#/$defs/options" } },
  "$defs": { "options": { "properties": { "mode": { "description": "reconciliation" } } } } }
```

Search text was `Inspect records options`, so
`tool_search("reconciliation")` found nothing. Durable's copy of
`tool_search` had the same gap. The codemode `resolves to` summary had
the same blind spot for output schemas: a field behind a `$ref` showed
as `structuredContent?` with no field names.

**Fix**

- pi-codemode exports its existing local JSON Pointer resolver as
`resolveSchemaRef(ref, root)`. A malformed percent escape now resolves
to nothing instead of throwing `URIError` (this also affected
`schemaToType()`).
- coding-agent and Durable `schemaText()` follow local `$ref`s. Each
referenced subschema is read once, so recursive and shared definitions
neither loop nor inflate BM25 term counts. Unreferenced `$defs` and
remote refs stay out.
- coding-agent `describeFields()`/`describeUnionFields()` resolve `$ref`
chains against the output schema root.

**Tests**

- `packages/codemode/test/declarations.test.ts`: escaped, remote,
missing, malformed refs.
- `packages/coding-agent/test/tool-search.test.ts`: refs, escaped
segments, recursion and shared definitions, unused definitions.
- `packages/coding-agent/test/suite/agent-session-codemode.test.ts`:
summary through root, field, const, and union refs.
- `packages/durable/test/tool-search.test.ts`: end-to-end load via a
ref'd description; unused definition does not match.

`npm run check` passes.
This commit is contained in:
Petr Houška 2026-11-06 00:19:58 +01:00 • committed by GitHub
parent 850ea2eae2
commit 6d3e342b25
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
12 changed files with 262 additions and 29 deletions

View file

@ -193,6 +193,37 @@ describe("deferred tools and tool_search", () => {
await harness.close(context);
});
// #11803
it("finds a tool by a parameter description behind a local reference, and not by unreferenced definitions", async () => {
const chat = setup();
addTool(
chat.registry,
tool("ledger_inspect", "Inspect records", {
deferred: true,
parameters: {
type: "object",
properties: { options: { $ref: "#/$defs/options" } },
$defs: {
options: { type: "object", properties: { mode: { type: "string", description: "reconciliation" } } },
unused: { description: "forecast" },
},
},
}),
);
chat.faux.setResponses([
call("tool_search", { query: "forecast" }),
call("tool_search", { query: "reconciliation" }, "c2"),
DONE,
]);
const { harness, root } = await openChat(new MemoryStorage(), chat);
await (await root.submit({ type: "input", content: "go" }, context)).wait(context);
expect(toolResultTexts(await allEntries(root))).toEqual([
"No matching tools found.",
"Loaded 1 tool. They are available from your next call:\n- ledger_inspect: Inspect records",
]);
await harness.close(context);
});
it("finds nothing for an unrelated query and loads nothing", async () => {
const chat = setup();
chat.faux.setResponses([call("tool_search", { query: "weather forecast" }), DONE]);