@posthog/mcp 0.10.6 → 0.10.8

package/dist/extensions/instrumentation.mjs

@@ -2,14 +2,15 @@ import { getAnalyticsParameterOwnership, stripOwnedAnalyticsArguments } from "./
 import { addContextParameterToTools, getContextDescription, isContextEnabled } from "./context-parameters.mjs";
 import { addConversationIdToTools, canInjectConversationIdPromptBack, injectConversationIdPromptBack, resolveConversationId } from "./conversation-id.mjs";
 import { stampMetaClientInfo } from "./client-identity.mjs";
+import { addInstructionsToOutputSchemas, mirrorInstructionsIntoStructuredContent } from "./output-instructions.mjs";
 import { captureEvent } from "./capture.mjs";
 import { MCPAnalyticsEventType } from "./event-types.mjs";
 import { captureException } from "./exceptions.mjs";
 import { resolveToolCallIntent, setEventIntent, setExplicitContextIntent } from "./intent.mjs";
-import { getServerTrackingData, handleIdentify, setServerTrackingData } from "./internal.mjs";
+import { getServerTrackingData, handleIdentify, setServerTrackingData, withIdentity } from "./internal.mjs";
 import { buildCapturedMcpParameters } from "./mcp-payloads.mjs";
 import { getLiteralValue, getObjectShape } from "./mcp-sdk-compat.mjs";
-import { getSessionId, newSessionId } from "./session.mjs";
+import { getSessionId, getSessionInfo, newSessionId } from "./session.mjs";
 import { encodeSessionId, readMcpSessionHeader, writeSessionIdToTransport } from "./session-token.mjs";
 import { getReportMissingToolDescriptor, resolveMissingCapabilityToolName } from "./tools.mjs";
 import { applyResolvedMetadata, isToolResultError } from "./tracing-helpers.mjs";
@@ -17,27 +18,29 @@ async function captureToolCall(params) {
     const { server, data, request, extra, execute, parameterOwnership, eventType, explicitContextIntent, takeCapturedError } = params;
     const resolvedEventType = eventType ?? MCPAnalyticsEventType.mcpToolsCall;
     const ownership = getActiveAnalyticsParameterOwnership(data, request.params?.name, parameterOwnership, resolvedEventType === MCPAnalyticsEventType.mcpMissingCapability);
-    const conversation = resolveConversationId(ownership.conversationId, request.params?.arguments, request.params?.name, resolvedEventType === MCPAnalyticsEventType.mcpMissingCapability ? resolveMissingCapabilityToolName(data.options) : '');
+    const conversation = resolveConversationId(ownership.conversationId, request.params?.arguments);
     const downstreamRequest = cloneRequestWithoutOwnedAnalyticsArguments(request, ownership);
     const startTime = new Date();
-    const event = await prepareToolCallEvent(server, data, request, downstreamRequest, extra, startTime, conversation, ownership, resolvedEventType);
-    if (event && explicitContextIntent) setExplicitContextIntent(event, explicitContextIntent);
+    const preparedEvent = await prepareToolCallEvent(server, data, request, downstreamRequest, extra, startTime, conversation, ownership, resolvedEventType);
+    if (preparedEvent && explicitContextIntent) setExplicitContextIntent(preparedEvent.event, explicitContextIntent);
     let result;
     try {
         result = await execute(downstreamRequest);
     } catch (error) {
-        publishFailedToolEvent(server, event, error, startTime, conversation, data.logger);
+        publishFailedToolEvent(server, preparedEvent, error, startTime, conversation, data.logger);
         throw error;
     }
-    const finalResult = applyConversationPromptBack(event, result, conversation);
-    publishSuccessfulToolEvent(server, event, finalResult, startTime, data.logger, takeCapturedError);
+    const finalResult = applyConversationInstructions(preparedEvent?.event ?? null, result, conversation, ownership);
+    publishSuccessfulToolEvent(server, preparedEvent, finalResult, startTime, data.logger, takeCapturedError);
     return finalResult;
 }
 function getActiveAnalyticsParameterOwnership(data, toolName, override, isMissingCapabilityTool) {
-    const ownership = override ?? (toolName ? data.toolAnalyticsParameterOwnership.get(toolName) : void 0);
+    const listed = toolName ? data.toolAnalyticsParameterOwnership.get(toolName) : void 0;
+    const ownership = override ?? listed;
     return {
         context: !isMissingCapabilityTool && isContextEnabled(data.options.context) && ownership?.context === true,
-        conversationId: !isMissingCapabilityTool && true === data.options.enableConversationId && ownership?.conversationId === true
+        conversationId: true === data.options.enableConversationId && ownership?.conversationId === true,
+        outputInstructions: true === data.options.enableConversationId && listed?.outputInstructions === true
     };
 }
 function cloneRequestWithoutOwnedAnalyticsArguments(request, ownership) {
@@ -54,8 +57,10 @@ function cloneRequestWithoutOwnedAnalyticsArguments(request, ownership) {
 }
 async function prepareToolCallEvent(server, data, request, downstreamRequest, extra, startTime, conversation, ownership, eventType) {
     try {
-        const sessionId = getSessionId(server, extra);
-        await handleIdentify(server, data, sessionId, request, extra);
+        const sessionId = getSessionId(server, extra, conversation.conversationId);
+        const sessionInfo = getSessionInfo(server, data, sessionId);
+        const identity = await handleIdentify(server, data, sessionId, request, sessionInfo, extra, !!conversation.conversationId);
+        const requestAttribution = withIdentity(sessionInfo, identity);
         const toolName = request.params?.name;
         const event = {
             sessionId,
@@ -70,20 +75,35 @@ async function prepareToolCallEvent(server, data, request, downstreamRequest, ex
         stampMetaClientInfo(event, request);
         await applyResolvedMetadata(event, data, request, extra);
         setEventIntent(event, await resolveToolCallIntent(data, request, ownership.context, extra));
-        return event;
+        return {
+            event,
+            requestAttribution
+        };
     } catch (error) {
         data.logger(`Warning: PostHog MCP analytics instrumentation failed for tool ${request.params?.name}, the tool will still run - ${error}`);
         return null;
     }
 }
-function applyConversationPromptBack(event, result, conversation) {
-    if (!conversation.minted) return result;
-    if (canInjectConversationIdPromptBack(result)) return injectConversationIdPromptBack(result, conversation.conversationId);
-    if (event) event.conversationId = void 0;
-    return result;
+function applyConversationInstructions(event, result, conversation, ownership) {
+    const conversationId = conversation.conversationId;
+    if (!conversationId) return result;
+    let updated = result;
+    let delivered = false;
+    if (ownership.outputInstructions) {
+        const mirrored = mirrorInstructionsIntoStructuredContent(updated, conversationId);
+        delivered = mirrored !== updated;
+        updated = mirrored;
+    }
+    if (conversation.minted && canInjectConversationIdPromptBack(updated)) {
+        updated = injectConversationIdPromptBack(updated, conversationId);
+        delivered = true;
+    }
+    if (!delivered && conversation.minted && event) event.conversationId = void 0;
+    return updated;
 }
-function publishSuccessfulToolEvent(server, event, result, startTime, logger, takeCapturedError) {
-    if (!event) return;
+function publishSuccessfulToolEvent(server, preparedEvent, result, startTime, logger, takeCapturedError) {
+    if (!preparedEvent) return;
+    const { event, requestAttribution } = preparedEvent;
     try {
         if (isToolResultError(result)) {
             event.isError = true;
@@ -92,19 +112,20 @@ function publishSuccessfulToolEvent(server, event, result, startTime, logger, ta
         } else event.isError = false;
         event.response = result;
         event.duration = Date.now() - startTime.getTime();
-        captureEvent(server, event, logger);
+        captureEvent(server, event, logger, requestAttribution);
     } catch (error) {
         logger(`Warning: PostHog MCP analytics failed to publish tool event - ${error}`);
     }
 }
-function publishFailedToolEvent(server, event, error, startTime, conversation, logger) {
-    if (!event) return;
+function publishFailedToolEvent(server, preparedEvent, error, startTime, conversation, logger) {
+    if (!preparedEvent) return;
+    const { event, requestAttribution } = preparedEvent;
     try {
         if (conversation.minted) event.conversationId = void 0;
         event.isError = true;
         event.error = captureException(error);
         event.duration = Date.now() - startTime.getTime();
-        captureEvent(server, event, logger);
+        captureEvent(server, event, logger, requestAttribution);
     } catch (publishError) {
         logger(`Warning: PostHog MCP analytics failed to publish failed tool event - ${publishError}`);
     }
@@ -159,15 +180,17 @@ async function isToolAdvertised(server, toolName, extra, logger) {
 async function handleListToolsRequest(server, originalListToolsHandler, request, extra, logger) {
     const data = getServerTrackingData(server);
     const startTime = new Date();
+    const sessionId = getSessionId(server, extra);
+    const requestAttribution = getSessionInfo(server, data, sessionId);
     const event = {
-        sessionId: getSessionId(server, extra),
+        sessionId,
         parameters: buildCapturedMcpParameters(request),
         eventType: MCPAnalyticsEventType.mcpToolsList,
         timestamp: startTime
     };
     stampMetaClientInfo(event, request);
     if (data) await applyResolvedMetadata(event, data, request, extra);
-    const tools = await getTracedToolsList(server, originalListToolsHandler, request, extra, event, logger);
+    const tools = await getTracedToolsList(server, originalListToolsHandler, request, extra, event, logger, requestAttribution);
     if (!data) {
         logger('Warning: PostHog MCP analytics is unable to find server tracking data. Please ensure you have called instrument(server, options) before using tool calls.');
         return {
@@ -179,7 +202,7 @@ async function handleListToolsRequest(server, originalListToolsHandler, request,
         event.error = captureException('No tools were sent to MCP client.');
         event.isError = true;
         event.duration = Date.now() - startTime.getTime();
-        captureEvent(server, event, data.logger);
+        captureEvent(server, event, data.logger, requestAttribution);
         return {
             tools
         };
@@ -190,20 +213,20 @@ async function handleListToolsRequest(server, originalListToolsHandler, request,
     event.listedToolNames = collectListedToolNames(tools);
     event.isError = false;
     event.duration = Date.now() - startTime.getTime();
-    captureEvent(server, event, data.logger);
+    captureEvent(server, event, data.logger, requestAttribution);
     return {
         tools
     };
 }
 function cacheToolAnalyticsParameterOwnership(cache, tools) {
-    for (const tool of tools)if (tool?.name) cache.set(tool.name, getAnalyticsParameterOwnership(tool.inputSchema));
+    for (const tool of tools)if (tool?.name) cache.set(tool.name, getAnalyticsParameterOwnership(tool.inputSchema, tool.outputSchema));
 }
 function collectListedToolNames(tools) {
     if (!tools || 0 === tools.length) return;
     const names = tools.map((tool)=>tool?.name).filter((name)=>'string' == typeof name);
     return names.length > 0 ? names : void 0;
 }
-async function getTracedToolsList(server, originalListToolsHandler, request, extra, event, logger) {
+async function getTracedToolsList(server, originalListToolsHandler, request, extra, event, logger, requestAttribution) {
     try {
         const data = getServerTrackingData(server);
         const originalResponse = await originalListToolsHandler(request, extra);
@@ -214,16 +237,21 @@ async function getTracedToolsList(server, originalListToolsHandler, request, ext
         if (data && isContextEnabled(data.options.context)) tools = addContextParameterToTools(tools, getContextDescription(data.options.context), data.logger);
         if (data) {
             const missingToolName = resolveMissingCapabilityToolName(data.options);
-            let injectedMissingCapabilityTool = false;
             if (data.options.reportMissing) {
                 const alreadyPresent = tools.some((tool)=>tool?.name === missingToolName);
                 if (alreadyPresent) data.logger(`Warning: Cannot inject missing-capability tool "${missingToolName}" because a real tool already uses that name. The real tool will not be intercepted.`);
                 else {
-                    tools.push(getReportMissingToolDescriptor(missingToolName));
-                    injectedMissingCapabilityTool = true;
+                    const virtualTool = getReportMissingToolDescriptor(missingToolName);
+                    tools.push(virtualTool);
+                    cacheToolAnalyticsParameterOwnership(data.toolAnalyticsParameterOwnership, [
+                        virtualTool
+                    ]);
                 }
             }
-            if (data.options.enableConversationId) tools = addConversationIdToTools(tools, missingToolName, injectedMissingCapabilityTool, data.logger);
+            if (data.options.enableConversationId) {
+                tools = addConversationIdToTools(tools, data.logger);
+                tools = addInstructionsToOutputSchemas(tools, data.logger);
+            }
         }
         if (data) {
             cacheToolDescriptions(data.toolDescriptions, tools);
@@ -235,7 +263,7 @@ async function getTracedToolsList(server, originalListToolsHandler, request, ext
         event.error = captureException(error);
         event.isError = true;
         event.duration = event.timestamp ? Date.now() - event.timestamp.getTime() : 0;
-        captureEvent(server, event, logger);
+        captureEvent(server, event, logger, requestAttribution);
         throw error;
     }
 }
@@ -284,19 +312,19 @@ function mintStatelessSessionOnInitialize(server, data, request, extra) {
         return;
     }
 }
-function upgradeMintedTokenToNegotiated(server, data, mintedSessionId, negotiatedProtocolVersion) {
+function upgradeMintedTokenToNegotiated(server, mintedSessionId, sessionInfo, negotiatedProtocolVersion, logger) {
     try {
         const transport = server.transport;
         if (!transport) return;
         const token = encodeSessionId({
             sessionId: mintedSessionId,
-            clientName: data.sessionInfo.clientName,
-            clientVersion: data.sessionInfo.clientVersion,
+            clientName: sessionInfo.clientName,
+            clientVersion: sessionInfo.clientVersion,
             protocolVersion: negotiatedProtocolVersion
         });
         writeSessionIdToTransport(transport, token);
     } catch (error) {
-        data.logger(`Warning: PostHog MCP analytics failed to upgrade the stateless session token - ${error}`);
+        logger(`Warning: PostHog MCP analytics failed to upgrade the stateless session token - ${error}`);
     }
 }
 function readInitializeClientInfo(request) {
@@ -316,7 +344,15 @@ async function handleInitializeRequest(server, originalInitializeHandler, reques
     }
     const mintedSessionId = mintStatelessSessionOnInitialize(server, data, request, extra);
     const sessionId = getSessionId(server, extra);
-    await handleIdentify(server, data, sessionId, request, extra);
+    const sessionInfo = getSessionInfo(server, data, sessionId);
+    const initializeClientInfo = readInitializeClientInfo(request);
+    const requestSessionInfo = {
+        ...sessionInfo,
+        clientName: initializeClientInfo?.name ?? sessionInfo.clientName,
+        clientVersion: initializeClientInfo?.version ?? sessionInfo.clientVersion
+    };
+    const identity = await handleIdentify(server, data, sessionId, request, requestSessionInfo, extra);
+    const requestAttribution = withIdentity(requestSessionInfo, identity);
     const event = {
         sessionId,
         resourceName: request.params?.name || 'Unknown Tool Name',
@@ -330,10 +366,18 @@ async function handleInitializeRequest(server, originalInitializeHandler, reques
     event.response = result;
     const negotiatedProtocolVersion = readProtocolVersion(result, request);
     event.protocolVersion = negotiatedProtocolVersion;
-    data.sessionInfo.protocolVersion = negotiatedProtocolVersion;
-    setServerTrackingData(server, data);
-    if (mintedSessionId) upgradeMintedTokenToNegotiated(server, data, mintedSessionId, negotiatedProtocolVersion);
-    captureEvent(server, event, data.logger);
+    if (data.sessionId === sessionId) {
+        data.sessionInfo = {
+            ...data.sessionInfo,
+            protocolVersion: negotiatedProtocolVersion
+        };
+        setServerTrackingData(server, data);
+    }
+    if (mintedSessionId) upgradeMintedTokenToNegotiated(server, mintedSessionId, requestSessionInfo, negotiatedProtocolVersion, data.logger);
+    captureEvent(server, event, data.logger, {
+        ...requestAttribution,
+        protocolVersion: negotiatedProtocolVersion
+    });
     return result;
 }
 function readProtocolVersion(result, request) {

package/dist/extensions/internal.d.ts

@@ -1,4 +1,4 @@
-import type { CompatibleRequestHandlerExtra, MCPAnalyticsData, MCPRequestLike, MCPServerLike, UserIdentity } from '../types';
+import type { CompatibleRequestHandlerExtra, MCPAnalyticsData, MCPRequestLike, MCPServerLike, SessionInfo, UserIdentity } from '../types';
 /**
  * Bounded LRU cache for session identities, capped at `maxSize` entries so a
  * long-lived server can't accumulate identities for unboundedly many sessions.
@@ -24,7 +24,15 @@ export declare function mergeIdentities(previous: UserIdentity | undefined, next
  * `$identify` event at most once per session: at `initialize`, when a
  * long-lived server first sees the identity, or when it materially changes.
  */
-export declare function handleIdentify(server: MCPServerLike, data: MCPAnalyticsData, sessionId: string, request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra): Promise<void>;
+export declare function handleIdentify(server: MCPServerLike, data: MCPAnalyticsData, sessionId: string, request: MCPRequestLike, requestAttribution: SessionInfo, extra?: CompatibleRequestHandlerExtra, 
+/**
+ * True when this session id came from an agent-carried `conversation_id`
+ * rather than the transport. Such a session is brand new and was never
+ * announced at `initialize`, whatever `data.sessionSource` still says about
+ * the connection.
+ */
+sessionFromConversation?: boolean): Promise<UserIdentity | undefined>;
+export declare function withIdentity(sessionInfo: SessionInfo, identity: UserIdentity | undefined): SessionInfo;
 /**
  * Resolves the `eventProperties` callback. Returns null when no callback is
  * configured, or when it returns nullish or throws — a throw never propagates

package/dist/extensions/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/extensions/internal.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,6BAA6B,EAC7B,gBAAgB,EAChB,cAAc,EACd,aAAa,EAEb,YAAY,EACb,MAAM,UAAU,CAAA;AAKjB;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;gBAErB,OAAO,SAAO;IAI1B,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAWhD,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI;IAapD,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI/B,IAAI,IAAI,MAAM;CAGf;AAID,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,gBAAgB,GAAG,SAAS,CAEzF;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAEzF;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,OAAO,CA4B5E;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,YAAY,CAapG;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,KAAK,CAAC,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CAkDf;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,cAAc,EACvB,KAAK,CAAC,EAAE,6BAA6B,GACpC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAUzC"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/extensions/internal.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,6BAA6B,EAC7B,gBAAgB,EAChB,cAAc,EACd,aAAa,EAEb,WAAW,EACX,YAAY,EACb,MAAM,UAAU,CAAA;AAKjB;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;gBAErB,OAAO,SAAO;IAI1B,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAWhD,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI;IAapD,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI/B,IAAI,IAAI,MAAM;CAGf;AAID,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,gBAAgB,GAAG,SAAS,CAEzF;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAEzF;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,OAAO,CA4B5E;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,YAAY,CAapG;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,kBAAkB,EAAE,WAAW,EAC/B,KAAK,CAAC,EAAE,6BAA6B;AACrC;;;;;GAKG;AACH,uBAAuB,UAAQ,GAC9B,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAuDnC;AAED,wBAAgB,YAAY,CAAC,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,GAAG,SAAS,GAAG,WAAW,CAOtG;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,cAAc,EACvB,KAAK,CAAC,EAAE,6BAA6B,GACpC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAUzC"}

package/dist/extensions/internal.js

@@ -26,11 +26,12 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     mergeIdentities: ()=>mergeIdentities,
     areIdentitiesEqual: ()=>areIdentitiesEqual,
+    getServerTrackingData: ()=>getServerTrackingData,
+    setServerTrackingData: ()=>setServerTrackingData,
     resolveEventProperties: ()=>resolveEventProperties,
+    withIdentity: ()=>withIdentity,
     handleIdentify: ()=>handleIdentify,
-    getServerTrackingData: ()=>getServerTrackingData,
-    IdentityCache: ()=>IdentityCache,
-    setServerTrackingData: ()=>setServerTrackingData
+    IdentityCache: ()=>IdentityCache
 });
 const external_event_types_js_namespaceObject = require("./event-types.js");
 const external_capture_js_namespaceObject = require("./capture.js");
@@ -94,8 +95,10 @@ function mergeIdentities(previous, next) {
         groups: next.groups ?? previous.groups
     };
 }
-async function handleIdentify(server, data, sessionId, request, extra) {
-    if (!data.options.identify) return;
+async function handleIdentify(server, data, sessionId, request, requestAttribution, extra, sessionFromConversation = false) {
+    const identityBeforeRequest = data.identifiedSessions.get(sessionId);
+    const sessionSourceBeforeIdentify = data.sessionSource;
+    if (!data.options.identify) return identityBeforeRequest;
     const identifyEvent = {
         sessionId,
         resourceName: getRequestResourceName(request),
@@ -114,17 +117,28 @@ async function handleIdentify(server, data, sessionId, request, extra) {
             const mergedIdentity = mergeIdentities(previousIdentity, identityResult);
             const changed = void 0 !== previousIdentity && !areIdentitiesEqual(previousIdentity, mergedIdentity);
             const firstSeen = void 0 === previousIdentity;
-            const announcedAtInitialize = 'token' === data.sessionSource && 'initialize' !== request.method;
+            const announcedAtInitialize = !sessionFromConversation && 'token' === sessionSourceBeforeIdentify && 'initialize' !== request.method;
             const shouldPublish = changed || firstSeen && !announcedAtInitialize;
             data.identifiedSessions.set(sessionId, mergedIdentity);
             if (shouldPublish) {
                 data.logger(`Identified session ${sessionId}`);
-                (0, external_capture_js_namespaceObject.captureEvent)(server, identifyEvent, data.logger);
+                (0, external_capture_js_namespaceObject.captureEvent)(server, identifyEvent, data.logger, withIdentity(requestAttribution, mergedIdentity));
             }
-        } else data.logger(`Warning: Supplied identify function returned null for session ${sessionId}`);
+            return mergedIdentity;
+        }
+        data.logger(`Warning: Supplied identify function returned null for session ${sessionId}`);
     } catch (error) {
         data.logger(`Error: User supplied identify function threw an error while identifying session ${sessionId} - ${error}`);
     }
+    return identityBeforeRequest;
+}
+function withIdentity(sessionInfo, identity) {
+    return {
+        ...sessionInfo,
+        identifyActorGivenId: identity?.distinctId,
+        identifyActorData: identity?.properties || {},
+        identifyActorGroups: identity?.groups
+    };
 }
 async function resolveEventProperties(data, request, extra) {
     if (!data.options.eventProperties) return null;
@@ -148,6 +162,7 @@ exports.handleIdentify = __webpack_exports__.handleIdentify;
 exports.mergeIdentities = __webpack_exports__.mergeIdentities;
 exports.resolveEventProperties = __webpack_exports__.resolveEventProperties;
 exports.setServerTrackingData = __webpack_exports__.setServerTrackingData;
+exports.withIdentity = __webpack_exports__.withIdentity;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "IdentityCache",
     "areIdentitiesEqual",
@@ -155,7 +170,8 @@ for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "handleIdentify",
     "mergeIdentities",
     "resolveEventProperties",
-    "setServerTrackingData"
+    "setServerTrackingData",
+    "withIdentity"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {
     value: true

package/dist/extensions/internal.mjs

@@ -60,8 +60,10 @@ function mergeIdentities(previous, next) {
         groups: next.groups ?? previous.groups
     };
 }
-async function handleIdentify(server, data, sessionId, request, extra) {
-    if (!data.options.identify) return;
+async function handleIdentify(server, data, sessionId, request, requestAttribution, extra, sessionFromConversation = false) {
+    const identityBeforeRequest = data.identifiedSessions.get(sessionId);
+    const sessionSourceBeforeIdentify = data.sessionSource;
+    if (!data.options.identify) return identityBeforeRequest;
     const identifyEvent = {
         sessionId,
         resourceName: getRequestResourceName(request),
@@ -80,17 +82,28 @@ async function handleIdentify(server, data, sessionId, request, extra) {
             const mergedIdentity = mergeIdentities(previousIdentity, identityResult);
             const changed = void 0 !== previousIdentity && !areIdentitiesEqual(previousIdentity, mergedIdentity);
             const firstSeen = void 0 === previousIdentity;
-            const announcedAtInitialize = 'token' === data.sessionSource && 'initialize' !== request.method;
+            const announcedAtInitialize = !sessionFromConversation && 'token' === sessionSourceBeforeIdentify && 'initialize' !== request.method;
             const shouldPublish = changed || firstSeen && !announcedAtInitialize;
             data.identifiedSessions.set(sessionId, mergedIdentity);
             if (shouldPublish) {
                 data.logger(`Identified session ${sessionId}`);
-                captureEvent(server, identifyEvent, data.logger);
+                captureEvent(server, identifyEvent, data.logger, withIdentity(requestAttribution, mergedIdentity));
             }
-        } else data.logger(`Warning: Supplied identify function returned null for session ${sessionId}`);
+            return mergedIdentity;
+        }
+        data.logger(`Warning: Supplied identify function returned null for session ${sessionId}`);
     } catch (error) {
         data.logger(`Error: User supplied identify function threw an error while identifying session ${sessionId} - ${error}`);
     }
+    return identityBeforeRequest;
+}
+function withIdentity(sessionInfo, identity) {
+    return {
+        ...sessionInfo,
+        identifyActorGivenId: identity?.distinctId,
+        identifyActorData: identity?.properties || {},
+        identifyActorGroups: identity?.groups
+    };
 }
 async function resolveEventProperties(data, request, extra) {
     if (!data.options.eventProperties) return null;
@@ -107,4 +120,4 @@ function getRequestResourceName(request) {
     if (!params || 'object' != typeof params || !('name' in params)) return 'Unknown';
     return 'string' == typeof params.name ? params.name : 'Unknown';
 }
-export { IdentityCache, areIdentitiesEqual, getServerTrackingData, handleIdentify, mergeIdentities, resolveEventProperties, setServerTrackingData };
+export { IdentityCache, areIdentitiesEqual, getServerTrackingData, handleIdentify, mergeIdentities, resolveEventProperties, setServerTrackingData, withIdentity };

package/dist/extensions/output-instructions.d.ts

@@ -0,0 +1,70 @@
+import type { LoggerFn } from './logger';
+/**
+ * The `conversation_id` session handle reaches the agent as a text block appended to the
+ * tool result. That block is invisible to any client that reads
+ * `structuredContent` instead of `content` — which is what clients do whenever a
+ * tool declares an `outputSchema`. Measured against Claude Code, correlation for
+ * such tools drops to zero.
+ *
+ * The fix is to mirror the session handle into `structuredContent` as well, which this
+ * module does in two halves that must stay in that order:
+ *
+ *   1. declare `_mcp_instructions` on the tool's advertised `outputSchema`
+ *   2. write it into the result's `structuredContent`
+ *
+ * The declaration is what makes the write safe. The MCP client ajv-validates
+ * `structuredContent` against the schema from `tools/list`, and
+ * `zod-to-json-schema` emits `additionalProperties: false` for a plain
+ * `z.object`, so an undeclared key is not ignored — it fails the entire tool
+ * result. Only tools that got the declaration are ever written to.
+ */
+export declare const MCP_INSTRUCTIONS_KEY = "_mcp_instructions";
+export interface OutputInstructionsInjectableTool {
+    name?: string;
+    outputSchema?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * True when we can safely declare {@link MCP_INSTRUCTIONS_KEY} on this tool's
+ * advertised output schema.
+ *
+ * Requires a plain-object schema we can extend. A tool with no `outputSchema`
+ * has nothing to mirror into and keeps working through `content`; a composed
+ * schema (`oneOf`/`allOf`/`anyOf`/`$ref`) has no single `properties` bag to add
+ * to. Both stay content-only, matching the policy on the input side.
+ */
+export declare function canDeclareOutputInstructions(outputSchema: unknown): boolean;
+/**
+ * Returns a copy of the tool with an optional {@link MCP_INSTRUCTIONS_KEY}
+ * property added to its output schema, or the tool untouched when it has no
+ * output schema to extend.
+ *
+ * The property is never added to `required` — a result without it must stay
+ * valid, since every tool result predating this change lacks it.
+ */
+export declare function addInstructionsToOutputSchema<TTool extends OutputInstructionsInjectableTool>(tool: TTool, logger?: LoggerFn): TTool;
+/**
+ * Declares {@link MCP_INSTRUCTIONS_KEY} across a tool listing. Tools without an
+ * output schema, and tools whose schema we cannot extend, pass through unchanged.
+ */
+export declare function addInstructionsToOutputSchemas<TTool extends OutputInstructionsInjectableTool>(tools: TTool[], logger?: LoggerFn): TTool[];
+export interface ConversationInstructions {
+    conversation_id: string;
+    instructions: string;
+}
+/** The payload mirrored into `structuredContent` for a tool we declared the key on. */
+export declare function buildConversationInstructions(conversationId: string): ConversationInstructions;
+/**
+ * Adds {@link MCP_INSTRUCTIONS_KEY} to a result's `structuredContent`, which is
+ * where clients look once a tool declares an `outputSchema` — the `content` text
+ * block carrying the session handle is invisible to them.
+ *
+ * Unlike the text block, this rides *every* response rather than only the one
+ * that minted the session handle, so an agent that drops it can read it back.
+ *
+ * Returns the result untouched when there is no plain-object `structuredContent`
+ * to extend, or when the tool already produced its own key — customer data wins.
+ * Never mutates the input.
+ */
+export declare function mirrorInstructionsIntoStructuredContent(result: unknown, conversationId: string): unknown;
+//# sourceMappingURL=output-instructions.d.ts.map

package/dist/extensions/output-instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-instructions.d.ts","sourceRoot":"","sources":["../../src/extensions/output-instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAIxC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,sBAAsB,CAAA;AAQvD,MAAM,WAAW,gCAAgC;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAgC3E;AAwCD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,SAAS,gCAAgC,EAC1F,IAAI,EAAE,KAAK,EACX,MAAM,GAAE,QAAc,GACrB,KAAK,CA8CP;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,SAAS,gCAAgC,EAC3F,KAAK,EAAE,KAAK,EAAE,EACd,MAAM,GAAE,QAAc,GACrB,KAAK,EAAE,CAET;AAED,MAAM,WAAW,wBAAwB;IACvC,eAAe,EAAE,MAAM,CAAA;IACvB,YAAY,EAAE,MAAM,CAAA;CACrB;AAID,uFAAuF;AACvF,wBAAgB,6BAA6B,CAAC,cAAc,EAAE,MAAM,GAAG,wBAAwB,CAE9F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uCAAuC,CAAC,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAkBxG"}