cecli-dev 1.6.0rc5__tar.gz → 1.6.2rc1__tar.gz

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cecli-dev
-Version: 1.6.0rc5
+Version: 1.6.2rc1
 Summary: we also can't pronounce cecli
 Project-URL: Homepage, https://github.com/dwash96/cecli
 Project-URL: Documentation, https://github.com/dwash96/cecli

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.6.0rc5'
-__version_tuple__ = version_tuple = (1, 6, 0, 'rc5')
+__version__ = version = '1.6.2rc1'
+__version_tuple__ = version_tuple = (1, 6, 2, 'rc1')
 
-__commit_id__ = commit_id = 'gca072134c'
+__commit_id__ = commit_id = 'g699b98e21'

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/coders/base_coder.py

@@ -46,6 +46,7 @@ from cecli.helpers.loop_detect import LoopDetectedError, LoopDetector
 from cecli.helpers.memory_control import trim_memory
 from cecli.helpers.observations.service import ObservationService
 from cecli.helpers.profiler import TokenProfiler
+from cecli.helpers.sessions import SessionManager
 from cecli.helpers.threading import ThreadSafeEvent
 from cecli.history import ChatSummary
 from cecli.hooks import HookIntegration
@@ -53,7 +54,6 @@ from cecli.io import ConfirmGroup, InputOutput
 from cecli.linter import Linter
 from cecli.llm import litellm
 from cecli.mcp import LocalServer
-from cecli.models import RETRY_TIMEOUT
 from cecli.reasoning_tags import (
     REASONING_TAG,
     format_reasoning_content,
@@ -64,7 +64,6 @@ from cecli.repo import ANY_GIT_ERROR, GitRepoProxy
 from cecli.repomap import RepoMap
 from cecli.report import update_error_prefix
 from cecli.run_cmd import run_cmd_async
-from cecli.sessions import SessionManager
 from cecli.tools.utils.output import print_tool_response
 from cecli.tools.utils.registry import ToolRegistry
 from cecli.utils import copy_tool_call, format_tokens, is_image_file
@@ -2829,24 +2828,14 @@ class Coder(metaclass=UsageMeta):
                 except EmptyResponseError:
                     self.io.tool_warning(self.empty_llm_tool_warning())
 
-                    retry_on_empty = False
-                    retries_config = self.get_active_model().retries
-                    if isinstance(retries_config, str):
-                        try:
-                            retries_config = json.loads(retries_config)
-                        except json.JSONDecodeError:
-                            self.io.tool_warning(
-                                f"Could not parse retries config: {retries_config}"
-                            )
-                            retries_config = {}
-                    if isinstance(retries_config, dict):
-                        retry_on_empty = retries_config.get("retry_on_empty", False)
+                    retry_config = models.parse_retry_config(self.get_active_model().retries)
+                    retry_on_empty = retry_config["retry_on_empty"]
 
                     if not retry_on_empty:
                         break
 
-                    retry_delay *= 2
-                    if retry_delay > RETRY_TIMEOUT:
+                    retry_delay *= retry_config["retry_backoff_factor"]
+                    if retry_delay > retry_config["retry_timeout"]:
                         self.io.tool_error("Retry timeout exceeded on empty response.")
                         break
 
@@ -2866,10 +2855,15 @@ class Coder(metaclass=UsageMeta):
                         exhausted = True
                         break
 
+                    retry_config = models.parse_retry_config(self.get_active_model().retries)
+
                     should_retry = ex_info.retry
+                    if ex_info.name == "ServiceUnavailableError":
+                        should_retry = should_retry or retry_config["retry_on_unavailable"]
+
                     if should_retry:
-                        retry_delay *= 2
-                        if retry_delay > RETRY_TIMEOUT:
+                        retry_delay *= retry_config["retry_backoff_factor"]
+                        if retry_delay > retry_config["retry_timeout"]:
                             should_retry = False
 
                     if not should_retry:
@@ -3193,7 +3187,8 @@ class Coder(metaclass=UsageMeta):
                 tool_name_from_schema = nested.getter(tool, "function.name")
                 if (
                     tool_name_from_schema
-                    and tool_name_from_schema.lower() == unprefixed_tool_name.lower()
+                    and responses.sanitize_tool_name(tool_name_from_schema).lower()
+                    == responses.sanitize_tool_name(unprefixed_tool_name).lower()
                 ):
                     # Find the McpServer instance that will be used for communication
                     for server in self.mcp_manager:
@@ -3415,6 +3410,10 @@ class Coder(metaclass=UsageMeta):
         # with a "missing required parameter" error.
         arguments = responses.coerce_tool_structure(arguments)
 
+        # Providers require a provider-safe tool name, so the name coming back
+        # from the model may not be the name the MCP server advertises.
+        name = responses.original_tool_name(name)
+
         return await session.call_tool(name=name, arguments=arguments)
 
     async def process_tool_calls(self, tool_call_response):
@@ -3504,6 +3503,7 @@ class Coder(metaclass=UsageMeta):
 
     def get_tool_list(self):
         """Get a flattened list of all MCP tools with server prefixes, filtered by registered_servers."""
+        responses.register_tool_names(self.mcp_tools)
         tool_list = []
         if self.mcp_tools:
             for server_name, server_tools in self.mcp_tools:
@@ -5234,6 +5234,7 @@ class Coder(metaclass=UsageMeta):
                     session_manager.save_session,
                     getattr(self.args, "auto_save_session_name", "auto-save"),
                     False,
+                    True,
                 )
             except Exception:
                 # Don't show errors for auto-save to avoid interrupting the user experience

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/commands/core.py

@@ -92,57 +92,6 @@ class Commands:
         # Commands that should NOT trigger auto-processing of the queue
         self._MANAGEMENT_COMMANDS = {"queue", "list-queue", "remove-queue"}
 
-    # ── Queue Management Methods (CLI-33) ────────────────────────────── #
-    #
-    # The prompt queue itself lives on the coder (Coder.prompt_queue) and
-    # is managed by cecli.helpers.command_queue. These thin wrappers keep
-    # the /queue, /list-queue and /remove-queue command implementations
-    # stable while operating on the coder that owns this Commands
-    # instance, so each sub-agent's commands manage that sub-agent's own
-    # queue.
-
-    @property
-    def prompt_queue(self):
-        """Proxy to the owning coder's prompt queue."""
-        coder = self.coder
-        return coder.prompt_queue if coder is not None else []
-
-    def _insert_prompt(self, text: str, index: int) -> dict:
-        """Insert a prompt at the given index in the active coder's queue."""
-        from cecli.helpers import command_queue
-
-        return command_queue.insert_prompt(self._active_coder(), text, index)
-
-    def _enqueue_prompt(self, text: str) -> dict:
-        """Add a prompt to the owning coder's queue."""
-        from cecli.helpers import command_queue
-
-        return command_queue.enqueue_prompt(self.coder, text)
-
-    def _dequeue_prompt(self) -> dict | None:
-        """Remove and return the first item from the owning coder's queue."""
-        from cecli.helpers import command_queue
-
-        return command_queue.dequeue_prompt(self.coder)
-
-    def _get_queue_length(self) -> int:
-        """Return the current number of items in the owning coder's queue."""
-        from cecli.helpers import command_queue
-
-        return command_queue.get_queue_length(self.coder)
-
-    def _remove_from_queue(self, index: int) -> dict | None:
-        """Remove and return the item at the given index from the owning coder's queue."""
-        from cecli.helpers import command_queue
-
-        return command_queue.remove_from_queue(self.coder, index)
-
-    def _clear_queue(self) -> list:
-        """Remove all items from the owning coder's queue and return them."""
-        from cecli.helpers import command_queue
-
-        return command_queue.clear_queue(self.coder)
-
     def _load_custom_commands(self, custom_commands):
         """
         Load custom commands from plugin paths.

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/commands/insert_queue.py

@@ -4,6 +4,7 @@ from typing import List
 
 from cecli.commands.utils.base_command import BaseCommand
 from cecli.commands.utils.helpers import format_command_result
+from cecli.helpers import command_queue
 
 
 class InsertQueueCommand(BaseCommand):
@@ -57,7 +58,7 @@ class InsertQueueCommand(BaseCommand):
 
         # Happy path: insert the prompt
         try:
-            item = coder.commands._insert_prompt(prompt_text, index)
+            item = command_queue.insert_prompt(coder, prompt_text, index)
             io.tool_output(f"Prompt inserted at position {index + 1} (id: {item['id']})")
             return f"Successfully executed {cls.NORM_NAME}."
         except ValueError as e:

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/commands/list_queue.py

@@ -5,6 +5,7 @@ from typing import List
 
 from cecli.commands.utils.base_command import BaseCommand
 from cecli.commands.utils.helpers import format_command_result
+from cecli.helpers import command_queue
 
 
 class ListQueueCommand(BaseCommand):
@@ -30,7 +31,7 @@ class ListQueueCommand(BaseCommand):
                 io, cls.NORM_NAME, "", error="Command system not available. Cannot list queue."
             )
 
-        queue = coder.commands.prompt_queue
+        queue = command_queue.list_queue(coder)
 
         # Sad path: empty queue
         if not queue:

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/commands/list_sessions.py

@@ -11,7 +11,7 @@ class ListSessionsCommand(BaseCommand):
     @classmethod
     async def execute(cls, io, coder, args, **kwargs):
         """Execute the list-sessions command with given parameters."""
-        from cecli import sessions
+        from cecli.helpers import sessions
 
         session_manager = sessions.SessionManager(coder, io)
         sessions_list = session_manager.list_sessions()

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/commands/load_session.py

@@ -15,7 +15,7 @@ class LoadSessionCommand(BaseCommand):
             io.tool_output("Usage: /load-session <session-name>")
             return format_command_result(io, "load-session", "No session name provided")
 
-        from cecli import sessions
+        from cecli.helpers import sessions
 
         session_manager = sessions.SessionManager(coder, io)
         await session_manager.load_session(args.strip())
@@ -26,7 +26,7 @@ class LoadSessionCommand(BaseCommand):
     def get_completions(cls, io, coder, args) -> List[str]:
         """Get completion options for load-session command."""
         # Return available session names for completion
-        from cecli import sessions
+        from cecli.helpers import sessions
 
         session_manager = sessions.SessionManager(coder, io)
         sessions_list = session_manager.list_sessions()
@@ -41,7 +41,10 @@ class LoadSessionCommand(BaseCommand):
         help_text += "\nExamples:\n"
         help_text += "  /load-session my-feature      # Load session 'my-feature'\n"
         help_text += "  /load-session bug-fix         # Load session 'bug-fix'\n"
-        help_text += "\nSessions are loaded from the .cecli/sessions/ directory.\n"
+        help_text += (
+            "\nSessions are loaded from the .cecli/sessions/ directory. Loading a session"
+            " also restores any sub-agents saved with it.\n"
+        )
         help_text += (
             "Use /list-sessions to see saved sessions and /save-session to save a session.\n"
         )

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/commands/queue.py

@@ -4,6 +4,7 @@ from typing import List
 
 from cecli.commands.utils.base_command import BaseCommand
 from cecli.commands.utils.helpers import format_command_result
+from cecli.helpers import command_queue
 
 
 class QueueCommand(BaseCommand):
@@ -55,8 +56,8 @@ class QueueCommand(BaseCommand):
 
         # Happy path: enqueue the prompt
         try:
-            item = coder.commands._enqueue_prompt(prompt_text)
-            position = len(coder.commands.prompt_queue)
+            item = command_queue.enqueue_prompt(coder, prompt_text)
+            position = command_queue.get_queue_length(coder)
             io.tool_output(f"Prompt queued at position {position} (id: {item['id']})")
             return f"Successfully executed {cls.NORM_NAME}."
         except ValueError as e:

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/commands/remove_queue.py

@@ -4,6 +4,7 @@ from typing import List
 
 from cecli.commands.utils.base_command import BaseCommand
 from cecli.commands.utils.helpers import format_command_result
+from cecli.helpers import command_queue
 
 
 class RemoveQueueCommand(BaseCommand):
@@ -33,14 +34,14 @@ class RemoveQueueCommand(BaseCommand):
             )
 
         # Sad path: empty queue
-        if coder.commands._get_queue_length() == 0:
+        if command_queue.get_queue_length(coder) == 0:
             return format_command_result(
                 io, cls.NORM_NAME, "", error="Queue is empty. Nothing to remove."
             )
 
         # Handle wildcard: clear entire queue
         if args and args.strip() == "*":
-            items = coder.commands._clear_queue()
+            items = command_queue.clear_queue(coder)
             count = len(items)
             io.tool_output(f"Removed all {count} queued prompt(s).")
             return f"Successfully executed {cls.NORM_NAME}."
@@ -57,9 +58,9 @@ class RemoveQueueCommand(BaseCommand):
                     error=f"Invalid index: '{args.strip()}'. Please provide a number or '*'.",
                 )
 
-            item = coder.commands._remove_from_queue(index)
+            item = command_queue.remove_from_queue(coder, index)
             if item is None:
-                queue_len = coder.commands._get_queue_length()
+                queue_len = command_queue.get_queue_length(coder)
                 return format_command_result(
                     io,
                     cls.NORM_NAME,
@@ -71,7 +72,7 @@ class RemoveQueueCommand(BaseCommand):
             return f"Successfully executed {cls.NORM_NAME}."
 
         # Interactive mode: no args provided
-        queue = coder.commands.prompt_queue
+        queue = command_queue.list_queue(coder)
         io.tool_output("Queued prompts:")
         for i, item in enumerate(queue, 1):
             text = item["text"][:80]
@@ -91,7 +92,7 @@ class RemoveQueueCommand(BaseCommand):
         if not coder.commands:
             return []
 
-        queue_len = coder.commands._get_queue_length()
+        queue_len = command_queue.get_queue_length(coder)
         completions = [str(i) for i in range(1, queue_len + 1)]
         completions.append("*")
         return completions

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/commands/save_session.py

@@ -15,7 +15,7 @@ class SaveSessionCommand(BaseCommand):
             io.tool_error("Please provide a session name to save.")
             return format_command_result(io, "save-session", "No session name provided")
 
-        from cecli import sessions
+        from cecli.helpers import sessions
 
         session_manager = sessions.SessionManager(coder, io)
         session_manager.save_session(args.strip())
@@ -26,7 +26,7 @@ class SaveSessionCommand(BaseCommand):
     def get_completions(cls, io, coder, args) -> List[str]:
         """Get completion options for save-session command."""
         # Return existing session names for completion to prevent accidental overwrites
-        from cecli import sessions
+        from cecli.helpers import sessions
 
         session_manager = sessions.SessionManager(coder, io)
         sessions_list = session_manager.list_sessions()
@@ -42,6 +42,10 @@ class SaveSessionCommand(BaseCommand):
         help_text += "  /save-session my-feature      # Save session as 'my-feature'\n"
         help_text += "  /save-session bug-fix         # Save session as 'bug-fix'\n"
         help_text += "\nSessions are saved in the .cecli/sessions/ directory as JSON files.\n"
+        help_text += (
+            "When the session has sub-agents it is saved as a folder holding the primary"
+            " and each sub-agent payload.\n"
+        )
         help_text += "Use /list-sessions to see saved sessions and /load-session to load them.\n"
         help_text += (
             "\nNote: Existing session names will be shown for tab completion to help prevent"

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/helpers/hashpos/transformations.py

@@ -297,7 +297,7 @@ def apply_contextual_marker(
     range_end: str,
     num_lines: int,
 ) -> tuple[list[int], list[int]]:
-    """Expand range using @C{{num}}, @P{{num}}, or @N{{num}} contextual markers.
+    """Expand range using @C<num>, @P<num>, or @N<num> contextual markers.
 
     Requires exactly one start match.  Raises ValueError when the number
     of start matches is not 1 (the caller is expected to format the error

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/helpers/model_config/pipeline.py

@@ -333,7 +333,9 @@ def _closest_provider_match(sources, provider, route):
 
     Raw sources are enumerated via a lightweight top-level key scan (a string
     pass, never a full parse) and only ``provider/``-prefixed keys are parsed
-    for scoring, so the fallback stays memory friendly.
+    for scoring, so the fallback stays memory friendly. A candidate with no
+    shared leading characters is not a match: returning it would let an
+    unrelated route inherit an arbitrary sibling record's wire mode.
     """
     if not provider:
         return None
@@ -376,7 +378,7 @@ def _closest_provider_match(sources, provider, route):
                     best_score = score
                     best = record
 
-    return best
+    return best if best_score > 0 else None
 
 
 def _prefix_score(left, right):

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/helpers/model_providers.py

@@ -399,6 +399,10 @@ class ModelProviderManager:
             )
             response.raise_for_status()
             return response.json()
+        except requests.exceptions.ConnectionError:
+            # Unreachable endpoint (e.g. no local Ollama server at
+            # localhost:11434): stay silent and contribute no models.
+            return None
         except Exception as ex:
             print(f"Failed to fetch {provider} model list: {ex}")
             return None

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/helpers/orchestration/agent_proxy.py

@@ -89,10 +89,27 @@ class AgentProxy:
                             self._coder,
                             mcp_server=server,
                             mcp_tool_name=schema_name,
+                            tool_schema=tool_schema,
                         )
 
         raise ValueError(f"Unknown tool: '{tool_name}'")
 
+    def get_tool_schema(self, tool_name: str) -> dict[str, Any] | None:
+        """Return a copy of the full function-calling schema for a tool.
+
+        Returns ``None`` when the tool has no schema. Unknown or disallowed
+        tools raise the same errors as ``get_tool``.
+        """
+        return self.get_tool(tool_name).get_schema()
+
+    def get_tool_signature(self, tool_name: str) -> str | None:
+        """Return a readable Python-style call signature for a tool.
+
+        Optional parameters without a declared default use ``...`` to show
+        that they may be omitted without implying a value such as ``None``.
+        """
+        return self.get_tool(tool_name).get_signature()
+
     def _find_mcp_server(self, server_name: str, server_prefix: str) -> Any:
         if not hasattr(self._coder, "mcp_manager") or not self._coder.mcp_manager:
             return None

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/helpers/orchestration/environment.py

@@ -547,7 +547,7 @@ def build_orchestration_context_block(agent_config: dict[str, Any]) -> str | Non
     context = """<context name="orchestration" from="agent">
 The `Orchestrate` tool runs Python in a sandbox where you can script other tools programmatically. 
 Use it for batch, loop-heavy, and repeat-able workflows.
-Variables and helpers persist across calls; `state` persists across all Orchestrate calls in the session.
+The sandbox is stateless between calls — variables don't persist. To carry values across calls, use `state` (per-agent) or `shared_state` (cross-agent).
 You may need to explore the below primitives to understand how to use the sandbox effectively.
 
 ### Primitives
@@ -556,11 +556,13 @@ You may need to explore the below primitives to understand how to use the sandbo
 |-----------|--------------|
 | `Agent.allowed_methods()` / `Agent.allowed_tools()` | List helper methods and available tools |
 | `Agent.get_tool(name)` | Get a tool proxy (case-insensitive; `Local--` / `{{Server Name}}--` prefixes ok) |
+| `Agent.get_tool_schema(name)` | Return a copy of the full function-calling JSON schema |
+| `Agent.get_tool_signature(name)` | Return a readable Python-style signature; optional params without defaults appear as `= ...` |
 | `await tool.call(**params)` | Run a tool; returns `{"result": [...], "errors": [...], "details": [...]}`, items with shape `{"content", "_"}` |
 | `Agent.peek(result)` / `Agent.get_value(result, path, default?)` | Inspect / extract values from tool results. path is dot-separated string |
 | `Agent.resolve_regions(path, specs)` / `Agent.edit_region(path, edits)` | Resolve text boundaries once, then apply edits |
 | `gather(**tasks)` | Run tasks concurrently; results expose `.key` and `["key"]` |
-| `state` / `shared_state` | Persistent dicts; `state.get(k)` falls back to `shared_state` |
+| `state` / `shared_state` | Persistent dicts that survive between Orchestrate calls; `state.get(k)` falls back to `shared_state`. Use these for anything you need to reuse in a later call |
 | `print(...)` / `reset(local_vars=True, state=False)` | Emit output / clear namespaces |
 | `typeof(x)`, `isinstance(x, t)`, `hasattr(x, n)`, `repr(x)`, `vars(obj)` | Type inspection and debugging |
 

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/helpers/orchestration/safe_methods.py

@@ -12,6 +12,7 @@ import json
 import pathlib
 import re as _re_mod
 import traceback as _tb_mod
+from collections.abc import Mapping
 from typing import Any
 
 # ---------------------------------------------------------------------------
@@ -139,12 +140,12 @@ async def _safe_sleep(seconds: float) -> None:
     await asyncio.sleep(seconds)
 
 
-class GatherResult:
-    """Result container for named ``gather()`` calls.
+class GatherResult(Mapping[str, Any]):
+    """Read-only mapping of named ``gather()`` task results.
 
-    Supports both attribute access (``results.my_task``) and
-    key access (``results["my_task"]``), plus ``len()`` and
-    iteration for unpacking.
+    Supports standard mapping access (``results["task"]``, iteration over
+    keys, and ``keys()``, ``values()``, and ``items()``) plus attribute access
+    as a convenience. Use key access when task names may collide with methods.
     """
 
     def __init__(self, results: dict[str, Any]) -> None:
@@ -192,7 +193,7 @@ class GatherResult:
 
     def __iter__(self):
         results = object.__getattribute__(self, "_results")
-        return iter(results.items())
+        return iter(results)
 
     def keys(self) -> Any:
         results = object.__getattribute__(self, "_results")
@@ -225,12 +226,12 @@ async def _safe_gather(*args: Any, **named_awaitables: Any):
     Safely execute multiple awaitables concurrently.
 
     All awaitables must be passed as keyword arguments. Results are returned
-    as a ``GatherResult`` with attribute and key access:
+    as a ``GatherResult`` mapping with attribute access as a convenience:
 
         results = await gather(read_a=task_a, grep_b=task_b)
-        print(results.read_a)       # attribute access
-        print(results["grep_b"])    # key access
-        len(results)                # number of results
+        print(results["read_a"])   # canonical mapping access
+        print(results.grep_b)      # attribute convenience
+        list(results)              # task names
 
     Forces ``return_exceptions=True`` so that failures in one task
     do not crash the entire batch. Exceptions are converted to

{cecli_dev-1.6.0rc5 → cecli_dev-1.6.2rc1}/cecli/helpers/orchestration/tool_proxy.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+from copy import deepcopy
 from typing import Any
 
 
@@ -63,6 +64,7 @@ class ToolProxy:
         tool_module: Any = None,
         mcp_server: Any = None,
         mcp_tool_name: str = "",
+        tool_schema: dict[str, Any] | None = None,
     ) -> None:
         # Respect the per-coder tool includelist/excludelist filters
         incl = getattr(coder, "registered_tools", {}).get("included", set())
@@ -78,6 +80,16 @@ class ToolProxy:
         self._tool_module = tool_module
         self._mcp_server = mcp_server
         self._mcp_tool_name = mcp_tool_name
+        self._tool_schema = (
+            tool_schema if tool_schema is not None else getattr(tool_module, "SCHEMA", None)
+        )
+
+    def get_schema(self) -> dict[str, Any] | None:
+        """Return a deep copy of this tool's JSON schema, if available."""
+        if not isinstance(self._tool_schema, dict):
+            return None
+
+        return deepcopy(self._tool_schema)
 
     async def __call__(self, *args: Any, **kwargs: Any):
         """Make the proxy directly callable.
@@ -131,12 +143,79 @@ class ToolProxy:
 
         return await self.call(**kwargs)
 
+    def get_signature(self) -> str | None:
+        """Return a readable Python-style signature based on the JSON schema.
+
+        Type annotations are best-effort summaries; use the schema for exact
+        constraints. Optional parameters without defaults display as ``...``.
+        """
+        schema = self._tool_schema
+        if not isinstance(schema, dict):
+            return None
+
+        function = schema.get("function", {})
+        if not isinstance(function, dict):
+            return None
+
+        parameters = function.get("parameters", {})
+        if not isinstance(parameters, dict):
+            return None
+
+        properties = parameters.get("properties", {})
+        if not isinstance(properties, dict):
+            return None
+
+        required = parameters.get("required", [])
+        required = set(required) if isinstance(required, list) else set()
+        signature_parameters = []
+        for name, property_schema in properties.items():
+            annotation = self._python_type_name(property_schema)
+            parameter = f"{name}: {annotation}"
+            if name not in required:
+                if isinstance(property_schema, dict) and "default" in property_schema:
+                    parameter += f" = {property_schema['default']!r}"
+                else:
+                    parameter += " = ..."
+            signature_parameters.append(parameter)
+
+        function_name = function.get("name") or self._tool_name
+        if signature_parameters:
+            return f"{function_name}(*, {', '.join(signature_parameters)})"
+        return f"{function_name}()"
+
+    @staticmethod
+    def _python_type_name(schema: Any) -> str:
+        """Render common JSON Schema types as readable Python type names."""
+        if not isinstance(schema, dict):
+            return "Any"
+
+        schema_type = schema.get("type")
+        if isinstance(schema_type, list):
+            type_names = [ToolProxy._python_type_name({"type": item}) for item in schema_type]
+            return " | ".join(type_names)
+
+        type_names = {
+            "array": "list",
+            "boolean": "bool",
+            "integer": "int",
+            "number": "float",
+            "null": "None",
+            "object": "dict",
+            "string": "str",
+        }
+        if schema_type in type_names:
+            return type_names[schema_type]
+
+        alternatives = schema.get("anyOf") or schema.get("oneOf")
+        if isinstance(alternatives, list):
+            return " | ".join(ToolProxy._python_type_name(item) for item in alternatives)
+
+        return "Any"
+
     def _get_param_names(self) -> list:
-        """Extract ordered parameter names from the tool's JSON Schema."""
-        if self._tool_module is None:
-            return []
+        """Extract parameter names in schema order for positional calls."""
         try:
-            props = self._tool_module.SCHEMA["function"]["parameters"]["properties"]
+            props = self._tool_schema["function"]["parameters"]["properties"]
             return list(props.keys())
         except (KeyError, TypeError, AttributeError):
             return []