@echomem/mcp 1.4.49 → 1.4.51

package/dist/source-session.js

@@ -9,6 +9,9 @@ const UUID_IN_TEXT_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f
 const MAX_TAIL_BYTES = 512 * 1024;
 const DEFAULT_MAX_AGE_MS = 15 * 60 * 1000;
 const MAX_RECENT_FILES_PER_PROVIDER = 24;
+const MAX_CODEX_AGENT_DEPTH = 16;
+const CODEX_FILE_INDEX_TTL_MS = 5_000;
+const codexFileIndexes = new Map();
 function normalizedProviderSessionId(provider, value) {
     const normalized = value.trim();
     if (!normalized || normalized.length > 200 || /\s/.test(normalized)) {
@@ -31,47 +34,73 @@ export function verifiedSourceSession(provider, providerSessionId, evidence) {
         evidence,
     };
 }
-/**
- * Resolve identity from host-owned MCP metadata. Unlike tool arguments, these values are attached by
- * Codex/Claude outside the model-controlled input. The SessionStart hook performs the eager bind;
- * this resolver lets the MCP process independently attach the same identity on its first real call.
- */
-export function resolveSourceSessionFromMcpContext(metadata, options = {}) {
-    const host = options.hostPlatform?.toLowerCase().replace(/[^a-z0-9]+/g, "_") ?? "";
-    const env = options.env ?? process.env;
-    if (host.includes("codex")) {
-        const root = isRecord(metadata) ? metadata : {};
-        const turn = isRecord(root["x-codex-turn-metadata"])
-            ? root["x-codex-turn-metadata"]
-            : {};
-        const candidate = typeof turn.thread_id === "string"
-            ? turn.thread_id
-            : typeof turn.session_id === "string"
-                ? turn.session_id
-                : typeof root.threadId === "string"
-                    ? root.threadId
-                    : "";
-        return candidate
-            ? verifiedSourceSession("codex", candidate, SOURCE_SESSION_MCP_METADATA_EVIDENCE)
-            : null;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizedUuid(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim().toLowerCase();
+    return UUID_RE.test(normalized) ? normalized : null;
+}
+function sourceParentThreadId(source) {
+    if (!isRecord(source) || !isRecord(source.subagent))
+        return null;
+    const direct = normalizedUuid(source.subagent.parent_thread_id);
+    if (direct)
+        return direct;
+    const spawn = isRecord(source.subagent.thread_spawn) ? source.subagent.thread_spawn : null;
+    return normalizedUuid(spawn?.parent_thread_id);
+}
+function metadataMarksSubagent(value) {
+    if (value == null || value === false || value === 0)
+        return false;
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        return normalized !== "" && normalized !== "0" && normalized !== "false" && normalized !== "no";
     }
-    if (host.includes("claude_desktop") || host === "claude" || host.includes("cowork")) {
-        const candidate = env.CLAUDE_CODE_HOST_SESSION_ID?.trim() ?? "";
-        return candidate
-            ? verifiedSourceSession("cowork", candidate, SOURCE_SESSION_MCP_METADATA_EVIDENCE)
-            : null;
+    return true;
+}
+function codexLineageNode(file) {
+    let descriptor = null;
+    try {
+        descriptor = fs.openSync(file, "r");
+        const stat = fs.fstatSync(descriptor);
+        const bytes = Math.min(stat.size, 128 * 1024);
+        const buffer = Buffer.allocUnsafe(bytes);
+        fs.readSync(descriptor, buffer, 0, bytes, 0);
+        for (const line of buffer.toString("utf8").split(/\r?\n/)) {
+            if (!line.includes("session_meta"))
+                continue;
+            try {
+                const row = JSON.parse(line);
+                if (!isRecord(row) || row.type !== "session_meta" || !isRecord(row.payload))
+                    continue;
+                const id = normalizedUuid(row.payload.id) ?? normalizedUuid(row.payload.session_id);
+                if (!id)
+                    return null;
+                const source = row.payload.source;
+                const directParent = normalizedUuid(row.payload.parent_thread_id);
+                const parentThreadId = directParent ?? sourceParentThreadId(source);
+                const isSubagent = parentThreadId !== null
+                    || (isRecord(source) && Object.hasOwn(source, "subagent"))
+                    || row.payload.thread_source === "subagent";
+                return { id, isSubagent, parentThreadId };
+            }
+            catch {
+                continue;
+            }
+        }
     }
-    if (host.includes("claude_code")) {
-        const candidate = env.CLAUDE_CODE_SESSION_ID?.trim() ?? "";
-        return candidate
-            ? verifiedSourceSession("claude-code", candidate, SOURCE_SESSION_MCP_METADATA_EVIDENCE)
-            : null;
+    catch {
+        return null;
+    }
+    finally {
+        if (descriptor !== null)
+            fs.closeSync(descriptor);
     }
     return null;
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function readableDirectory(candidate) {
     try {
         return fs.statSync(candidate).isDirectory();
@@ -115,8 +144,105 @@ function walkJsonlFiles(roots) {
     }
     return files;
 }
-function recentFiles(roots, nowMs, maxAgeMs) {
-    return walkJsonlFiles(roots)
+/** Codex stores spawned-agent transcripts below `subagents`, so lineage discovery must include them. */
+function walkCodexJsonlFiles(roots) {
+    const files = [];
+    const pending = roots.filter(readableDirectory);
+    while (pending.length) {
+        const directory = pending.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const target = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                pending.push(target);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+                files.push(target);
+            }
+        }
+    }
+    return files;
+}
+function codexFileIndexKey(roots) {
+    return [...roots].map((root) => path.resolve(root)).sort().join("\u0000");
+}
+function buildCodexFileIndex(roots) {
+    const filesById = new Map();
+    for (const file of walkCodexJsonlFiles(roots)) {
+        const filenameId = path.basename(file).match(UUID_IN_TEXT_RE)?.[0]?.toLowerCase();
+        if (filenameId && !filesById.has(filenameId))
+            filesById.set(filenameId, file);
+    }
+    return filesById;
+}
+function codexFileForSession(sessionId, roots, forceRefresh = false) {
+    const key = codexFileIndexKey(roots);
+    const now = Date.now();
+    let cached = codexFileIndexes.get(key);
+    if (forceRefresh || !cached || cached.expiresAtMs <= now) {
+        cached = {
+            expiresAtMs: now + CODEX_FILE_INDEX_TTL_MS,
+            filesById: buildCodexFileIndex(roots),
+        };
+        codexFileIndexes.set(key, cached);
+    }
+    const normalized = sessionId.toLowerCase();
+    return cached.filesById.get(normalized) ?? null;
+}
+function codexNodeForSession(sessionId, roots) {
+    let file = codexFileForSession(sessionId, roots);
+    if (!file)
+        file = codexFileForSession(sessionId, roots, true);
+    if (!file)
+        return null;
+    const node = codexLineageNode(file);
+    return node?.id === sessionId.toLowerCase() ? node : null;
+}
+function resolveCodexRootThread(agentThreadId, explicitParentThreadId, explicitSubagentMarker, roots) {
+    const localAgent = codexNodeForSession(agentThreadId, roots);
+    const isSubagent = explicitSubagentMarker || explicitParentThreadId !== null || localAgent?.isSubagent === true;
+    if (!isSubagent) {
+        return { isSubagent: false, rootThreadId: agentThreadId, parentThreadId: null, agentDepth: 0 };
+    }
+    const localParent = localAgent?.parentThreadId ?? null;
+    if (explicitParentThreadId && localParent && explicitParentThreadId !== localParent) {
+        return { isSubagent: true, rootThreadId: null, parentThreadId: explicitParentThreadId, agentDepth: 0 };
+    }
+    const firstParent = explicitParentThreadId ?? localParent;
+    if (!firstParent) {
+        return { isSubagent: true, rootThreadId: null, parentThreadId: null, agentDepth: 0 };
+    }
+    const visited = new Set([agentThreadId]);
+    let currentId = firstParent;
+    let depth = 1;
+    while (depth <= MAX_CODEX_AGENT_DEPTH) {
+        if (visited.has(currentId)) {
+            return { isSubagent: true, rootThreadId: null, parentThreadId: firstParent, agentDepth: depth };
+        }
+        visited.add(currentId);
+        const current = codexNodeForSession(currentId, roots);
+        if (!current) {
+            return { isSubagent: true, rootThreadId: null, parentThreadId: firstParent, agentDepth: depth };
+        }
+        if (!current.isSubagent) {
+            return { isSubagent: true, rootThreadId: current.id, parentThreadId: firstParent, agentDepth: depth };
+        }
+        if (!current.parentThreadId) {
+            return { isSubagent: true, rootThreadId: null, parentThreadId: firstParent, agentDepth: depth };
+        }
+        currentId = current.parentThreadId;
+        depth += 1;
+    }
+    return { isSubagent: true, rootThreadId: null, parentThreadId: firstParent, agentDepth: depth };
+}
+function recentFiles(roots, nowMs, maxAgeMs, includeCodexSubagents = false) {
+    return (includeCodexSubagents ? walkCodexJsonlFiles(roots) : walkJsonlFiles(roots))
         .map((file) => {
         try {
             return { file, mtimeMs: fs.statSync(file).mtimeMs };
@@ -151,41 +277,11 @@ function tailContainsBinding(file, bindingToken) {
             fs.closeSync(descriptor);
     }
 }
-function codexSessionId(file) {
-    let descriptor = null;
-    try {
-        descriptor = fs.openSync(file, "r");
-        const stat = fs.fstatSync(descriptor);
-        const bytes = Math.min(stat.size, 128 * 1024);
-        const buffer = Buffer.allocUnsafe(bytes);
-        fs.readSync(descriptor, buffer, 0, bytes, 0);
-        for (const line of buffer.toString("utf8").split(/\r?\n/)) {
-            if (!line.includes("session_meta"))
-                continue;
-            try {
-                const row = JSON.parse(line);
-                if (!isRecord(row) || row.type !== "session_meta" || !isRecord(row.payload))
-                    continue;
-                if (typeof row.payload.parent_thread_id === "string" && row.payload.parent_thread_id)
-                    return null;
-                const raw = typeof row.payload.id === "string"
-                    ? row.payload.id
-                    : typeof row.payload.session_id === "string"
-                        ? row.payload.session_id
-                        : "";
-                return UUID_RE.test(raw) ? raw.toLowerCase() : null;
-            }
-            catch {
-                continue;
-            }
-        }
-    }
-    catch {
-        return null;
-    }
-    finally {
-        if (descriptor !== null)
-            fs.closeSync(descriptor);
+function codexSessionId(file, roots) {
+    const node = codexLineageNode(file);
+    if (node) {
+        const resolution = resolveCodexRootThread(node.id, node.parentThreadId, node.isSubagent, roots);
+        return resolution.rootThreadId;
     }
     return path.basename(file).match(UUID_IN_TEXT_RE)?.[0]?.toLowerCase() ?? null;
 }
@@ -208,6 +304,88 @@ function enabledProviders(hostPlatform) {
     }
     return ["codex", "claude-code", "cowork"];
 }
+/**
+ * Resolve host-owned request metadata into EchoMem's root human-thread context. A Codex subagent
+ * gets its own model/tool transcript, but its durable memory context remains the originating root.
+ * Child lineage must be corroborated by local host JSONL; failures stay explicitly unbound.
+ */
+export function resolveSourceSessionRequestContext(metadata, options = {}) {
+    const host = options.hostPlatform?.toLowerCase().replace(/[^a-z0-9]+/g, "_") ?? "";
+    const env = options.env ?? process.env;
+    if (host.includes("codex")) {
+        const root = isRecord(metadata) ? metadata : {};
+        const turn = isRecord(root["x-codex-turn-metadata"])
+            ? root["x-codex-turn-metadata"]
+            : {};
+        const agentThreadId = normalizedUuid(turn.thread_id)
+            ?? normalizedUuid(turn.session_id)
+            ?? normalizedUuid(root.threadId);
+        const parentThreadId = normalizedUuid(root["x-codex-parent-thread-id"])
+            ?? normalizedUuid(turn.parent_thread_id)
+            ?? normalizedUuid(turn.parentThreadId)
+            ?? sourceParentThreadId(turn.source);
+        const explicitSubagentMarker = parentThreadId !== null
+            || metadataMarksSubagent(root["x-openai-subagent"])
+            || turn.thread_source === "subagent"
+            || metadataMarksSubagent(turn.subagent_kind)
+            || (isRecord(turn.source) && Object.hasOwn(turn.source, "subagent"));
+        if (!agentThreadId) {
+            return {
+                sourceSession: null,
+                isSubagent: explicitSubagentMarker,
+                lineageStatus: explicitSubagentMarker ? "unresolved_subagent" : "unbound",
+                parentThreadId: parentThreadId ?? undefined,
+            };
+        }
+        const codexRoots = options.roots?.codex
+            ?? resolveCodexSessionRoots({ env }).map((entry) => entry.path);
+        const lineage = resolveCodexRootThread(agentThreadId, parentThreadId, explicitSubagentMarker, codexRoots);
+        if (lineage.isSubagent && !lineage.rootThreadId) {
+            return {
+                sourceSession: null,
+                isSubagent: true,
+                lineageStatus: "unresolved_subagent",
+                agentThreadId,
+                parentThreadId: lineage.parentThreadId ?? undefined,
+                agentDepth: lineage.agentDepth,
+            };
+        }
+        const rootThreadId = lineage.rootThreadId ?? agentThreadId;
+        return {
+            sourceSession: verifiedSourceSession("codex", rootThreadId, SOURCE_SESSION_MCP_METADATA_EVIDENCE),
+            isSubagent: lineage.isSubagent,
+            lineageStatus: lineage.isSubagent ? "resolved_subagent" : "top_level",
+            agentThreadId,
+            parentThreadId: lineage.parentThreadId ?? undefined,
+            rootThreadId,
+            agentDepth: lineage.agentDepth,
+        };
+    }
+    if (host.includes("claude_desktop") || host === "claude" || host.includes("cowork")) {
+        const candidate = env.CLAUDE_CODE_HOST_SESSION_ID?.trim() ?? "";
+        return {
+            sourceSession: candidate
+                ? verifiedSourceSession("cowork", candidate, SOURCE_SESSION_MCP_METADATA_EVIDENCE)
+                : null,
+            isSubagent: false,
+            lineageStatus: candidate ? "not_applicable" : "unbound",
+        };
+    }
+    if (host.includes("claude_code")) {
+        const candidate = env.CLAUDE_CODE_SESSION_ID?.trim() ?? "";
+        return {
+            sourceSession: candidate
+                ? verifiedSourceSession("claude-code", candidate, SOURCE_SESSION_MCP_METADATA_EVIDENCE)
+                : null,
+            isSubagent: false,
+            lineageStatus: candidate ? "not_applicable" : "unbound",
+        };
+    }
+    return { sourceSession: null, isSubagent: false, lineageStatus: "unbound" };
+}
+export function resolveSourceSessionFromMcpContext(metadata, options = {}) {
+    return resolveSourceSessionRequestContext(metadata, options).sourceSession;
+}
 export function resolveSourceSessionFromBindingToken(bindingToken, options = {}) {
     const normalizedToken = bindingToken.trim().toLowerCase();
     if (!UUID_RE.test(normalizedToken)) {
@@ -231,11 +409,11 @@ export function resolveSourceSessionFromBindingToken(bindingToken, options = {})
             : provider === "claude-code"
                 ? roots.claudeCode
                 : roots.cowork;
-        for (const file of recentFiles(providerRoots, nowMs, maxAgeMs)) {
+        for (const file of recentFiles(providerRoots, nowMs, maxAgeMs, provider === "codex")) {
             if (!tailContainsBinding(file, normalizedToken))
                 continue;
             const providerSessionId = provider === "codex"
-                ? codexSessionId(file)
+                ? codexSessionId(file, roots.codex)
                 : provider === "claude-code"
                     ? claudeCodeSessionId(file)
                     : coworkSessionId(file);

package/dist/v1-contract.js

@@ -2,6 +2,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",
+    linkWorkspaceTicketSession: "link_workspace_ticket_session",
     search: "search_memories",
     save: "save_conversation",
     timeRange: "get_memories_by_time_range",
@@ -59,6 +60,7 @@ const READ_ONLY_TOOL_NAMES = new Set([
 ]);
 const IDEMPOTENT_WRITE_TOOL_NAMES = new Set([
     canonicalToolNames.bindSourceSession,
+    canonicalToolNames.linkWorkspaceTicketSession,
     canonicalToolNames.recordCitations,
     canonicalToolNames.setGroupSessionSharing,
     canonicalToolNames.updateGroupProfile,
@@ -78,6 +80,7 @@ const REQUIRES_USER_INTERACTION_TOOL_NAMES = new Set([
 ]);
 const ALWAYS_LOAD_TOOL_NAMES = new Set([
     canonicalToolNames.bindSourceSession,
+    canonicalToolNames.linkWorkspaceTicketSession,
     canonicalToolNames.search,
     canonicalToolNames.save,
 ]);
@@ -226,6 +229,11 @@ export const saveConversationSchema = z.object({
 export const bindSourceSessionSchema = z.object({
     bindingToken: z.string().uuid(),
 });
+export const linkWorkspaceTicketSessionSchema = z.object({
+    ...triggerMetadataSchema,
+    ticketId: z.string().uuid(),
+    workspaceId: z.string().uuid().optional(),
+});
 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,
@@ -467,6 +475,32 @@ export function listToolSpecs(opts = {}) {
                 required: ["bindingToken"],
             },
         },
+        {
+            name: canonicalToolNames.linkWorkspaceTicketSession,
+            title: "Link this agent conversation to an Echo workspace ticket",
+            description: withMcpVersion("Call when the user asks to work on, continue, attach, or bind this conversation to an Echo workspace ticket and supplies its UUID. Pass the ticketId exactly; pass workspaceId when a structured Echo ticket marker provides it. The operation is idempotent. If the current source session is already verified, EchoMem links it immediately. Otherwise Echo Desktop can recover this exact tool invocation from the local transcript and finish the verified link; never guess or ask the user for a source-session/context ID."),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    ticketId: {
+                        type: "string",
+                        format: "uuid",
+                        description: "The Echo workspace ticket UUID from the user's message or structured launch marker.",
+                    },
+                    workspaceId: {
+                        type: "string",
+                        format: "uuid",
+                        description: "Optional Echo workspace UUID when it is present in the structured launch marker.",
+                    },
+                    triggerMessage: {
+                        type: "string",
+                        description: "Optional user message that expressed the ticket-linking intent.",
+                    },
+                    triggerMessageRole: { type: "string", default: "user" },
+                },
+                required: ["ticketId"],
+            },
+        },
         {
             name: canonicalToolNames.search,
             title: "Search your memories by topic",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.49",
+  "version": "1.4.51",
   "description": "EchoMem MCP bridge for cross-agent memory, local history import, and recall",
   "main": "dist/index.js",
   "type": "module",
@@ -31,7 +31,9 @@
     "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/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/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",
+    "test:config-safety": "npm run build && node test/config-safety.test.mjs",
+    "test:mcp-control": "npm run build && node test/mcp-control.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/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/config-safety.test.mjs && node test/mcp-control.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 && node test/durable-entry.test.mjs && node test/durable-reexec.test.mjs && node test/doctor.test.mjs && node test/environment-matrix.test.mjs",
     "prepack": "npm run build"
   },
   "dependencies": {