Struct SharedState 

pub struct SharedState { /* private fields */ }

A shared string key-value store for sub-agent communication.

Cheaply cloneable (wraps Arc). Delegates all operations to a pluggable SharedStateBackend.

Scoping

Sharing is the point of this type — a parent stores an artifact once and several sub-agents read it by reference. So the default is a single flat namespace where every holder sees every key.

When a sub-agent should not see its siblings’ data, hand it a scoped view via scoped. Keys are transparently prefixed, and keys / summary report only that scope with the prefix stripped — so the sub-agent cannot enumerate, read, or overwrite anything outside it. Prefixing is applied on the way in, so a crafted key cannot escape the scope. The unscoped handle still sees everything, which is what lets the parent collect results.

let state = SharedState::new();
let researcher = state.scoped("researcher");
researcher.set("notes", "…".into()).await.unwrap();

// A sibling sees nothing of it.
assert!(state.scoped("writer").get("notes").await.is_none());
// The parent does.
assert!(researcher.get("notes").await.is_some());

Implementations

impl SharedState

pub fn new() -> Self

Create a new in-memory store with the default 10 MB capacity.

pub fn with_max_bytes(max_bytes: usize) -> Self

Create a new in-memory store with a custom byte capacity.

pub fn with_backend(backend: impl SharedStateBackend + 'static) -> Self

Create a store backed by a custom backend.

pub fn scoped(&self, scope: impl AsRef<str>) -> Self

A view of this store restricted to scope.

The view shares the same backend, so the parent still sees everything the scope writes. Scoping a scoped view nests (a then b behaves as a/b), so a sub-agent cannot widen its own access.

pub fn scope(&self) -> Option<&str>

The scope this view is restricted to, if any.

pub async fn get(&self, key: &str) -> Option<String>

Get a value by key. Returns None if the key doesn’t exist.

pub async fn set( &self, key: &str, value: String, ) -> Result<(), SharedStateError>

Store a value. Returns Err if the backend rejects it (capacity, I/O, etc.).

pub async fn remove(&self, key: &str) -> bool

Remove a key. Returns true if the key existed.

pub async fn keys(&self) -> Vec<String>

List keys (sorted). A scoped view lists only its own, prefix stripped.

pub async fn prompt_summary(&self) -> String

Summary for a system prompt: like summary but excluding machine-generated truncation stashes.

The system prompt is the most prefix-cache-sensitive text in a request. A stash entry appearing here would change the prompt on every truncation, breaking the cache on every subsequent turn and filling it with kilobyte-sized keys nobody asked about. The model can still discover them at runtime via the shared_state tool’s list, which uses the complete summary.

pub async fn summary(&self) -> String

Human-readable summary of stored variables (key names + byte sizes). Suitable for injecting into a system prompt.

A scoped view summarizes only its own keys. This matters more than the other accessors: the summary is injected into the sub-agent’s system prompt, so an unscoped one would disclose every sibling’s key names.

Trait Implementations

impl Clone for SharedState

fn clone(&self) -> SharedState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for SharedState

fn default() -> Self

Returns the “default value” for a type.