Skip to main content

torana_plugin_sdk/
lib.rs

1//! Rust bindings and WASI Preview 1 trampolines for Torana Plugin ABI v1.
2//!
3//! The SDK deliberately exposes only the host calls granted by Torana. A
4//! plugin cannot gain a capability by importing a function that the operator
5//! did not grant.
6
7use core::alloc::Layout;
8use core::{ptr, slice};
9use prost::Message;
10mod capability_contract;
11mod http_binding;
12pub use http_binding::{http_conversation, HttpConversationBinding};
13
14#[cfg(not(target_arch = "wasm32"))]
15type NativeTransport = dyn Fn(&str, &[u8]) -> Result<Vec<u8>, HostCallError>;
16#[cfg(not(target_arch = "wasm32"))]
17thread_local! { static NATIVE_HOST: std::cell::RefCell<Option<Box<NativeTransport>>> = const { std::cell::RefCell::new(None) }; }
18thread_local! { static EXECUTION_CTX: std::cell::RefCell<Option<(u64, Option<pbv1::ExecutionInfo>)>> = const { std::cell::RefCell::new(None) }; }
19
20#[doc(hidden)]
21pub use prost;
22
23pub mod pbv1 {
24    include!(concat!(env!("OUT_DIR"), "/torana.v1.rs"));
25}
26
27/// Host observation for a plugin route verdict. The selected route and the
28/// eventual upstream can differ after failover.
29#[derive(Clone, Debug, PartialEq, serde::Deserialize)]
30pub struct RouteAppliedInfo {
31    pub provider: String,
32    pub model: String,
33    pub verdict_plugin: String,
34    pub refused: Option<String>,
35    pub served_by: String,
36    pub served_model: String,
37    pub failover: bool,
38    #[serde(default)]
39    pub effort: Option<String>,
40    #[serde(default)]
41    pub effort_status: Option<String>,
42}
43
44/// Read the optional host-owned route observation on an after-response hook.
45pub fn route_applied(response: &pbv1::ChatResponse) -> Result<Option<RouteAppliedInfo>, String> {
46    if response.torana_meta_json.is_empty() {
47        return Ok(None);
48    }
49    let object = strict_json(&response.torana_meta_json)
50        .map_err(|err| format!("route applied metadata: {err}"))?;
51    let Some(route) = object.get("_route_applied") else {
52        return Ok(None);
53    };
54    if !route.is_object() {
55        return Err("route applied metadata must be an object".into());
56    }
57    serde_json::from_value(route.clone())
58        .map(Some)
59        .map_err(|err| format!("route applied metadata: {err}"))
60}
61
62#[derive(Clone, Debug, PartialEq, serde::Deserialize)]
63pub struct SuggestionOutcome {
64    pub id: String,
65    pub status: String,
66    #[serde(default)]
67    pub action: String,
68    #[serde(default)]
69    pub via: String,
70}
71
72/// Read host-owned outcomes scoped to this plugin, never provider-visible.
73pub fn suggestions(request: &pbv1::ChatRequest) -> Result<Vec<SuggestionOutcome>, String> {
74    if request.torana_meta_json.is_empty() {
75        return Ok(Vec::new());
76    }
77    let object = strict_json(&request.torana_meta_json)
78        .map_err(|err| format!("suggestions metadata: {err}"))?;
79    let Some(raw) = object.get("_suggestions") else {
80        return Ok(Vec::new());
81    };
82    if !raw.is_array() {
83        return Err("suggestions metadata: must be an array".into());
84    }
85    let values: Vec<SuggestionOutcome> = serde_json::from_value(raw.clone())
86        .map_err(|err| format!("suggestions metadata: {err}"))?;
87    if values
88        .iter()
89        .any(|v| v.id.is_empty() || v.status.is_empty())
90    {
91        return Err("suggestion outcomes need id and status".into());
92    }
93    Ok(values)
94}
95
96/// Read the host's MCP-connection observation when one has been published.
97pub fn torana_mcp(request: &pbv1::ChatRequest) -> Result<Option<String>, String> {
98    if request.torana_meta_json.is_empty() {
99        return Ok(None);
100    }
101    let object =
102        strict_json(&request.torana_meta_json).map_err(|err| format!("MCP metadata: {err}"))?;
103    let Some(raw) = object.get("_torana_mcp") else {
104        return Ok(None);
105    };
106    let value = raw
107        .as_str()
108        .filter(|v| !v.is_empty())
109        .ok_or_else(|| "MCP metadata must be a non-empty string".to_owned())?;
110    Ok(Some(value.to_owned()))
111}
112
113/// Runtime ABI contract identifier. The high 32 bits are the ABI epoch and
114/// the low 32 bits are the contract revision within that epoch.
115pub const ABI_VERSION: u64 = (1u64 << 32) | 1;
116
117pub const fn abi_version() -> u64 {
118    ABI_VERSION
119}
120
121/// Error returned by an ABI-v1 host call.
122#[derive(Clone, Debug, PartialEq, Eq)]
123pub enum HostCallError {
124    /// The host refused the operation with a stable, machine-readable code.
125    Refused(pbv1::HostError),
126    /// The host returned a frame that violates the ABI-v1 result contract.
127    Protocol(String),
128}
129
130/// Installs a native transport for the duration of a test. The guard restores
131/// the previous transport on drop and storage is thread-local.
132pub struct NativeHostGuard {
133    #[cfg(not(target_arch = "wasm32"))]
134    previous: Option<Box<NativeTransport>>,
135}
136#[cfg(not(target_arch = "wasm32"))]
137pub fn install_native_host<F>(call: F) -> NativeHostGuard
138where
139    F: Fn(&str, &[u8]) -> Result<Vec<u8>, HostCallError> + 'static,
140{
141    let previous = NATIVE_HOST.with(|slot| slot.borrow_mut().replace(Box::new(call)));
142    NativeHostGuard { previous }
143}
144#[cfg(not(target_arch = "wasm32"))]
145impl Drop for NativeHostGuard {
146    fn drop(&mut self) {
147        NATIVE_HOST.with(|slot| *slot.borrow_mut() = self.previous.take());
148    }
149}
150
151pub fn pass_request() -> Option<pbv1::HookResult> {
152    None
153}
154pub fn pass_response() -> Option<pbv1::HookResult> {
155    None
156}
157pub fn pass_event() -> Option<pbv1::HookResult> {
158    None
159}
160pub fn pass_http() -> Option<pbv1::HookResult> {
161    None
162}
163pub fn pass_tick() -> Option<pbv1::HookResult> {
164    None
165}
166pub struct RequestResult(Option<pbv1::HookResult>);
167pub struct ResponseResult(Option<pbv1::HookResult>);
168pub struct StreamResult(Option<pbv1::HookResult>);
169pub struct HttpResult(Option<pbv1::HookResult>);
170pub struct TickResult(Option<pbv1::HookResult>);
171impl RequestResult {
172    pub fn pass() -> Self {
173        Self(None)
174    }
175    pub fn replace(r: pbv1::ChatRequest) -> Result<Self, String> {
176        Ok(Self(Some(replace_request(r)?)))
177    }
178    pub fn into_hook_result(self) -> Option<pbv1::HookResult> {
179        self.0
180    }
181}
182impl ResponseResult {
183    pub fn pass() -> Self {
184        Self(None)
185    }
186    pub fn replace(r: pbv1::ChatResponse) -> Result<Self, String> {
187        Ok(Self(Some(replace_response(r)?)))
188    }
189    pub fn into_hook_result(self) -> Option<pbv1::HookResult> {
190        self.0
191    }
192}
193impl StreamResult {
194    pub fn pass() -> Self {
195        Self(None)
196    }
197    pub fn suppress() -> Self {
198        Self(Some(pbv1::HookResult {
199            action: Some(pbv1::hook_result::Action::Suppress(pbv1::Suppress {})),
200        }))
201    }
202    pub fn emit(e: Vec<pbv1::StreamEvent>) -> Result<Self, String> {
203        Ok(Self(Some(emit_events(e)?)))
204    }
205    pub fn into_hook_result(self) -> Option<pbv1::HookResult> {
206        self.0
207    }
208}
209impl HttpResult {
210    pub fn pass() -> Self {
211        Self(None)
212    }
213    pub fn serve(r: pbv1::HttpResponse) -> Result<Self, String> {
214        Ok(Self(Some(serve_http(r)?)))
215    }
216    pub fn into_hook_result(self) -> Option<pbv1::HookResult> {
217        self.0
218    }
219}
220impl TickResult {
221    pub fn pass() -> Self {
222        Self(None)
223    }
224    pub fn outcome(actions: i32, note: impl Into<String>) -> Result<Self, String> {
225        Ok(Self(Some(tick_outcome(actions, note)?)))
226    }
227    pub fn into_hook_result(self) -> Option<pbv1::HookResult> {
228        self.0
229    }
230}
231
232/// Typed plugin callbacks cannot return another hook family's result:
233///
234/// ```compile_fail
235/// use torana_plugin_sdk::{Plugin, RequestResult, ResponseResult, pbv1};
236/// struct Wrong;
237/// impl Plugin for Wrong {
238///     const SUPPORTED_HOOKS: u32 = 1 << 2;
239///     fn after_response(_: pbv1::ChatResponse) -> Result<ResponseResult, String> {
240///         Ok(RequestResult::pass())
241///     }
242/// }
243/// ```
244pub trait Plugin {
245    const SUPPORTED_HOOKS: u32;
246    fn before_request(_: pbv1::ChatRequest) -> Result<RequestResult, String> {
247        Ok(RequestResult::pass())
248    }
249    fn after_response(_: pbv1::ChatResponse) -> Result<ResponseResult, String> {
250        Ok(ResponseResult::pass())
251    }
252    fn on_stream(_: pbv1::StreamEvent) -> Result<StreamResult, String> {
253        Ok(StreamResult::pass())
254    }
255    fn on_http(_: pbv1::HttpRequest) -> Result<HttpResult, String> {
256        Ok(HttpResult::pass())
257    }
258    fn on_tick(_: pbv1::TickRequest) -> Result<TickResult, String> {
259        Ok(TickResult::pass())
260    }
261}
262
263pub fn __plugin_dispatch<P: Plugin>(
264    input: pbv1::HookInput,
265) -> Result<Option<pbv1::HookResult>, String> {
266    match input.payload {
267        Some(pbv1::hook_input::Payload::ChatRequest(r)) => {
268            P::before_request(r).map(|x| x.into_hook_result())
269        }
270        Some(pbv1::hook_input::Payload::AfterResponse(r)) => {
271            P::after_response(r.response.ok_or("missing response")?).map(|x| x.into_hook_result())
272        }
273        Some(pbv1::hook_input::Payload::StreamEvent(e)) => {
274            P::on_stream(e).map(|x| x.into_hook_result())
275        }
276        Some(pbv1::hook_input::Payload::HttpRequest(r)) => {
277            P::on_http(r).map(|x| x.into_hook_result())
278        }
279        Some(pbv1::hook_input::Payload::TickRequest(r)) => {
280            P::on_tick(r).map(|x| x.into_hook_result())
281        }
282        None => Err("missing hook payload".into()),
283    }
284}
285
286pub fn replace_request(request: pbv1::ChatRequest) -> Result<pbv1::HookResult, String> {
287    validate_chat_request(&request)?;
288    Ok(pbv1::HookResult {
289        action: Some(pbv1::hook_result::Action::ReplaceRequest(request)),
290    })
291}
292
293pub fn set_text_at(message: &mut pbv1::Message, block: usize, text: &str) -> Result<(), String> {
294    let Some(slot) = message.blocks.get_mut(block) else {
295        return Err("text block index out of range".into());
296    };
297    let Some(pbv1::request_block::Kind::Text(t)) = slot.kind.as_mut() else {
298        return Err("block is not text".into());
299    };
300    if t.text != text {
301        t.text = text.into();
302        t.signature.clear();
303        if message.blocks.last().is_some_and(|b| {
304            matches!(
305                b.kind,
306                Some(pbv1::request_block::Kind::TrailingSignature(_))
307            )
308        }) {
309            message.blocks.pop();
310        }
311    }
312    Ok(())
313}
314pub fn replace_tool_result_text(
315    message: &mut pbv1::Message,
316    block: usize,
317    text: &str,
318) -> Result<bool, String> {
319    let Some(slot) = message.blocks.get_mut(block) else {
320        return Err("tool result index out of range".into());
321    };
322    let Some(pbv1::request_block::Kind::ToolResult(tr)) = slot.kind.as_mut() else {
323        return Err("block is not tool result".into());
324    };
325    let mut found = None;
326    for (i, c) in tr.content.iter().enumerate() {
327        match c.kind.as_ref() {
328            Some(pbv1::tool_result_content_block::Kind::Text(_)) if found.is_none() => {
329                found = Some(i)
330            }
331            Some(pbv1::tool_result_content_block::Kind::Text(_)) => {
332                return Err("multiple text arms".into())
333            }
334            Some(pbv1::tool_result_content_block::Kind::Unknown(_)) => {
335                return Err("unknown content arm".into())
336            }
337            Some(pbv1::tool_result_content_block::Kind::CacheBreakpoint(_)) => {}
338            None => return Err("empty content arm".into()),
339        }
340    }
341    let i = found.ok_or("tool result has no text")?;
342    let Some(pbv1::tool_result_content_block::Kind::Text(t)) = tr.content[i].kind.as_mut() else {
343        unreachable!()
344    };
345    if t.text == text {
346        return Ok(false);
347    }
348    t.text = text.into();
349    tr.signature.clear();
350    Ok(true)
351}
352
353/// Replaces a tool result with one safe text arm per cache-delimited segment
354/// and marks the result as an explicit tool error. Cache markers are preserved
355/// byte-for-byte and in their original relative order. Validation completes
356/// before mutation.
357pub fn replace_tool_result_with_error(
358    message: &mut pbv1::Message,
359    block: usize,
360    text: &str,
361) -> Result<bool, String> {
362    let Some(slot) = message.blocks.get_mut(block) else {
363        return Err("tool result index out of range".into());
364    };
365    let Some(pbv1::request_block::Kind::ToolResult(tr)) = slot.kind.as_mut() else {
366        return Err("block is not tool result".into());
367    };
368
369    let mut has_visible = false;
370    for content in &tr.content {
371        match content.kind.as_ref() {
372            Some(pbv1::tool_result_content_block::Kind::Text(_)) => {
373                has_visible = true;
374            }
375            Some(pbv1::tool_result_content_block::Kind::Unknown(unknown)) => {
376                json_object(&unknown.payload_json, "tool result unknown payload")?;
377                has_visible = true;
378            }
379            Some(pbv1::tool_result_content_block::Kind::CacheBreakpoint(marker)) => {
380                json_object(&marker.marker_json, "tool result cache marker")?;
381            }
382            None => return Err("empty content arm".into()),
383        }
384    }
385    if !has_visible {
386        return Err("tool result has no provider-visible content arm".into());
387    }
388
389    let mut replacement = Vec::with_capacity(tr.content.len());
390    let mut inserted_in_segment = false;
391    for content in &tr.content {
392        if matches!(
393            content.kind,
394            Some(pbv1::tool_result_content_block::Kind::CacheBreakpoint(_))
395        ) {
396            replacement.push(content.clone());
397            inserted_in_segment = false;
398        } else if !inserted_in_segment {
399            replacement.push(pbv1::ToolResultContentBlock {
400                kind: Some(pbv1::tool_result_content_block::Kind::Text(
401                    pbv1::ToolResultTextBlock { text: text.into() },
402                )),
403            });
404            inserted_in_segment = true;
405        }
406    }
407
408    let content_changed = tr.content != replacement;
409    let error_changed = tr.is_error != Some(true);
410    if content_changed {
411        tr.content = replacement;
412    }
413    if error_changed {
414        tr.is_error = Some(true);
415    }
416    if content_changed || error_changed {
417        tr.signature.clear();
418    }
419    Ok(content_changed || error_changed)
420}
421pub fn set_cache_breakpoint(
422    message: &mut pbv1::Message,
423    block: usize,
424    marker: &[u8],
425) -> Result<(), String> {
426    let Some(slot) = message.blocks.get_mut(block) else {
427        return Err("cache index out of range".into());
428    };
429    let Some(pbv1::request_block::Kind::CacheBreakpoint(c)) = slot.kind.as_mut() else {
430        return Err("block is not cache breakpoint".into());
431    };
432    json_object(marker, "marker_json")?;
433    c.marker_json = marker.to_vec();
434    Ok(())
435}
436pub fn move_cache_breakpoint(
437    message: &mut pbv1::Message,
438    from: usize,
439    to: usize,
440) -> Result<(), String> {
441    if from >= message.blocks.len() || to > message.blocks.len() {
442        return Err("cache breakpoint index out of range".into());
443    }
444    if !matches!(
445        message
446            .blocks
447            .get(from)
448            .and_then(|block| block.kind.as_ref()),
449        Some(pbv1::request_block::Kind::CacheBreakpoint(_))
450    ) {
451        return Err("block is not cache breakpoint".into());
452    }
453    let b = message.blocks.remove(from);
454    let at = if to > from { to - 1 } else { to };
455    message.blocks.insert(at, b);
456    Ok(())
457}
458pub fn replace_response(response: pbv1::ChatResponse) -> Result<pbv1::HookResult, String> {
459    validate_response(&response)?;
460    Ok(pbv1::HookResult {
461        action: Some(pbv1::hook_result::Action::ReplaceResponse(response)),
462    })
463}
464pub fn emit_events(events: Vec<pbv1::StreamEvent>) -> Result<pbv1::HookResult, String> {
465    if events.is_empty() {
466        return Err("torana sdk: emitted events cannot be empty".into());
467    }
468    Ok(pbv1::HookResult {
469        action: Some(pbv1::hook_result::Action::EmitEvents(pbv1::StreamEvents {
470            events,
471        })),
472    })
473}
474pub fn serve_http(response: pbv1::HttpResponse) -> Result<pbv1::HookResult, String> {
475    validate_action(&pbv1::hook_result::Action::ServeHttp(response.clone()))?;
476    Ok(pbv1::HookResult {
477        action: Some(pbv1::hook_result::Action::ServeHttp(response)),
478    })
479}
480pub fn tick_outcome(actions: i32, note: impl Into<String>) -> Result<pbv1::HookResult, String> {
481    if actions < 0 {
482        return Err("torana sdk: TickOutcome.actions cannot be negative".into());
483    }
484    Ok(pbv1::HookResult {
485        action: Some(pbv1::hook_result::Action::TickOutcome(pbv1::TickOutcome {
486            actions,
487            note: note.into(),
488        })),
489    })
490}
491
492impl core::fmt::Display for HostCallError {
493    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
494        match self {
495            Self::Refused(err) => write!(f, "host call refused ({})", err.code),
496            Self::Protocol(message) => f.write_str(message),
497        }
498    }
499}
500
501impl std::error::Error for HostCallError {}
502
503/// ABI-v1 hook bitmap bits. Bit N corresponds to `pbv1::Hook` value N.
504pub const HOOK_BEFORE_REQUEST: u32 = 1 << (pbv1::Hook::BeforeRequest as u32);
505pub const HOOK_AFTER_RESPONSE: u32 = 1 << (pbv1::Hook::AfterResponse as u32);
506pub const HOOK_ON_STREAM_CHUNK: u32 = 1 << (pbv1::Hook::OnStreamChunk as u32);
507pub const HOOK_ON_HTTP_REQUEST: u32 = 1 << (pbv1::Hook::OnHttpRequest as u32);
508pub const HOOK_ON_TICK: u32 = 1 << (pbv1::Hook::OnTick as u32);
509const ALL_V1_HOOKS: u32 = HOOK_BEFORE_REQUEST
510    | HOOK_AFTER_RESPONSE
511    | HOOK_ON_STREAM_CHUNK
512    | HOOK_ON_HTTP_REQUEST
513    | HOOK_ON_TICK;
514
515/// Returns the hook selected by a valid ABI-v1 input envelope.
516pub fn hook_of(input: &pbv1::HookInput) -> Result<pbv1::Hook, String> {
517    use pbv1::hook_input::Payload;
518    match input.payload.as_ref() {
519        Some(Payload::ChatRequest(_)) => Ok(pbv1::Hook::BeforeRequest),
520        Some(Payload::AfterResponse(_)) => Ok(pbv1::Hook::AfterResponse),
521        Some(Payload::StreamEvent(_)) => Ok(pbv1::Hook::OnStreamChunk),
522        Some(Payload::HttpRequest(_)) => Ok(pbv1::Hook::OnHttpRequest),
523        Some(Payload::TickRequest(_)) => Ok(pbv1::Hook::OnTick),
524        None => Err("torana sdk: HookInput requires a payload".to_owned()),
525    }
526}
527pub fn execution() -> Option<pbv1::ExecutionInfo> {
528    EXECUTION_CTX.with(|x| x.borrow().as_ref().and_then(|(_, e)| e.clone()))
529}
530pub fn request_id() -> Option<u64> {
531    EXECUTION_CTX.with(|x| x.borrow().as_ref().map(|(id, _)| *id))
532}
533
534struct ExecutionGuard(Option<(u64, Option<pbv1::ExecutionInfo>)>);
535impl ExecutionGuard {
536    fn enter(input: &pbv1::HookInput) -> Self {
537        let old = EXECUTION_CTX
538            .with(|slot| slot.replace(Some((input.request_id, input.execution.clone()))));
539        Self(old)
540    }
541}
542impl Drop for ExecutionGuard {
543    fn drop(&mut self) {
544        EXECUTION_CTX.with(|slot| {
545            slot.replace(self.0.take());
546        });
547    }
548}
549
550fn json_object(raw: &[u8], field: &str) -> Result<(), String> {
551    if raw.is_empty() {
552        return Ok(());
553    }
554    let value: serde_json::Value =
555        strict_json(raw).map_err(|e| format!("torana sdk: {field} is invalid JSON: {e}"))?;
556    if !value.is_object() {
557        return Err(format!("torana sdk: {field} must be a JSON object"));
558    }
559    Ok(())
560}
561fn json_array(raw: &[u8], field: &str) -> Result<(), String> {
562    if raw.is_empty() {
563        return Ok(());
564    }
565    let value: serde_json::Value =
566        strict_json(raw).map_err(|e| format!("torana sdk: {field} is invalid JSON: {e}"))?;
567    if !value.is_array() {
568        return Err(format!("torana sdk: {field} must be a JSON array"));
569    }
570    Ok(())
571}
572
573fn strict_json(raw: &[u8]) -> Result<serde_json::Value, serde_json::Error> {
574    use serde::de::{DeserializeSeed, Deserializer, MapAccess, SeqAccess, Visitor};
575    use std::{collections::HashSet, fmt};
576    struct V;
577    impl<'de> DeserializeSeed<'de> for V {
578        type Value = serde_json::Value;
579        fn deserialize<D: Deserializer<'de>>(self, d: D) -> Result<Self::Value, D::Error> {
580            d.deserialize_any(V)
581        }
582    }
583    impl<'de> Visitor<'de> for V {
584        type Value = serde_json::Value;
585        fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
586            f.write_str("JSON value")
587        }
588        fn visit_map<A: MapAccess<'de>>(self, mut a: A) -> Result<Self::Value, A::Error> {
589            let mut m = serde_json::Map::new();
590            let mut keys = HashSet::new();
591            while let Some(k) = a.next_key::<String>()? {
592                if !keys.insert(k.clone()) {
593                    return Err(serde::de::Error::custom("duplicate JSON key"));
594                }
595                m.insert(k, a.next_value_seed(V)?);
596            }
597            Ok(serde_json::Value::Object(m))
598        }
599        fn visit_seq<A: SeqAccess<'de>>(self, mut a: A) -> Result<Self::Value, A::Error> {
600            let mut v = Vec::new();
601            while let Some(x) = a.next_element_seed(V)? {
602                v.push(x);
603            }
604            Ok(serde_json::Value::Array(v))
605        }
606        fn visit_bool<E: serde::de::Error>(self, v: bool) -> Result<Self::Value, E> {
607            Ok(serde_json::Value::Bool(v))
608        }
609        fn visit_i64<E: serde::de::Error>(self, v: i64) -> Result<Self::Value, E> {
610            Ok(serde_json::Value::Number(v.into()))
611        }
612        fn visit_u64<E: serde::de::Error>(self, v: u64) -> Result<Self::Value, E> {
613            Ok(serde_json::Value::Number(v.into()))
614        }
615        fn visit_f64<E: serde::de::Error>(self, v: f64) -> Result<Self::Value, E> {
616            serde_json::Number::from_f64(v)
617                .map(serde_json::Value::Number)
618                .ok_or_else(|| E::custom("non-finite number"))
619        }
620        fn visit_str<E: serde::de::Error>(self, v: &str) -> Result<Self::Value, E> {
621            Ok(serde_json::Value::String(v.into()))
622        }
623        fn visit_string<E: serde::de::Error>(self, v: String) -> Result<Self::Value, E> {
624            Ok(serde_json::Value::String(v))
625        }
626        fn visit_none<E: serde::de::Error>(self) -> Result<Self::Value, E> {
627            Ok(serde_json::Value::Null)
628        }
629        fn visit_unit<E: serde::de::Error>(self) -> Result<Self::Value, E> {
630            Ok(serde_json::Value::Null)
631        }
632    }
633    let mut d = serde_json::Deserializer::from_slice(raw);
634    let v = d.deserialize_any(V)?;
635    d.end()?;
636    Ok(v)
637}
638
639/* fn strict_json(raw: &[u8]) -> Result<serde_json::Value, serde_json::Error> {
640    use serde::de::{Deserialize, DeserializeSeed, MapAccess, SeqAccess, Visitor};
641    use std::{collections::HashSet, fmt};
642    struct V;
643    impl<'de> Visitor<'de> for V {
644        type Value = serde_json::Value;
645        fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
646            f.write_str("JSON value")
647        }
648        fn visit_map<A: MapAccess<'de>>(self, mut a: A) -> Result<Self::Value, A::Error> {
649            let mut m = serde_json::Map::new();
650            let mut keys = HashSet::new();
651            while let Some(k) = a.next_key::<String>()? {
652                if !keys.insert(k.clone()) {
653                    return Err(serde::de::Error::custom("duplicate JSON key"));
654                }
655                m.insert(k, a.next_value_seed(V)?);
656            }
657            Ok(serde_json::Value::Object(m))
658        }
659        fn visit_seq<A: SeqAccess<'de>>(self, mut a: A) -> Result<Self::Value, A::Error> {
660            let mut v = Vec::new();
661            while let Some(x) = a.next_element_seed(V)? {
662                v.push(x);
663            }
664            Ok(serde_json::Value::Array(v))
665        }
666        fn visit_bool<E: serde::de::Error>(self, v: bool) -> Result<Self::Value, E> {
667            Ok(serde_json::Value::Bool(v))
668        }
669        fn visit_i64<E: serde::de::Error>(self, v: i64) -> Result<Self::Value, E> {
670            Ok(serde_json::Value::Number(v.into()))
671        }
672        fn visit_u64<E: serde::de::Error>(self, v: u64) -> Result<Self::Value, E> {
673            Ok(serde_json::Value::Number(v.into()))
674        }
675        fn visit_f64<E: serde::de::Error>(self, v: f64) -> Result<Self::Value, E> {
676            serde_json::Number::from_f64(v)
677                .map(serde_json::Value::Number)
678                .ok_or_else(|| E::custom("non-finite number"))
679        }
680        fn visit_str<E: serde::de::Error>(self, v: &str) -> Result<Self::Value, E> {
681            Ok(serde_json::Value::String(v.into()))
682        }
683        fn visit_string<E: serde::de::Error>(self, v: String) -> Result<Self::Value, E> {
684            Ok(serde_json::Value::String(v))
685        }
686        fn visit_none<E: serde::de::Error>(self) -> Result<Self::Value, E> {
687            Ok(serde_json::Value::Null)
688        }
689        fn visit_unit<E: serde::de::Error>(self) -> Result<Self::Value, E> {
690            Ok(serde_json::Value::Null)
691        }
692    }
693    let mut d = serde_json::Deserializer::from_slice(raw);
694    let v = V.deserialize(&mut d)?;
695    d.end()?;
696    Ok(v)
697} */
698
699fn validate_chat_request(request: &pbv1::ChatRequest) -> Result<(), String> {
700    if request.max_tokens.is_some_and(|v| v <= 0)
701        || request.temperature.is_some_and(|v| !v.is_finite())
702        || request.top_p.is_some_and(|v| !v.is_finite())
703    {
704        return Err("torana sdk: ChatRequest numeric fields are invalid".into());
705    }
706    for (i, message) in request.messages.iter().enumerate() {
707        if message.role.is_empty() {
708            return Err(format!("torana sdk: message {i} role is required"));
709        }
710        if message.blocks.is_empty() {
711            return Err(format!("torana sdk: message {i} requires blocks"));
712        }
713        for block in &message.blocks {
714            let Some(kind) = block.kind.as_ref() else {
715                return Err(format!("torana sdk: message {i} contains an empty block"));
716            };
717            match kind {
718                pbv1::request_block::Kind::ToolUse(t) => {
719                    if t.id.is_empty() || t.name.is_empty() {
720                        return Err("torana sdk: tool use id/name required".into());
721                    }
722                    if !matches!(t.invocation_kind, x if x == pbv1::ToolInvocationKind::Function as i32 || x == pbv1::ToolInvocationKind::Freeform as i32)
723                    {
724                        return Err("torana sdk: invalid tool invocation kind".into());
725                    }
726                    match t.invocation_kind {
727                        x if x == pbv1::ToolInvocationKind::Function as i32 => {
728                            if t.arguments_json.is_empty() || t.input_text.is_some() {
729                                return Err("torana sdk: invalid function tool input".into());
730                            }
731                            json_object(&t.arguments_json, "arguments_json")?;
732                        }
733                        _ => {
734                            if t.input_text.is_none() || !t.arguments_json.is_empty() {
735                                return Err("torana sdk: invalid freeform tool input".into());
736                            }
737                        }
738                    }
739                    json_object(&t.part_metadata_json, "part_metadata_json")?;
740                }
741                pbv1::request_block::Kind::ToolResult(t) => {
742                    if t.tool_call_id.is_empty()
743                        || t.content.is_empty()
744                        || t.content.iter().any(|x| x.kind.is_none())
745                    {
746                        return Err("torana sdk: invalid tool result".into());
747                    }
748                }
749                pbv1::request_block::Kind::CacheBreakpoint(t) => {
750                    if t.marker_json.is_empty() {
751                        return Err("torana sdk: cache marker required".into());
752                    }
753                    json_object(&t.marker_json, "marker_json")?;
754                }
755                pbv1::request_block::Kind::Unknown(t) => {
756                    if t.kind.is_empty() || t.payload_json.is_empty() {
757                        return Err("torana sdk: unknown block requires kind and payload".into());
758                    }
759                    json_object(&t.payload_json, "payload_json")?;
760                }
761                pbv1::request_block::Kind::TrailingSignature(t) if t.signature.is_empty() => {
762                    return Err("torana sdk: trailing signature required".into())
763                }
764                _ => {}
765            }
766        }
767    }
768    json_object(
769        &request.provider_extensions_json,
770        "provider_extensions_json",
771    )?;
772    json_array(&request.safety_settings_json, "safety_settings_json")?;
773    if let Some(format) = request.output_format.as_ref() {
774        match format.mode {
775            0 | 1 => {
776                if !format.name.is_empty()
777                    || !format.schema_json.is_empty()
778                    || format.strict.is_some()
779                {
780                    return Err(
781                        "torana sdk: text/object output format carries schema options".into(),
782                    );
783                }
784            }
785            2 => {
786                if format.name.is_empty() {
787                    return Err("torana sdk: JSON schema output requires a name".into());
788                }
789                json_object(&format.schema_json, "output_format.schema_json")?;
790            }
791            _ => return Err("torana sdk: unknown output format mode".into()),
792        }
793    }
794    Ok(())
795}
796
797fn validate_response(response: &pbv1::ChatResponse) -> Result<(), String> {
798    if let Some(message) = response.message.as_ref() {
799        if message.blocks.iter().any(|b| b.kind.is_none()) {
800            return Err("torana sdk: response contains an empty block".into());
801        }
802    }
803    json_object(
804        &response.provider_extensions_json,
805        "provider_extensions_json",
806    )
807}
808
809fn validate_input(input: &pbv1::HookInput, raw: &[u8]) -> Result<(), String> {
810    __validate_wire_message(raw, ".torana.v1.HookInput")?;
811    if input.contract_revision != 1 {
812        return Err(format!(
813            "torana sdk: unsupported contract revision {}",
814            input.contract_revision
815        ));
816    }
817    match input.payload.as_ref() {
818        Some(pbv1::hook_input::Payload::ChatRequest(r)) => validate_chat_request(r),
819        Some(pbv1::hook_input::Payload::AfterResponse(r)) => {
820            let response = r
821                .response
822                .as_ref()
823                .ok_or("torana sdk: AfterResponse.response is required")?;
824            validate_response(response)
825        }
826        Some(pbv1::hook_input::Payload::HttpRequest(r)) => {
827            json_object(&r.headers_json, "HttpRequest.headers_json")
828        }
829        Some(pbv1::hook_input::Payload::StreamEvent(event)) => validate_stream_event(event),
830        Some(pbv1::hook_input::Payload::TickRequest(_)) => Ok(()),
831        None => Err("torana sdk: HookInput requires a payload".into()),
832    }
833}
834
835fn validate_stream_event(event: &pbv1::StreamEvent) -> Result<(), String> {
836    use pbv1::stream_event::Event;
837    match event.event.as_ref() {
838        None => Err("torana sdk: stream event carries no event".into()),
839        Some(Event::ToolCallDelta(delta)) => {
840            if delta.index < 0 {
841                Err("torana sdk: tool call delta index must be non-negative".into())
842            } else if delta.input_text_delta.is_some() && !delta.arguments_delta.is_empty() {
843                Err("torana sdk: tool call delta cannot carry both argument forms".into())
844            } else {
845                Ok(())
846            }
847        }
848        Some(Event::ContentBlockStart(start)) => {
849            if start.index < 0 || start.block.is_none() {
850                return Err(
851                    "torana sdk: content block start requires non-negative index and block".into(),
852                );
853            }
854            if let Some(pbv1::content_block_start::Block::ToolCall(call)) = start.block.as_ref() {
855                if call.id.is_empty() || call.name.is_empty() {
856                    return Err("torana sdk: tool call start requires id and name".into());
857                }
858                if !matches!(call.invocation_kind, 0 | 1) {
859                    return Err("torana sdk: invalid tool invocation kind".into());
860                }
861            }
862            if let Some(pbv1::content_block_start::Block::Provider(provider)) = start.block.as_ref()
863            {
864                if provider.kind.is_empty() {
865                    return Err("torana sdk: provider block kind is required".into());
866                }
867            }
868            Ok(())
869        }
870        Some(Event::ContentBlockStop(stop)) if stop.index < 0 => {
871            Err("torana sdk: content block stop index must be non-negative".into())
872        }
873        Some(_) => Ok(()),
874    }
875}
876
877#[doc(hidden)]
878pub fn __validate_stream_event(bytes: &[u8]) -> Result<(), String> {
879    __validate_wire_message(bytes, ".torana.v1.StreamEvent")?;
880    let event = pbv1::StreamEvent::decode(bytes)
881        .map_err(|error| format!("torana sdk: decode StreamEvent: {error}"))?;
882    validate_stream_event(&event)
883}
884
885#[doc(hidden)]
886pub fn __validate_wire_message(bytes: &[u8], name: &str) -> Result<(), String> {
887    use prost::Message;
888    use prost_types::FileDescriptorSet;
889    static SET: std::sync::OnceLock<Result<FileDescriptorSet, String>> = std::sync::OnceLock::new();
890    let set = SET
891        .get_or_init(|| {
892            FileDescriptorSet::decode(
893                include_bytes!(concat!(env!("OUT_DIR"), "/torana.descriptor.bin")).as_slice(),
894            )
895            .map_err(|e| format!("torana sdk: descriptor decode: {e}"))
896        })
897        .as_ref()
898        .map_err(Clone::clone)?;
899    validate_wire_message_with_set(bytes, name, set, 1)
900}
901
902fn validate_wire_message_with_set(
903    mut bytes: &[u8],
904    name: &str,
905    set: &prost_types::FileDescriptorSet,
906    depth: usize,
907) -> Result<(), String> {
908    use prost_types::field_descriptor_proto::{Label, Type};
909    // Keep validation bounded if a future schema introduces a recursive
910    // message edge. The root message counts as depth one.
911    if depth > 100 {
912        return Err("torana sdk: protobuf message nesting exceeds 100".into());
913    }
914    let descriptor = set
915        .file
916        .iter()
917        .find_map(|f| {
918            let prefix = f
919                .package
920                .as_deref()
921                .map(|p| format!(".{p}."))
922                .unwrap_or_else(|| ".".into());
923            f.message_type
924                .iter()
925                .find(|m| format!("{}{}", prefix, m.name.as_deref().unwrap_or("")) == name)
926        })
927        .ok_or_else(|| format!("torana sdk: unknown message descriptor {name}"))?;
928    let mut seen_oneof = std::collections::HashSet::new();
929    let mut seen_singular = std::collections::HashSet::new();
930    while !bytes.is_empty() {
931        let (key, n) = read_varint_raw(bytes)?;
932        bytes = &bytes[n..];
933        let number = i32::try_from(key >> 3).map_err(|_| "torana sdk: field number overflow")?;
934        let wire = key & 7;
935        let field = descriptor
936            .field
937            .iter()
938            .find(|f| f.number == Some(number))
939            .ok_or_else(|| format!("torana sdk: unknown field {number} in {name}"))?;
940        if field.label.and_then(|label| Label::try_from(label).ok()) != Some(Label::Repeated)
941            && !seen_singular.insert(number)
942        {
943            return Err(format!("torana sdk: duplicate field {number} in {name}"));
944        }
945        let field_type = field.r#type.and_then(|value| Type::try_from(value).ok());
946        let expected = match field_type {
947            Some(Type::Double) | Some(Type::Fixed64) | Some(Type::Sfixed64) => 1,
948            Some(Type::Float) | Some(Type::Fixed32) | Some(Type::Sfixed32) => 5,
949            Some(Type::Int32) | Some(Type::Sint32) | Some(Type::Int64) | Some(Type::Sint64)
950            | Some(Type::Uint32) | Some(Type::Uint64) | Some(Type::Bool) | Some(Type::Enum) => 0,
951            _ => 2,
952        };
953        let repeated =
954            field.label.and_then(|label| Label::try_from(label).ok()) == Some(Label::Repeated);
955        let packable = repeated && matches!(expected, 0 | 1 | 5);
956        if !accepts_wire_type(repeated, expected, wire) {
957            return Err(format!(
958                "torana sdk: field {number} in {name} has wrong wire type"
959            ));
960        }
961        if let Some(index) = field.oneof_index {
962            if !seen_oneof.insert(index) {
963                return Err(format!("torana sdk: duplicate oneof arm in {name}"));
964            }
965        }
966        if wire == 2 {
967            let (len, p) = read_varint_raw(bytes)?;
968            let len = usize::try_from(len).map_err(|_| "torana sdk: length overflow")?;
969            if p.checked_add(len).ok_or("torana sdk: length overflow")? > bytes.len() {
970                return Err("torana sdk: truncated nested field".into());
971            }
972            if packable {
973                validate_packed_field(&bytes[p..p + len], expected)?;
974            } else if field_type == Some(Type::Message) {
975                let ty = field.type_name.as_deref().ok_or_else(|| {
976                    format!("torana sdk: message field {number} in {name} has no type")
977                })?;
978                validate_wire_message_with_set(&bytes[p..p + len], ty, set, depth + 1)?;
979            }
980        }
981        let consumed = skip_wire(bytes, wire)?;
982        bytes = &bytes[consumed..];
983    }
984    Ok(())
985}
986
987fn accepts_wire_type(repeated: bool, scalar_wire: u64, actual_wire: u64) -> bool {
988    actual_wire == scalar_wire || (repeated && matches!(scalar_wire, 0 | 1 | 5) && actual_wire == 2)
989}
990
991fn validate_packed_field(mut bytes: &[u8], element_wire: u64) -> Result<(), String> {
992    while !bytes.is_empty() {
993        let consumed = skip_wire(bytes, element_wire)?;
994        bytes = &bytes[consumed..];
995    }
996    Ok(())
997}
998
999fn validate_action(action: &pbv1::hook_result::Action) -> Result<(), String> {
1000    match action {
1001        pbv1::hook_result::Action::ReplaceRequest(r) => validate_chat_request(r),
1002        pbv1::hook_result::Action::ReplaceResponse(r) => validate_response(r),
1003        pbv1::hook_result::Action::ServeHttp(r) => {
1004            if !(200..=599).contains(&r.status) {
1005                return Err("torana sdk: HttpResponse.status must be 200..=599".into());
1006            }
1007            if matches!(r.status, 204 | 205 | 304) && !r.body.is_empty() {
1008                return Err("torana sdk: status forbids a response body".into());
1009            }
1010            json_object(&r.headers_json, "HttpResponse.headers_json")
1011        }
1012        pbv1::hook_result::Action::TickOutcome(r) if r.actions < 0 => {
1013            Err("torana sdk: TickOutcome.actions cannot be negative".into())
1014        }
1015        pbv1::hook_result::Action::EmitEvents(r) if r.events.is_empty() => {
1016            Err("torana sdk: emitted events cannot be empty".into())
1017        }
1018        pbv1::hook_result::Action::EmitEvents(r) => {
1019            if r.events.iter().any(|event| event.event.is_none()) {
1020                return Err("torana sdk: emitted event requires an event arm".into());
1021            }
1022            Ok(())
1023        }
1024        _ => Ok(()),
1025    }
1026}
1027
1028fn read_varint_raw(bytes: &[u8]) -> Result<(u64, usize), String> {
1029    for i in 0..10 {
1030        let b = *bytes.get(i).ok_or("torana sdk: truncated protobuf")?;
1031        if i == 9 && b > 1 {
1032            break;
1033        }
1034        if b & 0x80 == 0 {
1035            let mut v = 0;
1036            for (j, x) in bytes[..=i].iter().enumerate() {
1037                v |= u64::from(x & 0x7f) << (j * 7);
1038            }
1039            return Ok((v, i + 1));
1040        }
1041    }
1042    Err("torana sdk: invalid protobuf varint".into())
1043}
1044fn skip_wire(bytes: &[u8], wire: u64) -> Result<usize, String> {
1045    match wire {
1046        0 => Ok(read_varint_raw(bytes)?.1),
1047        1 => {
1048            if bytes.len() >= 8 {
1049                Ok(8)
1050            } else {
1051                Err("torana sdk: truncated fixed64".into())
1052            }
1053        }
1054        2 => {
1055            let (n, m) = read_varint_raw(bytes)?;
1056            let n = usize::try_from(n).map_err(|_| "torana sdk: length overflow")?;
1057            if bytes.len() - m < n {
1058                Err("torana sdk: truncated bytes".into())
1059            } else {
1060                Ok(m + n)
1061            }
1062        }
1063        5 => {
1064            if bytes.len() >= 4 {
1065                Ok(4)
1066            } else {
1067                Err("torana sdk: truncated fixed32".into())
1068            }
1069        }
1070        _ => Err("torana sdk: unsupported protobuf wire type".into()),
1071    }
1072}
1073
1074fn validate_hook_result(hook: pbv1::Hook, result: &pbv1::HookResult) -> Result<(), String> {
1075    use pbv1::hook_result::Action;
1076    let valid = matches!(
1077        (hook, result.action.as_ref()),
1078        (pbv1::Hook::BeforeRequest, Some(Action::ReplaceRequest(_)))
1079            | (pbv1::Hook::AfterResponse, Some(Action::ReplaceResponse(_)))
1080            | (pbv1::Hook::OnStreamChunk, Some(Action::EmitEvents(_)))
1081            | (pbv1::Hook::OnStreamChunk, Some(Action::Suppress(_)))
1082            | (pbv1::Hook::OnHttpRequest, Some(Action::ServeHttp(_)))
1083            | (pbv1::Hook::OnTick, Some(Action::TickOutcome(_)))
1084    );
1085    if valid {
1086        Ok(())
1087    } else {
1088        Err(format!(
1089            "torana sdk: HookResult action does not match {}",
1090            hook.as_str_name()
1091        ))
1092    }
1093}
1094
1095/// Decodes, dispatches, validates, and encodes one ABI-v1 hook invocation.
1096///
1097/// Returning `Ok(None)` from `handler` is the sole pass-through representation.
1098/// This ordinary Rust function owns the contract logic so it is testable off
1099/// WASM; [`export_plugin_v1!`] only supplies the two required exports.
1100#[doc(hidden)]
1101pub fn __dispatch_v1<E: core::fmt::Display>(
1102    input_bytes: &[u8],
1103    hooks: u32,
1104    handler: fn(pbv1::HookInput) -> Result<Option<pbv1::HookResult>, E>,
1105) -> Result<Vec<u8>, String> {
1106    use prost::Message;
1107
1108    if hooks == 0 || hooks & !ALL_V1_HOOKS != 0 {
1109        return Err(
1110            "torana sdk: supported hook bitmap is empty or contains unknown bits".to_owned(),
1111        );
1112    }
1113    let input = pbv1::HookInput::decode(input_bytes)
1114        .map_err(|err| format!("torana sdk: decode run_hook: {err}"))?;
1115    validate_input(&input, input_bytes)?;
1116    let hook = hook_of(&input)?;
1117    if hooks & (1 << hook as u32) == 0 {
1118        return Err(format!(
1119            "torana sdk: dispatched unregistered hook {}",
1120            hook.as_str_name()
1121        ));
1122    }
1123    let _execution_guard = ExecutionGuard::enter(&input);
1124    let Some(result) = handler(input).map_err(|err| format!("torana plugin: {err}"))? else {
1125        return Ok(Vec::new());
1126    };
1127    validate_hook_result(hook, &result)?;
1128    if let Some(action) = result.action.as_ref() {
1129        validate_action(action)?;
1130    }
1131    let mut output = Vec::new();
1132    result
1133        .encode(&mut output)
1134        .map_err(|err| format!("torana sdk: encode run_hook: {err}"))?;
1135    if output.is_empty() {
1136        return Err("torana sdk: non-pass HookResult encoded to empty bytes".to_owned());
1137    }
1138    Ok(output)
1139}
1140
1141/// Exports the two functions required by ABI v1: `supported_hooks` and
1142/// `run_hook`. The handler receives the typed HookInput and returns `Ok(None)`
1143/// for pass-through or one hook-appropriate HookResult.
1144#[macro_export]
1145macro_rules! export_plugin_v1 {
1146    ($plugin:ty) => {
1147        #[no_mangle]
1148        pub extern "C" fn abi_version() -> u64 {
1149            $crate::ABI_VERSION
1150        }
1151        #[no_mangle]
1152        pub extern "C" fn supported_hooks() -> u32 {
1153            <$plugin as $crate::Plugin>::SUPPORTED_HOOKS
1154        }
1155        #[no_mangle]
1156        pub extern "C" fn run_hook(ptr: u32, len: u32) -> u64 {
1157            let input = unsafe { $crate::__input(ptr, len) };
1158            let output = $crate::__dispatch_v1(
1159                input,
1160                <$plugin as $crate::Plugin>::SUPPORTED_HOOKS,
1161                $crate::__plugin_dispatch::<$plugin>,
1162            )
1163            .unwrap_or_else(|e| panic!("{e}"));
1164            $crate::__result(&output)
1165        }
1166    };
1167    ($hooks:expr, $handler:path) => {
1168        #[no_mangle]
1169        pub extern "C" fn abi_version() -> u64 {
1170            $crate::ABI_VERSION
1171        }
1172
1173        #[no_mangle]
1174        pub extern "C" fn supported_hooks() -> u32 {
1175            $hooks
1176        }
1177
1178        #[no_mangle]
1179        pub extern "C" fn run_hook(ptr: u32, len: u32) -> u64 {
1180            // SAFETY: ptr/len are the guest-memory allocation populated by
1181            // the Torana host for this invocation and are consumed before
1182            // the hook returns.
1183            let input = unsafe { $crate::__input(ptr, len) };
1184            let output = $crate::__dispatch_v1(input, $hooks, $handler)
1185                .unwrap_or_else(|error| panic!("{error}"));
1186            $crate::__result(&output)
1187        }
1188    };
1189}
1190
1191#[repr(i32)]
1192#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1193pub enum LogLevel {
1194    Debug = 0,
1195    Info = 1,
1196}
1197pub const LOG_DEBUG: LogLevel = LogLevel::Debug;
1198pub const LOG_INFO: LogLevel = LogLevel::Info;
1199
1200#[link(wasm_import_module = "env")]
1201#[cfg(target_arch = "wasm32")]
1202extern "C" {
1203    #[link_name = "log"]
1204    fn host_log(level: i32, ptr: u32, len: u32);
1205    #[link_name = "emit_metric"]
1206    fn host_emit_metric(
1207        kind: i32,
1208        ptr: u32,
1209        len: u32,
1210        value: f64,
1211        labels_ptr: u32,
1212        labels_len: u32,
1213    );
1214    #[link_name = "host_call"]
1215    fn raw_host_call(cmd_ptr: u32, cmd_len: u32, args_ptr: u32, args_len: u32) -> u64;
1216}
1217
1218/// Logs a bounded diagnostic string when the host granted `env.log`.
1219/// Delivery is best effort: the void ABI import cannot report refusal.
1220pub fn log(message: &str, level: LogLevel) {
1221    if message.is_empty() {
1222        return;
1223    }
1224    #[cfg(target_arch = "wasm32")]
1225    unsafe {
1226        host_log(level as i32, message.as_ptr() as u32, message.len() as u32)
1227    }
1228    #[cfg(not(target_arch = "wasm32"))]
1229    let _ = level as i32;
1230}
1231
1232// Allocation goes through `std::alloc` with an explicit `Layout`, which is the
1233// pattern docs/WASM_PLUGIN_GUIDE.md already documents and this crate did not
1234// follow.
1235//
1236// The previous version paired `Vec::with_capacity(n)` + `mem::forget` with
1237// `Vec::from_raw_parts(ptr, 0, n)`. That requires n to be the vector's ACTUAL
1238// capacity, and `with_capacity` is only obliged to allocate *at least* n. It
1239// happens to allocate exactly n for `u8` today, so nothing has gone wrong yet —
1240// but the deallocation is only correct by coincidence, and freeing with a
1241// layout that does not match the allocation is undefined behaviour. Naming the
1242// layout in both places removes the coincidence.
1243
1244/// Allocates `size` bytes and returns a host-visible pointer.
1245///
1246/// The buffer is uninitialised. Hosts call [`dealloc`] with the same size after
1247/// consuming a non-zero hook result.
1248///
1249/// Allocation failure TRAPS rather than returning a sentinel. ABI v1 defines
1250/// no failure value for `alloc`, and the host treats 0 as a valid pointer — it
1251/// would write the payload at linear-memory offset 0, over the guest's own
1252/// memory, and then call the hook with `ptr = 0`.
1253#[no_mangle]
1254pub extern "C" fn alloc(size: u32) -> u32 {
1255    alloc_bytes(size as usize) as u32
1256}
1257
1258/// Frees a buffer previously returned by [`alloc`]. `size` must be the size
1259/// that was passed to `alloc`.
1260#[no_mangle]
1261pub extern "C" fn dealloc(ptr: u32, size: u32) {
1262    dealloc_bytes(ptr as *mut u8, size as usize);
1263}
1264
1265// The pointer-level halves exist so the allocator contract can be tested on the
1266// host, where a real pointer does not fit in the u32 the wasm ABI uses.
1267
1268fn alloc_bytes(size: usize) -> *mut u8 {
1269    if size == 0 {
1270        // Zero bytes needs no allocation, and a zero-sized layout is UB to
1271        // pass to the allocator. No caller dereferences this.
1272        return ptr::null_mut();
1273    }
1274    let Ok(layout) = Layout::array::<u8>(size) else {
1275        // Only reachable for a size beyond isize::MAX. Unrecoverable, and
1276        // there is no ABI value to report it with.
1277        std::process::abort();
1278    };
1279    let p = unsafe { std::alloc::alloc(layout) };
1280    if p.is_null() {
1281        // Out of memory. Returning null here would be reported to the host as
1282        // a pass-through by __result, which means the plugin's output is
1283        // dropped and the ORIGINAL request continues upstream — a redaction
1284        // plugin would fail open. Trap so failure_mode applies.
1285        std::alloc::handle_alloc_error(layout);
1286    }
1287    p
1288}
1289
1290fn dealloc_bytes(p: *mut u8, size: usize) {
1291    if p.is_null() || size == 0 {
1292        return;
1293    }
1294    if let Ok(layout) = Layout::array::<u8>(size) {
1295        unsafe { std::alloc::dealloc(p, layout) }
1296    }
1297}
1298
1299/// Borrows a host-provided buffer as a slice.
1300///
1301/// # Safety
1302///
1303/// `ptr..ptr+len` must denote readable guest memory for the returned borrow's
1304/// lifetime. The memory must not be mutated or freed during that lifetime.
1305/// Only the generated hook wrapper should call this function.
1306///
1307/// The leading underscores mark it as ABI plumbing rather than API.
1308#[doc(hidden)]
1309pub unsafe fn __input<'a>(ptr: u32, len: u32) -> &'a [u8] {
1310    if ptr == 0 || len == 0 {
1311        return &[];
1312    }
1313    unsafe { slice::from_raw_parts(ptr as *const u8, len as usize) }
1314}
1315
1316/// Copies `bytes` into a freshly allocated host-visible buffer and packs the
1317/// pointer and length into the u64 the ABI returns.
1318#[doc(hidden)]
1319pub fn __result(bytes: &[u8]) -> u64 {
1320    // Zero is reserved by the ABI for a DELIBERATE pass-through. An empty
1321    // payload is the only thing that means, so it is the only thing that
1322    // returns 0 here — allocation failure traps inside alloc_bytes rather than
1323    // arriving as a null this function could not tell apart from "no change".
1324    if bytes.is_empty() {
1325        return 0;
1326    }
1327    let (dst, len) = copy_to_owned_buffer(bytes);
1328    pack(dst as u32, len as u32)
1329}
1330
1331/// Copies `bytes` into a fresh buffer, returning the pointer and length.
1332///
1333/// Split out from [`__result`] so it can be tested: off wasm32 a real pointer
1334/// does not fit in the u32 the ABI packs it into, so a test that round-trips
1335/// through `pack` would reconstruct a truncated pointer and segfault.
1336fn copy_to_owned_buffer(bytes: &[u8]) -> (*mut u8, usize) {
1337    if bytes.is_empty() {
1338        return (ptr::null_mut(), 0);
1339    }
1340    // Non-null: alloc_bytes traps on failure rather than returning null.
1341    let dst = alloc_bytes(bytes.len());
1342    // copy_nonoverlapping rather than building a &mut [u8] first. The buffer is
1343    // UNINITIALISED, and constructing a reference to uninitialised memory is
1344    // undefined behaviour even when nothing reads it before the write — which
1345    // is exactly what `slice::from_raw_parts_mut(..).copy_from_slice(..)` did.
1346    unsafe { ptr::copy_nonoverlapping(bytes.as_ptr(), dst, bytes.len()) };
1347    (dst, bytes.len())
1348}
1349
1350/// Packs a pointer and length into the single u64 an ABI hook returns:
1351/// pointer in the high 32 bits, length in the low 32.
1352fn pack(ptr: u32, len: u32) -> u64 {
1353    ((ptr as u64) << 32) | len as u64
1354}
1355
1356#[repr(i32)]
1357#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1358pub enum MetricKind {
1359    Counter = 0,
1360    Histogram = 1,
1361    Gauge = 2,
1362}
1363pub const METRIC_COUNTER: MetricKind = MetricKind::Counter;
1364pub const METRIC_HISTOGRAM: MetricKind = MetricKind::Histogram;
1365pub const METRIC_GAUGE: MetricKind = MetricKind::Gauge;
1366
1367/// Emits a metric on a best-effort void host import.
1368pub fn emit_metric(name: &str, kind: MetricKind, value: f64, labels: &serde_json::Value) {
1369    let labels = labels.to_string();
1370    #[cfg(target_arch = "wasm32")]
1371    unsafe {
1372        host_emit_metric(
1373            kind as i32,
1374            name.as_ptr() as u32,
1375            name.len() as u32,
1376            value,
1377            labels.as_ptr() as u32,
1378            labels.len() as u32,
1379        )
1380    }
1381    #[cfg(not(target_arch = "wasm32"))]
1382    let _ = (name, kind, value, labels);
1383}
1384
1385pub fn debug(message: &str) {
1386    log(message, LogLevel::Debug);
1387}
1388pub fn info(message: &str) {
1389    log(message, LogLevel::Info);
1390}
1391pub fn counter(name: &str, value: f64, labels: &serde_json::Value) {
1392    emit_metric(name, MetricKind::Counter, value, labels);
1393}
1394pub fn histogram(name: &str, value: f64, labels: &serde_json::Value) {
1395    emit_metric(name, MetricKind::Histogram, value, labels);
1396}
1397pub fn gauge(name: &str, value: f64, labels: &serde_json::Value) {
1398    emit_metric(name, MetricKind::Gauge, value, labels);
1399}
1400
1401pub fn decode_host_call_result(bytes: &[u8]) -> Result<Vec<u8>, HostCallError> {
1402    use pbv1::host_call_result::Result as ResultArm;
1403    use prost::Message;
1404
1405    validate_host_call_result_wire(bytes)?;
1406    let result = pbv1::HostCallResult::decode(bytes)
1407        .map_err(|err| HostCallError::Protocol(format!("decode HostCallResult: {err}")))?;
1408    match result.result {
1409        Some(ResultArm::Value(value)) => Ok(value),
1410        Some(ResultArm::Error(error)) => {
1411            if !matches!(error.code, 1..=7) {
1412                return Err(HostCallError::Protocol(format!(
1413                    "HostError code {} is not classified by this SDK",
1414                    error.code
1415                )));
1416            }
1417            Err(HostCallError::Refused(error))
1418        }
1419        None => Err(HostCallError::Protocol(
1420            "HostCallResult requires a result arm".to_owned(),
1421        )),
1422    }
1423}
1424
1425fn validate_host_call_result_wire(mut bytes: &[u8]) -> Result<(), HostCallError> {
1426    let mut arms = 0u8;
1427    while !bytes.is_empty() {
1428        let (key, key_len) = read_varint(bytes)?;
1429        bytes = &bytes[key_len..];
1430        let field = key >> 3;
1431        let wire = key & 7;
1432        if !matches!(field, 1 | 2) || wire != 2 {
1433            return Err(HostCallError::Protocol(
1434                "HostCallResult carries an unknown or malformed result arm".to_owned(),
1435            ));
1436        }
1437        arms = arms.saturating_add(1);
1438        let (length, length_len) = read_varint(bytes)?;
1439        bytes = &bytes[length_len..];
1440        let length = usize::try_from(length).map_err(|_| {
1441            HostCallError::Protocol("HostCallResult field length overflows usize".to_owned())
1442        })?;
1443        if length > bytes.len() {
1444            return Err(HostCallError::Protocol(
1445                "HostCallResult field is truncated".to_owned(),
1446            ));
1447        }
1448        bytes = &bytes[length..];
1449    }
1450    if arms != 1 {
1451        return Err(HostCallError::Protocol(
1452            "HostCallResult must carry exactly one result arm".to_owned(),
1453        ));
1454    }
1455    Ok(())
1456}
1457
1458fn read_varint(bytes: &[u8]) -> Result<(u64, usize), HostCallError> {
1459    let mut value = 0u64;
1460    for (index, byte) in bytes.iter().copied().take(10).enumerate() {
1461        if index == 9 && byte > 1 {
1462            break;
1463        }
1464        value |= u64::from(byte & 0x7f) << (index * 7);
1465        if byte & 0x80 == 0 {
1466            return Ok((value, index + 1));
1467        }
1468    }
1469    Err(HostCallError::Protocol(
1470        "HostCallResult contains an invalid varint".to_owned(),
1471    ))
1472}
1473
1474/// Invokes a host command with protobuf arguments and decodes the ABI-v1
1475/// `HostCallResult` envelope. Empty successful values remain distinguishable
1476/// from typed refusals; callers must branch on [`HostCallError::Refused`]'s
1477/// code, never its diagnostic message.
1478pub fn host_call<M: prost::Message>(
1479    command: &str,
1480    arguments: &M,
1481) -> Result<Vec<u8>, HostCallError> {
1482    let arguments = arguments.encode_to_vec();
1483    let contract = capability_contract::command(command)
1484        .ok_or_else(|| HostCallError::Protocol(format!("unknown host command {command}")))?;
1485    if contract.arguments == "import" || contract.arguments.ends_with("-json") {
1486        return Err(HostCallError::Protocol(format!(
1487            "{command} is not a protobuf host-call command"
1488        )));
1489    }
1490    validate_host_arguments(command, &arguments)?;
1491    call_encoded(command, &arguments)
1492}
1493
1494fn call_encoded(command: &str, arguments: &[u8]) -> Result<Vec<u8>, HostCallError> {
1495    #[cfg(not(target_arch = "wasm32"))]
1496    if let Some(result) =
1497        NATIVE_HOST.with(|slot| slot.borrow().as_ref().map(|f| f(command, arguments)))
1498    {
1499        return result.and_then(|frame| decode_host_call_result(&frame));
1500    }
1501    #[cfg(not(target_arch = "wasm32"))]
1502    return Err(HostCallError::Protocol(
1503        "no native host transport installed".into(),
1504    ));
1505    #[cfg(target_arch = "wasm32")]
1506    {
1507        let packed = unsafe {
1508            raw_host_call(
1509                command.as_ptr() as u32,
1510                command.len() as u32,
1511                arguments.as_ptr() as u32,
1512                arguments.len() as u32,
1513            )
1514        };
1515        if packed == 0 {
1516            return Err(HostCallError::Protocol(
1517                "host_call returned no HostCallResult frame".to_owned(),
1518            ));
1519        }
1520        let ptr = (packed >> 32) as u32;
1521        let len = packed as u32;
1522        // SAFETY: raw_host_call returns a host-owned result buffer valid until
1523        // dealloc below; copy it before releasing that allocation.
1524        let bytes = unsafe { __input(ptr, len) }.to_vec();
1525        dealloc(ptr, len);
1526        decode_host_call_result(&bytes)
1527    }
1528}
1529
1530/// Calls one catalogued JSON extension through the same ABI transport as typed
1531/// protobuf helpers. Both arguments and JSON results use strict object shape.
1532pub fn extension_call(command: &str, arguments: &[u8]) -> Result<serde_json::Value, HostCallError> {
1533    let contract = capability_contract::command(command)
1534        .ok_or_else(|| HostCallError::Protocol(format!("unknown host command {command}")))?;
1535    if !contract.arguments.ends_with("-json") {
1536        return Err(HostCallError::Protocol(format!(
1537            "{command} is not a JSON extension"
1538        )));
1539    }
1540    let input = strict_json(arguments).map_err(|e| {
1541        HostCallError::Protocol(format!("{command} arguments are invalid JSON: {e}"))
1542    })?;
1543    if !input.is_object() {
1544        return Err(HostCallError::Protocol(format!(
1545            "{command} arguments must be a JSON object"
1546        )));
1547    }
1548    let value = call_encoded(command, arguments)?;
1549    if contract.result == "empty" && value.is_empty() {
1550        return Ok(serde_json::Value::Null);
1551    }
1552    let output = strict_json(&value)
1553        .map_err(|e| HostCallError::Protocol(format!("{command} result is invalid JSON: {e}")))?;
1554    if !output.is_object() {
1555        return Err(HostCallError::Protocol(format!(
1556            "{command} result must be a JSON object"
1557        )));
1558    }
1559    Ok(output)
1560}
1561
1562fn validate_host_arguments(command: &str, bytes: &[u8]) -> Result<(), HostCallError> {
1563    macro_rules! decode {
1564        ($ty:ty) => {
1565            <$ty>::decode(bytes)
1566                .map_err(|e| HostCallError::Protocol(format!("decode {command} arguments: {e}")))?
1567        };
1568    }
1569    let bad = |message: &str| HostCallError::Protocol(format!("{command} arguments: {message}"));
1570    match command {
1571        "env.meta_get" => {
1572            if decode!(pbv1::MetaGetArgs).key.is_empty() {
1573                return Err(bad("key is required"));
1574            }
1575        }
1576        "env.meta_set" => {
1577            if decode!(pbv1::MetaSetArgs).key.is_empty() {
1578                return Err(bad("key is required"));
1579            }
1580        }
1581        "env.state_get" | "env.state_get_versioned" => {
1582            if decode!(pbv1::StateGetArgs).key.is_empty() {
1583                return Err(bad("key is required"));
1584            }
1585        }
1586        "env.state_set" => {
1587            if decode!(pbv1::StateSetArgs).key.is_empty() {
1588                return Err(bad("key is required"));
1589            }
1590        }
1591        "env.state_delete" => {
1592            if decode!(pbv1::StateDeleteArgs).key.is_empty() {
1593                return Err(bad("key is required"));
1594            }
1595        }
1596        "env.cache_get" | "env.shared_cache_get" => {
1597            if decode!(pbv1::CacheGetArgs).key.is_empty() {
1598                return Err(bad("key is required"));
1599            }
1600        }
1601        "env.cache_set" | "env.shared_cache_set" => {
1602            let a = decode!(pbv1::CacheSetArgs);
1603            if a.key.is_empty() {
1604                return Err(bad("key is required"));
1605            }
1606            if a.ttl_ms == Some(0) {
1607                return Err(bad("ttl_ms must be positive"));
1608            }
1609        }
1610        "env.cache_delete" | "env.shared_cache_delete" => {
1611            if decode!(pbv1::CacheDeleteArgs).key.is_empty() {
1612                return Err(bad("key is required"));
1613            }
1614        }
1615        "env.state_compare_and_set" => {
1616            if decode!(pbv1::StateCompareAndSetArgs).key.is_empty() {
1617                return Err(bad("key is required"));
1618            }
1619        }
1620        "env.state_compare_and_delete" => {
1621            let a = decode!(pbv1::StateCompareAndDeleteArgs);
1622            if a.key.is_empty() || a.expected_version.is_empty() {
1623                return Err(bad("key and expected_version are required"));
1624            }
1625        }
1626        "env.state_scan" => {
1627            if !(1..=256).contains(&decode!(pbv1::StateScanArgs).limit) {
1628                return Err(bad("limit must be 1..256"));
1629            }
1630        }
1631        "env.model_complete" => {
1632            let a = decode!(pbv1::ModelCompleteArgs);
1633            if !valid_resource_name(&a.service)
1634                || a.messages.is_empty()
1635                || a.max_tokens == Some(0)
1636                || a.temperature.is_some_and(|v| !v.is_finite())
1637            {
1638                return Err(bad("request violates the model contract"));
1639            }
1640        }
1641        "env.http_request" => {
1642            let a = decode!(pbv1::OutboundHttpRequestArgs);
1643            let method_ok =
1644                !a.method.is_empty() && a.method.bytes().all(|b| b.is_ascii_uppercase());
1645            let path_ok =
1646                a.path.starts_with('/') && !a.path.starts_with("//") && !a.path.contains('#');
1647            if !valid_resource_name(&a.endpoint)
1648                || !method_ok
1649                || !path_ok
1650                || !valid_http_headers(&a.headers)
1651            {
1652                return Err(bad("request violates the HTTP contract"));
1653            }
1654        }
1655        "env.model_pricing"
1656            if !valid_resource_name(&decode!(pbv1::ModelPricingGetArgs).resource) =>
1657        {
1658            return Err(bad("resource is invalid"));
1659        }
1660        "env.model_capabilities" => {
1661            let a = decode!(pbv1::ModelCapabilitiesArgs);
1662            if a.provider.trim().is_empty() || a.model.trim().is_empty() {
1663                return Err(bad("provider and model are required"));
1664            }
1665        }
1666        "env.route_request" => {
1667            let a = decode!(pbv1::RouteRequestArgs);
1668            if (a.provider.is_empty() && a.model.is_empty()) || !(0..=6).contains(&a.effort) {
1669                return Err(bad("route needs provider or model and a known effort"));
1670            }
1671        }
1672        "env.suggest" => {
1673            let a = decode!(pbv1::SuggestArgs);
1674            if !valid_suggestion_token(&a.kind, 64)
1675                || !valid_suggestion_token(&a.dedupe_key, 128)
1676                || !valid_suggestion_text(&a.title, 120)
1677                || !valid_suggestion_text(&a.body, 600)
1678                || a.actions.len() > 4
1679                || a.actions.iter().any(|v| {
1680                    !valid_suggestion_token(&v.id, 64) || !valid_suggestion_text(&v.label, 80)
1681                })
1682                || a.cost_usd.is_some_and(|v| !v.is_finite() || v < 0.0)
1683                || a.harness_target_model
1684                    .as_deref()
1685                    .is_some_and(|v| !valid_suggestion_text(v, 256))
1686                || a.expires_after_user_turns > 100
1687            {
1688                return Err(bad("suggestion violates the contract"));
1689            }
1690        }
1691        "env.cache_policy"
1692            if !valid_resource_name(&decode!(pbv1::PromptCachePolicyGetArgs).resource) =>
1693        {
1694            return Err(bad("resource is invalid"));
1695        }
1696        _ => {}
1697    }
1698    Ok(())
1699}
1700
1701fn valid_suggestion_token(value: &str, max: usize) -> bool {
1702    !value.is_empty()
1703        && value.len() <= max
1704        && value
1705            .bytes()
1706            .enumerate()
1707            .all(|(i, b)| b.is_ascii_alphanumeric() || (i > 0 && matches!(b, b'_' | b'-' | b'.')))
1708}
1709
1710fn valid_suggestion_text(value: &str, max: usize) -> bool {
1711    !value.trim().is_empty() && value.chars().count() <= max && !value.chars().any(char::is_control)
1712}
1713
1714fn valid_http_headers(headers: &[pbv1::HttpHeader]) -> bool {
1715    let mut seen = std::collections::HashSet::new();
1716    headers.iter().all(|header| {
1717        let name = header.name.to_ascii_lowercase();
1718        !header.name.is_empty()
1719            && header.name.is_ascii()
1720            && header
1721                .name
1722                .bytes()
1723                .all(|b| b.is_ascii_alphanumeric() || b"!#$%&'*+-.^_`|~".contains(&b))
1724            && seen.insert(name)
1725            && header
1726                .values
1727                .iter()
1728                .all(|value| !value.contains(['\r', '\n']))
1729    })
1730}
1731
1732fn decode_host_value<R: prost::Message + Default>(
1733    bytes: &[u8],
1734    protobuf_name: &str,
1735) -> Result<R, HostCallError> {
1736    __validate_wire_message(bytes, protobuf_name).map_err(HostCallError::Protocol)?;
1737    R::decode(bytes).map_err(|e| HostCallError::Protocol(format!("decode {protobuf_name}: {e}")))
1738}
1739
1740/// Resolves one operator-bound credential slot. Treat the returned bytes as a
1741/// secret and do not place them in logs or diagnostic errors.
1742pub fn get_credential(slot: &str) -> Result<Vec<u8>, HostCallError> {
1743    host_call(
1744        "env.credential_get",
1745        &pbv1::CredentialGetArgs {
1746            slot: slot.to_owned(),
1747        },
1748    )
1749}
1750
1751pub fn meta_get(key: &str) -> Result<Option<String>, HostCallError> {
1752    match host_call("env.meta_get", &pbv1::MetaGetArgs { key: key.into() }) {
1753        Err(HostCallError::Refused(e)) if e.code == pbv1::ErrorCode::NotFound as i32 => Ok(None),
1754        Err(e) => Err(e),
1755        Ok(v) => match v {
1756            v if v.is_empty() => Ok(Some(String::new())),
1757            v => String::from_utf8(v)
1758                .map(Some)
1759                .map_err(|_| HostCallError::Protocol("meta value is not UTF-8".into())),
1760        },
1761    }
1762}
1763pub fn meta_set(key: &str, value: &str) -> Result<(), HostCallError> {
1764    host_call(
1765        "env.meta_set",
1766        &pbv1::MetaSetArgs {
1767            key: key.into(),
1768            value: value.into(),
1769        },
1770    )
1771    .map(|_| ())
1772}
1773pub fn meta_append(block_index: i32, fragment: &[u8]) -> Result<Vec<u8>, HostCallError> {
1774    host_call(
1775        "env.meta_append",
1776        &pbv1::MetaAppendArgs {
1777            block_index,
1778            fragment: fragment.to_vec(),
1779        },
1780    )
1781}
1782pub fn state_get(key: &str) -> Result<Option<String>, HostCallError> {
1783    match host_call("env.state_get", &pbv1::StateGetArgs { key: key.into() }) {
1784        Err(HostCallError::Refused(e)) if e.code == pbv1::ErrorCode::NotFound as i32 => Ok(None),
1785        Err(e) => Err(e),
1786        Ok(v) => match v {
1787            v if v.is_empty() => Ok(Some(String::new())),
1788            v => String::from_utf8(v)
1789                .map(Some)
1790                .map_err(|_| HostCallError::Protocol("state value is not UTF-8".into())),
1791        },
1792    }
1793}
1794pub fn state_set(key: &str, value: &str) -> Result<(), HostCallError> {
1795    host_call(
1796        "env.state_set",
1797        &pbv1::StateSetArgs {
1798            key: key.into(),
1799            value: value.into(),
1800        },
1801    )
1802    .map(|_| ())
1803}
1804pub fn state_delete(key: &str) -> Result<(), HostCallError> {
1805    host_call(
1806        "env.state_delete",
1807        &pbv1::StateDeleteArgs { key: key.into() },
1808    )
1809    .map(|_| ())
1810}
1811pub fn cache_get(key: &str) -> Result<Option<String>, HostCallError> {
1812    cache_get_named("env.cache_get", key)
1813}
1814pub fn cache_set(key: &str, value: &str, ttl_ms: Option<u64>) -> Result<(), HostCallError> {
1815    host_call(
1816        "env.cache_set",
1817        &pbv1::CacheSetArgs {
1818            key: key.into(),
1819            value: value.into(),
1820            ttl_ms,
1821        },
1822    )
1823    .map(|_| ())
1824}
1825pub fn cache_delete(key: &str) -> Result<(), HostCallError> {
1826    host_call(
1827        "env.cache_delete",
1828        &pbv1::CacheDeleteArgs { key: key.into() },
1829    )
1830    .map(|_| ())
1831}
1832pub fn state_keys() -> Result<Vec<String>, HostCallError> {
1833    let b = host_call("env.state_keys", &EmptyArgs {})?;
1834    let value = strict_json(&b)
1835        .map_err(|e| HostCallError::Protocol(format!("state keys are invalid JSON: {e}")))?;
1836    let array = value
1837        .as_array()
1838        .ok_or_else(|| HostCallError::Protocol("state keys must be a JSON array".into()))?;
1839    array
1840        .iter()
1841        .map(|item| {
1842            item.as_str()
1843                .map(str::to_owned)
1844                .ok_or_else(|| HostCallError::Protocol("state key must be a string".into()))
1845        })
1846        .collect()
1847}
1848pub fn state_get_versioned(key: &str) -> Result<Option<pbv1::StateValue>, HostCallError> {
1849    match host_call(
1850        "env.state_get_versioned",
1851        &pbv1::StateGetArgs { key: key.into() },
1852    ) {
1853        Ok(b) => Ok(Some(decode_host_value(&b, ".torana.v1.StateValue")?)),
1854        Err(HostCallError::Refused(e)) if e.code == pbv1::ErrorCode::NotFound as i32 => Ok(None),
1855        Err(e) => Err(e),
1856    }
1857}
1858pub fn state_compare_and_set(
1859    key: &str,
1860    value: &str,
1861    expected_version: Option<&str>,
1862) -> Result<pbv1::StateMutationResult, HostCallError> {
1863    let b = host_call(
1864        "env.state_compare_and_set",
1865        &pbv1::StateCompareAndSetArgs {
1866            key: key.into(),
1867            value: value.into(),
1868            expected_version: expected_version.map(str::to_owned),
1869        },
1870    )?;
1871    let result: pbv1::StateMutationResult =
1872        decode_host_value(&b, ".torana.v1.StateMutationResult")?;
1873    if result.applied && result.version.is_none() {
1874        return Err(HostCallError::Protocol(
1875            "applied state mutation requires version".into(),
1876        ));
1877    }
1878    Ok(result)
1879}
1880pub fn state_compare_and_delete(
1881    key: &str,
1882    expected_version: &str,
1883) -> Result<pbv1::StateMutationResult, HostCallError> {
1884    let b = host_call(
1885        "env.state_compare_and_delete",
1886        &pbv1::StateCompareAndDeleteArgs {
1887            key: key.into(),
1888            expected_version: expected_version.into(),
1889        },
1890    )?;
1891    decode_host_value(&b, ".torana.v1.StateMutationResult")
1892}
1893pub fn state_scan(
1894    prefix: &str,
1895    cursor: &str,
1896    limit: u32,
1897) -> Result<pbv1::StateScanResult, HostCallError> {
1898    if !(1..=256).contains(&limit) {
1899        return Err(HostCallError::Protocol(
1900            "state scan limit must be 1..256".into(),
1901        ));
1902    }
1903    let b = host_call(
1904        "env.state_scan",
1905        &pbv1::StateScanArgs {
1906            prefix: prefix.into(),
1907            cursor: cursor.into(),
1908            limit,
1909        },
1910    )?;
1911    let result: pbv1::StateScanResult = decode_host_value(&b, ".torana.v1.StateScanResult")?;
1912    if result.entries.iter().any(|entry| {
1913        entry.key.is_empty() || entry.value.as_ref().is_none_or(|v| v.version.is_empty())
1914    }) {
1915        return Err(HostCallError::Protocol(
1916            "state scan returned an invalid entry".into(),
1917        ));
1918    }
1919    Ok(result)
1920}
1921pub fn shared_cache_get(key: &str) -> Result<Option<String>, HostCallError> {
1922    cache_get_named("env.shared_cache_get", key)
1923}
1924pub fn shared_cache_set(key: &str, value: &str, ttl_ms: Option<u64>) -> Result<(), HostCallError> {
1925    host_call(
1926        "env.shared_cache_set",
1927        &pbv1::CacheSetArgs {
1928            key: key.into(),
1929            value: value.into(),
1930            ttl_ms,
1931        },
1932    )
1933    .map(|_| ())
1934}
1935pub fn shared_cache_delete(key: &str) -> Result<(), HostCallError> {
1936    host_call(
1937        "env.shared_cache_delete",
1938        &pbv1::CacheDeleteArgs { key: key.into() },
1939    )
1940    .map(|_| ())
1941}
1942fn cache_get_named(command: &str, key: &str) -> Result<Option<String>, HostCallError> {
1943    match host_call(command, &pbv1::CacheGetArgs { key: key.into() }) {
1944        Err(HostCallError::Refused(e)) if e.code == pbv1::ErrorCode::NotFound as i32 => Ok(None),
1945        Err(e) => Err(e),
1946        Ok(v) if v.is_empty() => Ok(Some(String::new())),
1947        Ok(v) => String::from_utf8(v)
1948            .map(Some)
1949            .map_err(|_| HostCallError::Protocol("cache value is not UTF-8".into())),
1950    }
1951}
1952pub fn respond_request(response: pbv1::SyntheticResponse) -> Result<(), HostCallError> {
1953    validate_synthetic_response(&response).map_err(HostCallError::Protocol)?;
1954    host_call(
1955        "env.respond_request",
1956        &pbv1::RespondRequestArgs {
1957            response: Some(response),
1958        },
1959    )
1960    .map(|_| ())
1961}
1962
1963fn validate_synthetic_response(response: &pbv1::SyntheticResponse) -> Result<(), String> {
1964    let message = response
1965        .message
1966        .as_ref()
1967        .ok_or("synthetic response requires a message")?;
1968    if message.blocks.is_empty() {
1969        return Err("synthetic response requires at least one block".into());
1970    }
1971    let mut has_tools = false;
1972    for block in &message.blocks {
1973        let Some(kind) = block.kind.as_ref() else {
1974            return Err("synthetic response contains an empty block".into());
1975        };
1976        match kind {
1977            pbv1::response_block::Kind::Text(_) => {}
1978            pbv1::response_block::Kind::ToolCall(call) => {
1979                has_tools = true;
1980                if !call.id.is_empty() || !call.signature.is_empty() {
1981                    return Err("synthetic tool IDs/signatures are host-owned".into());
1982                }
1983                if call.name.is_empty() {
1984                    return Err("synthetic tool name is required".into());
1985                }
1986                if call.arguments_json.is_empty() {
1987                    return Err("synthetic tool arguments are required".into());
1988                }
1989                json_object(&call.arguments_json, "tool arguments_json")?;
1990            }
1991        }
1992    }
1993    let expected = if has_tools { "tool_calls" } else { "stop" };
1994    if response.finish_reason != expected {
1995        return Err("synthetic finish_reason disagrees with tool-call presence".into());
1996    }
1997    Ok(())
1998}
1999pub fn respond_text(content: &str) -> Result<(), HostCallError> {
2000    respond_request(pbv1::SyntheticResponse {
2001        message: Some(pbv1::ResponseMessage {
2002            blocks: vec![pbv1::ResponseBlock {
2003                kind: Some(pbv1::response_block::Kind::Text(pbv1::ResponseTextBlock {
2004                    text: content.into(),
2005                })),
2006            }],
2007        }),
2008        finish_reason: "stop".into(),
2009    })
2010}
2011pub fn get_resource_info(kind: &str, name: &str) -> Result<pbv1::ResourceInfo, HostCallError> {
2012    let b = host_call(
2013        "env.resource_info",
2014        &pbv1::ResourceInfoArgs {
2015            kind: kind.into(),
2016            name: name.into(),
2017        },
2018    )?;
2019    decode_host_value(&b, ".torana.v1.ResourceInfo")
2020}
2021pub fn block_request(status: i32, code: &str, message: &str) -> Result<(), HostCallError> {
2022    host_call(
2023        "env.block_request",
2024        &pbv1::BlockRequestArgs {
2025            status,
2026            code: code.into(),
2027            message: message.into(),
2028        },
2029    )
2030    .map(|_| ())
2031}
2032pub fn route_request(provider: &str, model: &str) -> Result<(), HostCallError> {
2033    host_call(
2034        "env.route_request",
2035        &pbv1::RouteRequestArgs {
2036            provider: provider.into(),
2037            model: model.into(),
2038            effort: 0,
2039        },
2040    )
2041    .map(|_| ())
2042}
2043/// Route with an explicitly operator-authorized effort. UNSPECIFIED leaves
2044/// the harness's effort untouched. The route is atomic: if the host refuses
2045/// the effort, it does not apply the provider or model change either.
2046/// Handle a refusal explicitly, for example by retrying with route_request
2047/// (no effort) or passing. Return the error only if the request should fail
2048/// under the plugin's failure_mode.
2049pub fn route_request_with_effort(
2050    provider: &str,
2051    model: &str,
2052    effort: pbv1::Effort,
2053) -> Result<(), HostCallError> {
2054    host_call(
2055        "env.route_request",
2056        &pbv1::RouteRequestArgs {
2057            provider: provider.into(),
2058            model: model.into(),
2059            effort: effort as i32,
2060        },
2061    )
2062    .map(|_| ())
2063}
2064pub fn set_identity(identity: &str) -> Result<(), HostCallError> {
2065    host_call(
2066        "env.set_identity",
2067        &pbv1::SetIdentityArgs {
2068            identity: identity.into(),
2069        },
2070    )
2071    .map(|_| ())
2072}
2073
2074#[derive(Clone)]
2075pub struct AssembledToolCall {
2076    pub index: i32,
2077    pub id: String,
2078    pub name: String,
2079    pub signature: String,
2080    pub invocation_kind: pbv1::ToolInvocationKind,
2081    pub arguments: String,
2082    pub input_text: Option<String>,
2083}
2084pub struct StreamFeed {
2085    pub emit: Vec<pbv1::StreamEvent>,
2086    pub suppress: bool,
2087    pub complete: Option<AssembledToolCall>,
2088}
2089pub struct StreamAssembler;
2090impl Default for StreamAssembler {
2091    fn default() -> Self {
2092        Self::new()
2093    }
2094}
2095impl StreamAssembler {
2096    pub fn new() -> Self {
2097        Self
2098    }
2099    pub fn feed(&self, event: pbv1::StreamEvent) -> Result<StreamFeed, HostCallError> {
2100        validate_stream_event(&event).map_err(HostCallError::Protocol)?;
2101        let original = event.clone();
2102        use pbv1::stream_event::Event;
2103        match event.event {
2104            Some(Event::ContentBlockStart(s)) => {
2105                if let Some(pbv1::content_block_start::Block::ToolCall(r)) = s.block {
2106                    let mut h = r.encode_to_vec();
2107                    let mut f = (h.len() as u32).to_be_bytes().to_vec();
2108                    f.append(&mut h);
2109                    meta_append(s.index, &f)?;
2110                    return Ok(StreamFeed {
2111                        emit: vec![],
2112                        suppress: true,
2113                        complete: None,
2114                    });
2115                }
2116            }
2117            Some(Event::ToolCallDelta(d)) => {
2118                let f = d.input_text_delta.unwrap_or(d.arguments_delta).into_bytes();
2119                if !f.is_empty() {
2120                    meta_append(d.index, &f)?;
2121                }
2122                return Ok(StreamFeed {
2123                    emit: vec![],
2124                    suppress: true,
2125                    complete: None,
2126                });
2127            }
2128            Some(Event::ContentBlockStop(s)) => {
2129                let b = meta_append(s.index, &[])?;
2130                if b.is_empty() {
2131                    return Ok(StreamFeed {
2132                        emit: vec![original],
2133                        suppress: false,
2134                        complete: None,
2135                    });
2136                }
2137                if b.len() < 4 {
2138                    return Err(HostCallError::Protocol("corrupt tool frame header".into()));
2139                }
2140                let n = u32::from_be_bytes(b[..4].try_into().unwrap()) as usize;
2141                let end = n.checked_add(4).ok_or_else(|| {
2142                    HostCallError::Protocol("corrupt tool frame length overflow".into())
2143                })?;
2144                if end > b.len() {
2145                    return Err(HostCallError::Protocol("corrupt tool frame".into()));
2146                }
2147                __validate_wire_message(&b[4..end], ".torana.v1.ToolCallRef")
2148                    .map_err(HostCallError::Protocol)?;
2149                let r = pbv1::ToolCallRef::decode(&b[4..end])
2150                    .map_err(|e| HostCallError::Protocol(e.to_string()))?;
2151                if r.id.is_empty()
2152                    || r.name.is_empty()
2153                    || !matches!(
2154                        r.invocation_kind,
2155                        value if value == pbv1::ToolInvocationKind::Function as i32
2156                            || value == pbv1::ToolInvocationKind::Freeform as i32
2157                    )
2158                {
2159                    return Err(HostCallError::Protocol(
2160                        "corrupt tool frame reference".into(),
2161                    ));
2162                }
2163                let args = String::from_utf8(b[end..].to_vec())
2164                    .map_err(|_| HostCallError::Protocol("tool arguments not UTF-8".into()))?;
2165                let input = (r.invocation_kind == pbv1::ToolInvocationKind::Freeform as i32)
2166                    .then_some(args.clone());
2167                let arguments = if input.is_none() { args } else { String::new() };
2168                return Ok(StreamFeed {
2169                    emit: vec![],
2170                    suppress: true,
2171                    complete: Some(AssembledToolCall {
2172                        index: s.index,
2173                        id: r.id,
2174                        name: r.name,
2175                        signature: r.signature,
2176                        invocation_kind: pbv1::ToolInvocationKind::try_from(r.invocation_kind)
2177                            .map_err(|_| {
2178                                HostCallError::Protocol("corrupt tool invocation kind".into())
2179                            })?,
2180                        arguments,
2181                        input_text: input,
2182                    }),
2183                });
2184            }
2185            _ => {}
2186        }
2187        Ok(StreamFeed {
2188            emit: vec![original],
2189            suppress: false,
2190            complete: None,
2191        })
2192    }
2193}
2194
2195pub struct StreamHandler<F> {
2196    assembler: StreamAssembler,
2197    on_tool: F,
2198}
2199impl<F, E> StreamHandler<F>
2200where
2201    F: Fn(AssembledToolCall) -> Result<Option<String>, E>,
2202    E: std::fmt::Display,
2203{
2204    pub fn new(on_tool: F) -> Self {
2205        Self {
2206            assembler: StreamAssembler::new(),
2207            on_tool,
2208        }
2209    }
2210    pub fn handle(&self, event: pbv1::StreamEvent) -> Result<Vec<pbv1::StreamEvent>, String> {
2211        let fed = self.assembler.feed(event).map_err(|e| e.to_string())?;
2212        if let Some(call) = fed.complete {
2213            let original = if call.invocation_kind == pbv1::ToolInvocationKind::Freeform {
2214                call.input_text.clone().unwrap_or_default()
2215            } else {
2216                call.arguments.clone()
2217            };
2218            let payload = (self.on_tool)(call.clone())
2219                .map_err(|e| e.to_string())?
2220                .unwrap_or(original.clone());
2221            let sig = if payload == original {
2222                call.signature
2223            } else {
2224                String::new()
2225            };
2226            let r = pbv1::ToolCallRef {
2227                id: call.id,
2228                name: call.name,
2229                signature: sig,
2230                invocation_kind: call.invocation_kind as i32,
2231            };
2232            let mut out = Vec::new();
2233            out.push(pbv1::StreamEvent {
2234                event: Some(pbv1::stream_event::Event::ContentBlockStart(
2235                    pbv1::ContentBlockStart {
2236                        index: call.index,
2237                        block: Some(pbv1::content_block_start::Block::ToolCall(r)),
2238                    },
2239                )),
2240            });
2241            let mut d = pbv1::ToolCallDelta {
2242                index: call.index,
2243                ..Default::default()
2244            };
2245            if call.invocation_kind == pbv1::ToolInvocationKind::Freeform {
2246                d.input_text_delta = Some(payload)
2247            } else {
2248                d.arguments_delta = payload
2249            }
2250            out.push(pbv1::StreamEvent {
2251                event: Some(pbv1::stream_event::Event::ToolCallDelta(d)),
2252            });
2253            out.push(pbv1::StreamEvent {
2254                event: Some(pbv1::stream_event::Event::ContentBlockStop(
2255                    pbv1::ContentBlockStop { index: call.index },
2256                )),
2257            });
2258            Ok(out)
2259        } else if fed.suppress {
2260            Ok(Vec::new())
2261        } else {
2262            Ok(fed.emit)
2263        }
2264    }
2265}
2266
2267#[derive(Clone, PartialEq, prost::Message)]
2268struct EmptyArgs {}
2269pub fn plugin_config<T: serde::de::DeserializeOwned>() -> Result<T, HostCallError> {
2270    let mut bytes = host_call("env.plugin_config", &EmptyArgs {})?;
2271    if bytes.is_empty() {
2272        bytes.extend_from_slice(b"{}");
2273    }
2274    let value = strict_json(&bytes)
2275        .map_err(|e| HostCallError::Protocol(format!("plugin config is invalid JSON: {e}")))?;
2276    if !value.is_object() {
2277        return Err(HostCallError::Protocol(
2278            "plugin config must be a JSON object".into(),
2279        ));
2280    }
2281    serde_json::from_value(value)
2282        .map_err(|e| HostCallError::Protocol(format!("plugin config has wrong shape: {e}")))
2283}
2284
2285pub fn append_file(path: &str, data: &[u8]) -> Result<(), HostCallError> {
2286    host_call(
2287        "env.file_append",
2288        &pbv1::FileAppendArgs {
2289            path: path.to_owned(),
2290            data: data.to_vec(),
2291        },
2292    )
2293    .map(|_| ())
2294}
2295
2296pub fn read_file(path: &str) -> Result<Vec<u8>, HostCallError> {
2297    host_call(
2298        "env.file_read",
2299        &pbv1::FileReadArgs {
2300            path: path.to_owned(),
2301        },
2302    )
2303}
2304
2305pub fn write_file(path: &str, data: &[u8]) -> Result<(), HostCallError> {
2306    host_call(
2307        "env.file_write",
2308        &pbv1::FileWriteArgs {
2309            path: path.to_owned(),
2310            data: data.to_vec(),
2311        },
2312    )
2313    .map(|_| ())
2314}
2315
2316pub fn list_files(prefix: &str) -> Result<Vec<String>, HostCallError> {
2317    let value = host_call(
2318        "env.file_list",
2319        &pbv1::FileListArgs {
2320            prefix: prefix.to_owned(),
2321        },
2322    )?;
2323    decode_host_value::<pbv1::FileListResult>(&value, ".torana.v1.FileListResult")
2324        .map(|result| result.paths)
2325}
2326
2327pub fn delete_file(path: &str) -> Result<(), HostCallError> {
2328    host_call(
2329        "env.file_delete",
2330        &pbv1::FileDeleteArgs {
2331            path: path.to_owned(),
2332        },
2333    )
2334    .map(|_| ())
2335}
2336
2337pub fn http_request(
2338    request: &pbv1::OutboundHttpRequestArgs,
2339) -> Result<pbv1::OutboundHttpResponse, HostCallError> {
2340    let value = host_call("env.http_request", request)?;
2341    let response: pbv1::OutboundHttpResponse =
2342        decode_host_value(&value, ".torana.v1.OutboundHTTPResponse")?;
2343    if !(100..=599).contains(&response.status) {
2344        return Err(HostCallError::Protocol(format!(
2345            "OutboundHTTPResponse status {} is invalid",
2346            response.status
2347        )));
2348    }
2349    if !valid_http_headers(&response.headers) {
2350        return Err(HostCallError::Protocol(
2351            "OutboundHTTPResponse headers are invalid".into(),
2352        ));
2353    }
2354    Ok(response)
2355}
2356
2357/// Invokes one operator-bound model-service slot. Provider, URL, model,
2358/// credentials, and hard budgets are owned by the binding, not by the plugin.
2359pub fn model_complete(
2360    request: &pbv1::ModelCompleteArgs,
2361) -> Result<pbv1::ModelCompleteResult, HostCallError> {
2362    if !valid_resource_name(&request.service)
2363        || request.messages.is_empty()
2364        || request
2365            .messages
2366            .iter()
2367            .any(|message| message.role.is_empty())
2368        || request.max_tokens == Some(0)
2369        || request.temperature.is_some_and(|value| !value.is_finite())
2370    {
2371        return Err(HostCallError::Protocol(
2372            "ModelCompleteArgs violates the SDK contract".to_owned(),
2373        ));
2374    }
2375    let value = host_call("env.model_complete", request)?;
2376    let result: pbv1::ModelCompleteResult =
2377        decode_host_value(&value, ".torana.v1.ModelCompleteResult")?;
2378    if result.message.as_ref().is_none_or(|message| {
2379        message.blocks.is_empty() || message.blocks.iter().any(|block| block.kind.is_none())
2380    }) || result.usage.as_ref().is_some_and(|usage| {
2381        usage.input_tokens < 0
2382            || usage.output_tokens < 0
2383            || usage.cache_read_tokens < 0
2384            || usage.cache_write_tokens < 0
2385    }) {
2386        return Err(HostCallError::Protocol(
2387            "ModelCompleteResult violates the SDK contract".into(),
2388        ));
2389    }
2390    Ok(result)
2391}
2392
2393pub fn model_complete_text(request: &pbv1::ModelCompleteArgs) -> Result<String, HostCallError> {
2394    let result = model_complete(request)?;
2395    let message = result
2396        .message
2397        .ok_or_else(|| HostCallError::Protocol("model result has no message".into()))?;
2398    let mut text = String::new();
2399    for block in message.blocks {
2400        match block.kind {
2401            Some(pbv1::response_block::Kind::Text(t)) => text.push_str(&t.text),
2402            Some(_) => {
2403                return Err(HostCallError::Protocol(
2404                    "model result contains non-text block".into(),
2405                ))
2406            }
2407            None => {
2408                return Err(HostCallError::Protocol(
2409                    "model result contains empty block".into(),
2410                ))
2411            }
2412        }
2413    }
2414    Ok(text)
2415}
2416
2417/// Resolves one operator-bound pricing resource. `None` means an unknown rate;
2418/// `Some(0.0)` is an explicitly free rate.
2419pub fn get_model_pricing(resource: &str) -> Result<pbv1::ModelPricing, HostCallError> {
2420    if !valid_resource_name(resource) {
2421        return Err(HostCallError::Protocol(
2422            "model pricing resource is required".to_owned(),
2423        ));
2424    }
2425    let value = host_call(
2426        "env.model_pricing",
2427        &pbv1::ModelPricingGetArgs {
2428            resource: resource.to_owned(),
2429        },
2430    )?;
2431    let pricing: pbv1::ModelPricing = decode_host_value(&value, ".torana.v1.ModelPricing")?;
2432    for rate in [
2433        pricing.input_usd_per_mtok,
2434        pricing.output_usd_per_mtok,
2435        pricing.cache_read_usd_per_mtok,
2436        pricing.cache_write_usd_per_mtok,
2437    ] {
2438        if rate.is_some_and(|value| !value.is_finite() || value < 0.0) {
2439            return Err(HostCallError::Protocol(
2440                "ModelPricing rates must be finite and non-negative".to_owned(),
2441            ));
2442        }
2443    }
2444    Ok(pricing)
2445}
2446
2447/// Read capabilities for an operator-declared model; unknown models receive
2448/// a typed host refusal.
2449pub fn get_model_capabilities(
2450    provider: &str,
2451    model: &str,
2452) -> Result<pbv1::ModelCapabilities, HostCallError> {
2453    if provider.trim().is_empty() || model.trim().is_empty() {
2454        return Err(HostCallError::Protocol(
2455            "model capabilities need a provider and model".into(),
2456        ));
2457    }
2458    let value = host_call(
2459        "env.model_capabilities",
2460        &pbv1::ModelCapabilitiesArgs {
2461            provider: provider.into(),
2462            model: model.into(),
2463        },
2464    )?;
2465    let result: pbv1::ModelCapabilities =
2466        decode_host_value(&value, ".torana.v1.ModelCapabilities")?;
2467    let mut levels = std::collections::HashSet::new();
2468    if result.format.trim().is_empty()
2469        || result.context_window_tokens == Some(0)
2470        || result
2471            .effort_levels
2472            .iter()
2473            .any(|v| *v <= 0 || *v > 6 || !levels.insert(*v))
2474        || result.pricing.as_ref().is_some_and(|p| {
2475            [
2476                p.input_usd_per_mtok,
2477                p.output_usd_per_mtok,
2478                p.cache_read_usd_per_mtok,
2479                p.cache_write_usd_per_mtok,
2480            ]
2481            .into_iter()
2482            .flatten()
2483            .any(|v| !v.is_finite() || v < 0.0)
2484        })
2485    {
2486        return Err(HostCallError::Protocol("invalid model capabilities".into()));
2487    }
2488    Ok(result)
2489}
2490
2491/// Submit a conversation-scoped suggestion; the host returns its ID and keeps
2492/// the confirmation code in the user-delivery channel.
2493pub fn suggest(args: pbv1::SuggestArgs) -> Result<pbv1::SuggestResult, HostCallError> {
2494    let value = host_call("env.suggest", &args)?;
2495    let result: pbv1::SuggestResult = decode_host_value(&value, ".torana.v1.SuggestResult")?;
2496    if result.suggestion_id.is_empty() {
2497        return Err(HostCallError::Protocol("invalid suggestion result".into()));
2498    }
2499    Ok(result)
2500}
2501
2502/// Resolves one operator-bound prompt-cache-policy resource. The plugin names
2503/// only its declared slot; provider, model, routing, prices, and lifetime
2504/// semantics are owned by the binding.
2505pub fn get_prompt_cache_policy(resource: &str) -> Result<pbv1::PromptCachePolicy, HostCallError> {
2506    if !valid_resource_name(resource) {
2507        return Err(HostCallError::Protocol(
2508            "prompt cache policy resource is required".to_owned(),
2509        ));
2510    }
2511    let value = host_call(
2512        "env.cache_policy",
2513        &pbv1::PromptCachePolicyGetArgs {
2514            resource: resource.to_owned(),
2515        },
2516    )?;
2517    let policy: pbv1::PromptCachePolicy =
2518        decode_host_value(&value, ".torana.v1.PromptCachePolicy")?;
2519    validate_prompt_cache_policy(&policy)?;
2520    Ok(policy)
2521}
2522
2523fn valid_resource_name(value: &str) -> bool {
2524    let bytes = value.as_bytes();
2525    !bytes.is_empty()
2526        && bytes.len() <= 64
2527        && bytes.iter().enumerate().all(|(index, byte)| {
2528            byte.is_ascii_alphanumeric() || (index > 0 && matches!(byte, b'.' | b'_' | b'-'))
2529        })
2530}
2531
2532fn validate_prompt_cache_policy(policy: &pbv1::PromptCachePolicy) -> Result<(), HostCallError> {
2533    for rate in [
2534        policy.cache_read_usd_per_mtok,
2535        policy.cache_write_usd_per_mtok,
2536    ] {
2537        if rate.is_some_and(|value| !value.is_finite() || value < 0.0) {
2538            return Err(HostCallError::Protocol(
2539                "PromptCachePolicy rates must be finite and non-negative".to_owned(),
2540            ));
2541        }
2542    }
2543    if policy.cache_read_usd_per_mtok.is_none()
2544        && policy.cache_write_usd_per_mtok.is_none()
2545        && policy.tiers.is_empty()
2546    {
2547        return Err(HostCallError::Protocol(
2548            "PromptCachePolicy carries no prices or tiers".to_owned(),
2549        ));
2550    }
2551    if policy.warm_interval_seconds == Some(0) {
2552        return Err(HostCallError::Protocol(
2553            "PromptCachePolicy warm_interval_seconds must be positive when present".to_owned(),
2554        ));
2555    }
2556    if policy.warm_interval_seconds.is_some() && !policy.refresh_on_read {
2557        return Err(HostCallError::Protocol(
2558            "PromptCachePolicy warm_interval_seconds requires refresh_on_read".to_owned(),
2559        ));
2560    }
2561    let mut ttls = std::collections::BTreeSet::new();
2562    for tier in &policy.tiers {
2563        if tier.ttl_seconds == 0
2564            || tier
2565                .write_multiplier
2566                .is_some_and(|value| !value.is_finite() || value < 0.0)
2567            || !ttls.insert(tier.ttl_seconds)
2568        {
2569            return Err(HostCallError::Protocol(
2570                "PromptCachePolicy contains an invalid tier".to_owned(),
2571            ));
2572        }
2573        let marker: serde_json::Value = strict_json(&tier.marker_json).map_err(|_| {
2574            HostCallError::Protocol("PromptCachePolicy marker_json is invalid JSON".to_owned())
2575        })?;
2576        if !marker.is_object() {
2577            return Err(HostCallError::Protocol(
2578                "PromptCachePolicy marker_json must be an object".to_owned(),
2579            ));
2580        }
2581    }
2582    if let Some(interval) = policy.warm_interval_seconds {
2583        let shortest = policy
2584            .tiers
2585            .iter()
2586            .map(|tier| tier.ttl_seconds)
2587            .min()
2588            .unwrap_or(0);
2589        if shortest == 0 || interval >= shortest {
2590            return Err(HostCallError::Protocol(
2591                "PromptCachePolicy warm_interval_seconds must be below the shortest tier"
2592                    .to_owned(),
2593            ));
2594        }
2595    }
2596    Ok(())
2597}
2598
2599#[cfg(test)]
2600mod tests {
2601    use super::*;
2602
2603    #[test]
2604    fn route_applied_reads_host_observation() {
2605        let mut response = pbv1::ChatResponse::default();
2606        assert!(route_applied(&response).unwrap().is_none());
2607        response.torana_meta_json = br#"{"_route_applied":{"provider":"a","model":"m","verdict_plugin":"router","refused":null,"served_by":"b","served_model":"m","failover":true}}"#.to_vec();
2608        let route = route_applied(&response).unwrap().unwrap();
2609        assert_eq!(route.provider, "a");
2610        assert_eq!(route.served_by, "b");
2611        assert!(route.failover);
2612        response.torana_meta_json = br#"{"_route_applied":null}"#.to_vec();
2613        assert!(route_applied(&response).is_err());
2614    }
2615
2616    #[test]
2617    fn recoverable_tool_error_scrubs_content_and_is_idempotent() {
2618        let mut message = pbv1::Message {
2619            role: "user".into(),
2620            blocks: vec![pbv1::RequestBlock {
2621                kind: Some(pbv1::request_block::Kind::ToolResult(
2622                    pbv1::RequestToolResultBlock {
2623                        tool_call_id: "call-1".into(),
2624                        content: vec![
2625                            pbv1::ToolResultContentBlock {
2626                                kind: Some(pbv1::tool_result_content_block::Kind::Text(
2627                                    pbv1::ToolResultTextBlock { text: "one".into() },
2628                                )),
2629                            },
2630                            pbv1::ToolResultContentBlock {
2631                                kind: Some(pbv1::tool_result_content_block::Kind::CacheBreakpoint(
2632                                    pbv1::ToolResultCacheBreakpoint {
2633                                        marker_json: br#"{"type":"ephemeral","ttl":"5m"}"#.to_vec(),
2634                                    },
2635                                )),
2636                            },
2637                            pbv1::ToolResultContentBlock {
2638                                kind: Some(pbv1::tool_result_content_block::Kind::Text(
2639                                    pbv1::ToolResultTextBlock { text: "two".into() },
2640                                )),
2641                            },
2642                            pbv1::ToolResultContentBlock {
2643                                kind: Some(pbv1::tool_result_content_block::Kind::CacheBreakpoint(
2644                                    pbv1::ToolResultCacheBreakpoint {
2645                                        marker_json: br#"{"type":"ephemeral","ttl":"1h"}"#.to_vec(),
2646                                    },
2647                                )),
2648                            },
2649                        ],
2650                        signature: "signed".into(),
2651                        ..Default::default()
2652                    },
2653                )),
2654            }],
2655        };
2656
2657        assert!(replace_tool_result_with_error(&mut message, 0, "withheld").unwrap());
2658        let Some(pbv1::request_block::Kind::ToolResult(result)) = message.blocks[0].kind.as_ref()
2659        else {
2660            panic!("missing tool result")
2661        };
2662        assert_eq!(result.is_error, Some(true));
2663        assert!(result.signature.is_empty());
2664        assert_eq!(result.content.len(), 4);
2665        let Some(pbv1::tool_result_content_block::Kind::Text(text)) =
2666            result.content[0].kind.as_ref()
2667        else {
2668            panic!("missing replacement text")
2669        };
2670        assert_eq!(text.text, "withheld");
2671        assert!(matches!(
2672            result.content[1].kind,
2673            Some(pbv1::tool_result_content_block::Kind::CacheBreakpoint(_))
2674        ));
2675        assert!(matches!(
2676            result.content[2].kind,
2677            Some(pbv1::tool_result_content_block::Kind::Text(_))
2678        ));
2679        assert!(matches!(
2680            result.content[3].kind,
2681            Some(pbv1::tool_result_content_block::Kind::CacheBreakpoint(_))
2682        ));
2683        assert!(!replace_tool_result_with_error(&mut message, 0, "withheld").unwrap());
2684    }
2685
2686    // CI has run `cargo test` on this crate all along, against zero tests — so
2687    // the green tick meant only that the crate compiled. These cover the ABI
2688    // plumbing that every hook goes through.
2689    //
2690    // They exercise the pointer-level halves rather than the extern "C"
2691    // wrappers, because off wasm32 a real pointer does not fit in the u32 the
2692    // ABI uses and `ptr as u32` would truncate it.
2693
2694    #[test]
2695    fn alloc_dealloc_round_trip() {
2696        for size in [1usize, 7, 64, 4096] {
2697            let p = alloc_bytes(size);
2698            assert!(!p.is_null(), "alloc_bytes({size}) returned null");
2699
2700            // Write and read back every byte. This does NOT prove the layout
2701            // was large enough — it cannot, since both use the same `size` —
2702            // but it does exercise the alloc/write/read/free cycle, and a
2703            // dealloc whose layout disagreed with the allocation corrupts the
2704            // allocator, which the repeated cycles below surface.
2705            unsafe { ptr::write_bytes(p, 0xAB, size) };
2706            let seen = unsafe { slice::from_raw_parts(p, size) };
2707            assert!(seen.iter().all(|&b| b == 0xAB));
2708
2709            // Frees with a layout built the same way it was allocated. This is
2710            // the pairing the Vec::with_capacity version only got right by
2711            // coincidence.
2712            dealloc_bytes(p, size);
2713        }
2714    }
2715
2716    // Repeated alloc/free at varying sizes. A dealloc whose Layout disagreed
2717    // with the allocation corrupts allocator bookkeeping, and the corruption
2718    // shows up on a later allocation rather than at the bad free — so the loop
2719    // is the point.
2720    #[test]
2721    fn repeated_alloc_free_cycles_do_not_corrupt_the_allocator() {
2722        for round in 0..64 {
2723            let size = 1 + (round * 37) % 4096;
2724            let p = alloc_bytes(size);
2725            assert!(!p.is_null());
2726            unsafe { ptr::write_bytes(p, round as u8, size) };
2727            let seen = unsafe { slice::from_raw_parts(p, size) };
2728            assert!(
2729                seen.iter().all(|&b| b == round as u8),
2730                "round {round} readback"
2731            );
2732            dealloc_bytes(p, size);
2733        }
2734    }
2735
2736    #[test]
2737    fn empty_payload_is_the_only_pass_through() {
2738        // The ABI reserves 0 for a deliberate no-op. Anything non-empty must
2739        // produce a real buffer; allocation failure traps instead of landing
2740        // here as a 0 the host would read as "plugin made no change".
2741        assert_eq!(__result(&[]), 0);
2742        assert_ne!(__result(&[0u8]), 0);
2743    }
2744
2745    #[test]
2746    fn zero_size_allocation_is_a_null_pointer() {
2747        // Zero is the ABI's "no buffer" signal, and a zero-sized layout would
2748        // be undefined behaviour to pass to the allocator.
2749        assert!(alloc_bytes(0).is_null());
2750        assert_eq!(alloc(0), 0);
2751    }
2752
2753    #[test]
2754    fn dealloc_tolerates_null_and_zero() {
2755        dealloc_bytes(ptr::null_mut(), 16);
2756        dealloc_bytes(ptr::null_mut(), 0);
2757        dealloc(0, 16);
2758    }
2759
2760    #[test]
2761    fn pack_puts_the_pointer_high_and_the_length_low() {
2762        assert_eq!(pack(0x0000_1234, 0x0000_0056), 0x0000_1234_0000_0056);
2763        // The full u32 range must survive: a sign-extending cast would corrupt
2764        // any pointer above 2GiB, which is reachable in a 4GiB wasm memory.
2765        assert_eq!(pack(0xFFFF_FFFF, 0xFFFF_FFFF), 0xFFFF_FFFF_FFFF_FFFF);
2766        assert_eq!(pack(0x8000_0000, 1), 0x8000_0000_0000_0001);
2767    }
2768
2769    #[test]
2770    fn empty_result_is_pass_through() {
2771        // Zero is reserved by the ABI for "the plugin made no change".
2772        assert_eq!(__result(&[]), 0);
2773    }
2774
2775    #[test]
2776    fn result_copies_the_payload_verbatim() {
2777        // Every byte value, so a copy that dropped or mangled one is visible.
2778        let payload: Vec<u8> = (0u8..=255).collect();
2779
2780        let (p, len) = copy_to_owned_buffer(&payload);
2781        assert!(!p.is_null());
2782        assert_eq!(len, payload.len());
2783
2784        let copied = unsafe { slice::from_raw_parts(p, len) };
2785        assert_eq!(copied, payload.as_slice());
2786
2787        dealloc_bytes(p, len);
2788    }
2789
2790    #[test]
2791    fn copying_nothing_yields_no_buffer() {
2792        let (p, len) = copy_to_owned_buffer(&[]);
2793        assert!(p.is_null());
2794        assert_eq!(len, 0);
2795    }
2796
2797    #[test]
2798    fn input_of_an_empty_or_null_buffer_is_an_empty_slice() {
2799        // SAFETY: zero-length/null inputs are explicitly accepted without a
2800        // dereference by the ABI helper.
2801        unsafe {
2802            assert!(__input(0, 0).is_empty());
2803            assert!(__input(0, 10).is_empty());
2804            assert!(__input(10, 0).is_empty());
2805        }
2806    }
2807
2808    fn pass(_input: pbv1::HookInput) -> Result<Option<pbv1::HookResult>, String> {
2809        Ok(None)
2810    }
2811
2812    fn replace(input: pbv1::HookInput) -> Result<Option<pbv1::HookResult>, String> {
2813        let request = match input.payload {
2814            Some(pbv1::hook_input::Payload::ChatRequest(request)) => request,
2815            _ => return Err("wrong payload".to_owned()),
2816        };
2817        Ok(Some(pbv1::HookResult {
2818            action: Some(pbv1::hook_result::Action::ReplaceRequest(request)),
2819        }))
2820    }
2821
2822    fn wrong_action(_input: pbv1::HookInput) -> Result<Option<pbv1::HookResult>, String> {
2823        Ok(Some(pbv1::HookResult {
2824            action: Some(pbv1::hook_result::Action::Suppress(pbv1::Suppress {})),
2825        }))
2826    }
2827
2828    fn before_request_input() -> Vec<u8> {
2829        use prost::Message;
2830        pbv1::HookInput {
2831            contract_revision: 1,
2832            request_id: 7,
2833            execution: None,
2834            payload: Some(pbv1::hook_input::Payload::ChatRequest(pbv1::ChatRequest {
2835                model: "rust-v1".to_owned(),
2836                ..Default::default()
2837            })),
2838        }
2839        .encode_to_vec()
2840    }
2841
2842    #[test]
2843    fn v1_pass_through_is_exactly_empty_output() {
2844        assert_eq!(
2845            __dispatch_v1(&before_request_input(), HOOK_BEFORE_REQUEST, pass).unwrap(),
2846            Vec::<u8>::new()
2847        );
2848    }
2849
2850    #[test]
2851    fn v1_replacement_round_trips_through_the_single_action_envelope() {
2852        use prost::Message;
2853        let output = __dispatch_v1(&before_request_input(), HOOK_BEFORE_REQUEST, replace).unwrap();
2854        let result = pbv1::HookResult::decode(output.as_slice()).unwrap();
2855        let Some(pbv1::hook_result::Action::ReplaceRequest(request)) = result.action else {
2856            panic!("expected replace_request")
2857        };
2858        assert_eq!(request.model, "rust-v1");
2859    }
2860
2861    #[test]
2862    fn v1_dispatch_rejects_undeclared_and_mismatched_hooks() {
2863        let err = __dispatch_v1(&before_request_input(), HOOK_ON_TICK, pass).unwrap_err();
2864        assert!(err.contains("unregistered"), "{err}");
2865        let err =
2866            __dispatch_v1(&before_request_input(), HOOK_BEFORE_REQUEST, wrong_action).unwrap_err();
2867        assert!(err.contains("does not match"), "{err}");
2868    }
2869
2870    #[test]
2871    fn v1_host_call_result_keeps_empty_success_distinct_from_refusal() {
2872        use prost::Message;
2873        let success = pbv1::HostCallResult {
2874            result: Some(pbv1::host_call_result::Result::Value(Vec::new())),
2875        };
2876        assert_eq!(
2877            decode_host_call_result(&success.encode_to_vec()).unwrap(),
2878            Vec::<u8>::new()
2879        );
2880
2881        let refusal = pbv1::HostCallResult {
2882            result: Some(pbv1::host_call_result::Result::Error(pbv1::HostError {
2883                code: pbv1::ErrorCode::PermissionDenied as i32,
2884                message: "diagnostic only".to_owned(),
2885            })),
2886        };
2887        assert_eq!(
2888            decode_host_call_result(&refusal.encode_to_vec()),
2889            Err(HostCallError::Refused(pbv1::HostError {
2890                code: pbv1::ErrorCode::PermissionDenied as i32,
2891                message: "diagnostic only".to_owned(),
2892            }))
2893        );
2894    }
2895
2896    #[test]
2897    fn v1_host_call_result_rejects_empty_and_unclassified_frames() {
2898        use prost::Message;
2899        let err = decode_host_call_result(&[]).unwrap_err();
2900        assert!(matches!(err, HostCallError::Protocol(_)));
2901
2902        for code in [pbv1::ErrorCode::Unspecified as i32, 99] {
2903            let frame = pbv1::HostCallResult {
2904                result: Some(pbv1::host_call_result::Result::Error(pbv1::HostError {
2905                    code,
2906                    message: String::new(),
2907                })),
2908            }
2909            .encode_to_vec();
2910            assert!(matches!(
2911                decode_host_call_result(&frame),
2912                Err(HostCallError::Protocol(_))
2913            ));
2914        }
2915
2916        // Unknown top-level field 3, length-delimited empty payload. Prost
2917        // normally discards it, but the v1 contract treats it as a future
2918        // result arm this build cannot classify.
2919        assert!(matches!(
2920            decode_host_call_result(&[0x1a, 0x00]),
2921            Err(HostCallError::Protocol(_))
2922        ));
2923    }
2924
2925    fn native_value(value: Vec<u8>) -> Result<Vec<u8>, HostCallError> {
2926        Ok(pbv1::HostCallResult {
2927            result: Some(pbv1::host_call_result::Result::Value(value)),
2928        }
2929        .encode_to_vec())
2930    }
2931
2932    #[test]
2933    fn option_getters_distinguish_not_found_from_empty() {
2934        use std::cell::Cell;
2935        let calls = Cell::new(0);
2936        let _guard = install_native_host(move |_, _| {
2937            let call = calls.get();
2938            calls.set(call + 1);
2939            if call == 0 {
2940                Ok(pbv1::HostCallResult {
2941                    result: Some(pbv1::host_call_result::Result::Error(pbv1::HostError {
2942                        code: pbv1::ErrorCode::NotFound as i32,
2943                        message: "missing".into(),
2944                    })),
2945                }
2946                .encode_to_vec())
2947            } else {
2948                native_value(Vec::new())
2949            }
2950        });
2951        assert_eq!(meta_get("key").unwrap(), None);
2952        assert_eq!(meta_get("key").unwrap(), Some(String::new()));
2953    }
2954
2955    #[test]
2956    fn nested_native_host_guards_restore_the_previous_transport() {
2957        let outer = install_native_host(|command, _| native_value(command.as_bytes().to_vec()));
2958        assert_eq!(
2959            host_call("env.plugin_config", &EmptyArgs {}).unwrap(),
2960            b"env.plugin_config"
2961        );
2962        {
2963            let _inner = install_native_host(|_, _| native_value(b"inner".to_vec()));
2964            assert_eq!(
2965                host_call("env.plugin_config", &EmptyArgs {}).unwrap(),
2966                b"inner"
2967            );
2968        }
2969        assert_eq!(
2970            host_call("env.plugin_config", &EmptyArgs {}).unwrap(),
2971            b"env.plugin_config"
2972        );
2973        drop(outer);
2974        assert!(matches!(
2975            host_call("env.plugin_config", &EmptyArgs {}),
2976            Err(HostCallError::Protocol(message)) if message.contains("no native host transport")
2977        ));
2978    }
2979
2980    #[test]
2981    fn failed_cache_breakpoint_move_preserves_the_message() {
2982        let mut message = pbv1::Message {
2983            role: "user".into(),
2984            blocks: vec![pbv1::RequestBlock {
2985                kind: Some(pbv1::request_block::Kind::Text(pbv1::RequestTextBlock {
2986                    text: "keep".into(),
2987                    ..Default::default()
2988                })),
2989            }],
2990        };
2991        let before = message.clone();
2992        assert_eq!(
2993            move_cache_breakpoint(&mut message, 0, 1),
2994            Err("block is not cache breakpoint".into())
2995        );
2996        assert_eq!(message, before);
2997    }
2998
2999    #[test]
3000    fn packed_numeric_payload_validation_rejects_truncation() {
3001        for scalar_wire in [0, 1, 5] {
3002            assert!(accepts_wire_type(true, scalar_wire, scalar_wire));
3003            assert!(accepts_wire_type(true, scalar_wire, 2));
3004            assert!(!accepts_wire_type(false, scalar_wire, 2));
3005        }
3006        assert!(validate_packed_field(&[1, 0xac, 0x02], 0).is_ok());
3007        assert!(validate_packed_field(&[0x80], 0).is_err());
3008        assert!(validate_packed_field(&[0; 8], 1).is_ok());
3009        assert!(validate_packed_field(&[0; 7], 1).is_err());
3010        assert!(validate_packed_field(&[0; 4], 5).is_ok());
3011        assert!(validate_packed_field(&[0; 3], 5).is_err());
3012    }
3013
3014    fn synthetic_wire_descriptor() -> prost_types::FileDescriptorSet {
3015        use prost_types::{
3016            field_descriptor_proto::{Label, Type},
3017            DescriptorProto, FieldDescriptorProto, FileDescriptorProto, FileDescriptorSet,
3018        };
3019        let field =
3020            |name: &str, number: i32, kind: Type, repeated: bool, type_name: Option<&str>| {
3021                FieldDescriptorProto {
3022                    name: Some(name.into()),
3023                    number: Some(number),
3024                    label: Some(if repeated {
3025                        Label::Repeated
3026                    } else {
3027                        Label::Optional
3028                    } as i32),
3029                    r#type: Some(kind as i32),
3030                    type_name: type_name.map(Into::into),
3031                    ..Default::default()
3032                }
3033            };
3034        FileDescriptorSet {
3035            file: vec![FileDescriptorProto {
3036                package: Some("test".into()),
3037                syntax: Some("proto3".into()),
3038                message_type: vec![
3039                    DescriptorProto {
3040                        name: Some("Packed".into()),
3041                        field: vec![
3042                            field("numbers", 1, Type::Int32, true, None),
3043                            field("modes", 2, Type::Enum, true, Some(".test.Mode")),
3044                        ],
3045                        ..Default::default()
3046                    },
3047                    DescriptorProto {
3048                        name: Some("Node".into()),
3049                        field: vec![field("child", 1, Type::Message, false, Some(".test.Node"))],
3050                        ..Default::default()
3051                    },
3052                ],
3053                ..Default::default()
3054            }],
3055        }
3056    }
3057
3058    #[test]
3059    fn descriptor_backed_scanner_accepts_packed_and_unpacked_numeric_fields() {
3060        let set = synthetic_wire_descriptor();
3061        for valid in [
3062            &[0x08, 0x01, 0x08, 0xac, 0x02][..],
3063            &[0x0a, 0x03, 0x01, 0xac, 0x02],
3064            &[0x10, 0x00, 0x10, 0x01],
3065            &[0x12, 0x02, 0x00, 0x01],
3066        ] {
3067            validate_wire_message_with_set(valid, ".test.Packed", &set, 1).unwrap();
3068        }
3069        for malformed in [&[0x0a, 0x01, 0x80][..], &[0x0d, 0, 0, 0, 0]] {
3070            assert!(validate_wire_message_with_set(malformed, ".test.Packed", &set, 1).is_err());
3071        }
3072    }
3073
3074    fn nested_message(levels: usize) -> Vec<u8> {
3075        let mut message = Vec::new();
3076        for _ in 0..levels {
3077            let mut wrapped = vec![0x0a];
3078            let mut len = message.len() as u64;
3079            loop {
3080                let mut byte = (len & 0x7f) as u8;
3081                len >>= 7;
3082                if len != 0 {
3083                    byte |= 0x80;
3084                }
3085                wrapped.push(byte);
3086                if len == 0 {
3087                    break;
3088                }
3089            }
3090            wrapped.extend_from_slice(&message);
3091            message = wrapped;
3092        }
3093        message
3094    }
3095
3096    #[test]
3097    fn descriptor_backed_scanner_bounds_message_depth_including_root() {
3098        let set = synthetic_wire_descriptor();
3099        validate_wire_message_with_set(&nested_message(99), ".test.Node", &set, 1).unwrap();
3100        let error = validate_wire_message_with_set(&nested_message(100), ".test.Node", &set, 1)
3101            .unwrap_err();
3102        assert!(error.contains("nesting exceeds 100"), "{error}");
3103    }
3104
3105    #[test]
3106    fn state_keys_uses_empty_args_and_host_json_shape() {
3107        let _guard = install_native_host(|command, arguments| {
3108            assert_eq!(command, "env.state_keys");
3109            assert!(
3110                arguments.is_empty(),
3111                "Empty protobuf arguments must encode empty"
3112            );
3113            native_value(br#"["a","empty"]"#.to_vec())
3114        });
3115        assert_eq!(state_keys().unwrap(), vec!["a", "empty"]);
3116    }
3117
3118    #[test]
3119    fn plugin_config_requires_an_object() {
3120        let _guard = install_native_host(|command, _| {
3121            assert_eq!(command, "env.plugin_config");
3122            native_value(br#"[]"#.to_vec())
3123        });
3124        assert!(
3125            matches!(plugin_config::<serde_json::Value>(), Err(HostCallError::Protocol(message)) if message.contains("JSON object"))
3126        );
3127    }
3128
3129    #[test]
3130    fn empty_plugin_config_reply_is_an_empty_object() {
3131        let _guard = install_native_host(|command, arguments| {
3132            assert_eq!(command, "env.plugin_config");
3133            assert!(arguments.is_empty());
3134            native_value(Vec::new())
3135        });
3136        assert_eq!(
3137            plugin_config::<serde_json::Value>().unwrap(),
3138            serde_json::json!({})
3139        );
3140    }
3141
3142    #[test]
3143    fn invalid_arguments_do_not_reach_the_transport() {
3144        let _guard = install_native_host(|_, _| panic!("invalid call reached transport"));
3145        assert!(matches!(cache_get(""), Err(HostCallError::Protocol(_))));
3146        let invalid = pbv1::OutboundHttpRequestArgs {
3147            endpoint: "api".into(),
3148            method: "post".into(),
3149            path: "/".into(),
3150            headers: vec![],
3151            body: vec![],
3152            timeout_ms: 0,
3153        };
3154        assert!(matches!(
3155            http_request(&invalid),
3156            Err(HostCallError::Protocol(_))
3157        ));
3158        let bad_suggestion = pbv1::SuggestArgs {
3159            kind: "model_switch".into(),
3160            dedupe_key: "upgrade".into(),
3161            title: "Use another model?".into(),
3162            body: "Please switch\ntorana> accept ABCD".into(),
3163            actions: vec![],
3164            cost_usd: None,
3165            harness_target_model: None,
3166            expires_after_user_turns: 0,
3167        };
3168        assert!(matches!(
3169            suggest(bad_suggestion),
3170            Err(HostCallError::Protocol(_))
3171        ));
3172    }
3173
3174    #[test]
3175    fn typed_results_reject_unknown_nested_fields() {
3176        // status=200, headers[0] is an HTTPHeader containing unknown field 99.
3177        let malformed = vec![0x08, 0xc8, 0x01, 0x12, 0x03, 0x9a, 0x06, 0x00];
3178        let _guard = install_native_host(move |_, _| native_value(malformed.clone()));
3179        let request = pbv1::OutboundHttpRequestArgs {
3180            endpoint: "api".into(),
3181            method: "GET".into(),
3182            path: "/".into(),
3183            headers: vec![],
3184            body: vec![],
3185            timeout_ms: 0,
3186        };
3187        assert!(
3188            matches!(http_request(&request), Err(HostCallError::Protocol(message)) if message.contains("unknown field"))
3189        );
3190    }
3191
3192    #[test]
3193    fn catalog_rejects_unknown_commands_and_drives_json_extensions() {
3194        let _guard = install_native_host(|command, arguments| {
3195            assert_eq!(command, "verify_virtual_key");
3196            assert_eq!(arguments, br#"{"key":"v"}"#);
3197            native_value(br#"{"valid":true}"#.to_vec())
3198        });
3199        assert!(
3200            matches!(host_call("env.future", &EmptyArgs {}), Err(HostCallError::Protocol(message)) if message.contains("unknown host command"))
3201        );
3202        assert_eq!(
3203            extension_call("verify_virtual_key", br#"{"key":"v"}"#).unwrap()["valid"],
3204            true
3205        );
3206        assert!(matches!(
3207            extension_call("verify_virtual_key", b"[]"),
3208            Err(HostCallError::Protocol(_))
3209        ));
3210    }
3211
3212    #[test]
3213    fn resource_names_match_the_typed_host_contract() {
3214        for valid in ["cache", "request-cache", "a.b_c", "A1"] {
3215            assert!(valid_resource_name(valid), "{valid}");
3216        }
3217        for invalid in ["", "-cache", "../cache", "cache/name", "caché"] {
3218            assert!(!valid_resource_name(invalid), "{invalid}");
3219        }
3220        assert!(!valid_resource_name(&"a".repeat(65)));
3221    }
3222
3223    #[test]
3224    fn prompt_cache_policy_validation_rejects_unusable_results() {
3225        let valid = pbv1::PromptCachePolicy {
3226            cache_read_usd_per_mtok: Some(0.1),
3227            cache_write_usd_per_mtok: Some(1.25),
3228            refresh_on_read: true,
3229            tiers: vec![pbv1::PromptCacheTier {
3230                ttl_seconds: 300,
3231                write_multiplier: Some(1.25),
3232                marker_json: br#"{"type":"ephemeral"}"#.to_vec(),
3233            }],
3234            warm_interval_seconds: Some(240),
3235        };
3236        validate_prompt_cache_policy(&valid).unwrap();
3237
3238        let mut invalid = valid.clone();
3239        invalid.tiers[0].marker_json = b"[]".to_vec();
3240        assert!(validate_prompt_cache_policy(&invalid).is_err());
3241        let mut invalid = valid.clone();
3242        invalid.tiers[0].ttl_seconds = 0;
3243        assert!(validate_prompt_cache_policy(&invalid).is_err());
3244        let mut invalid = valid;
3245        invalid.warm_interval_seconds = Some(300);
3246        assert!(validate_prompt_cache_policy(&invalid).is_err());
3247    }
3248}