@echomem/mcp 1.4.40 → 1.4.42

package/dist/v1-contract.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { MCP_DESKTOP_MANAGED, MCP_VAULT_UNLOCK_INSTRUCTION, MEMORY_CITATION_INSTRUCTION, SAVED_MEMORY_RECEIPT_INSTRUCTION, withMcpVersion, } from "./package-metadata.js";
 export const canonicalToolNames = {
+    bindSourceSession: "bind_source_session",
     search: "search_memories",
     save: "save_conversation",
     timeRange: "get_memories_by_time_range",
@@ -59,6 +60,7 @@ const READ_ONLY_TOOL_NAMES = new Set([
     canonicalToolNames.recompose,
 ]);
 const IDEMPOTENT_WRITE_TOOL_NAMES = new Set([
+    canonicalToolNames.bindSourceSession,
     canonicalToolNames.recordCitations,
     canonicalToolNames.setGroupSessionSharing,
     canonicalToolNames.updateGroupProfile,
@@ -77,6 +79,7 @@ const REQUIRES_USER_INTERACTION_TOOL_NAMES = new Set([
     canonicalToolNames.delete,
 ]);
 const ALWAYS_LOAD_TOOL_NAMES = new Set([
+    canonicalToolNames.bindSourceSession,
     canonicalToolNames.search,
     canonicalToolNames.save,
 ]);
@@ -162,6 +165,42 @@ const triggerMetadataSchema = {
     triggerMessage: z.string().optional(),
     triggerMessageRole: z.string().optional(),
 };
+// Canonical workspace selector for tools that act inside a company workspace.
+// `workspaceId` is the current name; `groupId` is the legacy alias kept working
+// so existing prompts keep functioning. Handlers normalize with
+// normalizeWorkspaceId (workspaceId ?? groupId). Required only when the user
+// belongs to more than one workspace; a single-workspace user may omit it.
+const WORKSPACE_SELECTOR_DESCRIPTION = "Workspace to act in. Required when the user belongs to more than one workspace; omit it when they have a single workspace. If omitted with multiple workspaces, the tool returns the available workspaces so you can ask the user which to use.";
+const workspaceSelectorSchema = {
+    workspaceId: z.string().uuid().optional().describe(WORKSPACE_SELECTOR_DESCRIPTION),
+    groupId: z.string().uuid().optional().describe("Legacy alias for workspaceId."),
+};
+// The advertised JSON-Schema counterpart of workspaceSelectorSchema. Tool
+// inputSchemas are hand-written, so the selector must be injected into every
+// workspace-scoped tool's properties or clients never learn they can pass it.
+const workspaceSelectorProperties = {
+    workspaceId: { type: "string", description: WORKSPACE_SELECTOR_DESCRIPTION },
+    groupId: { type: "string", description: "Legacy alias for workspaceId." },
+};
+const WORKSPACE_SCOPED_TOOL_NAMES = new Set([
+    canonicalToolNames.others,
+    canonicalToolNames.publicMemory,
+    canonicalToolNames.groupContext,
+    canonicalToolNames.createGroupInvite,
+    canonicalToolNames.prepareGroupPublication,
+    canonicalToolNames.updateGroupProfile,
+    canonicalToolNames.publishToGroup,
+    canonicalToolNames.publishBatchToGroup,
+]);
+function injectWorkspaceSelector(specs) {
+    for (const spec of specs) {
+        if (!WORKSPACE_SCOPED_TOOL_NAMES.has(spec.name))
+            continue;
+        const existing = spec.inputSchema.properties ?? {};
+        spec.inputSchema.properties = { ...workspaceSelectorProperties, ...existing };
+    }
+    return specs;
+}
 export const searchMemoriesSchema = z.object({
     ...triggerMetadataSchema,
     query: z.string().trim().min(1).optional(),
@@ -187,6 +226,9 @@ export const saveConversationSchema = z.object({
     }))
         .optional(),
 });
+export const bindSourceSessionSchema = z.object({
+    bindingToken: z.string().uuid(),
+});
 const dateBoundarySchema = z.string().trim().min(1).refine((value) => Number.isFinite(Date.parse(value)), "Expected an ISO-8601 date or date-time string");
 export const timeRangeSchema = z.object({
     ...triggerMetadataSchema,
@@ -229,6 +271,8 @@ export const sendFriendRequestSchema = z.object({
 });
 export const othersSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
+    scope: z.enum(["group", "friends"]).optional(),
     query: z.string().trim().optional().default(""),
     limit: z.number().int().min(1).max(50).optional().default(10),
     target: z.string().optional(),
@@ -243,6 +287,7 @@ export const othersSchema = z.object({
 });
 export const publicMemorySchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
     memoryId: z.string().min(1),
 });
 export const recordMemoryCitationsSchema = z.object({
@@ -252,6 +297,7 @@ export const recordMemoryCitationsSchema = z.object({
 });
 export const groupContextSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
 });
 export const getGroupSessionSharingSchema = z.object({
     ...triggerMetadataSchema,
@@ -276,6 +322,7 @@ export const createGroupSchema = z.object({
 });
 export const createGroupInviteSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
     expiresInDays: z.number().int().min(1).max(30).optional(),
     maxUses: z.number().int().min(1).max(100).optional(),
 });
@@ -288,6 +335,7 @@ export const joinGroupSchema = z.object({
 });
 export const prepareGroupPublicationSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
     scope: z.enum(["bootstrap", "since_last_scan", "context", "time_range"]).default("since_last_scan"),
     contextId: z.string().min(1).optional(),
     startAt: z.string().optional(),
@@ -304,6 +352,7 @@ export const flagPublicationAttentionSchema = z.object({
 });
 export const updateGroupProfileSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
     displayName: z.string().min(1).max(120).optional(),
     title: z.string().min(1).max(160),
     responsibilitySummary: z.string().min(1).max(1000),
@@ -319,11 +368,13 @@ export const completeGroupPublicationSchema = z.object({
 });
 export const publishToGroupSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
     memoryId: z.string().min(1),
     acknowledgedFlaggedMemoryIds: z.array(z.string().min(1)).max(1).optional(),
 });
 export const publishBatchToGroupSchema = z.object({
     ...triggerMetadataSchema,
+    ...workspaceSelectorSchema,
     memoryIds: z.array(z.string().min(1)).min(1).max(50),
     contextId: z.string().min(1).optional(),
     selectionReason: z.string().max(500).optional(),
@@ -403,6 +454,22 @@ export function listToolSpecs(opts = {}) {
         required: ["startDate", "endDate"],
     };
     const tools = [
+        {
+            name: canonicalToolNames.bindSourceSession,
+            title: "Bind this agent conversation to its source session",
+            description: withMcpVersion("Compatibility fallback for clients where EchoMem's automatic SessionStart binding is unavailable or reports that the session is unbound. Generate a fresh random UUID for bindingToken and pass only that token. EchoMem finds this exact tool call in the local host JSONL, derives the real provider session ID itself, and idempotently binds the authenticated backend context. Never reuse a bindingToken, guess a session ID, or copy a token between conversations. After success, later saves, recalls, citations, sharing decisions, and MCP activity from this bridge are attached to the returned context automatically. Do not call it routinely when automatic binding is active."),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    bindingToken: {
+                        type: "string",
+                        format: "uuid",
+                        description: "A fresh random UUID generated only for this invocation. The local bridge verifies it inside the current host JSONL.",
+                    },
+                },
+                required: ["bindingToken"],
+            },
+        },
         {
             name: canonicalToolNames.search,
             title: "Search your memories by topic",
@@ -551,10 +618,15 @@ export function listToolSpecs(opts = {}) {
         {
             name: canonicalToolNames.others,
             title: "Search teammates' and friends' memories",
-            description: `PEER-MEMORY SEARCH for public memories owned by accepted friends or company-group members—not the user's own memories. Pass query for a topic; omit it only when intentionally browsing peer memories, and optionally use target to scope a person. Do not use this tool for the user's private memories or the EchoMem user directory. EchoMem identifies the caller from the EchoMem credential and has already excluded only that authenticated user's own memories. Present every returned owner; never filter again using a Claude account, host profile, git identity, or inference. For onboarding and division-of-work questions, call get_group_context first. Returned memories are recorded in memory_views for the owners. ${memoryCitationInstruction}${groupMapSection}`,
+            description: `PEER-MEMORY SEARCH for public memories owned by accepted friends or company-group members—not the user's own memories. Pass query for a topic. Set scope to pick the audience — 'group' (only workspace teammates) or 'friends' (only friends) — or target for one person; scope defaults to teammates. Do not use this tool for the user's private memories or the EchoMem user directory. EchoMem identifies the caller from the EchoMem credential and has already excluded only that authenticated user's own memories. Present every returned owner; never filter again using a Claude account, host profile, git identity, or inference. For onboarding and division-of-work questions, call get_group_context first. Returned memories are recorded in memory_views for the owners. ${memoryCitationInstruction}${groupMapSection}`,
             inputSchema: {
                 type: "object",
                 properties: {
+                    scope: {
+                        type: "string",
+                        enum: ["group", "friends"],
+                        description: "Audience to search. 'group' = only the named workspace's teammates (you'll be asked which if the user is in several and names none). 'friends' = only accepted friends. For one specific person, omit scope and pass target instead. Omitting scope defaults to the group/teammates audience.",
+                    },
                     query: {
                         type: "string",
                         description: "Optional peer-memory topic. Omit only for an intentional broad browse; never send this field as conversation.",
@@ -562,7 +634,7 @@ export function listToolSpecs(opts = {}) {
                     limit: { type: "integer", minimum: 1, maximum: 50, default: 10 },
                     target: {
                         type: "string",
-                        description: "Accessible friend or group-member user id or exact display name. Prefer this for @Name asks.",
+                        description: "Accessible friend or group-member user id or exact display name. Prefer this for @Name asks or a single specific person.",
                     },
                     ownerUserId: {
                         type: "string",
@@ -999,5 +1071,5 @@ export function listToolSpecs(opts = {}) {
             },
         },
     ];
-    return tools.map(decorateLocalToolSpec);
+    return injectWorkspaceSelector(tools).map(decorateLocalToolSpec);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.40",
+  "version": "1.4.42",
   "description": "EchoMem MCP bridge: cloud-first memory tools and the Agent Doctor workspace forensics report (cost ledger + 3D repo city)",
   "main": "dist/index.js",
   "type": "module",
@@ -33,7 +33,7 @@
     "test:ui": "npm run build && node test/setup-ui.test.mjs",
     "test:onboarding-resilience": "npm run build && node test/onboarding-resilience.test.mjs",
     "test:billing-ui": "npm run build && node test/setup-ui.test.mjs billing",
-    "test": "npm run build && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/onboarding-resilience.test.mjs && node test/local-auth.test.mjs && node test/retrieval-only.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/group-map.test.mjs && node test/update-check.test.mjs && node test/headless-runtime.test.mjs && node test/claude-code-config.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/restart-recovery.test.mjs && node test/save-checkpoint-hook.test.mjs",
+    "test": "npm run build && node test/source-session.test.mjs && node test/source-session-hook.test.mjs && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/onboarding-resilience.test.mjs && node test/local-auth.test.mjs && node test/retrieval-only.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/workspace-selector.test.mjs && node test/group-map.test.mjs && node test/update-check.test.mjs && node test/headless-runtime.test.mjs && node test/claude-code-config.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/restart-recovery.test.mjs && node test/save-checkpoint-hook.test.mjs",
     "prepack": "npm run build && node scripts/bundle-city.mjs"
   },
   "dependencies": {

package/templates/echomem-recall.md

@@ -6,6 +6,9 @@
 
 This project has EchoMem connected — the user's long-term memory across all their AI tools.
 
+- EchoMem's local SessionStart hook automatically binds new Codex and Claude Code conversations to
+  their real provider session. Call `bind_source_session` with a fresh random UUID only as a
+  compatibility fallback when automatic binding is unavailable or reports that the session is unbound.
 - **At the start of any non-trivial task**, call `search_memories` first to recall the user's
   prior decisions, preferences, and constraints before planning or writing code. Don't re-derive
   things they've already decided.