cordis_define / cordis_inspect_query: object/oneOf tool-call params arrive as raw strings, not parsed objects

[MauricioPerera]

Summary

Model-supplied tool-call parameters whose JSON Schema has no top-level type — i.e. a bare oneOf (like cordis_define's plugin) or a type: "json" annotation (like cordis_inspect_query's input) — arrive at execute() as a raw string instead of a parsed object/array, and are rejected by the argument validator. This makes cordis_define and half of cordis_inspect_query unusable with at least one Ollama-routed cloud model (glm-5.3-flash:cloud).

Repro

1. dsh web profile, Creator mode, model glm-5.3-flash:cloud (via the llm-pi-ai → Ollama openai-completions route).
2. Ask the agent to define any dynamic Cordis plugin (cordis_define) — e.g. the example flow in the cordis-plugin-development skill (plugin: { kind: "new", idPrefix: "clock" }).
3. cordis_define fails every time with:

   invalid arguments: "plugin" must match exactly one oneOf branch (matched 0)
   

   even when the argument object is exactly what the tool's own declared schema requires (verified by reading Tool.listTools's live schema for cordis_define mid-session).
4. Same symptom, different message, for cordis_inspect_query with {"root": "tool.view.cordis"}:

   Client Cordis inspect Slots.listSubTree rejected input: "input" must be an object
   

   — three consecutive identical retries, always the same rejection.

Root cause (verified by reading the installed package, not inferred)

packages/core/tools (installed as @deepseek-ai/dsh-tools@0.1.1-rc.2, lib/index.js), the argument walker/validator (checkValue → case "object" / case "array"):

case "object": {
  if (!isPlainJsonRecord(frame.value)) {
    finish([`"${diagnosticPath(frame.path)}" must be an object`]);
    break;
  }
  ...

By the time this runs, frame.value for the affected parameter is a string containing valid JSON (e.g. "{\"kind\":\"new\",\"idPrefix\":\"clock\"}"), not an object — even though the outer tool-call arguments blob already went through one JSON.parse in dsh-agent-loop's parseArguments(raw). So the model is emitting that specific nested parameter double-encoded (as a JSON string inside the outer JSON), and nothing downstream re-parses it.

The parameters that are affected have one thing in common: they have no top-level type in their model-facing schema — plugin is a bare oneOf (dsh-tool-cordis/lib/index.js, cordis_define's parameters.plugin), input is a type: "json" annotation-only node. Parameters with an explicit type: "object" / type: "array" at the top level (e.g. todo_write's todos) are unaffected — they arrive already parsed. My working theory is that whatever renders/normalizes the parameter schema surfaced to this particular model loses the "this must be a structured value" signal for the no-top-level-type cases, and the model falls back to stringifying it.

Suggested fix (tested locally, works)

Purely defensive, harness-side, and low-risk (only activates on what would otherwise be a guaranteed rejection): when a value destined for an object/array schema position is a string, attempt JSON.parse and use the parsed result if it structurally matches, writing the coerced value back into the parent container (not just a local copy) so the tool's execute(args, ...) actually receives the fixed value, not just a validator-local one.

Two things need patching together, both in lib/index.js's checkValue:

1. The case "object" / case "array" branches themselves (defends the root-argument-is-a-string edge case).
2. The point where child frames are built — the object-properties loop and the array-items loop — since a string value living inside a parent object/array needs the coercion written back onto frame.value[key] / the array slot itself, or the fix only makes validation pass while execute() still receives the original unparsed string.

After applying both, in the same session with the same model:

• cordis_inspect_query with {"root": "tool.view.cordis"} succeeded on the first try (previously failed 3/3).
• cordis_define's plugin argument passed validation (previously failed 100% of attempts with the oneOf error) and reached execute() correctly shaped.

One related but distinct issue found afterward

With the above fixed, cordis_define can still fail with no dynamic plugin "undefined" in this process — it may have been removed or lost on DSH restart on some calls, which traces to dsh-cordis-host-runner treating args.plugin.kind as not "new" at the point it builds the request — even though the tool-layer args.plugin object was, this time, correctly typed. This looks like a separate bug (possibly in how the args cross the tool→runner RPC boundary), not something the argument-coercion fix above addresses. Flagging it here rather than opening a second discussion since it surfaced while reproducing this one and may share a cause once someone with runner-internals context looks at it.

Environment

• @deepseek-ai/dsh 0.1.1-rc.2 (npm global install)
• @deepseek-ai/dsh-tools 0.1.1-rc.2
• Node.js v24.16.0, Windows 11
• Model: glm-5.3-flash:cloud via the llm-pi-ai Ollama route (api: openai-completions, baseURL: http://localhost:11434/v1)
• Also reproduced (inspect-only) with deepseek-v4-pro:cloud on the same route before the fix — the cordis_inspect_query failure was not model-specific.

Happy to share the exact patch diff if useful — kept it out of this report to stay focused on repro + root cause first.

[MauricioPerera]

Second independent confirmation of the "one related but distinct issue" above

Reproduced again, separately, after the fix from the main report was applied and the dsh process was restarted (so the fix was verifiably loaded — patched file confirmed still on disk, and the running process necessarily re-read it from disk on boot; there is no build cache in the way for a plain Node ESM lib/index.js).

• 2 cordis_define attempts, two different argument encodings, plugin: { "kind": "new", "idPrefix": "clock" } in both.
• Schema validation passed both times — no oneOf error at all (confirms the argument-coercion fix from the main report is effective).
• Both attempts failed deterministically inside execute with the same error as before:

  Error: no dynamic plugin "undefined" in this process — it may have been removed or lost on DSH restart
  

• cordis_inspect_self after each failure showed plugins: [] — the runner's registry never got a mint, so no garbage/orphaned state either time.

Traced independently to the same spot flagged above: dsh-tool-cordis's execute (~L7290) computes args.plugin.kind === "new" ? {...} : {kind:"existing", pluginId: CordisDynamicPluginId(args.plugin.pluginId)}, and dsh-cordis-host-runner's define (~L1614-1626) throws exactly this message when it receives kind !== "new" with an undefined pluginId. Since the tool-layer argument is confirmed well-formed post-fix (validation matches exactly one oneOf branch), whatever is losing the kind: "new" shape happens between the tool's execute() and the runner receiving the request — most likely the transport/RPC boundary between the two (dsh-cordis-host-runner reads like it hosts the dynamic-plugin sandbox out of process), not the argument schema/validator this report's fix touches.

Not something we could resolve from the calling side — flagging as confirmed-reproducible for whoever has context on that boundary.

[nokkies]

Confirmed the mechanism, with one correction to the framing that changes where a fix belongs.

The top-level arguments are parsed — the gap is per-property

parseArguments in the agent loop parses the whole argument string before anything else sees it:

function parseArguments(raw: string): unknown {
  try { return raw ? JSON.parse(raw) : {} } catch { return raw }
}

So plugin does not arrive as a string because parsing was skipped. It arrives as a string because the model emitted {"plugin": "{\"kind\":\"new\",…}"} — a JSON string as the property value, rather than a nested object. One JSON.parse correctly yields a string there, and the validator then correctly rejects it against a oneOf of object branches.

That distinction matters: the validator is not wrong, and neither is the parse. What is missing is any tolerance for a model that stringifies nested values.

I checked for that tolerance and there is none anywhere in the path — json-schema.ts contains no JSON.parse at all, and the only string handling is case 'string': return typeof value === 'string'. So there is no coercion layer to fix; there is only the question of whether to add one.

Why your two symptoms differ

They are the same cause at different layers, which is why the messages do not match:

• cordis_define's plugin is validated by the shared argument walker, so you get its oneOf diagnostic.
• cordis_inspect_query's input is validated by the inspect provider's own check, which is why that one says "input" must be an object instead.

Anything that adds coercion has to cover both, or you will fix half of what you reported and the other half will look unchanged.

The design question, stated honestly

Coercion is not free. "If the schema wants an object and the value is a string that parses as JSON, parse it" would fix your case, and it would also silently accept a genuinely wrong argument whenever a model passes a JSON-looking string where a string was meant. A tool whose parameter is legitimately type: "string" and happens to receive "{\"a\":1}" must keep it as text — so any coercion must be gated on the declared shape, not attempted opportunistically.

The narrow version that seems defensible: coerce only when no branch of the declared schema accepts a string and the value parses to something that does. That keeps a real string parameter untouched, because a string branch exists and matches first. A bare oneOf of object branches, or an object-only annotation, is exactly the case where the string can only be a mistake.

Worth noting the schemas you hit are the ones most likely to trigger it — a property with no top-level type gives the model the least signal that a nested object is wanted, so it falls back to the shape it is surest about. That is an argument for declaring type on those schemas as well, independent of any coercion, since it fixes the cause rather than the symptom for models that respect it.

(Version check worth doing regardless: type: "json" is not something json-schema.ts recognises as a type, so if that annotation is reaching the shared walker rather than a provider-local check, that is a separate bug from the one you are describing.)

[denial123789]

I checked the rc.2 source and agree with the correction already made above: the outer call is parsed once, and the shared validator is correctly rejecting the value it receives.

agent-loop/src/tool-calls.ts does:

return raw ? JSON.parse(raw) : {}

So {"plugin":"{...}"} becomes an object with a string property. In core/tools/src/json-schema.ts, checkValue() is a pure traversal: oneOf runs every branch over that same string, and an object branch rejects it before visiting properties. There is no validator-local coercion, which is the safer default.

I would keep three repairs separate:

1. Schema modeling: use type: json only when a string, scalar, array, or object is genuinely legal. If an object is required, declare an object. For oneOf, each branch owns its explicit type; a sibling type beside oneOf is outside this enforced subset.
2. Compatibility normalization: if the Harness chooses to tolerate double encoding, do it before validation in a dedicated stage, never by mutating the validator frame. Normalize only when the declared node has no string-accepting branch, the string parses within size/depth limits, and the parsed value matches exactly one branch. Preserve the raw call and record that coercion occurred.
3. Runner/RPC shape loss: if shared validation passes with {kind:"new"} and a later boundary receives kind !== "new" or pluginId: undefined, that is an independent transport defect. More coercion at the tool boundary would hide it. Capture the normalized execute input and the exact runner request on both sides of the crossing.

The critical invariant is that presentation, human approval, validation, and execution all use the same normalized argument identity. Otherwise a user can approve one visible value while a different value executes.

We published the full normalization gates and regression matrix here:

https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/plugin-development/tool-schema-subset.md#route-double-encoded-structured-arguments-before-coercing-them

Pinned source: tool-calls.ts and json-schema.ts.

[MauricioPerera]

Thanks both — this is a real correction, not just confirmation, and I want to flag where I agree rather than let it read as settled.

Agreeing with the refinement

@nokkies is right that the fix I described is broader than it should be. My patch coerces a string-to-object whenever the schema has no top-level type, with no check for whether a string branch already exists. The narrower condition — coerce only when no branch of the declared schema accepts a string — is strictly better: it fixes the exact failure mode I hit without opening a hole for a legitimately-string parameter that happens to look like JSON. I did not implement or test that narrower condition; my patch is the blunter version, and it should not be read as the final shape of a fix, just evidence that the failure mode is real and coercion (correctly scoped) resolves it.

Agreeing on where it should live

@denial123789's point about not mutating the validator frame in place is also a fair critique of what I actually shipped — I did exactly that (mutate frame.value[key] during the walk) because it was the smallest change that produced observable proof the theory was correct, not because I thought it was the right permanent shape. A dedicated normalization stage before validation, that preserves the raw call for audit/approval-consistency purposes, is the right design — I just didn't build that; I built the minimum reproducer.

What I can't currently verify

I don't have a env set up right now to test the narrower "no string branch" condition against both the cordis_define and cordis_inspect_query cases, or to confirm whether type: "json" reaching the shared walker (vs. a provider-local check) is in fact a second bug as suspected. Flagging that gap rather than claiming it's covered.

One correction of my own: the linked handbook page (sandbaseai...github.io/.../tool-schema-subset#route-double-encoded-structured-arguments-before-coercing-them) 404s for me, and the site's own front page states it tracks source revision "rc.8" — the actual installed version in every repro in this thread (mine and the two above) is 0.1.1-rc.2. Not vouching for or against the content, just noting the specific anchor doesn't resolve and the version claim doesn't match what any of us actually ran, so I'd treat it as unverified rather than as a source.