Durable session identity: resume a conversation by id, and stop losing history

crates/tinyagents-integration-tests/tests/feature_session_transcript.rs

@@ -11,6 +11,8 @@ use tinyagents_session::transcript::{
 
 fn meta(turn_count: usize, input_tokens: u64, output_tokens: u64) -> TranscriptMeta {
     TranscriptMeta {
+        session_id: None,
+        parent_session_id: None,
         agent_name: "researcher".into(),
         agent_id: Some("researcher-v1".into()),
         agent_type: Some("root".into()),

crates/tinyagents-integration-tests/tests/session_conformance.rs

@@ -33,6 +33,8 @@ fn run_ledger_satisfies_the_conformance_suite_on_a_second_independent_workspace(
 
 fn contract_meta() -> TranscriptMeta {
     TranscriptMeta {
+        session_id: None,
+        parent_session_id: None,
         agent_name: "contract-agent".to_string(),
         agent_id: Some("contract-agent-id".to_string()),
         agent_type: Some("root".to_string()),

crates/tinyagents-runtime/Cargo.toml

@@ -17,6 +17,7 @@ tinyagents-session = { path = "../tinyagents-session", version = "2.1.2" }
 tinyinference-llm = { path = "../../vendor/tinyinference/crates/tinyinference-llm", version = "0.3.0" }
 tinytools = { path = "../../vendor/tinytools/crates/tinytools", version = "0.4.1" }
 tokio = { workspace = true, features = ["macros", "rt", "sync"] }
+tracing = { workspace = true }
 
 [dev-dependencies]
 anyhow = { workspace = true }

crates/tinyagents-runtime/src/builder.rs

@@ -1,6 +1,6 @@
 use std::sync::Arc;
 
-use tinyagents_session::transcript::{TranscriptLocator, TranscriptMeta};
+use tinyagents_session::transcript::{SessionRef, TranscriptLocator, TranscriptMeta, session_stem};
 
 use crate::{
     NoopSessionHooks, PrefixSnapshot, RuntimeError, Session, SessionDriver, SessionHooks,
@@ -20,6 +20,8 @@ pub struct SessionBuilder<C: Clone + Send + Sync + 'static = ()> {
 struct TranscriptConfig {
     locator: Arc<dyn TranscriptLocator>,
     stem: String,
+    session: Option<SessionRef>,
+    resume_agent: Option<String>,
     meta: TranscriptMeta,
 }
 
@@ -71,18 +73,57 @@ impl<C: Clone + Send + Sync + 'static> SessionBuilder<C> {
         self.transcript = Some(TranscriptConfig {
             locator,
             stem: stem.into(),
+            session: None,
+            resume_agent: None,
             meta,
         });
         self
     }
 
+    /// Enables persistence addressed by durable session identity.
+    ///
+    /// Prefer this over [`Self::transcript`]: the stem it derives is stable
+    /// across processes and launches, so one conversation stays in one
+    /// transcript instead of accumulating a file per cold boot. It is also what
+    /// [`ResumeMode::Session`](crate::ResumeMode::Session) resolves against.
+    pub fn session(
+        mut self,
+        locator: Arc<dyn TranscriptLocator>,
+        session: SessionRef,
+        mut meta: TranscriptMeta,
+    ) -> Self {
+        meta.session_id = Some(session.session_id());
+        meta.parent_session_id = session.parent_session_id();
+        self.transcript = Some(TranscriptConfig {
+            locator,
+            stem: session_stem(&session),
+            session: Some(session),
+            resume_agent: None,
+            meta,
+        });
+        self
+    }
+
+    /// Uses a distinct agent key for `ResumeMode::LatestForAgent` lookup.
+    ///
+    /// Previously reachable only through a hook-supplied `ResumePreparation`,
+    /// which meant a host that simply wanted a different resume key had to
+    /// implement a hook to say so.
+    pub fn resume_agent(mut self, resume_agent: impl Into<String>) -> Self {
+        if let Some(config) = self.transcript.as_mut() {
+            config.resume_agent = Some(resume_agent.into());
+        }
+        self
+    }
+
     /// Builds a session. A codec is required only when transcript persistence
     /// or transcript resume is configured.
     pub fn build(self) -> Result<Session<C>, RuntimeError> {
         let target = self.transcript.map(|config| crate::TranscriptTarget {
             locator: config.locator,
             stem: config.stem,
-            resume_agent: None,
+            resume_agent: config.resume_agent,
+            session: config.session,
             meta: config.meta,
         });
         if target.is_some() && self.codec.is_none() {