within-sdk 1.0.0

package/dist/modules/tracingV2.js

@@ -0,0 +1,300 @@
+import { writeToLog } from "./logging.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 { handleReportMissing } from "./tools.js";
+import { setupInitializeTracing, setupListToolsTracing } from "./tracing.js";
+import { captureException } from "./exceptions.js";
+import { getToolFunction, hasToolFunction, createWrappedTool, getObjectShape, getLiteralValue, } from "./mcp-sdk-compat.js";
+// WeakMap to track which callbacks have already been wrapped
+const wrappedCallbacks = new WeakMap();
+// Symbol to mark tools that have already been processed
+const WITHIN_PROCESSED = Symbol("__within_processed__");
+function isToolResultError(result) {
+    return result && typeof result === "object" && result.isError === true;
+}
+function addTracingToToolRegistry(tools, server) {
+    return Object.fromEntries(Object.entries(tools).map(([name, tool]) => [
+        name,
+        addTracingToToolCallbackInternal(tool, name, server),
+    ]));
+}
+function setupListenerToRegisteredTools(server) {
+    try {
+        const data = getServerTrackingData(server.server);
+        if (!data) {
+            writeToLog("Warning: Cannot setup listener - no tracking data found");
+            return;
+        }
+        // Create a proxy handler for the _registeredTools object
+        const handler = {
+            set(target, property, value) {
+                try {
+                    // Check if this is a tool being registered (has callback or handler property)
+                    if (typeof property === "string" &&
+                        value &&
+                        typeof value === "object" &&
+                        hasToolFunction(value)) {
+                        // Check if tool has already been processed
+                        if (value[WITHIN_PROCESSED]) {
+                            writeToLog(`Tool ${String(property)} already processed, skipping proxy wrapping`);
+                            // Just set the value without processing
+                            return Reflect.set(target, property, value);
+                        }
+                        // Check if callback/handler is already wrapped
+                        if (wrappedCallbacks.has(getToolFunction(value))) {
+                            writeToLog(`Tool ${String(property)} callback already wrapped, skipping proxy wrapping`);
+                            // Just set the value without processing
+                            return Reflect.set(target, property, value);
+                        }
+                        // Apply tracing to the callback (context injection happens in setupListToolsTracing)
+                        value = addTracingToToolCallbackInternal(value, property, server);
+                        // After adding a tool, try to set up list tools tracing
+                        // This handles the case where track() is called before tools are registered
+                        setupListToolsTracing(server);
+                        // If the tool has an update method, wrap it to handle callback updates
+                        if (typeof value.update === "function") {
+                            const originalUpdate = value.update;
+                            value.update = function (...updateArgs) {
+                                // If callback is being updated, wrap the new callback
+                                // Note: MCP SDK's update() method API uses "callback" property in its interface
+                                if (updateArgs[0]) {
+                                    const updateObj = updateArgs[0];
+                                    if (updateObj.callback &&
+                                        typeof updateObj.callback === "function") {
+                                        const wrappedTool = addTracingToToolCallbackInternal({ callback: updateObj.callback }, property, server);
+                                        updateObj.callback = getToolFunction(wrappedTool);
+                                    }
+                                }
+                                return originalUpdate.apply(this, updateArgs);
+                            };
+                        }
+                    }
+                    // Use Reflect to perform the actual property set
+                    return Reflect.set(target, property, value);
+                }
+                catch (error) {
+                    writeToLog(`Warning: Error in proxy set handler for tool ${String(property)} - ${error}`);
+                    // Fall back to default behavior on error
+                    return Reflect.set(target, property, value);
+                }
+            },
+            get(target, property) {
+                return Reflect.get(target, property);
+            },
+            deleteProperty(target, property) {
+                return Reflect.deleteProperty(target, property);
+            },
+            has(target, property) {
+                return Reflect.has(target, property);
+            },
+        };
+        // Replace _registeredTools with a proxied version
+        const originalTools = server._registeredTools || {};
+        server._registeredTools = new Proxy(originalTools, handler);
+        writeToLog("Successfully set up listener for new tool registrations");
+    }
+    catch (error) {
+        writeToLog(`Warning: Failed to setup listener for registered tools - ${error}`);
+    }
+}
+function addTracingToToolCallbackInternal(tool, toolName, _server) {
+    const originalCallback = getToolFunction(tool);
+    if (wrappedCallbacks.has(originalCallback)) {
+        writeToLog(`Tool ${toolName} callback already wrapped, skipping re-wrap`);
+        return tool;
+    }
+    if (tool[WITHIN_PROCESSED]) {
+        writeToLog(`Tool ${toolName} already processed, skipping re-wrap`);
+        return tool;
+    }
+    const wrappedCallback = async function (...params) {
+        let args;
+        let extra;
+        if (params.length === 2) {
+            args = params[0];
+            extra = params[1];
+        }
+        else {
+            args = undefined;
+            extra = params[0];
+        }
+        const removeContextFromArgs = (args) => {
+            if (args && typeof args === "object" && "context" in args) {
+                const { context: _context, ...argsWithoutContext } = args;
+                return argsWithoutContext;
+            }
+            return args;
+        };
+        const cleanedArgs = toolName === "get_more_tools" ? args : removeContextFromArgs(args);
+        try {
+            if (cleanedArgs === undefined) {
+                const handler = originalCallback;
+                return await handler(extra);
+            }
+            else {
+                const handler = originalCallback;
+                return await handler(cleanedArgs, extra);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                extra.__within_error = error;
+            }
+            throw error;
+        }
+    };
+    // Mark the original callback as wrapped
+    wrappedCallbacks.set(originalCallback, true);
+    // Mark the wrapped callback as well (in case it gets re-wrapped)
+    wrappedCallbacks.set(wrappedCallback, true);
+    // Create a new tool object with the wrapped callback, preserving the property name
+    const wrappedTool = createWrappedTool(tool, wrappedCallback);
+    // Mark the tool as processed
+    wrappedTool[WITHIN_PROCESSED] = true;
+    return wrappedTool;
+}
+function setupToolsCallHandlerWrapping(server) {
+    const lowLevelServer = server.server;
+    // Check if tools/call handler already exists
+    const existingHandler = lowLevelServer._requestHandlers.get("tools/call");
+    if (existingHandler) {
+        const wrappedHandler = createToolsCallWrapper(existingHandler, lowLevelServer);
+        lowLevelServer._requestHandlers.set("tools/call", wrappedHandler);
+    }
+    // Intercept future calls to setRequestHandler for tools registered after track()
+    const originalSetRequestHandler = lowLevelServer.setRequestHandler.bind(lowLevelServer);
+    lowLevelServer.setRequestHandler = function (requestSchema, handler) {
+        const shape = getObjectShape(requestSchema);
+        const method = shape?.method ? getLiteralValue(shape.method) : undefined;
+        // Only wrap tools/call handler
+        if (method === "tools/call") {
+            const wrappedHandler = createToolsCallWrapper(handler, lowLevelServer);
+            return originalSetRequestHandler(requestSchema, wrappedHandler);
+        }
+        // Pass through all other handlers unchanged
+        return originalSetRequestHandler(requestSchema, handler);
+    };
+}
+function createToolsCallWrapper(originalHandler, server) {
+    return async (request, extra) => {
+        const startTime = new Date();
+        let shouldPublishEvent = false;
+        let event = null;
+        try {
+            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.");
+            }
+            else {
+                shouldPublishEvent = true;
+                const sessionId = getServerSessionId(server, extra);
+                event = {
+                    sessionId,
+                    resourceName: request.params?.name || "Unknown Tool",
+                    parameters: { request, extra },
+                    eventType: WithinEventType.mcpToolsCall,
+                    timestamp: startTime,
+                    redactionFn: data.options.redactSensitiveInformation,
+                };
+                const context = request.params?.arguments?.context;
+                if (data.options.enableToolCallContext &&
+                    typeof context === "string") {
+                    event.userIntent = context;
+                }
+                // Identify user session
+                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;
+            }
+        }
+        catch (error) {
+            // If tracing setup fails, log it but continue with tool execution
+            writeToLog(`Warning: Within tracing failed for tool ${request.params?.name}, falling back to original handler - ${error}`);
+        }
+        // If this is get_more_tools, handle it directly without relying on server registration
+        if (request?.params?.name === "get_more_tools") {
+            try {
+                const result = await handleReportMissing({
+                    context: request?.params?.arguments?.context,
+                });
+                if (event && shouldPublishEvent) {
+                    event.userIntent = request?.params?.arguments?.context;
+                    event.response = result;
+                    event.duration = new Date().getTime() - startTime.getTime();
+                    publishEvent(server, event);
+                }
+                return result;
+            }
+            catch (error) {
+                if (event && shouldPublishEvent) {
+                    event.isError = true;
+                    event.error = captureException(error);
+                    event.duration = new Date().getTime() - startTime.getTime();
+                    publishEvent(server, event);
+                }
+                throw error;
+            }
+        }
+        // Execute other tools (even if tracing setup failed)
+        try {
+            const result = await originalHandler(request, extra);
+            if (event && shouldPublishEvent) {
+                // Check for execution errors (SDK converts them to CallToolResult)
+                if (isToolResultError(result)) {
+                    event.isError = true;
+                    // Check if callback captured the original error (has full stack)
+                    const capturedError = extra.__within_error;
+                    if (capturedError) {
+                        // Use captured error from callback
+                        event.error = captureException(capturedError);
+                        delete extra.__within_error; // Cleanup
+                    }
+                    else {
+                        // SDK 1.21.0+ converted error (no stack trace available)
+                        event.error = captureException(result);
+                    }
+                }
+                event.response = result;
+                event.duration = new Date().getTime() - startTime.getTime();
+                publishEvent(server, event);
+            }
+            return result;
+        }
+        catch (error) {
+            // Validation errors, unknown tool, disabled tool
+            if (event && shouldPublishEvent) {
+                event.isError = true;
+                event.error = captureException(error);
+                event.duration = new Date().getTime() - startTime.getTime();
+                publishEvent(server, event);
+            }
+            // Re-throw so Protocol converts to JSONRPC error response
+            throw error;
+        }
+    };
+}
+export function setupTracking(server) {
+    try {
+        const _withinData = getServerTrackingData(server.server);
+        // Setup handler wrapping before any tools are registered
+        setupToolsCallHandlerWrapping(server);
+        setupInitializeTracing(server);
+        // Modify existing callbacks to include tracing and publishing events
+        // This now includes get_more_tools if it was added
+        server._registeredTools = addTracingToToolRegistry(server._registeredTools, server);
+        setupListToolsTracing(server);
+        // Proxy the high level server's registered tools to ensure new tools are injected with tracing
+        // Note: Context parameter injection now happens in setupListToolsTracing (after JSON Schema conversion)
+        setupListenerToRegisteredTools(server);
+    }
+    catch (error) {
+        writeToLog(`Warning: Failed to setup tool call tracing - ${error}`);
+    }
+}

package/dist/modules/truncation.d.ts

@@ -0,0 +1,24 @@
+import { Event, UnredactedEvent } from "../types.js";
+export declare const MAX_DEPTH = 10;
+export declare const MAX_BREADTH = 100;
+export declare const MAX_STRING_LENGTH = 32768;
+export declare const MAX_EVENT_BYTES = 102400;
+/**
+ * Recursively normalizes a value, handling:
+ * - String truncation (> MAX_STRING_LENGTH)
+ * - Non-serializable values (functions, symbols, undefined, BigInt, NaN, Infinity)
+ * - Date objects -> ISO string
+ * - Circular reference detection
+ * - Depth limiting
+ * - Breadth limiting
+ */
+export declare function normalize(input: unknown, depth?: number, maxBreadth?: number, maxStringLength?: number): unknown;
+/**
+ * Applies layered truncation to an event:
+ * 1. Field-level string limits (userIntent, resourceName, metadata fields, error.message)
+ * 2. Error frame limiting (first 25 + last 25 if > 50)
+ * 3. Response content text limits (32KB per text block)
+ * 4. Recursive normalization on user-controlled fields
+ * 5. Size-targeted truncation (progressive depth reduction + last-resort string truncation)
+ */
+export declare function truncateEvent<T extends Event | UnredactedEvent>(event: T): T;

package/dist/modules/truncation.js

@@ -0,0 +1,303 @@
+// --- Constants ---
+export const MAX_DEPTH = 10;
+export const MAX_BREADTH = 100;
+export const MAX_STRING_LENGTH = 32_768; // 32KB
+export const MAX_EVENT_BYTES = 102_400; // 100KB
+// --- Field-level limit constants ---
+const MAX_USER_INTENT_LENGTH = 2_048;
+const MAX_ERROR_MESSAGE_LENGTH = 2_048;
+const MAX_RESOURCE_NAME_LENGTH = 256;
+const MAX_METADATA_LENGTH = 256;
+const MAX_STACK_FRAMES = 50;
+const MAX_CONTENT_TEXT_LENGTH = 32_768;
+// --- Truncation markers ---
+const TRUNCATION_SUFFIX = "...";
+/**
+ * Recursively normalizes a value, handling:
+ * - String truncation (> MAX_STRING_LENGTH)
+ * - Non-serializable values (functions, symbols, undefined, BigInt, NaN, Infinity)
+ * - Date objects -> ISO string
+ * - Circular reference detection
+ * - Depth limiting
+ * - Breadth limiting
+ */
+export function normalize(input, depth = MAX_DEPTH, maxBreadth = MAX_BREADTH, maxStringLength = MAX_STRING_LENGTH) {
+    const memo = new WeakSet();
+    return visit(input, depth, maxBreadth, maxStringLength, memo);
+}
+function visit(value, remainingDepth, maxBreadth, maxStringLength, memo) {
+    // null
+    if (value === null)
+        return null;
+    // undefined
+    if (value === undefined)
+        return "[undefined]";
+    // boolean
+    if (typeof value === "boolean")
+        return value;
+    // number (including NaN, Infinity)
+    if (typeof value === "number") {
+        if (Number.isNaN(value))
+            return "[NaN]";
+        if (!Number.isFinite(value))
+            return value > 0 ? "[Infinity]" : "[-Infinity]";
+        return value;
+    }
+    // bigint
+    if (typeof value === "bigint")
+        return `[BigInt: ${value}]`;
+    // string
+    if (typeof value === "string") {
+        if (value.length > maxStringLength) {
+            return value.slice(0, maxStringLength) + TRUNCATION_SUFFIX;
+        }
+        return value;
+    }
+    // symbol
+    if (typeof value === "symbol") {
+        const desc = value.description;
+        return desc ? `[Symbol(${desc})]` : "[Symbol()]";
+    }
+    // function
+    if (typeof value === "function") {
+        const name = value.name || "<anonymous>";
+        return `[Function: ${name}]`;
+    }
+    // Date
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime())
+            ? "[Invalid Date]"
+            : value.toISOString();
+    }
+    // Objects and arrays from here — need depth/breadth/circular checks
+    if (typeof value === "object") {
+        // Circular reference detection
+        if (memo.has(value))
+            return "[Circular ~]";
+        // Depth limit
+        if (remainingDepth <= 0) {
+            return Array.isArray(value) ? "[Array]" : "[Object]";
+        }
+        memo.add(value);
+        let result;
+        if (Array.isArray(value)) {
+            result = visitArray(value, remainingDepth - 1, maxBreadth, maxStringLength, memo);
+        }
+        else {
+            result = visitObject(value, remainingDepth - 1, maxBreadth, maxStringLength, memo);
+        }
+        memo.delete(value);
+        return result;
+    }
+    // Fallback: coerce to string
+    return String(value);
+}
+function visitArray(arr, remainingDepth, maxBreadth, maxStringLength, memo) {
+    const result = [];
+    for (let i = 0; i < arr.length; i++) {
+        if (i >= maxBreadth) {
+            result.push("[MaxProperties ~]");
+            break;
+        }
+        result.push(visit(arr[i], remainingDepth, maxBreadth, maxStringLength, memo));
+    }
+    return result;
+}
+function visitObject(obj, remainingDepth, maxBreadth, maxStringLength, memo) {
+    const result = {};
+    const keys = Object.keys(obj);
+    let count = 0;
+    for (const key of keys) {
+        if (count >= maxBreadth) {
+            result["..."] = "[MaxProperties ~]";
+            break;
+        }
+        // Skip undefined values — matches JSON.stringify behavior (omits undefined properties)
+        if (obj[key] === undefined)
+            continue;
+        result[key] = visit(obj[key], remainingDepth, maxBreadth, maxStringLength, memo);
+        count++;
+    }
+    return result;
+}
+// --- Field-level truncation helpers ---
+function truncateString(str, maxLength) {
+    if (str == null)
+        return str;
+    if (str.length <= maxLength)
+        return str;
+    return str.slice(0, maxLength) + TRUNCATION_SUFFIX;
+}
+function truncateStackFrames(frames) {
+    if (!frames || frames.length <= MAX_STACK_FRAMES)
+        return frames;
+    const half = Math.floor(MAX_STACK_FRAMES / 2);
+    return [...frames.slice(0, half), ...frames.slice(-half)];
+}
+function truncateResponseContent(response) {
+    if (response == null || typeof response !== "object")
+        return response;
+    const result = { ...response };
+    if (Array.isArray(result.content)) {
+        result.content = result.content.map((block) => {
+            if (block?.type === "text" &&
+                typeof block.text === "string" &&
+                block.text.length > MAX_CONTENT_TEXT_LENGTH) {
+                return {
+                    ...block,
+                    text: block.text.slice(0, MAX_CONTENT_TEXT_LENGTH) + TRUNCATION_SUFFIX,
+                };
+            }
+            return block;
+        });
+    }
+    return result;
+}
+/**
+ * Calculates the UTF-8 byte size of a JSON-serialized value.
+ */
+const textEncoder = new TextEncoder();
+function jsonByteSize(value) {
+    return textEncoder.encode(JSON.stringify(value)).length;
+}
+/**
+ * Finds and truncates the largest string values in an object to fit within a byte budget.
+ * Last-resort mechanism when depth reduction alone isn't enough.
+ * Iterates until the result fits or no further reduction is possible.
+ */
+function truncateLargestFields(obj, maxBytes) {
+    let result = structuredClone(obj);
+    for (let attempt = 0; attempt < 10; attempt++) {
+        const currentSize = jsonByteSize(result);
+        if (currentSize <= maxBytes)
+            return result;
+        const excess = currentSize - maxBytes;
+        // Find all string values and their sizes, sorted largest first
+        const stringPaths = [];
+        collectStringPaths(result, [], stringPaths);
+        stringPaths.sort((a, b) => b.length - a.length);
+        if (stringPaths.length === 0)
+            break; // no strings left to truncate
+        // Distribute the reduction across the largest strings
+        let remaining = excess + 200; // buffer for JSON overhead from added "..." suffixes
+        let truncated = false;
+        for (const { path, length } of stringPaths) {
+            if (remaining <= 0)
+                break;
+            const reduction = Math.min(remaining, Math.floor(length * 0.5));
+            if (reduction < 10)
+                continue; // not worth truncating tiny strings
+            const newLength = length - reduction;
+            setNestedValue(result, path, getNestedValue(result, path).slice(0, newLength) + TRUNCATION_SUFFIX);
+            remaining -= reduction;
+            truncated = true;
+        }
+        if (!truncated)
+            break; // no progress possible
+    }
+    return result;
+}
+function collectStringPaths(obj, currentPath, results) {
+    if (typeof obj === "string" && obj.length > 100) {
+        results.push({ path: [...currentPath], length: obj.length });
+        return;
+    }
+    if (Array.isArray(obj)) {
+        obj.forEach((item, i) => collectStringPaths(item, [...currentPath, String(i)], results));
+        return;
+    }
+    if (obj != null && typeof obj === "object") {
+        for (const [key, value] of Object.entries(obj)) {
+            collectStringPaths(value, [...currentPath, key], results);
+        }
+    }
+}
+function getNestedValue(obj, path) {
+    let current = obj;
+    for (const key of path)
+        current = current[key];
+    return current;
+}
+function setNestedValue(obj, path, value) {
+    let current = obj;
+    for (let i = 0; i < path.length - 1; i++)
+        current = current[path[i]];
+    current[path[path.length - 1]] = value;
+}
+/**
+ * Ensures an event fits within MAX_EVENT_BYTES by progressively reducing
+ * normalization depth, then truncating largest string fields as a last resort.
+ */
+function truncateToSize(event) {
+    // Check if already within budget
+    if (jsonByteSize(event) <= MAX_EVENT_BYTES)
+        return event;
+    // Progressive depth reduction
+    for (let depth = MAX_DEPTH - 1; depth >= 1; depth--) {
+        const reduced = { ...event };
+        if (reduced.parameters != null)
+            reduced.parameters = normalize(reduced.parameters, depth);
+        if (reduced.response != null)
+            reduced.response = normalize(reduced.response, depth);
+        if (reduced.identifyActorData != null)
+            reduced.identifyActorData = normalize(reduced.identifyActorData, depth);
+        if (reduced.error != null)
+            reduced.error = normalize(reduced.error, depth);
+        if (jsonByteSize(reduced) <= MAX_EVENT_BYTES)
+            return reduced;
+    }
+    // Last resort: truncate largest string fields
+    const minimal = { ...event };
+    if (minimal.parameters != null)
+        minimal.parameters = normalize(minimal.parameters, 1);
+    if (minimal.response != null)
+        minimal.response = normalize(minimal.response, 1);
+    if (minimal.identifyActorData != null)
+        minimal.identifyActorData = normalize(minimal.identifyActorData, 1);
+    if (minimal.error != null)
+        minimal.error = normalize(minimal.error, 1);
+    return truncateLargestFields(minimal, MAX_EVENT_BYTES);
+}
+/**
+ * Applies layered truncation to an event:
+ * 1. Field-level string limits (userIntent, resourceName, metadata fields, error.message)
+ * 2. Error frame limiting (first 25 + last 25 if > 50)
+ * 3. Response content text limits (32KB per text block)
+ * 4. Recursive normalization on user-controlled fields
+ * 5. Size-targeted truncation (progressive depth reduction + last-resort string truncation)
+ */
+export function truncateEvent(event) {
+    const result = { ...event };
+    // Layer 1: Field-level string limits
+    result.userIntent = truncateString(result.userIntent, MAX_USER_INTENT_LENGTH);
+    result.resourceName = truncateString(result.resourceName, MAX_RESOURCE_NAME_LENGTH);
+    result.serverName = truncateString(result.serverName, MAX_METADATA_LENGTH);
+    result.serverVersion = truncateString(result.serverVersion, MAX_METADATA_LENGTH);
+    result.clientName = truncateString(result.clientName, MAX_METADATA_LENGTH);
+    result.clientVersion = truncateString(result.clientVersion, MAX_METADATA_LENGTH);
+    // Error field limits
+    if (result.error != null && typeof result.error === "object") {
+        result.error = { ...result.error };
+        result.error.message = truncateString(result.error.message, MAX_ERROR_MESSAGE_LENGTH);
+        if (result.error.frames !== undefined) {
+            result.error.frames = truncateStackFrames(result.error.frames);
+        }
+    }
+    // Response content text limits
+    result.response = truncateResponseContent(result.response);
+    // Layer 2: Recursive normalization on user-controlled fields
+    if (result.parameters != null) {
+        result.parameters = normalize(result.parameters);
+    }
+    if (result.response != null) {
+        result.response = normalize(result.response);
+    }
+    if (result.identifyActorData != null) {
+        result.identifyActorData = normalize(result.identifyActorData);
+    }
+    if (result.error != null) {
+        result.error = normalize(result.error);
+    }
+    // Layer 3: Size-targeted normalization
+    return truncateToSize(result);
+}

package/dist/modules/validation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Validates and filters a tags object against Within tag constraints.
+ * Invalid entries are logged as warnings and dropped.
+ * Returns null if no valid entries remain.
+ */
+export declare function validateTags(tags: Record<string, string>): Record<string, string> | null;

package/dist/modules/validation.js

@@ -0,0 +1,51 @@
+import { writeToLog } from "./logging.js";
+const TAG_KEY_REGEX = /^[a-zA-Z0-9$_.:\- ]+$/;
+const MAX_TAG_KEY_LENGTH = 32;
+const MAX_TAG_VALUE_LENGTH = 200;
+const MAX_TAG_ENTRIES = 50;
+/**
+ * Validates and filters a tags object against Within tag constraints.
+ * Invalid entries are logged as warnings and dropped.
+ * Returns null if no valid entries remain.
+ */
+export function validateTags(tags) {
+    const entries = Object.entries(tags);
+    if (entries.length === 0) {
+        return null;
+    }
+    const valid = [];
+    for (const [key, value] of entries) {
+        // Key validation
+        if (typeof key !== "string" || !TAG_KEY_REGEX.test(key)) {
+            writeToLog(`Dropping invalid tag: "${String(key)}" — key contains invalid characters or is empty`);
+            continue;
+        }
+        if (key.length > MAX_TAG_KEY_LENGTH) {
+            writeToLog(`Dropping invalid tag: "${key}" — key exceeds max length of ${MAX_TAG_KEY_LENGTH}`);
+            continue;
+        }
+        // Value validation
+        if (typeof value !== "string") {
+            writeToLog(`Dropping invalid tag: "${key}" — non-string value (got ${typeof value})`);
+            continue;
+        }
+        if (value.length > MAX_TAG_VALUE_LENGTH) {
+            writeToLog(`Dropping invalid tag: "${key}" — value exceeds max length of ${MAX_TAG_VALUE_LENGTH}`);
+            continue;
+        }
+        if (value.includes("\n")) {
+            writeToLog(`Dropping invalid tag: "${key}" — value contains newline character`);
+            continue;
+        }
+        valid.push([key, value]);
+    }
+    if (valid.length === 0) {
+        return null;
+    }
+    if (valid.length > MAX_TAG_ENTRIES) {
+        const dropped = valid.length - MAX_TAG_ENTRIES;
+        writeToLog(`Dropping ${dropped} tag(s) — exceeds maximum of ${MAX_TAG_ENTRIES} entries per event`);
+        valid.length = MAX_TAG_ENTRIES;
+    }
+    return Object.fromEntries(valid);
+}