trinity-lite 0.1.2__tar.gz → 0.1.4__tar.gz

{trinity_lite-0.1.2/trinity_lite.egg-info → trinity_lite-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trinity-lite
-Version: 0.1.2
+Version: 0.1.4
 Summary: A minimal public multi-agent task bus with routing, workers, and safety checks.
 Author: Yomiracle
 License-Expression: MIT
@@ -155,7 +155,24 @@ trinity-lite worker codex --once
 trinity-lite tasks
 ```
 
-For local development from source:
+## Upgrading
+
+```bash
+python3 -m pip install --upgrade trinity-lite
+```
+
+Trinity Lite follows [semantic versioning](https://semver.org). Patch releases (0.1.x) are backward-compatible
+and require no configuration or data migration. Check your version:
+
+```bash
+trinity-lite doctor
+# or
+python3 -m pip show trinity-lite | grep Version
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for what changed between versions.
+
+## Quick Start (from source)
 
 ```bash
 git clone https://github.com/Yomiracle/trinity-lite.git

{trinity_lite-0.1.2 → trinity_lite-0.1.4}/README.md

@@ -134,7 +134,24 @@ trinity-lite worker codex --once
 trinity-lite tasks
 ```
 
-For local development from source:
+## Upgrading
+
+```bash
+python3 -m pip install --upgrade trinity-lite
+```
+
+Trinity Lite follows [semantic versioning](https://semver.org). Patch releases (0.1.x) are backward-compatible
+and require no configuration or data migration. Check your version:
+
+```bash
+trinity-lite doctor
+# or
+python3 -m pip show trinity-lite | grep Version
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for what changed between versions.
+
+## Quick Start (from source)
 
 ```bash
 git clone https://github.com/Yomiracle/trinity-lite.git

{trinity_lite-0.1.2 → trinity_lite-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trinity-lite"
-version = "0.1.2"
+version = "0.1.4"
 description = "A minimal public multi-agent task bus with routing, workers, and safety checks."
 readme = "README.md"
 requires-python = ">=3.10"

{trinity_lite-0.1.2 → trinity_lite-0.1.4}/tests/test_bus.py

@@ -61,6 +61,19 @@ class BusTest(unittest.TestCase):
         with self.assertRaises(KeyError):
             self.bus.get_task("rollback-test")
 
+    def test_await_task_returns_on_completion(self):
+        task = self.bus.submit_task("user", "codex", "build it", "implementation", cwd=self.root)
+        self.bus.task_for_worker("codex")
+        self.bus.finish_worker(task["id"], result="ok")
+        result = self.bus.await_task(task["id"], timeout=5)
+        self.assertEqual(result["status"], "completed")
+        self.assertEqual(result["result"], "ok")
+
+    def test_await_task_timeout_raises(self):
+        task = self.bus.submit_task("user", "codex", "slow task", "implementation", cwd=self.root)
+        with self.assertRaises(TimeoutError):
+            self.bus.await_task(task["id"], timeout=0.1)
+
     def test_message_round_trip(self):
         msg = self.bus.send_message("codex", "claude_code", "please review")
         self.assertEqual(msg["read"], 0)

trinity_lite-0.1.4/tests/test_cli.py

@@ -0,0 +1,323 @@
+import io
+import json
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+
+from trinity_lite.cli import main
+
+
+class CliTest(unittest.TestCase):
+    def test_global_options_work_after_subcommand(self):
+        with tempfile.TemporaryDirectory(dir=str(Path.home())) as tmp:
+            root = Path(tmp)
+            db = root / "bus.db"
+            output = io.StringIO()
+            with redirect_stdout(output):
+                code = main([
+                    "dispatch-auto",
+                    "implement a parser",
+                    "--db",
+                    str(db),
+                    "--cwd",
+                    str(root),
+                ])
+                self.assertEqual(code, 0)
+                code = main(["worker", "codex", "--once", "--db", str(db)])
+                self.assertEqual(code, 0)
+
+    def test_route_errors_are_structured(self):
+        output = io.StringIO()
+        with redirect_stdout(output):
+            code = main(["route", "review this patch"])
+        self.assertEqual(code, 2)
+        self.assertIn('"error"', output.getvalue())
+
+    def test_doctor_accepts_runtime_hygiene_options(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            runtime = root / "runtime"
+            runtime.mkdir()
+            (runtime / "metrics.jsonl").write_text("", encoding="utf-8")
+            output = io.StringIO()
+            with redirect_stdout(output):
+                code = main([
+                    "doctor",
+                    "--db",
+                    str(root / "bus.db"),
+                    "--runtime-root",
+                    str(runtime),
+                    "--retired-port",
+                    "70000",
+                ])
+            self.assertEqual(code, 0)
+            self.assertIn('"runtime_metrics"', output.getvalue())
+            self.assertIn('"retired_port:70000"', output.getvalue())
+
+    def test_dispatch_wait_blocks_until_complete(self):
+        with tempfile.TemporaryDirectory(dir=str(Path.home())) as tmp:
+            root = Path(tmp)
+            output = io.StringIO()
+            with redirect_stdout(output):
+                code = main([
+                    "dispatch",
+                    "codex",
+                    "implement hello world",
+                    "--db",
+                    str(root / "bus.db"),
+                    "--cwd",
+                    str(root),
+                    "--wait",
+                    "--wait-timeout",
+                    "5",
+                ])
+            self.assertEqual(code, 0)
+            data = json.loads(output.getvalue())
+            self.assertEqual(data["status"], "completed")
+            self.assertIn("target_agent", data)
+            self.assertEqual(data["target_agent"], "codex")
+
+    def test_dispatch_auto_wait_blocks_until_complete(self):
+        with tempfile.TemporaryDirectory(dir=str(Path.home())) as tmp:
+            root = Path(tmp)
+            agents_path = root / "agents.json"
+            routes_path = root / "routes.json"
+            agents_path.write_text(json.dumps({
+                "agents": {
+                    "qwen_cli": {
+                        "mode": "mock",
+                        "roles": ["primary_engineer"],
+                        "capabilities": ["code_edit"],
+                        "priority": 80,
+                    }
+                }
+            }), encoding="utf-8")
+            routes_path.write_text(json.dumps({
+                "routes": {
+                    "implementation": {
+                        "requires": ["code_edit"],
+                        "prefer": ["primary_engineer"],
+                    }
+                },
+                "opposites": {}
+            }), encoding="utf-8")
+            output = io.StringIO()
+            with redirect_stdout(output):
+                code = main([
+                    "dispatch-auto",
+                    "implement a parser",
+                    "--db",
+                    str(root / "bus.db"),
+                    "--cwd",
+                    str(root),
+                    "--agents",
+                    str(agents_path),
+                    "--routes",
+                    str(routes_path),
+                    "--wait",
+                    "--wait-timeout",
+                    "5",
+                ])
+            self.assertEqual(code, 0)
+            data = json.loads(output.getvalue())
+            self.assertEqual(data["status"], "completed")
+            self.assertEqual(data["target_agent"], "qwen_cli")
+
+    def test_dispatch_auto_uses_capability_routes_and_agents(self):
+        with tempfile.TemporaryDirectory(dir=str(Path.home())) as tmp:
+            root = Path(tmp)
+            agents_path = root / "agents.json"
+            routes_path = root / "routes.json"
+            agents_path.write_text(json.dumps({
+                "agents": {
+                    "qwen_cli": {
+                        "mode": "mock",
+                        "roles": ["primary_engineer"],
+                        "capabilities": ["code_edit"],
+                        "priority": 80,
+                    }
+                }
+            }), encoding="utf-8")
+            routes_path.write_text(json.dumps({
+                "routes": {
+                    "implementation": {
+                        "requires": ["code_edit"],
+                        "prefer": ["primary_engineer"],
+                    }
+                },
+                "opposites": {}
+            }), encoding="utf-8")
+            output = io.StringIO()
+            with redirect_stdout(output):
+                code = main([
+                    "dispatch-auto",
+                    "implement a parser",
+                    "--db",
+                    str(root / "bus.db"),
+                    "--cwd",
+                    str(root),
+                    "--agents",
+                    str(agents_path),
+                    "--routes",
+                    str(routes_path),
+                ])
+            self.assertEqual(code, 0)
+            self.assertIn('"target_agent": "qwen_cli"', output.getvalue())
+
+    def test_orchestrate_uses_capability_routes_and_agents(self):
+        with tempfile.TemporaryDirectory(dir=str(Path.home())) as tmp:
+            root = Path(tmp)
+            agents_path = root / "agents.json"
+            routes_path = root / "routes.json"
+            agents_path.write_text(json.dumps({
+                "agents": {
+                    "qwen_cli": {
+                        "mode": "mock",
+                        "capabilities": ["code_edit"],
+                    },
+                    "gemini_cli": {
+                        "mode": "mock",
+                        "capabilities": ["code_review"],
+                    },
+                }
+            }), encoding="utf-8")
+            routes_path.write_text(json.dumps({
+                "routes": {
+                    "implementation": {
+                        "requires": ["code_edit"],
+                        "review_required": True,
+                    },
+                    "code_review": {
+                        "requires": ["code_review"],
+                    },
+                },
+                "opposites": {}
+            }), encoding="utf-8")
+            output = io.StringIO()
+            with redirect_stdout(output):
+                code = main([
+                    "orchestrate",
+                    "implement parser",
+                    "--db",
+                    str(root / "bus.db"),
+                    "--cwd",
+                    str(root),
+                    "--agents",
+                    str(agents_path),
+                    "--routes",
+                    str(routes_path),
+                ])
+            self.assertEqual(code, 0)
+            text = output.getvalue()
+            self.assertIn('"target_agent": "qwen_cli"', text)
+            self.assertIn('"target_agent": "gemini_cli"', text)
+            self.assertIn('"acceptance_status": "accepted"', text)
+
+    def test_orchestrate_wait_runs_workers_and_completes(self):
+        with tempfile.TemporaryDirectory(dir=str(Path.home())) as tmp:
+            root = Path(tmp)
+            agents_path = root / "agents.json"
+            routes_path = root / "routes.json"
+            agents_path.write_text(json.dumps({
+                "agents": {
+                    "qwen_cli": {
+                        "mode": "mock",
+                        "capabilities": ["code_edit"],
+                    },
+                    "gemini_cli": {
+                        "mode": "mock",
+                        "capabilities": ["code_review"],
+                    },
+                }
+            }), encoding="utf-8")
+            routes_path.write_text(json.dumps({
+                "routes": {
+                    "implementation": {
+                        "requires": ["code_edit"],
+                        "review_required": True,
+                    },
+                    "code_review": {
+                        "requires": ["code_review"],
+                    },
+                },
+                "opposites": {}
+            }), encoding="utf-8")
+            output = io.StringIO()
+            with redirect_stdout(output):
+                code = main([
+                    "orchestrate",
+                    "implement parser",
+                    "--db",
+                    str(root / "bus.db"),
+                    "--cwd",
+                    str(root),
+                    "--agents",
+                    str(agents_path),
+                    "--routes",
+                    str(routes_path),
+                    "--wait",
+                    "--wait-timeout",
+                    "10",
+                ])
+            self.assertEqual(code, 0)
+            text = output.getvalue()
+            self.assertIn('"acceptance_status": "accepted"', text)
+
+
+    def test_demo_command_produces_friendly_output(self):
+        with tempfile.TemporaryDirectory(dir=str(Path.home())) as tmp:
+            root = Path(tmp)
+            output = io.StringIO()
+            with redirect_stdout(output):
+                code = main([
+                    "demo",
+                    "--db",
+                    str(root / "bus.db"),
+                ])
+            self.assertEqual(code, 0)
+            text = output.getvalue()
+            self.assertIn("Trinity Lite Demo", text)
+            self.assertIn("Next steps:", text)
+            self.assertIn("trinity-lite tasks", text)
+            self.assertIn("docs/REAL_AGENTS.md", text)
+
+    def test_version_command_prints_version(self):
+        output = io.StringIO()
+        with redirect_stdout(output):
+            code = main(["version"])
+        self.assertEqual(code, 0)
+        self.assertIn("trinity-lite", output.getvalue())
+
+    def test_version_flag_prints_version(self):
+        output = io.StringIO()
+        with redirect_stdout(output):
+            code = main(["--version"])
+        self.assertEqual(code, 0)
+        self.assertIn("trinity-lite", output.getvalue())
+
+    def test_no_args_shows_banner(self):
+        output = io.StringIO()
+        with redirect_stdout(output):
+            code = main([])
+        self.assertEqual(code, 0)
+        text = output.getvalue()
+        self.assertIn("Trinity Lite", text)
+        self.assertIn("Quick demo", text)
+        self.assertIn("trinity-lite demo", text)
+
+    def test_help_flag_works(self):
+        import sys
+        output = io.StringIO()
+        with redirect_stdout(output):
+            try:
+                main(["--help"])
+            except SystemExit as e:
+                self.assertEqual(e.code, 0)
+        text = output.getvalue()
+        self.assertIn("demo", text)
+        self.assertIn("version", text)
+
+
+if __name__ == "__main__":
+    unittest.main()

{trinity_lite-0.1.2 → trinity_lite-0.1.4}/trinity_lite/bus.py

@@ -216,6 +216,17 @@ class TrinityBus:
             row = conn.execute("SELECT * FROM messages WHERE id = ?", (msg_id,)).fetchone()
         return dict(row)
 
+    def await_task(self, task_id: str, timeout: float = 300) -> dict[str, Any]:
+        """Block until task reaches terminal status or timeout."""
+        import time
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            task = self.get_task(task_id)
+            if task["status"] in TERMINAL_STATUSES:
+                return task
+            time.sleep(0.2)
+        raise TimeoutError(f"task {task_id} did not finish within {timeout}s")
+
     def inbox(
         self,
         agent: str,

trinity_lite-0.1.4/trinity_lite/cli.py

@@ -0,0 +1,440 @@
+"""Command line interface for Trinity Lite."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+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 _version() -> str:
+    """Return the installed version, favouring importlib.metadata."""
+    try:
+        from importlib.metadata import PackageNotFoundError, version  # Python >= 3.8
+
+        return version("trinity-lite")
+    except (ImportError, PackageNotFoundError):
+        from . import __version__
+
+        return __version__  # pragma: no cover — fallback for development
+
+
+BANNER = """\
+Trinity Lite — multi-agent task bus
+====================================
+
+Quick demo:  trinity-lite demo
+Full help:   trinity-lite --help
+
+Commands: demo, dispatch, dispatch-auto, worker, orchestrate,
+          status, tasks, route, doctor, send, inbox"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="trinity-lite")
+    parser.add_argument("--version", action="store_true", help="show version and exit")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--db", default=None, help="SQLite database path")
+    common.add_argument("--routes", default=None, help="routes JSON path")
+    common.add_argument("--agents", default=None, help="agents JSON path")
+    sub = parser.add_subparsers(dest="command")
+
+    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())
+    dispatch.add_argument("--wait", action="store_true", help="block until task completes and print final result")
+    dispatch.add_argument("--wait-timeout", type=float, default=300, help="timeout in seconds for --wait (default: 300)")
+
+    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())
+    auto.add_argument("--wait", action="store_true", help="block until task completes and print final result")
+    auto.add_argument("--wait-timeout", type=float, default=300, help="timeout in seconds for --wait (default: 300)")
+
+    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")
+    orchestrate.add_argument("--wait", action="store_true", help="block until orchestrated flow completes")
+    orchestrate.add_argument("--wait-timeout", type=float, default=300, help="timeout in seconds for --wait (default: 300)")
+
+    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",
+    )
+
+    version_cmd = sub.add_parser("version", parents=[common], help="show version and exit")
+
+    demo = sub.add_parser("demo", parents=[common], help="run a guided first-run demo")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+
+    # No-args: show friendly intro
+    if argv is None:
+        argv = sys.argv[1:]
+    if not argv:
+        print(BANNER)
+        return 0
+
+    args = parser.parse_args(argv)
+
+    # --version flag (before subcommand)
+    if args.version:
+        print(f"trinity-lite {_version()}")
+        return 0
+
+    # No subcommand but unknown args → show friendly intro
+    if args.command is None:
+        print(BANNER)
+        return 0
+
+    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 == "version":
+        print(f"trinity-lite {_version()}")
+        return 0
+
+    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":
+        task = bus.submit_task(
+            source_agent=args.source,
+            target_agent=args.target_agent,
+            prompt=args.task,
+            task_type=args.task_type,
+            cwd=args.cwd,
+        )
+        if getattr(args, "wait", False):
+            task = _wait_for_task(bus, task["id"], args.target_agent, args.agents, args.wait_timeout)
+        print_json(task)
+        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
+        if getattr(args, "wait", False):
+            task = _wait_for_task(bus, task["id"], route["agent"], args.agents, args.wait_timeout)
+        print_json(task)
+        return 0
+    if args.command == "orchestrate":
+        result = 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 and not getattr(args, "wait", False),
+        )
+        if getattr(args, "wait", False):
+            result = _wait_for_flow(bus, result, args.agents, args.routes, args.wait_timeout)
+        print_json(result)
+        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
+    if args.command == "demo":
+        return _demo(args, bus)
+
+    raise AssertionError(f"unhandled command: {args.command}")
+
+
+def _wait_for_task(
+    bus: TrinityBus,
+    task_id: str,
+    agent: str,
+    agents_path: str | None,
+    timeout: float,
+) -> dict[str, Any]:
+    """Run worker cycles for agent until task completes or timeout."""
+    import time as _time
+    from .bus import TERMINAL_STATUSES
+    deadline = _time.monotonic() + timeout
+    while _time.monotonic() < deadline:
+        task = bus.get_task(task_id)
+        if task["status"] in TERMINAL_STATUSES:
+            return task
+        # Try to process one queued/running task
+        run_once(agent, bus, agents_path, task_id=task_id)
+        _time.sleep(0.1)
+    raise TimeoutError(f"task {task_id} did not finish within {timeout}s")
+
+
+def _wait_for_flow(
+    bus: TrinityBus,
+    flow: dict[str, Any],
+    agents_path: str | None,
+    routes_path: str | None,
+    timeout: float,
+) -> dict[str, Any]:
+    """Run workers to complete a review flow until terminal."""
+    import time as _time
+    from .bus import TERMINAL_STATUSES
+    from .orchestrator import _review_prompt
+
+    primary_id = flow["primary_task"]["id"]
+    primary_agent = flow["route"]["agent"]
+    route = flow["route"]
+
+    # Review may not have been dispatched yet (if run_workers=False was used)
+    review_id = None
+    review_agent = None
+    review = flow.get("review_task")
+    if review:
+        review_id = review["id"]
+        review_agent = flow.get("review_route", {}).get("agent") if flow.get("review_route") else None
+
+    deadline = _time.monotonic() + timeout
+    review_dispatched = review_id is not None
+
+    while _time.monotonic() < deadline:
+        primary = bus.get_task(primary_id)
+
+        # If primary just completed and review is required but not yet dispatched
+        if (primary["status"] == "completed"
+                and route["review_required"]
+                and not review_dispatched):
+            review_prompt_text = _review_prompt(primary)
+            review_route = resolve_route(
+                review_prompt_text,
+                "code_review",
+                route["agent"],
+                routes_path,
+                agents_path,
+            )
+            review_task = bus.submit_task(
+                source_agent=route["agent"],
+                target_agent=review_route["agent"],
+                prompt=review_prompt_text,
+                task_type=review_route["task_type"],
+                cwd=primary["cwd"],
+                depth=int(primary["depth"]) + 1,
+            )
+            review_id = review_task["id"]
+            review_agent = review_route["agent"]
+            review_dispatched = True
+            flow["review_route"] = review_route
+            flow["review_task"] = review_task
+
+        review_done = True
+        if review_id is not None:
+            review_task = bus.get_task(review_id)
+            review_done = review_task["status"] in TERMINAL_STATUSES
+
+        if primary["status"] in TERMINAL_STATUSES and review_done:
+            flow["primary_task"] = primary
+            if review_id is not None:
+                flow["review_task"] = bus.get_task(review_id)
+            flow["acceptance_status"] = _acceptance_status_from_flow(
+                flow["route"], primary, flow.get("review_task")
+            )
+            return flow
+
+        if primary["status"] not in TERMINAL_STATUSES:
+            run_once(primary_agent, bus, agents_path, task_id=primary_id)
+        elif review_id is not None and review_agent:
+            run_once(review_agent, bus, agents_path, task_id=review_id)
+        _time.sleep(0.1)
+    raise TimeoutError(f"flow for {primary_id} did not finish within {timeout}s")
+
+
+def _acceptance_status_from_flow(
+    route: dict[str, Any],
+    primary_task: dict[str, Any],
+    review_task: dict[str, Any] | None,
+) -> str:
+    from .orchestrator import _acceptance_status
+    return _acceptance_status(route, primary_task, review_task)
+
+
+def _demo(args: argparse.Namespace, bus: TrinityBus) -> int:
+    """Run a guided demo flow with human-friendly output."""
+
+    print("Trinity Lite Demo")
+    print("=================")
+
+    # ---- 1. Doctor ----
+    print("→ Running environment checks...")
+    try:
+        health = run_doctor(args.db, args.routes, args.agents)
+        status_label = "healthy" if health["status"] == "healthy" else "unhealthy"
+        icon = "✓" if health["status"] == "healthy" else "✗"
+        print(f"  {icon} Doctor: {status_label}")
+        for check in health.get("checks", []):
+            mark = "✓" if check["ok"] else "✗"
+            print(f"    {mark} {check['name']}: {str(check.get('detail', '')).strip()}")
+    except Exception as exc:
+        print(f"  ✗ Doctor: {exc}")
+    print()
+
+    # ---- 2. Dispatch + worker cycle (full orchestrated flow) ----
+    demo_prompt = "write a hello world function in Python"
+    print("→ Dispatching demo task...")
+    flow = run_review_flow(
+        demo_prompt,
+        bus,
+        args.routes,
+        args.agents,
+        source_agent="user",
+        cwd=str(Path.home()),
+        run_workers=True,
+    )
+    primary = flow["primary_task"]
+    route = flow["route"]
+
+    print(f"  Task ID: {primary['id']}")
+    print(f"  Routed to: {route['agent']}")
+    print()
+
+    # ---- 3. Codex worker already ran in run_review_flow ----
+    print(f"→ Running mock worker ({route['agent']})...")
+    icon = "✓" if primary["status"] == "completed" else "✗"
+    print(f"  {icon} Task {primary['id']} {primary['status']}")
+    print()
+
+    # ---- 4. Claude Code review (already ran via run_review_flow) ----
+    print("→ Running mock worker (claude_code)...")
+    review_task = flow.get("review_task")
+    if review_task:
+        icon = "✓" if review_task.get("status") == "completed" else "✗"
+        print(f"  {icon} Review {review_task.get('status')}")
+    else:
+        print("  - No review task required for this demo")
+    print()
+
+    # ---- 5. Results ----
+    print("→ Results:")
+    final = bus.get_task(primary["id"])
+    print(f"  Task: {final['prompt']}")
+    print(f"  Status: {final['status']}")
+    if final.get("result"):
+        result_text = final["result"]
+        if len(result_text) > 200:
+            result_text = result_text[:200] + "..."
+        print(f"  Result: {result_text}")
+    if final.get("error"):
+        print(f"  Error: {final['error']}")
+    if review_task:
+        review_final = bus.get_task(review_task["id"])
+        print(f"  Review: {review_final.get('status')}")
+        if review_final.get("result"):
+            r_text = review_final["result"]
+            if len(r_text) > 200:
+                r_text = r_text[:200] + "..."
+            print(f"  Review result: {r_text}")
+    print()
+
+    # ---- 6. Next steps ----
+    print("Next steps:")
+    print("  • See all tasks: trinity-lite tasks")
+    print("  • Connect real agents: docs/REAL_AGENTS.md")
+    print("  • Full docs: https://github.com/Yomiracle/trinity-lite")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{trinity_lite-0.1.2 → trinity_lite-0.1.4/trinity_lite.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trinity-lite
-Version: 0.1.2
+Version: 0.1.4
 Summary: A minimal public multi-agent task bus with routing, workers, and safety checks.
 Author: Yomiracle
 License-Expression: MIT
@@ -155,7 +155,24 @@ trinity-lite worker codex --once
 trinity-lite tasks
 ```
 
-For local development from source:
+## Upgrading
+
+```bash
+python3 -m pip install --upgrade trinity-lite
+```
+
+Trinity Lite follows [semantic versioning](https://semver.org). Patch releases (0.1.x) are backward-compatible
+and require no configuration or data migration. Check your version:
+
+```bash
+trinity-lite doctor
+# or
+python3 -m pip show trinity-lite | grep Version
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for what changed between versions.
+
+## Quick Start (from source)
 
 ```bash
 git clone https://github.com/Yomiracle/trinity-lite.git

trinity_lite-0.1.2/tests/test_cli.py

@@ -1,150 +0,0 @@
-import io
-import json
-import tempfile
-import unittest
-from contextlib import redirect_stdout
-from pathlib import Path
-
-from trinity_lite.cli import main
-
-
-class CliTest(unittest.TestCase):
-    def test_global_options_work_after_subcommand(self):
-        with tempfile.TemporaryDirectory(dir=str(Path.home())) as tmp:
-            root = Path(tmp)
-            db = root / "bus.db"
-            output = io.StringIO()
-            with redirect_stdout(output):
-                code = main([
-                    "dispatch-auto",
-                    "implement a parser",
-                    "--db",
-                    str(db),
-                    "--cwd",
-                    str(root),
-                ])
-                self.assertEqual(code, 0)
-                code = main(["worker", "codex", "--once", "--db", str(db)])
-                self.assertEqual(code, 0)
-
-    def test_route_errors_are_structured(self):
-        output = io.StringIO()
-        with redirect_stdout(output):
-            code = main(["route", "review this patch"])
-        self.assertEqual(code, 2)
-        self.assertIn('"error"', output.getvalue())
-
-    def test_doctor_accepts_runtime_hygiene_options(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
-            runtime = root / "runtime"
-            runtime.mkdir()
-            (runtime / "metrics.jsonl").write_text("", encoding="utf-8")
-            output = io.StringIO()
-            with redirect_stdout(output):
-                code = main([
-                    "doctor",
-                    "--db",
-                    str(root / "bus.db"),
-                    "--runtime-root",
-                    str(runtime),
-                    "--retired-port",
-                    "70000",
-                ])
-            self.assertEqual(code, 0)
-            self.assertIn('"runtime_metrics"', output.getvalue())
-            self.assertIn('"retired_port:70000"', output.getvalue())
-
-    def test_dispatch_auto_uses_capability_routes_and_agents(self):
-        with tempfile.TemporaryDirectory(dir=str(Path.home())) as tmp:
-            root = Path(tmp)
-            agents_path = root / "agents.json"
-            routes_path = root / "routes.json"
-            agents_path.write_text(json.dumps({
-                "agents": {
-                    "qwen_cli": {
-                        "mode": "mock",
-                        "roles": ["primary_engineer"],
-                        "capabilities": ["code_edit"],
-                        "priority": 80,
-                    }
-                }
-            }), encoding="utf-8")
-            routes_path.write_text(json.dumps({
-                "routes": {
-                    "implementation": {
-                        "requires": ["code_edit"],
-                        "prefer": ["primary_engineer"],
-                    }
-                },
-                "opposites": {}
-            }), encoding="utf-8")
-            output = io.StringIO()
-            with redirect_stdout(output):
-                code = main([
-                    "dispatch-auto",
-                    "implement a parser",
-                    "--db",
-                    str(root / "bus.db"),
-                    "--cwd",
-                    str(root),
-                    "--agents",
-                    str(agents_path),
-                    "--routes",
-                    str(routes_path),
-                ])
-            self.assertEqual(code, 0)
-            self.assertIn('"target_agent": "qwen_cli"', output.getvalue())
-
-    def test_orchestrate_uses_capability_routes_and_agents(self):
-        with tempfile.TemporaryDirectory(dir=str(Path.home())) as tmp:
-            root = Path(tmp)
-            agents_path = root / "agents.json"
-            routes_path = root / "routes.json"
-            agents_path.write_text(json.dumps({
-                "agents": {
-                    "qwen_cli": {
-                        "mode": "mock",
-                        "capabilities": ["code_edit"],
-                    },
-                    "gemini_cli": {
-                        "mode": "mock",
-                        "capabilities": ["code_review"],
-                    },
-                }
-            }), encoding="utf-8")
-            routes_path.write_text(json.dumps({
-                "routes": {
-                    "implementation": {
-                        "requires": ["code_edit"],
-                        "review_required": True,
-                    },
-                    "code_review": {
-                        "requires": ["code_review"],
-                    },
-                },
-                "opposites": {}
-            }), encoding="utf-8")
-            output = io.StringIO()
-            with redirect_stdout(output):
-                code = main([
-                    "orchestrate",
-                    "implement parser",
-                    "--db",
-                    str(root / "bus.db"),
-                    "--cwd",
-                    str(root),
-                    "--agents",
-                    str(agents_path),
-                    "--routes",
-                    str(routes_path),
-                ])
-            self.assertEqual(code, 0)
-            text = output.getvalue()
-            self.assertIn('"target_agent": "qwen_cli"', text)
-            self.assertIn('"target_agent": "gemini_cli"', text)
-            self.assertIn('"acceptance_status": "accepted"', text)
-
-
-if __name__ == "__main__":
-    unittest.main()

trinity_lite-0.1.2/trinity_lite/cli.py

@@ -1,175 +0,0 @@
-"""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")
-    common = argparse.ArgumentParser(add_help=False)
-    common.add_argument("--db", default=None, help="SQLite database path")
-    common.add_argument("--routes", default=None, help="routes JSON path")
-    common.add_argument("--agents", default=None, 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())