Skip to main content

Crate torana_plugin_sdk

Crate torana_plugin_sdk 

Source
Expand description

Rust bindings and WASI Preview 1 trampolines for Torana Plugin ABI v1.

The SDK deliberately exposes only the host calls granted by Torana. A plugin cannot gain a capability by importing a function that the operator did not grant.

Modules§

pbv1

Macros§

export_plugin_v1
Exports the two functions required by ABI v1: supported_hooks and run_hook. The handler receives the typed HookInput and returns Ok(None) for pass-through or one hook-appropriate HookResult.

Structs§

AssembledToolCall
HttpConversationBinding
Host-owned MCP evidence. A session identity is not a plugin’s thread/state key.
HttpResult
NativeHostGuard
Installs a native transport for the duration of a test. The guard restores the previous transport on drop and storage is thread-local.
RequestResult
ResponseResult
RouteAppliedInfo
Host observation for a plugin route verdict. The selected route and the eventual upstream can differ after failover.
StreamAssembler
StreamFeed
StreamHandler
StreamResult
SuggestionOutcome
TickResult

Enums§

HostCallError
Error returned by an ABI-v1 host call.
LogLevel
MetricKind

Constants§

ABI_VERSION
Runtime ABI contract identifier. The high 32 bits are the ABI epoch and the low 32 bits are the contract revision within that epoch.
HOOK_AFTER_RESPONSE
HOOK_BEFORE_REQUEST
ABI-v1 hook bitmap bits. Bit N corresponds to pbv1::Hook value N.
HOOK_ON_HTTP_REQUEST
HOOK_ON_STREAM_CHUNK
HOOK_ON_TICK
LOG_DEBUG
LOG_INFO
METRIC_COUNTER
METRIC_GAUGE
METRIC_HISTOGRAM

Traits§

Plugin
Typed plugin callbacks cannot return another hook family’s result:

Functions§

__plugin_dispatch
abi_version
alloc
Allocates size bytes and returns a host-visible pointer.
append_file
block_request
cache_delete
cache_get
cache_set
counter
dealloc
Frees a buffer previously returned by alloc. size must be the size that was passed to alloc.
debug
decode_host_call_result
delete_file
emit_events
emit_metric
Emits a metric on a best-effort void host import.
execution
extension_call
Calls one catalogued JSON extension through the same ABI transport as typed protobuf helpers. Both arguments and JSON results use strict object shape.
gauge
get_credential
Resolves one operator-bound credential slot. Treat the returned bytes as a secret and do not place them in logs or diagnostic errors.
get_model_capabilities
Read capabilities for an operator-declared model; unknown models receive a typed host refusal.
get_model_pricing
Resolves one operator-bound pricing resource. None means an unknown rate; Some(0.0) is an explicitly free rate.
get_prompt_cache_policy
Resolves one operator-bound prompt-cache-policy resource. The plugin names only its declared slot; provider, model, routing, prices, and lifetime semantics are owned by the binding.
get_resource_info
histogram
hook_of
Returns the hook selected by a valid ABI-v1 input envelope.
host_call
Invokes a host command with protobuf arguments and decodes the ABI-v1 HostCallResult envelope. Empty successful values remain distinguishable from typed refusals; callers must branch on HostCallError::Refused’s code, never its diagnostic message.
http_conversation
Read only from the request supplied to Plugin::on_http. This validates the envelope, not provenance; model arguments and caller-created headers are not trusted evidence. None means ordinary HTTP; Some with bound=false means MCP explicitly reported an unbound call. Neither authorizes scoped state access.
http_request
info
install_native_host
list_files
log
Logs a bounded diagnostic string when the host granted env.log. Delivery is best effort: the void ABI import cannot report refusal.
meta_append
meta_get
meta_set
model_complete
Invokes one operator-bound model-service slot. Provider, URL, model, credentials, and hard budgets are owned by the binding, not by the plugin.
model_complete_text
move_cache_breakpoint
pass_event
pass_http
pass_request
pass_response
pass_tick
plugin_config
read_file
replace_request
replace_response
replace_tool_result_text
replace_tool_result_with_error
Replaces a tool result with one safe text arm per cache-delimited segment and marks the result as an explicit tool error. Cache markers are preserved byte-for-byte and in their original relative order. Validation completes before mutation.
request_id
respond_request
respond_text
route_applied
Read the optional host-owned route observation on an after-response hook.
route_request
route_request_with_effort
Route with an explicitly operator-authorized effort. UNSPECIFIED leaves the harness’s effort untouched. The route is atomic: if the host refuses the effort, it does not apply the provider or model change either. Handle a refusal explicitly, for example by retrying with route_request (no effort) or passing. Return the error only if the request should fail under the plugin’s failure_mode.
serve_http
set_cache_breakpoint
set_identity
set_text_at
shared_cache_delete
shared_cache_get
shared_cache_set
state_compare_and_delete
state_compare_and_set
state_delete
state_get
state_get_versioned
state_keys
state_scan
state_set
suggest
Submit a conversation-scoped suggestion; the host returns its ID and keeps the confirmation code in the user-delivery channel.
suggestions
Read host-owned outcomes scoped to this plugin, never provider-visible.
tick_outcome
torana_mcp
Read the host’s MCP-connection observation when one has been published.
write_file