@slashfi/agents-sdk 0.20.0 → 0.22.0

package/dist/serialized.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Serialized Agent Definition
+ *
+ * Pure-data, JSON-serializable representation of an agent.
+ * No execute functions, no runtime hooks — just schemas and metadata.
+ *
+ * This is the universal IR:
+ * - Codegen produces it (MCP introspection → SerializedAgentDefinition)
+ * - Registry stores it (JSON in DB or filesystem)
+ * - API serves it (GET /agents/:name → SerializedAgentDefinition)
+ * - createClient() hydrates it (definition → typed proxy with real calls)
+ */
+import type { JsonSchema, SecurityScheme } from "./types.js";
+export interface SerializedTool {
+    /** Tool name (unique within agent) */
+    name: string;
+    /** Short description for tool discovery */
+    description: string;
+    /** JSON Schema for input parameters */
+    inputSchema: JsonSchema;
+    /** JSON Schema for output (optional) */
+    outputSchema?: JsonSchema;
+}
+export interface SerializedAgentDefinition {
+    /** Agent path (e.g., 'notion', 'linear', 'github') */
+    path: string;
+    /** Human-readable name */
+    name: string;
+    /** Short description */
+    description: string;
+    /** Version of the definition */
+    version: string;
+    /** Visibility level */
+    visibility: "public" | "private";
+    /** Auth requirements */
+    auth?: SecurityScheme;
+    /** MCP server source command (e.g., 'npx @notionhq/notion-mcp-server') */
+    serverSource?: string;
+    /** Server info from MCP introspection */
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+    /** Tool definitions (schemas only, no execute) */
+    tools: SerializedTool[];
+    /** ISO timestamp of when this was generated */
+    generatedAt?: string;
+    /** SDK version used for codegen */
+    sdkVersion?: string;
+}
+import type { AgentDefinition, ToolContext, ToolDefinition } from "./types.js";
+/**
+ * Serialize an AgentDefinition to its pure-data representation.
+ * Strips execute functions, runtime hooks, listeners, etc.
+ */
+export declare function serializeAgent(agent: AgentDefinition, meta?: {
+    serverSource?: string;
+    version?: string;
+}): SerializedAgentDefinition;
+/**
+ * Serialize a single ToolDefinition to its pure-data representation.
+ */
+export declare function serializeTool(tool: ToolDefinition<ToolContext, unknown, unknown>): SerializedTool;
+//# sourceMappingURL=serialized.d.ts.map

package/dist/serialized.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialized.d.ts","sourceRoot":"","sources":["../src/serialized.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAM7D,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,WAAW,EAAE,UAAU,CAAC;IACxB,wCAAwC;IACxC,YAAY,CAAC,EAAE,UAAU,CAAC;CAC3B;AAMD,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,UAAU,EAAE,QAAQ,GAAG,SAAS,CAAC;IACjC,wBAAwB;IACxB,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,kDAAkD;IAClD,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE/E;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,eAAe,EACtB,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD,yBAAyB,CAY3B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,cAAc,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,GAClD,cAAc,CAOhB"}

package/dist/serialized.js

@@ -0,0 +1,41 @@
+/**
+ * Serialized Agent Definition
+ *
+ * Pure-data, JSON-serializable representation of an agent.
+ * No execute functions, no runtime hooks — just schemas and metadata.
+ *
+ * This is the universal IR:
+ * - Codegen produces it (MCP introspection → SerializedAgentDefinition)
+ * - Registry stores it (JSON in DB or filesystem)
+ * - API serves it (GET /agents/:name → SerializedAgentDefinition)
+ * - createClient() hydrates it (definition → typed proxy with real calls)
+ */
+/**
+ * Serialize an AgentDefinition to its pure-data representation.
+ * Strips execute functions, runtime hooks, listeners, etc.
+ */
+export function serializeAgent(agent, meta) {
+    return {
+        path: agent.path,
+        name: agent.config?.name ?? agent.path,
+        description: agent.config?.description ?? "",
+        version: meta?.version ?? "1.0.0",
+        visibility: agent.visibility ?? "public",
+        auth: agent.config?.security,
+        serverSource: meta?.serverSource,
+        tools: agent.tools.map(serializeTool),
+        generatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Serialize a single ToolDefinition to its pure-data representation.
+ */
+export function serializeTool(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+    };
+}
+//# sourceMappingURL=serialized.js.map

package/dist/serialized.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialized.js","sourceRoot":"","sources":["../src/serialized.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAyDH;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAsB,EACtB,IAAkD;IAElD,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,IAAI,KAAK,CAAC,IAAI;QACtC,WAAW,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,IAAI,EAAE;QAC5C,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,OAAO;QACjC,UAAU,EAAG,KAAK,CAAC,UAAmC,IAAI,QAAQ;QAClE,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ;QAC5B,YAAY,EAAE,IAAI,EAAE,YAAY;QAChC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC;QACrC,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACtC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAmD;IAEnD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClE,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slashfi/agents-sdk",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "author": "Slash Financial",
   "repository": {
     "type": "git",
@@ -8,7 +8,8 @@
   },
   "main": "dist/index.js",
   "bin": {
-    "agents-sdk": "./src/cli.ts"
+    "adk": "./src/adk.ts",
+    "agents-sdk": "./src/adk.ts"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",

package/src/adk.ts

@@ -0,0 +1,398 @@
+#!/usr/bin/env bun
+/**
+ * ADK CLI — Agent Development Kit
+ *
+ * Unified CLI for building, testing, and publishing agent definitions.
+ *
+ * Commands:
+ *   codegen     Generate agent definitions from an MCP server (full codegen)
+ *   introspect  Introspect an MCP server → agent.json (lightweight)
+ *   pack        Generate publishable @agentdef/* package from agent.json
+ *   publish     Pack + npm publish to @agentdef/*
+ *   use         Execute a tool on a generated agent
+ *   list        List all generated agents
+ *
+ * @example
+ * ```bash
+ * # Full codegen from MCP server
+ * adk codegen --server 'npx @mcp/notion' --name notion --out ./agents/@notion
+ *
+ * # Lightweight introspect → agent.json
+ * adk introspect --server 'npx @notionhq/notion-mcp-server' --name notion
+ *
+ * # Build + publish
+ * adk pack
+ * adk publish
+ *
+ * # Use a tool
+ * adk use notion search_pages '{"query": "hello"}'
+ * adk use notion --list
+ * ```
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { codegen, listAgentTools, useAgent } from "./codegen.js";
+import type { CodegenManifest } from "./codegen.js";
+import { pack, publish } from "./pack.js";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+// ============================================
+// Helpers
+// ============================================
+
+function getArg(flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return undefined;
+  return args[idx + 1];
+}
+
+function hasFlag(flag: string): boolean {
+  return args.includes(flag);
+}
+
+function getAgentsDir(): string {
+  return resolve(process.env.AGENTS_SDK_DIR ?? "./agents");
+}
+
+function findAgentDir(name: string): string | null {
+  const agentsDir = getAgentsDir();
+
+  const exactPath = resolve(name);
+  if (existsSync(join(exactPath, ".codegen-manifest.json"))) return exactPath;
+
+  const withAt = join(agentsDir, `@${name}`);
+  if (existsSync(join(withAt, ".codegen-manifest.json"))) return withAt;
+
+  const withoutAt = join(agentsDir, name);
+  if (existsSync(join(withoutAt, ".codegen-manifest.json"))) return withoutAt;
+
+  return null;
+}
+
+function printUsage() {
+  console.log(`
+adk — Agent Development Kit
+
+Usage:
+  adk codegen [options]              Generate agent from MCP server (full codegen)
+  adk introspect [options]           Introspect MCP server → agent.json
+  adk pack [options]                 Generate publishable package from agent.json
+  adk publish [options]              Pack + npm publish to @agentdef/*
+  adk use <agent> [options]          Execute a tool on a generated agent
+  adk list                           List all generated agents
+
+Codegen options:
+  --server <source>     MCP server (command string or URL)
+  --name <name>         Agent name (default: derived from server)
+  --out <dir>           Output directory (default: ./agents/@<name>)
+  --path <path>         Agent path override
+  --no-cli              Skip CLI generation
+  --no-types            Skip TypeScript interface generation
+  --visibility <level>  Agent visibility (public|internal|private)
+
+Introspect options:
+  --server <cmd>        MCP server command to introspect
+  --name <name>         Agent name for output
+  --out <path>          Output path (default: ./<name>.json)
+
+Pack / Publish options:
+  --agent <path>        Path to agent.json (default: ./agent.json)
+  --out <dir>           Output directory (default: ./dist)
+  --scope <scope>       npm scope (default: @agentdef)
+  --previous <path>     Previous agent.json for diff
+  --dry-run             Don't actually publish (publish only)
+  --tag <tag>           npm dist-tag (default: latest)
+  --access <level>      npm access: public | restricted (default: public)
+
+Use options:
+  adk use <agent> <tool> [params_json]
+  adk use <agent> --list              List tools on the agent
+
+Examples:
+  adk codegen --server 'npx @mcp/notion' --name notion
+  adk introspect --server 'npx @notionhq/notion-mcp-server' --name notion
+  adk pack --agent ./agent.json
+  adk publish --dry-run
+  adk use notion search_pages '{"query": "hello"}'
+`);
+}
+
+// ============================================
+// Commands
+// ============================================
+
+async function runCodegen() {
+  const server = getArg("--server");
+  const name = getArg("--name");
+  const outDir = getArg("--out");
+  const agentPath = getArg("--path");
+  const visibility = getArg("--visibility") as
+    | "public"
+    | "internal"
+    | "private"
+    | undefined;
+  const noCli = hasFlag("--no-cli");
+  const noTypes = hasFlag("--no-types");
+
+  if (!server) {
+    console.error(
+      "Error: --server is required.\n" +
+        "  Example: adk codegen --server 'npx @mcp/notion' --name notion",
+    );
+    process.exit(1);
+  }
+
+  const resolvedOutDir =
+    outDir ??
+    join(
+      getAgentsDir(),
+      `@${(name ?? "mcp-agent").toLowerCase().replace(/[^a-z0-9-]/g, "-")}`,
+    );
+
+  console.log(`Connecting to MCP server: ${server}`);
+  console.log(`Output: ${resolvedOutDir}\n`);
+
+  try {
+    const result = await codegen({
+      server,
+      outDir: resolvedOutDir,
+      agentPath,
+      name,
+      cli: !noCli,
+      types: !noTypes,
+      visibility,
+    });
+
+    console.log(
+      `\x1b[32m\u2713\x1b[0m Generated ${result.toolCount} tools from ${result.serverInfo.name ?? "MCP server"}`,
+    );
+    console.log("\nFiles:");
+    for (const f of result.files) {
+      console.log(`  ${f}`);
+    }
+    console.log(
+      `\nUse: adk use ${name ?? result.serverInfo.name ?? "<agent>"} --list`,
+    );
+  } catch (err) {
+    console.error(
+      `\x1b[31mError:\x1b[0m ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exit(1);
+  }
+}
+
+async function runIntrospect() {
+  const server = getArg("--server");
+  const name = getArg("--name");
+  const out = getArg("--out") || (name ? `./${name}.json` : undefined);
+
+  if (!server || !name) {
+    console.error(
+      "Usage: adk introspect --server <cmd> --name <name> [--out <path>]",
+    );
+    process.exit(1);
+  }
+
+  const { introspectMcp } = await import("./introspect.js");
+  await introspectMcp({ server, name, out });
+}
+
+function runPack() {
+  const agentFile = getArg("--agent") || "./agent.json";
+  const outDir = getArg("--out") || "./dist";
+  const scope = getArg("--scope") || "@agentdef";
+  const previousAgentFile = getArg("--previous");
+
+  if (!existsSync(resolve(agentFile))) {
+    console.error(`agent.json not found at ${resolve(agentFile)}`);
+    console.error("Run 'adk introspect' first, or specify --agent <path>");
+    process.exit(1);
+  }
+
+  const result = pack({ agentFile, outDir, scope, previousAgentFile });
+  console.log(`\n\u2705 Packed ${result.packageName}@${result.version}`);
+  console.log(`   Hash: ${result.hash}`);
+  console.log(`   Tools: ${result.meta.toolCount}`);
+  console.log(`   Size: ${(result.meta.sizeBytes / 1024).toFixed(1)}KB`);
+  console.log(`   Output: ${result.packageDir}`);
+  if (result.meta.changes) {
+    const c = result.meta.changes;
+    if (c.toolsAdded.length > 0)
+      console.log(`   Added: ${c.toolsAdded.join(", ")}`);
+    if (c.toolsRemoved.length > 0)
+      console.log(`   Removed: ${c.toolsRemoved.join(", ")}`);
+    if (c.toolsModified.length > 0)
+      console.log(`   Modified: ${c.toolsModified.join(", ")}`);
+  }
+}
+
+function runPublish() {
+  const agentFile = getArg("--agent") || "./agent.json";
+  const outDir = getArg("--out") || "./dist";
+  const scope = getArg("--scope") || "@agentdef";
+  const previousAgentFile = getArg("--previous");
+  const dryRun = hasFlag("--dry-run");
+  const tag = getArg("--tag");
+  const access = getArg("--access") as "public" | "restricted" | undefined;
+  const registry = getArg("--registry");
+
+  if (!existsSync(resolve(agentFile))) {
+    console.error(`agent.json not found at ${resolve(agentFile)}`);
+    console.error("Run 'adk introspect' first, or specify --agent <path>");
+    process.exit(1);
+  }
+
+  try {
+    const result = publish({
+      agentFile,
+      outDir,
+      scope,
+      previousAgentFile,
+      dryRun,
+      tag,
+      access,
+      registry,
+    });
+    console.log(
+      `\n\u2705 Published ${result.packageName}@${result.version} (hash: ${result.hash})`,
+    );
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+
+async function runUse() {
+  const agentName = args[1];
+
+  if (!agentName) {
+    console.error(
+      "Error: agent name required.\n" +
+        "  Example: adk use notion search_pages '{...}'",
+    );
+    process.exit(1);
+  }
+
+  const agentDir = findAgentDir(agentName);
+  if (!agentDir) {
+    console.error(
+      `Error: agent '${agentName}' not found.\n` +
+        `  Looked in: ${getAgentsDir()}\n` +
+        `  Generate first: adk codegen --server '...' --name ${agentName}`,
+    );
+    process.exit(1);
+  }
+
+  if (hasFlag("--list")) {
+    const tools = listAgentTools(agentDir);
+    console.log(`Tools for ${agentName}:\n`);
+    for (const t of tools) {
+      console.log(`  ${t.name.padEnd(30)} ${t.description ?? ""}`);
+    }
+    return;
+  }
+
+  const toolName = args[2];
+  if (!toolName) {
+    console.error(
+      `Error: tool name required.\n  Example: adk use ${agentName} <tool> [params]\n  List tools: adk use ${agentName} --list`,
+    );
+    process.exit(1);
+  }
+
+  const paramsStr = args[3];
+  const params = paramsStr ? JSON.parse(paramsStr) : {};
+
+  try {
+    const result = await useAgent({
+      agentDir,
+      tool: toolName,
+      params,
+    });
+    console.log(JSON.stringify(result, null, 2));
+  } catch (err) {
+    console.error(
+      `\x1b[31mError:\x1b[0m ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exit(1);
+  }
+}
+
+function runList() {
+  const agentsDir = getAgentsDir();
+
+  if (!existsSync(agentsDir)) {
+    console.log("No generated agents found.");
+    return;
+  }
+
+  const entries = readdirSync(agentsDir);
+  const agents: { name: string; tools: number; server?: string }[] = [];
+
+  for (const entry of entries) {
+    const manifestPath = join(agentsDir, entry, ".codegen-manifest.json");
+    if (existsSync(manifestPath)) {
+      try {
+        const manifest: CodegenManifest = JSON.parse(
+          require("node:fs").readFileSync(manifestPath, "utf-8"),
+        );
+        agents.push({
+          name: manifest.agentPath,
+          tools: manifest.tools.length,
+          server: manifest.serverInfo.name,
+        });
+      } catch {
+        agents.push({ name: entry, tools: 0 });
+      }
+    }
+  }
+
+  if (agents.length === 0) {
+    console.log("No generated agents found.");
+    return;
+  }
+
+  console.log("Generated agents:\n");
+  for (const a of agents) {
+    console.log(
+      `  ${a.name.padEnd(25)} ${String(a.tools).padEnd(5)} tools${a.server ? `  (${a.server})` : ""}`,
+    );
+  }
+}
+
+// ============================================
+// Main
+// ============================================
+
+switch (command) {
+  case "codegen":
+    await runCodegen();
+    break;
+  case "introspect":
+    await runIntrospect();
+    break;
+  case "pack":
+    runPack();
+    break;
+  case "publish":
+    runPublish();
+    break;
+  case "use":
+    await runUse();
+    break;
+  case "list":
+    runList();
+    break;
+  case "--help":
+  case "-h":
+  case undefined:
+    printUsage();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+}