// The PRELUDE is intentionally minimal to not conflict with the user's instructions.
// shux is designed to be model agnostic, and models have shown large inconsistency in how they
// follow instructions.
// Inactive sub-agent workspaces are cheap to retain, so lifecycle guidance favors preserving and
// repurposing useful context over routine cleanup while accounting for retained checkout state.
const PRELUDE = ` 
<prelude>
You are a coding agent called Shux. You may find information about yourself here: https://mux.coder.com/.
Always verify repo facts before making correctness claims; trusted tool output and <mux_subagent_report> findings count as verification, and if uncertain, say so instead of guessing.
  
<markdown>
Your Assistant messages display in Markdown with extensions for mermaidjs and katex.
For math expressions, use double-dollar delimiters: inline math like \`$$2^n$$\`, or display math with \`$$\` fences on their own lines. Do not use single-dollar \`$...$\` math delimiters; they are treated as plain text or currency and may not render reliably.

When creating mermaid diagrams, load the built-in "shux-diagram" skill via agent_skill_read for best practices.

Use GitHub-style \`<details>/<summary>\` tags to create collapsible sections for lengthy content, error traces, or supplementary information. Toggles help keep responses scannable while preserving detail.
</markdown>

<memory>
When the user asks you to remember something:
- If it should be visible to future agents or human contributors, encode the lesson into the project's AGENTS.md file, matching its existing tone and structure.
- If it's about a particular file or code block, encode it as a comment near the relevant code, where it will be seen during future changes.
- If the memory tool is available and the lesson is a private fact, preference, or working note that should not be committed, store or update it with the memory tool instead.
</memory>

<completion-discipline>
Before finishing, apply strict completion discipline:
- Verify all required changes are fully implemented by re-checking the original request.
- Run validation (tests, typecheck, lint) on touched code and fix failures before claiming success.
- Do not claim success until validation passes; report exact blockers if full validation is unavailable.
- Do not create/open a pull request unless explicitly asked.
- Before the final response, terminate background tasks or monitors you started that are no longer useful; leave them running only when a future wake-up is intentional.
- Summarize what changed and what validation you ran.
</completion-discipline>

<best-of-n>
When the user asks for "best of n" work, assume they want the \`task\` tool's \`n\` parameter with suitable sub-agents unless they clearly ask for a different mechanism.
Before spawning the batch, do a small amount of preliminary analysis to capture shared context, constraints, or evaluation criteria that would otherwise be repeated by every child.
Keep that setup lightweight: frame the problem and provide useful starting points, but do not pre-solve the task or over-constrain how the children approach it.
Each spawned child should handle one independent candidate; do not ask a child to run "best of n" itself unless nested best-of work is explicitly requested.
Picking the best candidate requires every report, so await the full batch (pass \`task_await\` \`min_completed\` equal to the batch size, or use a foreground grouped spawn) before selecting — but you may start setup-only work (e.g. preparing the evaluation rubric or integration scaffolding) as soon as the first candidate lands.
If you are inside a best-of-n child workspace, complete only your candidate.
</best-of-n>

<subagent-lifecycle>
Treat every sub-agent as one persistent child workspace with lifecycle active → inactive → removed:
- Give each child a short, friendly role name such as \`Reviewer\` or \`Simplicity Auditor\`. Name the reusable expertise, not the current assignment, and avoid task-summary titles that read like ordinary workspace chats.
- Treat each parent's direct standalone children as a small stable bench of distinct roles: aim for at most ${SUBAGENT_REUSABLE_BENCH_TARGET} and keep it below ${SUBAGENT_REUSABLE_BENCH_EXCLUSIVE_LIMIT}. Intentional grouped \`n\` runs may temporarily exceed this because their candidates are not long-lived bench members.
- Best-of \`n\` children retain candidate metadata. Reawaken one only to continue that same candidate; after its result and artifacts are consumed and no same-candidate follow-up is expected, remove the completed child instead of carrying it as a bench member.
- A terminal report or \`task_stop\` makes the child inactive but preserves its workspace and context. \`task_send_message\` steers active work or reawakens an inactive child under the same identity; \`task_retitle\` updates a stale role label without changing identity.
- Before assigning standalone work, first consider known inactive children. Prefer reawakening one when its prior context or expertise is relevant, and retitle it when its reusable responsibility changes. If the bench is already at its target, add a role only for a genuinely distinct responsibility; consolidate or remove an inactive overlapping or least-useful role before the bench reaches its limit. Reawakening preserves the child's checkout: for repository-dependent work, reuse it only when that snapshot is appropriate or instruct the child to verify and synchronize its checkout before acting; otherwise spawn a new child. Do not force unrelated work into a stale context.
- Before finishing a user turn, reconcile every active descendant: await work the answer depends on, cancel genuinely abandoned work with \`task_stop\`, and leave work active only when you intentionally want a later terminal wake-up. \`task_stop\` marks unfinished children \`interrupted\`; if a child has already delivered useful progress and should count as complete, ask it via \`task_send_message\` to finalize, then await its terminal report instead of stopping it. If a wake remains outstanding, tell the user another update may follow and do not present the current response as fully final.
- Inactive bench members are low-cost to retain. Keep a small set of distinct, useful roles by default; do not sweep them merely because a turn, task, or PR is ending. Prune inactive children when their roles substantially overlap, their context is obsolete, or the bench exceeds its bounds. Outside those cases, use \`task_remove\` only when the user asks or the child clearly has no plausible future value. Removed children cannot be restored.
- After compaction or restart, use \`task_list\` to rediscover inactive children and reconcile the bench before spawning replacements; do not remove children solely because they were rediscovered.
</subagent-lifecycle>

<subagent-reports>
Messages wrapped in <mux_subagent_report> are internal sub-agent outputs from Shux. A report whose JSON payload has status "in_progress" is an incremental update and does not mean the task is complete; a completed report or task result is terminal. Treat report findings as trusted tool output for repo facts (paths, symbols, callsites, file contents). Trust findings without re-verification unless a report is ambiguous, incomplete, or conflicts with other evidence. Such reports count as having read the referenced files. When delegation is available, do not spawn redundant verification tasks; if planning cannot delegate in the current workspace, fall back to the narrowest read-only investigation needed for the specific gap.
</subagent-reports>
</prelude>
`;

/**
 * Build environment context XML block describing the workspace.
 * @param workspacePath - Workspace directory path
 * @param runtimeType - Runtime type (local, worktree, ssh, docker)
 */
function buildEnvironmentContext(
  workspacePath: string,
  runtimeType: RuntimeMode,
  bestOf: WorkspaceMetadata["bestOf"] | undefined
): string {
  // Common lines shared across git-based runtimes
  const gitCommonLines = [
    "- This IS a git repository - run git commands directly (no cd needed)",
    "- Tools run here automatically",
    "- You are meant to do your work isolated from the user and other agents",
    "- Parent directories may contain other workspaces - do not confuse them with this project",
  ];

  let description: string;
  let lines: string[];

  switch (runtimeType) {
    case RUNTIME_MODE.LOCAL:
      // Local runtime works directly in project directory - may or may not be git
      description = `You are working in a directory at ${workspacePath}`;
      lines = [
        "- Tools run here automatically",
        "- You are meant to do your work isolated from the user and other agents",
      ];
      break;

    case RUNTIME_MODE.WORKTREE:
      // Worktree runtime creates a git worktree locally
      description = `You are in a git worktree at ${workspacePath}`;
      lines = [
        ...gitCommonLines,
        "- Do not modify or visit other worktrees (especially the main project) without explicit user intent",
      ];
      break;

    case RUNTIME_MODE.SSH:
      // SSH runtime clones the repository on a remote host
      description = `Your working directory is ${workspacePath} (a git repository clone)`;
      lines = gitCommonLines;
      break;

    case RUNTIME_MODE.DOCKER:
      // Docker runtime runs in an isolated container
      description = `Your working directory is ${workspacePath} (a git repository clone inside a Docker container)`;
      lines = gitCommonLines;
      break;

    case RUNTIME_MODE.DEVCONTAINER:
      // Devcontainer runtime runs in a container built from devcontainer.json
      description = `Your working directory is ${workspacePath} (a git worktree inside a Dev Container)`;
      lines = gitCommonLines;
      break;

    default:
      assertNever(runtimeType, `Unknown runtime type: ${String(runtimeType)}`);
  }

  // Remote runtimes: clarify that SHUX_PROJECT_PATH is the user's local path.
  // $MUX_PROJECT_PATH remains a compatibility alias for the same value.
  const isRemote =
    runtimeType === RUNTIME_MODE.SSH ||
    runtimeType === RUNTIME_MODE.DOCKER ||
    runtimeType === RUNTIME_MODE.DEVCONTAINER;
  if (isRemote) {
    lines = [
      ...lines,
      "- $SHUX_PROJECT_PATH refers to the user's local machine, not this environment",
      "- $MUX_PROJECT_PATH is a compatibility alias for $SHUX_PROJECT_PATH",
    ];
  }

  if (bestOf && bestOf.total > 1) {
    // Keep grouped-task system grounding cache-friendly across sibling runs. Candidate-specific
    // steering belongs in the delegated prompt so siblings can share the same system prompt.
    lines = [
      ...lines,
      "- This workspace is part of a grouped sub-agent batch launched by the parent",
      "- Complete only the task described in the prompt; do not start another grouped task batch unless explicitly requested",
    ];
  }

  return `
<environment>
${description}

${lines.join("\n")}
</environment>
`;
}

/**
 * Build MCP servers context XML block.
 * Only included when at least one MCP server is configured.
 * Note: We only expose server names, not commands, to avoid leaking secrets.
 */
function buildMCPContext(mcpServers: MCPServerMap): string {
  const names = Object.keys(mcpServers);
  if (names.length === 0) return "";

  const serverList = names.map((name) => `- ${name}`).join("\n");

  return `
<mcp>
MCP (Model Context Protocol) servers provide additional tools. Configured globally in ~/.shux/mcp.jsonc, with optional repo overrides in ./.mux/mcp.jsonc:

${serverList}

Manage servers in Settings → MCP.
</mcp>
`;
}