@slashfi/agents-sdk 0.20.0 → 0.22.0

package/src/client.ts

@@ -0,0 +1,273 @@
+/**
+ * Agent Client
+ *
+ * Creates a typed client from a SerializedAgentDefinition.
+ * The client spawns (or connects to) the MCP server and proxies
+ * tool calls via JSON-RPC.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@slashfi/agents-sdk';
+ * import definition from './agents/notion/definition.json';
+ *
+ * const client = createClient(definition, {
+ *   env: { NOTION_TOKEN: process.env.NOTION_TOKEN },
+ * });
+ *
+ * const result = await client.call('API-post-search', { query: 'meeting notes' });
+ * await client.close();
+ * ```
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+import type {
+  SerializedAgentDefinition,
+  SerializedTool,
+} from "./serialized.js";
+
+// ============================================
+// Client Options
+// ============================================
+
+export interface CreateClientOptions {
+  /** Extra environment variables for the MCP server process */
+  env?: Record<string, string | undefined>;
+  /** Override the server command (defaults to definition.serverSource) */
+  serverCommand?: string;
+  /** Timeout for tool calls in ms (default: 30000) */
+  timeout?: number;
+}
+
+// ============================================
+// Agent Client
+// ============================================
+
+export interface AgentClient {
+  /** The definition this client was created from */
+  readonly definition: SerializedAgentDefinition;
+
+  /** List available tools */
+  tools(): SerializedTool[];
+
+  /** Call a tool by name */
+  call(toolName: string, input?: Record<string, unknown>): Promise<unknown>;
+
+  /** Check if connected */
+  isConnected(): boolean;
+
+  /** Close the MCP server connection */
+  close(): void;
+}
+
+// ============================================
+// MCP Stdio Transport
+// ============================================
+
+interface PendingRequest {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+class McpStdioClient implements AgentClient {
+  readonly definition: SerializedAgentDefinition;
+  private proc: ChildProcess | null = null;
+  private messageId = 0;
+  private buffer = "";
+  private pending = new Map<number, PendingRequest>();
+  private initialized = false;
+  private initPromise: Promise<void> | null = null;
+  private serverCommand: string;
+  private env: Record<string, string | undefined>;
+  private timeout: number;
+
+  constructor(
+    definition: SerializedAgentDefinition,
+    options: CreateClientOptions = {},
+  ) {
+    this.definition = definition;
+    this.serverCommand = options.serverCommand ?? definition.serverSource ?? "";
+    this.env = options.env ?? {};
+    this.timeout = options.timeout ?? 30000;
+
+    if (!this.serverCommand) {
+      throw new Error(
+        `No server command for agent "${definition.path}". Set serverSource in the definition or pass serverCommand in options.`,
+      );
+    }
+  }
+
+  tools(): SerializedTool[] {
+    return this.definition.tools;
+  }
+
+  isConnected(): boolean {
+    return this.proc !== null && !this.proc.killed;
+  }
+
+  async call(
+    toolName: string,
+    input: Record<string, unknown> = {},
+  ): Promise<unknown> {
+    // Validate tool exists
+    const tool = this.definition.tools.find((t) => t.name === toolName);
+    if (!tool) {
+      const available = this.definition.tools.map((t) => t.name).join(", ");
+      throw new Error(`Tool "${toolName}" not found. Available: ${available}`);
+    }
+
+    // Ensure connected + initialized
+    await this.ensureInitialized();
+
+    // Send tools/call
+    const result = await this.sendRequest("tools/call", {
+      name: toolName,
+      arguments: input,
+    });
+
+    // MCP tools/call returns { content: [{ type, text }] }
+    const resultObj = result as Record<string, unknown> | null;
+    if (resultObj && typeof resultObj === "object" && "content" in resultObj) {
+      const content = resultObj.content;
+      if (Array.isArray(content) && content.length > 0) {
+        const first = content[0];
+        if (first.type === "text") {
+          try {
+            return JSON.parse(first.text);
+          } catch {
+            return first.text;
+          }
+        }
+        return first;
+      }
+    }
+    return result;
+  }
+
+  close(): void {
+    if (this.proc) {
+      this.proc.kill();
+      this.proc = null;
+    }
+    this.initialized = false;
+    this.initPromise = null;
+    // Reject all pending
+    for (const req of Array.from(this.pending.values())) {
+      clearTimeout(req.timer);
+      req.reject(new Error("Client closed"));
+    }
+    this.pending.clear();
+  }
+
+  // ── Private ──
+
+  private async ensureInitialized(): Promise<void> {
+    if (this.initialized) return;
+    if (this.initPromise) return this.initPromise;
+
+    this.initPromise = this.connect();
+    await this.initPromise;
+    this.initialized = true;
+  }
+
+  private async connect(): Promise<void> {
+    const parts = this.serverCommand.split(/\s+/);
+    this.proc = spawn(parts[0], parts.slice(1), {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, ...this.env },
+    });
+
+    this.proc.stdout?.on("data", (chunk: Buffer) => this.onData(chunk));
+    this.proc.on("error", (err) => {
+      for (const req of Array.from(this.pending.values())) {
+        clearTimeout(req.timer);
+        req.reject(err);
+      }
+      this.pending.clear();
+    });
+
+    // Initialize handshake
+    await this.sendRequest("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "agents-sdk-client", version: "1.0.0" },
+    });
+
+    // Send initialized notification
+    this.sendNotification("notifications/initialized");
+  }
+
+  private sendRequest(
+    method: string,
+    params: Record<string, unknown> = {},
+  ): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const id = ++this.messageId;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Timeout after ${this.timeout}ms calling ${method}`));
+      }, this.timeout);
+
+      this.pending.set(id, { resolve, reject, timer });
+
+      const msg = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+      this.proc?.stdin?.write(`${msg}\n`);
+    });
+  }
+
+  private sendNotification(
+    method: string,
+    params?: Record<string, unknown>,
+  ): void {
+    const msg = JSON.stringify({
+      jsonrpc: "2.0",
+      method,
+      ...(params ? { params } : {}),
+    });
+    this.proc?.stdin?.write(`${msg}\n`);
+  }
+
+  private onData(chunk: Buffer): void {
+    this.buffer += chunk.toString();
+    const lines = this.buffer.split("\n");
+    this.buffer = lines.pop() || "";
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed.id != null && this.pending.has(parsed.id)) {
+          const req = this.pending.get(parsed.id);
+          if (!req) continue;
+          this.pending.delete(parsed.id);
+          clearTimeout(req.timer);
+          if (parsed.error) {
+            req.reject(new Error(JSON.stringify(parsed.error)));
+          } else {
+            req.resolve(parsed.result);
+          }
+        }
+      } catch {
+        // ignore non-JSON lines (stderr leakage, etc.)
+      }
+    }
+  }
+}
+
+// ============================================
+// Factory
+// ============================================
+
+/**
+ * Create an agent client from a serialized definition.
+ *
+ * The client lazily spawns the MCP server on first call and
+ * proxies tool invocations via JSON-RPC over stdio.
+ */
+export function createClient(
+  definition: SerializedAgentDefinition,
+  options?: CreateClientOptions,
+): AgentClient {
+  return new McpStdioClient(definition, options);
+}

package/src/index.ts

@@ -294,3 +294,49 @@ export type {
   McpTransport,
   ServerSource,
 } from "./codegen.js";
+
+// ============================================
+// Serialized Agent Definitions
+// ============================================
+
+export { serializeAgent, serializeTool } from "./serialized.js";
+export type {
+  SerializedAgentDefinition,
+  SerializedTool,
+} from "./serialized.js";
+
+// ============================================
+// Agent Client
+// ============================================
+
+export { createClient } from "./client.js";
+export type {
+  AgentClient,
+  CreateClientOptions,
+} from "./client.js";
+
+// ============================================
+// JSONC Parser
+// ============================================
+
+export { parseJsonc, readJsoncFile } from "./jsonc.js";
+
+// ============================================
+// Pack & Publish
+// ============================================
+
+export { pack, publish } from "./pack.js";
+export type {
+  PackOptions,
+  PackResult,
+  PublishOptions,
+  VersionMeta,
+  VersionChanges,
+} from "./pack.js";
+
+// ============================================
+// Introspect
+// ============================================
+
+export { introspectMcp } from "./introspect.js";
+export type { IntrospectOptions } from "./introspect.js";

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);
+}