@slashfi/agents-sdk 0.28.3 → 0.30.0

package/src/registry-consumer.ts

@@ -38,7 +38,7 @@ import type {
   ResolvedRegistry,
 } from "./define-config.js";
 import {
-  isSecretUrl,
+  isSecretUri,
   normalizeRef,
   normalizeRegistry,
 } from "./define-config.js";
@@ -55,6 +55,72 @@ export const REGISTRY_TYPE_HTTPS = "https";
 /** Built-in registry types that bypass normal registry resolution */
 const DIRECT_REGISTRY_TYPES = new Set([REGISTRY_TYPE_MCP, REGISTRY_TYPE_HTTPS]);
 
+/** Regex for {{secret-uri}} template syntax */
+const TEMPLATE_REGEX = /\{\{(.+?)\}\}/g;
+
+/** Check if a string contains {{...}} template expressions */
+function hasTemplates(value: string): boolean {
+  return TEMPLATE_REGEX.test(value);
+}
+
+/**
+ * Resolve {{secret-uri}} templates in a string.
+ * E.g. "Bearer {{file:///.secrets/key}}" → "Bearer actual-key-value"
+ */
+async function resolveTemplateString(
+  value: string,
+  resolver: SecretResolver,
+  auth?: { token?: string },
+): Promise<string> {
+  // Reset regex state
+  TEMPLATE_REGEX.lastIndex = 0;
+  const matches = [...value.matchAll(/\{\{(.+?)\}\}/g)];
+  if (matches.length === 0) return value;
+
+  let result = value;
+  for (const match of matches) {
+    const uri = match[1]!.trim();
+    const resolved = await resolver(uri, auth);
+    result = result.replace(match[0], resolved);
+  }
+  return result;
+}
+
+/**
+ * Recursively resolve {{secret-uri}} templates in an object.
+ * Walks all string values at any depth.
+ */
+async function resolveTemplates<T>(
+  obj: T,
+  resolver: SecretResolver,
+  auth?: { token?: string },
+): Promise<T> {
+  if (typeof obj === 'string') {
+    // Handle {{secret-uri}} templates
+    if (hasTemplates(obj)) {
+      return (await resolveTemplateString(obj, resolver, auth)) as T;
+    }
+    // Handle raw secret URIs (backward compat)
+    if (isSecretUri(obj)) {
+      return (await resolver(obj, auth)) as T;
+    }
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return (await Promise.all(
+      obj.map((item) => resolveTemplates(item, resolver, auth)),
+    )) as T;
+  }
+  if (obj !== null && typeof obj === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = await resolveTemplates(value, resolver, auth);
+    }
+    return result as T;
+  }
+  return obj;
+}
+
 // ============================================
 // Registry Discovery Types
 // ============================================
@@ -378,10 +444,10 @@ export interface RegistryConsumer {
   /** Resolve a secret URL to its value */
   resolveSecret(url: string): Promise<string>;
 
-  /** Resolve all secret URLs in a config object, returning resolved values */
+  /** Resolve {{secret-uri}} templates in a config object (recursive) */
   resolveConfig(
     config: RefConfig,
-  ): Promise<Record<string, string | number | boolean>>;
+  ): Promise<RefConfig>;
 
   /** Produce the indexed/serialized config output */
   index(): ResolvedConfig;
@@ -408,13 +474,7 @@ export async function createRegistryConsumer(
 
   // Normalize refs
   const resolvedRefs: ResolvedRef[] = (config.refs ?? []).map((entry) => {
-    const normalized = normalizeRef(entry);
-    return {
-      ref: normalized.ref,
-      name: normalized.name,
-      registry: normalized.registry ?? resolvedRegistries[0]?.url ?? "unknown",
-      config: normalized.config,
-    };
+    return normalizeRef(entry);
   });
 
   // Cache for registry configurations
@@ -526,25 +586,19 @@ export async function createRegistryConsumer(
 
       // Also collect from direct MCP/HTTPS refs
       for (const ref of resolvedRefs) {
-        if (!DIRECT_REGISTRY_TYPES.has(ref.registry)) continue;
-        const refEntry = (config.refs ?? []).find((r) => {
-          const n = normalizeRef(r);
-          return n.name === ref.name;
-        });
-        const url =
-          typeof refEntry === "object" ? refEntry?.url : undefined;
-        if (!url) continue;
+        if (!ref.scheme || !DIRECT_REGISTRY_TYPES.has(ref.scheme)) continue;
+        if (!ref.url) continue;
 
         try {
-          if (ref.registry === REGISTRY_TYPE_MCP) {
+          if (ref.scheme === REGISTRY_TYPE_MCP) {
             const mcpListings = await listFromMcpServer(
-              url,
+              ref.url,
               { token: options.token },
               fetchFn,
             );
             listings.push(...mcpListings);
-          } else if (ref.registry === REGISTRY_TYPE_HTTPS) {
-            listings.push(...listFromHttpsApi(url));
+          } else if (ref.scheme === REGISTRY_TYPE_HTTPS) {
+            listings.push(...listFromHttpsApi(ref.url));
           }
         } catch {
           // Skip unreachable direct refs during list
@@ -574,39 +628,43 @@ export async function createRegistryConsumer(
         );
       }
 
+      // Resolve config headers ({{secret-uri}} templates)
+      const configHeaders = ref.config?.headers as
+        | Record<string, string>
+        | undefined;
+      const resolvedHeaders = configHeaders
+        ? await resolveTemplates(configHeaders, resolveSecretFn, {
+            token: options.token,
+          })
+        : undefined;
+      const auth = { token: options.token, headers: resolvedHeaders };
+
       // Direct MCP ref — bypass registry, call MCP server directly
-      if (ref.registry === REGISTRY_TYPE_MCP) {
-        const refEntry = (config.refs ?? []).find((r) => {
-          const n = normalizeRef(r);
-          return n.name === ref.name;
-        });
-        const url = typeof refEntry === "object" ? refEntry?.url : undefined;
-        if (!url) {
+      if (ref.scheme === REGISTRY_TYPE_MCP) {
+        if (!ref.url) {
           throw new Error(`MCP ref "${refName}" has no url`);
         }
-        return callMcpTool(url, tool, params, { token: options.token }, fetchFn);
+        return callMcpTool(ref.url, tool, params, auth, fetchFn);
       }
 
       // Direct HTTPS ref — bypass registry, call REST API directly
-      if (ref.registry === REGISTRY_TYPE_HTTPS) {
-        const refEntry = (config.refs ?? []).find((r) => {
-          const n = normalizeRef(r);
-          return n.name === ref.name;
-        });
-        const url = typeof refEntry === "object" ? refEntry?.url : undefined;
-        if (!url) {
+      if (ref.scheme === REGISTRY_TYPE_HTTPS) {
+        if (!ref.url) {
           throw new Error(`HTTPS ref "${refName}" has no url`);
         }
-        return callHttpsTool(url, tool, params, { token: options.token }, fetchFn);
+        return callHttpsTool(ref.url, tool, params, auth, fetchFn);
       }
 
       // Standard registry ref
-      const registry = resolvedRegistries.find(
-        (r) => r.url === ref.registry || r.name === ref.registry,
-      );
+      const registryUrl = ref.sourceRegistry?.url;
+      const registry = registryUrl
+        ? resolvedRegistries.find(
+            (r) => r.url === registryUrl || r.name === registryUrl,
+          )
+        : resolvedRegistries[0]; // Default to first registry if no source specified
       if (!registry) {
         throw new Error(
-          `Registry "${ref.registry}" not found for ref "${refName}"`,
+          `Registry not found for ref "${refName}"${registryUrl ? ` (source: ${registryUrl})` : ''}`,
         );
       }
 
@@ -619,20 +677,10 @@ export async function createRegistryConsumer(
       return resolveSecretFn(url, { token: options.token });
     },
 
-    async resolveConfig(
-      config: RefConfig,
-    ): Promise<Record<string, string | number | boolean>> {
-      const resolved: Record<string, string | number | boolean> = {};
-      for (const [key, value] of Object.entries(config)) {
-        if (isSecretUrl(value)) {
-          resolved[key] = await resolveSecretFn(value as string, {
-            token: options.token,
-          });
-        } else {
-          resolved[key] = value;
-        }
-      }
-      return resolved;
+    async resolveConfig(config: RefConfig): Promise<RefConfig> {
+      return resolveTemplates(config, resolveSecretFn, {
+        token: options.token,
+      });
     },
 
     index(): ResolvedConfig {

package/src/secret-collection.ts

@@ -27,7 +27,6 @@ export interface PendingCollection {
     callerId: string;
     callerType: string;
     scopes?: string[];
-    isRoot?: boolean;
   };
   createdAt: number;
 }

package/src/server.test.ts

@@ -241,7 +241,7 @@ describe("atlas ↔ registry E2E", () => {
     const consumer = await createRegistryConsumer(
       {
         registries: [REGISTRY_URL],
-        refs: ["notion"],
+        refs: [{ ref: "notion" }],
       },
       { token: authToken },
     );
@@ -256,7 +256,7 @@ describe("atlas ↔ registry E2E", () => {
     const consumer = await createRegistryConsumer(
       {
         registries: [REGISTRY_URL],
-        refs: ["linear"],
+        refs: [{ ref: "linear" }],
       },
       { token: authToken },
     );
@@ -269,7 +269,7 @@ describe("atlas ↔ registry E2E", () => {
     const consumer = await createRegistryConsumer(
       {
         registries: [REGISTRY_URL],
-        refs: ["notion"],
+        refs: [{ ref: "notion" }],
       },
       { token: authToken },
     );

package/src/server.ts

@@ -180,7 +180,7 @@ interface JsonRpcResponse {
 
 export interface AuthConfig {
   store?: AuthStore;
-  rootKey?: string;
+  /** @deprecated Use JWT scopes instead. Will be removed in a future version. */
   tokenTtl?: number;
 }
 
@@ -189,11 +189,16 @@ export interface ResolvedAuth {
   callerId: string;
   callerType: "agent" | "user" | "system";
   scopes: string[];
-  isRoot: boolean;
   /** All JWT claims from the verified token (passthrough) */
   claims: Record<string, unknown>;
 }
 
+/** Check if auth has admin-level access (wildcard or admin scope) */
+export function hasAdminScope(auth: ResolvedAuth | null): boolean {
+  if (!auth) return false;
+  return auth.scopes.includes("*") || auth.scopes.includes("admin");
+}
+
 // ============================================
 // HTTP Helpers
 // ============================================
@@ -265,16 +270,14 @@ export function detectAuth(registry: AgentRegistry): AuthConfig {
   const authAgent = registry.get("@auth") as
     | (AgentDefinition & {
         __authStore?: AuthStore;
-        __rootKey?: string;
         __tokenTtl?: number;
       })
     | undefined;
 
-  if (!authAgent?.__authStore || !authAgent.__rootKey) return {};
+  if (!authAgent?.__authStore) return {};
 
   return {
     store: authAgent.__authStore,
-    rootKey: authAgent.__rootKey,
     tokenTtl: authAgent.__tokenTtl ?? 3600,
   };
 }
@@ -293,17 +296,6 @@ export async function resolveAuth(
   const [scheme, credential] = authHeader.split(" ", 2);
   if (scheme?.toLowerCase() !== "bearer" || !credential) return null;
 
-  // Root key check
-  if (authConfig.rootKey && credential === authConfig.rootKey) {
-    return {
-      callerId: "root",
-      callerType: "system",
-      scopes: ["*"],
-      isRoot: true,
-      claims: {},
-    };
-  }
-
   // Try ES256 verification against own signing keys
   const parts = credential.split(".");
   if (parts.length === 3 && jwksOptions?.signingKeys?.length) {
@@ -315,7 +307,6 @@ export async function resolveAuth(
             callerId: verified.sub ?? verified.name ?? "unknown",
             callerType: "agent",
             scopes: verified.scopes ?? ["*"],
-            isRoot: false,
             claims: verified as unknown as Record<string, unknown>,
           };
         }
@@ -347,7 +338,6 @@ export async function resolveAuth(
               callerId: verified.sub ?? verified.name ?? "unknown",
               callerType: isSystem ? "system" : "agent",
               scopes,
-              isRoot: isSystem,
               claims: verified as unknown as Record<string, unknown>,
             };
           }
@@ -379,7 +369,6 @@ export async function resolveAuth(
               callerId: verified.name || client.name,
               callerType: "agent",
               scopes: verified.scopes,
-              isRoot: false,
               claims: verified as unknown as Record<string, unknown>,
             };
           }
@@ -400,7 +389,6 @@ export async function resolveAuth(
     callerId: client?.name ?? token.clientId,
     callerType: "agent",
     scopes: token.scopes,
-    isRoot: false,
     claims: {},
   };
 }
@@ -412,7 +400,7 @@ export function canSeeAgent(
   const visibility = ((agent as any).visibility ??
     agent.config?.visibility ??
     "internal") as Visibility;
-  if (auth?.isRoot) return true;
+  if (hasAdminScope(auth)) return true;
   if (visibility === "public") return true;
   if (visibility === "internal" && auth) return true;
   return false;
@@ -445,10 +433,10 @@ function getVisibleTools(
     "internal") as Visibility;
   return agent.tools.filter((t) => {
     const tv = t.visibility;
-    if (auth?.isRoot) return true;
+    if (hasAdminScope(auth)) return true;
     // Tool has explicit visibility — respect it
     if (tv === "public") return true;
-    if (tv === "private") return auth?.isRoot ?? false;
+    if (tv === "private") return hasAdminScope(auth) ?? false;
     if (tv === "internal" && auth) return true;
     // No explicit tool visibility — inherit from agent
     if (!tv && agentVisibility === "public") return true;
@@ -622,10 +610,9 @@ export function createAgentServer(
           req.callerType = auth.callerType;
           if (!req.metadata) req.metadata = {};
           req.metadata.scopes = auth.scopes;
-          req.metadata.isRoot = auth.isRoot;
           if (auth.issuer) req.metadata.issuer = auth.issuer;
         }
-        if (auth?.isRoot) {
+        if (hasAdminScope(auth)) {
           req.callerType = "system";
         }
 
@@ -663,7 +650,7 @@ export function createAgentServer(
             tools: agent.tools
               .filter((t) => {
                 const tv = t.visibility ?? "internal";
-                if (auth?.isRoot) return true;
+                if (hasAdminScope(auth)) return true;
                 if (tv === "public") return true;
                 if (
                   tv === "authenticated" &&
@@ -707,7 +694,7 @@ export function createAgentServer(
         for (const agent of visible) {
           const visibleTools = agent.tools.filter((t) => {
             const tv = t.visibility ?? "internal";
-            if (auth?.isRoot) return true;
+            if (hasAdminScope(auth)) return true;
             if (tv === "public") return true;
             if (
               tv === "authenticated" &&
@@ -1053,7 +1040,6 @@ export function createAgentServer(
                 callerId: actorId,
                 callerType: (actorType as any) ?? "agent",
                 scopes: ["*"],
-                isRoot: false,
                 claims: {},
               };
             }
@@ -1281,7 +1267,7 @@ export function createAgentServer(
             tools: agent.tools
               .filter((t) => {
                 const tv = t.visibility ?? "internal";
-                if (effectiveAuth?.isRoot) return true;
+                if (hasAdminScope(effectiveAuth)) return true;
                 if (tv === "public") return true;
                 if (tv === "internal" && effectiveAuth) return true;
                 return false;
@@ -1309,6 +1295,8 @@ export function createAgentServer(
             name: agent.config?.name,
             description:
               agent.config?.description ?? agent.entrypoint?.slice(0, 200),
+            mode: agent.mode ?? 'direct',
+            ...(agent.upstream && { upstream: agent.upstream }),
             tools: getVisibleTools(agent, effectiveAuth).map((t) => ({
               name: t.name,
               description: t.description,
@@ -1334,6 +1322,8 @@ export function createAgentServer(
           name: agent.config?.name,
           description:
             agent.config?.description ?? agent.entrypoint?.slice(0, 200),
+          mode: agent.mode ?? 'direct',
+          ...(agent.upstream && { upstream: agent.upstream }),
           tools: getVisibleTools(agent, effectiveAuth).map((t) => ({
             name: t.name,
             description: t.description,
@@ -1379,7 +1369,7 @@ export function createAgentServer(
             callerId: effectiveAuth?.callerId,
             callerType: effectiveAuth?.callerType ?? "system",
             metadata: effectiveAuth
-              ? { scopes: effectiveAuth.scopes, isRoot: effectiveAuth.isRoot }
+              ? { scopes: effectiveAuth.scopes }
               : undefined,
           });
           const res = jsonResponse({ success: true, result });
@@ -1464,7 +1454,6 @@ export function createAgentServer(
               metadata: effectiveAuth
                 ? {
                     scopes: effectiveAuth.scopes,
-                    isRoot: effectiveAuth.isRoot,
                     ...(effectiveAuth.issuer
                       ? { issuer: effectiveAuth.issuer }
                       : {}),

package/src/types.ts

@@ -633,6 +633,19 @@ export interface AgentDefinition<TContext extends ToolContext = ToolContext> {
   /** Tools provided by this agent */
   tools: ToolDefinition<TContext, unknown, unknown>[];
 
+  /**
+   * Registry hosting mode:
+   * - 'direct': registry hosts and serves this agent's tools (default)
+   * - 'redirect': registry catalogs this agent but clients connect to `upstream` directly
+   */
+  mode?: 'direct' | 'redirect';
+
+  /**
+   * Upstream URL for redirect-mode agents.
+   * When mode is 'redirect', clients should connect to this URL instead of the registry.
+   */
+  upstream?: string;
+
   /**
    * Runtime hooks factory.
    * Called once to create the runtime for this agent.