trinity-lite 0.7.0__tar.gz → 0.7.2__tar.gz

{trinity_lite-0.7.0 → trinity_lite-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trinity-lite
-Version: 0.7.0
+Version: 0.7.2
 Summary: Local AgentOps for cross-vendor CLI agents: route work, recover state, and accept only with evidence.
 Author: Yomiracle
 License-Expression: MIT
@@ -99,7 +99,7 @@ LangGraph and CrewAI give you primitives for building agents from scratch — gr
 - **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.
+- **Check health in one pass.** `trinity-lite doctor` verifies Python, SQLite, route config, agent config, and publish readiness. `trinity-lite doctor --onboarding` grades every check as blocker or optional, probes for agent CLIs, and fails only on blockers.
 - **Zero core dependencies.** The default runtime is Python standard library only. YAML pipelines are available through an optional extra.
 - **150+ tests guarding the surface area.** Mock workflows, safety checks, routing, persistence, MCP, and acceptance gates — all covered.
 - **Optional model selection hints.** Select from your declared model pool with transparent task, tier, and capability rules; no claim of a universal best or cheapest model.
@@ -130,13 +130,15 @@ trinity-lite orchestrate "implement a rate limiter for the API"
 
 The primary task row records `route_json`, `review_task_id`, `verification_json`, `acceptance_status`, `acceptance_reason`, and `accepted_at`.
 
-Ready for real CLIs when you are:
+Ready for real CLIs when you are — auto-detect what is installed and generate a safe starter config:
 
 ```bash
-cp examples/agents.command.example.json agents.local.json
+trinity-lite init
 trinity-lite orchestrate "implement a rate limiter for the API" --agents agents.local.json
 ```
 
+`trinity-lite init` probes PATH for Codex, Claude Code, and Hermes, writes `agents.local.json` with JSON-array commands for the CLIs it finds, keeps the rest in mock mode, and never writes credentials or overwrites an existing config without `--force`. Prefer hand-editing? `cp examples/agents.command.example.json agents.local.json` still works.
+
 Prefer manual control? Use the lower-level bus commands:
 
 ```bash

{trinity_lite-0.7.0 → trinity_lite-0.7.2}/README.md

@@ -69,7 +69,7 @@ LangGraph and CrewAI give you primitives for building agents from scratch — gr
 - **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.
+- **Check health in one pass.** `trinity-lite doctor` verifies Python, SQLite, route config, agent config, and publish readiness. `trinity-lite doctor --onboarding` grades every check as blocker or optional, probes for agent CLIs, and fails only on blockers.
 - **Zero core dependencies.** The default runtime is Python standard library only. YAML pipelines are available through an optional extra.
 - **150+ tests guarding the surface area.** Mock workflows, safety checks, routing, persistence, MCP, and acceptance gates — all covered.
 - **Optional model selection hints.** Select from your declared model pool with transparent task, tier, and capability rules; no claim of a universal best or cheapest model.
@@ -100,13 +100,15 @@ trinity-lite orchestrate "implement a rate limiter for the API"
 
 The primary task row records `route_json`, `review_task_id`, `verification_json`, `acceptance_status`, `acceptance_reason`, and `accepted_at`.
 
-Ready for real CLIs when you are:
+Ready for real CLIs when you are — auto-detect what is installed and generate a safe starter config:
 
 ```bash
-cp examples/agents.command.example.json agents.local.json
+trinity-lite init
 trinity-lite orchestrate "implement a rate limiter for the API" --agents agents.local.json
 ```
 
+`trinity-lite init` probes PATH for Codex, Claude Code, and Hermes, writes `agents.local.json` with JSON-array commands for the CLIs it finds, keeps the rest in mock mode, and never writes credentials or overwrites an existing config without `--force`. Prefer hand-editing? `cp examples/agents.command.example.json agents.local.json` still works.
+
 Prefer manual control? Use the lower-level bus commands:
 
 ```bash

{trinity_lite-0.7.0 → trinity_lite-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trinity-lite"
-version = "0.7.0"
+version = "0.7.2"
 description = "Local AgentOps for cross-vendor CLI agents: route work, recover state, and accept only with evidence."
 readme = "README.md"
 requires-python = ">=3.10"

trinity_lite-0.7.2/tests/test_init.py

@@ -0,0 +1,238 @@
+import io
+import json
+import os
+import stat
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+from trinity_lite.cli import main
+from trinity_lite.doctor import run_doctor
+from trinity_lite.init import (
+    AGENT_CLI_PRESETS,
+    build_starter_config,
+    detect_agent_clis,
+    run_init,
+)
+
+
+def _fake_path(dir_path: Path, names: list[str]) -> str:
+    """Create executable stubs for the given CLI names in dir_path."""
+    for name in names:
+        stub = dir_path / name
+        stub.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+        stub.chmod(stub.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return str(dir_path)
+
+
+class DetectAgentClisTest(unittest.TestCase):
+    def test_detects_present_clis(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = _fake_path(Path(tmp), ["codex", "claude"])
+            with mock.patch.dict(os.environ, {"PATH": path}):
+                detected = detect_agent_clis()
+            self.assertTrue(detected["codex"].endswith("codex"))
+            self.assertTrue(detected["claude_code"].endswith("claude"))
+            self.assertIsNone(detected["hermes"])
+
+    def test_detects_nothing_on_empty_path(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch.dict(os.environ, {"PATH": str(Path(tmp))}):
+                detected = detect_agent_clis()
+            self.assertTrue(all(exe is None for exe in detected.values()))
+            self.assertEqual(set(detected), set(AGENT_CLI_PRESETS))
+
+
+class BuildStarterConfigTest(unittest.TestCase):
+    def test_detected_agents_use_command_mode(self):
+        config = build_starter_config({"codex": "/usr/bin/codex", "claude_code": None, "hermes": None})
+        agents = config["agents"]
+        self.assertEqual(agents["codex"]["mode"], "command")
+        self.assertEqual(agents["codex"]["command"], ["codex", "exec", "-C", "{cwd}", "{prompt}"])
+        self.assertEqual(agents["claude_code"]["mode"], "mock")
+        self.assertEqual(agents["hermes"]["mode"], "mock")
+
+    def test_commands_are_json_arrays_without_credentials(self):
+        config = build_starter_config({agent: f"/usr/bin/{agent}" for agent in AGENT_CLI_PRESETS})
+        text = json.dumps(config).lower()
+        for spec in config["agents"].values():
+            self.assertIsInstance(spec["command"], list)
+            self.assertTrue(all(isinstance(part, str) for part in spec["command"]))
+        for forbidden in ("api_key", "apikey", "token", "secret", "password"):
+            self.assertNotIn(forbidden, text)
+
+
+class RunInitTest(unittest.TestCase):
+    def test_writes_starter_config_with_detected_clis(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "bin").mkdir()
+            path = _fake_path(root / "bin", ["codex"])
+            out = root / "agents.local.json"
+            with mock.patch.dict(os.environ, {"PATH": path}):
+                result = run_init(out_path=str(out))
+            self.assertTrue(result["written"])
+            self.assertFalse(result["skipped"])
+            self.assertFalse(result["mock_only"])
+            self.assertEqual([d["agent"] for d in result["detected"]], ["codex"])
+            self.assertEqual(result["missing"], ["claude_code", "hermes"])
+            config = json.loads(out.read_text(encoding="utf-8"))
+            self.assertEqual(config["agents"]["codex"]["mode"], "command")
+            self.assertEqual(config["agents"]["claude_code"]["mode"], "mock")
+
+    def test_mock_only_config_when_no_cli_found(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            out = root / "agents.local.json"
+            with mock.patch.dict(os.environ, {"PATH": str(root)}):
+                result = run_init(out_path=str(out))
+            self.assertTrue(result["written"])
+            self.assertTrue(result["mock_only"])
+            self.assertEqual(result["detected"], [])
+            config = json.loads(out.read_text(encoding="utf-8"))
+            self.assertTrue(all(s["mode"] == "mock" for s in config["agents"].values()))
+
+    def test_never_overwrites_existing_config_without_force(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            out = Path(tmp) / "agents.local.json"
+            out.write_text('{"agents": {"custom": {"mode": "mock"}}}\n', encoding="utf-8")
+            with mock.patch.dict(os.environ, {"PATH": str(Path(tmp))}):
+                result = run_init(out_path=str(out))
+            self.assertFalse(result["written"])
+            self.assertTrue(result["skipped"])
+            self.assertIn("exists", result["reason"])
+            self.assertIn("custom", out.read_text(encoding="utf-8"))
+
+    def test_force_overwrites_existing_config(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            out = Path(tmp) / "agents.local.json"
+            out.write_text('{"agents": {"custom": {"mode": "mock"}}}\n', encoding="utf-8")
+            with mock.patch.dict(os.environ, {"PATH": str(Path(tmp))}):
+                result = run_init(out_path=str(out), force=True)
+            self.assertTrue(result["written"])
+            self.assertTrue(result["forced"])
+            config = json.loads(out.read_text(encoding="utf-8"))
+            self.assertNotIn("custom", config["agents"])
+
+
+class InitCliTest(unittest.TestCase):
+    def test_cli_init_writes_config_and_prints_json(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            out = Path(tmp) / "agents.local.json"
+            output = io.StringIO()
+            with mock.patch.dict(os.environ, {"PATH": str(Path(tmp))}):
+                with redirect_stdout(output):
+                    code = main(["init", "--out", str(out)])
+            self.assertEqual(code, 0)
+            result = json.loads(output.getvalue())
+            self.assertTrue(result["written"])
+            self.assertTrue(out.exists())
+
+    def test_cli_init_skips_existing_without_force(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            out = Path(tmp) / "agents.local.json"
+            out.write_text("{}", encoding="utf-8")
+            output = io.StringIO()
+            with redirect_stdout(output):
+                code = main(["init", "--out", str(out)])
+            self.assertEqual(code, 0)
+            result = json.loads(output.getvalue())
+            self.assertTrue(result["skipped"])
+            self.assertEqual(out.read_text(encoding="utf-8"), "{}")
+
+
+class OnboardingDoctorTest(unittest.TestCase):
+    def test_run_doctor_marks_levels_on_all_checks(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            report = run_doctor(db_path=str(Path(tmp) / "bus.db"))
+            self.assertTrue(report["checks"])
+            for check in report["checks"]:
+                self.assertIn(check["level"], ("blocker", "optional"))
+            self.assertEqual(report["blockers_failed"], [])
+            self.assertEqual(report["optional_failed"], [])
+
+    def test_onboarding_adds_agent_cli_check_as_optional(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch.dict(os.environ, {"PATH": str(Path(tmp))}):
+                report = run_doctor(db_path=str(Path(tmp) / "bus.db"), onboarding=True)
+            cli_check = next(c for c in report["checks"] if c["name"] == "agent_clis")
+            self.assertEqual(cli_check["level"], "optional")
+            self.assertFalse(cli_check["ok"])
+            self.assertIn("hint", cli_check)
+            # Optional failure alone does not make onboarding unhealthy.
+            self.assertEqual(report["status"], "healthy")
+            self.assertEqual(report["blockers_failed"], [])
+            self.assertEqual(report["optional_failed"], ["agent_clis"])
+
+    def test_onboarding_unhealthy_only_on_blocker_failure(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            agents_path = root / "agents.json"
+            agents_path.write_text(json.dumps({"agents": {"bad": {"mode": "nope"}}}), encoding="utf-8")
+            with mock.patch.dict(os.environ, {"PATH": str(root)}):
+                report = run_doctor(
+                    db_path=str(root / "bus.db"),
+                    agents_path=str(agents_path),
+                    onboarding=True,
+                )
+            self.assertEqual(report["status"], "unhealthy")
+            self.assertIn("agents", report["blockers_failed"])
+            self.assertIn("agent_clis", report["optional_failed"])
+
+    def test_default_doctor_status_unchanged_by_optional_failures(self):
+        # Default (non-onboarding) mode keeps the old semantics: any failed
+        # check makes the report unhealthy.
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            runtime = root / "runtime"
+            runtime.mkdir()
+            report = run_doctor(db_path=str(root / "bus.db"), runtime_root=str(runtime))
+            self.assertEqual(report["status"], "unhealthy")
+            self.assertIn("runtime_metrics", report["optional_failed"])
+
+    def test_cli_doctor_onboarding_exit_codes(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            # Healthy blockers + missing CLIs (optional) -> exit 0.
+            output = io.StringIO()
+            with mock.patch.dict(os.environ, {"PATH": str(root)}):
+                with redirect_stdout(output):
+                    code = main(["doctor", "--onboarding", "--db", str(root / "bus.db")])
+            self.assertEqual(code, 0)
+            report = json.loads(output.getvalue())
+            self.assertEqual(report["status"], "healthy")
+
+            # Blocker failure -> exit 1.
+            bad_agents = root / "agents.json"
+            bad_agents.write_text(json.dumps({"agents": {"bad": {"mode": "nope"}}}), encoding="utf-8")
+            output = io.StringIO()
+            with mock.patch.dict(os.environ, {"PATH": str(root)}):
+                with redirect_stdout(output):
+                    code = main([
+                        "doctor", "--onboarding",
+                        "--db", str(root / "bus.db"),
+                        "--agents", str(bad_agents),
+                    ])
+            self.assertEqual(code, 1)
+            report = json.loads(output.getvalue())
+            self.assertIn("agents", report["blockers_failed"])
+
+    def test_cli_doctor_default_still_exits_zero_on_failure(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            bad_agents = root / "agents.json"
+            bad_agents.write_text(json.dumps({"agents": {"bad": {"mode": "nope"}}}), encoding="utf-8")
+            output = io.StringIO()
+            with redirect_stdout(output):
+                code = main([
+                    "doctor",
+                    "--db", str(root / "bus.db"),
+                    "--agents", str(bad_agents),
+                ])
+            self.assertEqual(code, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

{trinity_lite-0.7.0 → trinity_lite-0.7.2}/tests/test_mcp_server.py

@@ -75,6 +75,19 @@ class McpServerTest(unittest.TestCase):
         resp = self._call(self._msg("initialized"))
         self.assertIsNone(resp)
 
+    def test_notifications_initialized_returns_none(self):
+        # Real MCP clients send `notifications/initialized` (no id) after
+        # initialize. Must return None and never emit an id:null error.
+        resp = self._call({"jsonrpc": "2.0", "method": "notifications/initialized"})
+        self.assertIsNone(resp)
+
+    def test_unknown_notification_returns_none(self):
+        # Any notification (no id) must not receive a response, even if the
+        # method is unknown. Regression for id:null error responses that
+        # crashed the official mcp SDK >= 2.x stdio transport.
+        resp = self._call({"jsonrpc": "2.0", "method": "notifications/whatever"})
+        self.assertIsNone(resp)
+
     def test_shutdown_returns_empty_result(self):
         resp = self._call(self._msg("shutdown", 1, {}))
         self.assertEqual(resp["id"], 1)

{trinity_lite-0.7.0 → trinity_lite-0.7.2}/trinity_lite/__init__.py

@@ -1,3 +1,3 @@
 """Trinity Lite: local AgentOps for cross-vendor CLI agents."""
 
-__version__ = "0.7.0"
+__version__ = "0.7.2"

{trinity_lite-0.7.0 → trinity_lite-0.7.2}/trinity_lite/cli.py

@@ -53,7 +53,7 @@ Trinity Lite — multi-agent task bus
 Quick demo:  trinity-lite demo
 Full help:   trinity-lite --help
 
-Commands: demo, dispatch, dispatch-auto, worker, orchestrate, worktree,
+Commands: demo, init, dispatch, dispatch-auto, worker, orchestrate, worktree,
           status, latest, tasks, route, proof, doctor, send, inbox, mcp,
           setup-models, detect-models"""
 
@@ -173,6 +173,28 @@ def build_parser() -> argparse.ArgumentParser:
         default=[],
         help="TCP port that should not be listening, repeatable",
     )
+    doctor.add_argument(
+        "--onboarding",
+        action="store_true",
+        help="onboarding mode: also probe agent CLIs, grade checks as blocker/optional, "
+             "and exit non-zero only when a blocker fails",
+    )
+
+    init_cmd = sub.add_parser(
+        "init",
+        parents=[common],
+        help="detect local agent CLIs and write a safe starter agents config",
+    )
+    init_cmd.add_argument(
+        "--out",
+        default=None,
+        help="output path (default: ./agents.local.json)",
+    )
+    init_cmd.add_argument(
+        "--force",
+        action="store_true",
+        help="overwrite an existing config file",
+    )
 
     version_cmd = sub.add_parser("version", parents=[common], help="show version and exit")
 
@@ -228,7 +250,12 @@ def run_command(args: argparse.Namespace) -> int:
     if args.command == "worktree":
         return _worktree(args)
 
-    # Model pool commands do not use the task bus.
+    # Init and model pool commands do not use the task bus.
+    if args.command == "init":
+        from .init import run_init
+
+        print_json(run_init(out_path=args.out, force=args.force))
+        return 0
     if args.command == "setup-models":
         from .model_pool_wizard import main as wizard_main
         wizard_main()
@@ -342,14 +369,18 @@ def run_command(args: argparse.Namespace) -> int:
         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(
+        report = run_doctor(
             args.db,
             args.routes,
             args.agents,
             args.scan_root,
             args.runtime_root,
             args.retired_port,
-        ))
+            onboarding=getattr(args, "onboarding", False),
+        )
+        print_json(report)
+        if getattr(args, "onboarding", False):
+            return 1 if report["blockers_failed"] else 0
         return 0
     if args.command == "demo":
         return _demo(args, bus)

{trinity_lite-0.7.0 → trinity_lite-0.7.2}/trinity_lite/doctor.py

@@ -24,6 +24,33 @@ RETIRED_RUNTIME_ARTIFACTS = {
     "trinity_learn.db-shm",
 }
 
+# Checks that never block a first run. Everything else is a blocker:
+# without it the bus, routes, or agent config cannot work at all.
+OPTIONAL_CHECKS = {
+    "public_tree_scan",
+    "runtime_root",
+    "runtime_metrics",
+    "retired_runtime_artifacts",
+    "retired_port",
+    "agent_clis",
+}
+
+# Hints attached to failed optional checks so onboarding users know the
+# failure does not block the mock-agent path.
+OPTIONAL_HINTS = {
+    "agent_clis": "no supported agent CLI on PATH; mock agents still work, or run `trinity-lite init` after installing one",
+    "public_tree_scan": "resolve before publishing this tree",
+    "runtime_root": "runtime state directory is not ready yet",
+    "runtime_metrics": "start the runtime once to generate metrics",
+    "retired_runtime_artifacts": "remove retired artifacts from the runtime directory",
+    "retired_port": "stop the listener on the retired port",
+}
+
+
+def _check_level(name: str) -> str:
+    base = name.split(":", 1)[0]
+    return "optional" if base in OPTIONAL_CHECKS else "blocker"
+
 
 def run_doctor(
     db_path: str | None = None,
@@ -32,6 +59,7 @@ def run_doctor(
     scan_root: str | None = None,
     runtime_root: str | None = None,
     retired_ports: list[int] | None = None,
+    onboarding: bool = False,
 ) -> dict[str, Any]:
     checks: list[dict[str, Any]] = []
 
@@ -99,12 +127,54 @@ def run_doctor(
     for port in retired_ports or []:
         checks.append(_retired_port_check(port))
 
+    if onboarding:
+        checks.append(_agent_cli_check())
+
+    for check in checks:
+        check["level"] = _check_level(check["name"])
+        if not check["ok"] and check["level"] == "optional":
+            hint = OPTIONAL_HINTS.get(check["name"].split(":", 1)[0])
+            if hint:
+                check["hint"] = hint
+
+    blockers_failed = [
+        c["name"] for c in checks if not c["ok"] and c["level"] == "blocker"
+    ]
+    optional_failed = [
+        c["name"] for c in checks if not c["ok"] and c["level"] == "optional"
+    ]
+
+    if onboarding:
+        status = "healthy" if not blockers_failed else "unhealthy"
+    else:
+        status = "healthy" if all(c["ok"] for c in checks) else "unhealthy"
+
     return {
-        "status": "healthy" if all(c["ok"] for c in checks) else "unhealthy",
+        "status": status,
+        "onboarding": bool(onboarding),
+        "blockers_failed": blockers_failed,
+        "optional_failed": optional_failed,
         "checks": checks,
     }
 
 
+def _agent_cli_check() -> dict[str, Any]:
+    """Probe PATH for supported agent CLIs (always optional)."""
+    from .init import detect_agent_clis
+
+    detected = detect_agent_clis()
+    found = sorted(agent for agent, exe in detected.items() if exe)
+    missing = sorted(agent for agent, exe in detected.items() if not exe)
+    return {
+        "name": "agent_clis",
+        "ok": bool(found),
+        "detail": {
+            "found": {agent: detected[agent] for agent in found},
+            "missing": missing,
+        },
+    }
+
+
 def _bus_acceptance_checks(bus: TrinityBus) -> list[dict[str, Any]]:
     with bus.connect() as conn:
         columns = {

trinity_lite-0.7.2/trinity_lite/init.py

@@ -0,0 +1,116 @@
+"""Detect local agent CLIs and generate a safe starter agents config.
+
+This module supports the five-minute onboarding path: probe PATH for
+supported agent CLIs, then write an ``agents.local.json`` that runs
+detected CLIs in command mode and keeps everything else on mock agents.
+
+Safety rules:
+
+- Commands are JSON arrays only; Trinity Lite executes them with
+  ``shell=False``.
+- No credentials, API keys, tokens, or private paths are ever written.
+- An existing config is never overwritten unless ``force=True``.
+- When no supported CLI is found, the generated config is mock-only and
+  still fully usable.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+# Supported agent CLI presets. Each entry maps the Trinity Lite agent id to
+# the executable probed on PATH and the safe command template aligned with
+# docs/REAL_AGENTS.md and examples/agents.command.example.json.
+AGENT_CLI_PRESETS: dict[str, dict[str, Any]] = {
+    "codex": {
+        "executable": "codex",
+        "command": ["codex", "exec", "-C", "{cwd}", "{prompt}"],
+    },
+    "claude_code": {
+        "executable": "claude",
+        "command": ["claude", "-p", "{prompt}"],
+    },
+    "hermes": {
+        "executable": "hermes",
+        "command": ["hermes", "-z", "{prompt}"],
+    },
+}
+
+DEFAULT_TIMEOUT = 1800
+DEFAULT_CONFIG_NAME = "agents.local.json"
+
+
+def detect_agent_clis() -> dict[str, str | None]:
+    """Probe PATH for supported agent CLI executables.
+
+    Returns a mapping of agent id to the resolved executable path, or None
+    when the executable is not on PATH.
+    """
+    found: dict[str, str | None] = {}
+    for agent_id, preset in AGENT_CLI_PRESETS.items():
+        found[agent_id] = shutil.which(preset["executable"])
+    return found
+
+
+def build_starter_config(detected: dict[str, str | None]) -> dict[str, Any]:
+    """Build an agents config from detection results.
+
+    Detected CLIs become command-mode agents with safe JSON-array commands;
+    undetected presets stay in mock mode so the bus works out of the box.
+    """
+    agents: dict[str, Any] = {}
+    for agent_id, preset in AGENT_CLI_PRESETS.items():
+        if detected.get(agent_id):
+            agents[agent_id] = {
+                "mode": "command",
+                "command": list(preset["command"]),
+                "timeout": DEFAULT_TIMEOUT,
+            }
+        else:
+            agents[agent_id] = {
+                "mode": "mock",
+                "timeout": DEFAULT_TIMEOUT,
+            }
+    return {"agents": agents}
+
+
+def run_init(out_path: str | None = None, force: bool = False) -> dict[str, Any]:
+    """Detect agent CLIs and write a starter config.
+
+    Returns a stable JSON-serializable result describing what was detected
+    and what was written. Never raises for a missing CLI; a mock-only
+    config is a successful outcome.
+    """
+    target = Path(out_path) if out_path else Path.cwd() / DEFAULT_CONFIG_NAME
+    detected = detect_agent_clis()
+    found = sorted(agent for agent, exe in detected.items() if exe)
+    missing = sorted(agent for agent, exe in detected.items() if not exe)
+
+    result: dict[str, Any] = {
+        "config_path": str(target),
+        "detected": [
+            {"agent": agent, "executable": detected[agent]} for agent in found
+        ],
+        "missing": missing,
+        "mock_only": not found,
+        "forced": bool(force),
+        "written": False,
+        "skipped": False,
+    }
+
+    if target.exists() and not force:
+        result["skipped"] = True
+        result["reason"] = f"exists: {target} (use --force to overwrite)"
+        return result
+
+    config = build_starter_config(detected)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(
+        json.dumps(config, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    result["written"] = True
+    return result

{trinity_lite-0.7.0 → trinity_lite-0.7.2}/trinity_lite/mcp_server.py

@@ -374,6 +374,7 @@ RESOURCE_DEFINITIONS = [
 ALLOWED_METHODS = {
     "initialize",
     "initialized",
+    "notifications/initialized",
     "tools/list",
     "tools/call",
     "resources/list",
@@ -1073,6 +1074,13 @@ def handle_request(msg, bus, agents_path, routes_path):
     id_ = msg.get("id")
     params = msg.get("params", {})
 
+    # JSON-RPC 2.0: notifications carry no `id` and must NOT receive a
+    # response. Silently accept any notification (known or unknown) so we
+    # never emit an `id: null` error response, which the official `mcp`
+    # SDK >= 2.x stdio transport fails to validate and closes the stream.
+    if id_ is None:
+        return None
+
     if method not in ALLOWED_METHODS:
         return jsonrpc_error(id_, -32601, "method not found: {}".format(method))
 
@@ -1083,7 +1091,7 @@ def handle_request(msg, bus, agents_path, routes_path):
             "serverInfo": {"name": SERVER_NAME, "version": SERVER_VERSION},
         })
 
-    if method == "initialized":
+    if method in ("initialized", "notifications/initialized"):
         return None
 
     if method == "tools/list":
@@ -1143,9 +1151,12 @@ def serve(bus, agents_path=None, routes_path=None):
         except Exception:
             tb = traceback.format_exc()
             print("[mcp] unhandled exception:\n{}".format(tb), file=sys.stderr, flush=True)
-            error_resp = jsonrpc_error(msg.get("id"), -32603, "internal server error")
-            sys.stdout.write(json.dumps(error_resp) + "\n")
-            sys.stdout.flush()
+            # Don't emit an `id: null` error for notifications (no id).
+            _err_id = msg.get("id")
+            if _err_id is not None:
+                error_resp = jsonrpc_error(_err_id, -32603, "internal server error")
+                sys.stdout.write(json.dumps(error_resp) + "\n")
+                sys.stdout.flush()
             continue
 
         # Write response

{trinity_lite-0.7.0 → trinity_lite-0.7.2}/trinity_lite.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trinity-lite
-Version: 0.7.0
+Version: 0.7.2
 Summary: Local AgentOps for cross-vendor CLI agents: route work, recover state, and accept only with evidence.
 Author: Yomiracle
 License-Expression: MIT
@@ -99,7 +99,7 @@ LangGraph and CrewAI give you primitives for building agents from scratch — gr
 - **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.
+- **Check health in one pass.** `trinity-lite doctor` verifies Python, SQLite, route config, agent config, and publish readiness. `trinity-lite doctor --onboarding` grades every check as blocker or optional, probes for agent CLIs, and fails only on blockers.
 - **Zero core dependencies.** The default runtime is Python standard library only. YAML pipelines are available through an optional extra.
 - **150+ tests guarding the surface area.** Mock workflows, safety checks, routing, persistence, MCP, and acceptance gates — all covered.
 - **Optional model selection hints.** Select from your declared model pool with transparent task, tier, and capability rules; no claim of a universal best or cheapest model.
@@ -130,13 +130,15 @@ trinity-lite orchestrate "implement a rate limiter for the API"
 
 The primary task row records `route_json`, `review_task_id`, `verification_json`, `acceptance_status`, `acceptance_reason`, and `accepted_at`.
 
-Ready for real CLIs when you are:
+Ready for real CLIs when you are — auto-detect what is installed and generate a safe starter config:
 
 ```bash
-cp examples/agents.command.example.json agents.local.json
+trinity-lite init
 trinity-lite orchestrate "implement a rate limiter for the API" --agents agents.local.json
 ```
 
+`trinity-lite init` probes PATH for Codex, Claude Code, and Hermes, writes `agents.local.json` with JSON-array commands for the CLIs it finds, keeps the rest in mock mode, and never writes credentials or overwrites an existing config without `--force`. Prefer hand-editing? `cp examples/agents.command.example.json agents.local.json` still works.
+
 Prefer manual control? Use the lower-level bus commands:
 
 ```bash

{trinity_lite-0.7.0 → trinity_lite-0.7.2}/trinity_lite.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ tests/test_bus.py
 tests/test_cli.py
 tests/test_doctor.py
 tests/test_guard.py
+tests/test_init.py
 tests/test_mcp_server.py
 tests/test_orchestrator.py
 tests/test_pipeline.py
@@ -20,6 +21,7 @@ trinity_lite/cli.py
 trinity_lite/config.py
 trinity_lite/doctor.py
 trinity_lite/guard.py
+trinity_lite/init.py
 trinity_lite/mcp_server.py
 trinity_lite/model_autodetect.py
 trinity_lite/model_pool_wizard.py