@slashfi/agents-sdk 0.62.0 → 0.64.0

package/src/codegen.ts

@@ -1,1423 +0,0 @@
-/**
- * MCP Codegen
- *
- * Connects to any MCP server, introspects its tools via `tools/list`,
- * and generates readable agent-definition source files.
- *
- * Supports three transport modes:
- * - stdio: spawn a process (e.g., `npx @modelcontextprotocol/server-notion`)
- * - sse: connect to an SSE endpoint
- * - http: connect to an HTTP JSON-RPC endpoint
- *
- * @example
- * ```typescript
- * import { codegen } from '@slashfi/agents-sdk';
- *
- * await codegen({
- *   server: 'npx @modelcontextprotocol/server-notion',
- *   outDir: './generated/notion',
- *   agentPath: '@notion',
- * });
- * ```
- *
- * @example CLI
- * ```bash
- * agents-sdk codegen --server 'npx @mcp/notion' --name notion
- * agents-sdk use notion search_pages '{"query": "hello"}'
- * agents-sdk use notion --list
- * ```
- */
-
-import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import type { JsonSchema } from "./types.js";
-import { discoverOAuthMetadata, type OAuthServerMetadata } from "./mcp-client.js";
-
-// ============================================
-// Types
-// ============================================
-
-/** MCP tool definition as returned by tools/list */
-export interface McpToolDefinition {
-  name: string;
-  description?: string;
-  inputSchema?: JsonSchema;
-}
-
-/** MCP server info from initialize response */
-export interface McpServerInfo {
-  name?: string;
-  version?: string;
-  protocolVersion?: string;
-}
-
-/** Transport for communicating with an MCP server */
-export interface McpTransport {
-  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
-  /** Send a JSON-RPC notification (no id, no response expected) */
-  notify(method: string, params?: Record<string, unknown>): Promise<void>;
-  close(): Promise<void>;
-}
-
-/** Server source — string command, URL, or explicit config */
-export type ServerSource =
-  | string
-  | { command: string; args?: string[]; env?: Record<string, string> }
-  | { url: string; headers?: Record<string, string> }
-  | { spawn: string; args?: string[]; env?: Record<string, string>; port?: number; endpoint?: string };
-
-/** Options for the codegen function */
-export interface CodegenOptions {
-  /** MCP server source — command string, URL, or config object */
-  server: ServerSource;
-
-  /** Output directory for generated files */
-  outDir: string;
-
-  /** Agent path override (default: derived from server name) */
-  agentPath?: string;
-
-  /** Agent display name */
-  name?: string;
-
-  /** SDK import path (default: '@slashfi/agents-sdk') */
-  sdkImport?: string;
-
-  /** Whether to generate a CLI entrypoint (default: true) */
-  cli?: boolean;
-
-  /** Whether to generate TypeScript interfaces from schemas (default: true) */
-  types?: boolean;
-
-  /** Visibility for the generated agent (default: 'public') */
-  visibility?: "public" | "internal" | "private";
-}
-
-/** Result of codegen */
-export interface CodegenResult {
-  /** Path to the output directory */
-  outDir: string;
-
-  /** Server info from the MCP initialize handshake */
-  serverInfo: McpServerInfo;
-
-  /** Number of tools generated */
-  toolCount: number;
-
-  /** Names of generated tool files */
-  toolFiles: string[];
-
-  /** All generated file paths */
-  files: string[];
-
-  /** OAuth server metadata (if discovered via .well-known/oauth-authorization-server) */
-  oauth?: OAuthServerMetadata;
-
-  /** Connection spec for consumers */
-  connection?: ConnectionSpec;
-}
-
-// ============================================
-// Protocol Constants
-// ============================================
-
-const LATEST_PROTOCOL_VERSION = "2025-03-26";
-const SUPPORTED_PROTOCOL_VERSIONS = [
-  "2025-03-26",
-  "2024-11-05",
-  "2024-10-07",
-];
-
-// ============================================
-// Safe Environment (security)
-// ============================================
-
-/** Only inherit safe env vars when spawning MCP servers (prevents secret leakage). */
-const DEFAULT_INHERITED_ENV_VARS =
-  process.platform === "win32"
-    ? [
-        "APPDATA",
-        "HOMEDRIVE",
-        "HOMEPATH",
-        "LOCALAPPDATA",
-        "PATH",
-        "PROCESSOR_ARCHITECTURE",
-        "SYSTEMDRIVE",
-        "SYSTEMROOT",
-        "TEMP",
-        "USERNAME",
-        "USERPROFILE",
-        "PROGRAMFILES",
-      ]
-    : ["HOME", "LOGNAME", "PATH", "SHELL", "TERM", "USER"];
-
-function getDefaultEnvironment(): Record<string, string> {
-  const env: Record<string, string> = {};
-  for (const key of DEFAULT_INHERITED_ENV_VARS) {
-    const value = process.env[key];
-    if (value === undefined || value.startsWith("()")) continue;
-    env[key] = value;
-  }
-  return env;
-}
-
-// ============================================
-// Transport: stdio
-// ============================================
-
-import spawn from "cross-spawn";
-import { spawn as _nodeSpawn } from "node:child_process";
-
-function createStdioTransport(source: {
-  command: string;
-  args?: string[];
-  env?: Record<string, string>;
-}): McpTransport {
-  // Use cross-spawn for Windows compatibility (.cmd/.bat wrappers, spaces in paths)
-  // Env: if explicit env provided, use safe defaults + explicit. Otherwise inherit process.env.
-  const env = source.env
-    ? { ...getDefaultEnvironment(), ...source.env }
-    : { ...process.env } as Record<string, string>;
-  const proc = spawn(source.command, source.args ?? [], {
-    stdio: ["pipe", "pipe", "pipe"],
-    env,
-  });
-
-  let requestId = 0;
-  const pending = new Map<
-    number,
-    { resolve: (v: unknown) => void; reject: (e: Error) => void }
-  >();
-
-  // Error handlers for pipes (prevent unhandled errors)
-  proc.on("error", (err: Error) => {
-    for (const [id, p] of pending) {
-      p.reject(new Error(`Process error: ${err.message}`));
-      pending.delete(id);
-    }
-  });
-  proc.stdin?.on("error", () => { /* ignore broken pipe */ });
-  proc.stdout?.on("error", () => { /* ignore */ });
-  proc.stderr?.on("error", () => { /* ignore */ });
-
-  // Read stdout with Content-Length framing (MCP spec) or newline-delimited fallback
-  let buffer = "";
-
-  proc.stdout!.on("data", (chunk: Buffer) => {
-    buffer += chunk.toString();
-
-    // Try to parse messages from buffer
-    while (buffer.length > 0) {
-      // Check for Content-Length framing (MCP standard)
-      const clMatch = buffer.match(
-        /^Content-Length:\s*(\d+)\r?\n(?:[^\r\n]+\r?\n)*\r?\n/,
-      );
-      if (clMatch) {
-        const contentLength = parseInt(clMatch[1], 10);
-        const headerEnd = clMatch[0].length;
-        if (buffer.length >= headerEnd + contentLength) {
-          const body = buffer.slice(headerEnd, headerEnd + contentLength);
-          buffer = buffer.slice(headerEnd + contentLength);
-          try {
-            const msg = JSON.parse(body);
-            if (msg.id !== undefined && pending.has(msg.id)) {
-              const p = pending.get(msg.id)!;
-              pending.delete(msg.id);
-              if (msg.error) {
-                p.reject(
-                  new Error(
-                    `MCP error ${msg.error.code}: ${msg.error.message}`,
-                  ),
-                );
-              } else {
-                p.resolve(msg.result);
-              }
-            }
-          } catch {
-            // malformed JSON, skip
-          }
-          continue;
-        }
-        // Not enough data yet, wait for more
-        break;
-      }
-
-      // Fallback: newline-delimited JSON
-      const newlineIdx = buffer.indexOf("\n");
-      if (newlineIdx === -1) break;
-
-      const line = buffer.slice(0, newlineIdx).trim();
-      buffer = buffer.slice(newlineIdx + 1);
-      if (!line) continue;
-
-      try {
-        const msg = JSON.parse(line);
-        if (msg.id !== undefined && pending.has(msg.id)) {
-          const p = pending.get(msg.id)!;
-          pending.delete(msg.id);
-          if (msg.error) {
-            p.reject(
-              new Error(
-                `MCP error ${msg.error.code}: ${msg.error.message}`,
-              ),
-            );
-          } else {
-            p.resolve(msg.result);
-          }
-        }
-      } catch {
-        // ignore non-JSON lines (e.g., server logs)
-      }
-    }
-  });
-
-  return {
-    async send(method: string, params?: Record<string, unknown>) {
-      const id = ++requestId;
-      const message = JSON.stringify({
-        jsonrpc: "2.0",
-        id,
-        method,
-        params: params ?? {},
-      });
-
-      // Send as newline-delimited JSON (compatible with all MCP SDK versions)
-      proc.stdin!.write(message + "\n");
-
-      return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-          pending.delete(id);
-          reject(new Error(`MCP request timed out: ${method}`));
-        }, 30_000);
-
-        pending.set(id, {
-          resolve: (v) => {
-            clearTimeout(timeout);
-            resolve(v);
-          },
-          reject: (e) => {
-            clearTimeout(timeout);
-            reject(e);
-          },
-        });
-      });
-    },
-    async notify(method: string, params?: Record<string, unknown>) {
-      // Notification = no id field, no response expected
-      const message = JSON.stringify({
-        jsonrpc: "2.0",
-        method,
-        ...(params ? { params } : {}),
-      });
-      proc.stdin!.write(message + "\n");
-    },
-    async close() {
-      // Graceful shutdown: stdin.end → wait → SIGTERM → wait → SIGKILL
-      const closePromise = new Promise<void>((resolve) => {
-        proc.once("close", () => resolve());
-      });
-
-      try { proc.stdin?.end(); } catch { /* ignore */ }
-      await Promise.race([closePromise, new Promise((r) => setTimeout(r, 2000))]);
-
-      if (proc.exitCode === null) {
-        try { proc.kill("SIGTERM"); } catch { /* ignore */ }
-        await Promise.race([closePromise, new Promise((r) => setTimeout(r, 2000))]);
-      }
-
-      if (proc.exitCode === null) {
-        try { proc.kill("SIGKILL"); } catch { /* ignore */ }
-      }
-    },
-  };
-}
-
-// ============================================
-// Transport: HTTP JSON-RPC (Streamable HTTP)
-// ============================================
-
-function createHttpTransport(source: {
-  url: string;
-  headers?: Record<string, string>;
-}): McpTransport {
-  let requestId = 0;
-  let sessionId: string | null = null;
-
-  return {
-    async send(method: string, params?: Record<string, unknown>) {
-      const id = ++requestId;
-      const res = await fetch(source.url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Accept": "application/json, text/event-stream",
-          ...source.headers,
-          ...(sessionId ? { "mcp-session-id": sessionId } : {}),
-        },
-        body: JSON.stringify({
-          jsonrpc: "2.0",
-          id,
-          method,
-          params: params ?? {},
-        }),
-      });
-
-      if (!res.ok) {
-        throw new Error(`HTTP ${res.status}: ${await res.text()}`);
-      }
-
-      // Capture session ID if returned
-      const newSessionId = res.headers.get("mcp-session-id");
-      if (newSessionId) sessionId = newSessionId;
-
-      const contentType = res.headers.get("content-type") ?? "";
-
-      // Handle SSE-wrapped responses (Streamable HTTP)
-      if (contentType.includes("text/event-stream")) {
-        const text = await res.text();
-        // Parse SSE: look for "data: {...}" lines
-        for (const line of text.split("\n")) {
-          if (line.startsWith("data: ")) {
-            try {
-              const msg = JSON.parse(line.slice(6));
-              if (msg.error) {
-                throw new Error(
-                  `MCP error ${msg.error.code}: ${msg.error.message}`,
-                );
-              }
-              return msg.result;
-            } catch (e) {
-              if (e instanceof SyntaxError) continue;
-              throw e;
-            }
-          }
-        }
-        throw new Error("No JSON-RPC response found in SSE stream");
-      }
-
-      // Standard JSON response
-      const msg = (await res.json()) as {
-        result?: unknown;
-        error?: { code: number; message: string };
-      };
-      if (msg.error) {
-        throw new Error(
-          `MCP error ${msg.error.code}: ${msg.error.message}`,
-        );
-      }
-      return msg.result;
-    },
-    async notify(method: string, params?: Record<string, unknown>) {
-      // Send notification (no id, accept 202 Accepted)
-      const res = await fetch(source.url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Accept": "application/json, text/event-stream",
-          ...source.headers,
-          ...(sessionId ? { "mcp-session-id": sessionId } : {}),
-        },
-        body: JSON.stringify({
-          jsonrpc: "2.0",
-          method,
-          ...(params ? { params } : {}),
-        }),
-      });
-      // 202 Accepted is expected for notifications
-      if (!res.ok && res.status !== 202) {
-        await res.text().catch(() => {});
-      }
-    },
-    async close() {
-      // nothing to close for HTTP
-    },
-  };
-}
-
-// ============================================
-// Transport: SSE (legacy MCP SSE protocol)
-// ============================================
-
-function createSseTransport(source: {
-  url: string;
-  headers?: Record<string, string>;
-}): McpTransport {
-  let postEndpoint: string | null = null;
-  let requestId = 0;
-  const pending = new Map<
-    number,
-    { resolve: (v: unknown) => void; reject: (e: Error) => void }
-  >();
-  let sseController: ReadableStreamDefaultReader | null = null;
-
-  // Connect to SSE and discover the POST endpoint
-  const connectPromise = (async () => {
-    const res = await fetch(source.url, {
-      headers: {
-        Accept: "text/event-stream",
-        ...source.headers,
-      },
-    });
-
-    if (!res.ok) {
-      throw new Error(`SSE connect failed: ${res.status} ${await res.text()}`);
-    }
-
-    const reader = res.body!.getReader() as ReadableStreamDefaultReader<Uint8Array>;
-    sseController = reader;
-    const decoder = new TextDecoder();
-    let buffer = "";
-
-    // Read SSE events in background
-    (async () => {
-      try {
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          buffer += decoder.decode(value, { stream: true });
-
-          // Process complete SSE events
-          while (buffer.includes("\n\n")) {
-            const eventEnd = buffer.indexOf("\n\n");
-            const eventText = buffer.slice(0, eventEnd);
-            buffer = buffer.slice(eventEnd + 2);
-
-            let eventType = "message";
-            let eventData = "";
-
-            for (const line of eventText.split("\n")) {
-              if (line.startsWith("event: ")) {
-                eventType = line.slice(7).trim();
-              } else if (line.startsWith("data: ")) {
-                eventData += line.slice(6);
-              }
-            }
-
-            if (eventType === "endpoint" && eventData) {
-              // Resolve relative URLs
-              const base = new URL(source.url);
-              postEndpoint = eventData.startsWith("http")
-                ? eventData
-                : `${base.origin}${eventData}`;
-            } else if (eventType === "message" && eventData) {
-              try {
-                const msg = JSON.parse(eventData);
-                if (msg.id !== undefined && pending.has(msg.id)) {
-                  const p = pending.get(msg.id)!;
-                  pending.delete(msg.id);
-                  if (msg.error) {
-                    p.reject(
-                      new Error(
-                        `MCP error ${msg.error.code}: ${msg.error.message}`,
-                      ),
-                    );
-                  } else {
-                    p.resolve(msg.result);
-                  }
-                }
-              } catch {
-                // ignore malformed JSON
-              }
-            }
-          }
-        }
-      } catch {
-        // stream closed
-      }
-    })();
-
-    // Wait for endpoint to be discovered
-    const deadline = Date.now() + 10_000;
-    while (!postEndpoint && Date.now() < deadline) {
-      await new Promise((r) => setTimeout(r, 100));
-    }
-    if (!postEndpoint) {
-      throw new Error("SSE endpoint not discovered within timeout");
-    }
-  })();
-
-  return {
-    async send(method: string, params?: Record<string, unknown>) {
-      await connectPromise;
-
-      const id = ++requestId;
-      const res = await fetch(postEndpoint!, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          ...source.headers,
-        },
-        body: JSON.stringify({
-          jsonrpc: "2.0",
-          id,
-          method,
-          params: params ?? {},
-        }),
-      });
-
-      if (!res.ok) {
-        const body = await res.text();
-        throw new Error(`HTTP ${res.status}: ${body}`);
-      }
-
-      // Response may come via SSE stream or directly
-      const contentType = res.headers.get("content-type") ?? "";
-      if (contentType.includes("application/json")) {
-        const msg = (await res.json()) as {
-          result?: unknown;
-          error?: { code: number; message: string };
-        };
-        if (msg.error) {
-          throw new Error(
-            `MCP error ${msg.error.code}: ${msg.error.message}`,
-          );
-        }
-        return msg.result;
-      }
-
-      // Otherwise wait for response via SSE stream
-      return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-          pending.delete(id);
-          reject(new Error(`MCP SSE request timed out: ${method}`));
-        }, 30_000);
-
-        pending.set(id, {
-          resolve: (v) => {
-            clearTimeout(timeout);
-            resolve(v);
-          },
-          reject: (e) => {
-            clearTimeout(timeout);
-            reject(e);
-          },
-        });
-      });
-    },
-    async close() {
-      if (sseController) {
-        await sseController.cancel().catch(() => {});
-      }
-    },
-    async notify(method: string, params?: Record<string, unknown>) {
-      await connectPromise;
-      await fetch(postEndpoint!, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          ...source.headers,
-        },
-        body: JSON.stringify({
-          jsonrpc: "2.0",
-          method,
-          ...(params ? { params } : {}),
-        }),
-      }).catch(() => {});
-    },
-  };
-}
-
-// ============================================
-// Source Parsing
-// ============================================
-
-/**
- * Extract the base URL from a server source (for OAuth discovery).
- * Returns null for stdio/command-based sources.
- */
-function resolveServerUrl(source: ServerSource): string | null {
-  if (typeof source === "string") {
-    if (source.startsWith("http://") || source.startsWith("https://")) {
-      return source.replace(/\/sse$/, "");
-    }
-    return null;
-  }
-  if ("url" in source) {
-    return source.url.replace(/\/sse$/, "");
-  }
-  return null;
-}
-
-function parseServerSource(source: ServerSource): McpTransport {
-  if (typeof source === "string") {
-    // URL -> HTTP or SSE transport
-    if (source.startsWith("http://") || source.startsWith("https://")) {
-      // URLs ending in /sse use SSE transport
-      if (source.endsWith("/sse")) {
-        return createSseTransport({ url: source });
-      }
-      return createHttpTransport({ url: source });
-    }
-    // Command string -> stdio transport
-    const parts = source.split(/\s+/);
-    return createStdioTransport({
-      command: parts[0],
-      args: parts.slice(1),
-    });
-  }
-
-  if ("url" in source) {
-    // URLs ending in /sse use SSE transport
-    if (source.url.endsWith("/sse")) {
-      return createSseTransport(source);
-    }
-    return createHttpTransport(source);
-  }
-
-  if ("spawn" in source) {
-    return createSpawnHttpTransport(source);
-  }
-
-  return createStdioTransport(source);
-}
-
-// ============================================
-// Transport: Spawn + HTTP (for servers needing a port)
-// ============================================
-
-function createSpawnHttpTransport(source: {
-  spawn: string;
-  args?: string[];
-  env?: Record<string, string>;
-  port?: number;
-  endpoint?: string;
-}): McpTransport {
-  const port = source.port ?? Math.floor(40000 + Math.random() * 10000);
-  const endpoint = source.endpoint ?? "/mcp";
-  const args = [...(source.args ?? []), "--port", String(port)];
-
-  const spawnEnv = source.env
-    ? { ...getDefaultEnvironment(), ...source.env }
-    : { ...process.env } as Record<string, string>;
-  const proc = Bun.spawn([source.spawn, ...args], {
-    stdin: "pipe",
-    stdout: "pipe",
-    stderr: "pipe",
-    env: spawnEnv,
-  });
-
-  // Create inner HTTP transport
-  const inner = createHttpTransport({ url: `http://127.0.0.1:${port}${endpoint}` });
-
-  // Wait for server to be ready
-  const readyPromise = (async () => {
-    const deadline = Date.now() + 15_000;
-    while (Date.now() < deadline) {
-      try {
-        await fetch(`http://127.0.0.1:${port}${endpoint}`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: "{}",
-          signal: AbortSignal.timeout(1000),
-        });
-        // Any response (even 400) means server is up
-        return;
-      } catch {
-        await new Promise((r) => setTimeout(r, 500));
-      }
-    }
-    throw new Error(`Server failed to start on port ${port} within 15s`);
-  })();
-
-  return {
-    async send(method: string, params?: Record<string, unknown>) {
-      await readyPromise;
-      return inner.send(method, params);
-    },
-    async notify(method: string, params?: Record<string, unknown>) {
-      await readyPromise;
-      return inner.notify(method, params);
-    },
-    async close() {
-      await inner.close();
-      proc.kill();
-    },
-  };
-}
-
-// ============================================
-// Code Generation Helpers
-// ============================================
-
-/** Convert tool name to a valid TypeScript identifier (camelCase) */
-export function toIdentifier(name: string): string {
-  return name
-    .replace(/[^a-zA-Z0-9_]/g, "_")
-    .split("_")
-    .filter(Boolean)
-    .map((part, i) =>
-      i === 0
-        ? part.toLowerCase()
-        : part.charAt(0).toUpperCase() + part.slice(1).toLowerCase(),
-    )
-    .join("");
-}
-
-/** Convert tool name to PascalCase for type names */
-export function toPascalCase(name: string): string {
-  return name
-    .replace(/[^a-zA-Z0-9_]/g, "_")
-    .split("_")
-    .filter(Boolean)
-    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
-    .join("");
-}
-
-/** Convert tool name to kebab-case for file names */
-function toKebabCase(name: string): string {
-  return name
-    .replace(/[^a-zA-Z0-9]/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-|-$/g, "")
-    .toLowerCase();
-}
-
-/** Serialize a JSON schema to a readable TypeScript literal string */
-export function schemaToString(schema: JsonSchema, indent = 4): string {
-  const pad = " ".repeat(indent);
-  const lines: string[] = [];
-
-  lines.push("{");
-  lines.push(`${pad}type: '${schema.type}' as const,`);
-
-  if (schema.description) {
-    lines.push(
-      `${pad}description: ${JSON.stringify(schema.description)},`,
-    );
-  }
-
-  if (schema.enum) {
-    lines.push(`${pad}enum: ${JSON.stringify(schema.enum)},`);
-  }
-
-  if (schema.properties) {
-    lines.push(`${pad}properties: {`);
-    for (const [key, prop] of Object.entries(schema.properties)) {
-      const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
-      lines.push(
-        `${pad}  ${safeKey}: ${schemaToString(prop as JsonSchema, indent + 4)},`,
-      );
-    }
-    lines.push(`${pad}},`);
-  }
-
-  if (schema.items) {
-    lines.push(
-      `${pad}items: ${schemaToString(schema.items as JsonSchema, indent + 2)},`,
-    );
-  }
-
-  if (schema.required && schema.required.length > 0) {
-    lines.push(
-      `${pad}required: [${schema.required.map((r) => `'${r}'`).join(", ")}] as const,`,
-    );
-  }
-
-  if (schema.additionalProperties !== undefined) {
-    if (typeof schema.additionalProperties === "boolean") {
-      lines.push(
-        `${pad}additionalProperties: ${schema.additionalProperties},`,
-      );
-    } else {
-      lines.push(
-        `${pad}additionalProperties: ${schemaToString(schema.additionalProperties as JsonSchema, indent + 2)},`,
-      );
-    }
-  }
-
-  if (schema.default !== undefined) {
-    lines.push(`${pad}default: ${JSON.stringify(schema.default)},`);
-  }
-
-  lines.push(`${" ".repeat(indent - 2)}}`);
-  return lines.join("\n");
-}
-
-/** Generate a TypeScript interface from a JSON Schema */
-export function schemaToInterface(
-  name: string,
-  schema: JsonSchema,
-): string {
-  if (schema.type !== "object" || !schema.properties) {
-    return `export type ${name} = unknown;`;
-  }
-
-  const required = new Set(schema.required ?? []);
-  const lines: string[] = [`export interface ${name} {`];
-
-  for (const [key, prop] of Object.entries(schema.properties)) {
-    const p = prop as JsonSchema;
-    const optional = required.has(key) ? "" : "?";
-    const tsType = jsonSchemaToTsType(p);
-    if (p.description) {
-      lines.push(`  /** ${p.description} */`);
-    }
-    lines.push(
-      `  ${/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key)}${optional}: ${tsType};`,
-    );
-  }
-
-  lines.push("}");
-  return lines.join("\n");
-}
-
-/** Convert a JSON Schema type to a TypeScript type string */
-function jsonSchemaToTsType(schema: JsonSchema): string {
-  // const literal
-  if (schema.const !== undefined) {
-    return JSON.stringify(schema.const);
-  }
-
-  // enum
-  if (schema.enum) {
-    return schema.enum.map((v) => JSON.stringify(v)).join(" | ");
-  }
-
-  // oneOf / anyOf → union
-  if (schema.oneOf) {
-    return (schema.oneOf as JsonSchema[]).map(jsonSchemaToTsType).join(" | ");
-  }
-  if (schema.anyOf) {
-    return (schema.anyOf as JsonSchema[]).map(jsonSchemaToTsType).join(" | ");
-  }
-
-  // allOf → intersection
-  if (schema.allOf) {
-    return (schema.allOf as JsonSchema[]).map(jsonSchemaToTsType).join(" & ");
-  }
-
-  // not → exclude
-  if (schema.not) {
-    return `Exclude<unknown, ${jsonSchemaToTsType(schema.not as JsonSchema)}>`;
-  }
-
-  // $ref
-  if (schema.$ref) {
-    const ref = schema.$ref as string;
-    // Extract name from #/$defs/Foo or #/definitions/Foo
-    const match = ref.match(/\/([^/]+)$/);
-    return match ? match[1] : "unknown";
-  }
-
-  switch (schema.type) {
-    case "string":
-      // Include format hint if present
-      if (schema.format) return `string /* ${schema.format} */`;
-      return "string";
-    case "integer":
-      return "number /* integer */";
-    case "number":
-      return "number";
-    case "boolean":
-      return "boolean";
-    case "null":
-      return "null";
-    case "array":
-      if (schema.items) {
-        return `${jsonSchemaToTsType(schema.items as JsonSchema)}[]`;
-      }
-      // Tuple arrays (prefixItems)
-      if (schema.prefixItems) {
-        const items = (schema.prefixItems as JsonSchema[]).map(jsonSchemaToTsType);
-        return `[${items.join(", ")}]`;
-      }
-      return "unknown[]";
-    case "object":
-      if (schema.properties) {
-        const required = new Set((schema.required as string[]) ?? []);
-        const props = Object.entries(schema.properties)
-          .map(([k, v]) => {
-            const opt = required.has(k) ? "" : "?";
-            return `${k}${opt}: ${jsonSchemaToTsType(v as JsonSchema)}`;
-          })
-          .join("; ");
-        // additionalProperties
-        if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
-          const addlType = jsonSchemaToTsType(schema.additionalProperties as JsonSchema);
-          return props
-            ? `{ ${props}; [key: string]: ${addlType} }`
-            : `Record<string, ${addlType}>`;
-        }
-        return `{ ${props} }`;
-      }
-      if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
-        return `Record<string, ${jsonSchemaToTsType(schema.additionalProperties as JsonSchema)}>`;
-      }
-      return "Record<string, unknown>";
-    default:
-      // type as array (e.g., ["string", "null"])
-      if (Array.isArray(schema.type)) {
-        return schema.type.map((t: string) => (t === "null" ? "null" : t === "integer" ? "number" : t)).join(" | ");
-      }
-      return "unknown";
-  }
-}
-
-// ============================================
-// File Generators
-// ============================================
-
-function generateToolFile(
-  tool: McpToolDefinition,
-  _sdkImport: string,
-  _generateTypes: boolean,
-): string {
-  const schema = tool.inputSchema ?? {
-    type: "object" as const,
-    properties: {},
-  };
-
-  const lines: string[] = [];
-
-  // Title
-  lines.push(`# ${tool.name}`);
-  lines.push("");
-  if (tool.description) {
-    lines.push(tool.description);
-    lines.push("");
-  }
-
-  // Parameters table
-  const props = (schema.properties ?? {}) as Record<string, JsonSchema>;
-  const required = new Set((schema.required as string[]) ?? []);
-  const paramNames = Object.keys(props);
-
-  if (paramNames.length > 0) {
-    lines.push("## Parameters");
-    lines.push("");
-    lines.push("| Name | Type | Required | Description |");
-    lines.push("|------|------|----------|-------------|");
-    for (const name of paramNames) {
-      const prop = props[name];
-      const type = jsonSchemaToTsType(prop);
-      const req = required.has(name) ? "\u2713" : "";
-      const desc = (prop.description ?? "").replace(/\|/g, "\\|");
-      lines.push(`| ${name} | \`${type}\` | ${req} | ${desc} |`);
-    }
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}
-
-function generateAgentConfig(
-  serverInfo: McpServerInfo,
-  _tools: McpToolDefinition[],
-  agentPath: string,
-  sdkImport: string,
-  visibility: string,
-): string {
-  const lines: string[] = [];
-
-  lines.push(`/**`);
-  lines.push(` * Agent: ${agentPath}`);
-  if (serverInfo.name) {
-    lines.push(` * MCP Server: ${serverInfo.name} v${serverInfo.version ?? "unknown"}`);
-  }
-  lines.push(` *`);
-  lines.push(` * Auto-generated by agents-sdk codegen.`);
-  lines.push(` */`);
-  lines.push("");
-  lines.push(`import { defineAgent } from '${sdkImport}';`);
-  lines.push("");
-  lines.push(`export default defineAgent({`);
-  lines.push(`  path: '${agentPath}',`);
-  lines.push(`  entrypoint: './entrypoint.md',`);
-  lines.push(`  visibility: '${visibility}' as const,`);
-  lines.push(`});`);
-  lines.push("");
-
-  return lines.join("\n");
-}
-
-function generateEntrypoint(
-  serverInfo: McpServerInfo,
-  tools: McpToolDefinition[],
-  agentPath: string,
-): string {
-  const lines: string[] = [];
-
-  const name = serverInfo.name ?? agentPath;
-  lines.push(`# ${name}`);
-  lines.push("");
-  if (serverInfo.version) {
-    lines.push(`> MCP Server v${serverInfo.version}`);
-    lines.push("");
-  }
-  lines.push(`You are an agent wrapping the ${name} MCP server.`);
-  lines.push("");
-  lines.push(`## Available Tools`);
-  lines.push("");
-  for (const tool of tools) {
-    lines.push(`- **${tool.name}**: ${tool.description ?? "No description"}`);
-  }
-  lines.push("");
-
-  return lines.join("\n");
-}
-
-function generateIndex(
-  _tools: McpToolDefinition[],
-): string {
-  const lines: string[] = [];
-
-  lines.push(`/**`);
-  lines.push(` * Auto-generated index.`);
-  lines.push(` */`);
-  lines.push("");
-  lines.push(`export { default as agent } from './agent.config.js';`);
-  lines.push("");
-
-  return lines.join("\n");
-}
-
-function generateCli(
-  serverInfo: McpServerInfo,
-  tools: McpToolDefinition[],
-  agentPath: string,
-): string {
-  const name = serverInfo.name ?? agentPath;
-  const lines: string[] = [];
-
-  lines.push(`#!/usr/bin/env bun`);
-  lines.push(`/**`);
-  lines.push(` * CLI for ${name}`);
-  lines.push(` *`);
-  lines.push(` * Usage:`);
-  lines.push(` *   bun cli.ts <tool_name> [json_params]`);
-  lines.push(` *   bun cli.ts --list`);
-  lines.push(` *`);
-  lines.push(` * Auto-generated by agents-sdk codegen.`);
-  lines.push(` */`);
-  lines.push("");
-  lines.push(`const tools = ${JSON.stringify(tools.map(t => ({ name: t.name, description: t.description ?? '' })), null, 2)};`);
-  lines.push("");
-  lines.push(`const args = process.argv.slice(2);`);
-  lines.push("");
-  lines.push(`if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {`);
-  lines.push(`  console.log('${name} CLI\\n');`);
-  lines.push(`  console.log('Usage: bun cli.ts <tool> [params_json]\\n');`);
-  lines.push(`  console.log('Available tools:');`);
-  lines.push(`  for (const t of tools) {`);
-  lines.push(`    console.log(\`  \${t.name.padEnd(30)} \${t.description}\`);`);
-  lines.push(`  }`);
-  lines.push(`  process.exit(0);`);
-  lines.push(`}`);
-  lines.push("");
-  lines.push(`if (args[0] === '--list') {`);
-  lines.push(`  for (const t of tools) {`);
-  lines.push(`    console.log(\`\${t.name}\\t\${t.description}\`);`);
-  lines.push(`  }`);
-  lines.push(`  process.exit(0);`);
-  lines.push(`}`);
-  lines.push("");
-  lines.push(`const toolName = args[0];`);
-  lines.push(`const params = args[1] ? JSON.parse(args[1]) : {};`);
-  lines.push("");
-  lines.push(`if (!tools.find(t => t.name === toolName)) {`);
-  lines.push(`  console.error(\`Unknown tool: \${toolName}\`);`);
-  lines.push(`  console.error(\`Available: \${tools.map(t => t.name).join(', ')}\`);`);
-  lines.push(`  process.exit(1);`);
-  lines.push(`}`);
-  lines.push("");
-  lines.push(`// TODO: Connect to MCP server and execute the tool`);
-  lines.push(`console.log(JSON.stringify({ tool: toolName, params, status: 'not_connected' }, null, 2));`);
-  lines.push("");
-
-  return lines.join("\n");
-}
-
-// ============================================
-// Manifest
-// ============================================
-
-/** Manifest stored in outDir for `agents-sdk use` */
-/** How a consumer connects to this MCP server */
-export interface ConnectionSpec {
-  /** MCP server URL (for HTTP/SSE transports) */
-  url?: string;
-  /** Transport type */
-  transport: 'http' | 'sse' | 'stdio';
-  /** Auth requirements */
-  auth: {
-    /** Auth type: oauth, api_key, or none */
-    type: 'oauth' | 'api_key' | 'none';
-    /** OAuth discovery URL (.well-known/oauth-authorization-server) */
-    discovery?: string;
-    /** Whether dynamic client registration (RFC 7591) is supported */
-    dynamic_registration?: boolean;
-  };
-}
-
-export interface CodegenManifest {
-  agentPath: string;
-  serverSource: ServerSource;
-  serverInfo: McpServerInfo;
-  tools: { name: string; description?: string; inputSchema?: Record<string, unknown> }[];
-  /** How to connect to and authenticate with this MCP server */
-  connection?: ConnectionSpec;
-  /** Raw OAuth server metadata (from .well-known discovery) */
-  oauth?: OAuthServerMetadata;
-  generatedAt: string;
-}
-
-function generateManifest(
-  serverSource: ServerSource,
-  serverInfo: McpServerInfo,
-  tools: McpToolDefinition[],
-  agentPath: string,
-  oauth?: OAuthServerMetadata | null,
-): string {
-  // Build connection spec from server source + OAuth discovery
-  const serverUrl = resolveServerUrl(serverSource);
-  const connection: ConnectionSpec | undefined = serverUrl
-    ? {
-        url: serverUrl,
-        transport: (typeof serverSource === 'string' && serverSource.endsWith('/sse')) ||
-                   (typeof serverSource === 'object' && 'url' in serverSource && serverSource.url.endsWith('/sse'))
-          ? 'sse' as const
-          : 'http' as const,
-        auth: oauth
-          ? {
-              type: 'oauth' as const,
-              discovery: `${serverUrl.replace(/\/mcp$/, '')}/.well-known/oauth-authorization-server`,
-              dynamic_registration: !!oauth.registration_endpoint,
-            }
-          : { type: 'none' as const },
-      }
-    : undefined;
-
-  const manifest: CodegenManifest = {
-    agentPath,
-    serverSource,
-    serverInfo,
-    tools: tools.map((t) => ({ name: t.name, description: t.description, ...(t.inputSchema ? { inputSchema: t.inputSchema } : {}) })),
-    ...(connection ? { connection } : {}),
-    ...(oauth ? { oauth } : {}),
-    generatedAt: new Date().toISOString(),
-  };
-  return JSON.stringify(manifest, null, 2) + "\n";
-}
-
-// ============================================
-// Main: codegen()
-// ============================================
-
-/**
- * Connect to an MCP server, introspect its tools, and generate
- * agent-definition source files.
- */
-export async function codegen(options: CodegenOptions): Promise<CodegenResult> {
-  const sdkImport = options.sdkImport ?? "@slashfi/agents-sdk";
-  const generateTypes = options.types !== false;
-  const generateCliFile = options.cli !== false;
-  const visibility = options.visibility ?? "public";
-  const outDir = resolve(options.outDir);
-
-  // 1. Connect to MCP server
-  const transport = parseServerSource(options.server);
-
-  let serverInfo: McpServerInfo = {};
-  let tools: McpToolDefinition[] = [];
-
-  try {
-    // 2. Initialize handshake
-    const initResult = (await transport.send("initialize", {
-      protocolVersion: LATEST_PROTOCOL_VERSION,
-      capabilities: {},
-      clientInfo: { name: "agents-sdk-codegen", version: "1.0.0" },
-    })) as {
-      serverInfo?: McpServerInfo;
-      protocolVersion?: string;
-      capabilities?: { tools?: unknown };
-    };
-
-    // Validate protocol version
-    if (
-      initResult?.protocolVersion &&
-      !SUPPORTED_PROTOCOL_VERSIONS.includes(initResult.protocolVersion)
-    ) {
-      throw new Error(
-        `Server protocol version ${initResult.protocolVersion} is not supported. Supported: ${SUPPORTED_PROTOCOL_VERSIONS.join(", ")}`,
-      );
-    }
-
-    serverInfo = initResult?.serverInfo ?? {};
-
-    // Send initialized notification (no id — this is a notification, not a request)
-    await transport.notify("notifications/initialized");
-
-    // 3. List tools (with pagination)
-    const allTools: McpToolDefinition[] = [];
-    let cursor: string | undefined;
-    do {
-      const toolsResult = (await transport.send("tools/list", {
-        ...(cursor ? { cursor } : {}),
-      })) as {
-        tools?: McpToolDefinition[];
-        nextCursor?: string;
-      };
-      allTools.push(...(toolsResult?.tools ?? []));
-      cursor = toolsResult?.nextCursor;
-    } while (cursor);
-    tools = allTools;
-  } finally {
-    await transport.close();
-  }
-
-  if (tools.length === 0) {
-    throw new Error(
-      "MCP server returned no tools. Is the server running and configured correctly?",
-    );
-  }
-
-  // 3.5. Discover OAuth metadata (for URL-based servers)
-  let oauth: OAuthServerMetadata | null = null;
-  const serverUrl = resolveServerUrl(options.server);
-  if (serverUrl) {
-    oauth = await discoverOAuthMetadata(serverUrl);
-  }
-
-  // 4. Derive agent path
-  const agentPath =
-    options.agentPath ??
-    `@${(options.name ?? serverInfo.name ?? "mcp-agent").toLowerCase().replace(/[^a-z0-9-]/g, "-")}`;
-
-  // 5. Create output directory
-  mkdirSync(outDir, { recursive: true });
-
-  const files: string[] = [];
-
-  // 6. Generate tool files
-  const toolFiles: string[] = [];
-  for (const tool of tools) {
-    const fileName = `${toKebabCase(tool.name)}.tool.md`;
-    const content = generateToolFile(tool, sdkImport, generateTypes);
-    writeFileSync(join(outDir, fileName), content);
-    toolFiles.push(fileName);
-    files.push(fileName);
-  }
-
-  // 7. Generate entrypoint.md
-  const entrypoint = generateEntrypoint(serverInfo, tools, agentPath);
-  writeFileSync(join(outDir, "entrypoint.md"), entrypoint);
-  files.push("entrypoint.md");
-
-  // 8. Generate agent.config.ts
-  const agentConfig = generateAgentConfig(
-    serverInfo,
-    tools,
-    agentPath,
-    sdkImport,
-    visibility,
-  );
-  writeFileSync(join(outDir, "agent.config.ts"), agentConfig);
-  files.push("agent.config.ts");
-
-  // 9. Generate index.ts
-  const index = generateIndex(tools);
-  writeFileSync(join(outDir, "index.ts"), index);
-  files.push("index.ts");
-
-  // 10. Generate CLI
-  if (generateCliFile) {
-    const cli = generateCli(serverInfo, tools, agentPath);
-    writeFileSync(join(outDir, "cli.ts"), cli);
-    files.push("cli.ts");
-  }
-
-  // 11. Generate manifest (for `agents-sdk use`)
-  const manifest = generateManifest(options.server, serverInfo, tools, agentPath, oauth);
-  writeFileSync(join(outDir, ".codegen-manifest.json"), manifest);
-  files.push(".codegen-manifest.json");
-
-  return {
-    outDir,
-    serverInfo,
-    toolCount: tools.length,
-    toolFiles,
-    files,
-    ...(oauth ? { oauth } : {}),
-  };
-}
-
-// ============================================
-// Use: execute a tool on a codegenned agent
-// ============================================
-
-/**
- * Execute a tool on a previously codegenned agent by reconnecting
- * to the MCP server and calling the tool.
- */
-export async function useAgent(options: {
-  /** Path to the generated agent directory (contains .codegen-manifest.json) */
-  agentDir: string;
-  /** Tool name to execute */
-  tool: string;
-  /** Tool parameters */
-  params?: Record<string, unknown>;
-}): Promise<unknown> {
-  const manifestPath = join(
-    resolve(options.agentDir),
-    ".codegen-manifest.json",
-  );
-
-  if (!existsSync(manifestPath)) {
-    throw new Error(
-      `No codegen manifest found at ${manifestPath}. Run codegen first.`,
-    );
-  }
-
-  const manifest: CodegenManifest = JSON.parse(
-    readFileSync(manifestPath, "utf-8"),
-  );
-
-  // Verify tool exists
-  const toolDef = manifest.tools.find((t) => t.name === options.tool);
-  if (!toolDef) {
-    const available = manifest.tools.map((t) => t.name).join(", ");
-    throw new Error(
-      `Unknown tool '${options.tool}'. Available: ${available}`,
-    );
-  }
-
-  // Connect to server and call tool
-  const transport = parseServerSource(manifest.serverSource);
-
-  try {
-    await transport.send("initialize", {
-      protocolVersion: LATEST_PROTOCOL_VERSION,
-      capabilities: {},
-      clientInfo: { name: "agents-sdk-use", version: "1.0.0" },
-    });
-
-    await transport.notify("notifications/initialized");
-
-    const result = await transport.send("tools/call", {
-      name: options.tool,
-      arguments: options.params ?? {},
-    });
-
-    return result;
-  } finally {
-    await transport.close();
-  }
-}
-
-/**
- * List tools available on a codegenned agent.
- */
-export function listAgentTools(agentDir: string): CodegenManifest["tools"] {
-  const manifestPath = join(resolve(agentDir), ".codegen-manifest.json");
-
-  if (!existsSync(manifestPath)) {
-    throw new Error(
-      `No codegen manifest found at ${manifestPath}. Run codegen first.`,
-    );
-  }
-
-  const manifest: CodegenManifest = JSON.parse(
-    readFileSync(manifestPath, "utf-8"),
-  );
-  return manifest.tools;
-}