opencode-multiagent 0.2.1 → 0.4.0

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

@@ -1,359 +0,0 @@
-/**
- * Inter-agent communication and team orchestration tools for opencode-multiagent.
- *
- * Exports `createTeamTools()` — a factory that returns a `{ [key: string]: ToolDefinition }`
- * object ready to be spread into the `tool` field of the plugin `Hooks`.
- *
- * Integration (hooks.ts):
- * ```ts
- * import { createMailbox, createMailboxEventHandler } from "./mailbox.ts";
- * import { createTeamManager, loadTeamProfiles } from "./team-manager.ts";
- * import { createTeamTools } from "./team-tools.ts";
- *
- * const mailbox = createMailbox();
- * const teamManager = createTeamManager();
- *
- * return {
- *   ...createPluginHooks({ client, flags, ... }),
- *   tool: createTeamTools(mailbox, teamManager, client, loadTeamProfiles),
- * };
- * ```
- */
-
-import { tool } from "@opencode-ai/plugin";
-
-import { note } from "./log.ts";
-import type { Mailbox } from "./mailbox.ts";
-import type { TeamManager, TeamProfileRegistry } from "./team-manager.ts";
-
-// ---------------------------------------------------------------------------
-// Client type for team orchestration
-// ---------------------------------------------------------------------------
-
-/**
- * Minimal OpenCode client interface required by team tools.
- * Defines session.create and a richer session.prompt (with optional `agent` field)
- * in addition to the mailbox delivery fallback (promptAsync).
- *
- * The parts array intentionally uses a loose element type so this interface is
- * structurally compatible with MailboxClient (required for mailbox.deliverPending).
- */
-export type TeamClient = {
-  session?: {
-    /** Create a new child session. Returns an object with `data.id`. */
-    create?(options?: {
-      body?: { parentID?: string; title?: string };
-    }): Promise<{ data?: { id: string } | null } | null | undefined>;
-    /** Send a message to a session (typed SDK single-object form). */
-    prompt?(options: {
-      path: { id: string };
-      body: {
-        agent?: string;
-        parts: Array<{ type: string; text?: string; name?: string }>;
-        noReply?: boolean;
-      };
-    }): Promise<unknown>;
-    /** Runtime-only fallback used elsewhere in the plugin. */
-    promptAsync?(input: {
-      sessionID: string;
-      noReply?: boolean;
-      parts: Array<{ type: string; text: string }>;
-    }): Promise<unknown>;
-  };
-};
-
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
-/**
- * Build all team-related custom tools.
- *
- * @param mailbox          Shared mailbox instance (from `createMailbox()`).
- * @param teamManager      Shared team manager (from `createTeamManager()`).
- * @param client           OpenCode client — used for session lifecycle and delivery.
- * @param loadTeamProfiles Async loader for `defaults/team-profiles.json`.
- */
-export const createTeamTools = (
-  mailbox: Mailbox,
-  teamManager: TeamManager,
-  client: TeamClient,
-  loadTeamProfiles: () => Promise<TeamProfileRegistry>,
-) => ({
-  // -------------------------------------------------------------------------
-  // Mailbox: send / read
-  // -------------------------------------------------------------------------
-
-  /**
-   * Send a message to a teammate agent by name or session ID.
-   * Immediate delivery is attempted; falls back to queued delivery on next idle.
-   */
-  team_send_message: tool({
-    description:
-      "Send a message to a teammate agent by agent name or session ID. " +
-      "Use this to communicate task results, status updates, or requests to other agents.",
-    args: {
-      to: tool.schema
-        .string()
-        .describe("Target agent name (e.g. 'backend-dev') or raw session ID"),
-      message: tool.schema.string().describe("Message content to deliver to the target agent"),
-    },
-    async execute(args, ctx) {
-      if (!ctx.sessionID) throw new Error("[opencode-multiagent] team_send_message: missing session ID");
-
-      const targetSessionID = teamManager.resolveSessionID(args.to) ?? args.to;
-      const msg = mailbox.send(ctx.sessionID, targetSessionID, args.message);
-
-      const delivered = await mailbox.deliverPending(targetSessionID, client);
-
-      await note("mailbox_send", {
-        observation: true,
-        from: ctx.sessionID,
-        fromAgent: ctx.agent,
-        to: args.to,
-        targetSessionID,
-        messageID: msg.id,
-        delivered,
-      });
-
-      return delivered > 0
-        ? `Message delivered to ${args.to}.`
-        : `Message queued for ${args.to}. It will be delivered when that agent is next idle.`;
-    },
-  }),
-
-  /**
-   * Read incoming messages. By default returns only unread messages and
-   * marks them as read. Pass `unreadOnly: false` to see the full inbox.
-   */
-  team_read_messages: tool({
-    description:
-      "Read incoming messages from other agents. " +
-      "Returns messages sent to this session and marks them as read.",
-    args: {
-      unreadOnly: tool.schema
-        .boolean()
-        .optional()
-        .default(true)
-        .describe("When true (default) return only unread messages; false returns all messages"),
-    },
-    async execute(args, ctx) {
-      const msgs = args.unreadOnly
-        ? mailbox.getUnread(ctx.sessionID)
-        : mailbox.getAll(ctx.sessionID);
-
-      msgs.forEach((m) => mailbox.markRead(m.id));
-
-      await note("mailbox_read", {
-        observation: true,
-        sessionID: ctx.sessionID,
-        agent: ctx.agent,
-        unreadOnly: args.unreadOnly,
-        count: msgs.length,
-      });
-
-      if (msgs.length === 0) return "No messages.";
-
-      return JSON.stringify(
-        msgs.map((m) => ({
-          id: m.id,
-          from: m.from,
-          content: m.content,
-          timestamp: m.timestamp,
-          delivered: m.delivered,
-        })),
-        null,
-        2,
-      );
-    },
-  }),
-
-  // -------------------------------------------------------------------------
-  // Team orchestration: create / status / spawn profile
-  // -------------------------------------------------------------------------
-
-  /**
-   * Create a new teammate agent session as a child of the current session.
-   *
-   * This tool:
-   * 1. Creates a child session via `client.session.create()`.
-   * 2. Registers the member in the team manager.
-   * 3. Sends the initial prompt to the new session.
-   */
-  team_create: tool({
-    description:
-      "Create a new teammate agent session. " +
-      "The teammate runs as a child of the current session and receives an initial prompt.",
-    args: {
-      name: tool.schema
-        .string()
-        .describe("Logical team name for this member (e.g. 'backend-dev', 'tester')"),
-      agent: tool.schema
-        .string()
-        .describe("OpenCode agent ID to use for this session (e.g. 'backend-dev')"),
-      role: tool.schema
-        .string()
-        .optional()
-        .describe("Human-readable role description for status display"),
-      prompt: tool.schema.string().describe("Initial prompt to send to the new agent session"),
-    },
-    async execute(args, ctx) {
-      if (!client.session?.create) {
-        throw new Error("[opencode-multiagent] team_create: client.session.create is unavailable");
-      }
-
-      // Set this session as the lead (idempotent).
-      teamManager.setLead(ctx.sessionID);
-
-      // 1. Create child session.
-      const result = await client.session.create({
-        body: { parentID: ctx.sessionID, title: `[team] ${args.name}` },
-      });
-      const sessionID = result?.data?.id;
-      if (!sessionID) {
-        throw new Error(`[opencode-multiagent] team_create: failed to create session for "${args.name}"`);
-      }
-
-      // 2. Register in team manager.
-      teamManager.register(args.name, {
-        sessionID,
-        agent: args.agent,
-        role: args.role,
-        status: "spawning",
-      });
-
-      // 3. Send initial prompt to the new session.
-      if (client.session?.prompt) {
-        await client.session.prompt({
-          path: { id: sessionID },
-          body: {
-            agent: args.agent,
-            parts: [{ type: "text", text: args.prompt }],
-            noReply: false,
-          },
-        });
-      }
-
-      await note("team_create", {
-        observation: true,
-        leadSessionID: ctx.sessionID,
-        memberName: args.name,
-        memberSessionID: sessionID,
-        agent: args.agent,
-        role: args.role,
-      });
-
-      return `Teammate "${args.name}" created (session: ${sessionID}).`;
-    },
-  }),
-
-  /**
-   * Return the current team composition and member statuses.
-   */
-  team_status: tool({
-    description:
-      "Show the current team status: lead session, member list, and each member's status.",
-    args: {},
-    async execute(_args, ctx) {
-      const status = teamManager.getStatus();
-
-      await note("team_status", {
-        observation: true,
-        sessionID: ctx.sessionID,
-        memberCount: status.memberCount,
-      });
-
-      return JSON.stringify(status, null, 2);
-    },
-  }),
-
-  /**
-   * Activate a pre-defined team profile from `defaults/team-profiles.json`.
-   *
-   * Members with `auto_spawn: true` are created immediately with their
-   * `initial_prompt`.  Members with `auto_spawn: false` are listed in the
-   * return value so the lead can spawn them manually with `team_create`.
-   */
-  team_spawn_profile: tool({
-    description:
-      "Activate a pre-defined team profile. " +
-      "Members marked auto_spawn:true are created immediately; others are listed for manual spawn.",
-    args: {
-      profile: tool.schema
-        .string()
-        .describe(
-          "Profile name to activate. Available profiles: standard, quick, review, fullstack.",
-        ),
-    },
-    async execute(args, ctx) {
-      const profiles = await loadTeamProfiles();
-      const profileData = profiles[args.profile];
-      if (!profileData) {
-        const available = Object.keys(profiles).join(", ") || "(none)";
-        return `Profile "${args.profile}" not found. Available: ${available}.`;
-      }
-
-      teamManager.setLead(ctx.sessionID);
-
-      const spawned: string[] = [];
-      const pending: string[] = [];
-
-      for (const member of profileData.members) {
-        if (member.auto_spawn && member.initial_prompt) {
-          if (!client.session?.create || !client.session?.prompt) {
-            pending.push(member.name);
-            continue;
-          }
-          try {
-            const result = await client.session.create({
-              body: { parentID: ctx.sessionID, title: `[team] ${member.name}` },
-            });
-            const sessionID = result?.data?.id;
-            if (!sessionID) {
-              pending.push(member.name);
-              continue;
-            }
-            teamManager.register(member.name, {
-              sessionID,
-              agent: member.agent,
-              role: member.role,
-              status: "spawning",
-            });
-            await client.session.prompt({
-              path: { id: sessionID },
-              body: {
-                agent: member.agent,
-                parts: [{ type: "text", text: member.initial_prompt }],
-                noReply: false,
-              },
-            });
-            spawned.push(member.name);
-          } catch {
-            pending.push(member.name);
-          }
-        } else {
-          pending.push(member.name);
-        }
-      }
-
-      await note("team_spawn_profile", {
-        observation: true,
-        leadSessionID: ctx.sessionID,
-        profile: args.profile,
-        spawned,
-        pending,
-      });
-
-      const lines: string[] = [`Profile "${args.profile}" activated.`];
-      if (spawned.length > 0) lines.push(`Auto-spawned: ${spawned.join(", ")}.`);
-      if (pending.length > 0) {
-        lines.push(
-          `Pending manual spawn (use team_create): ${pending.join(", ")}.`,
-        );
-      }
-      return lines.join("\n");
-    },
-  }),
-});
-
-export type TeamTools = ReturnType<typeof createTeamTools>;

package/src/opencode-multiagent/telemetry.ts

@@ -1,124 +0,0 @@
-import { note } from "./log.ts";
-
-const cleanupIntervalMs = 5 * 60 * 1000;
-const staleSessionTtlMs = 30 * 60 * 1000;
-const maxTrackedSessions = 200;
-const evictionFraction = 0.2;
-
-type SessionTelemetryState = {
-  sessionID: string;
-  agent?: string;
-  model?: string;
-  startedAt: number;
-  lastActivityAt: number;
-  toolCalls: number;
-  toolErrors: number;
-  filesEdited: number;
-  tasksDispatched: number;
-  permissionDenied: number;
-};
-
-export const createTelemetryController = ({ flags }: { flags: Record<string, any> }) => {
-  const sessions = new Map<string, SessionTelemetryState>();
-
-  const ensureSession = (sessionID: string | undefined, extra: Partial<SessionTelemetryState> = {}): SessionTelemetryState | null => {
-    if (!sessionID) return null;
-    const now = Date.now();
-    if (!sessions.has(sessionID)) {
-      sessions.set(sessionID, {
-        sessionID,
-        agent: undefined,
-        model: undefined,
-        startedAt: now,
-        lastActivityAt: now,
-        toolCalls: 0,
-        toolErrors: 0,
-        filesEdited: 0,
-        tasksDispatched: 0,
-        permissionDenied: 0,
-        ...extra,
-      });
-    }
-    const state = sessions.get(sessionID)!;
-    Object.assign(state, extra);
-    state.lastActivityAt = now;
-    return state;
-  };
-
-  const cleanupStaleSessions = (now = Date.now()): void => {
-    for (const [sessionID, state] of sessions.entries()) {
-      if (now - state.lastActivityAt > staleSessionTtlMs) sessions.delete(sessionID);
-    }
-  };
-
-  const enforceSessionLimit = (): void => {
-    if (sessions.size <= maxTrackedSessions) return;
-    const toRemove = [...sessions.values()]
-      .sort((left, right) => left.lastActivityAt - right.lastActivityAt)
-      .slice(0, Math.max(1, Math.ceil(sessions.size * evictionFraction)));
-    for (const state of toRemove) sessions.delete(state.sessionID);
-  };
-
-  let interval: ReturnType<typeof setInterval> | null = null;
-  if (flags.telemetry) {
-    interval = setInterval(() => cleanupStaleSessions(), cleanupIntervalMs);
-    interval.unref?.();
-  }
-
-  const cleanup = (): void => {
-    if (!interval) return;
-    clearInterval(interval);
-    interval = null;
-  };
-
-  return {
-    cleanup,
-    rememberSession(sessionID: string | undefined, extra: Partial<SessionTelemetryState> = {}): void {
-      ensureSession(sessionID, extra);
-      enforceSessionLimit();
-    },
-    trackEdit(sessionID: string | undefined): void {
-      const state = ensureSession(sessionID);
-      if (!state) return;
-      state.filesEdited += 1;
-    },
-    trackToolCall(sessionID: string | undefined, extra: Partial<SessionTelemetryState> = {}): void {
-      const state = ensureSession(sessionID, extra);
-      if (!state) return;
-      state.toolCalls += 1;
-    },
-    trackToolError(sessionID: string | undefined, extra: Partial<SessionTelemetryState> = {}): void {
-      const state = ensureSession(sessionID, extra);
-      if (!state) return;
-      state.toolErrors += 1;
-    },
-    trackTaskDispatch(sessionID: string | undefined, extra: Partial<SessionTelemetryState> = {}): void {
-      const state = ensureSession(sessionID, extra);
-      if (!state) return;
-      state.tasksDispatched += 1;
-    },
-    trackPermissionDenied(sessionID: string | undefined, extra: Partial<SessionTelemetryState> = {}): void {
-      const state = ensureSession(sessionID, extra);
-      if (!state) return;
-      state.permissionDenied += 1;
-    },
-    async flushSession(sessionID: string, reason = "session_deleted"): Promise<void> {
-      const state = sessions.get(sessionID);
-      if (!state) return;
-      sessions.delete(sessionID);
-      await note("session_metrics", {
-        observation: true,
-        sessionID,
-        agent: state.agent,
-        model: state.model,
-        duration_ms: Math.max(0, Date.now() - state.startedAt),
-        tool_calls: state.toolCalls,
-        tool_errors: state.toolErrors,
-        files_edited: state.filesEdited,
-        tasks_dispatched: state.tasksDispatched,
-        permission_denied: state.permissionDenied,
-        reason,
-      });
-    },
-  };
-};

package/src/opencode-multiagent/utils.ts

@@ -1,54 +0,0 @@
-export const compact = <T extends Record<string, unknown>>(value: T): Partial<T> =>
-  Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined)) as Partial<T>;
-
-export const clip = (value: unknown, size = 240): string | undefined => {
-  if (typeof value !== "string") return undefined;
-  if (value.length <= size) return value;
-  return `${value.slice(0, size)}...`;
-};
-
-type TextPart = { type?: string; text?: string } | null | undefined;
-
-export const text = (parts: unknown): string =>
-  Array.isArray(parts)
-    ? (parts as TextPart[])
-        .filter((part): part is { type: string; text: string } => Boolean(part) && part?.type === "text" && typeof part?.text === "string")
-        .map((part) => part.text)
-        .join("\n")
-    : "";
-
-export const label = (value: unknown, keys = ["name", "id", "modelID", "providerID"]): string | undefined => {
-  if (typeof value === "string") return value;
-  if (!value || typeof value !== "object") return undefined;
-  const objectValue = value as Record<string, unknown>;
-  for (const key of keys) {
-    if (typeof objectValue[key] === "string") return objectValue[key] as string;
-  }
-  return undefined;
-};
-
-export const own = (value: unknown, key: string): boolean =>
-  Boolean(value) && Object.prototype.hasOwnProperty.call(value, key);
-
-export const clone = <T>(value: T): T => {
-  if (value === undefined) return value;
-  return JSON.parse(JSON.stringify(value)) as T;
-};
-
-export const merge = <T>(base: T, extra: unknown): T => {
-  if (!extra || typeof extra !== "object" || Array.isArray(extra)) {
-    return clone((extra !== undefined ? extra : base) as T);
-  }
-
-  const result: Record<string, unknown> = { ...((base && typeof base === "object" && !Array.isArray(base) ? base : {}) as Record<string, unknown>) };
-
-  for (const [key, value] of Object.entries(extra as Record<string, unknown>)) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-      result[key] = value;
-      continue;
-    }
-    result[key] = merge(result[key], value);
-  }
-
-  return result as T;
-};