better-dsh 0.2.5 → 0.3.0-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/streaming-tts.md

@@ -1,98 +0,0 @@
----
-title: "Streaming TTS Internals"
-description: "Sentence chunker, streaming provider ABC, capability matrix and how to add a streaming TTS provider"
----
-
-# Streaming TTS
-
-Hermes can stream TTS audio as it arrives from the provider, instead of waiting
-for the full audio before playing. This is used by voice mode (CLI/TUI live
-conversation), the dashboard speak-stream WebSocket, and — via the gateway
-`StreamingTTSConsumer` — any platform adapter that opts into streaming audio.
-Voice replies start speaking after the first clause instead of after full
-generation + synthesis.
-
-## Architecture
-
-The streaming pipeline has four parts:
-
-1. **Producer** — the LLM emits text deltas as it generates a response
-2. **Sentence chunker** — `tools.tts_streaming.SentenceChunker` accumulates
-   deltas, strips `<think>` blocks (even split across deltas), and flushes
-   complete sentences
-3. **TTS provider** — a registered `StreamingTTSProvider` turns each sentence
-   into raw PCM chunks (int16 mono at the provider's declared `sample_rate`)
-4. **Audio sink** — `sounddevice.OutputStream` for local playback
-   (`tools.tts_tool_speaker.stream_tts_to_speaker`), or a gateway platform adapter's
-   `write_streaming_tts` seam (`gateway/streaming_tts_consumer.py`)
-
-Providers with no chunked API still get per-*sentence* playback via the proven
-sync `text_to_speech_tool` path, so edge (the default) is conversational too.
-All spoken text is cleaned by `tools.tts_text_normalize.prepare_spoken_text`
-(one cleaner, all paths).
-
-## How to pick a provider
-
-By default the dispatcher streams with the provider you already configured
-(`tts.provider`) when that provider has a chunked API — it never silently
-swaps your voice for a different provider just to get streaming.
-
-To override, set `tts.streaming.provider` in your `config.yaml`:
-
-- a provider name (`elevenlabs`, `gemini`, `openai`, `xai`) pins that streamer
-- `auto` walks the priority list `elevenlabs → gemini → openai → xai` and uses
-  the first one whose credentials resolve — an explicit opt-in to "best
-  chunked voice available"
-
-```yaml
-tts:
-  provider: gemini
-  streaming:
-    provider: gemini      # or "auto"
-  gemini:
-    model: gemini-2.5-flash-preview-tts
-    voice: Kore
-```
-
-## Capability matrix
-
-| Provider    | Transport                             | Chunked PCM | Credentials |
-|-------------|---------------------------------------|-------------|-------------|
-| elevenlabs  | chunked HTTP (`pcm_24000`)            | yes         | `ELEVENLABS_API_KEY` / `tts.elevenlabs` |
-| openai      | chunked HTTP (`with_streaming_response`, `pcm`) | yes | `tts.openai.api_key` → env → managed gateway |
-| gemini      | SSE (`streamGenerateContent?alt=sse`) | yes         | `GEMINI_API_KEY` / `GOOGLE_API_KEY` |
-| xai         | WebSocket (`wss://api.x.ai/v1/tts`)   | yes         | xAI OAuth or `XAI_API_KEY` |
-| edge, piper, kitten, neutts, mistral, minimax, deepinfra, … | — | no (per-sentence sync fallback) | as usual |
-
-All credential lookups go through `resolve_provider_secret()`
-(config > env/.env > credential pool) — never bare env reads. Streamed bodies
-are capped at 16 MiB per sentence, mirroring the sync providers' bounded
-upstream-body invariant.
-
-## Adding a new streaming provider
-
-1. Subclass `StreamingTTSProvider` in `tools/tts_streaming.py`
-2. Set `sample_rate` (and `channels` / `sample_width` if not int16 mono)
-3. Implement `available()` (a pure probe — never install anything) and
-   `stream(self, text) -> Iterator[bytes]` yielding raw PCM chunks
-4. Decorate with `@register("yourname")`
-5. Add tests in `tests/tools/test_tts_streaming.py`
-
-The ABC enforces the contract; the registry makes the provider discoverable;
-the dispatcher (`stream_tts_to_speaker`) and the gateway consumer handle the
-sentence buffer, stop events, and audio sink for free.
-
-## Gateway streaming (platform adapters)
-
-`gateway/streaming_tts_consumer.py` bridges agent deltas to an adapter's
-streaming-audio seam. Adapters opt in by overriding, on
-`BasePlatformAdapter`:
-
-- `supports_streaming_tts(chat_id, audio_format) -> bool`
-- `begin_streaming_tts / write_streaming_tts / finish_streaming_tts /
-  abort_streaming_tts`
-
-All default to unsupported/no-op, so existing adapters are untouched. When a
-turn's streaming audio completes, the whole-file auto-TTS reply for that turn
-is suppressed (no double playback); when streaming fails before any audio was
-audible, the gateway falls back to the legacy whole-file voice reply.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/subagent-lifecycle-api.md

@@ -1,61 +0,0 @@
----
-title: Public Subagent Lifecycle API
-sidebar_label: Subagent lifecycle API
----
-
-# Public Subagent Lifecycle API
-
-Plugins can launch and supervise fresh Hermes child sessions without importing
-`tools.delegate_tool`, gateway internals, TUI state, or `AIAgent` fields.
-The service resolves its parent from the current agent turn, so it works in
-CLI, gateway, non-interactive, and kanban-worker sessions. Launching outside an
-active agent turn fails closed with `No active Hermes parent session`.
-
-```python
-from agent.subagent_lifecycle import SubagentLaunchRequest
-
-def launch_review(ctx):
-    # Call from a plugin tool or hook while an agent turn is active.
-    service = ctx.subagent_lifecycle
-    handle = service.launch(SubagentLaunchRequest(
-        goal="Review this change for regressions.",
-        context="Only inspect the supplied repository.",
-        role="leaf",
-        correlation_id="review-42",
-        allowed_toolsets=("file",),
-    ))
-    # Persist handle.to_dict() if desired.
-    if service.wait(handle, timeout_seconds=2).timed_out:
-        return handle.to_dict()
-    return service.result(handle)
-```
-
-`SubagentHandle` is serializable and carries a versioned, opaque capability.
-Pass it back to `status`, `wait`, `cancel`, `result`, or `reconnect`; malformed
-or forged handles return `UNKNOWN`/`UNKNOWN_HANDLE` and cannot access a child.
-
-The stable states are `PENDING`, `STARTING`, `RUNNING`, `SUCCEEDED`, `FAILED`,
-`INTERRUPTED`, `CANCEL_REQUESTED`, `CANCELLED`, and `UNKNOWN`.
-
-`cancel(handle, reason=...)` is cooperative: it asks the child agent to
-interrupt at its next safe boundary and returns `CANCEL_REQUESTED`; it never
-claims completion until `wait` or `result` observes a terminal state. Terminal
-results are immutable, idempotent, bounded to 32k characters, omit transcripts
-and hidden reasoning, and include a stable result hash.
-
-This API is lifecycle-managed asynchronous execution. Child construction and
-completion use the same host-owned path as `delegate_task`, including parent
-tool-resolution restoration, memory notification, serialized `subagent_stop`
-hooks, resource cleanup, and child-cost rollup. It does not change the
-synchronous `delegate_task` tool, batch delegation, or its gateway/TUI display.
-The initial implementation retains metadata and terminal results in-process for
-one hour.
-After a process restart, `reconnect` returns `RECONNECT_UNAVAILABLE` and never
-starts a replacement child. Running Python threads also cannot survive process
-exit; callers must treat those handles as interrupted by process exit.
-
-Requests are fail-closed: goal/context/metadata sizes are capped, unknown or
-parent-broadening toolsets are rejected, and per-tool blocks, working-directory
-overrides, and per-launch timeouts are explicitly rejected until Hermes can
-support them without weakening isolation. Use `allowed_toolsets` to narrow a
-child; Hermes's existing unsafe-tool block remains enforced.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/terminal-environment-plugin.md

@@ -1,140 +0,0 @@
-# Terminal Environment Provider Plugins
-
-Hermes runs shell commands through a pluggable set of **terminal backends**.
-The built-in backends (local, Docker, Singularity, Modal, Daytona, Vercel
-Sandbox, SSH) live in the core repo under `tools/environments/`. Third-party
-sandbox vendors integrate as **plugins** instead — a standalone plugin repo
-installed under `~/.hermes/plugins/`, registering a backend the user selects
-exactly like a built-in one via `terminal.backend` in `config.yaml`.
-
-This page mirrors the [Browser Provider Plugins](/developer-guide/browser-provider-plugin)
-guide — same registration flow, same scope semantics.
-
-## What a provider controls
-
-A registered backend automatically participates in every core surface:
-
-| Surface | Driven by |
-|---|---|
-| Command dispatch (`terminal`, `execute_code`, file tools) | `create_environment()` |
-| `hermes setup` backend picker | `display_name`, `description`, `setup_instructions()`, `post_setup()` |
-| Dashboard terminal-backend picker (probe status) | `probe()` |
-| `hermes status` / `hermes doctor` | `doctor_checks()` |
-| System-prompt environment hints | `is_remote`, `env_description` |
-| Dangerous-command approval skipping | `skip_container_guards` |
-| Container path/cwd handling | `is_container` |
-| Synced cache-file path translation | `cache_path_base` |
-| Secret stripping from spawned subprocesses | `strip_env_keys` |
-| Per-session sandbox isolation (`container_persistent: false`) | `session_isolated_when_nonpersistent` |
-
-Declaring these flags on the provider closes the classic "new backend missed
-classification site N" bug class — the core consults the registry at each
-site instead of a hardcoded list of names.
-
-## Minimal provider
-
-```python title="~/.hermes/plugins/acmebox/__init__.py"
-from agent.terminal_env_provider import TerminalEnvironmentProvider
-
-
-class AcmeBoxEnvironment:
-    """Must satisfy the BaseEnvironment duck-typed contract."""
-
-    def __init__(self, cwd, timeout, task_id):
-        self.cwd, self.timeout, self.task_id = cwd, timeout, task_id
-
-    def execute(self, command, timeout=None, **kwargs):
-        ...  # run the command in the sandbox
-        return {"output": "...", "exit_code": 0}
-
-    def cleanup(self):
-        ...  # tear down / detach
-
-
-class AcmeBoxProvider(TerminalEnvironmentProvider):
-    name = "acmebox"
-    display_name = "AcmeBox"
-    is_remote = True          # commands don't run on the host
-    is_container = True       # container-style path/cwd semantics
-
-    @property
-    def description(self):
-        return "Run commands in an AcmeBox cloud sandbox."
-
-    @property
-    def cache_path_base(self):
-        return "~/.hermes"    # where synced cache files land, or None
-
-    @property
-    def strip_env_keys(self):
-        return frozenset({"ACMEBOX_TOKEN"})
-
-    def is_available(self):
-        import importlib.util, os
-        return (
-            importlib.util.find_spec("acmebox") is not None
-            and bool(os.getenv("ACMEBOX_TOKEN"))
-        )
-
-    def create_environment(self, *, cwd, timeout, task_id="default",
-                           image=None, container_config=None, **kwargs):
-        return AcmeBoxEnvironment(cwd, timeout, task_id)
-
-
-def register(ctx):
-    ctx.register_terminal_environment_provider(AcmeBoxProvider())
-```
-
-```yaml title="~/.hermes/plugins/acmebox/plugin.yaml"
-name: acmebox
-version: 0.1.0
-description: AcmeBox cloud sandbox terminal backend
-kind: backend
-```
-
-Enable it, select it, run:
-
-```bash
-hermes plugins enable acmebox
-hermes config set terminal.backend acmebox
-```
-
-## Rules
-
-- **Reserved names.** Registrations that collide with a built-in backend name
-  (`local`, `docker`, `singularity`, `modal`, `managed_modal`, `daytona`,
-  `vercel_sandbox`, `ssh`) are rejected. Plugins extend the backend set; they
-  never shadow in-tree backends.
-- **`create_environment` must accept `**kwargs`** and ignore unknown keys —
-  the forward-compat contract that lets the factory signature evolve without
-  breaking older plugins.
-- **`is_available()` / `probe()` must be cheap.** No network calls — they run
-  during requirement checks and UI paints.
-- **Fail-soft everywhere.** A provider attribute that raises is treated as
-  its default by the core (e.g. a raising `skip_container_guards` keeps the
-  approval layer ON). Don't rely on exceptions for control flow.
-- **Secrets belong in `strip_env_keys`.** Your vendor token must never be
-  readable by a model-authored shell command; listing it strips it from every
-  spawned subprocess unconditionally, like the built-in `MODAL_*` /
-  `DAYTONA_API_KEY` handling.
-
-## Environment object contract
-
-`create_environment()` returns an object satisfying the same duck-typed
-interface as `tools.environments.base.BaseEnvironment`:
-
-- `execute(command, timeout=None, ...)` → `{"output": str, "exit_code": int}`
-- `cleanup()` — release resources; called on session teardown / idle reaping
-- Optional: persistence hooks mirroring the built-in cloud backends
-
-Subclassing `BaseEnvironment` is recommended (you inherit the shared file-sync
-and background-process plumbing) but not required.
-
-## Session isolation semantics
-
-If your sandbox is **resumed by name** (a durable VM the backend re-attaches
-to), set `session_isolated_when_nonpersistent = True`. With
-`terminal.container_persistent: false`, each session then gets its own
-sandbox identity instead of sharing one — without this, two independent
-ephemeral runs could attach one live VM and delete it out from under each
-other.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/tools-runtime.md

@@ -1,250 +0,0 @@
----
-sidebar_position: 9
-title: "Tools Runtime"
-description: "Runtime behavior of the tool registry, toolsets, dispatch, and terminal environments"
----
-
-# Tools Runtime
-
-Hermes tools are self-registering functions grouped into toolsets and executed through a central registry/dispatch system.
-
-Primary files:
-
-- `tools/registry.py`
-- `model_tools.py`
-- `toolsets.py`
-- `tools/terminal_tool.py`
-- `tools/environments/*`
-
-## Tool registration model
-
-Each tool module calls `registry.register(...)` at import time.
-
-`model_tools.py` is responsible for importing/discovering tool modules and building the schema list used by the model.
-
-### How `registry.register()` works
-
-Every tool file in `tools/` calls `registry.register()` at module level to declare itself. The function signature is:
-
-```python
-registry.register(
-    name="terminal",               # Unique tool name (used in API schemas)
-    toolset="terminal",            # Toolset this tool belongs to
-    schema={...},                  # Model-facing schema (description, parameters)
-    handler=handle_terminal,       # The function that executes when the tool is called
-    check_fn=check_terminal,       # Optional: returns True/False for availability
-    requires_env=["SOME_VAR"],     # Optional: env vars needed (for UI display)
-    is_async=False,                # Whether the handler is an async coroutine
-    description="Run commands",    # Optional ToolEntry registry metadata
-    emoji="💻",                    # Emoji for spinner/progress display
-)
-```
-
-Each call creates a `ToolEntry` stored in the singleton `ToolRegistry._tools` dict keyed by tool name. A registration that would shadow an existing tool from a **different** toolset is rejected (with an error log) unless the caller passes `override=True`; plugin overrides of built-in tools additionally require the operator opt-in `plugins.entries.<plugin_id>.allow_tool_override: true` in `config.yaml`.
-
-`schema["description"]` is the authoritative model-facing description. The separate `description=` argument populates `ToolEntry.description`; when it is omitted, the registry metadata falls back to the schema description. `get_definitions()` builds the OpenAI function definition from `entry.schema` and does not copy `entry.description` into a schema that lacks `description`. Therefore, `description=` alone does not describe the tool to the model, and when both values differ the model sees the schema value. Prefer defining the description once in the schema unless a registry consumer intentionally needs different metadata.
-
-### Discovery: `discover_builtin_tools()`
-
-When `model_tools.py` is imported, it calls `discover_builtin_tools()` from `tools/registry.py`. This function scans every `tools/*.py` file using AST parsing to find modules that contain top-level `registry.register()` calls, then imports them:
-
-```python
-# tools/registry.py (simplified)
-def discover_builtin_tools(tools_dir=None):
-    tools_path = Path(tools_dir) if tools_dir else Path(__file__).parent
-    for path in sorted(tools_path.glob("*.py")):
-        if path.name in {"__init__.py", "registry.py", "mcp_tool.py"}:
-            continue
-        if _module_registers_tools(path):  # AST check for top-level registry.register()
-            importlib.import_module(f"tools.{path.stem}")
-```
-
-This auto-discovery means new tool files are picked up automatically — no manual list to maintain. The AST check only matches top-level `registry.register()` calls (not calls inside functions), so helper modules in `tools/` are not imported.
-
-Each import triggers the module's `registry.register()` calls. Errors in optional tools (e.g., missing `fal_client` for image generation) are caught and logged — they don't prevent other tools from loading.
-
-After core tool discovery, MCP tools and plugin tools are also discovered:
-
-1. **MCP tools** — `tools.mcp_tool_discovery.discover_mcp_tools()` (re-exported by the `tools.mcp_tool` facade) reads MCP server config and registers tools from external servers.
-2. **Plugin tools** — `hermes_cli.plugins.discover_plugins()` loads user/project/pip plugins that may register additional tools.
-
-## Tool availability checking (`check_fn`)
-
-Each tool can optionally provide a `check_fn` — a callable that returns `True` when the tool is available and `False` otherwise. Typical checks include:
-
-- **API key present** — e.g., `lambda: bool(os.environ.get("SERP_API_KEY"))` for web search
-- **Service running** — e.g., checking if the Honcho server is configured
-- **Binary installed** — e.g., verifying `playwright` is available for browser tools
-
-When `registry.get_definitions()` builds the schema list for the model, it runs each tool's `check_fn()`:
-
-```python
-# Simplified from registry.py
-if entry.check_fn:
-    try:
-        available = bool(entry.check_fn())
-    except Exception:
-        available = False   # Exceptions = unavailable
-    if not available:
-        continue            # Skip this tool entirely
-```
-
-Key behaviors:
-- Check results are **cached per-call** — if multiple tools share the same `check_fn`, it only runs once.
-- Exceptions in `check_fn()` are treated as "unavailable" (fail-safe).
-- The `is_toolset_available()` method checks whether a toolset's `check_fn` passes, used for UI display and toolset resolution.
-
-## Toolset resolution
-
-Toolsets are named bundles of tools. Hermes resolves them through:
-
-- explicit enabled/disabled toolset lists
-- platform presets (`hermes-cli`, `hermes-telegram`, etc.)
-- dynamic MCP toolsets
-- curated special-purpose sets like `hermes-acp`
-
-### How `get_tool_definitions()` filters tools
-
-The main entry point is `model_tools.get_tool_definitions(enabled_toolsets, disabled_toolsets, quiet_mode)`:
-
-1. **If `enabled_toolsets` is provided** — only tools from those toolsets are included. Each toolset name is resolved via `resolve_toolset()` which expands composite toolsets into individual tool names.
-
-2. **If `disabled_toolsets` is provided** — start with ALL toolsets, then subtract the disabled ones.
-
-3. **If neither** — include all known toolsets.
-
-4. **Registry filtering** — the resolved tool name set is passed to `registry.get_definitions()`, which applies `check_fn` filtering and returns OpenAI-format schemas.
-
-5. **Dynamic schema patching** — after filtering, `execute_code` and `browser_navigate` schemas are dynamically adjusted to only reference tools that actually passed filtering (prevents model hallucination of unavailable tools).
-
-### Legacy toolset names
-
-Old toolset names with `_tools` suffixes (e.g., `web_tools`, `terminal_tools`) are mapped to their modern tool names via `_LEGACY_TOOLSET_MAP` for backward compatibility.
-
-## Dispatch
-
-At runtime, tools are dispatched through the central registry, with agent-loop exceptions for some agent-level tools such as memory/todo/session-search handling.
-
-### Dispatch flow: model tool_call → handler execution
-
-When the model returns a `tool_call`, the flow is:
-
-```
-Model response with tool_call
-    ↓
-agent loop (`agent/conversation_loop.py`, via `run_agent.py`'s `AIAgent` facade)
-    ↓
-model_tools.handle_function_call(name, args, task_id, user_task)
-    ↓
-[Agent-loop tools?] → handled directly by agent loop (todo, memory, session_search, delegate_task)
-    ↓
-[Plugin pre-hook] → invoke_hook("pre_tool_call", ...)
-    ↓
-registry.dispatch(name, args, **kwargs)
-    ↓
-Look up ToolEntry by name
-    ↓
-[Async handler?] → bridge via _run_async()
-[Sync handler?]  → call directly
-    ↓
-Return result string (or JSON error)
-    ↓
-[Plugin post-hook] → invoke_hook("post_tool_call", ...)
-```
-
-### Error wrapping
-
-All tool execution is wrapped in error handling at two levels:
-
-1. **`registry.dispatch()`** — catches any exception from the handler and returns `{"error": "Tool execution failed: ExceptionType: message"}` as JSON.
-
-2. **`handle_function_call()`** — wraps the entire dispatch in a secondary try/except that returns `{"error": "Error executing tool_name: message"}`.
-
-This ensures the model always receives a well-formed JSON string, never an unhandled exception.
-
-### Agent-loop tools
-
-Four tools are intercepted before registry dispatch because they need agent-level state (TodoStore, MemoryStore, etc.):
-
-- `todo` — planning/task tracking
-- `memory` — persistent memory writes
-- `session_search` — cross-session recall
-- `delegate_task` — spawns subagent sessions
-
-These tools' schemas are still registered in the registry (for `get_tool_definitions`), but their handlers return a stub error if dispatch somehow reaches them directly.
-
-### Async bridging
-
-When a tool handler is async, `_run_async()` bridges it to the sync dispatch path:
-
-- **CLI path (no running loop)** — uses a persistent event loop to keep cached async clients alive
-- **Gateway path (running loop)** — spins up a disposable thread with `asyncio.run()`
-- **Worker threads (parallel tools)** — uses per-thread persistent loops stored in thread-local storage
-
-## The DANGEROUS_PATTERNS approval flow
-
-The terminal tool integrates a dangerous-command approval system defined in `tools/approval.py`:
-
-1. **Pattern detection** — `DANGEROUS_PATTERNS` is a list of `(regex, description)` tuples covering destructive operations:
-   - Recursive deletes (`rm -rf`)
-   - Filesystem formatting (`mkfs`, `dd`)
-   - SQL destructive operations (`DROP TABLE`, `DELETE FROM` without `WHERE`)
-   - System config overwrites (`> /etc/`)
-   - Service manipulation (`systemctl stop`)
-   - Remote code execution (`curl | sh`)
-   - Fork bombs, process kills, etc.
-
-2. **Detection** — before executing any terminal command, `detect_dangerous_command(command)` checks against all patterns.
-
-3. **Approval prompt** — if a match is found:
-   - **CLI mode** — an interactive prompt asks the user to approve, deny, or allow permanently
-   - **Gateway mode** — an async approval callback sends the request to the messaging platform
-   - **Smart approval** — optionally, an auxiliary LLM can auto-approve low-risk commands that match patterns (e.g., `rm -rf node_modules/` is safe but matches "recursive delete")
-
-4. **Session state** — approvals are tracked per-session. Once you approve "recursive delete" for a session, subsequent `rm -rf` commands don't re-prompt.
-
-5. **Permanent allowlist** — the "allow permanently" option writes the pattern to `config.yaml`'s `command_allowlist`, persisting across sessions.
-
-## Terminal/runtime environments
-
-The terminal system supports multiple backends:
-
-- local
-- docker
-- ssh
-- singularity
-- modal
-- daytona
-- vercel_sandbox
-
-It also supports:
-
-- per-task cwd overrides
-- background process management
-- PTY mode
-- approval callbacks for dangerous commands
-
-`tools/process_registry_checkpoint.py` owns running-process checkpoints and
-PID-safe adoption. Completed output is separate: `tools/process_registry_results.py`
-writes one atomic, redacted receipt per process under the profile's
-`logs/process-results/`. Producers cannot overwrite another parent's results by
-rewriting the shared PID checkpoint. The registry persists the receipt before
-releasing its completion event; one-shot linger waits on that event. The existing
-process query methods load retained snapshots without adopting PIDs or enqueuing
-notifications. Reads require the commissioning durable session or its compression
-continuation; knowing a handle alone does not authorize a retained result read.
-The registry captures that owner before starting any output reader, including on
-CLI and non-notifying processes, and preserves the producer's profile context in
-reader threads. Receipt redaction is forced independently of live-output opt-out;
-retention is bounded by age and count.
-
-## Concurrency
-
-Tool calls may execute sequentially or concurrently depending on the tool mix and interaction requirements.
-
-## Related docs
-
-- [Toolsets Reference](../reference/toolsets-reference.md)
-- [Built-in Tools Reference](../reference/tools-reference.md)
-- [Agent Loop Internals](./agent-loop.md)
-- [ACP Internals](./acp-internals.md)