feat(core): skip tools with unknown call template types instead of failing the manual
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 content | Before | After |
|---|---|---|
one http tool + one tool of an unregistered type | 0 tools, raises | 1 tool, one WARNING naming tool and type |
the info key from docs/implementation.md's own example | raises TypeError | loads; info kept in model_extra and re-emitted by to_dict |
x-acme-retry on an http call template | loads, key dropped | loads, key kept and re-emitted |
call template with no call_template_type | raises | raises (UtcpSerializerValidationError) — unchanged |
Four changes:
UtcpUnknownCallTemplateTypeError(new, inutcp.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 fromException, not
ValueError, so pydantic propagates it through the nestedToolvalidator
rather than folding it into aValidationError.CallTemplateSerializer.validate_dictraises it for an unregistered
type. The lookup moved out of thetryblock: previously aKeyErrorfrom
the serializer's own body was misreported as an invalid type, and the
except KeyErrorhandler itself raisedKeyErrorwhen
call_template_typewas absent. A missing key is now its own explicit
error.UtcpManualgainsextra="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 reasoninfowas rejected — pydantic
passed the extra key to__init__, which had no parameter for it.
CallTemplategainsextra="allow"for the same round-trip reason.ToolSerializer.validate_dictre-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
UtcpUnknownCallTemplateTypeErrorso the loader can tell "no plugin for this protocol" apart from "malformed template". - Each skipped tool logs a
WARNINGnaming the tool and its unregistered type. - Malformed templates of known types still raise
UtcpSerializerValidationErroras before. UtcpManualandCallTemplatenow allow extra keys, keepinginfoandx-data intact on rewrite.