polyc-llm 2026.7.1

//! Request-side LLM types: [`CompletionRequest`], [`Message`], [`Content`],
//! [`ToolSpec`], [`ToolChoice`], and [`JsonSchema`].

use serde::{Deserialize, Serialize};

// ── CompletionRequest ─────────────────────────────────────────────────────────

/// Top-level request to an LLM provider.
///
/// Construct via [`CompletionRequest::new`], then populate fields directly.
///
/// `#[non_exhaustive]`: provider-shaped sampling fields (`top_p`, `seed`, …)
/// will be added over time; build through [`new`](CompletionRequest::new) so
/// such additions stay non-breaking.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct CompletionRequest {
    /// The model identifier (e.g. `"fast-2"`, `"reasoning-pro"`).
    pub model: String,
    /// Optional system prompt text prepended before the conversation.
    pub system: Option<String>,
    /// Ordered list of messages in the conversation.
    pub messages: Vec<Message>,
    /// Tool definitions available to the model.
    pub tools: Vec<ToolSpec>,
    /// How the model should decide whether to call a tool.
    pub tool_choice: ToolChoice,
    /// When set, instructs the provider to return structured JSON output.
    pub response_format: Option<JsonSchema>,
    /// Maximum number of tokens the model may generate.
    pub max_tokens: Option<u32>,
    /// Sampling temperature in `[0.0, 2.0]`. Lower is more deterministic.
    pub temperature: Option<f32>,
    /// Token sequences that cause the model to stop generating.
    pub stop: Vec<String>,
    /// When `true`, the model may search the public web to ground its answer.
    ///
    /// This is a provider-agnostic capability hint: a provider maps it to its
    /// native mechanism (Vertex Gemini → the `googleSearch` grounding tool,
    /// alongside any `tools` function declarations) and a provider without web
    /// search ignores it. Defaults to `false`; the agent's answering loop
    /// (`run_turn`) sets it from its `RunTurnOptions.web_search`, so auxiliary
    /// calls (summarization, classification) that bypass that loop never offer
    /// search.
    pub web_search: bool,
    /// Provider-agnostic hint about caching the request's stable prefix.
    ///
    /// See [`CacheHint`]. Defaults to [`CacheHint::None`]; the agent's answering
    /// loop sets it from its `RunTurnOptions` so a multi-step turn can cache the
    /// system text + tool-spec block once and skip re-processing it each step.
    pub cache: CacheHint,
}

impl CompletionRequest {
    /// Creates a new request for the given `model` with sensible defaults:
    /// empty `messages`, `tools`, and `stop` lists; `tool_choice` set to
    /// [`ToolChoice::Auto`]; all optional fields `None`.
    #[must_use]
    pub fn new(model: impl Into<String>) -> Self {
        Self {
            model: model.into(),
            system: None,
            messages: Vec::new(),
            tools: Vec::new(),
            tool_choice: ToolChoice::Auto,
            response_format: None,
            max_tokens: None,
            temperature: None,
            stop: Vec::new(),
            web_search: false,
            cache: CacheHint::None,
        }
    }
}

// ── CacheHint ─────────────────────────────────────────────────────────────────

/// Provider-agnostic hint about caching a request's stable prefix.
///
/// A multi-step turn re-sends a growing conversation behind an unchanging
/// prefix — the system text plus the tool-spec block (built once per turn). This
/// hint marks that prefix as stable so a provider that supports prompt caching
/// can cache it and skip re-processing it on every step, the single biggest
/// latency lever on multi-step turns. It is purely advisory: a provider maps it
/// to its native mechanism, and a provider with no caching ignores it with no
/// behavior change.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum CacheHint {
    /// No caching is requested; a provider processes the full prompt on every
    /// call. The default so auxiliary calls that bypass the answering loop never
    /// opt in accidentally.
    #[default]
    None,
    /// The request's leading stable prefix (system text + tool-spec block) stays
    /// byte-identical across the steps of a turn — and across turns of a
    /// conversation — so a provider that supports prompt caching should cache it.
    StablePrefix {
        /// Optional stable per-conversation identifier a provider MAY use to pin
        /// cache routing (a provider maps it to its own cache-key field). A
        /// provider with only implicit prefix caching, or none at all, ignores
        /// it. `None` leaves routing to the provider's implicit prefix match.
        key: Option<String>,
    },
}

impl CacheHint {
    /// Reconstructs a hint from its flat single-string form: a non-empty `key`
    /// is a keyed [`CacheHint::StablePrefix`]; an empty one is
    /// [`CacheHint::None`]. The inverse of [`Self::key`] — together they carry
    /// the hint across a boundary that has one string field (the control-plane
    /// → harness turn input), which cannot express a keyless stable-prefix
    /// hint (the control plane always keys by conversation).
    #[must_use]
    pub fn from_key(key: String) -> Self {
        if key.is_empty() {
            Self::None
        } else {
            Self::StablePrefix { key: Some(key) }
        }
    }

    /// The cache-routing key this hint carries, if any. See [`Self::from_key`]
    /// for the flat form the pair round-trips.
    #[must_use]
    pub fn key(&self) -> Option<&str> {
        match self {
            Self::StablePrefix { key: Some(key) } => Some(key),
            _ => None,
        }
    }
}

// ── Message ───────────────────────────────────────────────────────────────────

/// A single turn in a conversation, composed of one or more [`Content`] parts.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Message {
    /// The participant that produced this message.
    pub role: Role,
    /// Ordered content blocks that make up the message body.
    pub content: Vec<Content>,
}

impl Message {
    /// Creates a [`Role::User`] message with a single [`Content::Text`] block.
    #[must_use]
    pub fn user(text: impl Into<String>) -> Self {
        Self {
            role: Role::User,
            content: vec![Content::Text(text.into())],
        }
    }

    /// Creates a [`Role::Assistant`] message with a single [`Content::Text`] block.
    #[must_use]
    pub fn assistant(text: impl Into<String>) -> Self {
        Self {
            role: Role::Assistant,
            content: vec![Content::Text(text.into())],
        }
    }

    /// Creates a [`Role::System`] message with a single [`Content::Text`] block.
    #[must_use]
    pub fn system(text: impl Into<String>) -> Self {
        Self {
            role: Role::System,
            content: vec![Content::Text(text.into())],
        }
    }
}

// ── Role ──────────────────────────────────────────────────────────────────────

/// The participant role for a [`Message`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum Role {
    /// A human turn.
    User,
    /// A model-generated turn.
    Assistant,
    /// A system-level instruction (not all providers support this as a role).
    System,
    /// A tool-result turn injected back into the conversation.
    Tool,
}

// ── Content ───────────────────────────────────────────────────────────────────

/// A single content block within a [`Message`].
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum Content {
    /// Plain text.
    Text(String),
    /// A tool invocation emitted by the model.
    ToolUse(ToolCall),
    /// The result of a prior [`Content::ToolUse`], fed back to the model.
    ToolResult(ToolResult),
    /// A reference to an image (HTTP URL or `data:` URI).
    Image(ImageRef),
}

impl Content {
    /// Wraps `s` in a [`Content::Text`] variant.
    #[must_use]
    pub fn text(s: impl Into<String>) -> Self {
        Self::Text(s.into())
    }

    /// Constructs a [`Content::ToolUse`] block.
    #[must_use]
    pub fn tool_use(
        id: impl Into<String>,
        name: impl Into<String>,
        args_json: impl Into<String>,
    ) -> Self {
        Self::ToolUse(ToolCall {
            id: id.into(),
            name: name.into(),
            args_json: args_json.into(),
            signature: None,
        })
    }

    /// Constructs a [`Content::ToolUse`] block carrying an opaque
    /// provider-specific `signature` (e.g. a thinking model's thought
    /// signature, which some providers require echoed back on the next
    /// request that includes this call).
    #[must_use]
    pub fn tool_use_signed(
        id: impl Into<String>,
        name: impl Into<String>,
        args_json: impl Into<String>,
        signature: Option<String>,
    ) -> Self {
        Self::ToolUse(ToolCall {
            id: id.into(),
            name: name.into(),
            args_json: args_json.into(),
            signature,
        })
    }

    /// Constructs a [`Content::ToolResult`] block.
    ///
    /// `first_party` is the ingestion-time provenance bit (see
    /// [`ToolResult::first_party`]) — pass the caller's already-computed
    /// verdict (the static per-tool-name check for an ordinary tool, or the
    /// worker-derived verdict for a `__delegate_to` result), not a fixed
    /// default: the whole point of carrying this on [`ToolResult`] is that
    /// the live same-turn taint scan needs the REAL per-call answer.
    #[must_use]
    pub fn tool_result(
        tool_call_id: impl Into<String>,
        result_json: impl Into<String>,
        is_error: bool,
        first_party: bool,
    ) -> Self {
        Self::ToolResult(ToolResult {
            tool_call_id: tool_call_id.into(),
            result_json: result_json.into(),
            is_error,
            first_party,
        })
    }

    /// Constructs a [`Content::Image`] block.
    #[must_use]
    pub fn image(url: impl Into<String>, mime_type: Option<String>) -> Self {
        Self::Image(ImageRef {
            url: url.into(),
            mime_type,
        })
    }
}

// ── ToolCall ──────────────────────────────────────────────────────────────────

/// A tool call emitted by the model inside an assistant [`Message`].
///
/// Mirrors the wire-side `polychrome.agent.v1.ToolCall`; surfaced inside a
/// [`Content::ToolUse`] block.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolCall {
    /// Provider-assigned call identifier, used to correlate with [`ToolResult`].
    pub id: String,
    /// Name of the tool being called.
    pub name: String,
    /// Arguments serialized as a JSON string (opaque at this layer).
    pub args_json: String,
    /// Opaque, provider-specific signature attached to this call (e.g. a
    /// thinking model's thought signature). Some providers require it to be
    /// echoed back verbatim on the follow-up request that carries this call
    /// in the history; `None` when the provider emits no such token.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub signature: Option<String>,
}

// ── ToolResult ────────────────────────────────────────────────────────────────

/// The result of executing a tool, fed back to the model as a [`Content`] block.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolResult {
    /// Matches the [`ToolCall::id`] this result corresponds to.
    pub tool_call_id: String,
    /// Serialized JSON payload returned by the tool executor.
    pub result_json: String,
    /// `true` when the tool raised an error rather than producing output.
    pub is_error: bool,
    /// Ingestion-time provenance: `true` when the producing tool is
    /// first-party and closed-domain (does not ingest untrusted open-world
    /// content). Mirrors `polyc_proto`'s wire `ToolResultContent.first_party`
    /// — this is the SAME bit, carried on the in-memory, provider-facing
    /// representation so the live same-turn taint scan
    /// (`untrusted_content_in_context`) reads a per-call signal instead of
    /// re-deriving it from the tool name. A `__delegate_to` call's result
    /// reflects what the delegated worker actually touched, not a static
    /// per-tool-name check — see `polyc_agent`'s `DelegateRecord::first_party`.
    pub first_party: bool,
}

// ── ImageRef ──────────────────────────────────────────────────────────────────

/// A reference to an image attached to a [`Message`].
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ImageRef {
    /// HTTP URL or `data:` URI for the image bytes.
    pub url: String,
    /// Optional MIME type hint (e.g. `"image/png"`).
    pub mime_type: Option<String>,
}

// ── ToolSpec ──────────────────────────────────────────────────────────────────

/// Declaration of a tool the model may invoke.
///
/// Mirrors the MCP `Tool` shape so built-in and connector tools are described
/// uniformly: `title` is the MCP `title` annotation, and `read_only` /
/// `destructive` / `open_world` are the `readOnlyHint` / `destructiveHint` /
/// `openWorldHint` annotations. Build with [`ToolSpec::new`] + the chainable
/// setters rather than a struct literal.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
// The flags are independent MCP-style annotation hints (each serialized as an
// optional bool); folding them into an enum/bitflags would fight serde's
// per-field optional-default model for no gain.
#[allow(clippy::struct_excessive_bools)]
pub struct ToolSpec {
    /// Unique tool name; the model references this when emitting a [`ToolCall`].
    pub name: String,
    /// Human-readable description of what the tool does.
    pub description: String,
    /// JSON Schema object describing the tool's argument shape.
    pub schema_json: serde_json::Value,
    /// MCP-style human display name for this tool (the `title` annotation):
    /// a friendly label shown to people (e.g. in an approval prompt) while the
    /// machine-facing [`name`](ToolSpec::name) stays the audit identifier.
    ///
    /// `None` means no curated label was provided; callers derive a display
    /// name from [`name`](ToolSpec::name) via `polyc_proto::humanize_tool_name`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    /// Intrinsic "this tool is side-effecting / requires human approval" flag.
    ///
    /// When `true` the tool must be routed through the harness's
    /// human-in-the-loop (HITL) approval gate before it executes, even when no
    /// operator-side allow-list names it. Pure, read-only tools leave this
    /// `false`.
    ///
    /// This is the per-tool generalization of the old hard-coded
    /// approval-by-name list: it maps from the MCP `destructiveHint` tool
    /// annotation, so an upstream connector that advertises a destructive tool
    /// is gated per-tool rather than per-connector.
    ///
    /// Defaults to `false` and is skipped when serializing the safe default, so
    /// older payloads that omit the field still deserialize as ungated.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub needs_approval: bool,
    /// MCP `readOnlyHint`: the tool does not modify its environment. Advisory —
    /// surfaced to the model and usable by callers (e.g. sandbox-mode gating
    /// never gates a read-only tool). Defaults to `false`.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub read_only: bool,
    /// MCP `destructiveHint`: the tool may perform irreversible / side-effecting
    /// changes. Drives sandbox-mode gating (destructive tools gate in read-only
    /// mode) and maps from a connector's `destructiveHint`. Defaults to `false`.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub destructive: bool,
    /// MCP `openWorldHint`: the tool may interact with an open world of external
    /// entities, so its RESULT can carry content of uncontrolled provenance. This
    /// is the INBOUND ("untrusted content in context") leg of the lethal
    /// trifecta — a tool with `open_world = true` seeds the leg when its result
    /// is in context (see `polyc_agent`'s `untrusted_content_in_context`). The
    /// built-in web fetchers set it; the sandbox coding tools do not. For a
    /// dialed connector it is read from `openWorldHint` at connect. Defaults to
    /// `false`.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub open_world: bool,
    /// Whether a single human approval for this tool may be *remembered* for the
    /// rest of a conversation session (per-caller) and reused for later calls,
    /// instead of re-prompting every time. Defaults to `false`.
    ///
    /// The session grant is **per-tool, not per-argument**: approving one call
    /// authorizes the tool for ANY arguments for the rest of the session. So set
    /// this ONLY when the tool's ENTIRE argument space is safe to auto-run within
    /// the sandbox boundary — i.e. it is both idempotent AND can't reach anything
    /// the human wouldn't have blanket-approved. `file_read` qualifies because it
    /// is workspace-confined (`coding::workspace::resolve` rejects absolute/`..`
    /// paths), so "approve one read" only ever grants reads inside the sandbox.
    /// NEVER set it on a tool that spends money, has side effects, or whose risk
    /// varies by argument (e.g. it could read/write outside a confined root):
    /// those must get a fresh decision per call.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub cacheable_approval: bool,
}

impl ToolSpec {
    /// A tool spec with the given `name`, `description`, and JSON-Schema
    /// `schema_json`; all annotations default off. Chain the setters below to
    /// add a title or mark it read-only / destructive / approval-gated.
    #[must_use]
    pub fn new(
        name: impl Into<String>,
        description: impl Into<String>,
        schema_json: serde_json::Value,
    ) -> Self {
        Self {
            name: name.into(),
            description: description.into(),
            schema_json,
            title: None,
            needs_approval: false,
            read_only: false,
            destructive: false,
            open_world: false,
            cacheable_approval: false,
        }
    }

    /// Set the MCP `title` display annotation.
    #[must_use]
    pub fn titled(mut self, title: impl Into<String>) -> Self {
        self.title = Some(title.into());
        self
    }

    /// Mark the tool read-only (MCP `readOnlyHint`).
    #[must_use]
    pub const fn read_only(mut self) -> Self {
        self.read_only = true;
        self
    }

    /// Mark the tool destructive (MCP `destructiveHint`).
    #[must_use]
    pub const fn destructive(mut self) -> Self {
        self.destructive = true;
        self
    }

    /// Mark the tool open-world (MCP `openWorldHint`): its result can carry
    /// content of uncontrolled provenance, seeding the untrusted-content leg.
    #[must_use]
    pub const fn open_world(mut self) -> Self {
        self.open_world = true;
        self
    }

    /// Mark a single approval for this tool as rememberable for the rest of a
    /// conversation session (per-caller). Only set this on idempotent tools (see
    /// [`Self::cacheable_approval`] field docs).
    #[must_use]
    pub const fn cacheable_approval(mut self) -> Self {
        self.cacheable_approval = true;
        self
    }

    /// Mark the tool as intrinsically requiring HITL approval (independent of
    /// sandbox mode — e.g. `paid_fetch`).
    #[must_use]
    pub const fn approval_required(mut self) -> Self {
        self.needs_approval = true;
        self
    }
}

/// The model-facing note appended to a gated tool's [`ToolSpec::description`]
/// (`#743`) so the tool is self-describing as propose-first.
///
/// The model stops guessing at approval/execution status, which the runtime —
/// never the model — owns and reports (the approval card, then the resume's
/// genuine result narration).
///
/// This lives here, in `polyc-llm`, rather than in `polyc-agent` or
/// `polyc-capability`, because the layer graph runs foundation ⇒ component:
/// `polyc-agent` composes the intrinsic [`ToolSpec::needs_approval`] flag with
/// the capability gate to decide WHICH specs are gated, then appends this
/// shared literal ONCE per turn at spec-pinning time — so every provider
/// builder that forwards [`ToolSpec::description`] verbatim carries the same
/// wording without either of them depending back down into this crate's
/// caller.
///
/// Per the project's copy rules: a complete, warm, plain sentence — no
/// vendor names, no internal jargon, no apology words.
pub const GATED_TOOL_APPROVAL_NOTE: &str = "Calling this pauses while a person reviews the \
    request — the system shows them what's pending and tells the user; don't describe approval \
    status yourself. A result from this tool means it was approved and has already run.";

// ── ToolChoice ────────────────────────────────────────────────────────────────

/// Controls whether and how the model calls tools.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ToolChoice {
    /// The model decides whether to call a tool (default).
    Auto,
    /// The model must not call any tool.
    None,
    /// The model must call at least one tool.
    Required,
    /// Force the model to call the named tool.
    Named(String),
}

// ── JsonSchema ────────────────────────────────────────────────────────────────

/// Wrapper for a response-format JSON Schema.
///
/// Instructs the provider to return structured output conforming to the schema.
/// Serializes transparently as the inner [`serde_json::Value`].
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(transparent)]
pub struct JsonSchema(
    /// The raw JSON Schema value.
    pub serde_json::Value,
);

// ── Tests ─────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    #![allow(clippy::pedantic, clippy::nursery, missing_docs)]

    use serde_json::{Value, json};

    use super::*;

    #[test]
    fn new_sets_model_and_defaults() {
        let req = CompletionRequest::new("fast-2");
        assert_eq!(req.model, "fast-2");
        assert!(req.messages.is_empty());
        assert!(req.tools.is_empty());
        assert!(req.stop.is_empty());
        assert!(req.system.is_none());
        assert!(req.max_tokens.is_none());
        assert!(req.temperature.is_none());
        assert!(req.response_format.is_none());
        assert_eq!(req.tool_choice, ToolChoice::Auto);
    }

    #[test]
    fn role_serializes_to_snake_case() {
        assert_eq!(serde_json::to_string(&Role::User).unwrap(), r#""user""#);
        assert_eq!(
            serde_json::to_string(&Role::Assistant).unwrap(),
            r#""assistant""#
        );
        assert_eq!(serde_json::to_string(&Role::System).unwrap(), r#""system""#);
        assert_eq!(serde_json::to_string(&Role::Tool).unwrap(), r#""tool""#);
    }

    #[test]
    fn role_round_trips() {
        for role in [Role::User, Role::Assistant, Role::System, Role::Tool] {
            let json = serde_json::to_string(&role).unwrap();
            let back: Role = serde_json::from_str(&json).unwrap();
            assert_eq!(back, role);
        }
    }

    #[test]
    fn tool_choice_unit_variants_serialize_as_strings() {
        assert_eq!(
            serde_json::to_string(&ToolChoice::Auto).unwrap(),
            r#""auto""#
        );
        assert_eq!(
            serde_json::to_string(&ToolChoice::None).unwrap(),
            r#""none""#
        );
        assert_eq!(
            serde_json::to_string(&ToolChoice::Required).unwrap(),
            r#""required""#
        );
    }

    #[test]
    fn tool_choice_named_serializes_as_object() {
        let tc = ToolChoice::Named("my_tool".to_owned());
        let v: Value = serde_json::to_value(&tc).unwrap();
        assert_eq!(v, json!({"named": "my_tool"}));
    }

    #[test]
    fn tool_choice_round_trips() {
        for tc in [
            ToolChoice::Auto,
            ToolChoice::None,
            ToolChoice::Required,
            ToolChoice::Named("search".to_owned()),
        ] {
            let json = serde_json::to_string(&tc).unwrap();
            let back: ToolChoice = serde_json::from_str(&json).unwrap();
            assert_eq!(back, tc);
        }
    }

    #[test]
    fn content_text_constructor() {
        let c = Content::text("hello");
        assert!(matches!(c, Content::Text(s) if s == "hello"));
    }

    #[test]
    fn content_tool_use_constructor() {
        let c = Content::tool_use("call-1", "search", r#"{"q":"rust"}"#);
        match c {
            Content::ToolUse(tu) => {
                assert_eq!(tu.id, "call-1");
                assert_eq!(tu.name, "search");
                assert_eq!(tu.args_json, r#"{"q":"rust"}"#);
            }
            _ => panic!("wrong variant"),
        }
    }

    #[test]
    fn content_tool_result_constructor() {
        let c = Content::tool_result("call-1", r#"{"result":"ok"}"#, false, true);
        match c {
            Content::ToolResult(tr) => {
                assert_eq!(tr.tool_call_id, "call-1");
                assert_eq!(tr.result_json, r#"{"result":"ok"}"#);
                assert!(!tr.is_error);
                assert!(tr.first_party);
            }
            _ => panic!("wrong variant"),
        }
    }

    #[test]
    fn content_image_constructor() {
        let c = Content::image("https://example.com/img.png", Some("image/png".to_owned()));
        match c {
            Content::Image(img) => {
                assert_eq!(img.url, "https://example.com/img.png");
                assert_eq!(img.mime_type.as_deref(), Some("image/png"));
            }
            _ => panic!("wrong variant"),
        }
    }

    #[test]
    fn message_user_constructor() {
        let m = Message::user("hi");
        assert_eq!(m.role, Role::User);
        assert_eq!(m.content.len(), 1);
        assert!(matches!(&m.content[0], Content::Text(s) if s == "hi"));
    }

    #[test]
    fn message_assistant_constructor() {
        let m = Message::assistant("hello back");
        assert_eq!(m.role, Role::Assistant);
        assert_eq!(m.content.len(), 1);
        assert!(matches!(&m.content[0], Content::Text(s) if s == "hello back"));
    }

    #[test]
    fn message_system_constructor() {
        let m = Message::system("You are helpful.");
        assert_eq!(m.role, Role::System);
        assert_eq!(m.content.len(), 1);
        assert!(matches!(&m.content[0], Content::Text(_)));
    }

    #[test]
    fn tool_use_args_json_preserved_as_opaque_string() {
        let original = r#"{"nested":{"key":42},"arr":[1,2,3]}"#;
        let c = Content::tool_use("id-42", "complex_tool", original);
        let serialized = serde_json::to_string(&c).unwrap();
        let back: Content = serde_json::from_str(&serialized).unwrap();
        match back {
            Content::ToolUse(tu) => assert_eq!(tu.args_json, original),
            _ => panic!("wrong variant"),
        }
    }

    #[test]
    fn completion_request_round_trips_all_content_variants() {
        let mut req = CompletionRequest::new("test-model");
        req.system = Some("Be concise.".to_owned());
        req.max_tokens = Some(256);
        req.temperature = Some(0.7);
        req.stop = vec!["<end>".to_owned()];
        req.tool_choice = ToolChoice::Named("calculator".to_owned());
        req.response_format = Some(JsonSchema(json!({"type": "object"})));
        req.tools = vec![ToolSpec::new(
            "calculator",
            "Evaluates math expressions.",
            json!({"type": "object", "properties": {"expr": {"type": "string"}}}),
        )];
        req.messages = vec![
            Message::user("Compute 2+2"),
            Message {
                role: Role::Assistant,
                content: vec![Content::tool_use(
                    "call-1",
                    "calculator",
                    r#"{"expr":"2+2"}"#,
                )],
            },
            Message {
                role: Role::Tool,
                content: vec![Content::tool_result(
                    "call-1",
                    r#"{"value":4}"#,
                    false,
                    true,
                )],
            },
            Message {
                role: Role::User,
                content: vec![Content::image(
                    "https://example.com/chart.png",
                    Some("image/png".to_owned()),
                )],
            },
        ];

        let json_str = serde_json::to_string(&req).unwrap();
        let back: CompletionRequest = serde_json::from_str(&json_str).unwrap();

        assert_eq!(back.model, "test-model");
        assert_eq!(back.system.as_deref(), Some("Be concise."));
        assert_eq!(back.max_tokens, Some(256));
        assert_eq!(back.messages.len(), 4);
        assert_eq!(back.tools.len(), 1);
        assert_eq!(back.tool_choice, ToolChoice::Named("calculator".to_owned()));
    }

    #[test]
    fn cache_hint_defaults_to_none_and_round_trips_on_the_request() {
        // A fresh request opts out of caching.
        assert_eq!(CompletionRequest::new("m").cache, CacheHint::None);

        // The stable-prefix hint (with a routing key) survives a serde round trip.
        let mut req = CompletionRequest::new("m");
        req.cache = CacheHint::StablePrefix {
            key: Some("conv-7".to_owned()),
        };
        let json_str = serde_json::to_string(&req).unwrap();
        let back: CompletionRequest = serde_json::from_str(&json_str).unwrap();
        assert_eq!(
            back.cache,
            CacheHint::StablePrefix {
                key: Some("conv-7".to_owned())
            }
        );
    }

    #[test]
    fn cache_hint_round_trips_through_its_flat_key_form() {
        // The single-string form the harness turn input carries: a non-empty
        // key is a keyed stable-prefix hint, an empty key is no hint.
        let keyed = CacheHint::StablePrefix {
            key: Some("conv-9".to_owned()),
        };
        assert_eq!(keyed.key(), Some("conv-9"));
        assert_eq!(CacheHint::from_key("conv-9".to_owned()), keyed);

        assert_eq!(CacheHint::None.key(), None);
        assert_eq!(CacheHint::from_key(String::new()), CacheHint::None);

        // The one lossy case, by design: a KEYLESS stable-prefix hint has no
        // flat form (the control plane always keys by conversation).
        assert_eq!((CacheHint::StablePrefix { key: None }).key(), None);
    }

    #[test]
    fn cache_hint_snake_case_wire_shape() {
        let hint = CacheHint::StablePrefix { key: None };
        let v: Value = serde_json::to_value(&hint).unwrap();
        assert_eq!(v, json!({"stable_prefix": {"key": null}}));
        assert_eq!(
            serde_json::to_value(CacheHint::None).unwrap(),
            json!("none")
        );
    }

    #[test]
    fn json_schema_serializes_transparently() {
        let schema = JsonSchema(json!({"type": "object", "required": ["name"]}));
        let v: Value = serde_json::to_value(&schema).unwrap();
        assert_eq!(v["type"], "object");
        assert_eq!(v["required"][0], "name");
    }

    #[test]
    fn json_schema_round_trips() {
        let inner = json!({"type": "string", "maxLength": 100});
        let schema = JsonSchema(inner.clone());
        let json_str = serde_json::to_string(&schema).unwrap();
        let back: JsonSchema = serde_json::from_str(&json_str).unwrap();
        assert_eq!(back.0, inner);
    }

    #[test]
    fn image_ref_default_is_sensible() {
        let img = ImageRef::default();
        assert!(img.url.is_empty());
        assert!(img.mime_type.is_none());
    }

    #[test]
    fn tool_spec_carries_optional_title() {
        let spec = ToolSpec::new("paid_fetch", "d", json!({})).titled("Pay for & fetch a web page");
        assert_eq!(spec.title.as_deref(), Some("Pay for & fetch a web page"));
    }

    #[test]
    fn tool_spec_carries_needs_approval_flag() {
        let spec = ToolSpec::new("delete_file", "d", json!({})).approval_required();
        assert!(spec.needs_approval);
    }

    /// `needs_approval` is `skip_serializing_if` false, so a non-gated spec
    /// omits the field on the wire; deserialization must read that absence back
    /// as `false` (the `#[serde(default)]` counterpart).
    #[test]
    fn tool_spec_needs_approval_defaults_false_on_deserialize() {
        let payload = json!({
            "name": "calculator",
            "description": "math",
            "schema_json": {"type": "object"}
        });
        let spec: ToolSpec = serde_json::from_value(payload).unwrap();
        assert!(
            !spec.needs_approval,
            "omitted needs_approval must default to false"
        );
    }

    /// `#743`: the shared gated-tool note is a complete, plain sentence that
    /// never leaks internal jargon or apology words — the same banned-word
    /// list every user-facing string in the project is checked against.
    #[test]
    fn gated_tool_approval_note_is_clean_user_facing_copy() {
        let lower = GATED_TOOL_APPROVAL_NOTE.to_lowercase();
        for banned in [
            "please",
            "sorry",
            "unfortunately",
            "operator",
            "sub-agent",
            "lethal-trifecta",
            "state-changing action",
        ] {
            assert!(
                !lower.contains(banned),
                "gated-tool note leaked banned word {banned:?}: {GATED_TOOL_APPROVAL_NOTE}"
            );
        }
        assert!(
            GATED_TOOL_APPROVAL_NOTE.contains("pauses"),
            "note must say the call pauses, not that it ran"
        );
        assert!(
            GATED_TOOL_APPROVAL_NOTE.contains("already run"),
            "note must say a result means the tool already ran"
        );
    }
}