agenthub-multiagent-mcp 1.77.0 → 1.78.0

package/dist/tools/index.js

@@ -1,6 +1,7 @@
 /**
  * MCP tool definitions and handlers
  */
+import { AgentHubApiError, } from "../client.js";
 import { resolveAgentIdentity, missingStateGuidance, credentialIsDead, } from "../agentIdentity.js";
 import { boundInbox, resolveInboxLimit, CHECK_INBOX_DEFAULT_LIMIT, CHECK_INBOX_MAX_LIMIT, } from "./inboxBounds.js";
 import * as state from "../state.js";
@@ -20,6 +21,7 @@ import { isWhatsAppTool, runWhatsAppTool, whatsappToolDefinitions } from "./what
 import { installPackFromArchive } from "../skillPackInstaller.js";
 import { getServerTime, useTimeInjection } from "../lib/server-time.js";
 import { getPendingItems } from "../lib/pending-items.js";
+import { brainstormAutoAcceptEnabled, inviteGuidance, } from "../lib/brainstormInvites.js";
 import { ENG_IC_CHARTER } from "../employee.js";
 import { promises as fsp } from "node:fs";
 import * as os from "node:os";
@@ -84,6 +86,19 @@ function backgroundSync(client, agentId, workingDir) {
         }
     })();
 }
+/**
+ * The invite fields every pending-items block carries (check_inbox and the
+ * tool wrapper). The guidance rides along only when there is an invite, so an
+ * empty inbox costs no extra text.
+ */
+function inviteFields(invites) {
+    const list = invites ?? [];
+    return {
+        pending_brainstorm_invites: list,
+        pending_brainstorm_invites_count: list.length,
+        ...(list.length > 0 ? { brainstorm_invite_guidance: inviteGuidance(brainstormAutoAcceptEnabled()) } : {}),
+    };
+}
 /**
  * Wraps a tool response with pending messages and tasks
  * This enables automatic delivery without extra API calls
@@ -161,6 +176,7 @@ async function wrapWithPendingItems(client, agentId, result, context) {
             pending_messages_count: messages.length,
             pending_tasks: tasks,
             pending_tasks_count: tasks.length,
+            ...inviteFields(cachedItems.invites),
             urgent_action: urgentAction,
         };
         if (useTimeInjection()) {
@@ -977,7 +993,7 @@ export function registerTools() {
         },
         {
             name: "skill_pack_install",
-            description: "Install an opt-in skill pack into ~/.claude/skills/. Hash-safe (never overwrites files you've edited unless force=true). Destructive packs (e.g. cybersecurity, which ships offensive PoC scripts) require the skill-pack:<name> capability attached to this agent. Returns a per-file install report.",
+            description: "Install an opt-in skill pack into ~/.claude/skills/. Hash-safe (never overwrites files you've edited unless force=true). On upgrade, files the new version dropped are removed if unedited (removed) and kept if you edited them (kept_modified). Destructive packs (e.g. cybersecurity, which ships offensive PoC scripts) require the skill-pack:<name> capability attached to this agent. Returns a per-file install report.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -990,6 +1006,52 @@ export function registerTools() {
                 required: ["pack"],
             },
         },
+        // add-product-lifecycle-pack §2.1–2.2 — product-lifecycle hard gates.
+        // 503 lifecycle_gates_disabled while AGENTHUB_LIFECYCLE_GATES_ENABLED is off.
+        {
+            name: "lifecycle_gate_request",
+            description: "Open a product-lifecycle hard gate (stage 3, 6, 9 or dvt) on the stage's gate task. Creates a blocking lifecycle_gate review that only an org owner or admin can sign, on the dashboard (/reviews) — not an agent, an API key or a chat button. Returns the review id and status; poll lifecycle_gate_list until it is decided. A second pending gate on the same task is refused (gate_pending). For a re-gate after a stale or revised one, pass parent_review_id.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_id: { type: "string", description: "Project id (defaults to the project this agent is bound to)" },
+                    task_id: { type: "string", description: "The stage's gate task id (must be in project_id)" },
+                    stage: { type: "string", enum: ["3", "6", "9", "dvt"], description: "Hard-gate stage" },
+                    title: { type: "string", description: "Gate title" },
+                    content: { type: "string", description: "The gate pack, as markdown" },
+                    evidence_hash: { type: "string", description: "sha256 of the evidence, 64 lowercase hex characters" },
+                    items: {
+                        type: "array",
+                        description: "The stage's tasks and their verdicts",
+                        items: {
+                            type: "object",
+                            properties: {
+                                task_id: { type: "string" },
+                                status: { type: "string" },
+                                verdict: { type: "string" },
+                                refs: { type: "array", items: { type: "string" }, description: "Evidence refs (PRs, docs, runs)" },
+                            },
+                            required: ["task_id", "status", "verdict"],
+                        },
+                    },
+                    parent_review_id: { type: "string", description: "Earlier lifecycle_gate on the same task this one supersedes" },
+                },
+                required: ["task_id", "stage", "title", "content", "evidence_hash", "items"],
+            },
+        },
+        {
+            name: "lifecycle_gate_list",
+            description: "List a project's product-lifecycle hard gates, newest first, with their parsed metadata (stage, evidence hash, items) and status (pending/approved/denied/…). Filter by stage, task_id or status.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_id: { type: "string", description: "Project id (defaults to the project this agent is bound to)" },
+                    stage: { type: "string", enum: ["3", "6", "9", "dvt"], description: "Only this stage" },
+                    task_id: { type: "string", description: "Only gates on this task" },
+                    status: { type: "string", description: "Only this review status, e.g. pending" },
+                },
+            },
+        },
         {
             name: "api_search",
             description: "Search the API knowledge graph — endpoints (REST/MCP/GraphQL/gRPC) extracted from indexed repos across the org. Use this BEFORE building a new endpoint to check if it already exists or to match a sibling project's contract. Org-wide read.",
@@ -1141,6 +1203,21 @@ export function registerTools() {
                 required: ["channel"],
             },
         },
+        {
+            name: "room_history",
+            description: "Read a room's (channel's) earlier posts, oldest first, paged — e.g. after joining late. " +
+                "Pass next_since from the previous page as `since` to read on. Reading marks nothing read. " +
+                "Rooms belong to your organization; another org's room is 'not found'.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    room: { type: "string", description: "Room (channel) name" },
+                    since: { type: "number", description: "Return posts after this message seq (default 0: from the start)" },
+                    limit: { type: "number", description: "Posts per page (default 50, at most 200)" },
+                },
+                required: ["room"],
+            },
+        },
         {
             name: "leave_channel",
             description: "Unsubscribe from a channel",
@@ -1779,13 +1856,18 @@ export function registerTools() {
                 required: ["topic"],
             },
         },
+        {
+            name: "brainstorm_invites",
+            description: "List your pending brainstorm invites (session id, display number, topic, initiator). An invite is not chat: bring it to your human before brainstorm_accept unless they asked for that brainstorm or AGENTHUB_BRAINSTORM_AUTO_ACCEPT=true. The same list rides on check_inbox and every tool response as pending_brainstorm_invites. (requires agent_register first)",
+            inputSchema: { type: "object", properties: {} },
+        },
         {
             name: "brainstorm_accept",
-            description: "Accept a brainstorm invite (transition the session to active). Idempotent — a redelivered invite can't double-join. You are the responder. (requires agent_register first)",
+            description: "Accept a brainstorm invite (transition the session to active). Idempotent — a redelivered invite can't double-join. You are the responder. Unless your human asked for this brainstorm or AGENTHUB_BRAINSTORM_AUTO_ACCEPT=true, ask them first. (requires agent_register first)",
             inputSchema: {
                 type: "object",
                 properties: {
-                    session_id: { type: "string", description: "The session id from the invite message." },
+                    session_id: { type: "string", description: "The session id, from pending_brainstorm_invites / brainstorm_invites (or a legacy invite message)." },
                 },
                 required: ["session_id"],
             },
@@ -2372,10 +2454,14 @@ export function registerTools() {
                     query: { type: "string", description: "Search query" },
                     category: {
                         type: "string",
-                        enum: ["decision", "convention", "architecture", "blocker", "alert", "insight"],
+                        enum: ["decision", "convention", "architecture", "blocker", "alert", "insight", "lesson"],
                         description: "Filter by knowledge category",
                     },
                     project: { type: "string", description: "Filter by project" },
+                    tag: {
+                        type: "string",
+                        description: "Exact tag filter: matches a row only when one of its tags equals this string (e.g. `stage:6` does not match `stage:60`)",
+                    },
                     limit: { type: "number", description: "Max results (default 20)" },
                 },
                 required: ["query"],
@@ -2383,20 +2469,38 @@ export function registerTools() {
         },
         {
             name: "brain_write_knowledge",
-            description: "Write an org knowledge fact (decision, convention, architecture insight, blocker, or alert) to the shared org brain. The result carries `check`: `created` for a new row (with its `id`), or `deduped` when an identical active fact already exists — then `canonical_id` names the existing row if it is your organization's, and nothing is named if the match belongs to another organization. A refusal (missing fact, unknown category) is an error.",
+            description: "Write an org knowledge fact (decision, convention, architecture insight, blocker, or alert) to the shared org brain. The result carries `check`: `created` for a new row (with its `id`), or `deduped` when an identical active fact already exists — then `canonical_id` names the existing row. Dedup matches only your organization's own facts: identical text held by another organization is stored as your own new row. A refusal (missing fact, unknown category) is an error.",
             inputSchema: {
                 type: "object",
                 properties: {
                     category: {
                         type: "string",
-                        enum: ["decision", "convention", "architecture", "blocker", "alert", "insight"],
+                        enum: ["decision", "convention", "architecture", "blocker", "alert", "insight", "lesson"],
                         description: "Knowledge category",
                     },
-                    fact: { type: "string", description: "The fact or decision (concise)" },
+                    fact: { type: "string", description: "The fact or decision (concise). Required except for a lesson, whose fact defaults to `LESSON s<stage>: <rule>`." },
                     detail: { type: "string", description: "Extended context or rationale" },
                     project: { type: "string", description: "Project this applies to (optional)" },
+                    tags: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Tags for the exact tag filter (e.g. [\"lesson\",\"stage:6\"]). A lesson always also gets lesson, stage:<n>, track:<t>, product:<p>.",
+                    },
+                    lesson: {
+                        type: "object",
+                        description: "Required for category=lesson (400 invalid_lesson otherwise). All six fields are non-empty strings.",
+                        properties: {
+                            stage: { type: "string", description: "\"0\"–\"10\", \"HW-POC\", \"HW-EVT\", \"HW-DVT\", \"HW-PVT\" or \"HW-CERT\"" },
+                            product: { type: "string" },
+                            track: { type: "string", enum: ["gov", "commercial", "hardware", "any"] },
+                            rule: { type: "string", description: "One imperative sentence" },
+                            evidence: { type: "string", description: "A verifiable reference" },
+                            gate_kind: { type: "string", enum: ["gate item", "template field", "stage instruction"] },
+                        },
+                        required: ["stage", "product", "track", "rule", "evidence", "gate_kind"],
+                    },
                 },
-                required: ["category", "fact"],
+                required: ["category"],
             },
         },
         {
@@ -3233,6 +3337,23 @@ function brainstormError(tool, result) {
         message: result.message || `${tool} failed: ${result.error} (HTTP ${result.status})`,
     };
 }
+// lifecycleGateProject resolves a lifecycle gate tool's project: the argument,
+// else the project this agent is bound to (add-product-lifecycle-pack §2.1).
+function lifecycleGateProject(args, context) {
+    if (typeof args.project_id === "string" && args.project_id !== "")
+        return args.project_id;
+    return state.loadState(context.getWorkingDir())?.project_id ?? "";
+}
+// lifecycleGateError passes a server refusal through with its code and status,
+// and says in plain words what a 503 lifecycle_gates_disabled means.
+function lifecycleGateError(err) {
+    if (!(err instanceof AgentHubApiError))
+        throw err;
+    const message = err.code === "lifecycle_gates_disabled"
+        ? "Lifecycle gates are switched off on this AgentHub server (AGENTHUB_LIFECYCLE_GATES_ENABLED is not true). No gate can be opened or listed until an operator turns it on; existing gates stay readable and decidable on /reviews."
+        : err.message;
+    return { ok: false, error: err.code || "request_failed", status: err.status, message };
+}
 export async function handleToolCall(name, args, client, context) {
     const agentId = context.getCurrentAgentId();
     // Session steering + takeover (add-multiplayer-sessions §4.7, §5.9). Handled
@@ -3972,7 +4093,7 @@ export async function handleToolCall(name, args, client, context) {
                 throw new Error("Not registered. Call agent_register first.");
             const inboxLimit = resolveInboxLimit(args.limit);
             const raw = await client.getInbox(agentId, args.unread_only, inboxLimit);
-            return boundInbox(raw);
+            return { ...boundInbox(raw), ...inviteFields(raw.pending_brainstorm_invites) };
         }
         case "mark_read": {
             const result = await client.markRead(args.message_id);
@@ -4118,6 +4239,12 @@ export async function handleToolCall(name, args, client, context) {
             const result = await client.joinChannel(args.channel, agentId);
             return wrapWithPendingItems(client, agentId, result, context);
         }
+        case "room_history": {
+            if (!agentId)
+                throw new Error("Not registered. Call agent_register first.");
+            const result = await client.roomHistory(args.room, args.since, args.limit);
+            return wrapWithPendingItems(client, agentId, result, context);
+        }
         case "leave_channel": {
             if (!agentId)
                 throw new Error("Not registered. Call agent_register first.");
@@ -4545,6 +4672,55 @@ export async function handleToolCall(name, args, client, context) {
                 message: `Filed bug ${result.key} (${result.severity}/${result.bug_state}): ${args.title}`,
             };
         }
+        case "lifecycle_gate_request": {
+            const projectId = lifecycleGateProject(args, context);
+            if (!projectId) {
+                return {
+                    ok: false,
+                    error: "invalid_args",
+                    message: "project_id is required (or bind this agent to a project with agent_register).",
+                };
+            }
+            const body = { project_id: projectId };
+            for (const k of ["task_id", "stage", "title", "content", "evidence_hash", "items", "parent_review_id"]) {
+                if (args[k] !== undefined)
+                    body[k] = args[k];
+            }
+            try {
+                const review = await client.post("/lifecycle/gates", body);
+                return {
+                    ok: true,
+                    review_id: review.id,
+                    status: review.status,
+                    review,
+                    message: `Opened lifecycle gate ${review.id} (stage ${String(args.stage)}, ${review.status}). An org owner or admin signs it on /reviews.`,
+                };
+            }
+            catch (err) {
+                return lifecycleGateError(err);
+            }
+        }
+        case "lifecycle_gate_list": {
+            const projectId = lifecycleGateProject(args, context);
+            if (!projectId) {
+                return {
+                    ok: false,
+                    error: "invalid_args",
+                    message: "project_id is required (or bind this agent to a project with agent_register).",
+                };
+            }
+            const params = new URLSearchParams({ project_id: projectId });
+            for (const k of ["stage", "task_id", "status"]) {
+                if (typeof args[k] === "string" && args[k] !== "")
+                    params.set(k, args[k]);
+            }
+            try {
+                return await client.get(`/lifecycle/gates?${params.toString()}`);
+            }
+            catch (err) {
+                return lifecycleGateError(err);
+            }
+        }
         case "skill_pack_list": {
             try {
                 const { packs } = await client.listSkillPacks();
@@ -4612,7 +4788,8 @@ export async function handleToolCall(name, args, client, context) {
             const c = report.counts;
             const summary = `${pack} v${manifest.version}: ${c.installed} installed, ${c.updated} updated, ` +
                 `${c.skipped_current} unchanged, ${c.skipped_user_modified} skipped (user-modified), ` +
-                `${c.overwritten_force} overwritten, ${c.error} errors.`;
+                `${c.overwritten_force} overwritten, ${c.removed} removed (dropped by this version), ` +
+                `${c.kept_modified} kept (dropped but user-modified), ${c.error} errors.`;
             return {
                 ok: c.error === 0,
                 pack,
@@ -4707,7 +4884,37 @@ export async function handleToolCall(name, args, client, context) {
                 invites: result.data.invites,
                 mirror_thread_id: result.data.mirror_thread_id,
                 mirror_warning: result.data.mirror_warning,
-                message: `Brainstorm ${result.data.display_number} opened with ${invitees}. Invite delivered${result.data.invite_delivered === false ? " FAILED" : ""}.`,
+                // separate-agent-chat-from-brainstorms §1.4: event | message |
+                // event+message | none. "none" means recorded but the invitee is not
+                // connected — it will see the invite in pending_brainstorm_invites.
+                invite_delivery: result.data.invite_delivery,
+                warning: result.data.warning,
+                message: `Brainstorm ${result.data.display_number} opened with ${invitees}. ${result.data.invite_delivered === false
+                    ? result.data.warning
+                        ? "Invite delivery FAILED."
+                        : "Invite recorded; the invitee is not connected and will see it in pending_brainstorm_invites."
+                    : "Invite delivered."}`,
+            };
+        }
+        case "brainstorm_invites": {
+            // separate-agent-chat-from-brainstorms §2.1. Not wrapped: the wrapper
+            // would repeat this same list as pending_brainstorm_invites.
+            if (!agentId)
+                throw new Error("Not registered. Call agent_register first.");
+            const result = await client.brainstormInvites();
+            if (!result.ok)
+                return brainstormError("brainstorm_invites", result);
+            const invites = Array.isArray(result.data.invites) ? result.data.invites : [];
+            const autoAccept = brainstormAutoAcceptEnabled();
+            return {
+                ok: true,
+                count: invites.length,
+                invites,
+                auto_accept: autoAccept,
+                guidance: inviteGuidance(autoAccept),
+                message: invites.length === 0
+                    ? "No pending brainstorm invites."
+                    : `${invites.length} pending brainstorm invite(s). ${autoAccept ? "Auto-accept is on." : "Ask your human before accepting any you were not asked to join."}`,
             };
         }
         case "brainstorm_accept": {
@@ -5266,6 +5473,8 @@ export async function handleToolCall(name, args, client, context) {
                 brainParams.set("category", args.category);
             if (args.project)
                 brainParams.set("project", args.project);
+            if (args.tag)
+                brainParams.set("tag", args.tag);
             if (args.limit)
                 brainParams.set("limit", String(args.limit));
             return client.get(`/brain/knowledge?${brainParams.toString()}`);
@@ -5275,10 +5484,13 @@ export async function handleToolCall(name, args, client, context) {
                 throw new Error("Not registered. Call agent_register first.");
             return client.createBrainKnowledge({
                 category: args.category,
-                fact: args.fact,
+                fact: args.fact || "",
                 detail: args.detail || "",
                 source_agent: agentId,
                 project: args.project,
+                // The server stores tags as a JSON array string.
+                ...(Array.isArray(args.tags) ? { tags: JSON.stringify(args.tags) } : {}),
+                ...(args.lesson ? { lesson: args.lesson } : {}),
             });
         }
         case "brain_get_context": {