Struct SessionTargetHandle

Source

pub struct SessionTargetHandle<'a> { /* private fields */ }

Expand description

A scoped handle for operations on a specific target within a session.

Created via Session::target(). Carries the target, email, and timestamp from the session so callers never have to pass them.

§Example

let session = Session::discover()?;
let handle = session.target(&Target::parse("commit:abc123")?);
handle.set("agent:model", "claude")?;
let val = handle.get_value("agent:model")?;

Implementations§

Source §

impl<'a> SessionTargetHandle<'a>

Source

pub fn get_value(&self, key: &str) -> Result<Option<MetaValue>>

Get a metadata value by key.

Source

pub fn set(&self, key: &str, value: impl Into<MetaValue>) -> Result<()>

Set a metadata value with convenience conversion.

Accepts anything that converts to MetaValue: &str, String, Vec<ListEntry>, BTreeSet<String>, or MetaValue directly.

handle.set("key", "hello")?;                    // string
handle.set("key", MetaValue::String("hello".into()))?; // explicit

Uses the session’s email and timestamp automatically.

Source

pub fn set_record(&self, prefix: &str, record: impl Serialize) -> Result<()>

Merge string metadata fields under a common key prefix.

The record must serialize to a JSON object. Object field names, including serde renames, become key suffixes. String values are written as prefix:field.

This is a partial update, not a replacement operation. Null fields are skipped and existing keys are left untouched. This makes Option<T> fields useful for patch-style records, but callers that need to clear a field must remove that key explicitly.

#[derive(serde::Serialize)]
#[serde(rename_all = "kebab-case")]
struct Source<'a> {
    agent: &'a str,
    tool_version: Option<&'a str>,
}

handle.set_record("agent-session:abc:source:def", &Source {
    agent: "codex",
    tool_version: Some("1.2.3"),
})?;

// Later updates that serialize `tool_version` as null do not remove the
// existing `agent-session:abc:source:def:tool-version` key.
handle.set_record("agent-session:abc:source:def", &Source {
    agent: "codex",
    tool_version: None,
})?;

Source

pub fn get_record<T>(&self, prefix: &str) -> Result<Option<T>>
where T: DeserializeOwned,

Read string metadata fields under a common key prefix into a record.

This is the read-side pair to set_record. Immediate child keys like prefix:field become JSON object fields before being deserialized into T. Missing records return Ok(None). Nested keys such as prefix:child:field are ignored because they belong to a deeper metadata subtree, not this record.

Because set_record leaves null or omitted fields untouched, get_record reads the current merged field set under the prefix, not the exact last value passed to set_record.

§Errors

Returns an error if an immediate child field exists but is not a string, or if the collected fields do not deserialize into T.

Source

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

Remove a metadata key.

Uses the session’s email and timestamp automatically.

Source

pub fn list_push(&self, key: &str, value: &str) -> Result<()>

Push a value onto a list.

Uses the session’s email and timestamp automatically.

Source

pub fn apply_edits<'b>( &self, edits: impl IntoIterator<Item = MetaEdit<'b>>, ) -> Result<()>

Apply metadata edits in one transaction.

Empty edit batches are no-ops. If any edit fails, none of the batch is committed. The session email and timestamp are used for every edit. List entry timestamps are adjusted only for list append edits, and edits that touch the same key are applied in caller-provided order.

Source