opencode-multiagent 0.2.1 → 0.4.0

package/src/opencode-multiagent/hooks.ts

@@ -1,599 +0,0 @@
-import { join } from "node:path";
-
-import type { Hooks } from "@opencode-ai/plugin";
-import { tool as pluginTool } from "@opencode-ai/plugin";
-import type { Config } from "@opencode-ai/sdk";
-
-import {
-  applyBuiltInAgentPolicy,
-  applyPermissionDefaults,
-  compileAgents,
-  compileCommands,
-  type MergedConfig,
-  type MpcPermissionRegistry,
-} from "./compiler.ts";
-
-/**
- * Extends the official SDK Hooks interface with additional hooks that OpenCode
- * supports at runtime but does not yet document in its published types.
- */
-export type ExtendedHooks = Hooks & {
-  /** Called at plugin teardown to release resources. */
-  cleanup?: () => void;
-  /** Inject custom HTTP headers into every LLM request. */
-  "chat.headers"?: (
-    input: { sessionID: string; agent?: unknown },
-    output: { headers: Record<string, string> },
-  ) => Promise<void>;
-  /** Observe or block a command before it is executed. */
-  "command.execute.before"?: (input: {
-    sessionID: string;
-    command: string;
-    arguments: string;
-  }) => Promise<void>;
-  /** Modify a built-in tool's definition (e.g. append policy notes). */
-  "tool.definition"?: (
-    input: { toolID: string },
-    output: { description: string },
-  ) => Promise<void>;
-  /** Inject environment variables into every shell invocation. */
-  "shell.env"?: (
-    input: unknown,
-    output: { env: Record<string, string> },
-  ) => Promise<void>;
-  /** Append text to the system prompt (experimental). */
-  "experimental.chat.system.transform"?: (
-    input: unknown,
-    output: { system: string[] },
-  ) => Promise<void>;
-  /** Mutate the chat message list sent to the LLM (experimental). */
-  "experimental.chat.messages.transform"?: (
-    input: unknown,
-    output: { messages: Array<{ info?: { role?: string }; parts: unknown[] }> },
-  ) => Promise<void>;
-  /** Inject context into session compaction summaries (experimental). */
-  "experimental.session.compacting"?: (
-    input: unknown,
-    output: { context: string[] },
-  ) => Promise<void>;
-  /** Append text to completed LLM responses (experimental). */
-  "experimental.text.complete"?: (
-    input: unknown,
-    output: { text: string },
-  ) => Promise<void>;
-};
-import {
-  bundledAgentsDir,
-  bundledCommandsDir,
-  globalAgentsDir,
-  globalCommandsDir,
-  mcpToolPrefixes,
-  pluginMode,
-  trackedEventTypes,
-} from "./constants.ts";
-import { createFileLockController } from "./file-lock.ts";
-import { note } from "./log.ts";
-import { applyMcpDefaults, loadMcpDefaults } from "./mcp.ts";
-import { blocked, experimentalText, flagged, risky, tokenizedBashBlocked } from "./policy.ts";
-import { createQualityController } from "./quality.ts";
-import { resolveExistingTierReferences } from "./runtime.ts";
-import { loadSkillRegistry } from "./skills.ts";
-import { createMailbox, createMailboxEventHandler } from "./mailbox.ts";
-import { createSupervisionController } from "./supervision.ts";
-import { createTaskManager } from "./task-manager.ts";
-import { createTeamManager, loadTeamProfiles } from "./team-manager.ts";
-import { createTeamTools } from "./team-tools.ts";
-import { createTelemetryController } from "./telemetry.ts";
-import { clip, compact, label, text } from "./utils.ts";
-
-type GenericRecord = Record<string, any>;
-
-const isMcpTool = (tool: unknown): tool is string =>
-  typeof tool === "string" && mcpToolPrefixes.some((prefix) => tool.startsWith(prefix));
-
-const qaWarningThreshold = 3;
-const qaWarningCooldownMs = 5 * 60 * 1000;
-
-const getTaskTarget = (args: GenericRecord = {}): string | undefined => {
-  for (const key of ["subagent_type", "agent", "subagent", "type", "name"]) {
-    if (typeof args?.[key] === "string") return args[key];
-  }
-  return undefined;
-};
-
-const matchesMcpPermission = (tool: string, registry?: MpcPermissionRegistry): boolean => {
-  if (!registry) return true;
-  for (const pattern of registry.denied ?? []) {
-    if (pattern.endsWith("*") && tool.startsWith(pattern.slice(0, -1))) return false;
-    if (pattern === tool) return false;
-  }
-  for (const pattern of registry.allowed ?? []) {
-    if (pattern.endsWith("*") && tool.startsWith(pattern.slice(0, -1))) return true;
-    if (pattern === tool) return true;
-  }
-  return registry.fallback === "allow";
-};
-
-export const createPluginHooks = ({
-  client,
-  flags,
-  modelTiers,
-  agentSettings,
-  projectRoot,
-}: {
-  client: any;
-  flags: GenericRecord;
-  modelTiers: Record<string, string>;
-  agentSettings: GenericRecord;
-  projectRoot?: string;
-}): ExtendedHooks => {
-  const projectAgentsDir = projectRoot ? join(projectRoot, ".opencode", "agents") : undefined;
-  const projectCommandsDir = projectRoot ? join(projectRoot, ".opencode", "commands") : undefined;
-  const { handleSupervision, cleanup } = createSupervisionController({ flags, client });
-  const quality = createQualityController({ flags, client });
-  const telemetry = createTelemetryController({ flags });
-  const fileLocks = createFileLockController();
-  const sessionAgentMap = new Map<string, GenericRecord>();
-  const qaDispatchState = new Map<string, { count: number; remindedAt: number }>();
-  let skillRegistry: Map<string, any> | null = null;
-  let mcpDefaults: Record<string, unknown> | null = null;
-  let mcpRegistry: Map<string, MpcPermissionRegistry> | null = null;
-  const taskManager = createTaskManager(projectRoot);
-  void taskManager.load();
-  const mailbox = createMailbox();
-  const teamManager = createTeamManager();
-  /** Tracks parent session ID and agent name for each child session — used by mailboxHandler. */
-  const childMailboxInfo = new Map<string, { parentID: string; agentName: string | null }>();
-  const mailboxHandler = createMailboxEventHandler(mailbox, client, (sid) => childMailboxInfo.get(sid));
-
-  const rememberSession = (sessionID: string | undefined, extra: GenericRecord = {}): void => {
-    if (!sessionID) return;
-    const current = sessionAgentMap.get(sessionID) ?? {};
-    const next = { ...current, ...extra };
-    sessionAgentMap.set(sessionID, next);
-    telemetry.rememberSession(sessionID, next);
-  };
-
-  const trackQaDispatch = async (sessionID: string | undefined, agentInfo: GenericRecord = {}): Promise<void> => {
-    if (!sessionID) return;
-    const state = qaDispatchState.get(sessionID) ?? { count: 0, remindedAt: 0 };
-    state.count += 1;
-    qaDispatchState.set(sessionID, state);
-    if (state.count < qaWarningThreshold || !client?.session?.prompt) return;
-    const now = Date.now();
-    if (now - state.remindedAt < qaWarningCooldownMs) return;
-    state.remindedAt = now;
-    try {
-      await client.session.prompt({
-        path: { id: sessionID },
-        body: {
-          noReply: true,
-          parts: [
-            {
-              type: "text",
-              text:
-                `[opencode-multiagent qa] This session has dispatched QA ${state.count} times. ` +
-                "Reassess the brief, consider planner repair, or narrow the defect before sending QA again.",
-            },
-          ],
-        },
-      });
-    } catch {
-      return;
-    }
-    await note("qa_counter_warning", {
-      observation: true,
-      sessionID,
-      agent: agentInfo.agent,
-      model: agentInfo.model,
-      qa_dispatch_count: state.count,
-    });
-  };
-
-  return {
-    cleanup(): void {
-      cleanup?.();
-      quality.cleanup?.();
-      telemetry.cleanup?.();
-      fileLocks.cleanup?.();
-      teamManager.cleanup();
-      childMailboxInfo.clear();
-    },
-    async event(input: any): Promise<void> {
-      const type = input.event?.type;
-      const props = input.event?.properties ?? {};
-
-      if (flags.observation && trackedEventTypes.has(type)) {
-        await note(
-          "event",
-          compact({
-            event: type,
-            data: compact({
-              sessionID:
-                typeof props.sessionID === "string"
-                  ? props.sessionID
-                  : typeof props.info?.sessionID === "string"
-                    ? props.info.sessionID
-                    : undefined,
-              messageID: typeof props.messageID === "string" ? props.messageID : undefined,
-              partID: typeof props.partID === "string" ? props.partID : undefined,
-              permissionID: typeof props.permissionID === "string" ? props.permissionID : undefined,
-              response: typeof props.response === "string" ? props.response : undefined,
-              file: typeof props.file === "string" ? clip(props.file) : undefined,
-              error: typeof props.error?.message === "string" ? clip(props.error.message) : undefined,
-            }),
-          }),
-        );
-      }
-
-      if (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) {
-          const parent = sessionAgentMap.get(parentID) ?? {};
-          telemetry.trackTaskDispatch(parentID, { agent: parent.agent, model: parent.model });
-          await note("task_dispatch", {
-            observation: true,
-            parent_sessionID: parentID,
-            parent_agent: parent.agent,
-            child_sessionID: childID,
-          });
-          // Track for mailbox delivery and lead notification.
-          childMailboxInfo.set(childID, { parentID, agentName: null });
-          // Mark team member as active if it was registered by team_create.
-          teamManager.setMemberStatus(childID, "active");
-        }
-      }
-
-      if (type === "message.updated") {
-        const sessionID = typeof props.info?.sessionID === "string" ? props.info.sessionID : undefined;
-        const agent = typeof props.info?.agent === "string" ? props.info.agent : undefined;
-        if (sessionID && agent) {
-          rememberSession(sessionID, { agent });
-          // Keep childMailboxInfo agent name up-to-date for lead notifications.
-          const mailboxChild = childMailboxInfo.get(sessionID);
-          if (mailboxChild) mailboxChild.agentName = agent;
-        }
-      }
-
-      if (type === "session.deleted") {
-        const sessionID = typeof props.info?.id === "string" ? props.info.id : typeof props.sessionID === "string" ? props.sessionID : undefined;
-        if (sessionID) {
-          sessionAgentMap.delete(sessionID);
-          qaDispatchState.delete(sessionID);
-          fileLocks.releaseAll(sessionID);
-          await telemetry.flushSession(sessionID);
-          teamManager.remove(sessionID);
-          // Note: childMailboxInfo is intentionally NOT cleaned here so that
-          // mailboxHandler (called below) can read the parent info for lead notification.
-        }
-      }
-
-      await handleSupervision(input.event);
-      await quality.handleQualityEvent(input.event);
-      // Deliver pending mailbox messages on idle; notify lead on child session deletion.
-      await mailboxHandler(input.event);
-    },
-
-    async "permission.ask"(input: any, output: any): Promise<void> {
-      if (!flags.enforcement) return;
-      const patternValue = Array.isArray(input.pattern) ? input.pattern.join(" ") : String(input.pattern ?? "");
-      if (["read", "edit", "external_directory"].includes(input.type) && blocked(patternValue)) {
-        output.status = "deny";
-        return;
-      }
-      if (input.type === "bash" && tokenizedBashBlocked(patternValue)) {
-        output.status = "deny";
-      }
-    },
-
-    async "chat.params"(input: any, output: any): Promise<void> {
-      rememberSession(input.sessionID, {
-        agent: label(input.agent),
-        model: label(input.model, ["id", "name", "modelID"]),
-      });
-      if (!flags.observation) return;
-      const marks: string[] = [];
-      if (typeof output.temperature === "number" && output.temperature > 1) marks.push("high_temperature");
-      if (typeof output.topK === "number" && output.topK > 0) marks.push("nonzero_top_k");
-      if (Object.keys(output.options ?? {}).length > 0) marks.push("non_empty_options");
-      await note(
-        "chat_params",
-        compact({
-          observation: true,
-          sessionID: input.sessionID,
-          agent: label(input.agent),
-          provider: compact({
-            source: input.provider?.source,
-            id: label(input.provider?.info, ["id", "name", "providerID"]),
-          }),
-          model: compact({
-            id: label(input.model, ["id", "name", "modelID"]),
-            providerID: label(input.model, ["providerID"]),
-          }),
-          params: compact({
-            temperature: output.temperature,
-            topP: output.topP,
-            topK: output.topK,
-            optionKeys: Object.keys(output.options ?? {}),
-          }),
-          heuristic: marks.length > 0 ? marks : undefined,
-        }),
-      );
-    },
-
-    async "chat.headers"(input: any, output: any): Promise<void> {
-      if (!flags.prompt_controls) return;
-      Object.assign(output.headers, {
-        "x-opencode-multiagent": "1",
-        "x-opencode-multiagent-profile": flags.profile ?? "standard",
-        "x-opencode-agent": label(input.agent) ?? "unknown",
-      });
-    },
-
-    async "chat.message"(input: any, output: any): Promise<void> {
-      if (!flags.prompt_controls || !risky(text(output.parts))) return;
-      await note(
-        "chat_risk",
-        compact({
-          observation: true,
-          sessionID: input.sessionID,
-          agent: label(input.agent),
-          text: clip(text(output.parts)),
-        }),
-      );
-    },
-
-    async "command.execute.before"(input: any): Promise<void> {
-      if (!flags.prompt_controls || !risky(input.arguments)) return;
-      await note(
-        "command_risk",
-        compact({
-          observation: true,
-          sessionID: input.sessionID,
-          command: input.command,
-          arguments: clip(input.arguments),
-        }),
-      );
-    },
-
-    async "experimental.chat.system.transform"(_input: any, output: any): Promise<void> {
-      if (flags.experimental?.chat_system_transform !== true) return;
-      if (output.system.includes(experimentalText)) return;
-      output.system.push(experimentalText);
-    },
-
-    async "experimental.chat.messages.transform"(_input: any, output: any): Promise<void> {
-      if (flags.experimental?.chat_messages_transform !== true) return;
-      const last = [...output.messages].reverse().find((message: any) => message.info?.role === "user");
-      if (!last) return;
-      if (text(last.parts).includes(experimentalText)) return;
-      last.parts.push({ type: "text", text: experimentalText });
-    },
-
-    async "experimental.session.compacting"(_input: any, output: any): Promise<void> {
-      if (flags.experimental?.session_compacting !== true) return;
-      if (output.context.includes(experimentalText)) return;
-      output.context.push(experimentalText);
-    },
-
-    async "experimental.text.complete"(_input: any, output: any): Promise<void> {
-      if (flags.experimental?.text_complete !== true) return;
-      if (output.text.includes(experimentalText)) return;
-      output.text += `\n${experimentalText}`;
-    },
-
-    async config(sdkCfg: Config): Promise<void> {
-      // The SDK delivers Config; we treat it as our superset MergedConfig internally.
-      const cfg = sdkCfg as unknown as MergedConfig;
-      resolveExistingTierReferences(cfg, modelTiers);
-      if (flags.agent_compilation) {
-        mcpRegistry = await compileAgents(cfg, [bundledAgentsDir, globalAgentsDir, projectAgentsDir], modelTiers, agentSettings);
-      }
-      if (flags.command_compilation) {
-        await compileCommands(cfg, [bundledCommandsDir, globalCommandsDir, projectCommandsDir], modelTiers);
-      }
-      if (flags.mcp_compilation !== false) {
-        mcpDefaults ??= await loadMcpDefaults();
-        applyMcpDefaults(cfg, mcpDefaults);
-      }
-      resolveExistingTierReferences(cfg, modelTiers);
-      await applyBuiltInAgentPolicy(cfg);
-      if (flags.compiler?.permission_compilation === true) {
-        applyPermissionDefaults(cfg);
-      }
-      if (flags.skill_injection === true) {
-        skillRegistry ??= await loadSkillRegistry(flags.skill_sources, flags);
-        await note(
-          "skill_injection",
-          compact({
-            observation: true,
-            mode: "available",
-            skills: [...skillRegistry.keys()],
-          }),
-        );
-      }
-    },
-
-    async "tool.execute.before"(input: any, output: any): Promise<void> {
-      const agentInfo = sessionAgentMap.get(input.sessionID) ?? {};
-      const agentName = agentInfo.agent;
-      if (input.tool === "task") {
-        const targetAgent = getTaskTarget(output.args ?? input.args ?? {});
-        if (targetAgent === "qa") {
-          await trackQaDispatch(input.sessionID, agentInfo);
-        }
-      }
-      if (input.tool === "webfetch" && typeof output.args?.url === "string" && output.args.url.startsWith("http://")) {
-        output.args.url = output.args.url.replace("http://", "https://");
-      }
-      if (flags.enforcement && ["read", "edit"].includes(input.tool) && typeof output.args?.filePath === "string" && blocked(output.args.filePath)) {
-        throw new Error("[opencode-multiagent] blocked sensitive path access");
-      }
-      if (flags.enforcement && input.tool === "bash" && typeof output.args?.command === "string" && tokenizedBashBlocked(output.args.command)) {
-        throw new Error("[opencode-multiagent] blocked destructive bash command");
-      }
-      if (input.tool === "edit" && typeof output.args?.filePath === "string") {
-        const lock = fileLocks.acquire(input.sessionID, output.args.filePath);
-        if (!lock.ok) {
-          telemetry.trackPermissionDenied(input.sessionID, { agent: agentName, model: agentInfo.model });
-          await note("permission_denied", {
-            observation: true,
-            sessionID: input.sessionID,
-            agent: agentName,
-            model: agentInfo.model,
-            tool: input.tool,
-            file: lock.filePath,
-            reason: "file_locked_by_other_session",
-            owner_sessionID: lock.ownerSessionID,
-            enforcement_layer: "plugin_hook",
-          });
-          throw new Error(`[opencode-multiagent] File lock conflict for ${lock.filePath}; active session ${lock.ownerSessionID}`);
-        }
-      }
-      if (!flags.enforcement) return;
-      if (isMcpTool(input.tool) && agentName && mcpRegistry?.has(agentName)) {
-        const allowed = matchesMcpPermission(input.tool, mcpRegistry.get(agentName));
-        if (!allowed) {
-          telemetry.trackPermissionDenied(input.sessionID, { agent: agentName, model: agentInfo.model });
-          await note("permission_denied", {
-            observation: true,
-            sessionID: input.sessionID,
-            agent: agentName,
-            model: agentInfo.model,
-            tool: input.tool,
-            reason: "mcp_tool_not_allowed",
-            enforcement_layer: "plugin_hook",
-          });
-          throw new Error(`[opencode-multiagent] MCP tool ${input.tool} not allowed for agent ${agentName}`);
-        }
-      }
-    },
-
-    async "tool.definition"(input: any, output: any): Promise<void> {
-      if (!flags.enforcement) return;
-      if (input.toolID === "bash") {
-        output.description +=
-          "\n\n[Policy] Commands matching destructive patterns (rm -rf /, sudo, shutdown, reboot, git reset --hard, etc.) are blocked by opencode-multiagent.";
-      }
-      if (input.toolID === "read") {
-        output.description +=
-          "\n\n[Policy] Reads targeting sensitive system paths (/etc, /root, /proc, /sys, /dev, /boot, .ssh) are blocked.";
-      }
-      if (input.toolID === "edit") {
-        output.description +=
-          "\n\n[Policy] Edits targeting sensitive system paths (/etc, /root, /proc, /sys, /dev, /boot, .ssh) are blocked.";
-      }
-      if (input.toolID === "webfetch") {
-        output.description += "\n\n[Policy] http:// URLs are automatically upgraded to https://.";
-      }
-    },
-
-    async "shell.env"(_input: any, output: any): Promise<void> {
-      if (!flags.enforcement) return;
-      Object.assign(output.env, {
-        OPENCODE_MULTIAGENT: "1",
-        OPENCODE_MULTIAGENT_MODE: pluginMode,
-        OPENCODE_MULTIAGENT_PROFILE: flags.profile ?? "standard",
-        OPENCODE_CONTROL_PLANE: "1",
-      });
-    },
-
-    async "tool.execute.after"(input: any, output: any): Promise<void> {
-      if (input.tool === "edit" && typeof input.args?.filePath === "string") {
-        quality.trackEdit(input.sessionID, input.args.filePath);
-        telemetry.trackEdit(input.sessionID);
-        fileLocks.acquire(input.sessionID, input.args.filePath);
-      }
-      if (input.tool === "bash" && typeof input.args?.command === "string") {
-        quality.recordQualityEvidence(input.sessionID, input.args.command);
-      }
-      const agentInfo = sessionAgentMap.get(input.sessionID) ?? {};
-      telemetry.trackToolCall(input.sessionID, { agent: agentInfo.agent, model: agentInfo.model });
-      if (typeof output.metadata?.exit === "number" && output.metadata.exit !== 0) {
-        telemetry.trackToolError(input.sessionID, { agent: agentInfo.agent, model: agentInfo.model });
-        await note("tool_error", {
-          observation: true,
-          sessionID: input.sessionID,
-          agent: agentInfo.agent,
-          model: agentInfo.model,
-          tool: input.tool,
-          callID: input.callID,
-          exit_code: output.metadata.exit,
-          error_type: "nonzero_exit",
-          title: clip(output.title),
-          output: clip(output.output),
-        });
-      }
-      if (!flags.observation) return;
-      const lower = `${String(output.title ?? "")}\n${String(output.output ?? "")}`.toLowerCase();
-      const marks = flagged(lower);
-      if (typeof output.metadata?.exit === "number" && output.metadata.exit !== 0) {
-        marks.push("nonzero_exit");
-      }
-      await note(
-        "tool_after",
-        compact({
-          observation: true,
-          tool: input.tool,
-          sessionID: input.sessionID,
-          callID: input.callID,
-          title: clip(output.title),
-          args: input.args,
-          suspicious: marks.length > 0,
-          flags: marks,
-          output: clip(output.output),
-        }),
-      );
-    },
-
-    tool: {
-      ...createTeamTools(mailbox, teamManager, client, loadTeamProfiles),
-
-      task_create: pluginTool({
-        description: "Create a new task in the team task board",
-        args: {
-          title: pluginTool.schema.string().describe("Short title for the task"),
-          description: pluginTool.schema.string().describe("Detailed description of what needs to be done"),
-          assignedAgent: pluginTool.schema.string().optional().describe("Name of the agent to assign this task to"),
-          dependencies: pluginTool.schema
-            .array(pluginTool.schema.string())
-            .optional()
-            .describe("IDs of tasks this task depends on"),
-          priority: pluginTool.schema
-            .enum(["high", "medium", "low"])
-            .optional()
-            .describe("Task priority: high, medium, or low"),
-        },
-        async execute(args, ctx) {
-          return JSON.stringify(taskManager.create({ ...args, createdBy: ctx.agent }));
-        },
-      }),
-
-      task_update: pluginTool({
-        description: "Update a task's status or result on the team task board",
-        args: {
-          taskID: pluginTool.schema.string().describe("ID of the task to update"),
-          status: pluginTool.schema
-            .enum(["pending", "claimed", "in_progress", "completed", "failed", "blocked"])
-            .describe("New status for the task"),
-          result: pluginTool.schema.string().optional().describe("Result summary or notes"),
-        },
-        async execute(args) {
-          return JSON.stringify(taskManager.update(args.taskID, { status: args.status, result: args.result }));
-        },
-      }),
-
-      task_list: pluginTool({
-        description: "List tasks on the team task board with optional filters",
-        args: {
-          status: pluginTool.schema.string().optional().describe("Filter by task status"),
-          assignedAgent: pluginTool.schema.string().optional().describe("Filter by assigned agent name"),
-        },
-        async execute(args) {
-          return JSON.stringify(taskManager.list(args));
-        },
-      }),
-    },
-  };
-};

package/src/opencode-multiagent/log.ts

@@ -1,12 +0,0 @@
-import { appendFile, mkdir } from "node:fs/promises";
-
-import { logDirPath, logFilePath } from "./constants.ts";
-
-export const note = async (kind: string, payload: Record<string, unknown>): Promise<void> => {
-  try {
-    await mkdir(logDirPath, { recursive: true });
-    await appendFile(logFilePath, `${JSON.stringify({ ts: Date.now(), kind, ...payload })}\n`);
-  } catch {
-    // Logging is best-effort.
-  }
-};