agent-relay-server 0.62.3 → 0.63.1

package/src/mcp/identity.ts

@@ -0,0 +1,131 @@
+import { MAX_BODY_BYTES } from "../config";
+import { compactAndResume } from "../self-resume";
+import { getAgent, listAgents, searchContinuationArchives } from "../db";
+import { resolveCallerAgentId } from "../agent-ref";
+import { getComponentAuth, getIntegrationAuth, hasComponentScope, hasIntegrationScope } from "../security";
+import { McpAuthError } from "../mcp-errors";
+import { optionalEnum } from "../validation";
+import type { McpAuthContext, ToolDefinition } from "./types";
+import { optionalPositiveInt, optionalString, stringField } from "./validation";
+
+export const IDENTITY_TOOLS: ToolDefinition[] = [
+  {
+    name: "relay_whoami",
+    description: "Return your own Relay identity and agent card (id, label, status, tags, capabilities). Your identity comes from your auth token — you do NOT need this to send, reply, or pair; use it only when you need to reason about yourself.",
+    requiredScopes: ["mcp:use"],
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_compact_and_resume",
+    description: "Self-resume this same agent in place: Relay stores the continuation envelope, compacts or clears context, then resumes with the relay-built continuation. Use at a clean seam after a context advisory.",
+    requiredScopes: ["command:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        workingState: { type: "string", description: "Current replaceable working state for the next generation." },
+        ruledOut: {
+          type: "array",
+          items: {
+            oneOf: [
+              { type: "string" },
+              {
+                type: "object",
+                properties: {
+                  ruledOut: { type: "string" },
+                  why: { type: "string" },
+                },
+                required: ["ruledOut"],
+                additionalProperties: false,
+              },
+            ],
+          },
+        },
+        mode: { type: "string", enum: ["clear-inject", "native"] },
+        objective: { type: "string", description: "Seed-only objective. Used only on the first call when no spawn prompt seeded the envelope." },
+      },
+      required: ["workingState"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_recall",
+    description: "Recall this same agent's archived pre-compaction transcript segments by keyword/BM25 search. Self-only: caller identity comes from the MCP token; no agentId parameter is accepted.",
+    requiredScopes: ["memory:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Keyword query over archived compact/clear segments." },
+        limit: { type: "integer", minimum: 1, maximum: 20 },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+];
+
+export function mcpAuthContext(req: Request): McpAuthContext {
+  const component = getComponentAuth(req);
+  if (component) return { actor: component.sub, kind: "component", scopes: component.scope, component };
+  const integration = getIntegrationAuth(req);
+  if (integration) return { actor: integration.name, kind: "integration", scopes: integration.scopes, integration };
+  return { actor: "server", kind: "server", scopes: ["*"] };
+}
+
+// THE caller-identity resolver for MCP. It delegates to src/agent-ref.ts so every
+// transport resolves token constraints -> caller agent id through the same logic.
+export function callerAgentId(auth: McpAuthContext): string | undefined {
+  if (auth.kind !== "component") return undefined;
+  return resolveCallerAgentId(auth.component?.constraints, listAgents);
+}
+
+export function relayWhoami(auth: McpAuthContext): Record<string, unknown> {
+  const agentId = callerAgentId(auth);
+  const agent = agentId ? getAgent(agentId) : null;
+  return {
+    agentId: agentId ?? null,
+    actor: auth.actor,
+    kind: auth.kind,
+    scopes: auth.scopes,
+    agent: agent ?? null,
+  };
+}
+
+export function relayCompactAndResume(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const agentId = callerAgentId(auth);
+  if (!agentId) throw new McpAuthError("relay_compact_and_resume requires a single caller agent identity");
+  return compactAndResume({
+    agentId,
+    workingState: stringField(args.workingState, "workingState", { required: true, maxBytes: MAX_BODY_BYTES }),
+    ruledOut: args.ruledOut,
+    mode: optionalEnum(args.mode, "mode", ["clear-inject", "native"] as const),
+    objective: optionalString(args.objective, "objective", 64_000),
+  }) as unknown as Record<string, unknown>;
+}
+
+export function relayRecall(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const agentId = callerAgentId(auth);
+  if (!agentId) throw new McpAuthError("relay_recall requires a single caller agent identity");
+  const query = stringField(args.query, "query", { required: true, max: 1000 });
+  const matches = searchContinuationArchives({
+    agentId,
+    query,
+    limit: optionalPositiveInt(args.limit, "limit"),
+  });
+  return { query, matches, count: matches.length };
+}
+
+export function hasAnyScope(auth: McpAuthContext, required: string[]): boolean {
+  if (auth.scopes.includes("*") || auth.scopes.includes("admin:*")) return true;
+  return required.some((scope) => hasScope(auth, scope));
+}
+
+export function hasScope(auth: McpAuthContext, scope: string): boolean {
+  if (auth.kind === "component" && auth.component) return hasComponentScope(auth.component, scope);
+  if (auth.kind === "integration" && auth.integration) return hasIntegrationScope(auth.integration, scope);
+  const [category] = scope.split(":");
+  return auth.scopes.includes(scope) || Boolean(category && auth.scopes.includes(`${category}:*`));
+}

package/src/mcp/index.ts

@@ -0,0 +1,208 @@
+import { maxArtifactBytes } from "../artifact-storage";
+import { readBodyBytes } from "../http-body";
+import { MAX_BODY_BYTES, VERSION } from "../config";
+import { spawnCapablePrimer } from "../spawn-targets";
+import { McpAuthError, McpNotFoundError } from "../mcp-errors";
+import { createActivityEvent, ValidationError } from "../db";
+import { PLAN_TOOLS, relayPlanTool } from "../mcp-plan-tools";
+import { TEAM_TOOLS, relayTeamTool } from "../mcp-team-tools";
+import { BLACKBOARD_TOOLS, relayBlackboardTool } from "../mcp-blackboard-tools";
+import { PROJECT_TOOLS, relayProjectTool } from "../mcp-project-tools"; import { ISSUE_REF_TOOLS, relayIssueRefTool } from "../mcp-issue-ref-tools"; import { ISSUE_ASSOCIATION_TOOLS, relayIssueAssociationTool } from "../mcp-issue-association-tools"; import { ISSUE_ACTIVITY_TOOLS, relayIssueActivityTool } from "../mcp-issue-activity-tools"; import { ISSUE_LIFECYCLE_TOOLS, relayIssueLifecycleTool } from "../mcp-issue-lifecycle-tools";
+import { NOTIFICATION_SUBSCRIPTION_TOOLS, relayNotificationSubscriptionTool } from "../mcp-notification-subscription-tools"; import { MERGE_TOOLS, relayMergeTool } from "../mcp-merge-tools";
+import { AGENT_ACTION_TOOL, relayAgentAction } from "../mcp-agent-action"; import { providerCatalogToolInputSchema } from "../mcp-provider-catalog";
+import type { ActivityKind } from "../types";
+import { worktreeMcpInstructions } from "../workspace-phase";
+import { errMessage, isRecord } from "agent-relay-sdk";
+import type { JsonRpcId, JsonRpcRequest, McpAuthContext, ToolDefinition } from "./types";
+import { positiveIdOrUndefined, recordField, stringField } from "./validation";
+import { IDENTITY_TOOLS, hasAnyScope, mcpAuthContext, relayCompactAndResume, relayRecall, relayWhoami } from "./identity";
+import { MESSAGING_TOOLS, relayAgentStatus, relayAttachArtifact, relayFindAgents, relayGetMessage, relayGetThread, relayReply, relaySendMessage, relayUploadArtifact } from "./tools-messaging";
+import { SPAWN_TOOLS, relayShutdownAgent, relaySpawnAgent, relaySpawnTargets } from "./tools-spawn";
+import { WORKSPACE_TOOLS, callerIsolatedWorkspace, relayWorkspaceList, relayWorkspaceMutation, relayWorkspaceStatus } from "./tools-workspace";
+
+const MCP_PROTOCOL_VERSION = "2024-11-05";
+const MCP_BODY_OVERHEAD_BYTES = 16 * 1024;
+const TOOLS: ToolDefinition[] = [
+  ...MESSAGING_TOOLS,
+  ...IDENTITY_TOOLS,
+  ...SPAWN_TOOLS,
+  AGENT_ACTION_TOOL,
+  ...WORKSPACE_TOOLS,
+  ...MERGE_TOOLS, ...TEAM_TOOLS,
+  ...PLAN_TOOLS, ...ISSUE_REF_TOOLS, ...ISSUE_ASSOCIATION_TOOLS, ...ISSUE_ACTIVITY_TOOLS, ...ISSUE_LIFECYCLE_TOOLS,
+  ...BLACKBOARD_TOOLS,
+  ...PROJECT_TOOLS,
+  ...NOTIFICATION_SUBSCRIPTION_TOOLS,
+];
+
+export async function postMcp(req: Request): Promise<Response> {
+  const parsed = await parseJsonRpcRequest(req);
+  if (!parsed.ok) return Response.json(jsonRpcError(null, -32700, parsed.error), { status: parsed.status });
+  const request = parsed.request;
+  const id = request.id ?? null;
+  const method = request.method;
+  if (typeof method !== "string") return Response.json(jsonRpcError(id, -32600, "method required"));
+
+  try {
+    const auth = mcpAuthContext(req);
+    if (!hasAnyScope(auth, ["mcp:use"])) {
+      return Response.json(jsonRpcError(id, -32001, "MCP token missing mcp:use scope", { status: 403 }));
+    }
+
+    if (method === "initialize") {
+      // Mode-tailored primer (#214 §3): surface the worktree merge-back map only
+      // to callers that own an isolated worktree; shared-workspace agents omit it.
+      // #308: append the spawn primer only when the token actually grants command:spawn —
+      // authoritative scope-gating, eager + thin, so non-spawn agents get nothing.
+      const worktree = callerIsolatedWorkspace(auth);
+      const instructions = [
+        worktree ? worktreeMcpInstructions(worktree) : "",
+        spawnCapablePrimer({ canSpawn: hasAnyScope(auth, ["command:spawn"]), quota: auth.component?.constraints?.maxSpawnedAgents }),
+      ].filter(Boolean).join("\n\n");
+      return Response.json(jsonRpcResult(id, {
+        protocolVersion: MCP_PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: "agent-relay", title: "Agent Relay", version: VERSION },
+        ...(instructions ? { instructions } : {}),
+      }));
+    }
+    if (method === "notifications/initialized") {
+      return new Response(null, { status: 202 });
+    }
+    if (method === "tools/list") {
+      return Response.json(jsonRpcResult(id, { tools: visibleTools(auth) }));
+    }
+    if (method === "tools/call") {
+      const result = await callTool(auth, request.params);
+      return Response.json(jsonRpcResult(id, result));
+    }
+    return Response.json(jsonRpcError(id, -32601, `unknown MCP method: ${method}`));
+  } catch (error) {
+    const message = errMessage(error);
+    const status = error instanceof McpAuthError ? 403 : error instanceof McpNotFoundError ? 404 : 400;
+    const code = error instanceof McpAuthError ? -32001 : error instanceof McpNotFoundError ? -32004 : -32602;
+    return Response.json(jsonRpcError(id, code, message, { status }));
+  }
+}
+
+async function parseJsonRpcRequest(req: Request): Promise<
+  | { ok: true; request: JsonRpcRequest }
+  | { ok: false; status: number; error: string }
+> {
+  if (!req.body) return { ok: false, status: 400, error: "JSON-RPC body required" };
+  const maxBodyBytes = Math.max(MAX_BODY_BYTES, maxArtifactBytes() + MCP_BODY_OVERHEAD_BYTES);
+  const read = await readBodyBytes(req.body, maxBodyBytes);
+  if (!read.ok) return read;
+  try {
+    const body = JSON.parse(new TextDecoder().decode(read.bytes)) as unknown;
+    if (!isRecord(body)) return { ok: false, status: 400, error: "JSON-RPC body must be an object" };
+    return { ok: true, request: body as JsonRpcRequest };
+  } catch {
+    return { ok: false, status: 400, error: "invalid JSON-RPC body" };
+  }
+}
+
+async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<string, unknown>> {
+  if (!isRecord(params)) throw new ValidationError("tools/call params must be an object");
+  const name = stringField(params.name, "name", { required: true });
+  const args = recordField(params.arguments ?? {}, "arguments");
+  const tool = TOOLS.find((item) => item.name === name);
+  if (!tool) throw new ValidationError(`unknown tool: ${name}`);
+  if (!hasAnyScope(auth, tool.requiredScopes)) {
+    auditToolCall(auth, name, "denied", undefined, `missing scope: ${tool.requiredScopes.join(" or ")}`);
+    throw new McpAuthError(`tool ${name} requires ${tool.requiredScopes.join(" or ")}`);
+  }
+
+  try {
+    let result: unknown;
+    if (name === "relay_send_message") result = relaySendMessage(auth, args);
+    else if (name === "relay_reply") result = relayReply(auth, args);
+    else if (name === "relay_get_message") result = relayGetMessage(args);
+    else if (name === "relay_get_thread") result = relayGetThread(args);
+    else if (name === "relay_upload_artifact") result = await relayUploadArtifact(auth, args);
+    else if (name === "relay_attach_artifact") result = relayAttachArtifact(auth, args);
+    else if (name === "relay_agent_status") result = relayAgentStatus(args);
+    else if (name === "relay_find_agents") result = relayFindAgents(auth, args);
+    else if (name === "relay_whoami") result = relayWhoami(auth);
+    else if (name === "relay_compact_and_resume") result = relayCompactAndResume(auth, args);
+    else if (name === "relay_recall") result = relayRecall(auth, args);
+    else if (name === "relay_spawn_agent") result = await relaySpawnAgent(auth, args);
+    else if (name === "relay_spawn_targets") result = relaySpawnTargets(auth);
+    else if (name === "relay_shutdown_agent") result = relayShutdownAgent(auth, args);
+    else if (name === "relay_agent_action") result = relayAgentAction(auth, args);
+    else if (name === "relay_workspace_status") result = await relayWorkspaceStatus(auth, args);
+    else if (name === "relay_workspace_list") result = relayWorkspaceList(auth, args);
+    else if (name === "relay_workspace_ready") result = relayWorkspaceMutation(auth, "ready", args);
+    else if (name === "relay_workspace_deps") result = relayWorkspaceMutation(auth, "deps-refresh", args);
+    else if (name === "relay_workspace_claim") result = relayWorkspaceMutation(auth, "claim", args);
+    else if (name === "relay_workspace_release") result = relayWorkspaceMutation(auth, "release-claim", args);
+    else if (name === "relay_workspace_land") result = relayWorkspaceMutation(auth, "merge", args);
+    else if (name.startsWith("relay_merge_")) result = relayMergeTool(auth, name, args); else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
+    else if (name.startsWith("relay_plan_")) result = relayPlanTool(auth, name, args);
+    else if (name.startsWith("relay_blackboard_")) result = relayBlackboardTool(auth, name, args);
+    else if (name.startsWith("relay_project_")) result = relayProjectTool(auth, name, args); else if (name.startsWith("relay_issue_ref_")) result = relayIssueRefTool(auth, name, args); else if (name.startsWith("relay_issue_association_")) result = relayIssueAssociationTool(auth, name, args); else if (name.startsWith("relay_issue_activity_")) result = relayIssueActivityTool(auth, name, args); else if (name.startsWith("relay_issue_lifecycle_")) result = await relayIssueLifecycleTool(auth, name, args);
+    else if (name === "relay_subscribe" || name === "relay_unsubscribe" || name === "relay_list_subscriptions") result = relayNotificationSubscriptionTool(auth, name, args);
+    else throw new ValidationError(`unknown tool: ${name}`);
+
+    auditToolCall(auth, name, "ok", result);
+    return toolResult(result);
+  } catch (error) {
+    const message = errMessage(error);
+    auditToolCall(auth, name, error instanceof McpAuthError ? "denied" : "error", undefined, message);
+    throw error;
+  }
+}
+
+function visibleTools(auth: McpAuthContext): Array<Record<string, unknown>> {
+  return TOOLS
+    .filter((tool) => hasAnyScope(auth, tool.requiredScopes))
+    .map(({ name, description, alwaysLoad, ...tool }) => ({
+      name,
+      description,
+      inputSchema: providerCatalogToolInputSchema(name, tool.inputSchema),
+      ...(alwaysLoad ? { _meta: { "anthropic/alwaysLoad": true } } : {}),
+    }));
+}
+
+function toolResult(result: unknown): Record<string, unknown> {
+  return {
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    structuredContent: result,
+  };
+}
+
+function jsonRpcResult(id: JsonRpcId, result: unknown): Record<string, unknown> {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function jsonRpcError(id: JsonRpcId, code: number, message: string, data?: unknown): Record<string, unknown> {
+  return { jsonrpc: "2.0", id, error: { code, message, ...(data ? { data } : {}) } };
+}
+
+function auditToolCall(
+  auth: McpAuthContext,
+  tool: string,
+  status: "ok" | "denied" | "error",
+  result?: unknown,
+  error?: string,
+): void {
+  try {
+    const messageId = isRecord(result) && isRecord(result.message)
+      ? positiveIdOrUndefined(result.message.id)
+      : isRecord(result) ? positiveIdOrUndefined(result.id) : undefined;
+    const kind: ActivityKind = tool.includes("reply") ? "reply" : tool.includes("send") ? "message" : "state";
+    createActivityEvent({
+      kind,
+      title: `MCP ${tool}`,
+      body: error ?? status,
+      meta: auth.actor,
+      icon: status === "ok" ? "ti-plug-connected" : status === "denied" ? "ti-shield-x" : "ti-alert-triangle",
+      view: "messages",
+      messageId,
+      agentId: auth.actor,
+      metadata: { source: "mcp", tool, actor: auth.actor, authKind: auth.kind, status },
+    });
+  } catch {
+    // Audit writes must not block tool calls.
+  }
+}