Module session_driver 

Generic, explicitly user-authorized foreground session driving.

This module grants no authority by itself: the local frontend must obtain a permission-gated eager handler, bind it to an explicit user action/session, and recheck its identity before polling or committing a prepared proposal. Timers, terminal boundaries, cancellation and user-input arbitration belong to that frontend. Loop policy and prompts belong exclusively to the plugin.

Structs

Grant

An ephemeral allowlist and deadline, never persisted. Public identity fields are host bookkeeping, not values the plugin may update via subsequent replies.

PollRequest

Coarse host metadata only. decision_id is stable across transport retries; the independent command request_id is always fresh. Neither contains secrets.

Proposal

Selection

Enums

ContextMode

Optional session-local context policy requested by an explicit start only. Absent on older drivers means leave the current session preference unchanged.

Outcome

PrepareError

Reply

Functions

classify_error

Recognize only anchored host-generated API status forms. Never search arbitrary error/transcript text for “auth”, “429”, “quota” etc. Raw strings are not copied into the return value. Prefer classify_turn_error externally.

classify_turn_error

Typed provenance is mandatory at the frontend boundary. Even ProviderFailed includes local config/session/tool failures: these are NOT failover signals. Cancellation is Blocked here; the frontend must revoke without polling.

parse_reply

Parse only the structured top-level response, never printed output. Unknown fields inside the driver object/selections fail closed. Unrelated command response fields are allowed, but count toward the 64 KiB bound. Optional start selection is redundant and must exactly equal models[0]. It is removed here so the coordinated public Start enum has no extra field.

poll

Bounded asynchronous poll using the existing command.invoke frame contract. No spawned task or manager lock is retained here: dropping this future drops both invocation and collector. The frontend owns cancellation/generation.

prepare

Atomic session-only model/effort preparation. history is the EXISTING history: this function adds the proposed user message for full preflight. The caller commits returned Runtime plus its own session mirrors only on success, after rechecking cancellation/deadline/handler/session identity. No config writes, credential refresh, provider calls, or history mutation.

validate_prepared

Recheck dynamic catalog/media evidence immediately before frontend commit. Async credential preflight may have yielded while a capability was revoked.