cecli-dev 1.6.0rc4__tar.gz → 1.6.1__tar.gz

{cecli_dev-1.6.0rc4 → cecli_dev-1.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cecli-dev
-Version: 1.6.0rc4
+Version: 1.6.1
 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.0rc4 → cecli_dev-1.6.1}/cecli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.6.0rc4'
-__version_tuple__ = version_tuple = (1, 6, 0, 'rc4')
+__version__ = version = '1.6.1'
+__version_tuple__ = version_tuple = (1, 6, 1)
 
-__commit_id__ = commit_id = 'gf40f954f0'
+__commit_id__ = commit_id = 'ge49b18e26'

{cecli_dev-1.6.0rc4 → cecli_dev-1.6.1}/cecli/coders/agent_coder.py

@@ -939,7 +939,11 @@ class AgentCoder(Coder):
             lint_coro = self.lint_edited(edited, show_output=False)
             lint_errors, interrupted = await interruptible(lint_coro, self.interrupt_event)
             if interrupted:
-                raise KeyboardInterrupt("Interrupted during linting")
+                # Abort the turn with CancelledError, which the linear run loop
+                # handles by re-prompting for input. KeyboardInterrupt is a
+                # BaseException that would escape the worker's event loop and
+                # leave it unable to accept further prompts.
+                raise asyncio.CancelledError("Interrupted during linting")
 
             has_errors = False
 
@@ -1078,7 +1082,10 @@ class AgentCoder(Coder):
             sleep_coro = asyncio.sleep(command_timeout / 2)
             _res, interrupted = await interruptible(sleep_coro, self.interrupt_event)
             if interrupted:
-                raise KeyboardInterrupt("Interrupted while waiting for background commands")
+                # Use CancelledError (not KeyboardInterrupt) so the interrupt
+                # stays inside the worker loop and re-prompts, matching the
+                # lint interrupt path above.
+                raise asyncio.CancelledError("Interrupted while waiting for background commands")
             return True
 
         # Check for recently finished commands that need reflection

{cecli_dev-1.6.0rc4 → cecli_dev-1.6.1}/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
@@ -64,7 +65,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
@@ -1999,7 +1999,13 @@ class Coder(metaclass=UsageMeta):
             if self.commands.is_run_command(inp):
                 self.commands.cmd_running_event.clear()  # Command is running
 
-            return await self.commands.run(inp, coder=self, **run_kwargs)
+            try:
+                return await self.commands.run(inp, coder=self, **run_kwargs)
+            finally:
+                # Dispatch can return early (unknown/ambiguous command) or
+                # raise without ever running a command; the gate must still be
+                # reopened or the input/output loops park forever.
+                self.commands.cmd_running_event.set()
 
         await self.check_for_file_mentions(inp)
         inp = await self.check_for_urls(inp)
@@ -5228,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.0rc4 → cecli_dev-1.6.1}/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.0rc4 → cecli_dev-1.6.1}/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.0rc4 → cecli_dev-1.6.1}/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.0rc4 → cecli_dev-1.6.1}/cecli/helpers/coroutines.py

@@ -9,16 +9,10 @@ logger = logging.getLogger(__name__)
 # Strong reference pool to protect fire-and-forget tasks from garbage collection
 background_tasks: set = set()
 
-
-def _handle_result(task: asyncio.Task) -> None:
-    """Callback to clean up references and capture exceptions safely."""
-    background_tasks.discard(task)
-    try:
-        task.result()
-    except asyncio.CancelledError:
-        pass
-    except Exception as e:
-        logger.error(f"Background task failed: {e}", exc_info=True)
+# Grace period granted to a cancelled task to unwind. Transports that defer or
+# swallow cancellation (AnyIO cancel scopes, shielded streams) would otherwise
+# block the interrupting coroutine forever.
+INTERRUPT_UNWIND_GRACE_SECONDS = 5.0
 
 
 def fire_and_forget(coro) -> asyncio.Task:
@@ -35,6 +29,7 @@ async def interruptible_async_generator(async_generator, interrupt_event):
     """
     gen = async_generator.__aiter__()
     interrupt_task = asyncio.create_task(interrupt_event.wait())
+    next_task = None
 
     try:
         while True:
@@ -44,11 +39,7 @@ async def interruptible_async_generator(async_generator, interrupt_event):
             )
 
             if interrupt_task in done:
-                next_task.cancel()
-                try:
-                    await next_task
-                except asyncio.CancelledError:
-                    pass
+                await cancel_and_abandon([next_task])
                 break
 
             if next_task in done:
@@ -57,11 +48,9 @@ async def interruptible_async_generator(async_generator, interrupt_event):
                 except StopAsyncIteration:
                     break
     finally:
-        interrupt_task.cancel()
-        try:
-            await interrupt_task
-        except asyncio.CancelledError:
-            pass
+        # Cancel whichever task is still pending if the generator is closed early
+        # (e.g. GeneratorExit at the wait or yield), not just the interrupt waiter.
+        await cancel_and_abandon([task for task in (next_task, interrupt_task) if task is not None])
 
 
 def is_active(task):
@@ -83,6 +72,10 @@ async def interruptible(coroutine, interrupt_event):
         A tuple of (result, interrupted).
         - If not interrupted: (coroutine_result, False)
         - If interrupted: (None, True)
+
+    A task that ignores cancellation is abandoned once the grace period
+    elapses (see cancel_and_abandon) so a wedged transport cannot block the
+    caller forever.
     """
     if interrupt_event is None:
         interrupt_event = ThreadSafeEvent()
@@ -90,25 +83,26 @@ async def interruptible(coroutine, interrupt_event):
     main_task = asyncio.create_task(coroutine)
     interrupt_task = asyncio.create_task(interrupt_event.wait())
 
-    done, pending = await asyncio.wait(
-        {main_task, interrupt_task},
-        return_when=asyncio.FIRST_COMPLETED,
-    )
+    try:
+        done, pending = await asyncio.wait(
+            {main_task, interrupt_task},
+            return_when=asyncio.FIRST_COMPLETED,
+        )
 
-    for task in pending:
-        task.cancel()
-        try:
-            await task
-        except asyncio.CancelledError:
-            pass  # Expected
+        await cancel_and_abandon(pending)
 
-    if interrupt_task in done:
-        return None, True
+        if interrupt_task in done:
+            return None, True
 
-    try:
-        return main_task.result(), False
-    except asyncio.CancelledError:
-        return None, True
+        try:
+            return main_task.result(), False
+        except asyncio.CancelledError:
+            return None, True
+    finally:
+        # When the caller is cancelled while waiting, neither branch above
+        # runs, so cancel any remaining tasks here instead of orphaning the
+        # inner coroutine (which would keep running detached).
+        await cancel_and_abandon([main_task, interrupt_task])
 
 
 def task_is_cancelling() -> bool:
@@ -133,3 +127,58 @@ def task_is_cancelling() -> bool:
 
     # Python 3.10 fallback: best-effort only (see docstring).
     return bool(getattr(task, "_must_cancel", False))
+
+
+def drain_task_results(tasks):
+    """Consume exceptions from finished tasks so they aren't reported as unretrieved."""
+    for task in tasks:
+        if task.cancelled():
+            continue
+
+        try:
+            exc = task.exception()
+        except (asyncio.CancelledError, asyncio.InvalidStateError):
+            continue
+
+        if exc is not None:
+            logger.warning(f"Task raised while unwinding after interrupt: {exc}")
+
+
+async def cancel_and_abandon(tasks, grace=INTERRUPT_UNWIND_GRACE_SECONDS):
+    """Cancel tasks and wait up to ``grace`` seconds for them to unwind.
+
+    Cancellation is cooperative, and some transports (AnyIO cancel scopes,
+    shielded streams) defer or swallow it. Waiting on them unconditionally
+    would block the caller forever, so anything still running after the grace
+    period is abandoned: it keeps a strong reference so it can finish on its
+    own without tripping the "Task was destroyed but it is pending" warning.
+    """
+    pending_tasks = [task for task in tasks if not task.done()]
+
+    if not pending_tasks:
+        return
+
+    for task in pending_tasks:
+        task.cancel()
+
+    done, still_running = await asyncio.wait(set(pending_tasks), timeout=grace)
+    drain_task_results(done)
+
+    for task in still_running:
+        logger.warning(
+            f"Task ignored cancellation after {grace}s; abandoning it. It may still be"
+            " running and could touch shared state later."
+        )
+        background_tasks.add(task)
+        task.add_done_callback(_handle_result)
+
+
+def _handle_result(task: asyncio.Task) -> None:
+    """Callback to clean up references and capture exceptions safely."""
+    background_tasks.discard(task)
+    try:
+        task.result()
+    except asyncio.CancelledError:
+        pass
+    except Exception as e:
+        logger.error(f"Background task failed: {e}", exc_info=True)

{cecli_dev-1.6.0rc4 → cecli_dev-1.6.1}/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.1/cecli/helpers/lock_detect.py

@@ -0,0 +1,137 @@
+import asyncio
+import logging
+import os
+import sys
+import threading
+import time
+import traceback
+
+from cecli.decoding import safe_open
+
+# Set up logging to catch asyncio framework logs
+logging.basicConfig(level=logging.INFO)
+logging.getLogger("asyncio").setLevel(logging.DEBUG)
+
+
+# Registered event loops whose asyncio tasks are included in each dump.
+# Task state is only read from the owning loop (see _dump_async_state), since
+# thread stacks alone cannot show coroutine/task state.
+_async_loops: dict = {}
+_async_state_providers: dict = {}
+
+
+def dump_stacks_to_file(filename=".cecli/logs/threads.log", interval=5, max_prints=10):
+    """Periodically writes stack traces to a file, resetting it after max_prints."""
+    print_count = 0
+
+    log_dir = os.path.dirname(filename)
+    if log_dir:
+        os.makedirs(log_dir, exist_ok=True)
+
+    while True:
+        time.sleep(interval)
+        try:
+            # Determine mode: "w" to overwrite/clear on the 11th print, "a" to append
+            mode = "w" if print_count >= max_prints else "a"
+
+            with safe_open(filename, mode) as f:
+                if mode == "w":
+                    f.write(f"--- Log reset automatically after {max_prints} prints ---\n")
+                    print_count = 0  # Reset the counter
+
+                timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
+                f.write(
+                    f"\n=================== STACK TRACE DUMP ({timestamp}) ===================\n"
+                )
+
+                for thread_id, frame in sys._current_frames().items():
+                    thread_obj = threading._active.get(thread_id)
+                    thread_name = thread_obj.name if thread_obj else "Unknown Thread"
+
+                    f.write(f"\nThread Name: {thread_name} (ID: {thread_id})\n")
+                    f.write("-" * 40 + "\n")
+                    traceback.print_stack(frame, file=f)
+
+                f.write("=" * 70 + "\n")
+
+            for name in list(_async_loops.keys()):
+                _schedule_async_dump(name, filename)
+
+            print_count += 1  # Increment after a successful write
+
+        except Exception as e:
+            print(f"Error writing stack dump to file: {e}", file=sys.stderr)
+
+
+def register_async_loop(name, loop) -> None:
+    """Register an event loop to include asyncio task dumps for."""
+    _async_loops[name] = loop
+
+
+def register_async_state_provider(name, provider) -> None:
+    """Register a callable returning extra state text for a loop's dump."""
+    _async_state_providers[name] = provider
+
+
+def _format_async_tasks(loop, name) -> str:
+    """Return a readable dump of every task on ``loop`` (loop thread only)."""
+    lines = [f"\n------------------- ASYNCIO TASKS ({name}) -------------------\n"]
+
+    try:
+        tasks = asyncio.all_tasks(loop)
+    except Exception as e:
+        return f"<unable to read asyncio tasks: {e}>\n"
+
+    for task in tasks:
+        lines.append(f"\n[{task.get_name()}] done={task.done()} cancelled={task.cancelled()}\n")
+        lines.append(f"  {task.get_coro()!r}\n")
+
+        for frame in task.get_stack(limit=10):
+            lines.append("".join(traceback.format_stack(frame, limit=1)))
+
+    return "".join(lines)
+
+
+def _dump_async_state(name, filename) -> None:
+    """Append asyncio task/state info for one loop. Runs on the loop thread."""
+    loop = _async_loops.get(name)
+    if loop is None or loop.is_closed():
+        return
+
+    parts = []
+    provider = _async_state_providers.get(name)
+
+    if provider is not None:
+        try:
+            parts.append(provider())
+        except Exception as e:
+            parts.append(f"<state provider error: {e}>\n")
+
+    parts.append(_format_async_tasks(loop, name))
+
+    try:
+        with safe_open(filename, "a") as f:
+            f.write("".join(parts))
+    except Exception:
+        pass
+
+
+def _schedule_async_dump(name, filename) -> None:
+    """Schedule an async-state dump onto a registered loop, if it is running."""
+    loop = _async_loops.get(name)
+    if loop is None or loop.is_closed() or not loop.is_running():
+        return
+
+    try:
+        loop.call_soon_threadsafe(_dump_async_state, name, filename)
+    except RuntimeError:
+        pass
+
+
+# Start the monitor in a background daemon thread
+monitor_thread = threading.Thread(
+    target=dump_stacks_to_file,
+    args=(".cecli/logs/threads.log", 5, 10),  # Clears every 10 prints
+    daemon=True,
+)
+monitor_thread.start()

{cecli_dev-1.6.0rc4 → cecli_dev-1.6.1}/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.0rc4 → cecli_dev-1.6.1}/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.0rc4 → cecli_dev-1.6.1}/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.0rc4 → cecli_dev-1.6.1}/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.0rc4 → cecli_dev-1.6.1}/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