tinyagents 2.1.1

A durable agent + graph harness for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

//! Durable session database and run ledger.
//!
//! SQLite-backed store (WAL + FTS5) for sessions, messages, tool calls, cost
//! metadata, and parent/child lineage, plus a [`run_ledger`] for background
//! agent/workflow execution state. This is the runtime's *history* layer: what
//! ran, what it cost, what it called, and how runs nest.
//!
//! # Why this is a top-level module
//!
//! Session history is a persistence domain in its own right, not a part of the
//! agent loop. Nothing in [`crate::harness`] reads from it, and a host can use
//! it without running a harness at all — indexing sessions produced elsewhere,
//! or recovering orchestration state at boot before any agent exists. Filing it
//! under `harness::` would imply a dependency that does not exist in either
//! direction.
//!
//! # Relationship to the other persistence layers
//!
//! - [`crate::harness::store`] is namespaced key-value storage for live
//!   runtime data. It is a substrate runs read and write during execution.
//! - [`crate::graph::checkpoint`] is durability for *resuming* an interrupted
//!   graph run.
//! - This module is queryable history. Nothing resumes from it; it answers
//!   "what happened", supports cross-session search, and lets a host recover
//!   orchestration state after a restart.
//!
//! A host that keeps its own transcript files (the source of truth for
//! KV-cache resume) still wants this module for indexing and search over them.
//!
//! # Layout
//!
//! Every entry point takes the workspace root and derives the database path,
//! so a host chooses only where its workspace lives:
//!
//! ```text
//! {workspace_dir}/session_db/sessions.db
//! ```
//!
//! # Example
//!
//! ```no_run
//! use std::path::Path;
//! use tinyagents::session::{self, SessionStatus};
//!
//! # fn main() -> tinyagents::Result<()> {
//! let workspace = Path::new("/tmp/workspace");
//!
//! session::record_session_start(
//!     workspace, "sess-1", "researcher", "Researcher", "sess-1",
//!     None, None, None, Some("gpt-5"), None,
//! )?;
//! session::record_message(
//!     workspace, "sess-1", "user", "summarize the repo", None, None, None, None,
//! )?;
//! session::record_session_end(
//!     workspace, "sess-1", SessionStatus::Completed, 1, 120, 340, 0, 0.004,
//! )?;
//! # Ok(())
//! # }
//! ```
//!
//! Requires the `sqlite` feature.
//!
//! See [`README.md`](./README.md) for the schema, the FTS behaviour, and the
//! coordination guarantees.

mod context;
mod migrations;
pub mod ops;
pub mod retention;
pub mod run_ledger;
mod store;
pub mod types;

pub use ops::{
    DEFAULT_FTS_SNIPPET_BYTES, fts_snippet_bytes, get_session, list_children, list_messages,
    list_sessions, list_tool_calls, mark_interrupted, record_message, record_session_end,
    record_session_start, record_tool_call, search_sessions, set_fts_snippet_bytes,
};
pub use retention::{
    RetentionReport, apply_retention, prune_run_events_before, prune_run_telemetry_before,
    prune_sessions_before, prune_tool_calls_before, reindex_fts, trim_session_messages,
};
pub use store::{db_path, with_connection, with_transaction};
pub use types::{
    SessionMessage, SessionRecord, SessionSearchParams, SessionSearchResult, SessionStatus,
    SessionToolCall,
};

#[cfg(test)]
mod test;