Expand description
§K1 chat-thread session provider 0.1.0
SessionProvider is the provider-execution owner for one Session Actor. new(adapter, base_key, sender) starts at generation zero with the base key and a fresh ActorShim.
job, active_key, inference_active, and mailbox_flush_active expose the current correlation state. Active means a spawned operation still awaits acceptance of its correlated completion.
drive(durable, usage, view) does nothing while inference is active or no shim is available. Otherwise it begins one durable input, subscribes model usage when needed, records the exact Turn input in the view, moves the shim into a spawned inference, records the job, and sends Message::Inferred on completion. Subscription failure is model-usage subscription failed.
launch_mailbox_flush(durable, view, prepared) rejects overlap with overlapping Codex mailbox flushes, validates and renders the prepared durable input, records the exact MailboxFlush input in the view, and spawns Adapter::steer for the active key. Completion is sent as Message::MailboxFlushCompleted with the current job and unchanged preparation.
accept_mailbox_flush(durable, job, prepared, result) requires both the live flush handle and exact current job before removing the handle. A mismatch is stale Codex mailbox-flush completion. It then propagates the provider result and commits the prepared durable flush. accept_inferred(job) similarly requires a live inference handle, no live mailbox flush, and the exact current job before removing the handle; mismatch is stale Codex inference completion.
settle_success(shim) restores the shim and clears the job. settle_failure() clears the job and leaves the shim absent. prepare_restart() returns an opaque RestartPlan for the next generation or ActorError::NotRestartable on overflow without changing provider state. After the caller’s durable restart succeeds, install_restart(plan) installs that generation, its base_key#restart-N key, and a fresh shim.
abort() aborts and removes both spawned handles. It deliberately preserves the current job and does not restore a shim; the caller remains responsible for durable failure and settlement semantics.
The provider has no internal locks or caller-visible queue. Inference and mailbox steering run in spawned tasks and report through the actor’s unbounded channel, so slow provider work does not block unrelated actor receives; the adapter retains ownership of same-key serialization. Distinct providers share no state here. The package owns no durable restart, terminal completion, tool execution, authorization, retry, deployment, or provider-selection policy.