@slashfi/agents-sdk 0.78.0 → 0.80.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

@@ -1155,3 +1155,157 @@ describe("ADK ref registry cache", () => {
     expect(refs[0].description).toBeUndefined();
   });
 });
+
+// ─── isRefAuthComplete + authFields cache ────────────────────────
+
+describe("isRefAuthComplete + cached authFields", () => {
+  /**
+   * The core idea: `auth-status` knows what fields are required for a
+   * given security scheme (it asks the registry). Cache that answer
+   * shape per-ref so subsequent host-side "is this ref ready to call?"
+   * checks can be evaluated locally with no network round-trip, and
+   * stay accurate as the user fills in or clears credentials in the
+   * entry's config.
+   *
+   * `isRefAuthComplete(entry, cacheEntry)` returns:
+   *   - `true`  when all required fields are satisfied (present in
+   *     `entry.config` OR marked `automated`).
+   *   - `false` when at least one required, non-automated field is
+   *     missing.
+   *   - `null`  when the cache has no `authFields` for this ref yet
+   *     (caller should fall back or refresh via `auth-status`).
+   */
+
+  test("cache miss returns null", async () => {
+    const { isRefAuthComplete } = await import("./config-store");
+    const result = isRefAuthComplete(
+      {
+        ref: "@unknown",
+        name: "@unknown",
+        scheme: "https",
+        url: "http://localhost",
+      },
+      undefined,
+    );
+    expect(result).toBeNull();
+  });
+
+  test("proxy mode short-circuits to true regardless of cache", async () => {
+    const { isRefAuthComplete } = await import("./config-store");
+    const result = isRefAuthComplete(
+      {
+        ref: "slash",
+        name: "slash",
+        scheme: "registry",
+        // proxy mode set by ref.add when registry inspection includes it.
+        // biome-ignore lint/suspicious/noExplicitAny: mode isn't on the public type
+        mode: "proxy",
+      } as any,
+      undefined,
+    );
+    expect(result).toBe(true);
+  });
+
+  test("required field present → true", 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: "xyz",
+          access_token: "tok",
+        },
+      },
+      {
+        ref: "@oauth",
+        fetchedAt: new Date().toISOString(),
+        authFields: {
+          client_id: { required: true, automated: false },
+          client_secret: { required: true, automated: false },
+          access_token: { required: true, automated: true },
+        },
+      },
+    );
+    expect(result).toBe(true);
+  });
+
+  test("automated field absent still counts as satisfied", async () => {
+    const { isRefAuthComplete } = await import("./config-store");
+    // dynamicRegistration: client_id is automated, so absence is fine.
+    const result = isRefAuthComplete(
+      {
+        ref: "@oauth",
+        name: "@oauth",
+        scheme: "https",
+        url: "http://localhost",
+        config: {
+          // client_id missing
+          access_token: "tok",
+        },
+      },
+      {
+        ref: "@oauth",
+        fetchedAt: new Date().toISOString(),
+        authFields: {
+          client_id: { required: true, automated: true },
+          access_token: { required: true, automated: true },
+        },
+      },
+    );
+    expect(result).toBe(true);
+  });
+
+  test("required, non-automated field missing → false", 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: "xyz",
+          // access_token missing — user hasn't completed OAuth yet.
+        },
+      },
+      {
+        ref: "@oauth",
+        fetchedAt: new Date().toISOString(),
+        authFields: {
+          client_id: { required: true, automated: false },
+          client_secret: { required: true, automated: false },
+          access_token: { required: true, automated: false },
+        },
+      },
+    );
+    expect(result).toBe(false);
+  });
+
+  test("non-required field absence is fine", async () => {
+    const { isRefAuthComplete } = await import("./config-store");
+    const result = isRefAuthComplete(
+      {
+        ref: "@oauth",
+        name: "@oauth",
+        scheme: "https",
+        url: "http://localhost",
+        config: { access_token: "tok" },
+      },
+      {
+        ref: "@oauth",
+        fetchedAt: new Date().toISOString(),
+        authFields: {
+          client_id: { required: false, automated: false },
+          access_token: { required: true, automated: false },
+        },
+      },
+    );
+    expect(result).toBe(true);
+  });
+});
+

package/src/config-store.ts

@@ -68,16 +68,49 @@ export interface RegistryCacheToolSummary {
 }
 
 /**
- * Per-ref cache entry. Updated as a side-effect of `ref.add()` and
- * `ref.inspect()` whenever the registry response carries description or tool
- * information. Identity-relative (lives next to the consumer-config that
- * issued the registry call), so permission-filtered views stay consistent.
+ * Slim auth-field metadata cached so hosts can locally answer "is this
+ * ref ready to call?" without a registry round-trip. Mirrors the
+ * authoritative shape `auth-status` produces — same source of truth,
+ * just persisted.
+ *
+ * For each field name in the security scheme:
+ *   - `required`  — must end up satisfied for `ref.call` to work.
+ *   - `automated` — adk fills this in itself (e.g. dynamic OAuth
+ *                   client registration). Doesn't need to be `present`
+ *                   in the user's config to count as satisfied.
+ */
+export interface RegistryCacheAuthField {
+  required: boolean;
+  automated: boolean;
+}
+
+/**
+ * Per-ref cache entry. Updated as a side-effect of `ref.add()`,
+ * `ref.inspect()`, and `ref.authStatus()` whenever the registry
+ * response carries description / tool / security-scheme info.
+ * Identity-relative (lives next to the consumer-config that issued
+ * the registry call), so permission-filtered views stay consistent.
  */
 export interface RegistryCacheEntry {
   /** Canonical agent path (e.g. `notion`). Stored for sanity/debug. */
   ref: string;
   description?: string;
   tools?: RegistryCacheToolSummary[];
+  /**
+   * Auth field requirements derived from the registry's security
+   * scheme (extracted by `auth-status`). When present, hosts can
+   * compute "is this ref callable?" by intersecting these with the
+   * entry's `config` — no network round-trip needed. Absent when the
+   * scheme couldn't be fetched (e.g. registry was offline at add
+   * time); fall back to whatever heuristic the caller chooses.
+   *
+   * Note on proxy refs: when the entry is in `proxy` mode the
+   * security scheme is exposed by the *proxy*, and the answer to
+   * "is this callable?" lives server-side — `authFields` is omitted
+   * locally and hosts should treat proxy refs as authoritative
+   * regardless of entry-side fields.
+   */
+  authFields?: Record<string, RegistryCacheAuthField>;
   /** ISO timestamp of the most recent registry round-trip that wrote this. */
   fetchedAt: string;
 }
@@ -91,6 +124,46 @@ export interface RegistryCache {
   refs: Record<string, RegistryCacheEntry>;
 }
 
+/**
+ * "Is this ref ready to call?" answered locally using the cached
+ * security-scheme requirements. Mirrors the `complete` boolean
+ * `auth-status` returns, but doesn't need a network round-trip — the
+ * cached `authFields` capture what the registry said is required, and
+ * we evaluate satisfaction against the entry's current `config`.
+ *
+ * Behavior:
+ *   - `mode: 'proxy'` refs → always true. Auth lives server-side; the
+ *     proxy is the source of truth, no entry-side fields involved.
+ *   - Cache miss (no `authFields` for this ref yet) → returns `null`,
+ *     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.
+ *
+ * Returning `null` for cache miss is intentional. A boolean would
+ * force callers to choose a default that's wrong half the time;
+ * `null` lets them branch explicitly.
+ */
+export function isRefAuthComplete(
+  entry: RefEntry,
+  cacheEntry: RegistryCacheEntry | undefined,
+): 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 ?? {};
+  for (const [field, info] of Object.entries(authFields)) {
+    if (!info.required) continue;
+    if (info.automated) continue;
+    if (!(field in config)) return false;
+  }
+  return true;
+}
+
 // ============================================
 // Types
 // ============================================
@@ -650,6 +723,29 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
     await writeRegistryCache(cache);
   }
 
+  /**
+   * Merge `authFields` into an existing cache entry without clobbering
+   * description/tools, or create a minimal entry if one doesn't exist
+   * yet. Called from `authStatus` so the slim {required, automated}
+   * shape is always available for `isRefAuthComplete` to answer
+   * locally on subsequent calls.
+   */
+  async function upsertRegistryCacheAuthFields(
+    name: string,
+    ref: string,
+    authFields: Record<string, RegistryCacheAuthField>,
+  ): Promise<void> {
+    const cache = await readRegistryCache();
+    const existing = cache.refs[name];
+    cache.refs[name] = {
+      ...(existing ?? { ref, fetchedAt: new Date().toISOString() }),
+      authFields,
+      // Refresh fetchedAt so freshness telemetry stays accurate.
+      fetchedAt: new Date().toISOString(),
+    };
+    await writeRegistryCache(cache);
+  }
+
   async function removeRegistryCacheEntry(name: string): Promise<void> {
     const cache = await readRegistryCache();
     if (!(name in cache.refs)) return;
@@ -2342,6 +2438,21 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         (f) => !f.required || f.present || f.resolvable,
       );
 
+      // Persist the slim {required, automated} per-field shape into the
+      // registry cache so `isRefAuthComplete` can answer subsequent
+      // host-side "is this ref ready?" checks without re-fetching the
+      // security scheme. We deliberately omit `present`/`resolvable`
+      // because those are computed against the current entry.config and
+      // host environment — caching them would go stale immediately.
+      const authFields: Record<string, RegistryCacheAuthField> = {};
+      for (const [field, info] of Object.entries(fields)) {
+        authFields[field] = {
+          required: info.required,
+          automated: info.automated,
+        };
+      }
+      await upsertRegistryCacheAuthFields(name, entry.ref, authFields);
+
       return { name, security, complete, fields };
     },
 

package/src/index.ts

@@ -437,7 +437,9 @@ export type {
   RegistryCache,
   RegistryCacheEntry,
   RegistryCacheToolSummary,
+  RegistryCacheAuthField,
 } from "./config-store.js";
+export { isRefAuthComplete } from "./config-store.js";
 export { createLocalFsStore, getLocalEncryptionKey } from "./local-fs.js";
 export { AdkError, getError, getRecentErrors } from "./adk-error.js";
 export {

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