snipara-companion 3.2.27 → 3.2.28

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## New In 3.2.28
+
+- Adds bounded Outcome Loop retrieval correlation to generated Codex, Claude,
+  Cursor, VS Code/Continue, and generic HTTP MCP references through
+  `SNIPARA_SESSION_ID` / `X-Snipara-Session-Id`.
+- Prints the active correlation session during `init` and documents the
+  explicit `correlation_context.session_id` fallback for MCP clients that
+  cannot inject environment-backed headers.
+- Keeps the correlation identifier telemetry-only and project-scoped; it does
+  not alter authentication or authorization.
+
 ## New In 3.2.27
 
 - Scopes `context-control drift` dirty Git detection to the ProjectContext

package/README.md

@@ -49,6 +49,18 @@ Use this after `create-snipara` activation. `create-snipara` remains the
 canonical engine for first workspace setup; Companion owns the repeatable local
 continuity loop after that.
 
+## Retrieval And Outcome Correlation
+
+`snipara-companion init` creates and prints a bounded workspace session ID.
+Export it as `SNIPARA_SESSION_ID` before starting Codex, Claude, Cursor, VS Code,
+Continue, or another HTTP MCP client. Generated configs forward it as
+`X-Snipara-Session-Id`, while canonical execution events use the same Companion
+session automatically. Clients without environment-backed headers can pass the
+same value as `correlation_context.session_id` on retrieval tools.
+
+The identifier is opaque, project-scoped telemetry. It does not grant access or
+change authorization, and explicit per-call correlation remains authoritative.
+
 Example output excerpt:
 
 ```text

package/dist/index.js

@@ -5641,6 +5641,7 @@ Claude Code should apply this workflow automatically for project-specific work;
 
 - Bound Snipara project: \`${projectSlug}\`
 - Hosted MCP endpoint: \`${buildHostedMcpEndpoint(projectSlug)}\`
+- Keep \`SNIPARA_SESSION_ID\` equal to the active Companion session. Generated MCP configs send it as \`X-Snipara-Session-Id\`; when a client cannot send that header, pass the same value as \`correlation_context.session_id\` on retrieval tools.
 - At the start of substantial work, validate the hosted MCP surface with a tool-oriented call, then use \`snipara_recall\` and a targeted \`snipara_context_query\` before falling back to local search.
 - Do not treat empty MCP resources/templates as an outage. If the tool surface looks incomplete, call \`snipara_help(list_all=true)\` and compare exact tool names.
 - Use \`snipara_context_query\` for docs, business context, architecture notes, runbooks, and source truth. Use \`snipara_get_chunk\` for exact cited sections when references are returned.
@@ -5660,6 +5661,7 @@ function buildSharedWorkflowInstructionBlock(projectSlug, client) {
 This workspace is bound to Snipara project \`${projectSlug}\` for ${formatClientName(client)}. Agents should use Snipara automatically for project-specific context, decisions, and workflow state.
 
 - Hosted MCP endpoint: \`${buildHostedMcpEndpoint(projectSlug)}\`
+- Keep \`SNIPARA_SESSION_ID\` equal to the active Companion session. Generated MCP configs send it as \`X-Snipara-Session-Id\`; when a client cannot send that header, pass the same value as \`correlation_context.session_id\` on retrieval tools.
 - At the start of substantial work, validate the hosted MCP surface with a tool-oriented call, then use \`snipara_recall\` and a targeted \`snipara_context_query\` before falling back to local search.
 - Do not treat empty MCP resources/templates as an outage. If the tool surface looks incomplete, call \`snipara_help(list_all=true)\` and compare exact tool names.
 - Use \`snipara_context_query\` for docs, business context, architecture notes, runbooks, and source truth. Use \`snipara_get_chunk\` for exact cited sections when references are returned.
@@ -5911,6 +5913,7 @@ function generateCodexConfigString(projectSlug) {
 type = "streamable_http"
 url = "https://api.snipara.com/mcp/${projectSlug}"
 bearer_token_env_var = "SNIPARA_API_KEY"
+env_http_headers = { "X-Snipara-Session-Id" = "SNIPARA_SESSION_ID" }
 `;
 }
 function generateGenericMcpReferenceString(client, projectSlug) {
@@ -5920,7 +5923,8 @@ function generateGenericMcpReferenceString(client, projectSlug) {
         name: "snipara",
         url: `https://api.snipara.com/mcp/${projectSlug}`,
         headers: {
-          "X-API-Key": "${SNIPARA_API_KEY}"
+          "X-API-Key": "${SNIPARA_API_KEY}",
+          "X-Snipara-Session-Id": "${SNIPARA_SESSION_ID}"
         }
       },
       null,
@@ -5935,7 +5939,8 @@ function generateGenericMcpReferenceString(client, projectSlug) {
           type: "http",
           url: `https://api.snipara.com/mcp/${projectSlug}`,
           headers: {
-            "X-API-Key": "${SNIPARA_API_KEY}"
+            "X-API-Key": "${SNIPARA_API_KEY}",
+            "X-Snipara-Session-Id": "${SNIPARA_SESSION_ID}"
           }
         }
       }
@@ -5995,6 +6000,7 @@ async function callSniparaTool(name: string, args: Record<string, unknown>): Pro
     headers: {
       "Content-Type": "application/json",
       "X-API-Key": SNIPARA_API_KEY,
+      "X-Snipara-Session-Id": process.env.SNIPARA_SESSION_ID || "",
     },
     body: JSON.stringify({
       jsonrpc: "2.0",
@@ -6561,12 +6567,13 @@ async function initCommand(options) {
     existingProjectId: existingConfig.projectId,
     selectedProject
   });
+  const sessionId = `sess_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
   saveConfig(
     {
       apiKey,
       apiUrl: existingConfig.apiUrl,
       projectId: projectIdentifier,
-      sessionId: `sess_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      sessionId,
       client: selectedClient
     },
     { cwd: projectDir, scope: "workspace" }
@@ -6688,6 +6695,10 @@ async function initCommand(options) {
   console.log(`Companion config: ${configPaths.companion}`);
   console.log(`Selected project: ${formatProjectChoice(selectedProject)}`);
   console.log(`Selected client:  ${formatClientName(selectedClient)}`);
+  console.log(`Correlation session: ${sessionId}`);
+  console.log(
+    "Export SNIPARA_SESSION_ID with this value before starting the MCP client so served context and execution outcomes share one bounded session."
+  );
   if (options.withHooks) {
     console.log("\nNext steps:");
     if (hookClient === "cursor") {

package/docs/FULL_REFERENCE.md

@@ -821,6 +821,15 @@ Mistral generates MCP-first files (`MISTRAL.md`, Vibe config, Le Chat connector
 reference, and LangChain `ChatMistralAI.bindTools` snippets); Mistral request
 hooks are model request hooks, not local agent lifecycle hooks.
 
+All generated HTTP/SSE references include a bounded correlation header sourced
+from `SNIPARA_SESSION_ID`. Set it to the session printed by `init` before
+starting Codex, Claude, Cursor, VS Code/Continue, GLM, or another generic MCP
+host. The hosted server uses the header only for project-scoped retrieval
+telemetry and ignores invalid values. If the host cannot inject environment
+headers, pass the same value as `correlation_context.session_id` on
+`snipara_context_query`, `snipara_recall`, `snipara_search`, `snipara_ask`, and
+`snipara_get_chunk`.
+
 OpenClaw hooks remain separate:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "3.2.27",
+  "version": "3.2.28",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {