ags-cli 0.1.0__py3-none-any.whl

harness/skills/manager.py

@@ -0,0 +1,141 @@
+"""Harness-managed skill library for the spawned CLI agents (claude / agy).
+
+Skills are a native CLI feature, not a harness one. The user's **project**
+``.claude/skills/`` already load because the harness runs the CLI with
+``cwd=project_dir`` and ``--add-dir``. This module adds a harness-curated library on
+top, two ways:
+
+1. **System-prompt index** (always on when ``inject_index``): a short "available
+   skills" note appended to the prompt the harness already builds, so the agent knows
+   which managed skills exist and to reach for its native Skill tool. Transport-safe and
+   never touches the user's config or repo.
+
+2. **Isolated config home** (opt-in, ``isolated_home``): copy the managed ``SKILL.md``
+   trees into a harness-owned config dir and point the CLI at it (claude:
+   ``CLAUDE_CONFIG_DIR``). This makes the skills natively loadable, but relocating the
+   config dir means the CLI no longer sees the user's own login — so it is OFF by
+   default and intended for setups where the harness supplies the API key
+   (``ANTHROPIC_API_KEY`` via ``secret_ref``).
+
+A skill is a directory containing a ``SKILL.md`` with YAML frontmatter (``name`` /
+``description``), matching the convention used across the ecosystem.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from harness.observability.logging import get_logger
+from harness.settings import HOME_DIR, get_settings
+
+log = get_logger("skills")
+
+# Where isolated config homes live, one per provider: ~/.ags/agents/<provider>/
+AGENTS_HOME = HOME_DIR / "agents"
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    description: str
+    path: Path
+
+
+def skills_config() -> dict:
+    return get_settings().config().get("skills") or {}
+
+
+def _managed_dir(cfg: dict) -> Path:
+    return Path(cfg.get("managed_dir", str(HOME_DIR / "skills"))).expanduser()
+
+
+def _bound(cfg: dict, *, provider: str | None, workspace: str | None) -> bool:
+    bind = cfg.get("bind") or {}
+    provs = bind.get("providers") or []
+    wss = bind.get("workspaces") or []
+    return (provider is None or not provs or provider in provs) and (
+        workspace is None or not wss or workspace in wss
+    )
+
+
+def _parse_frontmatter(text: str) -> dict:
+    """Parse a leading ``---``-delimited YAML block; tolerant of skills without one."""
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    try:
+        data = yaml.safe_load(text[3:end])
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def discover(managed_dir: Path | None = None) -> list[Skill]:
+    """Find ``<dir>/<skill>/SKILL.md`` skills and read their name/description."""
+    base = managed_dir or _managed_dir(skills_config())
+    if not base.is_dir():
+        return []
+    skills: list[Skill] = []
+    for sub in sorted(base.iterdir()):
+        md = sub / "SKILL.md"
+        if not md.is_file():
+            continue
+        fm = _parse_frontmatter(md.read_text(encoding="utf-8", errors="ignore"))
+        skills.append(Skill(
+            name=str(fm.get("name") or sub.name),
+            description=str(fm.get("description") or ""),
+            path=sub,
+        ))
+    return skills
+
+
+def index_text(skills: list[Skill]) -> str:
+    """The "available skills" note injected into the system prompt."""
+    if not skills:
+        return ""
+    lines = ["## Available skills",
+             "Managed skills are installed for this session. Use your native Skill tool "
+             "to invoke one when relevant:"]
+    lines += [f"- {s.name}: {s.description}".rstrip(": ").rstrip() for s in skills]
+    return "\n".join(lines)
+
+
+def index_for(*, provider: str | None = None, workspace: str | None = None) -> str:
+    """System-prompt skills index for a run, honoring config + binding. Empty string
+    when skills are disabled, not bound, or none are installed."""
+    cfg = skills_config()
+    if not cfg or not cfg.get("inject_index", True):
+        return ""
+    if not _bound(cfg, provider=provider, workspace=workspace):
+        return ""
+    return index_text(discover(_managed_dir(cfg)))
+
+
+def provision_config_home(provider: str) -> str | None:
+    """Opt-in: sync managed skills into ``~/.ags/agents/<provider>/skills`` and return
+    that home dir, or ``None`` when isolated-home provisioning is disabled / not bound /
+    no skills exist. Idempotent (mirrors the managed dir on each call)."""
+    cfg = skills_config()
+    if not cfg or not cfg.get("isolated_home"):
+        return None
+    if not _bound(cfg, provider=provider, workspace=None):
+        return None
+    src = _managed_dir(cfg)
+    if not src.is_dir() or not any(src.iterdir()):
+        return None
+    home = AGENTS_HOME / provider
+    dst = home / "skills"
+    try:
+        if dst.exists():
+            shutil.rmtree(dst, ignore_errors=True)
+        shutil.copytree(src, dst)
+    except OSError as e:
+        log.warning("skills_provision_failed", provider=provider, error=str(e))
+        return None
+    return str(home)

harness/tools/__init__.py

@@ -0,0 +1 @@
+"""Harness-side tools that adapters can expose to tool-calling models."""

harness/tools/fs_tools.py

@@ -0,0 +1,295 @@
+"""Filesystem tools for the agentic tool loop (OpenAI-compatible adapter).
+
+Gives a tool-calling model read — and, in write mode, write — access to the run's
+project directory, **confined to ``workspace_dir``** so it cannot escape the project
+tree. The harness owns execution and safety here; the adapter only threads the OpenAI
+tool-call protocol. Read tools are always available when tool-calling is on; the write
+tool is offered only when the workspace is in write mode (``read_only=False``).
+
+Outputs are bounded (file size, listing count, grep hits) to protect the model's context.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+from harness.models.enums import TrustPolicy
+from harness.security.approval_policy import ApprovalRequired, evaluate_gate
+
+_MAX_FILE_BYTES = 64_000
+_MAX_LIST = 400
+_MAX_GREP_HITS = 100
+_SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", ".ruff_cache", ".pytest_cache"}
+
+
+def tool_specs(read_only: bool) -> list[dict]:
+    """OpenAI ``tools`` schema for the file tools available in this mode."""
+    specs: list[dict] = [
+        {
+            "type": "function",
+            "function": {
+                "name": "read_file",
+                "description": "Read a UTF-8 text file from the project.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string", "description": "Path relative to project root."}
+                    },
+                    "required": ["path"],
+                },
+            },
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "list_dir",
+                "description": "List files and directories under a project path.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string", "description": "Dir under root (default '.')."}
+                    },
+                },
+            },
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "grep",
+                "description": "Search the project for a regex; returns file:line matches.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "pattern": {"type": "string"},
+                        "path": {"type": "string", "description": "Dir to search (default '.')."},
+                    },
+                    "required": ["pattern"],
+                },
+            },
+        },
+    ]
+    if not read_only:
+        specs.extend([
+            {
+                "type": "function",
+                "function": {
+                    "name": "write_file",
+                    "description": "Create or overwrite a UTF-8 text file (write mode only).",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "path": {"type": "string"},
+                            "content": {"type": "string"},
+                        },
+                        "required": ["path", "content"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "replace_in_file",
+                    "description": "Replace a specific string block with another in a UTF-8 text file.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "path": {"type": "string"},
+                            "old_content": {"type": "string", "description": "The exact content to replace."},
+                            "new_content": {"type": "string", "description": "The new content to insert."},
+                        },
+                        "required": ["path", "old_content", "new_content"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "execute_command",
+                    "description": "Execute a bash command in the project directory. Use this to run tests, scripts, or build tools.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "command": {"type": "string", "description": "The bash command to execute."},
+                        },
+                        "required": ["command"],
+                    },
+                },
+            }
+        ])
+    return specs
+
+
+class FileTools:
+    """Executes the file tools against a project root, confined to that root."""
+
+    def __init__(
+        self,
+        workspace_dir: str,
+        read_only: bool = True,
+        trust_policy: TrustPolicy = TrustPolicy.restricted,
+    ) -> None:
+        self.root = Path(workspace_dir).resolve()
+        self.read_only = read_only
+        self.trust_policy = trust_policy
+
+    def _resolve(self, path: str) -> Path:
+        # Confine to the workspace root — reject traversal / symlink escapes.
+        # If the model provides an absolute path that starts with the workspace root,
+        # or an absolute path in general, strip it to safely apply relative to self.root
+        path_str = (path or ".").strip()
+        root_str = str(self.root).replace('\\', '/')
+        normalized = path_str.replace('\\', '/')
+        if normalized.startswith(root_str):
+            path_str = path_str[len(root_str):].lstrip('/\\')
+            if not path_str:
+                path_str = "."
+        elif path_str.startswith('/') or (len(path_str) > 1 and path_str[1] == ':'):
+            path_str = path_str.lstrip('/\\')
+            
+        p = (self.root / path_str).resolve()
+        
+        try:
+            if not p.is_relative_to(self.root):
+                raise ValueError(f"path escapes project root: {path!r}")
+        except AttributeError:
+            if p != self.root and self.root.resolve() not in p.parents:
+                raise ValueError(f"path escapes project root: {path!r}")
+        return p
+
+    def read_file(self, path: str) -> str:
+        p = self._resolve(path)
+        if not p.is_file():
+            return f"error: not a file: {path}"
+        data = p.read_bytes()
+        try:
+            text = data[:_MAX_FILE_BYTES].decode("utf-8")
+        except UnicodeDecodeError:
+            return f"error: not a UTF-8 text file: {path}"
+        if len(data) > _MAX_FILE_BYTES:
+            text += f"\n… (truncated at {_MAX_FILE_BYTES} bytes)"
+        return text
+
+    def list_dir(self, path: str = ".") -> str:
+        p = self._resolve(path)
+        if not p.is_dir():
+            return f"error: not a directory: {path}"
+        entries = []
+        for child in sorted(p.iterdir())[:_MAX_LIST]:
+            if child.name in _SKIP_DIRS:
+                continue
+            rel = child.relative_to(self.root)
+            entries.append(f"{rel}/" if child.is_dir() else str(rel))
+        return "\n".join(entries) or "(empty)"
+
+    def grep(self, pattern: str, path: str = ".") -> str:
+        try:
+            rx = re.compile(pattern)
+        except re.error as e:
+            return f"error: bad regex: {e}"
+        base = self._resolve(path)
+        walk_root = base if base.is_dir() else base.parent
+        hits: list[str] = []
+        for dirpath, dirnames, filenames in os.walk(walk_root):
+            dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+            for fn in filenames:
+                fp = Path(dirpath) / fn
+                try:
+                    with fp.open("r", encoding="utf-8", errors="ignore") as fh:
+                        rel = fp.relative_to(self.root)
+                        for i, line in enumerate(fh, 1):
+                            if rx.search(line):
+                                hits.append(f"{rel}:{i}: {line.rstrip()[:200]}")
+                                if len(hits) >= _MAX_GREP_HITS:
+                                    return "\n".join(hits) + "\n… (truncated)"
+                except OSError:
+                    continue
+        return "\n".join(hits) or "(no matches)"
+
+    def write_file(self, path: str, content: str) -> str:
+        if self.read_only:
+            return "error: project is in read-only mode; writes are not permitted"
+        p = self._resolve(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf-8")
+        return f"wrote {len(content)} bytes to {p.relative_to(self.root)}"
+
+    def replace_in_file(self, path: str, old_content: str, new_content: str) -> str:
+        if self.read_only:
+            return "error: project is in read-only mode; writes are not permitted"
+        p = self._resolve(path)
+        if not p.is_file():
+            return f"error: not a file: {path}"
+        try:
+            content = p.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            return f"error: not a UTF-8 text file: {path}"
+        if old_content not in content:
+            return "error: old_content not found in file"
+        # We only replace the first occurrence to avoid unintended changes
+        content = content.replace(old_content, new_content, 1)
+        p.write_text(content, encoding="utf-8")
+        return f"replaced block in {p.relative_to(self.root)}"
+
+    def execute_command(self, command: str) -> str:
+        import subprocess
+        if self.read_only:
+            return "error: project is in read-only mode; execution is not permitted"
+        try:
+            result = subprocess.run(
+                command,
+                shell=True,
+                cwd=self.root,
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+            out = result.stdout.strip()
+            err = result.stderr.strip()
+            if not out and not err:
+                return f"command executed successfully with no output (exit code {result.returncode})"
+            res = ""
+            if out:
+                res += f"STDOUT:\n{out}\n"
+            if err:
+                res += f"STDERR:\n{err}\n"
+            res += f"Exit code: {result.returncode}"
+            return res[:_MAX_FILE_BYTES]
+        except subprocess.TimeoutExpired:
+            return "error: command timed out after 60 seconds"
+        except Exception as e:
+            return f"error: {e}"
+
+    def execute(self, name: str, args: dict, *, bypass_gate: bool = False) -> tuple[str, bool]:
+        """Dispatch a tool by name. Returns ``(output, is_error)``.
+
+        Raises ``ApprovalRequired`` instead of executing when the gate decides
+        this call needs a human decision first (e.g. an un-allowlisted shell
+        command). Pass ``bypass_gate=True`` to run a call that has ALREADY been
+        approved by a human (the Continuation Run after an approval) — otherwise
+        re-evaluating the gate would just raise ``ApprovalRequired`` again."""
+        if not bypass_gate:
+            decision = evaluate_gate(name, args, trust_policy=self.trust_policy)
+            if decision.requires_approval:
+                raise ApprovalRequired(name, args, decision)
+        try:
+            if name == "read_file":
+                return self.read_file(args["path"]), False
+            if name == "list_dir":
+                return self.list_dir(args.get("path", ".")), False
+            if name == "grep":
+                return self.grep(args["pattern"], args.get("path", ".")), False
+            if name == "write_file":
+                return self.write_file(args["path"], args["content"]), False
+            if name == "replace_in_file":
+                return self.replace_in_file(args["path"], args["old_content"], args["new_content"]), False
+            if name == "execute_command":
+                return self.execute_command(args["command"]), False
+            return f"error: unknown tool {name!r}", True
+        except KeyError as e:
+            return f"error: missing argument {e}", True
+        except ValueError as e:  # path escape / bad input
+            return f"error: {e}", True
+        except OSError as e:
+            return f"error: {e}", True

harness/workers/dispatch.py

@@ -0,0 +1,26 @@
+"""Session dispatch seam.
+
+Schedules an in-process ``asyncio`` task (no Redis, no worker process). The run
+executes off the request path and the CLI tails the ledger via SSE."""
+
+from __future__ import annotations
+
+import uuid
+
+from harness.workers.inprocess import schedule_session
+
+
+async def dispatch_session(
+    session_id: uuid.UUID,
+    policy: str,
+    providers: list[str] | None,
+    additional_objective: str | None = None,
+    model_override: str | None = None,
+    model_overrides: dict[str, str] | None = None,
+    attachments: list[dict] | None = None,
+) -> None:
+    schedule_session(
+        session_id, policy, providers,
+        additional_objective=additional_objective, model_override=model_override,
+        model_overrides=model_overrides, attachments=attachments,
+    )

harness/workers/inprocess.py

@@ -0,0 +1,135 @@
+"""In-process session executor for this daemonless setup.
+
+Runs ``execute_session`` (harness/orchestrator/engine.py) as an ``asyncio`` task on
+the API process's event loop — so ``ags chat`` (async + SSE) works with no separate
+worker process or message broker. Events are written to the durable ``run_events``
+ledger; the SSE endpoint tails them by polling.
+
+The task gets its own DB session (the request's session closes when the response is
+sent), a no-op event bus, and the process-local cancellation registry."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+
+from harness.db import get_sessionmaker
+from harness.eventbus import get_event_bus
+from harness.memory.extract import extract_session_memory
+from harness.memory.summarize import summarize_session
+from harness.observability.logging import get_logger
+from harness.orchestrator.engine import execute_session
+from harness.orchestrator.lifecycle import get_canceller
+from harness.orchestrator.policies import compile_policy, load_policy_specs
+from harness.settings import get_settings
+
+log = get_logger("inprocess")
+
+# Hold strong references to in-flight tasks so they aren't garbage-collected
+# mid-run (asyncio only keeps weak refs to tasks).
+_tasks: set[asyncio.Task[None]] = set()
+
+# Per-session locks to serialize concurrent turns for the same session.
+_session_locks: dict[uuid.UUID, asyncio.Lock] = {}
+
+
+def _session_lock(session_id: uuid.UUID) -> asyncio.Lock:
+    """Get or create a lock for the given session ID.
+
+    Locks are tiny; prune opportunistically when uncontended.
+    """
+    if len(_session_locks) > 256:
+        for k in [k for k, v in _session_locks.items() if not v.locked()][:128]:
+            _session_locks.pop(k, None)
+    return _session_locks.setdefault(session_id, asyncio.Lock())
+
+
+def schedule_session(
+    session_id: uuid.UUID,
+    policy_name: str,
+    providers: list[str] | None,
+    additional_objective: str | None = None,
+    model_override: str | None = None,
+    model_overrides: dict[str, str] | None = None,
+    attachments: list[dict] | None = None,
+) -> None:
+    """Fire-and-forget the session execution on the running event loop."""
+    task = asyncio.create_task(
+        _run(session_id, policy_name, providers, additional_objective, model_override,
+             model_overrides, attachments)
+    )
+    _tasks.add(task)
+    task.add_done_callback(_tasks.discard)
+
+
+def schedule_finalize(session_id: uuid.UUID, *, sessionmaker=None) -> None:
+    """Fire-and-forget background task that runs summarize + extract post-run.
+
+    Called from the inline (``ags ask``) path after ``execute_session`` so the
+    response is returned to the caller immediately, without waiting for the
+    (potentially slow) memory-finalization steps.
+
+    When *sessionmaker* is provided, it is used instead of the process-global
+    factory returned by ``get_sessionmaker()``.  Pass a sessionmaker bound to
+    the caller's engine so the background task hits the same DB as the request
+    or test session (the global factory defaults to 127.0.0.1:5432 which may
+    not be reachable in test environments).
+
+    Uses the same strong-reference set + done-callback pattern as
+    ``schedule_session`` so the task cannot be garbage-collected mid-run.
+    """
+    task = asyncio.create_task(_finalize(session_id, sessionmaker=sessionmaker))
+    _tasks.add(task)
+    task.add_done_callback(_tasks.discard)
+
+
+async def _finalize(session_id: uuid.UUID, *, sessionmaker=None) -> None:
+    """Async helper that runs summarize + extract in their own DB session."""
+    factory = sessionmaker if sessionmaker is not None else get_sessionmaker()
+    async with _session_lock(session_id):
+        async with factory() as db:
+            try:
+                await summarize_session(db, session_id)
+                await db.commit()
+                await extract_session_memory(db, session_id)
+                await db.commit()
+            except Exception:
+                await db.rollback()
+                log.error("inprocess_finalize_failed", session_id=str(session_id), exc_info=True)
+
+
+async def _run(
+    session_id: uuid.UUID,
+    policy_name: str,
+    providers: list[str] | None,
+    additional_objective: str | None,
+    model_override: str | None,
+    model_overrides: dict[str, str] | None = None,
+    attachments: list[dict] | None = None,
+) -> None:
+    specs = load_policy_specs(get_settings().config())
+    policy_spec = specs.get(policy_name, {"name": policy_name, "mode": policy_name})
+    policy = compile_policy(policy_spec, override_providers=providers)
+    bus = get_event_bus()
+    canceller = get_canceller()
+
+    async with _session_lock(session_id):
+        async with get_sessionmaker()() as db:
+            try:
+                await execute_session(
+                    db, session_id=session_id, policy=policy, bus=bus, canceller=canceller,
+                    message_override=additional_objective, model_override=model_override,
+                    model_overrides=model_overrides, attachments=attachments,
+                )
+                # Commit each phase so the SQLite write lock is released promptly. Memory
+                # extraction (embeddings) can take seconds; holding one transaction across
+                # it blocks a concurrent turn's `create_runs` INSERT and 500s with
+                # "database is locked" under the GUI's overlapping requests.
+                await db.commit()
+                await summarize_session(db, session_id)
+                await db.commit()
+                await extract_session_memory(db, session_id)
+                await db.commit()
+            except Exception:  # contain — the run row already carries failure state
+                await db.rollback()
+                log.error("inprocess_session_failed", session_id=str(session_id), exc_info=True)