@mcpmesh/sdk 0.8.0-beta.1

package/dist/template.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Template rendering for LLM system prompts using Handlebars.
+ *
+ * Supports both inline templates and file-based templates using the `file://` prefix.
+ * Handlebars was chosen for its popularity in the TypeScript/JavaScript ecosystem.
+ *
+ * @example
+ * ```typescript
+ * // Inline template
+ * const rendered = await renderTemplate(
+ *   "Hello, {{name}}! You have {{count}} items.",
+ *   { name: "User", count: 5 }
+ * );
+ *
+ * // File-based template
+ * const rendered = await renderTemplate(
+ *   "file://prompts/assistant.hbs",
+ *   { user: "John", context: { topic: "math" } }
+ * );
+ * ```
+ */
+import Handlebars from "handlebars";
+/**
+ * Check if a template string is a file reference.
+ */
+export declare function isFileTemplate(template: string): boolean;
+/**
+ * Extract the file path from a file:// template reference.
+ */
+export declare function extractFilePath(template: string): string;
+/**
+ * Render a template with the given context.
+ *
+ * @param template - Template string (inline) or file reference ("file://path/to/template.hbs")
+ * @param context - Context object for template variables
+ * @returns Rendered string
+ *
+ * @example
+ * ```typescript
+ * // Inline template
+ * const result = await renderTemplate("Hello {{name}}!", { name: "World" });
+ * // => "Hello World!"
+ *
+ * // File template (prompts/assistant.hbs)
+ * const result = await renderTemplate("file://prompts/assistant.hbs", {
+ *   user: { name: "John" },
+ *   preferences: ["math", "science"],
+ * });
+ * ```
+ */
+export declare function renderTemplate(template: string, context?: Record<string, unknown>): Promise<string>;
+/**
+ * Clear the template cache.
+ * Useful for development/testing when templates are being modified.
+ */
+export declare function clearTemplateCache(): void;
+/**
+ * Register a custom Handlebars helper.
+ *
+ * @param name - Helper name
+ * @param fn - Helper function
+ *
+ * @example
+ * ```typescript
+ * registerHelper("uppercase", (str) => str.toUpperCase());
+ * // Template: "Hello {{uppercase name}}!"
+ * // Context: { name: "world" }
+ * // Result: "Hello WORLD!"
+ * ```
+ */
+export declare function registerHelper(name: string, fn: Handlebars.HelperDelegate): void;
+/**
+ * Register a partial template.
+ *
+ * @param name - Partial name
+ * @param template - Template string
+ *
+ * @example
+ * ```typescript
+ * registerPartial("header", "<h1>{{title}}</h1>");
+ * // Template: "{{> header title='Welcome'}}"
+ * // Result: "<h1>Welcome</h1>"
+ * ```
+ */
+export declare function registerPartial(name: string, template: string): void;
+//# sourceMappingURL=template.d.ts.map

package/dist/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,UAAU,MAAM,YAAY,CAAC;AAUpC;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKxD;AAuED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,UAAU,CAAC,cAAc,GAC5B,IAAI,CAEN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEpE"}

package/dist/template.js

@@ -0,0 +1,206 @@
+/**
+ * Template rendering for LLM system prompts using Handlebars.
+ *
+ * Supports both inline templates and file-based templates using the `file://` prefix.
+ * Handlebars was chosen for its popularity in the TypeScript/JavaScript ecosystem.
+ *
+ * @example
+ * ```typescript
+ * // Inline template
+ * const rendered = await renderTemplate(
+ *   "Hello, {{name}}! You have {{count}} items.",
+ *   { name: "User", count: 5 }
+ * );
+ *
+ * // File-based template
+ * const rendered = await renderTemplate(
+ *   "file://prompts/assistant.hbs",
+ *   { user: "John", context: { topic: "math" } }
+ * );
+ * ```
+ */
+import Handlebars from "handlebars";
+import * as fs from "fs/promises";
+import * as path from "path";
+/**
+ * Cache for compiled Handlebars templates.
+ * Key is the template string (for inline) or resolved file path (for file://).
+ */
+const templateCache = new Map();
+/**
+ * Check if a template string is a file reference.
+ */
+export function isFileTemplate(template) {
+    return template.startsWith("file://");
+}
+/**
+ * Extract the file path from a file:// template reference.
+ */
+export function extractFilePath(template) {
+    if (!isFileTemplate(template)) {
+        throw new Error(`Not a file template: ${template}`);
+    }
+    return template.slice(7); // Remove "file://" prefix
+}
+/**
+ * Resolve a file path relative to the caller's location.
+ * If the path is absolute, it's returned as-is.
+ * If relative, it's resolved from the current working directory.
+ */
+function resolveTemplatePath(filePath) {
+    if (path.isAbsolute(filePath)) {
+        return filePath;
+    }
+    return path.resolve(process.cwd(), filePath);
+}
+/**
+ * Load a template file and return its contents.
+ */
+async function loadTemplateFile(filePath) {
+    const resolvedPath = resolveTemplatePath(filePath);
+    try {
+        return await fs.readFile(resolvedPath, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new Error(`Template file not found: ${resolvedPath}`);
+        }
+        throw err;
+    }
+}
+/**
+ * Get or compile a Handlebars template.
+ * Templates are cached by their source (inline string or resolved absolute file path).
+ */
+async function getCompiledTemplate(template) {
+    // Determine cache key - use absolute path for file templates
+    let cacheKey;
+    let templateContent;
+    if (isFileTemplate(template)) {
+        const filePath = extractFilePath(template);
+        const absolutePath = resolveTemplatePath(filePath);
+        cacheKey = absolutePath; // Use absolute path as cache key
+        // Check cache first
+        const cached = templateCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        templateContent = await loadTemplateFile(filePath);
+    }
+    else {
+        cacheKey = template; // Use inline template as cache key
+        // Check cache first
+        const cached = templateCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        templateContent = template;
+    }
+    // Compile and cache
+    const compiled = Handlebars.compile(templateContent);
+    templateCache.set(cacheKey, compiled);
+    return compiled;
+}
+/**
+ * Render a template with the given context.
+ *
+ * @param template - Template string (inline) or file reference ("file://path/to/template.hbs")
+ * @param context - Context object for template variables
+ * @returns Rendered string
+ *
+ * @example
+ * ```typescript
+ * // Inline template
+ * const result = await renderTemplate("Hello {{name}}!", { name: "World" });
+ * // => "Hello World!"
+ *
+ * // File template (prompts/assistant.hbs)
+ * const result = await renderTemplate("file://prompts/assistant.hbs", {
+ *   user: { name: "John" },
+ *   preferences: ["math", "science"],
+ * });
+ * ```
+ */
+export async function renderTemplate(template, context = {}) {
+    const compiled = await getCompiledTemplate(template);
+    return compiled(context);
+}
+/**
+ * Clear the template cache.
+ * Useful for development/testing when templates are being modified.
+ */
+export function clearTemplateCache() {
+    templateCache.clear();
+}
+/**
+ * Register a custom Handlebars helper.
+ *
+ * @param name - Helper name
+ * @param fn - Helper function
+ *
+ * @example
+ * ```typescript
+ * registerHelper("uppercase", (str) => str.toUpperCase());
+ * // Template: "Hello {{uppercase name}}!"
+ * // Context: { name: "world" }
+ * // Result: "Hello WORLD!"
+ * ```
+ */
+export function registerHelper(name, fn) {
+    Handlebars.registerHelper(name, fn);
+}
+/**
+ * Register a partial template.
+ *
+ * @param name - Partial name
+ * @param template - Template string
+ *
+ * @example
+ * ```typescript
+ * registerPartial("header", "<h1>{{title}}</h1>");
+ * // Template: "{{> header title='Welcome'}}"
+ * // Result: "<h1>Welcome</h1>"
+ * ```
+ */
+export function registerPartial(name, template) {
+    Handlebars.registerPartial(name, template);
+}
+// Register common helpers
+/**
+ * JSON helper - stringify an object
+ * Usage: {{json data}}
+ */
+registerHelper("json", (context) => {
+    return JSON.stringify(context, null, 2);
+});
+/**
+ * Join helper - join array elements
+ * Usage: {{join items ", "}}
+ */
+registerHelper("join", (items, separator) => {
+    if (!Array.isArray(items))
+        return "";
+    return items.join(typeof separator === "string" ? separator : ", ");
+});
+/**
+ * Eq helper - equality check
+ * Usage: {{#if (eq a b)}}...{{/if}}
+ */
+registerHelper("eq", (a, b) => {
+    return a === b;
+});
+/**
+ * Ne helper - not equal check
+ * Usage: {{#if (ne a b)}}...{{/if}}
+ */
+registerHelper("ne", (a, b) => {
+    return a !== b;
+});
+/**
+ * Default helper - provide default value
+ * Usage: {{default value "fallback"}}
+ */
+registerHelper("default", (value, defaultValue) => {
+    return value ?? defaultValue;
+});
+//# sourceMappingURL=template.js.map

package/dist/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"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"}

package/dist/tracing.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Distributed tracing for MCP Mesh TypeScript SDK.
+ *
+ * Publishes trace spans to Redis via Rust core for distributed tracing.
+ * Uses the same trace format as Python SDK for interoperability.
+ */
+export interface TraceContext {
+    traceId: string;
+    parentSpanId: string | null;
+}
+export interface AgentMetadata {
+    agentId: string;
+    agentName: string;
+    agentNamespace: string;
+    agentHostname: string;
+    agentIp: string;
+    agentPort: number;
+    agentEndpoint: string;
+}
+/**
+ * Initialize the tracing system.
+ *
+ * Must be called before publishing spans. Checks if tracing is enabled
+ * and initializes the Redis connection via Rust core.
+ *
+ * @returns true if tracing is enabled and ready, false otherwise.
+ */
+export declare function initTracing(agentMetadata: AgentMetadata): Promise<boolean>;
+/**
+ * Check if tracing is currently available.
+ */
+export declare function isTracingAvailable(): Promise<boolean>;
+/**
+ * Generate a new trace ID (OpenTelemetry compliant).
+ *
+ * @returns 32-character hex string (128-bit trace ID per OTel spec)
+ */
+export declare function generateTraceId(): string;
+/**
+ * Generate a new span ID (OpenTelemetry compliant).
+ *
+ * @returns 16-character hex string (64-bit span ID per OTel spec)
+ */
+export declare function generateSpanId(): string;
+/**
+ * Parse trace context from HTTP headers.
+ *
+ * Looks for X-Trace-ID and X-Parent-Span headers (matching Python SDK).
+ */
+export declare function parseTraceContext(headers: Record<string, string | undefined>): TraceContext | null;
+/**
+ * Create trace headers to propagate context to downstream calls.
+ * Uses Python SDK convention: X-Trace-ID, X-Parent-Span
+ */
+export declare function createTraceHeaders(traceId: string, spanId: string): Record<string, string>;
+/**
+ * Span data for publishing.
+ */
+export interface SpanData {
+    traceId: string;
+    spanId: string;
+    parentSpan: string | null;
+    functionName: string;
+    startTime: number;
+    endTime: number;
+    durationMs: number;
+    success: boolean;
+    error: string | null;
+    resultType: string;
+    argsCount: number;
+    kwargsCount: number;
+    dependencies: string[];
+    injectedDependencies: number;
+    meshPositions: number[];
+}
+/**
+ * Publish a trace span to Redis via Rust core.
+ *
+ * Non-blocking - silently handles failures to never break agent operations.
+ */
+export declare function publishTraceSpan(span: SpanData): Promise<boolean>;
+/**
+ * Create a traced wrapper for a tool execution function.
+ *
+ * Automatically captures timing, success/error status, and publishes spans.
+ */
+export declare function createTracedExecutor<TArgs, TResult>(functionName: string, dependencies: string[], injectedDependencies: number, executor: (args: TArgs, traceContext: TraceContext | null) => Promise<TResult>): (args: TArgs, traceContext: TraceContext | null) => Promise<TResult>;
+//# sourceMappingURL=tracing.d.ts.map

package/dist/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAGD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAOD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CA0BhF;AAED;;GAEG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC,CAG3D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC1C,YAAY,GAAG,IAAI,CAWrB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKxB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAsCvE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EACjD,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EAAE,EACtB,oBAAoB,EAAE,MAAM,EAC5B,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,GAC7E,CAAC,IAAI,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAoDtE"}

package/dist/tracing.js

@@ -0,0 +1,193 @@
+/**
+ * Distributed tracing for MCP Mesh TypeScript SDK.
+ *
+ * Publishes trace spans to Redis via Rust core for distributed tracing.
+ * Uses the same trace format as Python SDK for interoperability.
+ */
+import { randomUUID } from "crypto";
+import { isTracingEnabled, initTracePublisher, publishSpan, isTracePublisherAvailable, } from "@mcpmesh/core";
+// Global state
+let tracingEnabled = false;
+let tracingInitialized = false;
+let currentAgentMetadata = null;
+/**
+ * Initialize the tracing system.
+ *
+ * Must be called before publishing spans. Checks if tracing is enabled
+ * and initializes the Redis connection via Rust core.
+ *
+ * @returns true if tracing is enabled and ready, false otherwise.
+ */
+export async function initTracing(agentMetadata) {
+    if (tracingInitialized) {
+        return tracingEnabled;
+    }
+    tracingInitialized = true;
+    currentAgentMetadata = agentMetadata;
+    // Check if tracing is enabled via env var
+    tracingEnabled = isTracingEnabled();
+    if (!tracingEnabled) {
+        console.log("Distributed tracing: disabled");
+        return false;
+    }
+    console.log("Distributed tracing: enabled");
+    // Initialize Rust core trace publisher
+    const available = await initTracePublisher();
+    if (!available) {
+        console.warn("Rust core trace publisher initialization failed");
+        tracingEnabled = false;
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if tracing is currently available.
+ */
+export async function isTracingAvailable() {
+    if (!tracingEnabled)
+        return false;
+    return await isTracePublisherAvailable();
+}
+/**
+ * Generate a new trace ID (OpenTelemetry compliant).
+ *
+ * @returns 32-character hex string (128-bit trace ID per OTel spec)
+ */
+export function generateTraceId() {
+    return randomUUID().replace(/-/g, "");
+}
+/**
+ * Generate a new span ID (OpenTelemetry compliant).
+ *
+ * @returns 16-character hex string (64-bit span ID per OTel spec)
+ */
+export function generateSpanId() {
+    return randomUUID().replace(/-/g, "").slice(0, 16);
+}
+/**
+ * Parse trace context from HTTP headers.
+ *
+ * Looks for X-Trace-ID and X-Parent-Span headers (matching Python SDK).
+ */
+export function parseTraceContext(headers) {
+    // Check both cases: X-Trace-ID (Python) and X-Trace-Id (legacy)
+    const traceId = headers["x-trace-id"] || headers["X-Trace-ID"] || headers["X-Trace-Id"];
+    if (!traceId)
+        return null;
+    return {
+        traceId,
+        // Check both: X-Parent-Span (Python) and X-Parent-Span-Id (legacy)
+        parentSpanId: headers["x-parent-span"] || headers["X-Parent-Span"] ||
+            headers["x-parent-span-id"] || headers["X-Parent-Span-Id"] || null,
+    };
+}
+/**
+ * Create trace headers to propagate context to downstream calls.
+ * Uses Python SDK convention: X-Trace-ID, X-Parent-Span
+ */
+export function createTraceHeaders(traceId, spanId) {
+    return {
+        "X-Trace-ID": traceId,
+        "X-Parent-Span": spanId,
+    };
+}
+/**
+ * Publish a trace span to Redis via Rust core.
+ *
+ * Non-blocking - silently handles failures to never break agent operations.
+ */
+export async function publishTraceSpan(span) {
+    if (!tracingEnabled || !currentAgentMetadata) {
+        return false;
+    }
+    try {
+        // Convert span to string map for Redis storage
+        const spanMap = {
+            trace_id: span.traceId,
+            span_id: span.spanId,
+            parent_span: span.parentSpan ?? "null",
+            function_name: span.functionName,
+            start_time: String(span.startTime),
+            end_time: String(span.endTime),
+            duration_ms: span.durationMs.toFixed(2),
+            success: String(span.success),
+            error: span.error ?? "null",
+            result_type: span.resultType,
+            args_count: String(span.argsCount),
+            kwargs_count: String(span.kwargsCount),
+            dependencies: JSON.stringify(span.dependencies),
+            injected_dependencies: String(span.injectedDependencies),
+            mesh_positions: JSON.stringify(span.meshPositions),
+            // Agent metadata
+            agent_id: currentAgentMetadata.agentId,
+            agent_name: currentAgentMetadata.agentName,
+            agent_namespace: currentAgentMetadata.agentNamespace,
+            agent_hostname: currentAgentMetadata.agentHostname,
+            agent_ip: currentAgentMetadata.agentIp,
+            agent_port: String(currentAgentMetadata.agentPort),
+            agent_endpoint: currentAgentMetadata.agentEndpoint,
+        };
+        return await publishSpan(spanMap);
+    }
+    catch (err) {
+        // Non-blocking - never fail agent operations due to trace publishing
+        return false;
+    }
+}
+/**
+ * Create a traced wrapper for a tool execution function.
+ *
+ * Automatically captures timing, success/error status, and publishes spans.
+ */
+export function createTracedExecutor(functionName, dependencies, injectedDependencies, executor) {
+    return async (args, traceContext) => {
+        if (!tracingEnabled) {
+            return executor(args, traceContext);
+        }
+        // Generate span context
+        const traceId = traceContext?.traceId ?? generateTraceId();
+        const spanId = generateSpanId();
+        const parentSpan = traceContext?.parentSpanId ?? null;
+        const startTime = Date.now() / 1000;
+        let success = true;
+        let error = null;
+        let resultType = "unknown";
+        try {
+            // Execute with trace context for propagation
+            const newContext = { traceId, parentSpanId: spanId };
+            const result = await executor(args, newContext);
+            resultType = typeof result;
+            return result;
+        }
+        catch (err) {
+            success = false;
+            error = err instanceof Error ? err.message : String(err);
+            throw err;
+        }
+        finally {
+            const endTime = Date.now() / 1000;
+            const durationMs = (endTime - startTime) * 1000;
+            // Publish span asynchronously (fire and forget)
+            publishTraceSpan({
+                traceId,
+                spanId,
+                parentSpan,
+                functionName,
+                startTime,
+                endTime,
+                durationMs,
+                success,
+                error,
+                resultType,
+                argsCount: 0,
+                kwargsCount: typeof args === "object" && args !== null ? Object.keys(args).length : 0,
+                dependencies,
+                injectedDependencies,
+                meshPositions: [],
+            }).catch(() => {
+                // Silently ignore publish errors
+            });
+        }
+    };
+}
+//# sourceMappingURL=tracing.js.map

package/dist/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"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"}