locode_provider/
request.rs

1//! The API-agnostic request the engine hands to any [`Provider`](crate::Provider).
2
3use locode_protocol::{Message, ToolSpec};
4
5/// One provider-neutral sampling request (ADR-0007).
6///
7/// The loop builds exactly one of these and knows nothing about any wire. Per
8/// ADR-0013 there is **no separate `system` field** — `messages` carries the whole
9/// role-tagged stream (System/Developer included), and each wire hoists leading
10/// System messages into its own top-level slot (e.g. Anthropic's `system`).
11#[derive(Debug, Clone)]
12pub struct ConversationRequest {
13    /// The full role-tagged conversation stream (System/Developer/User/Assistant).
14    pub messages: Vec<Message>,
15    /// The tool specs offered to the model, mapped by the wire to its tool format.
16    pub tools: Vec<ToolSpec>,
17    /// Provider-neutral sampling knobs.
18    pub sampling_args: SamplingArgs,
19    /// A hint for where the wire should place prompt-cache breakpoints.
20    pub cache_hint: CacheHint,
21}
22
23/// Provider-neutral sampling knobs — the **common core** only.
24///
25/// Wire-specific parameters (Anthropic `top_k`/`stop_sequences`/thinking budget,
26/// OpenAI `frequency_penalty`, …) are the concern of each wire's request builder,
27/// not this type, keeping [`ConversationRequest`] API-agnostic (ADR-0007). Grok
28/// Build uses the same layering: a neutral core plus per-wire superset structs.
29#[derive(Debug, Clone, PartialEq)]
30pub struct SamplingArgs {
31    /// The maximum number of tokens to generate; see
32    /// [`DEFAULT_MAX_TOKENS`] for the default and why.
33    pub max_tokens: u32,
34    /// Sampling temperature; a wire may omit it (e.g. Anthropic requires temp=1
35    /// when thinking is on, so the wire drops it there).
36    pub temperature: Option<f32>,
37    /// Nucleus-sampling probability mass.
38    pub top_p: Option<f32>,
39    /// Neutral reasoning budget; each wire maps it to its own control
40    /// (Anthropic `budget_tokens`, OpenAI reasoning `effort`).
41    pub reasoning_effort: Option<ReasoningEffort>,
42}
43
44/// The default output-token budget for one sample.
45///
46/// A file-writing agent spends most of a turn inside one `tool_use` argument
47/// blob, so this is not a "typical reply length" knob — it is the ceiling on
48/// the largest single tool call the model can emit. Set it too low and the
49/// wire truncates mid-call: the API returns the `tool_use` block with an
50/// **empty** `input` (`{}`) and `stop_reason: "max_tokens"`, the typed decode
51/// then reports a missing required field, and the model retries the same
52/// oversized call forever. That is what 4096 did here.
53///
54/// 32k is the value the studied harnesses converge on for this tier. Claude
55/// Code resolves a per-model `{default, upperLimit}` pair
56/// (`utils/context.ts:149-208`) — 32k default for the sonnet-4-6 / 4.5
57/// families, 64k for opus-4-6 — and its 8k `CAPPED_DEFAULT_MAX_TOKENS`
58/// (`utils/context.ts:24`) is **not** the shipped default: it is gated on the
59/// `tengu_otk_slot_v1` slot-reservation experiment, which defaults to *false*
60/// off first-party (`services/api/claude.ts:3394-3397`), and is paired with a
61/// one-shot escalate to `ESCALATED_MAX_TOKENS = 64_000` on truncation. Codex
62/// never sends a sampling cap at all; Grok Build leaves `max_tokens: None`.
63/// Our own Responses wire already caps at 32k (`openai/mod.rs:119`), so this
64/// also stops the Anthropic wire being the odd one out.
65///
66/// A per-model table (Claude Code's shape) is the eventual answer; a single
67/// safe default is the honest v0 — every current Anthropic and OpenAI model
68/// this crate targets accepts 32k.
69pub const DEFAULT_MAX_TOKENS: u32 = 32_000;
70
71impl Default for SamplingArgs {
72    fn default() -> Self {
73        Self {
74            max_tokens: DEFAULT_MAX_TOKENS,
75            temperature: None,
76            top_p: None,
77            reasoning_effort: None,
78        }
79    }
80}
81
82/// A neutral reasoning-effort level, mapped per-wire (ADR-0007).
83///
84/// Grok Build proves this shape: one neutral enum with per-backend mappings
85/// (`to_messages_api()` → Anthropic budget, `to_responses_api()` → OpenAI effort).
86/// Tiers fragment per vendor/model generation (OpenAI `none…xhigh`, codex
87/// `minimal…xhigh`, grok stores per-model allowed-effort lists), so the ladder
88/// covers the observed union and `Other` passes vendor-specific strings
89/// through verbatim (ADR-0007 amendment 2026-07-19). Wires surface the API's
90/// own error on unsupported tiers — never silently clamp (silent clamping
91/// would corrupt eval comparisons).
92#[derive(Debug, Clone, PartialEq, Eq)]
93#[non_exhaustive]
94pub enum ReasoningEffort {
95    /// Explicitly send the wire's "none" (distinct from omitting the param —
96    /// `SamplingArgs.reasoning_effort: None` omits it entirely).
97    None,
98    /// Minimal reasoning.
99    Minimal,
100    /// Low reasoning effort.
101    Low,
102    /// Medium reasoning effort.
103    Medium,
104    /// High reasoning effort.
105    High,
106    /// Extra-high reasoning effort.
107    XHigh,
108    /// A vendor/model-specific tier, passed through verbatim by wires that
109    /// take effort strings; wires with fixed mappings soft-reject it.
110    Other(String),
111}
112
113/// Where the wire should place prompt-cache breakpoints (ADR-0007).
114///
115/// A reserved seam: the actual `cache_control` placement (Anthropic: one marker on
116/// the last message + ≤4 on system blocks) lives in the wire (Task 12).
117#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
118pub enum CacheHint {
119    /// No prompt caching.
120    Off,
121    /// Apply the wire's default breakpoint policy.
122    #[default]
123    Standard,
124}
locode_provider/request.rs

locode_provider/
request.rs
