agentty 0.10.3

//! Shared prompt-shaping helpers for agent-facing Askama markdown templates.

use askama::Template;

use super::backend::AgentBackendError;
use super::instruction::InstructionDeliveryMode;
use super::protocol::{self, ProtocolRequestProfile};

/// Marker used to detect whether protocol instructions are already included
/// in a prompt.
const PROTOCOL_INSTRUCTIONS_MARKER: &str = "Structured response protocol:";
/// Marker used to detect whether the compact protocol reminder is already
/// included in a prompt.
const PROTOCOL_REFRESH_REMINDER_MARKER: &str = "Protocol refresh reminder:";

/// Controls whether bootstrap prompt instructions include the full protocol
/// JSON Schema text.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProtocolSchemaInstructionMode {
    /// Include the full self-descriptive JSON Schema in the prompt because
    /// the provider does not enforce Agentty's response schema natively.
    PromptSchema,
    /// Omit the full schema text because the provider enforces the same
    /// response schema through its transport-level structured output API.
    TransportSchema,
}

impl ProtocolSchemaInstructionMode {
    /// Returns whether bootstrap instructions should embed the full JSON
    /// Schema text in the prompt body.
    fn includes_response_json_schema(self) -> bool {
        matches!(self, Self::PromptSchema)
    }
}

/// Askama view model for rendering resume prompts with prior session output.
#[derive(Template)]
#[template(path = "resume_with_session_output_prompt.md", escape = "none")]
struct ResumeWithSessionOutputPromptTemplate<'a> {
    /// New prompt content appended after the replayed transcript.
    prompt: &'a str,
    /// Prior session output replayed into the follow-up prompt.
    session_output: &'a str,
}

/// Askama view model for rendering structured response protocol
/// instructions with the shared self-descriptive JSON Schema for providers
/// that need prompt-side enforcement.
#[derive(Template)]
#[template(path = "protocol_instruction_prompt.md", escape = "none")]
struct ProtocolInstructionPromptTemplate<'a> {
    /// User prompt appended after protocol instructions.
    prompt: &'a str,
    /// Request-family-specific instructions that reinforce the expected
    /// response shape for the active prompt type.
    protocol_usage_instructions: &'a str,
    /// Pretty-printed self-descriptive JSON schema contract injected into the
    /// prompt template.
    response_json_schema: &'a str,
}

/// Askama view model for rendering policy-only protocol instructions.
///
/// Providers with native structured-output enforcement receive this smaller
/// prompt contract so Agentty does not duplicate the full schema text in the
/// model context.
#[derive(Template)]
#[template(path = "protocol_instruction_policy_prompt.md", escape = "none")]
struct ProtocolInstructionPolicyPromptTemplate<'a> {
    /// User prompt appended after protocol instructions.
    prompt: &'a str,
    /// Request-family-specific instructions that reinforce the expected
    /// response shape for the active prompt type.
    protocol_usage_instructions: &'a str,
}

/// Askama view model for rendering compact protocol refresh reminders.
#[derive(Template)]
#[template(path = "protocol_refresh_prompt.md", escape = "none")]
struct ProtocolRefreshPromptTemplate<'a> {
    /// Request-family-specific reminder that reinforces the expected response
    /// shape for the active prompt type.
    protocol_refresh_instructions: &'a str,
    /// User prompt appended after the compact reminder.
    prompt: &'a str,
}

/// Askama view model for rendering session-turn protocol usage guidance.
#[derive(Template)]
#[template(path = "protocol_instruction_session_turn_usage.md", escape = "none")]
struct SessionTurnProtocolUsageInstructionsTemplate;

/// Askama view model for rendering utility-prompt protocol usage guidance.
#[derive(Template)]
#[template(path = "protocol_instruction_utility_prompt_usage.md", escape = "none")]
struct UtilityPromptProtocolUsageInstructionsTemplate;

/// Askama view model for rendering session-turn compact refresh guidance.
#[derive(Template)]
#[template(path = "protocol_refresh_session_turn_instruction.md", escape = "none")]
struct SessionTurnProtocolRefreshInstructionsTemplate;

/// Askama view model for rendering utility-prompt compact refresh guidance.
#[derive(Template)]
#[template(
    path = "protocol_refresh_utility_prompt_instruction.md",
    escape = "none"
)]
struct UtilityPromptProtocolRefreshInstructionsTemplate;

/// Shared prompt preparation input for one transport turn.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct PromptPreparationRequest<'a> {
    /// Delivery mode selected for the current provider attempt.
    pub instruction_delivery_mode: InstructionDeliveryMode,
    /// Base user prompt before replay wrapping and protocol instructions.
    pub prompt: &'a str,
    /// Protocol family that determines the rendered instruction envelope.
    pub protocol_profile: ProtocolRequestProfile,
    /// Prior session output available for transcript replay.
    pub replay_session_output: Option<&'a str>,
    /// Schema guidance mode selected from the provider's structured-output
    /// capability.
    pub schema_instruction_mode: ProtocolSchemaInstructionMode,
}

/// Applies transcript replay and protocol instructions to one prompt.
///
/// # Errors
/// Returns an error when replay or instruction templates fail to render.
pub(crate) fn prepare_prompt_text(
    request: PromptPreparationRequest<'_>,
) -> Result<String, AgentBackendError> {
    match request.instruction_delivery_mode {
        InstructionDeliveryMode::BootstrapFull => prepend_protocol_instructions(
            request.prompt,
            request.protocol_profile,
            request.schema_instruction_mode,
        ),
        InstructionDeliveryMode::DeltaOnly => {
            prepend_protocol_refresh_reminder(request.prompt, request.protocol_profile)
        }
        InstructionDeliveryMode::BootstrapWithReplay => {
            let prompt = build_resume_prompt(request.prompt, request.replay_session_output)?;

            prepend_protocol_instructions(
                &prompt,
                request.protocol_profile,
                request.schema_instruction_mode,
            )
        }
    }
}

/// Builds a resume prompt that optionally prepends previous session output.
///
/// # Errors
/// Returns an error if Askama template rendering fails.
pub(crate) fn build_resume_prompt(
    prompt: &str,
    session_output: Option<&str>,
) -> Result<String, AgentBackendError> {
    let Some(session_output) = session_output
        .map(str::trim)
        .filter(|value| !value.is_empty())
    else {
        return Ok(prompt.to_string());
    };

    let template = ResumeWithSessionOutputPromptTemplate {
        prompt,
        session_output,
    };

    render_template("resume_with_session_output_prompt.md", &template)
}

/// Prepends structured response protocol instructions to a prompt.
///
/// Tells agents to emit one top-level JSON object that matches Agentty's
/// structured protocol while selecting the cheapest safe schema guidance for
/// the current provider. Providers without native structured output receive
/// the full JSON Schema in the prompt; providers with native enforcement get
/// policy and field-routing instructions only. The shared prompt contract
/// also requires repository-root-relative POSIX file paths, repository-defined
/// quality checks for touched files and the affected dependency graph,
/// cleanup of temporary session files, and full repository validation when
/// targeted coverage is unclear. If the prompt already contains the protocol
/// marker, this function returns the prompt unchanged to avoid duplicated
/// guidance.
///
/// # Errors
/// Returns an error if Askama template rendering fails.
pub(crate) fn prepend_protocol_instructions(
    prompt: &str,
    profile: ProtocolRequestProfile,
    schema_instruction_mode: ProtocolSchemaInstructionMode,
) -> Result<String, AgentBackendError> {
    if prompt.contains(PROTOCOL_INSTRUCTIONS_MARKER) {
        return Ok(prompt.to_string());
    }

    let protocol_usage_instructions = render_protocol_usage_instructions(profile)?;
    if !schema_instruction_mode.includes_response_json_schema() {
        let template = ProtocolInstructionPolicyPromptTemplate {
            prompt,
            protocol_usage_instructions: &protocol_usage_instructions,
        };

        return render_template("protocol_instruction_policy_prompt.md", &template);
    }

    let response_json_schema = protocol::agent_response_json_schema_json();
    let template = ProtocolInstructionPromptTemplate {
        prompt,
        protocol_usage_instructions: &protocol_usage_instructions,
        response_json_schema: &response_json_schema,
    };

    render_template("protocol_instruction_prompt.md", &template)
}

/// Prepends a compact refresh reminder for providers that already received
/// the full instruction contract in the active context.
pub(crate) fn prepend_protocol_refresh_reminder(
    prompt: &str,
    profile: ProtocolRequestProfile,
) -> Result<String, AgentBackendError> {
    if prompt.contains(PROTOCOL_INSTRUCTIONS_MARKER)
        || prompt.contains(PROTOCOL_REFRESH_REMINDER_MARKER)
    {
        return Ok(prompt.to_string());
    }

    let protocol_refresh_instructions = render_protocol_refresh_instructions(profile)?;
    let template = ProtocolRefreshPromptTemplate {
        protocol_refresh_instructions: &protocol_refresh_instructions,
        prompt,
    };

    render_template("protocol_refresh_prompt.md", &template)
}

/// Returns request-family-specific protocol guidance for the shared prompt
/// preamble from Askama-backed markdown templates.
fn render_protocol_usage_instructions(
    profile: ProtocolRequestProfile,
) -> Result<String, AgentBackendError> {
    match profile {
        ProtocolRequestProfile::SessionTurn => render_template(
            "protocol_instruction_session_turn_usage.md",
            &SessionTurnProtocolUsageInstructionsTemplate,
        ),
        ProtocolRequestProfile::UtilityPrompt => render_template(
            "protocol_instruction_utility_prompt_usage.md",
            &UtilityPromptProtocolUsageInstructionsTemplate,
        ),
    }
}

/// Returns the compact reminder text for providers that already know the full
/// schema and policy contract from Askama-backed markdown templates.
fn render_protocol_refresh_instructions(
    profile: ProtocolRequestProfile,
) -> Result<String, AgentBackendError> {
    match profile {
        ProtocolRequestProfile::SessionTurn => render_template(
            "protocol_refresh_session_turn_instruction.md",
            &SessionTurnProtocolRefreshInstructionsTemplate,
        ),
        ProtocolRequestProfile::UtilityPrompt => render_template(
            "protocol_refresh_utility_prompt_instruction.md",
            &UtilityPromptProtocolRefreshInstructionsTemplate,
        ),
    }
}

/// Builds a Markdown code-fence delimiter long enough to safely wrap an
/// arbitrary diff payload.
///
/// Returns a string of backticks whose length exceeds the longest run of
/// consecutive backticks found anywhere in `content`, with a minimum length
/// of three. This prevents a triple-backtick fence from being terminated
/// prematurely when the diff itself contains Markdown fences (for example,
/// when reviewing changes to Markdown or prompt-template files).
pub(crate) fn diff_fence(content: &str) -> String {
    let mut max_run = 0usize;
    let mut current_run = 0usize;
    for character in content.chars() {
        if character == '`' {
            current_run += 1;
            if current_run > max_run {
                max_run = current_run;
            }
        } else {
            current_run = 0;
        }
    }

    let fence_length = std::cmp::max(3, max_run + 1);

    "`".repeat(fence_length)
}

/// Renders one Askama markdown template and trims the trailing newline added
/// by file-based templates.
fn render_template(
    template_name: &str,
    template: &impl Template,
) -> Result<String, AgentBackendError> {
    let rendered = template.render().map_err(|error| {
        AgentBackendError::CommandBuild(format!("Failed to render `{template_name}`: {error}"))
    })?;

    Ok(rendered.trim_end().to_string())
}

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

    #[test]
    /// Ensures the diff fence falls back to three backticks when the content
    /// contains no backtick runs.
    fn test_diff_fence_returns_minimum_three_backticks_for_plain_diff() {
        // Arrange
        let diff = "diff --git a/a.rs b/a.rs\n+fn main() {}\n";

        // Act
        let fence = diff_fence(diff);

        // Assert
        assert_eq!(fence, "```");
    }

    #[test]
    /// Ensures the diff fence grows to exceed the longest backtick run in the
    /// diff so a Markdown triple-backtick fence inside the diff cannot
    /// terminate the outer wrapper fence.
    fn test_diff_fence_exceeds_longest_backtick_run_in_diff() {
        // Arrange
        let diff = "+```\nsample\n+```\n";

        // Act
        let fence = diff_fence(diff);

        // Assert
        assert_eq!(fence, "````");
    }

    #[test]
    /// Ensures longer backtick runs keep producing a strictly longer fence so
    /// nested or unusually long code fences in the diff stay contained.
    fn test_diff_fence_handles_long_backtick_runs() {
        // Arrange
        let diff = "prefix `````diff\ncontent\n`````\n";

        // Act
        let fence = diff_fence(diff);

        // Assert
        assert_eq!(fence, "``````");
    }

    #[test]
    /// Ensures resume prompt rendering includes trimmed session output and
    /// the new user prompt.
    fn test_build_resume_prompt_includes_session_output_and_prompt() {
        // Arrange
        let prompt = "Continue and update tests";
        let session_output = Some("  previous output line  \n");

        // Act
        let resume_prompt =
            build_resume_prompt(prompt, session_output).expect("resume prompt should render");

        // Assert
        assert!(resume_prompt.contains("previous output line"));
        assert!(resume_prompt.contains("Continue and update tests"));
    }

    #[test]
    /// Ensures whitespace-only session output does not trigger transcript
    /// wrapping and returns the original prompt.
    fn test_build_resume_prompt_returns_original_prompt_when_output_is_blank() {
        // Arrange
        let prompt = "Follow-up request";
        let session_output = Some("   ");

        // Act
        let resume_prompt =
            build_resume_prompt(prompt, session_output).expect("resume prompt should render");

        // Assert
        assert_eq!(resume_prompt, prompt);
    }

    #[test]
    /// Ensures absent session output keeps resume prompt formatting unchanged.
    fn test_build_resume_prompt_returns_original_prompt_without_output() {
        // Arrange
        let prompt = "Retry merge";

        // Act
        let resume_prompt = build_resume_prompt(prompt, None).expect("resume prompt should render");

        // Assert
        assert_eq!(resume_prompt, prompt);
    }

    #[test]
    /// Ensures session prompts include the critical protocol contract markers.
    fn test_prepend_protocol_instructions_adds_session_protocol_instructions() {
        // Arrange
        let prompt = "Implement feature";

        // Act
        let rendered_prompt = prepend_protocol_instructions(
            prompt,
            ProtocolRequestProfile::SessionTurn,
            ProtocolSchemaInstructionMode::PromptSchema,
        )
        .expect("protocol instruction prompt should render");

        // Assert
        assert!(rendered_prompt.contains("File path output requirements:"));
        assert!(rendered_prompt.contains("repository-root-relative POSIX paths"));
        assert!(rendered_prompt.contains("Paths must be relative to the repository root."));
        assert!(rendered_prompt.contains("If you run git commands, use read-only commands only"));
        assert!(rendered_prompt.contains("Do not run mutating git commands"));
        assert!(rendered_prompt.contains("Quality check requirements:"));
        assert!(rendered_prompt.contains("repository-defined quality checks"));
        let normalized_rendered_prompt = rendered_prompt.split_whitespace().collect::<Vec<_>>();
        let normalized_rendered_prompt = normalized_rendered_prompt.join(" ");
        assert!(normalized_rendered_prompt.contains("affected dependencies and dependents"));
        assert!(rendered_prompt.contains("full repository test/check suite"));
        assert!(rendered_prompt.contains("Remove any temporary scripts or files"));
        assert!(rendered_prompt.contains("Structured response protocol:"));
        assert!(rendered_prompt.contains("Return a single JSON object"));
        assert!(rendered_prompt.contains("Do not wrap the JSON in markdown code fences."));
        assert!(rendered_prompt.contains("Follow this JSON Schema exactly."));
        assert!(rendered_prompt.contains("Treat the JSON Schema titles and descriptions"));
        assert!(rendered_prompt.contains("Authoritative JSON Schema:"));
        assert!(rendered_prompt.contains("---"));
        assert!(rendered_prompt.contains("For this session turn"));
        assert!(normalized_rendered_prompt.contains("Do not create commits"));
        assert!(normalized_rendered_prompt.contains("suggest creating commits"));
        assert!(rendered_prompt.contains("summary"));
        assert!(rendered_prompt.contains("turn"));
        assert!(rendered_prompt.contains("session"));
        assert!(rendered_prompt.contains("\"answer\""));
        assert!(rendered_prompt.contains("\"questions\""));
        assert!(rendered_prompt.contains("\"title\""));
        assert!(rendered_prompt.contains("\"description\""));
        assert!(rendered_prompt.contains("summary"));
        assert!(rendered_prompt.ends_with(prompt));
    }

    #[test]
    /// Ensures schema-enforcing transports get protocol policy without the
    /// large prompt-side JSON Schema body.
    fn test_prepend_protocol_instructions_omits_schema_for_transport_schema_mode() {
        // Arrange
        let prompt = "Implement feature";

        // Act
        let rendered_prompt = prepend_protocol_instructions(
            prompt,
            ProtocolRequestProfile::SessionTurn,
            ProtocolSchemaInstructionMode::TransportSchema,
        )
        .expect("protocol instruction prompt should render");

        // Assert
        assert!(rendered_prompt.contains("Structured response protocol:"));
        assert!(rendered_prompt.contains("provider enforces Agentty's response JSON schema"));
        assert!(rendered_prompt.contains("Return a single JSON object"));
        assert!(!rendered_prompt.contains("Follow this JSON Schema exactly."));
        assert!(!rendered_prompt.contains("Authoritative JSON Schema:"));
        assert!(rendered_prompt.ends_with(prompt));
    }

    #[test]
    /// Ensures protocol instructions are not duplicated when already present.
    fn test_prepend_protocol_instructions_is_idempotent() {
        // Arrange
        let prompt = prepend_protocol_instructions(
            "Implement feature",
            ProtocolRequestProfile::SessionTurn,
            ProtocolSchemaInstructionMode::PromptSchema,
        )
        .expect("protocol instruction prompt should render");

        // Act
        let rendered_prompt = prepend_protocol_instructions(
            &prompt,
            ProtocolRequestProfile::UtilityPrompt,
            ProtocolSchemaInstructionMode::TransportSchema,
        )
        .expect("protocol instruction prompt should render");

        // Assert
        assert_eq!(rendered_prompt, prompt);
    }

    #[test]
    /// Ensures one-shot prompts reuse the shared full-schema protocol
    /// instructions.
    fn test_prepend_protocol_instructions_reuses_same_contract_for_one_shot() {
        // Arrange
        let prompt = "Generate title";

        // Act
        let rendered_prompt = prepend_protocol_instructions(
            prompt,
            ProtocolRequestProfile::UtilityPrompt,
            ProtocolSchemaInstructionMode::PromptSchema,
        )
        .expect("protocol instruction prompt should render");

        // Assert
        assert!(rendered_prompt.contains("Structured response protocol:"));
        assert!(rendered_prompt.contains("---"));
        assert!(rendered_prompt.contains("For this one-shot utility prompt"));
        assert!(rendered_prompt.contains(r#"{"answer":"...","questions":[],"summary":null}"#));
        assert!(rendered_prompt.contains("\"summary\""));
        assert!(rendered_prompt.ends_with(prompt));
    }

    #[test]
    /// Ensures shared prompt preparation applies replay wrapping before
    /// protocol instructions.
    fn test_prepare_prompt_text_applies_replay_and_protocol_instructions() {
        // Arrange
        let request = PromptPreparationRequest {
            instruction_delivery_mode: InstructionDeliveryMode::BootstrapWithReplay,
            prompt: "Continue edits",
            protocol_profile: ProtocolRequestProfile::SessionTurn,
            replay_session_output: Some("previous output"),
            schema_instruction_mode: ProtocolSchemaInstructionMode::PromptSchema,
        };

        // Act
        let prepared_prompt = prepare_prompt_text(request).expect("prompt should render");

        // Assert
        assert!(prepared_prompt.contains("Structured response protocol:"));
        assert!(prepared_prompt.contains("previous output"));
        assert!(prepared_prompt.ends_with("Continue edits"));
    }

    #[test]
    /// Ensures compact refresh reminders omit the full schema while keeping
    /// the contract reminder and task body.
    fn test_prepend_protocol_refresh_reminder_adds_compact_contract_notice() {
        // Arrange
        let prompt = "Continue the implementation";

        // Act
        let rendered_prompt =
            prepend_protocol_refresh_reminder(prompt, ProtocolRequestProfile::SessionTurn)
                .expect("protocol refresh reminder should render");

        // Assert
        assert!(rendered_prompt.contains("Protocol refresh reminder:"));
        assert!(rendered_prompt.contains("repository-root-relative POSIX paths"));
        assert!(rendered_prompt.contains("read-only git commands"));
        assert!(!rendered_prompt.contains("Authoritative JSON Schema:"));
        assert!(rendered_prompt.ends_with(prompt));
    }

    #[test]
    /// Ensures prompt preparation can emit the compact app-server reminder
    /// instead of the full bootstrap wrapper.
    fn test_prepare_prompt_text_uses_delta_only_refresh_mode() {
        // Arrange
        let request = PromptPreparationRequest {
            instruction_delivery_mode: InstructionDeliveryMode::DeltaOnly,
            prompt: "Continue edits",
            protocol_profile: ProtocolRequestProfile::SessionTurn,
            replay_session_output: Some("previous output"),
            schema_instruction_mode: ProtocolSchemaInstructionMode::PromptSchema,
        };

        // Act
        let prepared_prompt = prepare_prompt_text(request).expect("prompt should render");

        // Assert
        assert!(prepared_prompt.contains("Protocol refresh reminder:"));
        assert!(!prepared_prompt.contains("Authoritative JSON Schema:"));
        assert!(!prepared_prompt.contains("previous output"));
        assert!(prepared_prompt.ends_with("Continue edits"));
    }
}