[bug] cordis_define: typeless plugin parameter schema makes the web client stringify the object argument

[kataguru]

[bug] cordis_define: typeless plugin parameter schema makes the web client stringify the object argument

Merged draft — evidence consolidated by AICORE (Linux) + JKDTPC (Windows), 2026-09-03. E2E validation completed 2026-09-04 (§ Evidence 5-7).

Environment

• @deepseek-ai/dsh 0.1.1-rc.2 (npm install), observed on Windows 11 (dsh web process, dsh web --patch …, GUI on :3080), Node v24.13.0 (npm-installed CLI); package contents cross-checked on Linux (AICORE) — identical dsh-tool-cordis file on both machines
• File: node_modules/@deepseek-ai/dsh-tool-cordis/lib/index.js, md5 cf9d4cf4096378c1c14e6aa5343247d9 (unpatched, identical on both machines)

Symptom

Calling the cordis_define tool from a session in the dsh web process (web GUI :3080) with a fully-formed argument object fails:

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

args.plugin arrives at the host as a string (the JSON object serialized), so neither oneOf branch (both declare type: "object") matches. Expected: plugin arrives as an object and the define succeeds.

Observed 2026-08-31, documented baseline: messaging-wake-bridge-SETUP.md (JKDTPC machine).

Root cause

The tool's parameter schema declares the parameter without a top-level type:

parameters: {
    plugin: {
        required: true,
        oneOf: [{ type: "object", additionalProperties: false, ... }, { ... }],
    },
    ...
}

(dsh-tool-cordis/lib/index.js, cordis_define tool definition, ~line 7189.)

Because the parameter carries no type, the web client's tool-call serialization stringifies the argument before it reaches the host. The host-side validator then — correctly — rejects the string against the object-only oneOf branches (validator: @deepseek-ai/dsh-tools/lib/index.js line 417, must match exactly one oneOf branch (matched ${frame.matches})). The validator behaves as designed; the typeless schema is the trigger.

Evidence

1. Baseline (before fix): web-process call with a valid object → verbatim error above; args.plugin = string. Neither oneOf branch matched.
2. Control A: cordis.yml composition rows load normally in the same process — the defect is isolated to the dynamic tool-call path, not a wholesale schema-file breakage.
3. Control B (independent machine, Linux, identical package md5): cordis_define from a non-web session succeeds with an object plugin argument (probe plugin defined and then removed). The defect does not manifest on the session/loopback path — it is specific to the web client's argument serialization.
4. Fix applied locally: one line, node --check passes. E2E validation followed (next items).
5. E2E validation (2026-09-04, after dsh web restart, Windows): cordis_define called via the runtime API in the web process with plugin as a well-formed object — define succeeded (3 test plugins defined; acceptance criteria met: plugin arrives as an object, arity preserved, string arguments to other parameters not regressed). Patched schema validation still correctly rejects invalid idPrefix values (non-letter characters, >6 characters) — the added line did not weaken validation.
6. Patch-loss recurrence (natural, same session): an npm update had silently overwritten node_modules and removed the patch before the validation run — re-applying the one-liner restored md5 21966A07066E0786F43ACD88F124F2B9. This demonstrates in practice why an upstream schema fix is the durable solution: local patches do not survive package updates.
7. Rollback leg: the backup was restored to disk, the patch re-applied, and the final md5 verified before the manifest update. Note: the web process keeps the loaded module in memory until restart, so an in-process negative test (patch absent while running) was not executed; the unpatched failure mode is documented from the original incident (2026-08-31 baseline) and its recurrence condition was observed in practice during item 6.

Proposed fix

Add the missing type so every client path serializes the argument as an object:

 			plugin: {
+				type: "object",
 				required: true,
 				oneOf: [{
 					type: "object",
 					additionalProperties: false,

md5 of lib/index.js: before CF9D4CF4096378C1C14E6AA5343247D9 → after 21966A07066E0786F43ACD88F124F2B9 (verified on the local Windows installation).

Notes

• The same schema file uses boolean required: true inside property schemas (nonstandard JSON Schema, but accepted by the host validator). The actionable defect here is only the missing type on plugin.
• Audit note: in dsh-tool-cordis 0.1.1-rc.2 this was the only top-level oneOf parameter; tools elsewhere in the broader schema dialect should be checked for the same missing parameter-level type.
• The local patch is temporary — npm update overwrites node_modules. An upstream schema fix is the durable solution.
• File upstream: deepseek-ai/deepseek-harness (per package.json → repository, directory apps/cli); the defect lives in the @deepseek-ai/dsh-tool-cordis package.

Requested upstream action

1. Add parameter-level type: "object" alongside oneOf in the schema dialect handling (or teach the web-process adapter to coerce/parse typeless oneOf parameters).
2. Confirm whether the adapter should ever pass stringified objects for typed object parameters.

[argszero]

Great report — the root cause is correct and the E2E evidence (both Windows and Linux, same package md5, controls A/B) is solid. I dug into the source and found an important nuance about the fix that I think changes the shape of it.

The reporter's "one line: add type: 'object'" fix would be rejected by the author-time schema validator.

cordis_define is defined via defineTool (from @deepseek-ai/dsh-tools), and its parameter spec is compiled by the schema authoring layer in packages/core/tools/src/schema.ts. That layer explicitly forbids a node declaring both type and oneOf:

// schema.ts ~line 342 (author-time validation)
if (Object.hasOwn(input, 'type')) authorError(`${path} cannot declare both type and oneOf`)

So adding type: 'object' alongside the existing oneOf (as your fix does) would make the tool definition fail to load with cannot declare both type and oneOf, not silently succeed. This is tested in packages/core/tools/tests/json-schema.spec.ts:94 (expect(...).toEqual(['schema cannot declare both type and oneOf'])).

The runtime error you hit (must match exactly one oneOf branch) comes from a different file — json-schema.ts:523 — and it correctly rejects the stringified arg. Both layers are behaving as designed; the friction is that the tool spec's plugin param is forced into the oneOf-without-type shape by the authoring invariant.

Because type + oneOf is forbidden, the fix has to remove the oneOf from that level or move the discrimination elsewhere. Two viable shapes:

1. Single type: 'object' with a discriminated kind — merge the two oneOf branches into one object schema whose kind is a const-constrained enum (already how the branches are shaped), then keep the type: 'object' that the client serialization needs. This preserves the object argument the web client currently stringifies.

2. Fix the client serialization — the deeper question: the web client stringifies an argument when its schema declares no top-level type (the typeless oneOf case). If the client is expected to handle oneOf-typed params at all, this is the more general bug (any future oneOf-only object param hits the same stringify). But it's a client-side change, so it might be a bigger surface than this one tool.

My read: option 1 (reshaping the param to avoid top-level oneOf) is the smallest end-to-end fix that keeps your E2E-acceptance criteria (object arrives as an object, arity preserved, no regression on string args) and stays within the authoring invariant. If you want, I can sketch the concrete schema change.

One further note: plugin is the only oneOf-bearing parameter across tool-cordis's tools, so this is isolated — no other tool shares the latent shape. Worth a regression test at the schema.spec.ts/json-schema.spec.ts level asserting a oneOf-only object param round-trips through the client serialization.

[kataguru]

E2E validation — extended test matrix (2026-09-04, JKDTPC Windows, DSH 0.1.1-rc.2, Node v24.13.0)

After the initial 3-plugin E2E (§ Evidence 5 in the main report), a final consolidated run extended the matrix:

Accepted (plugin arrives as OBJECT, validation intact): test-4/pkg-4, test-5/pkg-5, testt-6, xyz-7, abcd-8, eabe-9, eabc-10 (7 cases) — args.plugin.kind = "new" recognized, arity preserved, string arguments to other parameters not regressed.

Rejected as expected (idPrefix regex /^[a-z]{3,6}$/ intact): e2etest (7 letters > limit), e2e/e2et/e2ab/e2e2/ze2z/test2 (contain digits).

Rollback leg: backup (CF9D4CF4096378C1C14E6AA5343247D9) verified on disk, diff CF9D4CF4 → 21966A07066E0786F43ACD88F124F2B9 proven, final md5-verify before manifest write. In-process negative not executed: the Node module cache does not reload from disk in a running process, and killing the web process mid-session was out of scope — the unpatched failure mode is covered by the 2026-08-31 baseline (§ Evidence 1) and its recurrence during the npm-overwrite incident (§ Evidence 6).

Negative result: NONE — patch active and functional.

[kataguru]

Re: maintainer feedback — local adoption + incident note (fixed form verified)

Thank you — the author-time type+oneOf invariant explanation makes complete sense, and it surfaced something important on our side: our interim local fix (adding type: "object" next to the existing oneOf, file md5 21966A07066E0786F43ACD88F124F2B9) would have crashed the entire dsh-tool-cordis module at load on the next maintenance restart, not just cordis_define. We adopted your option-1 form locally before any further restarts:

• Option-1 applied (Windows, verified): merged single type: "object" schema with kind enum discriminator ["new","existing"]; conditional per-kind requirements handled as handler guards (no if/then/else in dialect). node --check OK, require-load OK.
• Validation results with the merged schema: combined schema loads; valid object args pass for both kinds; string args rejected cleanly ('plugin' must be an object); unknown kind → enum error; kind:"new" without idPrefix → handler guard.
• E2E conclusions from our earlier runs are unchanged: object arrives as object, arity preserved, no string-arg regression — the E2E at the next maintenance restart now validates the option-1 form.
• Warning propagated to our fleet: do not apply the interim +1-line fix anywhere; the unpatched baseline (CF9D4CF4096378C1C14E6AA5343247D9) is a safe state. Other fleet machines stay unpatched until the upstream fix lands.

Original report content stands (root cause: typeless plugin parameter made the web client stringify the object argument); only the fix form is superseded per your option-1.