winx_code_agent/utils/

orchestration.rs

use std::fmt::Write as _;

const DEFAULT_INSTRUCTIONS: &str = concat!(
    "Initialize Winx once for the intended workspace. Treat structuredContent.status as ",
    "authoritative. Never repeat a failed tool call unchanged: execute next_action and every ",
    "required_read first. Keep the exact thread_id/workspace_root pair for the user's current ",
    "project; never borrow one from another chat. workspace_root identifies the session, not a ",
    "path sandbox: allowed absolute targets outside it do not require rebinding. After a SEARCH ",
    "conflict, only ReadFiles refreshes the edit guard: execute its exact next_action, then use the ",
    "returned revision and visible lines in one corrected EditFiles line_patch. Never fall back to ",
    "shell, sed, or Python for an ordinary source edit. If ",
    "edit_applied=true or status=completed_with_issues, never repeat the original edit: diagnose ",
    "verification and make only corrective changes. If Initialize ",
    "reports initialize_workspace_already_bound or workspace_change_requires_new_session, do not ",
    "call Initialize again in that conversation. If a reset or mode change follows adapter state ",
    "loss, accept the recovered first_call result and continue with its returned pair. Request ",
    "reset_shell only after BashCommand returns a shell-runtime failure; if Winx reports ",
    "reset_skipped_healthy, continue with the preserved PTY instead of retrying. Use CodeMap ",
    "with a concise query to locate code, ",
    "then batch ReadFiles for exact text. Read existing targets before editing; use one EditFiles ",
    "call for a single change or a validated cross-file batch (each file is replaced atomically; a ",
    "commit-time failure reports which files were already written). For an existing file read by ReadFiles, ",
    "default to revision-bound line_patch; reserve search_replace for intentional text anchoring ",
    "copied exactly from the current read, replace for new files or intentional whole-file rewrites, ",
    "and undo only with the returned undo_id. Combine related ",
    "finite checks with && or EditFiles verify_command. For ",
    "BashCommand, follow next_action only while status is running and never auto-approve a prompt ",
    "that changes permissions, data, or system state. If command_already_running, the new command ",
    "did not start; status_check observes the existing execution. Run independent work with ",
    "is_background=true and an explicit working directory; the new shell does not inherit foreground ",
    "variables or functions. Never interrupt or reset an unrelated execution. Use ReadFiles for unsupported CodeMap ",
    "languages; never transform source solely to make CodeMap parse it. Put useful derived helpers ",
    "only in the temporary_artifact_dir returned by Initialize (exported as WINX_TEMP_DIR). Keep ",
    "a small stable set: overwrite or reuse the same descriptive helper per purpose, retain ",
    "source-path/line provenance, remove obsolete files, and treat helpers as non-canonical. Never turn ",
    "TTL-expired helpers into durable state: Winx may reclaim them near the session quota. Never ",
    "convert command, lint, test, or search output into a parseable carrier merely to call CodeMap. CodeMap ",
    "on helpers accepts only an existing single file and has a smaller aggregate session budget; ",
    "canonical source maps remain available. Never encode payload in names or create .winx-* or ",
    ".winx_tmp artifacts at the project root."
);

const DISALLOW_INSTRUCTION: &str = "As soon as you encounter \"The user has chosen to disallow the tool call.\", immediately stop doing everything and ask the user for the reason.";

/// Instructions advertised in the MCP handshake. The stable defaults come
/// first so clients that truncate this field still receive the orchestration
/// contract; operator-provided rules are appended without requiring a rebuild.
///
/// Stateless HTTP clients get a fresh one-shot service per request, so this is
/// on the per-request path; the text is rebuilt only when the operator
/// variable changes.
pub fn server_instructions() -> String {
    static CACHE: std::sync::Mutex<Option<(Option<String>, String)>> = std::sync::Mutex::new(None);
    let extra = crate::config::env_text("WINX_SERVER_INSTRUCTIONS");
    let mut cache = CACHE.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
    if let Some((cached_extra, text)) = cache.as_ref() {
        if *cached_extra == extra {
            return text.clone();
        }
    }
    let mut instructions = format!("{DEFAULT_INSTRUCTIONS}\n\n{DISALLOW_INSTRUCTION}");
    if let Some(extra) = extra.as_deref() {
        let _ = write!(instructions, "\n\nOperator instructions:\n{extra}");
    }
    *cache = Some((extra, instructions.clone()));
    instructions
}

/// Mirror the handshake contract in Initialize output for older clients that
/// do not surface ServerInfo.instructions to the model.
pub fn append_initialize_instructions(response: &mut String) {
    let _ = write!(response, "\n# Winx orchestration contract\n{}\n", server_instructions());
}

#[cfg(test)]
mod tests {
    use super::server_instructions;

    #[test]
    fn default_contract_names_structured_recovery_before_optional_operator_text() {
        let instructions = server_instructions();
        let prefix = instructions.chars().take(512).collect::<String>();
        assert!(prefix.contains("structuredContent.status"));
        assert!(prefix.contains("Never repeat a failed tool call unchanged"));
        assert!(prefix.contains("required_read"));
        assert!(prefix.contains("thread_id/workspace_root pair"));
        assert!(prefix.contains("user's current project"));
        assert!(prefix.contains("not a path sandbox"));
    }

    #[test]
    fn default_contract_keeps_agent_artifacts_coherent() {
        let instructions = server_instructions();
        assert!(instructions.contains("never transform source solely"));
        assert!(instructions.contains("Use ReadFiles"));
        assert!(instructions.contains("temporary_artifact_dir returned by Initialize"));
        assert!(instructions.contains("exported as WINX_TEMP_DIR"));
        assert!(instructions.contains("helpers as non-canonical"));
        assert!(instructions.contains("overwrite or reuse the same descriptive helper"));
        assert!(instructions.contains("merely to call CodeMap"));
        assert!(instructions.contains("existing single file"));
        assert!(instructions.contains("Never encode payload in names"));
        assert!(instructions.contains(".winx-* or .winx_tmp artifacts"));
        assert!(instructions.contains("Winx may reclaim them near the session quota"));
    }

    #[test]
    fn default_contract_stops_terminal_initialize_retries() {
        let instructions = server_instructions();
        assert!(instructions.contains("initialize_workspace_already_bound"));
        assert!(instructions.contains("workspace_change_requires_new_session"));
        assert!(instructions.contains("do not call Initialize again"));
        assert!(instructions.contains("allowed absolute targets outside it"));
        assert!(instructions.contains("reset_shell only after BashCommand"));
        assert!(instructions.contains("reset_skipped_healthy"));
    }

    #[test]
    fn default_contract_distinguishes_edit_conflicts_from_verification_follow_up() {
        let instructions = server_instructions();
        assert!(instructions.contains("only ReadFiles refreshes the edit guard"));
        assert!(instructions.contains("one corrected EditFiles line_patch"));
        assert!(instructions.contains("Never fall back to shell, sed, or Python"));
        assert!(instructions.contains("default to revision-bound line_patch"));
        assert!(instructions.contains("edit_applied=true"));
        assert!(instructions.contains("status=completed_with_issues"));
        assert!(instructions.contains("never repeat the original edit"));
    }
}