Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""Shared protocol stream framing and terminal-event taxonomy."""
from __future__ import annotations
import json
from dataclasses import dataclass, field
from typing import AbstractSet, BinaryIO, Callable, Final, Iterable, Literal, Mapping
from .async_owner import run_owned_in_thread
from .hosted_items import responses_item_succeeded
from .json_wire import JSONEvent, JSONPath, JSONScope, SelectiveJSONParser
SSE_LINE_ENDINGS: Final = (b"\r\n", b"\n", b"\r")
# Wire observation is a bounded, fail-closed metadata copy. These are not
# protocol or response limits: the original bytes continue downstream unchanged.
SSE_OBSERVATION_BYTES: Final = 64 * 1024
SSE_OBSERVATION_STRING_BYTES: Final = 16 * 1024
SSE_OBSERVATION_EVENT_BYTES: Final = 256
UTF8_BOM: Final = b"\xef\xbb\xbf"
@dataclass
class SSEFrameTokenizer:
"""Incrementally split exact SSE frames for response mutation."""
_line: bytearray = field(default_factory=bytearray)
_frame_lines: list[bytes] = field(default_factory=list)
_after_cr: bool = False
_stream_prefix: bytearray = field(default_factory=bytearray)
_stream_started: bool = False
_raw_partial: bytearray = field(default_factory=bytearray)
@property
def retained_bytes(self) -> int:
return (
len(self._stream_prefix)
+ len(self._line)
+ sum(map(len, self._frame_lines))
+ len(self._raw_partial)
)
def feed(self, chunk: bytes) -> tuple[bytes, ...]:
if not self._stream_started:
self._stream_prefix.extend(chunk)
prefix = bytes(self._stream_prefix)
if len(prefix) < len(UTF8_BOM) and UTF8_BOM.startswith(prefix):
return ()
self._stream_started = True
self._stream_prefix.clear()
chunk = prefix[len(UTF8_BOM) :] if prefix.startswith(UTF8_BOM) else prefix
frames: list[bytes] = []
for byte in chunk:
if self._after_cr:
self._after_cr = False
if byte == 0x0A:
if self._raw_partial:
self._raw_partial.append(byte)
continue
self._raw_partial.append(byte)
if byte == 0x0D:
if self._finish_line(frames):
self._raw_partial.clear()
self._after_cr = True
elif byte == 0x0A:
if self._finish_line(frames):
self._raw_partial.clear()
else:
self._line.append(byte)
return tuple(frames)
def discard_partial_frame(self) -> bool | None:
"""Discard an unterminated frame and report whether its line is open."""
if not self._line and not self._frame_lines:
return None
line_open = bool(self._line)
self._line.clear()
self._frame_lines.clear()
self._after_cr = False
self._stream_prefix.clear()
self._raw_partial.clear()
return line_open
def drain_partial_frame(self) -> bytes:
"""Return and clear the exact unterminated wire bytes."""
if not self._stream_started:
pending = bytes(self._stream_prefix)
else:
pending = bytes(self._raw_partial)
self._line.clear()
self._frame_lines.clear()
self._after_cr = False
self._stream_prefix.clear()
self._raw_partial.clear()
return pending
def _finish_line(self, frames: list[bytes]) -> bool:
line = bytes(self._line)
self._line.clear()
if line:
self._frame_lines.append(line)
return False
if self._frame_lines:
frames.append(b"\n".join(self._frame_lines))
self._frame_lines.clear()
return True
return False
@dataclass(frozen=True)
class SSEObservedFrame:
"""The protocol metadata retained from one SSE frame."""
event_name: str | None
observation: ProtocolObservation
@dataclass
class SSEObservationTokenizer:
"""Observe SSE metadata without retaining model-authored string bodies."""
protocol: str
_field: bytearray = field(default_factory=bytearray)
_field_too_long: bool = False
_line_kind: str | None = None
_value_started: bool = False
_skip_value_space: bool = False
_line_started: bool = False
_frame_started: bool = False
_event_value: bytearray = field(default_factory=bytearray)
_event_value_too_long: bool = False
_current_event_name: str | None = None
_current_event_name_unknown: bool = False
_has_data: bool = False
_data: ProtocolFactProjector | None = None
_after_cr: bool = False
_stream_prefix: bytearray = field(default_factory=bytearray)
_stream_started: bool = False
@property
def retained_bytes(self) -> int:
return (
len(self._field)
+ len(self._event_value)
+ (self._data.retained_bytes if self._data is not None else 0)
)
def feed(self, chunk: bytes) -> tuple[SSEObservedFrame, ...]:
if not self._stream_started:
self._stream_prefix.extend(chunk)
prefix = bytes(self._stream_prefix)
if len(prefix) < len(UTF8_BOM) and UTF8_BOM.startswith(prefix):
return ()
self._stream_started = True
self._stream_prefix.clear()
chunk = prefix[len(UTF8_BOM) :] if prefix.startswith(UTF8_BOM) else prefix
frames: list[SSEObservedFrame] = []
offset = 0
if self._after_cr and chunk:
self._after_cr = False
if chunk.startswith(b"\n"):
offset = 1
while offset < len(chunk):
cr = chunk.find(b"\r", offset)
lf = chunk.find(b"\n", offset)
if cr < 0:
boundary = lf
elif lf < 0:
boundary = cr
else:
boundary = min(cr, lf)
if boundary < 0:
self._consume_bytes(chunk[offset:])
break
self._consume_bytes(chunk[offset:boundary])
self._finish_line(frames)
if chunk[boundary] == 0x0D:
if boundary + 1 < len(chunk) and chunk[boundary + 1] == 0x0A:
offset = boundary + 2
elif boundary + 1 < len(chunk):
offset = boundary + 1
else:
self._after_cr = True
offset = boundary + 1
else:
offset = boundary + 1
return tuple(frames)
def discard_partial_frame(self) -> bool | None:
if not self._frame_started and not self._line_started:
return None
line_open = self._line_started
self._reset_line()
self._reset_frame()
self._after_cr = False
self._stream_prefix.clear()
return line_open
def _consume_bytes(self, payload: bytes) -> None:
if not payload:
return
self._line_started = True
self._frame_started = True
if not self._value_started:
colon = payload.find(b":")
field_payload = payload if colon < 0 else payload[:colon]
if not self._field_too_long:
remaining = len(b"event") - len(self._field)
if len(field_payload) <= remaining:
self._field.extend(field_payload)
else:
self._field.clear()
self._field_too_long = True
if colon < 0:
return
self._value_started = True
field_name = bytes(self._field) if not self._field_too_long else b""
self._line_kind = (
"event" if field_name == b"event" else "data" if field_name == b"data" else None
)
self._skip_value_space = True
if self._line_kind == "data":
self._start_data_line()
payload = payload[colon + 1 :]
if self._skip_value_space and payload:
self._skip_value_space = False
if payload.startswith(b" "):
payload = payload[1:]
if not payload:
return
if self._line_kind == "event":
if self._event_value_too_long:
return
remaining = SSE_OBSERVATION_EVENT_BYTES - len(self._event_value)
if len(payload) <= remaining:
self._event_value.extend(payload)
else:
self._event_value.clear()
self._event_value_too_long = True
elif self._line_kind == "data":
assert self._data is not None
self._data.feed(payload)
def _finish_line(self, frames: list[SSEObservedFrame]) -> None:
if not self._line_started:
if self._frame_started:
frames.append(
SSEObservedFrame(
event_name=self._current_event_name,
observation=(
self._data.finish(
streamed=True,
event_name=self._current_event_name,
)
if self._data is not None
and not self._current_event_name_unknown
else ProtocolObservation()
),
)
)
self._reset_frame()
return
if not self._value_started and not self._field_too_long:
field_name = bytes(self._field)
if field_name == b"data":
self._start_data_line()
elif field_name == b"event":
self._line_kind = "event"
if self._line_kind == "event":
if self._event_value_too_long:
self._current_event_name = None
self._current_event_name_unknown = True
else:
try:
decoded = self._event_value.decode("utf-8")
self._current_event_name = decoded or None
self._current_event_name_unknown = False
except UnicodeDecodeError:
self._current_event_name = None
self._current_event_name_unknown = True
self._reset_line()
def _start_data_line(self) -> None:
if self._has_data:
assert self._data is not None
self._data.feed_byte(0x0A)
else:
self._data = ProtocolFactProjector(self.protocol)
self._has_data = True
def _reset_line(self) -> None:
self._field.clear()
self._field_too_long = False
self._line_kind = None
self._value_started = False
self._skip_value_space = False
self._line_started = False
self._event_value.clear()
self._event_value_too_long = False
def _reset_frame(self) -> None:
self._frame_started = False
self._current_event_name = None
self._current_event_name_unknown = False
self._has_data = False
self._data = None
def parse_sse_frame(frame: bytes) -> tuple[str | None, bytes | None]:
"""Return the event name and joined data field from one normalized frame."""
event_name: str | None = None
data_lines: list[bytes] = []
for line in frame.split(b"\n"):
field, separator, value = line.partition(b":")
if not separator:
continue
if value.startswith(b" "):
value = value[1:]
if field == b"event":
try:
event_name = value.decode("utf-8")
except UnicodeDecodeError:
event_name = None
elif field == b"data":
data_lines.append(value)
return event_name, b"\n".join(data_lines) if data_lines else None
def _anthropic_terminal_event(
_key: str,
message: str,
_next_sequence_number: int,
) -> dict[str, object]:
return {"type": "error", "error": {"type": "api_error", "message": message}}
def _responses_terminal_event(
key: str,
message: str,
next_sequence_number: int,
) -> dict[str, object]:
return {
"type": "error",
"code": key,
"message": message,
"param": None,
"sequence_number": next_sequence_number,
}
def _images_terminal_event(
key: str,
message: str,
_next_sequence_number: int,
) -> dict[str, object]:
return {"error": {"type": "server_error", "code": key, "message": message}}
def _chat_terminal_event(
key: str,
message: str,
_next_sequence_number: int,
) -> dict[str, object]:
return {
"object": "chat.completion.chunk",
"type": "error",
"error": {"type": "server_error", "code": key, "message": message},
"choices": [],
}
def _google_terminal_event(key: str, message: str, _next_sequence_number: int) -> dict[str, object]:
return {"error": {"code": 500, "status": "INTERNAL", "message": message, "details": [{"reason": key}]}}
StreamTerminalOutcome = Literal["served", "failed_terminal"]
# The processing tier a response reports having served (docs/plans/fast-mode.md):
# the vendor's fast tier, or any other tier it names.
ServedTier = Literal["fast", "standard"]
ProtocolObservationOutcome = Literal["served", "failed_terminal", "protocol_error"]
ErrorEnvelopePath = tuple[str, ...]
# Token counts are vendor-reported, never self-measured, so one hostile or buggy
# response must not be able to poison a persisted aggregate. The ceiling is fixed
# in our code; it is never derived from a value the upstream declares.
#
# It bounds ONE report, which is what the name has to say, because the scope is
# the whole argument for the number. No request composes a billion input tokens,
# so a single response past this is broken or hostile and dropping it costs
# nothing true. An aggregate of many accepted reports is a different quantity
# with no upper bound worth inventing — a user may spend whatever they spend —
# and this ceiling was once reused there, where it silently truncated real usage
# into a plausible-looking total. What an aggregate needs is
# `usage.USAGE_COUNTER_CEILING`: a statement about what the read contract can
# carry, not about what a count is allowed to be.
USAGE_REPORT_TOKEN_CEILING: Final = 1_000_000_000
@dataclass(frozen=True)
class ProtocolUsageReport:
"""One protocol-normalized token report observed on the wire."""
input_tokens: int = 0
cached_input_tokens: int = 0
output_tokens: int = 0
# Input written to the prompt cache: a subset of input disjoint from cached
# input. The lifetime-specific fields are disjoint subsets of this total;
# Anthropic uses the one-hour field and official OpenAI Responses uses the
# separate 30-minute and 12-hour fields.
cache_write_input_tokens: int = 0
cache_write_1h_input_tokens: int = 0
cache_write_30m_input_tokens: int = 0
cache_write_12h_input_tokens: int = 0
# Count of reports whose cache-write lifetime evidence was absent or
# invalid. This is per protocol report and is summed when calls fold.
cache_write_ttl_uncaptured_reports: int = 0
@classmethod
def of(
cls,
*,
input_tokens: int,
cached_input_tokens: int,
output_tokens: int,
cache_write_input_tokens: int = 0,
cache_write_1h_input_tokens: int = 0,
cache_write_30m_input_tokens: int = 0,
cache_write_12h_input_tokens: int = 0,
cache_write_ttl_uncaptured_reports: int = 0,
) -> "ProtocolUsageReport":
"""Build one report with the cached-input subset invariant enforced.
Cached input is a *part* of the input the turn was billed for, which is
what the read contract promises and what the settings page will divide
by. Both numbers come from the same upstream, so the only bound worth
trusting is the input count this module normalized itself — never a
total the response declares. Cached input reported without a readable
input count is a subset of nothing, so it clamps to zero. Cache writes are
the input left after cache reads, and one-hour writes are part of them.
"""
raw_values = (
input_tokens,
cached_input_tokens,
cache_write_input_tokens,
cache_write_1h_input_tokens,
cache_write_30m_input_tokens,
cache_write_12h_input_tokens,
)
invalid_ttl = any(value < 0 for value in raw_values[2:]) or (
cache_write_input_tokens > max(0, input_tokens - max(0, cached_input_tokens))
) or (
cache_write_1h_input_tokens + cache_write_30m_input_tokens + cache_write_12h_input_tokens
> cache_write_input_tokens
)
input_tokens = max(0, input_tokens)
cached_input_tokens = max(0, cached_input_tokens)
output_tokens = max(0, output_tokens)
cache_write_input_tokens = max(0, cache_write_input_tokens)
cache_write_1h_input_tokens = max(0, cache_write_1h_input_tokens)
cache_write_30m_input_tokens = max(0, cache_write_30m_input_tokens)
cache_write_12h_input_tokens = max(0, cache_write_12h_input_tokens)
cached = min(cached_input_tokens, input_tokens)
cache_write = min(cache_write_input_tokens, input_tokens - cached)
cache_write_1h = min(cache_write_1h_input_tokens, cache_write)
cache_write_30m = min(cache_write_30m_input_tokens, max(0, cache_write - cache_write_1h))
cache_write_12h = min(
cache_write_12h_input_tokens, max(0, cache_write - cache_write_1h - cache_write_30m)
)
ttl_uncaptured = max(max(0, cache_write_ttl_uncaptured_reports), int(invalid_ttl))
return cls(
input_tokens=input_tokens,
cached_input_tokens=cached,
output_tokens=output_tokens,
cache_write_input_tokens=cache_write,
cache_write_1h_input_tokens=cache_write_1h,
cache_write_30m_input_tokens=cache_write_30m,
cache_write_12h_input_tokens=cache_write_12h,
cache_write_ttl_uncaptured_reports=ttl_uncaptured,
)
def merge(self, other: "ProtocolUsageReport") -> "ProtocolUsageReport":
"""Combine two reports for the same turn by taking the larger of each.
The per-field max is re-normalized because the winning input and cached
counts can come from different frames, which is a second way an upstream
could compose a cached count larger than the input it belongs to.
"""
return ProtocolUsageReport.of(
input_tokens=max(self.input_tokens, other.input_tokens),
cached_input_tokens=max(self.cached_input_tokens, other.cached_input_tokens),
output_tokens=max(self.output_tokens, other.output_tokens),
cache_write_input_tokens=max(self.cache_write_input_tokens, other.cache_write_input_tokens),
cache_write_1h_input_tokens=max(
self.cache_write_1h_input_tokens, other.cache_write_1h_input_tokens
),
cache_write_30m_input_tokens=max(
self.cache_write_30m_input_tokens, other.cache_write_30m_input_tokens
),
cache_write_12h_input_tokens=max(
self.cache_write_12h_input_tokens, other.cache_write_12h_input_tokens
),
cache_write_ttl_uncaptured_reports=max(
self.cache_write_ttl_uncaptured_reports,
other.cache_write_ttl_uncaptured_reports,
),
)
@dataclass(frozen=True)
class ProtocolObservation:
outcome: ProtocolObservationOutcome | None = None
model_output_started: bool = False
error_payload: bytes | None = None
error_envelope_paths: tuple[ErrorEnvelopePath, ...] = ()
sequence_number: int | None = None
message: str | None = None
usage: ProtocolUsageReport | None = None
error_type_candidates: tuple[str, ...] = ()
error_code_candidates: tuple[str, ...] = ()
recovery_verified: bool = False
# Raw upstream text, for bounded redacted display only; never in reprs.
error_message: str | None = field(default=None, repr=False)
# Search tools whose own completed hosted item this response carried (§3.2).
hosted_tools: frozenset[str] = frozenset()
# The tier this frame or buffered response reports having served, if it names one.
served_tier: ServedTier | None = None
@dataclass(frozen=True)
class ServedTierPaths:
"""Where a protocol reports the processing tier it served, and the value that names the fast tier.
Anthropic reports ``usage.speed`` (``fast`` or ``standard``); OpenAI reports
``service_tier`` (``priority`` for its fast tier, else ``default``, ``flex``,
``scale``). Any other value names a tier that is not the fast one.
"""
paths: tuple[JSONPath, ...]
fast_value: str
# Only the stream's terminal frame states the tier that ran: an earlier one
# (Responses ``response.created``) may echo the request, which a relay that
# dropped the field can still do. A terminal that names no tier confirms none.
settled_by_terminal: bool = False
@dataclass(frozen=True)
class HostedItemPaths:
"""Where a protocol carries its own hosted-tool items (``vibey-hosted-tools.md`` §3.2).
A streamed response carries one item per ``event_type`` event, at
``event_item``; a buffered one carries them in the ``buffered_items`` array.
``leaves`` are the item fields that say which tool ran and whether it
completed, relative to the item.
"""
event_type: str
event_item: JSONPath
buffered_items: JSONPath
leaves: tuple[JSONPath, ...]
@dataclass(frozen=True)
class ProtocolTerminalEnvelope:
event_name: str | None
selector_path: tuple[str, ...]
selector_value: str | None
terminal_outcome: StreamTerminalOutcome
error_envelope_paths: tuple[ErrorEnvelopePath, ...] = ()
required_error_path: ErrorEnvelopePath | None = None
required_error_code_path: ErrorEnvelopePath | None = None
require_nonempty: bool = False
@dataclass(frozen=True)
class ProtocolModelOutputEnvelope:
event_name: str | None
selector_path: tuple[str, ...]
selector_value: str | None
require_nonempty: bool = False
@dataclass(frozen=True)
class ProtocolUsageTaxonomy:
"""Declare where one protocol reports token usage and how to compose it.
Leaf paths are relative to a container. Values found under the leaves of one
logical field are summed within a single container, because a protocol may
split one quantity across sibling members; candidates from different
containers are then merged by taking the larger, because protocols repeat a
cumulative report across frames.
"""
container_paths: tuple[tuple[str, ...], ...]
input_paths: tuple[tuple[str, ...], ...]
cached_input_paths: tuple[tuple[str, ...], ...]
output_paths: tuple[tuple[str, ...], ...]
# Protocols that report no cache writes leave these empty.
cache_write_paths: tuple[tuple[str, ...], ...] = ()
cache_write_1h_paths: tuple[tuple[str, ...], ...] = ()
# Lifetime-specific OpenAI Responses write breakdowns. When these are
# declared, both must be present and sum to cache_write_tokens; otherwise
# the known total remains usable but is marked incomplete for pricing.
cache_write_30m_paths: tuple[tuple[str, ...], ...] = ()
cache_write_12h_paths: tuple[tuple[str, ...], ...] = ()
@dataclass(frozen=True)
class ProtocolStreamTaxonomy:
terminal_envelopes: tuple[ProtocolTerminalEnvelope, ...]
model_output_envelopes: tuple[ProtocolModelOutputEnvelope, ...]
success_literal: tuple[str | None, bytes] | None
sequence_number_path: tuple[str, ...] | None
buffered_error_envelope_paths: tuple[ErrorEnvelopePath, ...]
terminal_event_name: str | None
render_terminal_event: Callable[[str, str, int], dict[str, object]]
usage: ProtocolUsageTaxonomy
# Positive buffered recovery evidence, not a response-admission schema.
# Project only these finite selectors and the result container's shape.
buffered_success_selectors: tuple[tuple[JSONPath, tuple[str, ...]], ...] = ()
buffered_output_array_path: JSONPath | None = None
buffered_terminal_string_paths: tuple[JSONPath, ...] = ()
hosted_items: HostedItemPaths | None = None
served_tier: ServedTierPaths | None = None
PROTOCOL_STREAM_TAXONOMY: Final[Mapping[str, ProtocolStreamTaxonomy]] = {
"google": ProtocolStreamTaxonomy(
terminal_envelopes=(
ProtocolTerminalEnvelope(None, ("error",), None, "failed_terminal", (("error",),)),
ProtocolTerminalEnvelope("error", ("error",), None, "failed_terminal", (("error",),)),
ProtocolTerminalEnvelope(
None, ("candidates", "*", "finishReason"), None, "served", require_nonempty=True,
),
ProtocolTerminalEnvelope(
None, ("promptFeedback", "blockReason"), None, "served", require_nonempty=True,
),
),
model_output_envelopes=(
ProtocolModelOutputEnvelope(
None, ("candidates", "*", "content", "parts"), None, require_nonempty=True,
),
),
success_literal=None,
sequence_number_path=None,
buffered_error_envelope_paths=(("error",),),
buffered_output_array_path=("candidates",),
buffered_terminal_string_paths=(("promptFeedback", "blockReason"),),
terminal_event_name=None,
render_terminal_event=_google_terminal_event,
usage=ProtocolUsageTaxonomy(
# Gemini GenerateContentResponse. Prompt count includes cache;
# thoughtsTokenCount is separate from candidatesTokenCount.
container_paths=(("usageMetadata",),),
input_paths=(("promptTokenCount",),),
cached_input_paths=(("cachedContentTokenCount",),),
output_paths=(("candidatesTokenCount",), ("thoughtsTokenCount",)),
),
),
"anthropic": ProtocolStreamTaxonomy(
terminal_envelopes=(
ProtocolTerminalEnvelope(
# https://platform.claude.com/docs/en/build-with-claude/streaming
"message_stop",
("type",),
"message_stop",
"served",
),
ProtocolTerminalEnvelope(
# https://platform.claude.com/docs/en/build-with-claude/streaming#error-events
"error",
("type",),
"error",
"failed_terminal",
(("error",),),
),
),
model_output_envelopes=(
ProtocolModelOutputEnvelope(
# https://platform.claude.com/docs/en/build-with-claude/streaming#content-block-start-event
"content_block_start",
("type",),
"content_block_start",
),
ProtocolModelOutputEnvelope(
# https://platform.claude.com/docs/en/build-with-claude/streaming#content-block-delta-event
"content_block_delta",
("type",),
"content_block_delta",
),
),
success_literal=None,
sequence_number_path=None,
buffered_error_envelope_paths=(("error",),),
buffered_success_selectors=((("type",), ("message",)),),
buffered_output_array_path=("content",),
# A server tool's result block arrives whole in its start event; its
# ``content`` is the result list, or the error object on a failed search.
hosted_items=HostedItemPaths(
"content_block_start", ("content_block",), ("content",), (("type",), ("content",), ("content", "type")),
),
terminal_event_name="error",
render_terminal_event=_anthropic_terminal_event,
usage=ProtocolUsageTaxonomy(
# https://platform.claude.com/docs/en/build-with-claude/streaming
# message_start nests the report under `message`; message_delta and
# buffered responses report it at the top level.
container_paths=(("message", "usage"), ("usage",)),
# https://platform.claude.com/docs/en/docs/build-with-claude/prompt-caching
# `input_tokens` excludes both cache members, so the input total is
# their sum. Only cache reads are input served from cache; cache
# creation is fresh input that was also written to the cache.
input_paths=(
("input_tokens",),
("cache_read_input_tokens",),
("cache_creation_input_tokens",),
),
cached_input_paths=(("cache_read_input_tokens",),),
output_paths=(("output_tokens",),),
# Cache writes are priced apart from fresh input; the one-hour
# lifetime is split out under `cache_creation`.
cache_write_paths=(("cache_creation_input_tokens",),),
cache_write_1h_paths=(("cache_creation", "ephemeral_1h_input_tokens"),),
),
# https://platform.claude.com/docs/en/build-with-claude/fast-mode#checking-which-speed-was-used
served_tier=ServedTierPaths(paths=(("message", "usage", "speed"), ("usage", "speed")), fast_value="fast"),
),
"openai_responses": ProtocolStreamTaxonomy(
terminal_envelopes=(
ProtocolTerminalEnvelope(
# https://platform.openai.com/docs/api-reference/responses-streaming/response/completed
"response.completed",
("type",),
"response.completed",
"served",
),
ProtocolTerminalEnvelope(
# https://platform.openai.com/docs/api-reference/responses-streaming/error
# The reference carries the class at the root, as this hub's own
# terminal frame does. CLIProxyAPI nests it under `error`
# (sdk/api/handlers/openai_responses_stream_error.go).
"error",
("type",),
"error",
"failed_terminal",
((), ("error",)),
),
ProtocolTerminalEnvelope(
# https://platform.openai.com/docs/api-reference/responses-streaming/response/failed
"response.failed",
("type",),
"response.failed",
"failed_terminal",
(("response", "error"),),
),
ProtocolTerminalEnvelope(
# Some OpenAI-compatible relays preserve the SSE event name but
# omit the duplicated `type` member from the JSON data. The
# event name and the response error envelope are still enough
# to identify this terminal failure.
"response.failed",
("response", "error"),
None,
"failed_terminal",
(("response", "error"),),
),
ProtocolTerminalEnvelope(
# https://platform.openai.com/docs/api-reference/responses-streaming/response/incomplete
"response.incomplete",
("type",),
"response.incomplete",
"failed_terminal",
(("response", "error"),),
("response", "error"),
("response", "error", "code"),
),
ProtocolTerminalEnvelope(
# https://platform.openai.com/docs/api-reference/responses-streaming/response/incomplete
# Incomplete output without an error envelope is completed
# output and does not change Source health.
"response.incomplete",
("type",),
"response.incomplete",
"served",
),
),
model_output_envelopes=(
ProtocolModelOutputEnvelope(
# https://platform.openai.com/docs/api-reference/responses-streaming/response/output-text/delta
"response.output_text.delta",
("type",),
"response.output_text.delta",
),
ProtocolModelOutputEnvelope(
# https://platform.openai.com/docs/api-reference/responses-streaming/response/refusal/delta
"response.refusal.delta",
("type",),
"response.refusal.delta",
),
ProtocolModelOutputEnvelope(
# https://platform.openai.com/docs/api-reference/responses-streaming/response/reasoning-summary-text/delta
"response.reasoning_summary_text.delta",
("type",),
"response.reasoning_summary_text.delta",
),
ProtocolModelOutputEnvelope(
# https://platform.openai.com/docs/api-reference/responses-streaming/response/reasoning-text/delta
"response.reasoning_text.delta",
("type",),
"response.reasoning_text.delta",
),
ProtocolModelOutputEnvelope(
# https://platform.openai.com/docs/api-reference/responses-streaming/response/function-call-arguments/delta
"response.function_call_arguments.delta",
("type",),
"response.function_call_arguments.delta",
),
),
success_literal=None,
sequence_number_path=("sequence_number",),
buffered_error_envelope_paths=(("error",),),
buffered_success_selectors=(
(("object",), ("response",)),
(("status",), ("completed", "incomplete")),
),
buffered_output_array_path=("output",),
hosted_items=HostedItemPaths(
"response.output_item.done", ("item",), ("output",), (("type",), ("name",), ("status",)),
),
terminal_event_name="error",
render_terminal_event=_responses_terminal_event,
usage=ProtocolUsageTaxonomy(
# https://platform.openai.com/docs/api-reference/responses/object#responses/object-usage
# Terminal response events nest the completed response; buffered
# responses are that object.
container_paths=(("response", "usage"), ("usage",)),
# `input_tokens` already includes cached input, so the cached count
# is an informational subset and never an addend.
input_paths=(("input_tokens",),),
cached_input_paths=(("input_tokens_details", "cached_tokens"),),
output_paths=(("output_tokens",),),
cache_write_paths=(("input_tokens_details", "cache_write_tokens"),),
cache_write_30m_paths=(("input_tokens_details", "cache_write_tokens_details", "ttl_30m_tokens"),),
cache_write_12h_paths=(("input_tokens_details", "cache_write_tokens_details", "ttl_12h_tokens"),),
),
# https://platform.openai.com/docs/api-reference/responses/object#responses/object-service_tier
# The terminal event nests the completed response; a buffered response is it.
served_tier=ServedTierPaths(
paths=(("response", "service_tier"), ("service_tier",)), fast_value="priority", settled_by_terminal=True,
),
),
"openai_chat": ProtocolStreamTaxonomy(
terminal_envelopes=(
ProtocolTerminalEnvelope(
# https://developers.openai.com/api/reference/resources/chat
# Chat streaming errors use the top-level error member; they
# do not require a second, top-level type discriminator.
None,
("error",),
None,
"failed_terminal",
(("error",),),
),
),
model_output_envelopes=(
ProtocolModelOutputEnvelope(
# https://platform.openai.com/docs/api-reference/chat/create#chat-create-stream
None,
("choices", "*", "delta", "content"),
None,
require_nonempty=True,
),
ProtocolModelOutputEnvelope(
# https://api-docs.deepseek.com/guides/reasoning_model
None,
("choices", "*", "delta", "reasoning_content"),
None,
require_nonempty=True,
),
ProtocolModelOutputEnvelope(
# https://platform.openai.com/docs/api-reference/chat/create#chat-create-stream
None,
("choices", "*", "delta", "refusal"),
None,
require_nonempty=True,
),
ProtocolModelOutputEnvelope(
# https://platform.openai.com/docs/api-reference/chat/create#chat-create-stream
None,
("choices", "*", "delta", "tool_calls"),
None,
require_nonempty=True,
),
ProtocolModelOutputEnvelope(
# https://platform.openai.com/docs/api-reference/chat/create#chat-create-stream
None,
("choices", "*", "delta", "function_call"),
None,
require_nonempty=True,
),
),
# https://platform.openai.com/docs/api-reference/chat/create#chat-create-stream
success_literal=(None, b"[DONE]"),
sequence_number_path=None,
buffered_error_envelope_paths=(("error",),),
buffered_success_selectors=((("object",), ("chat.completion",)),),
buffered_output_array_path=("choices",),
terminal_event_name=None,
render_terminal_event=_chat_terminal_event,
usage=ProtocolUsageTaxonomy(
# https://platform.openai.com/docs/api-reference/chat/object#chat/object-usage
# Streaming chat reports usage only when the client asked for it via
# `stream_options.include_usage`, on a dedicated final chunk.
container_paths=(("usage",),),
input_paths=(("prompt_tokens",),),
cached_input_paths=(("prompt_tokens_details", "cached_tokens"),),
output_paths=(("completion_tokens",),),
),
# https://platform.openai.com/docs/api-reference/chat/object#chat/object-service_tier
# Every streamed chunk repeats it.
served_tier=ServedTierPaths(paths=(("service_tier",),), fast_value="priority"),
),
# The engine's images endpoints (vibey-hosted-tools.md §7.4): a buffered JSON
# answer only; ``image_generate`` never streams, so nothing here is streamed.
"openai_images": ProtocolStreamTaxonomy(
terminal_envelopes=(),
model_output_envelopes=(),
success_literal=None,
sequence_number_path=None,
# https://platform.openai.com/docs/api-reference/images/object
buffered_error_envelope_paths=(("error",),),
buffered_output_array_path=("data",),
terminal_event_name=None,
render_terminal_event=_images_terminal_event,
usage=ProtocolUsageTaxonomy(
# https://platform.openai.com/docs/api-reference/images/object#images-object-usage
container_paths=(("usage",),),
input_paths=(("input_tokens",),),
cached_input_paths=(("input_tokens_details", "cached_tokens"),),
output_paths=(("output_tokens",),),
),
),
}
def _path_values(document: Mapping[str, object], path: tuple[str, ...]) -> tuple[object, ...]:
values: tuple[object, ...] = (document,)
for component in path:
next_values: list[object] = []
for value in values:
if component == "*" and isinstance(value, list):
next_values.extend(value)
elif isinstance(value, Mapping) and component in value:
next_values.append(value[component])
values = tuple(next_values)
if not values:
break
return values
def _selector_matches(
payload: Mapping[str, object],
*,
selector_path: tuple[str, ...],
selector_value: str | None,
require_nonempty: bool = False,
) -> bool:
values = _path_values(payload, selector_path)
if selector_value is not None:
return selector_value in values
if require_nonempty:
return any(bool(value) for value in values)
return any(isinstance(value, Mapping) for value in values)
def is_protocol_model_output(
protocol: str,
event_name: str | None,
payload: Mapping[str, object],
) -> bool:
"""Return the sole table-backed first-model-output boundary fact."""
return any(
envelope.event_name == event_name
and _selector_matches(
payload,
selector_path=envelope.selector_path,
selector_value=envelope.selector_value,
require_nonempty=envelope.require_nonempty,
)
for envelope in PROTOCOL_STREAM_TAXONOMY[protocol].model_output_envelopes
)
def _usage_total(values: Iterable[object]) -> int | None:
"""Sum one logical field's leaves, rejecting anything not a bounded count.
Every token count read from the wire, streamed or buffered, passes here: the
one place the per-report ceiling applies.
"""
total: int | None = None
for value in values:
if not isinstance(value, int) or isinstance(value, bool):
continue
if value < 0 or value > USAGE_REPORT_TOKEN_CEILING:
continue
total = value if total is None else total + value
if total is None:
return None
return min(total, USAGE_REPORT_TOKEN_CEILING)
def _usage_sum(container: Mapping[str, object], paths: tuple[tuple[str, ...], ...]) -> int | None:
return _usage_total(value for path in paths for value in _path_values(container, path))
def extract_protocol_usage(
protocol: str,
payload: Mapping[str, object],
) -> ProtocolUsageReport | None:
"""Read one document's token report, or None when it carries none."""
taxonomy = PROTOCOL_STREAM_TAXONOMY[protocol].usage
report: ProtocolUsageReport | None = None
for container_path in taxonomy.container_paths:
for container in _path_values(payload, container_path):
if not isinstance(container, Mapping):
continue
input_tokens = _usage_sum(container, taxonomy.input_paths)
cached_input_tokens = _usage_sum(container, taxonomy.cached_input_paths)
output_tokens = _usage_sum(container, taxonomy.output_paths)
if input_tokens is None and cached_input_tokens is None and output_tokens is None:
continue
reported_cache_write_total = _usage_sum(container, taxonomy.cache_write_paths)
cache_write_30m = _usage_sum(container, taxonomy.cache_write_30m_paths)
cache_write_12h = _usage_sum(container, taxonomy.cache_write_12h_paths)
cache_write_total = reported_cache_write_total
ttl_uncaptured = 0
if taxonomy.cache_write_30m_paths or taxonomy.cache_write_12h_paths:
has_cache_write_evidence = (
reported_cache_write_total is not None
or cache_write_30m is not None
or cache_write_12h is not None
)
if has_cache_write_evidence and cache_write_total is None and cache_write_30m is not None and cache_write_12h is not None:
# The documented OpenAI breakdowns are disjoint and sum to
# cache_write_tokens; retain that evidence, but keep the
# missing total visible as an incomplete report.
cache_write_total = cache_write_30m + cache_write_12h
if has_cache_write_evidence and (
reported_cache_write_total is None
or cache_write_30m is None
or cache_write_12h is None
or cache_write_30m + cache_write_12h != cache_write_total
):
ttl_uncaptured = 1
candidate = ProtocolUsageReport.of(
input_tokens=input_tokens or 0,
cached_input_tokens=cached_input_tokens or 0,
output_tokens=output_tokens or 0,
cache_write_input_tokens=cache_write_total or 0,
cache_write_1h_input_tokens=_usage_sum(container, taxonomy.cache_write_1h_paths) or 0,
cache_write_30m_input_tokens=cache_write_30m or 0,
cache_write_12h_input_tokens=cache_write_12h or 0,
cache_write_ttl_uncaptured_reports=ttl_uncaptured,
)
report = candidate if report is None else report.merge(candidate)
return report
def _usage_from_scalar_paths(
taxonomy: ProtocolUsageTaxonomy,
scalars: Mapping[tuple[str, ...], object],
) -> ProtocolUsageReport | None:
"""Project token reports from selected scalar paths in a buffered body."""
report: ProtocolUsageReport | None = None
for container_path in taxonomy.container_paths:
def usage_sum(paths: tuple[tuple[str, ...], ...]) -> int | None:
return _usage_total(scalars.get((*container_path, *path)) for path in paths)
input_tokens = usage_sum(taxonomy.input_paths)
cached_input_tokens = usage_sum(taxonomy.cached_input_paths)
output_tokens = usage_sum(taxonomy.output_paths)
if input_tokens is None and cached_input_tokens is None and output_tokens is None:
continue
reported_cache_write_total = usage_sum(taxonomy.cache_write_paths)
cache_write_30m = usage_sum(taxonomy.cache_write_30m_paths)
cache_write_12h = usage_sum(taxonomy.cache_write_12h_paths)
cache_write_total = reported_cache_write_total
ttl_uncaptured = 0
if taxonomy.cache_write_30m_paths or taxonomy.cache_write_12h_paths:
has_cache_write_evidence = (
reported_cache_write_total is not None
or cache_write_30m is not None
or cache_write_12h is not None
)
if has_cache_write_evidence and cache_write_total is None and cache_write_30m is not None and cache_write_12h is not None:
cache_write_total = cache_write_30m + cache_write_12h
if has_cache_write_evidence and (
reported_cache_write_total is None
or cache_write_30m is None
or cache_write_12h is None
or cache_write_30m + cache_write_12h != cache_write_total
):
ttl_uncaptured = 1
candidate = ProtocolUsageReport.of(
input_tokens=input_tokens or 0,
cached_input_tokens=cached_input_tokens or 0,
output_tokens=output_tokens or 0,
cache_write_input_tokens=cache_write_total or 0,
cache_write_1h_input_tokens=usage_sum(taxonomy.cache_write_1h_paths) or 0,
cache_write_30m_input_tokens=cache_write_30m or 0,
cache_write_12h_input_tokens=cache_write_12h or 0,
cache_write_ttl_uncaptured_reports=ttl_uncaptured,
)
report = candidate if report is None else report.merge(candidate)
return report
# A Google RPC error envelope's integer ``code`` is the HTTP status it answered
# with; this is the machine code each one projects to.
GOOGLE_ERROR_STATUS_MACHINE_CODES: Final[Mapping[int, str]] = {
400: "invalid_request_error", 401: "authentication_error",
403: "permission_error", 404: "not_found_error",
429: "rate_limit_error", 500: "server_error",
502: "server_error", 503: "server_error", 504: "server_error",
}
# Container markers for a hosted item's fields; scalars keep their value.
_ARRAY: Final = object()
_MAP: Final = object()
# The buffered response items whose fields are kept; a response carries a few.
_MAX_HOSTED_MEMBERS: Final = 256
def _hosted_item_tool(protocol: str, fields: Mapping[JSONPath, object]) -> str | None:
"""The search tool one hosted item proves ran to completion, or None (``vibey-hosted-tools.md`` §3.2)."""
def text(leaf: JSONPath) -> str | None:
value = fields.get(leaf)
return value if isinstance(value, str) else None
if protocol == "openai_responses":
return responses_item_succeeded(text(("type",)), text(("name",)), text(("status",)))
if protocol == "anthropic":
# A failed search arrives under the same block type with an error object as
# its content; only a result list proves the search ran.
if text(("type",)) == "web_search_tool_result" and fields.get(("content",)) is _ARRAY:
return "web_search"
return None
def _protocol_projection_paths(protocol: str) -> frozenset[JSONPath]:
taxonomy = PROTOCOL_STREAM_TAXONOMY[protocol]
paths: set[JSONPath] = {()}
paths.update(path for path, _values in taxonomy.buffered_success_selectors)
paths.update(taxonomy.buffered_terminal_string_paths)
if taxonomy.buffered_output_array_path is not None:
paths.add(taxonomy.buffered_output_array_path)
for envelope in (*taxonomy.terminal_envelopes, *taxonomy.model_output_envelopes):
paths.add(envelope.selector_path)
if isinstance(envelope, ProtocolTerminalEnvelope):
if envelope.required_error_path is not None:
paths.add(envelope.required_error_path)
if envelope.required_error_code_path is not None:
paths.add(envelope.required_error_code_path)
for error_path in _protocol_error_paths(taxonomy):
paths.update(
(error_path, (*error_path, "type"), (*error_path, "code"), (*error_path, "message"))
)
if taxonomy.sequence_number_path is not None:
paths.add(taxonomy.sequence_number_path)
if taxonomy.hosted_items is not None:
items = taxonomy.hosted_items
paths.update((*items.event_item, *leaf) for leaf in items.leaves)
paths.update((*items.buffered_items, "*", *leaf) for leaf in items.leaves)
if taxonomy.served_tier is not None:
paths.update(taxonomy.served_tier.paths)
for container_path in taxonomy.usage.container_paths:
for leaf_paths in (
taxonomy.usage.input_paths,
taxonomy.usage.cached_input_paths,
taxonomy.usage.output_paths,
taxonomy.usage.cache_write_paths,
taxonomy.usage.cache_write_1h_paths,
taxonomy.usage.cache_write_30m_paths,
taxonomy.usage.cache_write_12h_paths,
):
paths.update((*container_path, *leaf_path) for leaf_path in leaf_paths)
return frozenset(paths)
def _buffered_recovery_verified(
taxonomy: ProtocolStreamTaxonomy,
scalars: Mapping[JSONPath, object],
arrays: AbstractSet[JSONPath],
nonempty: AbstractSet[JSONPath],
) -> bool:
"""Recognize a completed native result without validating every body field."""
return any(
path in scalars and path in nonempty and (isinstance(scalars[path], str) or scalars[path] is None)
for path in taxonomy.buffered_terminal_string_paths
) or (
taxonomy.buffered_output_array_path is not None
and taxonomy.buffered_output_array_path in arrays
and all(scalars.get(path) in values for path, values in taxonomy.buffered_success_selectors)
)
def _protocol_error_paths(taxonomy: ProtocolStreamTaxonomy) -> frozenset[JSONPath]:
return frozenset(
(
*taxonomy.buffered_error_envelope_paths,
*(
path
for envelope in taxonomy.terminal_envelopes
for path in envelope.error_envelope_paths
),
)
)
class ProtocolFactProjector:
"""Own the finite protocol facts independently of response storage size."""
def __init__(
self,
protocol: str,
*,
machine_error_codes: AbstractSet[str] = frozenset(),
) -> None:
self.protocol = protocol
self.taxonomy = PROTOCOL_STREAM_TAXONOMY[protocol]
self.machine_error_codes = machine_error_codes
self._maps: set[JSONPath] = set()
self._arrays: set[JSONPath] = set()
self._nonempty: set[JSONPath] = set()
self._scoped_nonempty: set[tuple[JSONPath, JSONScope]] = set()
self._scalars: dict[JSONPath, object] = {}
self._literal = bytearray()
self._literal_too_long = False
items = self.taxonomy.hosted_items
# A buffered response's hosted items are array members: their fields are
# kept per member, a few short values each, for a bounded number of members.
self._member_leaves: dict[JSONPath, JSONPath] = (
{(*items.buffered_items, "*", *leaf): leaf for leaf in items.leaves} if items is not None else {}
)
self._member_path: JSONPath | None = (*items.buffered_items, "*") if items is not None else None
self._member_values: dict[JSONScope, dict[JSONPath, object]] = {}
self._members: list[dict[JSONPath, object]] = []
self._parser = SelectiveJSONParser(
_protocol_projection_paths(protocol),
self._visit,
)
@property
def retained_bytes(self) -> int:
return self._parser.retained_bytes + len(self._literal)
def feed_byte(self, byte: int) -> None:
if len(self._literal) < 16:
self._literal.append(byte)
else:
self._literal.clear()
self._literal_too_long = True
self._parser.feed_byte(byte)
def feed(self, chunk: bytes) -> None:
if not self._literal_too_long:
remaining = 16 - len(self._literal)
if len(chunk) <= remaining:
self._literal.extend(chunk)
else:
self._literal.clear()
self._literal_too_long = True
self._parser.feed(chunk)
def finish(
self,
*,
streamed: bool,
event_name: str | None = None,
previous_sequence_number: int = -1,
) -> ProtocolObservation:
literal = None if self._literal_too_long else bytes(self._literal)
if streamed and self.taxonomy.success_literal == (event_name, literal):
return ProtocolObservation(outcome="served", recovery_verified=True)
if not self._parser.finish() or () not in self._maps:
return ProtocolObservation(outcome="served" if not streamed else None)
usage = _usage_from_scalar_paths(self.taxonomy.usage, self._scalars)
served_tier = self._served_tier()
hosted_tools = self._hosted_tools(streamed=streamed)
model_output_started = any(
envelope.event_name == event_name and self._selector_matches(envelope)
for envelope in self.taxonomy.model_output_envelopes
)
sequence_number: int | None = None
if self.taxonomy.sequence_number_path is not None:
candidate = self._scalars.get(self.taxonomy.sequence_number_path)
if isinstance(candidate, int) and not isinstance(candidate, bool) and candidate >= 0:
sequence_number = max(previous_sequence_number, candidate)
if not streamed:
matched_paths = tuple(
path
for path in self.taxonomy.buffered_error_envelope_paths
if path in self._maps
)
type_candidates = self._machine_candidates("type", matched_paths)
code_candidates = self._machine_candidates("code", matched_paths)
return ProtocolObservation(
outcome="failed_terminal" if matched_paths else "served",
hosted_tools=frozenset() if matched_paths else hosted_tools,
error_envelope_paths=matched_paths,
error_message=self._error_message(matched_paths),
usage=usage,
error_type_candidates=(type_candidates if matched_paths else ()),
error_code_candidates=(code_candidates if matched_paths else ()),
recovery_verified=(
not matched_paths
and _buffered_recovery_verified(self.taxonomy, self._scalars, self._arrays, self._nonempty)
),
served_tier=served_tier,
)
for envelope in self.taxonomy.terminal_envelopes:
if envelope.event_name != event_name or not self._selector_matches(envelope):
continue
if (
envelope.required_error_path is not None
and envelope.required_error_path not in self._maps
):
continue
if envelope.required_error_code_path is not None:
code = self._scalars.get(envelope.required_error_code_path)
elided_nonempty_string = (
envelope.required_error_code_path in self._scalars
and code is None
and envelope.required_error_code_path in self._nonempty
)
if not (isinstance(code, str) and code) and not elided_nonempty_string:
continue
error_paths = (
envelope.error_envelope_paths
if envelope.terminal_outcome == "failed_terminal"
else ()
)
type_candidates = self._machine_candidates("type", error_paths)
code_candidates = self._machine_candidates("code", error_paths)
return ProtocolObservation(
outcome=envelope.terminal_outcome,
model_output_started=model_output_started,
error_envelope_paths=(
envelope.error_envelope_paths
if envelope.terminal_outcome == "failed_terminal"
else ()
),
sequence_number=sequence_number,
usage=usage,
error_message=self._error_message(error_paths),
error_type_candidates=(
type_candidates
if envelope.terminal_outcome == "failed_terminal"
else ()
),
error_code_candidates=(
code_candidates
if envelope.terminal_outcome == "failed_terminal"
else ()
),
recovery_verified=model_output_started or envelope.terminal_outcome == "served",
hosted_tools=hosted_tools,
served_tier=served_tier,
)
return ProtocolObservation(
model_output_started=model_output_started,
sequence_number=sequence_number,
usage=usage,
recovery_verified=model_output_started,
hosted_tools=hosted_tools,
served_tier=served_tier,
)
def _served_tier(self) -> ServedTier | None:
"""The tier this frame or buffered response names, by the protocol's own value for its fast tier."""
declared = self.taxonomy.served_tier
if declared is None:
return None
for path in declared.paths:
value = self._scalars.get(path)
if isinstance(value, str) and value.strip():
return "fast" if value.strip() == declared.fast_value else "standard"
return None
def _hosted_tools(self, *, streamed: bool) -> frozenset[str]:
"""The search tools whose own completed item this event or buffered response carries."""
items = self.taxonomy.hosted_items
if items is None:
return frozenset()
if streamed:
if self._scalars.get(("type",)) != items.event_type:
return frozenset()
members = [{leaf: self._field((*items.event_item, *leaf)) for leaf in items.leaves}]
else:
members = self._members
return frozenset(
tool for fields in members if (tool := _hosted_item_tool(self.protocol, fields)) is not None
)
def _field(self, path: JSONPath) -> object:
if path in self._arrays:
return _ARRAY
if path in self._maps:
return _MAP
return self._scalars.get(path)
def _visit(
self,
path: JSONPath,
event: JSONEvent,
value: object | None,
scope: JSONScope,
) -> None:
if scope and path in self._member_leaves and len(self._members) < _MAX_HOSTED_MEMBERS:
value_of = {"scalar": value, "start_array": _ARRAY, "start_map": _MAP}
if event in value_of:
self._member_values.setdefault(scope, {})[self._member_leaves[path]] = value_of[event]
if event == "scope_end" and path == self._member_path:
if (member := self._member_values.pop(scope, None)) is not None and len(self._members) < _MAX_HOSTED_MEMBERS:
self._members.append(member)
if event == "replace":
self._clear_path(path, scope)
elif event == "start_map" and not scope:
self._maps.add(path)
elif event == "start_array" and not scope:
self._arrays.add(path)
elif event in {"nonempty", "elided_string"}:
if scope:
self._scoped_nonempty.add((path, scope))
else:
self._nonempty.add(path)
elif event == "scalar":
if scope:
if bool(value):
self._scoped_nonempty.add((path, scope))
else:
self._scalars[path] = value
if bool(value):
self._nonempty.add(path)
elif event == "scope_end":
self._collapse_scope(scope)
def _collapse_scope(self, scope: JSONScope) -> None:
"""Fold a completed array member into its parent without retaining its index."""
if not scope:
return
completed = {
path
for path, candidate_scope in self._scoped_nonempty
if candidate_scope == scope
}
self._scoped_nonempty = {
candidate
for candidate in self._scoped_nonempty
if candidate[1] != scope
}
parent_scope = scope[:-1]
if parent_scope:
self._scoped_nonempty.update(
(path, parent_scope) for path in completed
)
else:
self._nonempty.update(completed)
def _clear_path(self, path: JSONPath, scope: JSONScope) -> None:
def inside(candidate: JSONPath) -> bool:
return candidate[: len(path)] == path
def inside_scope(candidate: tuple[JSONPath, JSONScope]) -> bool:
candidate_path, candidate_scope = candidate
return inside(candidate_path) and candidate_scope[: len(scope)] == scope
self._scoped_nonempty = {
candidate
for candidate in self._scoped_nonempty
if not inside_scope(candidate)
}
if scope:
return
self._maps = {candidate for candidate in self._maps if not inside(candidate)}
self._arrays = {candidate for candidate in self._arrays if not inside(candidate)}
self._nonempty = {candidate for candidate in self._nonempty if not inside(candidate)}
self._scalars = {
candidate: value
for candidate, value in self._scalars.items()
if not inside(candidate)
}
def _machine_candidates(
self,
field: Literal["type", "code"],
error_paths: tuple[ErrorEnvelopePath, ...],
) -> tuple[str, ...]:
candidates: list[str] = []
for error_path in error_paths:
value = self._scalars.get((*error_path, field))
if self.protocol == "google" and field == "code" and type(value) is int:
# Gemini error.code carries an HTTP status even inside SSE.
# Normalize only shaped native errors; classification retains
# sole ownership of retry/health policy.
value = GOOGLE_ERROR_STATUS_MACHINE_CODES.get(value)
if not isinstance(value, str):
continue
if self.machine_error_codes and value not in self.machine_error_codes:
continue
if value not in candidates and len(candidates) < 8:
candidates.append(value)
return tuple(candidates)
def _error_message(self, error_paths: tuple[ErrorEnvelopePath, ...]) -> str | None:
for error_path in error_paths:
value = self._scalars.get((*error_path, "message"))
if isinstance(value, str) and value.strip():
return value
return None
def _selector_matches(
self,
envelope: ProtocolTerminalEnvelope | ProtocolModelOutputEnvelope,
) -> bool:
if envelope.selector_value is not None:
return self._scalars.get(envelope.selector_path) == envelope.selector_value
if getattr(envelope, "require_nonempty", False):
return envelope.selector_path in self._nonempty
return envelope.selector_path in self._maps
def observe_buffered_protocol_response(
protocol: str,
reader: BinaryIO,
*,
machine_error_codes: AbstractSet[str] = frozenset(),
) -> ProtocolObservation:
"""Project buffered protocol facts without retaining the response body.
The taxonomy owns the small set of facts settlement needs: native error
envelopes, their machine fields, and usage. Everything else is parsed and
discarded while the exact bytes remain owned by the caller for replay.
"""
projector = ProtocolFactProjector(
protocol,
machine_error_codes=machine_error_codes,
)
while chunk := reader.read(64 * 1024):
projector.feed(chunk)
return projector.finish(streamed=False)
def _try_parse_payload(data: bytes) -> object | None:
"""Parse untrusted observation data without leaking parser failures."""
try:
return json.loads(data)
except (TypeError, ValueError, RecursionError):
return None
def observe_protocol_response(
protocol: str,
*,
streamed: bool,
data: bytes | None,
event_name: str | None = None,
previous_sequence_number: int = -1,
) -> ProtocolObservation:
"""Observe one response fact before any caller can construct success."""
taxonomy = PROTOCOL_STREAM_TAXONOMY[protocol]
if data is None:
return ProtocolObservation()
if streamed and taxonomy.success_literal == (event_name, data):
return ProtocolObservation(outcome="served", recovery_verified=True)
payload = _try_parse_payload(data)
if not isinstance(payload, dict):
if not streamed:
return ProtocolObservation(outcome="served")
return ProtocolObservation()
usage = extract_protocol_usage(protocol, payload)
# This legacy byte helper retains its forwarding policy, but its recovery
# evidence shares the incremental reader's handling of malformed JSON.
projector = ProtocolFactProjector(protocol)
projector.feed(data)
recovery_verified = projector.finish(
streamed=streamed,
event_name=event_name,
previous_sequence_number=previous_sequence_number,
).recovery_verified
if not streamed:
if any(
isinstance(value, Mapping)
for path in taxonomy.buffered_error_envelope_paths
for value in _path_values(payload, path)
):
return ProtocolObservation(
outcome="failed_terminal",
error_payload=data,
error_envelope_paths=taxonomy.buffered_error_envelope_paths,
usage=usage,
)
return ProtocolObservation(
outcome="served",
usage=usage,
recovery_verified=recovery_verified,
)
sequence_number: int | None = None
if taxonomy.sequence_number_path is not None:
sequence_values = _path_values(payload, taxonomy.sequence_number_path)
candidate = sequence_values[0] if len(sequence_values) == 1 else None
if isinstance(candidate, int) and not isinstance(candidate, bool) and candidate >= 0:
sequence_number = max(previous_sequence_number, candidate)
model_output_started = is_protocol_model_output(protocol, event_name, payload)
for envelope in taxonomy.terminal_envelopes:
if envelope.event_name != event_name:
continue
if not _selector_matches(
payload,
selector_path=envelope.selector_path,
selector_value=envelope.selector_value,
require_nonempty=envelope.require_nonempty,
):
continue
if envelope.required_error_path is not None and not any(
isinstance(value, Mapping) for value in _path_values(payload, envelope.required_error_path)
):
continue
if envelope.required_error_code_path is not None and not any(
isinstance(value, str) and value
for value in _path_values(payload, envelope.required_error_code_path)
):
continue
return ProtocolObservation(
outcome=envelope.terminal_outcome,
model_output_started=model_output_started,
error_payload=(data if envelope.terminal_outcome == "failed_terminal" else None),
error_envelope_paths=(
envelope.error_envelope_paths if envelope.terminal_outcome == "failed_terminal" else ()
),
sequence_number=sequence_number,
usage=usage,
recovery_verified=recovery_verified,
)
return ProtocolObservation(
model_output_started=model_output_started,
sequence_number=sequence_number,
usage=usage,
recovery_verified=recovery_verified,
)
@dataclass
class ProtocolSSEState:
"""Observe settlement facts without validating the upstream protocol stream."""
protocol: str
tokenizer: SSEObservationTokenizer = field(init=False)
terminal_outcome: StreamTerminalOutcome | None = None
error_payload: bytes | None = None
error_envelope_paths: tuple[ErrorEnvelopePath, ...] = ()
last_sequence_number: int = -1
model_output_started: bool = False
usage: ProtocolUsageReport | None = None
error_type_candidates: tuple[str, ...] = ()
error_code_candidates: tuple[str, ...] = ()
error_message: str | None = field(default=None, repr=False)
hosted_tools: frozenset[str] = frozenset()
# The tier the stream named: OpenAI repeats it on every Chat chunk and states
# it on the completed Responses event alone; Anthropic reports it in usage.
served_tier: ServedTier | None = None
def __post_init__(self) -> None:
self.tokenizer = SSEObservationTokenizer(self.protocol)
def observe(self, chunk: bytes) -> None:
frames = self.tokenizer.feed(chunk)
for frame in frames:
self._observe_frame(frame)
async def observe_async(self, chunk: bytes) -> None:
"""Observe one transport chunk without monopolizing the event loop."""
await run_owned_in_thread(self.observe, chunk)
def invalidate_partial_frame(self) -> bytes:
"""Make an already-forwarded partial frame non-terminal, then close it."""
line_open = self.tokenizer.discard_partial_frame()
if line_open is None:
return b""
line_break = b"\n" if line_open else b""
return line_break + b"data: {}\n\n"
@property
def next_sequence_number(self) -> int:
return self.last_sequence_number + 1
@property
def reached_model(self) -> bool:
"""Whether this stream got far enough upstream to have been billed.
Forwarded model output proves the call reached the model even when the
stream then ended without a recognized terminal — a connection lost after
a text delta is a request that happened, and `token_reports` staying at
zero is exactly how the ledger records that nobody reported its tokens.
Lives on the tracker rather than beside one of its readers, because both
sides of the hand-off keep a tracker over the same body and a fact read
from only one of them is a fact the other half of the turn cannot use.
"""
return self.terminal_outcome == "served" or self.model_output_started
def _observe_frame(self, frame: SSEObservedFrame) -> None:
observation = frame.observation
if self.terminal_outcome is not None:
# Google's finishReason completes model output, but the pinned
# Chat -> Gemini translator can send billing in a following frame.
# Preserve terminal truth; only that protocol's usage may advance.
if self.protocol == "google" and self.terminal_outcome == "served" and observation.usage is not None:
self.usage = observation.usage if self.usage is None else self.usage.merge(observation.usage)
return
if observation.model_output_started:
self.model_output_started = True
if observation.hosted_tools:
self.hosted_tools |= observation.hosted_tools
tier_paths = PROTOCOL_STREAM_TAXONOMY[self.protocol].served_tier
if tier_paths is not None and tier_paths.settled_by_terminal:
if observation.outcome is not None:
self.served_tier = observation.served_tier
elif observation.served_tier is not None:
self.served_tier = observation.served_tier
if observation.usage is not None:
self.usage = (
observation.usage if self.usage is None else self.usage.merge(observation.usage)
)
if observation.outcome in {"served", "failed_terminal"}:
self.terminal_outcome = observation.outcome
if observation.error_payload is not None:
self.error_payload = observation.error_payload
self.error_envelope_paths = observation.error_envelope_paths
elif observation.error_envelope_paths:
self.error_envelope_paths = observation.error_envelope_paths
if observation.error_type_candidates:
self.error_type_candidates = observation.error_type_candidates
if observation.error_code_candidates:
self.error_code_candidates = observation.error_code_candidates
if observation.error_message is not None:
self.error_message = observation.error_message
if observation.sequence_number is not None:
self.last_sequence_number = max(
self.last_sequence_number,
observation.sequence_number,
)
def terminal_observation(self) -> ProtocolObservation | None:
"""Report the settled facts, including everything accumulated to get here.
Usage often arrives before the terminal — Anthropic reports input tokens on
``message_start`` — so a terminal that dropped the accumulated report would
lose tokens the upstream already billed on exactly the streams that end
badly.
"""
if self.terminal_outcome is not None:
return ProtocolObservation(
outcome=self.terminal_outcome,
error_payload=self.error_payload,
error_envelope_paths=self.error_envelope_paths,
model_output_started=self.model_output_started,
usage=self.usage,
error_type_candidates=self.error_type_candidates,
error_code_candidates=self.error_code_candidates,
recovery_verified=self.reached_model,
error_message=self.error_message,
hosted_tools=self.hosted_tools if self.terminal_outcome == "served" else frozenset(),
served_tier=self.served_tier,
)
return None
def render_protocol_terminal_event(
protocol: str,
key: str,
message: str,
next_sequence_number: int,
) -> dict[str, object]:
"""Render a terminal outcome in the requested protocol's wire shape."""
try:
taxonomy = PROTOCOL_STREAM_TAXONOMY[protocol]
except KeyError as exc:
raise ValueError(f"unsupported terminal event protocol: {protocol}") from exc
return taxonomy.render_terminal_event(key, message, next_sequence_number)
def render_protocol_terminal_frame(protocol: str, payload: bytes) -> bytes:
"""Frame one locally projected terminal in the protocol's native SSE form."""
try:
event_name = PROTOCOL_STREAM_TAXONOMY[protocol].terminal_event_name
except KeyError as exc:
raise ValueError(f"unsupported terminal event protocol: {protocol}") from exc
event_line = b"" if event_name is None else b"event: " + event_name.encode() + b"\n"
return event_line + b"data: " + payload + b"\n\n"