langchain-quickjs 0.0.1__py3-none-any.whl

langchain_quickjs/__init__.py

@@ -0,0 +1,7 @@
+"""QuickJS integration package for Deep Agents."""
+
+from langchain_quickjs.middleware import QuickJSMiddleware
+
+__version__ = "0.0.1"
+
+__all__ = ["QuickJSMiddleware", "__version__"]

langchain_quickjs/_foreign_function_docs.py

@@ -0,0 +1,447 @@
+"""Render compact prompt-facing documentation for QuickJS foreign functions.
+
+QuickJS foreign functions are Python callables or LangChain tools exposed inside
+JavaScript. The model needs a concise description of their names, argument
+shapes, return types, and any referenced structured types. This module converts
+Python signatures and docstrings into small TypeScript-like stubs and prompt
+sections that are easy for the model to consume.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import inspect
+from typing import TYPE_CHECKING, Any, get_args, get_origin, get_type_hints
+
+from langchain_core.tools import BaseTool
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+_ELLIPSIS_TUPLE_ARG_COUNT = 2
+
+
+def _format_basic_annotation(annotation: Any) -> str | None:
+    """Render simple built-in annotations without container introspection."""
+    basic_types = {
+        Any: "any",
+        inspect.Signature.empty: "any",
+        str: "string",
+        bool: "boolean",
+        type(None): "null",
+        dict: "Record<string, any>",
+    }
+    if annotation in basic_types:
+        return basic_types[annotation]
+    if annotation in (int, float):
+        return "number"
+    if isinstance(annotation, type):
+        return annotation.__name__
+    return None
+
+
+def _format_collection_annotation(origin: Any, args: tuple[Any, ...]) -> str | None:
+    """Render collection-like generic annotations."""
+    if origin in (list, set, frozenset):
+        item = _format_annotation(args[0]) if args else "any"
+        return f"{item}[]"
+    if origin is tuple:
+        if len(args) == _ELLIPSIS_TUPLE_ARG_COUNT and args[1] is Ellipsis:
+            return f"{_format_annotation(args[0])}[]"
+        return f"[{', '.join(_format_annotation(arg) for arg in args)}]"
+    if origin is dict:
+        key_type = _format_annotation(args[0]) if args else "string"
+        value_type = _format_annotation(args[1]) if len(args) > 1 else "any"
+        return f"Record<{key_type}, {value_type}>"
+    return None
+
+
+def _format_generic_annotation(origin: Any, args: tuple[Any, ...]) -> str | None:
+    """Render non-collection generic annotations."""
+    if origin is type:
+        inner = _format_annotation(args[0]) if args else "any"
+        return f"new (...args: any[]) => {inner}"
+    origin_name = getattr(origin, "__name__", None)
+    if origin_name in {"Union", "UnionType"}:
+        return " | ".join(_format_annotation(arg) for arg in args)
+    if origin_name:
+        formatted_args = ", ".join(_format_annotation(arg) for arg in args)
+        return f"{origin_name}<{formatted_args}>"
+    return None
+
+
+def _format_stringified_annotation(annotation: Any) -> str:
+    """Render fallback annotations from their string representation."""
+    rendered = str(annotation).replace("typing.", "").replace("'", "")
+    if rendered.endswith(" | None"):
+        return f"{rendered.removesuffix(' | None')} | null"
+    if "." in rendered and "[" not in rendered:
+        return rendered.rsplit(".", maxsplit=1)[-1]
+    return rendered
+
+
+def _format_annotation(annotation: Any) -> str:
+    """Render one Python type annotation in a TypeScript-like form.
+
+    Args:
+        annotation: The Python annotation to render.
+
+    Returns:
+        A compact string suitable for prompt-facing function signatures.
+    """
+    basic = _format_basic_annotation(annotation)
+    if basic is not None:
+        return basic
+
+    origin = get_origin(annotation)
+    if origin is None:
+        return _format_stringified_annotation(annotation)
+
+    args = get_args(annotation)
+    collection = _format_collection_annotation(origin, args)
+    if collection is not None:
+        return collection
+
+    generic = _format_generic_annotation(origin, args)
+    if generic is not None:
+        return generic
+
+    return _format_stringified_annotation(annotation)
+
+
+def _unwrap_typed_dict_annotation(annotation: Any) -> tuple[Any, str]:
+    """Extract a TypedDict annotation from supported container types."""
+    container_prefix = ""
+    origin = get_origin(annotation)
+    if origin not in (list, tuple, set, frozenset):
+        return annotation, container_prefix
+
+    args = get_args(annotation)
+    if not args:
+        return annotation, container_prefix
+
+    unwrapped = args[0]
+    container_prefix = f"Contained `{unwrapped.__name__}` structure:\n"
+    return unwrapped, container_prefix
+
+
+def _is_not_required_annotation(annotation: Any) -> bool:
+    """Return whether a TypedDict field annotation marks an optional key."""
+    origin = get_origin(annotation)
+    if getattr(origin, "__name__", None) == "NotRequired":
+        return True
+    forward_arg = getattr(annotation, "__forward_arg__", None)
+    return isinstance(forward_arg, str) and forward_arg.startswith("NotRequired[")
+
+
+def _typed_dict_key_sets(
+    annotation: type[Any],
+) -> tuple[frozenset[str], frozenset[str]]:
+    """Return required and optional TypedDict keys, including postponed annotations."""
+    required_keys = getattr(annotation, "__required_keys__", frozenset())
+    optional_keys = getattr(annotation, "__optional_keys__", frozenset())
+    if optional_keys:
+        return required_keys, optional_keys
+
+    raw_annotations = getattr(annotation, "__annotations__", {})
+    inferred_optional = {
+        key
+        for key, value in raw_annotations.items()
+        if _is_not_required_annotation(value)
+    }
+    if not inferred_optional:
+        return required_keys, optional_keys
+    inferred_required = frozenset(set(raw_annotations) - inferred_optional)
+    return inferred_required, frozenset(inferred_optional)
+
+
+def _render_typed_dict_fields(
+    annotation: type[Any], field_types: dict[str, Any]
+) -> str | None:
+    """Render field lines for a TypedDict annotation."""
+    if not field_types:
+        return None
+
+    required_keys, optional_keys = _typed_dict_key_sets(annotation)
+    lines = [f"Return structure `{annotation.__name__}`:"]
+    for key, value in field_types.items():
+        marker = "required" if key in required_keys else "optional"
+        if key not in required_keys and key not in optional_keys:
+            marker = "field"
+        field_name = f"{key}?" if key in optional_keys else key
+        lines.append(f"- {field_name}: {_format_annotation(value)} ({marker})")
+    return "\n".join(lines)
+
+
+def _format_typed_dict_structure(annotation: Any) -> str | None:
+    """Render a compact field listing for a TypedDict annotation."""
+    annotation, container_prefix = _unwrap_typed_dict_annotation(annotation)
+    if not isinstance(annotation, type):
+        return None
+    if not hasattr(annotation, "__annotations__") or not hasattr(
+        annotation, "__required_keys__"
+    ):
+        return None
+
+    field_types = getattr(annotation, "__annotations__", {})
+    with contextlib.suppress(TypeError, NameError):
+        field_types = get_type_hints(annotation)
+
+    rendered_fields = _render_typed_dict_fields(annotation, field_types)
+    if rendered_fields is None:
+        return None
+    return container_prefix + rendered_fields
+
+
+def render_external_functions_section(
+    implementations: dict[str, Callable[..., Any] | BaseTool], *, add_docs: bool
+) -> str:
+    """Build the optional prompt section describing foreign functions."""
+    if not implementations:
+        return ""
+
+    if not add_docs:
+        formatted_functions = "\n".join(f"- {name}" for name in implementations)
+        return f"\n\nAvailable foreign functions:\n{formatted_functions}"
+
+    return f"\n\n{render_foreign_function_section(implementations)}"
+
+
+def _get_tool_doc_target(tool: BaseTool) -> Callable[..., Any] | None:
+    """Choose the underlying callable that best represents a LangChain tool.
+
+    Args:
+        tool: The LangChain tool being documented.
+
+    Returns:
+        The sync function or coroutine that provides the most useful signature
+        and docstring for prompt generation, or `None` if neither is available.
+    """
+    target = getattr(tool, "func", None)
+    if callable(target):
+        return target
+    target = getattr(tool, "coroutine", None)
+    if callable(target):
+        return target
+    return None
+
+
+def _get_foreign_function_mode(implementation: Callable[..., Any] | BaseTool) -> str:
+    """Return whether a foreign function should be treated as sync or async."""
+    if isinstance(implementation, BaseTool):
+        coroutine = getattr(implementation, "coroutine", None)
+        return "async" if callable(coroutine) else "sync"
+    return "async" if inspect.iscoroutinefunction(implementation) else "sync"
+
+
+def _get_return_annotation(target: Callable[..., Any]) -> Any:
+    """Resolve the return annotation for a callable, if present."""
+    with contextlib.suppress(TypeError, ValueError, NameError):
+        inspected_signature = inspect.signature(target)
+        resolved_hints = get_type_hints(target)
+        return resolved_hints.get("return", inspected_signature.return_annotation)
+    return inspect.Signature.empty
+
+
+def _render_jsdoc(doc: str) -> str:
+    """Convert a Python docstring into a compact JSDoc block."""
+    lines = inspect.cleandoc(doc).splitlines()
+    summary: list[str] = []
+    params: list[tuple[str, str]] = []
+    in_args = False
+    for line in lines:
+        stripped = line.strip()
+        if stripped == "Args:":
+            in_args = True
+            continue
+        if in_args:
+            if not stripped:
+                continue
+            if line.startswith("    ") and ":" in stripped:
+                name, description = stripped.split(":", maxsplit=1)
+                params.append((name.strip(), description.strip()))
+                continue
+            in_args = False
+        if stripped:
+            summary.append(stripped)
+
+    rendered = ["/**"]
+    rendered.extend(f" * {line}" for line in summary)
+    if summary and params:
+        rendered.append(" *")
+    for name, description in params:
+        rendered.append(f" * @param {name} {description}")
+    rendered.append(" */")
+    return "\n".join(rendered)
+
+
+def _render_function_stub(
+    name: str, implementation: Callable[..., Any] | BaseTool
+) -> str:
+    """Render one prompt-facing function declaration for a foreign function.
+
+    Args:
+        name: The JavaScript-visible foreign function name.
+        implementation: The Python callable or LangChain tool backing that name.
+
+    Returns:
+        A TypeScript-like function declaration, optionally prefixed with a small
+        JSDoc block derived from the Python docstring.
+    """
+    function_mode = _get_foreign_function_mode(implementation)
+    target = (
+        _get_tool_doc_target(implementation)
+        if isinstance(implementation, BaseTool)
+        else implementation
+    )
+    if target is None:
+        prefix = "async function" if function_mode == "async" else "function"
+        return f"{prefix} {name}(...args: any[]): any"
+
+    signature = "(...args: any[])"
+    return_annotation = inspect.Signature.empty
+    with contextlib.suppress(TypeError, ValueError, NameError):
+        inspected_signature = inspect.signature(target)
+        resolved_hints = get_type_hints(target)
+        parameter_parts = [
+            (
+                f"{param.name}: "
+                + _format_annotation(resolved_hints.get(param.name, param.annotation))
+            )
+            if param.annotation is not inspect.Signature.empty
+            or param.name in resolved_hints
+            else f"{param.name}: any"
+            for param in inspected_signature.parameters.values()
+        ]
+        signature = f"({', '.join(parameter_parts)})"
+        return_annotation = resolved_hints.get(
+            "return", inspected_signature.return_annotation
+        )
+
+    rendered_return = (
+        _format_annotation(return_annotation)
+        if return_annotation is not inspect.Signature.empty
+        else "any"
+    )
+    if function_mode == "async":
+        rendered_return = f"Promise<{rendered_return}>"
+    prefix = "async function" if function_mode == "async" else "function"
+    declaration = f"{prefix} {name}{signature}: {rendered_return}"
+    doc = inspect.getdoc(target) or inspect.getdoc(implementation)
+    if not doc:
+        return declaration
+    return f"{_render_jsdoc(doc)}\n{declaration}"
+
+
+def _collect_referenced_types(
+    implementations: dict[str, Callable[..., Any] | BaseTool],
+) -> list[type[Any]]:
+    """Collect unique structured return types that should be documented.
+
+    Args:
+        implementations: Mapping of JavaScript-visible function names to Python
+            callables or LangChain tools.
+
+    Returns:
+        A list of TypedDict-like annotations referenced by foreign function
+        return types, preserving first-seen order.
+    """
+    collected: list[type[Any]] = []
+    seen: set[type[Any]] = set()
+    for implementation in implementations.values():
+        target = (
+            _get_tool_doc_target(implementation)
+            if isinstance(implementation, BaseTool)
+            else implementation
+        )
+        if target is None:
+            continue
+        annotation = _get_return_annotation(target)
+        origin = get_origin(annotation)
+        if origin in (list, tuple, set, frozenset):
+            args = get_args(annotation)
+            if args:
+                annotation = args[0]
+        if not isinstance(annotation, type):
+            continue
+        if not hasattr(annotation, "__annotations__") or not hasattr(
+            annotation, "__required_keys__"
+        ):
+            continue
+        if annotation not in seen:
+            seen.add(annotation)
+            collected.append(annotation)
+    return collected
+
+
+def _render_typed_dict_definition(annotation: type[Any]) -> str:
+    """Render a TypeScript-like type definition for a TypedDict."""
+    _, optional_keys = _typed_dict_key_sets(annotation)
+    with contextlib.suppress(TypeError, NameError):
+        field_types = get_type_hints(annotation)
+        lines = [f"type {annotation.__name__} = {{"]
+        for key, value in field_types.items():
+            field_name = f"{key}?" if key in optional_keys else key
+            lines.append(f"  {field_name}: {_format_annotation(value)}")
+        lines.append("}")
+        return "\n".join(lines)
+
+    field_types = getattr(annotation, "__annotations__", {})
+    lines = [f"type {annotation.__name__} = {{"]
+    for key, value in field_types.items():
+        field_name = f"{key}?" if key in optional_keys else key
+        lines.append(f"  {field_name}: {_format_annotation(value)}")
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def render_foreign_function_section(
+    implementations: dict[str, Callable[..., Any] | BaseTool],
+) -> str:
+    """Render the complete prompt section for available foreign functions."""
+    function_blocks = [
+        _render_function_stub(name, implementation)
+        for name, implementation in implementations.items()
+    ]
+    sections = [
+        "Available foreign functions:\n",
+        (
+            "These are JavaScript-callable foreign functions exposed inside QuickJS. "
+            "The TypeScript-style signatures below document argument and return shapes."
+        ),
+        "",
+        "```ts",
+        "\n\n".join(function_blocks),
+        "```",
+    ]
+
+    referenced_types = _collect_referenced_types(implementations)
+    if referenced_types:
+        type_blocks = [
+            _render_typed_dict_definition(annotation) for annotation in referenced_types
+        ]
+        sections.extend(
+            [
+                "",
+                "Referenced types:",
+                "```ts",
+                "\n\n".join(type_blocks),
+                "```",
+            ]
+        )
+    return "\n".join(sections)
+
+
+def format_foreign_function_docs(
+    name: str,
+    implementation: Callable[..., Any] | BaseTool,
+) -> str:
+    """Render a compact signature and docstring block for a foreign function."""
+    return _render_function_stub(name, implementation)
+
+
+__all__ = [
+    "format_foreign_function_docs",
+    "render_external_functions_section",
+    "render_foreign_function_section",
+]

langchain_quickjs/_foreign_functions.py

@@ -0,0 +1,257 @@
+"""Bridge Python foreign functions into QuickJS with transparent JSON round-tripping.
+
+The QuickJS Python binding can pass primitive return values directly, but complex
+Python values like lists and dicts do not automatically become JavaScript arrays
+or objects. This module adds a small bridge layer that JSON-encodes complex
+Python results on the way out and parses them back inside QuickJS so foreign
+functions behave more naturally from JavaScript.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import threading
+from typing import TYPE_CHECKING, Any, Literal
+
+from langchain_core.tools import BaseTool
+from langchain_core.tools.base import (
+    _is_injected_arg_type,
+    get_all_basemodel_annotations,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Coroutine
+    from concurrent.futures import Future
+
+    import quickjs
+    from langchain.tools import ToolRuntime
+
+
+class _AsyncLoopThread:
+    """Run coroutines on a dedicated daemon-thread event loop."""
+
+    def __init__(self) -> None:
+        self._ready = threading.Event()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        self._ready.wait()
+
+    def _run(self) -> None:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        self._loop = loop
+        self._ready.set()
+        loop.run_forever()
+
+    def submit(self, coroutine: Coroutine[Any, Any, Any]) -> Future[Any]:
+        loop = self._loop
+        if loop is None:
+            msg = "Async loop thread was not initialized."
+            raise RuntimeError(msg)
+        return asyncio.run_coroutine_threadsafe(coroutine, loop)
+
+
+_ASYNC_LOOP_THREAD = _AsyncLoopThread()
+
+
+def _await_if_needed(value: Any) -> Any:
+    """Resolve awaitable results on the background event loop when needed."""
+    if inspect.isawaitable(value):
+        return _ASYNC_LOOP_THREAD.submit(value).result()
+    return value
+
+
+def _invoke_tool(
+    tool: BaseTool,
+    payload: str | dict[str, Any],
+    *,
+    prefer_async: bool = False,
+) -> Any:
+    """Invoke a tool through its sync or async entrypoint as appropriate."""
+    has_async = getattr(tool, "coroutine", None) is not None or (
+        tool.__class__._arun is not BaseTool._arun  # noqa: SLF001
+    )
+    has_sync = getattr(tool, "func", None) is not None or (
+        tool.__class__._run is not BaseTool._run  # noqa: SLF001
+    )
+    if has_async and (prefer_async or not has_sync):
+        return _await_if_needed(tool.ainvoke(payload))
+    return _await_if_needed(tool.invoke(payload))
+
+
+def get_ptc_implementations(
+    ptc: list[Callable[..., Any] | BaseTool] | None,
+) -> dict[str, Callable[..., Any] | BaseTool]:
+    """Return configured PTC implementations keyed by exported function name."""
+    implementations: dict[str, Callable[..., Any] | BaseTool] = {}
+    for implementation in ptc or []:
+        if isinstance(implementation, BaseTool):
+            implementations[implementation.name] = implementation
+            continue
+        name = getattr(implementation, "__name__", None)
+        if isinstance(name, str):
+            implementations[name] = implementation
+    return implementations
+
+
+def _get_runtime_arg_name(tool: BaseTool) -> str | None:
+    """Return the injected runtime parameter name for a tool, if any."""
+    for name, type_ in get_all_basemodel_annotations(tool.get_input_schema()).items():
+        if name == "runtime" and _is_injected_arg_type(type_):
+            return name
+    return None
+
+
+def _build_tool_payload(
+    tool: BaseTool,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    *,
+    runtime: ToolRuntime | None = None,
+) -> str | dict[str, Any]:
+    """Convert QuickJS call arguments into a LangChain tool payload."""
+    input_schema = tool.get_input_schema()
+    schema_annotations = getattr(input_schema, "__annotations__", {})
+    fields = [
+        name
+        for name, type_ in schema_annotations.items()
+        if not _is_injected_arg_type(type_)
+    ]
+    runtime_arg_name = _get_runtime_arg_name(tool)
+
+    if kwargs:
+        payload: str | dict[str, Any] = kwargs
+    elif (
+        len(args) == 1 and isinstance(args[0], (str, dict)) and runtime_arg_name is None
+    ):
+        payload = args[0]
+    elif len(args) == 1 and len(fields) == 1:
+        payload = {fields[0]: args[0]}
+    elif len(args) == len(fields) and fields:
+        payload = dict(zip(fields, args, strict=False))
+    else:
+        payload = {"args": list(args)}
+
+    if (
+        runtime is not None
+        and runtime_arg_name is not None
+        and isinstance(payload, dict)
+    ):
+        return {**payload, runtime_arg_name: runtime}
+    return payload
+
+
+def _wrap_tool_for_js(
+    tool: BaseTool,
+    *,
+    prefer_async: bool = False,
+    runtime: ToolRuntime | None = None,
+) -> Callable[..., Any]:
+    """Adapt a LangChain tool into a plain sync callable for QuickJS."""
+
+    def tool_wrapper(*args: Any, **kwargs: Any) -> Any:
+        payload = _build_tool_payload(tool, args, kwargs, runtime=runtime)
+        return _invoke_tool(tool, payload, prefer_async=prefer_async)
+
+    return tool_wrapper
+
+
+def _serialize_for_js(value: Any) -> Any:
+    """Convert Python return values into primitives the bridge can round-trip."""
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    return json.dumps(value)
+
+
+def _wrap_function_for_js(implementation: Callable[..., Any]) -> Callable[..., Any]:
+    """Wrap a Python callable so complex return values are JSON-encoded."""
+
+    def function_wrapper(*args: Any, **kwargs: Any) -> Any:
+        return _serialize_for_js(_await_if_needed(implementation(*args, **kwargs)))
+
+    return function_wrapper
+
+
+def _raw_function_name(name: str) -> str:
+    """Build the hidden Python callable name used by the JS bridge shim."""
+    return f"__python_{name}"
+
+
+def _build_external_functions(
+    implementations: dict[str, Callable[..., Any] | BaseTool] | None,
+    *,
+    prefer_async: bool = False,
+    runtime: ToolRuntime | None = None,
+) -> dict[str, Callable[..., Any]]:
+    """Normalize foreign implementations into QuickJS-registerable callables."""
+    external_functions: dict[str, Callable[..., Any]] = {}
+    for name, implementation in (implementations or {}).items():
+        callable_implementation = (
+            _wrap_tool_for_js(
+                implementation,
+                prefer_async=prefer_async,
+                runtime=runtime,
+            )
+            if isinstance(implementation, BaseTool)
+            else implementation
+        )
+        external_functions[_raw_function_name(name)] = _wrap_function_for_js(
+            callable_implementation
+        )
+    return external_functions
+
+
+_EXTERNAL_FUNCTION_SHIM_TEMPLATE = """
+globalThis[{name}] = (...args) => {{
+    const value = globalThis[{raw_name}](...args);
+    if (typeof value !== \"string\") {{ return value; }}
+    const trimmed = value.trim();
+    if (!trimmed) {{ return value; }}
+    const first = trimmed[0];
+    if (first !== \"[\" && first !== \"{{\") {{ return value; }}
+    return JSON.parse(value);
+}};
+"""
+
+
+def inject_external_function_shims(
+    context: quickjs.Context, external_functions: list[str] | None
+) -> None:
+    """Install JavaScript shims for foreign functions inside a QuickJS context."""
+    if not external_functions:
+        return
+
+    shim_lines = []
+    for name in external_functions:
+        raw_name = _raw_function_name(name)
+        shim_lines.append(
+            _EXTERNAL_FUNCTION_SHIM_TEMPLATE.format(
+                name=json.dumps(name),
+                raw_name=json.dumps(raw_name),
+            )
+        )
+    context.eval("".join(shim_lines))
+
+
+def install_external_functions(
+    context: quickjs.Context,
+    implementations: dict[str, Callable[..., Any] | BaseTool] | None,
+    *,
+    execution_mode: Literal["sync", "async"] = "sync",
+    runtime: ToolRuntime | None = None,
+) -> None:
+    """Install foreign functions and JavaScript shims into a QuickJS context."""
+    external_functions = _build_external_functions(
+        implementations,
+        prefer_async=execution_mode == "async",
+        runtime=runtime,
+    )
+    for name, implementation in external_functions.items():
+        context.add_callable(name, implementation)
+    inject_external_function_shims(context, list(implementations or {}))
+
+
+__all__ = ["get_ptc_implementations", "install_external_functions"]

langchain_quickjs/middleware.py

@@ -0,0 +1,235 @@
+"""Middleware for providing a QuickJS-backed repl tool to an agent."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated, Any
+
+import quickjs
+from deepagents.middleware._utils import append_to_system_message
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    ContextT,
+    ModelRequest,
+    ModelResponse,
+    ResponseT,
+)
+from langchain.tools import ToolRuntime
+from langchain_core.tools import BaseTool, StructuredTool
+
+from langchain_quickjs._foreign_function_docs import render_external_functions_section
+from langchain_quickjs._foreign_functions import (
+    get_ptc_implementations,
+    install_external_functions,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from langchain.tools import ToolRuntime
+
+
+REPL_TOOL_DESCRIPTION = """Evaluates code using a QuickJS-backed JavaScript REPL.
+
+CRITICAL: The REPL does NOT retain state between calls. Each `repl` invocation is evaluated from scratch.
+Do NOT assume variables, functions, imports, or helper objects from prior `repl` calls are available.
+
+Capabilities and limitations:
+- Executes JavaScript with QuickJS.
+- Use `print(...)` to emit output. The tool returns printed lines joined with newlines.
+- The final expression value is returned only if nothing was printed.
+- There is no filesystem or network access unless you expose Python callables as foreign functions.
+{external_functions_section}
+"""  # noqa: E501  # preserve prompt text formatting exactly for the model
+
+REPL_SYSTEM_PROMPT = """## REPL tool
+
+You have access to a `repl` tool.
+
+CRITICAL: The REPL does NOT retain state between calls. Each `repl` invocation is evaluated from scratch.
+Do NOT assume variables, functions, imports, or helper objects from prior `repl` calls are available.
+
+- The REPL executes JavaScript with QuickJS.
+- Use `print(...)` to emit output. The tool returns printed lines joined with newlines.
+- The final expression value is returned only if nothing was printed.
+- There is no filesystem or network access unless equivalent foreign functions have been provided.
+- Use it for small computations, control flow, JSON manipulation, and calling externally registered foreign functions.
+{external_functions_section}
+"""  # noqa: E501  # preserve prompt text formatting exactly for the model
+
+
+class QuickJSMiddleware(AgentMiddleware[AgentState[Any], ContextT, ResponseT]):
+    """Provide a QuickJS-backed `repl` tool to an agent."""
+
+    def __init__(
+        self,
+        *,
+        ptc: list[Callable[..., Any] | BaseTool] | None = None,
+        add_ptc_docs: bool = False,
+        timeout: int | None = None,
+        memory_limit: int | None = None,
+    ) -> None:
+        """Initialize the middleware.
+
+        Args:
+            ptc: Functions or LangChain tools to expose inside the REPL.
+            add_ptc_docs: Whether to add signatures and docstrings for exposed PTC
+                functions to the system prompt.
+            timeout: Optional timeout in seconds for each evaluation.
+            memory_limit: Optional memory limit in bytes for each evaluation.
+        """
+        self._ptc = ptc or []
+        self._add_ptc_docs = add_ptc_docs
+        self._timeout = timeout
+        self._memory_limit = memory_limit
+        self.tools = [self._create_repl_tool()]
+
+    def _format_repl_system_prompt(self) -> str:
+        """Build the system prompt fragment describing the repl tool."""
+        external_functions_section = render_external_functions_section(
+            get_ptc_implementations(self._ptc),
+            add_docs=self._add_ptc_docs,
+        )
+        return REPL_SYSTEM_PROMPT.format(
+            external_functions_section=external_functions_section
+        )
+
+    def modify_request(self, request: ModelRequest[ContextT]) -> ModelRequest[ContextT]:
+        """Inject REPL usage instructions into the system message."""
+        repl_prompt = self._format_repl_system_prompt()
+        new_system_message = append_to_system_message(
+            request.system_message, repl_prompt
+        )
+        return request.override(system_message=new_system_message)
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest[ContextT],
+        handler: Callable[[ModelRequest[ContextT]], ModelResponse[ResponseT]],
+    ) -> ModelResponse[ResponseT]:
+        """Wrap model call to inject REPL instructions into system prompt."""
+        modified_request = self.modify_request(request)
+        return handler(modified_request)
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest[ContextT],
+        handler: Callable[
+            [ModelRequest[ContextT]], Awaitable[ModelResponse[ResponseT]]
+        ],
+    ) -> ModelResponse[ResponseT]:
+        """Async wrap model call to inject REPL instructions into system prompt."""
+        modified_request = self.modify_request(request)
+        return await handler(modified_request)
+
+    def _create_context(
+        self,
+        timeout: int | None,
+        printed_lines: list[str],
+        *,
+        prefer_async: bool = False,
+        runtime: ToolRuntime | None = None,
+    ) -> quickjs.Context:
+        """Create a configured QuickJS context for a single evaluation."""
+        context = quickjs.Context()
+        effective_timeout = timeout if timeout is not None else self._timeout
+        if effective_timeout is not None:
+            if effective_timeout <= 0:
+                msg = f"timeout must be positive, got {effective_timeout}."
+                raise ValueError(msg)
+            context.set_time_limit(effective_timeout)
+        if self._memory_limit is not None:
+            if self._memory_limit <= 0:
+                msg = f"memory_limit must be positive, got {self._memory_limit}."
+                raise ValueError(msg)
+            context.set_memory_limit(self._memory_limit)
+
+        def _print(*args: Any) -> None:
+            printed_lines.append(" ".join(map(str, args)))
+
+        context.add_callable("print", _print)
+        install_external_functions(
+            context,
+            get_ptc_implementations(self._ptc),
+            execution_mode="async" if prefer_async else "sync",
+            runtime=runtime,
+        )
+        return context
+
+    def _evaluate(
+        self,
+        code: str,
+        *,
+        timeout: int | None,
+        prefer_async: bool = False,
+        runtime: ToolRuntime | None = None,
+    ) -> str:
+        """Execute JavaScript and return printed output or final value."""
+        printed_lines: list[str] = []
+        try:
+            context = self._create_context(
+                timeout,
+                printed_lines,
+                prefer_async=prefer_async,
+                runtime=runtime,
+            )
+        except ValueError as exc:
+            return f"Error: {exc}"
+
+        try:
+            value = context.eval(code)
+        except quickjs.JSException as exc:
+            return str(exc)
+
+        if printed_lines:
+            return "\n".join(printed_lines).rstrip()
+        if value is None:
+            return ""
+        return str(value)
+
+    def _create_repl_tool(self) -> BaseTool:
+        """Create the LangChain tool wrapper around QuickJS execution."""
+
+        def _sync_quickjs(
+            code: Annotated[str, "Code string to evaluate in QuickJS."],
+            runtime: ToolRuntime,
+            timeout: Annotated[
+                int | None, "Optional timeout in seconds for this evaluation."
+            ] = None,
+        ) -> str:
+            """Execute a single QuickJS program and return captured stdout."""
+            return self._evaluate(
+                code,
+                timeout=timeout,
+                prefer_async=False,
+                runtime=runtime,
+            )
+
+        async def _async_quickjs(
+            code: Annotated[str, "Code string to evaluate in QuickJS."],
+            runtime: ToolRuntime,
+            timeout: Annotated[
+                int | None, "Optional timeout in seconds for this evaluation."
+            ] = None,
+        ) -> str:
+            """Execute a single QuickJS program in the async tool path."""
+            return self._evaluate(
+                code,
+                timeout=timeout,
+                prefer_async=True,
+                runtime=runtime,
+            )
+
+        tool_description = REPL_TOOL_DESCRIPTION.format(
+            external_functions_section=render_external_functions_section(
+                get_ptc_implementations(self._ptc),
+                add_docs=self._add_ptc_docs,
+            )
+        )
+
+        return StructuredTool.from_function(
+            name="repl",
+            description=tool_description,
+            func=_sync_quickjs,
+            coroutine=_async_quickjs,
+        )

langchain_quickjs-0.0.1.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: langchain-quickjs
+Version: 0.0.1
+Summary: QuickJS integration package for Deep Agents
+Project-URL: Homepage, https://github.com/langchain-ai/deepagents/tree/main/libs/partners/quickjs
+Project-URL: Repository, https://github.com/langchain-ai/deepagents
+Project-URL: Documentation, https://github.com/langchain-ai/deepagents/tree/main/libs/partners/quickjs
+License: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0,>=3.11
+Requires-Dist: deepagents
+Requires-Dist: quickjs<2,>=1.19.4
+Description-Content-Type: text/markdown
+
+# langchain-quickjs
+
+`langchain-quickjs` provides a QuickJS-backed REPL middleware for Deep Agents. It adds a `repl` tool that can evaluate small JavaScript snippets for computation, control flow, JSON manipulation, and calls to exposed Python foreign functions.
+
+## Basic usage
+
+```python
+from deepagents import create_deep_agent
+from langchain_quickjs import QuickJSMiddleware
+
+
+def normalize_name(name: str) -> str:
+    return name.strip().lower()
+
+
+agent = create_deep_agent(
+    model="openai:gpt-4.1",
+    tools=[],
+    middleware=[
+        QuickJSMiddleware(
+            ptc=[normalize_name],
+            add_ptc_docs=True,
+        )
+    ],
+)
+```
+
+With this middleware installed, the agent receives a `repl` tool that runs each JavaScript evaluation in a fresh QuickJS context. If you expose Python callables through `ptc`, they are available inside the REPL as foreign functions.
+
+## REPL behavior
+
+- The REPL is stateless. Each call starts from a fresh QuickJS context, so variables, functions, and other values defined in one `repl` call are not available in the next one.
+- Execution uses [QuickJS](https://bellard.org/quickjs/), so JavaScript support is limited to what QuickJS provides. It is good for small computations, control flow, JSON manipulation, and calling exposed foreign functions, but it is not a browser or Node.js runtime and does not provide their APIs.
+- Foreign functions support passing primitive values between JavaScript and Python, including `int`, `float`, `bool`, `str`, and `None`. Lists and dictionaries returned from Python are also supported and are bridged back into JavaScript arrays and objects.
+- Async foreign functions are supported. Because QuickJS callbacks are synchronous, awaitables are delegated to a dedicated daemon-thread event loop and their resolved results are returned back into the REPL call.
+
+## Current limitations
+
+- Does not work with HIL in the REPL.
+- Does not support `ToolRuntime` yet.

langchain_quickjs-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+langchain_quickjs/__init__.py,sha256=XJLajb7cQ2pYcFL2B5W_QqLJ47glRvge2SF9Z4e3IxQ,182
+langchain_quickjs/_foreign_function_docs.py,sha256=2mkq4dUhXDuGKOHL5NArcbc7HSI6uzmH0ZMinaHUxeM,16049
+langchain_quickjs/_foreign_functions.py,sha256=qwK0XTpTwb6SWXZ-Wx4groSnZXVnwV6ez3pOaOwZxdc,8506
+langchain_quickjs/middleware.py,sha256=54SXMF2Ojw5pXLLz7UtPSie87PtIYOYKChAiy8--4hY,8717
+langchain_quickjs-0.0.1.dist-info/METADATA,sha256=0WMdwzpjZIZl_7O-NNxZoECEObNoZ8Es1S9IUv5SZbs,2921
+langchain_quickjs-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+langchain_quickjs-0.0.1.dist-info/licenses/LICENSE,sha256=TsZ-TKbmch26hJssqCJhWXyGph7iFLvyFBYAa3stBHg,1067
+langchain_quickjs-0.0.1.dist-info/RECORD,,

langchain_quickjs-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

langchain_quickjs-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) LangChain, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.