agent-relay-server 0.32.2 → 0.32.3

package/src/routes/workspaces.ts

@@ -0,0 +1,355 @@
+// Auto-split from routes.ts (#299). Domain: workspaces.
+import { RELAY_TOKEN_HEADER, isRecord } from "agent-relay-sdk";
+import { TERMINAL_WORKSPACE_STATUSES, describeWorkspacePhase, landReceipt } from "../workspace-phase";
+import { VALID_WORKSPACE_STATUSES, cleanMeta, cleanString, optionalEnum } from "../validation";
+import { ValidationError, deleteWorkspace, getAgent, getWorkspace, listMergeLeases, listOrchestrators, listRepoStewards, listWorkspaces, updateWorkspaceStatus } from "../db";
+import { WORKSPACE_ACTIONS, applyWorkspaceAction, buildWorkspaceCleanupCommand, waitForWorkspaceStatus } from "../workspace-actions";
+import { auditEvent, authAuditMetadata, authorizeRoute, emitCommand, error, json, parseBody, type Handler } from "./_shared";
+import { collectWorkspaceOrphans } from "../workspace-orphans";
+import { createCommand } from "../commands-db";
+import { isOwnerAlive, withOwnerOnline } from "../workspace-merge";
+import { isPathWithinBase } from "../utils";
+import { resolve } from "node:path";
+import { type WorkspaceDiagnostics, type WorkspaceGitState, type WorkspaceMergeStrategy, type WorkspaceRecord, type WorkspaceStatus } from "../types";
+import { workspaceActiveClaim } from "../workspace-claim";
+
+export const getWorkspaces: Handler = (req) => {
+  try {
+    const url = new URL(req.url);
+    const repoRoot = cleanString(url.searchParams.get("repoRoot") ?? undefined, "repoRoot", { max: 1000 });
+    const ownerAgentId = cleanString(url.searchParams.get("agentId") ?? undefined, "agentId", { max: 240 });
+    const status = optionalEnum(url.searchParams.get("status") ?? undefined, "status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
+    return json(listWorkspaces({ repoRoot, ownerAgentId, status }).map(withOwnerOnline));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const getWorkspaceById: Handler = (_req, params) => {
+  const workspace = getWorkspace(params.id!);
+  if (!workspace) return error("workspace not found", 404);
+  return json(withOwnerOnline(workspace));
+};
+
+export const getWorkspaceStewards: Handler = () => json({ stewards: listRepoStewards(), mergeLeases: listMergeLeases() });
+
+async function proxyWorkspaceHostGet(workspaceId: string, hostPath: string, extraQuery?: Record<string, string>): Promise<Response> {
+  const workspace = getWorkspace(workspaceId);
+  if (!workspace) return error("workspace not found", 404);
+  if (workspace.mode !== "isolated" || !workspace.worktreePath) {
+    return json({ available: false, reason: "no isolated worktree" });
+  }
+  const orch = listOrchestrators().find(
+    (candidate) => candidate.status === "online" && candidate.apiUrl && isPathWithinBase(workspace.sourceCwd, candidate.baseDir),
+  );
+  if (!orch?.apiUrl) return json({ available: false, reason: "owning orchestrator offline" });
+  const query = new URLSearchParams({ path: workspace.worktreePath });
+  if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
+  if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
+  for (const [key, value] of Object.entries(extraQuery ?? {})) query.set(key, value);
+  const headers: Record<string, string> = {};
+  const relayToken = process.env.AGENT_RELAY_TOKEN;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
+  try {
+    const res = await fetch(`${orch.apiUrl}${hostPath}?${query.toString()}`, {
+      headers,
+      signal: AbortSignal.timeout(10_000),
+    });
+    const body = await res.text();
+    return new Response(body, { status: res.status, headers: { "Content-Type": res.headers.get("content-type") || "application/json" } });
+  } catch (e) {
+    return json({ available: false, reason: `orchestrator unreachable: ${(e as Error).message}` });
+  }
+}
+
+export const getWorkspaceGitState: Handler = (_req, params) => proxyWorkspaceHostGet(params.id!, "/api/workspace/state");
+
+export const getWorkspaceMergePreview: Handler = (req, params) => {
+  const strategy = new URL(req.url).searchParams.get("strategy");
+  return proxyWorkspaceHostGet(params.id!, "/api/workspace/merge-preview", strategy ? { strategy } : undefined);
+};
+
+export const getWorkspaceDiff: Handler = (req, params) => {
+  const patch = new URL(req.url).searchParams.get("patch");
+  return proxyWorkspaceHostGet(params.id!, "/api/workspace/diff", patch === "0" ? { patch: "0" } : undefined);
+};
+
+export const getWorkspaceOrphans: Handler = async () => {
+  const { orphans, missingWorktrees, reason } = await collectWorkspaceOrphans();
+  return json(reason ? { orphans, missingWorktrees, reason } : { orphans, missingWorktrees });
+};
+
+export const postWorkspaceOrphanReclaim: Handler = async (req) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const worktreePath = cleanString(parsed.body.worktreePath, "worktreePath", { max: 1000 });
+    const repoRoot = cleanString(parsed.body.repoRoot, "repoRoot", { max: 1000 });
+    const branch = cleanString(parsed.body.branch, "branch", { max: 240 });
+    if (!worktreePath || !repoRoot) return error("worktreePath and repoRoot required", 400);
+    const force = parsed.body.force === true;
+    // Refuse to reclaim a path that still backs a live workspace row.
+    const live = listWorkspaces().find((ws) => ws.worktreePath && resolve(ws.worktreePath) === resolve(worktreePath) && !TERMINAL_WORKSPACE_STATUSES.has(ws.status));
+    if (live) return error(`path backs live workspace ${live.id}; clean it through the workspace, not orphan reclaim`, 409);
+    const orch = listOrchestrators().find((candidate) => candidate.status === "online" && isPathWithinBase(repoRoot, candidate.baseDir));
+    if (!orch) return error("no online orchestrator owns this path", 409);
+    // Land-safety gate (#244): reclaim force-removes the worktree, so refuse when
+    // it holds un-landed work unless the caller explicitly opts into discarding
+    // it. Mirrors the scheduled reaper — never destroy work on uncertainty.
+    if (!force) {
+      const { orphans } = await collectWorkspaceOrphans();
+      const target = orphans.find((o) => resolve(o.worktreePath) === resolve(worktreePath));
+      if (target && target.safeToReap !== true) {
+        const why = target.safeToReap === undefined
+          ? "land-state could not be determined"
+          : target.dirty ? "uncommitted changes" : `${target.unmergedAhead ?? target.ahead ?? "?"} un-landed commit(s)`;
+        return error(`worktree holds un-landed work (${why}); recover it first, or pass {"force":true} to discard`, 409);
+      }
+    }
+    const command = createCommand({
+      type: "workspace.cleanup",
+      source: "system",
+      target: orch.agentId,
+      params: { action: "cleanup", worktreePath, repoRoot, branch, deleteBranch: true, reclaim: true, requestedBy: "dashboard", requestedAt: Date.now() },
+    });
+    emitCommand(command);
+    auditEvent({
+      clientId: `workspace-orphan-reclaim-${Date.now()}`,
+      kind: "state",
+      title: "Workspace orphan reclaim",
+      body: worktreePath,
+      meta: branch ?? repoRoot,
+      icon: "ti-trash",
+      view: "orchestrators",
+      metadata: { worktreePath, repoRoot, branch, commandId: command.id, ...authAuditMetadata(req) },
+    });
+    return json({ command }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+async function fetchWorkspaceGitState(workspace: WorkspaceRecord): Promise<{ state: WorkspaceGitState } | { unavailable: string }> {
+  if (workspace.mode !== "isolated" || !workspace.worktreePath) return { unavailable: "no isolated worktree" };
+  const orch = listOrchestrators().find(
+    (candidate) => candidate.status === "online" && candidate.apiUrl && isPathWithinBase(workspace.sourceCwd, candidate.baseDir),
+  );
+  if (!orch?.apiUrl) return { unavailable: "owning orchestrator offline" };
+  const query = new URLSearchParams({ path: workspace.worktreePath });
+  if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
+  if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
+  const headers: Record<string, string> = {};
+  const relayToken = process.env.AGENT_RELAY_TOKEN;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
+  try {
+    const res = await fetch(`${orch.apiUrl}/api/workspace/state?${query.toString()}`, { headers, signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) return { unavailable: `host returned ${res.status}` };
+    return { state: await res.json() as WorkspaceGitState };
+  } catch (e) {
+    return { unavailable: `orchestrator unreachable: ${(e as Error).message}` };
+  }
+}
+
+function recommendWorkspaceAction(input: { workspace: WorkspaceRecord; ownerOnline: boolean; gitState?: WorkspaceGitState; claim: ReturnType<typeof workspaceActiveClaim> }): WorkspaceDiagnostics["recommendation"] {
+  const { workspace, ownerOnline, gitState, claim } = input;
+  if (claim) return { action: "wait", confidence: "high", reason: `claimed by ${claim.by ?? "steward"}` };
+  if (TERMINAL_WORKSPACE_STATUSES.has(workspace.status)) return { action: "none", confidence: "high", reason: `workspace is ${workspace.status}` };
+  if (!gitState || gitState.error) return { action: "review", confidence: "low", reason: gitState?.error ? `git state error: ${gitState.error}` : "git state unavailable" };
+  if (gitState.missing) return { action: "cleanup", confidence: "high", reason: "worktree no longer exists on disk" };
+  const ahead = gitState.unmergedAhead ?? gitState.ahead ?? 0;
+  const landed = gitState.landed === true;
+  if ((gitState.dirtyCount ?? 0) > 0) return { action: "review", confidence: "medium", reason: `${gitState.dirtyCount} uncommitted change(s)` };
+  if (ahead === 0 || landed) {
+    if (!ownerOnline) return { action: "cleanup", confidence: "high", reason: landed ? "work already landed; owner offline" : "no unmerged commits; owner offline" };
+    // Owner active but the workspace is awaiting attention with nothing to land (#230):
+    // landing it is a safe no-op that resolves it to terminal `merged`, clearing the
+    // queue (the host keeps a live owner's worktree). Otherwise there's genuinely
+    // nothing to do.
+    if (workspace.status === "review_requested" || workspace.status === "conflict") {
+      return { action: "merge", confidence: "high", reason: landed ? "work already landed; resolve the no-op" : "nothing to merge; resolve the no-op" };
+    }
+    return { action: "none", confidence: "medium", reason: "nothing to merge; owner active" };
+  }
+  if (ownerOnline && workspace.status !== "review_requested" && workspace.status !== "conflict") {
+    return { action: "wait", confidence: "medium", reason: "owner active and not awaiting review" };
+  }
+  if (workspace.status === "conflict") return { action: "rebase", confidence: "high", reason: "conflict — rebase onto base and resolve" };
+  if ((gitState.behind ?? 0) > 0) return { action: "rebase", confidence: "medium", reason: `${gitState.behind} behind base — rebase then merge` };
+  return { action: "merge", confidence: "high", reason: `${ahead} commit(s) ready to land` };
+}
+
+export const getWorkspaceDiagnostics: Handler = async (_req, params) => {
+  const workspace = getWorkspace(params.id!);
+  if (!workspace) return error("workspace not found", 404);
+  const owner = workspace.ownerAgentId ? getAgent(workspace.ownerAgentId) : null;
+  const ownerOnline = isOwnerAlive(workspace.ownerAgentId);
+  const orch = listOrchestrators().find((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
+  const orchOnline = Boolean(orch) && orch!.status === "online";
+  const fetched = await fetchWorkspaceGitState(workspace);
+  const gitState = "state" in fetched ? fetched.state : undefined;
+  const claim = workspaceActiveClaim(workspace);
+  const liveBranch = gitState?.branch;
+  const diagnostics: WorkspaceDiagnostics = {
+    workspaceId: workspace.id,
+    status: workspace.status,
+    mode: workspace.mode,
+    repoRoot: workspace.repoRoot,
+    worktreePath: workspace.worktreePath,
+    recordedBranch: workspace.branch,
+    liveBranch,
+    baseRef: workspace.baseRef,
+    branchMismatch: workspace.branch && liveBranch ? workspace.branch !== liveBranch : undefined,
+    owner: { id: workspace.ownerAgentId, status: owner?.status, online: ownerOnline },
+    orchestrator: { id: orch?.id, online: orchOnline },
+    ...(claim ? { claim: { by: claim.by, purpose: claim.purpose, expiresAt: claim.expiresAt } } : {}),
+    ...(gitState ? { gitState } : { gitStateUnavailable: "unavailable" in fetched ? fetched.unavailable : "unknown" }),
+    recommendation: recommendWorkspaceAction({ workspace, ownerOnline, gitState, claim }),
+  };
+  return json(diagnostics);
+};
+
+export const postWorkspaceCleanupStale: Handler = async (req) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = isRecord(parsed.body) ? parsed.body : {};
+  const repoRoot = cleanString(body.repoRoot, "repoRoot", { max: 1000 });
+  const dryRun = body.dryRun !== false; // safe by default
+  const landedOnly = body.landedOnly !== false;
+  const offlineOwnerOnly = body.offlineOwnerOnly !== false;
+
+  const candidates = listWorkspaces().filter((ws) =>
+    ws.mode === "isolated" && Boolean(ws.worktreePath) && !TERMINAL_WORKSPACE_STATUSES.has(ws.status) && (!repoRoot || ws.repoRoot === repoRoot),
+  );
+
+  const rows: Array<Record<string, unknown>> = [];
+  const cleaned: string[] = [];
+  for (const ws of candidates) {
+    const owner = ws.ownerAgentId ? getAgent(ws.ownerAgentId) : null;
+    const ownerOnline = isOwnerAlive(ws.ownerAgentId);
+    if (ownerOnline) continue;                         // never clean a live owner's worktree
+    if (offlineOwnerOnly && !ws.ownerAgentId) { /* no owner recorded — still eligible */ }
+    if (workspaceActiveClaim(ws)) continue;            // respect steward claims
+    const fetched = await fetchWorkspaceGitState(ws);
+    const gitState = "state" in fetched ? fetched.state : undefined;
+    const missing = gitState?.missing === true;
+    const dirtyCount = gitState?.dirtyCount;
+    const ahead = gitState?.unmergedAhead ?? gitState?.ahead ?? 0;
+    const landed = gitState?.landed === true;
+    // Safe = gone from disk, OR clean tree with no unmerged work (landed/empty).
+    const safe = missing || (gitState !== undefined && (dirtyCount ?? 1) === 0 && (!landedOnly || landed || ahead === 0));
+    const proof = { ownerStatus: owner?.status ?? "missing", ownerOnline, ahead, behind: gitState?.behind, landed, dirtyCount, missing, gitStateUnavailable: gitState ? undefined : ("unavailable" in fetched ? fetched.unavailable : undefined) };
+    const row: Record<string, unknown> = { workspaceId: ws.id, branch: ws.branch, worktreePath: ws.worktreePath, repoRoot: ws.repoRoot, safe, proof };
+    if (safe && !dryRun) {
+      const built = buildWorkspaceCleanupCommand(ws, "cleanup-stale");
+      if (built.ok) {
+        updateWorkspaceStatus(ws.id, "cleanup_requested", { lastWorkspaceAction: "cleanup-stale", lastWorkspaceActionAt: Date.now(), cleanupProof: proof });
+        emitCommand(built.command);
+        row.commandId = built.command.id;
+        cleaned.push(ws.id);
+      } else {
+        row.cleanupError = built.error;
+      }
+    }
+    rows.push(row);
+  }
+  return json({ dryRun, landedOnly, offlineOwnerOnly, repoRoot, scanned: candidates.length, eligible: rows.filter((r) => r.safe).length, cleaned, candidates: rows }, dryRun ? 200 : 202);
+};
+
+export const postWorkspaceAction: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const workspace = getWorkspace(params.id!);
+    if (!workspace) return error("workspace not found", 404);
+    const action = optionalEnum(parsed.body.action, "action", WORKSPACE_ACTIONS);
+    if (!action) return error("action required", 400);
+    const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
+    const requiresCommand = action === "cleanup" || action === "merge";
+    // Shared-mode rows are occupancy markers with no worktree — reject host commands
+    // up front, before authz, preserving the original 422-before-auth ordering.
+    if (requiresCommand && (workspace.mode !== "isolated" || !workspace.worktreePath)) {
+      return error(`workspace ${workspace.id} has no worktree to ${action}`, 422);
+    }
+    const denied = authorizeRoute(req, { scope: requiresCommand ? "command:write" : "agent:write", resource: { agentId, cwd: workspace.worktreePath } });
+    if (denied) return denied;
+
+    // status: optionally long-poll until the workspace transitions — after a `ready`,
+    // block until the auto-merge job lands it (→ merged/recycled-to-active) or it
+    // stalls into conflict/review_requested, instead of the caller busy-polling.
+    if (action === "status") {
+      if (parsed.body.wait === true) {
+        const timeoutSeconds = typeof parsed.body.timeoutSeconds === "number" && parsed.body.timeoutSeconds > 0 ? parsed.body.timeoutSeconds : undefined;
+        const waited = await waitForWorkspaceStatus(workspace.id, timeoutSeconds ? { timeoutMs: timeoutSeconds * 1000 } : {});
+        if (!waited.workspace) return error("workspace not found", 404);
+        const landed = waited.transitioned ? landReceipt(waited.fromStatus, waited.workspace) : null;
+        // Mirror the relay_workspace_status MCP tool: bare record (legacy fields)
+        // plus the directive projection + land receipt so the CLI `--wait` and any
+        // HTTP caller get the same legible answer.
+        return json({
+          workspace: withOwnerOnline(waited.workspace),
+          guidance: describeWorkspacePhase(waited.workspace),
+          ...(landed ? { landed } : {}),
+          fromStatus: waited.fromStatus,
+          transitioned: waited.transitioned,
+          timedOut: waited.timedOut,
+        });
+      }
+      return json(withOwnerOnline(workspace));
+    }
+
+    // Everything else delegates to the shared core (one home, shared with the
+    // relay_workspace_* MCP tools); the core self-audits and returns any command to
+    // emit, mirroring requestWorkspaceMerge's "caller emits" contract.
+    const result = applyWorkspaceAction(workspace, {
+      action,
+      agentId,
+      detail: cleanString(parsed.body.detail, "detail", { max: 4000 }),
+      metadata: cleanMeta(parsed.body.metadata) ?? {},
+      strategy: optionalEnum(parsed.body.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const, "auto") as WorkspaceMergeStrategy,
+      deleteBranch: typeof parsed.body.deleteBranch === "boolean" ? parsed.body.deleteBranch : undefined,
+      force: parsed.body.force === true,
+      prTitle: cleanString(parsed.body.prTitle, "prTitle", { max: 240 }),
+      prBody: cleanString(parsed.body.prBody, "prBody", { max: 8000 }),
+      purpose: cleanString(parsed.body.purpose, "purpose", { max: 120 }),
+      checkOnly: parsed.body.checkOnly === true,
+      auditMetadata: authAuditMetadata(req),
+    });
+    if (!result.ok) return error(result.error, result.httpStatus);
+    if (result.command) emitCommand(result.command);
+    const payload: Record<string, unknown> = { workspace: withOwnerOnline(result.workspace) };
+    if (result.command) payload.command = result.command;
+    if (result.claim !== undefined) payload.claim = result.claim;
+    return json(payload, result.httpStatus);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const deleteWorkspaceById: Handler = (req, params) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const workspace = getWorkspace(params.id!);
+  if (!workspace) return error("workspace not found", 404);
+  const removed = deleteWorkspace(workspace.id);
+  if (!removed) return error("workspace not found", 404);
+  auditEvent({
+    clientId: `workspace-delete-${workspace.id}-${Date.now()}`,
+    kind: "state",
+    title: "Workspace record purged",
+    body: workspace.worktreePath,
+    meta: workspace.branch ?? workspace.id,
+    icon: "ti-trash",
+    view: "orchestrators",
+    metadata: { workspaceId: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath, status: workspace.status, diskUntouched: true, ...authAuditMetadata(req) },
+  });
+  return json({ deleted: true, workspace });
+};