@slashfi/agents-sdk 0.21.0 → 0.23.0

package/src/introspect.ts

@@ -0,0 +1,171 @@
+/**
+ * MCP Introspection
+ *
+ * Connects to an MCP server, introspects its tools,
+ * and outputs a SerializedAgentDefinition (agent.json).
+ *
+ * Deduplicates shared $defs across tools.
+ */
+
+import { spawn } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+export interface IntrospectOptions {
+  server: string;
+  name: string;
+  out?: string;
+  env?: Record<string, string>;
+}
+
+function deduplicateDefs(tools: Record<string, unknown>[]): {
+  tools: Record<string, unknown>[];
+  sharedDefs: Record<string, unknown>;
+} {
+  const defsByContent = new Map<string, { name: string; schema: unknown }>();
+
+  for (const tool of tools) {
+    const schema = tool.inputSchema as Record<string, unknown> | undefined;
+    const defs = schema?.$defs;
+    if (!defs || typeof defs !== "object") continue;
+    for (const [defName, defSchema] of Object.entries(
+      defs as Record<string, unknown>,
+    )) {
+      const key = JSON.stringify(defSchema);
+      if (!defsByContent.has(key)) {
+        defsByContent.set(key, { name: defName, schema: defSchema });
+      }
+    }
+  }
+
+  const sharedDefs: Record<string, unknown> = {};
+  for (const { name, schema } of Array.from(defsByContent.values())) {
+    sharedDefs[name] = schema;
+  }
+
+  const cleanedTools = tools.map((t) => {
+    const schema = { ...(t.inputSchema as Record<string, unknown>) };
+    schema.$defs = undefined;
+    return { ...t, inputSchema: schema };
+  });
+
+  return { tools: cleanedTools, sharedDefs };
+}
+
+export async function introspectMcp(options: IntrospectOptions): Promise<void> {
+  const { server, name, out } = options;
+
+  const parts = server.split(/\s+/);
+  const proc = spawn(parts[0], parts.slice(1), {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: { ...process.env, ...options.env },
+  });
+
+  let buffer = "";
+  let messageId = 0;
+
+  function sendJsonRpc(
+    method: string,
+    params: Record<string, unknown> = {},
+  ): number {
+    const id = ++messageId;
+    const msg = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    proc.stdin?.write(`${msg}\n`);
+    return id;
+  }
+
+  function waitForResponse(targetId: number): Promise<Record<string, unknown>> {
+    return new Promise((res, reject) => {
+      const timeout = setTimeout(() => reject(new Error("Timeout")), 30000);
+      const handler = (chunk: Buffer) => {
+        buffer += chunk.toString();
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed.id === targetId) {
+              clearTimeout(timeout);
+              proc.stdout?.removeListener("data", handler);
+              if (parsed.error) reject(new Error(JSON.stringify(parsed.error)));
+              else res(parsed.result);
+            }
+          } catch {
+            /* ignore non-JSON */
+          }
+        }
+      };
+      proc.stdout?.on("data", handler);
+    });
+  }
+
+  try {
+    console.log(`Connecting to MCP server: ${server}`);
+
+    const initId = sendJsonRpc("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "adk-introspect", version: "1.0.0" },
+    });
+    const initResult = (await waitForResponse(initId)) as Record<
+      string,
+      unknown
+    >;
+    const serverInfo = initResult.serverInfo as
+      | Record<string, string>
+      | undefined;
+    console.log(`Server: ${serverInfo?.name} v${serverInfo?.version}`);
+
+    proc.stdin?.write(
+      `${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}\n`,
+    );
+
+    const toolsId = sendJsonRpc("tools/list", {});
+    const toolsResult = (await waitForResponse(toolsId)) as Record<
+      string,
+      unknown
+    >;
+    const rawTools = (
+      (toolsResult.tools || []) as Record<string, unknown>[]
+    ).map((t) => ({
+      name: t.name as string,
+      description: (t.description as string) || "",
+      inputSchema: (t.inputSchema as Record<string, unknown>) || {
+        type: "object",
+        properties: {},
+      },
+    }));
+    console.log(`Discovered ${rawTools.length} tools`);
+
+    const { tools, sharedDefs } = deduplicateDefs(rawTools);
+    const defsCount = Object.keys(sharedDefs).length;
+    if (defsCount > 0) {
+      console.log(`Hoisted ${defsCount} shared $defs`);
+    }
+
+    const definition: Record<string, unknown> = {
+      path: name,
+      name: serverInfo?.name || name,
+      description: `Agent for ${serverInfo?.name || name}`,
+      version: serverInfo?.version || "1.0.0",
+      visibility: "public",
+      serverSource: server,
+      serverInfo,
+      ...(defsCount > 0 ? { $defs: sharedDefs } : {}),
+      tools,
+      generatedAt: new Date().toISOString(),
+      sdkVersion: "0.22.0",
+    };
+
+    const outPath = out || `./${name}.json`;
+    const resolved = resolve(outPath);
+    mkdirSync(dirname(resolved), { recursive: true });
+    writeFileSync(resolved, `${JSON.stringify(definition, null, 2)}\n`);
+    const sizeKB = (JSON.stringify(definition).length / 1024).toFixed(1);
+    console.log(`\nWrote ${resolved} (${sizeKB}KB, ${tools.length} tools)`);
+  } finally {
+    proc.kill();
+  }
+}

package/src/jsonc.ts

@@ -0,0 +1,83 @@
+/**
+ * JSONC Parser
+ *
+ * Parses JSON with comments (single-line and multi-line)
+ * so agent.json files can be annotated.
+ */
+
+import { readFileSync } from "node:fs";
+
+/**
+ * Strip comments from JSONC content and parse as JSON.
+ */
+export function parseJsonc(content: string): unknown {
+  let result = "";
+  let i = 0;
+  let inString = false;
+  let stringChar = "";
+
+  while (i < content.length) {
+    if (inString) {
+      if (content[i] === "\\" && i + 1 < content.length) {
+        result += content[i] + content[i + 1];
+        i += 2;
+        continue;
+      }
+      if (content[i] === stringChar) {
+        inString = false;
+      }
+      result += content[i];
+      i++;
+      continue;
+    }
+
+    if (content[i] === '"') {
+      inString = true;
+      stringChar = content[i];
+      result += content[i];
+      i++;
+      continue;
+    }
+
+    // Single-line comment
+    if (
+      content[i] === "/" &&
+      i + 1 < content.length &&
+      content[i + 1] === "/"
+    ) {
+      while (i < content.length && content[i] !== "\n") i++;
+      continue;
+    }
+
+    // Multi-line comment
+    if (
+      content[i] === "/" &&
+      i + 1 < content.length &&
+      content[i + 1] === "*"
+    ) {
+      i += 2;
+      while (
+        i + 1 < content.length &&
+        !(content[i] === "*" && content[i + 1] === "/")
+      )
+        i++;
+      i += 2;
+      continue;
+    }
+
+    result += content[i];
+    i++;
+  }
+
+  // Handle trailing commas
+  const cleaned = result.replace(/,\s*([}\]])/g, "$1");
+  return JSON.parse(cleaned);
+}
+
+/**
+ * Read and parse a JSONC file.
+ */
+export function readJsoncFile(path: string): unknown {
+  const content = readFileSync(path, "utf-8");
+  return parseJsonc(content);
+}

package/src/pack.ts

@@ -0,0 +1,395 @@
+/**
+ * ADK Pack
+ *
+ * Generates a publishable npm package from an agent.json file.
+ *
+ * Input: agent.json (SerializedAgentDefinition)
+ * Output: ready-to-publish directory with:
+ *   - package.json
+ *   - agent.json (copy)
+ *   - meta.json (version metadata + diff)
+ *   - index.js + index.d.ts (typed export)
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { resolve } from "node:path";
+import { parseJsonc } from "./jsonc.js";
+import type { SerializedAgentDefinition } from "./serialized.js";
+
+// ============================================
+// Types
+// ============================================
+
+export interface PackOptions {
+  /** Path to agent.json */
+  agentFile: string;
+  /** Output directory (default: ./dist) */
+  outDir?: string;
+  /** npm scope (default: @agentdef) */
+  scope?: string;
+  /** Previous version's agent.json path for diff (optional) */
+  previousAgentFile?: string;
+}
+
+export interface PackResult {
+  packageDir: string;
+  packageName: string;
+  version: string;
+  hash: string;
+  meta: VersionMeta;
+}
+
+export interface VersionMeta {
+  hash: string;
+  serverVersion: string;
+  npmPackage?: string;
+  toolCount: number;
+  sizeBytes: number;
+  generatedAt: string;
+  sdkVersion: string;
+  changes?: VersionChanges;
+}
+
+export interface VersionChanges {
+  previousHash?: string;
+  toolsAdded: string[];
+  toolsRemoved: string[];
+  toolsModified: string[];
+  schemaChanges: string[];
+}
+
+// ============================================
+// Hash
+// ============================================
+
+function contentHash(content: string): string {
+  return createHash("sha256").update(content).digest("hex").slice(0, 8);
+}
+
+// ============================================
+// Diff
+// ============================================
+
+function diffDefinitions(
+  current: SerializedAgentDefinition,
+  previous: SerializedAgentDefinition,
+  previousRawContent: string,
+): VersionChanges {
+  const prevToolNames = new Set(previous.tools.map((t) => t.name));
+  const currToolNames = new Set(current.tools.map((t) => t.name));
+
+  const toolsAdded = current.tools
+    .filter((t) => !prevToolNames.has(t.name))
+    .map((t) => t.name);
+  const toolsRemoved = previous.tools
+    .filter((t) => !currToolNames.has(t.name))
+    .map((t) => t.name);
+
+  // Find modified tools (same name, different schema)
+  const toolsModified: string[] = [];
+  const schemaChanges: string[] = [];
+  const prevToolMap = new Map(previous.tools.map((t) => [t.name, t]));
+
+  for (const tool of current.tools) {
+    const prev = prevToolMap.get(tool.name);
+    if (!prev) continue;
+    const currSchema = JSON.stringify(tool.inputSchema);
+    const prevSchema = JSON.stringify(prev.inputSchema);
+    if (currSchema !== prevSchema) {
+      toolsModified.push(tool.name);
+      // Generate human-readable schema change description
+      const currProps = Object.keys(
+        ((tool.inputSchema as Record<string, unknown>).properties as Record<
+          string,
+          unknown
+        >) || {},
+      );
+      const prevProps = Object.keys(
+        ((prev.inputSchema as Record<string, unknown>).properties as Record<
+          string,
+          unknown
+        >) || {},
+      );
+      const added = currProps.filter((p) => !prevProps.includes(p));
+      const removed = prevProps.filter((p) => !currProps.includes(p));
+      if (added.length > 0) {
+        schemaChanges.push(
+          `${tool.name}: added properties: ${added.join(", ")}`,
+        );
+      }
+      if (removed.length > 0) {
+        schemaChanges.push(
+          `${tool.name}: removed properties: ${removed.join(", ")}`,
+        );
+      }
+      if (added.length === 0 && removed.length === 0) {
+        schemaChanges.push(`${tool.name}: schema modified`);
+      }
+    }
+  }
+
+  return {
+    previousHash: contentHash(previousRawContent),
+    toolsAdded,
+    toolsRemoved,
+    toolsModified,
+    schemaChanges,
+  };
+}
+
+// ============================================
+// Pack
+// ============================================
+
+export function pack(options: PackOptions): PackResult {
+  const { agentFile, outDir = "./dist", scope = "@agentdef" } = options;
+
+  // Read agent.json
+  const agentPath = resolve(agentFile);
+  if (!existsSync(agentPath)) {
+    throw new Error(`agent.json not found: ${agentPath}`);
+  }
+  const agentContent = readFileSync(agentPath, "utf-8");
+  const definition = parseJsonc(agentContent) as SerializedAgentDefinition;
+
+  // Compute hash + version
+  const hash = contentHash(agentContent);
+  const version = `${definition.version || "1.0.0"}`;
+  const packageName = `${scope}/${definition.path}`;
+
+  // Create output directory
+  const packageDir = resolve(outDir, definition.path);
+  mkdirSync(packageDir, { recursive: true });
+
+  // Generate meta.json
+  const meta: VersionMeta = {
+    hash,
+    serverVersion:
+      definition.serverInfo?.version || definition.version || "1.0.0",
+    npmPackage: definition.serverSource,
+    toolCount: definition.tools.length,
+    sizeBytes: Buffer.byteLength(agentContent, "utf-8"),
+    generatedAt: definition.generatedAt || new Date().toISOString(),
+    sdkVersion: definition.sdkVersion || "0.21.0",
+  };
+
+  // Diff against previous if provided
+  if (options.previousAgentFile) {
+    const prevPath = resolve(options.previousAgentFile);
+    if (existsSync(prevPath)) {
+      const prevContent = readFileSync(prevPath, "utf-8");
+      const prevDef = parseJsonc(prevContent) as SerializedAgentDefinition;
+      meta.changes = diffDefinitions(definition, prevDef, prevContent);
+    }
+  }
+
+  // Write agent.json
+  writeFileSync(resolve(packageDir, "agent.json"), agentContent);
+
+  // Write meta.json
+  writeFileSync(
+    resolve(packageDir, "meta.json"),
+    `${JSON.stringify(meta, null, 2)}\n`,
+  );
+
+  // Write package.json
+  const pkg = {
+    name: packageName,
+    version,
+    description:
+      definition.description || `Agent definition for ${definition.name}`,
+    type: "module",
+    main: "index.js",
+    types: "index.d.ts",
+    exports: {
+      ".": {
+        import: "./index.js",
+        types: "./index.d.ts",
+      },
+      "./agent.json": "./agent.json",
+      "./meta.json": "./meta.json",
+    },
+    files: ["index.js", "index.d.ts", "agent.json", "meta.json"],
+    peerDependencies: {
+      "@slashfi/agents-sdk": ">=0.21.0",
+    },
+    keywords: ["agent", "mcp", "agentdef", definition.path],
+    license: "MIT",
+    repository: {
+      type: "git",
+      url: "https://github.com/slashfi/agents-sdk",
+    },
+  };
+  writeFileSync(
+    resolve(packageDir, "package.json"),
+    `${JSON.stringify(pkg, null, 2)}\n`,
+  );
+
+  // Write index.js
+  writeFileSync(
+    resolve(packageDir, "index.js"),
+    [
+      'import { readFileSync } from "node:fs";',
+      'import { fileURLToPath } from "node:url";',
+      'import { dirname, resolve } from "node:path";',
+      "",
+      "const __dirname = dirname(fileURLToPath(import.meta.url));",
+      'const definition = JSON.parse(readFileSync(resolve(__dirname, "agent.json"), "utf-8"));',
+      "export default definition;",
+      "export { definition };",
+      "",
+    ].join("\n"),
+  );
+
+  // Write index.d.ts
+  writeFileSync(
+    resolve(packageDir, "index.d.ts"),
+    [
+      'import type { SerializedAgentDefinition } from "@slashfi/agents-sdk";',
+      "",
+      "declare const definition: SerializedAgentDefinition;",
+      "export default definition;",
+      "export { definition };",
+      "",
+    ].join("\n"),
+  );
+
+  return { packageDir, packageName, version, hash, meta };
+}
+
+// ============================================
+// Publish
+// ============================================
+
+export interface PublishOptions extends PackOptions {
+  /** Dry run (don't actually publish) */
+  dryRun?: boolean;
+  /** npm tag (default: latest) */
+  tag?: string;
+  /** npm access level */
+  access?: "public" | "restricted";
+  /** npm registry URL */
+  registry?: string;
+}
+
+/**
+ * Compare semver: returns true if `a` is older than `b`.
+ */
+function isOlderVersion(a: string, b: string): boolean {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) < (pb[i] || 0)) return true;
+    if ((pa[i] || 0) > (pb[i] || 0)) return false;
+  }
+  return false; // equal
+}
+
+export function publish(options: PublishOptions): PackResult {
+  const result = pack(options);
+
+  // Check if this version already exists in the registry
+  const registryArgs = options.registry ? ["--registry", options.registry] : [];
+  const viewProc = spawnSync(
+    "npm",
+    ["view", `${result.packageName}`, "versions", "--json", ...registryArgs],
+    { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
+  );
+
+  if (viewProc.status === 0 && viewProc.stdout) {
+    try {
+      const raw = JSON.parse(viewProc.stdout);
+      const existing: string[] = Array.isArray(raw) ? raw : [raw];
+
+      // E409 prevention: version already exists
+      if (existing.includes(result.version)) {
+        const versions = existing.join(", ");
+        throw new Error(
+          `\x1b[31m\u2717 ${result.packageName}@${result.version} already exists in registry\x1b[0m\n\n  Published versions: ${versions}\n  Hint: bump the version in agent.json, or use --tag to publish a pre-release`,
+        );
+      }
+
+      // Out-of-order protection: warn if publishing older than latest
+      const latestViewProc = spawnSync(
+        "npm",
+        ["view", `${result.packageName}`, "dist-tags.latest", ...registryArgs],
+        { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
+      );
+      if (latestViewProc.status === 0 && latestViewProc.stdout) {
+        const latest = latestViewProc.stdout.trim();
+        if (latest && !options.tag && isOlderVersion(result.version, latest)) {
+          console.warn(
+            `\x1b[33m\u26A0 Warning: publishing ${result.version} which is older than latest (${latest})\x1b[0m`,
+          );
+          console.warn(
+            `  This will move the "latest" tag from ${latest} to ${result.version}.`,
+          );
+          console.warn(
+            "  Use --tag <name> to publish without affecting latest.",
+          );
+          throw new Error(
+            `Refusing to clobber latest tag. Use --tag <name> to publish ${result.version} alongside ${latest}.`,
+          );
+        }
+      }
+    } catch (e) {
+      if (e instanceof Error && e.message.includes("already exists")) throw e;
+      if (e instanceof Error && e.message.includes("Refusing to clobber"))
+        throw e;
+      // JSON parse error or other issue — continue with publish
+    }
+  }
+
+  const npmArgs = ["publish", result.packageDir];
+  npmArgs.push("--access", options.access || "public");
+  if (options.tag) npmArgs.push("--tag", options.tag);
+  if (options.dryRun) npmArgs.push("--dry-run");
+  if (options.registry) npmArgs.push("--registry", options.registry);
+
+  console.log(
+    `Publishing ${result.packageName}@${result.version} (hash: ${result.hash})`,
+  );
+  const proc = spawnSync("npm", npmArgs, {
+    stdio: ["pipe", "pipe", "pipe"],
+    encoding: "utf-8",
+  });
+
+  if (proc.status !== 0) {
+    const stderr = proc.stderr || "";
+    // Extract npm log path for debug hint
+    const logMatch = stderr.match(/complete log[^:]*:\s*(.+\.log)/i);
+    const logHint = logMatch
+      ? `\n  Debug: cat ${logMatch[1].trim()} | tail -40`
+      : "";
+    // Parse npm error for better messages
+    if (stderr.includes("E409") || stderr.includes("already present")) {
+      throw new Error(
+        `\x1b[31m\u2717 ${result.packageName}@${result.version} already exists in registry\x1b[0m\n\n` +
+          `  Hint: bump the version in agent.json, or use --tag to publish a pre-release${logHint}`,
+      );
+    }
+    if (stderr.includes("E401") || stderr.includes("authentication")) {
+      throw new Error(
+        `\x1b[31m\u2717 Authentication failed\x1b[0m\n\n  Run: npm login --scope=@agentdef\n  Or set NPM_TOKEN in your environment${logHint}`,
+      );
+    }
+    if (stderr.includes("E403") || stderr.includes("Forbidden")) {
+      throw new Error(
+        `\x1b[31m\u2717 Permission denied publishing ${result.packageName}\x1b[0m\n\n  Make sure you have publish access to the @agentdef scope.\n  Run: npm access ls-packages @agentdef${logHint}`,
+      );
+    }
+    // Fallback: show raw error
+    throw new Error(
+      `npm publish failed (exit ${proc.status}):${logHint}\n${stderr}`,
+    );
+  }
+
+  return result;
+}

package/dist/cli.d.ts

@@ -1,24 +0,0 @@
-#!/usr/bin/env bun
-/**
- * agents-sdk CLI
- *
- * Unified command-line interface for the agents SDK.
- *
- * Commands:
- *   codegen  - Generate agent definitions from an MCP server
- *   use      - Execute a tool on a codegenned agent
- *
- * @example
- * ```bash
- * # Generate from MCP server
- * agents-sdk codegen --server 'npx @mcp/notion' --name notion --out ./agents/@notion
- *
- * # Use a tool
- * agents-sdk use notion search_pages '{"query": "hello"}'
- *
- * # List tools on a codegenned agent
- * agents-sdk use notion --list
- * ```
- */
-export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;GAoBG"}