agent-relay-server 0.20.0 → 0.22.0

package/src/workspace-actions.ts

@@ -0,0 +1,336 @@
+// Single home for workspace lifecycle actions, shared by the HTTP route
+// (`POST /api/workspaces/:id/actions`) and the `relay_workspace_*` MCP tools.
+//
+// Why this module exists: the action→status mapping, claim/merge/deps branching,
+// and the per-action audit descriptors are exactly the kind of rule that used to
+// live in one handler and silently drift when a second surface re-implemented it.
+// Both surfaces authorize FIRST (route via authorizeRoute, MCP via token scopes)
+// and then call `applyWorkspaceAction` — which does NO auth. Like
+// `requestWorkspaceMerge`, the core does not emit the command event; it returns
+// the Command and the caller emits via its own `emitCommand` (kept module-local).
+
+import { createCommand } from "./commands-db";
+import { isPathWithinBase } from "./utils";
+import {
+  createActivityEvent,
+  getWorkspace,
+  listOrchestrators,
+  patchWorkspaceMetadata,
+  updateWorkspaceStatus,
+} from "./db";
+import { emitActivityEvent } from "./sse";
+import { requestWorkspaceMerge } from "./workspace-merge";
+import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
+import type { Command, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
+
+// Single source of truth for the action verb set. The route's `optionalEnum` and
+// the MCP tool surface both import this so they can never drift out of sync.
+export const WORKSPACE_ACTIONS = [
+  "status",
+  "ready",
+  "conflict-found",
+  "request-review",
+  "merge-plan",
+  "merge",
+  "abandon",
+  "cleanup",
+  "claim",
+  "release-claim",
+  "deps-refresh",
+] as const;
+export type WorkspaceAction = (typeof WORKSPACE_ACTIONS)[number];
+
+export interface ApplyWorkspaceActionInput {
+  action: WorkspaceAction;
+  agentId?: string;
+  detail?: string;
+  metadata?: Record<string, unknown>;
+  // merge
+  strategy?: WorkspaceMergeStrategy;
+  deleteBranch?: boolean;
+  prTitle?: string;
+  prBody?: string;
+  // claim / release-claim
+  purpose?: string;
+  // deps-refresh
+  checkOnly?: boolean;
+  // Provenance merged into the activity-event metadata (who/how) — the HTTP route
+  // passes `authAuditMetadata(req)`, the MCP surface passes `{ via: "mcp", actor }`.
+  auditMetadata?: Record<string, unknown>;
+}
+
+export type WorkspaceActionResult =
+  | {
+      ok: true;
+      httpStatus: number;
+      workspace: WorkspaceRecord;
+      command?: Command;
+      claim?: ReturnType<typeof workspaceActiveClaim>;
+    }
+  | { ok: false; httpStatus: number; error: string };
+
+// Map of the plain status-transition actions to their target status. merge/cleanup
+// (command-emitting) and status/claim/release/deps (special) are handled explicitly.
+const STATUS_BY_ACTION: Partial<Record<WorkspaceAction, WorkspaceStatus>> = {
+  ready: "ready",
+  "conflict-found": "conflict",
+  "request-review": "review_requested",
+  "merge-plan": "merge_planned",
+  abandon: "abandoned",
+  cleanup: "cleanup_requested",
+};
+
+// Mirror of routes.ts `auditEvent` (source-tagged, never-throws) so the activity
+// feed gets identical entries whether the action came over HTTP or MCP.
+function recordWorkspaceAudit(a: {
+  action: WorkspaceAction;
+  workspace: WorkspaceRecord;
+  agentId?: string;
+  title: string;
+  body?: string;
+  icon: string;
+  auditMetadata?: Record<string, unknown>;
+  extra?: Record<string, unknown>;
+}): void {
+  try {
+    const event = createActivityEvent({
+      clientId: `workspace-${a.action}-${a.workspace.id}-${Date.now()}`,
+      kind: "state",
+      title: a.title,
+      body: a.body,
+      meta: a.workspace.branch ?? a.workspace.id,
+      icon: a.icon,
+      view: "orchestrators",
+      agentId: a.agentId,
+      metadata: {
+        source: "server",
+        action: a.action,
+        workspaceId: a.workspace.id,
+        repoRoot: a.workspace.repoRoot,
+        worktreePath: a.workspace.worktreePath,
+        ...(a.extra ?? {}),
+        ...(a.auditMetadata ?? {}),
+      },
+    });
+    emitActivityEvent(event);
+  } catch {
+    // Audit trail writes must never block relay behavior.
+  }
+}
+
+export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWorkspaceActionInput): WorkspaceActionResult {
+  const { action } = input;
+  const agentId = input.agentId;
+  const detail = input.detail;
+  const metadata = input.metadata ?? {};
+  const requiresCommand = action === "cleanup" || action === "merge";
+
+  // Shared-mode rows are occupancy markers with no worktree — nothing on disk to
+  // merge or clean. Reject host commands against them up front.
+  if (requiresCommand && (workspace.mode !== "isolated" || !workspace.worktreePath)) {
+    return { ok: false, httpStatus: 422, error: `workspace ${workspace.id} has no worktree to ${action}` };
+  }
+
+  if (action === "status") {
+    return { ok: true, httpStatus: 200, workspace };
+  }
+
+  // Steward claim/lease (#208): a TTL'd metadata lease that auto-merge yields to,
+  // so deterministic landing can't race a steward mid-validation. No status change.
+  if (action === "claim" || action === "release-claim") {
+    const release = action === "release-claim";
+    const updated = patchWorkspaceMetadata(workspace.id, claimMetadataPatch(release, agentId ?? "steward", input.purpose));
+    if (!updated) return { ok: false, httpStatus: 404, error: "workspace not found" };
+    recordWorkspaceAudit({
+      action,
+      workspace: updated,
+      agentId,
+      title: release ? "Workspace claim released" : "Workspace claimed",
+      body: detail ?? input.purpose ?? updated.worktreePath,
+      icon: "ti-lock",
+      auditMetadata: input.auditMetadata,
+    });
+    return { ok: true, httpStatus: 200, workspace: updated, claim: workspaceActiveClaim(updated) };
+  }
+
+  // Base merges go through the shared helper (lease + command + bind), the same
+  // path the auto-merge job uses, so both serialize per repo (issue #157).
+  if (action === "merge") {
+    const result = requestWorkspaceMerge(workspace, {
+      requestedBy: agentId ?? "dashboard",
+      strategy: input.strategy ?? "auto",
+      deleteBranch: input.deleteBranch !== false,
+      prTitle: input.prTitle,
+      prBody: input.prBody,
+      metadata: { ...metadata, ...(detail ? { detail } : {}), ...(agentId ? { updatedByAgentId: agentId } : {}) },
+    });
+    if (!result.ok) return { ok: false, httpStatus: result.status, error: result.error };
+    recordWorkspaceAudit({
+      action: "merge",
+      workspace: result.workspace,
+      agentId,
+      title: "Workspace merge",
+      body: detail ?? workspace.worktreePath,
+      icon: "ti-git-merge",
+      auditMetadata: input.auditMetadata,
+      extra: { status: result.workspace.status, commandId: result.command.id },
+    });
+    return { ok: true, httpStatus: 202, workspace: result.workspace, command: result.command };
+  }
+
+  // Deps refresh (#51): self-service for the owning agent — re-provision deps the
+  // shared symlinked node_modules has gone stale on (or, checkOnly, just report).
+  if (action === "deps-refresh") {
+    if (workspace.mode !== "isolated" || !workspace.worktreePath) {
+      return { ok: false, httpStatus: 422, error: `workspace ${workspace.id} has no isolated worktree to refresh` };
+    }
+    const checkOnly = input.checkOnly === true;
+    const built = buildWorkspaceDepsRefreshCommand(workspace, agentId ?? "agent", checkOnly);
+    if (!built.ok) return { ok: false, httpStatus: built.status, error: built.error };
+    recordWorkspaceAudit({
+      action,
+      workspace,
+      agentId,
+      title: checkOnly ? "Workspace deps check" : "Workspace deps refresh",
+      body: detail ?? workspace.worktreePath,
+      icon: "ti-package",
+      auditMetadata: input.auditMetadata,
+      extra: { checkOnly, commandId: built.command.id },
+    });
+    return { ok: true, httpStatus: 202, workspace, command: built.command };
+  }
+
+  const nextStatus = STATUS_BY_ACTION[action];
+  if (!nextStatus) return { ok: false, httpStatus: 400, error: `unsupported action: ${action}` };
+
+  const updated = updateWorkspaceStatus(workspace.id, nextStatus, {
+    ...metadata,
+    ...(detail ? { detail } : {}),
+    ...(agentId ? { updatedByAgentId: agentId } : {}),
+    lastWorkspaceAction: action,
+    lastWorkspaceActionAt: Date.now(),
+  });
+  if (!updated) return { ok: false, httpStatus: 404, error: "workspace not found" };
+
+  let command: Command | undefined;
+  if (requiresCommand) {
+    // Only `cleanup` reaches here — `merge` returned early via the shared helper.
+    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard");
+    if (!built.ok) return { ok: false, httpStatus: built.status, error: built.error };
+    command = built.command;
+  }
+  recordWorkspaceAudit({
+    action,
+    workspace: updated,
+    agentId,
+    title: `Workspace ${action}`,
+    body: detail ?? workspace.worktreePath,
+    icon: action === "cleanup" ? "ti-trash" : action === "conflict-found" ? "ti-alert-triangle" : "ti-git-branch",
+    auditMetadata: input.auditMetadata,
+    extra: { status: updated.status, commandId: command?.id },
+  });
+  return { ok: true, httpStatus: requiresCommand ? 202 : 200, workspace: updated, command };
+}
+
+// Build a `workspace.cleanup` command for the worktree's owning orchestrator.
+// Moved here (from routes.ts) so the MCP surface reaches it without importing routes.
+export function buildWorkspaceCleanupCommand(
+  workspace: WorkspaceRecord,
+  requestedBy: string,
+): { ok: true; command: Command } | { ok: false; status: number; error: string } {
+  const owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
+  const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
+  if (!owner) return { ok: false, status: 409, error: "no orchestrator owns this workspace path; use DELETE /api/workspaces/:id to purge the record" };
+  const command = createCommand({
+    type: "workspace.cleanup",
+    source: "system",
+    target: owner.agentId,
+    correlationId: workspace.id,
+    params: {
+      action: "cleanup",
+      workspaceId: workspace.id,
+      repoRoot: workspace.repoRoot,
+      worktreePath: workspace.worktreePath,
+      branch: workspace.branch,
+      requestedBy,
+      requestedAt: Date.now(),
+      deleteBranch: true,
+      queued: owner.status !== "online",
+    },
+  });
+  return { ok: true, command };
+}
+
+// Build a `workspace.deps-refresh` command for a worktree's owning orchestrator
+// (issue #51). checkOnly just reports staleness. Same owner-resolution as cleanup.
+export function buildWorkspaceDepsRefreshCommand(
+  workspace: WorkspaceRecord,
+  requestedBy: string,
+  checkOnly: boolean,
+): { ok: true; command: Command } | { ok: false; status: number; error: string } {
+  const owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
+  const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
+  if (!owner) return { ok: false, status: 409, error: "no online orchestrator owns this workspace path" };
+  const command = createCommand({
+    type: "workspace.deps-refresh",
+    source: "system",
+    target: owner.agentId,
+    correlationId: workspace.id,
+    params: {
+      action: "deps-refresh",
+      workspaceId: workspace.id,
+      repoRoot: workspace.repoRoot,
+      worktreePath: workspace.worktreePath,
+      checkOnly,
+      requestedBy,
+      requestedAt: Date.now(),
+      queued: owner.status !== "online",
+    },
+  });
+  return { ok: true, command };
+}
+
+export const DEFAULT_WORKSPACE_WAIT_MS = 300_000;
+export const MAX_WORKSPACE_WAIT_MS = 600_000;
+
+export interface WaitForWorkspaceResult {
+  workspace: WorkspaceRecord | null;
+  /** The status when the wait began. */
+  fromStatus?: WorkspaceStatus;
+  /** True when the status changed before the deadline (the actionable signal). */
+  transitioned: boolean;
+  /** True when the deadline was reached without a transition. */
+  timedOut: boolean;
+}
+
+// Long-poll a workspace until its status changes (the actionable signal after a
+// `ready`: the auto-merge job either lands it → `merged`/recycled-to-`active`, or
+// stalls into `conflict`/`review_requested`), or until the deadline. A plain
+// handler-side poll loop — no workspace event bus exists, and this stays correct
+// and cheap. `sleep` is injectable so tests don't wait real time.
+export async function waitForWorkspaceStatus(
+  id: string,
+  opts: { timeoutMs?: number; pollMs?: number; sleep?: (ms: number) => Promise<void> } = {},
+): Promise<WaitForWorkspaceResult> {
+  const timeoutMs = Math.min(Math.max(opts.timeoutMs ?? DEFAULT_WORKSPACE_WAIT_MS, 0), MAX_WORKSPACE_WAIT_MS);
+  const pollMs = opts.pollMs ?? 750;
+  const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+  const start = getWorkspace(id);
+  if (!start) return { workspace: null, transitioned: false, timedOut: false };
+  const fromStatus = start.status;
+  const deadline = Date.now() + timeoutMs;
+
+  let current = start;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    await sleep(Math.min(pollMs, Math.max(0, remaining)));
+    const next = getWorkspace(id);
+    if (!next) return { workspace: null, fromStatus, transitioned: false, timedOut: false };
+    current = next;
+    if (current.status !== fromStatus) {
+      return { workspace: current, fromStatus, transitioned: true, timedOut: false };
+    }
+  }
+  return { workspace: current, fromStatus, transitioned: false, timedOut: true };
+}

package/src/workspace-phase.ts

@@ -0,0 +1,181 @@
+// Directive status projection (#214 §2 / #235) — the single home for "what does
+// this workspace state mean to the branch agent, and what should it do next."
+//
+// Why its own module (no server deps): a branch agent reads raw `status` enums
+// and can't tell "working as designed" from "stuck" — `review_requested` looks
+// like an escalation, an absent steward looks like nobody's handling it, the
+// recycled `…--2` branch looks alarming. This pure projection is rendered by the
+// CLI (`agent-relay workspace status`, a remote HTTP client) AND returned by the
+// in-process MCP status tool, so the guidance can never drift between surfaces.
+// Keeping it dependency-light (types only) means the CLI can import it without
+// dragging in db/sse/merge — the server graph stays out of the client.
+//
+// The load-bearing decision: `ready` and `review_requested` collapse to the SAME
+// "handed off, healthy, wait" guidance, and `actionNeeded:false` is the explicit
+// anti-panic signal.
+
+import type { WorkspaceRecord, WorkspaceStatus } from "./types";
+
+// Statuses where the worktree's lifecycle is over — landed or torn down. Single
+// home; imported by maintenance (stale reap), routes (orphan scan), and the MCP
+// initialize primer (don't brief an agent on a dead workspace). Was duplicated.
+export const TERMINAL_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(["cleaned", "merged", "abandoned"]);
+
+export type WorkspacePhase =
+  | "working" // active — your turn: commit, then mark ready
+  | "land-pending" // ready | review_requested — handed off; auto-merge will land it
+  | "landing" // merge_planned — merge dispatched, in progress
+  | "steward" // conflict — auto-merge couldn't; a steward is reconciling (not your job)
+  | "landed" // merged — on the base; a fresh rebased branch is coming
+  | "closed"; // abandoned | cleanup_requested | cleaned — torn down
+
+export interface WorkspaceNextAction {
+  /** MCP tool to call (when the agent is on the MCP surface). */
+  tool?: string;
+  /** Equivalent CLI invocation (when the agent is on the shell surface). */
+  cli?: string;
+  /** When/why to take this step. */
+  when: string;
+}
+
+export interface WorkspacePhaseView {
+  phase: WorkspacePhase;
+  /** One-line meaning of the current state, in the agent's terms. */
+  headline: string;
+  /** What to do — or an explicit statement that nothing is required. */
+  hint: string;
+  /** The crux: false means "do not intervene, wait" — the anti-panic flag. */
+  actionNeeded: boolean;
+  nextActions: WorkspaceNextAction[];
+  /** Real blockers the agent should know about (rare — most "stuck"-looking states aren't). */
+  blockers: string[];
+}
+
+const WAIT_ACTION: WorkspaceNextAction = {
+  tool: "relay_workspace_status (wait:true)",
+  cli: "agent-relay workspace status --wait",
+  when: "to block until your branch lands (returns when the status changes)",
+};
+
+const READY_ACTION: WorkspaceNextAction = {
+  tool: "relay_workspace_ready",
+  cli: "agent-relay workspace ready",
+  when: "after you commit your work in this worktree",
+};
+
+// Map every WorkspaceStatus to the branch agent's mental model. Statuses that
+// look scary but are healthy (review_requested, conflict) carry actionNeeded:false
+// and an explicit "not your job" hint.
+export function describeWorkspacePhase(workspace: Pick<WorkspaceRecord, "status" | "branch" | "stewardAgentId">): WorkspacePhaseView {
+  switch (workspace.status) {
+    case "active":
+      return {
+        phase: "working",
+        headline: "Your isolated branch — work in progress.",
+        hint: "Commit your work in this worktree, then mark it ready. Relay rebases onto the latest base, lands, and pushes for you — do NOT push, rebase, or merge yourself, and never touch the main checkout.",
+        actionNeeded: true,
+        nextActions: [READY_ACTION],
+        blockers: [],
+      };
+    case "ready":
+    case "review_requested":
+      // The #235 crux: these are the SAME healthy "handed off, waiting" state.
+      // `review_requested` reads like an escalation but is the normal post-ready
+      // node; an absent steward is the healthy case, not a stall.
+      return {
+        phase: "land-pending",
+        headline: "Handed off — waiting for the auto-merge to land your branch. This is the normal, healthy post-ready state (not an escalation).",
+        hint: "No action needed. Relay auto-merges clean rebases roughly every 2 minutes; a steward agent is spawned only if it can't land deterministically — so no steward visible means it's healthy, not stuck. Wait. Do NOT merge, push, resolve anything, or touch the main checkout.",
+        actionNeeded: false,
+        nextActions: [WAIT_ACTION],
+        blockers: [],
+      };
+    case "merge_planned":
+      return {
+        phase: "landing",
+        headline: "Merge dispatched — landing your branch on the base now.",
+        hint: "No action needed. When it completes you'll be moved onto a fresh rebased branch (the name gains a `--N` suffix — expected) to keep working.",
+        actionNeeded: false,
+        nextActions: [WAIT_ACTION],
+        blockers: [],
+      };
+    case "conflict":
+      return {
+        phase: "steward",
+        headline: "Auto-merge hit a conflict — a steward agent is reconciling it. Resolving it is NOT your job.",
+        hint: "Do not resolve the conflict, rebase, merge, or push yourself. The steward rebases and lands it, escalating to the human only if it truly can't. You can keep working or wait for it to land.",
+        actionNeeded: false,
+        nextActions: [WAIT_ACTION],
+        blockers: ["rebase/merge conflict against the base — a steward is handling it"],
+      };
+    case "merged":
+      return {
+        phase: "landed",
+        headline: "✅ Landed — your commits are on the base.",
+        hint: "A fresh rebased branch is being prepared; you'll continue on it (the branch name gains a `--N` suffix — expected, not an error). Keep working.",
+        actionNeeded: false,
+        nextActions: [],
+        blockers: [],
+      };
+    case "abandoned":
+    case "cleanup_requested":
+    case "cleaned":
+      return {
+        phase: "closed",
+        headline: "This workspace is being torn down.",
+        hint: "No further branch work happens here. If you still have work to do, the host will spawn you into a fresh workspace.",
+        actionNeeded: false,
+        nextActions: [],
+        blockers: [],
+      };
+  }
+}
+
+// Plain-language contract printed/returned right when an agent marks a workspace
+// ready, so the whole "what happens next" is stated up front instead of being
+// decoded from status enums over the following minutes (#235).
+export function readyContract(workspace: Pick<WorkspaceRecord, "status">): string {
+  return [
+    `Marked ready. Status is now \`${workspace.status}\` — this is the normal, healthy hand-off state, not an escalation.`,
+    "Relay auto-merges clean rebases roughly every 2 minutes. A steward agent is spawned (after a short delay) ONLY if it can't land deterministically — so no steward appearing means it's working, not stuck.",
+    "Wait with `relay_workspace_status wait:true` (or `agent-relay workspace status --wait`) — it returns the moment your branch lands.",
+    "On landing you'll be moved onto a fresh rebased branch (its name gains a `--N` suffix — expected). Keep working there.",
+    "Do NOT merge, push, rebase, resolve conflicts, or `cd` into the main checkout — Relay (and the steward) own all of that.",
+  ].join("\n");
+}
+
+// Mode-tailored MCP `initialize` instructions primer (#214 §3). The relay's MCP
+// endpoint returns this in the `instructions` field ONLY for callers that own an
+// isolated worktree, so worktree agents get a concise one-time map of the
+// merge-back flow even if they connected without the runner's spawn briefing —
+// and shared-workspace agents never see the noise. Kept short and in the same
+// home as the projection so the wording can't drift from `status`/`ready`.
+export function worktreeMcpInstructions(workspace: Pick<WorkspaceRecord, "branch" | "baseRef">): string {
+  const branch = workspace.branch ? `\`${workspace.branch}\`` : "an isolated agent branch";
+  const base = workspace.baseRef ? `\`${workspace.baseRef}\`` : "the base branch";
+  return [
+    `You are in an isolated git worktree on branch ${branch}, based on ${base} — NOT the main checkout. ${base} moves under you as other agents land in parallel; that's expected.`,
+    "Changes reach the base via: commit your work, then call `relay_workspace_ready`. Relay rebases onto the latest base, lands, and pushes for you.",
+    "Do NOT push, rebase, merge, resolve conflicts, or `cd` into the main checkout — Relay (and a steward, spawned only if a clean auto-merge isn't possible) own all of that.",
+    "After `ready` the status is `review_requested` — that is the NORMAL, healthy hand-off state, not a stall. Call `relay_workspace_status` with `wait:true` to block until your branch lands; you'll then continue on a fresh rebased branch (name gains a `--N` suffix).",
+    "Call `relay_workspace_status` anytime to see where you are and the exact next step.",
+  ].join("\n");
+}
+
+// Positive land receipt for the wait-result path: when a long-poll observes the
+// status leave a pending/landing state into landed/recycled, tell the agent its
+// work is on the base and which branch to keep working on. Returns null when the
+// transition isn't a land (so callers can omit the field).
+export function landReceipt(
+  fromStatus: WorkspaceStatus | undefined,
+  workspace: Pick<WorkspaceRecord, "status" | "branch">,
+): string | null {
+  const wasPending = fromStatus === "ready" || fromStatus === "review_requested" || fromStatus === "merge_planned" || fromStatus === "conflict";
+  if (!wasPending) return null;
+  // merged, or recycled straight back to active on a fresh branch.
+  if (workspace.status === "merged" || workspace.status === "active") {
+    const branch = workspace.branch ? `\`${workspace.branch}\`` : "a fresh rebased branch";
+    return `✅ Landed — your commits are on the base. You're now on ${branch}; keep working there.`;
+  }
+  return null;
+}