opencode-multiagent 0.2.0

package/src/opencode-multiagent/skills.ts

@@ -0,0 +1,144 @@
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { packageRoot } from "./constants.ts";
+import { note } from "./log.ts";
+
+type SkillManifest = {
+  name: string;
+  triggers: string[];
+  applicable_agents: string[];
+  max_context_tokens: number;
+  entry_file?: string;
+};
+
+type SkillEntry = {
+  path: string;
+  manifest: SkillManifest;
+  content: string;
+};
+
+const resolveSource = (value: unknown): string =>
+  String(value ?? "")
+    .replaceAll("${plugin_root}", packageRoot)
+    .replaceAll("${home}", homedir());
+
+const uniqueSources = (sources: unknown[]): string[] =>
+  [...new Set((sources ?? []).map(resolveSource).filter(Boolean).map((value) => resolve(value)))];
+
+const isStringArray = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((item) => typeof item === "string" && item.trim().length > 0);
+
+const normalizeManifest = (manifest: SkillManifest): SkillManifest => ({
+  ...manifest,
+  entry_file: typeof manifest.entry_file === "string" && manifest.entry_file.trim() ? manifest.entry_file : "SKILL.md",
+  triggers: manifest.triggers.map((trigger) => trigger.toLowerCase().trim()),
+  applicable_agents: manifest.applicable_agents.map((agent) => agent.trim()),
+});
+
+const validManifest = (manifest: unknown): manifest is SkillManifest => {
+  if (!manifest || typeof manifest !== "object") return false;
+  const candidate = manifest as SkillManifest;
+  if (typeof candidate.name !== "string" || candidate.name.trim().length === 0) return false;
+  if (!isStringArray(candidate.triggers)) return false;
+  if (!isStringArray(candidate.applicable_agents)) return false;
+  if (typeof candidate.max_context_tokens !== "number" || candidate.max_context_tokens <= 0) return false;
+  if (candidate.entry_file != null && (typeof candidate.entry_file !== "string" || candidate.entry_file.trim().length === 0)) {
+    return false;
+  }
+  return true;
+};
+
+export async function loadSkillRegistry(sources: unknown[], flags: Record<string, unknown> = {}): Promise<Map<string, SkillEntry>> {
+  const registry = new Map<string, SkillEntry>();
+
+  for (const source of uniqueSources(sources)) {
+    const entries = await readdir(source, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries.filter((item) => item.isDirectory()).sort((left, right) => left.name.localeCompare(right.name))) {
+      const skillDir = join(source, entry.name);
+      const manifestPath = join(skillDir, "manifest.json");
+      const manifest = await readFile(manifestPath, "utf8")
+        .then((value) => JSON.parse(value) as unknown)
+        .catch(async () => {
+          await note("skill_registry_warning", {
+            observation: flags.observation === true,
+            warning: "invalid_manifest",
+            source: skillDir,
+          });
+          return null;
+        });
+      if (!validManifest(manifest)) {
+        if (manifest !== null) {
+          await note("skill_registry_warning", {
+            observation: flags.observation === true,
+            warning: "invalid_manifest",
+            source: skillDir,
+          });
+        }
+        continue;
+      }
+
+      const normalized = normalizeManifest(manifest);
+      if (registry.has(normalized.name)) {
+        await note("skill_registry_warning", {
+          observation: flags.observation === true,
+          warning: "duplicate_skill",
+          skill: normalized.name,
+          source: skillDir,
+        });
+        continue;
+      }
+
+      const content = await readFile(join(skillDir, normalized.entry_file!), "utf8").catch(async () => {
+        await note("skill_registry_warning", {
+          observation: flags.observation === true,
+          warning: "invalid_skill_content",
+          skill: normalized.name,
+          source: skillDir,
+        });
+        return null;
+      });
+      if (typeof content !== "string" || content.trim().length === 0) continue;
+
+      registry.set(normalized.name, {
+        path: skillDir,
+        manifest: normalized,
+        content: content.trim(),
+      });
+    }
+  }
+
+  if (registry.size === 0) {
+    await note("skill_registry_warning", {
+      observation: flags.observation === true,
+      warning: "empty_registry",
+    });
+  }
+
+  return registry;
+}
+
+export function findSkillsForTask(registry: Map<string, SkillEntry>, taskText: unknown, agentName: unknown): SkillEntry[] {
+  const text = String(taskText ?? "").toLowerCase();
+  const agent = String(agentName ?? "").trim();
+  const matches: Array<{ score: number; skill: SkillEntry }> = [];
+
+  for (const skill of registry.values()) {
+    if (!skill.manifest.applicable_agents.includes(agent)) continue;
+    const score = skill.manifest.triggers.reduce((count, trigger) => count + (text.includes(trigger) ? 1 : 0), 0);
+    if (score === 0) continue;
+    matches.push({ score, skill });
+  }
+
+  return matches
+    .sort((left, right) => right.score - left.score || left.skill.manifest.name.localeCompare(right.skill.manifest.name))
+    .slice(0, 3)
+    .map((entry) => entry.skill);
+}
+
+export function injectSkills(skills: SkillEntry[] = []): string {
+  const entries = skills.filter((skill) => typeof skill?.content === "string" && skill.content.trim().length > 0);
+  if (entries.length === 0) return "";
+  return entries.map((skill) => `## Skill: ${skill.manifest.name}\n${skill.content.trim()}`).join("\n\n");
+}

package/src/opencode-multiagent/supervision.ts

@@ -0,0 +1,156 @@
+import { supervisionEventTypes } from "./constants.ts";
+import { note } from "./log.ts";
+
+const cleanupIntervalMs = 5 * 60 * 1000;
+const staleChildTtlMs = 30 * 60 * 1000;
+const maxTrackedChildren = 100;
+const evictionFraction = 0.2;
+
+type ChildInfo = {
+  parentID: string;
+  agentName: string | null;
+  lastActivity: number;
+  remindedAt: number;
+};
+
+type PromptClient = {
+  session?: {
+    prompt?: (options: {
+      path: { id: string };
+      body?: { parts: Array<{ type: string; text: string }>; noReply?: boolean };
+    }) => Promise<unknown>;
+  };
+};
+
+export const createSupervisionController = ({ flags, client }: { flags: Record<string, any>; client: PromptClient }) => {
+  const childMap = new Map<string, Set<string>>();
+  const childInfo = new Map<string, ChildInfo>();
+
+  const removeChild = (childID: string): boolean => {
+    const info = childInfo.get(childID);
+    if (!info) return false;
+    childInfo.delete(childID);
+    const children = childMap.get(info.parentID);
+    if (!children) return true;
+    children.delete(childID);
+    if (children.size === 0) childMap.delete(info.parentID);
+    return true;
+  };
+
+  const cleanupStaleChildren = (now = Date.now()): void => {
+    for (const [childID, info] of childInfo.entries()) {
+      if (now - info.lastActivity > staleChildTtlMs) removeChild(childID);
+    }
+  };
+
+  const evictOldestChildren = (count: number): void => {
+    if (count <= 0) return;
+    const childIDs = [...childInfo.entries()]
+      .sort((left, right) => left[1].lastActivity - right[1].lastActivity)
+      .slice(0, count)
+      .map(([childID]) => childID);
+    for (const childID of childIDs) removeChild(childID);
+  };
+
+  const enforceChildLimit = (): void => {
+    if (childInfo.size <= maxTrackedChildren) return;
+    evictOldestChildren(Math.max(1, Math.ceil(childInfo.size * evictionFraction)));
+  };
+
+  let interval: ReturnType<typeof setInterval> | null = null;
+  if (flags.supervision) {
+    interval = setInterval(() => {
+      cleanupStaleChildren();
+    }, cleanupIntervalMs);
+    interval.unref?.();
+  }
+
+  const cleanup = (): void => {
+    if (!interval) return;
+    clearInterval(interval);
+    interval = null;
+  };
+
+  const handleSupervision = async (event: { type?: string; properties?: any }): Promise<void> => {
+    if (!flags.supervision || !supervisionEventTypes.has(event?.type ?? "")) return;
+    const props = event.properties ?? {};
+
+    if (event.type === "session.created") {
+      const parentID = typeof props.info?.parentID === "string" ? props.info.parentID : undefined;
+      const childID =
+        typeof props.sessionID === "string" ? props.sessionID : typeof props.info?.id === "string" ? props.info.id : undefined;
+      if (!parentID || !childID) return;
+      removeChild(childID);
+      if (!childMap.has(parentID)) childMap.set(parentID, new Set());
+      childMap.get(parentID)?.add(childID);
+      childInfo.set(childID, {
+        parentID,
+        agentName: null,
+        lastActivity: Date.now(),
+        remindedAt: 0,
+      });
+      enforceChildLimit();
+      await note("supervision", { event: "child_tracked", parentID, childID });
+      return;
+    }
+
+    if (["message.updated", "message.part.updated", "message.part.delta"].includes(event.type ?? "")) {
+      const sessionID =
+        event.type === "message.updated"
+          ? typeof props.info?.sessionID === "string"
+            ? props.info.sessionID
+            : undefined
+          : event.type === "message.part.updated"
+            ? typeof props.part?.sessionID === "string"
+              ? props.part.sessionID
+              : undefined
+            : typeof props.sessionID === "string"
+              ? props.sessionID
+              : undefined;
+      if (!sessionID || !childInfo.has(sessionID)) return;
+      const info = childInfo.get(sessionID)!;
+      info.lastActivity = Date.now();
+      if (event.type === "message.updated" && props.info?.role === "assistant" && typeof props.info?.agent === "string") {
+        info.agentName = props.info.agent;
+      }
+      return;
+    }
+
+    if (event.type === "session.idle") {
+      const sessionID = typeof props.sessionID === "string" ? props.sessionID : undefined;
+      if (!sessionID || !childInfo.has(sessionID) || !client?.session?.prompt) return;
+      const info = childInfo.get(sessionID)!;
+      const now = Date.now();
+      const idleTimeout = flags.supervision_config?.idle_timeout_ms ?? 180000;
+      const cooldown = flags.supervision_config?.cooldown_ms ?? 300000;
+      if (now - info.lastActivity < idleTimeout || now - info.remindedAt < cooldown) return;
+      info.remindedAt = now;
+      const reminderText =
+        `[opencode-multiagent supervision] Child session ${sessionID} ` +
+        `(agent: ${info.agentName ?? "unknown"}) has been idle. Check status or resume if needed.`;
+      try {
+        await client.session.prompt({
+          path: { id: info.parentID },
+          body: { parts: [{ type: "text", text: reminderText }], noReply: true },
+        });
+      } catch {
+        return;
+      }
+      await note("supervision", {
+        event: "idle_reminder",
+        parentID: info.parentID,
+        childID: sessionID,
+        agentName: info.agentName,
+      });
+      return;
+    }
+
+    if (event.type === "session.deleted") {
+      const sessionID = typeof props.info?.id === "string" ? props.info.id : undefined;
+      if (!sessionID || !removeChild(sessionID)) return;
+      await note("supervision", { event: "child_removed", sessionID });
+    }
+  };
+
+  return { handleSupervision, cleanup };
+};

package/src/opencode-multiagent/task-manager.ts

@@ -0,0 +1,148 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export type TaskStatus = "pending" | "claimed" | "in_progress" | "completed" | "failed" | "blocked";
+export type TaskPriority = "high" | "medium" | "low";
+
+export type Task = {
+  id: string;
+  title: string;
+  description: string;
+  status: TaskStatus;
+  priority: TaskPriority;
+  assignedAgent?: string;
+  claimedBy?: string;
+  createdBy?: string;
+  dependencies: string[];
+  result?: string;
+  createdAt: number;
+  updatedAt: number;
+};
+
+export type CreateTaskInput = {
+  title: string;
+  description: string;
+  assignedAgent?: string;
+  dependencies?: string[];
+  priority?: TaskPriority;
+  createdBy?: string;
+};
+
+export type UpdateTaskInput = {
+  status?: TaskStatus;
+  result?: string;
+  assignedAgent?: string;
+};
+
+export type TaskFilter = {
+  status?: string;
+  assignedAgent?: string;
+};
+
+let taskCounter = 0;
+
+const generateTaskID = (): string => {
+  taskCounter += 1;
+  return `T-${Date.now()}-${taskCounter.toString().padStart(4, "0")}`;
+};
+
+/**
+ * In-memory task board with optional JSON persistence under .magent/tasks/taskboard.json.
+ * All mutating operations fire-and-forget a persist() call — failures are non-fatal.
+ */
+export const createTaskManager = (projectRoot?: string) => {
+  const tasks = new Map<string, Task>();
+  const boardPath = projectRoot ? join(projectRoot, ".magent", "tasks", "taskboard.json") : undefined;
+
+  const persist = async (): Promise<void> => {
+    if (!boardPath) return;
+    try {
+      await mkdir(join(boardPath, ".."), { recursive: true });
+      await writeFile(boardPath, JSON.stringify([...tasks.values()], null, 2), "utf8");
+    } catch {
+      // non-fatal
+    }
+  };
+
+  const load = async (): Promise<void> => {
+    if (!boardPath) return;
+    try {
+      const raw = await readFile(boardPath, "utf8");
+      const items = JSON.parse(raw) as Task[];
+      for (const item of items) tasks.set(item.id, item);
+    } catch {
+      // non-fatal — board may not exist yet
+    }
+  };
+
+  const create = (input: CreateTaskInput): Task => {
+    const task: Task = {
+      id: generateTaskID(),
+      title: input.title,
+      description: input.description,
+      status: "pending",
+      priority: input.priority ?? "medium",
+      assignedAgent: input.assignedAgent,
+      createdBy: input.createdBy,
+      dependencies: input.dependencies ?? [],
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+    tasks.set(task.id, task);
+    void persist();
+    return task;
+  };
+
+  const get = (taskID: string): Task | undefined => tasks.get(taskID);
+
+  const update = (taskID: string, input: UpdateTaskInput): Task => {
+    const task = tasks.get(taskID);
+    if (!task) throw new Error(`Task ${taskID} not found`);
+    if (input.status !== undefined) task.status = input.status;
+    if (input.result !== undefined) task.result = input.result;
+    if (input.assignedAgent !== undefined) task.assignedAgent = input.assignedAgent;
+    task.updatedAt = Date.now();
+    void persist();
+    return task;
+  };
+
+  const claim = (taskID: string, sessionID: string): Task => {
+    const task = tasks.get(taskID);
+    if (!task) throw new Error(`Task ${taskID} not found`);
+    task.claimedBy = sessionID;
+    task.status = "claimed";
+    task.updatedAt = Date.now();
+    void persist();
+    return task;
+  };
+
+  const complete = (taskID: string, result?: string): Task => {
+    const task = tasks.get(taskID);
+    if (!task) throw new Error(`Task ${taskID} not found`);
+    task.status = "completed";
+    if (result !== undefined) task.result = result;
+    task.updatedAt = Date.now();
+    void persist();
+    return task;
+  };
+
+  const list = (filter?: TaskFilter): Task[] => {
+    const all = [...tasks.values()];
+    if (!filter) return all;
+    return all.filter((task) => {
+      if (filter.status && task.status !== filter.status) return false;
+      if (filter.assignedAgent && task.assignedAgent !== filter.assignedAgent) return false;
+      return true;
+    });
+  };
+
+  const getDependencyReady = (taskID: string): boolean => {
+    const task = tasks.get(taskID);
+    if (!task) return false;
+    return task.dependencies.every((depID) => tasks.get(depID)?.status === "completed");
+  };
+
+  return { create, get, update, claim, complete, list, getDependencyReady, persist, load };
+};
+
+export type TaskManager = ReturnType<typeof createTaskManager>;

package/src/opencode-multiagent/team-manager.ts

@@ -0,0 +1,219 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { packageRoot } from "./constants.ts";
+import { note } from "./log.ts";
+
+// ---------------------------------------------------------------------------
+// Team member types
+// ---------------------------------------------------------------------------
+
+export type TeamMemberStatus = "spawning" | "active" | "idle" | "done" | "error";
+
+export type TeamMember = {
+  name: string;
+  sessionID: string;
+  agent: string;
+  role?: string;
+  status: TeamMemberStatus;
+  spawnedAt: number;
+};
+
+export type TeamStatus = {
+  leadSessionID: string | null;
+  memberCount: number;
+  members: Array<{
+    name: string;
+    sessionID: string;
+    agent: string;
+    role?: string;
+    status: TeamMemberStatus;
+  }>;
+};
+
+// ---------------------------------------------------------------------------
+// Team profile types (defaults/team-profiles.json schema)
+// ---------------------------------------------------------------------------
+
+export type TeamProfileMember = {
+  name: string;
+  agent: string;
+  role?: string;
+  /** When true the member is spawned automatically when the profile is activated. */
+  auto_spawn: boolean;
+  /** Initial prompt injected into the session when auto_spawn is true. */
+  initial_prompt?: string;
+};
+
+export type TeamProfile = {
+  description: string;
+  members: TeamProfileMember[];
+};
+
+export type TeamProfileRegistry = Record<string, TeamProfile>;
+
+// ---------------------------------------------------------------------------
+// Profile loader (mirrors loadMcpDefaults pattern)
+// ---------------------------------------------------------------------------
+
+const profilesFilePath = join(packageRoot, "defaults", "team-profiles.json");
+let cachedProfiles: TeamProfileRegistry | undefined;
+
+/**
+ * Load team profiles from `defaults/team-profiles.json`.
+ * Results are cached after the first successful read.
+ */
+export const loadTeamProfiles = async (): Promise<TeamProfileRegistry> => {
+  if (cachedProfiles) return cachedProfiles;
+  try {
+    const parsed = JSON.parse(await readFile(profilesFilePath, "utf8")) as TeamProfileRegistry;
+    cachedProfiles = parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    cachedProfiles = {};
+    await note("config_warning", {
+      observation: true,
+      warning: "team_profiles_unreadable",
+      path: profilesFilePath,
+    });
+  }
+  return cachedProfiles;
+};
+
+// ---------------------------------------------------------------------------
+// TeamManager factory
+// ---------------------------------------------------------------------------
+
+/**
+ * In-memory registry of team members for a single lead session.
+ *
+ * The lead session ID is set lazily on the first `register()` call that
+ * provides a `leadSessionID`, so the manager can be constructed before the
+ * lead session is known.
+ *
+ * @example
+ * ```ts
+ * const tm = createTeamManager();
+ * tm.setLead(ctx.sessionID);
+ * const member = tm.register("backend-dev", {
+ *   sessionID: "child-123",
+ *   agent: "backend-dev",
+ *   status: "spawning",
+ * });
+ * ```
+ */
+export const createTeamManager = () => {
+  let leadSessionID: string | null = null;
+  /** name → member */
+  const members = new Map<string, TeamMember>();
+  /** sessionID → member name (reverse index) */
+  const sessionIndex = new Map<string, string>();
+
+  /** Set the lead session ID (idempotent — first caller wins). */
+  const setLead = (sessionID: string): void => {
+    if (!leadSessionID) leadSessionID = sessionID;
+  };
+
+  /**
+   * Register a new team member.  Overwrites any existing entry with the same name.
+   */
+  const register = (
+    name: string,
+    info: { sessionID: string; agent: string; role?: string; status?: TeamMemberStatus },
+  ): TeamMember => {
+    // Remove stale index entry if the name was previously registered.
+    const existing = members.get(name);
+    if (existing) sessionIndex.delete(existing.sessionID);
+
+    const member: TeamMember = {
+      name,
+      sessionID: info.sessionID,
+      agent: info.agent,
+      role: info.role,
+      status: info.status ?? "spawning",
+      spawnedAt: Date.now(),
+    };
+    members.set(name, member);
+    sessionIndex.set(info.sessionID, name);
+    return member;
+  };
+
+  /** Look up a member by their logical team name. */
+  const getMemberByName = (name: string): TeamMember | undefined => members.get(name);
+
+  /** Look up a member by their OpenCode session ID. */
+  const getMemberBySessionID = (sessionID: string): TeamMember | undefined => {
+    const name = sessionIndex.get(sessionID);
+    return name ? members.get(name) : undefined;
+  };
+
+  /**
+   * Update the status of a member identified by session ID.
+   * No-op if the session ID is not tracked.
+   */
+  const setMemberStatus = (sessionID: string, status: TeamMemberStatus): void => {
+    const member = getMemberBySessionID(sessionID);
+    if (member) member.status = status;
+  };
+
+  /**
+   * Remove a member by their session ID.
+   * Called when a child session is deleted.
+   */
+  const remove = (sessionID: string): void => {
+    const name = sessionIndex.get(sessionID);
+    if (!name) return;
+    sessionIndex.delete(sessionID);
+    members.delete(name);
+  };
+
+  /**
+   * Resolve an agent name or raw session ID to a canonical session ID.
+   *
+   * - If the string matches a known member name → return that member's sessionID.
+   * - If the string is itself a tracked sessionID → return it unchanged.
+   * - Otherwise → return `undefined` (caller should treat the value as a raw ID).
+   */
+  const resolveSessionID = (nameOrSessionID: string): string | undefined => {
+    const byName = members.get(nameOrSessionID);
+    if (byName) return byName.sessionID;
+    if (sessionIndex.has(nameOrSessionID)) return nameOrSessionID;
+    return undefined;
+  };
+
+  /** Return a snapshot of the current team state. */
+  const getStatus = (): TeamStatus => ({
+    leadSessionID,
+    memberCount: members.size,
+    members: [...members.values()].map(({ name, sessionID, agent, role, status }) => ({
+      name,
+      sessionID,
+      agent,
+      role,
+      status,
+    })),
+  });
+
+  /** Release all in-memory state. Call on plugin teardown. */
+  const cleanup = (): void => {
+    members.clear();
+    sessionIndex.clear();
+    leadSessionID = null;
+  };
+
+  return {
+    get leadSessionID() {
+      return leadSessionID;
+    },
+    setLead,
+    register,
+    getMemberByName,
+    getMemberBySessionID,
+    setMemberStatus,
+    remove,
+    resolveSessionID,
+    getStatus,
+    cleanup,
+  };
+};
+
+export type TeamManager = ReturnType<typeof createTeamManager>;