multiagents 0.1.0

package/orchestrator/session-control.ts

@@ -0,0 +1,343 @@
+// ============================================================================
+// multiagents — Session Control
+// ============================================================================
+// Pause/resume agents, broadcast messages, resolve agent targets, and
+// dispatch control actions for the orchestrator.
+// ============================================================================
+
+import type { Slot } from "../shared/types.ts";
+import type { BrokerClient } from "../shared/broker-client.ts";
+import { log } from "../shared/utils.ts";
+import { resumeAfterGuardrailAdjusted } from "./guardrails.ts";
+import { getTeamStatus, formatTeamStatusForDisplay } from "./progress.ts";
+
+const LOG_PREFIX = "session-ctrl";
+
+/** Result of a control action. */
+export interface ControlResult {
+  status: string;
+  affected?: number;
+  message: string;
+  agents?: any[];
+  warnings?: any[];
+  guardrail?: any;
+}
+
+/**
+ * Main dispatch function for session control actions.
+ */
+export async function controlSession(
+  sessionId: string,
+  action: string,
+  brokerClient: BrokerClient,
+  target?: string,
+  value?: number,
+): Promise<ControlResult> {
+  switch (action) {
+    case "pause_all":
+      return await pauseAll(sessionId, brokerClient);
+
+    case "resume_all":
+      return await resumeAll(sessionId, brokerClient);
+
+    case "pause_agent": {
+      if (!target) return { status: "error", message: "Target agent required for pause_agent" };
+      const slot = await resolveTarget(sessionId, target, brokerClient);
+      if (!slot) return { status: "error", message: `Could not find agent matching "${target}"` };
+      await pauseAgent(sessionId, slot, brokerClient);
+      return { status: "ok", affected: 1, message: `Paused ${slot.display_name ?? `slot ${slot.id}`}` };
+    }
+
+    case "resume_agent": {
+      if (!target) return { status: "error", message: "Target agent required for resume_agent" };
+      const slot = await resolveTarget(sessionId, target, brokerClient);
+      if (!slot) return { status: "error", message: `Could not find agent matching "${target}"` };
+      await resumeAgent(sessionId, slot, brokerClient);
+      return { status: "ok", affected: 1, message: `Resumed ${slot.display_name ?? `slot ${slot.id}`}` };
+    }
+
+    case "extend_budget": {
+      if (value === undefined) return { status: "error", message: "Value required for extend_budget" };
+      // Extend the session_duration guardrail by the given value
+      const guardrails = await brokerClient.getGuardrails(sessionId);
+      const duration = guardrails.find((g) => g.id === "session_duration");
+      if (!duration) return { status: "error", message: "Session duration guardrail not found" };
+
+      const newValue = duration.current_value + value;
+      const updated = await brokerClient.updateGuardrail({
+        session_id: sessionId,
+        guardrail_id: "session_duration",
+        new_value: newValue,
+        changed_by: "orchestrator",
+        reason: `Extended by ${value} ${duration.unit}`,
+      });
+
+      // If session was paused due to this guardrail, resume
+      const session = await brokerClient.getSession(sessionId);
+      if (session.status === "paused" && session.pause_reason?.includes("session_duration")) {
+        await resumeAfterGuardrailAdjusted(sessionId, brokerClient);
+      }
+
+      return {
+        status: "ok",
+        message: `Extended session duration to ${newValue} ${duration.unit}`,
+        guardrail: updated,
+      };
+    }
+
+    case "set_budget": {
+      if (!target) return { status: "error", message: "Target guardrail_id required" };
+      if (value === undefined) return { status: "error", message: "Value required for set_budget" };
+
+      const updated = await brokerClient.updateGuardrail({
+        session_id: sessionId,
+        guardrail_id: target,
+        new_value: value,
+        changed_by: "orchestrator",
+      });
+
+      // Check if this resolves a pause
+      const session = await brokerClient.getSession(sessionId);
+      if (session.status === "paused" && session.pause_reason?.includes(target)) {
+        await resumeAfterGuardrailAdjusted(sessionId, brokerClient);
+      }
+
+      return {
+        status: "ok",
+        message: `Set ${target} to ${value}`,
+        guardrail: updated,
+      };
+    }
+
+    case "status": {
+      const teamStatus = await getTeamStatus(sessionId, brokerClient);
+      const display = formatTeamStatusForDisplay(teamStatus);
+      return {
+        status: "ok",
+        message: display,
+        agents: teamStatus.agents,
+        warnings: teamStatus.issues,
+      };
+    }
+
+    default:
+      return { status: "error", message: `Unknown action: ${action}` };
+  }
+}
+
+/**
+ * Pause a single agent slot. Sends a control message, holds future messages.
+ */
+export async function pauseAgent(
+  sessionId: string,
+  slot: Slot,
+  brokerClient: BrokerClient,
+): Promise<void> {
+  // Update slot state
+  await brokerClient.updateSlot({
+    id: slot.id,
+    paused: true,
+    paused_at: Date.now(),
+  });
+
+  // Hold incoming messages
+  await brokerClient.holdMessages(sessionId, slot.id);
+
+  // Release file locks held by this agent
+  try {
+    const locks = await brokerClient.listFileLocks(sessionId);
+    for (const lock of locks) {
+      if (lock.held_by_slot === slot.id) {
+        await brokerClient.releaseFile({
+          session_id: sessionId,
+          peer_id: lock.held_by_peer,
+          file_path: lock.file_path,
+        });
+      }
+    }
+  } catch {
+    // Best-effort lock release
+  }
+
+  // Send control message to the agent
+  if (slot.peer_id) {
+    await brokerClient.sendMessage({
+      from_id: "orchestrator",
+      to_id: slot.peer_id,
+      text: JSON.stringify({ action: "pause", reason: "Paused by orchestrator" }),
+      msg_type: "control",
+      session_id: sessionId,
+    });
+  }
+
+  log(LOG_PREFIX, `Paused agent ${slot.display_name ?? slot.id}`);
+}
+
+/**
+ * Resume a paused agent. Sends resume with any held messages + team changes.
+ */
+export async function resumeAgent(
+  sessionId: string,
+  slot: Slot,
+  brokerClient: BrokerClient,
+): Promise<void> {
+  // Update slot state
+  await brokerClient.updateSlot({
+    id: slot.id,
+    paused: false,
+    paused_at: null,
+  });
+
+  // Release held messages
+  await brokerClient.releaseHeldMessages(sessionId, slot.id);
+
+  // Send resume control message
+  if (slot.peer_id) {
+    await brokerClient.sendMessage({
+      from_id: "orchestrator",
+      to_id: slot.peer_id,
+      text: JSON.stringify({
+        action: "resume",
+        reason: "Resumed by orchestrator",
+      }),
+      msg_type: "control",
+      session_id: sessionId,
+    });
+  }
+
+  log(LOG_PREFIX, `Resumed agent ${slot.display_name ?? slot.id}`);
+}
+
+/**
+ * Resolve a target string to a Slot. Supports matching by:
+ * - Exact slot ID (number)
+ * - Exact display name
+ * - Exact role name
+ * - Partial/fuzzy match on name or role
+ */
+export async function resolveTarget(
+  sessionId: string,
+  target: string,
+  brokerClient: BrokerClient,
+): Promise<Slot | null> {
+  const slots = await brokerClient.listSlots(sessionId);
+  const lower = target.toLowerCase();
+
+  // Try exact slot ID
+  const asNum = parseInt(target, 10);
+  if (!isNaN(asNum)) {
+    const byId = slots.find((s) => s.id === asNum);
+    if (byId) return byId;
+  }
+
+  // Try exact name match
+  const byName = slots.find(
+    (s) => s.display_name?.toLowerCase() === lower,
+  );
+  if (byName) return byName;
+
+  // Try exact role match
+  const byRole = slots.find((s) => s.role?.toLowerCase() === lower);
+  if (byRole) return byRole;
+
+  // Partial match on name
+  const partialName = slots.find(
+    (s) => s.display_name?.toLowerCase().includes(lower),
+  );
+  if (partialName) return partialName;
+
+  // Partial match on role
+  const partialRole = slots.find(
+    (s) => s.role?.toLowerCase().includes(lower),
+  );
+  if (partialRole) return partialRole;
+
+  return null;
+}
+
+/**
+ * Broadcast a message to all connected slots in the session.
+ */
+export async function broadcastToTeam(
+  sessionId: string,
+  message: string,
+  brokerClient: BrokerClient,
+  excludeRoles?: string[],
+): Promise<{ delivered_to: number }> {
+  const slots = await brokerClient.listSlots(sessionId);
+  const excludeSet = new Set((excludeRoles ?? []).map((r) => r.toLowerCase()));
+
+  let deliveredTo = 0;
+
+  for (const slot of slots) {
+    // Skip disconnected or paused agents
+    if (slot.status !== "connected" || slot.paused) continue;
+    if (!slot.peer_id) continue;
+
+    // Skip excluded roles
+    if (slot.role && excludeSet.has(slot.role.toLowerCase())) continue;
+
+    await brokerClient.sendMessage({
+      from_id: "orchestrator",
+      to_id: slot.peer_id,
+      text: message,
+      msg_type: "broadcast",
+      session_id: sessionId,
+    });
+
+    deliveredTo++;
+  }
+
+  log(LOG_PREFIX, `Broadcast to ${deliveredTo} agents`);
+  return { delivered_to: deliveredTo };
+}
+
+/** Pause all agents in a session. */
+async function pauseAll(
+  sessionId: string,
+  brokerClient: BrokerClient,
+): Promise<ControlResult> {
+  await brokerClient.updateSession({
+    id: sessionId,
+    status: "paused",
+    pause_reason: "Paused by orchestrator",
+    paused_at: Date.now(),
+  });
+
+  const slots = await brokerClient.listSlots(sessionId);
+  let affected = 0;
+
+  for (const slot of slots) {
+    if (slot.status === "connected" && !slot.paused) {
+      await pauseAgent(sessionId, slot, brokerClient);
+      affected++;
+    }
+  }
+
+  return { status: "ok", affected, message: `Paused ${affected} agents` };
+}
+
+/** Resume all agents in a session. */
+async function resumeAll(
+  sessionId: string,
+  brokerClient: BrokerClient,
+): Promise<ControlResult> {
+  await brokerClient.updateSession({
+    id: sessionId,
+    status: "active",
+    pause_reason: null,
+    paused_at: null,
+  });
+
+  const slots = await brokerClient.listSlots(sessionId);
+  let affected = 0;
+
+  for (const slot of slots) {
+    if (slot.paused) {
+      await resumeAgent(sessionId, slot, brokerClient);
+      affected++;
+    }
+  }
+
+  return { status: "ok", affected, message: `Resumed ${affected} agents` };
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "multiagents",
+  "version": "0.1.0",
+  "description": "Multi-agent orchestration platform for Claude Code, Codex CLI, and Gemini CLI",
+  "module": "index.ts",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "multiagents": "./cli.ts",
+    "multiagents-server": "./server.ts",
+    "multiagents-orch": "./orchestrator/orchestrator-server.ts",
+    "multiagents-broker": "./broker.ts"
+  },
+  "files": [
+    "cli.ts",
+    "server.ts",
+    "broker.ts",
+    "index.ts",
+    "noop-mcp.ts",
+    "shared/",
+    "adapters/",
+    "orchestrator/",
+    "cli/",
+    ".mcp.json",
+    "README.md",
+    "LICENSE",
+    "tsconfig.json",
+    "scripts/"
+  ],
+  "scripts": {
+    "broker": "bun broker.ts",
+    "server": "bun server.ts",
+    "orchestrator": "bun orchestrator/orchestrator-server.ts",
+    "setup": "bun cli.ts setup",
+    "dashboard": "bun cli.ts dashboard",
+    "test": "bun test",
+    "version:patch": "bun run scripts/version.ts patch",
+    "version:minor": "bun run scripts/version.ts minor",
+    "version:major": "bun run scripts/version.ts major",
+    "prepack": "bun test",
+    "postinstall": "bun run scripts/postinstall.ts 2>/dev/null || true"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.12"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zetbrush/multiagents"
+  },
+  "keywords": [
+    "mcp",
+    "multi-agent",
+    "claude",
+    "codex",
+    "gemini",
+    "orchestration",
+    "ai-agents"
+  ],
+  "license": "MIT",
+  "author": "Arman Andreasyan"
+}

package/scripts/postinstall.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env bun
+/**
+ * Post-install script: auto-configures MCP servers for Claude Code.
+ *
+ * Adds multiagents and multiagents-orch to ~/.claude/.mcp.json
+ * so Claude Code can discover the tools without manual configuration.
+ *
+ * Safe: only adds entries if they don't already exist. Never overwrites.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+const HOME = os.homedir();
+const CLAUDE_DIR = path.join(HOME, ".claude");
+const MCP_JSON = path.join(CLAUDE_DIR, ".mcp.json");
+
+// Resolve the installed package's bin paths
+const PKG_ROOT = path.resolve(import.meta.dir, "..");
+const SERVER_PATH = path.join(PKG_ROOT, "server.ts");
+const ORCH_PATH = path.join(PKG_ROOT, "orchestrator", "orchestrator-server.ts");
+
+// Find bun binary
+function findBun(): string {
+  const bunInPath = Bun.spawnSync(["which", "bun"]).stdout.toString().trim();
+  if (bunInPath) return bunInPath;
+  const defaultBun = path.join(HOME, ".bun", "bin", "bun");
+  if (fs.existsSync(defaultBun)) return defaultBun;
+  return "bun"; // fallback — hope it's in PATH at runtime
+}
+
+const BUN = findBun();
+
+try {
+  // Ensure ~/.claude/ exists
+  if (!fs.existsSync(CLAUDE_DIR)) {
+    fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+  }
+
+  // Read or create .mcp.json
+  let config: { mcpServers: Record<string, unknown> } = { mcpServers: {} };
+  if (fs.existsSync(MCP_JSON)) {
+    try {
+      config = JSON.parse(fs.readFileSync(MCP_JSON, "utf-8"));
+      if (!config.mcpServers) config.mcpServers = {};
+    } catch {
+      // Corrupted file — back up and recreate
+      fs.copyFileSync(MCP_JSON, MCP_JSON + ".bak");
+      config = { mcpServers: {} };
+    }
+  }
+
+  let changed = false;
+
+  // Add multiagents MCP server
+  if (!config.mcpServers["multiagents"]) {
+    config.mcpServers["multiagents"] = {
+      command: BUN,
+      args: [SERVER_PATH],
+    };
+    changed = true;
+  }
+
+  // Add orchestrator MCP server
+  if (!config.mcpServers["multiagents-orch"]) {
+    config.mcpServers["multiagents-orch"] = {
+      command: BUN,
+      args: [ORCH_PATH],
+    };
+    changed = true;
+  }
+
+  if (changed) {
+    fs.writeFileSync(MCP_JSON, JSON.stringify(config, null, 2) + "\n");
+    console.log("[multiagents] MCP servers configured in ~/.claude/.mcp.json");
+    console.log("  Restart Claude Code to pick up the new tools.");
+  } else {
+    console.log("[multiagents] MCP servers already configured.");
+  }
+} catch (e) {
+  // Postinstall should never fail the install
+  console.error(`[multiagents] postinstall warning: ${e instanceof Error ? e.message : String(e)}`);
+}

package/scripts/version.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env bun
+/**
+ * SemVer version bumper.
+ *
+ * Usage:
+ *   bun run scripts/version.ts patch   # 0.1.0 → 0.1.1
+ *   bun run scripts/version.ts minor   # 0.1.0 → 0.2.0
+ *   bun run scripts/version.ts major   # 0.1.0 → 1.0.0
+ *
+ * What it does:
+ *   1. Bumps version in package.json
+ *   2. Stages package.json
+ *   3. Creates a git commit: "release: vX.Y.Z"
+ *   4. Creates a git tag: vX.Y.Z
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const ROOT = path.resolve(import.meta.dir, "..");
+const PKG_PATH = path.join(ROOT, "package.json");
+
+type BumpType = "patch" | "minor" | "major";
+
+const bump = process.argv[2] as BumpType;
+if (!["patch", "minor", "major"].includes(bump)) {
+  console.error("Usage: bun run scripts/version.ts <patch|minor|major>");
+  process.exit(1);
+}
+
+// Read current version
+const pkg = JSON.parse(fs.readFileSync(PKG_PATH, "utf-8"));
+const [major, minor, patch] = pkg.version.split(".").map(Number);
+
+// Compute new version
+let newVersion: string;
+switch (bump) {
+  case "major":
+    newVersion = `${major + 1}.0.0`;
+    break;
+  case "minor":
+    newVersion = `${major}.${minor + 1}.0`;
+    break;
+  case "patch":
+    newVersion = `${major}.${minor}.${patch + 1}`;
+    break;
+}
+
+// Write
+pkg.version = newVersion;
+fs.writeFileSync(PKG_PATH, JSON.stringify(pkg, null, 2) + "\n");
+
+console.log(`${pkg.version.replace(newVersion, `${major}.${minor}.${patch}`)} → ${newVersion}`);
+
+// Git commit + tag
+const tag = `v${newVersion}`;
+Bun.spawnSync(["git", "add", "package.json"], { cwd: ROOT });
+Bun.spawnSync(["git", "commit", "-m", `release: ${tag}`], { cwd: ROOT });
+Bun.spawnSync(["git", "tag", "-a", tag, "-m", `Release ${tag}`], { cwd: ROOT });
+
+console.log(`Committed and tagged: ${tag}`);
+console.log(`To publish: git push && git push --tags && bun publish`);

package/server.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env bun
+/**
+ * multiagents MCP server — thin dispatcher
+ *
+ * Parses --agent-type from argv and delegates to the appropriate adapter.
+ *
+ * Usage:
+ *   bun server.ts                    # defaults to claude
+ *   bun server.ts --agent-type codex
+ *   bun server.ts --agent-type gemini
+ */
+
+import type { AgentType } from "./shared/types.ts";
+
+const typeFlag = process.argv.indexOf("--agent-type");
+const agentType: AgentType =
+  typeFlag !== -1 && process.argv[typeFlag + 1]
+    ? (process.argv[typeFlag + 1] as AgentType)
+    : "claude";
+
+async function main() {
+  switch (agentType) {
+    case "claude": {
+      const { ClaudeAdapter } = await import("./adapters/claude-adapter.ts");
+      await new ClaudeAdapter().start();
+      break;
+    }
+    case "codex": {
+      const { CodexAdapter } = await import("./adapters/codex-adapter.ts");
+      await new CodexAdapter().start();
+      break;
+    }
+    case "gemini": {
+      const { GeminiAdapter } = await import("./adapters/gemini-adapter.ts");
+      await new GeminiAdapter().start();
+      break;
+    }
+    default: {
+      // For 'custom' or unknown types, fall back to Claude adapter behavior
+      const { ClaudeAdapter } = await import("./adapters/claude-adapter.ts");
+      await new ClaudeAdapter().start();
+      break;
+    }
+  }
+}
+
+main().catch((e) => {
+  console.error(
+    `[multiagents] Fatal: ${e instanceof Error ? e.message : String(e)}`,
+  );
+  process.exit(1);
+});