harn-vm 0.10.131

use super::*;

pub(super) const DIRECTIVE_ENVELOPE_INSTRUCTIONS_ASSET: &str =
    "llm/prompts/directive_envelope_instructions.harn.prompt";
pub(super) const DIRECTIVE_IDS_KEY: &str = "_harn_directive_ids";

pub(super) fn directive_envelope_instructions() -> &'static str {
    static RENDERED: std::sync::OnceLock<String> = std::sync::OnceLock::new();
    RENDERED
        .get_or_init(|| {
            crate::stdlib::template::render_stdlib_prompt_asset(
                DIRECTIVE_ENVELOPE_INSTRUCTIONS_ASSET,
                None,
            )
            .expect("directive envelope instruction prompt asset is embedded and must render")
            .trim_end()
            .to_string()
        })
        .as_str()
}

/// Who a directive speaks as once it reaches the model.
///
/// Chosen by a total match on [`ReminderRoleHint`], with no default arm, so a
/// hint added later cannot fall through and silently borrow the person's
/// voice.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum DirectiveSpeaker {
    /// Harness machinery: reminder providers, the completion judge, loop
    /// feedback. Not the person the agent is working for.
    Harness,
    /// The person's own instructions, carried in a directive.
    Person,
}

impl DirectiveSpeaker {
    pub(super) fn from_role_hint(role_hint: ReminderRoleHint) -> Self {
        match role_hint {
            ReminderRoleHint::System
            | ReminderRoleHint::Developer
            | ReminderRoleHint::EphemeralCache => Self::Harness,
            ReminderRoleHint::UserBlock => Self::Person,
        }
    }

    pub(super) fn as_str(self) -> &'static str {
        match self {
            Self::Harness => "harness",
            Self::Person => "person",
        }
    }

    /// The wire role the envelope message travels under.
    ///
    /// Both variants project onto `user` today, because `user` is the only
    /// mid-conversation role every provider dialect accepts: Anthropic's
    /// Messages API rejects any top-level role but `user` and `assistant`
    /// inside the array, and the OpenAI, Gemini, and local dialects offer no
    /// mid-array system slot either. So the distinction the model actually
    /// reads is the envelope's `speaker` attribute plus the audience clause in
    /// the instruction asset, not this role. The mapping lives here so that a
    /// dialect which later grows a real harness role changes one function.
    pub(super) fn transport_role(self) -> &'static str {
        match self {
            Self::Harness | Self::Person => "user",
        }
    }
}

/// One envelope carries every pending directive, so a single harness directive
/// makes the whole envelope harness machinery.
fn envelope_speaker(rendered: &[RenderedReminder]) -> DirectiveSpeaker {
    if rendered
        .iter()
        .any(|reminder| reminder.speaker == DirectiveSpeaker::Harness)
    {
        DirectiveSpeaker::Harness
    } else {
        DirectiveSpeaker::Person
    }
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) struct RenderedReminder {
    reminder_id: Option<String>,
    text: String,
    speaker: DirectiveSpeaker,
}

impl RenderedReminder {
    #[cfg(test)]
    pub(super) fn untracked(text: impl Into<String>, speaker: DirectiveSpeaker) -> Self {
        Self {
            reminder_id: None,
            text: text.into(),
            speaker,
        }
    }

    pub(super) fn tracked(
        reminder_id: impl Into<String>,
        text: impl Into<String>,
        speaker: DirectiveSpeaker,
    ) -> Self {
        Self {
            reminder_id: Some(reminder_id.into()),
            text: text.into(),
            speaker,
        }
    }

    /// The role the wire actually used, for the reminder-lifecycle telemetry.
    /// Both speakers transport as `user`, so this equals the role of the
    /// envelope this directive rode in. Telemetry must never claim a role the
    /// wire did not use.
    fn rendered_role(&self) -> String {
        self.speaker.transport_role().to_string()
    }

    fn rendered_bytes(&self) -> usize {
        self.text.len()
    }

    pub(super) fn text(&self) -> &str {
        &self.text
    }

    pub(super) fn reminder_id(&self) -> Option<&str> {
        self.reminder_id.as_deref()
    }
}

/// Wrap rendered directive blocks in the one model-facing envelope. Both the
/// legacy per-request projection and append-only placement render through
/// here, so the model-visible text is identical under either placement.
pub(crate) fn directive_envelope(rendered: &[RenderedReminder]) -> Option<String> {
    let blocks: Vec<&str> = rendered.iter().map(RenderedReminder::text).collect();
    if blocks.is_empty() {
        return None;
    }
    let instructions = directive_envelope_instructions();
    let speaker = envelope_speaker(rendered).as_str();
    Some(format!(
        "<context-directives speaker=\"{speaker}\">\n{instructions}\n{}\n</context-directives>",
        blocks.join("\n")
    ))
}

/// One trailing message carrying the directive envelope, under the transport
/// role its speaker projects onto.
pub(crate) fn directive_envelope_message(
    rendered: &[RenderedReminder],
) -> Option<serde_json::Value> {
    let role = envelope_speaker(rendered).transport_role();
    directive_envelope(rendered).map(|envelope| {
        let mut message = serde_json::json!({"role": role, "content": envelope});
        let reminder_ids: Vec<&str> = rendered
            .iter()
            .filter_map(RenderedReminder::reminder_id)
            .collect();
        if !reminder_ids.is_empty() {
            message[DIRECTIVE_IDS_KEY] = serde_json::json!(reminder_ids);
        }
        message
    })
}

#[cfg(test)]
pub(crate) fn tracked_directive_envelope_message(
    reminder_id: &str,
    text: &str,
) -> serde_json::Value {
    directive_envelope_message(&[RenderedReminder::tracked(
        reminder_id,
        text,
        DirectiveSpeaker::Harness,
    )])
    .expect("tracked directive is non-empty")
}

/// Remove durable placement receipts before a message array reaches any
/// provider. The receipts distinguish reminder instances inside Harn; the
/// model-facing directive text carries authority and lifetime, not IDs.
pub(crate) fn strip_directive_commit_metadata(messages: &mut [serde_json::Value]) {
    for message in messages {
        if let Some(object) = message.as_object_mut() {
            object.remove(DIRECTIVE_IDS_KEY);
        }
    }
}

pub(crate) fn has_directive_commit_metadata(message: &serde_json::Value) -> bool {
    message
        .get(DIRECTIVE_IDS_KEY)
        .and_then(serde_json::Value::as_array)
        .is_some_and(|ids| !ids.is_empty())
}

pub(super) fn reminder_directive_text(reminder: &SystemReminder) -> String {
    let lifetime = reminder
        .ttl_turns
        .map(|turns| format!(" ttl_turns=\"{turns}\""))
        .unwrap_or_default();
    format!(
        "<directive authority=\"{}\"{}>\n{}\n</directive>",
        reminder.authority.as_str(),
        lifetime,
        escape_xml_text(&reminder.body)
    )
}

pub(crate) fn render_pending_reminders(
    _caps: &crate::llm::capabilities::Capabilities,
    reminders: &[SystemReminder],
) -> Vec<RenderedReminder> {
    reminders
        .iter()
        .map(|reminder| {
            RenderedReminder::tracked(
                reminder.id.clone(),
                reminder_directive_text(reminder),
                DirectiveSpeaker::from_role_hint(reminder.role_hint),
            )
        })
        .collect()
}

pub(super) fn rendered_reminder_lifecycle(
    session_id: Option<&str>,
    turn_number: i64,
    reminders: &[SystemReminder],
    rendered: &[RenderedReminder],
) -> Vec<crate::llm::api::ReminderLifecycleEmission> {
    reminders
        .iter()
        .zip(rendered.iter())
        .map(|(reminder, rendered)| {
            let rendered_role = rendered.rendered_role();
            crate::llm::api::ReminderLifecycleEmission {
                session_id: session_id.map(str::to_string),
                turn_number,
                reminder_id: reminder.id.clone(),
                tags: reminder.tags.clone(),
                body: reminder.body.clone(),
                dedupe_key: reminder.dedupe_key.clone(),
                source: reminder.source.as_str().to_string(),
                role_hint: reminder.role_hint.as_str().to_string(),
                authority: reminder.authority.as_str().to_string(),
                rendered_role,
                body_bytes: reminder.body.len(),
                rendered_bytes: rendered.rendered_bytes(),
                ttl_turns: reminder.ttl_turns,
                propagate: reminder.propagate.as_str().to_string(),
                originating_agent_id: reminder.originating_agent_id.clone(),
            }
        })
        .collect()
}

pub(super) fn emit_dropped_reminder_lifecycle(session_id: &str, reminder_id: String, reason: &str) {
    emit_reminder_lifecycle_event(
        REMINDER_DROPPED_EVENT_KIND,
        serde_json::json!({
            "session_id": session_id,
            "reminder_id": reminder_id,
            "reason": reason,
        }),
    );
}

pub(crate) fn pending_reminders_from_session(session_id: Option<&str>) -> Vec<SystemReminder> {
    let Some(session_id) = session_id.filter(|id| !id.is_empty()) else {
        return Vec::new();
    };
    let Some(transcript) = crate::agent_sessions::transcript(session_id) else {
        return Vec::new();
    };
    let Some(dict) = transcript.as_dict() else {
        return Vec::new();
    };
    let events = dict.get("events").or_else(|| dict.get("messages"));
    let Some(VmValue::List(items)) = events else {
        return Vec::new();
    };
    let mut reminders = Vec::new();
    let mut invalid_count = 0;
    for event in items.iter() {
        if let Some(reminder) = reminder_from_event(event) {
            if reminder.body.trim().is_empty() {
                invalid_count += 1;
                emit_dropped_reminder_lifecycle(session_id, reminder.id, "invalid");
                continue;
            }
            reminders.push(reminder);
            continue;
        }
        let Some(dict) = event.as_dict() else {
            continue;
        };
        if dict.get("kind").map(VmValue::display).as_deref() != Some(SYSTEM_REMINDER_EVENT_KIND) {
            continue;
        }
        invalid_count += 1;
        let reminder_id = dict
            .get("reminder")
            .and_then(VmValue::as_dict)
            .and_then(|reminder| reminder.get("id"))
            .map(VmValue::display)
            .filter(|id| !id.is_empty())
            .or_else(|| {
                dict.get("id")
                    .map(VmValue::display)
                    .filter(|id| !id.is_empty())
            })
            .unwrap_or_else(|| "invalid-reminder".to_string());
        emit_dropped_reminder_lifecycle(session_id, reminder_id, "invalid");
    }
    if invalid_count > 0 {
        crate::agent_sessions::prune_invalid_reminder_events(session_id);
    }
    dedupe_and_order_directives(reminders)
}

/// Enforce the directive envelope's one deduplication and precedence policy.
/// Authority wins before recency, first for an explicit producer key and then
/// for normalized model-visible content. The retained directives are emitted
/// in contract > corrective > advisory order, with transcript order preserved
/// inside a tier.
fn dedupe_and_order_directives(reminders: Vec<SystemReminder>) -> Vec<SystemReminder> {
    fn candidate_wins(
        candidate: &(usize, SystemReminder),
        current: &(usize, SystemReminder),
    ) -> bool {
        candidate.1.authority.priority() > current.1.authority.priority()
            || (candidate.1.authority.priority() == current.1.authority.priority()
                && candidate.0 > current.0)
    }

    let indexed: Vec<(usize, SystemReminder)> = reminders.into_iter().enumerate().collect();
    let mut winner_for_key = std::collections::HashMap::<String, (usize, SystemReminder)>::new();
    for candidate in &indexed {
        let Some(key) = candidate.1.dedupe_key.as_ref() else {
            continue;
        };
        match winner_for_key.get(key) {
            Some(current) if !candidate_wins(candidate, current) => {}
            _ => {
                winner_for_key.insert(key.clone(), candidate.clone());
            }
        }
    }
    let keyed: Vec<(usize, SystemReminder)> = indexed
        .into_iter()
        .filter(|candidate| match candidate.1.dedupe_key.as_ref() {
            Some(key) => winner_for_key
                .get(key)
                .is_some_and(|winner| winner.0 == candidate.0),
            None => true,
        })
        .collect();

    let mut winner_for_body = std::collections::HashMap::<String, (usize, SystemReminder)>::new();
    for candidate in &keyed {
        let normalized = candidate
            .1
            .body
            .split_whitespace()
            .collect::<Vec<_>>()
            .join(" ");
        match winner_for_body.get(&normalized) {
            Some(current) if !candidate_wins(candidate, current) => {}
            _ => {
                winner_for_body.insert(normalized, candidate.clone());
            }
        }
    }
    let mut retained: Vec<(usize, SystemReminder)> = keyed
        .into_iter()
        .filter(|candidate| {
            let normalized = candidate
                .1
                .body
                .split_whitespace()
                .collect::<Vec<_>>()
                .join(" ");
            winner_for_body
                .get(&normalized)
                .is_some_and(|winner| winner.0 == candidate.0)
        })
        .collect();
    retained.sort_by_key(|(index, reminder)| {
        (std::cmp::Reverse(reminder.authority.priority()), *index)
    });
    retained.into_iter().map(|(_, reminder)| reminder).collect()
}

/// Project pending directives into the provider-visible message array.
///
/// Directives already committed to durable history are not re-issued. A new
/// envelope is always its own trailing `user` turn.
///
/// This is normally a no-op inside an agent loop: the turn boundary has
/// already committed the envelope, so nothing is left uncommitted by the time
/// a request is built. The tail append serves callers that read the visible
/// projection without a turn boundary of their own.
pub(crate) fn apply_rendered_reminder_messages(
    messages: Vec<serde_json::Value>,
    rendered: &[RenderedReminder],
) -> Vec<serde_json::Value> {
    let mut messages = messages;
    let pending = super::directive_placement::uncommitted_directives(&messages, rendered);
    if let Some(message) = directive_envelope_message(&pending) {
        messages.push(message);
    }
    messages
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::llm::helpers::{DirectiveAuthority, ReminderSource};

    fn reminder(body: &str, dedupe_key: Option<&str>) -> SystemReminder {
        let mut reminder = SystemReminder::new(body, ReminderSource::StdlibProvider, 0);
        reminder.dedupe_key = dedupe_key.map(str::to_string);
        reminder
    }

    /// harn#4731 defect #3: two reminders sharing a `dedupe_key` (e.g. a recap
    /// re-attached across a compaction) must render/emit at most once per
    /// iteration. Newest wins; first-seen order is preserved.
    #[test]
    fn dedup_prefers_authority_then_recency_and_orders_the_envelope() {
        let input = vec![
            reminder("recap v1", Some("post_compact_recap")),
            reminder("workspace anchor", Some("workspace_anchor")),
            reminder("recap v2", Some("post_compact_recap")),
            {
                let mut value = reminder("  workspace   anchor ", None);
                value.authority = DirectiveAuthority::Advisory;
                value
            },
            {
                let mut value = reminder("correct the loop", None);
                value.authority = DirectiveAuthority::Corrective;
                value
            },
        ];
        let out = dedupe_and_order_directives(input);
        let bodies: Vec<&str> = out.iter().map(|r| r.body.as_str()).collect();
        assert_eq!(
            bodies,
            vec!["workspace anchor", "recap v2", "correct the loop"]
        );
    }

    #[test]
    fn higher_authority_wins_even_when_the_duplicate_is_older() {
        let mut contract = reminder("contract", Some("same"));
        contract.authority = DirectiveAuthority::Contract;
        let mut corrective = reminder("corrective", Some("same"));
        corrective.authority = DirectiveAuthority::Corrective;

        let out = dedupe_and_order_directives(vec![contract, corrective]);
        assert_eq!(out.len(), 1);
        assert_eq!(out[0].body, "contract");
    }

    /// The trace shape behind harn#7580, replayed at the seam that decides it.
    ///
    /// An operator steers mid-turn; the turn-end judge then vetoes, re-derives
    /// acceptance from the ORIGINAL task, and its feedback is stamped
    /// `corrective` under `runtime_feedback/<kind>` by
    /// `crate::llm::agent_config::inject_agent_feedback`. The two carry
    /// different dedupe keys, so both survive into one envelope and the model
    /// is told two contradictory things in the same breath. Which one it
    /// follows is decided entirely by the authority each carries.
    ///
    /// Before the fix the steer was a plain user message with no authority at
    /// all, so the judge's corrective was the ranking instruction and the
    /// model reverted. Delivering the steer as `contract` puts the operator
    /// above the harness — the order the envelope instructions state — and
    /// renders it first regardless of arrival order.
    #[test]
    fn an_operator_steer_outranks_a_judge_corrective_that_arrives_later() {
        let mut steer = reminder(
            "The operator redirected this run mid-turn. […] final reply must be exactly BRAVO",
            Some("operator_steer/msg_inj_0199"),
        );
        steer.authority = DirectiveAuthority::Contract;
        let mut veto = reminder(
            "the final reply was 'BRAVO' not 'ALPHA'; call look to confirm",
            Some("runtime_feedback/verify_completion"),
        );
        veto.authority = DirectiveAuthority::Corrective;

        // Arrival order is the defect's order: the judge speaks last.
        let out = dedupe_and_order_directives(vec![steer, veto]);
        let authorities: Vec<&str> = out.iter().map(|r| r.authority.as_str()).collect();
        assert_eq!(
            authorities,
            vec!["contract", "corrective"],
            "the operator's steer must rank above a later judge corrective, and \
             render first; got {out:#?}"
        );
        assert!(
            out[0].body.contains("BRAVO"),
            "the steer text must still be present at the next model call; got {:?}",
            out[0].body
        );
    }
}