agent-relay-server 0.62.3 → 0.63.0

package/src/mcp/tools-messaging.ts

@@ -0,0 +1,459 @@
+import { Buffer } from "node:buffer";
+import { getArtifactStorage, maxArtifactBytes, normalizeDigest } from "../artifact-storage";
+import { bytesToStream } from "../http-body";
+import { MAX_BODY_BYTES } from "../config";
+import { getManagedAgentState, getSpawnPolicy, listSpawnPolicies } from "../config-store";
+import {
+  createArtifact,
+  getAgent,
+  getArtifact,
+  getMessage,
+  getOrchestrator,
+  getTask,
+  getThread,
+  linkArtifact,
+  listArtifactsForEntity,
+  listOrchestrators,
+  searchAgents,
+  upsertArtifactBlob,
+  ValidationError,
+  type AgentSearchFilter,
+  type AgentSearchSort,
+} from "../db";
+import { type DeliveryReceipt } from "../agent-ref";
+import { emitRelayEvent } from "../events";
+import { McpAuthError, McpNotFoundError } from "../mcp-errors";
+import { authContextFromMcp } from "../services/auth-context";
+import { ServiceAuthError } from "../services/errors";
+import { sendMessageService } from "../services/send-message";
+import { optionalEnum } from "../validation";
+import { isRecord } from "agent-relay-sdk";
+import type { ArtifactKind, ArtifactSensitivity, AttachmentRef, Message, SendMessageInput } from "../types";
+import type { McpAuthContext, ToolDefinition } from "./types";
+import { callerAgentId } from "./identity";
+import { enumField, optionalAttachments, optionalBoolean, optionalFutureTimestamp, optionalPositiveInt, optionalRecord, optionalString, positiveId, recordField, stringField } from "./validation";
+
+const VALID_ARTIFACT_KINDS = ["image", "audio", "video", "document", "archive", "other"] as const;
+const VALID_ARTIFACT_SENSITIVITIES = ["public", "normal", "sensitive", "secret"] as const;
+const VALID_ARTIFACT_ROLES = ["media", "patch", "report", "log", "output", "input"] as const;
+const VALID_ARTIFACT_ENTITY_TYPES = ["message", "task", "recipeRun", "recipeStep", "channelEvent"] as const;
+
+export const MESSAGING_TOOLS: ToolDefinition[] = [
+  {
+    name: "relay_send_message",
+    description: "Send an Agent Relay message. Returns a delivery receipt (delivered/expectReply/recipients): if expectReply is false, no live recipient exists — don't wait for a reply. An ambiguous target is rejected up front. An unknown target is stored for delivery once that id registers (the receipt reports delivered:false with empty recipients and a reason) — never silently dropped.",
+    requiredScopes: ["messages:write", "message:send"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Deprecated/optional. Your identity is taken from your auth token; ignored for managed agents. You never need to set this." },
+        to: { type: "string", description: "Target: an agent id, label, name, or a unique id segment (e.g. the number part) — resolved automatically. Or a fan-out selector: tag:, cap:, label:, team:, policy:, or broadcast." },
+        body: { type: "string" },
+        subject: { type: "string" },
+        channel: { type: "string" },
+        claimable: { type: "boolean" },
+        idempotencyKey: { type: "string" },
+        attachments: { type: "array", items: { type: "object" } },
+        payload: { type: "object" },
+        meta: { type: "object" },
+      },
+      required: ["to", "body"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_reply",
+    description: "Reply to an Agent Relay message by id, preserving reply/thread/channel context. Returns a delivery receipt; expectReply:false means the original sender is no longer reachable.",
+    requiredScopes: ["messages:write", "message:send"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Deprecated/optional. Your identity is taken from your auth token; ignored for managed agents. You never need to set this." },
+        messageId: { type: "integer", minimum: 1 },
+        body: { type: "string" },
+        subject: { type: "string" },
+        format: { type: "string", enum: ["text", "markdown", "markdownv2"] },
+        attachments: { type: "array", items: { type: "object" } },
+        payload: { type: "object" },
+        meta: { type: "object" },
+      },
+      required: ["messageId", "body"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_get_message",
+    description: "Fetch a full Agent Relay message body with optional attachments and thread context.",
+    requiredScopes: ["messages:read", "message:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        messageId: { type: "integer", minimum: 1 },
+        includeArtifacts: { type: "boolean", default: true },
+        includeThread: { type: "boolean", default: true },
+      },
+      required: ["messageId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_get_thread",
+    description: "Fetch the full Agent Relay thread containing a message.",
+    requiredScopes: ["messages:read", "message:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        messageId: { type: "integer", minimum: 1 },
+      },
+      required: ["messageId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_upload_artifact",
+    description: "Upload long text or base64 content as an Agent Relay artifact.",
+    requiredScopes: ["artifact:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        content: { type: "string", description: "UTF-8 text content to store." },
+        base64: { type: "string", description: "Base64-encoded binary content to store." },
+        filename: { type: "string" },
+        mediaType: { type: "string" },
+        kind: { type: "string", enum: VALID_ARTIFACT_KINDS },
+        sensitivity: { type: "string", enum: VALID_ARTIFACT_SENSITIVITIES },
+        role: { type: "string", enum: VALID_ARTIFACT_ROLES },
+        title: { type: "string" },
+        metadata: { type: "object" },
+        expiresAt: { type: "integer", minimum: 1 },
+        digest: { type: "string", description: "Optional sha256 digest for integrity verification." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_attach_artifact",
+    description: "Attach an existing Relay artifact to a message, task, recipe run, recipe step, or channel event.",
+    requiredScopes: ["artifact:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifactId: { type: "string" },
+        entityType: { type: "string", enum: VALID_ARTIFACT_ENTITY_TYPES },
+        entityId: { oneOf: [{ type: "string" }, { type: "integer", minimum: 1 }] },
+        role: { type: "string", enum: VALID_ARTIFACT_ROLES },
+        title: { type: "string" },
+      },
+      required: ["artifactId", "entityType", "entityId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_agent_status",
+    description: "Inspect Relay agent, orchestrator, and managed spawn-policy status. The default agent list shows only RUNNING agents (the ones you can actually message/reply/pair with); pass includeOffline:true for the full roster.",
+    requiredScopes: ["agents:read", "agent:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        agentId: { type: "string" },
+        policyName: { type: "string" },
+        orchestratorId: { type: "string" },
+        includeOffline: { type: "boolean", description: "Include offline/stale agents in the default list (default false)." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_find_agents",
+    description: "Search the fleet for agents by label, capability, provider, tag, machine, status, or kind, sorted by last-active/created/label. Defaults to running agents only. Use this to find a reachable, capable peer before messaging or pairing — instead of dumping the whole roster.",
+    requiredScopes: ["agents:read", "agent:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        label: { type: "string", description: "Substring match on label or name." },
+        capability: { type: ["string", "array"], items: { type: "string" }, description: "One or more capabilities (OR within)." },
+        provider: { type: ["string", "array"], items: { type: "string" }, description: "Model provider, e.g. claude or codex." },
+        tag: { type: ["string", "array"], items: { type: "string" } },
+        machine: { type: ["string", "array"], items: { type: "string" } },
+        kind: { type: ["string", "array"], items: { type: "string" } },
+        status: { type: ["string", "array"], items: { type: "string" }, description: "online/idle/busy/offline/stale, the 'running' shorthand, or 'all'. Default 'running'." },
+        spawnedBy: { type: "string", description: "Parent agent id, or 'me' for your own spawned children (#221)." },
+        teamId: { type: "string", description: "Durable team id for roster filtering." },
+        sortBy: { type: "string", enum: ["lastActive", "created", "label"] },
+        order: { type: "string", enum: ["asc", "desc"] },
+        limit: { type: "integer", minimum: 1, maximum: 200 },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+function runMcpSend(auth: McpAuthContext, input: SendMessageInput): Message & { delivery: DeliveryReceipt } {
+  try {
+    const result = sendMessageService(
+      input,
+      authContextFromMcp({ kind: auth.kind, actor: auth.actor, scopes: auth.scopes, component: auth.component }),
+      { integration: auth.integration },
+    );
+    return { ...result.message, delivery: result.receipt };
+  } catch (e) {
+    if (e instanceof ServiceAuthError) throw new McpAuthError(e.message);
+    throw e;
+  }
+}
+
+export function relaySendMessage(auth: McpAuthContext, args: Record<string, unknown>): Message & { delivery: DeliveryReceipt } {
+  const attachments = optionalAttachments(args.attachments);
+  const payload = payloadWithAttachments(optionalRecord(args.payload, "payload"), attachments);
+  const input: SendMessageInput = {
+    from: optionalString(args.from, "from", 200) ?? "",
+    to: stringField(args.to, "to", { required: true, max: 200 }),
+    body: stringField(args.body, "body", { required: true, maxBytes: MAX_BODY_BYTES }),
+    subject: optionalString(args.subject, "subject", 200),
+    channel: optionalString(args.channel, "channel", 120),
+    claimable: optionalBoolean(args.claimable, "claimable"),
+    idempotencyKey: optionalString(args.idempotencyKey, "idempotencyKey", 240),
+    attachments,
+    payload,
+    meta: optionalRecord(args.meta, "meta"),
+  };
+  return runMcpSend(auth, input);
+}
+
+export function relayReply(auth: McpAuthContext, args: Record<string, unknown>): Message & { delivery: DeliveryReceipt } {
+  const messageId = positiveId(args.messageId, "messageId");
+  const parent = getMessage(messageId);
+  if (!parent) throw new McpNotFoundError(`message ${messageId} not found`);
+  const attachments = optionalAttachments(args.attachments);
+  const payload = optionalRecord(args.payload, "payload") ?? {};
+  const format = optionalEnum(args.format, "format", ["text", "markdown", "markdownv2"] as const);
+  const replyPayload = payloadWithAttachments({
+    ...payload,
+    ...(format ? { message: { ...(isRecord(payload.message) ? payload.message : {}), format } } : {}),
+  }, attachments);
+  return runMcpSend(auth, {
+    from: optionalString(args.from, "from", 200) ?? "",
+    to: "",
+    body: stringField(args.body, "body", { required: true, maxBytes: MAX_BODY_BYTES }),
+    subject: optionalString(args.subject, "subject", 200),
+    replyTo: parent.id,
+    attachments,
+    payload: replyPayload,
+    meta: optionalRecord(args.meta, "meta"),
+  });
+}
+
+export function relayGetMessage(args: Record<string, unknown>): Record<string, unknown> {
+  const messageId = positiveId(args.messageId, "messageId");
+  const message = getMessage(messageId);
+  if (!message) throw new McpNotFoundError(`message ${messageId} not found`);
+  const includeArtifacts = args.includeArtifacts !== false;
+  const includeThread = args.includeThread !== false;
+  return {
+    message,
+    ...(includeArtifacts ? { artifacts: listArtifactsForEntity("message", message.id) } : {}),
+    ...(includeThread ? { thread: getThread(message.id) } : {}),
+  };
+}
+
+export function relayGetThread(args: Record<string, unknown>): Record<string, unknown> {
+  const messageId = positiveId(args.messageId, "messageId");
+  const thread = getThread(messageId);
+  if (!thread.length) throw new McpNotFoundError(`message ${messageId} not found`);
+  return { thread };
+}
+
+export async function relayUploadArtifact(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const bytes = artifactBytes(args);
+  const maxBytes = maxArtifactBytes();
+  if (bytes.byteLength > maxBytes) throw new ValidationError(`artifact exceeds ${maxBytes} bytes`);
+  const filename = optionalString(args.filename, "filename", 240);
+  const hintedMediaType = optionalString(args.mediaType, "mediaType", 160);
+  const mediaType = sniffMediaType(bytes, hintedMediaType, filename);
+  const storage = getArtifactStorage();
+  const digest = optionalString(args.digest, "digest", 80);
+  const stored = await storage.store(bytesToStream(bytes), {
+    mediaType,
+    size: bytes.byteLength,
+    digest: digest ? normalizeDigest(digest) : undefined,
+  });
+  upsertArtifactBlob({
+    digest: stored.digest,
+    storageUri: stored.storageUri,
+    mediaType,
+    size: stored.size,
+  });
+  const artifact = createArtifact({
+    blobDigest: stored.digest,
+    mediaType,
+    kind: (optionalEnum(args.kind, "kind", VALID_ARTIFACT_KINDS) as ArtifactKind | undefined) ?? inferArtifactKind(mediaType, filename),
+    filename,
+    size: stored.size,
+    sensitivity: optionalEnum(args.sensitivity, "sensitivity", VALID_ARTIFACT_SENSITIVITIES) as ArtifactSensitivity | undefined,
+    createdBy: auth.actor,
+    expiresAt: optionalFutureTimestamp(args.expiresAt, "expiresAt"),
+    metadata: optionalRecord(args.metadata, "metadata"),
+  });
+  emitRelayEvent({ type: "artifact.created", source: "mcp", subject: artifact.id, data: { artifact, actor: auth.actor } });
+  return {
+    artifact,
+    attachment: {
+      artifactId: artifact.id,
+      kind: artifact.kind,
+      role: optionalEnum(args.role, "role", VALID_ARTIFACT_ROLES),
+      title: optionalString(args.title, "title", 240) ?? artifact.filename,
+    },
+  };
+}
+
+export function relayAttachArtifact(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const artifactId = stringField(args.artifactId, "artifactId", { required: true, max: 120 });
+  const artifact = getArtifact(artifactId);
+  if (!artifact) throw new McpNotFoundError(`artifact ${artifactId} not found`);
+  const entityType = enumField(args.entityType, "entityType", VALID_ARTIFACT_ENTITY_TYPES);
+  const rawEntityId = args.entityId;
+  if (typeof rawEntityId !== "string" && typeof rawEntityId !== "number") throw new ValidationError("entityId must be a string or integer");
+  const entityId = typeof rawEntityId === "number" ? positiveId(rawEntityId, "entityId") : stringField(rawEntityId, "entityId", { required: true, max: 200 });
+  assertArtifactEntityExists(entityType, entityId);
+  const link = linkArtifact({
+    artifactId,
+    entityType,
+    entityId,
+    role: optionalEnum(args.role, "role", VALID_ARTIFACT_ROLES),
+    title: optionalString(args.title, "title", 240),
+    createdBy: auth.actor,
+  });
+  return { artifact: getArtifact(artifactId) ?? artifact, link };
+}
+
+export function relayAgentStatus(args: Record<string, unknown>): Record<string, unknown> {
+  const agentId = optionalString(args.agentId, "agentId", 240);
+  if (agentId) {
+    const agent = getAgent(agentId);
+    if (!agent) throw new McpNotFoundError(`agent ${agentId} not found`);
+    return { agent };
+  }
+  const policyName = optionalString(args.policyName, "policyName", 120);
+  if (policyName) return policyStatus(policyName);
+  const orchestratorId = optionalString(args.orchestratorId, "orchestratorId", 200);
+  if (orchestratorId) {
+    const orchestrator = getOrchestrator(orchestratorId);
+    if (!orchestrator) throw new McpNotFoundError(`orchestrator ${orchestratorId} not found`);
+    return { orchestrator };
+  }
+  const includeOffline = optionalBoolean(args.includeOffline, "includeOffline") === true;
+  return {
+    agents: searchAgents({ status: includeOffline ? "all" : "running" }),
+    spawnPolicies: listSpawnPolicies().map((entry) => policyStatusPayload(entry.value)),
+    orchestrators: listOrchestrators(),
+  };
+}
+
+function optionalStringOrArray(value: unknown, field: string): string | string[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    return value.map((item, i) => stringField(item, `${field}[${i}]`, { required: true, max: 200 }));
+  }
+  throw new ValidationError(`${field} must be a string or string array`);
+}
+
+export function relayFindAgents(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const spawnedByArg = optionalString(args.spawnedBy, "spawnedBy", 240);
+  const spawnedBy = spawnedByArg === "me" ? callerAgentId(auth) ?? "\0unresolved" : spawnedByArg;
+  const filter: AgentSearchFilter = {
+    label: optionalString(args.label, "label", 200),
+    capability: optionalStringOrArray(args.capability, "capability"),
+    provider: optionalStringOrArray(args.provider, "provider"),
+    tag: optionalStringOrArray(args.tag, "tag"),
+    machine: optionalStringOrArray(args.machine, "machine"),
+    kind: optionalStringOrArray(args.kind, "kind"),
+    spawnedBy,
+    teamId: optionalString(args.teamId, "teamId", 120),
+    status: optionalStringOrArray(args.status, "status") ?? "running",
+  };
+  const sort: AgentSearchSort = {
+    sortBy: optionalEnum(args.sortBy, "sortBy", ["lastActive", "created", "label"] as const),
+    order: optionalEnum(args.order, "order", ["asc", "desc"] as const),
+    limit: optionalPositiveInt(args.limit, "limit"),
+  };
+  const agents = searchAgents(filter, sort);
+  return { agents, count: agents.length };
+}
+
+function payloadWithAttachments(
+  payload: Record<string, unknown> | undefined,
+  attachments: AttachmentRef[] | undefined,
+): Record<string, unknown> | undefined {
+  if (!attachments) return payload;
+  if (payload?.attachments !== undefined) throw new ValidationError("attachments must be provided either top-level or in payload.attachments, not both");
+  return { ...(payload ?? {}), attachments };
+}
+
+function policyStatus(policyName: string): Record<string, unknown> {
+  const entry = getSpawnPolicy(policyName);
+  if (!entry) throw new McpNotFoundError(`spawn policy ${policyName} not found`);
+  return policyStatusPayload(entry.value);
+}
+
+function policyStatusPayload(policy: NonNullable<ReturnType<typeof getSpawnPolicy>>["value"]): Record<string, unknown> {
+  return {
+    policy,
+    state: getManagedAgentState(policy.name) ?? {
+      policyName: policy.name,
+      status: "stopped",
+      orchestratorId: policy.orchestratorId,
+      provider: policy.provider,
+      restartCount: 0,
+      consecutiveFailures: 0,
+      updatedAt: 0,
+    },
+  };
+}
+
+function artifactBytes(args: Record<string, unknown>): Uint8Array {
+  const hasContent = args.content !== undefined && args.content !== null;
+  const hasBase64 = args.base64 !== undefined && args.base64 !== null;
+  if (hasContent === hasBase64) throw new ValidationError("provide exactly one of content or base64");
+  if (hasContent) {
+    if (typeof args.content !== "string" || args.content.length === 0) throw new ValidationError("content required");
+    return new TextEncoder().encode(args.content);
+  }
+  const encoded = stringField(args.base64, "base64", { required: true }).replace(/\s+/g, "");
+  if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) throw new ValidationError("base64 must be valid base64 content");
+  return new Uint8Array(Buffer.from(encoded, "base64"));
+}
+
+function assertArtifactEntityExists(entityType: string, entityId: string | number): void {
+  if (entityType === "message" && !getMessage(Number(entityId))) throw new McpNotFoundError(`message ${entityId} not found`);
+  if (entityType === "task" && !getTask(Number(entityId))) throw new McpNotFoundError(`task ${entityId} not found`);
+}
+
+function inferArtifactKind(mediaType: string, filename?: string): ArtifactKind {
+  const lowerName = filename?.toLowerCase() ?? "";
+  if (mediaType.startsWith("image/")) return "image";
+  if (mediaType.startsWith("audio/")) return "audio";
+  if (mediaType.startsWith("video/")) return "video";
+  if (["application/zip", "application/gzip", "application/x-tar"].includes(mediaType) || /\.(zip|tgz|tar|gz)$/.test(lowerName)) return "archive";
+  if (
+    mediaType.startsWith("text/") ||
+    ["application/pdf", "application/json", "application/xml"].includes(mediaType) ||
+    /\.(pdf|txt|md|json|csv|diff|patch)$/.test(lowerName)
+  ) return "document";
+  return "other";
+}
+
+function sniffMediaType(bytes: Uint8Array, hinted?: string, filename?: string): string {
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) return "image/png";
+  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) return "image/gif";
+  if (bytes[0] === 0x25 && bytes[1] === 0x50 && bytes[2] === 0x44 && bytes[3] === 0x46) return "application/pdf";
+  if (bytes[0] === 0x50 && bytes[1] === 0x4b) return "application/zip";
+  const lower = filename?.toLowerCase() ?? "";
+  if (lower.endsWith(".svg")) return "image/svg+xml";
+  if (lower.endsWith(".md")) return "text/markdown";
+  if (lower.endsWith(".json")) return "application/json";
+  if (lower.endsWith(".csv")) return "text/csv";
+  if (lower.endsWith(".diff") || lower.endsWith(".patch")) return "text/x-diff";
+  return hinted || "text/plain";
+}

package/src/mcp/tools-spawn.ts

@@ -0,0 +1,145 @@
+import { spawnAgent, type SpawnAgentInput } from "../services/spawn-agent";
+import { authContextFromMcp } from "../services/auth-context";
+import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "../services/shutdown-agent";
+import { buildSpawnTargets } from "../spawn-targets";
+import { McpAuthError, McpNotFoundError } from "../mcp-errors";
+import { parseProjectInstructions, PROJECT_INSTRUCTION_POLICY_NAMES } from "../project-instructions";
+import { ValidationError } from "../db";
+import { optionalEnum } from "../validation";
+import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
+import type { ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import type { AgentLifecycle, SpawnApprovalMode, SpawnProvider, WorkspaceMode } from "../types";
+import type { McpAuthContext, ToolDefinition } from "./types";
+import { callerAgentId } from "./identity";
+import { enumField, optionalNonNegativeInt, optionalPositiveInt, optionalString, optionalStringArray } from "./validation";
+
+export const SPAWN_TOOLS: ToolDefinition[] = [
+  {
+    name: "relay_spawn_agent",
+    description: "Spawn a long-living provider agent through Relay's orchestrator, optionally handing it its first task via `prompt` in the same call. Defaults to your own host (override with orchestratorId) and returns the resolved agent id once it registers. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).",
+    requiredScopes: ["command:spawn"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        provider: { type: "string", enum: SPAWN_PROVIDERS },
+        orchestratorId: { type: "string", description: "Target host. Defaults to the host that owns cwd, else YOUR OWN host — only set it to spawn onto a different machine." },
+        cwd: { type: "string", description: "Working directory for the agent. Defaults to YOUR OWN cwd (the repo you're working in) when omitted, else the orchestrator's base dir. Must resolve within the target orchestrator's base directory (enforced server-side). NOTE: workspaceMode `isolated` requires a git repo — the resolved cwd must be inside one or the spawn is rejected." },
+        label: { type: "string" },
+        model: { type: "string" },
+        effort: { type: "string", enum: VALID_EFFORTS },
+        approvalMode: { type: "string", enum: APPROVAL_MODES, description: "Permission posture for the worker. Defaults to YOUR OWN approval mode when omitted (a headless `guarded` worker wedges on the first approval prompt), so a coordinator running `open` spawns workers that can act autonomously. Pass an explicit value to narrow a child (e.g. `read-only` reviewer)." },
+        prompt: { type: "string", description: "Initial task/message delivered to the agent on launch — spawn and hand it its first instruction in one call (no separate follow-up message needed)." },
+        expectReply: { type: "boolean", description: "Require the worker to report back: it gets a pending reply obligation to you and CANNOT go idle until it delivers its result (which routes to your inbox and wakes you). Defaults true when you pass a prompt — set false for a true fire-and-forget worker that needn't report (e.g. one that only lands a branch)." },
+        systemPromptAppend: { type: "string" },
+        projectInstructions: { type: "object", description: "#409 — project instruction projection (default OFF). When set, relay composes a knowledge preamble from the spawn cwd's resolved project (own + inherited entries) and prepends it to systemPromptAppend, instead of relying on host CLAUDE.md. `policy: \"all\"` includes ingested host content; `\"vanilla\"` excludes it (manual+promoted only). Omit to keep current behavior.", properties: { policy: { type: "string", enum: PROJECT_INSTRUCTION_POLICY_NAMES } }, additionalProperties: false },
+        profile: { type: "string", description: "Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota)." },
+        tags: { type: "array", items: { type: "string" } },
+        capabilities: { type: "array", items: { type: "string" } },
+        providerArgs: { type: "array", items: { type: "string" } },
+        policyName: { type: "string" },
+        spawnRequestId: { type: "string" },
+        lifecycle: { type: "string", enum: VALID_AGENT_LIFECYCLES, description: "Lifecycle mode. `persistent` keeps the agent until explicitly stopped. `transient` lets Relay auto-shutdown the child after it is idle and, for isolated workers, after its branch has landed. Default: persistent." },
+        workspaceMode: { type: "string", enum: VALID_WORKSPACE_MODES, description: "Git workspace for the worker. `isolated` = its own worktree on an `agent/session-*` branch off main that auto-lands when ready (delegate a unit of work, get a branch worker). `shared` = edits your live checkout (a sidecar). `inherit` = let the orchestrator decide. DEFAULT for agent-initiated spawns is `isolated` so a delegated worker lands to main instead of editing your tree; pass `shared`/`inherit` to override." },
+        waitForRegistrationMs: { type: "integer", minimum: 0, maximum: 30000, description: "How long to wait for the spawned agent to register before returning, so the response carries its resolved agent id (default 8000; 0 = return immediately with just spawnRequestId)." },
+      },
+      required: ["provider"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_spawn_targets",
+    description: "Return the LIVE spawn capability matrix before you spawn: which orchestrators/hosts are online, which providers actually run on each (orchestrator-probed, not a static guess), each provider's models with per-model effort levels + defaults, your own host (isSelf) and remaining spawn quota, and named profiles you can spawn by role. Call this first whenever you decide to spawn — it removes the guesswork that otherwise only surfaces as a runtime rejection. Requires the command:spawn scope.",
+    requiredScopes: ["command:spawn"],
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_shutdown_agent",
+    description: "Shut down an agent through Relay's orchestrator. Gated: requires the command:shutdown scope; an agent caller may only target its OWN live spawned children, addressed by agentId or spawnRequestId (policyName/tmuxSession are admin-only broad targets). Admin tokens keep full reach.",
+    requiredScopes: ["command:shutdown"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        agentId: { type: "string", description: "Target child by agent id. For an agent caller, agentId or spawnRequestId identifies your spawned child." },
+        policyName: { type: "string", description: "Broad target by managed-agent policy — admin/full-reach callers only." },
+        spawnRequestId: { type: "string", description: "Target child by the idempotency key relay_spawn_agent returned — resolved to your spawned child server-side." },
+        tmuxSession: { type: "string", description: "Broad target by tmux session — admin/full-reach callers only." },
+        orchestratorId: { type: "string" },
+        reason: { type: "string" },
+        timeoutMs: { type: "integer", minimum: 1 },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const input: SpawnAgentInput = {
+    provider: enumField(args.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider,
+    orchestratorId: optionalString(args.orchestratorId, "orchestratorId", 200),
+    cwd: optionalString(args.cwd, "cwd", 500),
+    model: optionalString(args.model, "model", 120),
+    effort: optionalString(args.effort, "effort", 120) as ProviderEffort | undefined,
+    approvalMode: optionalEnum(args.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined,
+    workspaceMode: optionalEnum(args.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES) as WorkspaceMode | undefined,
+    lifecycle: (optionalEnum(args.lifecycle, "lifecycle", VALID_AGENT_LIFECYCLES) as AgentLifecycle | undefined) ?? "persistent",
+    label: optionalString(args.label, "label", 120),
+    policyName: optionalString(args.policyName, "policyName", 120),
+    profile: optionalString(args.profile, "profile", 120),
+    prompt: optionalString(args.prompt, "prompt", 16_000),
+    expectReply: typeof args.expectReply === "boolean" ? args.expectReply : undefined,
+    systemPromptAppend: optionalString(args.systemPromptAppend, "systemPromptAppend", 64_000),
+    projectInstructions: parseProjectInstructions(args.projectInstructions, (m) => new ValidationError(m)),
+    tags: optionalStringArray(args.tags, "tags"),
+    capabilities: optionalStringArray(args.capabilities, "capabilities"),
+    providerArgs: optionalStringArray(args.providerArgs, "providerArgs"),
+    spawnRequestId: optionalString(args.spawnRequestId, "spawnRequestId", 160),
+    requestedVia: "mcp",
+    waitForRegistrationMs: optionalNonNegativeInt(args.waitForRegistrationMs, "waitForRegistrationMs") ?? 8000,
+  };
+  const result = await spawnAgent(input, authContextFromMcp(auth));
+  return { ...result };
+}
+
+export function relaySpawnTargets(auth: McpAuthContext): Record<string, unknown> {
+  return buildSpawnTargets({
+    callerId: callerAgentId(auth),
+    quota: auth.component?.constraints?.maxSpawnedAgents ?? 0,
+  });
+}
+
+export function relayShutdownAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const agentId = optionalString(args.agentId, "agentId", 240);
+  const policyName = optionalString(args.policyName, "policyName", 120);
+  const spawnRequestId = optionalString(args.spawnRequestId, "spawnRequestId", 160);
+  const tmuxSession = optionalString(args.tmuxSession, "tmuxSession", 200);
+  if (!agentId && !policyName && !spawnRequestId && !tmuxSession) {
+    throw new ValidationError("agentId, policyName, spawnRequestId, or tmuxSession required");
+  }
+
+  try {
+    const result = shutdownAgent(
+      {
+        agentId,
+        policyName,
+        spawnRequestId,
+        tmuxSession,
+        orchestratorId: optionalString(args.orchestratorId, "orchestratorId", 200),
+        graceful: true,
+        timeoutMs: optionalPositiveInt(args.timeoutMs, "timeoutMs") ?? 10_000,
+        reason: optionalString(args.reason, "reason", 200) ?? "mcp-shutdown",
+        requestedVia: "mcp",
+        requestedBy: auth.actor,
+      },
+      authContextFromMcp(auth),
+    );
+    return { ok: true, action: "shutdown", orchestratorId: result.orchestratorId, command: result.command };
+  } catch (e) {
+    if (e instanceof ShutdownAuthError) throw new McpAuthError(e.message);
+    if (e instanceof ShutdownTargetError) throw new McpNotFoundError(e.message);
+    throw e;
+  }
+}