import type { WorkspaceMetadata, WorkspaceMode } from "agent-relay-sdk";
import type { WorkspaceLandGateLevel, WorkspaceLandMechanism, WorkspaceMergeResult } from "agent-relay-sdk";

/** Attach to or branch off an existing managed worktree instead of creating a fresh one (#635). */
export interface ResumeWorkspaceTarget {
  branch: string;
  /** `attach` = reuse the existing worktree as-is (crash recovery). `branch-from` = new worktree off the existing branch HEAD. */
  mode: "attach" | "branch-from";
  /** Resolved worktree path from the relay DB. For `attach`: must exist on disk. For `branch-from`: unused (HEAD resolved from branch). */
  worktreePath?: string;
  /** Existing workspace DB id. For `attach`: passed back so the relay reuses the same record (avoids duplicates). */
  workspaceId?: string;
  /** Preserved baseRef from the original workspace. For `attach` only. */
  baseRef?: string;
  /** Preserved baseSha from the original workspace. For `attach` only. */
  baseSha?: string;
}

export interface WorkspaceResolutionInput {
  cwd: string;
  label?: string;
  policyName?: string;
  spawnRequestId?: string;
  workspaceMode?: WorkspaceMode;
  workspaceRoot?: string;
  workspaceSymlinks?: string[];
  /** Preferred base for a fresh isolated worktree, e.g. fetched origin/main after project acquisition. */
  baseRef?: string;
  baseSha?: string;
  automationId?: string;
  automationRunId?: string;
  /** #635 — attach to or branch off an existing worktree instead of creating a fresh one. */
  resumeWorkspace?: ResumeWorkspaceTarget;
}

export interface WorkspaceResolution {
  cwd: string;
  workspace: WorkspaceMetadata;
  reusedExisting?: boolean;
}

export interface WorkspaceMergeInput {
  id?: string;
  repoRoot?: string;
  worktreePath?: string;
  branch?: string;
  /** Immutable worker tip captured by the relay's merge preview at dispatch. The host
   * refuses if the worktree has moved before it claims the command (#1690). */
  expectedHeadSha?: string;
  baseRef?: string;
  baseSha?: string;
  strategy?: "pr" | "rebase-ff" | "auto";
  /** Direct-land executor selected by Relay. PR/auto remain managed. */
  landMechanism?: WorkspaceLandMechanism;
  deleteBranch?: boolean;
  /** Push the advanced base to its upstream (origin) after a rebase-ff land.
   * Defaults to true; auto-skipped when base has no upstream. Disable with
   * AGENT_RELAY_WORKSPACE_PUSH=0. */
  push?: boolean;
  prTitle?: string;
  prBody?: string;
  /** Auto-merge policy for pr-strategy lands (#305).
   *  - "on-green": arm GitHub auto-merge after PR creation (default).
   *  - "on-approval": open PR, do NOT arm; reviewer pipeline arms it later.
   *  - "manual": open PR, do NOT arm (today's legacy behavior). */
  autoMerge?: "on-green" | "on-approval" | "manual";
  /** Land-gate level. Omitted/"full" runs the base-declared required gates. */
  gateLevel?: WorkspaceLandGateLevel;
  /** Required by Relay before subset/none reaches the host; carried for audit output. */
  gateReason?: string;
  gateRequestedBy?: string;
  /**
   * Set when the relay observed this branch's PR already merged on the remote and is
   * dispatching a land-and-continue RECYCLE (#423). Carries the relay's ground truth (the
   * merge SHA/subject). Its presence forces the live-owner recycle even when local git can't
   * see the landing — a squash onto an advanced base re-creates the work as a new commit
   * (patch ids drift, trees diverge) so `previewWorkspaceMerge` reports ahead>0 and would
   * otherwise loop via review_requested. prMerged is monotonic and was read from THIS host's
   * own `checkPr` scan, so trusting it is safe; we still refuse on a dirty tree. */
  prLanded?: { sha?: string; subject?: string };
  signal?: AbortSignal;
}