agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/swarm/store.py

@@ -0,0 +1,148 @@
+"""Swarm store — filesystem layout, atomic writes, observability."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .models import STATE_VERSION
+
+# Default swarm root relative to repo: .agent-toolkit/swarm/runs/<run-id>
+SWARM_DIR_NAME = ".agent-toolkit"
+SWARM_SUBDIR = "swarm"
+RUNS_SUBDIR = "runs"
+
+ALLOWED_PATH_RE = re.compile(r"^[a-zA-Z0-9._/-]+$")
+
+
+def swarm_root_for_repo(repo_root: Path) -> Path:
+    return repo_root / SWARM_DIR_NAME / SWARM_SUBDIR
+
+
+def run_dir_for(repo_root: Path, run_id: str) -> Path:
+    # Validate run_id strictly to prevent traversal
+    if not re.match(r"^[a-zA-Z0-9][a-zA-Z0-9._-]{2,64}$", run_id):
+        raise ValueError(f"Invalid run_id: {run_id!r}")
+    return swarm_root_for_repo(repo_root) / RUNS_SUBDIR / run_id
+
+
+def ensure_run_dirs(run_dir: Path) -> None:
+    for sub in [
+        "artifacts",
+        "handoffs/outbox",
+        "handoffs/queued",
+        "handoffs/active",
+        "handoffs/completed",
+        "handoffs/failed",
+        "prompts",
+        "worktrees",
+        "runner/opencode/agents",
+    ]:
+        (run_dir / sub).mkdir(parents=True, exist_ok=True)
+
+
+def atomic_write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_fd, tmp_path = tempfile.mkstemp(dir=str(path.parent), prefix=".tmp-")
+    try:
+        with os.fdopen(tmp_fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, sort_keys=True)
+            f.write("\n")
+        os.replace(tmp_path, path)
+    finally:
+        try:
+            Path(tmp_path).unlink(missing_ok=True)
+        except Exception:
+            pass
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_fd, tmp_path = tempfile.mkstemp(dir=str(path.parent), prefix=".tmp-")
+    try:
+        with os.fdopen(tmp_fd, "w", encoding="utf-8") as f:
+            f.write(text)
+        os.replace(tmp_path, path)
+    finally:
+        try:
+            Path(tmp_path).unlink(missing_ok=True)
+        except Exception:
+            pass
+
+
+def append_trace(run_dir: Path, event: dict[str, Any]) -> None:
+    trace_path = run_dir / "trace.jsonl"
+    trace_path.parent.mkdir(parents=True, exist_ok=True)
+    line = json.dumps(event, ensure_ascii=False)
+    with trace_path.open("a", encoding="utf-8") as f:
+        f.write(line + "\n")
+
+
+def now_ts() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def is_path_contained(base: Path, candidate: Path) -> bool:
+    try:
+        candidate.resolve().relative_to(base.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def validate_artifact_path(run_dir: Path, artifact: str) -> Path:
+    # Must be relative, no traversal, stay under run_dir/artifacts or run_dir
+    if os.path.isabs(artifact):
+        raise ValueError(f"Artifact path must be relative: {artifact!r}")
+    if ".." in Path(artifact).parts:
+        raise ValueError(f"Artifact path traversal: {artifact!r}")
+    # Normalize
+    p = (run_dir / artifact).resolve()
+    base = run_dir.resolve()
+    if not is_path_contained(base, p) and p != base:
+        raise ValueError(f"Artifact escape: {artifact!r}")
+    return p
+
+
+def read_json(path: Path) -> Any:
+    if not path.is_file():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_state(run_dir: Path, state: dict[str, Any]) -> None:
+    state = dict(state)
+    state["version"] = STATE_VERSION
+    state["updated_at"] = now_ts()
+    atomic_write_json(run_dir / "state.json", state)
+    append_trace(
+        run_dir, {"ts": now_ts(), "kind": "state_changed", "state": state.get("run_state")}
+    )
+
+
+def read_state(run_dir: Path) -> dict[str, Any] | None:
+    return read_json(run_dir / "state.json")
+
+
+def list_runs(repo_root: Path) -> list[Path]:
+    runs_root = swarm_root_for_repo(repo_root) / RUNS_SUBDIR
+    if not runs_root.is_dir():
+        return []
+    return sorted([p for p in runs_root.iterdir() if p.is_dir()])
+
+
+def sanitize_args(args: list[str]) -> list[str]:
+    # Redact secrets in args for logging: look for token-like values
+    redacted: list[str] = []
+    for a in args:
+        low = a.lower()
+        if any(k in low for k in ["token", "secret", "key", "password"]):
+            redacted.append("[REDACTED]")
+        else:
+            redacted.append(a)
+    return redacted

agent_toolkit/swarm/worktree.py

@@ -0,0 +1,105 @@
+"""Worktree and branch management."""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+ROLE_RE = re.compile(r"^[a-z][a-z0-9_-]{1,31}$")
+
+
+def branch_for_run_role(run_id: str, role: str) -> str:
+    if not ROLE_RE.match(role):
+        raise ValueError(f"Invalid role: {role!r}")
+    # Safe short prefix if too long (git branch limit ~ 255, filesystem limits)
+    safe_run = re.sub(r"[^a-zA-Z0-9._-]", "-", run_id)[:32]
+    return f"agent-toolkit-swarm/{safe_run}/{role}"
+
+
+def worktree_path_for(run_dir: Path, role: str) -> Path:
+    if not ROLE_RE.match(role):
+        raise ValueError(f"Invalid role: {role!r}")
+    return run_dir / "worktrees" / role
+
+
+def git_run(args: list[str], cwd: Path, check: bool = True) -> subprocess.CompletedProcess:
+    # Safe arg handling — no shell
+    return subprocess.run(["git"] + args, cwd=str(cwd), capture_output=True, text=True, check=False)
+
+
+def create_worktree(
+    repo_root: Path, run_dir: Path, role: str, run_id: str, base_ref: str = "HEAD"
+) -> dict[str, Any]:
+    branch = branch_for_run_role(run_id, role)
+    wt_path = worktree_path_for(run_dir, role)
+    if wt_path.exists():
+        return {"branch": branch, "path": str(wt_path), "exists": True}
+    # Create branch if not exists
+    res = git_run(["rev-parse", "--verify", branch], cwd=repo_root, check=False)
+    if res.returncode != 0:
+        # create branch from base_ref
+        cre = git_run(["branch", branch, base_ref], cwd=repo_root, check=False)
+        if cre.returncode != 0:
+            raise RuntimeError(f"Failed to create branch {branch}: {cre.stderr}")
+    # Create worktree
+    wt_path.parent.mkdir(parents=True, exist_ok=True)
+    res2 = git_run(["worktree", "add", str(wt_path), branch], cwd=repo_root, check=False)
+    if res2.returncode != 0:
+        raise RuntimeError(f"Failed to create worktree {wt_path}: {res2.stderr}")
+    return {"branch": branch, "path": str(wt_path), "exists": False}
+
+
+def remove_worktree(repo_root: Path, wt_path: Path, force: bool = False) -> bool:
+    if not wt_path.exists():
+        return False
+    # Check dirty
+    res = git_run(["status", "--porcelain"], cwd=wt_path, check=False)
+    if res.returncode == 0 and res.stdout.strip() and not force:
+        raise RuntimeError(f"Worktree dirty, refusing removal without --force: {wt_path}")
+    # Remove worktree
+    git_run(
+        ["worktree", "remove", str(wt_path), "--force" if force else str(wt_path)],
+        cwd=repo_root,
+        check=False,
+    )
+    # Clean up directory if still exists
+    if wt_path.exists():
+        shutil.rmtree(wt_path, ignore_errors=True)
+    return True
+
+
+def is_worktree_dirty(wt_path: Path) -> bool:
+    res = git_run(["status", "--porcelain"], cwd=wt_path, check=False)
+    return bool(res.stdout.strip())
+
+
+def validate_worktree_ownership(run_dir: Path, wt_path: Path) -> bool:
+    # Check that wt_path is under run_dir/worktrees and owned
+    try:
+        wt_path.resolve().relative_to((run_dir / "worktrees").resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def list_worktrees(repo_root: Path) -> list[dict[str, Any]]:
+    res = git_run(["worktree", "list", "--porcelain"], cwd=repo_root, check=False)
+    if res.returncode != 0:
+        return []
+    items: list[dict[str, Any]] = []
+    cur: dict[str, Any] = {}
+    for line in res.stdout.splitlines():
+        if line.startswith("worktree "):
+            if cur:
+                items.append(cur)
+            cur = {"worktree": line.split(" ", 1)[1]}
+        elif line.startswith("branch "):
+            cur["branch"] = line.split(" ", 1)[1]
+        elif line.startswith("HEAD "):
+            cur["head"] = line.split(" ", 1)[1]
+    if cur:
+        items.append(cur)
+    return items

agent_toolkit/templates/workspace/.gitignore

@@ -0,0 +1,19 @@
+# Cloned repos (large, machine-specific)
+repos/
+
+# Project symlinks (machine-specific)
+projects/
+
+# Devcompanion artifacts
+.devcompanion/runs/
+
+# Loop run artifacts (keep STATE.md but not run dirs)
+loops/*/runs/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+
+# OS
+.DS_Store

agent_toolkit/templates/workspace/AGENTS.md

@@ -0,0 +1,82 @@
+<!-- generated-by: agent-toolkit workspace init -->
+# AGENTS.md — AI Workspace Orchestrator
+
+**Purpose**: Stateless session that orchestrates multi-repository work across any project or team.
+
+**Language**: Match the user's language for conversation → English for commits, PRs, tickets, docs.
+
+---
+
+## Work Context
+
+- **Repos**: `./projects/` symlinks (quick access) · `./repos/` cloned on-demand
+- **Knowledge**: `./knowledge/` — persistent memory across sessions
+- **Personas**: `./personas/` — focused work modes with behavioral constraints
+- **Packs**: `./packs/` — context bundles for switching between clients/projects
+
+---
+
+## agent-toolkit CLI
+
+```bash
+# Session start
+agent-toolkit workspace context    # inject workspace state
+agent-toolkit memory inject        # load all persistent knowledge
+agent-toolkit memory todo          # review pending follow-ups
+
+# During session
+agent-toolkit memory search "topic"                      # before asking known questions
+agent-toolkit memory add --type learning "pattern found" # save discoveries
+agent-toolkit memory add --type todo "follow-up item"    # track follow-ups
+
+# Async work
+agent-toolkit loop run <name>                       # run a loop template
+agent-toolkit devcompanion queue <project> --request "..." # background job
+agent-toolkit devcompanion status                   # check queue
+
+# Projects
+agent-toolkit project clone owner/repo             # clone + symlink
+agent-toolkit project list                         # list indexed projects
+```
+
+---
+
+## Operating Rules
+
+**Always:**
+- Run `agent-toolkit workspace context` at session start
+- Run `agent-toolkit memory search` before asking questions answered before
+- Save discoveries after every session: `agent-toolkit memory add`
+- For delivery: follow plan → implement → review → PR phases
+
+**Never:**
+- Assume we are inside a repo without verifying
+- Commit without code review
+- Skip the plan phase for non-trivial work
+
+---
+
+## Routing
+
+| Task type | Delegate to |
+|-----------|-------------|
+| Discovery / first look at a repo | `assistant` skill |
+| Generic delivery workflow | `workflow-generic-project` skill |
+| Code review / refactor | `code-reviewer` / `refactor-cleaner` agents |
+| Background async work | `agent-toolkit devcompanion queue` |
+| Recurring automation | `agent-toolkit loop run` |
+
+---
+
+## Portability
+
+| AI Tool | Config read |
+|---------|-------------|
+| Claude Code | `AGENTS.md` |
+| Cursor / OpenCode / Windsurf | `CLAUDE.md` → symlink to `AGENTS.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+
+---
+
+> Customize this file to reflect your team's skills, routing, and conventions.
+> See [agent-toolkit](https://github.com/ulises-jeremias/agent-toolkit) for the full toolkit.

agent_toolkit/templates/workspace/knowledge/README.md

@@ -0,0 +1,22 @@
+# Knowledge Base
+
+Persistent memory across AI sessions.
+
+## Structure
+
+```
+knowledge/
+├── learnings/general.md    # factual learnings and patterns
+├── processes/              # how-to procedures (one file per topic)
+└── todos/pending.md        # follow-up items
+```
+
+## Usage
+
+```bash
+agent-toolkit memory add --type learning "what you learned"
+agent-toolkit memory add --type todo "follow-up item"
+agent-toolkit memory search "topic"
+agent-toolkit memory inject   # output all for session context
+agent-toolkit memory todo     # show pending todos
+```

agent_toolkit/templates/workspace/knowledge/learnings/general.md

@@ -0,0 +1,3 @@
+# General Learnings
+
+> Add learnings as you discover them: `agent-toolkit memory add --type learning "..."`

agent_toolkit/templates/workspace/knowledge/todos/pending.md

@@ -0,0 +1,7 @@
+# Pending Items
+
+> Add todos: `agent-toolkit memory add --type todo "..."`
+
+---
+
+_No pending items._

agent_toolkit/templates/workspace/packs/README.md

@@ -0,0 +1,24 @@
+# Context Packs
+
+Packs bundle context for a specific client, project, or domain.
+
+## Usage
+
+```bash
+agent-toolkit workspace context load packs/my-client.yaml
+```
+
+## Structure
+
+```yaml
+# packs/my-client.yaml
+name: my-client
+description: Context for MyClient engagement
+repos:
+  - owner/repo1
+  - owner/repo2
+env:
+  JIRA_PROJECT: MYPROJ
+notes: |
+  Key conventions and decisions for this client.
+```

agent_toolkit/templates/workspace/personas/architect.md

@@ -0,0 +1,12 @@
+# Architect Persona
+
+> Activate: tell the AI "switch to architect mode"
+
+## Focus
+System design, tradeoffs, ADRs. Think before acting.
+
+## Allow
+- Read files, write ADRs and design docs
+
+## Deny
+- Implement code without plan approval

agent_toolkit/templates/workspace/personas/implementer.md

@@ -0,0 +1,12 @@
+# Implementer Persona
+
+> Activate: tell the AI "switch to implementer mode"
+
+## Focus
+Write code and take action. Bias toward shipping.
+
+## Allow
+- Edit files, run commands, create PRs
+
+## Deny
+- Skip tests or reviews without approval

agent_toolkit/templates/workspace/personas/researcher.md

@@ -0,0 +1,12 @@
+# Researcher Persona
+
+> Activate: tell the AI "switch to researcher mode"
+
+## Focus
+Explore and summarize. No implementation.
+
+## Allow
+- Read files, search, summarize findings
+
+## Deny
+- Create PRs or deploy changes

agent_toolkit/templates/workspace/personas/reviewer.md

@@ -0,0 +1,12 @@
+# Reviewer Persona
+
+> Activate: tell the AI "switch to reviewer mode"
+
+## Focus
+Analyze and critique. No changes without explicit approval.
+
+## Allow
+- Read files, write analysis, suggest changes
+
+## Deny
+- Edit production files without approval