@kontext-dev/js-sdk 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @kontext-dev/js-sdk
+
+Broker credentials between your AI agents and integrations.
+
+[Website](https://kontex.dev)  
+[Documentation](https://docs.kontext.dev)  
+[Dashboard](https://app.kontext.dev)
+
+## Install
+
+```bash
+npm install @kontext-dev/js-sdk
+```
+
+## What You Get
+
+- OAuth-based authentication and token handling for AI applications
+- MCP tool discovery and execution through a typed client
+- Server-side credential brokering per user and integration
+- Management API client for applications, integrations, and service accounts
+- React, Cloudflare, and AI adapter entry points
+
+## Quick Start (Client)
+
+```ts
+import { createKontextClient } from "@kontext-dev/js-sdk/client";
+
+const client = createKontextClient({
+  clientId: "app_your-client-id",
+  redirectUri: "http://localhost:3000/callback",
+  onAuthRequired: (url) => {
+    window.location.href = url.toString();
+  },
+});
+
+await client.connect();
+const tools = await client.tools.list();
+```
+
+## Quick Start (Server)
+
+```ts
+import { Kontext } from "@kontext-dev/js-sdk/server";
+
+const kontext = new Kontext({
+  clientId: process.env.KONTEXT_CLIENT_ID!,
+});
+
+const githubCredential = await kontext.require("github", userAccessToken);
+```
+
+## Entry Points
+
+- `@kontext-dev/js-sdk` (root convenience exports)
+- `@kontext-dev/js-sdk/client`
+- `@kontext-dev/js-sdk/server`
+- `@kontext-dev/js-sdk/management`
+- `@kontext-dev/js-sdk/react`
+- `@kontext-dev/js-sdk/cloudflare`
+- `@kontext-dev/js-sdk/ai`
+- `@kontext-dev/js-sdk/mcp`
+- `@kontext-dev/js-sdk/errors`
+- `@kontext-dev/js-sdk/verify`
+- `@kontext-dev/js-sdk/oauth`
+
+## Learn More
+
+- TypeScript SDK overview: https://docs.kontext.dev/sdks/typescript
+- Getting started guide: https://docs.kontext.dev/getting-started/quickstart
+- Framework guides: https://docs.kontext.dev/frameworks/vercel-ai

package/dist/adapters/ai/index.cjs

@@ -0,0 +1,175 @@
+'use strict';
+
+var ai = require('ai');
+
+// src/adapters/ai/index.ts
+
+// src/client/tool-utils.ts
+function buildKontextSystemPrompt(toolNames, integrations) {
+  if (toolNames.length === 0) return "";
+  const searchTool = toolNames.find((n) => n.endsWith("_SEARCH_TOOLS"));
+  const executeTool = toolNames.find((n) => n.endsWith("_EXECUTE_TOOL"));
+  const requestCapabilityTool = toolNames.find(
+    (n) => n.endsWith("_REQUEST_CAPABILITY")
+  );
+  let prompt = "You are a helpful assistant with access to various tools and integrations through Kontext.\nYou can help users with tasks across their connected services (GitHub, Linear, Slack, etc.).\nWhen a user asks about their services, use the available MCP tools to help them.\nThe user has already authenticated \u2014 tools run as the user with their permissions, including access to private repositories and org resources.";
+  if (searchTool && executeTool) {
+    prompt += `
+
+You have access to external integrations through Kontext MCP tools:
+- Call \`${searchTool}\` first to discover what tools/integrations are available.
+- Then call \`${executeTool}\` with the tool_id and arguments to run a specific tool.
+- When the user asks about "my repos", "my issues", etc., use the appropriate tool to look up their data directly. Do not ask for their username \u2014 the tools already know who they are.
+Always start by searching for tools when the user asks about their connected services.`;
+  }
+  if (integrations.length > 0) {
+    const connected = integrations.filter((i) => i.connected);
+    const disconnected = integrations.filter((i) => !i.connected);
+    if (disconnected.length > 0) {
+      prompt += "\n\n## Integration Status";
+      if (connected.length > 0) {
+        prompt += `
+
+You already have access to: ${connected.map((i) => i.name).join(", ")}`;
+      }
+      prompt += `
+
+The following services require user authorization: ${disconnected.map((i) => i.name).join(", ")}`;
+      if (requestCapabilityTool) {
+        const example = disconnected[0]?.name ?? "GitHub";
+        prompt += `
+
+**IMPORTANT:** When the user requests an action that requires one of these services:
+1. Call the \`${requestCapabilityTool}\` tool with \`capability_name\` set to the service name (e.g. "${example}")
+2. The tool will return an authorization link
+3. Include the link in your response so the user can click it to connect
+4. After the user authorizes, the service will be available on their next message`;
+      } else {
+        prompt += "\n\nWhen the user asks about a disconnected integration, let them know it needs to be connected first. Do not attempt to use tools from disconnected integrations without informing the user.";
+      }
+    }
+  }
+  return prompt;
+}
+function enrichToolsWithAuthAwareness(toolNames, integrations, options) {
+  const hasDisconnected = integrations.some(
+    (i) => !i.connected && i.connectUrl
+  );
+  if (!hasDisconnected) {
+    return {
+      systemPrompt: buildKontextSystemPrompt(toolNames, integrations),
+      requestCapabilityTool: null
+    };
+  }
+  const prefix = toolNames.find((n) => n.endsWith("_SEARCH_TOOLS"))?.replace(/_SEARCH_TOOLS$/, "") ?? "kontext";
+  const toolName = `${prefix}_REQUEST_CAPABILITY`;
+  const tool = buildRequestCapabilityTool(integrations);
+  const allToolNames = [...toolNames, toolName];
+  return {
+    systemPrompt: buildKontextSystemPrompt(allToolNames, integrations),
+    requestCapabilityTool: { name: toolName, ...tool }
+  };
+}
+function buildRequestCapabilityTool(capabilities) {
+  const disconnected = capabilities.filter((c) => !c.connected && c.connectUrl);
+  const capabilityList = disconnected.length > 0 ? disconnected.map((c) => c.name).join(", ") : "none";
+  return {
+    description: `Request connection to a capability that is not yet connected. Currently disconnected capabilities: ${capabilityList}. Call this tool with the capability name to initiate the connection flow.`,
+    parameters: {
+      type: "object",
+      properties: {
+        capability_name: {
+          type: "string",
+          description: "The name of the capability to connect"
+        }
+      },
+      required: ["capability_name"]
+    },
+    execute: async (...args) => {
+      const input = args[0] ?? {};
+      const name = input.capability_name ?? "";
+      if (!name && disconnected.length === 1 && disconnected[0]) {
+        return `${disconnected[0].name} requires authorization. Please visit the following link to connect: ${disconnected[0].connectUrl}`;
+      }
+      const match = disconnected.find(
+        (c) => c.name.toLowerCase() === name.toLowerCase()
+      );
+      if (!match) {
+        const isConnected = capabilities.find(
+          (c) => c.connected && c.name.toLowerCase() === name.toLowerCase()
+        );
+        if (isConnected) {
+          return `${isConnected.name} is already connected and ready to use.`;
+        }
+        return `Unknown capability "${name}". Available disconnected capabilities: ${capabilityList}.`;
+      }
+      return `${match.name} requires authorization. Please visit the following link to connect: ${match.connectUrl}`;
+    }
+  };
+}
+
+// src/adapters/ai/index.ts
+async function toKontextTools(client, options) {
+  const [tools, integrations] = await Promise.all([
+    client.tools.list(),
+    client.integrations.list()
+  ]);
+  const coreTools = {};
+  const usedNames = /* @__PURE__ */ new Set();
+  for (const tool of tools) {
+    const name = buildToolName(tool, usedNames);
+    coreTools[name] = {
+      description: formatDescription(tool),
+      parameters: tool.inputSchema ? ai.jsonSchema(tool.inputSchema) : ai.jsonSchema({ type: "object", properties: {} }),
+      execute: async (args) => {
+        const r = await client.tools.execute(tool.id, args);
+        return (options?.formatResult ?? defaultFormat)(r);
+      }
+    };
+  }
+  const { systemPrompt, requestCapabilityTool } = enrichToolsWithAuthAwareness(
+    tools.map((t) => t.name),
+    integrations
+  );
+  if (requestCapabilityTool) {
+    coreTools[requestCapabilityTool.name] = {
+      description: requestCapabilityTool.description,
+      parameters: ai.jsonSchema(
+        requestCapabilityTool.parameters
+      ),
+      execute: async (args) => {
+        return requestCapabilityTool.execute(args);
+      }
+    };
+  }
+  return { tools: coreTools, systemPrompt, integrations };
+}
+function defaultFormat(r) {
+  return r.content;
+}
+function formatDescription(tool) {
+  const base = tool.description ?? tool.name;
+  const serverLabel = tool.server?.name ?? tool.server?.id;
+  return serverLabel ? `[${serverLabel}] ${base}` : base;
+}
+function buildToolName(tool, usedNames) {
+  const rawName = tool.name || tool.id || "tool";
+  const base = tool.server ? `${tool.server.name ?? tool.server.id ?? "server"}_${rawName}` : rawName;
+  const sanitized = sanitizeToolName(base);
+  const fallback = sanitized || `tool_${usedNames.size + 1}`;
+  let name = fallback;
+  let suffix = 1;
+  while (usedNames.has(name)) {
+    name = `${fallback}_${suffix}`;
+    suffix += 1;
+  }
+  usedNames.add(name);
+  return name;
+}
+function sanitizeToolName(name) {
+  return name.replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "").slice(0, 64);
+}
+
+exports.toKontextTools = toKontextTools;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/adapters/ai/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/client/tool-utils.ts","../../../src/adapters/ai/index.ts"],"names":["jsonSchema"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Shared utilities for Kontext tool handling.\n * Used by both KontextClient (core) and withKontext (Cloudflare adapter).\n */\n\nimport {\n  IntegrationConnectionRequiredError,\n  type ElicitationEntry,\n} from \"../errors.js\";\n\n// Re-export for backward compatibility\nexport type { ElicitationEntry } from \"../errors.js\";\n\n// ============================================================================\n// Shared types\n// ============================================================================\n\nexport interface IntegrationStatus {\n  readonly id: string;\n  readonly name: string;\n  readonly connected: boolean;\n  readonly connectUrl?: string;\n}\n\n// ============================================================================\n// System prompt\n// ============================================================================\n\n/**\n * Build an LLM system prompt based on available tool names and integration status.\n * Detects `*_SEARCH_TOOLS` / `*_EXECUTE_TOOL` suffixed names from the\n * Cloudflare Agents MCP proxy and generates appropriate guidance.\n */\nexport function buildKontextSystemPrompt(\n  toolNames: readonly string[],\n  integrations: readonly IntegrationStatus[],\n): string {\n  if (toolNames.length === 0) return \"\";\n\n  const searchTool = toolNames.find((n) => n.endsWith(\"_SEARCH_TOOLS\"));\n  const executeTool = toolNames.find((n) => n.endsWith(\"_EXECUTE_TOOL\"));\n  const requestCapabilityTool = toolNames.find((n) =>\n    n.endsWith(\"_REQUEST_CAPABILITY\"),\n  );\n\n  let prompt =\n    \"You are a helpful assistant with access to various tools and integrations through Kontext.\\n\" +\n    \"You can help users with tasks across their connected services (GitHub, Linear, Slack, etc.).\\n\" +\n    \"When a user asks about their services, use the available MCP tools to help them.\\n\" +\n    \"The user has already authenticated — tools run as the user with their permissions, including access to private repositories and org resources.\";\n\n  if (searchTool && executeTool) {\n    prompt +=\n      `\\n\\nYou have access to external integrations through Kontext MCP tools:\\n` +\n      `- Call \\`${searchTool}\\` first to discover what tools/integrations are available.\\n` +\n      `- Then call \\`${executeTool}\\` with the tool_id and arguments to run a specific tool.\\n` +\n      `- When the user asks about \"my repos\", \"my issues\", etc., use the appropriate tool to look up their data directly. Do not ask for their username — the tools already know who they are.\\n` +\n      `Always start by searching for tools when the user asks about their connected services.`;\n  }\n\n  // Append integration status section when there are integrations to report\n  if (integrations.length > 0) {\n    const connected = integrations.filter((i) => i.connected);\n    const disconnected = integrations.filter((i) => !i.connected);\n\n    if (disconnected.length > 0) {\n      prompt += \"\\n\\n## Integration Status\";\n\n      if (connected.length > 0) {\n        prompt += `\\n\\nYou already have access to: ${connected.map((i) => i.name).join(\", \")}`;\n      }\n\n      prompt += `\\n\\nThe following services require user authorization: ${disconnected.map((i) => i.name).join(\", \")}`;\n\n      if (requestCapabilityTool) {\n        const example = disconnected[0]?.name ?? \"GitHub\";\n        prompt +=\n          `\\n\\n**IMPORTANT:** When the user requests an action that requires one of these services:` +\n          `\\n1. Call the \\`${requestCapabilityTool}\\` tool with \\`capability_name\\` set to the service name (e.g. \"${example}\")` +\n          `\\n2. The tool will return an authorization link` +\n          `\\n3. Include the link in your response so the user can click it to connect` +\n          `\\n4. After the user authorizes, the service will be available on their next message`;\n      } else {\n        prompt +=\n          \"\\n\\nWhen the user asks about a disconnected integration, let them know it needs to be connected first. Do not attempt to use tools from disconnected integrations without informing the user.\";\n      }\n    }\n  }\n\n  return prompt;\n}\n\n// ============================================================================\n// Auth-aware toolset orchestrator\n// ============================================================================\n\nexport interface AuthAwareToolset {\n  /** System prompt with integration status and REQUEST_CAPABILITY instructions. */\n  readonly systemPrompt: string;\n  /** REQUEST_CAPABILITY tool to inject, or null if all integrations are connected. */\n  readonly requestCapabilityTool: {\n    readonly name: string;\n    readonly description: string;\n    readonly parameters: Record<string, unknown>;\n    readonly execute: (...args: unknown[]) => Promise<string>;\n  } | null;\n}\n\n/**\n * Enrich a tool set with auth awareness.\n *\n * Given tool names and integration status, produces:\n * - A system prompt that tells the LLM about connected/disconnected integrations\n * - A REQUEST_CAPABILITY tool (if needed) that returns auth URLs as text\n *\n * Both `ai/` and `cloudflare/` adapters use this as their core auth layer.\n */\nexport function enrichToolsWithAuthAwareness(\n  toolNames: readonly string[],\n  integrations: readonly IntegrationStatus[],\n  options?: { prefix?: string },\n): AuthAwareToolset {\n  const hasDisconnected = integrations.some(\n    (i) => !i.connected && i.connectUrl,\n  );\n\n  if (!hasDisconnected) {\n    return {\n      systemPrompt: buildKontextSystemPrompt(toolNames, integrations),\n      requestCapabilityTool: null,\n    };\n  }\n\n  // Determine prefix from existing tool names or option\n  const prefix =\n    options?.prefix ??\n    toolNames\n      .find((n) => n.endsWith(\"_SEARCH_TOOLS\"))\n      ?.replace(/_SEARCH_TOOLS$/, \"\") ??\n    \"kontext\";\n\n  const toolName = `${prefix}_REQUEST_CAPABILITY`;\n  const tool = buildRequestCapabilityTool(integrations);\n\n  // Include REQUEST_CAPABILITY in tool names so the system prompt references it\n  const allToolNames = [...toolNames, toolName];\n\n  return {\n    systemPrompt: buildKontextSystemPrompt(allToolNames, integrations),\n    requestCapabilityTool: { name: toolName, ...tool },\n  };\n}\n\n// ============================================================================\n// Integration status parsing\n// ============================================================================\n\n/**\n * Parse integration status from gateway tool search results.\n * Extracts connected integrations from tools and disconnected from errors.\n */\nexport function parseIntegrationStatus(\n  tools: ReadonlyArray<{ server?: { id?: string; name?: string } }>,\n  errors: ReadonlyArray<{ serverId: string; serverName?: string }>,\n  elicitations?: ReadonlyArray<{\n    url: string;\n    integrationId?: string;\n    integrationName?: string;\n  }>,\n): IntegrationStatus[] {\n  const seen = new Set<string>();\n  const result: IntegrationStatus[] = [];\n\n  for (const t of tools) {\n    const sid = t.server?.id;\n    if (sid && !seen.has(sid)) {\n      seen.add(sid);\n      result.push({\n        id: sid,\n        name: t.server?.name ?? sid,\n        connected: true,\n      });\n    }\n  }\n\n  for (const e of errors) {\n    if (!seen.has(e.serverId)) {\n      seen.add(e.serverId);\n      const elicitation = elicitations?.find(\n        (el) => el.integrationId === e.serverId,\n      );\n      result.push({\n        id: e.serverId,\n        name: e.serverName ?? e.serverId,\n        connected: false,\n        connectUrl: elicitation?.url,\n      });\n    }\n  }\n\n  return result;\n}\n\n// ============================================================================\n// Request capability tool\n// ============================================================================\n\n/**\n * Build a tool that lets the LLM request connection of a disconnected capability.\n * Returns the connect URL as text so the LLM can present it to the user.\n * No popups — the user clicks the link in the chat to authorize.\n */\nexport function buildRequestCapabilityTool(\n  capabilities: readonly IntegrationStatus[],\n): {\n  description: string;\n  parameters: Record<string, unknown>;\n  execute: (...args: unknown[]) => Promise<string>;\n} {\n  const disconnected = capabilities.filter((c) => !c.connected && c.connectUrl);\n\n  const capabilityList =\n    disconnected.length > 0\n      ? disconnected.map((c) => c.name).join(\", \")\n      : \"none\";\n\n  return {\n    description:\n      `Request connection to a capability that is not yet connected. ` +\n      `Currently disconnected capabilities: ${capabilityList}. ` +\n      `Call this tool with the capability name to initiate the connection flow.`,\n    parameters: {\n      type: \"object\",\n      properties: {\n        capability_name: {\n          type: \"string\",\n          description: \"The name of the capability to connect\",\n        },\n      },\n      required: [\"capability_name\"],\n    },\n    execute: async (...args: unknown[]): Promise<string> => {\n      const input = (args[0] ?? {}) as { capability_name?: string };\n      const name = input.capability_name ?? \"\";\n\n      // Auto-select when called without a name and there's only one option\n      if (!name && disconnected.length === 1 && disconnected[0]) {\n        return (\n          `${disconnected[0].name} requires authorization. ` +\n          `Please visit the following link to connect: ${disconnected[0].connectUrl}`\n        );\n      }\n\n      const match = disconnected.find(\n        (c) => c.name.toLowerCase() === name.toLowerCase(),\n      );\n\n      if (!match) {\n        const isConnected = capabilities.find(\n          (c) => c.connected && c.name.toLowerCase() === name.toLowerCase(),\n        );\n        if (isConnected) {\n          return `${isConnected.name} is already connected and ready to use.`;\n        }\n        return `Unknown capability \"${name}\". Available disconnected capabilities: ${capabilityList}.`;\n      }\n\n      return (\n        `${match.name} requires authorization. ` +\n        `Please visit the following link to connect: ${match.connectUrl}`\n      );\n    },\n  };\n}\n\n/**\n * Pre-flight integration status detection.\n * Calls SEARCH_TOOLS on raw (unwrapped) tools to detect connected/disconnected\n * integrations without triggering any popups or broadcasts.\n */\nexport async function preflightIntegrationStatus(\n  tools: ToolSetLike,\n): Promise<IntegrationStatus[]> {\n  const searchToolKey = Object.keys(tools).find((k) =>\n    k.endsWith(\"_SEARCH_TOOLS\"),\n  );\n  if (!searchToolKey || !tools[searchToolKey]?.execute) return [];\n\n  try {\n    const result = await tools[searchToolKey].execute!({ limit: 100 });\n\n    // Cloudflare getAITools() returns MCP CallToolResult objects, not strings.\n    // Extract JSON text from either a plain string or a CallToolResult shape.\n    let json: string | undefined;\n    if (typeof result === \"string\") {\n      json = result;\n    } else if (result && typeof result === \"object\") {\n      const content = (\n        result as {\n          content?: Array<{\n            type: string;\n            resource?: { text?: string };\n            text?: string;\n          }>;\n        }\n      ).content;\n      const first = content?.[0];\n      json = first?.resource?.text ?? first?.text;\n    }\n\n    if (typeof json === \"string\") {\n      const parsed = JSON.parse(json);\n      if (parsed && typeof parsed === \"object\") {\n        return parseIntegrationStatus(\n          Array.isArray(parsed.items) ? parsed.items : [],\n          Array.isArray(parsed.errors) ? parsed.errors : [],\n          Array.isArray(parsed.elicitations) ? parsed.elicitations : [],\n        );\n      }\n    }\n  } catch (err: unknown) {\n    // All integrations disconnected: -32042 error contains elicitations\n    const elicitations = extractElicitations(err);\n    if (elicitations?.length) {\n      return elicitations\n        .filter(\n          (e): e is ElicitationEntry & { integrationId: string } =>\n            !!e.integrationId,\n        )\n        .map((e) => ({\n          id: e.integrationId,\n          name: e.integrationName ?? e.integrationId,\n          connected: false,\n          connectUrl: e.url,\n        }));\n    }\n  }\n\n  return [];\n}\n\n// ============================================================================\n// Tool wrapping\n// ============================================================================\n\n/** A tool with an optional async execute method */\nexport interface ToolLike {\n  execute?: (...args: unknown[]) => Promise<unknown>;\n  [key: string]: unknown;\n}\n\n/** Record of named tools */\nexport type ToolSetLike = Record<string, ToolLike>;\n\n/**\n * Extract elicitation entries from an error thrown by the MCP SDK.\n * Handles two shapes: direct code/data and nested cause.\n */\nexport function extractElicitations(\n  err: unknown,\n): ElicitationEntry[] | undefined {\n  const error = err as {\n    code?: number;\n    data?: { elicitations?: ElicitationEntry[] };\n    cause?: {\n      code?: number;\n      data?: { elicitations?: ElicitationEntry[] };\n    };\n  };\n\n  // Primary: structured McpError with code -32042\n  if (error?.code === -32042 && error?.data?.elicitations?.length) {\n    return error.data.elicitations;\n  }\n\n  // Nested cause (some SDK wrappers nest the original error)\n  if (\n    error?.cause?.code === -32042 &&\n    error?.cause?.data?.elicitations?.length\n  ) {\n    return error.cause.data.elicitations;\n  }\n\n  return undefined;\n}\n\n/**\n * Wrap tools to catch MCP error code -32042 (URL elicitation required)\n * and convert to IntegrationConnectionRequiredError.\n */\nexport function wrapToolsWithElicitation<T extends ToolSetLike>(tools: T): T {\n  return Object.fromEntries(\n    Object.entries(tools).map(([name, tool]) => [\n      name,\n      {\n        ...tool,\n        execute: tool.execute\n          ? async (...args: unknown[]) => {\n              try {\n                return await tool.execute!(...args);\n              } catch (err: unknown) {\n                const elicitations = extractElicitations(err);\n                const elicitation = elicitations?.[0];\n                if (elicitation?.url) {\n                  const integrationId = elicitation.integrationId ?? \"unknown\";\n                  throw new IntegrationConnectionRequiredError(integrationId, {\n                    integrationName: elicitation.integrationName,\n                    connectUrl: elicitation.url,\n                    message: elicitation.message,\n                  });\n                }\n                throw err;\n              }\n            }\n          : undefined,\n      },\n    ]),\n  ) as T;\n}\n","/**\n * Vercel AI SDK adapter for Kontext.\n *\n * Pure format converter: maps KontextClient tools to AI SDK CoreTools.\n *\n * @example\n * ```typescript\n * import { createKontextClient } from '@kontext-dev/js-sdk';\n * import { toKontextTools } from '@kontext-dev/js-sdk/ai';\n * import { generateText } from 'ai';\n *\n * const client = createKontextClient({\n *   clientId: process.env.KONTEXT_CLIENT_ID!,\n *   redirectUri: 'http://localhost:3000/callback',\n *   onAuthRequired: (url) => open(url.toString()),\n * });\n *\n * const { tools, systemPrompt } = await toKontextTools(client);\n * const result = await generateText({ model, system: systemPrompt, tools, prompt: '...', maxSteps: 5 });\n * ```\n *\n * @packageDocumentation\n */\n\nimport { jsonSchema, type CoreTool } from \"ai\";\nimport type {\n  KontextClient,\n  KontextTool,\n  IntegrationInfo,\n  ToolResult,\n} from \"../../client/index.js\";\nimport type { KontextOrchestrator } from \"../../client/orchestrator/index.js\";\nimport { enrichToolsWithAuthAwareness } from \"../../client/tool-utils.js\";\n\nexport interface ToKontextToolsOptions {\n  formatResult?: (result: ToolResult) => unknown;\n}\n\nexport interface KontextToolsResult {\n  readonly tools: Record<string, CoreTool>;\n  readonly systemPrompt: string;\n  readonly integrations: readonly IntegrationInfo[];\n}\n\n/**\n * Convert a KontextClient's tools into an AI SDK ToolSet with system prompt.\n *\n * Calls `client.tools.list()` and `client.integrations.list()` to discover\n * tools and integration status, then wraps each tool as an AI SDK `CoreTool`\n * whose `execute` delegates to `client.tools.execute()`.\n */\nexport async function toKontextTools(\n  client: KontextClient | KontextOrchestrator,\n  options?: ToKontextToolsOptions,\n): Promise<KontextToolsResult> {\n  const [tools, integrations] = await Promise.all([\n    client.tools.list(),\n    client.integrations.list(),\n  ]);\n\n  const coreTools: Record<string, CoreTool> = {};\n  const usedNames = new Set<string>();\n\n  for (const tool of tools) {\n    const name = buildToolName(tool, usedNames);\n    coreTools[name] = {\n      description: formatDescription(tool),\n      parameters: tool.inputSchema\n        ? jsonSchema(tool.inputSchema as Parameters<typeof jsonSchema>[0])\n        : jsonSchema({ type: \"object\" as const, properties: {} }),\n      execute: async (args: Record<string, unknown>) => {\n        const r = await client.tools.execute(tool.id, args);\n        return (options?.formatResult ?? defaultFormat)(r);\n      },\n    };\n  }\n\n  const { systemPrompt, requestCapabilityTool } = enrichToolsWithAuthAwareness(\n    tools.map((t) => t.name),\n    integrations,\n  );\n\n  if (requestCapabilityTool) {\n    coreTools[requestCapabilityTool.name] = {\n      description: requestCapabilityTool.description,\n      parameters: jsonSchema(\n        requestCapabilityTool.parameters as Parameters<typeof jsonSchema>[0],\n      ),\n      execute: async (args: Record<string, unknown>) => {\n        return requestCapabilityTool.execute(args);\n      },\n    };\n  }\n\n  return { tools: coreTools, systemPrompt, integrations };\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nfunction defaultFormat(r: ToolResult): unknown {\n  return r.content;\n}\n\nfunction formatDescription(tool: KontextTool): string {\n  const base = tool.description ?? tool.name;\n  const serverLabel = tool.server?.name ?? tool.server?.id;\n  return serverLabel ? `[${serverLabel}] ${base}` : base;\n}\n\nfunction buildToolName(tool: KontextTool, usedNames: Set<string>): string {\n  const rawName = tool.name || tool.id || \"tool\";\n  const base = tool.server\n    ? `${tool.server.name ?? tool.server.id ?? \"server\"}_${rawName}`\n    : rawName;\n  const sanitized = sanitizeToolName(base);\n  const fallback = sanitized || `tool_${usedNames.size + 1}`;\n\n  let name = fallback;\n  let suffix = 1;\n  while (usedNames.has(name)) {\n    name = `${fallback}_${suffix}`;\n    suffix += 1;\n  }\n\n  usedNames.add(name);\n  return name;\n}\n\nfunction sanitizeToolName(name: string): string {\n  return name\n    .replace(/[^a-zA-Z0-9_-]/g, \"_\")\n    .replace(/_+/g, \"_\")\n    .replace(/^_+|_+$/g, \"\")\n    .slice(0, 64);\n}\n"]}

package/dist/adapters/ai/index.d.cts

@@ -0,0 +1,51 @@
+import { CoreTool } from 'ai';
+import { IntegrationInfo, ToolResult, KontextClient } from '../../client/index.cjs';
+import { K as KontextOrchestrator } from '../../index-DcL4a5Vq.cjs';
+import '../../mcp/index.cjs';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '@modelcontextprotocol/sdk/types.js';
+import '../../types-RIzHnRpk.cjs';
+import '../../errors.cjs';
+
+/**
+ * Vercel AI SDK adapter for Kontext.
+ *
+ * Pure format converter: maps KontextClient tools to AI SDK CoreTools.
+ *
+ * @example
+ * ```typescript
+ * import { createKontextClient } from '@kontext-dev/js-sdk';
+ * import { toKontextTools } from '@kontext-dev/js-sdk/ai';
+ * import { generateText } from 'ai';
+ *
+ * const client = createKontextClient({
+ *   clientId: process.env.KONTEXT_CLIENT_ID!,
+ *   redirectUri: 'http://localhost:3000/callback',
+ *   onAuthRequired: (url) => open(url.toString()),
+ * });
+ *
+ * const { tools, systemPrompt } = await toKontextTools(client);
+ * const result = await generateText({ model, system: systemPrompt, tools, prompt: '...', maxSteps: 5 });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+interface ToKontextToolsOptions {
+    formatResult?: (result: ToolResult) => unknown;
+}
+interface KontextToolsResult {
+    readonly tools: Record<string, CoreTool>;
+    readonly systemPrompt: string;
+    readonly integrations: readonly IntegrationInfo[];
+}
+/**
+ * Convert a KontextClient's tools into an AI SDK ToolSet with system prompt.
+ *
+ * Calls `client.tools.list()` and `client.integrations.list()` to discover
+ * tools and integration status, then wraps each tool as an AI SDK `CoreTool`
+ * whose `execute` delegates to `client.tools.execute()`.
+ */
+declare function toKontextTools(client: KontextClient | KontextOrchestrator, options?: ToKontextToolsOptions): Promise<KontextToolsResult>;
+
+export { type KontextToolsResult, type ToKontextToolsOptions, toKontextTools };

package/dist/adapters/ai/index.d.ts

@@ -0,0 +1,51 @@
+import { CoreTool } from 'ai';
+import { IntegrationInfo, ToolResult, KontextClient } from '../../client/index.js';
+import { K as KontextOrchestrator } from '../../index-D5hS5PGn.js';
+import '../../mcp/index.js';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '@modelcontextprotocol/sdk/types.js';
+import '../../types-RIzHnRpk.js';
+import '../../errors.js';
+
+/**
+ * Vercel AI SDK adapter for Kontext.
+ *
+ * Pure format converter: maps KontextClient tools to AI SDK CoreTools.
+ *
+ * @example
+ * ```typescript
+ * import { createKontextClient } from '@kontext-dev/js-sdk';
+ * import { toKontextTools } from '@kontext-dev/js-sdk/ai';
+ * import { generateText } from 'ai';
+ *
+ * const client = createKontextClient({
+ *   clientId: process.env.KONTEXT_CLIENT_ID!,
+ *   redirectUri: 'http://localhost:3000/callback',
+ *   onAuthRequired: (url) => open(url.toString()),
+ * });
+ *
+ * const { tools, systemPrompt } = await toKontextTools(client);
+ * const result = await generateText({ model, system: systemPrompt, tools, prompt: '...', maxSteps: 5 });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+interface ToKontextToolsOptions {
+    formatResult?: (result: ToolResult) => unknown;
+}
+interface KontextToolsResult {
+    readonly tools: Record<string, CoreTool>;
+    readonly systemPrompt: string;
+    readonly integrations: readonly IntegrationInfo[];
+}
+/**
+ * Convert a KontextClient's tools into an AI SDK ToolSet with system prompt.
+ *
+ * Calls `client.tools.list()` and `client.integrations.list()` to discover
+ * tools and integration status, then wraps each tool as an AI SDK `CoreTool`
+ * whose `execute` delegates to `client.tools.execute()`.
+ */
+declare function toKontextTools(client: KontextClient | KontextOrchestrator, options?: ToKontextToolsOptions): Promise<KontextToolsResult>;
+
+export { type KontextToolsResult, type ToKontextToolsOptions, toKontextTools };

package/dist/adapters/ai/index.js

@@ -0,0 +1,173 @@
+import { jsonSchema } from 'ai';
+
+// src/adapters/ai/index.ts
+
+// src/client/tool-utils.ts
+function buildKontextSystemPrompt(toolNames, integrations) {
+  if (toolNames.length === 0) return "";
+  const searchTool = toolNames.find((n) => n.endsWith("_SEARCH_TOOLS"));
+  const executeTool = toolNames.find((n) => n.endsWith("_EXECUTE_TOOL"));
+  const requestCapabilityTool = toolNames.find(
+    (n) => n.endsWith("_REQUEST_CAPABILITY")
+  );
+  let prompt = "You are a helpful assistant with access to various tools and integrations through Kontext.\nYou can help users with tasks across their connected services (GitHub, Linear, Slack, etc.).\nWhen a user asks about their services, use the available MCP tools to help them.\nThe user has already authenticated \u2014 tools run as the user with their permissions, including access to private repositories and org resources.";
+  if (searchTool && executeTool) {
+    prompt += `
+
+You have access to external integrations through Kontext MCP tools:
+- Call \`${searchTool}\` first to discover what tools/integrations are available.
+- Then call \`${executeTool}\` with the tool_id and arguments to run a specific tool.
+- When the user asks about "my repos", "my issues", etc., use the appropriate tool to look up their data directly. Do not ask for their username \u2014 the tools already know who they are.
+Always start by searching for tools when the user asks about their connected services.`;
+  }
+  if (integrations.length > 0) {
+    const connected = integrations.filter((i) => i.connected);
+    const disconnected = integrations.filter((i) => !i.connected);
+    if (disconnected.length > 0) {
+      prompt += "\n\n## Integration Status";
+      if (connected.length > 0) {
+        prompt += `
+
+You already have access to: ${connected.map((i) => i.name).join(", ")}`;
+      }
+      prompt += `
+
+The following services require user authorization: ${disconnected.map((i) => i.name).join(", ")}`;
+      if (requestCapabilityTool) {
+        const example = disconnected[0]?.name ?? "GitHub";
+        prompt += `
+
+**IMPORTANT:** When the user requests an action that requires one of these services:
+1. Call the \`${requestCapabilityTool}\` tool with \`capability_name\` set to the service name (e.g. "${example}")
+2. The tool will return an authorization link
+3. Include the link in your response so the user can click it to connect
+4. After the user authorizes, the service will be available on their next message`;
+      } else {
+        prompt += "\n\nWhen the user asks about a disconnected integration, let them know it needs to be connected first. Do not attempt to use tools from disconnected integrations without informing the user.";
+      }
+    }
+  }
+  return prompt;
+}
+function enrichToolsWithAuthAwareness(toolNames, integrations, options) {
+  const hasDisconnected = integrations.some(
+    (i) => !i.connected && i.connectUrl
+  );
+  if (!hasDisconnected) {
+    return {
+      systemPrompt: buildKontextSystemPrompt(toolNames, integrations),
+      requestCapabilityTool: null
+    };
+  }
+  const prefix = toolNames.find((n) => n.endsWith("_SEARCH_TOOLS"))?.replace(/_SEARCH_TOOLS$/, "") ?? "kontext";
+  const toolName = `${prefix}_REQUEST_CAPABILITY`;
+  const tool = buildRequestCapabilityTool(integrations);
+  const allToolNames = [...toolNames, toolName];
+  return {
+    systemPrompt: buildKontextSystemPrompt(allToolNames, integrations),
+    requestCapabilityTool: { name: toolName, ...tool }
+  };
+}
+function buildRequestCapabilityTool(capabilities) {
+  const disconnected = capabilities.filter((c) => !c.connected && c.connectUrl);
+  const capabilityList = disconnected.length > 0 ? disconnected.map((c) => c.name).join(", ") : "none";
+  return {
+    description: `Request connection to a capability that is not yet connected. Currently disconnected capabilities: ${capabilityList}. Call this tool with the capability name to initiate the connection flow.`,
+    parameters: {
+      type: "object",
+      properties: {
+        capability_name: {
+          type: "string",
+          description: "The name of the capability to connect"
+        }
+      },
+      required: ["capability_name"]
+    },
+    execute: async (...args) => {
+      const input = args[0] ?? {};
+      const name = input.capability_name ?? "";
+      if (!name && disconnected.length === 1 && disconnected[0]) {
+        return `${disconnected[0].name} requires authorization. Please visit the following link to connect: ${disconnected[0].connectUrl}`;
+      }
+      const match = disconnected.find(
+        (c) => c.name.toLowerCase() === name.toLowerCase()
+      );
+      if (!match) {
+        const isConnected = capabilities.find(
+          (c) => c.connected && c.name.toLowerCase() === name.toLowerCase()
+        );
+        if (isConnected) {
+          return `${isConnected.name} is already connected and ready to use.`;
+        }
+        return `Unknown capability "${name}". Available disconnected capabilities: ${capabilityList}.`;
+      }
+      return `${match.name} requires authorization. Please visit the following link to connect: ${match.connectUrl}`;
+    }
+  };
+}
+
+// src/adapters/ai/index.ts
+async function toKontextTools(client, options) {
+  const [tools, integrations] = await Promise.all([
+    client.tools.list(),
+    client.integrations.list()
+  ]);
+  const coreTools = {};
+  const usedNames = /* @__PURE__ */ new Set();
+  for (const tool of tools) {
+    const name = buildToolName(tool, usedNames);
+    coreTools[name] = {
+      description: formatDescription(tool),
+      parameters: tool.inputSchema ? jsonSchema(tool.inputSchema) : jsonSchema({ type: "object", properties: {} }),
+      execute: async (args) => {
+        const r = await client.tools.execute(tool.id, args);
+        return (options?.formatResult ?? defaultFormat)(r);
+      }
+    };
+  }
+  const { systemPrompt, requestCapabilityTool } = enrichToolsWithAuthAwareness(
+    tools.map((t) => t.name),
+    integrations
+  );
+  if (requestCapabilityTool) {
+    coreTools[requestCapabilityTool.name] = {
+      description: requestCapabilityTool.description,
+      parameters: jsonSchema(
+        requestCapabilityTool.parameters
+      ),
+      execute: async (args) => {
+        return requestCapabilityTool.execute(args);
+      }
+    };
+  }
+  return { tools: coreTools, systemPrompt, integrations };
+}
+function defaultFormat(r) {
+  return r.content;
+}
+function formatDescription(tool) {
+  const base = tool.description ?? tool.name;
+  const serverLabel = tool.server?.name ?? tool.server?.id;
+  return serverLabel ? `[${serverLabel}] ${base}` : base;
+}
+function buildToolName(tool, usedNames) {
+  const rawName = tool.name || tool.id || "tool";
+  const base = tool.server ? `${tool.server.name ?? tool.server.id ?? "server"}_${rawName}` : rawName;
+  const sanitized = sanitizeToolName(base);
+  const fallback = sanitized || `tool_${usedNames.size + 1}`;
+  let name = fallback;
+  let suffix = 1;
+  while (usedNames.has(name)) {
+    name = `${fallback}_${suffix}`;
+    suffix += 1;
+  }
+  usedNames.add(name);
+  return name;
+}
+function sanitizeToolName(name) {
+  return name.replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "").slice(0, 64);
+}
+
+export { toKontextTools };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/adapters/ai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/client/tool-utils.ts","../../../src/adapters/ai/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Shared utilities for Kontext tool handling.\n * Used by both KontextClient (core) and withKontext (Cloudflare adapter).\n */\n\nimport {\n  IntegrationConnectionRequiredError,\n  type ElicitationEntry,\n} from \"../errors.js\";\n\n// Re-export for backward compatibility\nexport type { ElicitationEntry } from \"../errors.js\";\n\n// ============================================================================\n// Shared types\n// ============================================================================\n\nexport interface IntegrationStatus {\n  readonly id: string;\n  readonly name: string;\n  readonly connected: boolean;\n  readonly connectUrl?: string;\n}\n\n// ============================================================================\n// System prompt\n// ============================================================================\n\n/**\n * Build an LLM system prompt based on available tool names and integration status.\n * Detects `*_SEARCH_TOOLS` / `*_EXECUTE_TOOL` suffixed names from the\n * Cloudflare Agents MCP proxy and generates appropriate guidance.\n */\nexport function buildKontextSystemPrompt(\n  toolNames: readonly string[],\n  integrations: readonly IntegrationStatus[],\n): string {\n  if (toolNames.length === 0) return \"\";\n\n  const searchTool = toolNames.find((n) => n.endsWith(\"_SEARCH_TOOLS\"));\n  const executeTool = toolNames.find((n) => n.endsWith(\"_EXECUTE_TOOL\"));\n  const requestCapabilityTool = toolNames.find((n) =>\n    n.endsWith(\"_REQUEST_CAPABILITY\"),\n  );\n\n  let prompt =\n    \"You are a helpful assistant with access to various tools and integrations through Kontext.\\n\" +\n    \"You can help users with tasks across their connected services (GitHub, Linear, Slack, etc.).\\n\" +\n    \"When a user asks about their services, use the available MCP tools to help them.\\n\" +\n    \"The user has already authenticated — tools run as the user with their permissions, including access to private repositories and org resources.\";\n\n  if (searchTool && executeTool) {\n    prompt +=\n      `\\n\\nYou have access to external integrations through Kontext MCP tools:\\n` +\n      `- Call \\`${searchTool}\\` first to discover what tools/integrations are available.\\n` +\n      `- Then call \\`${executeTool}\\` with the tool_id and arguments to run a specific tool.\\n` +\n      `- When the user asks about \"my repos\", \"my issues\", etc., use the appropriate tool to look up their data directly. Do not ask for their username — the tools already know who they are.\\n` +\n      `Always start by searching for tools when the user asks about their connected services.`;\n  }\n\n  // Append integration status section when there are integrations to report\n  if (integrations.length > 0) {\n    const connected = integrations.filter((i) => i.connected);\n    const disconnected = integrations.filter((i) => !i.connected);\n\n    if (disconnected.length > 0) {\n      prompt += \"\\n\\n## Integration Status\";\n\n      if (connected.length > 0) {\n        prompt += `\\n\\nYou already have access to: ${connected.map((i) => i.name).join(\", \")}`;\n      }\n\n      prompt += `\\n\\nThe following services require user authorization: ${disconnected.map((i) => i.name).join(\", \")}`;\n\n      if (requestCapabilityTool) {\n        const example = disconnected[0]?.name ?? \"GitHub\";\n        prompt +=\n          `\\n\\n**IMPORTANT:** When the user requests an action that requires one of these services:` +\n          `\\n1. Call the \\`${requestCapabilityTool}\\` tool with \\`capability_name\\` set to the service name (e.g. \"${example}\")` +\n          `\\n2. The tool will return an authorization link` +\n          `\\n3. Include the link in your response so the user can click it to connect` +\n          `\\n4. After the user authorizes, the service will be available on their next message`;\n      } else {\n        prompt +=\n          \"\\n\\nWhen the user asks about a disconnected integration, let them know it needs to be connected first. Do not attempt to use tools from disconnected integrations without informing the user.\";\n      }\n    }\n  }\n\n  return prompt;\n}\n\n// ============================================================================\n// Auth-aware toolset orchestrator\n// ============================================================================\n\nexport interface AuthAwareToolset {\n  /** System prompt with integration status and REQUEST_CAPABILITY instructions. */\n  readonly systemPrompt: string;\n  /** REQUEST_CAPABILITY tool to inject, or null if all integrations are connected. */\n  readonly requestCapabilityTool: {\n    readonly name: string;\n    readonly description: string;\n    readonly parameters: Record<string, unknown>;\n    readonly execute: (...args: unknown[]) => Promise<string>;\n  } | null;\n}\n\n/**\n * Enrich a tool set with auth awareness.\n *\n * Given tool names and integration status, produces:\n * - A system prompt that tells the LLM about connected/disconnected integrations\n * - A REQUEST_CAPABILITY tool (if needed) that returns auth URLs as text\n *\n * Both `ai/` and `cloudflare/` adapters use this as their core auth layer.\n */\nexport function enrichToolsWithAuthAwareness(\n  toolNames: readonly string[],\n  integrations: readonly IntegrationStatus[],\n  options?: { prefix?: string },\n): AuthAwareToolset {\n  const hasDisconnected = integrations.some(\n    (i) => !i.connected && i.connectUrl,\n  );\n\n  if (!hasDisconnected) {\n    return {\n      systemPrompt: buildKontextSystemPrompt(toolNames, integrations),\n      requestCapabilityTool: null,\n    };\n  }\n\n  // Determine prefix from existing tool names or option\n  const prefix =\n    options?.prefix ??\n    toolNames\n      .find((n) => n.endsWith(\"_SEARCH_TOOLS\"))\n      ?.replace(/_SEARCH_TOOLS$/, \"\") ??\n    \"kontext\";\n\n  const toolName = `${prefix}_REQUEST_CAPABILITY`;\n  const tool = buildRequestCapabilityTool(integrations);\n\n  // Include REQUEST_CAPABILITY in tool names so the system prompt references it\n  const allToolNames = [...toolNames, toolName];\n\n  return {\n    systemPrompt: buildKontextSystemPrompt(allToolNames, integrations),\n    requestCapabilityTool: { name: toolName, ...tool },\n  };\n}\n\n// ============================================================================\n// Integration status parsing\n// ============================================================================\n\n/**\n * Parse integration status from gateway tool search results.\n * Extracts connected integrations from tools and disconnected from errors.\n */\nexport function parseIntegrationStatus(\n  tools: ReadonlyArray<{ server?: { id?: string; name?: string } }>,\n  errors: ReadonlyArray<{ serverId: string; serverName?: string }>,\n  elicitations?: ReadonlyArray<{\n    url: string;\n    integrationId?: string;\n    integrationName?: string;\n  }>,\n): IntegrationStatus[] {\n  const seen = new Set<string>();\n  const result: IntegrationStatus[] = [];\n\n  for (const t of tools) {\n    const sid = t.server?.id;\n    if (sid && !seen.has(sid)) {\n      seen.add(sid);\n      result.push({\n        id: sid,\n        name: t.server?.name ?? sid,\n        connected: true,\n      });\n    }\n  }\n\n  for (const e of errors) {\n    if (!seen.has(e.serverId)) {\n      seen.add(e.serverId);\n      const elicitation = elicitations?.find(\n        (el) => el.integrationId === e.serverId,\n      );\n      result.push({\n        id: e.serverId,\n        name: e.serverName ?? e.serverId,\n        connected: false,\n        connectUrl: elicitation?.url,\n      });\n    }\n  }\n\n  return result;\n}\n\n// ============================================================================\n// Request capability tool\n// ============================================================================\n\n/**\n * Build a tool that lets the LLM request connection of a disconnected capability.\n * Returns the connect URL as text so the LLM can present it to the user.\n * No popups — the user clicks the link in the chat to authorize.\n */\nexport function buildRequestCapabilityTool(\n  capabilities: readonly IntegrationStatus[],\n): {\n  description: string;\n  parameters: Record<string, unknown>;\n  execute: (...args: unknown[]) => Promise<string>;\n} {\n  const disconnected = capabilities.filter((c) => !c.connected && c.connectUrl);\n\n  const capabilityList =\n    disconnected.length > 0\n      ? disconnected.map((c) => c.name).join(\", \")\n      : \"none\";\n\n  return {\n    description:\n      `Request connection to a capability that is not yet connected. ` +\n      `Currently disconnected capabilities: ${capabilityList}. ` +\n      `Call this tool with the capability name to initiate the connection flow.`,\n    parameters: {\n      type: \"object\",\n      properties: {\n        capability_name: {\n          type: \"string\",\n          description: \"The name of the capability to connect\",\n        },\n      },\n      required: [\"capability_name\"],\n    },\n    execute: async (...args: unknown[]): Promise<string> => {\n      const input = (args[0] ?? {}) as { capability_name?: string };\n      const name = input.capability_name ?? \"\";\n\n      // Auto-select when called without a name and there's only one option\n      if (!name && disconnected.length === 1 && disconnected[0]) {\n        return (\n          `${disconnected[0].name} requires authorization. ` +\n          `Please visit the following link to connect: ${disconnected[0].connectUrl}`\n        );\n      }\n\n      const match = disconnected.find(\n        (c) => c.name.toLowerCase() === name.toLowerCase(),\n      );\n\n      if (!match) {\n        const isConnected = capabilities.find(\n          (c) => c.connected && c.name.toLowerCase() === name.toLowerCase(),\n        );\n        if (isConnected) {\n          return `${isConnected.name} is already connected and ready to use.`;\n        }\n        return `Unknown capability \"${name}\". Available disconnected capabilities: ${capabilityList}.`;\n      }\n\n      return (\n        `${match.name} requires authorization. ` +\n        `Please visit the following link to connect: ${match.connectUrl}`\n      );\n    },\n  };\n}\n\n/**\n * Pre-flight integration status detection.\n * Calls SEARCH_TOOLS on raw (unwrapped) tools to detect connected/disconnected\n * integrations without triggering any popups or broadcasts.\n */\nexport async function preflightIntegrationStatus(\n  tools: ToolSetLike,\n): Promise<IntegrationStatus[]> {\n  const searchToolKey = Object.keys(tools).find((k) =>\n    k.endsWith(\"_SEARCH_TOOLS\"),\n  );\n  if (!searchToolKey || !tools[searchToolKey]?.execute) return [];\n\n  try {\n    const result = await tools[searchToolKey].execute!({ limit: 100 });\n\n    // Cloudflare getAITools() returns MCP CallToolResult objects, not strings.\n    // Extract JSON text from either a plain string or a CallToolResult shape.\n    let json: string | undefined;\n    if (typeof result === \"string\") {\n      json = result;\n    } else if (result && typeof result === \"object\") {\n      const content = (\n        result as {\n          content?: Array<{\n            type: string;\n            resource?: { text?: string };\n            text?: string;\n          }>;\n        }\n      ).content;\n      const first = content?.[0];\n      json = first?.resource?.text ?? first?.text;\n    }\n\n    if (typeof json === \"string\") {\n      const parsed = JSON.parse(json);\n      if (parsed && typeof parsed === \"object\") {\n        return parseIntegrationStatus(\n          Array.isArray(parsed.items) ? parsed.items : [],\n          Array.isArray(parsed.errors) ? parsed.errors : [],\n          Array.isArray(parsed.elicitations) ? parsed.elicitations : [],\n        );\n      }\n    }\n  } catch (err: unknown) {\n    // All integrations disconnected: -32042 error contains elicitations\n    const elicitations = extractElicitations(err);\n    if (elicitations?.length) {\n      return elicitations\n        .filter(\n          (e): e is ElicitationEntry & { integrationId: string } =>\n            !!e.integrationId,\n        )\n        .map((e) => ({\n          id: e.integrationId,\n          name: e.integrationName ?? e.integrationId,\n          connected: false,\n          connectUrl: e.url,\n        }));\n    }\n  }\n\n  return [];\n}\n\n// ============================================================================\n// Tool wrapping\n// ============================================================================\n\n/** A tool with an optional async execute method */\nexport interface ToolLike {\n  execute?: (...args: unknown[]) => Promise<unknown>;\n  [key: string]: unknown;\n}\n\n/** Record of named tools */\nexport type ToolSetLike = Record<string, ToolLike>;\n\n/**\n * Extract elicitation entries from an error thrown by the MCP SDK.\n * Handles two shapes: direct code/data and nested cause.\n */\nexport function extractElicitations(\n  err: unknown,\n): ElicitationEntry[] | undefined {\n  const error = err as {\n    code?: number;\n    data?: { elicitations?: ElicitationEntry[] };\n    cause?: {\n      code?: number;\n      data?: { elicitations?: ElicitationEntry[] };\n    };\n  };\n\n  // Primary: structured McpError with code -32042\n  if (error?.code === -32042 && error?.data?.elicitations?.length) {\n    return error.data.elicitations;\n  }\n\n  // Nested cause (some SDK wrappers nest the original error)\n  if (\n    error?.cause?.code === -32042 &&\n    error?.cause?.data?.elicitations?.length\n  ) {\n    return error.cause.data.elicitations;\n  }\n\n  return undefined;\n}\n\n/**\n * Wrap tools to catch MCP error code -32042 (URL elicitation required)\n * and convert to IntegrationConnectionRequiredError.\n */\nexport function wrapToolsWithElicitation<T extends ToolSetLike>(tools: T): T {\n  return Object.fromEntries(\n    Object.entries(tools).map(([name, tool]) => [\n      name,\n      {\n        ...tool,\n        execute: tool.execute\n          ? async (...args: unknown[]) => {\n              try {\n                return await tool.execute!(...args);\n              } catch (err: unknown) {\n                const elicitations = extractElicitations(err);\n                const elicitation = elicitations?.[0];\n                if (elicitation?.url) {\n                  const integrationId = elicitation.integrationId ?? \"unknown\";\n                  throw new IntegrationConnectionRequiredError(integrationId, {\n                    integrationName: elicitation.integrationName,\n                    connectUrl: elicitation.url,\n                    message: elicitation.message,\n                  });\n                }\n                throw err;\n              }\n            }\n          : undefined,\n      },\n    ]),\n  ) as T;\n}\n","/**\n * Vercel AI SDK adapter for Kontext.\n *\n * Pure format converter: maps KontextClient tools to AI SDK CoreTools.\n *\n * @example\n * ```typescript\n * import { createKontextClient } from '@kontext-dev/js-sdk';\n * import { toKontextTools } from '@kontext-dev/js-sdk/ai';\n * import { generateText } from 'ai';\n *\n * const client = createKontextClient({\n *   clientId: process.env.KONTEXT_CLIENT_ID!,\n *   redirectUri: 'http://localhost:3000/callback',\n *   onAuthRequired: (url) => open(url.toString()),\n * });\n *\n * const { tools, systemPrompt } = await toKontextTools(client);\n * const result = await generateText({ model, system: systemPrompt, tools, prompt: '...', maxSteps: 5 });\n * ```\n *\n * @packageDocumentation\n */\n\nimport { jsonSchema, type CoreTool } from \"ai\";\nimport type {\n  KontextClient,\n  KontextTool,\n  IntegrationInfo,\n  ToolResult,\n} from \"../../client/index.js\";\nimport type { KontextOrchestrator } from \"../../client/orchestrator/index.js\";\nimport { enrichToolsWithAuthAwareness } from \"../../client/tool-utils.js\";\n\nexport interface ToKontextToolsOptions {\n  formatResult?: (result: ToolResult) => unknown;\n}\n\nexport interface KontextToolsResult {\n  readonly tools: Record<string, CoreTool>;\n  readonly systemPrompt: string;\n  readonly integrations: readonly IntegrationInfo[];\n}\n\n/**\n * Convert a KontextClient's tools into an AI SDK ToolSet with system prompt.\n *\n * Calls `client.tools.list()` and `client.integrations.list()` to discover\n * tools and integration status, then wraps each tool as an AI SDK `CoreTool`\n * whose `execute` delegates to `client.tools.execute()`.\n */\nexport async function toKontextTools(\n  client: KontextClient | KontextOrchestrator,\n  options?: ToKontextToolsOptions,\n): Promise<KontextToolsResult> {\n  const [tools, integrations] = await Promise.all([\n    client.tools.list(),\n    client.integrations.list(),\n  ]);\n\n  const coreTools: Record<string, CoreTool> = {};\n  const usedNames = new Set<string>();\n\n  for (const tool of tools) {\n    const name = buildToolName(tool, usedNames);\n    coreTools[name] = {\n      description: formatDescription(tool),\n      parameters: tool.inputSchema\n        ? jsonSchema(tool.inputSchema as Parameters<typeof jsonSchema>[0])\n        : jsonSchema({ type: \"object\" as const, properties: {} }),\n      execute: async (args: Record<string, unknown>) => {\n        const r = await client.tools.execute(tool.id, args);\n        return (options?.formatResult ?? defaultFormat)(r);\n      },\n    };\n  }\n\n  const { systemPrompt, requestCapabilityTool } = enrichToolsWithAuthAwareness(\n    tools.map((t) => t.name),\n    integrations,\n  );\n\n  if (requestCapabilityTool) {\n    coreTools[requestCapabilityTool.name] = {\n      description: requestCapabilityTool.description,\n      parameters: jsonSchema(\n        requestCapabilityTool.parameters as Parameters<typeof jsonSchema>[0],\n      ),\n      execute: async (args: Record<string, unknown>) => {\n        return requestCapabilityTool.execute(args);\n      },\n    };\n  }\n\n  return { tools: coreTools, systemPrompt, integrations };\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nfunction defaultFormat(r: ToolResult): unknown {\n  return r.content;\n}\n\nfunction formatDescription(tool: KontextTool): string {\n  const base = tool.description ?? tool.name;\n  const serverLabel = tool.server?.name ?? tool.server?.id;\n  return serverLabel ? `[${serverLabel}] ${base}` : base;\n}\n\nfunction buildToolName(tool: KontextTool, usedNames: Set<string>): string {\n  const rawName = tool.name || tool.id || \"tool\";\n  const base = tool.server\n    ? `${tool.server.name ?? tool.server.id ?? \"server\"}_${rawName}`\n    : rawName;\n  const sanitized = sanitizeToolName(base);\n  const fallback = sanitized || `tool_${usedNames.size + 1}`;\n\n  let name = fallback;\n  let suffix = 1;\n  while (usedNames.has(name)) {\n    name = `${fallback}_${suffix}`;\n    suffix += 1;\n  }\n\n  usedNames.add(name);\n  return name;\n}\n\nfunction sanitizeToolName(name: string): string {\n  return name\n    .replace(/[^a-zA-Z0-9_-]/g, \"_\")\n    .replace(/_+/g, \"_\")\n    .replace(/^_+|_+$/g, \"\")\n    .slice(0, 64);\n}\n"]}