better-dsh 0.2.4 → 0.2.5-a

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

@@ -0,0 +1,98 @@
+---
+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

@@ -0,0 +1,61 @@
+---
+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

@@ -0,0 +1,140 @@
+# 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

@@ -0,0 +1,250 @@
+---
+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)