trinity-lite 0.1.1__py3-none-any.whl

trinity_lite/__init__.py

@@ -0,0 +1,3 @@
+"""Trinity Lite: a minimal public multi-agent task bus."""
+
+__version__ = "0.1.1"

trinity_lite/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+
+raise SystemExit(main())

trinity_lite/adapters.py

@@ -0,0 +1,136 @@
+"""Agent adapters for Trinity Lite workers."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .config import string_list
+
+
+@dataclass
+class AgentSpec:
+    agent_id: str
+    mode: str = "mock"
+    command: list[str] | None = None
+    timeout: int = 1800
+    roles: list[str] | None = None
+    capabilities: list[str] | None = None
+    priority: int = 0
+
+
+class AdapterError(RuntimeError):
+    """Raised when an agent adapter fails."""
+
+
+class BaseAdapter:
+    def __init__(self, spec: AgentSpec) -> None:
+        self.spec = spec
+
+    def run(self, task: dict[str, Any]) -> str:
+        raise NotImplementedError
+
+
+class MockAdapter(BaseAdapter):
+    def run(self, task: dict[str, Any]) -> str:
+        prompt = task["prompt"].strip().splitlines()[0][:120]
+        return (
+            f"[mock:{self.spec.agent_id}] completed task {task['id']} "
+            f"({task.get('task_type') or 'unspecified'}): {prompt}"
+        )
+
+
+class CommandAdapter(BaseAdapter):
+    def run(self, task: dict[str, Any]) -> str:
+        if not self.spec.command:
+            raise AdapterError(f"agent {self.spec.agent_id} has no command")
+        command = [self._format_arg(arg, task) for arg in self.spec.command]
+        executable = command[0]
+        if shutil.which(executable) is None and not Path(executable).exists():
+            raise AdapterError(f"executable not found for {self.spec.agent_id}: {executable}")
+        uses_prompt_placeholder = any("{prompt}" in arg for arg in self.spec.command)
+        completed = subprocess.run(
+            command,
+            cwd=task["cwd"],
+            input=None if uses_prompt_placeholder else task["prompt"],
+            text=True,
+            capture_output=True,
+            timeout=self.spec.timeout,
+            shell=False,
+            check=False,
+        )
+        output = (completed.stdout or "").strip()
+        stderr = (completed.stderr or "").strip()
+        if completed.returncode != 0:
+            detail = stderr or output or f"exit code {completed.returncode}"
+            raise AdapterError(f"{self.spec.agent_id} failed: {detail}")
+        return output or stderr or f"{self.spec.agent_id} completed without output"
+
+    @staticmethod
+    def _format_arg(arg: str, task: dict[str, Any]) -> str:
+        return (
+            arg.replace("{prompt}", task["prompt"])
+            .replace("{cwd}", task["cwd"])
+            .replace("{task_id}", task["id"])
+            .replace("{task_type}", task.get("task_type") or "")
+        )
+
+
+def default_specs() -> dict[str, AgentSpec]:
+    return {
+        "codex": AgentSpec(
+            agent_id="codex",
+            roles=["primary_engineer"],
+            capabilities=[
+                "architecture_design",
+                "code_edit",
+                "documentation",
+                "project_audit",
+                "test_run",
+            ],
+            priority=80,
+        ),
+        "claude_code": AgentSpec(
+            agent_id="claude_code",
+            roles=["reviewer"],
+            capabilities=["code_review", "risk_check", "source_scan"],
+            priority=70,
+        ),
+        "hermes": AgentSpec(
+            agent_id="hermes",
+            roles=["orchestrator", "acceptance"],
+            capabilities=["acceptance", "orchestration", "verification"],
+            priority=60,
+        ),
+    }
+
+
+def load_specs(path: str | os.PathLike[str] | None = None) -> dict[str, AgentSpec]:
+    if path is None:
+        return default_specs()
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    specs: dict[str, AgentSpec] = {}
+    for agent_id, raw in data.get("agents", {}).items():
+        specs[agent_id] = AgentSpec(
+            agent_id=agent_id,
+            mode=raw.get("mode", "mock"),
+            command=raw.get("command"),
+            timeout=int(raw.get("timeout", 1800)),
+            roles=string_list(raw.get("roles")),
+            capabilities=string_list(raw.get("capabilities")),
+            priority=int(raw.get("priority", 0)),
+        )
+    return specs or default_specs()
+
+
+def build_adapter(spec: AgentSpec) -> BaseAdapter:
+    if spec.mode == "mock":
+        return MockAdapter(spec)
+    if spec.mode == "command":
+        return CommandAdapter(spec)
+    raise AdapterError(f"unknown adapter mode for {spec.agent_id}: {spec.mode}")

trinity_lite/bus.py

@@ -0,0 +1,229 @@
+"""SQLite task and message bus for Trinity Lite."""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .guard import GuardError, ensure_inside_roots
+from .paths import default_allowed_roots, default_db_path
+
+
+MAX_DEPTH = 2
+TERMINAL_STATUSES = {"completed", "failed", "cancelled"}
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class TrinityBus:
+    """Persistent task bus backed by SQLite."""
+
+    def __init__(
+        self,
+        db_path: str | os.PathLike[str] | None = None,
+        allowed_roots: list[Path] | None = None,
+    ) -> None:
+        self.db_path = Path(db_path).expanduser() if db_path else default_db_path()
+        self.allowed_roots = allowed_roots or default_allowed_roots()
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    def connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA foreign_keys=ON")
+        return conn
+
+    def _init_db(self) -> None:
+        with self.connect() as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS tasks (
+                    id TEXT PRIMARY KEY,
+                    source_agent TEXT NOT NULL,
+                    target_agent TEXT NOT NULL,
+                    task_type TEXT,
+                    prompt TEXT NOT NULL,
+                    cwd TEXT NOT NULL,
+                    status TEXT NOT NULL,
+                    depth INTEGER NOT NULL DEFAULT 0,
+                    result TEXT,
+                    error TEXT,
+                    created_at TEXT NOT NULL,
+                    started_at TEXT,
+                    finished_at TEXT,
+                    heartbeat_at TEXT
+                )
+                """
+            )
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS messages (
+                    id TEXT PRIMARY KEY,
+                    source_agent TEXT NOT NULL,
+                    target_agent TEXT NOT NULL,
+                    task_id TEXT,
+                    message TEXT NOT NULL,
+                    read INTEGER NOT NULL DEFAULT 0,
+                    created_at TEXT NOT NULL
+                )
+                """
+            )
+
+    def submit_task(
+        self,
+        source_agent: str,
+        target_agent: str,
+        prompt: str,
+        task_type: str | None = None,
+        cwd: str | os.PathLike[str] | None = None,
+        depth: int = 0,
+    ) -> dict[str, Any]:
+        if source_agent == target_agent:
+            raise GuardError("self-delegation is not allowed")
+        if depth > MAX_DEPTH:
+            raise GuardError(f"delegation depth exceeds max depth {MAX_DEPTH}")
+        workdir = ensure_inside_roots(cwd or os.getcwd(), self.allowed_roots)
+        task_id = uuid.uuid4().hex[:12]
+        now = utc_now()
+        with self.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO tasks (
+                    id, source_agent, target_agent, task_type, prompt, cwd,
+                    status, depth, created_at, heartbeat_at
+                )
+                VALUES (?, ?, ?, ?, ?, ?, 'queued', ?, ?, ?)
+                """,
+                (
+                    task_id,
+                    source_agent,
+                    target_agent,
+                    task_type,
+                    prompt,
+                    str(workdir),
+                    depth,
+                    now,
+                    now,
+                ),
+            )
+        return self.get_task(task_id)
+
+    def get_task(self, task_id: str) -> dict[str, Any]:
+        with self.connect() as conn:
+            row = conn.execute("SELECT * FROM tasks WHERE id = ?", (task_id,)).fetchone()
+        if row is None:
+            raise KeyError(f"task not found: {task_id}")
+        return dict(row)
+
+    def list_tasks(self, agent: str | None = None, limit: int = 20) -> list[dict[str, Any]]:
+        sql = "SELECT * FROM tasks"
+        params: list[Any] = []
+        if agent:
+            sql += " WHERE source_agent = ? OR target_agent = ?"
+            params.extend([agent, agent])
+        sql += " ORDER BY created_at DESC LIMIT ?"
+        params.append(limit)
+        with self.connect() as conn:
+            rows = conn.execute(sql, params).fetchall()
+        return [dict(r) for r in rows]
+
+    def task_for_worker(self, target_agent: str) -> dict[str, Any] | None:
+        now = utc_now()
+        with self.connect() as conn:
+            conn.execute("BEGIN IMMEDIATE")
+            row = conn.execute(
+                """
+                SELECT * FROM tasks
+                WHERE target_agent = ? AND status = 'queued'
+                ORDER BY created_at ASC
+                LIMIT 1
+                """,
+                (target_agent,),
+            ).fetchone()
+            if row is None:
+                conn.commit()
+                return None
+            conn.execute(
+                """
+                UPDATE tasks
+                SET status = 'running', started_at = ?, heartbeat_at = ?
+                WHERE id = ? AND status = 'queued'
+                """,
+                (now, now, row["id"]),
+            )
+            conn.commit()
+        return self.get_task(row["id"])
+
+    def finish_worker(
+        self,
+        task_id: str,
+        result: str | None = None,
+        error: str | None = None,
+    ) -> dict[str, Any]:
+        status = "failed" if error else "completed"
+        now = utc_now()
+        with self.connect() as conn:
+            conn.execute(
+                """
+                UPDATE tasks
+                SET status = ?, result = ?, error = ?, finished_at = ?, heartbeat_at = ?
+                WHERE id = ?
+                """,
+                (status, result, error, now, now, task_id),
+            )
+        return self.get_task(task_id)
+
+    def send_message(
+        self,
+        source_agent: str,
+        target_agent: str,
+        message: str,
+        task_id: str | None = None,
+    ) -> dict[str, Any]:
+        if source_agent == target_agent:
+            raise GuardError("self-messaging is not allowed")
+        msg_id = uuid.uuid4().hex[:12]
+        with self.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO messages (
+                    id, source_agent, target_agent, task_id, message, read, created_at
+                )
+                VALUES (?, ?, ?, ?, ?, 0, ?)
+                """,
+                (msg_id, source_agent, target_agent, task_id, message, utc_now()),
+            )
+            row = conn.execute("SELECT * FROM messages WHERE id = ?", (msg_id,)).fetchone()
+        return dict(row)
+
+    def inbox(
+        self,
+        agent: str,
+        unread_only: bool = True,
+        mark_read: bool = False,
+        limit: int = 20,
+    ) -> list[dict[str, Any]]:
+        sql = "SELECT * FROM messages WHERE target_agent = ?"
+        params: list[Any] = [agent]
+        if unread_only:
+            sql += " AND read = 0"
+        sql += " ORDER BY created_at DESC LIMIT ?"
+        params.append(limit)
+        with self.connect() as conn:
+            rows = conn.execute(sql, params).fetchall()
+            messages = [dict(r) for r in rows]
+            if mark_read and messages:
+                for message in messages:
+                    conn.execute(
+                        "UPDATE messages SET read = 1 WHERE id = ?",
+                        (message["id"],),
+                    )
+        return messages

trinity_lite/cli.py

@@ -0,0 +1,178 @@
+"""Command line interface for Trinity Lite."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from typing import Any
+
+from .bus import TrinityBus
+from .doctor import run_doctor
+from .orchestrator import run_review_flow
+from .router import resolve_route
+from .worker import run_loop, run_once
+
+
+def print_json(data: Any) -> None:
+    print(json.dumps(data, ensure_ascii=False, indent=2))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="trinity-lite")
+    parser.add_argument("--db", default=None, help="SQLite database path")
+    parser.add_argument("--routes", default=None, help="routes JSON path")
+    parser.add_argument("--agents", default=None, help="agents JSON path")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--db", default=argparse.SUPPRESS, help="SQLite database path")
+    common.add_argument("--routes", default=argparse.SUPPRESS, help="routes JSON path")
+    common.add_argument("--agents", default=argparse.SUPPRESS, help="agents JSON path")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    route = sub.add_parser("route", parents=[common], help="resolve a route without dispatching")
+    route.add_argument("task")
+    route.add_argument("--type", dest="task_type")
+    route.add_argument("--previous-agent")
+
+    dispatch = sub.add_parser("dispatch", parents=[common], help="dispatch to an explicit agent")
+    dispatch.add_argument("target_agent")
+    dispatch.add_argument("task")
+    dispatch.add_argument("--source", default="user")
+    dispatch.add_argument("--type", dest="task_type")
+    dispatch.add_argument("--cwd", default=os.getcwd())
+
+    auto = sub.add_parser("dispatch-auto", parents=[common], help="resolve route then dispatch")
+    auto.add_argument("task")
+    auto.add_argument("--source", default="user")
+    auto.add_argument("--type", dest="task_type")
+    auto.add_argument("--previous-agent")
+    auto.add_argument("--cwd", default=os.getcwd())
+
+    orchestrate = sub.add_parser("orchestrate", parents=[common], help="dispatch and run a primary task with optional review")
+    orchestrate.add_argument("task")
+    orchestrate.add_argument("--source", default="user")
+    orchestrate.add_argument("--type", dest="task_type")
+    orchestrate.add_argument("--previous-agent")
+    orchestrate.add_argument("--cwd", default=os.getcwd())
+    orchestrate.add_argument("--no-run", action="store_true", help="dispatch the primary task without running workers")
+
+    status = sub.add_parser("status", parents=[common], help="show task status")
+    status.add_argument("task_id")
+
+    tasks = sub.add_parser("tasks", parents=[common], help="list recent tasks")
+    tasks.add_argument("--agent")
+    tasks.add_argument("--limit", type=int, default=20)
+
+    worker = sub.add_parser("worker", parents=[common], help="run a worker for one agent")
+    worker.add_argument("agent")
+    worker.add_argument("--once", action="store_true")
+    worker.add_argument("--poll", type=float, default=2.0)
+
+    send = sub.add_parser("send", parents=[common], help="send a durable message")
+    send.add_argument("target_agent")
+    send.add_argument("message")
+    send.add_argument("--source", default="user")
+    send.add_argument("--task-id")
+
+    inbox = sub.add_parser("inbox", parents=[common], help="read durable messages")
+    inbox.add_argument("agent")
+    inbox.add_argument("--all", action="store_true")
+    inbox.add_argument("--mark-read", action="store_true")
+    inbox.add_argument("--limit", type=int, default=20)
+
+    doctor = sub.add_parser("doctor", parents=[common], help="run environment checks")
+    doctor.add_argument("--scan-root")
+    doctor.add_argument("--runtime-root", help="runtime state directory for hygiene checks")
+    doctor.add_argument(
+        "--retired-port",
+        action="append",
+        type=int,
+        default=[],
+        help="TCP port that should not be listening, repeatable",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return run_command(args)
+    except (KeyError, OSError, ValueError) as exc:
+        print_json({"error": str(exc)})
+        return 2
+
+
+def run_command(args: argparse.Namespace) -> int:
+    bus = TrinityBus(args.db)
+
+    if args.command == "route":
+        print_json(resolve_route(args.task, args.task_type, args.previous_agent, args.routes, args.agents))
+        return 0
+    if args.command == "dispatch":
+        print_json(bus.submit_task(
+            source_agent=args.source,
+            target_agent=args.target_agent,
+            prompt=args.task,
+            task_type=args.task_type,
+            cwd=args.cwd,
+        ))
+        return 0
+    if args.command == "dispatch-auto":
+        route = resolve_route(args.task, args.task_type, args.previous_agent, args.routes, args.agents)
+        task = bus.submit_task(
+            source_agent=args.source,
+            target_agent=route["agent"],
+            prompt=args.task,
+            task_type=route["task_type"],
+            cwd=args.cwd,
+        )
+        task["route"] = route
+        print_json(task)
+        return 0
+    if args.command == "orchestrate":
+        print_json(run_review_flow(
+            args.task,
+            bus,
+            args.routes,
+            args.agents,
+            args.source,
+            args.task_type,
+            args.previous_agent,
+            args.cwd,
+            run_workers=not args.no_run,
+        ))
+        return 0
+    if args.command == "status":
+        print_json(bus.get_task(args.task_id))
+        return 0
+    if args.command == "tasks":
+        print_json(bus.list_tasks(args.agent, args.limit))
+        return 0
+    if args.command == "worker":
+        if args.once:
+            print_json(run_once(args.agent, bus, args.agents))
+            return 0
+        run_loop(args.agent, bus, args.agents, args.poll)
+        return 0
+    if args.command == "send":
+        print_json(bus.send_message(args.source, args.target_agent, args.message, args.task_id))
+        return 0
+    if args.command == "inbox":
+        print_json(bus.inbox(args.agent, unread_only=not args.all, mark_read=args.mark_read, limit=args.limit))
+        return 0
+    if args.command == "doctor":
+        print_json(run_doctor(
+            args.db,
+            args.routes,
+            args.agents,
+            args.scan_root,
+            args.runtime_root,
+            args.retired_port,
+        ))
+        return 0
+    raise AssertionError(f"unhandled command: {args.command}")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

trinity_lite/config.py

@@ -0,0 +1,16 @@
+"""Configuration normalization helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def string_list(value: Any) -> list[str]:
+    """Return a string list from a string, list, or absent value."""
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    raise ValueError(f"expected string or list of strings, got {type(value).__name__}")