@mcpmesh/sdk 0.8.0-beta.1

package/dist/config.js

@@ -0,0 +1,60 @@
+/**
+ * Configuration utilities for MCP Mesh agents.
+ *
+ * All configuration resolution is delegated to Rust core for consistency
+ * across all language SDKs. Priority: ENV > config > defaults
+ *
+ * Defaults are also sourced from Rust core to ensure single source of truth.
+ */
+import { randomBytes } from "crypto";
+import { resolveConfig as rustResolveConfig, resolveConfigInt, getDefault, } from "@mcpmesh/core";
+// TypeScript-specific defaults (not in Rust core)
+const TS_DEFAULTS = {
+    version: "1.0.0",
+    description: "",
+};
+/**
+ * Generate a short UUID suffix (8 hex chars) for agent IDs.
+ */
+export function generateAgentIdSuffix() {
+    return randomBytes(4).toString("hex");
+}
+/**
+ * Resolve configuration with environment variable precedence via Rust core.
+ *
+ * All resolution is delegated to Rust core to ensure consistent behavior
+ * across Python and TypeScript SDKs.
+ *
+ * Priority (handled by Rust): ENV > config > defaults
+ *
+ * Environment variables:
+ * - MCP_MESH_AGENT_NAME: Override agent name
+ * - MCP_MESH_HTTP_HOST: Override host (auto-detected if not set)
+ * - MCP_MESH_HTTP_PORT: Override port
+ * - MCP_MESH_NAMESPACE: Override namespace
+ * - MCP_MESH_REGISTRY_URL: Override registry URL
+ * - MCP_MESH_HEALTH_INTERVAL: Override heartbeat interval
+ */
+export function resolveConfig(config) {
+    // All config resolution via Rust core - ensures consistent ENV > param > default
+    const resolvedName = rustResolveConfig("agent_name", config.name);
+    const resolvedPort = resolveConfigInt("http_port", config.port) ?? config.port;
+    const resolvedHost = rustResolveConfig("http_host", config.host ?? null);
+    const resolvedNamespace = rustResolveConfig("namespace", config.namespace ?? null);
+    const resolvedRegistryUrl = rustResolveConfig("registry_url", config.registryUrl ?? null);
+    // Get heartbeat interval with fallback to Rust core default
+    const healthIntervalDefault = parseInt(getDefault("health_interval") ?? "5", 10);
+    const resolvedHeartbeatInterval = resolveConfigInt("health_interval", config.heartbeatInterval ?? null) ??
+        healthIntervalDefault;
+    return {
+        name: resolvedName,
+        version: config.version ?? TS_DEFAULTS.version,
+        description: config.description ?? TS_DEFAULTS.description,
+        port: resolvedPort,
+        host: resolvedHost,
+        namespace: resolvedNamespace,
+        registryUrl: resolvedRegistryUrl,
+        heartbeatInterval: resolvedHeartbeatInterval,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,EACL,aAAa,IAAI,iBAAiB,EAClC,gBAAgB,EAChB,UAAU,GACX,MAAM,eAAe,CAAC;AAEvB,kDAAkD;AAClD,MAAM,WAAW,GAAG;IAClB,OAAO,EAAE,OAAO;IAChB,WAAW,EAAE,EAAE;CACP,CAAC;AAEX;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,MAAmB;IAC/C,iFAAiF;IACjF,MAAM,YAAY,GAAG,iBAAiB,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAClE,MAAM,YAAY,GAAG,gBAAgB,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC;IAC/E,MAAM,YAAY,GAAG,iBAAiB,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;IACzE,MAAM,iBAAiB,GAAG,iBAAiB,CACzC,WAAW,EACX,MAAM,CAAC,SAAS,IAAI,IAAI,CACzB,CAAC;IACF,MAAM,mBAAmB,GAAG,iBAAiB,CAC3C,cAAc,EACd,MAAM,CAAC,WAAW,IAAI,IAAI,CAC3B,CAAC;IAEF,4DAA4D;IAC5D,MAAM,qBAAqB,GAAG,QAAQ,CAAC,UAAU,CAAC,iBAAiB,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;IACjF,MAAM,yBAAyB,GAC7B,gBAAgB,CAAC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,IAAI,IAAI,CAAC;QACrE,qBAAqB,CAAC;IAExB,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,WAAW,CAAC,OAAO;QAC9C,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,WAAW,CAAC,WAAW;QAC1D,IAAI,EAAE,YAAY;QAClB,IAAI,EAAE,YAAY;QAClB,SAAS,EAAE,iBAAiB;QAC5B,WAAW,EAAE,mBAAmB;QAChC,iBAAiB,EAAE,yBAAyB;KAC7C,CAAC;AACJ,CAAC"}

package/dist/debug.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Debug logging utilities for MCP Mesh SDK.
+ *
+ * Debug output is controlled by standard MCP Mesh environment variables:
+ * - MCP_MESH_LOG_LEVEL=DEBUG - Enable debug output (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+ * - MCP_MESH_DEBUG_MODE=true - Force DEBUG level
+ *
+ * @example
+ * ```bash
+ * # Enable debug output
+ * MCP_MESH_LOG_LEVEL=DEBUG node my-agent.js
+ *
+ * # Or use debug mode
+ * MCP_MESH_DEBUG_MODE=true node my-agent.js
+ * ```
+ */
+type DebugCategory = "llm" | "llm-provider" | "sse" | "template" | "agent" | "registry" | "provider-handler-registry" | "provider-handler" | "claude-handler" | "openai-handler" | "gemini-handler";
+/**
+ * Create a debug logger for a specific category.
+ *
+ * @param category - Debug category (e.g., "llm", "sse", "template")
+ * @returns Debug function that only logs when category is enabled
+ *
+ * @example
+ * ```typescript
+ * const debug = createDebug("llm");
+ * debug("Executing tool", { name: "add" });
+ * // Only logs if MCP_MESH_LOG_LEVEL=DEBUG or MCP_MESH_DEBUG_MODE=true
+ * ```
+ */
+export declare function createDebug(category: DebugCategory): (...args: unknown[]) => void;
+/**
+ * Pre-configured debug loggers for common categories.
+ */
+export declare const debug: {
+    llm: (...args: unknown[]) => void;
+    sse: (...args: unknown[]) => void;
+    template: (...args: unknown[]) => void;
+    agent: (...args: unknown[]) => void;
+    registry: (...args: unknown[]) => void;
+};
+/**
+ * Check if any debug logging is enabled.
+ */
+export declare function isAnyDebugEnabled(): boolean;
+export {};
+//# sourceMappingURL=debug.d.ts.map

package/dist/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,KAAK,aAAa,GAAG,KAAK,GAAG,cAAc,GAAG,KAAK,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,2BAA2B,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAyCpM;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAQjF;AAED;;GAEG;AACH,eAAO,MAAM,KAAK;mBAb8C,OAAO,EAAE,KAAK,IAAI;mBAAlB,OAAO,EAAE,KAAK,IAAI;wBAAlB,OAAO,EAAE,KAAK,IAAI;qBAAlB,OAAO,EAAE,KAAK,IAAI;wBAAlB,OAAO,EAAE,KAAK,IAAI;CAmBjF,CAAC;AAEF;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C"}

package/dist/debug.js

@@ -0,0 +1,86 @@
+/**
+ * Debug logging utilities for MCP Mesh SDK.
+ *
+ * Debug output is controlled by standard MCP Mesh environment variables:
+ * - MCP_MESH_LOG_LEVEL=DEBUG - Enable debug output (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+ * - MCP_MESH_DEBUG_MODE=true - Force DEBUG level
+ *
+ * @example
+ * ```bash
+ * # Enable debug output
+ * MCP_MESH_LOG_LEVEL=DEBUG node my-agent.js
+ *
+ * # Or use debug mode
+ * MCP_MESH_DEBUG_MODE=true node my-agent.js
+ * ```
+ */
+/** Log levels in order of severity */
+const LOG_LEVELS = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"];
+/**
+ * Get the current log level from environment.
+ */
+function getLogLevel() {
+    // MCP_MESH_DEBUG_MODE forces DEBUG level
+    const debugMode = process.env.MCP_MESH_DEBUG_MODE;
+    if (debugMode === "true" || debugMode === "1") {
+        return "DEBUG";
+    }
+    // MCP_MESH_LOG_LEVEL sets the level
+    const level = process.env.MCP_MESH_LOG_LEVEL?.toUpperCase();
+    if (level && LOG_LEVELS.includes(level)) {
+        return level;
+    }
+    // Default to INFO
+    return "INFO";
+}
+/**
+ * Check if a log level is enabled.
+ */
+function isLevelEnabled(level) {
+    const currentLevel = getLogLevel();
+    return LOG_LEVELS.indexOf(level) >= LOG_LEVELS.indexOf(currentLevel);
+}
+/**
+ * Check if debug logging is enabled.
+ */
+function isDebugEnabled(_category) {
+    return isLevelEnabled("DEBUG");
+}
+/**
+ * Create a debug logger for a specific category.
+ *
+ * @param category - Debug category (e.g., "llm", "sse", "template")
+ * @returns Debug function that only logs when category is enabled
+ *
+ * @example
+ * ```typescript
+ * const debug = createDebug("llm");
+ * debug("Executing tool", { name: "add" });
+ * // Only logs if MCP_MESH_LOG_LEVEL=DEBUG or MCP_MESH_DEBUG_MODE=true
+ * ```
+ */
+export function createDebug(category) {
+    const prefix = `[mesh.${category}]`;
+    return (...args) => {
+        if (isDebugEnabled(category)) {
+            console.log(prefix, ...args);
+        }
+    };
+}
+/**
+ * Pre-configured debug loggers for common categories.
+ */
+export const debug = {
+    llm: createDebug("llm"),
+    sse: createDebug("sse"),
+    template: createDebug("template"),
+    agent: createDebug("agent"),
+    registry: createDebug("registry"),
+};
+/**
+ * Check if any debug logging is enabled.
+ */
+export function isAnyDebugEnabled() {
+    return isLevelEnabled("DEBUG");
+}
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,sCAAsC;AACtC,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,CAAU,CAAC;AAG9E;;GAEG;AACH,SAAS,WAAW;IAClB,yCAAyC;IACzC,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IAClD,IAAI,SAAS,KAAK,MAAM,IAAI,SAAS,KAAK,GAAG,EAAE,CAAC;QAC9C,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,oCAAoC;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,WAAW,EAA0B,CAAC;IACpF,IAAI,KAAK,IAAI,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,kBAAkB;IAClB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,KAAe;IACrC,MAAM,YAAY,GAAG,WAAW,EAAE,CAAC;IACnC,OAAO,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;AACvE,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,SAAwB;IAC9C,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,QAAuB;IACjD,MAAM,MAAM,GAAG,SAAS,QAAQ,GAAG,CAAC;IAEpC,OAAO,CAAC,GAAG,IAAe,EAAE,EAAE;QAC5B,IAAI,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC;IACvB,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC;IACvB,QAAQ,EAAE,WAAW,CAAC,UAAU,CAAC;IACjC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC;IAC3B,QAAQ,EAAE,WAAW,CAAC,UAAU,CAAC;CAClC,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Typed error classes for mesh.llm() operations.
+ *
+ * These errors provide specific context about different failure modes,
+ * matching Python's error class hierarchy.
+ */
+/**
+ * Error thrown when the agentic loop reaches max iterations without completing.
+ */
+export declare class MaxIterationsError extends Error {
+    /** Number of iterations that were executed */
+    readonly iterations: number;
+    /** The last response from the LLM before reaching the limit */
+    readonly lastResponse: unknown;
+    /** The message history at the time of the error */
+    readonly messages?: unknown[] | undefined;
+    readonly name = "MaxIterationsError";
+    constructor(
+    /** Number of iterations that were executed */
+    iterations: number, 
+    /** The last response from the LLM before reaching the limit */
+    lastResponse: unknown, 
+    /** The message history at the time of the error */
+    messages?: unknown[] | undefined);
+}
+/**
+ * Error thrown when a tool execution fails during the agentic loop.
+ */
+export declare class ToolExecutionError extends Error {
+    /** Name of the tool that failed */
+    readonly toolName: string;
+    /** The underlying error that caused the failure */
+    readonly cause: Error;
+    /** Arguments that were passed to the tool */
+    readonly args?: Record<string, unknown> | undefined;
+    readonly name = "ToolExecutionError";
+    constructor(
+    /** Name of the tool that failed */
+    toolName: string, 
+    /** The underlying error that caused the failure */
+    cause: Error, 
+    /** Arguments that were passed to the tool */
+    args?: Record<string, unknown> | undefined);
+}
+/**
+ * Error thrown when the LLM API returns an error response.
+ */
+export declare class LLMAPIError extends Error {
+    /** HTTP status code from the API */
+    readonly statusCode: number;
+    /** Response body from the API */
+    readonly body: string;
+    /** The provider that returned the error */
+    readonly provider?: string | undefined;
+    readonly name = "LLMAPIError";
+    constructor(
+    /** HTTP status code from the API */
+    statusCode: number, 
+    /** Response body from the API */
+    body: string, 
+    /** The provider that returned the error */
+    provider?: string | undefined);
+}
+/**
+ * Error thrown when response parsing/validation fails.
+ * Unified class used by both LLM agent and response parser.
+ */
+export declare class ResponseParseError extends Error {
+    /** The raw content that failed to parse */
+    readonly rawContent: string;
+    /** Zod validation error (if schema validation failed) */
+    readonly zodError?: unknown | undefined;
+    /** The expected schema (if using structured output) */
+    readonly expectedSchema?: unknown | undefined;
+    readonly name = "ResponseParseError";
+    constructor(message: string, 
+    /** The raw content that failed to parse */
+    rawContent: string, 
+    /** Zod validation error (if schema validation failed) */
+    zodError?: unknown | undefined, 
+    /** The expected schema (if using structured output) */
+    expectedSchema?: unknown | undefined);
+}
+/**
+ * Error thrown when the LLM provider is not available.
+ */
+export declare class ProviderUnavailableError extends Error {
+    /** The provider specification that could not be resolved */
+    readonly providerSpec: unknown;
+    /** Additional details about why resolution failed */
+    readonly reason?: string | undefined;
+    readonly name = "ProviderUnavailableError";
+    constructor(
+    /** The provider specification that could not be resolved */
+    providerSpec: unknown, 
+    /** Additional details about why resolution failed */
+    reason?: string | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAIzC,8CAA8C;aAC9B,UAAU,EAAE,MAAM;IAClC,+DAA+D;aAC/C,YAAY,EAAE,OAAO;IACrC,mDAAmD;aACnC,QAAQ,CAAC,EAAE,OAAO,EAAE;IARtC,QAAQ,CAAC,IAAI,wBAAwB;;IAGnC,8CAA8C;IAC9B,UAAU,EAAE,MAAM;IAClC,+DAA+D;IAC/C,YAAY,EAAE,OAAO;IACrC,mDAAmD;IACnC,QAAQ,CAAC,EAAE,OAAO,EAAE,YAAA;CAIvC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAIzC,mCAAmC;aACnB,QAAQ,EAAE,MAAM;IAChC,mDAAmD;aACnC,KAAK,EAAE,KAAK;IAC5B,6CAA6C;aAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IARhD,QAAQ,CAAC,IAAI,wBAAwB;;IAGnC,mCAAmC;IACnB,QAAQ,EAAE,MAAM;IAChC,mDAAmD;IACnC,KAAK,EAAE,KAAK;IAC5B,6CAA6C;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAIjD;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAIlC,oCAAoC;aACpB,UAAU,EAAE,MAAM;IAClC,iCAAiC;aACjB,IAAI,EAAE,MAAM;IAC5B,2CAA2C;aAC3B,QAAQ,CAAC,EAAE,MAAM;IARnC,QAAQ,CAAC,IAAI,iBAAiB;;IAG5B,oCAAoC;IACpB,UAAU,EAAE,MAAM;IAClC,iCAAiC;IACjB,IAAI,EAAE,MAAM;IAC5B,2CAA2C;IAC3B,QAAQ,CAAC,EAAE,MAAM,YAAA;CAIpC;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAKzC,2CAA2C;aAC3B,UAAU,EAAE,MAAM;IAClC,yDAAyD;aACzC,QAAQ,CAAC,EAAE,OAAO;IAClC,uDAAuD;aACvC,cAAc,CAAC,EAAE,OAAO;IAT1C,QAAQ,CAAC,IAAI,wBAAwB;gBAGnC,OAAO,EAAE,MAAM;IACf,2CAA2C;IAC3B,UAAU,EAAE,MAAM;IAClC,yDAAyD;IACzC,QAAQ,CAAC,EAAE,OAAO,YAAA;IAClC,uDAAuD;IACvC,cAAc,CAAC,EAAE,OAAO,YAAA;CAI3C;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAI/C,4DAA4D;aAC5C,YAAY,EAAE,OAAO;IACrC,qDAAqD;aACrC,MAAM,CAAC,EAAE,MAAM;IANjC,QAAQ,CAAC,IAAI,8BAA8B;;IAGzC,4DAA4D;IAC5C,YAAY,EAAE,OAAO;IACrC,qDAAqD;IACrC,MAAM,CAAC,EAAE,MAAM,YAAA;CAOlC"}

package/dist/errors.js

@@ -0,0 +1,110 @@
+/**
+ * Typed error classes for mesh.llm() operations.
+ *
+ * These errors provide specific context about different failure modes,
+ * matching Python's error class hierarchy.
+ */
+/**
+ * Error thrown when the agentic loop reaches max iterations without completing.
+ */
+export class MaxIterationsError extends Error {
+    iterations;
+    lastResponse;
+    messages;
+    name = "MaxIterationsError";
+    constructor(
+    /** Number of iterations that were executed */
+    iterations, 
+    /** The last response from the LLM before reaching the limit */
+    lastResponse, 
+    /** The message history at the time of the error */
+    messages) {
+        super(`Max iterations (${iterations}) reached without completing the task`);
+        this.iterations = iterations;
+        this.lastResponse = lastResponse;
+        this.messages = messages;
+    }
+}
+/**
+ * Error thrown when a tool execution fails during the agentic loop.
+ */
+export class ToolExecutionError extends Error {
+    toolName;
+    cause;
+    args;
+    name = "ToolExecutionError";
+    constructor(
+    /** Name of the tool that failed */
+    toolName, 
+    /** The underlying error that caused the failure */
+    cause, 
+    /** Arguments that were passed to the tool */
+    args) {
+        super(`Tool '${toolName}' failed: ${cause.message}`);
+        this.toolName = toolName;
+        this.cause = cause;
+        this.args = args;
+    }
+}
+/**
+ * Error thrown when the LLM API returns an error response.
+ */
+export class LLMAPIError extends Error {
+    statusCode;
+    body;
+    provider;
+    name = "LLMAPIError";
+    constructor(
+    /** HTTP status code from the API */
+    statusCode, 
+    /** Response body from the API */
+    body, 
+    /** The provider that returned the error */
+    provider) {
+        super(`LLM API error (${statusCode}): ${body}`);
+        this.statusCode = statusCode;
+        this.body = body;
+        this.provider = provider;
+    }
+}
+/**
+ * Error thrown when response parsing/validation fails.
+ * Unified class used by both LLM agent and response parser.
+ */
+export class ResponseParseError extends Error {
+    rawContent;
+    zodError;
+    expectedSchema;
+    name = "ResponseParseError";
+    constructor(message, 
+    /** The raw content that failed to parse */
+    rawContent, 
+    /** Zod validation error (if schema validation failed) */
+    zodError, 
+    /** The expected schema (if using structured output) */
+    expectedSchema) {
+        super(message);
+        this.rawContent = rawContent;
+        this.zodError = zodError;
+        this.expectedSchema = expectedSchema;
+    }
+}
+/**
+ * Error thrown when the LLM provider is not available.
+ */
+export class ProviderUnavailableError extends Error {
+    providerSpec;
+    reason;
+    name = "ProviderUnavailableError";
+    constructor(
+    /** The provider specification that could not be resolved */
+    providerSpec, 
+    /** Additional details about why resolution failed */
+    reason) {
+        super(`LLM provider unavailable${reason ? `: ${reason}` : ""}. ` +
+            `Provider spec: ${JSON.stringify(providerSpec)}`);
+        this.providerSpec = providerSpec;
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAKzB;IAEA;IAEA;IART,IAAI,GAAG,oBAAoB,CAAC;IAErC;IACE,8CAA8C;IAC9B,UAAkB;IAClC,+DAA+D;IAC/C,YAAqB;IACrC,mDAAmD;IACnC,QAAoB;QAEpC,KAAK,CAAC,mBAAmB,UAAU,uCAAuC,CAAC,CAAC;QAN5D,eAAU,GAAV,UAAU,CAAQ;QAElB,iBAAY,GAAZ,YAAY,CAAS;QAErB,aAAQ,GAAR,QAAQ,CAAY;IAGtC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAKzB;IAEA;IAEA;IART,IAAI,GAAG,oBAAoB,CAAC;IAErC;IACE,mCAAmC;IACnB,QAAgB;IAChC,mDAAmD;IACnC,KAAY;IAC5B,6CAA6C;IAC7B,IAA8B;QAE9C,KAAK,CAAC,SAAS,QAAQ,aAAa,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QANrC,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,UAAK,GAAL,KAAK,CAAO;QAEZ,SAAI,GAAJ,IAAI,CAA0B;IAGhD,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAKlB;IAEA;IAEA;IART,IAAI,GAAG,aAAa,CAAC;IAE9B;IACE,oCAAoC;IACpB,UAAkB;IAClC,iCAAiC;IACjB,IAAY;IAC5B,2CAA2C;IAC3B,QAAiB;QAEjC,KAAK,CAAC,kBAAkB,UAAU,MAAM,IAAI,EAAE,CAAC,CAAC;QANhC,eAAU,GAAV,UAAU,CAAQ;QAElB,SAAI,GAAJ,IAAI,CAAQ;QAEZ,aAAQ,GAAR,QAAQ,CAAS;IAGnC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAMzB;IAEA;IAEA;IATT,IAAI,GAAG,oBAAoB,CAAC;IAErC,YACE,OAAe;IACf,2CAA2C;IAC3B,UAAkB;IAClC,yDAAyD;IACzC,QAAkB;IAClC,uDAAuD;IACvC,cAAwB;QAExC,KAAK,CAAC,OAAO,CAAC,CAAC;QANC,eAAU,GAAV,UAAU,CAAQ;QAElB,aAAQ,GAAR,QAAQ,CAAU;QAElB,mBAAc,GAAd,cAAc,CAAU;IAG1C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAK/B;IAEA;IANT,IAAI,GAAG,0BAA0B,CAAC;IAE3C;IACE,4DAA4D;IAC5C,YAAqB;IACrC,qDAAqD;IACrC,MAAe;QAE/B,KAAK,CACH,2BAA2B,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI;YACxD,kBAAkB,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,EAAE,CACnD,CAAC;QAPc,iBAAY,GAAZ,YAAY,CAAS;QAErB,WAAM,GAAN,MAAM,CAAS;IAMjC,CAAC;CACF"}

package/dist/express.d.ts

@@ -0,0 +1,146 @@
+/**
+ * MeshExpress: Express app integration with MCP Mesh.
+ *
+ * Provides automatic registration with mesh registry and dependency injection
+ * for Express route handlers. Uses agent_type: "api" since API services only
+ * consume capabilities, they don't provide them.
+ *
+ * **Note:** For simpler usage, just use `mesh.route()` without `meshExpress()`.
+ * The API runtime auto-initializes when the first `mesh.route()` is called.
+ *
+ * @example Simple usage (recommended)
+ * ```typescript
+ * import express from "express";
+ * import { mesh } from "@mcpmesh/sdk";
+ *
+ * const app = express();
+ * app.use(express.json());
+ *
+ * // mesh.route() auto-initializes the mesh connection
+ * app.post("/compute", mesh.route(
+ *   [{ capability: "calculator" }],
+ *   async (req, res, { calculator }) => {
+ *     res.json({ result: await calculator({ a: req.body.a, b: req.body.b }) });
+ *   }
+ * ));
+ *
+ * app.listen(3000);
+ * ```
+ *
+ * @example Explicit control (advanced)
+ * ```typescript
+ * import express from "express";
+ * import { meshExpress, mesh } from "@mcpmesh/sdk";
+ *
+ * const app = express();
+ * const meshApp = meshExpress(app, { name: "my-api", port: 3000 });
+ *
+ * app.post("/compute", mesh.route(...));
+ *
+ * meshApp.start();
+ * ```
+ */
+import type { Application } from "express";
+import type { Server } from "http";
+import { type JsAgentHandle } from "@mcpmesh/core";
+import type { AgentConfig, ResolvedAgentConfig } from "./types.js";
+/**
+ * Configuration for MeshExpress.
+ * Extends AgentConfig with Express-specific options.
+ */
+export interface MeshExpressConfig extends AgentConfig {
+    /**
+     * If true, automatically start when the module loads.
+     * Defaults to false for Express (explicit start preferred).
+     */
+    autoStart?: boolean;
+}
+/**
+ * MeshExpress wraps an Express app with MCP Mesh capabilities.
+ *
+ * Provides:
+ * - Registration with mesh registry via Rust core
+ * - Heartbeat management
+ * - Dependency resolution for route handlers
+ * - Distributed tracing
+ */
+export declare class MeshExpress {
+    private app;
+    private config;
+    private serviceId;
+    private handle;
+    private server;
+    private started;
+    constructor(app: Application, config: MeshExpressConfig);
+    /**
+     * Setup health check endpoints for the registry.
+     */
+    private setupHealthEndpoints;
+    /**
+     * Start the Express server and register with mesh.
+     */
+    start(): Promise<void>;
+    /**
+     * Start the Express HTTP server.
+     */
+    private startServer;
+    /**
+     * Start the Rust core heartbeat loop.
+     */
+    private startHeartbeat;
+    /**
+     * Run the event loop to handle mesh events.
+     */
+    private runEventLoop;
+    /**
+     * Handle dependency_available event.
+     */
+    private handleDependencyAvailable;
+    /**
+     * Handle dependency_unavailable event.
+     */
+    private handleDependencyUnavailable;
+    /**
+     * Install signal handlers for graceful shutdown.
+     */
+    private installSignalHandlers;
+    /**
+     * Get the service ID.
+     */
+    getServiceId(): string;
+    /**
+     * Get the resolved configuration.
+     */
+    getConfig(): ResolvedAgentConfig;
+    /**
+     * Get the underlying Express app.
+     */
+    getApp(): Application;
+    /**
+     * Get the HTTP server instance.
+     */
+    getServer(): Server | null;
+    /**
+     * Get the agent handle for advanced operations.
+     */
+    getHandle(): JsAgentHandle | null;
+    /**
+     * Shutdown the service gracefully.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a MeshExpress instance wrapping an Express app.
+ *
+ * @example
+ * ```typescript
+ * const app = express();
+ * const meshApp = meshExpress(app, { name: "my-api", port: 3000 });
+ *
+ * // Define routes with mesh.route()...
+ *
+ * meshApp.start();
+ * ```
+ */
+export declare function meshExpress(app: Application, config: MeshExpressConfig): MeshExpress;
+//# sourceMappingURL=express.d.ts.map

package/dist/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../src/express.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAqB,MAAM,SAAS,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,EAGL,KAAK,aAAa,EAGnB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA8BnE;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,GAAG,CAAc;IACzB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,OAAO,CAAS;gBAEZ,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,iBAAiB;IAuBvD;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B5B;;OAEG;IACH,OAAO,CAAC,WAAW;IAiBnB;;OAEG;YACW,cAAc;IA+B5B;;OAEG;YACW,YAAY;IA0E1B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAyCjC;;OAEG;IACH,OAAO,CAAC,2BAA2B;IA+BnC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAwB7B;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,SAAS,IAAI,mBAAmB;IAIhC;;OAEG;IACH,MAAM,IAAI,WAAW;IAIrB;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B;;OAEG;IACH,SAAS,IAAI,aAAa,GAAG,IAAI;IAIjC;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAahC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,iBAAiB,GACxB,WAAW,CAEb"}