@slashfi/agents-sdk 0.40.1 → 0.41.1

package/src/adk-tools.ts

@@ -0,0 +1,156 @@
+/**
+ * ADK Tools — expose an Adk instance as MCP ToolDefinitions.
+ *
+ * Used by atlas-environments (@config agent) and atlas-runtime
+ * to register adk ref/registry operations as MCP tools.
+ *
+ * @example
+ * ```typescript
+ * // Standalone — no scopes
+ * const tools = createAdkTools({ resolveScope: () => adk });
+ *
+ * // Atlas — user/tenant scopes
+ * const tools = createAdkTools({
+ *   resolveScope: (scope) => scope === 'tenant' ? tenantAdk : userAdk,
+ *   scopes: ['user', 'tenant'],
+ * });
+ * ```
+ */
+
+import { defineTool } from "./define.js";
+import type { ToolDefinition, ToolContext } from "./types.js";
+import type { Adk } from "./config-store.js";
+import type { RefEntry, RegistryEntry } from "./define-config.js";
+
+export interface CreateAdkToolsOptions<TCtx extends ToolContext = ToolContext> {
+  /**
+   * Resolve an Adk instance from the scope string and tool context.
+   * Called per-operation. TCtx is your environment's context type.
+   */
+  resolveScope: (scope: string | undefined, ctx: TCtx) => Adk | Promise<Adk>;
+  /** Allowed scope values. If set, added as enum to the JSON schema. */
+  scopes?: string[];
+}
+
+export function createAdkTools<TCtx extends ToolContext = ToolContext>(opts: CreateAdkToolsOptions<TCtx>): ToolDefinition<TCtx>[] {
+  const { resolveScope, scopes } = opts;
+
+  const scopeSchema = scopes
+    ? { type: "string" as const, enum: scopes, description: "Config scope to operate on" }
+    : { type: "string" as const, description: "Config scope (optional)" };
+
+  const refTool = defineTool({
+    name: "ref",
+    description:
+      "Manage agent refs. Operations: add, remove, list, get, update, inspect, call, auth, auth-status, resources, read.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        operation: {
+          type: "string",
+          enum: ["add", "remove", "list", "get", "update", "inspect", "call", "auth", "auth-status", "resources", "read"],
+        },
+        scope: scopeSchema,
+        ref: { type: "string" },
+        name: { type: "string" },
+        scheme: { type: "string" },
+        url: { type: "string" },
+        as: { type: "string" },
+        sourceRegistry: { type: "object", properties: { url: { type: "string" }, agentPath: { type: "string" } } },
+        config: { type: "object" },
+        tool: { type: "string" },
+        params: { type: "object" },
+        full: { type: "boolean" },
+        uris: { type: "array", items: { type: "string" } },
+        apiKey: { type: "string" },
+      },
+      required: ["operation"],
+    },
+    execute: async (input: Record<string, unknown>, ctx) => {
+      const adk = await resolveScope(input.scope as string | undefined, ctx as TCtx);
+      const op = input.operation as string;
+
+      switch (op) {
+        case "add": {
+          const entry: Record<string, unknown> = { ref: input.ref };
+          if (input.scheme) entry.scheme = input.scheme;
+          if (input.url) entry.url = input.url;
+          if (input.as) entry.as = input.as;
+          if (input.sourceRegistry) entry.sourceRegistry = input.sourceRegistry;
+          if (input.config) entry.config = input.config;
+          return adk.ref.add(entry as unknown as RefEntry);
+        }
+        case "remove":
+          return { removed: await adk.ref.remove(input.name as string) };
+        case "list":
+          return { refs: await adk.ref.list() };
+        case "get":
+          return await adk.ref.get(input.name as string);
+        case "update":
+          return { updated: await adk.ref.update(input.name as string, input as unknown as Partial<RefEntry>) };
+        case "inspect":
+          return await adk.ref.inspect(input.name as string, { full: input.full as boolean });
+        case "call":
+          return await adk.ref.call(input.name as string, input.tool as string, input.params as Record<string, unknown>);
+        case "auth":
+          return await adk.ref.auth(input.name as string, { apiKey: input.apiKey as string });
+        case "auth-status":
+          return await adk.ref.authStatus(input.name as string);
+        case "resources":
+          return await adk.ref.resources(input.name as string);
+        case "read":
+          return await adk.ref.read(input.name as string, input.uris as string[]);
+        default:
+          throw new Error(`Unknown ref operation: ${op}`);
+      }
+    },
+  }) as ToolDefinition<TCtx>;
+
+  const registryTool = defineTool({
+    name: "registry",
+    description:
+      "Manage registry connections. Operations: add, remove, list, browse, inspect, test.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        operation: {
+          type: "string",
+          enum: ["add", "remove", "list", "browse", "inspect", "test"],
+        },
+        scope: scopeSchema,
+        url: { type: "string" },
+        name: { type: "string" },
+        query: { type: "string" },
+        auth: { type: "object" },
+      },
+      required: ["operation"],
+    },
+    execute: async (input: Record<string, unknown>, ctx) => {
+      const adk = await resolveScope(input.scope as string | undefined, ctx as TCtx);
+      const op = input.operation as string;
+
+      switch (op) {
+        case "add": {
+          const entry: Record<string, unknown> = { url: input.url, name: input.name };
+          if (input.auth) entry.auth = input.auth;
+          await adk.registry.add(entry as unknown as RegistryEntry);
+          return { added: true, name: input.name, url: input.url };
+        }
+        case "remove":
+          return { removed: await adk.registry.remove(input.name as string) };
+        case "list":
+          return { registries: await adk.registry.list() };
+        case "browse":
+          return { agents: await adk.registry.browse(input.name as string, input.query as string) };
+        case "inspect":
+          return await adk.registry.inspect(input.name as string);
+        case "test":
+          return { results: await adk.registry.test(input.name as string) };
+        default:
+          throw new Error(`Unknown registry operation: ${op}`);
+      }
+    },
+  });
+
+  return [refTool, registryTool as unknown as ToolDefinition<TCtx>];
+}

package/src/adk.ts

@@ -30,6 +30,7 @@ import { pack, publish } from "./pack.js";
 import { createAdk } from "./config-store.js";
 import { createLocalFsStore, getLocalEncryptionKey } from "./local-fs.js";
 import type { Adk } from "./config-store.js";
+import { AdkError, getError, getRecentErrors } from "./adk-error.js";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -78,6 +79,7 @@ function printUsage() {
 adk — Agent Development Kit
 
 Usage:
+  adk proxy <op> [options]           Manage remote adk proxies
   adk registry <op> [options]        Manage registry connections
   adk ref <op> [options]             Manage agent refs
   adk codegen [options]              Generate agent from MCP server
@@ -87,6 +89,11 @@ Usage:
   adk use <agent> [options]          Execute a tool on a generated agent
   adk list                           List all generated agents
 
+Proxy operations:
+  adk proxy add <url> --name <name> [--type mcp|registry] [--agent @config] [--default]
+  adk proxy remove <name>
+  adk proxy list
+
 Registry operations:
   adk registry add <url> --name <name> [--auth-type bearer|api-key|none]
   adk registry remove <name>
@@ -368,6 +375,59 @@ function runList() {
 // Registry CLI
 // ============================================
 
+// ============================================
+// Proxy CLI
+// ============================================
+
+async function runProxy() {
+  const op = args[1];
+  const adk = getAdk();
+
+  switch (op) {
+    case "add": {
+      const url = args[2];
+      const name = getArg("--name");
+      if (!url || !name) { console.error("Usage: adk proxy add <url> --name <name> [--type mcp|registry] [--agent @config] [--default]"); process.exit(1); }
+      const type = (getArg("--type") ?? (url.startsWith("http") ? "mcp" : "registry")) as "mcp" | "registry";
+      const agent = getArg("--agent");
+      const isDefault = hasFlag("--default");
+      await adk.proxy.add({ name, url, type, ...(agent && { agent }), ...(isDefault && { default: true }) });
+      console.log(`Added proxy: ${name} → ${url}${isDefault ? " (default)" : ""}`);
+      break;
+    }
+    case "remove": {
+      const name = args[2];
+      if (!name) { console.error("Usage: adk proxy remove <name>"); process.exit(1); }
+      const removed = await adk.proxy.remove(name);
+      console.log(removed ? `Removed: ${name}` : `Not found: ${name}`);
+      break;
+    }
+    case "list": {
+      const proxies = await adk.proxy.list();
+      if (proxies.length === 0) {
+        console.log("No proxies configured.");
+        break;
+      }
+      console.log(`\n${proxies.length} proxy(s)\n`);
+      for (const p of proxies) {
+        const def = p.default ? " (default)" : "";
+        console.log(`  ${p.name}${def}`);
+        console.log(`    ${p.url} [${p.type}${p.agent ? ` → ${p.agent}` : ""}]`);
+        console.log();
+      }
+      break;
+    }
+    default:
+      console.error(`Unknown proxy operation: ${op}`);
+      console.error("Operations: add, remove, list");
+      process.exit(1);
+  }
+}
+
+// ============================================
+// Registry CLI
+// ============================================
+
 async function runRegistry() {
   const op = args[1];
   const adk = getAdk();
@@ -480,11 +540,19 @@ async function runRef() {
           entry.sourceRegistry = { url: reg.url, agentPath: refArg };
         }
       }
-      const { security } = await adk.ref.add(entry as import("./define-config.js").RefEntry);
-      console.log(`Added ref: ${alias ?? refArg}`);
-      if (security && security.type !== "none") {
-        console.log(`\n  Auth required: ${security.type}`);
-        console.log(`  Run: adk ref auth ${alias ?? refArg}`);
+      try {
+        const { security } = await adk.ref.add(entry as import("./define-config.js").RefEntry);
+        console.log(`Added ref: ${alias ?? refArg}`);
+        if (security && security.type !== "none") {
+          console.log(`\n  Auth required: ${security.type}`);
+          console.log(`  Run: adk ref auth ${alias ?? refArg}`);
+        }
+      } catch (err) {
+        if (err instanceof AdkError) {
+          console.error(err.toAgentString());
+          process.exit(1);
+        }
+        throw err;
       }
       break;
     }
@@ -561,8 +629,17 @@ async function runRef() {
       console.log(`\n${icon} ${status.name}`);
       console.log(`  auth type: ${status.security?.type ?? "none"}`);
       console.log(`  complete:  ${status.complete}`);
-      if (status.present.length > 0) console.log(`  stored:    ${status.present.join(", ")}`);
-      if (status.missing.length > 0) console.log(`  missing:   ${status.missing.join(", ")}`);
+      for (const [field, info] of Object.entries(status.fields)) {
+        const fieldIcon = info.present ? "\x1b[32m\u2713\x1b[0m"
+          : info.resolvable ? "\x1b[36m\u2192\x1b[0m"
+          : info.automated ? "\x1b[33m~\x1b[0m"
+          : "\x1b[31m\u2717\x1b[0m";
+        const source = info.present ? "stored"
+          : info.resolvable ? "resolvable"
+          : info.automated ? "automated"
+          : "missing";
+        console.log(`  ${fieldIcon} ${field}: ${source}${info.required ? "" : " (optional)"}`);
+      }
       console.log();
       break;
     }
@@ -622,6 +699,26 @@ async function runRef() {
 // ============================================
 
 switch (command) {
+  case "error": {
+    const errorId = args[1];
+    if (!errorId) {
+      const errors = getRecentErrors();
+      if (errors.length === 0) { console.log("No recent errors."); break; }
+      console.log(`\n${errors.length} recent error(s)\n`);
+      for (const e of errors.slice(-10)) {
+        console.log(`  ${e.errorId} [${e.code}] ${e.message}`);
+      }
+      console.log();
+    } else {
+      const err = getError(errorId);
+      if (!err) { console.error(`Error not found: ${errorId}`); process.exit(1); }
+      console.log(err.toDebugString());
+    }
+    break;
+  }
+  case "proxy":
+    await runProxy();
+    break;
   case "registry":
     await runRegistry();
     break;