Skip to content

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

Rust

fix(hooks): deliver the pending handoff on a managed SessionStart

Welington06b20999af3e
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index 5b07dd24..0e0a20ae 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -1083,48 +1083,14 @@ async fn fetch_and_accept_handoff(
actor_user: Option<String>,
) -> anyhow::Result<Option<String>> {
let agent = query.agent.as_deref().map_or(AgentKind::Other, parse_agent);
- if let Some(raw_run_id) = query.managed_run.as_deref() {
- let Ok(run_id) = ManagedRunId::from_str(raw_run_id) else {
- warn!(managed_run = %raw_run_id, "invalid managed run id on SessionStart");
- return Ok(None);
- };
- if let Some(native_session_id) = query
- .session_id
- .as_deref()
- .filter(|value| !value.trim().is_empty())
- {
- let _ = state
- .writer
- .link_managed_run_session(run_id, agent, native_session_id)
- .await?;
- }
- let Some(context) = state.reader.managed_run_context(run_id, 256).await? else {
- warn!(managed_run = %run_id, "managed SessionStart has no active run");
- return Ok(None);
- };
- if context.agent != agent {
- warn!(
- managed_run = %run_id,
- expected = %context.agent.as_str(),
- actual = %agent.as_str(),
- "managed SessionStart agent mismatch"
- );
- return Ok(None);
- }
- let brief_md =
- resolve_requested_session_brief(state, &query, actor_user.as_deref()).await?;
- if context.context_delivered {
- return Ok(brief_md);
- }
- let rendered = render_managed_context(
- &context.events,
- &context.workstream_name,
- context.workstream_id,
- context.sync_after,
- );
- let _ = state.writer.accept_managed_run_context(run_id).await?;
- return Ok(combine_handoff_and_brief(rendered, brief_md));
- }
+ // A managed run's ledger is additive, not a replacement. Returning it here
+ // skipped `latest_open_handoff` below, so a session launched by
+ // `ai-memory run` never consumed the handoff a previous session left for
+ // it — the slot just stayed open, and the next managed session missed it
+ // too. The brief already reaches the managed path (it is recomposed per
+ // session, so resolving it twice was harmless); the handoff is single-use
+ // and had no second chance.
+ let managed_md = fetch_managed_context(state, &query, agent).await?;
// `/handoff` has no session_id in the request — `per_session` mode
// therefore falls back to the single slot (graceful degradation),
// while `per_actor` keys by `user` alone.
@@ -1161,32 +1127,67 @@ async fn fetch_and_accept_handoff(
// single-use slot consumed above), it is recomposed on every opted-in
// session start — exactly what a Claude Code `/clear` needs (#176).
let brief_md = render_requested_session_brief(state, &query, ws, proj).await?;
- Ok(combine_handoff_and_brief(handoff_md, brief_md))
+ // Handoff first: it is a short curated pointer and must not be buried
+ // under a ledger that can run tens of KB. The existing ledger-then-brief
+ // order is preserved.
+ Ok(combine_handoff_and_brief(
+ handoff_md,
+ combine_handoff_and_brief(managed_md, brief_md),
+ ))
}
-async fn resolve_requested_session_brief(
+/// Render the managed-run ledger for this SessionStart, if there is one.
+///
+/// Returns `None` — never an early exit for the caller — when the run is
+/// unusable (bad id, no active run, agent mismatch) or its context was
+/// already delivered. The pending handoff still has to reach the agent in
+/// every one of those cases.
+async fn fetch_managed_context(
state: &HookState,
query: &HandoffQuery,
- actor_user: Option<&str>,
+ agent: AgentKind,
) -> anyhow::Result<Option<String>> {
- if !crate::payload::query_flag_truthy(query.briefing.as_deref()) {
+ let Some(raw_run_id) = query.managed_run.as_deref() else {
+ return Ok(None);
+ };
+ let Ok(run_id) = ManagedRunId::from_str(raw_run_id) else {
+ warn!(managed_run = %raw_run_id, "invalid managed run id on SessionStart");
return Ok(None);
+ };
+ if let Some(native_session_id) = query
+ .session_id
+ .as_deref()
+ .filter(|value| !value.trim().is_empty())
+ {
+ let _ = state
+ .writer
+ .link_managed_run_session(run_id, agent, native_session_id)
+ .await?;
}
- let actor_key = ai_memory_core::ActorKey {
- user: actor_user.map(str::to_owned),
- session_id: None,
+ let Some(context) = state.reader.managed_run_context(run_id, 256).await? else {
+ warn!(managed_run = %run_id, "managed SessionStart has no active run");
+ return Ok(None);
};
- let (ws, proj) = resolve_project_ids_inner(
- state,
- query.cwd.as_deref(),
- query.workspace.as_deref(),
- query.project.as_deref(),
- ProjectStrategy::parse(query.project_strategy.as_deref()),
- &actor_key,
- false,
- )
- .await?;
- render_requested_session_brief(state, query, ws, proj).await
+ if context.agent != agent {
+ warn!(
+ managed_run = %run_id,
+ expected = %context.agent.as_str(),
+ actual = %agent.as_str(),
+ "managed SessionStart agent mismatch"
+ );
+ return Ok(None);
+ }
+ if context.context_delivered {
+ return Ok(None);
+ }
+ let rendered = render_managed_context(
+ &context.events,
+ &context.workstream_name,
+ context.workstream_id,
+ context.sync_after,
+ );
+ let _ = state.writer.accept_managed_run_context(run_id).await?;
+ Ok(rendered)
}
async fn render_requested_session_brief(
@@ -5649,6 +5650,114 @@ mod tests {
);
}
+ #[tokio::test]
+ async fn managed_session_start_delivers_ledger_and_pending_handoff() {
+ use ai_memory_core::{NewWorkstreamEvent, WorkstreamEventKind};
+ use ai_memory_store::{FinishWorkstreamRun, PrepareWorkstreamRun, WorkstreamSelection};
+
+ let tmp = TempDir::new().unwrap();
+ let state = make_state(&tmp).await;
+ let cwd = tmp.path().to_string_lossy().into_owned();
+
+ let prepare = PrepareWorkstreamRun {
+ workspace_id: state.workspace_id,
+ project_id: state.project_id,
+ repo_fingerprint: "repo".into(),
+ worktree_fingerprint: "worktree".into(),
+ cwd: cwd.clone(),
+ agent: AgentKind::Codex,
+ automatic_harness: false,
+ available_agents: Vec::new(),
+ selection: WorkstreamSelection::Current,
+ lease_owner: "test:1".into(),
+ };
+ // First run: nothing to replay, but it leaves a portable event behind.
+ let first = state
+ .writer
+ .prepare_workstream_run(prepare.clone())
+ .await
+ .unwrap();
+ state
+ .writer
+ .finish_workstream_run(FinishWorkstreamRun {
+ run_id: first.run_id,
+ native_session_id: Some("native-1".into()),
+ source_cursor: Some("cursor-1".into()),
+ events: vec![NewWorkstreamEvent {
+ event_id: "event-1".into(),
+ agent: AgentKind::Codex,
+ native_session_id: "native-1".into(),
+ source_record_id: Some("record-1".into()),
+ kind: WorkstreamEventKind::Message,
+ role: Some("assistant".into()),
+ content: "LEDGER-MARKER".into(),
+ occurred_at: None,
+ metadata: serde_json::json!({}),
+ }],
+ complete: true,
+ segment_path: Some("segment-1.jsonl".into()),
+ exit_code: Some(0),
+ })
+ .await
+ .unwrap();
+ // Second run: this is the SessionStart that has a ledger to deliver.
+ let run = state.writer.prepare_workstream_run(prepare).await.unwrap();
+
+ state
+ .writer
+ .insert_handoff(NewHandoff {
+ workspace_id: state.workspace_id,
+ project_id: state.project_id,
+ from_session_id: None,
+ from_agent: AgentKind::ClaudeCode,
+ to_agent: None,
+ cwd: None,
+ summary: "HANDOFF-MARKER".to_string(),
+ open_questions: Vec::new(),
+ next_steps: vec!["resume the curated thread".to_string()],
+ files_touched: Vec::new(),
+ })
+ .await
+ .unwrap();
+
+ let rendered = fetch_and_accept_handoff(
+ &state,
+ HandoffQuery {
+ agent: Some("codex".into()),
+ cwd: Some(cwd),
+ workspace: Some("default".into()),
+ project: Some("scratch".into()),
+ project_strategy: None,
+ briefing: None,
+ briefing_budget: None,
+ managed_run: Some(run.run_id.to_string()),
+ session_id: Some("native-2".into()),
+ },
+ None,
+ )
+ .await
+ .unwrap();
+
+ let rendered = rendered.expect("managed SessionStart must return context");
+ assert!(
+ rendered.contains("LEDGER-MARKER"),
+ "managed SessionStart must still deliver the workstream ledger: {rendered}"
+ );
+ assert!(
+ rendered.contains("HANDOFF-MARKER"),
+ "the managed ledger must not swallow the pending handoff: {rendered}"
+ );
+ assert!(
+ state
+ .reader
+ .latest_open_handoff(state.workspace_id, state.project_id, None)
+ .await
+ .unwrap()
+ .is_none(),
+ "a handoff delivered on a managed SessionStart must be marked accepted"
+ );
+ }
+
fn brief_page(
ws: ai_memory_core::WorkspaceId,
proj: ai_memory_core::ProjectId,