@heretyc/subagent-mcp 2.6.0

package/dist/stream-helpers.js

@@ -0,0 +1,182 @@
+// Defensive parsing of a sub-agent's VISIBLE provider stream.
+//
+// "Visible" = provider stream events, summaries, and assistant messages a human
+// would see in the CLI. Provider-internal reasoning blocks (Claude `thinking` /
+// `redacted_thinking` content blocks, Codex `reasoning` items/events) are not
+// parsed into visible items. Supports Codex `--json` JSONL and Claude
+// stream-json / buffered-json where feasible. NEVER throws; unparseable lines
+// are skipped.
+function pushText(out, type, text) {
+    if (typeof text === "string" && text.trim().length > 0) {
+        out.push({ type, text: text.trim() });
+    }
+}
+// Codex `exec --json` is newline-delimited JSON. Visible: agent messages and
+// completed items that carry text. Chain-of-thought (anything whose type or
+// item_type is `reasoning`) is dropped.
+function collectCodex(e, out) {
+    const type = typeof e.type === "string" ? e.type : "";
+    if (type.includes("reasoning"))
+        return;
+    // Shape A: { type: "agent_message", message: "..." }
+    if (type === "agent_message") {
+        pushText(out, "agent_message", e.message);
+        return;
+    }
+    // Shape B: { type: "item.completed", item: { item_type, text } }
+    if (type === "item.completed" && e.item && typeof e.item === "object") {
+        const item = e.item;
+        const itemType = typeof item.item_type === "string" ? item.item_type : "item";
+        if (itemType.includes("reasoning"))
+            return;
+        pushText(out, itemType, item.text);
+        return;
+    }
+    // Shape C: { msg: { type: "agent_message", message: "..." } }
+    if (e.msg && typeof e.msg === "object") {
+        const msg = e.msg;
+        const msgType = typeof msg.type === "string" ? msg.type : "";
+        if (msgType.includes("reasoning"))
+            return;
+        if (msgType === "agent_message")
+            pushText(out, "agent_message", msg.message);
+    }
+}
+// Claude stream-json emits one JSON event per line. Visible: assistant `text`
+// and `tool_use` blocks plus the final `result`. `thinking` /
+// `redacted_thinking` blocks are dropped. Tolerates the buffered-json single
+// `result` object too.
+function collectClaude(e, out) {
+    if (e.type === "result") {
+        pushText(out, "result", e.result);
+        return;
+    }
+    if (e.type === "assistant" && e.message && typeof e.message === "object") {
+        const message = e.message;
+        const content = message.content;
+        if (!Array.isArray(content))
+            return;
+        for (const block of content) {
+            if (!block || typeof block !== "object")
+                continue;
+            const b = block;
+            if (b.type === "text")
+                pushText(out, "text", b.text);
+            else if (b.type === "tool_use")
+                pushText(out, "tool_use", b.name);
+            // thinking / redacted_thinking: provider-internal reasoning, not parsed as visible.
+        }
+    }
+}
+// Returns true if a complete JSONL line contains only provider-internal reasoning
+// (Claude `thinking`/`redacted_thinking` blocks, Codex `reasoning` items) —
+// records that produce no visible stream items. Never throws.
+export function isNonVisibleStreamLine(provider, line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return false;
+    let evt;
+    try {
+        evt = JSON.parse(trimmed);
+    }
+    catch {
+        return false;
+    }
+    if (!evt || typeof evt !== "object")
+        return false;
+    const e = evt;
+    if (provider === "codex") {
+        const type = typeof e.type === "string" ? e.type : "";
+        if (type.includes("reasoning"))
+            return true;
+        if (type === "item.completed" && e.item && typeof e.item === "object") {
+            const item = e.item;
+            if (typeof item.item_type === "string" && item.item_type.includes("reasoning"))
+                return true;
+        }
+        if (e.msg && typeof e.msg === "object") {
+            const msg = e.msg;
+            if (typeof msg.type === "string" && msg.type.includes("reasoning"))
+                return true;
+        }
+        return false;
+    }
+    if (provider === "claude") {
+        if (e.type !== "assistant")
+            return false;
+        if (!e.message || typeof e.message !== "object")
+            return false;
+        const content = e.message.content;
+        if (!Array.isArray(content) || content.length === 0)
+            return false;
+        // Only pure hidden if every block is thinking/redacted_thinking.
+        return content.every((block) => {
+            if (!block || typeof block !== "object")
+                return false;
+            const b = block;
+            return b.type === "thinking" || b.type === "redacted_thinking";
+        });
+    }
+    return false;
+}
+// Parse a SINGLE complete JSONL line into visible items (appended to `out`).
+// Blank/unparseable lines are skipped. Never throws.
+function collectLine(provider, line, out) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return;
+    let evt;
+    try {
+        evt = JSON.parse(trimmed);
+    }
+    catch {
+        return;
+    }
+    if (!evt || typeof evt !== "object")
+        return;
+    if (provider === "codex")
+        collectCodex(evt, out);
+    else if (provider === "claude")
+        collectClaude(evt, out);
+}
+export function parseVisibleStream(provider, chunk) {
+    const out = [];
+    if (!chunk)
+        return out;
+    for (const line of chunk.split("\n"))
+        collectLine(provider, line, out);
+    return out;
+}
+export function consumeStreamChunk(provider, pending, chunk) {
+    const data = (pending || "") + (chunk || "");
+    const parts = data.split("\n");
+    // The last element is the trailing fragment: incomplete unless the chunk ended
+    // with a newline (in which case it is "").
+    const remainder = parts.pop() ?? "";
+    const items = [];
+    const lines = [];
+    for (const line of parts) {
+        if (!line.trim())
+            continue;
+        lines.push(line);
+        collectLine(provider, line, items);
+    }
+    return { items, pending: remainder, lines };
+}
+// Flush any buffered trailing fragment (call once on stream close, where the
+// final line may have arrived without a terminating newline).
+export function flushStream(provider, pending) {
+    const trimmed = (pending || "").trim();
+    if (!trimmed)
+        return { items: [], pending: "", lines: [] };
+    const items = [];
+    collectLine(provider, trimmed, items);
+    return { items, pending: "", lines: [trimmed] };
+}
+// Append new items to a rolling buffer, retaining only the last `n`.
+export function retainLastN(buffer, items, n) {
+    if (items.length === 0)
+        return buffer;
+    const merged = buffer.concat(items);
+    return merged.length > n ? merged.slice(-n) : merged;
+}

package/dist/wait-helpers.js

@@ -0,0 +1,21 @@
+export function formatLocalIso(ms) {
+    const d = new Date(ms);
+    const pad2 = (n) => String(n).padStart(2, "0");
+    const year = d.getFullYear();
+    const month = pad2(d.getMonth() + 1);
+    const day = pad2(d.getDate());
+    const hours = pad2(d.getHours());
+    const minutes = pad2(d.getMinutes());
+    const seconds = pad2(d.getSeconds());
+    const offsetMin = -d.getTimezoneOffset();
+    const sign = offsetMin >= 0 ? "+" : "-";
+    const absMin = Math.abs(offsetMin);
+    const offH = pad2(Math.floor(absMin / 60));
+    const offM = pad2(absMin % 60);
+    const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}${sign}${offH}:${offM} (${zone})`;
+}
+const TERMINAL_STATUSES = new Set(["finished", "errored", "stopped"]);
+export function selectUnreported(list) {
+    return list.filter((a) => TERMINAL_STATUSES.has(a.status) && a.exitedAt !== null && !a.waitReported);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@heretyc/subagent-mcp",
+  "version": "2.6.0",
+  "description": "MCP server that launches and manages local Claude Code and Codex CLI sub-agents as child processes (no direct Anthropic/OpenAI API).",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "subagent-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "directives",
+    "scripts/postinstall.mjs",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/gen-ruleset-scaffold.mjs && tsc && node scripts/copy-provider.mjs",
+    "start": "node dist/index.js",
+    "postinstall": "node scripts/postinstall.mjs",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test",
+    "test": "node test/effort.test.mjs && node test/platform.test.mjs && node test/wait.test.mjs && node test/status.test.mjs && node test/output.test.mjs && node test/stream.test.mjs && node test/routing.test.mjs && node test/deadlock.test.mjs && node test/handler-validation.test.mjs && node test/index-handler.test.mjs && node test/ruleset.test.mjs && node test/ruleset-exec.test.mjs && node test/ruleset-handler.test.mjs && node test/failover.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-directives.test.mjs && node test/setup-repair.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/mcp-compliance.test.mjs"
+  },
+  "author": "Lexi Blackburn",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Heretyc/subagent-mcp.git"
+  },
+  "homepage": "https://github.com/Heretyc/subagent-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/Heretyc/subagent-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com",
+    "access": "public"
+  }
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// Postinstall banner for subagent-mcp.
+//
+// `npm install -g @heretyc/subagent-mcp` ships only the MCP server + hook
+// assets; it does NOT wire them into Claude Code / Codex. Without feedback the
+// user has no idea an addon landed, let alone that a second step is required.
+// This prints a clear "what installed / what to run next / how to verify"
+// banner so the install is self-explanatory.
+//
+// Rules:
+//   - NEVER fail the install. Any error is swallowed; always exit 0.
+//   - Only speak for a real end-user install. In the dev checkout (src/ present)
+//     stay silent so `npm install` during development isn't noisy.
+//   - Print only — do not mutate vendor config. Wiring is the explicit,
+//     reversible `subagent-mcp setup` step.
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+
+try {
+  // Install root: scripts/postinstall.mjs -> scripts/ -> <root>
+  const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+  // Dev checkout? (src/ only exists in the repo, never in the shipped tarball.)
+  // Stay silent there — the maintainer doesn't need the end-user banner.
+  if (existsSync(join(ROOT, "src"))) process.exit(0);
+
+  let version = "";
+  try {
+    version = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version || "";
+  } catch { /* version is cosmetic */ }
+
+  // Best-effort vendor detection so the banner can say what WILL be wired.
+  // Pure read-only; failures just fall back to "not detected".
+  function has(cmd) {
+    try {
+      execSync(process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`, {
+        stdio: "ignore",
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  const hasClaude = has("claude");
+  const hasCodex = has("codex") || existsSync(join(homedir(), ".codex"));
+
+  const L = [];
+  const line = (s = "") => L.push(s);
+  const bar = "============================================================";
+
+  line();
+  line(bar);
+  line(`  subagent-mcp installed${version ? `  (v${version})` : ""}`);
+  line(bar);
+  line();
+  line("  This is an MCP ADDON for Claude Code CLI and Codex CLI.");
+  line("  It is NOT active yet — one command wires it in.");
+  line();
+  line("  FINISH SETUP  (auto-detects vendors, wires all present):");
+  line();
+  line("      subagent-mcp setup");
+  line();
+  line("  That registers the MCP server AND installs the per-turn");
+  line("  orchestration-mode hooks for every vendor it finds.");
+  line();
+
+  // Detected vendors — concrete, so the user knows what setup will touch.
+  if (hasClaude || hasCodex) {
+    line("  Detected on this machine:");
+    if (hasClaude) line("    - Claude Code CLI  (will get MCP server + UserPromptSubmit hook)");
+    if (hasCodex) line("    - Codex CLI        (will get MCP server + SessionStart/UserPromptSubmit hooks)");
+  } else {
+    line("  No Claude Code or Codex CLI detected yet. Install one,");
+    line("  then run:  subagent-mcp setup");
+  }
+  line();
+
+  line("  AFTER setup — confirm it took effect:");
+  if (hasClaude || !hasCodex) {
+    line("    - Claude Code: restart the session, run /mcp");
+    line("        -> 'subagent-mcp' shows Connected.");
+  }
+  if (hasCodex || !hasClaude) {
+    line("    - Codex CLI:   restart the session, run /hooks");
+    line("        -> TRUST the new subagent-mcp hook.");
+  }
+  line();
+  line("  Preview without changes:   subagent-mcp setup --dry-run");
+  line("  Health check any time:     subagent-mcp doctor");
+  line("  Docs:  https://github.com/Heretyc/subagent-mcp#readme");
+  line(bar);
+  line();
+
+  process.stdout.write(L.join("\n") + "\n");
+} catch {
+  // Never let a banner failure break the install.
+}
+process.exit(0);