npm - agent-relay-server - Versions diffs - 0.21.0 → 0.22.0 - Mend

agent-relay-server 0.21.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/docs/openapi.json +4 -1
package/package.json +2 -2
package/public/index.html +227 -94
package/src/cli.ts +62 -8
package/src/maintenance.ts +9 -4
package/src/mcp.ts +244 -2
package/src/routes.ts +79 -167
package/src/workspace-actions.ts +336 -0
package/src/workspace-phase.ts +181 -0

package/src/cli.ts CHANGED Viewed

@@ -48,8 +48,9 @@ import { DEFAULT_CONTEXT_PROBE_STATE_DIR, runContextProbe } from "agent-relay-sd
 import { shellQuote } from "agent-relay-sdk/shell-utils";
 import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
+import { describeWorkspacePhase, readyContract, type WorkspacePhaseView } from "./workspace-phase";
-export const WORKSPACE_USAGE = "Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--check] [--execute] [--json]";
+export const WORKSPACE_USAGE = "Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]";
 const HELP = `
 agent-relay ${VERSION}
@@ -70,7 +71,7 @@ Usage:
   agent-relay context-probe [print-status-line] [--wrap COMMAND] [--agent-id ID] [--state-dir DIR] [--standalone]
   agent-relay token <create|list|revoke|verify> [options]
   agent-relay pair <target|create|status|accept|reject|hangup|send> [options]
-  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--check] [--execute] [--json]
+  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]
   agent-relay steward <queue|inspect|checks> [WORKSPACE_ID] [--repo PATH] [--json]
   agent-relay message <target> <body> [options]
   agent-relay get-message <messageId> [--json|--body]
@@ -237,9 +238,17 @@ Isolated workspaces
   Relay does. Just commit your work in the worktree, then:
     agent-relay workspace ready    Hand off: Relay rebases onto the latest base,
                                    lands your work, and pushes.
-    agent-relay workspace status   Show your workspace's branch, base, status.
+    agent-relay workspace status   Show your workspace's state + what to do next.
+    agent-relay workspace status --wait
+                                   Block until your branch lands (returns the
+                                   moment the auto-merge completes).
+  After "ready", status is "review_requested" — this is NORMAL, not an
+  escalation. Relay auto-merges clean rebases ~every 2 min; a steward agent is
+  spawned only if it can't land deterministically, so no steward = healthy. On
+  landing you move onto a fresh rebased branch (name gains a "--N" suffix).
   The base branch will move as other agents land in parallel — that is normal,
-  let the merge handle it. Never push your branch yourself; it is local-only.
+  let the merge handle it. Never push, merge, resolve conflicts, or touch the
+  main checkout yourself; it is local-only and Relay (and the steward) own that.
   If typecheck/build fails on a missing module (a dep added to the base after
   your worktree was created), do NOT run a clean install — it mutates the shared
   node_modules. Instead refresh your worktree's deps in isolation:
@@ -1529,14 +1538,31 @@ function currentWorkspaceId(): string | undefined {
   }
 }
-function formatWorkspaceStatus(ws: any): string {
+function formatWorkspaceStatus(ws: any, extra?: { guidance?: WorkspacePhaseView; landed?: string | null }): string {
+  // Render the directive projection so the agent gets "what does this mean / what
+  // do I do next" inline, not a bare enum it has to decode (#235). Computed
+  // client-side from the record (the projection is pure) unless the wait response
+  // already carried it.
+  const guidance = extra?.guidance ?? describeWorkspacePhase(ws);
   const lines = [
     `Workspace ${ws.id}`,
-    `  status:   ${ws.status}`,
+    `  status:   ${ws.status}  (${guidance.phase}${guidance.actionNeeded ? "" : " — no action needed"})`,
     `  branch:   ${ws.branch ?? "(none)"}`,
     `  base:     ${ws.baseRef ?? "(none)"}`,
     `  worktree: ${ws.worktreePath ?? "(none)"}`,
+    "",
+    `  ${guidance.headline}`,
+    `  ${guidance.hint}`,
   ];
+  if (guidance.blockers.length) {
+    lines.push("", "  Blockers:");
+    for (const b of guidance.blockers) lines.push(`    - ${b}`);
+  }
+  if (guidance.nextActions.length) {
+    lines.push("", "  Next:");
+    for (const a of guidance.nextActions) lines.push(`    - ${a.cli ?? a.tool} — ${a.when}`);
+  }
+  if (extra?.landed) lines.push("", `  ${extra.landed}`);
   return lines.join("\n");
 }
@@ -1594,6 +1620,8 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
   let execute = false;
   let check = false;
   let json = false;
+  let wait = false;
+  let timeoutSeconds: number | undefined;
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--id" && i + 1 < args.length) id = args[++i];
@@ -1603,6 +1631,12 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
     else if (arg === "--execute") execute = true;
     else if (arg === "--check") check = true;
     else if (arg === "--refresh") check = false; // explicit no-op default for clarity
+    else if (arg === "--wait") wait = true;
+    else if (arg === "--timeout" && i + 1 < args.length) {
+      const parsed = Number.parseInt(args[++i]!, 10);
+      if (!Number.isFinite(parsed) || parsed <= 0) throw new Error("--timeout must be a positive number of seconds");
+      timeoutSeconds = parsed;
+    }
     else if (arg === "--json") json = true;
     else throw new Error(`Unknown workspace option "${arg}".`);
   }
@@ -1621,6 +1655,20 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
   if (!id) throw new Error("No current workspace detected (AGENT_RELAY_WORKSPACE_JSON unset). Pass --id WORKSPACE_ID — only isolated-workspace agents have one.");
   if (action === "status") {
+    // --wait long-polls via the action endpoint (server blocks until the status
+    // changes — the blessed way to wait for an auto-merge to land, #235), and the
+    // response carries the directive projection + land receipt. Plain status is a
+    // bare GET; the projection is computed client-side for rendering.
+    if (wait) {
+      const res = await apiRequest("POST", `/api/workspaces/${encodeURIComponent(id)}/actions`, {
+        action: "status",
+        wait: true,
+        ...(timeoutSeconds ? { timeoutSeconds } : {}),
+      }) as { workspace?: any; guidance?: WorkspacePhaseView; landed?: string | null };
+      if (json) { console.log(JSON.stringify(res, null, 2)); return; }
+      console.log(formatWorkspaceStatus(res.workspace ?? res, { guidance: res.guidance, landed: res.landed }));
+      return;
+    }
     const ws = await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}`);
     if (json) console.log(JSON.stringify(ws, null, 2));
     else console.log(formatWorkspaceStatus(ws));
@@ -1669,9 +1717,15 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
+  if (action === "ready") {
+    // Print the whole contract up front so the agent isn't left decoding status
+    // enums over the next minutes (#235). `result.workspace` is the post-ready row.
+    const ws = (result as { workspace?: any }).workspace ?? { status: "review_requested" };
+    console.log(`Workspace ${id} marked ready.\n\n${readyContract(ws)}`);
+    return;
+  }
   console.log(
-    action === "ready" ? `Workspace ${id} marked ready — Relay will rebase onto the latest base, land, and push.`
-    : action === "claim" ? `Workspace ${id} claimed${purpose ? ` (${purpose})` : ""} — auto-merge will yield until released or the claim expires.`
+    action === "claim" ? `Workspace ${id} claimed${purpose ? ` (${purpose})` : ""} — auto-merge will yield until released or the claim expires.`
     : action === "release" ? `Workspace ${id} claim released.`
     : `Workspace ${id} merge requested (${strategy ?? "auto"}).`,
   );

package/src/maintenance.ts CHANGED Viewed

@@ -34,6 +34,7 @@ import {
 import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./types";
 import { requestWorkspaceMerge } from "./workspace-merge";
 import { workspaceActiveClaim } from "./workspace-claim";
+import { TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
 import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import { getStewardConfig } from "./config-store";
 import { ensureRepoSteward } from "./steward";
@@ -86,7 +87,6 @@ const STRANDABLE_STATUSES = new Set<WorkspaceStatus>(["review_requested", "confl
 // Live statuses worth scanning. Terminal (cleaned/merged/abandoned) and
 // in-flight (cleanup_requested) states are skipped.
 const CONFLICT_SCAN_STATUSES = new Set<WorkspaceStatus>(["active", "ready", "review_requested", "merge_planned", "conflict"]);
-const TERMINAL_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(["cleaned", "merged", "abandoned"]);
 // In-flight merge statuses that should reconcile to `merged` once the host
 // reports the branch's work has landed in base (squash/cherry-pick, or a merged
 // PR). Excludes active/ready: an agent still working may have landed an early
@@ -695,7 +695,10 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
     // base, and mergeRebaseFf rebases then aborts-to-conflict on a real replay
     // conflict, so a too-optimistic prediction degrades safely to review_requested.
     // Only a predicted conflict (true) or unknown state (undefined) goes to the steward.
-    const canLand = p.conflict === false && ahead > 0;
+    // A no-op (#230) — nothing to land (ahead=0, clean) — is also landable: the host
+    // resolves it to a terminal `merged` status, draining the queue instead of waking
+    // the steward every sweep for a workspace with no work.
+    const canLand = p.noop === true || (p.conflict === false && ahead > 0);
     if (!canLand) {
       leftForSteward.push(ws.id);
       if (stewardEnabled) {
@@ -716,8 +719,10 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
     createActivityEvent({
       clientId: `workspace-auto-merge-${ws.id}-${Date.now()}`,
       kind: "state",
-      title: behind > 0 ? "Workspace auto-merging (rebase)" : "Workspace auto-merging (clean fast-forward)",
-      body: `${ws.branch ?? ws.id} → ${p.baseRef ?? "base"} (${ahead} ahead${behind > 0 ? `, ${behind} behind — rebasing` : ", clean"})`,
+      title: p.noop ? "Workspace auto-resolving (no work to merge)" : behind > 0 ? "Workspace auto-merging (rebase)" : "Workspace auto-merging (clean fast-forward)",
+      body: p.noop
+        ? `${ws.branch ?? ws.id} → ${p.baseRef ?? "base"} (nothing to land — resolving to merged)`
+        : `${ws.branch ?? ws.id} → ${p.baseRef ?? "base"} (${ahead} ahead${behind > 0 ? `, ${behind} behind — rebasing` : ", clean"})`,
       meta: ws.branch ?? ws.id,
       icon: "ti-git-merge",
       view: "orchestrators",

package/src/mcp.ts CHANGED Viewed

@@ -16,10 +16,13 @@ import {
   getArtifact,
   getMessage,
   getOrchestrator,
+  getRepoSteward,
   getTask,
   getThread,
+  getWorkspace,
   linkArtifact,
   listAgents,
+  listWorkspaces,
   searchAgents,
   type AgentSearchFilter,
   type AgentSearchSort,
@@ -40,7 +43,9 @@ import {
   isComponentAuthorizedFor,
   isIntegrationAllowed,
 } from "./security";
-import type { ActivityKind, AgentCard, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider } from "./types";
+import type { ActivityKind, AgentCard, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
+import { applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
+import { describeWorkspacePhase, landReceipt, readyContract, TERMINAL_WORKSPACE_STATUSES, worktreeMcpInstructions } from "./workspace-phase";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { errMessage, isRecord, SPAWN_PROVIDERS, APPROVAL_MODES, VALID_EFFORTS } from "agent-relay-sdk";
 import { runnerRuntimeTokenEnv } from "./runtime-tokens";
@@ -67,6 +72,12 @@ type ToolDefinition = {
   description: string;
   requiredScopes: string[];
   inputSchema: Record<string, unknown>;
+  // Emit `_meta: { "anthropic/alwaysLoad": true }` in tools/list so Claude Code
+  // (v2.1.121+) loads this tool's schema EAGERLY instead of deferring it behind a
+  // ToolSearch round-trip. Reserve for the few verbs most agents use every session
+  // (the doc warns each one costs context every turn). Verified convention; same
+  // mechanism callmux's per-tool alwaysLoad uses.
+  alwaysLoad?: boolean;
 };
 const MCP_PROTOCOL_VERSION = "2024-11-05";
@@ -279,6 +290,108 @@ const TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
+  {
+    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 the workspace you own; 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)." },
+        deleteBranch: { type: "boolean", description: "Delete the branch after a successful merge (default true)." },
+        prTitle: { type: "string" },
+        prBody: { type: "string" },
+        detail: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
 ];
 export async function postMcp(req: Request): Promise<Response> {
@@ -296,10 +409,14 @@ export async function postMcp(req: Request): Promise<Response> {
     }
     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.
+      const worktree = callerIsolatedWorkspace(auth);
       return Response.json(jsonRpcResult(id, {
         protocolVersion: MCP_PROTOCOL_VERSION,
         capabilities: { tools: {} },
         serverInfo: { name: "agent-relay", title: "Agent Relay", version: VERSION },
+        ...(worktree ? { instructions: worktreeMcpInstructions(worktree) } : {}),
       }));
     }
     if (method === "notifications/initialized") {
@@ -370,6 +487,13 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_whoami") result = relayWhoami(auth);
     else if (name === "relay_spawn_agent") result = relaySpawnAgent(auth, args);
     else if (name === "relay_shutdown_agent") result = relayShutdownAgent(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 throw new ValidationError(`unknown tool: ${name}`);
     auditToolCall(auth, name, "ok", result);
@@ -771,6 +895,119 @@ function relayShutdownAgent(auth: McpAuthContext, args: Record<string, unknown>)
   return { ok: true, action: "shutdown", orchestratorId: orchestrator.id, command };
 }
+// --- Workspace lifecycle tools (#215) -------------------------------------
+// Thin MCP surface over the shared applyWorkspaceAction core. Coarse scope is
+// enforced in callTool; here we add the resource check the routes' authorizeRoute
+// does: an agent may only act on a workspace it OWNS or stewards (server/wildcard
+// tokens keep full reach). Defaults the target to the caller's own workspace so a
+// branch agent never has to hunt for its workspace id.
+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;
+  // The repo's elected steward (authoritative repo_stewards record, not the mirrored
+  // workspace column which only updates on steward change) may reconcile any
+  // workspace in its repo — the conflict-landing flow it exists for.
+  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;
+}
+// Non-throwing variant for the initialize primer: the caller's most recently
+// active isolated worktree, or undefined (no caller identity / shared-only).
+// listWorkspaces is ORDER BY updated_at DESC → most recent worktree first.
+function callerIsolatedWorkspace(auth: McpAuthContext): WorkspaceRecord | undefined {
+  const caller = callerAgentId(auth);
+  if (!caller) return undefined;
+  return listWorkspaces({ ownerAgentId: caller }).find((w) => w.mode === "isolated" && !TERMINAL_WORKSPACE_STATUSES.has(w.status));
+}
+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,
+  };
+}
+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 };
+}
+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", ["pr", "rebase-ff", "auto"] as const) as WorkspaceMergeStrategy | undefined) : undefined,
+    deleteBranch: action === "merge" ? optionalBoolean(args.deleteBranch, "deleteBranch") : undefined,
+    prTitle: optionalString(args.prTitle, "prTitle", 240),
+    prBody: optionalString(args.prBody, "prBody", 8000),
+    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;
+  // After a `ready` hand-off, state the whole contract up front + the directive
+  // next-step, so the agent doesn't decode status enums over the next minutes (#235).
+  if (action === "ready") {
+    payload.contract = readyContract(result.workspace);
+    payload.guidance = describeWorkspacePhase(result.workspace);
+  }
+  return payload;
+}
 function replyContext(parent: Message): Record<string, unknown> {
   const parentPayload = parent.payload ?? {};
   if (parentPayload.schema !== "agent-relay.channel.v1" && !parentPayload.conversation) return {};
@@ -934,7 +1171,12 @@ function emitMessage(message: Message, created: boolean): void {
 function visibleTools(auth: McpAuthContext): Array<Record<string, unknown>> {
   return TOOLS
     .filter((tool) => hasAnyScope(auth, tool.requiredScopes))
-    .map(({ name, description, inputSchema }) => ({ name, description, inputSchema }));
+    .map(({ name, description, inputSchema, alwaysLoad }) => ({
+      name,
+      description,
+      inputSchema,
+      ...(alwaysLoad ? { _meta: { "anthropic/alwaysLoad": true } } : {}),
+    }));
 }
 function toolResult(result: unknown): Record<string, unknown> {