1use 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#[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
44pub 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
72pub 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
96pub 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
113pub const ABI_VERSION: u64 = (1u64 << 32) | 1;
116
117pub const fn abi_version() -> u64 {
118 ABI_VERSION
119}
120
121#[derive(Clone, Debug, PartialEq, Eq)]
123pub enum HostCallError {
124 Refused(pbv1::HostError),
126 Protocol(String),
128}
129
130pub 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
232pub 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
353pub 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
503pub 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
515pub 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
639fn 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 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#[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#[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 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
1218pub 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#[no_mangle]
1254pub extern "C" fn alloc(size: u32) -> u32 {
1255 alloc_bytes(size as usize) as u32
1256}
1257
1258#[no_mangle]
1261pub extern "C" fn dealloc(ptr: u32, size: u32) {
1262 dealloc_bytes(ptr as *mut u8, size as usize);
1263}
1264
1265fn alloc_bytes(size: usize) -> *mut u8 {
1269 if size == 0 {
1270 return ptr::null_mut();
1273 }
1274 let Ok(layout) = Layout::array::<u8>(size) else {
1275 std::process::abort();
1278 };
1279 let p = unsafe { std::alloc::alloc(layout) };
1280 if p.is_null() {
1281 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#[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#[doc(hidden)]
1319pub fn __result(bytes: &[u8]) -> u64 {
1320 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
1331fn copy_to_owned_buffer(bytes: &[u8]) -> (*mut u8, usize) {
1337 if bytes.is_empty() {
1338 return (ptr::null_mut(), 0);
1339 }
1340 let dst = alloc_bytes(bytes.len());
1342 unsafe { ptr::copy_nonoverlapping(bytes.as_ptr(), dst, bytes.len()) };
1347 (dst, bytes.len())
1348}
1349
1350fn 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
1367pub 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
1474pub 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 let bytes = unsafe { __input(ptr, len) }.to_vec();
1525 dealloc(ptr, len);
1526 decode_host_call_result(&bytes)
1527 }
1528}
1529
1530pub 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
1740pub 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}
2043pub 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
2357pub 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
2417pub 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
2447pub 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
2491pub 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
2502pub 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 #[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 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 dealloc_bytes(p, size);
2713 }
2714 }
2715
2716 #[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 assert_eq!(__result(&[]), 0);
2742 assert_ne!(__result(&[0u8]), 0);
2743 }
2744
2745 #[test]
2746 fn zero_size_allocation_is_a_null_pointer() {
2747 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 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 assert_eq!(__result(&[]), 0);
2773 }
2774
2775 #[test]
2776 fn result_copies_the_payload_verbatim() {
2777 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 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 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 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}