trinity-lite 0.1.1__tar.gz

trinity_lite-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yomiracle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trinity_lite-0.1.1/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: trinity-lite
+Version: 0.1.1
+Summary: A minimal public multi-agent task bus with routing, workers, and safety checks.
+Author: Yomiracle
+License: MIT License
+        
+        Copyright (c) 2026 Yomiracle
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/Yomiracle/trinity-lite
+Project-URL: Repository, https://github.com/Yomiracle/trinity-lite
+Project-URL: Issues, https://github.com/Yomiracle/trinity-lite/issues
+Keywords: ai-agent,multi-agent,agent-orchestration,codex,claude-code
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Trinity Lite
+
+[![Tests](https://github.com/Yomiracle/trinity-lite/actions/workflows/test.yml/badge.svg)](https://github.com/Yomiracle/trinity-lite/actions/workflows/test.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/Yomiracle/trinity-lite)](https://github.com/Yomiracle/trinity-lite/releases)
+
+**Local-first multi-agent workflow infrastructure for CLI-based AI agents.**
+
+Trinity Lite gives Codex, Claude Code, Hermes, Qwen, Gemini, Aider, and any CLI-based agent a shared task bus: route work, persist state in SQLite, run workers, capture results, and inspect the whole workflow from the command line.
+
+[中文 README](README_zh.md)
+
+## Why Trinity Lite
+
+AI coding agents are powerful on their own, but multi-agent work is often still coordinated by hand:
+
+| Manual workflow | Trinity Lite workflow |
+|-----------------|----------------------|
+| Copy results between tools | Dispatch tasks through a shared bus |
+| Remember task state yourself | Store task status and results in SQLite |
+| Decide handoffs manually | Route by task type or explicit agent |
+| Lose failure context | Keep errors, results, and messages queryable |
+| Demo depends on installed real agents | Mock agents run the full workflow locally |
+
+Trinity Lite turns "several AI tools on one machine" into a small, reproducible agent workflow layer.
+
+## Who It Is For
+
+| User | What Trinity Lite helps with |
+|------|------------------------------|
+| AI developers | Prototype multi-agent coding workflows without building a platform first |
+| Agent workflow builders | Test routing, task persistence, review handoffs, and worker execution |
+| Indie hackers and small teams | Coordinate local CLI agents without server infrastructure |
+| Technical creators and educators | Demonstrate real multi-agent flow with commands people can run |
+
+## 30-Second Demo
+
+```bash
+git clone https://github.com/Yomiracle/trinity-lite.git
+cd trinity-lite
+python3 -m pip install -e .
+trinity-lite doctor --scan-root .
+trinity-lite dispatch-auto "implement a hello-world function"
+trinity-lite worker codex --once
+trinity-lite tasks
+```
+
+The default agents are mock agents, so this demo works even if Codex, Claude Code, or Hermes are not installed.
+
+## How It Works
+
+```text
+                  +----------------+
+user task ------> | router         |
+                  +-------+--------+
+                          |
+                          v
+                  +-------+--------+
+                  | SQLite task bus|
+                  +-------+--------+
+                          |
+          +---------------+----------------+
+          v                                v
+   +------+-------+                 +------+-------+
+   | Codex worker |                 | review worker|
+   +------+-------+                 +------+-------+
+          |                                |
+          v                                v
+   agent adapter                    agent adapter
+          |                                |
+          +---------------+----------------+
+                          v
+                  status / result / inbox
+```
+
+Codex, Claude Code, and Hermes are default presets, not requirements. Roles are configurable:
+
+| Agent | Default Role |
+|-------|--------------|
+| `codex` | primary implementation, testing, project audit |
+| `claude_code` | secondary review and cross-check |
+| `hermes` | orchestration and acceptance |
+
+## Core Capabilities
+
+- **Routing**: resolve task types to explicit agents or agents selected by declared capabilities.
+- **Durable bus**: store tasks, status, results, errors, and messages in SQLite.
+- **Worker model**: pull queued tasks and execute mock agents or real local CLIs.
+- **Command adapters**: connect Codex, Claude Code, Hermes, Qwen, Gemini, Aider, or any CLI through JSON-array commands.
+- **Local health checks**: verify Python, SQLite, route config, agent config, publish readiness, and optional runtime hygiene.
+- **Safety boundaries**: block self-delegation, cap delegation depth, enforce allowed working directories, and scan public trees.
+
+## Technical Highlights
+
+- **Zero runtime dependencies**: standard-library Python package.
+- **SQLite-first state**: local, inspectable, transactional task storage.
+- **Shell-safe command execution**: command adapters use JSON arrays and `shell=False`.
+- **Mock-to-real upgrade path**: run the full demo before installing real agent CLIs.
+- **Capability routing**: agents can declare roles, capabilities, and priority for name-agnostic routing.
+- **CI-backed public release**: tests, compile checks, and doctor checks run in GitHub Actions.
+- **Designed for extension**: MCP server and orchestrator are planned as optional layers, not required for the core bus.
+
+## Product Positioning
+
+Trinity Lite sits between "single-agent CLI tools" and "full agent frameworks":
+
+```text
+Codex / Claude Code / custom CLI
+        |
+        v
+Trinity Lite: route -> bus -> worker -> result
+        |
+        v
+future layers: MCP server, orchestrator, tracing, dashboard
+```
+
+It does not try to replace agent frameworks. It provides a lightweight coordination layer for the AI tools developers already use.
+
+## Quick Start
+
+```bash
+git clone https://github.com/Yomiracle/trinity-lite.git
+cd trinity-lite
+python3 -m pip install -e .
+
+# Run a local health check
+trinity-lite doctor --scan-root .
+
+# Dispatch a task using the built-in route resolver
+trinity-lite dispatch-auto "implement a hello-world function"
+
+# Run one mock Codex worker cycle
+trinity-lite worker codex --once
+
+# Check recent tasks
+trinity-lite tasks
+```
+
+## Use Real Agent Commands
+
+Copy the command example and edit it for your machine:
+
+```bash
+cp examples/agents.command.example.json agents.local.json
+trinity-lite dispatch-auto "write a unit test"
+trinity-lite worker codex --once --agents agents.local.json
+```
+
+Agent commands are configured as JSON arrays and run with `shell=False`.
+
+See [docs/REAL_AGENTS.md](docs/REAL_AGENTS.md) for Codex, Claude Code, and generic CLI examples.
+
+For name-agnostic routing, copy the generic capability examples:
+
+```bash
+cp examples/agents.generic.example.json agents.local.json
+cp examples/routes.capabilities.example.json routes.local.json
+trinity-lite dispatch-auto "fix the parser bug" --agents agents.local.json --routes routes.local.json
+```
+
+## Roadmap
+
+- **v0.1.x**: harden the public local bus, docs, examples, and tests.
+- **v0.2**: add a minimal MCP server so AI clients can call Trinity Lite directly.
+- **v0.3**: add an optional orchestrator for primary work -> review -> doctor/tests -> acceptance.
+- **v1.0**: stabilize CLI, schema, and packaging.
+
+See [ROADMAP.md](ROADMAP.md).
+
+## Core Commands
+
+```bash
+trinity-lite route "review this patch" --previous-agent codex
+trinity-lite dispatch codex "implement X"
+trinity-lite dispatch-auto "audit this project"
+trinity-lite status <task_id>
+trinity-lite tasks
+trinity-lite worker codex --once
+trinity-lite send claude_code "please review task abc"
+trinity-lite inbox claude_code
+trinity-lite orchestrate "implement X"
+trinity-lite doctor --scan-root .
+```
+
+For long-running local installs that maintain a metrics log, add runtime hygiene
+checks:
+
+```bash
+trinity-lite doctor --runtime-root ~/.trinity-lite --retired-port 9797
+```
+
+## Architecture
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Project Docs
+
+- [Trinity Lite tutorial](docs/TRINITY_LITE.md)
+- [Real agent command setup](docs/REAL_AGENTS.md)
+- [Agent capabilities](docs/CAPABILITIES.md)
+- [Product positioning](docs/PRODUCT.md)
+- [Operations guide](docs/OPERATIONS.md)
+- [Security notes](docs/SECURITY.md)
+- [Roadmap](ROADMAP.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+
+## License
+
+MIT

trinity_lite-0.1.1/README.md

@@ -0,0 +1,211 @@
+# Trinity Lite
+
+[![Tests](https://github.com/Yomiracle/trinity-lite/actions/workflows/test.yml/badge.svg)](https://github.com/Yomiracle/trinity-lite/actions/workflows/test.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/Yomiracle/trinity-lite)](https://github.com/Yomiracle/trinity-lite/releases)
+
+**Local-first multi-agent workflow infrastructure for CLI-based AI agents.**
+
+Trinity Lite gives Codex, Claude Code, Hermes, Qwen, Gemini, Aider, and any CLI-based agent a shared task bus: route work, persist state in SQLite, run workers, capture results, and inspect the whole workflow from the command line.
+
+[中文 README](README_zh.md)
+
+## Why Trinity Lite
+
+AI coding agents are powerful on their own, but multi-agent work is often still coordinated by hand:
+
+| Manual workflow | Trinity Lite workflow |
+|-----------------|----------------------|
+| Copy results between tools | Dispatch tasks through a shared bus |
+| Remember task state yourself | Store task status and results in SQLite |
+| Decide handoffs manually | Route by task type or explicit agent |
+| Lose failure context | Keep errors, results, and messages queryable |
+| Demo depends on installed real agents | Mock agents run the full workflow locally |
+
+Trinity Lite turns "several AI tools on one machine" into a small, reproducible agent workflow layer.
+
+## Who It Is For
+
+| User | What Trinity Lite helps with |
+|------|------------------------------|
+| AI developers | Prototype multi-agent coding workflows without building a platform first |
+| Agent workflow builders | Test routing, task persistence, review handoffs, and worker execution |
+| Indie hackers and small teams | Coordinate local CLI agents without server infrastructure |
+| Technical creators and educators | Demonstrate real multi-agent flow with commands people can run |
+
+## 30-Second Demo
+
+```bash
+git clone https://github.com/Yomiracle/trinity-lite.git
+cd trinity-lite
+python3 -m pip install -e .
+trinity-lite doctor --scan-root .
+trinity-lite dispatch-auto "implement a hello-world function"
+trinity-lite worker codex --once
+trinity-lite tasks
+```
+
+The default agents are mock agents, so this demo works even if Codex, Claude Code, or Hermes are not installed.
+
+## How It Works
+
+```text
+                  +----------------+
+user task ------> | router         |
+                  +-------+--------+
+                          |
+                          v
+                  +-------+--------+
+                  | SQLite task bus|
+                  +-------+--------+
+                          |
+          +---------------+----------------+
+          v                                v
+   +------+-------+                 +------+-------+
+   | Codex worker |                 | review worker|
+   +------+-------+                 +------+-------+
+          |                                |
+          v                                v
+   agent adapter                    agent adapter
+          |                                |
+          +---------------+----------------+
+                          v
+                  status / result / inbox
+```
+
+Codex, Claude Code, and Hermes are default presets, not requirements. Roles are configurable:
+
+| Agent | Default Role |
+|-------|--------------|
+| `codex` | primary implementation, testing, project audit |
+| `claude_code` | secondary review and cross-check |
+| `hermes` | orchestration and acceptance |
+
+## Core Capabilities
+
+- **Routing**: resolve task types to explicit agents or agents selected by declared capabilities.
+- **Durable bus**: store tasks, status, results, errors, and messages in SQLite.
+- **Worker model**: pull queued tasks and execute mock agents or real local CLIs.
+- **Command adapters**: connect Codex, Claude Code, Hermes, Qwen, Gemini, Aider, or any CLI through JSON-array commands.
+- **Local health checks**: verify Python, SQLite, route config, agent config, publish readiness, and optional runtime hygiene.
+- **Safety boundaries**: block self-delegation, cap delegation depth, enforce allowed working directories, and scan public trees.
+
+## Technical Highlights
+
+- **Zero runtime dependencies**: standard-library Python package.
+- **SQLite-first state**: local, inspectable, transactional task storage.
+- **Shell-safe command execution**: command adapters use JSON arrays and `shell=False`.
+- **Mock-to-real upgrade path**: run the full demo before installing real agent CLIs.
+- **Capability routing**: agents can declare roles, capabilities, and priority for name-agnostic routing.
+- **CI-backed public release**: tests, compile checks, and doctor checks run in GitHub Actions.
+- **Designed for extension**: MCP server and orchestrator are planned as optional layers, not required for the core bus.
+
+## Product Positioning
+
+Trinity Lite sits between "single-agent CLI tools" and "full agent frameworks":
+
+```text
+Codex / Claude Code / custom CLI
+        |
+        v
+Trinity Lite: route -> bus -> worker -> result
+        |
+        v
+future layers: MCP server, orchestrator, tracing, dashboard
+```
+
+It does not try to replace agent frameworks. It provides a lightweight coordination layer for the AI tools developers already use.
+
+## Quick Start
+
+```bash
+git clone https://github.com/Yomiracle/trinity-lite.git
+cd trinity-lite
+python3 -m pip install -e .
+
+# Run a local health check
+trinity-lite doctor --scan-root .
+
+# Dispatch a task using the built-in route resolver
+trinity-lite dispatch-auto "implement a hello-world function"
+
+# Run one mock Codex worker cycle
+trinity-lite worker codex --once
+
+# Check recent tasks
+trinity-lite tasks
+```
+
+## Use Real Agent Commands
+
+Copy the command example and edit it for your machine:
+
+```bash
+cp examples/agents.command.example.json agents.local.json
+trinity-lite dispatch-auto "write a unit test"
+trinity-lite worker codex --once --agents agents.local.json
+```
+
+Agent commands are configured as JSON arrays and run with `shell=False`.
+
+See [docs/REAL_AGENTS.md](docs/REAL_AGENTS.md) for Codex, Claude Code, and generic CLI examples.
+
+For name-agnostic routing, copy the generic capability examples:
+
+```bash
+cp examples/agents.generic.example.json agents.local.json
+cp examples/routes.capabilities.example.json routes.local.json
+trinity-lite dispatch-auto "fix the parser bug" --agents agents.local.json --routes routes.local.json
+```
+
+## Roadmap
+
+- **v0.1.x**: harden the public local bus, docs, examples, and tests.
+- **v0.2**: add a minimal MCP server so AI clients can call Trinity Lite directly.
+- **v0.3**: add an optional orchestrator for primary work -> review -> doctor/tests -> acceptance.
+- **v1.0**: stabilize CLI, schema, and packaging.
+
+See [ROADMAP.md](ROADMAP.md).
+
+## Core Commands
+
+```bash
+trinity-lite route "review this patch" --previous-agent codex
+trinity-lite dispatch codex "implement X"
+trinity-lite dispatch-auto "audit this project"
+trinity-lite status <task_id>
+trinity-lite tasks
+trinity-lite worker codex --once
+trinity-lite send claude_code "please review task abc"
+trinity-lite inbox claude_code
+trinity-lite orchestrate "implement X"
+trinity-lite doctor --scan-root .
+```
+
+For long-running local installs that maintain a metrics log, add runtime hygiene
+checks:
+
+```bash
+trinity-lite doctor --runtime-root ~/.trinity-lite --retired-port 9797
+```
+
+## Architecture
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Project Docs
+
+- [Trinity Lite tutorial](docs/TRINITY_LITE.md)
+- [Real agent command setup](docs/REAL_AGENTS.md)
+- [Agent capabilities](docs/CAPABILITIES.md)
+- [Product positioning](docs/PRODUCT.md)
+- [Operations guide](docs/OPERATIONS.md)
+- [Security notes](docs/SECURITY.md)
+- [Roadmap](ROADMAP.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+
+## License
+
+MIT

trinity_lite-0.1.1/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trinity-lite"
+version = "0.1.1"
+description = "A minimal public multi-agent task bus with routing, workers, and safety checks."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Yomiracle" }
+]
+keywords = ["ai-agent", "multi-agent", "agent-orchestration", "codex", "claude-code"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = []
+
+[project.scripts]
+trinity-lite = "trinity_lite.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Yomiracle/trinity-lite"
+Repository = "https://github.com/Yomiracle/trinity-lite"
+Issues = "https://github.com/Yomiracle/trinity-lite/issues"
+
+[tool.setuptools]
+packages = ["trinity_lite"]

trinity_lite-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

trinity_lite-0.1.1/tests/test_bus.py

@@ -0,0 +1,74 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from trinity_lite.bus import TrinityBus
+from trinity_lite.guard import GuardError
+
+
+class BusTest(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.root = Path(self.temp.name)
+        self.db = self.root / "bus.db"
+        self.bus = TrinityBus(self.db, allowed_roots=[self.root])
+
+    def tearDown(self):
+        self.temp.cleanup()
+
+    def test_task_round_trip(self):
+        task = self.bus.submit_task("user", "codex", "build it", "implementation", cwd=self.root)
+        self.assertEqual(task["status"], "queued")
+        claimed = self.bus.task_for_worker("codex")
+        self.assertEqual(claimed["id"], task["id"])
+        self.assertEqual(claimed["status"], "running")
+        done = self.bus.finish_worker(task["id"], result="ok")
+        self.assertEqual(done["status"], "completed")
+        self.assertEqual(done["result"], "ok")
+
+    def test_rejects_self_delegation_depth_and_cwd_escape(self):
+        with self.assertRaises(GuardError):
+            self.bus.submit_task("codex", "codex", "loop", cwd=self.root)
+        with self.assertRaises(GuardError):
+            self.bus.submit_task("user", "codex", "too deep", cwd=self.root, depth=3)
+        with self.assertRaises(GuardError):
+            self.bus.submit_task("user", "codex", "escape", cwd="/")
+
+    def test_connection_context_rolls_back_on_exception(self):
+        with self.assertRaises(RuntimeError):
+            with self.bus.connect() as conn:
+                conn.execute(
+                    """
+                    INSERT INTO tasks (
+                        id, source_agent, target_agent, prompt, cwd,
+                        status, depth, created_at, heartbeat_at
+                    )
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        "rollback-test",
+                        "user",
+                        "codex",
+                        "work",
+                        str(self.root),
+                        "queued",
+                        0,
+                        "2026-01-01T00:00:00+00:00",
+                        "2026-01-01T00:00:00+00:00",
+                    ),
+                )
+                raise RuntimeError("force rollback")
+        with self.assertRaises(KeyError):
+            self.bus.get_task("rollback-test")
+
+    def test_message_round_trip(self):
+        msg = self.bus.send_message("codex", "claude_code", "please review")
+        self.assertEqual(msg["read"], 0)
+        inbox = self.bus.inbox("claude_code", mark_read=True)
+        self.assertEqual(len(inbox), 1)
+        self.assertEqual(inbox[0]["message"], "please review")
+        self.assertEqual(self.bus.inbox("claude_code"), [])
+
+
+if __name__ == "__main__":
+    unittest.main()