Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
fix(py): resolve $ref/$defs so file flags behind a reference aren't dropped (#3653)
Alberto Schiabelaeeb471c6341
diff --git a/python/composio/core/models/_files.py b/python/composio/core/models/_files.pyindex 57f1d0ae7..35985c5a8 100644--- a/python/composio/core/models/_files.py+++ b/python/composio/core/models/_files.py@@ -24,6 +24,7 @@ from composio.exceptions import (SDKFileNotFoundError,)from composio.utils import mimetypes+from composio.utils.json_schema import dereference_json_schemafrom composio.utils.sensitive_file_upload_paths import (assert_safe_local_file_upload_path,)@@ -813,10 +814,23 @@ class FileHelper(WithLogger):Should only be called when the caller opted in via`dangerously_allow_auto_upload_download_files=True`.Recursively handles anyOf, oneOf, allOf, nested properties, and array items.++ ``$ref``/``$defs`` indirection is inlined first so file_uploadable flags+ reachable only through a reference are visible to the transform below+ (https://github.com/ComposioHQ/composio/issues/3506). Tool schemas come+ from the API, which may emit a ``$ref`` without a ``$defs`` block+ (https://github.com/ComposioHQ/composio/issues/3307); ``"sentinel"``+ degrades that gracefully instead of raising."""- if "properties" not in schema:+ resolved = dereference_json_schema(schema, on_unresolved="sentinel")+ if "properties" not in resolved:return schema+ # Preserve the original object's identity (callers such as+ # ``process_schema_recursively`` mutate in place) while adopting the+ # dereferenced, ``$defs``-stripped shape.+ schema.clear()+ schema.update(resolved)schema["properties"] = {key: self._transform_schema_for_file_upload(prop)for key, prop in schema["properties"].items()@@ -1042,7 +1056,12 @@ class FileHelper(WithLogger):"""return self._substitute_file_uploads_recursively(tool=tool,- schema=tool.input_parameters,+ # Inline $ref/$defs once at the boundary so the walker sees+ # file_uploadable flags hidden behind a reference. Non-mutating:+ # ``tool.input_parameters`` is left untouched.+ schema=dereference_json_schema(+ tool.input_parameters, on_unresolved="sentinel"+ ),request=request,before_file_upload=before_file_upload,)@@ -1160,7 +1179,13 @@ class FileHelper(WithLogger):"ToolExecutionResponse",self._substitute_file_downloads_recursively(tool=tool,- schema=tool.output_parameters,+ # Inline $ref/$defs once at the boundary so the walker sees+ # file_downloadable flags hidden behind a reference (e.g.+ # GMAIL_GET_ATTACHMENT). Non-mutating: ``tool.output_parameters``+ # is left untouched.+ schema=dereference_json_schema(+ tool.output_parameters, on_unresolved="sentinel"+ ),request=t.cast(dict, response),),)diff --git a/python/composio/exceptions.py b/python/composio/exceptions.pyindex c8c124834..91bdf8d61 100644--- a/python/composio/exceptions.py+++ b/python/composio/exceptions.py@@ -79,6 +79,25 @@ class ValidationError(ComposioError):pass+class JSONSchemaRefResolutionError(ValidationError):+ """Raised when an internal JSON Schema ``$ref`` cannot be inlined.++ Covers malformed pointers, missing ``$defs``/``definitions`` targets+ (strict mode only), and ``$ref`` chains or node nesting that exceed the+ safety caps in :func:`composio.utils.json_schema.dereference_json_schema`.+ """++ def __init__(+ self,+ message: str,+ *args: t.Any,+ meta: t.Optional[t.Dict[str, t.Any]] = None,+ delegate: bool = False,+ ) -> None:+ super().__init__(message, *args, delegate=delegate)+ self.meta = meta or {}++class ToolkitError(ComposioError):passdiff --git a/python/composio/utils/json_schema.py b/python/composio/utils/json_schema.pynew file mode 100644index 000000000..0dc4ab559--- /dev/null+++ b/python/composio/utils/json_schema.py@@ -0,0 +1,257 @@+"""Inline internal JSON Schema ``$ref`` pointers.++Python counterpart of the TypeScript SDK's ``dereferenceJsonSchema``+(``ts/packages/core/src/utils/jsonSchema.ts``). Hand-rolled schema walkers in+the SDK (e.g. the file-upload/download substitution in+:mod:`composio.core.models._files`) recurse through ``properties``/``anyOf``/+``oneOf``/``allOf``/``items`` but do not dereference ``$ref``. The Composio API+emits tool parameter schemas with ``$ref``/``$defs`` indirection (``GMAIL_GET_+ATTACHMENT`` is the canonical shape), so a ``file_uploadable``/``file_+downloadable`` flag reachable only through a reference is silently missed.++Resolving references *once* at the boundary — rather than teaching every walker+to dereference — keeps the walkers reference-agnostic and gives all of them+``$ref`` support for free, including keywords they never special-cased+(``additionalProperties``, ``patternProperties``, ``prefixItems``, ``not``, …),+because :func:`dereference_json_schema` walks containers reflectively.+"""++from __future__ import annotations++import typing as t++from composio.exceptions import JSONSchemaRefResolutionError+from composio.utils.logging import get as get_logger++logger = get_logger()++# A ``$ref`` chain longer than this, or object nesting deeper than this, is+# treated as pathological (cyclic data, a billion-laughs-style schema) and+# raises rather than exhausting the interpreter's recursion limit. The caps+# fire in both strict and lenient modes — leniency applies to *unresolvable*+# refs, not to runaway expansion.+MAX_REF_CHAIN_DEPTH = 100+MAX_NODE_DEPTH = 512++# In-band hint attached to the sentinel when lenient mode stands in for an+# unresolvable ``$ref``. Makes the degradation visible to an LLM reading the+# schema instead of leaving it a bare permissive object. Overridden by a+# caller-provided ``description`` sibling (Draft 2020-12 sibling-keyword merge).+UNRESOLVED_REF_DESCRIPTION = (+ "Schema shape unresolved at the source — validate loosely. "+ "See https://github.com/ComposioHQ/composio/issues/3307."+)++# Strategy when an internal ``$ref`` cannot be resolved.+# - ``"throw"`` (default): raise ``JSONSchemaRefResolutionError``. Right for+# first-party / custom-tool schemas where a dangling ``$ref`` is a bug.+# - ``"sentinel"``: replace the node with a permissive object. Right for+# schemas from an upstream service the caller cannot edit (the Composio API+# ships some ``output_parameters`` with a ``$ref`` into ``#/$defs/...`` but no+# ``$defs`` block — see https://github.com/ComposioHQ/composio/issues/3307).+UnresolvedRefStrategy = t.Literal["throw", "sentinel"]+UnresolvedRefReason = t.Literal["missing-target", "malformed-pointer"]++# Callback invoked once per replaced node in ``"sentinel"`` mode.+OnReplace = t.Callable[[str, "UnresolvedRefReason"], None]+++def _cycle_break_sentinel() -> t.Dict[str, t.Any]:+ """A fresh permissive object used to break cycles / stand in for danglers."""+ return {"type": "object", "additionalProperties": True}+++def _is_mapping(value: t.Any) -> bool:+ return isinstance(value, dict)+++def _decode_pointer_segment(segment: str) -> str:+ # Order matters: ``~01`` must decode to ``~1`` (literal), not ``/``.+ return segment.replace("~1", "/").replace("~0", "~")+++class _Resolution(t.NamedTuple):+ ok: bool+ value: t.Any = None+ reason: t.Optional[UnresolvedRefReason] = None+ failed_at: t.Optional[str] = None+++def _try_resolve_pointer(root: t.Dict[str, t.Any], pointer: str) -> _Resolution:+ """Walk a local JSON Pointer (``#/a/b/0``) against ``root``.++ Returns a tagged result so the caller can distinguish a malformed pointer+ from a structurally valid pointer whose target is absent.+ """+ if pointer in ("#", ""):+ return _Resolution(ok=True, value=root)+ if not pointer.startswith("#/"):+ return _Resolution(ok=False, reason="malformed-pointer")++ cursor: t.Any = root+ for raw_segment in pointer[2:].split("/"):+ segment = _decode_pointer_segment(raw_segment)+ if isinstance(cursor, list):+ try:+ index = int(segment)+ except ValueError:+ return _Resolution(ok=False, reason="missing-target", failed_at=segment)+ if index < 0 or index >= len(cursor):+ return _Resolution(ok=False, reason="missing-target", failed_at=segment)+ cursor = cursor[index]+ elif isinstance(cursor, dict):+ if segment not in cursor:+ return _Resolution(ok=False, reason="missing-target", failed_at=segment)+ cursor = cursor[segment]+ else:+ return _Resolution(ok=False, reason="missing-target", failed_at=segment)+ return _Resolution(ok=True, value=cursor)+++def _raise_resolution_error(pointer: str, resolution: _Resolution) -> t.NoReturn:+ if resolution.reason == "malformed-pointer":+ raise JSONSchemaRefResolutionError(+ f"Unsupported $ref pointer: {pointer}",+ meta={"ref": pointer},+ )+ meta: t.Dict[str, t.Any] = {"ref": pointer}+ if resolution.failed_at is not None:+ meta["failed_at"] = resolution.failed_at+ raise JSONSchemaRefResolutionError(+ f"Cannot resolve $ref {pointer}",+ meta=meta,+ )+++def dereference_json_schema(+ schema: t.Any,+ *,+ on_unresolved: UnresolvedRefStrategy = "throw",+ on_replace: t.Optional[OnReplace] = None,+) -> t.Any:+ """Inline internal ``$ref`` pointers (``#/$defs/...`` and legacy+ ``#/definitions/...``), returning a new schema; the input is never mutated.++ External refs (``http://``, ``https://``, …) are left untouched (and logged+ once for audit, since a downstream resolver fetching them could enable SSRF+ or local-file disclosure). Cycles — both ``$ref`` cycles and JS-object-style+ identity cycles — are broken with a permissive ``{"type": "object",+ "additionalProperties": True}`` sentinel. ``$defs``/``definitions`` are+ stripped from the returned root once everything is inlined.++ :param on_unresolved: see :data:`UnresolvedRefStrategy`.+ :param on_replace: invoked once per replaced node in ``"sentinel"`` mode,+ with the original pointer and the reason it could not be resolved.+ :raises JSONSchemaRefResolutionError: on malformed pointers or missing+ targets (strict mode only), or chains/nesting past the safety caps+ (both modes).+ """+ if not _is_mapping(schema):+ return schema++ root = t.cast(t.Dict[str, t.Any], schema)+ # Identity-based cycle guard for the *current* walk path. Python doesn't+ # suffer JS-style prototype pollution, so unlike the TS port there's no+ # need to filter ``__proto__``/``constructor`` keys while cloning.+ visiting: t.Set[int] = set()++ # ``walk`` uses explicit loops (not comprehensions) so each level of schema+ # nesting costs exactly one Python stack frame. That keeps ``MAX_NODE_DEPTH``+ # the binding limit under the interpreter's default recursion ceiling, so a+ # pathologically deep schema fails with our typed error rather than a bare+ # ``RecursionError`` (which is also caught at the call site as a backstop).+ def walk(+ node: t.Any,+ visited_refs: t.FrozenSet[str],+ chain_depth: int,+ node_depth: int,+ ) -> t.Any:+ if node_depth >= MAX_NODE_DEPTH:+ raise JSONSchemaRefResolutionError(+ f"JSON Schema node depth exceeded cap ({MAX_NODE_DEPTH})"+ )++ if isinstance(node, list):+ node_id = id(node)+ if node_id in visiting:+ return _cycle_break_sentinel()+ visiting.add(node_id)+ try:+ cloned_list: t.List[t.Any] = []+ for item in node:+ cloned_list.append(+ walk(item, visited_refs, chain_depth, node_depth + 1)+ )+ return cloned_list+ finally:+ visiting.discard(node_id)++ if not _is_mapping(node):+ return node++ node_id = id(node)+ if node_id in visiting:+ return _cycle_break_sentinel()+ visiting.add(node_id)+ try:+ ref = node.get("$ref")+ ref = ref if isinstance(ref, str) else None++ # External refs and non-``$ref`` nodes both pass through the same+ # reflective clone path.+ if ref is None or not ref.startswith("#"):+ if ref is not None:+ logger.warning("Leaving external $ref untouched: %s", ref)+ cloned: t.Dict[str, t.Any] = {}+ for key, value in node.items():+ cloned[key] = walk(value, visited_refs, chain_depth, node_depth + 1)+ return cloned++ if chain_depth >= MAX_REF_CHAIN_DEPTH:+ raise JSONSchemaRefResolutionError(+ f"JSON Schema $ref chain exceeded depth cap "+ f"({MAX_REF_CHAIN_DEPTH}): {ref}",+ meta={"ref": ref},+ )+ if ref in visited_refs:+ return _cycle_break_sentinel()++ resolution = _try_resolve_pointer(root, ref)+ if resolution.ok:+ target: t.Any = resolution.value+ elif on_unresolved == "sentinel":+ if on_replace is not None and resolution.reason is not None:+ on_replace(ref, resolution.reason)+ target = {+ **_cycle_break_sentinel(),+ "description": UNRESOLVED_REF_DESCRIPTION,+ }+ else:+ _raise_resolution_error(ref, resolution)++ next_refs = visited_refs | {ref}+ resolved = walk(target, next_refs, chain_depth + 1, node_depth + 1)++ # Shallow-merge sibling keywords next to ``$ref`` (Draft 2020-12:+ # siblings win on collision). Draft 7 ignores them, but the Composio+ # tool surface admits both, so we honor siblings for safety.+ siblings = {key: value for key, value in node.items() if key != "$ref"}+ if not siblings or not _is_mapping(resolved):+ return resolved+ merged = dict(resolved)+ for key, value in siblings.items():+ merged[key] = walk(value, visited_refs, chain_depth, node_depth + 1)+ return merged+ finally:+ visiting.discard(node_id)++ try:+ out = walk(root, frozenset(), 0, 0)+ except RecursionError as exc: # pragma: no cover - depth cap normally fires first+ raise JSONSchemaRefResolutionError(+ "JSON Schema nesting too deep to dereference"+ ) from exc+ if _is_mapping(out):+ out.pop("$defs", None)+ out.pop("definitions", None)+ return outdiff --git a/python/tests/test_files.py b/python/tests/test_files.pyindex 15b399b47..8db242b9a 100644--- a/python/tests/test_files.py+++ b/python/tests/test_files.py@@ -336,6 +336,207 @@ class TestFileHelperSchemaHandling:assert result == {"data": {"value": "test"}}+class TestFileHelperRefDefsResolution:+ """File flags reachable only through a $ref/$defs indirection.++ Regression coverage for+ https://github.com/ComposioHQ/composio/issues/3506. References are inlined+ once at the public-method boundary (``dereference_json_schema``), so the+ walkers themselves stay reference-agnostic.+ """++ @patch("composio.core.models._files.FileDownloadable.download")+ def test_download_resolves_ref_defs(self, mock_download, file_helper, mock_tool):+ """GMAIL_GET_ATTACHMENT shape: file_downloadable two $ref hops deep."""+ mock_download.return_value = "/tmp/invoice.pdf"+ mock_tool.output_parameters = {+ "type": "object",+ "$defs": {+ "FileDownloadable": {+ "type": "object",+ "properties": {+ "name": {"type": "string"},+ "mimetype": {"type": "string"},+ "s3url": {"type": "string"},+ },+ "required": ["name", "mimetype", "s3url"],+ "file_downloadable": True,+ },+ "GetAttachmentResponse": {+ "type": "object",+ "properties": {+ "file": {"$ref": "#/$defs/FileDownloadable"},+ "display_url": {"type": "string"},+ },+ "required": ["file"],+ },+ },+ "properties": {+ "data": {"$ref": "#/$defs/GetAttachmentResponse"},+ "successful": {"type": "boolean"},+ },+ "required": ["data", "successful"],+ }+ response = {+ "data": {+ "file": {+ "name": "invoice.pdf",+ "mimetype": "application/pdf",+ "s3url": "https://s3.example.com/invoice.pdf",+ },+ "display_url": "https://mail.google.com/...",+ },+ "successful": True,+ }++ result = file_helper.substitute_file_downloads(+ tool=mock_tool,+ response=response,+ )++ assert result["data"]["file"] == "/tmp/invoice.pdf"+ assert result["data"]["display_url"] == "https://mail.google.com/..."+ assert result["successful"] is True+ mock_download.assert_called_once()++ @patch("composio.core.models._files.FileUploadable.from_path")+ def test_upload_resolves_ref_defs(self, mock_from_path, file_helper, mock_tool):+ """$ref/$defs input schema exposes a nested file_uploadable leaf."""+ upload = MagicMock()+ upload.model_dump.return_value = {+ "name": "invoice.pdf",+ "mimetype": "application/pdf",+ "s3key": "uploads/invoice.pdf",+ }+ mock_from_path.return_value = upload+ mock_tool.input_parameters = {+ "type": "object",+ "$defs": {+ "FileUploadable": {"type": "string", "file_uploadable": True},+ "AttachmentInput": {+ "type": "object",+ "properties": {+ "file": {"$ref": "#/$defs/FileUploadable"},+ "name": {"type": "string"},+ },+ "required": ["file"],+ },+ },+ "properties": {"attachment": {"$ref": "#/$defs/AttachmentInput"}},+ "required": ["attachment"],+ }+ request = {"attachment": {"file": "/local/invoice.pdf", "name": "invoice.pdf"}}++ result = file_helper.substitute_file_uploads(+ tool=mock_tool,+ request=request,+ )++ assert result["attachment"]["file"] == {+ "name": "invoice.pdf",+ "mimetype": "application/pdf",+ "s3key": "uploads/invoice.pdf",+ }+ assert result["attachment"]["name"] == "invoice.pdf"+ mock_from_path.assert_called_once()++ def test_process_file_uploadable_schema_resolves_ref_defs(self, file_helper):+ """The LLM-facing input transform inlines $ref and rewrites the leaf."""+ schema = {+ "type": "object",+ "$defs": {+ "FileUploadable": {"type": "string", "file_uploadable": True},+ "AttachmentInput": {+ "type": "object",+ "properties": {"file": {"$ref": "#/$defs/FileUploadable"}},+ },+ },+ "properties": {"attachment": {"$ref": "#/$defs/AttachmentInput"}},+ }++ result = file_helper.process_file_uploadable_schema(schema)++ leaf = result["properties"]["attachment"]["properties"]["file"]+ assert leaf["type"] == "string"+ assert leaf["format"] == "path"+ assert leaf["file_uploadable"] is True+ # $defs is inlined away; no dangling references remain.+ assert "$defs" not in result+ assert "$ref" not in result["properties"]["attachment"]++ @patch("composio.core.models._files.FileDownloadable.download")+ def test_dangling_ref_download_degrades_gracefully(+ self, mock_download, file_helper, mock_tool+ ):+ """A $ref with no $defs block (issue #3307) must not raise (sentinel)."""+ mock_tool.output_parameters = {+ "type": "object",+ "properties": {+ "data": {"$ref": "#/$defs/Missing"},+ "successful": {"type": "boolean"},+ },+ }+ response = {"data": {"value": "passthrough"}, "successful": True}++ # No $defs block at all: strict resolution would raise and abort the+ # tool call. Sentinel mode keeps execution working — the unresolved+ # branch is simply not treated as a file.+ result = file_helper.substitute_file_downloads(+ tool=mock_tool,+ response=response,+ )++ assert result == {"data": {"value": "passthrough"}, "successful": True}+ mock_download.assert_not_called()++ @patch("composio.core.models._files.FileDownloadable.download")+ def test_recursive_ref_schema_does_not_recurse_infinitely(+ self, mock_download, file_helper, mock_tool+ ):+ """A self-referential $ref schema must not blow the stack.++ A per-node lazy resolver without threaded cycle tracking infinite-loops+ here; the centralized walker breaks the cycle with a sentinel.+ """+ mock_download.return_value = "/tmp/node.bin"+ mock_tool.output_parameters = {+ "type": "object",+ "$defs": {+ "Node": {+ "type": "object",+ "properties": {+ "file": {+ "type": "object",+ "properties": {"s3url": {"type": "string"}},+ "file_downloadable": True,+ },+ "child": {"$ref": "#/$defs/Node"},+ },+ },+ },+ "properties": {"root": {"$ref": "#/$defs/Node"}},+ }+ response = {+ "root": {+ "file": {+ "name": "n.bin",+ "mimetype": "application/octet-stream",+ "s3url": "https://s3/x",+ },+ "child": {"value": "leaf"},+ }+ }++ # Must complete without RecursionError.+ result = file_helper.substitute_file_downloads(+ tool=mock_tool,+ response=response,+ )++ assert result["root"]["file"] == "/tmp/node.bin"+ assert result["root"]["child"] == {"value": "leaf"}++class TestFileUploadableInUnionTypes:"""Test cases for file_uploadable detection in anyOf, oneOf, and allOf schemas."""diff --git a/python/tests/test_json_schema.py b/python/tests/test_json_schema.pynew file mode 100644index 000000000..caad4c0b4--- /dev/null+++ b/python/tests/test_json_schema.py@@ -0,0 +1,426 @@+"""Tests for :func:`composio.utils.json_schema.dereference_json_schema`.++Mirrors the TypeScript SDK's ``jsonSchema.test.ts`` so the two SDKs share one+behavioral contract for inlining JSON Schema ``$ref`` pointers.+"""++import typing as t+from unittest.mock import patch++import pytest++from composio.exceptions import JSONSchemaRefResolutionError+from composio.utils import json_schema+from composio.utils.json_schema import (+ MAX_REF_CHAIN_DEPTH,+ UNRESOLVED_REF_DESCRIPTION,+ dereference_json_schema,+)+++def _contains_ref(value: t.Any) -> bool:+ if isinstance(value, dict):+ if "$ref" in value:+ return True+ return any(_contains_ref(v) for v in value.values())+ if isinstance(value, list):+ return any(_contains_ref(v) for v in value)+ return False+++PERMISSIVE: t.Dict[str, t.Any] = {"type": "object", "additionalProperties": True}+PERMISSIVE_WITH_HINT: t.Dict[str, t.Any] = {+ **PERMISSIVE,+ "description": UNRESOLVED_REF_DESCRIPTION,+}+++class TestDereferenceJsonSchema:+ def test_inlines_single_internal_ref(self):+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {"user": {"$ref": "#/$defs/User"}},+ "required": ["user"],+ "$defs": {"User": {"type": "string"}},+ }+ )+ assert out == {+ "type": "object",+ "properties": {"user": {"type": "string"}},+ "required": ["user"],+ }+ assert _contains_ref(out) is False++ def test_resolves_chain_a_b_c(self):+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {"v": {"$ref": "#/$defs/A"}},+ "$defs": {+ "A": {"$ref": "#/$defs/B"},+ "B": {"$ref": "#/$defs/C"},+ "C": {"type": "integer"},+ },+ }+ )+ assert _contains_ref(out) is False+ assert out["properties"]["v"] == {"type": "integer"}++ def test_walks_containers_reflectively(self):+ """Refs are resolved in keywords the file walkers never special-cased."""+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {+ "a": {"type": "array", "items": {"$ref": "#/$defs/Leaf"}},+ "b": {"oneOf": [{"$ref": "#/$defs/Leaf"}, {"type": "null"}]},+ "c": {"anyOf": [{"$ref": "#/$defs/Leaf"}]},+ "d": {"allOf": [{"$ref": "#/$defs/Leaf"}]},+ "e": {"not": {"$ref": "#/$defs/Leaf"}},+ "f": {+ "type": "object",+ "additionalProperties": {"$ref": "#/$defs/Leaf"},+ },+ "g": {+ "type": "object",+ "patternProperties": {"^x_": {"$ref": "#/$defs/Leaf"}},+ },+ "h": {"type": "array", "prefixItems": [{"$ref": "#/$defs/Leaf"}]},+ },+ "$defs": {"Leaf": {"type": "string"}},+ }+ )+ assert _contains_ref(out) is False++ def test_resolves_legacy_definitions(self):+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {"name": {"$ref": "#/definitions/Name"}},+ "definitions": {"Name": {"type": "string", "minLength": 1}},+ }+ )+ assert _contains_ref(out) is False+ assert out["properties"]["name"] == {"type": "string", "minLength": 1}++ def test_mixes_defs_and_definitions_transitively(self):+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {"v": {"$ref": "#/definitions/A"}},+ "definitions": {"A": {"$ref": "#/$defs/B"}},+ "$defs": {"B": {"type": "boolean"}},+ }+ )+ assert _contains_ref(out) is False+ assert out["properties"]["v"] == {"type": "boolean"}++ def test_sibling_keywords_win_on_collision(self):+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {+ "v": {+ "$ref": "#/$defs/Foo",+ "description": "caller override",+ "default": None,+ },+ },+ "$defs": {+ "Foo": {"type": "string", "description": "target description"}+ },+ }+ )+ v = out["properties"]["v"]+ assert v["type"] == "string"+ assert v["description"] == "caller override"+ assert v["default"] is None+ assert _contains_ref(out) is False++ def test_breaks_recursive_ref_cycles_with_sentinel(self):+ out = dereference_json_schema(+ {+ "$ref": "#/$defs/Tree",+ "$defs": {+ "Tree": {+ "type": "object",+ "properties": {+ "children": {+ "type": "array",+ "items": {"$ref": "#/$defs/Tree"},+ },+ },+ },+ },+ }+ )+ assert out["type"] == "object"+ assert out["properties"]["children"]["items"] == PERMISSIVE+ assert _contains_ref(out) is False++ def test_strips_defs_and_definitions_from_root(self):+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {"x": {"$ref": "#/$defs/Foo"}},+ "$defs": {"Foo": {"type": "integer"}},+ "definitions": {"Bar": {"type": "string"}},+ }+ )+ assert "$defs" not in out+ assert "definitions" not in out++ def test_throws_when_target_missing(self):+ with pytest.raises(JSONSchemaRefResolutionError):+ dereference_json_schema(+ {+ "type": "object",+ "properties": {"v": {"$ref": "#/$defs/Missing"}},+ "$defs": {},+ }+ )++ def test_throws_when_chain_depth_exceeds_cap(self):+ defs: t.Dict[str, t.Any] = {}+ for i in range(200):+ target = f"#/$defs/A{i + 1}" if i + 1 < 200 else "#/$defs/A0"+ defs[f"A{i}"] = {"$ref": target}+ with pytest.raises(JSONSchemaRefResolutionError):+ dereference_json_schema(+ {+ "type": "object",+ "properties": {"v": {"$ref": "#/$defs/A0"}},+ "$defs": defs,+ }+ )++ def test_throws_on_pathologically_deep_nesting(self):+ leaf: t.Dict[str, t.Any] = {"type": "string"}+ for _ in range(1000):+ leaf = {"type": "object", "properties": {"x": leaf}}+ with pytest.raises(JSONSchemaRefResolutionError):+ dereference_json_schema(leaf)++ def test_breaks_identity_cycles_without_ref(self):+ """A live-object cycle that does not flow through a ``$ref``."""+ root: t.Dict[str, t.Any] = {"type": "object", "properties": {}}+ root["properties"]["self"] = root+ out = dereference_json_schema(root)+ assert out["properties"]["self"] == PERMISSIVE++ def test_leaves_external_ref_untouched_and_warns(self):+ with patch.object(json_schema.logger, "warning") as warn:+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {"v": {"$ref": "https://example.com/Foo"}},+ }+ )+ assert out["properties"]["v"]["$ref"] == "https://example.com/Foo"+ warn.assert_called_once()+ assert "https://example.com/Foo" in str(warn.call_args)++ def test_does_not_mutate_input(self):+ import copy++ schema = {+ "type": "object",+ "properties": {"v": {"$ref": "#/$defs/Foo"}},+ "$defs": {"Foo": {"type": "string"}},+ }+ snapshot = copy.deepcopy(schema)+ dereference_json_schema(schema)+ assert schema == snapshot++ def test_decodes_json_pointer_escapes(self):+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {+ "a": {"$ref": "#/$defs/with~1slash"},+ "b": {"$ref": "#/$defs/with~0tilde"},+ "c": {"$ref": "#/$defs/tilde-then-slash~01"},+ },+ "$defs": {+ "with/slash": {"type": "string"},+ "with~tilde": {"type": "integer"},+ "tilde-then-slash~1": {"type": "boolean"},+ },+ }+ )+ props = out["properties"]+ assert props["a"]["type"] == "string"+ assert props["b"]["type"] == "integer"+ assert props["c"]["type"] == "boolean"++ def test_resolves_array_index_pointers(self):+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {"v": {"$ref": "#/$defs/foo/oneOf/0"}},+ "$defs": {"foo": {"oneOf": [{"type": "string"}, {"type": "number"}]}},+ }+ )+ assert out["properties"]["v"]["type"] == "string"++ def test_passthrough_for_non_dict_input(self):+ assert dereference_json_schema("not-a-schema") == "not-a-schema"+ assert dereference_json_schema(None) is None+++class TestSentinelMode:+ def test_replaces_dangling_ref_with_no_defs_block(self):+ """Mirrors GMAIL_FETCH_EMAILS: a ``$ref`` into ``#/$defs`` with no defs."""+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {+ "data": {"$ref": "#/$defs/FetchEmailsResponse"},+ "error": {"type": "string"},+ "successful": {"type": "boolean"},+ },+ "required": ["data", "successful"],+ "title": "FetchEmailsResponseWrapper",+ },+ on_unresolved="sentinel",+ )+ assert out["properties"]["data"] == PERMISSIVE_WITH_HINT+ assert out["properties"]["error"] == {"type": "string"}+ assert out["properties"]["successful"] == {"type": "boolean"}+ assert out["required"] == ["data", "successful"]+ assert _contains_ref(out) is False++ def test_replaces_ref_into_empty_defs(self):+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {"v": {"$ref": "#/$defs/Missing"}},+ "$defs": {},+ },+ on_unresolved="sentinel",+ )+ assert out["properties"]["v"] == PERMISSIVE_WITH_HINT+ assert _contains_ref(out) is False++ def test_on_replace_called_once_per_replacement(self):+ calls: t.List[t.Tuple[str, str]] = []+ dereference_json_schema(+ {+ "type": "object",+ "properties": {+ "a": {"$ref": "#/$defs/Missing"},+ "b": {"$ref": "#/$defs/Missing"},+ "c": {"$ref": "#/$defs/AlsoMissing"},+ },+ },+ on_unresolved="sentinel",+ on_replace=lambda ref, reason: calls.append((ref, reason)),+ )+ assert calls == [+ ("#/$defs/Missing", "missing-target"),+ ("#/$defs/Missing", "missing-target"),+ ("#/$defs/AlsoMissing", "missing-target"),+ ]++ def test_on_replace_malformed_pointer(self):+ calls: t.List[t.Tuple[str, str]] = []+ out = dereference_json_schema(+ {"type": "object", "properties": {"v": {"$ref": "#bar"}}},+ on_unresolved="sentinel",+ on_replace=lambda ref, reason: calls.append((ref, reason)),+ )+ assert calls == [("#bar", "malformed-pointer")]+ assert out["properties"]["v"] == PERMISSIVE_WITH_HINT++ def test_still_throws_on_chain_depth_cap(self):+ defs: t.Dict[str, t.Any] = {}+ for i in range(200):+ target = f"#/$defs/A{i + 1}" if i + 1 < 200 else "#/$defs/A0"+ defs[f"A{i}"] = {"$ref": target}+ with pytest.raises(JSONSchemaRefResolutionError):+ dereference_json_schema(+ {+ "type": "object",+ "properties": {"v": {"$ref": "#/$defs/A0"}},+ "$defs": defs,+ },+ on_unresolved="sentinel",+ )++ def test_still_throws_on_node_depth_cap(self):+ leaf: t.Dict[str, t.Any] = {"type": "string"}+ for _ in range(1000):+ leaf = {"type": "object", "properties": {"x": leaf}}+ with pytest.raises(JSONSchemaRefResolutionError):+ dereference_json_schema(leaf, on_unresolved="sentinel")++ def test_explicit_throw_matches_default(self):+ with pytest.raises(JSONSchemaRefResolutionError):+ dereference_json_schema(+ {+ "type": "object",+ "properties": {"v": {"$ref": "#/$defs/Missing"}},+ "$defs": {},+ },+ on_unresolved="throw",+ )++ def test_does_not_call_on_replace_in_strict_mode(self):+ calls: t.List[t.Any] = []+ with pytest.raises(JSONSchemaRefResolutionError):+ dereference_json_schema(+ {+ "type": "object",+ "properties": {"v": {"$ref": "#/$defs/Missing"}},+ "$defs": {},+ },+ on_unresolved="throw",+ on_replace=lambda ref, reason: calls.append((ref, reason)),+ )+ assert calls == []++ def test_injects_default_description_when_no_sibling(self):+ out = dereference_json_schema(+ {"type": "object", "properties": {"v": {"$ref": "#/$defs/Missing"}}},+ on_unresolved="sentinel",+ )+ description = out["properties"]["v"]["description"]+ assert "Schema shape unresolved at the source" in description+ assert "https://github.com/ComposioHQ/composio/issues/3307" in description++ def test_preserves_caller_description_sibling(self):+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {+ "v": {+ "$ref": "#/$defs/Missing",+ "description": "caller-supplied prose context",+ },+ },+ },+ on_unresolved="sentinel",+ )+ assert out["properties"]["v"]["description"] == "caller-supplied prose context"+ assert out["properties"]["v"]["type"] == "object"++ def test_preserves_resolvable_defs_while_replacing_dangling_branch(self):+ out = dereference_json_schema(+ {+ "type": "object",+ "properties": {+ "resolved": {"$ref": "#/$defs/Real"},+ "dangling": {"$ref": "#/$defs/Ghost"},+ },+ "$defs": {"Real": {"type": "integer"}},+ },+ on_unresolved="sentinel",+ )+ assert out["properties"]["resolved"] == {"type": "integer"}+ assert out["properties"]["dangling"] == PERMISSIVE_WITH_HINT+++def test_max_ref_chain_depth_is_exposed():+ """Guard against accidental removal of the safety cap constant."""+ assert MAX_REF_CHAIN_DEPTH == 100