tsugite-cli 0.14.3__tar.gz → 0.16.0__tar.gz

{tsugite_cli-0.14.3 → tsugite_cli-0.16.0}/AGENTS.md

@@ -24,6 +24,9 @@ uv run pytest --cov=tsugite --cov-report=html
 uv run black .
 uv run ruff check .
 uv run pylint tsugite
+
+# One-time: enable repo pre-commit hook (lint + format on commit)
+git config core.hooksPath .githooks
 ```
 
 ### Testing Agents
@@ -41,6 +44,20 @@ uv run tsu render agent.md "task"
 uv run tsu validate agents/*.md
 ```
 
+### Reusing tsugite from external coding agents
+
+`tsu exec` runs a Python snippet in tsugite's tool namespace, so a tsugite skill's code
+(which calls `read_file`, `http_request`, `get_secret`, ...) runs without the full agent
+loop. Secrets are allowlisted + masked; `--no-network` / `--sandbox` isolate the run. See
+[docs/external-agent-integration.md](docs/external-agent-integration.md) for reusing skills
+and agents from Claude Code, Cursor, or any agent that runs shell commands.
+
+```bash
+echo 'read_file(path="README.md")' | tsu exec -
+tsu exec snippet.py --tools @fs,@http --allow-secret gh-token
+tsu run +<agent> "task"                                 # or reuse a whole agent
+```
+
 ### Schema Management
 ```bash
 # Regenerate JSON schema after modifying AgentConfig

{tsugite_cli-0.14.3 → tsugite_cli-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tsugite-cli
-Version: 0.14.3
+Version: 0.16.0
 Summary: Micro-agent runner for task automation using markdown definitions
 Author: Justyn Shull
 License: GNU AFFERO GENERAL PUBLIC LICENSE
@@ -400,6 +400,8 @@ tsu run +default "task" --sandbox --no-network
 
 Filesystem access is limited to the workspace.  Network goes through a filtering proxy that only allows domains you specify.
 
+The daemon can also sandbox its agents (off by default, configured in `daemon.yaml`).  See [docs/sandbox.md](docs/sandbox.md).
+
 ## Config and Data Directories
 
 All paths follow [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/latest/) conventions and can be overridden with the standard environment variables.

{tsugite_cli-0.14.3 → tsugite_cli-0.16.0}/README.md

@@ -129,6 +129,8 @@ tsu run +default "task" --sandbox --no-network
 
 Filesystem access is limited to the workspace.  Network goes through a filtering proxy that only allows domains you specify.
 
+The daemon can also sandbox its agents (off by default, configured in `daemon.yaml`).  See [docs/sandbox.md](docs/sandbox.md).
+
 ## Config and Data Directories
 
 All paths follow [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/latest/) conventions and can be overridden with the standard environment variables.

{tsugite_cli-0.14.3 → tsugite_cli-0.16.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tsugite-cli"
-version = "0.14.3"
+version = "0.16.0"
 description = "Micro-agent runner for task automation using markdown definitions"
 authors = [{ name = "Justyn Shull" }]
 requires-python = ">=3.11"
@@ -67,6 +67,7 @@ members = ["plugins/*"]
 tsugite-cli = { workspace = true }
 tsugite-tmux = { workspace = true }
 tsugite-acp = { workspace = true }
+tsugite-codex-cli = { workspace = true }
 
 [tool.ruff]
 target-version = "py311"
@@ -142,4 +143,5 @@ dev = [
   "vulture>=2.14",
   "tsugite-tmux",
   "tsugite-acp",
+  "tsugite-codex-cli",
 ]

{tsugite_cli-0.14.3 → tsugite_cli-0.16.0}/tsugite/agent_inheritance.py

@@ -1,11 +1,38 @@
 """Agent inheritance resolution for Tsugite."""
 
+import importlib.metadata
+import importlib.util
+import logging
 import os
+from dataclasses import dataclass
+from enum import Enum
+from functools import lru_cache
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Set
 
 from tsugite.utils import ensure_file_exists
 
+logger = logging.getLogger(__name__)
+
+
+class AgentDirSource(Enum):
+    """Origin of an agent search directory."""
+
+    WORKSPACE = "workspace"  # caller-passed workspace agents/ (mutable)
+    PROJECT = "project"  # caller-passed project agents/ (mutable; today only http.py)
+    BUILTIN = "builtin"  # tsugite/builtin_agents/ (read-only)
+    PLUGIN = "plugin"  # plugin <pkg>/agents/ via tsugite.plugins entry-points (read-only)
+    GLOBAL = "global"  # XDG global agents/ (mutable)
+
+
+@dataclass(frozen=True)
+class AgentDir:
+    """A directory that may contain agent .md files."""
+
+    path: Path
+    source: AgentDirSource
+    readonly: bool
+
 
 def get_builtin_agents_path() -> Path:
     """Get the built-in agents directory path.
@@ -37,6 +64,113 @@ def get_global_agents_paths() -> List[Path]:
     return paths
 
 
+@lru_cache(maxsize=1)
+def get_plugin_agents_paths() -> List[Path]:
+    """Get agent directory paths contributed by installed plugins.
+
+    Scans the ``tsugite.plugins`` entry-point group; each plugin's package
+    may ship an ``agents/`` directory next to its top-level module. Plugin
+    agent dirs are treated as read-only.
+
+    Returns:
+        List of plugin-supplied agent directories (deduped, only existing dirs)
+    """
+    from tsugite.plugins import GROUP_PLUGINS
+
+    paths: List[Path] = []
+    seen: set[Path] = set()
+    try:
+        eps = importlib.metadata.entry_points(group=GROUP_PLUGINS)
+    except Exception as e:  # pragma: no cover - defensive
+        logger.debug("Failed to scan plugin entry points: %s", e)
+        return paths
+
+    for ep in eps:
+        module_name = ep.value.split(":")[0].strip()
+        top_level = module_name.split(".")[0]
+        try:
+            spec = importlib.util.find_spec(top_level)
+        except Exception:
+            spec = None
+        if spec is None or not spec.origin:
+            continue
+        agents_dir = Path(spec.origin).parent / "agents"
+        resolved = agents_dir.resolve()
+        if resolved in seen:
+            continue
+        if not agents_dir.is_dir():
+            continue
+        seen.add(resolved)
+        paths.append(agents_dir)
+    return paths
+
+
+def iter_agent_search_paths(
+    *,
+    current_agent_dir: Optional[Path] = None,
+    workspace: Optional[Any] = None,
+    extra_project_dirs: Optional[List[Path]] = None,
+    include_local_roots: bool = True,
+) -> List[AgentDir]:
+    """Yield the canonical agent-search order, deduped by resolved path.
+
+    Order:
+
+      1. workspace.agents_dir (if workspace given)
+      2. current_agent_dir / ".tsugite"
+      3. current_agent_dir / ".tsugite" / "agents"
+      4. current_agent_dir / "agents"
+      5. current_agent_dir itself (for `<name>.md` directly in cwd)
+      6. caller-supplied extra project dirs (HTTP adapter feeds per-agent dirs here)
+      7. builtin agents
+      8. XDG global agents (user agents beat plugin agents of the same name)
+      9. plugin-supplied agents
+
+    include_local_roots: when False, skip entries 2 and 5 (the bare .tsugite/
+    and cwd roots). Name-resolution callers want them so `extends: foo` finds a
+    sibling foo.md; discovery callers that glob *.md must skip them, otherwise
+    every frontmattered note in a docs/notes workspace lists as an agent.
+
+    Callers that only care about a subset filter on ``AgentDir.source``.
+    """
+    results: List[AgentDir] = []
+    seen: set[Path] = set()
+
+    def _add(path: Path, source: AgentDirSource, readonly: bool) -> None:
+        try:
+            resolved = path.resolve()
+        except (OSError, RuntimeError):
+            return
+        if resolved in seen:
+            return
+        seen.add(resolved)
+        results.append(AgentDir(path=path, source=source, readonly=readonly))
+
+    if workspace is not None and hasattr(workspace, "agents_dir"):
+        _add(workspace.agents_dir, AgentDirSource.WORKSPACE, readonly=False)
+
+    if current_agent_dir is not None:
+        if include_local_roots:
+            _add(current_agent_dir / ".tsugite", AgentDirSource.PROJECT, readonly=False)
+        _add(current_agent_dir / ".tsugite" / "agents", AgentDirSource.PROJECT, readonly=False)
+        _add(current_agent_dir / "agents", AgentDirSource.PROJECT, readonly=False)
+        if include_local_roots:
+            _add(current_agent_dir, AgentDirSource.PROJECT, readonly=False)
+
+    for extra in extra_project_dirs or []:
+        _add(extra, AgentDirSource.PROJECT, readonly=False)
+
+    _add(get_builtin_agents_path(), AgentDirSource.BUILTIN, readonly=True)
+
+    for global_dir in get_global_agents_paths():
+        _add(global_dir, AgentDirSource.GLOBAL, readonly=False)
+
+    for plugin_path in get_plugin_agents_paths():
+        _add(plugin_path, AgentDirSource.PLUGIN, readonly=True)
+
+    return results
+
+
 def find_agent_file(
     agent_ref: str,
     current_agent_dir: Path,
@@ -52,14 +186,8 @@ def find_agent_file(
     Returns:
         Path to agent file if found, None otherwise
 
-    Search order:
-    1. If path-like (contains / or .md), resolve relative to current agent
-    2. Workspace agents directory (if workspace provided)
-    3. .tsugite/{name}.md (project-local shared)
-    4. ./agents/{name}.md (project convention)
-    5. ./{name}.md (current directory)
-    6. Built-in agents directory (tsugite/builtin_agents/)
-    7. Global agent directories (XDG order)
+    Search order matches `iter_agent_search_paths`: workspace agents,
+    project-local (.tsugite/, agents/, current dir), builtin, global, plugin.
     """
     # If it looks like a path, resolve it relative to current agent
     if "/" in agent_ref or agent_ref.endswith(".md"):
@@ -71,38 +199,12 @@ def find_agent_file(
             return abs_path.resolve()
         return None
 
-    # Ensure .md extension for name-based lookup
     agent_name = agent_ref if agent_ref.endswith(".md") else f"{agent_ref}.md"
 
-    search_paths = []
-
-    # Workspace agents directory (highest priority)
-    if workspace and hasattr(workspace, "agents_dir"):
-        workspace_agents = workspace.agents_dir
-        if workspace_agents.exists():
-            search_paths.append(workspace_agents / agent_name)
-
-    # Project-local locations
-    search_paths.extend(
-        [
-            current_agent_dir / ".tsugite" / agent_name,
-            current_agent_dir / "agents" / agent_name,
-            current_agent_dir / agent_name,
-        ]
-    )
-
-    # Built-in agents directory
-    builtin_path = get_builtin_agents_path() / agent_name
-    search_paths.append(builtin_path)
-
-    # Global locations
-    for global_dir in get_global_agents_paths():
-        search_paths.append(global_dir / agent_name)
-
-    # Return first existing path
-    for path in search_paths:
-        if path.exists():
-            return path.resolve()
+    for entry in iter_agent_search_paths(current_agent_dir=current_agent_dir, workspace=workspace):
+        candidate = entry.path / agent_name
+        if candidate.exists():
+            return candidate.resolve()
 
     return None
 

{tsugite_cli-0.14.3 → tsugite_cli-0.16.0}/tsugite/agent_runner/__init__.py

@@ -3,16 +3,22 @@
 from tsugite.agent_runner.exec_directives import execute_exec_directives  # noqa: F401
 from tsugite.agent_runner.exec_runner import ExecBlockResult, run_python_block  # noqa: F401
 from tsugite.agent_runner.helpers import (  # noqa: F401
+    SandboxContext,
+    SandboxToolDeniedError,
     clear_allowed_agents,
     clear_current_agent,
+    clear_sandbox_context,
     get_allowed_agents,
     get_allowed_secrets,
     get_current_agent,
     get_display_console,
+    get_sandbox_context,
     get_ui_handler,
+    sandbox_context_to_override,
     set_allowed_agents,
     set_allowed_secrets,
     set_current_agent,
+    set_sandbox_context,
 )
 from tsugite.agent_runner.metrics import StepMetrics, display_step_metrics  # noqa: F401
 from tsugite.agent_runner.models import AgentExecutionResult  # noqa: F401
@@ -57,4 +63,10 @@ __all__ = [
     "set_allowed_secrets",
     "get_display_console",
     "get_ui_handler",
+    "SandboxContext",
+    "SandboxToolDeniedError",
+    "get_sandbox_context",
+    "set_sandbox_context",
+    "clear_sandbox_context",
+    "sandbox_context_to_override",
 ]

{tsugite_cli-0.14.3 → tsugite_cli-0.16.0}/tsugite/agent_runner/helpers.py

@@ -1,18 +1,133 @@
 """Shared helper functions for agent execution."""
 
 import threading
-from typing import Any, List, Optional
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, List, Optional
 
 from rich.console import Console
 
 from tsugite.console import get_stderr_console
 
+if TYPE_CHECKING:
+    from tsugite.options import ExecutionOptions
+
 # Console for warnings and debug output (stderr)
 _stderr_console = get_stderr_console()
 
 # Thread-local storage for tracking currently executing agent
 _current_agent_context = threading.local()
 
+# Thread-local storage for the active sandbox policy. Set per-run (in the same
+# thread as the agent loop and its parent-only tool dispatch) when an agent runs
+# sandboxed; read by host-exec/spawn tools to inherit the sandbox or be denied.
+# Thread-local (like _current_agent_context) so concurrent daemon sessions don't
+# clobber each other.
+_sandbox_context = threading.local()
+
+
+@dataclass
+class SandboxContext:
+    """Effective sandbox policy for the currently executing agent.
+
+    Presence of a SandboxContext means the agent is running sandboxed; tools read
+    it to propagate the same isolation to anything they spawn.
+    """
+
+    allow_domains: List[str] = field(default_factory=list)
+    no_network: bool = False
+    extra_ro_binds: List[Path] = field(default_factory=list)
+    extra_rw_binds: List[Path] = field(default_factory=list)
+    workspace_dir: Optional[Path] = None
+
+
+class SandboxToolDeniedError(RuntimeError):
+    """Raised when a host-exec tool is refused because the agent runs sandboxed
+    (see the deny_when_sandboxed decorator)."""
+
+
+def set_sandbox_context(ctx: Optional["SandboxContext"]) -> None:
+    """Set (or clear, with None) the active sandbox policy for this thread."""
+    _sandbox_context.value = ctx
+
+
+def get_sandbox_context() -> Optional["SandboxContext"]:
+    """Return the active sandbox policy, or None when not running sandboxed."""
+    return getattr(_sandbox_context, "value", None)
+
+
+def clear_sandbox_context() -> None:
+    """Clear the active sandbox policy from thread-local storage."""
+    if hasattr(_sandbox_context, "value"):
+        delattr(_sandbox_context, "value")
+
+
+def sandbox_context_to_override() -> Optional[dict]:
+    """Serialize the active sandbox policy as a metadata override dict, or None.
+
+    Spawn tools stamp this onto the records they create (sessions, jobs,
+    schedules) so the spawned daemon run inherits the same sandbox when it later
+    reaches the adapter chokepoint. The shape matches SandboxSettings so it can
+    be validated back there; paths are stringified to survive JSON metadata.
+    """
+    ctx = get_sandbox_context()
+    if ctx is None:
+        return None
+    return {
+        "enabled": True,
+        "no_network": ctx.no_network,
+        "allow_domains": list(ctx.allow_domains),
+        "extra_ro_binds": [str(p) for p in ctx.extra_ro_binds],
+        "extra_rw_binds": [str(p) for p in ctx.extra_rw_binds],
+    }
+
+
+def build_sandbox_policy(
+    exec_options: "ExecutionOptions",
+    *,
+    workspace_dir: Optional[Path] = None,
+    agent_config: Any = None,
+):
+    """Resolve the effective sandbox policy into (SandboxConfig, SandboxContext).
+
+    Returns (None, None) when the sandbox is off. Shared by the agent runner and
+    `tsu exec` so the two never drift. Agent frontmatter (network/sandbox) can only
+    tighten the CLI/daemon ceiling, never loosen it.
+
+    Raises RuntimeError if the sandbox is requested but bwrap is unavailable.
+    """
+    from tsugite.agent_runner.runner import resolve_effective_sandbox
+    from tsugite.core.sandbox import BubblewrapSandbox, SandboxConfig
+
+    sandbox_on, allow_domains, no_network = resolve_effective_sandbox(
+        daemon_enabled=exec_options.sandbox,
+        daemon_domains=list(exec_options.allow_domains),
+        daemon_no_network=exec_options.no_network,
+        fm_network=getattr(agent_config, "network", None),
+        fm_sandbox=getattr(agent_config, "sandbox", None),
+    )
+    if not sandbox_on:
+        return None, None
+
+    if not BubblewrapSandbox.check_available():
+        raise RuntimeError("bwrap not found. Install bubblewrap or use --no-sandbox.")
+
+    ctx = SandboxContext(
+        allow_domains=allow_domains,
+        no_network=no_network,
+        extra_ro_binds=list(exec_options.extra_ro_binds),
+        extra_rw_binds=list(exec_options.extra_rw_binds),
+        workspace_dir=workspace_dir,
+    )
+    config = SandboxConfig(
+        allowed_domains=ctx.allow_domains,
+        no_network=ctx.no_network,
+        extra_ro_binds=ctx.extra_ro_binds,
+        extra_rw_binds=ctx.extra_rw_binds,
+    )
+    return config, ctx
+
+
 # Module-level storage for allowed agents (single-threaded CLI execution)
 # Subagents run in separate processes, so this doesn't need to be thread-local
 _allowed_agents: Optional[List[str]] = None