within-sdk 1.0.0

package/dist/modules/session.js

@@ -0,0 +1,109 @@
+import { getServerTrackingData, setServerTrackingData } from "./internal.js";
+import KSUID from "../thirdparty/ksuid/index.js";
+import { createHash } from "crypto";
+import { INACTIVITY_TIMEOUT_IN_MINUTES, SDK_VERSION } from "./constants.js";
+export function newSessionId() {
+    return KSUID.withPrefix("ses").randomSync();
+}
+/**
+ * Creates a deterministic KSUID session ID from an MCP sessionId and optional projectId.
+ * The same inputs will always produce the same session ID, enabling correlation across server restarts.
+ *
+ * @param mcpSessionId - The session ID from the MCP protocol
+ * @param projectId - Optional Within project ID to include in the hash
+ * @returns A KSUID with "ses" prefix derived deterministically from the inputs
+ */
+export function deriveSessionIdFromMCPSession(mcpSessionId, projectId) {
+    // Create input string for hashing
+    const input = projectId ? `${mcpSessionId}:${projectId}` : mcpSessionId;
+    // Hash the input with SHA-256
+    const hash = createHash("sha256").update(input).digest();
+    // Extract timestamp from first 4 bytes of hash (for deterministic but reasonable timestamp)
+    // We'll use a fixed epoch (2024-01-01) plus the hash value to get a deterministic but valid timestamp
+    const EPOCH_2024 = new Date("2024-01-01T00:00:00Z").getTime();
+    const timestampOffset = hash.readUInt32BE(0) % (365 * 24 * 60 * 60 * 1000); // Max 1 year offset
+    const timestamp = EPOCH_2024 + timestampOffset;
+    // Use the remaining 16 bytes of hash as the KSUID payload
+    const payload = hash.subarray(4, 20);
+    // Create deterministic KSUID with prefix
+    return KSUID.withPrefix("ses").fromParts(timestamp, payload);
+}
+/**
+ * Gets or generates a session ID for the server.
+ * Prioritizes MCP protocol sessionId over Within-generated sessionId.
+ *
+ * @param server - The MCP server instance
+ * @param extra - Optional extra data containing MCP sessionId
+ * @returns The session ID to use for events
+ */
+export function getServerSessionId(server, extra) {
+    const data = getServerTrackingData(server);
+    if (!data) {
+        throw new Error("Server tracking data not found");
+    }
+    const mcpSessionId = extra?.sessionId;
+    // If MCP sessionId is provided
+    if (mcpSessionId) {
+        // Derive deterministic KSUID from MCP sessionId
+        data.sessionId = deriveSessionIdFromMCPSession(mcpSessionId, data.projectId || undefined);
+        data.lastMcpSessionId = mcpSessionId;
+        data.sessionSource = "mcp";
+        setServerTrackingData(server, data);
+        // If MCP sessionId hasn't changed, continue using the existing derived KSUID
+        setLastActivity(server);
+        return data.sessionId;
+    }
+    // No MCP sessionId provided - handle Within-generated sessions
+    // If we had an MCP sessionId before but it disappeared, keep using the last derived ID
+    if (data.sessionSource === "mcp" && data.lastMcpSessionId) {
+        setLastActivity(server);
+        return data.sessionId;
+    }
+    // For Within-generated sessions, apply timeout logic
+    const now = Date.now();
+    const timeoutMs = INACTIVITY_TIMEOUT_IN_MINUTES * 60 * 1000;
+    // If last activity timed out
+    if (now - data.lastActivity.getTime() > timeoutMs) {
+        data.sessionId = newSessionId();
+        data.sessionSource = "within";
+        setServerTrackingData(server, data);
+    }
+    setLastActivity(server);
+    return data.sessionId;
+}
+export function setLastActivity(server) {
+    const data = getServerTrackingData(server);
+    if (!data) {
+        throw new Error("Server tracking data not found");
+    }
+    data.lastActivity = new Date();
+    setServerTrackingData(server, data);
+}
+export function getSessionInfo(server, data) {
+    let clientInfo = {
+        name: undefined,
+        version: undefined,
+    };
+    if (!data?.sessionInfo.clientName) {
+        clientInfo = server.getClientVersion();
+    }
+    const actorInfo = data?.identifiedSessions.get(data.sessionId);
+    const sessionInfo = {
+        ipAddress: undefined, // grab from django
+        sdkLanguage: "TypeScript", // hardcoded for now
+        sdkVersion: SDK_VERSION,
+        serverName: server._serverInfo?.name,
+        serverVersion: server._serverInfo?.version,
+        clientName: clientInfo?.name,
+        clientVersion: clientInfo?.version,
+        identifyActorGivenId: actorInfo?.userId ?? data?.sessionInfo.identifyActorGivenId,
+        identifyActorName: actorInfo?.userName,
+        identifyActorData: actorInfo?.userData || data?.sessionInfo.identifyActorData || {},
+    };
+    if (!data) {
+        return sessionInfo;
+    }
+    data.sessionInfo = sessionInfo;
+    setServerTrackingData(server, data);
+    return data.sessionInfo;
+}

package/dist/modules/telemetry.d.ts

@@ -0,0 +1,8 @@
+import { Event, ExporterConfig } from "../types.js";
+export declare class TelemetryManager {
+    private exporters;
+    constructor(exporterConfigs?: Record<string, ExporterConfig>);
+    private createExporter;
+    export(event: Event): Promise<void>;
+    getExporterCount(): number;
+}

package/dist/modules/telemetry.js

@@ -0,0 +1,53 @@
+import { writeToLog } from "./logging.js";
+import { OTLPExporter } from "./exporters/otlp.js";
+import { DatadogExporter } from "./exporters/datadog.js";
+import { SentryExporter } from "./exporters/sentry.js";
+import { PostHogExporter } from "./exporters/posthog.js";
+export class TelemetryManager {
+    exporters = new Map();
+    constructor(exporterConfigs) {
+        if (!exporterConfigs)
+            return;
+        for (const [name, config] of Object.entries(exporterConfigs)) {
+            try {
+                const exporter = this.createExporter(name, config);
+                if (exporter) {
+                    this.exporters.set(name, exporter);
+                    writeToLog(`Initialized telemetry exporter: ${name}`);
+                }
+            }
+            catch (error) {
+                writeToLog(`Failed to initialize exporter ${name}: ${error}`);
+            }
+        }
+    }
+    createExporter(name, config) {
+        switch (config.type) {
+            case "otlp":
+                return new OTLPExporter(config);
+            case "datadog":
+                return new DatadogExporter(config);
+            case "sentry":
+                return new SentryExporter(config);
+            case "posthog":
+                return new PostHogExporter(config);
+            default:
+                writeToLog(`Unknown exporter type: ${config.type}`);
+                return null;
+        }
+    }
+    async export(event) {
+        if (this.exporters.size === 0)
+            return;
+        // Telemetry errors should be logged but not propagated
+        for (const [name, exporter] of this.exporters) {
+            exporter.export(event).catch((error) => {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                writeToLog(`Telemetry export failed for ${name}: ${errorMessage}`);
+            });
+        }
+    }
+    getExporterCount() {
+        return this.exporters.size;
+    }
+}

package/dist/modules/tools.d.ts

@@ -0,0 +1,25 @@
+import { MCPServerLike } from "../types.js";
+export declare const GET_MORE_TOOLS_NAME: "get_more_tools";
+export declare function getReportMissingToolDescriptor(): {
+    readonly name: "get_more_tools";
+    readonly description: "Check for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly context: {
+                readonly type: "string";
+                readonly description: "A description of your goal and what kind of tool would help accomplish it.";
+            };
+        };
+        readonly required: readonly ["context"];
+    };
+};
+export declare function handleReportMissing(args: {
+    context: string;
+}): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function setupWithinFeedbackTools(server: MCPServerLike): void;

package/dist/modules/tools.js

@@ -0,0 +1,119 @@
+import { ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { writeToLog } from "./logging.js";
+import { getServerTrackingData, handleIdentify } from "./internal.js";
+import { addContextParameterToTools } from "./context-parameters.js";
+import { publishEvent } from "./eventQueue.js";
+import { getServerSessionId } from "./session.js";
+import { WithinEventType } from "./constants.js";
+import { getMCPCompatibleErrorMessage } from "./compatibility.js";
+export const GET_MORE_TOOLS_NAME = "get_more_tools";
+export function getReportMissingToolDescriptor() {
+    return {
+        name: GET_MORE_TOOLS_NAME,
+        description: "Check for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                context: {
+                    type: "string",
+                    description: "A description of your goal and what kind of tool would help accomplish it.",
+                },
+            },
+            required: ["context"],
+        },
+    };
+}
+export function handleReportMissing(args) {
+    writeToLog(`Missing tool reported (context length: ${args?.context?.length ?? 0})`);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Unfortunately, we have shown you the full tool list. We have noted your feedback and will work to improve the tool list in the future.`,
+            },
+        ],
+    };
+}
+export function setupWithinFeedbackTools(server) {
+    // Store reference to original handlers - need to use the method name, not the schema
+    const handlers = server._requestHandlers;
+    const originalListToolsHandler = handlers.get("tools/list");
+    const originalCallToolHandler = handlers.get("tools/call");
+    if (!originalListToolsHandler || !originalCallToolHandler) {
+        writeToLog("Warning: Original tool handlers not found. Your tools may not be setup before Within track().");
+        return;
+    }
+    // Override tools list to include get_more_tools and add context parameter
+    try {
+        server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+            let tools = [];
+            const data = getServerTrackingData(server);
+            let event = {
+                sessionId: getServerSessionId(server, extra),
+                parameters: {
+                    request: request,
+                    extra: extra,
+                },
+                eventType: WithinEventType.mcpToolsList,
+                timestamp: new Date(),
+                redactionFn: data?.options.redactSensitiveInformation,
+            };
+            if (data) {
+                await handleIdentify(server, data, request, extra);
+                event.sessionId = data.sessionId;
+            }
+            try {
+                const originalResponse = (await originalListToolsHandler(request, extra));
+                tools = originalResponse.tools || [];
+            }
+            catch (error) {
+                // If original handler fails, start with empty tools
+                writeToLog(`Warning: Original list tools handler failed, this suggests an error Within did not cause - ${error}`);
+                event.error = { message: getMCPCompatibleErrorMessage(error) };
+                event.isError = true;
+                event.duration =
+                    (event.timestamp &&
+                        new Date().getTime() - event.timestamp.getTime()) ||
+                        0;
+                publishEvent(server, event);
+                throw error;
+            }
+            if (!data) {
+                writeToLog("Warning: Within SDK is unable to find server tracking data. Please ensure you have called track(server, options) before using tool calls.");
+                return { tools };
+            }
+            if (tools.length === 0) {
+                writeToLog("Warning: No tools found in the original list. This is likely due to the tools not being registered before Within.track().");
+                event.error = { message: "No tools were sent to MCP client." };
+                event.isError = true;
+                event.duration =
+                    (event.timestamp &&
+                        new Date().getTime() - event.timestamp.getTime()) ||
+                        0;
+                publishEvent(server, event);
+                return { tools };
+            }
+            // Add context parameter to all existing tools if enableToolCallContext is true
+            if (data.options.enableToolCallContext) {
+                tools = addContextParameterToTools(tools, data.options.customContextDescription);
+            }
+            // Add report_missing tool if enabled
+            if (data.options.enableReportMissing) {
+                const alreadyPresent = tools.some((t) => t?.name === GET_MORE_TOOLS_NAME);
+                if (!alreadyPresent) {
+                    tools.push(getReportMissingToolDescriptor());
+                }
+            }
+            event.response = { tools };
+            event.isError = false;
+            event.duration =
+                (event.timestamp && new Date().getTime() - event.timestamp.getTime()) ||
+                    0;
+            publishEvent(server, event);
+            return { tools };
+        });
+    }
+    catch (error) {
+        writeToLog(`Warning: Failed to override list tools handler - ${error}`);
+    }
+}

package/dist/modules/tracing.d.ts

@@ -0,0 +1,4 @@
+import { HighLevelMCPServerLike, MCPServerLike } from "../types.js";
+export declare function setupListToolsTracing(highLevelServer: HighLevelMCPServerLike): void;
+export declare function setupInitializeTracing(highLevelServer: HighLevelMCPServerLike): void;
+export declare function setupToolCallTracing(server: MCPServerLike): void;

package/dist/modules/tracing.js

@@ -0,0 +1,263 @@
+import { CallToolRequestSchema, InitializeRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { writeToLog } from "./logging.js";
+import { handleReportMissing } from "./tools.js";
+import { getServerTrackingData, handleIdentify, resolveEventTags, resolveEventProperties, } from "./internal.js";
+import { getServerSessionId } from "./session.js";
+import { WithinEventType } from "./constants.js";
+import { publishEvent } from "./eventQueue.js";
+import { getMCPCompatibleErrorMessage } from "./compatibility.js";
+import { captureException } from "./exceptions.js";
+import { addContextParameterToTools } from "./context-parameters.js";
+import { GET_MORE_TOOLS_NAME, getReportMissingToolDescriptor, } from "./tools.js";
+function isToolResultError(result) {
+    return result && typeof result === "object" && result.isError === true;
+}
+// Track if we've already set up list tools tracing per server instance
+const listToolsTracingSetup = new WeakMap();
+export function setupListToolsTracing(highLevelServer) {
+    const server = highLevelServer.server;
+    // Check if server supports tools capability
+    if (!server._capabilities?.tools) {
+        // Server doesn't support tools yet, skip setup
+        return;
+    }
+    // Check if we've already set up tracing for this server instance
+    if (listToolsTracingSetup.get(server)) {
+        return;
+    }
+    const handlers = server._requestHandlers;
+    const originalListToolsHandler = handlers.get("tools/list");
+    // No handler to override yet
+    if (!originalListToolsHandler) {
+        return;
+    }
+    try {
+        server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+            let tools = [];
+            const data = getServerTrackingData(server);
+            let event = {
+                sessionId: getServerSessionId(server, extra),
+                parameters: {
+                    request: request,
+                    extra: extra,
+                },
+                eventType: WithinEventType.mcpToolsList,
+                timestamp: new Date(),
+                redactionFn: data?.options.redactSensitiveInformation,
+            };
+            if (data) {
+                await handleIdentify(server, data, request, extra);
+                event.sessionId = data.sessionId;
+                const resolvedTags = await resolveEventTags(data, request, extra);
+                if (resolvedTags)
+                    event.tags = resolvedTags;
+                const resolvedProperties = await resolveEventProperties(data, request, extra);
+                if (resolvedProperties)
+                    event.properties = resolvedProperties;
+            }
+            try {
+                const originalResponse = (await originalListToolsHandler(request, extra));
+                tools = originalResponse.tools || [];
+                // Inject context parameters AFTER MCP SDK has converted Zod to JSON Schema
+                if (data?.options.enableToolCallContext) {
+                    tools = addContextParameterToTools(tools, data.options.customContextDescription);
+                }
+                // Add get_more_tools tool when enabled
+                if (data?.options.enableReportMissing) {
+                    const alreadyPresent = tools.some((t) => t?.name === GET_MORE_TOOLS_NAME);
+                    if (!alreadyPresent)
+                        tools.push(getReportMissingToolDescriptor());
+                }
+            }
+            catch (error) {
+                // If original handler fails, start with empty tools
+                writeToLog(`Warning: Original list tools handler failed, this suggests an error Within did not cause - ${error}`);
+                event.error = { message: getMCPCompatibleErrorMessage(error) };
+                event.isError = true;
+                event.duration =
+                    (event.timestamp &&
+                        new Date().getTime() - event.timestamp.getTime()) ||
+                        0;
+                publishEvent(server, event);
+                throw error;
+            }
+            if (!data) {
+                writeToLog("Warning: Within SDK is unable to find server tracking data. Please ensure you have called track(server, options) before using tool calls.");
+                return { tools };
+            }
+            if (tools.length === 0) {
+                writeToLog("Warning: No tools found in the original list. This is likely due to the tools not being registered before Within.track().");
+                event.error = { message: "No tools were sent to MCP client." };
+                event.isError = true;
+                event.duration =
+                    (event.timestamp &&
+                        new Date().getTime() - event.timestamp.getTime()) ||
+                        0;
+                publishEvent(server, event);
+                return { tools };
+            }
+            event.response = { tools };
+            event.isError = false;
+            event.duration =
+                (event.timestamp && new Date().getTime() - event.timestamp.getTime()) ||
+                    0;
+            publishEvent(server, event);
+            return { tools };
+        });
+        // Mark as setup successful for this server instance
+        listToolsTracingSetup.set(server, true);
+    }
+    catch (error) {
+        writeToLog(`Warning: Failed to override list tools handler - ${error}`);
+    }
+}
+export function setupInitializeTracing(highLevelServer) {
+    const server = highLevelServer.server;
+    const handlers = server._requestHandlers;
+    const originalInitializeHandler = handlers.get("initialize");
+    if (originalInitializeHandler) {
+        server.setRequestHandler(InitializeRequestSchema, async (request, extra) => {
+            const data = getServerTrackingData(server);
+            if (!data) {
+                writeToLog("Warning: Within SDK is unable to find server tracking data. Please ensure you have called track(server, options) before using tool calls.");
+                return await originalInitializeHandler(request, extra);
+            }
+            const sessionId = getServerSessionId(server, extra);
+            // Try to identify the session
+            await handleIdentify(server, data, request, extra);
+            let event = {
+                sessionId: sessionId,
+                resourceName: request.params?.name || "Unknown Tool Name",
+                eventType: WithinEventType.mcpInitialize,
+                parameters: {
+                    request: request,
+                    extra: extra,
+                },
+                timestamp: new Date(),
+                redactionFn: data.options.redactSensitiveInformation,
+            };
+            const resolvedTags = await resolveEventTags(data, request, extra);
+            if (resolvedTags)
+                event.tags = resolvedTags;
+            const resolvedProperties = await resolveEventProperties(data, request, extra);
+            if (resolvedProperties)
+                event.properties = resolvedProperties;
+            const result = await originalInitializeHandler(request, extra);
+            event.response = result;
+            publishEvent(server, event);
+            return result;
+        });
+    }
+}
+export function setupToolCallTracing(server) {
+    try {
+        const handlers = server._requestHandlers;
+        const originalCallToolHandler = handlers.get("tools/call");
+        const originalInitializeHandler = handlers.get("initialize");
+        if (originalInitializeHandler) {
+            server.setRequestHandler(InitializeRequestSchema, async (request, extra) => {
+                const data = getServerTrackingData(server);
+                if (!data) {
+                    writeToLog("Warning: Within SDK is unable to find server tracking data. Please ensure you have called track(server, options) before using tool calls.");
+                    return await originalInitializeHandler(request, extra);
+                }
+                const sessionId = getServerSessionId(server, extra);
+                // Try to identify the session
+                await handleIdentify(server, data, request, extra);
+                let event = {
+                    sessionId: sessionId,
+                    resourceName: request.params?.name || "Unknown Tool Name",
+                    eventType: WithinEventType.mcpInitialize,
+                    parameters: {
+                        request: request,
+                        extra: extra,
+                    },
+                    timestamp: new Date(),
+                    redactionFn: data.options.redactSensitiveInformation,
+                };
+                const resolvedTags = await resolveEventTags(data, request, extra);
+                if (resolvedTags)
+                    event.tags = resolvedTags;
+                const resolvedProperties = await resolveEventProperties(data, request, extra);
+                if (resolvedProperties)
+                    event.properties = resolvedProperties;
+                const result = await originalInitializeHandler(request, extra);
+                event.response = result;
+                publishEvent(server, event);
+                return result;
+            });
+        }
+        server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+            const data = getServerTrackingData(server);
+            if (!data) {
+                writeToLog("Warning: Within SDK is unable to find server tracking data. Please ensure you have called track(server, options) before using tool calls.");
+                return await originalCallToolHandler?.(request, extra);
+            }
+            const sessionId = getServerSessionId(server, extra);
+            let event = {
+                sessionId: sessionId,
+                resourceName: request.params?.name || "Unknown Tool Name",
+                parameters: {
+                    request: request,
+                    extra: extra,
+                },
+                eventType: WithinEventType.mcpToolsCall,
+                timestamp: new Date(),
+                redactionFn: data.options.redactSensitiveInformation,
+            };
+            try {
+                // Try to identify the session if we haven't already and identify function is provided
+                await handleIdentify(server, data, request, extra);
+                const resolvedTags = await resolveEventTags(data, request, extra);
+                if (resolvedTags)
+                    event.tags = resolvedTags;
+                const resolvedProperties = await resolveEventProperties(data, request, extra);
+                if (resolvedProperties)
+                    event.properties = resolvedProperties;
+                const context = request.params?.arguments?.context;
+                if (data.options.enableToolCallContext &&
+                    typeof context === "string") {
+                    event.userIntent = context;
+                }
+                let result;
+                if (request.params?.name === "get_more_tools") {
+                    result = await handleReportMissing(request.params.arguments.context);
+                    event.userIntent = request.params.arguments.context;
+                }
+                else if (originalCallToolHandler) {
+                    result = await originalCallToolHandler(request, extra);
+                }
+                else {
+                    event.isError = true;
+                    event.error = {
+                        message: `Tool call handler not found for ${request.params?.name || "unknown"}`,
+                    };
+                    event.duration =
+                        (event.timestamp &&
+                            new Date().getTime() - event.timestamp.getTime()) ||
+                            undefined;
+                    publishEvent(server, event);
+                    throw new Error(`Unknown tool: ${request.params?.name || "unknown"}`);
+                }
+                // Check if the result indicates an error
+                if (isToolResultError(result)) {
+                    event.isError = true;
+                    event.error = captureException(result);
+                }
+                event.response = result;
+                publishEvent(server, event);
+                return result;
+            }
+            catch (error) {
+                event.isError = true;
+                event.error = captureException(error);
+                publishEvent(server, event);
+                throw error;
+            }
+        });
+    }
+    catch (error) {
+        writeToLog(`Warning: Failed to setup tool call tracing - ${error}`);
+        throw error;
+    }
+}

package/dist/modules/tracingV2.d.ts

@@ -0,0 +1,2 @@
+import { HighLevelMCPServerLike } from "../types.js";
+export declare function setupTracking(server: HighLevelMCPServerLike): void;