feat(harness): add session_store — durable session history and run ledger

Cargo.toml

@@ -45,6 +45,10 @@ reqwest = { version = "0.12", default-features = false, features = [
 # Optional embedded SQLite checkpointer backend (`graph::checkpoint::sqlite`).
 # `bundled` compiles SQLite from vendored C source so no system library is
 # required; the dependency is pulled in only by the `sqlite` feature.
+# `bundled` compiles SQLite with FTS5 already enabled, which
+# `harness::session_store` relies on for its `sessions_fts` cross-session
+# search table. There is no separate `fts5` cargo feature at this version — do
+# not add one, it does not resolve.
 rusqlite = { version = "0.40", features = ["bundled"], optional = true }
 
 # Optional embedded Rhai scripting engine powering the `.ragsh` REPL session
@@ -54,7 +58,9 @@ rusqlite = { version = "0.40", features = ["bundled"], optional = true }
 rhai = { version = "1", features = ["sync"], optional = true }
 
 # Optional builtin tool family for deterministic time/date helpers.
-chrono = "0.4"
+# `serde` is required by `harness::session_store`, whose records carry
+# `DateTime<Utc>` timestamps across the serde boundary.
+chrono = { version = "0.4", features = ["serde"] }
 chrono-tz = { version = "0.10", optional = true }
 
 [features]
@@ -75,6 +81,9 @@ tools = ["dep:chrono-tz"]
 
 [dev-dependencies]
 tokio = { version = "1", features = ["macros", "rt-multi-thread", "time", "test-util"] }
+# Throwaway workspace roots for `harness::session_store` tests, which exercise
+# the real on-disk SQLite path rather than an in-memory database.
+tempfile = "3"
 # `.env` loading for the runnable examples.
 dotenvy = "0.15"
 # Stream combinators (`StreamExt::next`) for integration tests that drive a

src/error.rs

@@ -221,4 +221,27 @@ pub enum TinyAgentsError {
     /// (checkpoints, model wire formats, structured output, blueprints).
     #[error("serialization error: {0}")]
     Serialization(#[from] serde_json::Error),
+
+    /// A durable-storage operation failed — opening, migrating, reading, or
+    /// writing a backing database for the session store and run ledger
+    /// ([`crate::session`]).
+    ///
+    /// Distinct from [`TinyAgentsError::Checkpoint`], which covers graph
+    /// checkpoint durability: a session-store failure means run *history* could
+    /// not be recorded or queried, while a checkpoint failure means a run
+    /// cannot be resumed. The payload carries the operation context and the
+    /// underlying driver message.
+    #[error("storage error: {0}")]
+    Storage(String),
+}
+
+/// Converts a raw `rusqlite` failure into [`TinyAgentsError::Storage`] so the
+/// session store and run ledger can use `?` on driver calls directly. Call
+/// sites that have useful context to add should still map explicitly rather
+/// than relying on this bare conversion.
+#[cfg(feature = "sqlite")]
+impl From<rusqlite::Error> for TinyAgentsError {
+    fn from(err: rusqlite::Error) -> Self {
+        Self::Storage(err.to_string())
+    }
 }

src/lib.rs

@@ -79,6 +79,29 @@ pub mod registry;
 pub mod repl;
 #[cfg(feature = "rlm")]
 pub mod rlm;
+/// Durable session history and run ledger — a persistence domain in its own
+/// right, not part of the agent-loop harness. Requires the `sqlite` feature.
+#[cfg(feature = "sqlite")]
+pub mod session;
+
+// --- Session: durable session history + run ledger (feature `sqlite`) ---
+// Centralized here per AGENTS.md so downstream users get a predictable surface
+// rather than reaching through the module path. The record/query entry points
+// and the ledger's coordination types are the surface a host actually binds
+// against; the rest stays reachable via `session::` for callers that want it.
+#[cfg(feature = "sqlite")]
+pub use session::run_ledger::{
+    AgentRun, AgentRunKind, AgentRunStatus, AgentRunUpsert, AgentTeam, AgentTeamMember,
+    AgentTeamMemberStatus, AgentTeamStatus, AgentTeamTask, AgentTeamTaskStatus, ClaimOutcome,
+    CompletionOutcome, RunEvent, RunEventAppend, RunTelemetry, RunTelemetryUpsert, WorkflowRun,
+    WorkflowRunStatus, WorkflowRunUpsert,
+};
+#[cfg(feature = "sqlite")]
+pub use session::{
+    SessionMessage, SessionRecord, SessionSearchParams, SessionSearchResult, SessionStatus,
+    SessionToolCall, get_session, list_sessions, record_message, record_session_end,
+    record_session_start, record_tool_call, search_sessions,
+};
 
 // --- Error: the crate-wide error type and `Result` alias ---
 pub use error::{Result, TinyAgentsError};

src/session/README.md

@@ -0,0 +1,118 @@
+# `session` — durable session history and run ledger
+
+SQLite-backed history for agent sessions, and a restart-survivable ledger for
+background agent/workflow execution. Requires the `sqlite` feature.
+
+## Why this is a top-level module
+
+Session history is a persistence domain in its own right, not part of the agent
+loop. Nothing in `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 exists in neither direction.
+
+## How it differs from the other persistence layers
+
+| Layer | Question it answers | Lifetime |
+| --- | --- | --- |
+| `harness::store` | "what is this run working with right now?" | during a run |
+| `graph::checkpoint` | "how do I resume this interrupted run?" | until resumed |
+| **`session`** | "what happened, what did it cost, how did runs nest?" | indefinitely |
+
+Nothing resumes from this module. It is queryable history: cross-session search,
+cost attribution, and orchestration recovery.
+
+## Layout
+
+Every entry point takes the workspace root and derives the path itself, so a
+host chooses only where its workspace lives:
+
+```text
+{workspace_dir}/session_db/sessions.db
+```
+
+## Public surface
+
+Re-exported from the crate root (see `src/lib.rs`); the full surface stays
+reachable under `session::` and `session::run_ledger::`.
+
+- **Recording** — `record_session_start`, `record_message`, `record_tool_call`,
+  `record_session_end`
+- **Querying** — `get_session`, `list_sessions`, `search_sessions`,
+  `list_messages`, `list_tool_calls`, `list_children`
+- **Recovery** — `mark_interrupted`
+- **Run ledger** — agent runs, workflow runs, teams, members, tasks, run events,
+  and telemetry, with the claim/completion coordination primitives
+- **Connections** — `with_connection` (autocommit) and `with_transaction`
+  (`BEGIN IMMEDIATE`)
+
+## Schema
+
+Six tables plus one FTS5 virtual table, created on demand and idempotently:
+
+| Table | Holds |
+| --- | --- |
+| `sessions` | one row per session; lineage via `parent_session_id` |
+| `session_messages` | per-message content, model, tokens, cost |
+| `session_tool_calls` | tool name, input, bounded output, status, duration |
+| `sessions_fts` | FTS5 index over session name, message content, tool name |
+| `agent_runs` / `workflow_runs` | background execution state |
+| `run_events` / `run_telemetry` | per-run event stream and rollups |
+| `agent_teams` / `agent_team_members` / `agent_team_tasks` | team coordination |
+
+WAL journaling and `foreign_keys = ON`. FTS5 comes from `rusqlite`'s `bundled`
+build — there is no separate `fts5` cargo feature at 0.40, so do not add one.
+
+## Operational constraints
+
+These are the non-obvious rules; each is pinned by a test in `test.rs`.
+
+**Search input is plain text, not FTS5 syntax.** `SessionSearchParams::query` is
+translated to a quoted FTS5 expression before it reaches `MATCH`. Binding raw
+user input made ordinary strings (`C++`, `foo-bar`, `file.rs`) fail with a
+syntax or `no such column` error instead of searching.
+
+**Indexed content is truncated on a character boundary.** Slicing at a raw byte
+offset panics on multi-byte input, and because the message insert has already
+committed, the row would survive with no FTS entry — silently unsearchable.
+
+**Tool output is bounded** to `MAX_TOOL_OUTPUT_BYTES`, truncated on a character
+boundary with a marker appended.
+
+**Telemetry counters are `Option` for partial updates.** The columns are
+`NOT NULL DEFAULT`, and SQLite does not apply a column default to an explicitly
+supplied `NULL`, so the insert path coalesces to the default while the update
+path coalesces to the stored value. `excluded.*` cannot serve the update side —
+it observes the already-coalesced row, so `None` would read as `0` and clobber a
+stored counter.
+
+**Run-event sequences are allocated by the INSERT itself.** Reading
+`MAX(sequence) + 1` and then inserting is a read-modify-write race; the loser
+fails the primary key and the event is lost.
+
+**Coordination operations need `with_transaction`, not `with_connection`.**
+`with_connection` is autocommit, which gives ordering but no isolation. Claim
+and completion read state and then act on it, so they take the write lock up
+front with `BEGIN IMMEDIATE` — racing claims serialize at `BEGIN` rather than
+failing at `COMMIT` after one has already decided it won.
+
+**A claim is meaningful only while a task is `in_progress`.** An upsert that
+moves a task off that status clears `claimed_by_member_id` and `claim_token`;
+leaving them set strands the task, since a new claim sees `AlreadyClaimed`,
+completion sees `NotClaimed`, and release/shutdown skip it.
+
+**Evidence accumulates across completion attempts,** including attempts whose
+gate fails — otherwise a retry after fixing an unrelated gate would fail
+`require_evidence` on evidence already submitted.
+
+## Layout of this module
+
+| File | Role |
+| --- | --- |
+| `mod.rs` | module docs and public surface |
+| `types.rs` | serde record types |
+| `store.rs` | connection/transaction helpers and schema init |
+| `ops.rs` | recording and querying |
+| `context.rs` | `StorageContext`, the error-context shim |
+| `run_ledger/` | background run + team coordination |
+| `test.rs` | module-local unit tests |

src/session/context.rs

@@ -0,0 +1,38 @@
+//! Error-context helper for the session store's SQLite surface.
+//!
+//! The store and run ledger are dense with driver calls whose bare failures
+//! (`no such table`, `database is locked`) say nothing about which operation
+//! raised them. This trait attaches that operation context while funnelling
+//! everything into [`TinyAgentsError::Storage`], so the crate keeps one error
+//! type without every call site writing the same closure.
+//!
+//! It deliberately mirrors the shape of `anyhow::Context` — including the
+//! `Option` impl for "row expected but absent" — because this module was
+//! ported from a host that used `anyhow`, and matching the shape kept that
+//! port mechanical and reviewable.
+
+use std::fmt::Display;
+
+use crate::error::{Result, TinyAgentsError};
+
+/// Attaches operation context to a fallible storage call, producing a
+/// [`TinyAgentsError::Storage`].
+pub(crate) trait StorageContext<T> {
+    /// Wraps the failure as a storage error prefixed with `context`.
+    fn storage_context(self, context: &str) -> Result<T>;
+}
+
+impl<T, E: Display> StorageContext<T> for std::result::Result<T, E> {
+    fn storage_context(self, context: &str) -> Result<T> {
+        self.map_err(|err| TinyAgentsError::Storage(format!("{context}: {err}")))
+    }
+}
+
+/// A `None` where a row was expected is a storage inconsistency, not a
+/// user-facing absence — the callers using this read back a record they just
+/// wrote, so `None` means the write silently failed.
+impl<T> StorageContext<T> for Option<T> {
+    fn storage_context(self, context: &str) -> Result<T> {
+        self.ok_or_else(|| TinyAgentsError::Storage(context.to_string()))
+    }
+}