agentshim 0.1.0__py3-none-any.whl

agentshim/opencode/agent.py

@@ -0,0 +1,196 @@
+import json
+import subprocess
+from collections.abc import Callable
+from typing import Any
+
+from agentshim.trajectory import TrajectoryRecorderProtocol
+
+from ..base import register_provider
+from ..cli_agent import CLICodingAgent, CLIGenerationSession
+from ..events import AgentEventHandler
+from ..sandbox import SandboxConfig
+from ..usage import ProviderUsage, TokenUsage
+from .events import OpencodeEvent, StepFinishEvent, TextEvent, ToolUseEvent
+
+OPENCODE_DEFAULT_MODEL = "google-vertex/gemini-3-pro-preview"
+
+
+def _to_args_dict(input_data: Any) -> dict[str, Any]:
+    """Convert input_data to a dict[str, Any] for tool call recording."""
+    if isinstance(input_data, dict):
+        return {str(k): v for k, v in input_data.items()}  # type: ignore[reportUnknownVariableType]
+    return {"input": input_data}
+
+
+class OpencodeGenerationSession(CLIGenerationSession):
+    def __init__(self, **kwargs: Any):
+        super().__init__(**kwargs)
+        # Accumulates usage across step_finish events.
+        self._accumulated_tokens = TokenUsage()
+        self._accumulated_cost_usd: float = 0.0
+        self._saw_cost: bool = False
+
+    def _process_stdout(self, line: str) -> None:
+        """Process a line from stdout."""
+        if not line:
+            return
+        try:
+            data = json.loads(line)
+            if self.session_id is None:
+                sid = data.get("sessionID")
+                if isinstance(sid, str) and sid:
+                    self.session_id = sid
+            event = OpencodeEvent.from_dict(data)
+            if event:
+                self._handle_event(event)
+        except json.JSONDecodeError:
+            if not self.silent:
+                if self._at_line_start:
+                    self._log_raw(f"{self.log_prefix} ")
+                self._log_raw(line.rstrip() + "\n")
+                self._at_line_start = True
+
+    def _handle_event(self, event: OpencodeEvent):
+        """Handle a single parsed Opencode event."""
+        if isinstance(event, TextEvent):
+            self.stdout_lines.append(event.text)
+            if self.event_handler:
+                self.event_handler.on_thinking(event.text)
+
+        elif isinstance(event, StepFinishEvent):
+            self._update_usage_from_step(event)
+
+        elif isinstance(event, ToolUseEvent):
+            if event.status in ("success", "error"):
+                args = _to_args_dict(event.input_data)
+                stdout = str(event.output_data) if event.output_data is not None else ""
+
+                self.recorder.add_tool_call(
+                    tool=event.tool_name,
+                    args=args,
+                    stdout=stdout,
+                )
+
+                if self.event_handler:
+                    self.event_handler.on_tool_call(event.tool_name, args)
+                    self.event_handler.on_tool_result(
+                        tool=event.tool_name,
+                        stdout=stdout,
+                    )
+
+        if not self.silent:
+            self._render_event(event)
+
+    def _update_usage_from_step(self, event: StepFinishEvent) -> None:
+        """Fold a step_finish payload into the running usage totals."""
+        tokens: dict[str, Any] = event.tokens or {}
+        cache: dict[str, Any] = tokens.get("cache") or {}
+        cache_read = int(cache.get("read") or 0)
+        cache_write = int(cache.get("write") or 0)
+        cached = cache_read + cache_write
+        step_usage = TokenUsage(
+            input_tokens=int(tokens.get("input") or 0) + cached,
+            output_tokens=int(tokens.get("output") or 0) + int(tokens.get("reasoning") or 0),
+            cached_input_tokens=cached,
+            turns=1,
+        )
+        self._accumulated_tokens = self._accumulated_tokens + step_usage
+        if event.cost is not None:
+            self._accumulated_cost_usd += float(event.cost)
+            self._saw_cost = True
+        self.usage = ProviderUsage(
+            tokens=self._accumulated_tokens,
+            total_cost_usd=self._accumulated_cost_usd if self._saw_cost else None,
+            provider="opencode",
+        )
+
+    def _render_event(self, event: OpencodeEvent):
+        """Render the event to stdout."""
+        if isinstance(event, TextEvent):
+            self._print_stream_content(event.text)
+            return
+
+        if not self._at_line_start:
+            self._log_raw("\n")
+            self._at_line_start = True
+
+        output = event.render(self.log_prefix)
+        if output:
+            self._log_raw(output + "\n")
+
+
+@register_provider("opencode")
+class OpencodeCodingAgent(CLICodingAgent):
+    """Coding agent implementation using the Opencode CLI tool."""
+
+    def __init__(
+        self,
+        model: str | None = None,
+        recorder: TrajectoryRecorderProtocol | None = None,
+        event_handler: AgentEventHandler | None = None,
+        mcp_servers: list[object] | None = None,
+        sandbox: bool | SandboxConfig = False,
+    ):
+        """Initialize the Opencode coding agent.
+
+        Args:
+            model: Optional model name to use.
+            recorder: Trajectory recorder instance.
+            event_handler: Optional event handler for UI updates.
+            mcp_servers: Optional list of MCP server configurations.
+            sandbox: Not supported for Opencode; must be False.
+
+        Raises:
+            ValueError: If mcp_servers is non-empty (not supported).
+            NotImplementedError: If ``sandbox`` is truthy.
+        """
+        if mcp_servers:
+            raise ValueError("OpencodeCodingAgent does not support programmatic MCP server configuration via CLI flags")
+        if sandbox:
+            raise NotImplementedError("sandbox is not supported for OpencodeCodingAgent")
+        if not model:
+            model = OPENCODE_DEFAULT_MODEL
+        super().__init__("opencode", model, recorder, event_handler)
+
+    @property
+    def _log_prefix(self) -> str:
+        """Return the log prefix for this agent."""
+        return "[Opencode]"
+
+    def _get_command(self, prompt: str, resume_session_id: str | None = None) -> list[str]:
+        cmd = [self.binary_path, "run"]
+
+        if resume_session_id:
+            cmd.extend(["--session", resume_session_id])
+
+        cmd.append(f'"{prompt}"')
+
+        if self.model:
+            cmd.extend(["--model", self.model])
+
+        cmd.extend(["--format=json"])
+
+        return cmd
+
+    def _create_session(
+        self,
+        cmd: list[str],
+        cwd: str | None = None,
+        timeout: int = 300,
+        silent: bool = False,
+        recorder: TrajectoryRecorderProtocol | None = None,
+        on_process_started: Callable[[subprocess.Popen[str]], None] | None = None,
+    ) -> OpencodeGenerationSession:
+        return OpencodeGenerationSession(
+            binary_name=self.binary_name,
+            env=self.env,
+            log_prefix=self._log_prefix,
+            cmd=cmd,
+            logger=self.logger,
+            cwd=cwd,
+            timeout=timeout,
+            silent=silent,
+            recorder=recorder,
+            event_handler=self.event_handler,
+            on_process_started=on_process_started,
+        )

agentshim/opencode/events.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..utils import truncate_tool_params
+
+
+class OpencodeEvent(ABC):
+    """Base class for Opencode stream events."""
+
+    @abstractmethod
+    def render(self, log_prefix: str) -> str | None:
+        """Render the event as a string for terminal output."""
+
+    @staticmethod
+    def from_dict(data: dict[str, Any]) -> OpencodeEvent | None:
+        """Factory method to create events from JSON data."""
+        msg_type = data.get("type")
+        part = data.get("part", {})
+
+        if msg_type == "text":
+            return TextEvent(text=part.get("text", ""))
+        if msg_type == "tool_use":
+            return ToolUseEvent(
+                tool_name=part.get("tool", "Tool"),
+                input_data=part.get("state", {}).get("input"),
+                output_data=part.get("state", {}).get("output"),
+                status=part.get("state", {}).get("status"),
+            )
+        if msg_type == "step_start":
+            return StepStartEvent()
+        if msg_type == "step_finish":
+            return StepFinishEvent(
+                reason=part.get("reason"),
+                cost=part.get("cost"),
+                tokens=part.get("tokens"),
+            )
+
+        return None
+
+
+class TextEvent(OpencodeEvent):
+    def __init__(self, text: str):
+        self.text = text
+
+    def render(self, log_prefix: str) -> str | None:
+        # We will handle text printing in the agent loop to handle potential streaming
+        # or just print it as is.
+        # For now, let's return it.
+        return self.text
+
+
+class ToolUseEvent(OpencodeEvent):
+    def __init__(self, tool_name: str, input_data: Any, output_data: Any, status: str):
+        self.tool_name = tool_name
+        self.input_data = input_data
+        self.output_data = output_data
+        self.status = status
+
+    def render(self, log_prefix: str) -> str:
+        # Render tool use and result
+        truncated_input = truncate_tool_params(self.tool_name, self.input_data)
+
+        output_str = ""
+        if self.output_data:
+            # Truncate output to first 5 lines
+            out_lines = str(self.output_data).splitlines()
+            truncated_output = "\n".join(out_lines[:5] + (["..."] if len(out_lines) > 5 else []))
+            output_str = f"\n{log_prefix} \033[32m[Tool Result] {truncated_output}\033[0m"
+
+        return f"{log_prefix} \033[34m[Tool Use] {self.tool_name} {truncated_input}\033[0m{output_str}"
+
+
+class StepStartEvent(OpencodeEvent):
+    def render(self, log_prefix: str) -> str | None:
+        return None
+
+
+class StepFinishEvent(OpencodeEvent):
+    def __init__(self, reason: str | None, cost: float | None, tokens: dict[str, Any] | None):
+        self.reason = reason
+        self.cost = cost
+        self.tokens = tokens
+
+    def render(self, log_prefix: str) -> str | None:
+        # Optional: Print cost info?
+        # For now, maybe just ignore or print verbose.
+        # Let's keep it clean.
+        return None

agentshim/opencode_events.py

@@ -0,0 +1,11 @@
+"""Compatibility shim for older ``agentshim.opencode_events`` imports."""
+
+from .opencode.events import OpencodeEvent, StepFinishEvent, StepStartEvent, TextEvent, ToolUseEvent
+
+__all__ = [
+    "OpencodeEvent",
+    "StepFinishEvent",
+    "StepStartEvent",
+    "TextEvent",
+    "ToolUseEvent",
+]

agentshim/sandbox.py

@@ -0,0 +1,133 @@
+"""Sandbox support for CLI coding agents.
+
+Currently only ``ClaudeCodeCodingAgent`` supports sandboxing, via Claude
+Code's native bubblewrap/Seatbelt sandbox (configured through its
+``settings.json`` schema). Other providers raise ``NotImplementedError``
+if sandboxing is requested.
+
+See https://code.claude.com/docs/en/sandboxing for how the native sandbox
+scopes bash subprocesses at the OS level (filesystem + network), without
+wrapping the Claude process itself.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+_CONFINE_READS_HOOK = os.path.join(os.path.dirname(os.path.abspath(__file__)), "claude", "hooks", "confine_reads.py")
+
+
+@dataclass
+class SandboxConfig:
+    """Claude Code sandbox configuration.
+
+    Fields mirror a subset of the ``sandbox`` key in Claude Code's
+    ``settings.json``. Only the knobs we actually need are exposed; pass
+    additional keys through ``extra_settings`` if you need something not
+    modeled here.
+
+    Attributes:
+        fail_if_unavailable: If True, Claude exits with an error when the
+            sandbox can't start (missing ``bwrap``, unsupported platform)
+            instead of silently falling back to unsandboxed execution.
+            Recommended to keep True so sandbox behavior is a hard gate.
+        auto_allow_bash: If True, sandboxed bash commands are auto-approved
+            without permission prompts (they're already constrained by the
+            sandbox).
+        allow_unsandboxed_commands: If False, disables the
+            ``dangerouslyDisableSandbox`` escape hatch entirely.
+        excluded_commands: Commands that should run *outside* the sandbox
+            (e.g. ``["docker *"]``).
+        allow_write: Extra paths where sandboxed commands may write (cwd
+            is always writable by default).
+        deny_write: Paths sandboxed commands must not write to.
+        allow_read: Paths to re-allow inside ``deny_read`` regions.
+        deny_read: Paths sandboxed commands must not read.
+        allowed_domains: Outbound network domains allowed for bash
+            subprocesses (e.g. ``["github.com", "*.npmjs.org"]``).
+            Does not affect Claude's own API calls.
+        extra_settings: Raw dict merged into the ``sandbox`` settings
+            block, for fields not covered above.
+    """
+
+    fail_if_unavailable: bool = True
+    auto_allow_bash: bool = True
+    allow_unsandboxed_commands: bool = False
+    excluded_commands: list[str] = field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+    allow_write: list[str] = field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+    deny_write: list[str] = field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+    allow_read: list[str] = field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+    deny_read: list[str] = field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+    allowed_domains: list[str] = field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+    extra_settings: dict[str, Any] = field(default_factory=dict)  # pyright: ignore[reportUnknownVariableType]
+
+    # The OS-level sandbox only wraps bash subprocesses, not Claude's built-in
+    # Read/Glob/Grep/Edit/Write tools. When this list is non-empty we inject a
+    # PreToolUse hook that denies any tool call whose target path is outside
+    # the listed roots. Leave empty to allow Claude's native tools to read
+    # anywhere (the default; matches unsandboxed behavior).
+    confine_native_reads_to: list[str] = field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+
+
+def resolve_sandbox(value: bool | SandboxConfig | None) -> SandboxConfig | None:
+    """Normalize a user-supplied ``sandbox`` argument to a SandboxConfig or None."""
+    if value is None or value is False:
+        return None
+    if value is True:
+        return SandboxConfig()
+    if isinstance(value, SandboxConfig):  # pyright: ignore[reportUnnecessaryIsInstance]
+        return value
+    raise TypeError(f"sandbox must be bool or SandboxConfig, got {type(value).__name__}")
+
+
+def build_claude_sandbox_settings(config: SandboxConfig) -> dict[str, Any]:
+    """Build the Claude Code ``settings.json`` payload that enables the sandbox."""
+    sandbox: dict[str, Any] = {
+        "enabled": True,
+        "failIfUnavailable": config.fail_if_unavailable,
+        "autoAllowBashIfSandboxed": config.auto_allow_bash,
+        "allowUnsandboxedCommands": config.allow_unsandboxed_commands,
+    }
+
+    if config.excluded_commands:
+        sandbox["excludedCommands"] = list(config.excluded_commands)
+
+    filesystem: dict[str, Any] = {}
+    if config.allow_write:
+        filesystem["allowWrite"] = list(config.allow_write)
+    if config.deny_write:
+        filesystem["denyWrite"] = list(config.deny_write)
+    if config.allow_read:
+        filesystem["allowRead"] = list(config.allow_read)
+    if config.deny_read:
+        filesystem["denyRead"] = list(config.deny_read)
+    if filesystem:
+        sandbox["filesystem"] = filesystem
+
+    if config.allowed_domains:
+        sandbox["network"] = {"allowedDomains": list(config.allowed_domains)}
+
+    sandbox.update(config.extra_settings)
+
+    settings: dict[str, Any] = {"sandbox": sandbox}
+    if config.confine_native_reads_to:
+        settings["hooks"] = _build_confine_reads_hook(config.confine_native_reads_to)
+    return settings
+
+
+def _build_confine_reads_hook(roots: list[str]) -> dict[str, Any]:
+    """Build the ``hooks`` block that denies native-tool reads outside ``roots``."""
+    resolved = [os.path.realpath(r) for r in roots]
+    # Quote each arg with double-quotes so paths with spaces survive shell parsing.
+    args = " ".join(f'"{r}"' for r in resolved)
+    command = f'"{_CONFINE_READS_HOOK}" {args}'
+    return {
+        "PreToolUse": [
+            {
+                "matcher": "Read|Glob|Grep|Edit|Write|NotebookEdit",
+                "hooks": [{"type": "command", "command": command}],
+            }
+        ]
+    }

agentshim/subagent.py

@@ -0,0 +1,93 @@
+"""Shared subagent primitive for isolated LLM calls.
+
+Provides ``call_subagent()`` — a single fresh litellm call with its own
+message list.  Used by RLM (isolated recursive calls) and the
+SubagentCodingAgent (fan-out analysis calls).
+"""
+
+import os
+import subprocess
+import time
+from typing import Any
+
+import litellm
+from loguru import logger
+
+_NETWORK_ERROR_MARKERS = (
+    "nameresolutionerror",
+    "name or service not known",
+    "transporterror",
+    "apiconnectionerror",
+    "connectionerror",
+    "max retries exceeded",
+)
+
+
+def litellm_call_with_retry(
+    kwargs: dict[str, Any],
+    label: str,
+    max_attempts: int = 3,
+    token_acc: dict[str, int] | None = None,
+) -> str:
+    """Call litellm.completion with retry on transient network errors."""
+    for attempt in range(max_attempts):
+        try:
+            response = litellm.completion(**kwargs)  # type: ignore[reportUnknownMemberType]
+            if token_acc is not None:
+                usage = getattr(response, "usage", None)
+                if usage:
+                    token_acc["prompt_tokens"] = token_acc.get("prompt_tokens", 0) + (
+                        getattr(usage, "prompt_tokens", 0) or 0
+                    )
+                    token_acc["completion_tokens"] = token_acc.get("completion_tokens", 0) + (
+                        getattr(usage, "completion_tokens", 0) or 0
+                    )
+                    token_acc["total_tokens"] = token_acc.get("total_tokens", 0) + (
+                        getattr(usage, "total_tokens", 0) or 0
+                    )
+            return response.choices[0].message.content or ""  # type: ignore[reportAttributeAccessIssue]
+        except Exception as e:
+            if any(m in str(e).lower() for m in _NETWORK_ERROR_MARKERS) and attempt < max_attempts - 1:
+                delay = 15 * (2**attempt)
+                logger.warning(
+                    f"[RLM] {label}: transient network error (attempt {attempt + 1}/{max_attempts}), "
+                    f"retrying in {delay}s: {e}"
+                )
+                time.sleep(delay)
+            else:
+                raise
+
+    return ""  # unreachable; satisfies type checker
+
+
+def call_subagent(
+    model: str,
+    system_prompt: str,
+    user_prompt: str,
+    location: str | None = None,
+    token_acc: dict[str, int] | None = None,
+) -> str:
+    """Make a completely fresh, isolated litellm call.
+
+    Builds a new ``messages`` list from scratch (system + user), so there is
+    no shared conversation history with any other call.
+    """
+    kwargs: dict[str, Any] = {
+        "model": model,
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
+        "cache": {"no-cache": True},
+    }
+    loc = location or os.environ.get("VERTEX_LOCATION")
+    if loc:
+        kwargs["vertex_location"] = loc
+
+    try:
+        return litellm_call_with_retry(kwargs, label="subagent call", token_acc=token_acc)
+    except KeyboardInterrupt:
+        raise
+    except (TimeoutError, ConnectionError, subprocess.SubprocessError, OSError) as e:
+        logger.error(f"[Subagent] LLM call failed: {type(e).__name__}: {e}")
+        return f"Subagent call failed: {type(e).__name__}: {e}"

agentshim/trajectory.py

@@ -0,0 +1,168 @@
+"""Trajectory protocol and null implementation for the agent_cli library.
+
+This module provides the protocol interface and no-op implementation that
+standalone library code can use without depending on app_operator.
+
+The full TrajectoryRecorder implementation lives in app_operator/trajectory.py.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, TypedDict, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class TokenUsage(TypedDict):
+    """Token usage statistics from an LLM call."""
+
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+
+class FaultInjectionMetadata(TypedDict):
+    """Metadata about fault injection for embedding in trajectory JSON."""
+
+    enabled: bool
+    num_faults_requested: int
+    num_faults_injected: int
+    faults: list[Any]
+    failed_injections: list[Any]
+    fault_ids: list[str]
+    categories: list[str]
+    severities: list[str]
+
+
+@runtime_checkable
+class TrajectoryRecorderProtocol(Protocol):
+    """Protocol for trajectory recorders."""
+
+    def start_phase(self, phase: Any, context: dict[str, Any] | None = None) -> None: ...
+    def end_phase(self, status: str | None = None) -> None: ...
+    def add_system_message(self, content: str) -> None: ...
+    def add_user_message(self, content: str) -> None: ...
+
+    def add_assistant_message(self, content: str, duration: float | None = None) -> None: ...
+
+    def add_tool_call(
+        self,
+        tool: str,
+        args: dict[str, Any],
+        stdout: str = "",
+        stderr: str = "",
+        exit_code: int | None = None,
+        duration: float | None = None,
+    ) -> None: ...
+    def set_phase_status(self, status: str) -> None: ...
+    def set_agent_name(self, agent_name: str) -> None: ...
+    def set_prompt_version(self, version: str) -> None: ...
+    def record_fallback(self) -> None: ...
+    def record_prompt_kwargs(self, kwargs: dict[str, Any]) -> None: ...
+    def record_rendered_prompt(self, rendered_prompt: str) -> None: ...
+    def record_fault_injection(self, metadata: FaultInjectionMetadata) -> None: ...
+    def record_token_usage(self, usage: TokenUsage) -> None: ...
+    def finalize(self, status: str = "completed") -> Path: ...
+
+    def phase(self, phase: Any, context: dict[str, Any] | None = None) -> Any: ...
+
+
+class NullTrajectoryRecorder(TrajectoryRecorderProtocol):
+    """No-op recorder that formally implements TrajectoryRecorderProtocol.
+
+    Used as a default when no real recorder is needed (e.g. in tests).
+    Every method is a no-op, so callers never need to check for None.
+    """
+
+    def start_phase(self, phase: Any, context: dict[str, Any] | None = None) -> None:
+        pass
+
+    def end_phase(self, status: str | None = None) -> None:
+        pass
+
+    def add_system_message(self, content: str) -> None:
+        pass
+
+    def add_user_message(self, content: str) -> None:
+        pass
+
+    def add_assistant_message(self, content: str, duration: float | None = None) -> None:
+        pass
+
+    def add_tool_call(
+        self,
+        tool: str,
+        args: dict[str, Any],
+        stdout: str = "",
+        stderr: str = "",
+        exit_code: int | None = None,
+        duration: float | None = None,
+    ) -> None:
+        pass
+
+    def set_phase_status(self, status: str) -> None:
+        pass
+
+    def set_agent_name(self, agent_name: str) -> None:
+        pass
+
+    def set_prompt_version(self, version: str) -> None:
+        pass
+
+    def record_fallback(self) -> None:
+        pass
+
+    def record_prompt_kwargs(self, kwargs: dict[str, Any]) -> None:
+        pass
+
+    def record_rendered_prompt(self, rendered_prompt: str) -> None:
+        pass
+
+    def record_fault_injection(self, metadata: FaultInjectionMetadata) -> None:
+        pass
+
+    def record_token_usage(self, usage: TokenUsage) -> None:
+        pass
+
+    @contextmanager
+    def phase(self, phase: Any, context: dict[str, Any] | None = None):
+        yield self
+
+    def finalize(self, status: str = "completed") -> Path:
+        return Path("/dev/null")
+
+
+def _call_id_provider() -> int | None:
+    return None
+
+
+def _run_id_provider() -> str | None:
+    return None
+
+
+def register_context_providers(
+    call_id_fn: Callable[[], int | None],
+    run_id_fn: Callable[[], str | None],
+) -> None:
+    """Register live context providers for trajectory correlation.
+
+    Called by app_operator.trajectory at import time to wire in the real
+    thread-local implementations. Standalone consumers get None from the
+    default def stubs, which is correct outside of app_operator.
+    """
+    global _call_id_provider, _run_id_provider
+    _call_id_provider = call_id_fn
+    _run_id_provider = run_id_fn
+
+
+def get_current_call_id() -> int | None:
+    """Return the current call ID, or None if no trajectory is active."""
+    return _call_id_provider()
+
+
+def get_run_id() -> str | None:
+    """Return the current run ID, or None if no trajectory is active."""
+    return _run_id_provider()