@slashfi/agents-sdk 0.62.0 → 0.63.0

package/src/introspect.ts

@@ -1,171 +0,0 @@
-/**
- * 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

@@ -1,83 +0,0 @@
-/**
- * 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

@@ -1,394 +0,0 @@
-/**
- * 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";
-import { assertValidDefinition } from "./validate.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;
-
-  // Validate the definition schema
-  assertValidDefinition(definition, agentPath);
-
-  // 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;
-}