Function buildSystemMessage

src/node/services/systemMessage.ts:497–647

(
  metadata: WorkspaceMetadata,
  runtime: Runtime,
  workspacePath: string,
  additionalSystemInstructions?: string,
  modelString?: string,
  mcpServers?: MCPServerMap,
  options?: {
    /**
     * Resolved agent prompt as independently-authored sections (agent body,
     * subagent append_prompt, advisor guidance, …). Per-section so a trailing
     * scoped heading in one section cannot swallow the next section's text.
     */
    agentSystemPromptSections?: readonly string[];
    /**
     * Active mode identifiers used to extract "Mode: <mode>" sections from
     * Mux-dedicated instruction sources: the effective mode (plan/exec/compact)
     * plus the agent id, so "Mode: plan" covers custom plan-like agents and
     * "Mode: <agent>" covers per-agent sections. The first entry names the
     * injected <mode-...> tag. Duplicates are ignored.
     */
    modes?: readonly string[];
  }
)

 * @throws Error if metadata or workspacePath invalid
 */
export async function buildSystemMessage(
  metadata: WorkspaceMetadata,
  runtime: Runtime,
  workspacePath: string,
  additionalSystemInstructions?: string,
  modelString?: string,
  mcpServers?: MCPServerMap,
  options?: {
    /**
     * Resolved agent prompt as independently-authored sections (agent body,
     * subagent append_prompt, advisor guidance, …). Per-section so a trailing
     * scoped heading in one section cannot swallow the next section's text.
     */
    agentSystemPromptSections?: readonly string[];
    /**
     * Active mode identifiers used to extract "Mode: <mode>" sections from
     * Mux-dedicated instruction sources: the effective mode (plan/exec/compact)
     * plus the agent id, so "Mode: plan" covers custom plan-like agents and
     * "Mode: <agent>" covers per-agent sections. The first entry names the
     * injected <mode-...> tag. Duplicates are ignored.
     */
    modes?: readonly string[];
  }
): Promise<string> {
  if (!metadata) throw new Error("Invalid workspace metadata: metadata is required");
  if (!workspacePath) throw new Error("Invalid workspace path: workspacePath is required");

  // Read instruction sets
  // Get runtime type from metadata (defaults to "local" for legacy workspaces without runtimeConfig)
  const runtimeType = metadata.runtimeConfig?.type ?? "local";

  // Build system message
  let systemMessage = `${PRELUDE.trim()}\n\n${buildEnvironmentContext(
    workspacePath,
    runtimeType,
    metadata.bestOf
  )}`;

  // Add MCP context if servers are configured
  if (mcpServers && Object.keys(mcpServers).length > 0) {
    systemMessage += buildMCPContext(mcpServers);
  }

  // NOTE: Agent skills and available sub-agents are now injected into their respective
  // tool descriptions (agent_skill_read, task) for better model attention per Anthropic
  // best practices. See tools.ts ToolConfiguration.availableSkills/availableSubagents.

  // Read instruction sets
  // Sub-project workspaces pass the execution path (root + subProject); fall
  // back to the resolved root so the parent project's AGENTS.md is still read.
  // For non-sub-project workspaces this is a no-op (root === execution path).
  const workspaceRootPath = subProjectAwareWorkspaceRoot(metadata, runtime, workspacePath);
  const instructionSources = await loadInstructionSources(metadata, runtime, workspaceRootPath);
  // Mux-dedicated per-file contents (<dir>/.mux/AGENTS.md context files, then
  // the global ~/.mux/AGENTS.md set, which is Mux-dedicated by construction).
  // Scoped Model:/Mode: directives are honored ONLY in Mux-dedicated sources
  // so a "Model: …" heading in a shared AGENTS.md (read by non-Mux agents too)
  // stays ordinary markdown. Extraction runs per file: a scoped section at the