Host integration

Host integration

The host owns storage, model clients, authorization, scheduling, and durable appends. TinyHiveMind takes snapshots or narrow ports and returns decisions. Use only the crates needed for the application path described in Integration crates.

Transcript reads

SessionLog::read_before is the waiting boundary for live transcript projection. It returns newest-first rows, treats before as an exclusive sequence bound, respects limit, and never repeats a sequence. project_session checks these rules before giving a viewer chronological, attributed messages. A bad page produces a typed error rather than a plausible but incorrect history. See Transcript projection.

The host stores SharingState and commits a new watermark only after the corresponding rows have been appended. The pinboard and thread index are bounded views over the same log. For a longer lived channel, Digester is a port for producing a bounded account of older visible rows. The host stores the accepted digest; it never replaces source rows. See Recall.

Routing and responder choice

Core folds resolve desks, rosters, mentions, approval, referrals, and responder plans from supplied data. For an auto responder, responder_plan may return a SelectionRequest. The host calls its model and passes the result through accept_selection or accept_evaluation. Invalid output uses the plan's deterministic fallback. Responder ladder gives the rungs.

The pure mention_dispatch and referral decisions can authorize a child turn. If the host enables them, it must recheck the committed source row, authorization, policy, and target availability before an atomic, idempotent enqueue. A referral can cross conversations, so the host checks both sides and keeps its origin until the answer returns. The runtime wrappers and queue ports used in earlier examples were retired. The cross-desk referral page describes the retained fold.

The pure approve decision returns Allow, Deny, or Ask. The host handles any human prompt, grant storage, and retry policy after Ask. There is no runtime request_approval wrapper.

For semantic routing, tinyhivemind_core::embed consumes a host Router; tinyhivemind_core::typesafe can implement it through JevRouter and a host SystemOneTransport. The host supplies credentials and model transport.

Deliberation and completion

A hive step returns a decision or HiveStep::Speak with bounded turns and one next_state. Run the authorized turns, durably append each reply, then commit that state. A blind round may run concurrently because each seat's view omits its peers' current contributions. Episode policy covers the bounds.

For completion episodes, bind host handles through tinyhivemind_core::driver::BoundHive. The driver and Conductor propose rows and seats; the host appends each row and reports its sequence. Save conductor state with application state if an episode must resume after a restart. tinyhivemind-tools::EpisodeTools supplies native episode tool definitions, call validation, and a record to drain into the driver.

The OpenHuman adapter offers HostedRunner for host-built agents and EmbedRunner for openhuman-embed agents with native tools. run_episode and resume_episode use a host-owned Journal. The former TinyHiveMind MCP server and RawRunner integration have been retired. This does not affect a host's own MCP tools, such as a DeepSWE tool server. See Integration crates and ADR 0027.

What the host must supply

The trace grammar parses authored markers; it does not teach an agent to use them. The host explains the current moves in its prompt, including topic names, citations, and when to commit. Keep a turn's projected view consistent with its audience and visibility. Decide hop limits, quorum policy, turn budgets, and whether child turns are enabled. Keep all app-specific authorization and storage beside the app.

Each crate is publish = false. A consumer pins this repository as a submodule and uses path dependencies. The pinned commit is the version, so the library change lands before the consumer updates its pointer.