# Public API
## Inference contracts
- `LlmFuture<'a>` is the pinned, boxed, sendable future returned by an inference call. It resolves to `Result<Inference, LlmError>` and may borrow the thread and delta for `'a`.
- `ToolFuture` is a pinned, boxed, sendable `'static` future resolving to `ToolOutput`.
- `ToolOutput` is cloneable, debuggable, and equality-comparable. Its public `text` is terminal tool text and `cost_cents` is its exact decimal cost in cents. Free tools use zero.
- `CompactFuture` is a pinned, boxed, sendable `'static` future resolving to `Result<String, String>`.
- `Llm` is a `Send + Sync` factory. `start` creates one boxed `LlmThread`.
- `LlmThread` is `Send`. `infer` mutably borrows the thread and accepts a borrowed delta for the lifetime of its returned `LlmFuture`.
- `LlmError` has `Transient(String)` and `Permanent(String)` variants.
- `Inference` has public `text`, `calls`, and `continue_inference` fields.
- `Call` contains `ToolRequest`, `WorkerRequest`, or `CompactRequest`.
- `ToolRequest` has public `name` and `input`; `WorkerRequest` has public `llm` and `prompt`; `CompactRequest` has public `instruction`.
- `ToolMode` has `Fast` and `Queued` variants. `ToolStart` exposes public `mode`, `queued`, and `future` fields. `WorkerStart` exposes public `llm` and `queued` fields.
- `Runtime: Send + Sync` starts tools, resolves worker models, and starts compaction. Setup callbacks are nonblocking; remote or expensive work belongs in returned futures.
Except for future-bearing start values, the value declarations above are cloneable, debuggable, and equality-comparable; `ToolMode` is also copyable.
## Durable action identity and updates
`ActionId` is a copyable, orderable, hashable value containing exactly a 12-byte session identity and one `u64` action sequence. `ActionId::new(session, sequence)` constructs it; `session()` and `sequence()` return those values. It performs no parsing, formatting, allocation, randomness, or validation.
`SubmittedUpdate` has `Activity(String)` and `Append(String)` variants. `UpdateSink: Send + Sync + 'static` receives an `ActionId`, private update identity, and owned update. `Updates::bind(action, sink)` creates an opaque cloneable handle, and `action_id()` exposes the durable action identity for tool-effect idempotency. `activity` and `append` prepare updates. `PreparedUpdate::send` synchronously invokes the sink and returns its result unchanged.
Each bind starts update identity allocation at one. `Updates` clones share one relaxed `AtomicU64`, so distinct preparations receive distinct identities. Cloning a `PreparedUpdate` retains the exact action ID, update identity, payload, and sink. Every send invokes the sink; downstream state deduplicates by action and update identity. The wrapper creates no task, channel, wait, retry, or timeout.
## Chat state
- `ChatView` has public `primary`, `pending`, `history`, and `actions` fields.
- `PendingAction` has `Inference { attempt }`, `Tool { name }`, `Worker { llm }`, and `Compaction` variants.
- `ChatEvent` has `Text(String)`, `Activity(String)`, and `Stalled(String)` variants.
- `ChatError` has `Empty`, `NotStalled`, `Busy`, and `Closed` variants.
These declarations are cloneable, debuggable, and equality-comparable.
## Retry leaf
`infer_with_retry` owns one boxed `LlmThread`, one delta, and a shared attempt byte. It invokes the same object with the identical delta up to five times. Immediately before each call it stores attempt 1 through 5 with relaxed ordering. A success returns immediately. A permanent failure returns its text immediately. Transient failures after attempts one through four wait exactly 10, 20, 40, and 80 seconds; the fifth transient returns without another wait.
An inference call has no timeout and may remain pending indefinitely. Calls never overlap, retries never replace the thread, and failures are not retained. Dropping the operation drops the active inference or timer and yields no returned thread.