@kontext-dev/js-sdk 0.1.0

package/dist/adapters/cloudflare/index.js

@@ -0,0 +1,594 @@
+// src/errors.ts
+var KontextError = class extends Error {
+  /** Brand field for type narrowing without instanceof */
+  kontextError = true;
+  /** Machine-readable error code, always prefixed with `kontext_` */
+  code;
+  /** HTTP status code when applicable */
+  statusCode;
+  /** Auto-generated link to error documentation */
+  docsUrl;
+  /** Server request ID for debugging / support escalation */
+  requestId;
+  /** Contextual metadata bag (integration IDs, param names, etc.) */
+  meta;
+  constructor(message, code, options) {
+    super(message, { cause: options?.cause });
+    this.name = "KontextError";
+    this.code = code;
+    this.statusCode = options?.statusCode;
+    this.requestId = options?.requestId;
+    this.meta = options?.meta ?? {};
+    this.docsUrl = `https://docs.kontext.dev/errors/${code}`;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      docsUrl: this.docsUrl,
+      requestId: this.requestId,
+      meta: Object.keys(this.meta).length > 0 ? this.meta : void 0
+    };
+  }
+  toString() {
+    const parts = [`[${this.code}] ${this.message}`];
+    if (this.docsUrl) parts.push(`Docs: ${this.docsUrl}`);
+    if (this.requestId) parts.push(`Request ID: ${this.requestId}`);
+    return parts.join("\n");
+  }
+};
+var OAuthError = class extends KontextError {
+  errorCode;
+  errorDescription;
+  constructor(message, code, options) {
+    super(message, code, {
+      statusCode: options?.statusCode ?? 400,
+      ...options
+    });
+    this.name = "OAuthError";
+    this.errorCode = options?.errorCode;
+    this.errorDescription = options?.errorDescription;
+  }
+};
+var IntegrationConnectionRequiredError = class extends KontextError {
+  integrationId;
+  integrationName;
+  connectUrl;
+  constructor(integrationId, options) {
+    super(
+      options?.message ?? `Connection to integration "${integrationId}" is required. Visit the connect URL to authorize.`,
+      "kontext_integration_connection_required",
+      { statusCode: 403, ...options }
+    );
+    this.name = "IntegrationConnectionRequiredError";
+    this.integrationId = integrationId;
+    this.integrationName = options?.integrationName;
+    this.connectUrl = options?.connectUrl;
+  }
+};
+var ConfigError = class extends KontextError {
+  constructor(message, code, options) {
+    super(message, code, options);
+    this.name = "ConfigError";
+  }
+};
+
+// 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 parseIntegrationStatus(tools, errors, elicitations) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const t of tools) {
+    const sid = t.server?.id;
+    if (sid && !seen.has(sid)) {
+      seen.add(sid);
+      result.push({
+        id: sid,
+        name: t.server?.name ?? sid,
+        connected: true
+      });
+    }
+  }
+  for (const e of errors) {
+    if (!seen.has(e.serverId)) {
+      seen.add(e.serverId);
+      const elicitation = elicitations?.find(
+        (el) => el.integrationId === e.serverId
+      );
+      result.push({
+        id: e.serverId,
+        name: e.serverName ?? e.serverId,
+        connected: false,
+        connectUrl: elicitation?.url
+      });
+    }
+  }
+  return result;
+}
+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}`;
+    }
+  };
+}
+async function preflightIntegrationStatus(tools) {
+  const searchToolKey = Object.keys(tools).find(
+    (k) => k.endsWith("_SEARCH_TOOLS")
+  );
+  if (!searchToolKey || !tools[searchToolKey]?.execute) return [];
+  try {
+    const result = await tools[searchToolKey].execute({ limit: 100 });
+    let json;
+    if (typeof result === "string") {
+      json = result;
+    } else if (result && typeof result === "object") {
+      const content = result.content;
+      const first = content?.[0];
+      json = first?.resource?.text ?? first?.text;
+    }
+    if (typeof json === "string") {
+      const parsed = JSON.parse(json);
+      if (parsed && typeof parsed === "object") {
+        return parseIntegrationStatus(
+          Array.isArray(parsed.items) ? parsed.items : [],
+          Array.isArray(parsed.errors) ? parsed.errors : [],
+          Array.isArray(parsed.elicitations) ? parsed.elicitations : []
+        );
+      }
+    }
+  } catch (err) {
+    const elicitations = extractElicitations(err);
+    if (elicitations?.length) {
+      return elicitations.filter(
+        (e) => !!e.integrationId
+      ).map((e) => ({
+        id: e.integrationId,
+        name: e.integrationName ?? e.integrationId,
+        connected: false,
+        connectUrl: e.url
+      }));
+    }
+  }
+  return [];
+}
+function extractElicitations(err) {
+  const error = err;
+  if (error?.code === -32042 && error?.data?.elicitations?.length) {
+    return error.data.elicitations;
+  }
+  if (error?.cause?.code === -32042 && error?.cause?.data?.elicitations?.length) {
+    return error.cause.data.elicitations;
+  }
+  return void 0;
+}
+function wrapToolsWithElicitation(tools) {
+  return Object.fromEntries(
+    Object.entries(tools).map(([name, tool]) => [
+      name,
+      {
+        ...tool,
+        execute: tool.execute ? async (...args) => {
+          try {
+            return await tool.execute(...args);
+          } catch (err) {
+            const elicitations = extractElicitations(err);
+            const elicitation = elicitations?.[0];
+            if (elicitation?.url) {
+              const integrationId = elicitation.integrationId ?? "unknown";
+              throw new IntegrationConnectionRequiredError(integrationId, {
+                integrationName: elicitation.integrationName,
+                connectUrl: elicitation.url,
+                message: elicitation.message
+              });
+            }
+            throw err;
+          }
+        } : void 0
+      }
+    ])
+  );
+}
+
+// src/adapters/cloudflare/index.ts
+var STATE_EXPIRATION_MS = 10 * 60 * 1e3;
+var KontextCloudflareOAuthProvider = class {
+  authUrl;
+  serverId;
+  _clientId;
+  storage;
+  agentName;
+  _callbackUrl;
+  constructor(config) {
+    this._clientId = config.kontextClientId;
+    this.storage = config.storage;
+    this.agentName = config.agentName;
+    this._callbackUrl = config.callbackUrl;
+  }
+  get clientId() {
+    return this._clientId;
+  }
+  set clientId(_id) {
+  }
+  get redirectUrl() {
+    return this._callbackUrl;
+  }
+  get clientUri() {
+    return new URL(this._callbackUrl).origin;
+  }
+  get clientMetadata() {
+    return {
+      redirect_uris: [this._callbackUrl],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none"
+    };
+  }
+  async clientInformation() {
+    return { client_id: this._clientId };
+  }
+  async saveClientInformation(info) {
+    if (info.client_id !== this._clientId) return;
+  }
+  tokenKey() {
+    return `kontext/${this.agentName}/${this._clientId}/tokens`;
+  }
+  async tokens() {
+    return await this.storage.get(this.tokenKey()) ?? void 0;
+  }
+  async saveTokens(tokens) {
+    await this.storage.put(this.tokenKey(), tokens);
+  }
+  stateKey(nonce) {
+    return `kontext/${this.agentName}/state/${nonce}`;
+  }
+  async state() {
+    const nonce = crypto.randomUUID();
+    const sid = this.serverId ?? "unknown";
+    const stored = {
+      nonce,
+      serverId: sid,
+      createdAt: Date.now()
+    };
+    await this.storage.put(this.stateKey(nonce), stored);
+    return `${nonce}.${sid}`;
+  }
+  async checkState(state) {
+    const dotIndex = state.indexOf(".");
+    if (dotIndex === -1) {
+      return { valid: false, error: "Invalid state format" };
+    }
+    const nonce = state.slice(0, dotIndex);
+    const serverId = state.slice(dotIndex + 1);
+    const stored = await this.storage.get(this.stateKey(nonce));
+    if (!stored) {
+      return { valid: false, error: "State not found or already used" };
+    }
+    if (stored.serverId !== serverId) {
+      await this.storage.delete(this.stateKey(nonce));
+      return { valid: false, error: "State serverId mismatch" };
+    }
+    const age = Date.now() - stored.createdAt;
+    if (age > STATE_EXPIRATION_MS) {
+      await this.storage.delete(this.stateKey(nonce));
+      return { valid: false, error: "State expired" };
+    }
+    return { valid: true, serverId };
+  }
+  async consumeState(state) {
+    const dotIndex = state.indexOf(".");
+    if (dotIndex === -1) return;
+    const nonce = state.slice(0, dotIndex);
+    await this.storage.delete(this.stateKey(nonce));
+  }
+  codeVerifierKey() {
+    return `kontext/${this.agentName}/${this._clientId}/code_verifier`;
+  }
+  async saveCodeVerifier(verifier) {
+    await this.storage.put(this.codeVerifierKey(), verifier);
+  }
+  async codeVerifier() {
+    const verifier = await this.storage.get(this.codeVerifierKey());
+    if (!verifier) {
+      throw new OAuthError(
+        "No PKCE code verifier found. The OAuth flow may have expired or storage was cleared. Restart the auth flow.",
+        "kontext_oauth_code_verifier_missing"
+      );
+    }
+    return verifier;
+  }
+  async deleteCodeVerifier() {
+    await this.storage.delete(this.codeVerifierKey());
+  }
+  async redirectToAuthorization(url) {
+    this.authUrl = url.toString();
+  }
+  async invalidateCredentials(scope) {
+    if (scope === "all" || scope === "tokens") {
+      await this.storage.delete(this.tokenKey());
+    }
+    if (scope === "all" || scope === "verifier") {
+      await this.storage.delete(this.codeVerifierKey());
+    }
+  }
+};
+var DEFAULT_KONTEXT_SERVER = "https://api.kontext.dev";
+var CALLBACK_HOST_KEY = "kontext:callbackHost";
+function toOrigin(value) {
+  if (!value) return void 0;
+  try {
+    const url = new URL(value);
+    return `${url.protocol}//${url.host}`;
+  } catch {
+    return void 0;
+  }
+}
+function isLocalBrowserOrigin(origin) {
+  try {
+    const url = new URL(origin);
+    return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+  } catch {
+    return false;
+  }
+}
+function resolveLocalCallbackHost(request) {
+  const originHeader = toOrigin(request.headers.get("origin"));
+  if (originHeader && isLocalBrowserOrigin(originHeader)) return originHeader;
+  const refererHeader = toOrigin(request.headers.get("referer"));
+  if (refererHeader && isLocalBrowserOrigin(refererHeader))
+    return refererHeader;
+  const hostHeader = request.headers.get("host");
+  if (hostHeader) {
+    const candidate = `http://${hostHeader}`;
+    if (isLocalBrowserOrigin(candidate)) return toOrigin(candidate);
+  }
+  return void 0;
+}
+function findKontextConnection(agent) {
+  for (const [id, connection] of Object.entries(agent.mcp.mcpConnections)) {
+    if (!connection || typeof connection !== "object") continue;
+    const c = connection;
+    const state = c.connectionState ?? c.state;
+    if (state === "ready" || state === 3) return "ready";
+    return id;
+  }
+  if (agent.mcp.listServers) {
+    const servers = agent.mcp.listServers();
+    for (const server of servers) {
+      if (server.name === "kontext") return server.id;
+    }
+  }
+  return void 0;
+}
+function withKontext(Base) {
+  return class KontextAgent extends Base {
+    /** @internal */
+    _kontextCallbackHost;
+    /** @internal */
+    _kontextSystemPrompt = "";
+    /** @internal */
+    _kontextIntegrations = [];
+    // -- Lazy helpers --
+    /** @internal */
+    _kontextConfig() {
+      const clientId = this.env.KONTEXT_CLIENT_ID;
+      if (!clientId) {
+        throw new ConfigError(
+          "KONTEXT_CLIENT_ID environment variable is required. Set it in your Cloudflare Worker environment.",
+          "kontext_config_missing_client_id"
+        );
+      }
+      const serverUrl = (this.env.KONTEXT_SERVER_URL ?? DEFAULT_KONTEXT_SERVER).replace(/\/$/, "");
+      return {
+        clientId,
+        storage: this.ctx.storage,
+        agentName: this.name,
+        serverUrl
+      };
+    }
+    // -- Lifecycle hooks (auto-wired) --
+    createMcpOAuthProvider(callbackUrl) {
+      const cfg = this._kontextConfig();
+      return new KontextCloudflareOAuthProvider({
+        kontextClientId: cfg.clientId,
+        storage: cfg.storage,
+        agentName: cfg.agentName,
+        callbackUrl
+      });
+    }
+    onConnect(connection, ctx) {
+      if (super.onConnect) {
+        super.onConnect(connection, ctx);
+      }
+      const url = new URL(ctx.request.url);
+      const requestHost = `${url.protocol}//${url.host}`;
+      this._kontextCallbackHost = resolveLocalCallbackHost(ctx.request) ?? requestHost;
+      void this._kontextConfig().storage.put(
+        CALLBACK_HOST_KEY,
+        this._kontextCallbackHost
+      );
+    }
+    async onStart() {
+      if (super.onStart) {
+        await super.onStart();
+      }
+      this.mcp.configureOAuthCallback({
+        customHandler: () => new Response(
+          "<html><body><p>Authenticated! You can close this window.</p><script>window.close();</script></body></html>",
+          { headers: { "content-type": "text/html" }, status: 200 }
+        )
+      });
+    }
+    async onRequest(request) {
+      if (typeof this.mcp.onRequest === "function") {
+        const response = await this.mcp.onRequest(request);
+        if (response) return response;
+      }
+      if (super.onRequest) {
+        return super.onRequest(request);
+      }
+      return new Response("Not found", { status: 404 });
+    }
+    // -- Public API --
+    async kontextTools() {
+      const cfg = this._kontextConfig();
+      await this.mcp.ensureJsonSchema();
+      const kontextConnectionId = findKontextConnection(
+        this
+      );
+      if (kontextConnectionId !== "ready") {
+        if (kontextConnectionId) {
+          try {
+            if (this.removeMcpServer) {
+              await this.removeMcpServer(kontextConnectionId);
+            } else if (this.mcp.removeServer) {
+              await this.mcp.removeServer(kontextConnectionId);
+            }
+          } catch {
+          }
+        }
+        const host = this._kontextCallbackHost ?? await cfg.storage.get(CALLBACK_HOST_KEY);
+        if (!host) {
+          throw new ConfigError(
+            "No callbackHost available. Ensure onConnect() fires before kontextTools(). This usually means the WebSocket connection hasn't been established yet.",
+            "kontext_config_missing_callback_host"
+          );
+        }
+        await this.addMcpServer("kontext", `${cfg.serverUrl}/mcp`, {
+          callbackHost: host
+        });
+      }
+      const mcpTools = this.mcp.getAITools();
+      this._kontextIntegrations = await preflightIntegrationStatus(mcpTools);
+      const wrapped = wrapToolsWithElicitation(mcpTools);
+      const { systemPrompt, requestCapabilityTool } = enrichToolsWithAuthAwareness(
+        Object.keys(wrapped),
+        this._kontextIntegrations
+      );
+      if (requestCapabilityTool) {
+        wrapped[requestCapabilityTool.name] = requestCapabilityTool;
+      }
+      this._kontextSystemPrompt = systemPrompt;
+      return wrapped;
+    }
+    get kontextSystemPrompt() {
+      return this._kontextSystemPrompt;
+    }
+  };
+}
+var DurableObjectKontextStorage = class {
+  constructor(storage) {
+    this.storage = storage;
+  }
+  async getJson(key) {
+    return await this.storage.get(key) ?? void 0;
+  }
+  async setJson(key, value) {
+    if (value === void 0) {
+      await this.storage.delete(key);
+    } else {
+      await this.storage.put(key, value);
+    }
+  }
+};
+
+export { DurableObjectKontextStorage, KontextCloudflareOAuthProvider, withKontext };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map