traintrack 2.0.0

package/dist/worker/worker.js

@@ -0,0 +1,190 @@
+// ─── traintrack headless worker ──────────────────────────────────────────────
+// A long-lived loop that makes ONE agent a reliable, auto-responding teammate.
+// Unlike PTY injection (best-effort, research-proven unreliable), this drains the
+// agent's durable inbox (the local SQLite Channel) and runs each turn as a fresh
+// HEADLESS process (claude --print / codex exec resume), using the structured
+// turn-end event as the ACK. The receiving agent therefore "sees" messages with
+// zero human input and on a guaranteed schedule.
+//
+// Ported from $TT/src/cli/headless-worker.ts and REPOINTED off Orca's
+// RuntimeClient (RPC) onto the local Channel:
+//   orchestration.check {unread} → channel.getUnread(handle) + channel.markRead(ids)
+//   orchestration.send {to,from,body} → channel.insertMessage({to,from,body})
+//   team.join {...} → channel.addMember({handle, agent, role, kind:'headless', ...})
+//   team.list → channel.listMembers()
+// No RPC, no engine — the worker takes a Channel directly.
+import { buildHeadlessArgv } from '../runner/argv.js';
+import { runHeadlessTurn } from '../runner/turn-runner.js';
+import { buildBriefing } from '../onboarding/briefing.js';
+/** Build the team briefing from the channel's CURRENT roster. Called every loop
+ *  iteration so a worker's prompt reflects teammates who joined after it spawned. */
+export function buildRosterBriefing(channel, selfHandle, selfRole, teamName = 'team') {
+    const roster = channel.listMembers().map((m) => ({
+        handle: m.handle,
+        role: m.role,
+        agent: m.agent,
+        kind: m.kind,
+    }));
+    return buildBriefing({ teamName, selfHandle, selfRole, roster });
+}
+/** Build the turn prompt from the drained inbox messages (port of the rust build_prompt). */
+export function buildWorkerPrompt(agent, messages, briefing) {
+    const lines = messages.map((m) => `From ${m.from}: ${m.body}`).join('\n');
+    const body = [
+        `You are the "${agent}" agent in a traintrack multi-agent workspace, coordinating with teammates over a shared message channel.`,
+        `The following message(s) just arrived in your inbox. Read them and reply — your reply is delivered back to the sender(s).`,
+        '',
+        '--- Messages ---',
+        lines,
+        '--- End ---',
+        '',
+        'Respond now.'
+    ].join('\n');
+    if (briefing) {
+        return `${briefing}\n\n${body}`;
+    }
+    return body;
+}
+/**
+ * Resolve a direct peer address from a worker's reply text. If `text` starts with
+ * `@`, the leading token (up to the first whitespace) is matched case-insensitively
+ * as a substring against each member's `handle` or `role` (excluding `selfHandle`).
+ * On a match, returns `{ to: matchedHandle, body: <rest of text> }`. If the text has
+ * no leading `@`, or the token matches no member, returns `null` (caller falls back
+ * to replying to the original sender — the message is never dropped). Ported from the
+ * `@name` parse in traintrack-desktop's session.ts.
+ */
+export function resolvePeerAddress(text, members, selfHandle) {
+    if (!text.startsWith('@')) {
+        return null;
+    }
+    const ws = text.search(/\s/);
+    const token = (ws === -1 ? text.slice(1) : text.slice(1, ws)).trim();
+    const body = ws === -1 ? '' : text.slice(ws + 1).trim();
+    if (!token) {
+        return null;
+    }
+    const needle = token.toLowerCase();
+    const match = members.find((m) => m.handle !== selfHandle &&
+        (m.handle.toLowerCase().includes(needle) || m.role.toLowerCase().includes(needle)));
+    return match ? { to: match.handle, body } : null;
+}
+/**
+ * One drain → headless turn → reply cycle. Pulls this worker's unread inbox from
+ * the channel, runs a single headless agent turn with those messages spliced in,
+ * posts the agent's reply back to each distinct sender, and marks the drained
+ * messages read. Returns what happened (for logging + tests) including the
+ * (possibly new) session id to carry forward.
+ */
+export async function runWorkerCycle(deps) {
+    const { channel, handle, agent, cwd, model, runTurn, print, briefing } = deps;
+    const messages = channel.getUnread(handle);
+    if (messages.length === 0) {
+        return { processed: 0, sessionId: deps.sessionId, repliedTo: [] };
+    }
+    print?.(`[worker] ${agent} draining ${messages.length} message(s)`);
+    const prompt = buildWorkerPrompt(agent, messages, briefing);
+    const turn = await runTurn({
+        provider: agent,
+        prompt,
+        cwd,
+        model,
+        resumeSessionId: deps.sessionId
+    });
+    const reply = turn.finalText.trim();
+    const senders = [...new Set(messages.map((m) => m.from).filter(Boolean))];
+    // If the reply opens with `@<handle-or-role>`, route the rest to that teammate
+    // instead of the original sender(s). No `@` / no match → reply to senders as usual.
+    const peer = reply ? resolvePeerAddress(reply, channel.listMembers(), handle) : null;
+    let repliedTo = [];
+    if (reply && peer) {
+        channel.insertMessage({ to: peer.to, from: handle, body: peer.body, type: 'status' });
+        repliedTo = [peer.to];
+        print?.(`[worker] ${agent} addressed ${peer.to}`);
+    }
+    else if (reply) {
+        for (const to of senders) {
+            channel.insertMessage({ to, from: handle, body: reply, type: 'status' });
+        }
+        repliedTo = senders;
+        print?.(`[worker] ${agent} replied to ${senders.join(', ')}`);
+    }
+    else {
+        print?.(`[worker] ${agent} produced no reply text (isError=${turn.isError})`);
+    }
+    // ACK the drained messages so they are not re-processed next cycle. Done after
+    // the turn + reply so a crash mid-turn leaves them unread (re-tried) rather
+    // than silently dropped.
+    channel.markRead(messages.map((m) => m.id));
+    return {
+        processed: messages.length,
+        reply: reply || undefined,
+        sessionId: turn.sessionId ?? deps.sessionId,
+        repliedTo
+    };
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Default turn runner: build the argv then spawn a real headless turn. */
+const realTurnRunner = async (input) => {
+    const { command, args } = buildHeadlessArgv({
+        agent: input.provider,
+        prompt: input.prompt,
+        model: input.model,
+        resumeSessionId: input.resumeSessionId
+    });
+    const outcome = await runHeadlessTurn({
+        provider: input.provider,
+        command,
+        args,
+        cwd: input.cwd
+    });
+    return { finalText: outcome.finalText, sessionId: outcome.sessionId, isError: outcome.isError };
+};
+/**
+ * Run the worker loop until the process is killed (or one cycle when once=true).
+ * On start it registers itself in the channel's roster (addMember, kind=headless),
+ * reads the roster (listMembers), and builds the team briefing ONCE — the briefing
+ * is then prepended to every per-turn prompt.
+ */
+export async function runWorker(opts) {
+    const print = opts.print ?? ((msg) => process.stderr.write(`${msg}\n`));
+    const sleep = opts.sleep ?? defaultSleep;
+    const pollMs = opts.pollMs ?? 3000;
+    const runTurn = opts.runTurn ?? realTurnRunner;
+    // Self-register in the channel roster so teammates discover this worker.
+    const self = {
+        handle: opts.handle,
+        agent: opts.agent,
+        role: opts.role,
+        kind: opts.kind ?? 'headless',
+        status: 'active',
+        worktree: opts.cwd
+    };
+    opts.channel.addMember(self);
+    print(`[worker] online as ${opts.handle} (agent=${opts.agent}, role=${opts.role}, cwd=${opts.cwd}, poll=${pollMs}ms)`);
+    let sessionId;
+    for (;;) {
+        try {
+            const briefing = buildRosterBriefing(opts.channel, opts.handle, opts.role);
+            const cycle = await runWorkerCycle({
+                channel: opts.channel,
+                handle: opts.handle,
+                agent: opts.agent,
+                cwd: opts.cwd,
+                model: opts.model,
+                runTurn,
+                sessionId,
+                print,
+                briefing
+            });
+            sessionId = cycle.sessionId;
+        }
+        catch (err) {
+            print(`[worker] cycle error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (opts.once) {
+            return;
+        }
+        await sleep(pollMs);
+    }
+}

package/hooks/hooks-codex.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start-codex",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/hooks-cursor.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "./hooks/run-hook.cmd session-start"
+      }
+    ]
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/run-hook.cmd

@@ -0,0 +1,46 @@
+: << 'CMDBLOCK'
+@echo off
+REM Cross-platform polyglot wrapper for hook scripts.
+REM On Windows: cmd.exe runs the batch portion, which finds and calls bash.
+REM On Unix: the shell interprets this as a script (: is a no-op in bash).
+REM
+REM Hook scripts use extensionless filenames (e.g. "session-start" not
+REM "session-start.sh") so Claude Code's Windows auto-detection -- which
+REM prepends "bash" to any command containing .sh -- doesn't interfere.
+REM
+REM Usage: run-hook.cmd <script-name> [args...]
+
+if "%~1"=="" (
+    echo run-hook.cmd: missing script name >&2
+    exit /b 1
+)
+
+set "HOOK_DIR=%~dp0"
+
+REM Try Git for Windows bash in standard locations
+if exist "C:\Program Files\Git\bin\bash.exe" (
+    "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
+    "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM Try bash on PATH (e.g. user-installed Git Bash, MSYS2, Cygwin)
+where bash >nul 2>nul
+if %ERRORLEVEL% equ 0 (
+    bash "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM No bash found - exit silently rather than error
+REM (plugin still works, just without SessionStart context injection)
+exit /b 0
+CMDBLOCK
+
+# Unix: run the named script directly
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

package/hooks/session-start

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# SessionStart hook for the traintrack plugin.
+# Injects "you are the team lead" awareness so the model knows it can spawn,
+# delegate to, and collect from a team of worker agents via the traintrack MCP tools.
+
+set -euo pipefail
+
+# The traintrack awareness content injected into the session context.
+traintrack_content="You have the \`traintrack\` multi-agent coordination tools (list_team, spawn_worker, delegate_task, await_results, send_message, check_messages). You are the team LEAD. When the user asks you to build something sizable, you can spawn worker agents to parallelize: spawn_worker(agent, role, task) for each part, then await_results() to collect their work, then synthesize. Use them when delegation helps; do simple tasks yourself. You can run MULTIPLE rounds: spawn or delegate to teammates by role, call await_results to collect their replies, then delegate follow-up tasks based on what came back and collect again, before synthesizing your final answer. Give each teammate a clear role and keep the team small. If a human adds your session to an EXISTING team (rather than you leading), call join_team(handle, role) first, then check_messages — teammates may message you at any time."
+
+# Escape a string for embedding inside a JSON string literal. Each ${s//old/new}
+# is a single C-level pass — orders of magnitude faster than a char loop.
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+
+traintrack_escaped=$(escape_for_json "$traintrack_content")
+session_context="<EXTREMELY_IMPORTANT>\n${traintrack_escaped}\n</EXTREMELY_IMPORTANT>"
+
+# Output context injection as JSON.
+# Cursor hooks expect additional_context (snake_case).
+# Claude Code hooks expect hookSpecificOutput.additionalContext (nested).
+# Copilot CLI (v1.0.11+) and others expect additionalContext (top-level, SDK standard).
+#
+# Uses printf instead of heredoc to work around bash 5.3+ heredoc hang.
+# See: https://github.com/obra/superpowers/issues/571
+if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
+  # Cursor sets CURSOR_PLUGIN_ROOT (may also set CLAUDE_PLUGIN_ROOT)
+  printf '{\n  "additional_context": "%s"\n}\n' "$session_context" | cat
+elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
+  # Claude Code sets CLAUDE_PLUGIN_ROOT without COPILOT_CLI
+  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context" | cat
+else
+  # Copilot CLI (sets COPILOT_CLI=1) or unknown platform — SDK standard format
+  printf '{\n  "additionalContext": "%s"\n}\n' "$session_context" | cat
+fi
+
+exit 0

package/hooks/session-start-codex

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Codex SessionStart hook for traintrack plugin.
+# Injects "you are the team lead" awareness so the model knows it can spawn,
+# delegate to, and collect from a team of worker agents via the traintrack MCP tools.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+traintrack_content="You have the \`traintrack\` multi-agent coordination tools (list_team, spawn_worker, delegate_task, await_results, send_message, check_messages). You are the team LEAD. When the user asks you to build something sizable, you can spawn worker agents to parallelize: spawn_worker(agent, role, task) for each part, then await_results() to collect their work, then synthesize. Use them when delegation helps; do simple tasks yourself. You can run MULTIPLE rounds: spawn or delegate to teammates by role, call await_results to collect their replies, then delegate follow-up tasks based on what came back and collect again, before synthesizing your final answer. Give each teammate a clear role and keep the team small. If a human adds your session to an EXISTING team (rather than you leading), call join_team(handle, role) first, then check_messages — teammates may message you at any time."
+
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+
+traintrack_escaped=$(escape_for_json "$traintrack_content")
+session_context="<EXTREMELY_IMPORTANT>\n${traintrack_escaped}\n</EXTREMELY_IMPORTANT>"
+
+printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context" | cat
+
+exit 0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "traintrack",
+  "version": "2.0.0",
+  "publishConfig": { "access": "public" },
+  "description": "Multi-agent coordination for coding agents — a lead spawns worker agents, delegates tasks, and collects results over a local channel. One command wires it into Claude Code, Codex, Cursor, and OpenCode.",
+  "keywords": [
+    "mcp",
+    "multi-agent",
+    "claude",
+    "codex",
+    "cursor",
+    "opencode",
+    "agent",
+    "coordination",
+    "a2a",
+    "orchestration",
+    "ai"
+  ],
+  "homepage": "https://github.com/OKKHALIL3/traintrack#readme",
+  "bugs": {
+    "url": "https://github.com/OKKHALIL3/traintrack/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OKKHALIL3/traintrack.git"
+  },
+  "author": "Omar Khalil",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": { ".": "./dist/index.js" },
+  "bin": { "traintrack": "dist/cli.js" },
+  "files": ["dist", "hooks"],
+  "engines": { "node": ">=18" },
+  "os": ["darwin", "linux"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && npm run postbuild",
+    "postbuild": "chmod +x dist/cli.js",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": { "better-sqlite3": "^11.8.0" },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.4.0"
+  }
+}