@slashfi/agents-sdk 0.79.0 → 0.81.0

package/src/adk.ts

@@ -22,8 +22,9 @@
  * ```
  */
 
-import { join } from "node:path";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
+import { join } from "node:path";
 import { createAdk } from "./config-store.js";
 import { createLocalFsStore, getLocalEncryptionKey } from "./local-fs.js";
 import type { Adk } from "./config-store.js";
@@ -31,6 +32,12 @@ import { AdkError, getError, getRecentErrors } from "./adk-error.js";
 import { runInit, parseTarget } from "./init.js";
 import { materializeRef, syncAllRefs } from "./materialize.js";
 import { adkCheck } from "./adk-check.js";
+import {
+  refsRootExists,
+  renderResults,
+  searchRefs,
+  writeSearchIndex,
+} from "./search.js";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -39,6 +46,24 @@ const command = args[0];
 // Helpers
 // ============================================
 
+/**
+ * Read the SDK's published version from the sibling package.json.
+ * Resolved at runtime so a single source-of-truth lives in the manifest.
+ * Safe for both `bun src/adk.ts` (dev) and the npm-installed bin (which
+ * still runs through bun via the shebang).
+ */
+function getCliVersion(): string {
+  try {
+    const pkgPath = join(import.meta.dir, "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
+      version?: string;
+    };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 function getArg(flag: string): string | undefined {
   const idx = args.indexOf(flag);
   if (idx === -1 || idx + 1 >= args.length) return undefined;
@@ -95,10 +120,12 @@ adk — Agent Development Kit
 Usage:
   adk init [--target <agent>:<path>]  Setup + install skills for coding agents
   adk sync [--ref <name>]             Materialize tool docs for all refs in config
+  adk search <query> [options]        BM25 search over materialized refs/tools
   adk registry <op> [options]        Manage registry connections
   adk ref <op> [options]             Manage agent refs
   adk config-path                    Print config directory path
   adk error [id]                     View recent errors or a specific error
+  adk version | --version | -v       Print the installed adk SDK version
 
 Registry operations:
   adk registry add <url> --name <name> [--auth-type bearer|api-key|none] [--proxy [--proxy-agent @config]]
@@ -135,6 +162,15 @@ Environment:
   ADK_TOKEN             Bearer token for authenticated registries
   ADK_ENCRYPTION_KEY    Override encryption key (default: auto from ~/.adk/.encryption-key)
 
+Search options:
+  adk search <query> [--json] [--limit N] [--ref <name>] [--tools-only] [--refs-only]
+                                      BM25 over ~/.adk/refs/* — index includes
+                                      ref names, descriptions, tool names,
+                                      tool docs, parameter names, and skill
+                                      resources. Reads ~/.adk/.search-index.json
+                                      when present (rebuilt by \`adk sync\`),
+                                      otherwise walks refs/* on the fly.
+
 Examples:
   adk init --target claude --target cursor --target codex
   adk registry add https://registry.slash.com --name public
@@ -142,6 +178,8 @@ Examples:
   adk ref add notion --registry public
   adk ref inspect notion --full
   adk ref call notion notion-search '{"query":"hello"}'
+  adk search "schedule reminder" --json
+  adk search "email unread inbox" --tools-only --limit 5
 `);
 }
 
@@ -575,6 +613,58 @@ switch (command) {
       for (const f of failed) console.log(`    ${f.name}: ${f.error}`);
     }
     console.log(`\nDocs written to: ${configDir}/refs/`);
+    // Persist the BM25 search index so `adk search` can skip the
+    // recursive ref walk on every query. Best-effort — failure here
+    // shouldn't fail `adk sync` since the search path falls back to a
+    // fresh walk.
+    try {
+      const { path, documentCount } = writeSearchIndex(configDir);
+      console.log(`Search index: ${path} (${documentCount} docs)`);
+    } catch (err) {
+      console.log(
+        `\x1b[33m!\x1b[0m Failed to write search index: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    break;
+  }
+  case "search": {
+    const configDir = process.env.ADK_CONFIG_DIR ?? join(homedir(), ".adk");
+    const refsRoot = join(configDir, "refs");
+    // Positional query — first non-flag argv after the `search` command.
+    const query = args
+      .filter((a) => !a.startsWith("--"))
+      .slice(1)
+      .join(" ")
+      .trim();
+    if (!query) {
+      console.log("Usage: adk search \"<query>\" [--json] [--limit N] [--ref name] [--tools-only] [--refs-only]");
+      process.exit(1);
+    }
+    if (!refsRootExists(refsRoot)) {
+      const msg = `No materialized refs found at ${refsRoot}. Run \`adk sync\` first.`;
+      if (hasFlag("--json")) {
+        console.log(JSON.stringify({ error: msg, results: [] }));
+      } else {
+        console.log(msg);
+      }
+      break;
+    }
+    const limitArg = getArg("--limit");
+    const limit = limitArg ? Number.parseInt(limitArg, 10) : undefined;
+    const ref = getArg("--ref");
+    const toolsOnly = hasFlag("--tools-only");
+    const refsOnly = hasFlag("--refs-only");
+    const results = searchRefs(refsRoot, query, {
+      ...(limit !== undefined && Number.isFinite(limit) && { limit }),
+      ...(ref && { ref }),
+      ...(toolsOnly && { toolsOnly: true }),
+      ...(refsOnly && { refsOnly: true }),
+    });
+    if (hasFlag("--json")) {
+      console.log(JSON.stringify(results, null, 2));
+    } else {
+      console.log(renderResults(results));
+    }
     break;
   }
   case "config-path": {
@@ -619,6 +709,11 @@ switch (command) {
     const result = await adkCheck({ file, code, run: isRun, noCheck });
     process.exit(result.exitCode);
   }
+  case "--version":
+  case "-v":
+  case "version":
+    console.log(getCliVersion());
+    break;
   case "--help":
   case "-h":
   case undefined:

package/src/config-store.test.ts

@@ -1307,5 +1307,61 @@ describe("isRefAuthComplete + cached authFields", () => {
     );
     expect(result).toBe(true);
   });
+
+  test("resolvableFields satisfies required, non-automated fields absent from config", async () => {
+    // Scenario: registry-hosted OAuth where the platform injects
+    // client_id / client_secret at runtime via resolveCredentials.
+    // The registry sees them as user-provided (required + non-automated)
+    // but the consumer environment satisfies them externally.
+    const { isRefAuthComplete } = await import("./config-store");
+    const result = isRefAuthComplete(
+      {
+        ref: "google-gmail",
+        name: "google-gmail",
+        scheme: "registry",
+        config: {
+          // client_id / client_secret missing — resolved from env vars.
+          access_token: "tok",
+        },
+      },
+      {
+        ref: "google-gmail",
+        fetchedAt: new Date().toISOString(),
+        authFields: {
+          client_id: { required: true, automated: false },
+          client_secret: { required: true, automated: false },
+          access_token: { required: true, automated: true },
+        },
+      },
+      { resolvableFields: ["client_id", "client_secret"] },
+    );
+    expect(result).toBe(true);
+  });
+
+  test("resolvableFields does not bypass missing fields it doesn't list", async () => {
+    const { isRefAuthComplete } = await import("./config-store");
+    const result = isRefAuthComplete(
+      {
+        ref: "@oauth",
+        name: "@oauth",
+        scheme: "https",
+        url: "http://localhost",
+        config: {
+          client_id: "abc",
+          // client_secret missing AND not listed as resolvable.
+        },
+      },
+      {
+        ref: "@oauth",
+        fetchedAt: new Date().toISOString(),
+        authFields: {
+          client_id: { required: true, automated: false },
+          client_secret: { required: true, automated: false },
+        },
+      },
+      { resolvableFields: ["client_id"] },
+    );
+    expect(result).toBe(false);
+  });
 });
 

package/src/config-store.ts

@@ -124,6 +124,25 @@ export interface RegistryCache {
   refs: Record<string, RegistryCacheEntry>;
 }
 
+/**
+ * Options for `isRefAuthComplete`.
+ */
+export interface RefAuthCompleteOptions {
+  /**
+   * Field names the consumer can resolve at call time without them
+   * being present in `entry.config` — typically OAuth client_id /
+   * client_secret resolved from environment variables or platform
+   * config by the host's `resolveCredentials` callback.
+   *
+   * Required-non-automated fields listed here count as satisfied even
+   * when missing from `entry.config`. The default behaviour (no opt
+   * passed) requires every such field to live in config, which is
+   * correct for self-hosted SDK consumers but wrong for platforms
+   * that inject OAuth client credentials at runtime.
+   */
+  resolvableFields?: ReadonlyArray<string>;
+}
+
 /**
  * "Is this ref ready to call?" answered locally using the cached
  * security-scheme requirements. Mirrors the `complete` boolean
@@ -138,10 +157,11 @@ export interface RegistryCache {
  *     signaling "I don't know — caller should fall back to its own
  *     heuristic or call `auth-status` to populate the cache".
  *   - Cache hit → for every required, non-automated field, checks
- *     presence in `entry.config`. Mirrors the `present || resolvable`
- *     check in `auth-status` but evaluates against current config.
- *     `automated` fields (e.g. dynamic OAuth client_id) count as
- *     satisfied even when absent — adk supplies them at call time.
+ *     presence in `entry.config` OR (if `opts.resolvableFields`
+ *     includes the field name) treats it as satisfied externally.
+ *     Mirrors the `present || resolvable` check in `auth-status`.
+ *     `automated` fields (e.g. dynamic OAuth client_id minted by the
+ *     registry) always count as satisfied.
  *
  * Returning `null` for cache miss is intentional. A boolean would
  * force callers to choose a default that's wrong half the time;
@@ -150,16 +170,23 @@ export interface RegistryCache {
 export function isRefAuthComplete(
   entry: RefEntry,
   cacheEntry: RegistryCacheEntry | undefined,
+  opts?: RefAuthCompleteOptions,
 ): boolean | null {
   if (typeof entry === "string") return false;
   if ((entry as { mode?: unknown }).mode === "proxy") return true;
   const authFields = cacheEntry?.authFields;
   if (!authFields) return null;
   const config = entry.config ?? {};
+  const resolvable =
+    opts?.resolvableFields && opts.resolvableFields.length > 0
+      ? new Set(opts.resolvableFields)
+      : null;
   for (const [field, info] of Object.entries(authFields)) {
     if (!info.required) continue;
     if (info.automated) continue;
-    if (!(field in config)) return false;
+    if (field in config) continue;
+    if (resolvable && resolvable.has(field)) continue;
+    return false;
   }
   return true;
 }

package/src/materialize.ts

@@ -288,20 +288,58 @@ export async function materializeRef(
   }
 
   // 2. Fetch and write resources (skills)
+  //
+  // `list_resources` returns URIs only — content is omitted to keep the
+  // listing payload small. We have to follow up with `read_resources(uris)`
+  // to actually fetch the body. Then the per-resource field is `content`,
+  // not `text` (per `CallAgentReadResourcesResponse`).
+  //
+  // Response shape varies depending on the call path: direct calls return
+  // `{success, agentPath, resources}` while proxied calls return
+  // `{success, result: {success, agentPath, resources}}` (the proxy wraps
+  // the inner registry response). Unwrap both shapes the same way.
   try {
-    const resourcesResult = await adk.ref.resources(refName);
-    const response = resourcesResult as any;
-    if (response?.result?.resources) {
-      for (const resource of response.result.resources) {
-        if (resource.uri && resource.text) {
-          const filename = resource.uri.split("/").pop() ?? "resource.md";
-          ensureWrite(join(skillsDir, filename), resource.text);
-          skillCount++;
-        }
+    type ResourceListEntry = {
+      uri?: string;
+      name?: string;
+      mimeType?: string;
+    };
+    type ResourceReadEntry = ResourceListEntry & {
+      content?: string;
+      error?: string;
+    };
+    const unwrapResources = <T>(raw: unknown): T[] => {
+      const r = raw as Record<string, unknown> | null | undefined;
+      if (!r) return [];
+      if (Array.isArray(r.resources)) return r.resources as T[];
+      const inner = r.result as Record<string, unknown> | undefined;
+      if (inner && Array.isArray(inner.resources))
+        return inner.resources as T[];
+      return [];
+    };
+
+    const listed = unwrapResources<ResourceListEntry>(
+      await adk.ref.resources(refName),
+    );
+    const uris = listed
+      .map((r) => r.uri)
+      .filter((u): u is string => typeof u === "string" && u.length > 0);
+
+    if (uris.length > 0) {
+      const fetched = unwrapResources<ResourceReadEntry>(
+        await adk.ref.read(refName, uris),
+      );
+      for (const resource of fetched) {
+        if (!resource.uri) continue;
+        if (typeof resource.content !== "string") continue;
+        const filename = resource.uri.split("/").pop() || "resource.md";
+        ensureWrite(join(skillsDir, filename), resource.content);
+        skillCount++;
       }
     }
   } catch {
-    // resources fetch failed — might not be supported
+    // resources fetch failed — registry might not support resources, or
+    // ref isn't authenticated yet. Best-effort only.
   }
 
   return { toolCount, skillCount, typesGenerated, docsGenerated };