@slashfi/agents-sdk 0.21.0 → 0.23.0

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

package/src/callback/index.ts

@@ -0,0 +1,172 @@
+/**
+ * Agent Callback — Deferred call_agent execution with triggers.
+ *
+ * An agent_callback is a call_agent command with an optional trigger.
+ * When the trigger fires (e.g., user submits a form), template references
+ * like {{trigger.variable_name}} are resolved with the trigger's values
+ * and the call_agent command is executed.
+ *
+ * This module provides the unopinionated contract:
+ * - Trigger schema (extensible discriminated union)
+ * - Template resolution
+ * - Store interface
+ * - Validation utilities
+ *
+ * No platform-specific code (no Slack, no CockroachDB, no Atlas).
+ */
+
+// ---------------------------------------------------------------------------
+// Trigger Schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Base trigger type. Implementations extend this with specific trigger sources
+ * (e.g., slack_block_kit, webhook, timer).
+ *
+ * The `type` field discriminates between trigger sources.
+ * Additional fields are trigger-specific.
+ */
+export interface AgentCallbackTrigger {
+  type: string;
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Callback Status
+// ---------------------------------------------------------------------------
+
+export type AgentCallbackStatus =
+  | 'pending'
+  | 'completed'
+  | 'expired'
+  | 'cancelled';
+
+// ---------------------------------------------------------------------------
+// Callback Entry
+// ---------------------------------------------------------------------------
+
+/**
+ * A stored agent_callback — a call_agent command waiting for its trigger to fire.
+ */
+export interface AgentCallbackEntry<TMetadata = Record<string, unknown>> {
+  id: string;
+  status: AgentCallbackStatus;
+  /** The call_agent command. Params may contain {{trigger.x}} templates. */
+  callback: Record<string, unknown>;
+  /** Trigger definition — how values are collected. */
+  trigger?: AgentCallbackTrigger;
+  /** Implementation-specific context (e.g., creator branch, user ID). */
+  metadata?: TMetadata;
+  /** Resolved values from the trigger, keyed by variable name. */
+  resolvedValues?: Record<string, string>;
+  /** Callback expires after this time. */
+  expiresAt?: Date;
+  createdAt: Date;
+  completedAt?: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Create Options
+// ---------------------------------------------------------------------------
+
+export interface CreateAgentCallbackOptions<TMetadata = Record<string, unknown>> {
+  /** The call_agent command. May contain {{trigger.x}} template references in params. */
+  callback: Record<string, unknown>;
+  /** Trigger definition. */
+  trigger?: AgentCallbackTrigger;
+  /** Implementation-specific context. */
+  metadata?: TMetadata;
+  /** TTL in milliseconds (default: implementation-defined). */
+  ttlMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Resolve Options
+// ---------------------------------------------------------------------------
+
+export interface ResolveAgentCallbackOptions {
+  /** The callback ID to resolve. */
+  id: string;
+  /** Values from the trigger source, keyed by variable name. */
+  values: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Store Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Agent Callback Store — persistence layer for deferred call_agent commands.
+ * Implementations can use any backing store (CockroachDB, SQLite, in-memory, etc.).
+ */
+export interface AgentCallbackStore<TMetadata = Record<string, unknown>> {
+  create(options: CreateAgentCallbackOptions<TMetadata>): Promise<string>;
+  get(id: string): Promise<AgentCallbackEntry<TMetadata> | null>;
+  resolve(options: ResolveAgentCallbackOptions): Promise<AgentCallbackEntry<TMetadata>>;
+  cancel(id: string): Promise<boolean>;
+  listPending(limit?: number): Promise<AgentCallbackEntry<TMetadata>[]>;
+  expireStale(): Promise<number>;
+}
+
+// ---------------------------------------------------------------------------
+// Template Resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve {{trigger.variable}} references in an object tree.
+ * Scans all string values and replaces {{trigger.x}} with the
+ * corresponding value from triggerValues.
+ *
+ * Unresolved references are left as-is.
+ */
+export function resolveCallbackTemplates<T>(
+  obj: T,
+  triggerValues: Record<string, string>,
+): T {
+  if (typeof obj === 'string') {
+    return obj.replace(/\{\{trigger\.(\w+)\}\}/g, (_match, varName: string) => {
+      return triggerValues[varName] ?? `{{trigger.${varName}}}`;
+    }) as T;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => resolveCallbackTemplates(item, triggerValues)) as T;
+  }
+  if (obj !== null && typeof obj === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(obj as Record<string, unknown>)) {
+      result[key] = resolveCallbackTemplates(val, triggerValues);
+    }
+    return result as T;
+  }
+  return obj;
+}
+
+/**
+ * Validate that all {{trigger.x}} references in a callback have
+ * corresponding variables in the provided set.
+ * Returns array of unresolved variable names, or empty if valid.
+ */
+export function validateCallbackTemplates(
+  callback: Record<string, unknown>,
+  knownVariables: string[],
+): string[] {
+  const definedVars = new Set(knownVariables);
+  const referencedVars: string[] = [];
+
+  const scanForRefs = (obj: unknown): void => {
+    if (typeof obj === 'string') {
+      const matches = obj.matchAll(/\{\{trigger\.(\w+)\}\}/g);
+      for (const match of matches) {
+        referencedVars.push(match[1]);
+      }
+    } else if (Array.isArray(obj)) {
+      obj.forEach(scanForRefs);
+    } else if (obj !== null && typeof obj === 'object') {
+      Object.values(obj as Record<string, unknown>).forEach(scanForRefs);
+    }
+  };
+
+  scanForRefs(callback);
+
+  return referencedVars.filter((v) => !definedVars.has(v));
+}

package/src/index.ts

@@ -314,3 +314,46 @@ 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";
+
+// ============================================
+// Agent Callbacks (deferred call_agent commands)
+// ============================================
+
+export {
+  resolveCallbackTemplates,
+  validateCallbackTemplates,
+} from "./callback/index.js";
+export type {
+  AgentCallbackTrigger,
+  AgentCallbackStatus,
+  AgentCallbackEntry,
+  AgentCallbackStore,
+  CreateAgentCallbackOptions,
+  ResolveAgentCallbackOptions,
+} from "./callback/index.js";