feat(core): skip tools with unknown call template types instead of failing the manual

NI
2mo ago
+156-13

Implements the forward-compatibility rules proposed in
universal-tool-calling-protocol/utcp-specification#64

Behaviour change, measured on this branch against dev at 89a9832:

Manual contentBeforeAfter
one http tool + one tool of an unregistered type0 tools, raises1 tool, one WARNING naming tool and type
the info key from docs/implementation.md's own exampleraises TypeErrorloads; info kept in model_extra and re-emitted by to_dict
x-acme-retry on an http call templateloads, key droppedloads, key kept and re-emitted
call template with no call_template_typeraisesraises (UtcpSerializerValidationError) — unchanged

Four changes:

  1. UtcpUnknownCallTemplateTypeError (new, in utcp.exceptions). A distinct
    type is what makes the skip possible: the manual loader must tell "this
    client has no plugin for that protocol" apart from "this template is
    malformed", and only skip the first. It derives from Exception, not
    ValueError, so pydantic propagates it through the nested Tool validator
    rather than folding it into a ValidationError.
  2. CallTemplateSerializer.validate_dict raises it for an unregistered
    type. The lookup moved out of the try block: previously a KeyError from
    the serializer's own body was misreported as an invalid type, and the
    except KeyError handler itself raised KeyError when
    call_template_type was absent. A missing key is now its own explicit
    error.
  3. UtcpManual gains extra="allow" and loads tools one at a time, warning
    past the unknown ones. Its __init__ now takes **data; the previous
    explicit signature was the actual reason info was rejected — pydantic
    passed the extra key to __init__, which had no parameter for it.
    CallTemplate gains extra="allow" for the same round-trip reason.
  4. ToolSerializer.validate_dict re-raises the new error instead of
    wrapping it, so the manual loader can see it.

Tests: core/tests/data/test_manual_forward_compatibility.py, three cases —
the skip (asserting both the surviving tool and the warning), the round trip of
info and x-, and that a malformed template still fails loudly.

Suite: core 40 passed (37 before + 3 new). Plugin suites
http/text/file/cli: 226 passed, 5 skipped, 61 errors — byte-identical to
the same run on the unmodified tree; those errors are pre-existing
pytest-asyncio fixture-setup failures in this environment, untouched by this
change.

What a reviewer will push back on, and the answer

"Skipping hides provider mistakes." It does not: every skip emits a
WARNING naming the tool and the type, and a malformed template of a known
type still raises. Only the case a client provably cannot handle — a protocol it
has no plugin for — is downgraded from fatal to skipped.

"extra='allow' weakens validation." It weakens it exactly where the spec
change says it should be weak, and nowhere else. Every declared field keeps its
type. The alternative, extra='ignore', would load the manual but silently
delete x- data on rewrite, which is the round-trip failure this PR is fixing.

"This is a breaking change." For callers, no: UtcpManual(**kwargs) accepts
everything it accepted before, and the new exception type is not raised anywhere
a caller previously caught something specific — the old code raised a bare
ValueError wrapped in UtcpSerializerValidationError, which nothing in-tree
catches by type. For manual authors, it only widens what loads.

🤖 Generated with Claude Code

https://claude.ai/code/session_01H9PKfvS16TzzLUHi3xPUV4


Summary by cubic

Makes manual loading forward-compatible by skipping tools with unregistered call template types instead of failing the entire manual. Unknown keys like info and x- extensions are now preserved through load/store round trips.

  • Adds UtcpUnknownCallTemplateTypeError so the loader can tell "no plugin for this protocol" apart from "malformed template".
  • Each skipped tool logs a WARNING naming the tool and its unregistered type.
  • Malformed templates of known types still raise UtcpSerializerValidationError as before.
  • UtcpManual and CallTemplate now allow extra keys, keeping info and x- data intact on rewrite.