trinity-lite 0.2.0__tar.gz → 0.2.3__tar.gz

trinity_lite-0.2.3/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: trinity-lite
+Version: 0.2.3
+Summary: The bus that lets your AI agents talk to each other.
+Author: Yomiracle
+License-Expression: MIT
+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: 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
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: agent-skill
+Requires-Dist: agent-skill-system>=1.0.6; extra == "agent-skill"
+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)
+[![PyPI](https://img.shields.io/pypi/v/trinity-lite.svg)](https://pypi.org/project/trinity-lite/)
+
+**The bus that lets your AI agents talk to each other.**
+
+[中文 README](README_zh.md)
+
+## The problem
+
+You already use Claude Code. Maybe you just installed Codex. You want them to collaborate — but there's no built-in way to route tasks between them, remember who did what, or stop them from stepping on each other. Trinity Lite is the missing layer.
+
+## What it does
+
+- **Route by capability, not name.** You describe the task. The router matches it to the right agent — no hardcoded agent names, no fragile dispatch logic. *"Implement a rate limiter" lands on the agent you tagged `implement`. "Review the auth module" goes to the agent tagged `review`.*
+- **Give every agent a pull queue.** Workers read pending tasks from the shared bus, execute them via CLI, and write results back. Each agent polls on its own schedule. You never copy-paste an output between terminals again.
+- **Remember every decision.** Every task, status change, result, error, and inter-agent message lands in a local SQLite database. Query who did what, when, and what happened — without setting up a logging pipeline.
+- **Block footguns before they fire.** Self-delegation loops are rejected. Delegation depth has a hard cap. Working directories must be in the allowlist. You ship features, not incident reports.
+
+## Quick start
+
+30 seconds, no agents required:
+
+```bash
+pip install trinity-lite
+trinity-lite doctor
+trinity-lite dispatch-auto "implement a hello-world function"
+trinity-lite worker codex --once
+trinity-lite tasks
+```
+
+Mock agents are built in. You see the full dispatch → execute → result cycle before you wire up anything real.
+
+## Not another framework
+
+Trinity Lite doesn't build agents. It connects the agents you already have.
+
+LangGraph and CrewAI give you primitives for building agents from scratch — graph definitions, role abstractions, tool wrappers. Trinity Lite starts from the opposite end: Claude Code is running in one terminal, Codex is running in another, and they need a shared task bus, durable state, and safety boundaries. No SDK to learn. No new agent abstraction. Just a bus that works with the CLIs you already use.
+
+## Who this is for
+
+| You are... | Trinity Lite helps you... |
+|------------|---------------------------|
+| Copy-pasting prompts and outputs between two agent terminals all day | Dispatch once to the bus and let agents pull their own work |
+| Prototyping a multi-agent pipeline before committing infrastructure | Run the full flow with mock agents — no API keys, no provisioning |
+| Running everything on a single machine with zero server setup | Keep your state in SQLite, your runtime in stdlib, your daemon count at zero |
+| Showing a colleague how multi-agent collaboration works | `pip install` → five commands → they see it run. No explanation needed. |
+
+## Features
+
+- **Route by capability.** Tag agents with `implement`, `review`, `audit` — the router matches tasks to the agent that can do them. No agent names in your dispatch logic.
+- **Dispatch directly when you need control.** Bypass the router and send a task straight to `claude_code` or `codex`. Best of both worlds.
+- **Persist everything in SQLite.** Tasks, statuses, results, errors, and messages in one local file. Query it with `sqlite3` or any tool that speaks SQL.
+- **Run CLI workers on demand.** `trinity-lite worker codex --once` pulls one queued task, executes the agent's command, and writes the result. Run it in a loop, in cron, or by hand.
+- **Execute safely, no shell injection.** Agent commands are JSON arrays run with `shell=False`. No string interpolation into a shell. No surprises.
+- **Test with mock agents.** Mock agents simulate the full cycle without real CLIs. Prototype routing, persistence, and review handoffs first. Wire up real agents later.
+- **Guard against runaway delegation.** Self-delegation is blocked. Delegation depth is capped. Working directories are allowlisted. Safe by default.
+- **Check health in one pass.** `trinity-lite doctor` verifies Python, SQLite, route config, agent config, and publish readiness.
+- **Zero dependencies.** Runtime is Python standard library only. Nothing to install but Python 3.10+.
+- **109 tests guarding the surface area.** Mock workflows, safety checks, routing, persistence — all covered.
+
+## Install
+
+```bash
+pip install trinity-lite
+```
+
+Python 3.10+. Zero runtime dependencies. Standard library only.
+
+### Optional extras
+
+```bash
+pip install trinity-lite[mcp]           # MCP server — 10 tools + 3 resources
+pip install trinity-lite[agent-skill]   # agent-skill-system integration
+```
+
+## Workflow example
+
+Hermes routes → Codex implements → Claude Code reviews. Five commands, one audit trail.
+
+```bash
+# Hermes sends the task. The router picks Codex automatically.
+trinity-lite dispatch-auto "implement a rate limiter for the API" --source-agent hermes
+
+# Codex pulls the task and runs it.
+trinity-lite worker codex --once --agents agents.local.json
+
+# Claude Code reviews the result.
+trinity-lite send claude_code "please review task <task_id>" --source-agent hermes
+trinity-lite worker claude_code --once --agents agents.local.json
+
+# Read the full trail.
+trinity-lite status <task_id>
+```
+
+Works immediately with mock agents. Ready for real CLIs when you are:
+
+```bash
+cp examples/agents.command.example.json agents.local.json
+```
+
+## MCP server
+
+Turn the task bus into an MCP server. Let any MCP client dispatch, query, and route tasks.
+
+```bash
+pip install trinity-lite[mcp]
+trinity-lite mcp serve
+```
+
+**10 tools:**
+
+| Tool | What it does |
+|------|--------------|
+| `trinity_dispatch` | Dispatch a task to a specific agent |
+| `trinity_dispatch_auto` | Dispatch and let the capability router pick the agent |
+| `trinity_status` | Get the state and result of any task by ID |
+| `trinity_tasks` | List recent tasks, filterable by agent |
+| `trinity_worker` | Run one worker cycle for an agent |
+| `trinity_doctor` | Run health and diagnostic checks |
+| `trinity_inbox` | Read durable messages for an agent |
+| `trinity_send` | Send a message from one agent to another |
+| `trinity_skill_search` | Search agent-skill-system for relevant skills |
+| `trinity_skill_load` | Load the full content of a named skill |
+
+**3 resources:** `trinity://health`, `trinity://tasks/recent`, `trinity://tasks/{task_id}`
+
+## Links
+
+- [PyPI](https://pypi.org/project/trinity-lite/)
+- [Documentation](docs/)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Real agent setup](docs/REAL_AGENTS.md)
+
+## License
+
+MIT

trinity_lite-0.2.3/README.md

@@ -0,0 +1,142 @@
+# 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)
+[![PyPI](https://img.shields.io/pypi/v/trinity-lite.svg)](https://pypi.org/project/trinity-lite/)
+
+**The bus that lets your AI agents talk to each other.**
+
+[中文 README](README_zh.md)
+
+## The problem
+
+You already use Claude Code. Maybe you just installed Codex. You want them to collaborate — but there's no built-in way to route tasks between them, remember who did what, or stop them from stepping on each other. Trinity Lite is the missing layer.
+
+## What it does
+
+- **Route by capability, not name.** You describe the task. The router matches it to the right agent — no hardcoded agent names, no fragile dispatch logic. *"Implement a rate limiter" lands on the agent you tagged `implement`. "Review the auth module" goes to the agent tagged `review`.*
+- **Give every agent a pull queue.** Workers read pending tasks from the shared bus, execute them via CLI, and write results back. Each agent polls on its own schedule. You never copy-paste an output between terminals again.
+- **Remember every decision.** Every task, status change, result, error, and inter-agent message lands in a local SQLite database. Query who did what, when, and what happened — without setting up a logging pipeline.
+- **Block footguns before they fire.** Self-delegation loops are rejected. Delegation depth has a hard cap. Working directories must be in the allowlist. You ship features, not incident reports.
+
+## Quick start
+
+30 seconds, no agents required:
+
+```bash
+pip install trinity-lite
+trinity-lite doctor
+trinity-lite dispatch-auto "implement a hello-world function"
+trinity-lite worker codex --once
+trinity-lite tasks
+```
+
+Mock agents are built in. You see the full dispatch → execute → result cycle before you wire up anything real.
+
+## Not another framework
+
+Trinity Lite doesn't build agents. It connects the agents you already have.
+
+LangGraph and CrewAI give you primitives for building agents from scratch — graph definitions, role abstractions, tool wrappers. Trinity Lite starts from the opposite end: Claude Code is running in one terminal, Codex is running in another, and they need a shared task bus, durable state, and safety boundaries. No SDK to learn. No new agent abstraction. Just a bus that works with the CLIs you already use.
+
+## Who this is for
+
+| You are... | Trinity Lite helps you... |
+|------------|---------------------------|
+| Copy-pasting prompts and outputs between two agent terminals all day | Dispatch once to the bus and let agents pull their own work |
+| Prototyping a multi-agent pipeline before committing infrastructure | Run the full flow with mock agents — no API keys, no provisioning |
+| Running everything on a single machine with zero server setup | Keep your state in SQLite, your runtime in stdlib, your daemon count at zero |
+| Showing a colleague how multi-agent collaboration works | `pip install` → five commands → they see it run. No explanation needed. |
+
+## Features
+
+- **Route by capability.** Tag agents with `implement`, `review`, `audit` — the router matches tasks to the agent that can do them. No agent names in your dispatch logic.
+- **Dispatch directly when you need control.** Bypass the router and send a task straight to `claude_code` or `codex`. Best of both worlds.
+- **Persist everything in SQLite.** Tasks, statuses, results, errors, and messages in one local file. Query it with `sqlite3` or any tool that speaks SQL.
+- **Run CLI workers on demand.** `trinity-lite worker codex --once` pulls one queued task, executes the agent's command, and writes the result. Run it in a loop, in cron, or by hand.
+- **Execute safely, no shell injection.** Agent commands are JSON arrays run with `shell=False`. No string interpolation into a shell. No surprises.
+- **Test with mock agents.** Mock agents simulate the full cycle without real CLIs. Prototype routing, persistence, and review handoffs first. Wire up real agents later.
+- **Guard against runaway delegation.** Self-delegation is blocked. Delegation depth is capped. Working directories are allowlisted. Safe by default.
+- **Check health in one pass.** `trinity-lite doctor` verifies Python, SQLite, route config, agent config, and publish readiness.
+- **Zero dependencies.** Runtime is Python standard library only. Nothing to install but Python 3.10+.
+- **109 tests guarding the surface area.** Mock workflows, safety checks, routing, persistence — all covered.
+
+## Install
+
+```bash
+pip install trinity-lite
+```
+
+Python 3.10+. Zero runtime dependencies. Standard library only.
+
+### Optional extras
+
+```bash
+pip install trinity-lite[mcp]           # MCP server — 10 tools + 3 resources
+pip install trinity-lite[agent-skill]   # agent-skill-system integration
+```
+
+## Workflow example
+
+Hermes routes → Codex implements → Claude Code reviews. Five commands, one audit trail.
+
+```bash
+# Hermes sends the task. The router picks Codex automatically.
+trinity-lite dispatch-auto "implement a rate limiter for the API" --source-agent hermes
+
+# Codex pulls the task and runs it.
+trinity-lite worker codex --once --agents agents.local.json
+
+# Claude Code reviews the result.
+trinity-lite send claude_code "please review task <task_id>" --source-agent hermes
+trinity-lite worker claude_code --once --agents agents.local.json
+
+# Read the full trail.
+trinity-lite status <task_id>
+```
+
+Works immediately with mock agents. Ready for real CLIs when you are:
+
+```bash
+cp examples/agents.command.example.json agents.local.json
+```
+
+## MCP server
+
+Turn the task bus into an MCP server. Let any MCP client dispatch, query, and route tasks.
+
+```bash
+pip install trinity-lite[mcp]
+trinity-lite mcp serve
+```
+
+**10 tools:**
+
+| Tool | What it does |
+|------|--------------|
+| `trinity_dispatch` | Dispatch a task to a specific agent |
+| `trinity_dispatch_auto` | Dispatch and let the capability router pick the agent |
+| `trinity_status` | Get the state and result of any task by ID |
+| `trinity_tasks` | List recent tasks, filterable by agent |
+| `trinity_worker` | Run one worker cycle for an agent |
+| `trinity_doctor` | Run health and diagnostic checks |
+| `trinity_inbox` | Read durable messages for an agent |
+| `trinity_send` | Send a message from one agent to another |
+| `trinity_skill_search` | Search agent-skill-system for relevant skills |
+| `trinity_skill_load` | Load the full content of a named skill |
+
+**3 resources:** `trinity://health`, `trinity://tasks/recent`, `trinity://tasks/{task_id}`
+
+## Links
+
+- [PyPI](https://pypi.org/project/trinity-lite/)
+- [Documentation](docs/)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Real agent setup](docs/REAL_AGENTS.md)
+
+## License
+
+MIT

{trinity_lite-0.2.0 → trinity_lite-0.2.3}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trinity-lite"
-version = "0.2.0"
-description = "A minimal public multi-agent task bus with routing, workers, and safety checks."
+version = "0.2.3"
+description = "The bus that lets your AI agents talk to each other."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
@@ -26,6 +26,7 @@ dependencies = []
 
 [project.optional-dependencies]
 mcp = ["mcp>=1.0"]
+agent-skill = ["agent-skill-system>=1.0.6"]
 
 [project.scripts]
 trinity-lite = "trinity_lite.cli:main"

{trinity_lite-0.2.0 → trinity_lite-0.2.3}/tests/test_mcp_server.py

@@ -1,5 +1,6 @@
 import io
 import json
+import os
 import sys
 import tempfile
 import unittest
@@ -22,6 +23,19 @@ from trinity_lite.mcp_server import (
     _get_known_agents,
 )
 
+try:
+    from engine.bank import SkillBank  # noqa: F401
+
+    HAS_AGENT_SKILL = True
+except ImportError:
+    HAS_AGENT_SKILL = False
+
+# Detect agent-skill-system skills directory
+SKILLS_DIR = os.environ.get(
+    "TRINITY_SKILLS_DIR",
+    os.path.expanduser("~/agent-skill-system/skills"),
+)
+
 
 class McpServerTest(unittest.TestCase):
     def setUp(self):
@@ -54,7 +68,7 @@ class McpServerTest(unittest.TestCase):
         self.assertIn("resources", resp["result"]["capabilities"])
         self.assertIn("serverInfo", resp["result"])
         self.assertEqual(resp["result"]["serverInfo"]["name"], "trinity-lite-mcp")
-        self.assertEqual(resp["result"]["serverInfo"]["version"], "0.2.0")
+        self.assertEqual(resp["result"]["serverInfo"]["version"], "0.2.2")
 
     def test_initialized_returns_none(self):
         resp = self._call(self._msg("initialized"))
@@ -76,7 +90,7 @@ class McpServerTest(unittest.TestCase):
         resp = self._call(self._msg("tools/list", 1))
         tools = resp["result"]["tools"]
         self.assertIsInstance(tools, list)
-        self.assertEqual(len(tools), 8)
+        self.assertEqual(len(tools), 10)
         names = [t["name"] for t in tools]
         self.assertIn("trinity_dispatch", names)
         self.assertIn("trinity_dispatch_auto", names)
@@ -86,6 +100,8 @@ class McpServerTest(unittest.TestCase):
         self.assertIn("trinity_doctor", names)
         self.assertIn("trinity_inbox", names)
         self.assertIn("trinity_send", names)
+        self.assertIn("trinity_skill_search", names)
+        self.assertIn("trinity_skill_load", names)
         # Check schema structure
         for t in tools:
             self.assertIn("name", t)
@@ -117,7 +133,7 @@ class McpServerTest(unittest.TestCase):
         data = json.loads(contents[0]["text"])
         self.assertEqual(data["status"], "ok")
         self.assertEqual(data["bus"], "connected")
-        self.assertEqual(data["tools"], 8)
+        self.assertEqual(data["tools"], 10)
         self.assertEqual(data["resources"], 3)
 
     def test_resource_health_degraded(self):
@@ -451,5 +467,123 @@ class McpServerTest(unittest.TestCase):
         self.assertEqual(compact["id"], "abc123def456")
 
 
+    # ---- Skills: agent-skill-system integration ----
+
+    def test_skill_search_without_agent_skill_system(self):
+        """Graceful error when agent-skill-system not installed."""
+        import trinity_lite.mcp_server as mcp
+        from unittest.mock import patch
+
+        with patch.object(mcp, "_init_skill_engine", return_value=False):
+            params = {
+                "name": "trinity_skill_search",
+                "arguments": {"query": "parse a contract"},
+            }
+            resp = self._call(self._msg("tools/call", 1, params))
+            self.assertIn("result", resp)
+            self.assertIn("error", resp["result"])
+            self.assertEqual(resp["result"]["error"], "agent-skill-system not installed")
+            self.assertIn("hint", resp["result"])
+
+    @unittest.skipUnless(HAS_AGENT_SKILL and Path(SKILLS_DIR).exists(),
+                         "agent-skill-system not installed or skills dir not found")
+    def test_skill_search_returns_matching_skills(self):
+        """Search returns matching skills when engine is available."""
+        import trinity_lite.mcp_server as mcp
+
+        old_available = mcp._SKILL_ENGINE_AVAILABLE
+        old_bank = mcp._SKILL_BANK
+        old_bank_dir = mcp._SKILL_BANK_DIR
+        try:
+            from engine.bank import SkillBank
+            mcp._SKILL_ENGINE_AVAILABLE = True
+            mcp._SKILL_BANK_DIR = SKILLS_DIR
+            mcp._SKILL_BANK = SkillBank(mcp._SKILL_BANK_DIR)
+            mcp._SKILL_BANK.scan_directory()
+
+            params = {
+                "name": "trinity_skill_search",
+                "arguments": {"query": "generate a weekly report", "limit": 3},
+            }
+            resp = self._call(self._msg("tools/call", 1, params))
+            self.assertIn("result", resp)
+            self.assertIn("skills", resp["result"])
+            skills = resp["result"]["skills"]
+            self.assertIsInstance(skills, list)
+            if skills:
+                self.assertIn("name", skills[0])
+                self.assertIn("description", skills[0])
+                self.assertIn("score", skills[0])
+        finally:
+            mcp._SKILL_ENGINE_AVAILABLE = old_available
+            mcp._SKILL_BANK = old_bank
+            mcp._SKILL_BANK_DIR = old_bank_dir
+
+    @unittest.skipUnless(HAS_AGENT_SKILL and Path(SKILLS_DIR).exists(),
+                         "agent-skill-system not installed or skills dir not found")
+    def test_skill_load_returns_content(self):
+        """Load a skill's full content."""
+        import trinity_lite.mcp_server as mcp
+
+        old_available = mcp._SKILL_ENGINE_AVAILABLE
+        old_bank = mcp._SKILL_BANK
+        old_bank_dir = mcp._SKILL_BANK_DIR
+        try:
+            from engine.bank import SkillBank
+            mcp._SKILL_ENGINE_AVAILABLE = True
+            mcp._SKILL_BANK_DIR = SKILLS_DIR
+            mcp._SKILL_BANK = SkillBank(mcp._SKILL_BANK_DIR)
+            mcp._SKILL_BANK.scan_directory()
+
+            # Pick an active skill from the bank
+            active = mcp._SKILL_BANK.list_active()
+            if active:
+                skill_name = active[0].name
+                params = {
+                    "name": "trinity_skill_load",
+                    "arguments": {"skill_name": skill_name},
+                }
+                resp = self._call(self._msg("tools/call", 1, params))
+                self.assertIn("result", resp)
+                result = resp["result"]
+                self.assertIn("name", result)
+                self.assertIn("skill_md", result)
+                self.assertIn("system_prompt", result)
+        finally:
+            mcp._SKILL_ENGINE_AVAILABLE = old_available
+            mcp._SKILL_BANK = old_bank
+            mcp._SKILL_BANK_DIR = old_bank_dir
+
+    @unittest.skipUnless(HAS_AGENT_SKILL and Path(SKILLS_DIR).exists(),
+                         "agent-skill-system not installed or skills dir not found")
+    def test_skill_load_not_found(self):
+        """Graceful error when skill name is not in the bank."""
+        import trinity_lite.mcp_server as mcp
+
+        old_available = mcp._SKILL_ENGINE_AVAILABLE
+        old_bank = mcp._SKILL_BANK
+        old_bank_dir = mcp._SKILL_BANK_DIR
+        try:
+            from engine.bank import SkillBank
+            mcp._SKILL_ENGINE_AVAILABLE = True
+            mcp._SKILL_BANK_DIR = SKILLS_DIR
+            mcp._SKILL_BANK = SkillBank(mcp._SKILL_BANK_DIR)
+            mcp._SKILL_BANK.scan_directory()
+
+            params = {
+                "name": "trinity_skill_load",
+                "arguments": {"skill_name": "nonexistent-skill-xyz"},
+            }
+            resp = self._call(self._msg("tools/call", 1, params))
+            self.assertIn("result", resp)
+            self.assertIn("error", resp["result"])
+            self.assertIn("skill not found", resp["result"]["error"])
+            self.assertIn("available_skills", resp["result"])
+        finally:
+            mcp._SKILL_ENGINE_AVAILABLE = old_available
+            mcp._SKILL_BANK = old_bank
+            mcp._SKILL_BANK_DIR = old_bank_dir
+
+
 if __name__ == "__main__":
     unittest.main()

{trinity_lite-0.2.0 → trinity_lite-0.2.3}/trinity_lite/__init__.py

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