A hand-rolled register() with an output schema outside the SCHEMA_TYPES whitelist loads as a plugin with ZERO tools, and logs nothing (console.warn never called) - 0.2.0-rc.2

[LUgABeEEE]

Summary

A plugin whose tool output schema is invalid mounts successfully, registers zero tools, and prints nothing. Two separate behaviours combine into that dead end:

1. register() surfaces a contract violation only through the cordis logger, so on a normal deployment there is no visible error — measured console.warn invocations: 0.
2. The most natural authoring mistake — output: { schema: { type: 'json' } } — is not in the output whitelist (SCHEMA_TYPES, dsh-tools/lib/index.js:50-58), while the same 'json' sentinel is accepted on the valueSchemaSpec path that defineTool uses (:688-691, compiled to {} at :849). An author who hand-rolls register (instead of defineTool) therefore walks into it with no feedback at all.

Reproduction (measured on 0.2.0-rc.2, not inferred)

Running the same plugin under a real cordis Context + real ToolRuntime + SystemPrompt:

variant	ctx.tools.schemas()	warnings	console.warn calls
baseline (4 tools with { type: 'json' } output)	0 tools	0	0
after replacing those 4 schemas with {}	4 tools	0	—

Direct calls against the exported validators:

assertSupportedJsonSchema({ type: 'json' })
// throws: unsupported JSON schema: schema.type must be one of object/array/string/number/integer/boolean/null
valueSchemaSpecToJsonSchema({ type: 'json' })  // => {}
assertSupportedJsonSchema({})                  // accepted

Call chain in the current tree: SCHEMA_TYPES has no json (:50-58) → the violation is recorded (:236-237) → assertSupportedJsonSchema throws (:323-327) → register() calls it at :2882, after forcing an output with both schema and render (:2881) → the throw is caught and logged, never rethrown.

Why I think this is worth a change on the host side

The failure mode is silent by construction. The plugin appears in the loaded set, the tool list is simply empty, and there is nothing to grep for. In our case it survived a package with 282 passing tests — because those tests use a lenient hand-rolled register stub that never validates output.schema. So neither the author's logs nor the author's CI can see it.

From reading the code, the try/catch in register() looks intended to tolerate things like duplicate tool names. A schema-contract violation is a different class of problem and currently disappears into the same path.

Possible directions (author's opinion only — you know the design intent better)

1. Surface it where a human will see it. Even if registration stays tolerant, a contract violation could increment a load-diagnostics counter or appear in a startup summary, so a plugin that registered 0 tools is not indistinguishable from a plugin with no tools.
2. Accept 'json' on the output path too, for parity with the valueSchemaSpec path — or, if that is deliberately not wanted, make the thrown message name the working alternative (output: { schema: jsonValueOutputSchema(), render }) explicitly, so the error teaches the fix.
3. If neither, document loudly that a hand-rolled register() must produce a whitelist-compliant output.schema, and that a violation yields a silently tool-less plugin.

A note that helped us on the plugin side

Reusing the host's exported assertSupportedJsonSchema inside plugin tests catches this in CI in one line. A stub register that accepts anything makes a whole suite blind to the host contract — that is how the 282 green tests happened.

Happy to file a minimal reproduction repo if that is useful. Everything above was measured on 0.2.0-rc.2 with a real (not stubbed) runtime.

---

Context: found while integrating a third-party plugin bundle (ERD/data-modelling tools) from a scaffold into a web profile; four of its tools were silently absent until the output schemas were fixed. The same pattern was then checked across the other plugins in that bundle.

[argszero]

Confirmed on both counts — but direction 2 would break the layer it aims to fix

Thank you for measuring rather than inferring; the chain reproduces from the source on master (86a402200d).

Your chain is right. SCHEMA_TYPES is ['object','array','string','number','integer','boolean','null'] (packages/core/tools/src/json-schema.ts:87) — no json — and the violation is raised at :303-306. register() calls assertSupportedJsonSchema(output.schema) at packages/core/tools/src/index.ts:1079, having first rejected a missing render (:1074-1078). So register really does throw; the swallow is outside it — a throwing plugin apply is caught by cordis's fiber and routed to context.logger.error (vendor/cordis/src/fiber.ts:129-134), and whether that reaches a human belongs to the deployment's exporters. On a deployment with no sink at that level the plugin mounts, registers nothing, and says nothing. That is the "silent by construction" you describe.

But the two paths are not two spellings of one check — they are two layers, and the json sentinel's job is to compile into what the raw validator accepts. assertSupportedJsonSchema validates a raw node: its docstring calls it "One raw JSON Schema node in the enforced subset … the external wire schema" (json-schema.ts:26-30). valueSchemaSpecToJsonSchema takes the author-facing spec and compiles it (schema.ts:438-442). And the documented result of compiling { type: 'json' } is the annotation-only schema — json-schema.ts:380-382: "Annotation-only schemas are accepted as the standard unconstrained-JSON form", with JsonSchemaNode.type itself documented as "Omit with no constraints for any JSON value" (:31-33).

So { type: 'json' } compiling to {} is not a discrepancy to be levelled up; it is the sugar and its expansion. Adding json to SCHEMA_TYPES (direction 2) would put a keyword that does not exist in JSON Schema into the table that is the wire schema — the very table assertSupportedJsonSchema exists to enforce.

What that means for your three directions:

1. Direction 1 stands, and it is the one I would take. Registration already treats a contract violation as a throw rather than as the tolerated-duplicate case, so the two classes are distinguishable at that call site — a counter or startup line for "N tools refused at registration" is enough to separate a zero-tool plugin from a plugin with no tools, which is the whole class you hit.
2. Direction 2 is the wrong lever, but its second half is right and cheap. The thrown message should name the working alternative: one clause saying the unconstrained form is {} turns this from a long hunt into a one-line fix. (There is no jsonValueOutputSchema() helper to point at — I looked; the equivalent really is the literal {}.)
3. I would add a third: one sentence on the ToolDefinition.output docstring saying that a hand-rolled definition supplies an already-compiled schema, so the author-facing sugar on the defineTool path is not available to it. That single fact would have prevented this entire report.

Your last section is the most valuable part, and I would underline it: reusing the host's assertSupportedJsonSchema in plugin tests is the right call, and the deeper lesson is that hand-rolling register means re-implementing a compile step whose existence is invisible from the ToolDefinition type. defineTool is exported too, so a test can go through the real path and catch this class in one line instead of validating a stub — a stub register that accepts anything is exactly how 282 green tests and a tool-less plugin coexist.

One adjacent note, honestly scoped: the "mounted but silently inert" shape has a partial relative in the ecosystem — a plugin that is installed but never reaches the loaded set is what the activation-doctor style check watches (internal/status, profile bundles). It does not cover your case: your plugin loaded, it just registered nothing. That half is the registration-refusal counter above.