agent-relay-server 0.21.0 → 0.22.0

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;
+}