Crate hotl_types 

L1 — canonical conversation types.

Pure data + serde. No tokio, no I/O. Forward-compat serde is policy: #[serde(other)] Unknown on persisted enums, format_version in the session header, optional fields default + skip-when-none.

Assistant content is kept as verbatim provider blocks (serde_json::Value) rather than re-typed structs: signed thinking blocks must echo back to the provider byte-faithfully or replay breaks (review A11), and unknown future block types survive a round-trip losslessly. Typed views are provided for the engine (assistant_text, assistant_tool_uses).

Structs

Entry

One appended log record. parent_id forms a chain (a tree from M3); M0 logs are strictly linear.

Question

A structured multiple-choice question the agent asks the human (ask_user) — a header, a prompt, and 2-4 labelled options (plus an always-available free-text “other” the surfaces provide, not encoded here). multi reserves multi-select for a future surface; today’s surfaces treat every question as single-select.

QuestionOption

One selectable choice in a structured Question (ask_user, tier-1 gap #4). description is an optional one-line elaboration shown under the label.

SessionHeader

Todo

TokenUsage

Normalized usage; fields absent from a provider response default to zero.

ToolResultItem

ToolUse

A tool invocation extracted from assistant blocks.

Enums

EntryPayload

Item

One conversation item. Internally tagged so #[serde(other)] can absorb item kinds this binary doesn’t know yet (payload dropped, no crash).

QuestionAnswer

A human’s answer to an ask_user question (tier-1 gap #4). Lives here (not hotl-engine, where the plan first sketched it) so both hotl-tools’s QuestionSink and hotl-engine’s EngineEvent::Question can share one definition without either crate depending on the other — the same cycle-avoidance the plan flagged as open, resolved the way Question itself already is. NoHuman is the documented default when no reply arrives (headless, DontAsk, a dropped reply channel): the model must always get an answer, never a hang.

StopReason

Why a sample stopped. Other absorbs stop reasons newer than this binary.

SyntheticReason

Structural provenance on every injected user item (grok 04): no consumer ever parses message text to learn where it came from.

TodoStatus

A session checklist item (todo_write, M4/tier-1 gap #3). Full-state replace: the model rewrites the whole list each call, so there is no separate id/patch shape to reconcile.

Constants

FORMAT_VERSION

Bumped only on breaking changes to the persisted entry format.

Functions

assistant_text

Concatenated text of the assistant’s text blocks.

assistant_tool_uses

Tool-use blocks in source order.

new_ulid

normalize_session_name

A session display name: trimmed, non-empty, at most 64 chars. The one validator every entry point (CLI, ACP, TUI) funnels through.