Module store 

The state store contract and adapters.

agentd’s durability rests on four operations — put(key, seq, envelope) / get(key[, seq]) / list(prefix) / delete(key) — implemented by an adapter chosen in store.kind: mcp (any MCP server’s tools, mapped), http (plain HTTP), [file] (the local filesystem — durable for one host, single-writer), or memory (in-process; tests and dev). put is a compare-and-set on seq: the stored seq must be lower, else Conflict — the split-brain guard every caller treats as fatal. agentd links no database client and defines no schema beyond the Envelope.

Modules

file

The local-filesystem store — store.kind: file. One file per key, atomic writes, an exclusive instance lock, and traversal closed at the adapter.

http

The HTTP store: the four store operations as plain HTTP requests built from store.http.{get,put,list,delete} templates — GET/PUT/POST/DELETE {url} with an optional JSON body, extraction from body/status/headers. HTTPS (loopback http:// for dev), headers may carry {{secret:…}} references (resolved at dial time, never logged), the idempotency key rides as Idempotency-Key; conflict_status (default 409) maps to Conflict, 404 on a read to absent.

mapping

The mapping language the store adapters and the tool overrides share: render an argument object / URL / body from a template over named inputs, and extract a value from a result.

mcp

The MCP-mapped store: the four store operations are tools/calls against a declared MCP server, with argument templates and result extraction from store.mcp.{put,get,list,delete}. The default mapping is the checkpointer profile (state.put / state.get / state.list / state.delete), so a server advertising those tools needs no mapping at all.

memory

The in-process store — store.kind: memory. Keeps per-key history (so get(key, seq) works like a history-keeping server), enforces the seq CAS, supports list/delete, and offers fault injection for tests: fail the next N operations, add latency, or refuse a specific key. Not durable across the process (dev/test only — the loader warns).

Structs

Envelope

A versioned store record: state is the kind-specific payload; a tombstone carries state: null.

KeySeq

A list entry.

Enums

PutOutcome

The outcome of a put.

StoreError

Constants

ENVELOPE_VERSION

The envelope major this build writes and accepts. A record carrying any other major is refused as StoreError::Corrupt rather than guessed at: misreading a record’s shape would silently corrupt restored state.

Traits

Store

The four-operation store contract. Implementations are Send + Sync so the runtime’s executor pool can call them from any thread; every operation is bounded by the adapter’s timeout, so no store call can wedge a worker.

Functions

default_timeout

The store timeout class: store calls are management traffic rather than model traffic, so they inherit the management timeout unless the settings override it with an explicit store.timeout.

key

The store key layout: <prefix>/<instance>/<kind>/<id>. The instance segment keeps two agents sharing one backing store from colliding, and the kind segment lets a restore enumerate one entity kind by prefix alone.

open

Build the store an instance is configured with. servers resolves the mcp adapter’s coordination server by name; kind: none yields no store (the caller decides whether that is allowed).

parse_key

Split a key produced by key back into (kind, id) for the given prefix/instance; None for a foreign key.

with_retry

Bounded retry on Io errors (never on Conflict/Mapping/Corrupt).

Type Aliases

SharedStore

A shared store handle.