trantor 0.15.0

package/mcp.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// agent-bus MCP server — gives ANY MCP-capable agent (Claude Code, Codex, Gemini, …)
+// tools to talk to OTHER live agent sessions through the relay hub. Loaded per-session
+// via the agent's MCP config. Identity + hub URL come from env (RELAY_SESSION, RELAY_URL).
+// Loading this server AUTO-REGISTERS the session — so presence works on every agent.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir, hostname } from "node:os";
+import { execSync, spawnSync } from "node:child_process";
+import { advise } from "./bin/advise.mjs";
+import { z } from "zod";
+
+function relayUrl() {
+  if (process.env.RELAY_URL) return process.env.RELAY_URL;
+  try {
+    const cfg = join(homedir(), ".agent-bus", "config.json");
+    if (existsSync(cfg)) { const u = JSON.parse(readFileSync(cfg, "utf8")).url; if (u) return u; }
+  } catch {}
+  return "http://127.0.0.1:4477";
+}
+const URL_BASE = relayUrl();
+const PROJECT = process.env.RELAY_PROJECT || basename(process.env.CLAUDE_PROJECT_DIR || process.cwd());
+// Identity: RELAY_SESSION wins; else RELAY_AGENT ("codex", "kimi", …) brands the session per-project
+// (set it once in the CLI's global MCP config — works in every project); else hostname:project.
+const SESSION = process.env.RELAY_SESSION
+  || (process.env.RELAY_AGENT ? `${process.env.RELAY_AGENT}:${PROJECT}` : `${hostname()}:${PROJECT}`);
+let cursor = 0;
+
+async function api(method, path, payload) {
+  const opts = { method, headers: { "content-type": "application/json" } };
+  if (payload) opts.body = JSON.stringify(payload);
+  const r = await fetch(URL_BASE + path, opts);
+  if (!r.ok) throw new Error(`hub ${r.status} on ${path}`);
+  return r.json();
+}
+const fmt = (m) => `#${m.id} [${m.from} -> ${m.to}] ${new Date(m.ts).toLocaleTimeString()}: ${m.text}`;
+
+const server = new McpServer({ name: "agent-bus", version: "0.1.0" });
+
+server.tool("relay_whoami", "Show this session's relay identity, project, and the hub URL.", {}, async () => {
+  await api("POST", "/register", { session: SESSION, project: PROJECT }).catch(() => {});
+  return { content: [{ type: "text", text: `session=${SESSION}\nproject=${PROJECT}\nhub=${URL_BASE}` }] };
+});
+
+server.tool("relay_task_add", "Add a Kanban card to THIS project's board on the dashboard (what you're about to work on). Defaults: assigned to you, status 'todo'. Keep the team's progress visible.",
+  { title: z.string().describe("short task title"), status: z.enum(["todo","doing","testing","failed","done","blocked"]).optional(), assignee: z.string().optional().describe("session id to assign (default: you)"), difficulty: z.enum(["easy","medium","hard"]).optional().describe("difficulty tag — drives model/agent routing (relay_advise) and shows on the board"), model: z.string().optional().describe("the model this card is routed to (from relay_advise routing, or the CLI default) — shown on the card"), deps: z.array(z.number()).optional().describe("card ids this card depends on — drawn as edges in the Flow view (e.g. integration depends on every crew card)") },
+  async ({ title, status, assignee, difficulty, model, deps }) => {
+    const { task } = await api("POST", "/task", { project: PROJECT, title, status: status || "todo", assignee: assignee || SESSION, difficulty, model, deps, by: SESSION });
+    return { content: [{ type: "text", text: `card #${task.id} added to ${PROJECT}: "${title}" [${task.status}]` }] };
+  });
+
+server.tool("relay_task_move", "Move a Kanban card as you progress: todo -> doing -> testing -> done. NEVER move straight to done: move to 'testing' when you finish, run the project's tests/typecheck, then 'done' only if green — or 'failed' (with a relay_send explaining what broke) if not. The orchestrator bounces failed cards back to doing. blocked = waiting on something external.",
+  { id: z.number(), status: z.enum(["todo","doing","testing","failed","done","blocked"]) },
+  async ({ id, status }) => {
+    await api("POST", "/task/update", { id, status, by: SESSION });
+    return { content: [{ type: "text", text: `card #${id} -> ${status}` }] };
+  });
+
+server.tool("relay_project_brief", "Set a one-paragraph brief for THIS project shown on the dashboard: what it is, why it matters, and the goal. Set it once when you start work so anyone watching the board understands the project at a glance (the board itself shows where it is in the process).",
+  { brief: z.string().describe("1-3 sentences: what this project is + why + the goal") },
+  async ({ brief }) => {
+    await api("POST", "/project", { project: PROJECT, brief, by: SESSION });
+    return { content: [{ type: "text", text: `brief set for ${PROJECT}` }] };
+  });
+
+server.tool("relay_advise", "THE ADVISOR — ask the brain how to execute a body of work before spending tokens. Give it your work packages (with difficulty); it weighs task shape x the user's plan economics x context horizon and returns: mode (solo|scrooge|crew|hybrid), per-package executor+model routing, and a real-money estimate with quota-pool accounting. Call this at project kickoff and PRESENT the summary to the user before firing anything up.",
+  { task: z.string().describe("one-line description of the overall job"),
+    packages: z.array(z.object({ title: z.string(), difficulty: z.enum(["easy","medium","hard"]).optional(), kind: z.string().optional() })).describe("the work packages you'd cut as cards"),
+    horizon: z.enum(["short","medium","long"]).optional().describe("how long this build will run (default inferred from package count)") },
+  async ({ task, packages, horizon }) => {
+    const out = advise({ task, packages, horizon });
+    return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
+  });
+
+server.tool("relay_scrooge", "Delegate a SMALL, SELF-CONTAINED piece of grunt work (draft a function, summarize, extract, classify, boilerplate) to a cheap external model via Scrooge — costs a fraction of a cent and keeps the result OUT of expensive context where possible. Returns the model's output plus the ledger receipt. Use for stateless one-shots; use the crew for anything stateful or large.",
+  { prompt: z.string().describe("the complete, self-contained task (include all needed context — the cheap model sees ONLY this)"),
+    task: z.string().optional().describe("scrooge task type: code, summarize, extract, draft, verify, reason, cheap (default code)"),
+    difficulty: z.enum(["easy","medium","hard"]).optional() },
+  async ({ prompt, task, difficulty }) => {
+    const r = spawnSync("scrooge", ["-t", task || "code", "-d", difficulty || "easy"], { input: prompt, encoding: "utf8", timeout: 120000, maxBuffer: 8 * 1024 * 1024 });
+    if (r.error || r.status !== 0) return { content: [{ type: "text", text: `scrooge failed: ${r.error?.message || r.stderr?.slice(-300) || "exit " + r.status}` }] };
+    const receipt = (r.stderr || "").split("\n").filter(l => l.includes("\u{1FA99}") || l.includes("scrooge")).slice(-1)[0] || "";
+    return { content: [{ type: "text", text: `${r.stdout.trim()}\n\n[receipt] ${receipt.trim()}` }] };
+  });
+
+server.tool("relay_lesson", "Record a LESSON learned from a failure so future crews avoid it — injected into agents' kickoff prompts automatically. Use when you diagnose a recurring or preventable failure. scope: 'global' (applies to every agent) or an agent brand ('kimi','codex','gemini','deepseek') when it's that CLI's quirk.",
+  { text: z.string().describe("one-line imperative guardrail, e.g. 'never move a card to done without npm test passing'"), scope: z.string().optional().describe("'global' (default) or an agent brand") },
+  async ({ text, scope }) => {
+    const r = await api("POST", "/lesson", { text, scope: scope || "global", by: SESSION });
+    return { content: [{ type: "text", text: r.dedup ? "lesson already recorded" : `lesson recorded (${r.count} total)` }] };
+  });
+
+server.tool("relay_board", "Show THIS project's Kanban board (all cards + their status + assignee).", {}, async () => {
+  const { tasks } = await api("GET", `/tasks?project=${encodeURIComponent(PROJECT)}`);
+  if (!tasks.length) return { content: [{ type: "text", text: `${PROJECT}: no cards yet` }] };
+  const by = { todo: [], doing: [], testing: [], failed: [], done: [], blocked: [] };
+  for (const t of tasks) (by[t.status] || by.todo).push(`#${t.id} ${t.title}${t.assignee ? ` (@${t.assignee})` : ""}`);
+  const cols = Object.entries(by).filter(([, v]) => v.length).map(([k, v]) => `${k.toUpperCase()}:\n  ${v.join("\n  ")}`);
+  return { content: [{ type: "text", text: `${PROJECT} board\n${cols.join("\n")}` }] };
+});
+
+server.tool("relay_peers", "List other Claude sessions connected to the relay (online in last 5 min).", {}, async () => {
+  const { peers } = await api("GET", "/peers");
+  const lines = peers.map(p => `${p.online ? "🟢" : "⚪"} ${p.session}${p.session === SESSION ? " (you)" : ""}`);
+  return { content: [{ type: "text", text: lines.join("\n") || "no peers yet" }] };
+});
+
+server.tool("relay_send", "Send a live message to another Claude session (or 'all' to broadcast).",
+  { to: z.string().describe("target session id, or 'all'"), text: z.string().describe("message body") },
+  async ({ to, text }) => {
+    const { id } = await api("POST", "/send", { from: SESSION, to, text });
+    return { content: [{ type: "text", text: `sent #${id} to ${to}` }] };
+  });
+
+server.tool("relay_status", "Set this session's one-line status on the presence board (what you're working on / idle). Cheap — other sessions read it instantly via relay_peers without messaging you.",
+  { status: z.string().describe("short status, e.g. 'building auth in crebral' or 'idle'") },
+  async ({ status }) => {
+    await api("POST", "/status", { session: SESSION, status, project: PROJECT });
+    return { content: [{ type: "text", text: `status set: ${status}` }] };
+  });
+
+server.tool("relay_handoff", "Write a rich handoff for THIS session so a fresh session (any agent) can take over with a full context window instead of compacting. Provide a complete markdown summary (TASK / STATE / KEY DECISIONS / NEXT STEPS / KEY FILES). Universal — works in any agent, not just Claude's PreCompact hook.",
+  { summary: z.string().describe("complete markdown handoff: TASK, STATE, KEY DECISIONS, NEXT STEPS, KEY FILES & locations") },
+  async ({ summary }) => {
+    const project = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const name = basename(project);
+    const dir = join(homedir(), ".agent-bus", "handoffs");
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const stamp = (() => { try { return execSync("date +%s", { encoding: "utf8" }).trim(); } catch { return String(process.pid); } })();
+    let git = ""; try { git = execSync("git -C " + JSON.stringify(project) + " status --short 2>/dev/null | head -30", { encoding: "utf8" }).trim(); } catch {}
+    const rec = { id: `${name}-${stamp}`, project, projectName: name, machine: hostname(), trigger: "relay_handoff-tool", stamp: Number(stamp) || 0, summary: String(summary), gitStatus: git, consumed: false };
+    writeFileSync(join(dir, `${rec.id}.json`), JSON.stringify(rec, null, 2));
+    await api("POST", "/send", { from: SESSION, to: "all", text: `📋 Handoff ready for ${name} — open a fresh session here to take over (${rec.id}).` }).catch(() => {});
+    return { content: [{ type: "text", text: `handoff saved (${rec.id}). A fresh session in ${name} will load it on start. Tell the user to open a new terminal here.` }] };
+  });
+
+server.tool("relay_inbox", "Read NEW messages addressed to this session since the last read (non-blocking).", {}, async () => {
+  const { messages, cursor: c } = await api("GET", `/inbox?session=${encodeURIComponent(SESSION)}&since=${cursor}`);
+  cursor = c;
+  return { content: [{ type: "text", text: messages.length ? messages.map(fmt).join("\n") : "(no new messages)" }] };
+});
+
+server.tool("relay_wait", "Block up to `timeout` seconds waiting for the next message to this session (long-poll). Returns the instant a message arrives. When idle, park by calling this repeatedly. IMPORTANT: some MCP clients cap tool calls (Codex ~120s, OpenCode ~60s) — use timeout 50 and loop, unless you know your client allows more (Claude Code handles 280).",
+  { timeout: z.number().optional().describe("seconds to wait, default 25, max 280. Use 50 and call repeatedly for cross-client safety; only Claude Code reliably supports 280.") },
+  async ({ timeout }) => {
+    const w = Math.min(timeout ?? 25, 280);
+    const { messages, cursor: c } = await api("GET", `/poll?session=${encodeURIComponent(SESSION)}&since=${cursor}&wait=${w}`);
+    cursor = c;
+    return { content: [{ type: "text", text: messages.length ? messages.map(fmt).join("\n") : "(timed out, no message)" }] };
+  });
+
+await api("POST", "/register", { session: SESSION, project: PROJECT, status: `active in ${PROJECT}` }).catch(() => {});
+await server.connect(new StdioServerTransport());
+process.stderr.write(`[agent-bus-mcp] connected as ${SESSION} -> ${URL_BASE}\n`);

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "trantor",
+  "version": "0.15.0",
+  "type": "module",
+  "bin": {
+    "trantor": "bin/cli.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "test": "node test.mjs && node test-scenarios.mjs"
+  },
+  "description": "The hub-world for AI agent crews \u2014 orchestrate Claude Code, Codex, Gemini, Kimi & DeepSeek as live crews with a plan-aware Advisor, a Kanban/flow command center, a testing gate, and an economics brain (Scrooge).",
+  "files": [
+    "hub.mjs",
+    "mcp.mjs",
+    "ui.html",
+    "bin/",
+    "hooks/",
+    "skills/",
+    "deploy/",
+    "configs/",
+    ".claude-plugin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sashabogi/trantor.git"
+  },
+  "homepage": "https://github.com/sashabogi/trantor#readme",
+  "bugs": {
+    "url": "https://github.com/sashabogi/trantor/issues"
+  },
+  "keywords": [
+    "ai-agents",
+    "multi-agent",
+    "orchestration",
+    "claude-code",
+    "codex",
+    "gemini",
+    "mcp",
+    "kanban",
+    "agent-crew",
+    "llm-routing"
+  ],
+  "author": "Sasha Bogojevic <hello@hivedigitalllc.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/crew/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: crew
+description: Orchestrate a multi-agent build over agent-bus — get an Advisor recommendation (solo/scrooge/crew/hybrid based on the user's plans and the work), fire up helper AI CLIs (Codex, Gemini, Kimi, DeepSeek) with pinned models in visible terminal windows, assign difficulty-tagged work over the bus, track it on the Kanban dashboard with a testing gate, delegate grunt to Scrooge, supervise actively, integrate, ship. Use when the user wants several AI agents building something together, says "fire up the crew/agents", or asks to coordinate other coding CLIs on a task.
+---
+
+# agent-bus crew — the unified playbook (brain × body)
+
+You are the ARCHITECT. Two execution fabrics serve you:
+- **Scrooge calls** (`relay_scrooge`) — cheap stateless one-shots; the result returns to you.
+- **Crew members** — stateful colleagues in their own context windows under a runner that
+  keeps them alive forever and wakes them on bus messages. They report by reference.
+
+**Decision rule:** small + stateless + result-fits-inline → `relay_scrooge`.
+Large + stateful + parallel or long-horizon → crew member. You stay a foreman either way:
+your context burns at coordination rate, never work rate.
+
+## Phase −1 — THE ADVISOR MOMENT (always, before spending anything)
+Cut the work into packages, tag each `easy|medium|hard`, then call
+`relay_advise(task, packages, horizon)`. It weighs task shape × the user's declared plan
+economics (quota profile) × context horizon and returns mode + per-package routing — each
+route carries a `reason`, and `crew.why` explains the SEAT COUNT (seats follow the work,
+not the install list). Mark packages you'll own yourself with `owner:"self"` (foundation/
+integration are auto-reserved). **Never present a bare go/no-go.** In your TEXT REPLY (not
+inside a question dialog), paste verbatim: `routing_table_md`, the `why` bullets, `crew.why`,
+and the real-money total + quota pools. ONLY THEN ask go / adjust / hold. When creating the
+board, use `card_args` exactly — each entry is a ready `relay_task_add` call (title,
+difficulty, assignee with your project substituted, model). Cards without their model set
+are a defect. If the profile is unset, say so and suggest `node bin/profile.mjs set …`.
+
+## Phase 0 — plan (if the user wants a plan first)
+PRD.md + TDD.md. The TDD MUST define one file-set per agent (no merge conflicts) and an
+explicit EVENT/INTERFACE CONTRACT — cross-agent bugs come from contract drift.
+
+## Phase 1 — board setup
+1. `relay_project_brief("<what + why + goal>")`
+2. One card per package: `relay_task_add(title, assignee, difficulty, model)` — set `model`
+   to the advisor-routed model (or the CLI's default name); difficulty + model show as badges
+   on the card. Assignees: `codex:<project>` etc. Keep one for yourself.
+3. Open the dashboard: `open -na "Google Chrome" --args --new-window <hub-url>`
+
+## Phase 2 — fire up the crew (with the Advisor's models)
+`bash <plugin-root>/bin/crew.sh up codex:gpt-5.5 gemini kimi deepseek:deepseek-v4-pro`
+— `agent:model` pins a model (omit to use that CLI's default; use what relay_advise routed).
+The launcher auto-wires configs, spawns serialized runner windows, then **VERIFIES each agent
+on the bus with one retry**. READ ITS OUTPUT: it ends "crew verified" or "✗✗ CREW INCOMPLETE"
+naming no-shows. **Never assign work to an unverified agent.** The bus is the truth.
+
+## Phase 3 — contracts over the bus
+Build the shared foundation yourself first, then `relay_send` each agent its contract
+(<280 chars): file(s) owned, the interface contract verbatim, the spec. NOTE the wake-policy:
+plain broadcasts do NOT wake crew members (they batch as context) — to wake one, send a
+direct message or @mention it (`@codex …`) in a broadcast.
+
+## Phase 4 — SUPERVISE ACTIVELY (never wait passively)
+Loop until the board is done — you are a foreman, not a mailbox:
+1. `relay_wait(120)` (long waits are safe for YOU only; crew runners handle their own waiting).
+2. EVERY wake or timeout, SWEEP: `relay_board` (stale cards? `failed` pulsing?), `relay_peers`
+   (assignee lastSeen fresh? runner heartbeats keep live agents fresh in seconds — stale =
+   dead), spot-check files on disk.
+3. ACT within one cycle: failed card → read the report, send a fix contract, card back to
+   doing · dead agent → `crew.sh up <agent>` (re-verifies) + resend contract · silent-but-alive
+   → direct-message nudge naming the card.
+4. Grunt sub-tasks that appear mid-build (a regex, a config block, a doc paragraph) →
+   `relay_scrooge`, don't burn a crew seat or your own window.
+5. Record lessons as you diagnose (`relay_lesson(text, scope)` — global or per-agent quirks);
+   they auto-inject into every future crew's prompts.
+
+## Phase 5 — verification gate + integration
+Card flow is `todo → doing → testing → done`; `testing` runs the project's tests/typecheck;
+`done` only green; `failed` (+ bus report) pulses red on the board until you bounce it.
+Enforce the gate — bounce anything that skipped it (bounces are visible: "↩ bounced" on the
+card, history in its tooltip). When all report done: integrate, fix contract mismatches
+YOURSELF, move your card through testing → done, broadcast "🚀 <thing> is live", and when the
+user is finished: `bash .../crew.sh down`.
+
+## Rules
+- Coordinate ONLY over the bus; messages <280 chars; the dashboard lanes are the user's view.
+- Never edit a crew member's file unless integration is broken AND they're dead/silent.
+- Trust the verifier, the sweep, and the gate — not assumptions or optimistic reports.
+- If a CLI fails (auth/model/quota), tell the user plainly and continue with the rest.
+- Telemetry for cost reporting lands in `~/.agent-bus/logs/` automatically; the dashboard's
+  🪙 pill shows live Scrooge spend/savings.

package/skills/relay-handoff/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: relay-handoff
+description: |
+  Write a rich handoff for the CURRENT session so a fresh Claude Code session can take over
+  with a full new context window (instead of compacting). Use proactively when context is
+  getting full, or before ending, to pass the baton cleanly. Trigger: /agent-bus:relay-handoff
+user-invocable: true
+---
+
+# Relay Handoff — pass the baton to a fresh session
+
+Write a complete handoff capturing everything a NEW session needs to continue this work without
+re-deriving context, and save it so the next session in this project auto-loads it on start.
+
+## Instructions
+
+1. Compose a thorough markdown handoff for the current task with these sections (be specific —
+   exact file paths, concrete next actions; the successor has a fresh window and only this):
+   - **TASK** — what we're doing and the goal
+   - **STATE** — what's done, what's in progress
+   - **KEY DECISIONS** — choices made and why
+   - **OPEN THREADS & NEXT STEPS** — the concrete actions to do next, in order
+   - **KEY FILES & LOCATIONS** — exact paths, commands, URLs, IDs the successor needs
+   - **GOTCHAS** — anything that will bite if forgotten
+
+2. Save it by piping the markdown to the helper:
+   ```bash
+   cat << 'HANDOFF' | node "$(dirname "$(command -v claude)")/../<plugin>/bin/write-handoff.mjs"
+   <your handoff markdown>
+   HANDOFF
+   ```
+   (Or call the plugin's `bin/write-handoff.mjs` directly via its `${CLAUDE_PLUGIN_ROOT}`.)
+
+3. Tell the user: open a fresh terminal + `claude` in this same project directory — the
+   SessionStart hook will detect the handoff and the new session takes over with a full window.
+   (The PreCompact hook also writes one automatically at the compaction threshold.)