langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/tools/skill/tool.py

@@ -0,0 +1,222 @@
+"""
+tools/skill/tool.py — SkillRuntimeTool 主编排器
+
+职责：
+    在 RuntimeTool 生命周期内执行 skill：
+      normalize_input -> validate_input -> check_permissions -> invoke -> present
+    仅负责 orchestration，不承载 frontmatter 解析/展开细节。
+
+链路位置：
+    ToolExecutorPipeline.run()
+      -> SkillRuntimeTool hooks
+      -> ToolResultEnvelope
+
+CC 对照：
+    对齐 SkillTool 的 command lookup + args expand + metadata 透传语义，
+    但保持本工程 RuntimeTool 契约（标准 ToolMessage 路径）。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from langchain_agentx.tool_runtime.base import RuntimeTool
+from langchain_agentx.tool_runtime.models import (
+    AuthorizationDecision,
+    ToolExecutionContext,
+    ToolResultEnvelope,
+    ValidationResult,
+)
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+from .loader import SkillCommandRepository, SkillContentExpander, normalize_skill_name
+from .models import SkillToolInput, SkillToolOutput, _frontmatter_bool
+from .policy import SkillConstraintEvaluator
+from .prompt import COMMAND_NAME_TAG, DESCRIPTION, TOOL_NAME
+from ..agent.scope import resolve_effective_tools
+from ...tool_runtime.permission_context import set_pending_auto_approved_tools
+
+
+class SkillRuntimeTool(RuntimeTool):
+    name: str = TOOL_NAME
+    description: str = DESCRIPTION
+    input_model = SkillToolInput
+    output_model = SkillToolOutput
+
+    is_read_only: bool = True
+    is_concurrency_safe: bool = True
+    never_truncate: bool = False
+    max_result_size_chars: int = 60_000
+
+    def __init__(
+        self,
+        *,
+        workspace_root: str,
+        agent_home: str = ".langchain_agentx",
+        skills_root: str | None = None,
+        policy: Any | None = None,
+        state_bridge: Any | None = None,
+        repository: SkillCommandRepository | None = None,
+        expander: SkillContentExpander | None = None,
+        constraint_evaluator: SkillConstraintEvaluator | None = None,
+    ) -> None:
+        super().__init__(policy=policy, state_bridge=state_bridge)
+        workspace_cfg = resolve_agent_workspace_config(
+            workspace_root=workspace_root,
+            agent_home=agent_home,
+        )
+        self._workspace_root = workspace_cfg.workspace_root
+        self._agent_home = agent_home
+        self._skills_root = (
+            Path(skills_root).expanduser().resolve()
+            if skills_root
+            else workspace_cfg.skills_dir
+        )
+        self._repository = repository or SkillCommandRepository(self._skills_root)
+        self._expander = expander or SkillContentExpander()
+        self._constraint_evaluator = constraint_evaluator or SkillConstraintEvaluator(self._workspace_root)
+
+    def normalize_input(self, raw: dict[str, Any], ctx: ToolExecutionContext) -> dict[str, Any]:
+        data = dict(raw)
+        data["skill_name"] = normalize_skill_name(str(data.get("skill_name", "")))
+        return data
+
+    def validate_input(self, data: dict[str, Any], ctx: ToolExecutionContext) -> ValidationResult:
+        inp = SkillToolInput.model_validate(data)
+        if not inp.skill_name:
+            return ValidationResult(ok=False, message="skill_name cannot be empty")
+        cmd = self._repository.find_by_name(inp.skill_name)
+        if cmd is None:
+            return ValidationResult(
+                ok=False,
+                message=f"Unknown skill: {inp.skill_name}",
+                code="SKILL_NOT_FOUND",
+            )
+        if _frontmatter_bool(
+            cmd.frontmatter.get("disable-model-invocation")
+            or cmd.frontmatter.get("disable_model_invocation")
+        ):
+            return ValidationResult(
+                ok=False,
+                message=(
+                    f"Skill {inp.skill_name} cannot be used with {self.name} tool "
+                    "due to disable-model-invocation"
+                ),
+                code="SKILL_DISABLE_MODEL_INVOCATION",
+            )
+        return ValidationResult(ok=True)
+
+    def check_permissions(self, data: dict[str, Any], ctx: ToolExecutionContext) -> AuthorizationDecision:
+        # 先走 skill frontmatter 约束，再委托全局 PolicyEngine。
+        inp = SkillToolInput.model_validate(data)
+        cmd = self._repository.find_by_name(inp.skill_name)
+        if cmd is None:
+            return AuthorizationDecision(
+                behavior="deny",
+                message=f"Permission denied: unknown skill {inp.skill_name}",
+                policy_id="skill_not_found",
+            )
+
+        local = self._constraint_evaluator.evaluate(cmd.frontmatter)
+        if local.behavior != "allow":
+            return local
+
+        return super().check_permissions(data, ctx)
+
+    def invoke(self, data: dict[str, Any], ctx: ToolExecutionContext) -> SkillToolOutput:
+        inp = SkillToolInput.model_validate(data)
+        cmd = self._repository.find_by_name(inp.skill_name)
+        if cmd is None:
+            raise ValueError(f"Unknown skill: {inp.skill_name}")
+
+        content = self._expander.expand(cmd, inp.args)
+        frontmatter = cmd.frontmatter
+        allowed_tools = frontmatter.get("allowed-tools")
+        model_override = frontmatter.get("model")
+        constraints_applied = {
+            "has_allowed_tools": isinstance(allowed_tools, list) and len(allowed_tools) > 0,
+            "has_paths": isinstance(frontmatter.get("paths"), list) and len(frontmatter.get("paths")) > 0,
+            "has_model_override": isinstance(model_override, str) and bool(model_override.strip()),
+        }
+        # Tool scope 计算入口：先做纯计算并透出 explain，后续阶段再接 permission context 写回。
+        resolved_scope = resolve_effective_tools(
+            candidate_tools=list(getattr(ctx, "available_tools", []) or []),
+            agent_config=None,
+            skill_allowed_tools=[str(x) for x in allowed_tools] if isinstance(allowed_tools, list) else [],
+            parent_auto_approved=None,
+            global_deny=None,
+        )
+        constraints_applied["tool_scope_resolution"] = {
+            "auto_approved": sorted(resolved_scope.auto_approved),
+            "final_allowed": sorted(resolved_scope.final_allowed),
+            "explain": list(resolved_scope.explain),
+        }
+        set_pending_auto_approved_tools(ctx.session_store, resolved_scope.auto_approved)
+        return SkillToolOutput(
+            skill_name=cmd.name,
+            content=content,
+            source=cmd.source,
+            skill_path=str(cmd.path),
+            command_name_tag=f"<{COMMAND_NAME_TAG}>{cmd.name}</{COMMAND_NAME_TAG}>",
+            allowed_tools=[str(x) for x in allowed_tools] if isinstance(allowed_tools, list) else [],
+            model_override=str(model_override) if isinstance(model_override, str) else None,
+            constraints_applied=constraints_applied,
+        )
+
+    def present(self, data: dict[str, Any], result: Any, ctx: ToolExecutionContext) -> ToolResultEnvelope:
+        if not isinstance(result, SkillToolOutput):
+            return ToolResultEnvelope(
+                status="ok",
+                tool_name=self.name,
+                summary=f"Loaded skill {data.get('skill_name', '')}",
+                payload=str(result),
+            )
+
+        summary = f"Loaded skill: {result.skill_name}"
+        payload = (
+            f"{result.command_name_tag or ''}\n"
+            f"[skill:{result.skill_name}]\n\n"
+            f"{result.content}"
+        ).strip()
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=self.name,
+            summary=summary,
+            payload=payload,
+            meta={
+                "skill_name": result.skill_name,
+                "source": result.source,
+                "skill_path": result.skill_path,
+                "allowed_tools": result.allowed_tools,
+                "model_override": result.model_override,
+                "constraints_applied": result.constraints_applied,
+                "observability": {
+                    "schema_version": "v1",
+                    "scenario": "skill_tool_scope_resolution",
+                    "events": [
+                        {
+                            "event": "skill_loaded",
+                            "skill_name": result.skill_name,
+                            "source": result.source,
+                        },
+                        {
+                            "event": "tool_scope_resolved",
+                            "auto_approved": (
+                                result.constraints_applied.get("tool_scope_resolution", {})
+                                .get("auto_approved", [])
+                            ),
+                            "final_allowed": (
+                                result.constraints_applied.get("tool_scope_resolution", {})
+                                .get("final_allowed", [])
+                            ),
+                            "explain": (
+                                result.constraints_applied.get("tool_scope_resolution", {})
+                                .get("explain", [])
+                            ),
+                        },
+                    ],
+                },
+            },
+        )
+

langchain_agentx/utils/cwd.py

@@ -0,0 +1,124 @@
+"""
+utils/cwd.py — 工作目录单点管理
+
+职责：CwdContext 封装 ContextVar 与进程 cwd；模块级 get_cwd / run_with_cwd_override /
+      expand_path / to_relative_path 为薄封装（稳定 ABI）。
+在整体链路中的位置：所有工具 normalize_input → expand_path(path, ctx.cwd)；
+                    SubagentOrchestrator.invoke_subagent → run_with_cwd_override(effective_cwd)
+CC 对照：utils/cwd.ts getCwd() / runWithCwdOverride()；utils/path.ts expandPath() / toRelativePath()
+当前裁剪范围：v1 全量；ContextVar 替代 AsyncLocalStorage，语义完全对齐。
+"""
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Generator
+
+# 与历史模块级实现一致：在**导入时**固定进程 cwd，供默认 CwdContext 使用。
+_MODULE_PROCESS_CWD: str = os.path.realpath(os.getcwd())
+
+_default_ctx: CwdContext | None = None
+
+
+class CwdContext:
+    """单 Agent / 子任务链的 cwd 覆盖与路径展开（CC cwd.ts + path.ts 子集）。"""
+
+    def __init__(
+        self,
+        *,
+        process_cwd: str | None = None,
+        cwd_var: ContextVar[str | None] | None = None,
+    ) -> None:
+        self._cwd_var = cwd_var or ContextVar("cwd_override", default=None)
+        self._process_cwd = (
+            process_cwd if process_cwd is not None else os.path.realpath(os.getcwd())
+        )
+
+    def get_cwd(self) -> str:
+        """有 override → 返回 override；否则返回构造时固定的进程 cwd。"""
+        return self._cwd_var.get() or self._process_cwd
+
+    @contextmanager
+    def run_with_cwd_override(self, cwd: str) -> Generator[None, None, None]:
+        """在当前异步上下文中覆盖 cwd，退出后自动恢复。"""
+        token = self._cwd_var.set(os.path.realpath(cwd))
+        try:
+            yield
+        finally:
+            self._cwd_var.reset(token)
+
+    def expand_path(self, path: str, base_dir: str | None = None) -> str:
+        """将路径展开为绝对路径，基准为 base_dir 或 get_cwd()。"""
+        actual_base = base_dir or self.get_cwd()
+        expanded = os.path.expanduser(path.strip())
+        if os.path.isabs(expanded):
+            return os.path.normpath(expanded)
+        return os.path.normpath(os.path.join(actual_base, expanded))
+
+    def to_relative_path(self, absolute_path: str) -> str:
+        """将绝对路径转为相对于 get_cwd() 的路径；若会 ``..`` 溢出则保持绝对。"""
+        rel = os.path.relpath(absolute_path, self.get_cwd())
+        return absolute_path if rel.startswith("..") else rel
+
+
+def default_cwd_context() -> CwdContext:
+    """返回进程内共享单例（懒创建，``process_cwd`` 与导入时模块行为一致）。"""
+    global _default_ctx
+    if _default_ctx is None:
+        _default_ctx = CwdContext(process_cwd=_MODULE_PROCESS_CWD)
+    return _default_ctx
+
+
+def get_cwd() -> str:
+    """获取当前异步上下文的工作目录。
+
+    有 override → 返回 override；否则返回进程启动时的 cwd。
+    CC 对照：getCwd() = AsyncLocalStorage.getStore() ?? getCwdState()
+    """
+    return default_cwd_context().get_cwd()
+
+
+@contextmanager
+def run_with_cwd_override(cwd: str) -> Generator[None, None, None]:
+    """在当前异步上下文中覆盖 cwd，退出后自动恢复。
+
+    ContextVar 在 asyncio 中自动传播到所有子任务（Task/coroutine），
+    因此子代理整个执行链内的 get_cwd() 都返回 cwd，互不干扰。
+    CC 对照：runWithCwdOverride(cwd, fn)
+    """
+    with default_cwd_context().run_with_cwd_override(cwd):
+        yield
+
+
+def expand_path(path: str, base_dir: str | None = None) -> str:
+    """将路径展开为绝对路径，基准为 base_dir 或 get_cwd()。
+
+    处理顺序：
+      1. 展开 ~ / ~/...
+      2. 绝对路径直接 normpath 返回
+      3. 相对路径基于 actual_base 解析
+
+    CC 对照：utils/path.ts expandPath(path, baseDir?)
+    """
+    return default_cwd_context().expand_path(path, base_dir=base_dir)
+
+
+def to_relative_path(absolute_path: str) -> str:
+    """将绝对路径转为相对于 get_cwd() 的路径，节省 token。
+
+    若相对路径会超出 cwd（以 .. 开头），保持绝对路径不变。
+    CC 对照：utils/path.ts toRelativePath(absolutePath)
+    """
+    return default_cwd_context().to_relative_path(absolute_path)
+
+
+__all__ = [
+    "CwdContext",
+    "default_cwd_context",
+    "expand_path",
+    "get_cwd",
+    "run_with_cwd_override",
+    "to_relative_path",
+]

langchain_agentx/utils/host_platform.py

@@ -0,0 +1,112 @@
+"""utils/host_platform.py — 宿主 OS / WSL 分类（L1）
+
+职责：HostPlatformDetector 集中分类逻辑；可注入 getter/reader 供单测。
+链路位置：仅被需要「宿主类别」的模块引用；不解析业务路径。
+当前裁剪：不含 Cygwin/MSYS2；proc 版本读失败或空串时回退 LINUX。
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from enum import StrEnum
+from typing import Protocol
+
+logger = logging.getLogger(__name__)
+
+
+class HostPlatform(StrEnum):
+    """宿主平台枚举（字符串值与 CC / 遥测对齐）。"""
+
+    MACOS = "macos"
+    WINDOWS = "windows"
+    WSL = "wsl"
+    LINUX = "linux"
+    UNKNOWN = "unknown"
+
+
+class SysPlatformGetter(Protocol):
+    def __call__(self) -> str: ...
+
+
+class ProcVersionReader(Protocol):
+    def __call__(self) -> str: ...
+
+
+def _default_sys_platform() -> str:
+    return sys.platform
+
+
+def _default_read_proc_version() -> str:
+    with open("/proc/version", encoding="utf-8") as f:
+        return f.read()
+
+
+class HostPlatformDetector:
+    """进程级 memo：同一实例上 ``current()`` 结果缓存至 ``invalidate()``。"""
+
+    def __init__(
+        self,
+        *,
+        sys_platform_getter: SysPlatformGetter | None = None,
+        proc_version_reader: ProcVersionReader | None = None,
+    ) -> None:
+        self._sys_platform_getter = sys_platform_getter or _default_sys_platform
+        self._proc_version_reader = proc_version_reader or _default_read_proc_version
+        self._cache: HostPlatform | None = None
+
+    def current(self) -> HostPlatform:
+        if self._cache is None:
+            self._cache = self._compute()
+        return self._cache
+
+    def invalidate(self) -> None:
+        self._cache = None
+
+    def _compute(self) -> HostPlatform:
+        plat = self._sys_platform_getter().lower()
+        if plat == "darwin":
+            return HostPlatform.MACOS
+        if plat == "win32":
+            return HostPlatform.WINDOWS
+        if plat == "linux":
+            try:
+                ver_raw = self._proc_version_reader()
+            except Exception:
+                logger.debug("proc_version read failed", exc_info=True)
+                return HostPlatform.LINUX
+            ver = ver_raw.lower()
+            if not ver:
+                logger.debug("proc_version empty; treating as non-WSL linux")
+                return HostPlatform.LINUX
+            if "microsoft" in ver or "wsl" in ver:
+                logger.info("Detected WSL host environment")
+                return HostPlatform.WSL
+            return HostPlatform.LINUX
+        return HostPlatform.UNKNOWN
+
+
+_singleton: HostPlatformDetector | None = None
+
+
+def default_host_platform_detector() -> HostPlatformDetector:
+    """返回进程内共享单例（懒创建）。"""
+    global _singleton
+    if _singleton is None:
+        _singleton = HostPlatformDetector()
+    return _singleton
+
+
+def get_host_platform() -> HostPlatform:
+    """等价于 ``default_host_platform_detector().current()``。"""
+    return default_host_platform_detector().current()
+
+
+__all__ = [
+    "HostPlatform",
+    "HostPlatformDetector",
+    "ProcVersionReader",
+    "SysPlatformGetter",
+    "default_host_platform_detector",
+    "get_host_platform",
+]

langchain_agentx/utils/path_hierarchy.py

@@ -0,0 +1,48 @@
+"""utils/path_hierarchy.py — 路径层级原语（跨平台）。
+
+职责：
+    判断 Path 是否已到达当前卷/文件系统的根，供「沿父目录向上遍历」类逻辑安全退出。
+    核心逻辑在 FilesystemRootProbe；模块级 is_filesystem_root 为薄封装。
+
+链路位置：
+    memory/instruction/loader.py：ProjectRuleCollector.collect 等。
+
+当前裁剪范围：
+    仅提供根判定；不包含路径规范化业务规则。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class FilesystemRootProbe:
+    """封装 ``path.parent == path`` 根判定（与 CC git 向上遍历终止思想对齐）。"""
+
+    def is_root(self, path: Path) -> bool:
+        """若 *path* 已无更上层父目录则返回 True。"""
+        return path.parent == path
+
+
+_default_probe = FilesystemRootProbe()
+
+
+def default_filesystem_root_probe() -> FilesystemRootProbe:
+    """返回进程内共享的默认探测实例。"""
+    return _default_probe
+
+
+def is_filesystem_root(path: Path) -> bool:
+    """若 *path* 已无更上层父目录则返回 True。
+
+    使用 pathlib 约定：根目录满足 ``path.parent == path``（POSIX ``/``、
+    Windows 盘符根如 ``C:\\``、UNC 卷根等均为此类）。
+    """
+    return _default_probe.is_root(path)
+
+
+__all__ = [
+    "FilesystemRootProbe",
+    "default_filesystem_root_probe",
+    "is_filesystem_root",
+]

langchain_agentx/utils/path_user_input.py

@@ -0,0 +1,66 @@
+"""utils/path_user_input.py — 用户路径串规范化（N 层 / L2）
+
+职责：UserPathInputNormalizer 在 Windows 上将 /c/... 转为原生盘符路径；不校验 workspace。
+链路位置：expand_path 与 policy 之前；依赖 HostPlatformDetector 注入。
+当前裁剪：无 URI、无 NFC。
+"""
+
+from __future__ import annotations
+
+import re
+
+from langchain_agentx.utils.cwd import expand_path
+from langchain_agentx.utils.host_platform import (
+    HostPlatform,
+    HostPlatformDetector,
+    default_host_platform_detector,
+)
+
+# Git Bash 风格：/c/Users/... → C:\Users\...
+_POSIX_WINDOWS_DRIVE = re.compile(r"^/([a-zA-Z])(?:/|\\|$)")
+
+
+class UserPathInputNormalizer:
+    """Windows 上窄匹配 POSIX 盘符形态；其它宿主原样透传。"""
+
+    def __init__(self, host_detector: HostPlatformDetector | None = None) -> None:
+        self._host = host_detector or default_host_platform_detector()
+
+    def normalize_for_expand(self, path: str) -> str:
+        stripped = path.strip()
+        if stripped.startswith("~"):
+            return path
+        if self._host.current() is not HostPlatform.WINDOWS:
+            return path
+        m = _POSIX_WINDOWS_DRIVE.match(stripped)
+        if not m:
+            return path
+        drive = m.group(1).upper()
+        rest = stripped[m.end() :]
+        try:
+            if rest:
+                native = f"{drive}:\\" + rest.replace("/", "\\")
+            else:
+                native = f"{drive}:\\"
+            return native
+        except Exception:
+            return path
+
+    def normalize_and_expand(self, path: str, base_dir: str | None = None) -> str:
+        return expand_path(self.normalize_for_expand(path), base_dir=base_dir)
+
+
+_default_normalizer: UserPathInputNormalizer | None = None
+
+
+def normalize_user_path_string_for_expand(path: str) -> str:
+    global _default_normalizer
+    if _default_normalizer is None:
+        _default_normalizer = UserPathInputNormalizer()
+    return _default_normalizer.normalize_for_expand(path)
+
+
+__all__ = [
+    "UserPathInputNormalizer",
+    "normalize_user_path_string_for_expand",
+]

langchain_agentx/utils/rg_executable.py

@@ -0,0 +1,18 @@
+"""
+utils/rg_executable.py — 系统 ripgrep 可执行文件名
+
+职责：为子进程提供跨平台的默认 rg 命令名（本 SDK 不打包 vendor rg）。
+链路：GrepRuntimeTool / GlobRuntimeTool -> default_rg_executable()。
+
+约定：
+    - Windows：使用「rg.exe」（与 MSVC 安装及 PATH 常见形态一致）
+    - 非 Windows：使用「rg」
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def default_rg_executable() -> str:
+    return "rg.exe" if sys.platform == "win32" else "rg"

langchain_agentx/utils/subprocess_text.py

@@ -0,0 +1,101 @@
+"""utils/subprocess_text.py — 文本子进程默认编码（L4）
+
+职责：TextSubprocessRunner 封装默认 utf-8 + errors=replace；可注入 subprocess.run 测行为。
+链路位置：Bash/grep/git 等；不替代 BashRuntimeTool 安全语义。
+当前裁剪：不封装长生命周期 Popen；不默认 shell=True；禁止 shell=True。
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable, Sequence
+from typing import Any
+
+RunProc = Callable[..., subprocess.CompletedProcess[Any]]
+
+
+class TextSubprocessRunner:
+    """统一捕获文本子进程的 ``encoding`` / ``errors`` 默认值（方案 B）。"""
+
+    def __init__(
+        self,
+        *,
+        default_encoding: str = "utf-8",
+        default_errors: str = "replace",
+        subprocess_run: RunProc = subprocess.run,
+    ) -> None:
+        self._default_encoding = default_encoding
+        self._default_errors = default_errors
+        self._subprocess_run = subprocess_run
+
+    def run(
+        self,
+        args: Sequence[str] | str,
+        *,
+        encoding: str | None = None,
+        errors: str | None = None,
+        timeout: float | None = None,
+        text: bool | None = None,
+        capture_output: bool = False,
+        **kwargs: Any,
+    ) -> subprocess.CompletedProcess[Any]:
+        shell = kwargs.get("shell", False)
+        if shell is True:
+            raise ValueError(
+                "TextSubprocessRunner rejects shell=True; use argv list or a dedicated shell wrapper."
+            )
+
+        stdout = kwargs.get("stdout")
+        stderr = kwargs.get("stderr")
+
+        if text is False:
+            effective_text = False
+        elif text is True:
+            effective_text = True
+        else:
+            if capture_output or stdout is subprocess.PIPE or stderr is subprocess.PIPE:
+                effective_text = True
+            else:
+                effective_text = False
+
+        run_kw: dict[str, Any] = dict(kwargs)
+        run_kw["capture_output"] = capture_output
+        if timeout is not None:
+            run_kw["timeout"] = timeout
+
+        if effective_text:
+            enc = self._default_encoding if encoding is None else encoding
+            err = self._default_errors if errors is None else errors
+            run_kw["text"] = True
+            run_kw["encoding"] = enc
+            run_kw["errors"] = err
+        else:
+            run_kw["text"] = False
+            run_kw.pop("encoding", None)
+            run_kw.pop("errors", None)
+
+        return self._subprocess_run(args, **run_kw)
+
+
+_runner_singleton: TextSubprocessRunner | None = None
+
+
+def default_text_subprocess_runner() -> TextSubprocessRunner:
+    global _runner_singleton
+    if _runner_singleton is None:
+        _runner_singleton = TextSubprocessRunner()
+    return _runner_singleton
+
+
+def run_text(
+    args: Sequence[str] | str,
+    **kwargs: Any,
+) -> subprocess.CompletedProcess[Any]:
+    return default_text_subprocess_runner().run(args, **kwargs)
+
+
+__all__ = [
+    "TextSubprocessRunner",
+    "default_text_subprocess_runner",
+    "run_text",
+]