Crate tea_protocol

Expand description

Canonical, provider-neutral protocol types for agent runtimes.

Protocol compatibility is versioned independently from this crate’s semantic version. This crate contains data and validation only; it does not perform model requests, tool execution, policy evaluation, or persistence.

§Example

use std::str::FromStr;

use tea_protocol::{
    AgentCommand, CommandEnvelope, CommandId, ProfileId, ProtocolMetadata,
    ProtocolTimestamp,
};

let command = CommandEnvelope::new(
    CommandId::from_str("0195a0b1-5e3b-7ef0-8ec1-0aa7aa000001")?,
    None,
    ProtocolTimestamp::from_str("2026-07-23T09:30:12.123Z")?,
    AgentCommand::CreateSession {
        profile_id: ProfileId::from_str("minimal-assistant")?,
        metadata: ProtocolMetadata::default(),
    },
)?;

let json = serde_json::to_string(&command)?;
assert!(json.contains(r#""type":"create_session""#));

Structs§

ApprovalId: A stable approval request identifier.
BranchId: A stable session branch identifier.
CausationId: A stable identifier for the command or record that caused a fact.
CodeChange: Bounded, structured presentation of one changed file.
CodeChangeHunk: One grouped hunk of a code-change presentation.
CodeChangeLine: One bounded, line-numbered source line in a diff hunk.
CommandEnvelope: A versioned command transport envelope.
CommandId: A stable command identifier.
CommandText: Bounded command text that rejects controls unsafe for logs and transports.
CorrelationId: A stable diagnostic correlation identifier.
CurrencyCode: A three-letter uppercase ISO-style currency code.
CurrencyCodeParseError: Error returned when parsing a currency code.
DecimalAmount: A canonical, non-negative decimal amount encoded as text.
EventEnvelope: A versioned observable event envelope.
EventId: A stable observable event identifier.
ExactCost: An exact persisted monetary amount.
ExternalSource: A normalized external source returned by search or another hosted tool.
HostedToolActivity: One complete provider-hosted tool activity retained in assistant content.
HostedToolError: Provider-reported hosted tool failure.
MessageId: A stable canonical message identifier.
ModelId: A bounded canonical model selector.
ModelRef: Complete canonical identity of one model advertised by one provider.
ProfileId: A bounded product profile selector.
ProtocolError: A safe, localizable protocol error payload.
ProtocolErrorEnvelope: Versioned protocol-error transport envelope.
ProtocolMetadata: Bounded extension metadata keyed by collision-resistant namespaces.
ProtocolTimestamp: An RFC 3339 timestamp normalized to UTC with millisecond precision.
ProtocolVersion: A canonical major.minor agent protocol version.
ProviderContinuation: Bounded provider-owned data needed to reconstruct a later request.
ProviderId: A bounded canonical model-provider selector.
ReasoningEffortParseError: Error returned for an unknown reasoning effort spelling.
RecordEnvelope: Versioned durable session-record envelope.
RecordId: A stable durable session record identifier.
RunId: A stable agent run identifier.
SessionId: A stable agent session identifier.
SessionSequence: A monotonically increasing, session-local record or event sequence.
SourceCitation: A normalized citation associated with assistant text and an external source.
TokenCount: A token count safe to encode as a JSON number for JavaScript consumers.
ToolCallId: A stable canonical tool-call identifier.
ToolFailure: Machine-readable failure returned by a tool.
TurnId: A stable agent turn identifier.
UnknownSkippableEvent: Validated common fields retained when skipping an unknown observation.
Usage: Provider-neutral token usage.
WebFetchPresentation: Bounded provider-neutral presentation of one client web-fetch result.
WebFetchRedirect: One bounded redirect in a normalized client web-fetch result.

Enums§

AgentCommand: A provider- and transport-neutral agent command payload.
AgentCommandType: Stable initial command discriminators.
AgentErrorCode: Stable machine-readable protocol error code.
AgentEvent: A provider- and UI-neutral observable runtime event.
AgentEventType: Stable known event discriminators.
ApprovalDecision: A user decision for a pending approval.
CanonicalMessage: A provider-neutral conversation message.
CodeChangeKind: Kind of file change represented by a code-change presentation.
CodeChangeLineKind: Kind of one line in a code-change hunk.
CodeChangeTruncation: Reason a code-change presentation was deterministically truncated.
CodeChangeValidationError: Validation failure for a structured code-change presentation.
CommandDecodeError: Failure while decoding an untrusted command envelope.
CommandValidationError: Error returned when validating command data.
ContentBlock: A provider-neutral message content block.
ContentValidationError: Error returned when validating content blocks.
CostUnit: Unit used by exact currency amounts.
DecimalAmountParseError: Error returned when parsing an exact decimal amount.
EventCompatibility: Compatibility classification for observable events.
EventDecodeError: Failure while inspecting an untrusted observable event.
EventDelta: A bounded streaming content delta.
EventInspection: Result of inspecting a known or forward-compatible observable event.
EventValidationError: Error returned when validating event data.
ExecutionTarget: Tool executor boundary used for a durable invocation.
ExternalContentError: Validation failure for hosted tool, source, citation, or continuation content.
HostedToolOutcome: Terminal provider-hosted tool outcome.
ImageSource: Source of an image content block.
MessageRole: Role of a canonical message.
MessageValidationError: Error returned when validating canonical messages.
NextTurnAction: Kernel action allowed after a durable turn checkpoint.
PolicyDecision: Policy outcome persisted before an approval or execution transition.
ProtocolErrorValidationError: Error returned when validating a safe protocol error.
ProtocolIdParseError: Error returned when parsing a canonical protocol identifier.
ProtocolMetadataError: Error returned when validating extension metadata.
ProtocolTimestampParseError: Error returned when parsing a protocol timestamp.
ProtocolVersionParseError: Error returned when parsing a protocol version.
ReasoningEffort: Provider-neutral reasoning effort ordered from disabled to maximum.
RecordDecodeError: Failure while decoding an untrusted durable record.
RecordValidationError: Error returned when validating a durable record payload.
RetryClass: Whether and how a caller may retry an operation.
RunStatus: Terminal status of an observable run.
SelectorParseError: Error returned when parsing a model or profile selector.
SessionRecord: A typed durable fact used for deterministic session replay.
SessionRecordType: Stable initial durable record discriminators.
SessionSequenceParseError: Error returned when parsing a session sequence.
StopReason: Normalized assistant stop reason with forward-compatible unknown values.
ToolIdempotency: Declared retry semantics of a tool execution.
ToolPresentation: UI-only presentation attached to a tool result or preview.
UsageError: Error returned when validating token usage.
WebFetchTruncation: Why a normalized client web-fetch body was truncated.

Constants§

CURRENT_PROTOCOL_VERSION: The protocol version written by this crate.
MAX_APPROVAL_ITEMS: Maximum capabilities or resources in one approval observation.
MAX_APPROVAL_ITEM_BYTES: Maximum UTF-8 bytes in one capability or resource string.
MAX_CODE_CHANGE_HUNKS: Maximum hunks retained for one code-change presentation.
MAX_CODE_CHANGE_LINES: Maximum lines retained across one code-change presentation.
MAX_CODE_CHANGE_LINES_PER_HUNK: Maximum lines retained in one hunk.
MAX_CODE_CHANGE_LINE_BYTES: Maximum UTF-8 byte length of one retained source line.
MAX_CODE_CHANGE_PATCH_BYTES: Maximum UTF-8 byte length of an optional unified patch.
MAX_CODE_CHANGE_PATH_BYTES: Maximum UTF-8 byte length of a workspace-relative changed-file path.
MAX_COMMAND_TEXT_BYTES: Maximum UTF-8 bytes in a command text fragment.
MAX_ERROR_MESSAGE_BYTES: Maximum UTF-8 bytes in an English technical error message.
MAX_EVENT_DELTA_BYTES: Maximum UTF-8 bytes in one streaming delta.
MAX_EXTERNAL_SOURCE_TEXT_BYTES: Maximum UTF-8 bytes in a source snippet or cited text.
MAX_EXTERNAL_SOURCE_TITLE_BYTES: Maximum UTF-8 bytes in one external source title.
MAX_EXTERNAL_SOURCE_URL_BYTES: Maximum UTF-8 bytes in one external source URL.
MAX_HOSTED_TOOL_SOURCES: Maximum normalized sources retained for one hosted tool activity.
MAX_INLINE_IMAGE_BASE64_BYTES: Maximum encoded bytes in one inline Base64 image.
MAX_METADATA_BYTES: Maximum encoded JSON bytes for one metadata map.
MAX_METADATA_DEPTH: Maximum JSON container nesting depth inside metadata values.
MAX_METADATA_NAMESPACES: Maximum number of metadata namespaces on one protocol value.
MAX_PROGRESS_MESSAGE_BYTES: Maximum UTF-8 bytes in one progress diagnostic.
MAX_PROVIDER_CONTINUATION_BYTES: Maximum encoded JSON bytes in one opaque provider continuation envelope.
MAX_PROVIDER_CONTINUATION_DEPTH: Maximum nesting depth in provider continuation JSON.
MAX_RECORD_CONTENT_BLOCKS: Maximum result content blocks stored for one tool execution.
MAX_SAFE_INTEGER: Largest integer exactly representable by a JavaScript Number.
MAX_SELECTOR_BYTES: Maximum UTF-8 bytes in a model or profile selector.
MAX_TEXT_BLOCK_BYTES: Maximum UTF-8 bytes in one text or thinking content block.
MAX_TOOL_ARGUMENT_BYTES: Maximum encoded JSON bytes for tool arguments.
MAX_TOOL_ARGUMENT_DEPTH: Maximum nesting depth for tool arguments.
MAX_UNKNOWN_EVENT_BYTES: Maximum encoded JSON bytes retained while inspecting an unknown event.
MAX_WEB_FETCH_BODY_BYTES: Maximum UTF-8 bytes in an extracted client web-fetch body.
MAX_WEB_FETCH_BODY_CHARS: Maximum Unicode scalar values in an extracted client web-fetch body.
MAX_WEB_FETCH_MIME_BYTES: Maximum UTF-8 bytes in a normalized client web-fetch MIME type.
MAX_WEB_FETCH_REDIRECTS: Maximum redirect records retained by a normalized client web-fetch result.
MAX_WEB_FETCH_TITLE_BYTES: Maximum UTF-8 bytes in a normalized client web-fetch title.
MAX_WEB_FETCH_URL_BYTES: Maximum UTF-8 bytes in a normalized client web-fetch URL.
PROTOCOL_V1_0: Protocol version 1.0.

Crate tea_protocol

Crate tea_protocol Copy item path

§Example

Structs§

Enums§

Constants§

Crate tea_protocol