agent-relay-server 0.62.2 → 0.63.0

package/src/mcp/tools-workspace.ts

@@ -0,0 +1,227 @@
+import { getRepoSteward, getWorkspace, listWorkspaces, ownedIsolatedWorkspace, ValidationError } from "../db";
+import { emitRelayEvent } from "../events";
+import { McpAuthError, McpNotFoundError } from "../mcp-errors";
+import { AUTO_MERGE_POLICIES } from "../workspace-merge";
+import { describeWorkspacePhase, landReceipt, readyContract } from "../workspace-phase";
+import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "../workspace-actions";
+import { optionalEnum } from "../validation";
+import type { Command, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceRecord } from "../types";
+import type { McpAuthContext, ToolDefinition } from "./types";
+import { callerAgentId, hasScope } from "./identity";
+import { optionalBoolean, optionalPositiveInt, optionalString } from "./validation";
+
+export const WORKSPACE_TOOLS: ToolDefinition[] = [
+  {
+    name: "relay_workspace_status",
+    description: "Get your isolated workspace's lifecycle status (active/ready/conflict/review_requested/merged/...). With wait:true this BLOCKS until the status changes — use it after relay_workspace_ready to wait for the auto-merge to land your branch on main (status leaves 'ready' → merged/recycled-to-active with a fresh rebased branch) or to surface a conflict/review_requested the steward couldn't auto-resolve. Defaults to your own workspace; pass workspaceId to target another.",
+    requiredScopes: ["agents:read", "agent:read", "agent:write"],
+    alwaysLoad: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string", description: "Defaults to your own isolated workspace (resolved from your identity)." },
+        wait: { type: "boolean", description: "Block until the workspace status changes (the actionable signal), or until the timeout." },
+        timeoutSeconds: { type: "integer", minimum: 1, maximum: 600, description: "Max seconds to wait when wait:true (default 300, max 600). Returns early on any transition." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_workspace_ready",
+    description: "Signal that your branch work is finished and ready to merge back to main. This kicks off the auto-merge-back: a clean merge lands immediately; on conflict a steward agent reconciles and lands it (escalating if it can't). After this, poll relay_workspace_status with wait:true until it lands and you get a fresh rebased branch to continue on. Defaults to your own workspace.",
+    requiredScopes: ["agent:write"],
+    alwaysLoad: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
+        detail: { type: "string", description: "Optional note recorded on the activity feed." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_workspace_deps",
+    description: "Re-provision your worktree's dependencies when the shared symlinked node_modules has gone stale (e.g. typecheck reports a missing module). checkOnly:true just reports staleness without changing anything. Self-service — acts only on your own worktree.",
+    requiredScopes: ["agent:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
+        checkOnly: { type: "boolean", description: "Report staleness only; do not re-provision." },
+        detail: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_workspace_list",
+    description: "List the isolated workspaces you own (id, branch, status, repo). Use it when you're unsure which workspace is yours or to see a workspace's current state. Admin/server tokens may pass all:true to list every workspace.",
+    requiredScopes: ["agents:read", "agent:read", "agent:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        all: { type: "boolean", description: "Admin/server only: list all workspaces, not just your own." },
+        ownerAgentId: { type: "string", description: "Admin/server + all:true: filter to one owner." },
+        repoRoot: { type: "string", description: "Filter to one repository root." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_workspace_claim",
+    description: "Take a TTL'd steward claim on a workspace so the deterministic auto-merge yields to you while you reconcile a conflict. Renew/hold while validating; relay_workspace_release frees it. Owner or assigned steward only.",
+    requiredScopes: ["agent:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
+        purpose: { type: "string", description: "Why you're claiming (shown in the activity feed)." },
+        detail: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_workspace_release",
+    description: "Release a steward claim taken with relay_workspace_claim, letting the auto-merge resume. Owner or assigned steward only.",
+    requiredScopes: ["agent:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
+        purpose: { type: "string" },
+        detail: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_workspace_land",
+    description: "Dispatch a base merge for your workspace directly (lease-serialized per repo, same path the auto-merge job uses). Most branch agents should use relay_workspace_ready instead and let the relay land it; this is the explicit/steward path and requires the command:write scope.",
+    requiredScopes: ["command:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
+        strategy: { type: "string", enum: ["pr", "rebase-ff", "auto"], description: "Merge strategy (default auto). Falls back to the instance landing.strategy config when unset." },
+        deleteBranch: { type: "boolean", description: "Delete the branch after a successful merge (default true)." },
+        prTitle: { type: "string" },
+        prBody: { type: "string" },
+        autoMerge: { type: "string", enum: AUTO_MERGE_POLICIES, description: "Auto-merge policy for PR-strategy lands. Defaults to 'on-green' when strategy resolves to 'pr'. Ignored for rebase-ff/auto strategies." },
+        reviewer: { type: "string", description: "GitHub login or team slug to request as a reviewer on the opened PR (pr strategy only)." },
+        detail: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+function isWorkspaceAdmin(auth: McpAuthContext): boolean {
+  return auth.kind === "server" || hasScope(auth, "*");
+}
+
+function assertWorkspaceAccess(auth: McpAuthContext, ws: WorkspaceRecord, caller: string | undefined): void {
+  if (isWorkspaceAdmin(auth)) return;
+  if (!caller) throw new McpAuthError(`not authorized for workspace ${ws.id} (its owner or assigned steward only)`);
+  if (caller === ws.ownerAgentId) return;
+  if (caller === getRepoSteward(ws.repoRoot)?.stewardAgentId) return;
+  throw new McpAuthError(`not authorized for workspace ${ws.id} (its owner or assigned steward only)`);
+}
+
+function resolveWorkspaceForCaller(auth: McpAuthContext, args: Record<string, unknown>): WorkspaceRecord {
+  const explicitId = optionalString(args.workspaceId, "workspaceId", 240);
+  const caller = callerAgentId(auth);
+  if (explicitId) {
+    const ws = getWorkspace(explicitId);
+    if (!ws) throw new McpNotFoundError(`workspace ${explicitId} not found`);
+    assertWorkspaceAccess(auth, ws, caller);
+    return ws;
+  }
+  if (!caller) throw new ValidationError("workspaceId is required: no caller agent identity to resolve your own workspace");
+  const first = callerIsolatedWorkspace(auth);
+  if (!first) throw new McpNotFoundError("you don't own an isolated workspace; pass workspaceId");
+  return first;
+}
+
+export function callerIsolatedWorkspace(auth: McpAuthContext): WorkspaceRecord | undefined {
+  const caller = callerAgentId(auth);
+  if (!caller) return undefined;
+  return ownedIsolatedWorkspace(caller);
+}
+
+export async function relayWorkspaceStatus(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const ws = resolveWorkspaceForCaller(auth, args);
+  if (optionalBoolean(args.wait, "wait") !== true) {
+    return { workspace: ws, guidance: describeWorkspacePhase(ws), transitioned: false, timedOut: false };
+  }
+  const timeoutSeconds = optionalPositiveInt(args.timeoutSeconds, "timeoutSeconds");
+  const result = await waitForWorkspaceStatus(ws.id, timeoutSeconds ? { timeoutMs: timeoutSeconds * 1000 } : {});
+  if (!result.workspace) throw new McpNotFoundError(`workspace ${ws.id} not found`);
+  const landed = result.transitioned ? landReceipt(result.fromStatus, result.workspace) : null;
+  return {
+    workspace: result.workspace,
+    guidance: describeWorkspacePhase(result.workspace),
+    ...(landed ? { landed } : {}),
+    fromStatus: result.fromStatus,
+    transitioned: result.transitioned,
+    timedOut: result.timedOut,
+  };
+}
+
+export function relayWorkspaceList(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const filter: { ownerAgentId?: string; repoRoot?: string } = {};
+  const repoRoot = optionalString(args.repoRoot, "repoRoot", 1024);
+  if (repoRoot) filter.repoRoot = repoRoot;
+  if (isWorkspaceAdmin(auth) && optionalBoolean(args.all, "all") === true) {
+    const owner = optionalString(args.ownerAgentId, "ownerAgentId", 240);
+    if (owner) filter.ownerAgentId = owner;
+  } else {
+    const caller = callerAgentId(auth);
+    if (!caller) throw new ValidationError("no caller agent identity to list your workspaces");
+    filter.ownerAgentId = caller;
+  }
+  const workspaces = listWorkspaces(filter);
+  return { workspaces, count: workspaces.length };
+}
+
+export function relayWorkspaceMutation(auth: McpAuthContext, action: WorkspaceAction, args: Record<string, unknown>): Record<string, unknown> {
+  const ws = resolveWorkspaceForCaller(auth, args);
+  const result = applyWorkspaceAction(ws, {
+    action,
+    agentId: callerAgentId(auth) ?? auth.actor,
+    detail: optionalString(args.detail, "detail", 4000),
+    strategy: action === "merge" ? (optionalEnum(args.strategy, "strategy", LAND_STRATEGIES) as WorkspaceMergeStrategy | undefined) : undefined,
+    deleteBranch: action === "merge" ? optionalBoolean(args.deleteBranch, "deleteBranch") : undefined,
+    prTitle: optionalString(args.prTitle, "prTitle", 240),
+    prBody: optionalString(args.prBody, "prBody", 8000),
+    autoMerge: action === "merge" ? (optionalEnum(args.autoMerge, "autoMerge", AUTO_MERGE_POLICIES) as WorkspaceAutoMergePolicy | undefined) : undefined,
+    reviewer: action === "merge" ? optionalString(args.reviewer, "reviewer", 240) : undefined,
+    purpose: optionalString(args.purpose, "purpose", 120),
+    checkOnly: action === "deps-refresh" ? optionalBoolean(args.checkOnly, "checkOnly") === true : undefined,
+    auditMetadata: { via: "mcp", actor: auth.actor },
+  });
+  if (!result.ok) {
+    if (result.httpStatus === 404) throw new McpNotFoundError(result.error);
+    if (result.httpStatus === 403) throw new McpAuthError(result.error);
+    throw new ValidationError(result.error);
+  }
+  if (result.command) emitCommand(result.command);
+  const payload: Record<string, unknown> = { workspace: result.workspace };
+  if (result.command) payload.command = result.command;
+  if (result.claim !== undefined) payload.claim = result.claim;
+  if (action === "ready") {
+    payload.contract = readyContract(result.workspace);
+    payload.guidance = describeWorkspacePhase(result.workspace);
+  }
+  return payload;
+}
+
+function emitCommand(command: Command): void {
+  emitRelayEvent({
+    type: command.status === "pending" ? "command.requested" : `command.${command.status}`,
+    source: command.source,
+    subject: command.id,
+    data: { command },
+  });
+}

package/src/mcp/types.ts

@@ -0,0 +1,24 @@
+import type { IntegrationTokenConfig } from "../config";
+import type { ComponentToken } from "../types";
+
+export type JsonRpcId = string | number | null;
+
+export type JsonRpcRequest = { jsonrpc?: "2.0"; id?: JsonRpcId; method?: string; params?: unknown };
+
+export type McpAuthContext = {
+  actor: string;
+  kind: "component" | "integration" | "server";
+  scopes: string[];
+  component?: ComponentToken;
+  integration?: IntegrationTokenConfig;
+};
+
+export type ToolDefinition = {
+  name: string;
+  description: string;
+  requiredScopes: string[];
+  inputSchema: Record<string, unknown>;
+  // Emit `_meta: { "anthropic/alwaysLoad": true }` in tools/list so Claude Code
+  // loads this tool schema eagerly. Reserve this for the few verbs used every session.
+  alwaysLoad?: boolean;
+};

package/src/mcp/validation.ts

@@ -0,0 +1,104 @@
+import { optionalEnum } from "../validation";
+import { ValidationError } from "../db";
+import type { AttachmentRef } from "../types";
+import { isRecord } from "agent-relay-sdk";
+
+export function recordField(value: unknown, field: string): Record<string, unknown> {
+  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
+  return value;
+}
+
+export function optionalRecord(value: unknown, field: string): Record<string, unknown> | undefined {
+  if (value === undefined || value === null) return undefined;
+  return recordField(value, field);
+}
+
+export function stringField(
+  value: unknown,
+  field: string,
+  opts: { required?: boolean; max?: number; maxBytes?: number } = {},
+): string {
+  if (value === undefined || value === null) {
+    if (opts.required) throw new ValidationError(`${field} required`);
+    return "";
+  }
+  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`);
+  const trimmed = value.trim();
+  if (opts.required && !trimmed) throw new ValidationError(`${field} required`);
+  if (opts.max && trimmed.length > opts.max) throw new ValidationError(`${field} must be ${opts.max} characters or fewer`);
+  if (opts.maxBytes && encodedLength(trimmed) > opts.maxBytes) throw new ValidationError(`${field} exceeds ${opts.maxBytes} bytes`);
+  return trimmed;
+}
+
+export function optionalString(value: unknown, field: string, max: number): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  const cleaned = stringField(value, field, { max });
+  return cleaned || undefined;
+}
+
+export function optionalBoolean(value: unknown, field: string): boolean | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
+  return value;
+}
+
+export function enumField<T extends readonly string[]>(value: unknown, field: string, valid: T): T[number] {
+  const cleaned = optionalEnum(value, field, valid);
+  if (!cleaned) throw new ValidationError(`${field} required`);
+  return cleaned;
+}
+
+export function optionalStringArray(value: unknown, field: string): string[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array of strings`);
+  const cleaned = value.map((item, index) => stringField(item, `${field}[${index}]`, { required: true, max: 120 }));
+  if (cleaned.length > 50) throw new ValidationError(`${field} can contain at most 50 values`);
+  return [...new Set(cleaned)];
+}
+
+export function positiveId(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new ValidationError(`${field} must be a positive integer`);
+  return value;
+}
+
+export function positiveIdOrUndefined(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+export function optionalPositiveInt(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new ValidationError(`${field} must be a positive integer`);
+  return value;
+}
+
+export function optionalNonNegativeInt(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new ValidationError(`${field} must be a non-negative integer`);
+  return value;
+}
+
+export function optionalFutureTimestamp(value: unknown, field: string): number | undefined {
+  const timestamp = optionalPositiveInt(value, field);
+  if (timestamp !== undefined && timestamp <= Date.now()) throw new ValidationError(`${field} must be a future unix timestamp in milliseconds`);
+  return timestamp;
+}
+
+export function optionalAttachments(value: unknown): AttachmentRef[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) throw new ValidationError("attachments must be an array");
+  return value.map((item, index) => {
+    const record = recordField(item, `attachments[${index}]`);
+    return {
+      artifactId: stringField(record.artifactId, `attachments[${index}].artifactId`, { required: true, max: 120 }),
+      kind: optionalString(record.kind, `attachments[${index}].kind`, 40) as AttachmentRef["kind"],
+      role: optionalString(record.role, `attachments[${index}].role`, 40) as AttachmentRef["role"],
+      title: optionalString(record.title, `attachments[${index}].title`, 240),
+      ref: optionalRecord(record.ref, `attachments[${index}].ref`) as AttachmentRef["ref"],
+      metadata: optionalRecord(record.metadata, `attachments[${index}].metadata`),
+    };
+  });
+}
+
+function encodedLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}