@slashfi/agents-sdk 0.6.0 → 0.8.0

package/src/agent-definitions/secrets.ts

@@ -20,13 +20,42 @@ import type { AgentDefinition, ToolContext, ToolDefinition } from "../types.js";
  * Pluggable secret storage backend.
  * Stores encrypted values, resolves refs.
  */
+/**
+ * Scope for multi-tenant secret isolation.
+ * When provided, secrets are partitioned by tenant/instance.
+ */
+export interface SecretScope {
+  tenantId: string;
+  instanceKey?: string;
+}
+
 export interface SecretStore {
   /** Store a secret. Returns the secret ID (without prefix). */
-  store(value: string, ownerId: string): Promise<string>;
+  store(value: string, ownerId: string, scope?: SecretScope): Promise<string>;
+
   /** Resolve a secret ID to its decrypted value. */
-  resolve(id: string, ownerId: string): Promise<string | null>;
+  resolve(id: string, ownerId: string, scope?: SecretScope): Promise<string | null>;
+
   /** Delete a secret. */
-  delete(id: string, ownerId: string): Promise<boolean>;
+  delete(id: string, ownerId: string, scope?: SecretScope): Promise<boolean>;
+
+  /**
+   * Store multiple secrets in a single operation.
+   * Returns an array of secret IDs in the same order as the input values.
+   */
+  storeBatch?(values: string[], ownerId: string, scope?: SecretScope): Promise<string[]>;
+
+  /**
+   * Associate a secret with an entity (e.g., a provider config, a connection).
+   * Enables lookup of secrets by entity rather than by ID.
+   */
+  associate?(secretId: string, entityType: string, entityId: string, scope?: SecretScope): Promise<void>;
+
+  /**
+   * Resolve secrets associated with an entity.
+   * Returns all secret IDs linked to the given entity.
+   */
+  resolveByEntity?(entityType: string, entityId: string, scope?: SecretScope): Promise<string[]>;
 }
 
 // ============================================
@@ -61,27 +90,53 @@ function randomSecretId(): string {
 
 export function createInMemorySecretStore(encryptionKey: string): SecretStore {
   const secrets = new Map<string, { encrypted: string; ownerId: string }>();
+  const associations = new Map<string, string[]>(); // "entityType:entityId" -> secretIds
 
   return {
-    async store(value, ownerId) {
+    async store(value, ownerId, _scope?) {
       const id = randomSecretId();
       const encrypted = await encryptSecret(value, encryptionKey);
       secrets.set(id, { encrypted, ownerId });
       return id;
     },
 
-    async resolve(id, ownerId) {
+    async resolve(id, ownerId, _scope?) {
       const entry = secrets.get(id);
       if (!entry || entry.ownerId !== ownerId) return null;
       return decryptSecret(entry.encrypted, encryptionKey);
     },
 
-    async delete(id, ownerId) {
+    async delete(id, ownerId, _scope?) {
       const entry = secrets.get(id);
       if (!entry || entry.ownerId !== ownerId) return false;
       secrets.delete(id);
       return true;
     },
+
+    async storeBatch(values, ownerId, _scope?) {
+      const ids: string[] = [];
+      for (const value of values) {
+        const id = randomSecretId();
+        const encrypted = await encryptSecret(value, encryptionKey);
+        secrets.set(id, { encrypted, ownerId });
+        ids.push(id);
+      }
+      return ids;
+    },
+
+    async associate(secretId, entityType, entityId, _scope?) {
+      const key = `${entityType}:${entityId}`;
+      const existing = associations.get(key) ?? [];
+      if (!existing.includes(secretId)) {
+        existing.push(secretId);
+        associations.set(key, existing);
+      }
+    },
+
+    async resolveByEntity(entityType, entityId, _scope?) {
+      const key = `${entityType}:${entityId}`;
+      return associations.get(key) ?? [];
+    },
   };
 }
 

package/src/index.ts

@@ -125,6 +125,7 @@ export {
   processSecretParams,
 } from "./agent-definitions/secrets.js";
 export type {
+  SecretScope,
   SecretStore,
   SecretsAgentOptions,
 } from "./agent-definitions/secrets.js";
@@ -157,13 +158,16 @@ export type {
   IntegrationCallInput,
   RestCallInput,
   GraphqlCallInput,
-  AgentRegistryCallInput,
   UserConnection,
   ClientAuthMethod,
   TokenContentType,
   TokenExchangeResult,
 } from "./agent-definitions/integrations.js";
 
+
+// Remote Registry
+export { createRemoteRegistryAgent } from "./agent-definitions/remote-registry.js";
+export type { RemoteRegistryAgentOptions } from "./agent-definitions/remote-registry.js";
 // Users
 export {
   createUsersAgent,

package/src/registry.ts

@@ -290,6 +290,12 @@ export function createAgentRegistry(
           };
 
           try {
+            if (!tool.execute) {
+              return {
+                success: false,
+                error: `Tool ${request.tool} has no execute function`,
+              } as CallAgentErrorResponse;
+            }
             const result = await tool.execute(request.params, ctx);
             return {
               success: true,

package/src/server.ts

@@ -14,8 +14,10 @@
  * - list_agents  → List registered agents and their tools
  *
  * Additional endpoints:
- * - POST /oauth/token → OAuth2 client_credentials (when @auth registered)
- * - GET /health       → Health check
+ * - POST /oauth/token             → OAuth2 client_credentials (when @auth registered)
+ * - GET  /oauth/callback          → Unified OAuth callback (provider from state)
+ * - GET  /integrations/callback/* → Legacy OAuth callback (provider from URL path)
+ * - GET  /health                  → Health check
  *
  * Auth Integration:
  * When an `@auth` agent is registered, the server automatically:
@@ -702,13 +704,8 @@ export function createAgentServer(
       }
 
 
-      // GET /integrations/callback/:provider - OAuth callback
-      if (path.startsWith("/integrations/callback/") && req.method === "GET") {
-        const provider = path.split("/integrations/callback/")[1]?.split("?")[0];
-        if (!provider) {
-          return addCors(jsonResponse({ error: "Missing provider" }, 400));
-        }
-
+      // ---- Shared OAuth callback handler ----
+      async function handleIntegrationOAuthCallback(provider: string, req: Request): Promise<Response> {
         const url = new URL(req.url);
         const code = url.searchParams.get("code");
         const state = url.searchParams.get("state");
@@ -726,7 +723,6 @@ export function createAgentServer(
           return addCors(jsonResponse({ error: "Missing authorization code" }, 400));
         }
 
-        // Call handle_oauth_callback tool on @integrations
         try {
           await registry.call({
             action: "execute_tool",
@@ -741,13 +737,19 @@ export function createAgentServer(
             },
           } as any);
 
-          // Parse redirect URL from state
+          // Parse redirect URL from state (base64-encoded JSON)
           let redirectUrl = "/";
           if (state) {
             try {
-              const parsed = JSON.parse(state);
+              const parsed = JSON.parse(atob(state));
               if (parsed.redirectUrl) redirectUrl = parsed.redirectUrl;
-            } catch {}
+            } catch {
+              // Fallback: try raw JSON for backward compat
+              try {
+                const parsed = JSON.parse(state);
+                if (parsed.redirectUrl) redirectUrl = parsed.redirectUrl;
+              } catch {}
+            }
           }
 
           const sep = redirectUrl.includes("?") ? "&" : "?";
@@ -760,6 +762,38 @@ export function createAgentServer(
         }
       }
 
+      // GET /oauth/callback - Unified OAuth callback (provider from state param)
+      if (path === "/oauth/callback" && req.method === "GET") {
+        const url = new URL(req.url);
+        const state = url.searchParams.get("state");
+        let provider: string | undefined;
+        if (state) {
+          try {
+            const parsed = JSON.parse(atob(state));
+            provider = parsed.providerId;
+          } catch {
+            // Fallback: try raw JSON for backward compat
+            try {
+              const parsed = JSON.parse(state);
+              provider = parsed.providerId;
+            } catch {}
+          }
+        }
+        if (!provider) {
+          return addCors(jsonResponse({ error: "Missing provider in state param" }, 400));
+        }
+        return handleIntegrationOAuthCallback(provider, req);
+      }
+
+      // GET /integrations/callback/:provider - Legacy OAuth callback (provider from URL path)
+      if (path.startsWith("/integrations/callback/") && req.method === "GET") {
+        const provider = path.split("/integrations/callback/")[1]?.split("?")[0];
+        if (!provider) {
+          return addCors(jsonResponse({ error: "Missing provider" }, 400));
+        }
+        return handleIntegrationOAuthCallback(provider, req);
+      }
+
 
       // GET /secrets/form/:token - Serve hosted secrets form
       if (path.startsWith("/secrets/form/") && req.method === "GET") {

package/src/types.ts

@@ -421,8 +421,21 @@ export interface ToolDefinition<
 
   /**
    * Execute the tool with validated input.
+   * Optional — some registries load tool implementations dynamically.
    */
-  execute: (input: TInput, ctx: TContext) => Promise<TOutput>;
+  execute?: (input: TInput, ctx: TContext) => Promise<TOutput>;
+
+  /**
+   * Path to the tool source file (e.g., '/agents/@clock/timer.tool.ts').
+   * Used for tool discovery and prompt composition.
+   */
+  path?: string;
+
+  /**
+   * Full documentation content for system prompt composition.
+   * When set, rendered directly into the agent's system prompt.
+   */
+  doc?: string;
 }
 
 /**
@@ -473,6 +486,12 @@ export interface AgentDefinition<TContext extends ToolContext = ToolContext> {
    * by @integrations via standard methods (setup, list, connect, get, update).
    */
   integrationMethods?: IntegrationMethods;
+
+  /**
+   * Lazy loader for lifecycle listeners.
+   * Called once to load runtime hooks exported from the agent's entrypoint module.
+   */
+  loadListeners?: () => Promise<unknown>;
 }
 
 // ============================================