Struct ResponseBuffer 

pub struct ResponseBuffer { /* private fields */ }

Thread-safe response buffer with pause/resume and manual release/reject.

Hold duration is dynamically adjustable via [set_hold_duration] to support adaptive SLA — low-scoring agents can have their hold increased to give operators more review time.

Implementations

impl ResponseBuffer

pub fn new(hold_duration: Duration) -> Self

Create a new buffer with the given hold duration.

The hold duration initializes the response SLA for deadline-based release via [push_with_deadline]. The dashboard can later override the SLA via [set_response_sla].

Duration::ZERO means responses drain immediately (pass-through mode). Any non-zero duration is used as-is — callers control the review window.

pub fn hold_duration(&self) -> Duration

The current effective hold duration.

pub fn base_hold_duration(&self) -> Duration

The base hold duration as configured at startup.

pub fn set_hold_duration(&self, duration: Duration)

Dynamically update the effective hold duration.

Used by the adaptive SLA system to slow down or speed up the buffer based on agent scores.

pub fn set_response_sla(&self, sla: Duration)

Set the response SLA (used by [push_with_deadline] to compute release time).

Duration::ZERO disables the deadline (pass-through). Any non-zero value is used as-is.

pub fn response_sla(&self) -> Option<Duration>

Current response SLA duration, or None if not configured.

pub async fn push(&self, entry: BufferedResponse)

Add a completed response to the buffer.

pub async fn push_with_deadline( &self, entry: BufferedResponse, task_received: Instant, )

Add a completed response, computing release_at from the SLA deadline.

release_at = task_received + response_sla

The buffer holds the response for the full SLA duration. The rainfall animation on the dashboard runs for exactly this duration — card reaching the bottom = SLA expired = auto-release.

The orchestrator already sets round timeouts that respect all agent SLAs, so no reserve is needed at the buffer level.

Falls back to the caller-provided release_at if no SLA is configured.

pub async fn drain_ready(&self) -> Vec<BufferedResponse>

Drain entries whose release_at has passed, unless paused.

Returns the drained entries (caller is responsible for publishing + ack). When paused, always returns an empty vec.

pub async fn list(&self) -> Vec<BufferEntrySummary>

Return summaries of all buffered entries (for the dashboard UI).

pub async fn release(&self, id: &str) -> Option<BufferedResponse>

Manually release a specific entry by ID, regardless of hold duration.

Returns the entry if found, or None if not in the buffer.

pub async fn reject(&self, id: &str) -> Option<BufferedResponse>

Reject (discard) a specific entry by ID.

Returns the entry if found (caller should ack the message without publishing), or None if not in the buffer.

pub async fn drain_stale(&self, current_job_id: &str) -> Vec<BufferedResponse>

Remove all entries whose job_id does NOT match the given current job.

Returns the removed entries (caller is responsible for ack-ing them). This prevents stale responses from previous deliberations from lingering in the operator review queue.

pub fn pause(&self)

Pause the buffer: drain_ready() will return empty and the worker should also stop pulling new NATS tasks.

pub fn resume(&self)

Resume the buffer: drain_ready() resumes normal operation.

pub fn is_paused(&self) -> bool

Whether the buffer is currently paused.

pub fn set_auto_approve(&self, enabled: bool)

Enable or disable auto-approve mode.

When enabled, entries whose agent divergence is below the configured threshold are auto-released immediately instead of waiting for the hold timer or manual operator action.

pub fn is_auto_approve(&self) -> bool

Whether auto-approve mode is currently enabled.

pub fn set_auto_approve_threshold(&self, threshold: f32)

Set the divergence threshold for auto-approve (0.0 to 1.0).

Values are clamped to [0.0, 1.0]. Stored internally as thousandths.

pub fn auto_approve_threshold(&self) -> f32

Current auto-approve divergence threshold (0.0 to 1.0).

pub async fn auto_release_if_eligible(&self, divergence: Option<f32>) -> usize

When auto-approve is enabled and the agent’s divergence is at or below the threshold, mark all non-stopped pending entries for immediate release. The gate is strictly div > threshold → block, so a threshold of 1.0 (the default) releases every entry because compute_divergence clamps to [0.0, 1.0].

When divergence is None (no scores yet), the operator’s explicit opt-in to auto-approve takes precedence — entries are released. The threshold only blocks release when we have divergence data strictly exceeding the threshold.

Returns the number of entries marked for auto-release.

pub async fn len(&self) -> usize

Number of entries currently in the buffer.

pub async fn is_empty(&self) -> bool

Whether the buffer is empty.

pub async fn get_detail(&self, id: &str) -> Option<BufferEntryDetail>

Return the full detail of a specific buffer entry, including the deserialized response payload (for operator inspection/editing).

pub async fn update_payload(&self, id: &str, new_payload: Vec<u8>) -> bool

Update the payload of a specific buffer entry (operator edit).

Returns true if the entry was found and updated, false otherwise.

pub async fn add_comment( &self, id: &str, annotation: OperatorAnnotation, ) -> bool

Add an operator comment to a buffer entry without modifying the payload.

Returns true if the entry was found and annotated, false otherwise.

pub async fn mark_for_release(&self, id: &str) -> bool

Mark a buffer entry for immediate release by setting its release_at to now.

The entry stays in the buffer — the worker’s drain_buffer() loop will pick it up on the next cycle (≤500ms) and handle the NATS publish. This avoids needing a NATS client in the status server.

Note: The stopped flag is preserved. Stopped entries must be explicitly unstopped (or use [force_release]) before they can drain.

Returns true if the entry was found and marked, false otherwise.

pub async fn force_release(&self, id: &str) -> bool

Atomically unstop and mark a buffer entry for immediate release.

Combines [unstop] + [mark_for_release] in a single lock acquisition, eliminating the race window where drain_ready() could observe the entry as unstopped with a stale (already-passed) release_at.

Returns true if the entry was found, false otherwise.

pub async fn stop(&self, id: &str) -> bool

Stop (reversibly reject) a buffer entry.

Stopped entries remain in the buffer but are skipped by [drain_ready] — they won’t auto-release. The operator can later call [unstop] to make the entry eligible for release again.

Returns true if the entry was found and stopped, false otherwise.

pub async fn unstop(&self, id: &str) -> bool

Un-stop a previously stopped buffer entry.

The entry becomes eligible for [drain_ready] again. If its release_at has already passed, it will drain on the next cycle.

Returns true if the entry was found and un-stopped, false otherwise.

pub async fn update_payload_with_annotation( &self, id: &str, new_payload: Vec<u8>, annotation: OperatorAnnotation, ) -> bool

Update the payload of a buffer entry AND record an edit annotation.

Marks the entry as edited = true and appends the annotation. Returns true if the entry was found and updated, false otherwise.