Skip to content

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.md
index 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 stay
unchanged. (#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]`, as
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index 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.rs
index 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