harn-vm 0.10.162

//! Typed call/result pairing receipts for the LLM transcript sidecar.
//!
//! # Why the transcript needs them
//!
//! Reconstructing "which tool result answers which tool call" from the
//! recorded turns alone does not work on every channel.
//!
//! On the native channel the provider gives each call an id and the result
//! message carries it back, so the pair is visible. On the text channel there
//! is no such id: the model writes an inline `<tool_call>` block, and the
//! result is served back as an ordinary `role: "user"` echo with no identity
//! anywhere on it. A consumer left to pair those by position is guessing —
//! and that is precisely how a generic aggregate placeholder ends up looking
//! like a tool result.
//!
//! `provider_call_response.parsed_tool_calls` cannot stand in either. It is
//! written when the provider replies, before the loop parses the turn, and on
//! a text-channel run it re-parses the same text against its own counter. Its
//! synthetic `tc_N` ids are a parallel id space that no result ever answers.
//!
//! So the two moments that actually know the answer record it: dispatch knows
//! the id a call ran under, and injection knows the message index a result
//! landed at. Together they make the sidecar self-describing on every channel.
//!
//! # Observability-only
//!
//! Like `resolved_dispatch`, nothing recorded here re-enters request
//! construction. The model's next-turn payload is byte-identical with or
//! without these events.

use crate::orchestration::{TOOL_CALL_RECEIPT_VERSION, TOOL_RESULT_RECEIPT_VERSION};
use crate::value::VmValue;
use serde::Serialize;

const SESSION_MESSAGE_FACTS_KEY: &str = "_harn";
const CALL_ROLE_KEY: &str = "_harn_call_role";
const CALL_STAGE_KEY: &str = "_harn_call_stage";

/// Dispatch observation is distinct from a legacy record with no observation.
/// Both unit variants serialize as null; the containing field omits Absent.
#[derive(Serialize)]
#[serde(untagged)]
enum CallStageObservation {
    Absent,
    Unset,
    Named(String),
}

impl CallStageObservation {
    fn is_absent(&self) -> bool {
        matches!(self, Self::Absent)
    }

    fn from_result(result: &VmValue) -> Self {
        match result
            .as_dict()
            .and_then(|result| result.get(CALL_STAGE_KEY))
        {
            None => Self::Absent,
            Some(VmValue::String(stage)) => Self::Named(stage.to_string()),
            Some(_) => Self::Unset,
        }
    }
}

#[derive(Serialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
enum SessionMessageFacts {
    Assistant {
        tool_calls: Vec<serde_json::Value>,
        effective_reasoning_effort: crate::llm::EffectiveReasoningEffort,
        #[serde(skip_serializing_if = "Option::is_none")]
        call_role: Option<String>,
        /// Explicit null is a dispatch-observed unset stage; absent metadata
        /// in an older record remains distinguishable from that observation.
        #[serde(skip_serializing_if = "CallStageObservation::is_absent")]
        call_stage: CallStageObservation,
    },
    ToolResult {
        tool_call_id: String,
        tool_name: String,
        outcome: ToolResultOutcome,
        /// Who authored this result. Omitted for the ordinary dispatch case, so
        /// every existing message is byte-identical and a reader that does not
        /// know the field behaves as it always did.
        #[serde(skip_serializing_if = "ToolResultOrigin::is_dispatch")]
        origin: ToolResultOrigin,
        #[serde(skip_serializing_if = "Option::is_none")]
        data: Option<serde_json::Value>,
    },
}

/// The normalized dispatch contract supplies provenance, never response prose.
pub(crate) fn attach_call_provenance(
    result: VmValue,
    call_role: &str,
    call_stage: Option<&str>,
) -> VmValue {
    let Some(dict) = result.as_dict() else {
        return result;
    };
    let mut dict = dict.clone();
    dict.insert(
        crate::value::intern_key(CALL_ROLE_KEY),
        VmValue::string(call_role),
    );
    dict.insert(
        crate::value::intern_key(CALL_STAGE_KEY),
        call_stage.map(VmValue::string).unwrap_or(VmValue::Nil),
    );
    VmValue::dict(dict)
}

#[derive(Serialize)]
#[serde(rename_all = "snake_case")]
enum ToolResultOutcome {
    Ok,
    Error,
}

/// Who produced a tool result.
///
/// A result the harness synthesized carries the ORIGINAL tool's name and call
/// id, because that is what pairs it to the orphaned `tool_use` block. Without
/// this field it is therefore indistinguishable from a real failed call of that
/// tool, and a completion authority reads the harness's own injected feedback
/// back as an observation of the workspace (harn#7757).
#[derive(Clone, Copy, Default, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub(crate) enum ToolResultOrigin {
    /// The tool ran and this is what it returned.
    #[default]
    Dispatch,
    /// The harness wrote this to close an orphaned `tool_use` block. Its
    /// content is injected harness feedback, not a tool observation.
    HarnessRepair,
}

impl ToolResultOrigin {
    fn is_dispatch(&self) -> bool {
        matches!(self, Self::Dispatch)
    }
}

fn attach_session_message_facts(message: VmValue, facts: &SessionMessageFacts) -> VmValue {
    let Some(existing) = message.as_dict() else {
        return message;
    };
    let mut enriched = existing.clone();
    let encoded = serde_json::to_value(facts).expect("session message facts must serialize");
    enriched.insert(
        crate::value::intern_key(SESSION_MESSAGE_FACTS_KEY),
        crate::stdlib::json_to_vm_value(&encoded),
    );
    VmValue::dict(enriched)
}

/// Attach provider-neutral parsed call facts to a durable assistant message.
/// The unified post-parse `tool_calls` list is authoritative; direct host
/// embeddings that supply only `native_tool_calls` retain those as a fallback.
/// Provider adapters strip `_harn` before egress, so transcript consumers read
/// one lifecycle shape without altering provider-visible history.
pub(crate) fn attach_assistant_facts(message: VmValue, llm_result: &VmValue) -> VmValue {
    let tool_calls = ["tool_calls", "native_tool_calls"]
        .iter()
        .find_map(|key| {
            llm_result
                .as_dict()
                .and_then(|result| result.get(*key))
                .and_then(|value| match value {
                    VmValue::List(items) if !items.is_empty() => Some(
                        items
                            .iter()
                            .map(crate::llm::helpers::vm_value_to_json)
                            .collect::<Vec<_>>(),
                    ),
                    _ => None,
                })
        })
        .unwrap_or_default();
    let effective_reasoning_effort = llm_result
        .as_dict()
        .and_then(|result| result.get("effective_reasoning_effort"))
        .and_then(|value| serde_json::from_value(crate::llm::helpers::vm_value_to_json(value)).ok())
        .unwrap_or_default();
    attach_session_message_facts(
        message,
        &SessionMessageFacts::Assistant {
            tool_calls,
            effective_reasoning_effort,
            call_role: llm_result
                .as_dict()
                .and_then(|result| result.get(CALL_ROLE_KEY))
                .and_then(|value| match value {
                    VmValue::String(role) => Some(role.to_string()),
                    _ => None,
                }),
            call_stage: CallStageObservation::from_result(llm_result),
        },
    )
}

/// Attach the dispatch-owned result identity and outcome to a durable result
/// message on every provider/tool-format channel.
pub(crate) fn attach_tool_result_facts(
    message: VmValue,
    tool_call_id: &str,
    tool_name: &str,
    ok: bool,
    data: Option<&VmValue>,
    origin: ToolResultOrigin,
) -> VmValue {
    attach_session_message_facts(
        message,
        &SessionMessageFacts::ToolResult {
            tool_call_id: tool_call_id.to_string(),
            tool_name: tool_name.to_string(),
            outcome: if ok {
                ToolResultOutcome::Ok
            } else {
                ToolResultOutcome::Error
            },
            origin,
            data: data.map(crate::llm::helpers::vm_value_to_json),
        },
    )
}

/// Record the calls a batch is about to dispatch, with the ids their results
/// will answer under.
///
/// Emitted before dispatch, so the receipts for one assistant turn appear in
/// the order the calls were requested even when the batch runs them
/// concurrently.
pub(crate) fn emit_tool_call_receipts(calls: &[VmValue]) {
    let Some(session_id) = crate::agent_sessions::current_session_id() else {
        return;
    };
    // The calls were parsed from the message just before the next slot, i.e.
    // the assistant turn this batch answers.
    let Some(next_index) = crate::agent_sessions::next_message_index(&session_id) else {
        return;
    };
    let assistant_message_index = next_index.saturating_sub(1);
    for call in calls {
        let call = crate::llm::helpers::vm_value_to_json(call);
        let mut fields = serde_json::Map::new();
        fields.insert(
            "schema_version".to_string(),
            serde_json::json!(TOOL_CALL_RECEIPT_VERSION),
        );
        fields.insert("session_id".to_string(), serde_json::json!(session_id));
        fields.insert(
            "assistant_message_index".to_string(),
            serde_json::json!(assistant_message_index),
        );
        fields.insert(
            "call_id".to_string(),
            serde_json::json!(string_field(&call, &["id", "tool_call_id"])),
        );
        fields.insert(
            "tool_name".to_string(),
            serde_json::json!(string_field(&call, &["name", "tool_name"])),
        );
        fields.insert(
            "arguments".to_string(),
            call.get("arguments")
                .or_else(|| call.get("tool_args"))
                .cloned()
                .unwrap_or_else(|| serde_json::Value::Object(serde_json::Map::new())),
        );
        crate::llm::append_observability_sidecar_entry("tool_call", fields);
    }
}

/// Record which call the message just injected answers.
///
/// `message_index` is the index [`crate::agent_sessions::inject_message`]
/// returned, which binds the receipt to one exact message instead of to
/// whatever event happens to follow it.
pub(crate) fn emit_tool_result_receipt(
    session_id: &str,
    message_index: usize,
    tool_call_id: &str,
    tool_name: &str,
    ok: bool,
    tool_format: &str,
) {
    let mut fields = serde_json::Map::new();
    fields.insert(
        "schema_version".to_string(),
        serde_json::json!(TOOL_RESULT_RECEIPT_VERSION),
    );
    fields.insert("session_id".to_string(), serde_json::json!(session_id));
    fields.insert(
        "message_index".to_string(),
        serde_json::json!(message_index),
    );
    fields.insert("call_id".to_string(), serde_json::json!(tool_call_id));
    fields.insert("tool_name".to_string(), serde_json::json!(tool_name));
    fields.insert("ok".to_string(), serde_json::json!(ok));
    fields.insert("tool_format".to_string(), serde_json::json!(tool_format));
    crate::llm::append_observability_sidecar_entry("tool_result", fields);
}

fn string_field(call: &serde_json::Value, keys: &[&str]) -> String {
    keys.iter()
        .find_map(|key| call.get(*key).and_then(serde_json::Value::as_str))
        .unwrap_or_default()
        .to_string()
}