langchain-quickjs: nested Pydantic schemas render as unknown in PTC signatures

[AdamBurchett]

Submission checklist

• This is a bug, not a usage question.
• I added a clear and descriptive title.
• I searched existing issues and didn't find this.
• I can reproduce this with the latest released version.
• I included a minimal reproducible example and steps to reproduce.

Area (Required)

• deepagents (SDK)
• dcode
• talon
• acp
• evals
• daytona
• modal
• quickjs
• runloop
• vercel
• langsmith-sandbox
• Other / not sure / general

Related Issues / PRs

PR #3210, feat(quickjs): propagate return types, introduced return-type rendering but did not resolve compound schema references.

Reproduction Steps / Example Code (Python)

from langchain_core.tools import StructuredTool
from langchain_quickjs._ptc import render_ptc_prompt
from pydantic import BaseModel


class Address(BaseModel):
    city: str
    postal_code: str


class User(BaseModel):
    name: str
    address: Address


class BatchInput(BaseModel):
    users: list[User]


def normalize_users(users: list[User]) -> list[User]:
    return users


tool = StructuredTool.from_function(
    name="normalize_users",
    description="Normalize users.",
    func=normalize_users,
    args_schema=BatchInput,
)

prompt = render_ptc_prompt([tool])
print(prompt)

assert "users: unknown[]" not in prompt
assert "Promise<unknown[]>" not in prompt
assert "address: { city: string; postal_code: string }" in prompt

Error Message and Stack Trace (if applicable)

Description

langchain-quickjs lets an agent call Python tools from JavaScript. It generates a TypeScript-style API reference so the agent knows each tool's expected inputs and outputs.

When a tool uses nested Pydantic models, the generated reference loses their structure. In the reproduction provided, a tool accepting list[User], where each User contains an Address, is currently shown as:

tools.normalizeUsers(input: {
  users: unknown[];
}): Promise<unknown[]>

It should be shown as:

tools.normalizeUsers(input: {
  users: {
    name: string;
    address: {
      city: string;
      postal_code: string;
    };
  }[];
}): Promise<{
  name: string;
  address: {
    city: string;
    postal_code: string;
  };
}[]>

The JavaScript runtime can already transport these nested values. The problem is only in the generated API reference. Pydantic stores nested definitions using JSON Schema $defs and $ref, but the current renderer does not resolve those references and therefore falls back to unknown.

A minimal fix is to run input and return schemas through LangChain Core's existing dereference_refs utility before rendering them. This requires no new dependency or public API change and supports nested and inherited Pydantic models.

If this approach is acceptable, please assign this issue to me. I have a focused implementation and regression tests ready to submit.

Environment / System Info

OS: Linux x86_64
Python: 3.13.5
deepagents: 0.7.16
langchain: 1.4.2
langchain-core: 1.6.3
langchain-quickjs: 0.3.7
quickjs-rs: 0.2.5
Relevant environment variables: None
Date verified: September 21, 2026

[206459634]

I dug into this on main and can confirm the root cause and a minimal fix.

Verification. Running the reproduction from the issue, the PTC API reference renders:

tools.normalizeUsers(input: {
  users: unknown[];
}): Promise<unknown[]>

so both the nested input arg and the nested return type collapse to unknown, exactly as reported.

Root cause. In libs/partners/quickjs/langchain_quickjs/_prompt.py:

• Input schemas come from _safe_json_schema via args_schema.model_json_schema(), and return types from _render_return_type via pydantic.TypeAdapter(annotation).json_schema() (the path added in feat(quickjs): propagate return types #3210). For nested models, Pydantic v2 emits the nested definitions under $defs and points at them with $ref — e.g. {"type": "array", "items": {"$ref": "#/$defs/User"}}.
• _json_schema_to_ts is a shallow renderer: it handles enum / anyOf / type but has no $ref case, so any referenced node falls through to the final return "unknown". The code comment above _render_return_type (lines 485–491) already flags this as a known limitation of that path.

The bridge itself marshals nested values fine, so this is purely a prompt-rendering issue, as the issue says.

Proposed fix. Resolve references before rendering, using LangChain Core's existing dereference_refs utility (langchain_core.utils.function_calling) — no new dependency (langchain-core is already a direct dependency), no lockfile change, no public API change:

1. In _render_return_type, pass the TypeAdapter(...).json_schema() result through dereference_refs before _json_schema_to_ts.
2. In _safe_json_schema, do the same for the model_json_schema() result.
3. Update the two parametrized return-type cases in tests/unit_tests/test_ptc.py that currently pin list[TypedDict] / list[BaseModel] to Promise<unknown[]>, add regression tests for the exact scenario from this issue (nested input + nested return, inherited fields, and a recursive model — dereference_refs' built-in depth handling truncates those safely rather than hanging), and regenerate the prompt snapshots that pin Promise<unknown[]> for the find_users_by_name tool.

I've prototyped this locally: the nested input renders as users: { name: string; address: { city: string; postal_code: string } }[] and the return as the fully inlined Promise<{ name: string; address: { ... } }[]>, matching the expected output in the issue description, with existing primitive/union/Literal rendering unchanged.

If this approach looks good, could you assign me? I'll open the PR once assigned.

[AdamBurchett]

Updated implementation proposal

After testing the original dereference_refs approach, also implemented in #6460, I found that it fixes the reported example by expanding referenced models inline. That can repeat the same model throughout the generated prompt, increasing prompt size, while still representing some Pydantic schemas only partially.

I prepared an alternative that preserves Pydantic's shared schema definitions and renders references by name. It addresses the same reported bug without adding dependencies or changing public APIs or runtime behavior:

• Design and tradeoffs: design document
• Ready prototype: implementation branch

This is the preferred fix for my team because it supports the full range of Pydantic schema structures our tools use, rather than limiting support to shallow schemas.

If this direction is acceptable for #6459, please assign the issue to me and I will open the PR.