multiagents 0.1.0

package/shared/broker-client.ts

@@ -0,0 +1,243 @@
+import type {
+  RegisterRequest,
+  RegisterResponse,
+  HeartbeatRequest,
+  SetSummaryRequest,
+  ListPeersRequest,
+  Peer,
+  SendMessageRequest,
+  SendMessageResult,
+  PollMessagesRequest,
+  PollMessagesResponse,
+  SetRoleRequest,
+  RenamePeerRequest,
+  CreateSessionRequest,
+  Session,
+  UpdateSessionRequest,
+  CreateSlotRequest,
+  Slot,
+  UpdateSlotRequest,
+  AcquireFileRequest,
+  AcquireFileResult,
+  ReleaseFileRequest,
+  AssignOwnershipRequest,
+  FileLock,
+  FileOwnership,
+  GuardrailState,
+  UpdateGuardrailRequest,
+  MessageLogOptions,
+  Message,
+  PeerId,
+  SignalDoneRequest,
+  SubmitFeedbackRequest,
+  ApproveRequest,
+  ReleaseAgentRequest,
+  UnregisterResult,
+} from "./types.ts";
+
+/** HTTP client for the multiagents broker API. */
+export class BrokerClient {
+  constructor(private baseUrl: string) {}
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5000);
+    try {
+      const res = await globalThis.fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => res.statusText);
+        throw new Error(`Broker POST ${path} failed (${res.status}): ${text}`);
+      }
+      return (await res.json()) as T;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async isAlive(): Promise<boolean> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 2000);
+    try {
+      const res = await globalThis.fetch(`${this.baseUrl}/health`, {
+        method: "GET",
+        signal: controller.signal,
+      });
+      return res.ok;
+    } catch {
+      return false;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  register(req: RegisterRequest): Promise<RegisterResponse> {
+    return this.post("/register", req);
+  }
+
+  heartbeat(id: PeerId): Promise<{ ok: boolean }> {
+    return this.post("/heartbeat", { id });
+  }
+
+  setSummary(id: PeerId, summary: string): Promise<{ ok: boolean }> {
+    return this.post("/set-summary", { id, summary });
+  }
+
+  listPeers(req: ListPeersRequest): Promise<Peer[]> {
+    return this.post("/list-peers", req);
+  }
+
+  sendMessage(req: SendMessageRequest): Promise<SendMessageResult> {
+    return this.post("/send-message", req);
+  }
+
+  pollMessages(id: PeerId): Promise<PollMessagesResponse> {
+    return this.post("/poll-messages", { id });
+  }
+
+  unregister(id: PeerId): Promise<UnregisterResult> {
+    return this.post("/unregister", { id });
+  }
+
+  setRole(req: SetRoleRequest): Promise<{ ok: boolean }> {
+    return this.post("/set-role", req);
+  }
+
+  renamePeer(req: RenamePeerRequest): Promise<{ ok: boolean }> {
+    return this.post("/rename-peer", req);
+  }
+
+  createSession(req: CreateSessionRequest): Promise<Session> {
+    return this.post("/sessions/create", req);
+  }
+
+  getSession(id: string): Promise<Session> {
+    return this.post("/sessions/get", { id });
+  }
+
+  listSessions(): Promise<Session[]> {
+    return this.post("/sessions/list", {});
+  }
+
+  updateSession(req: UpdateSessionRequest): Promise<Session> {
+    return this.post("/sessions/update", req);
+  }
+
+  createSlot(req: CreateSlotRequest): Promise<Slot> {
+    return this.post("/slots/create", req);
+  }
+
+  getSlot(id: number): Promise<Slot> {
+    return this.post("/slots/get", { id });
+  }
+
+  listSlots(sessionId: string): Promise<Slot[]> {
+    return this.post("/slots/list", { session_id: sessionId });
+  }
+
+  updateSlot(req: UpdateSlotRequest): Promise<Slot> {
+    return this.post("/slots/update", req);
+  }
+
+  acquireFile(req: AcquireFileRequest): Promise<AcquireFileResult> {
+    return this.post("/files/acquire", req);
+  }
+
+  releaseFile(req: ReleaseFileRequest): Promise<{ ok: boolean }> {
+    return this.post("/files/release", req);
+  }
+
+  assignOwnership(req: AssignOwnershipRequest): Promise<{ ok: boolean }> {
+    return this.post("/files/assign-ownership", req);
+  }
+
+  listFileLocks(sessionId: string): Promise<FileLock[]> {
+    return this.post("/files/locks", { session_id: sessionId });
+  }
+
+  listFileOwnership(sessionId: string): Promise<FileOwnership[]> {
+    return this.post("/files/ownership", { session_id: sessionId });
+  }
+
+  getGuardrails(sessionId: string): Promise<GuardrailState[]> {
+    return this.post("/guardrails", { session_id: sessionId });
+  }
+
+  updateGuardrail(req: UpdateGuardrailRequest): Promise<GuardrailState> {
+    return this.post("/guardrails/update", req);
+  }
+
+  getMessageLog(sessionId: string, opts?: MessageLogOptions): Promise<Message[]> {
+    return this.post("/message-log", { session_id: sessionId, ...opts });
+  }
+
+  holdMessages(sessionId: string, slotId: number): Promise<{ ok: boolean }> {
+    return this.post("/hold-messages", { session_id: sessionId, slot_id: slotId });
+  }
+
+  releaseHeldMessages(sessionId: string, slotId: number): Promise<{ ok: boolean }> {
+    return this.post("/release-held", { session_id: sessionId, slot_id: slotId });
+  }
+
+  logAgentEvent(data: { session_id: string; peer_id: PeerId; slot_id?: number; event_type: string; data?: unknown }): Promise<{ ok: boolean }> {
+    return this.post("/agent-event", data);
+  }
+
+  // --- Lifecycle handoff ---
+
+  signalDone(req: SignalDoneRequest): Promise<{ ok: boolean; task_state: string }> {
+    return this.post("/lifecycle/signal-done", req);
+  }
+
+  submitFeedback(req: SubmitFeedbackRequest): Promise<{ ok: boolean; task_state: string }> {
+    return this.post("/lifecycle/submit-feedback", req);
+  }
+
+  approve(req: ApproveRequest): Promise<{ ok: boolean; task_state: string }> {
+    return this.post("/lifecycle/approve", req);
+  }
+
+  releaseAgent(req: ReleaseAgentRequest): Promise<{ ok: boolean; task_state: string }> {
+    return this.post("/lifecycle/release", req);
+  }
+
+  getTaskState(slotId: number): Promise<{ id: number; task_state: string; display_name: string | null; role: string | null }> {
+    return this.post("/lifecycle/get-task-state", { slot_id: slotId });
+  }
+
+  // --- Plans ---
+
+  createPlan(req: { session_id: string; title: string; items: { label: string; assigned_to_slot?: number }[] }): Promise<PlanState> {
+    return this.post("/plan/create", req);
+  }
+
+  getPlan(sessionId: string): Promise<PlanState> {
+    return this.post("/plan/get", { session_id: sessionId });
+  }
+
+  updatePlanItem(req: { item_id: number; status: string; session_id?: string }): Promise<PlanState | { ok: boolean }> {
+    return this.post("/plan/update-item", req);
+  }
+}
+
+export interface PlanItem {
+  id: number;
+  plan_id: number;
+  parent_id: number | null;
+  label: string;
+  status: "pending" | "in_progress" | "done" | "blocked";
+  assigned_to_slot: number | null;
+  assigned_name: string | null;
+  completed_at: number | null;
+  sort_order: number;
+}
+
+export interface PlanState {
+  plan: { id: number; session_id: string; title: string; created_at: number; updated_at: number } | null;
+  items: PlanItem[];
+  completion: number;
+}

package/shared/constants.ts

@@ -0,0 +1,148 @@
+// ============================================================================
+// multiagents — Constants & Defaults
+// ============================================================================
+
+import type { AgentType, Guardrail } from "./types.ts";
+
+// --- Networking ---
+
+export const DEFAULT_BROKER_PORT = 7899;
+export const DEFAULT_DB_PATH = `${process.env.HOME}/.multiagents/peers.db`;
+export const BROKER_HOSTNAME = "127.0.0.1";
+
+// --- Polling intervals (ms) ---
+
+export const POLL_INTERVALS: Record<AgentType, number> = {
+  claude: 1000, // Claude uses channel push — polling is fallback only
+  codex: 300, // Aggressive: piggyback delivery depends on fast buffering
+  gemini: 300, // Same as Codex — no push capability
+  custom: 500, // Reasonable default for unknown agents
+};
+
+export const HEARTBEAT_INTERVAL = 15_000; // 15s
+export const CLEANUP_INTERVAL = 30_000; // 30s
+export const DASHBOARD_REFRESH = 500; // 500ms
+
+// --- Broker startup ---
+
+export const BROKER_STARTUP_POLL_MS = 200;
+export const BROKER_STARTUP_MAX_ATTEMPTS = 30; // 30 * 200ms = 6s max wait
+export const BROKER_HEALTH_TIMEOUT = 2000; // 2s timeout for health check
+
+// --- File locks ---
+
+export const DEFAULT_LOCK_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+export const MAX_LOCK_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+
+// --- Sessions ---
+
+export const SESSION_DIR = ".multiagents";
+export const SESSION_FILE = ".multiagents/session.json";
+export const RECONNECT_RECAP_LIMIT = 20; // messages to replay on reconnect
+
+// --- Agent ID prefixes ---
+
+export const AGENT_ID_PREFIXES: Record<AgentType, string> = {
+  claude: "cl",
+  codex: "cx",
+  gemini: "gm",
+  custom: "cu",
+};
+
+export const AGENT_ID_LENGTH = 8; // total chars including prefix + hyphen (e.g. "cl-a1b2c3")
+
+// --- Guardrail defaults ---
+
+export const DEFAULT_GUARDRAILS: Guardrail[] = [
+  // --- Monitoring stats (observe-only, no enforcement) ---
+  {
+    id: "session_duration",
+    label: "Session Duration",
+    description: "How long the session has been running",
+    current_value: 0,       // no limit — monitor only
+    default_value: 0,
+    unit: "minutes",
+    scope: "session",
+    action: "monitor",
+    warn_at_percent: 1.0,   // never warns
+    adjustable: false,
+    suggested_increases: [],
+  },
+  {
+    id: "messages_total",
+    label: "Total Messages",
+    description: "Total messages exchanged across all agents",
+    current_value: 0,
+    default_value: 0,
+    unit: "messages",
+    scope: "session",
+    action: "monitor",
+    warn_at_percent: 1.0,
+    adjustable: false,
+    suggested_increases: [],
+  },
+  {
+    id: "messages_per_agent",
+    label: "Messages Per Agent (max)",
+    description: "Highest message count from any single agent",
+    current_value: 0,
+    default_value: 0,
+    unit: "messages",
+    scope: "per_agent",
+    action: "monitor",
+    warn_at_percent: 1.0,
+    adjustable: false,
+    suggested_increases: [],
+  },
+  {
+    id: "agent_count",
+    label: "Active Agents",
+    description: "Currently connected agents",
+    current_value: 0,
+    default_value: 0,
+    unit: "agents",
+    scope: "session",
+    action: "monitor",
+    warn_at_percent: 1.0,
+    adjustable: false,
+    suggested_increases: [],
+  },
+  {
+    id: "idle_max",
+    label: "Longest Idle",
+    description: "Longest time any agent has gone without activity",
+    current_value: 0,
+    default_value: 0,
+    unit: "minutes",
+    scope: "per_agent",
+    action: "monitor",
+    warn_at_percent: 1.0,
+    adjustable: false,
+    suggested_increases: [],
+  },
+  // --- Actual guardrail (enforced) ---
+  {
+    id: "max_restarts",
+    label: "Restart Limit",
+    description:
+      "Stops flapping agents after too many crash-restart cycles",
+    current_value: 5,
+    default_value: 5,
+    unit: "restarts",
+    scope: "per_agent",
+    action: "stop",
+    warn_at_percent: 0.6,
+    adjustable: true,
+    suggested_increases: [8, 12, 20],
+  },
+];
+
+// --- Orchestrator ---
+
+export const STUCK_THRESHOLD_MS = 2 * 60 * 1000; // 2 min — agent considered stuck
+export const SLOW_THRESHOLD_MS = 30 * 1000; // 30s — agent considered slow
+export const NUDGE_WAIT_MS = 30 * 1000; // 30s after nudge before escalating
+export const FLAP_WINDOW_MS = 5 * 60 * 1000; // 5 min window for flap detection
+export const FLAP_THRESHOLD = 3; // crashes in window before declaring flapping
+export const GUARDRAIL_CHECK_INTERVAL = 30_000; // 30s
+export const CONFLICT_CHECK_INTERVAL = 10_000; // 10s

package/shared/summarize.ts

@@ -0,0 +1,97 @@
+// ============================================================================
+// multiagents — Auto-Summary Generation
+// ============================================================================
+// Generates a brief summary of what a developer is working on using git
+// context (branch name, recently modified files). No LLM API calls — fast,
+// free, and no hardcoded model names to maintain.
+// ============================================================================
+
+export interface SummaryContext {
+  cwd: string;
+  git_root: string | null;
+  git_branch?: string | null;
+  recent_files?: string[];
+}
+
+/**
+ * Generate a 1-2 sentence summary of what the agent is working on.
+ * Uses git context only — no external API calls.
+ */
+export async function generateSummary(
+  context: SummaryContext
+): Promise<string> {
+  const parts: string[] = [];
+
+  if (context.git_branch && context.git_branch !== "main" && context.git_branch !== "master") {
+    parts.push(`Branch: ${context.git_branch}`);
+  }
+
+  if (context.recent_files?.length) {
+    const topFiles = context.recent_files.slice(0, 5).join(", ");
+    parts.push(`Files: ${topFiles}`);
+  }
+
+  if (parts.length === 0) {
+    const dirName = context.cwd.split("/").pop() ?? context.cwd;
+    return `Working in ${dirName}`;
+  }
+
+  return parts.join(" | ");
+}
+
+/** Get the current git branch name */
+export async function getGitBranch(cwd: string): Promise<string | null> {
+  try {
+    const proc = Bun.spawn(["git", "rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const text = await new Response(proc.stdout).text();
+    const code = await proc.exited;
+    return code === 0 ? text.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Get recently modified tracked files in the git repo */
+export async function getRecentFiles(
+  cwd: string,
+  limit = 10
+): Promise<string[]> {
+  try {
+    const diffProc = Bun.spawn(["git", "diff", "--name-only", "HEAD"], {
+      cwd,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const diffText = await new Response(diffProc.stdout).text();
+    await diffProc.exited;
+
+    const files = diffText
+      .trim()
+      .split("\n")
+      .filter((f) => f.length > 0);
+
+    if (files.length >= limit) {
+      return files.slice(0, limit);
+    }
+
+    const logProc = Bun.spawn(
+      ["git", "log", "--oneline", "--name-only", "-5", "--format="],
+      { cwd, stdout: "pipe", stderr: "ignore" }
+    );
+    const logText = await new Response(logProc.stdout).text();
+    await logProc.exited;
+
+    const logFiles = logText
+      .trim()
+      .split("\n")
+      .filter((f) => f.length > 0);
+
+    return [...new Set([...files, ...logFiles])].slice(0, limit);
+  } catch {
+    return [];
+  }
+}