Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(hooks): bound the observations SessionEnd loads for a huge session

Djalma Júnior1170a336390a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1a9a3964..a6bcb0b2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,21 @@ version in [`docs/changelog/`](docs/changelog/):
## [3.0.1] - 2026-10-15
### Fixed
+- Fixed SessionEnd loading every observation of the session into memory, up
+ to three times, on the hook path. One production claude-code session held
+ 948,136 observations, so ending it deserialized close to a million rows
+ (bodies included) per read. The lifecycle-only decision is now one
+ `EXISTS` query, and the summary page and the auto-handoff are rendered from
+ bounded reads taken in one read transaction: SQL aggregates for the counts
+ and the "last of a kind" markers, the 250 first and 250 last rows the raw
+ list prints, and early-exit scans for the first or last prompt that passes
+ the usual filters. The page, the handoff and the lifecycle-only decision are
+ unchanged byte for byte (an equivalence test holds them to the original
+ row-list code on sessions of every shape). What still grows with the session
+ is what the page itself lists: the title of every user prompt. The PreCompact
+ and PostCompaction checkpoint page uses the same bounded reads. The writer's
+ lifecycle-only re-check and the reader now build their query from one shared
+ predicate. (#PRNUM)
- Fixed the WinSW v2.12.0 service-account example using the v3
`<username>` element. WinSW v2.12.0 expects separate `<domain>` and `<user>`
elements; it ignored `<username>` and installed the service as
diff --git a/crates/ai-memory-hooks/src/lib.rs b/crates/ai-memory-hooks/src/lib.rs
index 38f366f7..984f1875 100644
--- a/crates/ai-memory-hooks/src/lib.rs
+++ b/crates/ai-memory-hooks/src/lib.rs
@@ -62,7 +62,7 @@ pub use router::{
DEFAULT_PROJECT_CACHE_MAX_ENTRIES, HookState, IngestGates, IngestRateLimiter, ProjectCache,
ProjectCacheStore, SubagentSessionSet, SubagentSessions, hook_router,
};
-pub use synth::synthesize_session_page;
+pub use synth::{DigestLoadStats, SessionDigest, synthesize_session_page};
pub use workstream::{WorkstreamState, workstream_router};
/// Request header every first-party client (native hook and CLI, the shell and
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index 15f6dc04..4498d270 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -16,8 +16,8 @@ use ai_memory_consolidate::Consolidator;
use ai_memory_core::{
ActiveProject, ActorKey, AgentKind, DEFAULT_WORKSPACE_NAME, Handoff, IdentityKey,
MANAGED_WORKSTREAM_PACKET_MARKER, ManagedRunId, MidSessionRouting, NewHandoff, NewObservation,
- NewSession, ObservationKind, PageId, PagePath, ProjectId, Sanitized, Sanitizer, SessionId,
- WorkspaceId, WorkstreamEvent, WorkstreamEventKind, truncate_utf8_bytes,
+ NewSession, PageId, PagePath, ProjectId, Sanitized, Sanitizer, SessionId, WorkspaceId,
+ WorkstreamEvent, WorkstreamEventKind, truncate_utf8_bytes,
};
use ai_memory_store::{
HookSessionAdmission, IngestObservationOutcome, StoreError, WriterHandle,
@@ -44,7 +44,7 @@ use crate::payload::{
HookEnvelope, HookEvent, HookQuery, ProjectSource, ProjectStrategy, body_is_subagent,
durable_body_cap, parse_agent,
};
-use crate::synth::synthesize_session_page;
+use crate::synth::{HandoffFacts, SessionDigest, synthesize_session_page};
/// Default maximum number of hook events allowed to be processing at once.
///
@@ -3799,8 +3799,11 @@ async fn process_authorized(
Ok(None) => debug!("wiki clean during SessionEnd recovery"),
Err(e) => warn!(error = %e, "SessionEnd recovery auto-commit failed"),
}
- let observations = state.reader.observations_for_session(session_id).await?;
- if !is_ephemeral_session(&observations) {
+ if state
+ .reader
+ .session_has_substantive_observation(session_id)
+ .await?
+ {
recovered |= enqueue_session_end_consolidation(
state,
session_id,
@@ -3973,11 +3976,19 @@ async fn process_authorized(
&& !managed
&& !body_is_subagent(&env.raw);
if matches!(env.event, HookEvent::SessionEnd) || turn_checkpoint {
- let mut observations = state.reader.observations_for_session(session_id).await?;
+ // A session can hold hundreds of thousands of rows, so nothing on this
+ // path loads them all: the lifecycle-only decision is one existence
+ // query (the writer re-checks it in the ending transaction with the
+ // same predicate), and the page and handoff are rendered from a
+ // digest read with bounded queries.
+ let substantive = state
+ .reader
+ .session_has_substantive_observation(session_id)
+ .await?;
// A checkpoint writes where the session's end will: the session row's
// scope, not wherever this Stop resolved (a marker may have appeared
// mid-session). One that lost the race with the end writes nothing.
- let checkpoint_scope = if turn_checkpoint && !is_ephemeral_session(&observations) {
+ let checkpoint_scope = if turn_checkpoint && substantive {
state.reader.open_session_scope(session_id).await?
} else {
None
@@ -3989,7 +4000,7 @@ async fn process_authorized(
return Ok(outcome);
}
let (page_ws, page_proj) = checkpoint_scope.unwrap_or((ws, proj));
- if is_ephemeral_session(&observations) {
+ if !substantive {
let lifecycle_outcome = state
.writer
.end_admitted_lifecycle_only_session(admitted.clone(), env.occurred_at_micros())
@@ -4017,23 +4028,25 @@ async fn process_authorized(
return Ok(outcome);
}
ai_memory_store::LifecycleOnlyEndOutcome::Substantive => {
- observations = state.reader.observations_for_session(session_id).await?;
debug!(
session = %session_id,
"substantive work raced lifecycle-only SessionEnd; using normal end path",
);
- // The writer observed substantive work, so the refreshed
- // set cannot still satisfy the lifecycle-only predicate.
- debug_assert!(!is_ephemeral_session(&observations));
}
}
}
+ // Read after the decision above, so a substantive write that raced the
+ // lifecycle-only end is in it.
+ let digest = SessionDigest::load(&state.reader, session_id).await?;
+ // The writer observed substantive work when it answered `Substantive`,
+ // so the digest cannot still satisfy the lifecycle-only predicate.
+ debug_assert!(substantive || digest.is_substantive());
let new_page = synthesize_session_page(
page_ws,
page_proj,
session_id,
admitted.agent_kind(),
- &observations,
+ &digest,
);
let track_page_write = turn_checkpoint && outcome == HookProcessingOutcome::Resumed;
let previous_page_id = if track_page_write {
@@ -4103,7 +4116,7 @@ async fn process_authorized(
env.agent,
session_id,
env.cwd.clone(),
- &observations,
+ &digest,
handoff_owner,
turn_checkpoint,
)
@@ -4286,16 +4299,22 @@ fn resolve_session_id(env: &HookEnvelope) -> anyhow::Result<SessionId> {
/// `Stop` and `Notification`, which some harnesses (e.g. OpenCode) fire for
/// purely internal work such as branch-naming — is ephemeral/no-op and must
/// not synthesize a session page. This positive definition MUST stay in sync
-/// with the store-side SQL in `end_lifecycle_only_session_in_tx`
-/// (ai-memory-store/src/ops.rs): both sides classify every observation set
-/// identically, or the atomic store re-check silently reverts this verdict.
+/// with the store-side SQL, `SUBSTANTIVE_OBSERVATION_KIND_SQL`
+/// (ai-memory-store/src/reader.rs), which both the writer's
+/// `end_lifecycle_only_session_in_tx` and the reader's existence query build
+/// from: all sides classify every observation set identically, or the atomic
+/// store re-check silently reverts this verdict.
+///
+/// Production asks the database (`session_has_substantive_observation`);
+/// this row-list form is the twin the tests pin the SQL to.
+#[cfg(test)]
fn is_ephemeral_session(observations: &[ai_memory_core::Observation]) -> bool {
!observations.iter().any(|observation| {
matches!(
observation.kind,
- ObservationKind::UserPrompt
- | ObservationKind::PreToolUse
- | ObservationKind::PostToolUse
+ ai_memory_core::ObservationKind::UserPrompt
+ | ai_memory_core::ObservationKind::PreToolUse
+ | ai_memory_core::ObservationKind::PostToolUse
)
})
}
@@ -4307,20 +4326,11 @@ fn build_auto_handoff(
from_agent: AgentKind,
session_id: SessionId,
cwd: Option<String>,
- observations: &[ai_memory_core::Observation],
+ digest: &SessionDigest,
owner_user: Option<String>,
turn_checkpoint: bool,
) -> NewHandoff {
- // Prefer obs.body (the full prompt) over obs.title (first-line +
- // truncated to 80 chars for log/list display). When body is
- // empty fall back to title so we never produce an empty entry.
- fn pick_text(obs: &ai_memory_core::Observation) -> &str {
- if !obs.body.is_empty() {
- obs.body.as_str()
- } else {
- obs.title.as_str()
- }
- }
+ let facts = digest.handoff_facts();
/// Cap so a single 10-page prompt doesn't blow up the handoff.
/// The body is already scrubbed at insert time; this is just a
/// length budget. 1500 chars ≈ 250 words ≈ a paragraph.
@@ -4333,33 +4343,13 @@ fn build_auto_handoff(
format!("{truncated}…")
}
}
- let mut prompts: Vec<String> = Vec::new();
- let mut tools: std::collections::BTreeSet<&str> = std::collections::BTreeSet::new();
- for obs in observations {
- match obs.kind {
- ObservationKind::UserPrompt => {
- let text = pick_text(obs);
- // A harness block delivered as a user turn (`<task-notification>`)
- // is not a request to continue from.
- if !text.is_empty() && !ai_memory_core::looks_like_markup_block(text) {
- prompts.push(text.to_string());
- }
- }
- // Skip `tool <family>` / bare-`<family>` labels: a family is a
- // partition of the calls, not a name for a tool, so "Tools used:
- // tool file, tool non-file" tells the receiver nothing. Only a
- // harness's own tool name is worth listing.
- ObservationKind::PostToolUse | ObservationKind::PreToolUse
- if !obs.title.is_empty()
- && crate::payload::tool_family_from_title(&obs.title).is_none() =>
- {
- tools.insert(obs.title.as_str());
- }
- _ => {}
- }
- }
- let first_prompt = prompts.first().cloned();
- let last_prompt = prompts.last().cloned();
+ // The first and last prompt with usable text (obs.body, the full prompt,
+ // over obs.title, which is first-line truncated for display; a harness
+ // block delivered as a user turn, `<task-notification>`, is not a request
+ // to continue from), and the tool names worth listing, were found with
+ // bounded queries when the digest loaded.
+ let first_prompt = facts.first_prompt.clone();
+ let last_prompt = facts.last_prompt.clone();
let mut summary = match (&first_prompt, &last_prompt) {
(Some(first), Some(last)) if first == last => format!("Session focused on: {}", cap(first)),
(Some(first), Some(last)) => format!("Started: {}\n\nLast: {}", cap(first), cap(last),),
@@ -4371,17 +4361,15 @@ fn build_auto_handoff(
} else {
"Session ended"
},
- observations.len()
+ digest.observation_count()
),
};
// Stop bodies exist only after the assistant-capture double opt-in. The
// excerpt continues the work in the next session's baton and stays out of
// the git-tracked session page.
- if let Some(assistant) = observations.iter().rev().find(|observation| {
- observation.kind == ObservationKind::Stop && !observation.body.trim().is_empty()
- }) {
+ if let Some(assistant) = &facts.latest_assistant {
summary.push_str("\n\nLatest assistant response: ");
- summary.push_str(&assistant.body);
+ summary.push_str(assistant);
}
let open_questions = if turn_checkpoint {
// A completed turn is neither a native-session exit nor evidence that
@@ -4394,14 +4382,19 @@ fn build_auto_handoff(
.into_iter()
.collect()
} else {
- derive_open_questions(observations, &last_prompt)
+ derive_open_questions(facts, &last_prompt)
};
- let next_steps = if tools.is_empty() {
+ let next_steps = if facts.tools.is_empty() {
Vec::new()
} else {
vec![format!(
"Tools used: {}",
- tools.into_iter().collect::<Vec<_>>().join(", ")
+ facts
+ .tools
+ .iter()
+ .map(String::as_str)
+ .collect::<Vec<_>>()
+ .join(", ")
)]
};
NewHandoff {
@@ -4437,24 +4430,13 @@ fn build_auto_handoff(
/// *substantive* prompt (filtering acknowledgments).
/// 4. Normal end → last substantive prompt as "Continue from: …".
/// 5. Fallback → empty Vec (same as the old behaviour when no prompts).
-fn derive_open_questions(
- observations: &[ai_memory_core::Observation],
- last_prompt: &Option<String>,
-) -> Vec<String> {
- let last_of_kind = |kind: ObservationKind| -> Option<&ai_memory_core::Observation> {
- observations.iter().rev().find(|o| o.kind == kind)
- };
-
- // Harness blocks delivered as a user turn are not the user's question.
- let last_prompt_obs = observations.iter().rev().find(|o| {
- let text = if o.body.is_empty() { &o.title } else { &o.body };
- o.kind == ObservationKind::UserPrompt && !ai_memory_core::looks_like_markup_block(text)
- });
- let last_tool = last_of_kind(ObservationKind::PostToolUse);
- let last_stop = last_of_kind(ObservationKind::Stop);
- let has_session_end = observations
- .iter()
- .any(|o| o.kind == ObservationKind::SessionEnd);
+fn derive_open_questions(facts: &HandoffFacts, last_prompt: &Option<String>) -> Vec<String> {
+ // Harness blocks delivered as a user turn are not the user's question, so
+ // `question_prompt` is the last prompt that is not one.
+ let last_prompt_obs = facts.question_prompt.as_ref();
+ let last_tool = facts.last_tool_title.as_deref();
+ let has_stop = facts.has_stop;
+ let has_session_end = facts.has_session_end;
// Heuristic 1: last prompt is a question → it is the open question.
if let Some(p) = last_prompt_obs {
@@ -4481,9 +4463,8 @@ fn derive_open_questions(
// made — only that the session touched files and then ended without a
// normal Stop, which is worth telling the receiver either way.
if let Some(tool) = last_tool {
- let touched_files =
- crate::payload::tool_family_from_title(&tool.title) == Some(ToolFamily::File);
- if touched_files && last_stop.is_none() {
+ let touched_files = crate::payload::tool_family_from_title(tool) == Some(ToolFamily::File);
+ if touched_files && !has_stop {
return vec![
"Session ended without a normal stop while working with files".into(),
"Check the working tree for uncommitted or unverified changes".into(),
@@ -4496,7 +4477,7 @@ fn derive_open_questions(
let body = p.trim();
if !body.is_empty() && !is_acknowledgment(body) {
// Heuristic 3 signal: no SessionEnd → flag as mid-task.
- if !has_session_end && last_stop.is_some() {
+ if !has_session_end && has_stop {
return vec![format!(
"Continue from (mid-task exit): {}",
cap_handoff_text(body)
@@ -4631,17 +4612,12 @@ async fn write_checkpoint_page(
{
return Ok(false);
}
- let observations = state.reader.observations_for_session(session_id).await?;
- if is_ephemeral_session(&observations) {
+ let digest = SessionDigest::load(&state.reader, session_id).await?;
+ if !digest.is_substantive() {
return Ok(false);
}
- let new_page = synthesize_session_page(
- workspace_id,
- project_id,
- session_id,
- agent_kind,
- &observations,
- );
+ let new_page =
+ synthesize_session_page(workspace_id, project_id, session_id, agent_kind, &digest);
// With a provider this page is the first half of a consolidation, so it
// carries the `consolidate` admission operation the inline LLM write
// used to: a policy refusing consolidation for this actor or scope fails
@@ -4758,9 +4734,63 @@ mod tests {
use ai_memory_wiki::Wiki;
use tempfile::TempDir;
+ use ai_memory_core::ObservationKind;
+
use super::*;
use crate::payload::HookQuery;
+ // The page and the handoff are rendered from a digest of the session.
+ // These tests describe a session as the row list it is made of, so each
+ // shim digests that list the way the database queries do
+ // (`SessionDigest::from_observations`) and the assertions read as before.
+ // `session_end_equivalence` holds the queries to the original row-list
+ // code.
+ fn synthesize_session_page(
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ session_id: SessionId,
+ agent_kind: AgentKind,
+ observations: &[ai_memory_core::Observation],
+ ) -> ai_memory_core::NewPage {
+ super::synthesize_session_page(
+ workspace_id,
+ project_id,
+ session_id,
+ agent_kind,
+ &SessionDigest::from_observations(session_id, observations),
+ )
+ }
+
+ #[allow(clippy::too_many_arguments)]
+ fn build_auto_handoff(
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ from_agent: AgentKind,
+ session_id: SessionId,
+ cwd: Option<String>,
+ observations: &[ai_memory_core::Observation],
+ owner_user: Option<String>,
+ turn_checkpoint: bool,
+ ) -> NewHandoff {
+ super::build_auto_handoff(
+ workspace_id,
+ project_id,
+ from_agent,
+ session_id,
+ cwd,
+ &SessionDigest::from_observations(session_id, observations),
+ owner_user,
+ turn_checkpoint,
+ )
+ }
+
+ fn derive_open_questions(
+ observations: &[ai_memory_core::Observation],
+ last_prompt: &Option<String>,
+ ) -> Vec<String> {
+ super::derive_open_questions(&HandoffFacts::from_observations(observations), last_prompt)
+ }
+
#[test]
fn inbox_notice_is_count_only_and_empty_at_zero() {
// Empty inbox: no notice at all, named or not.
@@ -14858,6 +14888,118 @@ mod tests {
);
}
+ /// A SessionEnd on a session far larger than the raw-observation window
+ /// must not load its rows: the page and the baton are rendered from
+ /// bounded reads. The reader pool's counter is the seam; it counts every
+ /// row a whole-session read deserializes, so a full load put back anywhere
+ /// on the path (the lifecycle-only check, the page, the handoff) moves it
+ /// by the size of the session.
+ #[tokio::test]
+ async fn session_end_of_a_huge_session_loads_a_bounded_number_of_rows() {
+ const FILLER: i64 = 12_000;
+ let tmp = TempDir::new().unwrap();
+ let state = make_state(&tmp).await;
+ let sid = "30303030-3030-3030-3030-303030303030";
+ let session_id: SessionId = sid.parse().unwrap();
+ let fire = |event: &str| {
+ HookEnvelope::from_query_and_body(
+ HookQuery {
+ event: event.into(),
+ agent: Some("codex".into()),
+ ..Default::default()
+ },
+ serde_json::json!({ "session_id": sid, "prompt": "ship the bounded read" }),
+ )
+ };
+ process(&state, fire("user-prompt-submit"), None, Vec::new())
+ .await
+ .unwrap();
+ let first = state
+ .reader
+ .observations_for_session(session_id)
+ .await
+ .unwrap()
+ .remove(0);
+
+ // Bulk-seed the rest of the session with plain SQL: this many rows
+ // through the writer actor would be the whole test.
+ let mut conn = rusqlite::Connection::open(tmp.path().join("db").join("memory.sqlite"))
+ .expect("the store's database file");
+ conn.pragma_update(None, "synchronous", "OFF").unwrap();
+ // The FTS trigger indexes every inserted row and nothing here
+ // searches them.
+ conn.execute_batch("DROP TRIGGER IF EXISTS observations_fts_ai")
+ .unwrap();
+ let first_us = first.created_at.as_microsecond();
+ let tx = conn.transaction().unwrap();
+ {
+ let mut insert = tx
+ .prepare(
+ "INSERT INTO observations \
+ (id, session_id, workspace_id, project_id, kind, title, body, importance, \
+ created_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, '', 5, ?7)",
+ )
+ .unwrap();
+ for i in 0..FILLER {
+ let kind = if i % 2 == 0 {
+ ObservationKind::PreToolUse
+ } else {
+ ObservationKind::PostToolUse
+ };
+ insert
+ .execute(rusqlite::params![
+ ai_memory_core::ObservationId::new().as_bytes(),
+ session_id.as_bytes(),
+ first.workspace_id.as_bytes(),
+ first.project_id.as_bytes(),
+ kind.as_str(),
+ "Bash",
+ first_us + 1 + i,
+ ])
+ .unwrap();
+ }
+ }
+ tx.commit().unwrap();
+
+ let before = state.reader.session_observation_rows_loaded();
+ process(&state, fire("session-end"), None, Vec::new())
+ .await
+ .unwrap();
+ let loaded = state.reader.session_observation_rows_loaded() - before;
+
+ // Head and tail lines plus one row per early-exit scan.
+ assert!(
+ loaded <= 500 + 16,
+ "SessionEnd of a {FILLER}-row session loaded {loaded} rows"
+ );
+ let page = state
+ .wiki
+ .read_page(
+ first.workspace_id,
+ first.project_id,
+ &PagePath::new(format!("sessions/{sid}.md")).unwrap(),
+ )
+ .expect("the session page is written");
+ assert!(
+ page.body
+ .contains("raw observations omitted from the middle"),
+ "a long session still gets the elided raw list: {}",
+ page.body.lines().take(12).collect::<Vec<_>>().join("\n")
+ );
+ let briefing = state
+ .reader
+ .briefing_for_project(
+ first.workspace_id,
+ first.project_id,
+ 1,
+ ai_memory_core::OwnerFilter::Any,
+ false,
+ )
+ .await
+ .unwrap();
+ assert_eq!(briefing.pending_handoff_count, 1, "the baton is still made");
+ }
+
#[tokio::test]
async fn session_end_queues_llm_work_without_calling_provider() {
let tmp = TempDir::new().unwrap();
@@ -19832,3 +19974,7 @@ mod tests {
assert_ne!(ordinary, (state.workspace_id, state.project_id));
}
}
+
+#[cfg(test)]
+#[path = "session_end_equivalence.rs"]
+mod session_end_equivalence;
diff --git a/crates/ai-memory-hooks/src/session_end_equivalence.rs b/crates/ai-memory-hooks/src/session_end_equivalence.rs
new file mode 100644
index 00000000..f2492143
--- /dev/null
+++ b/crates/ai-memory-hooks/src/session_end_equivalence.rs
@@ -0,0 +1,1340 @@
+//! The bounded SessionEnd reads against the full row load they replaced.
+//!
+//! A SessionEnd used to load every observation of the session and render the
+//! page and the handoff from that list. It now reads a [`SessionDigest`] with
+//! bounded queries. The claim is that nothing the page, the handoff or the
+//! lifecycle-only decision contain changed, so this file keeps the original
+//! code as the oracle: `full_load` below is `synth.rs` and the handoff half of
+//! `router.rs` at the commit before the change, byte for byte except for the
+//! two `pub(super)` that let the tests call it and the imports it needs from
+//! its new home. It exists in test code only.
+//!
+//! Each test seeds sessions into a real store, runs the oracle on the rows
+//! `observations_for_session` returns, runs the production path on the same
+//! session, and compares the outputs.
+
+#[rustfmt::skip]
+mod full_load {
+ use std::collections::BTreeMap;
+
+ use ai_memory_core::{
+ AgentKind, NewHandoff, NewPage, Observation, ObservationKind, PagePath, ProjectId,
+ SessionId, Tier, WorkspaceId, looks_like_markup_block, looks_like_scaffolding,
+ truncate_for_title,
+ };
+ use jiff::tz::TimeZone;
+
+ use crate::capture_policy::ToolFamily;
+ use crate::payload::is_safe_tool_title;
+ use crate::router::{cap_handoff_text, is_acknowledgment};
+
+ const RAW_OBSERVATION_MAX_LINES: usize = 500;
+ const RAW_OBSERVATION_HEAD_LINES: usize = 250;
+ const RAW_OBSERVATION_TAIL_LINES: usize =
+ RAW_OBSERVATION_MAX_LINES - RAW_OBSERVATION_HEAD_LINES;
+ const SUBAGENT_PROMPT_PREAMBLE: &str = "You are a subagent spawned by another session.";
+
+/// Build a [`NewPage`] from the observations collected during a session.
+///
+/// The returned page is *always* under `sessions/<session-id>.md` so each
+/// session has a stable URL the user can bookmark.
+#[must_use]
+pub(super) fn synthesize_session_page(
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ session_id: SessionId,
+ agent_kind: AgentKind,
+ observations: &[Observation],
+) -> NewPage {
+ // One tally for the whole page: the body renderer and the summary builder
+ // describe the same session and must not scan it twice to do so.
+ let tally = tally_session(observations);
+ let title = derive_title(observations, session_id);
+ let body = render_body(session_id, observations, &title, &tally);
+ let mut frontmatter_json = serde_json::json!({
+ "title": title,
+ "session_id": session_id.to_string(),
+ // Origin, not writer: callers pass the immutable value persisted on
+ // the session row, so checkpoints and later superseding versions keep
+ // naming the harness that produced the session.
+ "agent": agent_kind.as_str(),
+ "tier": "episodic",
+ });
+ let summary = session_summary(&tally);
+ if !summary.is_empty() {
+ // Insert only when there is something to say. The store's hit
+ // descriptor prefers `summary` over the body, so writing a blank one
+ // would trade real body text for nothing.
+ frontmatter_json["summary"] = serde_json::Value::String(summary);
+ }
+ let path = PagePath::new(format!("sessions/{session_id}.md"))
+ .expect("hard-coded sessions/<uuid>.md is always valid");
+ NewPage {
+ workspace_id,
+ project_id,
+ path,
+ title: title.clone(),
+ body,
+ tier: Tier::Episodic,
+ frontmatter_json,
+ pinned: false,
+ links: Vec::new(),
+ author_id: None,
+ expires_at: None,
+ entities: Vec::new(),
+ evidence: Vec::new(),
+ }
+}
+
+/// Title for a synthesised session page.
+///
+/// Prefers the first user prompt that reads as something a person wrote.
+/// A prompt payload is whatever the harness put there, so IDE context
+/// blocks and an echoed shell prompt can arrive in the same field (#484) —
+/// those are skipped rather than becoming the title the page is indexed and
+/// displayed under.
+///
+/// A `SessionStart` is skipped as a source outright. `best_title_hint`
+/// fills its title from `model` before `title` (`payload.rs`), so a bare
+/// model id became the page title whenever the prompts were unusable — and
+/// by the time it is a string it is indistinguishable from a terse human
+/// reference like `pr-477`, so it is excluded here by kind instead.
+///
+/// The skipped field is `["model", "title"]`, so this drops more than a
+/// model id: OpenCode's `session.created` puts `info.title` in the same
+/// slot. Its plugin subscribes to `created`/`idle`/`deleted`/`compacted`
+/// and never `session.updated`, and starts a session once per id, so the
+/// only value that can arrive is the creation-time name — in practice the
+/// shared literal "New session", never a rename. **That last part is an
+/// assumption about an external component, not an invariant:** it is read
+/// off OpenCode's subscription list as of v1.32.1, and if a future release
+/// surfaces a renamed session here, this would discard a good title with
+/// nothing in the tree failing. What a `SessionStart` carries is whatever
+/// the harness *named the session*, and no harness names it with something
+/// a person typed.
+///
+/// Falls through in decreasing order of confidence: a usable prompt, then
+/// any other usable observation title, then the session's own path. The
+/// literal "session" remains only for the case where there is nothing else
+/// at all.
+fn derive_title(observations: &[Observation], session_id: SessionId) -> String {
+ let mut rejected_subagent_preamble = false;
+ for obs in observations {
+ if obs.kind != ObservationKind::UserPrompt {
+ continue;
+ }
+ if obs.title.trim() == SUBAGENT_PROMPT_PREAMBLE {
+ rejected_subagent_preamble = true;
+ if let Some(title) = obs
+ .body
+ .lines()
+ .map(str::trim)
+ .find(|line| !line.is_empty() && !looks_like_title_scaffolding(line))
+ {
+ return truncate_for_title(title);
+ }
+ continue;
+ }
+ if !obs.title.is_empty() && !looks_like_scaffolding(&obs.title) {
+ return obs.title.clone();
+ }
+ }
+ if rejected_subagent_preamble {
+ return format!("Session {session_id}");
+ }
+ for obs in observations {
+ // The router titles an untitled lifecycle event with its kind name
+ // (`stop`, `session-end`): a string every such page would share, and
+ // what this loop reached once tool-family labels were skipped (#895).
+ if obs.kind == ObservationKind::SessionStart || obs.title == obs.kind.as_str() {
+ continue;
+ }
+ // A `tool <family>` label is a partition of the calls, not a title:
+ // `looks_like_scaffolding` does not catch it, so reject it here or a
+ // session whose only non-prompt observation is a closed-tool call
+ // ("tool non-file") would take the label as its page title.
+ if !obs.title.is_empty()
+ && !looks_like_title_scaffolding(&obs.title)
+ && !is_safe_tool_title(&obs.title)
+ {
+ return obs.title.clone();
+ }
+ }
+ // Every candidate was scaffolding. The page still needs a title, and its
+ // own identity is more use to a reader than the word "session" repeated
+ // across every such page.
+ if observations.is_empty() {
+ return "session".to_string();
+ }
+ format!("Session {session_id}")
+}
+
+fn looks_like_title_scaffolding(candidate: &str) -> bool {
+ candidate.trim() == SUBAGENT_PROMPT_PREAMBLE || looks_like_scaffolding(candidate)
+}
+
+/// The per-session counts that both the rendered body and the frontmatter
+/// summary are built from.
+struct SessionTally<'a> {
+ /// Completed calls per tool name, keyed for stable ordering.
+ tool_counts: BTreeMap<&'a str, usize>,
+ /// User prompts in arrival order.
+ prompts: Vec<&'a Observation>,
+ /// First `SessionStart`, if the session recorded one.
+ start: Option<&'a Observation>,
+ /// Last `SessionEnd`, if the session recorded one.
+ end: Option<&'a Observation>,
+}
+
+/// Tally a session's observations once.
+///
+/// [`render_body`] and [`session_summary`] both need these counts, and
+/// [`synthesize_session_page`] computes them once and lends them to both — so
+/// a page costs one pass over its observations, not two, and the body and the
+/// summary cannot describe the same session differently. It also keeps the
+/// summary from having to parse the counts back out of the markdown the body
+/// just rendered them into.
+fn tally_session(observations: &[Observation]) -> SessionTally<'_> {
+ let mut tally = SessionTally {
+ tool_counts: BTreeMap::new(),
+ prompts: Vec::new(),
+ start: None,
+ end: None,
+ };
+ for obs in observations {
+ match obs.kind {
+ ObservationKind::SessionStart => tally.start = Some(obs),
+ ObservationKind::SessionEnd => tally.end = Some(obs),
+ ObservationKind::UserPrompt => tally.prompts.push(obs),
+ // Count only PostToolUse — each tool call produces both a
+ // PreToolUse and a PostToolUse observation, so counting both
+ // doubles every reported number ("Bash: 4" for two real calls).
+ // PostToolUse is the "completed call" event; pre-only calls
+ // that never produced a post (cancellations) are intentionally
+ // excluded.
+ ObservationKind::PostToolUse if !obs.title.is_empty() => {
+ *tally.tool_counts.entry(obs.title.as_str()).or_insert(0) += 1;
+ }
+ _ => {}
+ }
+ }
+ tally
+}
+
+/// How many tools to name individually before summarising the rest as a count.
+const SUMMARY_MAX_NAMED_TOOLS: usize = 3;
+
+/// One line of plain prose describing what the session did, or empty when it
+/// did nothing worth stating.
+///
+/// This lands in `frontmatter.summary`, which the store prefers over the body
+/// when building the descriptor for a non-FTS hit. It is **not** used
+/// verbatim: the reader runs it through the same line filter it applies to a
+/// body, which drops headings, `- **key:** value` metadata bullets, and any
+/// line that merely repeats the title. When every line is dropped the filter
+/// falls back to echoing its raw input, so a summary written in the same house
+/// style as the metadata block above would be reproduced verbatim as the
+/// descriptor — displacing the body text that would otherwise have been used,
+/// silently and with no error anywhere.
+///
+/// Hence: one line, plain prose, no leading marker.
+fn session_summary(tally: &SessionTally<'_>) -> String {
+ let mut parts: Vec<String> = Vec::new();
+
+ if !tally.prompts.is_empty() {
+ parts.push(format!(
+ "{} prompt{}",
+ tally.prompts.len(),
+ plural(tally.prompts.len())
+ ));
+ }
+
+ let calls: usize = tally.tool_counts.values().sum();
+ if calls > 0 {
+ // Name the busiest tools first; ties fall back to the map's
+ // alphabetical order so the same session always renders the same way.
+ let mut by_calls: Vec<(&str, usize)> =
+ tally.tool_counts.iter().map(|(k, v)| (*k, *v)).collect();
+ by_calls.sort_by(|a, b| b.1.cmp(&a.1).then_with(|| a.0.cmp(b.0)));
+ // A `tool <family>` title is what `safe_tool_title` writes when the
+ // harness's own tool name is not carried through: a partition of the
+ // calls, never a name for them. Listing those spends the reader's
+ // attention to say "some of the calls touched files and some did
+ // not", so they are counted but not named, and a session with
+ // nothing else to name drops the clause rather than filling it.
+ let nameable: Vec<&str> = by_calls
+ .iter()
+ .map(|(name, _)| *name)
+ .filter(|name| !is_safe_tool_title(name))
+ .collect();
+ parts.push(if nameable.is_empty() {
+ format!("{calls} completed tool call{}", plural(calls))
+ } else {
+ let named: Vec<&str> = nameable
+ .iter()
+ .copied()
+ .take(SUMMARY_MAX_NAMED_TOOLS)
+ .collect();
+ let tools = if by_calls.len() > named.len() {
+ format!(
+ "{} and {} more",
+ join_and(&named),
+ by_calls.len() - named.len()
+ )
+ } else {
+ join_and(&named)
+ };
+ format!(
+ "{calls} completed tool call{} across {tools}",
+ plural(calls)
+ )
+ });
+ }
+
+ if let (Some(start), Some(end)) = (tally.start, tally.end)
+ && let Some(spent) =
+ format_duration(end.created_at.as_second() - start.created_at.as_second())
+ {
+ parts.push(format!("over {spent}"));
+ }
+
+ // The harness's own word for why the session ended (#1225), when the
+ // SessionEnd observation carried one. Display-bounded: a summary line
+ // is no place for a long free-text field.
+ if let Some(reason) = tally
+ .end
+ .and_then(|end| end.body.strip_prefix("reason: "))
+ .map(str::trim)
+ .filter(|reason| !reason.is_empty())
+ {
+ let shown: String = reason.chars().take(60).collect();
+ parts.push(format!("ended ({shown})"));
+ }
+
+ if parts.is_empty() {
+ return String::new();
+ }
+ format!("{}.", parts.join(", "))
+}
+
+/// `""` or `"s"` for a count.
+fn plural(n: usize) -> &'static str {
+ if n == 1 { "" } else { "s" }
+}
+
+/// `"Bash"`, `"Bash and Edit"`, `"Bash, Edit and Read"`.
+fn join_and(names: &[&str]) -> String {
+ match names {
+ [] => String::new(),
+ [only] => (*only).to_string(),
+ [rest @ .., last] => format!("{} and {last}", rest.join(", ")),
+ }
+}
+
+/// Human-readable elapsed time, or `None` when the session was not measurably
+/// long (a clock that did not advance, or ran backwards).
+fn format_duration(seconds: i64) -> Option<String> {
+ if seconds <= 0 {
+ return None;
+ }
+ if seconds < 60 {
+ return Some(format!("{seconds}s"));
+ }
+ let minutes = seconds / 60;
+ if minutes < 60 {
+ return Some(format!("{minutes}m"));
+ }
+ let (hours, rest) = (minutes / 60, minutes % 60);
+ Some(if rest == 0 {
+ format!("{hours}h")
+ } else {
+ format!("{hours}h {rest}m")
+ })
+}
+
+fn render_body(
+ session_id: SessionId,
+ observations: &[Observation],
+ title: &str,
+ tally: &SessionTally<'_>,
+) -> String {
+ let SessionTally {
+ tool_counts,
+ prompts,
+ start,
+ end,
+ } = tally;
+
+ let mut buf = String::with_capacity(2048);
+ buf.push_str(&format!("# {title}\n\n"));
+
+ buf.push_str("## Session metadata\n\n");
+ buf.push_str(&format!("- **session_id:** `{session_id}`\n"));
+ if let Some(s) = start {
+ buf.push_str(&format!("- **started_at:** {}\n", human_ts(&s.created_at),));
+ }
+ if let Some(e) = end {
+ buf.push_str(&format!("- **ended_at:** {}\n", human_ts(&e.created_at),));
+ }
+ buf.push_str(&format!("- **observations:** {}\n\n", observations.len()));
+
+ if let Some(note) = abrupt_ending_note(observations) {
+ buf.push_str(&format!("{note}\n\n"));
+ }
+
+ if !prompts.is_empty() {
+ buf.push_str("## Prompts\n\n");
+ for (i, p) in prompts.iter().enumerate() {
+ buf.push_str(&format!("{}. {}\n", i + 1, p.title));
+ }
+ buf.push('\n');
+ }
+
+ if !tool_counts.is_empty() {
+ buf.push_str("## Tool calls\n\n");
+ for (name, count) in tool_counts {
+ buf.push_str(&format!("- `{name}`: {count}\n"));
+ }
+ buf.push('\n');
+ }
+
+ buf.push_str("## Raw observations\n\n");
+ render_raw_observations(&mut buf, observations);
+
+ buf.push_str("\n_Synthesised by ai-memory (M3, no-LLM heuristic)._\n");
+ buf
+}
+
+/// One deterministic line flagging an abrupt ending, or `None` when the
+/// session closed normally (a Stop and a SessionEnd are both on record).
+///
+/// Mirrors the multi-signal heuristics the router's `derive_open_questions`
+/// uses for automatic SessionEnd handoffs, first match wins, so the
+/// zero-LLM page states the same terminal state a handoff would flag
+/// (#1221):
+/// 1. The final substantive prompt is an unanswered question and no Stop
+/// ever arrived after it.
+/// 2. The last completed tool call touched files and no Stop followed —
+/// the session ended while working in the tree.
+/// 3. A Stop was recorded but no SessionEnd — a mid-task exit (or a
+/// checkpoint page rendered while the session is still running; the
+/// wording only claims what the log shows).
+fn abrupt_ending_note(observations: &[Observation]) -> Option<&'static str> {
+ let last_of_kind = |kind: ObservationKind| observations.iter().rev().find(|o| o.kind == kind);
+ let last_stop = last_of_kind(ObservationKind::Stop);
+ let has_session_end = observations
+ .iter()
+ .any(|o| o.kind == ObservationKind::SessionEnd);
+ // Harness blocks delivered as a user turn are not the user's question.
+ let last_prompt = observations.iter().rev().find(|o| {
+ let text = if o.body.is_empty() { &o.title } else { &o.body };
+ o.kind == ObservationKind::UserPrompt && !looks_like_markup_block(text)
+ });
+
+ if last_stop.is_none()
+ && let Some(prompt) = last_prompt
+ {
+ let text = if prompt.body.is_empty() {
+ prompt.title.trim()
+ } else {
+ prompt.body.trim()
+ };
+ if text.ends_with('?') || text.ends_with('?') {
+ return Some(
+ "Session ended without a normal stop; the final prompt was never answered.",
+ );
+ }
+ }
+
+ if last_stop.is_none()
+ && let Some(tool) = last_of_kind(ObservationKind::PostToolUse)
+ && crate::payload::tool_family_from_title(&tool.title) == Some(ToolFamily::File)
+ {
+ return Some(
+ "Session ended without a normal stop while working with files; \
+ the working tree may hold uncommitted or unverified changes.",
+ );
+ }
+
+ if last_stop.is_some() && !has_session_end {
+ return Some(
+ "A stop was recorded but no session end; the session may have exited mid-task.",
+ );
+ }
+
+ None
+}
+
+fn render_raw_observations(buf: &mut String, observations: &[Observation]) {
+ if observations.len() <= RAW_OBSERVATION_MAX_LINES {
+ for obs in observations {
+ render_raw_observation(buf, obs);
+ }
+ return;
+ }
+
+ for obs in &observations[..RAW_OBSERVATION_HEAD_LINES] {
+ render_raw_observation(buf, obs);
+ }
+ let omitted = observations.len() - RAW_OBSERVATION_HEAD_LINES - RAW_OBSERVATION_TAIL_LINES;
+ buf.push_str(&format!(
+ "\n_... {omitted} raw observations omitted from the middle (showing first {RAW_OBSERVATION_HEAD_LINES} and last {RAW_OBSERVATION_TAIL_LINES})._\n\n",
+ ));
+ for obs in &observations[observations.len() - RAW_OBSERVATION_TAIL_LINES..] {
+ render_raw_observation(buf, obs);
+ }
+}
+
+fn render_raw_observation(buf: &mut String, obs: &Observation) {
+ let kind = observation_kind_label(obs);
+ buf.push_str(&format!(
+ "- `{}` @ {} — {}\n",
+ kind,
+ human_ts(&obs.created_at),
+ obs.title.chars().take(80).collect::<String>(),
+ ));
+}
+
+fn observation_kind_label(obs: &Observation) -> String {
+ match (&obs.extension, &obs.source_event) {
+ (Some(extension), Some(source_event)) => {
+ format!("{} [{}:{}]", obs.kind.as_str(), extension, source_event)
+ }
+ _ => obs.kind.as_str().to_string(),
+ }
+}
+
+fn human_ts(ts: &jiff::Timestamp) -> String {
+ ts.to_zoned(TimeZone::UTC)
+ .strftime("%Y-%m-%dT%H:%M:%SZ")
+ .to_string()
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn build_auto_handoff(
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ from_agent: AgentKind,
+ session_id: SessionId,
+ cwd: Option<String>,
+ observations: &[ai_memory_core::Observation],
+ owner_user: Option<String>,
+ turn_checkpoint: bool,
+) -> NewHandoff {
+ // Prefer obs.body (the full prompt) over obs.title (first-line +
+ // truncated to 80 chars for log/list display). When body is
+ // empty fall back to title so we never produce an empty entry.
+ fn pick_text(obs: &ai_memory_core::Observation) -> &str {
+ if !obs.body.is_empty() {
+ obs.body.as_str()
+ } else {
+ obs.title.as_str()
+ }
+ }
+ /// Cap so a single 10-page prompt doesn't blow up the handoff.
+ /// The body is already scrubbed at insert time; this is just a
+ /// length budget. 1500 chars ≈ 250 words ≈ a paragraph.
+ fn cap(s: &str) -> String {
+ const MAX: usize = 1500;
+ if s.chars().count() <= MAX {
+ s.to_string()
+ } else {
+ let truncated: String = s.chars().take(MAX).collect();
+ format!("{truncated}…")
+ }
+ }
+ let mut prompts: Vec<String> = Vec::new();
+ let mut tools: std::collections::BTreeSet<&str> = std::collections::BTreeSet::new();
+ for obs in observations {
+ match obs.kind {
+ ObservationKind::UserPrompt => {
+ let text = pick_text(obs);
+ // A harness block delivered as a user turn (`<task-notification>`)
+ // is not a request to continue from.
+ if !text.is_empty() && !ai_memory_core::looks_like_markup_block(text) {
+ prompts.push(text.to_string());
+ }
+ }
+ // Skip `tool <family>` / bare-`<family>` labels: a family is a
+ // partition of the calls, not a name for a tool, so "Tools used:
+ // tool file, tool non-file" tells the receiver nothing. Only a
+ // harness's own tool name is worth listing.
+ ObservationKind::PostToolUse | ObservationKind::PreToolUse
+ if !obs.title.is_empty()
+ && crate::payload::tool_family_from_title(&obs.title).is_none() =>
+ {
+ tools.insert(obs.title.as_str());
+ }
+ _ => {}
+ }
+ }
+ let first_prompt = prompts.first().cloned();
+ let last_prompt = prompts.last().cloned();
+ let mut summary = match (&first_prompt, &last_prompt) {
+ (Some(first), Some(last)) if first == last => format!("Session focused on: {}", cap(first)),
+ (Some(first), Some(last)) => format!("Started: {}\n\nLast: {}", cap(first), cap(last),),
+ (Some(first), None) => format!("Started: {}", cap(first)),
+ _ => format!(
+ "{}; {} observations recorded.",
+ if turn_checkpoint {
+ "Turn checkpoint"
+ } else {
+ "Session ended"
+ },
+ observations.len()
+ ),
+ };
+ // Stop bodies exist only after the assistant-capture double opt-in. The
+ // excerpt continues the work in the next session's baton and stays out of
+ // the git-tracked session page.
+ if let Some(assistant) = observations.iter().rev().find(|observation| {
+ observation.kind == ObservationKind::Stop && !observation.body.trim().is_empty()
+ }) {
+ summary.push_str("\n\nLatest assistant response: ");
+ summary.push_str(&assistant.body);
+ }
+ let open_questions = if turn_checkpoint {
+ // A completed turn is neither a native-session exit nor evidence that
+ // the user's last question remains unanswered.
+ last_prompt
+ .as_deref()
+ .map(str::trim)
+ .filter(|prompt| !prompt.is_empty() && !is_acknowledgment(prompt))
+ .map(|prompt| format!("Continue from last request: {}", cap_handoff_text(prompt)))
+ .into_iter()
+ .collect()
+ } else {
+ derive_open_questions(observations, &last_prompt)
+ };
+ let next_steps = if tools.is_empty() {
+ Vec::new()
+ } else {
+ vec![format!(
+ "Tools used: {}",
+ tools.into_iter().collect::<Vec<_>>().join(", ")
+ )]
+ };
+ NewHandoff {
+ workspace_id,
+ project_id,
+ from_session_id: Some(session_id),
+ from_agent,
+ to_agent: None,
+ cwd: cwd.map(std::path::PathBuf::from),
+ summary,
+ open_questions,
+ next_steps,
+ files_touched: Vec::new(),
+ owner_user,
+ }
+}
+
+/// Derive the `open_questions` field for an automatic SessionEnd handoff
+/// using multi-signal heuristics, instead of blindly copying the last user
+/// prompt.
+///
+/// The previous implementation always did `"Continue from: <last prompt>"`,
+/// which produced useless entries when the last prompt was an acknowledgment
+/// ("ok", "thanks", "好的") or when the session ended mid-task after an edit
+/// but before verification. This function inspects the *tail* of the
+/// observation stream to choose the most informative framing.
+///
+/// Heuristics (first match wins):
+/// 1. Last prompt ends with `?` or `?` → tag as an unresolved question.
+/// 2. Last tool was an edit/write/patch with no subsequent Stop → the
+/// session ended before verification; advise the receiver to run tests.
+/// 3. Has Stop but no SessionEnd → mid-task exit; use the last
+/// *substantive* prompt (filtering acknowledgments).
+/// 4. Normal end → last substantive prompt as "Continue from: …".
+/// 5. Fallback → empty Vec (same as the old behaviour when no prompts).
+fn derive_open_questions(
+ observations: &[ai_memory_core::Observation],
+ last_prompt: &Option<String>,
+) -> Vec<String> {
+ let last_of_kind = |kind: ObservationKind| -> Option<&ai_memory_core::Observation> {
+ observations.iter().rev().find(|o| o.kind == kind)
+ };
+
+ // Harness blocks delivered as a user turn are not the user's question.
+ let last_prompt_obs = observations.iter().rev().find(|o| {
+ let text = if o.body.is_empty() { &o.title } else { &o.body };
+ o.kind == ObservationKind::UserPrompt && !ai_memory_core::looks_like_markup_block(text)
+ });
+ let last_tool = last_of_kind(ObservationKind::PostToolUse);
+ let last_stop = last_of_kind(ObservationKind::Stop);
+ let has_session_end = observations
+ .iter()
+ .any(|o| o.kind == ObservationKind::SessionEnd);
+
+ // Heuristic 1: last prompt is a question → it is the open question.
+ if let Some(p) = last_prompt_obs {
+ let body = p.body.trim();
+ if body.ends_with('?') || body.ends_with('?') {
+ return vec![format!("Unresolved question: {}", cap_handoff_text(body))];
+ }
+ }
+
+ // Heuristic 2: file activity with no subsequent Stop → the session ended
+ // abnormally while working in the tree.
+ //
+ // The signal is the tool *family*, not the tool name. A PostToolUse
+ // observation's title carries the family in one of two spellings: the
+ // majority path (every closed-tool agent) writes `safe_tool_title`'s
+ // `"tool file"` / `"tool non-file"` / …, while the reserved-protocol
+ // path writes the bare `canonical_tool_name` form `"file"` / …. Both
+ // must match here, and `tool_family_from_title` recognises both; a raw
+ // tool name ("edit"/"write"/"patch") is neither and correctly does not.
+ //
+ // That same closed schema means read and write are indistinguishable:
+ // `ToolFamily::File` covers both, and `ToolOutcome` is only
+ // success/error/unknown. So this cannot honestly claim changes were
+ // made — only that the session touched files and then ended without a
+ // normal Stop, which is worth telling the receiver either way.
+ if let Some(tool) = last_tool {
+ let touched_files =
+ crate::payload::tool_family_from_title(&tool.title) == Some(ToolFamily::File);
+ if touched_files && last_stop.is_none() {
+ return vec![
+ "Session ended without a normal stop while working with files".into(),
+ "Check the working tree for uncommitted or unverified changes".into(),
+ ];
+ }
+ }
+
+ // Heuristic 3 & 4: use the last *substantive* prompt.
+ if let Some(p) = last_prompt {
+ let body = p.trim();
+ if !body.is_empty() && !is_acknowledgment(body) {
+ // Heuristic 3 signal: no SessionEnd → flag as mid-task.
+ if !has_session_end && last_stop.is_some() {
+ return vec![format!(
+ "Continue from (mid-task exit): {}",
+ cap_handoff_text(body)
+ )];
+ }
+ // Heuristic 4: normal end.
+ return vec![format!("Continue from: {}", cap_handoff_text(body))];
+ }
+ }
+
+ // Fallback: no substantive prompt → empty (same as old behaviour).
+ Vec::new()
+}
+}
+
+use ai_memory_core::{
+ AgentKind, NewSession, ObservationId, ObservationKind, ProjectId, SessionId, WorkspaceId,
+};
+use ai_memory_store::Store;
+use rusqlite::{Connection, params};
+use tempfile::TempDir;
+
+use super::{HandoffFacts, SessionDigest, is_ephemeral_session};
+
+/// `created_at` of the first row of every fixture, in microseconds.
+const BASE_US: i64 = 1_780_000_000_000_000;
+/// The longest raw-observation list a page prints whole.
+const RAW_CAP: usize = 500;
+/// Slack the bound tests allow on top of the head and tail lines: one row per
+/// early-exit scan (end marker, first and last prompt, question prompt, last
+/// tool, latest assistant response).
+const SCAN_SLACK: usize = 16;
+const SUBAGENT_PREAMBLE: &str = "You are a subagent spawned by another session.";
+
+/// A harness block delivered as a user turn: not a request to continue from.
+const TASK_NOTIFICATION: &str =
+ "<task-notification>\n<task-id>abc</task-id>\n<status>completed</status>\n</task-notification>";
+
+/// One observation row to seed, with its time in whole seconds after
+/// [`BASE_US`] (equal seconds are ties, ordered by insertion).
+#[derive(Clone)]
+struct Row {
+ kind: ObservationKind,
+ title: String,
+ body: String,
+ at: i64,
+ extension: Option<&'static str>,
+ source_event: Option<&'static str>,
+}
+
+fn row(kind: ObservationKind, title: &str, body: &str, at: i64) -> Row {
+ Row {
+ kind,
+ title: title.to_string(),
+ body: body.to_string(),
+ at,
+ extension: None,
+ source_event: None,
+ }
+}
+
+struct Fixture {
+ _tmp: TempDir,
+ store: Store,
+ ws: WorkspaceId,
+ proj: ProjectId,
+}
+
+async fn fixture() -> Fixture {
+ let tmp = TempDir::new().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let ws = store
+ .writer
+ .get_or_create_workspace("default")
+ .await
+ .unwrap();
+ let proj = store
+ .writer
+ .get_or_create_project(ws, "equivalence", None)
+ .await
+ .unwrap();
+ Fixture {
+ _tmp: tmp,
+ store,
+ ws,
+ proj,
+ }
+}
+
+impl Fixture {
+ /// Seed one session with `rows` in order, with plain SQL in one
+ /// transaction: tens of thousands of rows through the writer actor would
+ /// spend the test's whole time budget on the fixture.
+ async fn seed(&self, rows: &[Row]) -> SessionId {
+ let sid = SessionId::new();
+ self.store
+ .writer
+ .begin_session(NewSession {
+ occurred_at: None,
+ id: sid,
+ workspace_id: self.ws,
+ project_id: self.proj,
+ agent_kind: AgentKind::ClaudeCode,
+ cwd: None,
+ actor_user: None,
+ })
+ .await
+ .unwrap();
+ let mut conn = Connection::open(self.store.db_path()).unwrap();
+ conn.pragma_update(None, "synchronous", "OFF").unwrap();
+ // The FTS trigger indexes every inserted row, which is most of what
+ // seeding thousands of rows costs; nothing here searches them.
+ conn.execute_batch("DROP TRIGGER IF EXISTS observations_fts_ai")
+ .unwrap();
+ let tx = conn.transaction().unwrap();
+ {
+ let mut insert = tx
+ .prepare(
+ "INSERT INTO observations \
+ (id, session_id, workspace_id, project_id, kind, extension, source_event, \
+ title, body, importance, created_at) \
+ VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, 5, ?10)",
+ )
+ .unwrap();
+ for r in rows {
+ insert
+ .execute(params![
+ ObservationId::new().as_bytes(),
+ sid.as_bytes(),
+ self.ws.as_bytes(),
+ self.proj.as_bytes(),
+ r.kind.as_str(),
+ r.extension,
+ r.source_event,
+ r.title,
+ r.body,
+ BASE_US + r.at * 1_000_000,
+ ])
+ .unwrap();
+ }
+ }
+ tx.commit().unwrap();
+ sid
+ }
+
+ /// Everything the SessionEnd path renders, through the bounded reads and
+ /// through the row load they replaced, and the claim that they agree.
+ async fn assert_equivalent(&self, name: &str, sid: SessionId) {
+ let reader = &self.store.reader;
+ // The original path: every row, then the original row-list code.
+ let rows = reader.observations_for_session(sid).await.unwrap();
+ let agent = AgentKind::ClaudeCode;
+ let old_page = full_load::synthesize_session_page(self.ws, self.proj, sid, agent, &rows);
+
+ let digest = SessionDigest::load(reader, sid).await.unwrap();
+ let new_page = super::synthesize_session_page(self.ws, self.proj, sid, agent, &digest);
+ assert_eq!(new_page.path, old_page.path, "{name}: page path");
+ assert_eq!(new_page.title, old_page.title, "{name}: page title");
+ assert_eq!(
+ new_page.frontmatter_json, old_page.frontmatter_json,
+ "{name}: page frontmatter"
+ );
+ assert_eq!(new_page.body, old_page.body, "{name}: page body");
+
+ for turn_checkpoint in [false, true] {
+ let old_handoff = full_load::build_auto_handoff(
+ self.ws,
+ self.proj,
+ agent,
+ sid,
+ Some("/work/repo".into()),
+ &rows,
+ Some("owner".into()),
+ turn_checkpoint,
+ );
+ let new_handoff = super::build_auto_handoff(
+ self.ws,
+ self.proj,
+ agent,
+ sid,
+ Some("/work/repo".into()),
+ &digest,
+ Some("owner".into()),
+ turn_checkpoint,
+ );
+ let ctx = format!("{name}: handoff (turn_checkpoint={turn_checkpoint})");
+ assert_eq!(new_handoff.summary, old_handoff.summary, "{ctx} summary");
+ assert_eq!(
+ new_handoff.open_questions, old_handoff.open_questions,
+ "{ctx} open_questions"
+ );
+ assert_eq!(
+ new_handoff.next_steps, old_handoff.next_steps,
+ "{ctx} next_steps"
+ );
+ assert_eq!(
+ new_handoff.files_touched, old_handoff.files_touched,
+ "{ctx} files_touched"
+ );
+ assert_eq!(new_handoff.cwd, old_handoff.cwd, "{ctx} cwd");
+ assert_eq!(
+ new_handoff.owner_user, old_handoff.owner_user,
+ "{ctx} owner"
+ );
+ assert_eq!(
+ new_handoff.from_session_id, old_handoff.from_session_id,
+ "{ctx} session"
+ );
+ }
+
+ // The lifecycle-only decision: one existence query, same verdict as
+ // the original in-memory predicate.
+ let ephemeral = is_ephemeral_session(&rows);
+ assert_eq!(
+ !reader
+ .session_has_substantive_observation(sid)
+ .await
+ .unwrap(),
+ ephemeral,
+ "{name}: ephemeral decision (existence query)"
+ );
+ assert_eq!(
+ digest.is_substantive(),
+ !ephemeral,
+ "{name}: ephemeral decision (digest)"
+ );
+
+ // And the digest itself is the one walking the rows gives, which is
+ // what the unit tests of the renderers are written against.
+ assert_eq!(
+ digest,
+ SessionDigest::from_observations(sid, &rows),
+ "{name}: database digest vs row-list digest"
+ );
+ assert_eq!(
+ digest.handoff_facts(),
+ &HandoffFacts::from_observations(&rows),
+ "{name}: handoff facts"
+ );
+ }
+}
+
+fn start(at: i64) -> Row {
+ row(ObservationKind::SessionStart, "session-start", "", at)
+}
+
+fn prompt(text: &str, at: i64) -> Row {
+ row(ObservationKind::UserPrompt, text, text, at)
+}
+
+fn end(at: i64) -> Row {
+ row(
+ ObservationKind::SessionEnd,
+ "session-end",
+ "reason: logout",
+ at,
+ )
+}
+
+/// A pre/post pair of one tool.
+fn tool_pair(title: &str, at: i64) -> [Row; 2] {
+ [
+ row(ObservationKind::PreToolUse, title, "", at),
+ row(ObservationKind::PostToolUse, title, "", at + 1),
+ ]
+}
+
+// ── fixtures ────────────────────────────────────────────────────────────
+
+fn lifecycle_only() -> Vec<Row> {
+ vec![
+ start(0),
+ row(ObservationKind::Stop, "stop", "", 1),
+ row(ObservationKind::Notification, "notification", "", 2),
+ end(3),
+ ]
+}
+
+fn small() -> Vec<Row> {
+ let mut rows = vec![start(0), prompt("fix the flaky scheduler test", 1)];
+ rows.extend(tool_pair("Bash", 2));
+ // A call that never completed (cancelled): counted by nothing, but its
+ // name still reaches the handoff.
+ rows.push(row(ObservationKind::PreToolUse, "Grep", "", 3));
+ rows.extend(tool_pair("tool file", 4));
+ rows.push(row(ObservationKind::Stop, "stop", "", 6));
+ rows.push(end(7));
+ rows
+}
+
+/// `n` rows: a start, one prompt, then alternating tool pairs.
+fn of_length(n: usize) -> Vec<Row> {
+ let mut rows = vec![start(0), prompt("grow the list to a boundary size", 1)];
+ let mut at = 2;
+ while rows.len() < n {
+ let [pre, post] = tool_pair(if at % 4 == 0 { "Bash" } else { "Edit" }, at);
+ rows.push(pre);
+ if rows.len() < n {
+ rows.push(post);
+ }
+ at += 2;
+ }
+ rows.truncate(n);
+ rows
+}
+
+#[derive(Clone, Copy)]
+enum Ending {
+ /// Stop, then SessionEnd.
+ Normal,
+ /// The last completed tool call touched files and nothing followed.
+ FileToolNoStop,
+ /// The last prompt is an unanswered question.
+ QuestionNoStop,
+ /// A Stop and no SessionEnd.
+ StopNoEnd,
+}
+
+/// A few thousand mixed rows: prompts of every kind the heuristics tell apart,
+/// both tool families and real tool names, ties, stops with and without
+/// assistant text, long multi-byte titles and extension events.
+fn large(n: usize, ending: Ending) -> Vec<Row> {
+ let long = "長い題名".repeat(40);
+ let mut rows = vec![
+ start(0),
+ // A second start: the newest one is the page's `started_at`.
+ start(1),
+ prompt("make the backpressure test deterministic", 2),
+ ];
+ let mut at = 3_i64;
+ let mut seed = 7_u64;
+ let mut next = || {
+ seed = seed
+ .wrapping_mul(6_364_136_223_846_793_005)
+ .wrapping_add(1_442_695_040_888_963_407);
+ (seed >> 33) as usize
+ };
+ while rows.len() < n.saturating_sub(8) {
+ match next() % 12 {
+ 0 => rows.push(prompt(&format!("question number {at}?"), at)),
+ 1 => rows.push(prompt("ok", at)),
+ 2 => rows.push(row(
+ ObservationKind::UserPrompt,
+ "<task-notification>",
+ TASK_NOTIFICATION,
+ at,
+ )),
+ 3 => rows.push(prompt(&format!("{long} {at}"), at)),
+ 4 => {
+ let mut r = row(ObservationKind::Other, "extension event", "", at);
+ r.extension = Some("ext");
+ r.source_event = Some("evt");
+ rows.push(r);
+ }
+ 5 => rows.push(row(
+ ObservationKind::Stop,
+ "stop",
+ if next() % 2 == 0 {
+ "assistant said so"
+ } else {
+ ""
+ },
+ at,
+ )),
+ 6 => rows.extend(tool_pair("tool file", at)),
+ 7 => rows.extend(tool_pair("tool non-file", at)),
+ 8 => rows.extend(tool_pair("Bash", at)),
+ 9 => rows.extend(tool_pair("Edit", at)),
+ 10 if next() % 3 == 0 => rows.push(row(ObservationKind::PreToolUse, "Grep", "", at)),
+ 10 => {
+ // A tie: three rows at one instant.
+ rows.push(row(ObservationKind::Notification, "notification", "", at));
+ rows.push(row(ObservationKind::PreToolUse, "Read", "", at));
+ rows.push(row(ObservationKind::PostToolUse, "Read", "", at));
+ }
+ _ => rows.push(prompt(&format!("continue with step {at}"), at)),
+ }
+ at += 1;
+ }
+ let tail: Vec<Row> = match ending {
+ Ending::Normal => vec![
+ prompt("thanks", at),
+ row(ObservationKind::Stop, "stop", "all done", at + 1),
+ end(at + 2),
+ ],
+ Ending::FileToolNoStop => {
+ let mut v = vec![prompt("edit the file", at)];
+ v.extend(tool_pair("tool file", at + 1));
+ v
+ }
+ Ending::QuestionNoStop => vec![prompt("is this the right approach?", at)],
+ Ending::StopNoEnd => vec![
+ prompt("keep going", at),
+ row(ObservationKind::Stop, "stop", "", at + 1),
+ ],
+ };
+ rows.extend(tail);
+ rows
+}
+
+fn markup_only_prompts() -> Vec<Row> {
+ let mut rows = vec![start(0)];
+ for i in 0..3 {
+ rows.push(row(
+ ObservationKind::UserPrompt,
+ "<task-notification>",
+ TASK_NOTIFICATION,
+ 1 + i,
+ ));
+ }
+ rows.extend(tool_pair("tool file", 5));
+ rows.extend(tool_pair("Bash", 7));
+ rows
+}
+
+fn subagent_preamble(body: &str) -> Vec<Row> {
+ vec![
+ start(0),
+ row(ObservationKind::UserPrompt, SUBAGENT_PREAMBLE, body, 1),
+ row(ObservationKind::PostToolUse, "Read", "", 2),
+ ]
+}
+
+fn tools_only() -> Vec<Row> {
+ let mut rows = vec![start(0)];
+ rows.extend(tool_pair("tool non-file", 1));
+ rows.extend(tool_pair("Edit", 3));
+ rows
+}
+
+/// The last prompt has no text at all, and a question sits before it.
+fn empty_last_prompt() -> Vec<Row> {
+ vec![
+ start(0),
+ prompt("where does the writer actor start?", 1),
+ row(ObservationKind::UserPrompt, "", "", 2),
+ row(ObservationKind::PostToolUse, "Read", "", 3),
+ ]
+}
+
+/// The newest `Stop` with a body holds only whitespace: SQL calls it
+/// non-empty, the page trims it away, so the answer is the earlier one.
+fn whitespace_stop() -> Vec<Row> {
+ vec![
+ start(0),
+ prompt("summarise the change", 1),
+ row(ObservationKind::Stop, "stop", "the real answer", 2),
+ row(ObservationKind::PostToolUse, "Bash", "", 3),
+ row(ObservationKind::Stop, "stop", " \t\n", 4),
+ end(5),
+ ]
+}
+
+/// The newest rows share one instant: insertion order decides which is last.
+fn tied_tail() -> Vec<Row> {
+ vec![
+ start(0),
+ prompt("first", 1),
+ prompt("what about the tail?", 9),
+ prompt("a later statement", 9),
+ row(ObservationKind::PostToolUse, "tool file", "", 9),
+ row(ObservationKind::PostToolUse, "Bash", "", 9),
+ ]
+}
+
+/// Titles the title rule must skip: kind names, scaffolding, family labels.
+fn scaffolding_titles() -> Vec<Row> {
+ vec![
+ start(0),
+ row(ObservationKind::UserPrompt, "<ide_opened_file>noise", "", 1),
+ row(ObservationKind::Stop, "stop", "", 2),
+ row(ObservationKind::Notification, "notification", "", 3),
+ row(ObservationKind::PostToolUse, "tool file", "", 4),
+ row(ObservationKind::Other, "A real title", "", 5),
+ ]
+}
+
+// ── the tests ───────────────────────────────────────────────────────────
+
+/// Page, handoff (both flavours) and the lifecycle-only decision are the same
+/// whether they come from the bounded reads or from the full row load, on every
+/// small and boundary shape.
+#[tokio::test]
+async fn small_and_boundary_sessions_render_identically() {
+ let fx = fixture().await;
+ let empty = fx.seed(&[]).await;
+ fx.assert_equivalent("empty", empty).await;
+ for (name, rows) in [
+ ("lifecycle-only", lifecycle_only()),
+ ("small", small()),
+ ("499 rows", of_length(RAW_CAP - 1)),
+ ("500 rows (whole list)", of_length(RAW_CAP)),
+ ("501 rows (one omitted)", of_length(RAW_CAP + 1)),
+ ("600 rows", of_length(600)),
+ ("markup-only prompts", markup_only_prompts()),
+ (
+ "preamble with a usable body",
+ subagent_preamble("\n\n <ide_opened_file>x\n Review the diff in src/lib.rs\nmore"),
+ ),
+ (
+ "preamble with no usable body",
+ subagent_preamble("<ide_opened_file>x\n\n"),
+ ),
+ ("tools only", tools_only()),
+ ("empty last prompt", empty_last_prompt()),
+ ("whitespace-only last stop", whitespace_stop()),
+ ("tied tail", tied_tail()),
+ ("scaffolding titles", scaffolding_titles()),
+ ] {
+ let sid = fx.seed(&rows).await;
+ fx.assert_equivalent(name, sid).await;
+ }
+}
+
+/// A couple of thousand mixed rows, with each way a session can end.
+#[tokio::test]
+async fn a_large_mixed_session_renders_identically() {
+ let fx = fixture().await;
+ for (name, ending) in [
+ ("normal end", Ending::Normal),
+ ("file tool, no stop", Ending::FileToolNoStop),
+ ("unanswered question", Ending::QuestionNoStop),
+ ("stop without end", Ending::StopNoEnd),
+ ] {
+ let sid = fx.seed(&large(2_500, ending)).await;
+ fx.assert_equivalent(name, sid).await;
+ }
+}
+
+/// The page lists every prompt title, so the digest keeps them all; nothing
+/// else about a session grows its digest.
+#[tokio::test]
+async fn a_huge_session_reads_a_bounded_number_of_rows() {
+ let fx = fixture().await;
+ let rows = large(12_000, Ending::Normal);
+ let prompts = rows
+ .iter()
+ .filter(|r| r.kind == ObservationKind::UserPrompt)
+ .count();
+ let sid = fx.seed(&rows).await;
+ assert!(
+ rows.len() > 20 * RAW_CAP,
+ "the fixture must dwarf the bound"
+ );
+
+ let before = fx.store.reader.session_observation_rows_loaded();
+ let (digest, stats) = SessionDigest::load_with_stats(&fx.store.reader, sid)
+ .await
+ .unwrap();
+ let loaded = fx.store.reader.session_observation_rows_loaded() - before;
+
+ assert_eq!(digest.observation_count(), rows.len());
+ assert!(
+ stats.rows_read <= RAW_CAP + SCAN_SLACK,
+ "a {}-row session read {} rows; the page prints at most {RAW_CAP} lines",
+ rows.len(),
+ stats.rows_read
+ );
+ assert_eq!(
+ loaded, stats.rows_read as u64,
+ "the pool's counter and the snapshot's agree"
+ );
+ assert_eq!(stats.prompt_titles, prompts);
+
+ // Control: the load this replaced materializes every row.
+ let full = fx.store.reader.observations_for_session(sid).await.unwrap();
+ assert_eq!(full.len(), rows.len());
+ assert_eq!(
+ fx.store.reader.session_observation_rows_loaded() - before - loaded,
+ rows.len() as u64
+ );
+ // And the output did not change for being cheap.
+ fx.assert_equivalent("12k rows", sid).await;
+}
+
+/// The Rust predicate the original code used and the existence query the
+/// router asks now classify every observation kind alike. (The writer's
+/// lifecycle-only re-check is pinned to the same query in
+/// `ops::tests::the_lifecycle_only_verdict_follows_the_reader_predicate`.)
+#[tokio::test]
+async fn the_ephemeral_predicate_agrees_for_every_observation_kind() {
+ // An exhaustive match: a new kind cannot be added without deciding here.
+ fn all_kinds(kind: ObservationKind) -> bool {
+ match kind {
+ ObservationKind::SessionStart
+ | ObservationKind::UserPrompt
+ | ObservationKind::PreToolUse
+ | ObservationKind::PostToolUse
+ | ObservationKind::PreCompact
+ | ObservationKind::PostCompaction
+ | ObservationKind::Notification
+ | ObservationKind::Stop
+ | ObservationKind::SessionEnd
+ | ObservationKind::Other => true,
+ }
+ }
+ let kinds = [
+ ObservationKind::SessionStart,
+ ObservationKind::UserPrompt,
+ ObservationKind::PreToolUse,
+ ObservationKind::PostToolUse,
+ ObservationKind::PreCompact,
+ ObservationKind::PostCompaction,
+ ObservationKind::Notification,
+ ObservationKind::Stop,
+ ObservationKind::SessionEnd,
+ ObservationKind::Other,
+ ];
+ assert!(kinds.iter().all(|k| all_kinds(*k)));
+
+ let fx = fixture().await;
+ for kind in kinds {
+ let rows = [row(kind, "title", "body", 0)];
+ let sid = fx.seed(&rows).await;
+ let materialized = fx.store.reader.observations_for_session(sid).await.unwrap();
+ let rust = !is_ephemeral_session(&materialized);
+ let sql = fx
+ .store
+ .reader
+ .session_has_substantive_observation(sid)
+ .await
+ .unwrap();
+ let digest = SessionDigest::load(&fx.store.reader, sid).await.unwrap();
+ assert_eq!(sql, rust, "{kind:?}: existence query vs row predicate");
+ assert_eq!(
+ digest.is_substantive(),
+ rust,
+ "{kind:?}: digest vs row predicate"
+ );
+ }
+}
diff --git a/crates/ai-memory-hooks/src/synth.rs b/crates/ai-memory-hooks/src/synth.rs
index cac8fe98..096bda3d 100644
--- a/crates/ai-memory-hooks/src/synth.rs
+++ b/crates/ai-memory-hooks/src/synth.rs
@@ -1,28 +1,40 @@
//! Rule-based session-page synthesis (no LLM).
//!
-//! At `SessionEnd` we already have N observation rows for the session.
-//! We turn them into a single markdown page under `wiki/sessions/<id>.md`
-//! using only deterministic heuristics: first-prompt as title, files
-//! touched, tool-call counts. Once the LLM provider lands in M6 we'll
-//! add an opt-in path that re-narrates the page.
+//! At `SessionEnd` we turn a session's observations into a single markdown
+//! page under `wiki/sessions/<id>.md` using only deterministic heuristics:
+//! first-prompt as title, files touched, tool-call counts. Once the LLM
+//! provider lands in M6 we'll add an opt-in path that re-narrates the page.
+//!
+//! The page is rendered from a [`SessionDigest`], not from the observation
+//! rows. A session can hold hundreds of thousands of rows, and everything the
+//! page and the auto-handoff print is either a count, a "last of a kind"
+//! marker, the head and tail the raw-observation list shows, or the first or
+//! last row that passes a predicate. [`SessionDigest::load`] reads exactly
+//! those with bounded queries, so the memory a SessionEnd spends does not grow
+//! with the session, and the output is the one the full row list produced.
-use std::collections::BTreeMap;
+use std::collections::{BTreeMap, BTreeSet};
use ai_memory_core::{
AgentKind, NewPage, Observation, ObservationKind, PagePath, ProjectId, SessionId, Tier,
WorkspaceId, looks_like_markup_block, looks_like_scaffolding, truncate_for_title,
};
+use ai_memory_store::{
+ ObservationOrder, ReaderPool, SessionKindSummary, SessionLine, SessionObservationSnapshot,
+ SessionPromptTitle, StoreError, StoreResult,
+};
+use jiff::Timestamp;
use jiff::tz::TimeZone;
use crate::capture_policy::ToolFamily;
-use crate::payload::is_safe_tool_title;
+use crate::payload::{is_safe_tool_title, tool_family_from_title};
const RAW_OBSERVATION_MAX_LINES: usize = 500;
const RAW_OBSERVATION_HEAD_LINES: usize = 250;
const RAW_OBSERVATION_TAIL_LINES: usize = RAW_OBSERVATION_MAX_LINES - RAW_OBSERVATION_HEAD_LINES;
const SUBAGENT_PROMPT_PREAMBLE: &str = "You are a subagent spawned by another session.";
-/// Build a [`NewPage`] from the observations collected during a session.
+/// Build a [`NewPage`] from the digest of a session's observations.
///
/// The returned page is *always* under `sessions/<session-id>.md` so each
/// session has a stable URL the user can bookmark.
@@ -32,13 +44,12 @@ pub fn synthesize_session_page(
project_id: ProjectId,
session_id: SessionId,
agent_kind: AgentKind,
- observations: &[Observation],
+ digest: &SessionDigest,
) -> NewPage {
- // One tally for the whole page: the body renderer and the summary builder
- // describe the same session and must not scan it twice to do so.
- let tally = tally_session(observations);
- let title = derive_title(observations, session_id);
- let body = render_body(session_id, observations, &title, &tally);
+ // The body renderer and the summary builder describe the same session and
+ // read the same digest, so they cannot describe it differently.
+ let title = digest.title.clone();
+ let body = render_body(session_id, digest, &title);
let mut frontmatter_json = serde_json::json!({
"title": title,
"session_id": session_id.to_string(),
@@ -48,7 +59,7 @@ pub fn synthesize_session_page(
"agent": agent_kind.as_str(),
"tier": "episodic",
});
- let summary = session_summary(&tally);
+ let summary = session_summary(digest);
if !summary.is_empty() {
// Insert only when there is something to say. The store's hit
// descriptor prefers `summary` over the body, so writing a blank one
@@ -74,6 +85,331 @@ pub fn synthesize_session_page(
}
}
+/// A user prompt's text for the handoff and the abrupt-ending check: the body
+/// when there is one, the title otherwise.
+fn prompt_text(obs: &Observation) -> &str {
+ if obs.body.is_empty() {
+ obs.title.as_str()
+ } else {
+ obs.body.as_str()
+ }
+}
+
+/// One user prompt, as far as the open-question heuristics read it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct PromptFact {
+ pub(crate) title: String,
+ pub(crate) body: String,
+}
+
+/// The terminal `SessionEnd` observation, as far as the page reads it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct SessionEndFact {
+ created_at: Timestamp,
+ body: String,
+}
+
+/// Everything the auto-handoff and the abrupt-ending note read from a
+/// session's observations, besides what [`SessionDigest`] already counts.
+///
+/// Each field is the answer to a question the full row list used to answer by
+/// walking it; the `*_prompt*` and `latest_assistant` fields hold the first or
+/// last row that passes the same predicate, found by an early-exit scan.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub(crate) struct HandoffFacts {
+ /// First user prompt with usable text (not a harness markup block).
+ pub(crate) first_prompt: Option<String>,
+ /// Last user prompt with usable text.
+ pub(crate) last_prompt: Option<String>,
+ /// Last user prompt that is not a markup block, even when its text is
+ /// empty: the one the open-question heuristics test for a question.
+ pub(crate) question_prompt: Option<PromptFact>,
+ /// Title of the last completed tool call.
+ pub(crate) last_tool_title: Option<String>,
+ /// Body of the last `Stop` that carries assistant text.
+ pub(crate) latest_assistant: Option<String>,
+ /// The session recorded a `Stop`.
+ pub(crate) has_stop: bool,
+ /// The session recorded a `SessionEnd`.
+ pub(crate) has_session_end: bool,
+ /// Tool names worth listing in the baton: a harness's own tool name, not
+ /// a `tool <family>` label.
+ pub(crate) tools: BTreeSet<String>,
+}
+
+/// What a session's page and handoff are rendered from.
+///
+/// Built by [`Self::load`] with bounded reads in one read transaction, so a
+/// session of any size costs the same memory apart from what the output itself
+/// lists: the title of every user prompt, because the page prints each one.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SessionDigest {
+ /// Rows the session holds.
+ total: usize,
+ /// At least one prompt or tool use (the page is not lifecycle-only).
+ substantive: bool,
+ /// The first raw-observation lines the page shows (all of them when the
+ /// session fits in [`RAW_OBSERVATION_MAX_LINES`]).
+ first_lines: Vec<SessionLine>,
+ /// The last lines, only for a session longer than the cap.
+ last_lines: Vec<SessionLine>,
+ /// When the newest `SessionStart` happened.
+ start_at: Option<Timestamp>,
+ /// The newest `SessionEnd`.
+ end: Option<SessionEndFact>,
+ /// Every user prompt's title, in capture order.
+ prompt_titles: Vec<String>,
+ /// Completed calls per tool name, keyed for stable ordering.
+ tool_counts: BTreeMap<String, usize>,
+ /// The page title.
+ title: String,
+ /// What the handoff and the abrupt-ending note read.
+ handoff: HandoffFacts,
+}
+
+/// What loading a [`SessionDigest`] cost, for a bound test and for debugging.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct DigestLoadStats {
+ /// Rows deserialized: the raw-observation lines plus every row an
+ /// early-exit scan visited (one resident at a time).
+ pub rows_read: usize,
+ /// User prompts whose title the digest keeps.
+ pub prompt_titles: usize,
+}
+
+impl SessionDigest {
+ /// Read a session's digest with bounded queries.
+ ///
+ /// # Errors
+ /// Propagates any store error.
+ pub async fn load(reader: &ReaderPool, session_id: SessionId) -> StoreResult<Self> {
+ Ok(Self::load_with_stats(reader, session_id).await?.0)
+ }
+
+ /// [`Self::load`], also reporting what the load read.
+ ///
+ /// # Errors
+ /// Propagates any store error.
+ pub async fn load_with_stats(
+ reader: &ReaderPool,
+ session_id: SessionId,
+ ) -> StoreResult<(Self, DigestLoadStats)> {
+ reader
+ .read_session_observations(session_id, move |snapshot| {
+ build_digest(snapshot, session_id)
+ })
+ .await
+ }
+
+ /// Whether the session recorded real work (a prompt or a tool use).
+ #[must_use]
+ pub fn is_substantive(&self) -> bool {
+ self.substantive
+ }
+
+ /// Rows the session holds.
+ #[must_use]
+ pub fn observation_count(&self) -> usize {
+ self.total
+ }
+
+ pub(crate) fn handoff_facts(&self) -> &HandoffFacts {
+ &self.handoff
+ }
+}
+
+fn micros_to_timestamp(micros: i64) -> StoreResult<Timestamp> {
+ Timestamp::from_microsecond(micros).map_err(|e| {
+ StoreError::Memory(ai_memory_core::MemoryError::MalformedRecord(format!(
+ "bad timestamp: {e}"
+ )))
+ })
+}
+
+/// The handoff prompt predicate: a user prompt whose text is not empty and not
+/// a harness block delivered as a user turn (`<task-notification>`).
+fn handoff_prompt(obs: &Observation) -> Option<String> {
+ if obs.kind != ObservationKind::UserPrompt {
+ return None;
+ }
+ let text = prompt_text(obs);
+ (!text.is_empty() && !looks_like_markup_block(text)).then(|| text.to_string())
+}
+
+/// The open-question prompt predicate: a user prompt that is not a harness
+/// block. An empty text still counts, as it always did.
+fn question_prompt(obs: &Observation) -> Option<PromptFact> {
+ if obs.kind != ObservationKind::UserPrompt || looks_like_markup_block(prompt_text(obs)) {
+ return None;
+ }
+ Some(PromptFact {
+ title: obs.title.clone(),
+ body: obs.body.clone(),
+ })
+}
+
+/// Stop bodies exist only after the assistant-capture double opt-in.
+fn assistant_response(obs: &Observation) -> Option<String> {
+ (obs.kind == ObservationKind::Stop && !obs.body.trim().is_empty()).then(|| obs.body.clone())
+}
+
+#[cfg(test)]
+fn session_line(obs: &Observation) -> SessionLine {
+ SessionLine {
+ kind: obs.kind,
+ extension: obs.extension.clone(),
+ source_event: obs.source_event.clone(),
+ title: obs
+ .title
+ .chars()
+ .take(ai_memory_store::SESSION_LINE_TITLE_CHARS)
+ .collect(),
+ created_at: obs.created_at,
+ }
+}
+
+/// Tool names worth listing: a harness's own tool name. Skip `tool <family>` /
+/// bare-`<family>` labels: a family is a partition of the calls, not a name
+/// for a tool, so "Tools used: tool file, tool non-file" tells the receiver
+/// nothing.
+fn is_listable_tool_title(title: &str) -> bool {
+ !title.is_empty() && tool_family_from_title(title).is_none()
+}
+
+fn build_digest(
+ snapshot: &SessionObservationSnapshot<'_>,
+ session_id: SessionId,
+) -> StoreResult<(SessionDigest, DigestLoadStats)> {
+ let summary: SessionKindSummary = snapshot.kind_summary()?;
+ let total = summary.total;
+
+ // The raw-observation list: everything when it fits, else the head and the
+ // tail the page prints around its "omitted" marker.
+ let (first_lines, last_lines) = if total <= RAW_OBSERVATION_MAX_LINES {
+ (snapshot.first_lines(RAW_OBSERVATION_MAX_LINES)?, Vec::new())
+ } else {
+ (
+ snapshot.first_lines(RAW_OBSERVATION_HEAD_LINES)?,
+ snapshot.last_lines(RAW_OBSERVATION_TAIL_LINES)?,
+ )
+ };
+
+ let start_at = summary
+ .last_session_start_at
+ .map(micros_to_timestamp)
+ .transpose()?;
+ let end = match summary.last_session_end_at {
+ Some(at) => snapshot.scan(
+ ObservationOrder::Desc,
+ &[ObservationKind::SessionEnd],
+ Some(at),
+ |obs| {
+ Some(SessionEndFact {
+ created_at: obs.created_at,
+ body: obs.body.clone(),
+ })
+ },
+ )?,
+ None => None,
+ };
+
+ // Bodies only for a title that could be the subagent preamble: the title
+ // rule is the one reader of a prompt body.
+ let prompt_rows: Vec<SessionPromptTitle> = snapshot.prompt_titles(SUBAGENT_PROMPT_PREAMBLE)?;
+ let title = match title_from_prompts(
+ prompt_rows
+ .iter()
+ .map(|p| (p.title.as_str(), p.body.as_deref().unwrap_or(""))),
+ ) {
+ PromptTitle::Found(title) => title,
+ PromptTitle::RejectedPreamble => format!("Session {session_id}"),
+ PromptTitle::Unusable => snapshot
+ .scan(ObservationOrder::Asc, &[], None, fallback_title)?
+ .unwrap_or_else(|| title_without_candidate(session_id, total)),
+ };
+ let prompt_titles: Vec<String> = prompt_rows.into_iter().map(|p| p.title).collect();
+
+ let tools = snapshot.tool_titles()?;
+ let tool_counts: BTreeMap<String, usize> = tools.completed.into_iter().collect();
+
+ let handoff = HandoffFacts {
+ first_prompt: if summary.prompts > 0 {
+ snapshot.scan(
+ ObservationOrder::Asc,
+ &[ObservationKind::UserPrompt],
+ None,
+ handoff_prompt,
+ )?
+ } else {
+ None
+ },
+ last_prompt: snapshot.scan(
+ ObservationOrder::Desc,
+ &[ObservationKind::UserPrompt],
+ summary.last_prompt_at,
+ handoff_prompt,
+ )?,
+ question_prompt: snapshot.scan(
+ ObservationOrder::Desc,
+ &[ObservationKind::UserPrompt],
+ summary.last_prompt_at,
+ question_prompt,
+ )?,
+ last_tool_title: snapshot.scan(
+ ObservationOrder::Desc,
+ &[ObservationKind::PostToolUse],
+ summary.last_post_tool_at,
+ |obs| Some(obs.title.clone()),
+ )?,
+ latest_assistant: match summary.last_stop_with_body_at {
+ Some(at) => snapshot.scan(
+ ObservationOrder::Desc,
+ &[ObservationKind::Stop],
+ Some(at),
+ assistant_response,
+ )?,
+ None => None,
+ },
+ has_stop: summary.last_stop_at.is_some(),
+ has_session_end: summary.last_session_end_at.is_some(),
+ tools: tools
+ .titles
+ .into_iter()
+ .filter(|title| is_listable_tool_title(title))
+ .collect(),
+ };
+
+ let stats = DigestLoadStats {
+ rows_read: snapshot.rows_read(),
+ prompt_titles: prompt_titles.len(),
+ };
+ Ok((
+ SessionDigest {
+ total,
+ substantive: summary.substantive,
+ first_lines,
+ last_lines,
+ start_at,
+ end,
+ prompt_titles,
+ tool_counts,
+ title,
+ handoff,
+ },
+ stats,
+ ))
+}
+
+/// What the prompts alone say about the title.
+enum PromptTitle {
+ /// A usable prompt (or the body of a subagent preamble) named the page.
+ Found(String),
+ /// No prompt was usable, and at least one was the subagent preamble.
+ RejectedPreamble,
+ /// No prompt was usable: fall back to the other observations.
+ Unusable,
+}
+
/// Title for a synthesised session page.
///
/// Prefers the first user prompt that reads as something a person wrote.
@@ -105,53 +441,54 @@ pub fn synthesize_session_page(
/// any other usable observation title, then the session's own path. The
/// literal "session" remains only for the case where there is nothing else
/// at all.
-fn derive_title(observations: &[Observation], session_id: SessionId) -> String {
+fn title_from_prompts<'a>(prompts: impl Iterator<Item = (&'a str, &'a str)>) -> PromptTitle {
let mut rejected_subagent_preamble = false;
- for obs in observations {
- if obs.kind != ObservationKind::UserPrompt {
- continue;
- }
- if obs.title.trim() == SUBAGENT_PROMPT_PREAMBLE {
+ for (title, body) in prompts {
+ if title.trim() == SUBAGENT_PROMPT_PREAMBLE {
rejected_subagent_preamble = true;
- if let Some(title) = obs
- .body
+ if let Some(title) = body
.lines()
.map(str::trim)
.find(|line| !line.is_empty() && !looks_like_title_scaffolding(line))
{
- return truncate_for_title(title);
+ return PromptTitle::Found(truncate_for_title(title));
}
continue;
}
- if !obs.title.is_empty() && !looks_like_scaffolding(&obs.title) {
- return obs.title.clone();
+ if !title.is_empty() && !looks_like_scaffolding(title) {
+ return PromptTitle::Found(title.to_string());
}
}
if rejected_subagent_preamble {
- return format!("Session {session_id}");
+ PromptTitle::RejectedPreamble
+ } else {
+ PromptTitle::Unusable
}
- for obs in observations {
- // The router titles an untitled lifecycle event with its kind name
- // (`stop`, `session-end`): a string every such page would share, and
- // what this loop reached once tool-family labels were skipped (#895).
- if obs.kind == ObservationKind::SessionStart || obs.title == obs.kind.as_str() {
- continue;
- }
- // A `tool <family>` label is a partition of the calls, not a title:
- // `looks_like_scaffolding` does not catch it, so reject it here or a
- // session whose only non-prompt observation is a closed-tool call
- // ("tool non-file") would take the label as its page title.
- if !obs.title.is_empty()
- && !looks_like_title_scaffolding(&obs.title)
- && !is_safe_tool_title(&obs.title)
- {
- return obs.title.clone();
- }
+}
+
+/// The title a non-prompt observation can lend the page, in capture order.
+fn fallback_title(obs: &Observation) -> Option<String> {
+ // The router titles an untitled lifecycle event with its kind name
+ // (`stop`, `session-end`): a string every such page would share, and
+ // what this loop reached once tool-family labels were skipped (#895).
+ if obs.kind == ObservationKind::SessionStart || obs.title == obs.kind.as_str() {
+ return None;
}
- // Every candidate was scaffolding. The page still needs a title, and its
- // own identity is more use to a reader than the word "session" repeated
- // across every such page.
- if observations.is_empty() {
+ // A `tool <family>` label is a partition of the calls, not a title:
+ // `looks_like_scaffolding` does not catch it, so reject it here or a
+ // session whose only non-prompt observation is a closed-tool call
+ // ("tool non-file") would take the label as its page title.
+ (!obs.title.is_empty()
+ && !looks_like_title_scaffolding(&obs.title)
+ && !is_safe_tool_title(&obs.title))
+ .then(|| obs.title.clone())
+}
+
+/// Every candidate was scaffolding. The page still needs a title, and its
+/// own identity is more use to a reader than the word "session" repeated
+/// across every such page.
+fn title_without_candidate(session_id: SessionId, total: usize) -> String {
+ if total == 0 {
return "session".to_string();
}
format!("Session {session_id}")
@@ -161,54 +498,6 @@ fn looks_like_title_scaffolding(candidate: &str) -> bool {
candidate.trim() == SUBAGENT_PROMPT_PREAMBLE || looks_like_scaffolding(candidate)
}
-/// The per-session counts that both the rendered body and the frontmatter
-/// summary are built from.
-struct SessionTally<'a> {
- /// Completed calls per tool name, keyed for stable ordering.
- tool_counts: BTreeMap<&'a str, usize>,
- /// User prompts in arrival order.
- prompts: Vec<&'a Observation>,
- /// First `SessionStart`, if the session recorded one.
- start: Option<&'a Observation>,
- /// Last `SessionEnd`, if the session recorded one.
- end: Option<&'a Observation>,
-}
-
-/// Tally a session's observations once.
-///
-/// [`render_body`] and [`session_summary`] both need these counts, and
-/// [`synthesize_session_page`] computes them once and lends them to both — so
-/// a page costs one pass over its observations, not two, and the body and the
-/// summary cannot describe the same session differently. It also keeps the
-/// summary from having to parse the counts back out of the markdown the body
-/// just rendered them into.
-fn tally_session(observations: &[Observation]) -> SessionTally<'_> {
- let mut tally = SessionTally {
- tool_counts: BTreeMap::new(),
- prompts: Vec::new(),
- start: None,
- end: None,
- };
- for obs in observations {
- match obs.kind {
- ObservationKind::SessionStart => tally.start = Some(obs),
- ObservationKind::SessionEnd => tally.end = Some(obs),
- ObservationKind::UserPrompt => tally.prompts.push(obs),
- // Count only PostToolUse — each tool call produces both a
- // PreToolUse and a PostToolUse observation, so counting both
- // doubles every reported number ("Bash: 4" for two real calls).
- // PostToolUse is the "completed call" event; pre-only calls
- // that never produced a post (cancellations) are intentionally
- // excluded.
- ObservationKind::PostToolUse if !obs.title.is_empty() => {
- *tally.tool_counts.entry(obs.title.as_str()).or_insert(0) += 1;
- }
- _ => {}
- }
- }
- tally
-}
-
/// How many tools to name individually before summarising the rest as a count.
const SUMMARY_MAX_NAMED_TOOLS: usize = 3;
@@ -226,23 +515,26 @@ const SUMMARY_MAX_NAMED_TOOLS: usize = 3;
/// silently and with no error anywhere.
///
/// Hence: one line, plain prose, no leading marker.
-fn session_summary(tally: &SessionTally<'_>) -> String {
+fn session_summary(digest: &SessionDigest) -> String {
let mut parts: Vec<String> = Vec::new();
- if !tally.prompts.is_empty() {
+ if !digest.prompt_titles.is_empty() {
parts.push(format!(
"{} prompt{}",
- tally.prompts.len(),
- plural(tally.prompts.len())
+ digest.prompt_titles.len(),
+ plural(digest.prompt_titles.len())
));
}
- let calls: usize = tally.tool_counts.values().sum();
+ let calls: usize = digest.tool_counts.values().sum();
if calls > 0 {
// Name the busiest tools first; ties fall back to the map's
// alphabetical order so the same session always renders the same way.
- let mut by_calls: Vec<(&str, usize)> =
- tally.tool_counts.iter().map(|(k, v)| (*k, *v)).collect();
+ let mut by_calls: Vec<(&str, usize)> = digest
+ .tool_counts
+ .iter()
+ .map(|(k, v)| (k.as_str(), *v))
+ .collect();
by_calls.sort_by(|a, b| b.1.cmp(&a.1).then_with(|| a.0.cmp(b.0)));
// A `tool <family>` title is what `safe_tool_title` writes when the
// harness's own tool name is not carried through: a partition of the
@@ -279,9 +571,8 @@ fn session_summary(tally: &SessionTally<'_>) -> String {
});
}
- if let (Some(start), Some(end)) = (tally.start, tally.end)
- && let Some(spent) =
- format_duration(end.created_at.as_second() - start.created_at.as_second())
+ if let (Some(start), Some(end)) = (digest.start_at, digest.end.as_ref())
+ && let Some(spent) = format_duration(end.created_at.as_second() - start.as_second())
{
parts.push(format!("over {spent}"));
}
@@ -289,8 +580,9 @@ fn session_summary(tally: &SessionTally<'_>) -> String {
// The harness's own word for why the session ended (#1225), when the
// SessionEnd observation carried one. Display-bounded: a summary line
// is no place for a long free-text field.
- if let Some(reason) = tally
+ if let Some(reason) = digest
.end
+ .as_ref()
.and_then(|end| end.body.strip_prefix("reason: "))
.map(str::trim)
.filter(|reason| !reason.is_empty())
@@ -340,54 +632,42 @@ fn format_duration(seconds: i64) -> Option<String> {
})
}
-fn render_body(
- session_id: SessionId,
- observations: &[Observation],
- title: &str,
- tally: &SessionTally<'_>,
-) -> String {
- let SessionTally {
- tool_counts,
- prompts,
- start,
- end,
- } = tally;
-
+fn render_body(session_id: SessionId, digest: &SessionDigest, title: &str) -> String {
let mut buf = String::with_capacity(2048);
buf.push_str(&format!("# {title}\n\n"));
buf.push_str("## Session metadata\n\n");
buf.push_str(&format!("- **session_id:** `{session_id}`\n"));
- if let Some(s) = start {
- buf.push_str(&format!("- **started_at:** {}\n", human_ts(&s.created_at),));
+ if let Some(s) = &digest.start_at {
+ buf.push_str(&format!("- **started_at:** {}\n", human_ts(s)));
}
- if let Some(e) = end {
- buf.push_str(&format!("- **ended_at:** {}\n", human_ts(&e.created_at),));
+ if let Some(e) = &digest.end {
+ buf.push_str(&format!("- **ended_at:** {}\n", human_ts(&e.created_at)));
}
- buf.push_str(&format!("- **observations:** {}\n\n", observations.len()));
+ buf.push_str(&format!("- **observations:** {}\n\n", digest.total));
- if let Some(note) = abrupt_ending_note(observations) {
+ if let Some(note) = abrupt_ending_note(&digest.handoff) {
buf.push_str(&format!("{note}\n\n"));
}
- if !prompts.is_empty() {
+ if !digest.prompt_titles.is_empty() {
buf.push_str("## Prompts\n\n");
- for (i, p) in prompts.iter().enumerate() {
- buf.push_str(&format!("{}. {}\n", i + 1, p.title));
+ for (i, title) in digest.prompt_titles.iter().enumerate() {
+ buf.push_str(&format!("{}. {}\n", i + 1, title));
}
buf.push('\n');
}
- if !tool_counts.is_empty() {
+ if !digest.tool_counts.is_empty() {
buf.push_str("## Tool calls\n\n");
- for (name, count) in tool_counts {
+ for (name, count) in &digest.tool_counts {
buf.push_str(&format!("- `{name}`: {count}\n"));
}
buf.push('\n');
}
buf.push_str("## Raw observations\n\n");
- render_raw_observations(&mut buf, observations);
+ render_raw_observations(&mut buf, digest);
buf.push_str("\n_Synthesised by ai-memory (M3, no-LLM heuristic)._\n");
buf
@@ -407,20 +687,9 @@ fn render_body(
/// 3. A Stop was recorded but no SessionEnd — a mid-task exit (or a
/// checkpoint page rendered while the session is still running; the
/// wording only claims what the log shows).
-fn abrupt_ending_note(observations: &[Observation]) -> Option<&'static str> {
- let last_of_kind = |kind: ObservationKind| observations.iter().rev().find(|o| o.kind == kind);
- let last_stop = last_of_kind(ObservationKind::Stop);
- let has_session_end = observations
- .iter()
- .any(|o| o.kind == ObservationKind::SessionEnd);
- // Harness blocks delivered as a user turn are not the user's question.
- let last_prompt = observations.iter().rev().find(|o| {
- let text = if o.body.is_empty() { &o.title } else { &o.body };
- o.kind == ObservationKind::UserPrompt && !looks_like_markup_block(text)
- });
-
- if last_stop.is_none()
- && let Some(prompt) = last_prompt
+fn abrupt_ending_note(facts: &HandoffFacts) -> Option<&'static str> {
+ if !facts.has_stop
+ && let Some(prompt) = &facts.question_prompt
{
let text = if prompt.body.is_empty() {
prompt.title.trim()
@@ -434,9 +703,9 @@ fn abrupt_ending_note(observations: &[Observation]) -> Option<&'static str> {
}
}
- if last_stop.is_none()
- && let Some(tool) = last_of_kind(ObservationKind::PostToolUse)
- && crate::payload::tool_family_from_title(&tool.title) == Some(ToolFamily::File)
+ if !facts.has_stop
+ && let Some(tool) = &facts.last_tool_title
+ && tool_family_from_title(tool) == Some(ToolFamily::File)
{
return Some(
"Session ended without a normal stop while working with files; \
@@ -444,7 +713,7 @@ fn abrupt_ending_note(observations: &[Observation]) -> Option<&'static str> {
);
}
- if last_stop.is_some() && !has_session_end {
+ if facts.has_stop && !facts.has_session_end {
return Some(
"A stop was recorded but no session end; the session may have exited mid-task.",
);
@@ -453,42 +722,38 @@ fn abrupt_ending_note(observations: &[Observation]) -> Option<&'static str> {
None
}
-fn render_raw_observations(buf: &mut String, observations: &[Observation]) {
- if observations.len() <= RAW_OBSERVATION_MAX_LINES {
- for obs in observations {
- render_raw_observation(buf, obs);
- }
- return;
+fn render_raw_observations(buf: &mut String, digest: &SessionDigest) {
+ for line in &digest.first_lines {
+ render_raw_observation(buf, line);
}
-
- for obs in &observations[..RAW_OBSERVATION_HEAD_LINES] {
- render_raw_observation(buf, obs);
+ if digest.total <= RAW_OBSERVATION_MAX_LINES {
+ return;
}
- let omitted = observations.len() - RAW_OBSERVATION_HEAD_LINES - RAW_OBSERVATION_TAIL_LINES;
+ let omitted = digest.total - RAW_OBSERVATION_HEAD_LINES - RAW_OBSERVATION_TAIL_LINES;
buf.push_str(&format!(
"\n_... {omitted} raw observations omitted from the middle (showing first {RAW_OBSERVATION_HEAD_LINES} and last {RAW_OBSERVATION_TAIL_LINES})._\n\n",
));
- for obs in &observations[observations.len() - RAW_OBSERVATION_TAIL_LINES..] {
- render_raw_observation(buf, obs);
+ for line in &digest.last_lines {
+ render_raw_observation(buf, line);
}
}
-fn render_raw_observation(buf: &mut String, obs: &Observation) {
- let kind = observation_kind_label(obs);
+fn render_raw_observation(buf: &mut String, line: &SessionLine) {
+ let kind = observation_kind_label(line);
buf.push_str(&format!(
"- `{}` @ {} — {}\n",
kind,
- human_ts(&obs.created_at),
- obs.title.chars().take(80).collect::<String>(),
+ human_ts(&line.created_at),
+ line.title,
));
}
-fn observation_kind_label(obs: &Observation) -> String {
- match (&obs.extension, &obs.source_event) {
+fn observation_kind_label(line: &SessionLine) -> String {
+ match (&line.extension, &line.source_event) {
(Some(extension), Some(source_event)) => {
- format!("{} [{}:{}]", obs.kind.as_str(), extension, source_event)
+ format!("{} [{}:{}]", line.kind.as_str(), extension, source_event)
}
- _ => obs.kind.as_str().to_string(),
+ _ => line.kind.as_str().to_string(),
}
}
@@ -498,6 +763,107 @@ fn human_ts(ts: &jiff::Timestamp) -> String {
.to_string()
}
+/// The digest a full row list gives, computed by walking it with the same
+/// predicates the bounded queries apply. Test-only: production reads the
+/// database, and the equivalence tests pin this walk and the queries together.
+#[cfg(test)]
+impl SessionDigest {
+ pub(crate) fn from_observations(session_id: SessionId, observations: &[Observation]) -> Self {
+ let total = observations.len();
+ let (first_lines, last_lines) = if total <= RAW_OBSERVATION_MAX_LINES {
+ (observations.iter().map(session_line).collect(), Vec::new())
+ } else {
+ (
+ observations[..RAW_OBSERVATION_HEAD_LINES]
+ .iter()
+ .map(session_line)
+ .collect(),
+ observations[total - RAW_OBSERVATION_TAIL_LINES..]
+ .iter()
+ .map(session_line)
+ .collect(),
+ )
+ };
+ let last_of = |kind: ObservationKind| observations.iter().rev().find(|o| o.kind == kind);
+ let title = match title_from_prompts(
+ observations
+ .iter()
+ .filter(|o| o.kind == ObservationKind::UserPrompt)
+ .map(|o| (o.title.as_str(), o.body.as_str())),
+ ) {
+ PromptTitle::Found(title) => title,
+ PromptTitle::RejectedPreamble => format!("Session {session_id}"),
+ PromptTitle::Unusable => observations
+ .iter()
+ .find_map(fallback_title)
+ .unwrap_or_else(|| title_without_candidate(session_id, total)),
+ };
+ let mut tool_counts = BTreeMap::new();
+ for obs in observations {
+ if obs.kind == ObservationKind::PostToolUse && !obs.title.is_empty() {
+ *tool_counts.entry(obs.title.clone()).or_insert(0) += 1;
+ }
+ }
+ Self {
+ total,
+ substantive: observations.iter().any(|o| {
+ matches!(
+ o.kind,
+ ObservationKind::UserPrompt
+ | ObservationKind::PreToolUse
+ | ObservationKind::PostToolUse
+ )
+ }),
+ first_lines,
+ last_lines,
+ start_at: last_of(ObservationKind::SessionStart).map(|o| o.created_at),
+ end: last_of(ObservationKind::SessionEnd).map(|o| SessionEndFact {
+ created_at: o.created_at,
+ body: o.body.clone(),
+ }),
+ prompt_titles: observations
+ .iter()
+ .filter(|o| o.kind == ObservationKind::UserPrompt)
+ .map(|o| o.title.clone())
+ .collect(),
+ tool_counts,
+ title,
+ handoff: HandoffFacts::from_observations(observations),
+ }
+ }
+}
+
+#[cfg(test)]
+impl HandoffFacts {
+ pub(crate) fn from_observations(observations: &[Observation]) -> Self {
+ Self {
+ first_prompt: observations.iter().find_map(handoff_prompt),
+ last_prompt: observations.iter().rev().find_map(handoff_prompt),
+ question_prompt: observations.iter().rev().find_map(question_prompt),
+ last_tool_title: observations
+ .iter()
+ .rev()
+ .find(|o| o.kind == ObservationKind::PostToolUse)
+ .map(|o| o.title.clone()),
+ latest_assistant: observations.iter().rev().find_map(assistant_response),
+ has_stop: observations.iter().any(|o| o.kind == ObservationKind::Stop),
+ has_session_end: observations
+ .iter()
+ .any(|o| o.kind == ObservationKind::SessionEnd),
+ tools: observations
+ .iter()
+ .filter(|o| {
+ matches!(
+ o.kind,
+ ObservationKind::PostToolUse | ObservationKind::PreToolUse
+ ) && is_listable_tool_title(&o.title)
+ })
+ .map(|o| o.title.clone())
+ .collect(),
+ }
+ }
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -510,6 +876,34 @@ mod tests {
use ai_memory_core::{ObservationId, SessionId};
use jiff::Timestamp;
+ // The renderers take a digest of the session. These tests describe a
+ // session as the row list it is made of, so each shim digests that list
+ // the way the database queries do (`SessionDigest::from_observations`),
+ // and the assertions below read as they always did.
+ fn synthesize_session_page(
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ session_id: SessionId,
+ agent_kind: AgentKind,
+ observations: &[Observation],
+ ) -> NewPage {
+ super::synthesize_session_page(
+ workspace_id,
+ project_id,
+ session_id,
+ agent_kind,
+ &SessionDigest::from_observations(session_id, observations),
+ )
+ }
+
+ fn tally_session(observations: &[Observation]) -> SessionDigest {
+ SessionDigest::from_observations(SessionId::new(), observations)
+ }
+
+ fn derive_title(observations: &[Observation], session_id: SessionId) -> String {
+ SessionDigest::from_observations(session_id, observations).title
+ }
+
fn obs(kind: ObservationKind, title: &str) -> Observation {
Observation {
id: ObservationId::new(),
@@ -982,7 +1376,7 @@ mod tests {
];
let title = derive_title(&obs, test_session_id());
let tally = tally_session(&obs);
- let body = render_body(test_session_id(), &obs, &title, &tally);
+ let body = render_body(test_session_id(), &tally, &title);
assert!(
body.contains("Make the backpressure test deterministic"),
"the promoted prompt must still appear in the body: {body}"
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index 2a759c36..31b5bc16 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -92,11 +92,12 @@ pub use reader::{
PageMeta, PageSummary, PageVersion, PageVersionBody, PageVersions,
ProjectCoordinateCollisionReason, ProjectCoordinateDiagnostic, ProjectCoordinateStatus,
ProjectSummary, RELATED_WALK_MAX_DEPTH, RELATED_WALK_MAX_NODES, ReaderPool,
- ReindexTargetStatus, RelatedNode, RelatedPage, RrfContributions, ScopeRow, SearchExplain,
- SessionConsolidationQueue, SessionConsolidationSummary, SessionDependentRows,
- SessionEndDisposition, SessionSummary, SettledPage, StatusCounts, StorageStatus,
- StoredEmbedding, StoredPageBody, StreamTimings, VectorQuery, WorkspaceScopeRow,
- WorkspaceSummary, f32_vec_to_bytes,
+ ReindexTargetStatus, RelatedNode, RelatedPage, RrfContributions, SESSION_LINE_TITLE_CHARS,
+ SUBSTANTIVE_OBSERVATION_KIND_SQL, ScopeRow, SearchExplain, SessionConsolidationQueue,
+ SessionConsolidationSummary, SessionDependentRows, SessionEndDisposition, SessionKindSummary,
+ SessionLine, SessionObservationSnapshot, SessionPromptTitle, SessionSummary, SessionToolTitles,
+ SettledPage, StatusCounts, StorageStatus, StoredEmbedding, StoredPageBody, StreamTimings,
+ VectorQuery, WorkspaceScopeRow, WorkspaceSummary, f32_vec_to_bytes,
};
pub use retrieval_tuning::{RetrievalTuning, is_session_recall_query};
pub use scope::{
diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rs
index 3f8b15a7..9680a40c 100644
--- a/crates/ai-memory-store/src/ops.rs
+++ b/crates/ai-memory-store/src/ops.rs
@@ -2429,12 +2429,16 @@ fn end_lifecycle_only_session_in_tx(
// re-check would silently revert the router's verdict. Everything else,
// including `stop` and `notification` (some harnesses, e.g. OpenCode,
// fire these for purely internal work), is ephemeral.
+ // The predicate text is shared with the reader's SessionEnd aggregates
+ // (`SUBSTANTIVE_OBSERVATION_KIND_SQL`), so the two cannot drift.
let has_substantive_observation: bool = tx.query_row(
- "SELECT EXISTS( \
- SELECT 1 FROM observations \
- WHERE session_id = ?1 \
- AND kind IN ('user-prompt', 'pre-tool-use', 'post-tool-use') \
- )",
+ &format!(
+ "SELECT EXISTS( \
+ SELECT 1 FROM observations \
+ WHERE session_id = ?1 AND {} \
+ )",
+ crate::reader::SUBSTANTIVE_OBSERVATION_KIND_SQL
+ ),
params![session_id.as_bytes()],
|row| row.get(0),
)?;
@@ -12363,6 +12367,76 @@ pub(crate) mod tests {
);
}
+ /// The writer's lifecycle-only re-check and the reader's existence query
+ /// (the router's early SessionEnd decision) must classify every
+ /// observation kind alike: a disagreement would have the writer revert the
+ /// router's verdict on a session the router just rendered a page for.
+ #[test]
+ fn the_lifecycle_only_verdict_follows_the_reader_predicate() {
+ let (tmp, mut conn, ws, proj) = fresh_db();
+ let reader = crate::reader::ReaderPool::new(&tmp.path().join("test.sqlite"), 1).unwrap();
+ let runtime = tokio::runtime::Builder::new_current_thread()
+ .enable_all()
+ .build()
+ .unwrap();
+ for kind in [
+ ObservationKind::SessionStart,
+ ObservationKind::UserPrompt,
+ ObservationKind::PreToolUse,
+ ObservationKind::PostToolUse,
+ ObservationKind::PreCompact,
+ ObservationKind::PostCompaction,
+ ObservationKind::Notification,
+ ObservationKind::Stop,
+ ObservationKind::SessionEnd,
+ ObservationKind::Other,
+ ] {
+ let session = SessionId::new();
+ begin_session(
+ &mut conn,
+ &NewSession {
+ occurred_at: None,
+ id: session,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: AgentKind::OpenCode,
+ cwd: None,
+ actor_user: None,
+ },
+ )
+ .unwrap();
+ insert_observation(
+ &mut conn,
+ &NewObservation {
+ occurred_at: None,
+ session_id: session,
+ workspace_id: ws,
+ project_id: proj,
+ kind,
+ extension: None,
+ source_event: None,
+ title: "t".into(),
+ body: "b".into(),
+ importance: 5,
+ },
+ )
+ .unwrap();
+ // Asked before the writer ends the session: the question is the
+ // same one, put to the rows as they are.
+ let reader_says_substantive = runtime
+ .block_on(reader.session_has_substantive_observation(session))
+ .unwrap();
+ let writer_says_substantive = matches!(
+ end_lifecycle_only_session(&mut conn, &session).unwrap(),
+ LifecycleOnlyEndOutcome::Substantive
+ );
+ assert_eq!(
+ reader_says_substantive, writer_says_substantive,
+ "{kind:?}: reader and writer classify the same single-row session differently"
+ );
+ }
+ }
+
#[test]
fn failed_auto_handoff_insert_rolls_back_same_cwd_expiration() {
let (_tmp, mut conn, ws, proj) = fresh_db();
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index 878a0354..8cc61304 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -2181,6 +2181,11 @@ struct Inner {
db_path: PathBuf,
pool: Mutex<Pool>,
soft_cap: usize,
+ /// Observation rows deserialized by the whole-session reads
+ /// ([`ReaderPool::observations_for_session`] and
+ /// [`ReaderPool::read_session_observations`]); see
+ /// [`ReaderPool::session_observation_rows_loaded`].
+ session_rows_loaded: std::sync::atomic::AtomicU64,
}
/// The idle connections and whether the pool still hands out new ones. One
@@ -2206,6 +2211,7 @@ impl ReaderPool {
closed: false,
}),
soft_cap: soft_cap.max(1),
+ session_rows_loaded: std::sync::atomic::AtomicU64::new(0),
}),
tuning: RetrievalTuning::default(),
fts_stopwords: FtsStopwords::default(),
@@ -2228,6 +2234,19 @@ impl ReaderPool {
pool.idle.clear();
}
+ /// Observation rows the whole-session reads have deserialized since this
+ /// pool (or any clone of it) was created: every row
+ /// [`Self::observations_for_session`] returned, plus the rows
+ /// [`Self::read_session_observations`] snapshots read. A SessionEnd on a
+ /// session far larger than its raw-observation window must move this by no
+ /// more than that window, which is what the bound tests assert.
+ #[must_use]
+ pub fn session_observation_rows_loaded(&self) -> u64 {
+ self.inner
+ .session_rows_loaded
+ .load(std::sync::atomic::Ordering::Relaxed)
+ }
+
/// Configure the opt-in ranking signals used by [`Self::hybrid_search`].
/// Only handles cloned from this one afterwards observe the change.
pub fn set_retrieval_tuning(&mut self, tuning: RetrievalTuning) {
@@ -3576,6 +3595,7 @@ impl ReaderPool {
&self,
session_id: SessionId,
) -> StoreResult<Vec<Observation>> {
+ let inner = self.inner.clone();
self.with_conn(move |conn| {
let mut stmt = conn.prepare_cached(
"SELECT id, session_id, workspace_id, project_id, kind, extension, source_event, \
@@ -3589,11 +3609,74 @@ impl ReaderPool {
for r in rows {
out.push(r??);
}
+ inner
+ .session_rows_loaded
+ .fetch_add(out.len() as u64, std::sync::atomic::Ordering::Relaxed);
Ok(out)
})
.await
}
+ /// Whether the session holds at least one prompt or tool use: the positive
+ /// "real work" predicate ([`SUBSTANTIVE_OBSERVATION_KIND_SQL`]) the writer's
+ /// lifecycle-only end applies in its own transaction, asked as one
+ /// short-circuiting existence query instead of loading the rows.
+ ///
+ /// # Errors
+ /// Propagates any SQL or pool error.
+ pub async fn session_has_substantive_observation(
+ &self,
+ session_id: SessionId,
+ ) -> StoreResult<bool> {
+ self.with_conn(move |conn| {
+ let sql = format!(
+ "SELECT EXISTS(SELECT 1 FROM observations WHERE session_id = ?1 AND {})",
+ SUBSTANTIVE_OBSERVATION_KIND_SQL
+ );
+ Ok(conn.query_row(&sql, params![session_id.as_bytes()], |row| row.get(0))?)
+ })
+ .await
+ }
+
+ /// Read one session's observations through bounded queries, all inside one
+ /// read transaction so every answer describes the same set of rows.
+ ///
+ /// This is the SessionEnd path's alternative to
+ /// [`Self::observations_for_session`]: that call deserializes every row
+ /// (a session can hold hundreds of thousands), while `read` gets a
+ /// [`SessionObservationSnapshot`] whose queries are aggregates, `LIMIT`ed
+ /// windows and streamed scans. `read` runs on a blocking thread and must
+ /// not wait on anything async.
+ ///
+ /// # Errors
+ /// Propagates any SQL or pool error, and whatever `read` returns.
+ pub async fn read_session_observations<F, T>(
+ &self,
+ session_id: SessionId,
+ read: F,
+ ) -> StoreResult<T>
+ where
+ F: FnOnce(&SessionObservationSnapshot<'_>) -> StoreResult<T> + Send + 'static,
+ T: Send + 'static,
+ {
+ let inner = self.inner.clone();
+ self.with_conn(move |conn| {
+ let tx = conn.unchecked_transaction()?;
+ let snapshot = SessionObservationSnapshot {
+ conn: &tx,
+ session_id: session_id.as_bytes().to_vec(),
+ rows_read: std::cell::Cell::new(0),
+ };
+ let result = read(&snapshot);
+ inner.session_rows_loaded.fetch_add(
+ snapshot.rows_read() as u64,
+ std::sync::atomic::Ordering::Relaxed,
+ );
+ result
+ })
+ .await
+ }
+
/// Page through one session's raw observations as seen from one scope.
///
/// Only the rows that landed in `(workspace_id, project_id)` are returned:
@@ -11814,6 +11897,342 @@ fn page_meta_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<StoreResult<P
}))
}
+/// The observations of one session, read through bounded queries inside one
+/// read transaction (see [`ReaderPool::read_session_observations`]).
+///
+/// A session can hold hundreds of thousands of rows, and the SessionEnd path
+/// only needs a handful of facts about them: counts, a few "last of a kind"
+/// markers, the rows a page prints, and the first or last row that passes a
+/// predicate. Every method here answers one of those needs with an aggregate,
+/// a `LIMIT`ed query or a streamed scan that keeps one row resident, so the
+/// memory a caller spends does not grow with the session. Every query orders
+/// rows by `created_at` and then `rowid`, which is the order
+/// [`ReaderPool::observations_for_session`] returns them in (the
+/// `(session_id, created_at)` index carries the rowid as its last key).
+pub struct SessionObservationSnapshot<'c> {
+ conn: &'c Connection,
+ session_id: Vec<u8>,
+ rows_read: std::cell::Cell<usize>,
+}
+
+/// Counts and "last of a kind" markers for one session, from one aggregate
+/// pass. A `*_at` field is the newest `created_at` of that kind (microseconds
+/// since the epoch), which is enough to seek straight to the row with an
+/// indexed `created_at <= ?` range instead of walking the session.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct SessionKindSummary {
+ /// Every row of the session.
+ pub total: usize,
+ /// User prompts.
+ pub prompts: usize,
+ /// At least one prompt or tool use: the positive "real work" predicate
+ /// [`SUBSTANTIVE_OBSERVATION_KIND_SQL`] also gives the writer.
+ pub substantive: bool,
+ /// Newest `session-start`.
+ pub last_session_start_at: Option<i64>,
+ /// Newest `session-end`.
+ pub last_session_end_at: Option<i64>,
+ /// Newest `stop`.
+ pub last_stop_at: Option<i64>,
+ /// Newest `stop` whose body is not the empty string.
+ pub last_stop_with_body_at: Option<i64>,
+ /// Newest `post-tool-use`.
+ pub last_post_tool_at: Option<i64>,
+ /// Newest `user-prompt`.
+ pub last_prompt_at: Option<i64>,
+}
+
+/// Tool names a session used, grouped in SQL.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct SessionToolTitles {
+ /// Completed calls (`post-tool-use`) per non-empty title.
+ pub completed: Vec<(String, usize)>,
+ /// Every distinct non-empty title carried by a `pre-tool-use` or
+ /// `post-tool-use` row.
+ pub titles: Vec<String>,
+}
+
+/// A user prompt's title, plus its body when the caller asked for it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SessionPromptTitle {
+ /// The prompt's stored title.
+ pub title: String,
+ /// The body, loaded only for a title containing the `body_for_titles_like`
+ /// marker the caller passed (a superset the caller filters exactly).
+ pub body: Option<String>,
+}
+
+/// What a page prints about one observation, without the body.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SessionLine {
+ /// Event classification.
+ pub kind: ObservationKind,
+ /// Extension namespace, if any.
+ pub extension: Option<String>,
+ /// Source event name, if any.
+ pub source_event: Option<String>,
+ /// The first [`SESSION_LINE_TITLE_CHARS`] characters of the title.
+ pub title: String,
+ /// When the observation happened.
+ pub created_at: Timestamp,
+}
+
+/// Title characters a [`SessionLine`] keeps.
+pub const SESSION_LINE_TITLE_CHARS: usize = 80;
+
+/// The kinds that make a session worth a summary page: a user prompt or a tool
+/// use. The writer's lifecycle-only end
+/// (`end_lifecycle_only_session_in_tx`) and the reader's
+/// [`SessionKindSummary::substantive`] both build their query from this one
+/// predicate, and the router's `is_ephemeral_session` is its Rust twin (a test
+/// pins the three together).
+pub const SUBSTANTIVE_OBSERVATION_KIND_SQL: &str =
+ "kind IN ('user-prompt', 'pre-tool-use', 'post-tool-use')";
+
+impl SessionObservationSnapshot<'_> {
+ /// Rows this snapshot has deserialized into an [`Observation`] or a
+ /// [`SessionLine`] so far. Aggregates and the prompt-title projection are
+ /// not counted: they return counters and strings, not rows.
+ #[must_use]
+ pub fn rows_read(&self) -> usize {
+ self.rows_read.get()
+ }
+
+ /// Counts and newest-of-kind markers in one pass over the session.
+ ///
+ /// # Errors
+ /// Propagates any SQL error.
+ pub fn kind_summary(&self) -> StoreResult<SessionKindSummary> {
+ let sql = format!(
+ "SELECT COUNT(*), \
+ COALESCE(SUM(kind = ?2), 0), \
+ COALESCE(MAX({SUBSTANTIVE_OBSERVATION_KIND_SQL}), 0), \
+ MAX(CASE WHEN kind = ?3 THEN created_at END), \
+ MAX(CASE WHEN kind = ?4 THEN created_at END), \
+ MAX(CASE WHEN kind = ?5 THEN created_at END), \
+ MAX(CASE WHEN kind = ?5 AND body <> '' THEN created_at END), \
+ MAX(CASE WHEN kind = ?6 THEN created_at END), \
+ MAX(CASE WHEN kind = ?2 THEN created_at END) \
+ FROM observations WHERE session_id = ?1"
+ );
+ let summary = self.conn.query_row(
+ &sql,
+ params![
+ self.session_id,
+ ObservationKind::UserPrompt.as_str(),
+ ObservationKind::SessionStart.as_str(),
+ ObservationKind::SessionEnd.as_str(),
+ ObservationKind::Stop.as_str(),
+ ObservationKind::PostToolUse.as_str(),
+ ],
+ |row| {
+ Ok(SessionKindSummary {
+ total: usize::try_from(row.get::<_, i64>(0)?).unwrap_or(usize::MAX),
+ prompts: usize::try_from(row.get::<_, i64>(1)?).unwrap_or(usize::MAX),
+ substantive: row.get::<_, i64>(2)? != 0,
+ last_session_start_at: row.get(3)?,
+ last_session_end_at: row.get(4)?,
+ last_stop_at: row.get(5)?,
+ last_stop_with_body_at: row.get(6)?,
+ last_post_tool_at: row.get(7)?,
+ last_prompt_at: row.get(8)?,
+ })
+ },
+ )?;
+ Ok(summary)
+ }
+
+ /// The tool names the session used, grouped in SQL.
+ ///
+ /// # Errors
+ /// Propagates any SQL error.
+ pub fn tool_titles(&self) -> StoreResult<SessionToolTitles> {
+ let mut stmt = self.conn.prepare_cached(
+ "SELECT kind, title, COUNT(*) FROM observations \
+ WHERE session_id = ?1 AND kind IN (?2, ?3) AND title <> '' \
+ GROUP BY kind, title",
+ )?;
+ let rows = stmt.query_map(
+ params![
+ self.session_id,
+ ObservationKind::PreToolUse.as_str(),
+ ObservationKind::PostToolUse.as_str(),
+ ],
+ |row| {
+ Ok((
+ row.get::<_, String>(0)?,
+ row.get::<_, String>(1)?,
+ row.get::<_, i64>(2)?,
+ ))
+ },
+ )?;
+ let mut out = SessionToolTitles::default();
+ let mut titles = std::collections::BTreeSet::new();
+ for row in rows {
+ let (kind, title, count) = row?;
+ if kind == ObservationKind::PostToolUse.as_str() {
+ out.completed
+ .push((title.clone(), usize::try_from(count).unwrap_or(usize::MAX)));
+ }
+ titles.insert(title);
+ }
+ out.titles = titles.into_iter().collect();
+ Ok(out)
+ }
+
+ /// Every user prompt's title in capture order, with the body only for a
+ /// title that contains `body_for_titles_like`.
+ ///
+ /// The titles are the one part of a SessionEnd that grows with the
+ /// session: the page it renders lists each of them, so the output cannot
+ /// be smaller than this. A title is short by construction (the router
+ /// truncates it for display); the bodies, which are not, stay in the
+ /// database.
+ ///
+ /// # Errors
+ /// Propagates any SQL error.
+ pub fn prompt_titles(
+ &self,
+ body_for_titles_like: &str,
+ ) -> StoreResult<Vec<SessionPromptTitle>> {
+ let mut stmt = self.conn.prepare_cached(
+ "SELECT title, CASE WHEN instr(title, ?3) > 0 THEN body END \
+ FROM observations \
+ WHERE session_id = ?1 AND kind = ?2 \
+ ORDER BY created_at ASC, rowid ASC",
+ )?;
+ let rows = stmt.query_map(
+ params![
+ self.session_id,
+ ObservationKind::UserPrompt.as_str(),
+ body_for_titles_like,
+ ],
+ |row| {
+ Ok(SessionPromptTitle {
+ title: row.get(0)?,
+ body: row.get(1)?,
+ })
+ },
+ )?;
+ let mut out = Vec::new();
+ for row in rows {
+ out.push(row?);
+ }
+ Ok(out)
+ }
+
+ /// The first `limit` rows of the session, oldest first, as page lines.
+ ///
+ /// # Errors
+ /// Propagates any SQL error.
+ pub fn first_lines(&self, limit: usize) -> StoreResult<Vec<SessionLine>> {
+ self.lines(limit, ObservationOrder::Asc)
+ }
+
+ /// The last `limit` rows of the session, oldest first, as page lines.
+ ///
+ /// # Errors
+ /// Propagates any SQL error.
+ pub fn last_lines(&self, limit: usize) -> StoreResult<Vec<SessionLine>> {
+ let mut lines = self.lines(limit, ObservationOrder::Desc)?;
+ lines.reverse();
+ Ok(lines)
+ }
+
+ fn lines(&self, limit: usize, order: ObservationOrder) -> StoreResult<Vec<SessionLine>> {
+ let direction = match order {
+ ObservationOrder::Asc => "ASC",
+ ObservationOrder::Desc => "DESC",
+ };
+ let sql = format!(
+ "SELECT kind, extension, source_event, substr(title, 1, ?3), created_at \
+ FROM observations WHERE session_id = ?1 \
+ ORDER BY created_at {direction}, rowid {direction} LIMIT ?2"
+ );
+ let mut stmt = self.conn.prepare_cached(&sql)?;
+ let mut rows = stmt.query(params![
+ self.session_id,
+ i64::try_from(limit).unwrap_or(i64::MAX),
+ i64::try_from(SESSION_LINE_TITLE_CHARS).unwrap_or(80),
+ ])?;
+ let mut out = Vec::new();
+ while let Some(row) = rows.next()? {
+ let kind_str: String = row.get(0)?;
+ let created_us: i64 = row.get(4)?;
+ out.push(SessionLine {
+ kind: kind_str
+ .parse::<ObservationKind>()
+ .map_err(StoreError::from)?,
+ extension: row.get(1)?,
+ source_event: row.get(2)?,
+ title: row.get(3)?,
+ created_at: Timestamp::from_microsecond(created_us).map_err(|e| {
+ StoreError::Memory(ai_memory_core::MemoryError::MalformedRecord(format!(
+ "bad timestamp: {e}"
+ )))
+ })?,
+ });
+ self.rows_read.set(self.rows_read.get() + 1);
+ }
+ Ok(out)
+ }
+
+ /// Walk the session's rows in `order`, one resident at a time, and return
+ /// the first value `visit` produces.
+ ///
+ /// `kinds` restricts the walk to those kinds (empty = every kind) and
+ /// `at_or_before` starts it at an indexed `created_at` bound, which is how
+ /// a caller that already knows the newest row of a kind (from
+ /// [`Self::kind_summary`]) lands on it without walking the rows after it.
+ /// The walk ends at the first `Some`, so a predicate that accepts early
+ /// reads a handful of rows; one that never accepts walks the session, but
+ /// still keeps a single row in memory.
+ ///
+ /// # Errors
+ /// Propagates any SQL error.
+ pub fn scan<T>(
+ &self,
+ order: ObservationOrder,
+ kinds: &[ObservationKind],
+ at_or_before: Option<i64>,
+ mut visit: impl FnMut(&Observation) -> Option<T>,
+ ) -> StoreResult<Option<T>> {
+ let direction = match order {
+ ObservationOrder::Asc => "ASC",
+ ObservationOrder::Desc => "DESC",
+ };
+ let mut sql = String::from(
+ "SELECT id, session_id, workspace_id, project_id, kind, extension, source_event, \
+ title, body, importance, created_at \
+ FROM observations WHERE session_id = ?",
+ );
+ let mut sql_params: Vec<Value> = vec![Value::Blob(self.session_id.clone())];
+ if let Some(bound) = at_or_before {
+ sql.push_str(" AND created_at <= ?");
+ sql_params.push(Value::Integer(bound));
+ }
+ if !kinds.is_empty() {
+ sql.push_str(" AND kind IN (");
+ for (i, kind) in kinds.iter().enumerate() {
+ sql.push_str(if i == 0 { "?" } else { ", ?" });
+ sql_params.push(Value::Text(kind.as_str().to_string()));
+ }
+ sql.push(')');
+ }
+ let _ = write!(sql, " ORDER BY created_at {direction}, rowid {direction}");
+ let mut stmt = self.conn.prepare_cached(&sql)?;
+ let mut rows = stmt.query(params_from_iter(sql_params))?;
+ while let Some(row) = rows.next()? {
+ let observation = row_to_observation(row)??;
+ self.rows_read.set(self.rows_read.get() + 1);
+ if let Some(found) = visit(&observation) {
+ return Ok(Some(found));
+ }
+ }
+ Ok(None)
+ }
+}
+
fn row_to_observation(row: &rusqlite::Row<'_>) -> rusqlite::Result<StoreResult<Observation>> {
let id_bytes: Vec<u8> = row.get(0)?;
let session_bytes: Vec<u8> = row.get(1)?;