@mcpmesh/sdk 0.9.11 → 1.0.0-beta.1

package/dist/media/resolver.js

@@ -0,0 +1,311 @@
+/**
+ * Resolve resource_link URIs to provider-native multimodal content.
+ *
+ * When an LLM provider calls a tool that returns a resource_link (e.g., an image URI),
+ * the LLM currently sees just a JSON string. This module resolves the URI to base64
+ * media in provider-native format so the LLM can actually "see" the image.
+ *
+ * Based on Python's resolver:
+ * src/runtime/python/_mcp_mesh/media/resolver.py
+ */
+import { createDebug } from "../debug.js";
+import { getMediaStore } from "./media-store.js";
+const debug = createDebug("media-resolver");
+const IMAGE_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+const PDF_MIME_TYPES = new Set(["application/pdf"]);
+const TEXT_MIME_TYPES = new Set([
+    "text/plain",
+    "text/csv",
+    "text/markdown",
+    "text/html",
+    "text/xml",
+    "application/json",
+    "application/xml",
+    "application/csv",
+]);
+function formatForClaude(b64, mimeType) {
+    return {
+        type: "image",
+        source: {
+            type: "base64",
+            media_type: mimeType,
+            data: b64,
+        },
+    };
+}
+export function formatForOpenai(b64, mimeType) {
+    return {
+        type: "image_url",
+        image_url: {
+            url: `data:${mimeType};base64,${b64}`,
+            detail: "high",
+        },
+    };
+}
+function formatForGemini(b64, mimeType) {
+    // Vercel AI SDK handles Gemini images via OpenAI-compatible format
+    return formatForOpenai(b64, mimeType);
+}
+const VENDOR_FORMATTERS = {
+    anthropic: formatForClaude,
+    openai: formatForOpenai,
+    gemini: formatForGemini,
+    google: formatForGemini,
+};
+function formatPdfForClaude(b64) {
+    return {
+        type: "document",
+        source: {
+            type: "base64",
+            media_type: "application/pdf",
+            data: b64,
+        },
+    };
+}
+function formatPdfForOpenai(_b64, filename) {
+    return {
+        type: "text",
+        text: `[Attached PDF document: ${filename}. OpenAI does not support PDF analysis. Please use Claude for PDF processing.]`,
+    };
+}
+function formatPdfForGemini(_b64, filename) {
+    return {
+        type: "text",
+        text: `[Attached PDF document: ${filename}. Gemini PDF support via LiteLLM may vary.]`,
+    };
+}
+function formatTextContent(data, mimeType, filename) {
+    let text;
+    try {
+        text = data.toString("utf-8");
+    }
+    catch {
+        text = data.toString("latin1");
+    }
+    const maxChars = 50_000;
+    if (text.length > maxChars) {
+        text = text.slice(0, maxChars) + `\n\n[... truncated, ${text.length} total characters]`;
+    }
+    return {
+        type: "text",
+        text: `--- Content of ${filename} (${mimeType}) ---\n${text}\n--- End of ${filename} ---`,
+    };
+}
+/**
+ * Resolve a single resource_link dict to a provider-native content part.
+ *
+ * @param resourceLink - Dict with type "resource_link" and either flat or nested resource fields
+ * @param vendor - One of "anthropic", "openai", "gemini", "google"
+ * @returns Provider-native content dict (image block or text fallback)
+ */
+async function resolveSingleResourceLink(resourceLink, vendor) {
+    // Support both flat format and nested resource sub-object
+    const resource = (resourceLink.resource ?? {});
+    const uri = (resource.uri ?? resourceLink.uri ?? "");
+    const mimeType = (resource.mimeType ?? resourceLink.mimeType ?? "");
+    const name = (resource.name ?? resourceLink.name ?? uri);
+    // --- Images: existing behaviour ---
+    if (IMAGE_MIME_TYPES.has(mimeType)) {
+        try {
+            const store = getMediaStore();
+            const { data, mimeType: fetchedMime } = await store.fetch(uri);
+            const b64 = data.toString("base64");
+            const formatter = VENDOR_FORMATTERS[vendor] ?? formatForOpenai;
+            const result = formatter(b64, mimeType || fetchedMime);
+            debug(`Resolved resource_link ${name} to ${vendor} image block (${data.length} bytes)`);
+            return result;
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            debug(`Failed to fetch resource_link ${uri}: ${errMsg}`);
+            return {
+                type: "text",
+                text: `[resource_link: ${name} (${mimeType || "unknown"}) at ${uri} (fetch failed)]`,
+            };
+        }
+    }
+    // --- PDFs: provider-specific ---
+    if (PDF_MIME_TYPES.has(mimeType)) {
+        try {
+            const store = getMediaStore();
+            const { data } = await store.fetch(uri);
+            const b64 = data.toString("base64");
+            if (vendor === "anthropic" || vendor === "claude") {
+                return formatPdfForClaude(b64);
+            }
+            else if (vendor === "gemini" || vendor === "google") {
+                return formatPdfForGemini(b64, name);
+            }
+            else {
+                return formatPdfForOpenai(b64, name);
+            }
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            debug(`Failed to fetch PDF ${uri}: ${errMsg}`);
+            return { type: "text", text: `[PDF document: ${name} at ${uri}]` };
+        }
+    }
+    // --- Text files: read content and include as text (all providers) ---
+    if (TEXT_MIME_TYPES.has(mimeType) || mimeType.startsWith("text/")) {
+        try {
+            const store = getMediaStore();
+            const { data } = await store.fetch(uri);
+            return formatTextContent(data, mimeType, name);
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            debug(`Failed to fetch text file ${uri}: ${errMsg}`);
+            return { type: "text", text: `[Text document: ${name} at ${uri}]` };
+        }
+    }
+    // --- Unknown / unsupported MIME type ---
+    return {
+        type: "text",
+        text: `[resource_link: ${name} (${mimeType || "unknown"}) at ${uri}]`,
+    };
+}
+/**
+ * Scan tool result for resource_link items and resolve to provider-native format.
+ *
+ * Returns a list of content parts for the LLM message.
+ * - For image resource_links: fetches bytes, base64 encodes, formats per vendor
+ * - For non-image or non-resource_link: wraps in text content
+ *
+ * @param toolResult - The raw tool result (could be object, string, etc.)
+ * @param vendor - One of "anthropic", "openai", "gemini", "google"
+ * @returns List of content dicts suitable for provider-specific message content arrays
+ */
+export async function resolveResourceLinks(toolResult, vendor) {
+    // resource_link dict
+    if (toolResult &&
+        typeof toolResult === "object" &&
+        toolResult.type === "resource_link") {
+        const part = await resolveSingleResourceLink(toolResult, vendor);
+        return [part];
+    }
+    // multi_content dict (from extractContent in proxy.ts)
+    if (toolResult &&
+        typeof toolResult === "object" &&
+        toolResult.type === "multi_content") {
+        const obj = toolResult;
+        const items = (obj.items ?? obj.content ?? []);
+        const parts = [];
+        for (const item of items) {
+            if (item &&
+                typeof item === "object" &&
+                item.type === "resource_link") {
+                parts.push(await resolveSingleResourceLink(item, vendor));
+            }
+            else if (typeof item === "string") {
+                parts.push({ type: "text", text: item });
+            }
+            else if (item && typeof item === "object") {
+                // Non-resource_link objects (e.g., text items) — preserve or serialize
+                const itemObj = item;
+                if (itemObj.type === "text" && typeof itemObj.text === "string") {
+                    parts.push({ type: "text", text: itemObj.text });
+                }
+                else {
+                    parts.push({ type: "text", text: JSON.stringify(item) });
+                }
+            }
+            else {
+                parts.push({ type: "text", text: String(item) });
+            }
+        }
+        return parts;
+    }
+    // Plain string
+    if (typeof toolResult === "string") {
+        return [{ type: "text", text: toolResult }];
+    }
+    // Anything else (dict without resource_link type, number, etc.)
+    try {
+        const text = JSON.stringify(toolResult);
+        return [{ type: "text", text }];
+    }
+    catch {
+        return [{ type: "text", text: String(toolResult) }];
+    }
+}
+/** Vendors that do NOT support images in tool/function result messages. */
+export const TOOL_IMAGE_UNSUPPORTED_VENDORS = new Set(["openai", "gemini", "google"]);
+/**
+ * Resolve resource_links for inclusion in a tool result message.
+ *
+ * For vendors that support images in tool messages (Anthropic/Claude),
+ * returns the full multimodal content (text + image parts).
+ *
+ * For vendors that do NOT support images in tool messages (OpenAI, Gemini),
+ * returns text-only content with descriptive placeholders. The actual image
+ * should be injected via a separate user message using
+ * `resolveMediaAsUserMessage()`.
+ *
+ * @param toolResult - Raw tool result
+ * @param vendor - e.g. "anthropic", "openai", "gemini"
+ * @returns Content parts suitable for a tool result message
+ */
+export async function resolveResourceLinksForToolMessage(toolResult, vendor) {
+    if (!TOOL_IMAGE_UNSUPPORTED_VENDORS.has(vendor)) {
+        return resolveResourceLinks(toolResult, vendor);
+    }
+    const parts = await resolveResourceLinks(toolResult, vendor);
+    return parts.map((part) => {
+        if (part.type === "image" || part.type === "image_url") {
+            return { type: "text", text: "[Image content — see next message]" };
+        }
+        return part;
+    });
+}
+/**
+ * Return a user message containing resolved images from a tool result.
+ *
+ * For vendors that do NOT support images in tool messages (OpenAI, Gemini),
+ * resolves resource_link items and packages the image parts into a
+ * `role: "user"` message that can be appended after the tool result message.
+ *
+ * For vendors that support images in tool messages (Anthropic), returns null.
+ *
+ * @param toolResult - Raw tool result
+ * @param vendor - e.g. "anthropic", "openai", "gemini"
+ * @returns A user message object with image content, or null
+ */
+export async function resolveMediaAsUserMessage(toolResult, vendor) {
+    if (!TOOL_IMAGE_UNSUPPORTED_VENDORS.has(vendor)) {
+        return null;
+    }
+    const parts = await resolveResourceLinks(toolResult, vendor);
+    const imageParts = parts.filter((p) => p.type === "image" || p.type === "image_url");
+    if (imageParts.length === 0) {
+        return null;
+    }
+    return {
+        role: "user",
+        content: [
+            { type: "text", text: "The tool returned this image:" },
+            ...imageParts,
+        ],
+    };
+}
+/**
+ * Quick check whether a tool result contains any resource_link items.
+ *
+ * This is a lightweight synchronous check used to decide whether the
+ * more expensive async resolution is needed.
+ */
+export function hasResourceLink(toolResult) {
+    if (!toolResult || typeof toolResult !== "object") {
+        return false;
+    }
+    const obj = toolResult;
+    if (obj.type === "resource_link") {
+        return true;
+    }
+    if (obj.type === "multi_content") {
+        const items = (obj.items ?? obj.content ?? []);
+        return items.some((i) => i && typeof i === "object" && i.type === "resource_link");
+    }
+    return false;
+}
+//# sourceMappingURL=resolver.js.map

package/dist/media/resolver.js.map

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

package/dist/media-param.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Schema post-processing for media-typed tool parameters.
+ *
+ * Detects the "[media:TYPE]" convention in property descriptions
+ * (set by mediaParam() in types.ts) and enriches the JSON Schema
+ * with x-media-type annotations for LLM tool discovery.
+ */
+/**
+ * Post-process a JSON Schema to enrich properties that use the
+ * [media:TYPE] description convention with x-media-type annotations.
+ *
+ * Modifies the schema in place.
+ *
+ * @param schema - JSON Schema object (from zodToJsonSchema)
+ */
+export declare function enrichSchemaWithMediaTypes(schema: Record<string, unknown>): void;
+//# sourceMappingURL=media-param.d.ts.map

package/dist/media-param.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-param.d.ts","sourceRoot":"","sources":["../src/media-param.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAgBhF"}

package/dist/media-param.js

@@ -0,0 +1,32 @@
+/**
+ * Schema post-processing for media-typed tool parameters.
+ *
+ * Detects the "[media:TYPE]" convention in property descriptions
+ * (set by mediaParam() in types.ts) and enriches the JSON Schema
+ * with x-media-type annotations for LLM tool discovery.
+ */
+/**
+ * Post-process a JSON Schema to enrich properties that use the
+ * [media:TYPE] description convention with x-media-type annotations.
+ *
+ * Modifies the schema in place.
+ *
+ * @param schema - JSON Schema object (from zodToJsonSchema)
+ */
+export function enrichSchemaWithMediaTypes(schema) {
+    const properties = schema?.properties;
+    if (!properties)
+        return;
+    for (const [, prop] of Object.entries(properties)) {
+        const desc = prop?.description;
+        if (typeof desc === "string") {
+            const match = desc.match(/^\[media:([^\]]+)\]\s*/);
+            if (match) {
+                prop["x-media-type"] = match[1];
+                prop.description = desc.replace(/^\[media:[^\]]+\]\s*/, "")
+                    + ` (accepts media URI: ${match[1]})`;
+            }
+        }
+    }
+}
+//# sourceMappingURL=media-param.js.map

package/dist/media-param.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-param.js","sourceRoot":"","sources":["../src/media-param.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAA+B;IACtE,MAAM,UAAU,GAAI,MAAkC,EAAE,UACD,CAAC;IACxD,IAAI,CAAC,UAAU;QAAE,OAAO;IAExB,KAAK,MAAM,CAAC,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,IAAI,EAAE,WAAW,CAAC;QAC/B,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;YACnD,IAAI,KAAK,EAAE,CAAC;gBACR,IAAI,CAAC,cAAc,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBAChC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,sBAAsB,EAAE,EAAE,CAAC;sBACrD,wBAAwB,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;YAC9C,CAAC;QACL,CAAC;IACL,CAAC;AACL,CAAC"}

package/dist/provider-handlers/claude-handler.d.ts

@@ -4,16 +4,17 @@
  * Optimized for Claude API (Claude 3.x, Sonnet, Opus, Haiku)
  * using Anthropic's best practices for tool calling and JSON responses.
  *
- * Supports two output modes (TEXT + HINT only):
- * - hint: Use prompt-based JSON instructions with DECISION GUIDE (~95% reliable)
- * - text: Plain text output for str return types (fastest)
- *
- * Native response_format (strict mode) is NOT used due to cross-runtime
- * incompatibilities when tools are present, and grammar compilation overhead.
+ * Dual output strategy (matching Python SDK):
+ * - formatSystemPrompt (direct calls): HINT mode — prompt-based JSON instructions
+ *   with DECISION GUIDE for callers that don't control the provider-side API call.
+ * - prepareRequest (mesh delegation): native response_format with strict JSON schema
+ *   for provider-side enforcement. The caller controls the full API call and can
+ *   pass response_format directly to the Anthropic API.
  *
  * Features:
  * - Anti-XML tool calling instructions
  * - DECISION GUIDE for tool vs. direct JSON response decisions
+ * - Native response_format for structured output in mesh delegation
  *
  * Note: Prompt caching is not yet implemented for AI SDK v6.
  * TODO: Re-enable via experimental_providerOptions when AI SDK v6 supports it.
@@ -28,13 +29,12 @@ import { type ProviderHandler, type VendorCapabilities, type ToolSchema, type Ou
  * - Native tool calling (via Anthropic messages API)
  * - Performs best with anti-XML tool calling instructions
  *
- * Output Modes (TEXT + HINT only):
- * - hint: JSON schema in prompt with DECISION GUIDE (~95% reliable)
- * - text: Plain text output for str return types (fastest)
- *
- * Native response_format (strict mode) is not used. HINT mode with
- * detailed prompt instructions provides sufficient reliability (~95%)
- * without cross-runtime incompatibilities and grammar compilation overhead.
+ * Dual output strategy (matching Python SDK):
+ * - formatSystemPrompt: Adds brief JSON note in strict mode, detailed HINT
+ *   instructions in hint mode. Used for belt-and-suspenders prompt guidance.
+ * - prepareRequest: Sets native response_format with strict JSON schema when
+ *   outputMode is "strict". Used for mesh delegation where the provider
+ *   controls the full API call.
  *
  * Best Practices (from Anthropic docs):
  * - Add anti-XML instructions to prevent <invoke> style tool calls
@@ -45,7 +45,8 @@ export declare class ClaudeHandler implements ProviderHandler {
     /**
      * Prepare request parameters for Claude API with output mode support.
      *
-     * Output Mode Strategy (TEXT + HINT only):
+     * Output Mode Strategy:
+     * - strict: Set response_format with strict JSON schema (native enforcement)
      * - hint: No response_format, rely on prompt instructions (~95% reliable)
      * - text: No response_format, plain text output (fastest)
      *
@@ -64,7 +65,8 @@ export declare class ClaudeHandler implements ProviderHandler {
     /**
      * Format system prompt for Claude with output mode support.
      *
-     * Output Mode Strategy (TEXT + HINT only):
+     * Output Mode Strategy:
+     * - strict: Brief JSON note (response_format handles schema enforcement)
      * - hint: Add detailed JSON schema instructions with DECISION GUIDE in prompt
      * - text: No JSON instructions (plain text output)
      */
@@ -74,18 +76,11 @@ export declare class ClaudeHandler implements ProviderHandler {
      */
     getCapabilities(): VendorCapabilities;
     /**
-     * Determine the output mode based on schema complexity.
-     *
-     * Claude Strategy (Option A):
-     * - Always use "hint" mode (prompt-based) for schemas, never "strict"
-     * - Vercel AI SDK's generateObject() for Anthropic has issues with nested schemas
-     * - Anthropic's native structured output is slow and requires beta header
-     * - Prompt-based JSON instructions are fast and ~95% reliable for Claude
+     * Determine the optimal output mode for Claude.
      *
-     * Logic:
-     * - If overrideMode specified, use it
-     * - If no schema (string return type), use "text" mode
-     * - If schema exists, always use "hint" mode (prompt-based)
+     * Uses the default implementation which returns "strict" for schemas.
+     * This enables native response_format enforcement in mesh delegation
+     * (provider-side), matching the Python SDK behavior.
      */
     determineOutputMode(outputSchema: OutputSchema | null, overrideMode?: OutputMode): OutputMode;
 }

package/dist/provider-handlers/claude-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-handler.d.ts","sourceRoot":"","sources":["../../src/provider-handlers/claude-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,uBAAuB,CAAC;AAS/B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAc,YAAW,eAAe;IACnD,QAAQ,CAAC,MAAM,eAAe;IAE9B;;;;;;;;;;;OAWG;IACH,cAAc,CACZ,QAAQ,EAAE,UAAU,EAAE,EACtB,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,EAC1B,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,UAAU,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,GACA,eAAe;IAuClB;;;;;;OAMG;IACH,kBAAkB,CAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI,EAChC,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,UAAU,CAAC,EAAE,UAAU,GACtB,MAAM;IAyET;;OAEG;IACH,eAAe,IAAI,kBAAkB;IAWrC;;;;;;;;;;;;;OAaG;IACH,mBAAmB,CACjB,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,YAAY,CAAC,EAAE,UAAU,GACxB,UAAU;CAgBd"}
+{"version":3,"file":"claude-handler.d.ts","sourceRoot":"","sources":["../../src/provider-handlers/claude-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,uBAAuB,CAAC;AAS/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,aAAc,YAAW,eAAe;IACnD,QAAQ,CAAC,MAAM,eAAe;IAE9B;;;;;;;;;;;;OAYG;IACH,cAAc,CACZ,QAAQ,EAAE,UAAU,EAAE,EACtB,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,EAC1B,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,UAAU,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,GACA,eAAe;IAyDlB;;;;;;;OAOG;IACH,kBAAkB,CAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI,EAChC,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,UAAU,CAAC,EAAE,UAAU,GACtB,MAAM;IA8FT;;OAEG;IACH,eAAe,IAAI,kBAAkB;IAWrC;;;;;;OAMG;IACH,mBAAmB,CACjB,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,YAAY,CAAC,EAAE,UAAU,GACxB,UAAU;CAId"}