Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(mcp): route opencode tool calls by their native _meta session id
João Carlos Magalhães5af282b2faeb
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 653feca1..a3b4e28b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -80,6 +80,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0(not bare JSON 401), forms call existing `POST /auth/login` /`/auth/password` / `/auth/logout`, and `--web-ui-dir` custom SPAs stayunchanged. (#811)+- MCP tool calls from OpenCode 2 (2.0.4+) are routed by the native session id+ the client sends in `params._meta["ai.opencode/sessionID"]`, ahead of the+ `Mcp-Session-Id` transport header, which OpenCode shares across every+ session in a directory. Concurrent OpenCode sessions in different projects+ no longer read each other's active project; explicit `workspace`/`project`+ arguments still win and `X-Memory-Actor-Session-Id` keeps precedence. (#864)### Changed- Grok Build CLI shows a pending handoff, and an opted-in `[briefing]`, asdiff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 44539bce..89b011a9 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -1768,8 +1768,12 @@ impl AiMemoryServer {/// raw client-supplied headers./// - `session_id` comes from the same `ActorContext` when the auth/// middleware filled it; if not, falls back to the rung-4- /// `X-Memory-Actor-Session-Id` request header, then to the standard- /// MCP `Mcp-Session-Id` header. The session id is just a cache key+ /// `X-Memory-Actor-Session-Id` request header, then native request+ /// `_meta["ai.opencode/sessionID"]`, then the transport's+ /// `Mcp-Session-Id` header. The native id matches lifecycle hooks; a+ /// transport id does not, and only `--http-stateful` issues one (the+ /// default stateless transport never does, so clients send none).+ /// The session id is just a cache key/// for the active-project map — getting it wrong only routes the/// lookup to a different (or absent) slot, with no auth-bypass risk,/// so trusting the header here is safe.@@ -1804,6 +1808,12 @@ impl AiMemoryServer {let session_id = ctx.and_then(|c| c.session_id.clone()).or_else(|| header_session("x-memory-actor-session-id"))+ .or_else(|| {+ parts+ .extensions+ .get::<NativeSessionId>()+ .map(|id| id.0.clone())+ }).or_else(|| header_session("mcp-session-id"));ai_memory_core::ActorKey { user, session_id }}@@ -5087,8 +5097,10 @@ impl ServerHandler for AiMemoryServer {async fn call_tool(&self,request: rmcp::model::CallToolRequestParams,- context: rmcp::service::RequestContext<RoleServer>,+ mut context: rmcp::service::RequestContext<RoleServer>,) -> Result<rmcp::model::CallToolResult, McpError> {+ // rmcp moves params._meta into RequestContext before dispatch.+ attach_native_session(&mut context.extensions, &context.meta);self.record_client_activity(&request.name, &context);let tcc = rmcp::handler::server::tool::ToolCallContext::new(self, request, context);self.tool_router.call(tcc).await@@ -5664,6 +5676,29 @@ fn default_parts() -> axum::http::request::Parts {request.into_parts().0}+/// Routing-only native identity; never populate authenticated actor extensions+/// from client metadata. Keep it request-local even on shared MCP transports.+#[derive(Clone)]+struct NativeSessionId(String);++fn attach_native_session(extensions: &mut rmcp::model::Extensions, meta: &rmcp::model::Meta) {+ // OpenCode 2 (2.0.4+) sends this on every tools/call, never on+ // initialize. Its transport session is shared per (server, directory).+ let Some(session_id) = meta+ .get("ai.opencode/sessionID")+ .and_then(serde_json::Value::as_str)+ .map(str::trim)+ .filter(|id| !id.is_empty())+ else {+ return;+ };+ let OptionalParts(mut parts) = OptionalParts::from_extensions(extensions);+ parts+ .extensions+ .insert(NativeSessionId(session_id.to_owned()));+ extensions.insert(parts);+}+/// Tool-handler extractor for the request `Parts`. Unlike rmcp's/// `Extension<Parts>` — which fails every `tools/call` with "missing extension/// http::request::Parts" when the extension is absent — this yields the real@@ -6370,6 +6405,86 @@ mod tests {assert_eq!(actor.session_id.as_deref(), Some("hook-session"));}+ #[test]+ fn native_session_metadata_is_routing_only_and_preserves_precedence() {+ let native = serde_json::json!({"ai.opencode/sessionID": " native-session "});+ let other_native = serde_json::json!({"ai.opencode/sessionID": "other-native"});+ // `sessionID` is not an OpenCode key, so the transport id wins.+ let alias = serde_json::json!({"sessionID": "alias-session"});+ let none = serde_json::json!({});+ for (context_session, header_session, meta, expected) in [+ (None, None, &native, "native-session"),+ // Same shared transport, another native session: another slot.+ (None, None, &other_native, "other-native"),+ (None, None, &alias, "transport-session"),+ (None, None, &none, "transport-session"),+ (None, Some("header-session"), &native, "header-session"),+ (+ Some("context-session"),+ Some("header-session"),+ &native,+ "context-session",+ ),+ ] {+ let mut parts = test_parts_default();+ parts+ .headers+ .insert("mcp-session-id", "transport-session".parse().unwrap());+ if let Some(session) = header_session {+ parts+ .headers+ .insert("x-memory-actor-session-id", session.parse().unwrap());+ }+ parts.extensions.insert(AuthLevel::User);+ parts.extensions.insert(ActorContext {+ user: Some("alice".into()),+ session_id: context_session.map(str::to_owned),+ ..ActorContext::default()+ });+ let mut extensions = rmcp::model::Extensions::new();+ extensions.insert(parts);+ let mut meta = meta.clone();+ meta["user"] = "root".into();+ meta["auth"] = "root".into();+ let meta = serde_json::from_value(meta).unwrap();+ attach_native_session(&mut extensions, &meta);+ let OptionalParts(parts) = OptionalParts::from_extensions(&extensions);+ let actor = AiMemoryServer::actor_key_from_parts(Some(&parts));+ assert_eq!(actor.user.as_deref(), Some("user:alice"));+ assert_eq!(actor.session_id.as_deref(), Some(expected));+ assert_eq!(parts.extensions.get::<AuthLevel>(), Some(&AuthLevel::User));+ }+ }++ #[test]+ fn native_session_metadata_validates_strings_without_granting_identity() {+ for value in [+ serde_json::Value::Null,+ serde_json::json!(42),+ serde_json::json!({}),+ serde_json::json!([]),+ serde_json::json!(true),+ serde_json::json!(" \t "),+ serde_json::json!(" ses_native "),+ ] {+ let mut extensions = rmcp::model::Extensions::new();+ let meta = serde_json::from_value(+ serde_json::json!({"ai.opencode/sessionID": value, "user": "root"}),+ )+ .unwrap();+ attach_native_session(&mut extensions, &meta);+ let OptionalParts(parts) = OptionalParts::from_extensions(&extensions);+ let actor = AiMemoryServer::actor_key_from_parts(Some(&parts));+ assert_eq!(actor.user, None);+ assert_eq!(+ actor.session_id.as_deref(),+ value.as_str().map(str::trim).filter(|id| !id.is_empty())+ );+ assert!(parts.extensions.get::<ActorContext>().is_none());+ assert!(parts.extensions.get::<AuthLevel>().is_none());+ }+ }+#[test]fn actor_key_accepts_standard_mcp_session_header() {let mut parts = test_parts_default();diff --git a/crates/ai-memory-mcp/tests/suite/autoscope_multiuser.rs b/crates/ai-memory-mcp/tests/suite/autoscope_multiuser.rsindex 517349f9..ba681fd6 100644--- a/crates/ai-memory-mcp/tests/suite/autoscope_multiuser.rs+++ b/crates/ai-memory-mcp/tests/suite/autoscope_multiuser.rs@@ -354,6 +354,163 @@ async fn fire_hook_and_settle(h: &MultiUserHarness, token: &str, session_id: &st.expect("hook processing must release its harness permit");}+async fn native_call(+ router: &Router,+ token: &str,+ session: Option<&str>,+ name: &str,+ arguments: serde_json::Value,+) -> String {+ // The wire shape OpenCode 2 (2.0.4+) sends on every tools/call, Code+ // Mode included. Every native session in one directory shares a single+ // transport session, so the header below is the same for all of them.+ let mut params = json!({"name": name, "arguments": arguments});+ if let Some(session) = session {+ params["_meta"] = json!({"ai.opencode/sessionID": session});+ }+ let request = Request::builder()+ .method("POST")+ .uri("/mcp")+ .header("host", "localhost")+ .header("content-type", "application/json")+ .header("accept", "application/json, text/event-stream")+ .header("authorization", format!("Bearer {token}"))+ // A transport session must not mask the native lifecycle coordinate.+ .header("mcp-session-id", "shared-transport")+ .body(Body::from(+ json!({"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": params})+ .to_string(),+ ))+ .unwrap();+ let response = router.clone().oneshot(request).await.unwrap();+ assert_eq!(response.status(), StatusCode::OK);+ response_text(response).await+}++async fn native_tool(+ router: &Router,+ token: &str,+ session: &str,+ name: &str,+ arguments: serde_json::Value,+) -> String {+ let body = native_call(router, token, Some(session), name, arguments).await;+ let envelope: serde_json::Value = serde_json::from_str(&body).unwrap();+ assert_ne!(+ envelope.pointer("/result/isError"),+ Some(&json!(true)),+ "{body}"+ );+ tool_text(&body)+}++#[tokio::test(flavor = "multi_thread", worker_threads = 2)]+async fn native_metadata_routes_concurrent_reads_and_writes_to_hook_workspaces() {+ let h = MultiUserHarness::build(2).await;+ // One authenticated operator, two native sessions: user identity alone+ // cannot isolate their current projects (invariant #16).+ let token = &h.users[0].token;+ let sessions = ["ses_native_alpha", "ses_native_beta"];+ let workspaces = ["native-alpha", "native-beta"];+ for (session, workspace) in sessions.iter().zip(workspaces) {+ let mut request = hook_request(token, session, "shared");+ *request.uri_mut() = format!(+ "/hook?event=session-start&agent=opencode2&workspace={workspace}&project=shared"+ )+ .parse()+ .unwrap();+ let response = h.router.clone().oneshot(request).await.unwrap();+ assert_eq!(response.status(), StatusCode::ACCEPTED);+ tokio::time::timeout(Duration::from_secs(5), async {+ while h.ingest_semaphore.available_permits() != 1 {+ tokio::task::yield_now().await;+ }+ })+ .await+ .unwrap();+ }+ let write = |session, marker| {+ native_tool(+ &h.router,+ token,+ session,+ "memory_write_page",+ json!({+ "path": "native.md", "title": "Native routing", "body": marker+ }),+ )+ };+ tokio::join!(+ write(sessions[0], "native alpha evidence"),+ write(sessions[1], "native beta evidence")+ );+ let read = |session| {+ native_tool(+ &h.router,+ token,+ session,+ "memory_read_page",+ json!({"path": "native.md"}),+ )+ };+ let (alpha, beta) = tokio::join!(read(sessions[0]), read(sessions[1]));+ assert!(alpha.contains("native alpha evidence"), "{alpha}");+ assert!(!alpha.contains("native beta evidence"), "{alpha}");+ assert!(beta.contains("native beta evidence"), "{beta}");+ assert!(!beta.contains("native alpha evidence"), "{beta}");++ // Explicit scope remains authoritative, and pages remain shared with+ // another operator rather than being filtered by their author's identity.+ let shared = native_tool(+ &h.router,+ &h.users[1].token,+ sessions[1],+ "memory_read_page",+ json!({+ "workspace": workspaces[0], "project": "shared", "path": "native.md"+ }),+ )+ .await;+ assert!(shared.contains("native alpha evidence"), "{shared}");+ native_tool(+ &h.router,+ token,+ sessions[1],+ "memory_write_page",+ json!({+ "workspace": workspaces[0], "project": "shared", "path": "override.md",+ "title": "Explicit override", "body": "written into alpha"+ }),+ )+ .await;+ let overridden = native_tool(+ &h.router,+ token,+ sessions[0],+ "memory_read_page",+ json!({"path": "override.md"}),+ )+ .await;+ assert!(overridden.contains("written into alpha"), "{overridden}");+ // The override must not mutate beta's active pointer.+ assert!(read(sessions[1]).await.contains("native beta evidence"));++ // Without `_meta` the shared transport id is the only coordinate and it+ // names no hook session, so the call must not follow the last hook.+ let unrouted = native_call(+ &h.router,+ token,+ None,+ "memory_write_page",+ json!({"path": "unrouted.md", "title": "Unrouted", "body": "no native id"}),+ )+ .await;+ assert!(+ unrouted.contains("active-project pointer does not match this caller"),+ "{unrouted}"+ );+}+// ────────────────────────────────────────────────────────────────────────────// Each user, authenticated by their real Bearer token, hooks their own// project; concurrent reads must resolve into their OWN slot, never any