Struct OutboxStore 

pub struct OutboxStore { /* private fields */ }

Implementations

impl OutboxStore

pub fn default_root() -> Result<PathBuf>

pub fn open(root: impl Into<PathBuf>) -> Result<Self>

pub fn open_existing_default() -> Option<Self>

Open at the default location only if it already exists — for read paths that must not create state as a side effect.

pub fn root(&self) -> &Path

pub fn stage( &self, tool: &str, kind: OutboxKind, args: Value, taint: Taint, session_id: Option<String>, workspace: Option<PathBuf>, ) -> Result<OutboxItem>

Stage a drafted call. No lock: the id is fresh, so there is no state to race on, and the agent loop must never wait on a review session.

pub fn items(&self) -> Result<Vec<OutboxItem>>

Every item, oldest first.

pub fn item(&self, id: &str) -> Result<OutboxItem>

Find one item by id or unique prefix. Ambiguity is an error rather than a guess, same as session and proposal lookup.

pub fn item_exact(&self, id: &str) -> Result<Option<OutboxItem>>

One item by its exact store-minted id — a single file read, never a directory scan. For the hot paths (a button press on an event loop) that already hold the full id and must not pay items()’s read-and-parse of every draft ever staged. Prefix lookup stays OutboxStore::item’s business.

The id is validated by shape before it is joined onto the store root: ids arrive here from button payloads, and a value shaped like a path (../…) must be refused, not resolved. A hostile shape is an error; a missing item is Ok(None); a torn file is an error, so a caller that maps errors to “unreadable” keeps failing closed.

pub fn update_args(&self, id: &str, args: Value) -> Result<OutboxItem>

Replace a pending item’s release arguments. args_before is untouched — it is the baseline the learning capture diffs against.

pub fn resolve( &self, id: &str, status: &str, reason: Option<String>, ) -> Result<OutboxItem>

Resolve a pending item as sent or rejected, in place — the file is its own audit record, so nothing moves to an archive.

pub fn record_error(&self, id: &str, error: &str) -> Result<()>

Record a failed release attempt. The item stays pending: the draft is still good, and the next send retries.

pub fn lock(&self) -> Result<OutboxLock>

Writer lock for read-modify-write paths (edit, send, reject). Taken before reading the item acted on; never held across $EDITOR.