@slashfi/agents-sdk 0.16.0 → 0.18.0

package/dist/oidc-signin.js

@@ -0,0 +1,138 @@
+/**
+ * OIDC Sign-In Provider
+ *
+ * Implements the full OIDC authorization code flow for user sign-in.
+ * The server acts as an OIDC Relying Party — users authenticate with
+ * an external Identity Provider and receive a server-signed JWT.
+ *
+ * Flow:
+ *   GET  /signin/authorize  → 302 redirect to IdP
+ *   GET  /signin/callback   → exchange code → fetch userinfo → sign JWT → return
+ */
+import { signJwtES256 } from "./jwt.js";
+export function createOIDCSignIn(config) {
+    let discoveryCache = null;
+    const pendingFlows = new Map();
+    async function fetchDiscovery() {
+        if (discoveryCache)
+            return discoveryCache;
+        const url = `${config.issuer}/.well-known/openid-configuration`;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`OIDC discovery failed: ${res.status}`);
+        discoveryCache = (await res.json());
+        return discoveryCache;
+    }
+    function generateState() {
+        const bytes = crypto.getRandomValues(new Uint8Array(24));
+        return Buffer.from(bytes).toString("base64url");
+    }
+    return {
+        async handleRequest(req, { baseUrl, signingKey, issuerUrl }) {
+            const url = new URL(req.url);
+            // ── GET /signin/authorize → redirect to IdP ──
+            if (url.pathname === "/signin/authorize" && req.method === "GET") {
+                const redirectUri = url.searchParams.get("redirect_uri") ?? "";
+                if (!redirectUri) {
+                    return Response.json({
+                        error: "invalid_request",
+                        error_description: "Missing redirect_uri",
+                    }, { status: 400 });
+                }
+                const discovery = await fetchDiscovery();
+                const state = generateState();
+                const nonce = generateState();
+                pendingFlows.set(state, {
+                    redirectUri,
+                    nonce,
+                    createdAt: Date.now(),
+                });
+                // Clean up stale flows (> 10 min)
+                const now = Date.now();
+                for (const [k, v] of pendingFlows) {
+                    if (now - v.createdAt > 600_000)
+                        pendingFlows.delete(k);
+                }
+                const scopes = config.scopes ?? ["openid", "email", "profile"];
+                const callbackUrl = `${baseUrl}/signin/callback`;
+                const authUrl = new URL(discovery.authorization_endpoint);
+                authUrl.searchParams.set("response_type", "code");
+                authUrl.searchParams.set("client_id", config.clientId);
+                authUrl.searchParams.set("redirect_uri", callbackUrl);
+                authUrl.searchParams.set("scope", scopes.join(" "));
+                authUrl.searchParams.set("state", state);
+                authUrl.searchParams.set("nonce", nonce);
+                return Response.redirect(authUrl.toString(), 302);
+            }
+            // ── GET /signin/callback → exchange code → userinfo → JWT ──
+            if (url.pathname === "/signin/callback" && req.method === "GET") {
+                const code = url.searchParams.get("code");
+                const state = url.searchParams.get("state");
+                const error = url.searchParams.get("error");
+                if (error) {
+                    return Response.json({
+                        error,
+                        error_description: url.searchParams.get("error_description") ?? "",
+                    }, { status: 400 });
+                }
+                if (!code || !state) {
+                    return Response.json({
+                        error: "invalid_request",
+                        error_description: "Missing code or state",
+                    }, { status: 400 });
+                }
+                const flow = pendingFlows.get(state);
+                if (!flow) {
+                    return Response.json({
+                        error: "invalid_state",
+                        error_description: "Unknown or expired state",
+                    }, { status: 400 });
+                }
+                pendingFlows.delete(state);
+                const discovery = await fetchDiscovery();
+                const callbackUrl = `${baseUrl}/signin/callback`;
+                // Exchange code for tokens
+                const tokenRes = await fetch(discovery.token_endpoint, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                    body: new URLSearchParams({
+                        grant_type: "authorization_code",
+                        code,
+                        redirect_uri: callbackUrl,
+                        client_id: config.clientId,
+                        client_secret: config.clientSecret,
+                    }),
+                });
+                if (!tokenRes.ok) {
+                    const text = await tokenRes.text();
+                    return Response.json({ error: "token_exchange_failed", error_description: text }, { status: 502 });
+                }
+                const tokens = (await tokenRes.json());
+                // Fetch userinfo
+                const userinfoRes = await fetch(discovery.userinfo_endpoint, {
+                    headers: { Authorization: `Bearer ${tokens.access_token}` },
+                });
+                if (!userinfoRes.ok) {
+                    return Response.json({
+                        error: "userinfo_failed",
+                        error_description: `Status ${userinfoRes.status}`,
+                    }, { status: 502 });
+                }
+                const userinfo = (await userinfoRes.json());
+                // Sign server JWT with user's identity
+                const jwt = await signJwtES256({
+                    sub: userinfo.sub ?? "unknown",
+                    name: userinfo.name ?? "unknown",
+                    scopes: ["*"],
+                    iss: issuerUrl,
+                }, signingKey.privateKey, signingKey.kid, issuerUrl, "1h");
+                // Redirect back to the caller with the JWT
+                const sep = flow.redirectUri.includes("?") ? "&" : "?";
+                return Response.redirect(`${flow.redirectUri}${sep}token=${jwt}`, 302);
+            }
+            // Not a signin route
+            return null;
+        },
+    };
+}
+//# sourceMappingURL=oidc-signin.js.map

package/dist/oidc-signin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc-signin.js","sourceRoot":"","sources":["../src/oidc-signin.ts"],"names":[],"mappings":"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"}

package/dist/registry-consumer.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Registry Consumer — Connects to registries and resolves refs.
+ *
+ * The consumer reads a `ConsumerConfig`, discovers registries via
+ * `/.well-known/configuration`, resolves refs to agent definitions,
+ * and provides a unified interface for calling tools across all connected agents.
+ *
+ * @example
+ * ```typescript
+ * import { createRegistryConsumer, defineConfig } from '@slashfi/agents-sdk';
+ *
+ * const config = defineConfig({
+ *   registries: ['https://registry.slash.com'],
+ *   refs: ['notion', { ref: 'postgres', as: 'prod-db', config: { url: '...' } }],
+ * });
+ *
+ * const consumer = await createRegistryConsumer(config);
+ *
+ * // List all available agents across registries
+ * const available = await consumer.list();
+ *
+ * // List configured refs
+ * const refs = consumer.refs();
+ *
+ * // Call a tool on a ref
+ * const result = await consumer.call('notion', 'search', { query: 'meeting notes' });
+ *
+ * // Resolve secrets in config values
+ * const dbUrl = await consumer.resolveSecret('https://twin.slash.com/secrets/crdb-url');
+ * ```
+ */
+import type { ConsumerConfig, RefConfig, ResolvedConfig, ResolvedRef, ResolvedRegistry } from "./define-config.js";
+/** Registry well-known configuration (from /.well-known/configuration) */
+export interface RegistryConfiguration {
+    issuer: string;
+    jwks_uri?: string;
+    token_endpoint?: string;
+    agents_endpoint?: string;
+    call_endpoint?: string;
+    supported_grant_types?: string[];
+    /** @deprecated Use agents_endpoint + GET /list instead */
+    agents?: string[];
+}
+/** An agent definition as listed by a registry */
+export interface AgentListing {
+    /** Agent path (e.g., '@notion') */
+    path: string;
+    /** Description */
+    description?: string;
+    /** Publisher (registry name) */
+    publisher: string;
+    /** Tools available */
+    tools?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    /** Whether it requires auth */
+    requiresAuth?: boolean;
+    /** Integration config if applicable */
+    integration?: {
+        provider: string;
+        displayName: string;
+        category?: string;
+    };
+}
+export type SecretResolver = (uri: string, auth?: {
+    token?: string;
+}) => Promise<string>;
+export interface RegistryConsumerOptions {
+    /** Override the secret resolver (default: HTTP GET + JWT) */
+    resolveSecret?: SecretResolver;
+    /** Bearer token for authenticated registries */
+    token?: string;
+    /** Custom fetch implementation */
+    fetch?: typeof globalThis.fetch;
+}
+export interface RegistryConsumer {
+    /** List all available agents across all connected registries */
+    list(): Promise<AgentListing[]>;
+    /** List configured refs (from the consumer's config) */
+    refs(): ResolvedRef[];
+    /** Get the resolved registries */
+    registries(): ResolvedRegistry[];
+    /** Call a tool on a configured ref */
+    call(refName: string, tool: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Discover a registry's configuration */
+    discover(registryUrl: string): Promise<RegistryConfiguration>;
+    /** Resolve a secret URL to its value */
+    resolveSecret(url: string): Promise<string>;
+    /** Resolve all secret URLs in a config object, returning resolved values */
+    resolveConfig(config: RefConfig): Promise<Record<string, string | number | boolean>>;
+    /** Produce the indexed/serialized config output */
+    index(): ResolvedConfig;
+    /** Diff: what's available vs what's configured */
+    available(): Promise<AgentListing[]>;
+}
+/**
+ * Create a registry consumer from a config.
+ *
+ * The consumer connects to registries, discovers available agents,
+ * and provides a unified interface for calling tools.
+ */
+export declare function createRegistryConsumer(config: ConsumerConfig, options?: RegistryConsumerOptions): Promise<RegistryConsumer>;
+//# sourceMappingURL=registry-consumer.d.ts.map

package/dist/registry-consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-consumer.d.ts","sourceRoot":"","sources":["../src/registry-consumer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,cAAc,EACd,WAAW,EACX,gBAAgB,EACjB,MAAM,oBAAoB,CAAC;AAW5B,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,+BAA+B;IAC/B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,uCAAuC;IACvC,WAAW,CAAC,EAAE;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AASD,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KACtB,OAAO,CAAC,MAAM,CAAC,CAAC;AAoDrB,MAAM,WAAW,uBAAuB;IACtC,6DAA6D;IAC7D,aAAa,CAAC,EAAE,cAAc,CAAC;IAE/B,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,kCAAkC;IAClC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAMD,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAEhC,wDAAwD;IACxD,IAAI,IAAI,WAAW,EAAE,CAAC;IAEtB,kCAAkC;IAClC,UAAU,IAAI,gBAAgB,EAAE,CAAC;IAEjC,sCAAsC;IACtC,IAAI,CACF,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAE9D,wCAAwC;IACxC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C,4EAA4E;IAC5E,aAAa,CACX,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAEtD,mDAAmD;IACnD,KAAK,IAAI,cAAc,CAAC;IAExB,kDAAkD;IAClD,SAAS,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAiM3B"}

package/dist/registry-consumer.js

@@ -0,0 +1,230 @@
+/**
+ * Registry Consumer — Connects to registries and resolves refs.
+ *
+ * The consumer reads a `ConsumerConfig`, discovers registries via
+ * `/.well-known/configuration`, resolves refs to agent definitions,
+ * and provides a unified interface for calling tools across all connected agents.
+ *
+ * @example
+ * ```typescript
+ * import { createRegistryConsumer, defineConfig } from '@slashfi/agents-sdk';
+ *
+ * const config = defineConfig({
+ *   registries: ['https://registry.slash.com'],
+ *   refs: ['notion', { ref: 'postgres', as: 'prod-db', config: { url: '...' } }],
+ * });
+ *
+ * const consumer = await createRegistryConsumer(config);
+ *
+ * // List all available agents across registries
+ * const available = await consumer.list();
+ *
+ * // List configured refs
+ * const refs = consumer.refs();
+ *
+ * // Call a tool on a ref
+ * const result = await consumer.call('notion', 'search', { query: 'meeting notes' });
+ *
+ * // Resolve secrets in config values
+ * const dbUrl = await consumer.resolveSecret('https://twin.slash.com/secrets/crdb-url');
+ * ```
+ */
+import { isSecretUrl, normalizeRef, normalizeRegistry, } from "./define-config.js";
+// ============================================
+// Secret Resolver
+// ============================================
+/** Resolves secret URLs to their values */
+import { readFile } from "node:fs/promises";
+/**
+ * Default secret resolver — dispatches on URI scheme:
+ *   file://  → read from filesystem
+ *   env://   → read from environment variable
+ *   https:// → HTTP GET with optional bearer token
+ *   http://  → HTTP GET (dev only)
+ */
+async function defaultSecretResolver(uri, auth) {
+    const parsed = new URL(uri);
+    switch (parsed.protocol) {
+        case "file:": {
+            const filePath = parsed.pathname;
+            return (await readFile(filePath, "utf-8")).trim();
+        }
+        case "env:": {
+            // env://VAR_NAME or env:///VAR_NAME
+            const varName = parsed.hostname || parsed.pathname.replace(/^\//, "");
+            const value = process.env[varName];
+            if (!value) {
+                throw new Error(`Environment variable not set: ${varName}`);
+            }
+            return value;
+        }
+        case "https:":
+        case "http:": {
+            const headers = {};
+            if (auth?.token) {
+                headers.Authorization = `Bearer ${auth.token}`;
+            }
+            const res = await fetch(uri, { headers });
+            if (!res.ok) {
+                throw new Error(`Failed to resolve secret ${uri}: ${res.status} ${res.statusText}`);
+            }
+            return res.text();
+        }
+        default:
+            throw new Error(`Unsupported secret URI scheme: ${parsed.protocol}`);
+    }
+}
+/**
+ * Create a registry consumer from a config.
+ *
+ * The consumer connects to registries, discovers available agents,
+ * and provides a unified interface for calling tools.
+ */
+export async function createRegistryConsumer(config, options = {}) {
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    const resolveSecretFn = options.resolveSecret ?? defaultSecretResolver;
+    // Normalize registries
+    const resolvedRegistries = (config.registries ?? []).map(normalizeRegistry);
+    // Normalize refs
+    const resolvedRefs = (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,
+        };
+    });
+    // Cache for registry configurations
+    const discoveryCache = new Map();
+    // Discover a registry
+    async function discover(registryUrl) {
+        const cached = discoveryCache.get(registryUrl);
+        if (cached)
+            return cached;
+        const url = `${registryUrl.replace(/\/$/, "")}/.well-known/configuration`;
+        const res = await fetchFn(url);
+        if (!res.ok) {
+            throw new Error(`Failed to discover registry ${registryUrl}: ${res.status}`);
+        }
+        const configuration = (await res.json());
+        discoveryCache.set(registryUrl, configuration);
+        return configuration;
+    }
+    // List agents from a single registry
+    async function listFromRegistry(registry) {
+        const configuration = await discover(registry.url);
+        const listUrl = configuration.agents_endpoint ??
+            `${registry.url.replace(/\/$/, "")}/list`;
+        const headers = {};
+        if (registry.auth.type === "bearer" && "token" in registry.auth) {
+            headers.Authorization = `Bearer ${registry.auth.token}`;
+        }
+        else if (options.token) {
+            headers.Authorization = `Bearer ${options.token}`;
+        }
+        const res = await fetchFn(listUrl, { headers });
+        if (!res.ok) {
+            throw new Error(`Failed to list agents from ${registry.url}: ${res.status}`);
+        }
+        const agents = (await res.json());
+        return agents.map((agent) => ({
+            ...agent,
+            publisher: registry.publisher,
+        }));
+    }
+    // Call a tool via a registry
+    async function callTool(registry, agentPath, tool, params) {
+        const configuration = await discover(registry.url);
+        const callUrl = configuration.call_endpoint ?? `${registry.url.replace(/\/$/, "")}/call`;
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (registry.auth.type === "bearer" && "token" in registry.auth) {
+            headers.Authorization = `Bearer ${registry.auth.token}`;
+        }
+        else if (options.token) {
+            headers.Authorization = `Bearer ${options.token}`;
+        }
+        const res = await fetchFn(callUrl, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ path: agentPath, tool, params }),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "unknown error");
+            throw new Error(`Tool call failed (${registry.url}/${agentPath}/${tool}): ${res.status} ${text}`);
+        }
+        return res.json();
+    }
+    // Build the consumer
+    const consumer = {
+        async list() {
+            const results = await Promise.allSettled(resolvedRegistries.map(listFromRegistry));
+            return results.flatMap((r) => (r.status === "fulfilled" ? r.value : []));
+        },
+        refs() {
+            return resolvedRefs;
+        },
+        registries() {
+            return resolvedRegistries;
+        },
+        async call(refName, tool, params = {}) {
+            const ref = resolvedRefs.find((r) => r.name === refName);
+            if (!ref) {
+                throw new Error(`Ref "${refName}" not found in config. Available: ${resolvedRefs.map((r) => r.name).join(", ")}`);
+            }
+            const registry = resolvedRegistries.find((r) => r.url === ref.registry);
+            if (!registry) {
+                throw new Error(`Registry "${ref.registry}" not found for ref "${refName}"`);
+            }
+            return callTool(registry, ref.ref, tool, params);
+        },
+        discover,
+        async resolveSecret(url) {
+            return resolveSecretFn(url, { token: options.token });
+        },
+        async resolveConfig(config) {
+            const resolved = {};
+            for (const [key, value] of Object.entries(config)) {
+                if (isSecretUrl(value)) {
+                    resolved[key] = await resolveSecretFn(value, {
+                        token: options.token,
+                    });
+                }
+                else {
+                    resolved[key] = value;
+                }
+            }
+            return resolved;
+        },
+        index() {
+            return {
+                resolvedAt: new Date().toISOString(),
+                sourceHash: simpleHash(JSON.stringify(config)),
+                registries: resolvedRegistries,
+                refs: resolvedRefs,
+                meta: config.meta,
+            };
+        },
+        async available() {
+            const all = await consumer.list();
+            const configuredRefs = new Set(resolvedRefs.map((r) => r.ref));
+            return all.filter((a) => !configuredRefs.has(a.path));
+        },
+    };
+    return consumer;
+}
+// ============================================
+// Utilities
+// ============================================
+/** Simple hash for cache invalidation (not cryptographic) */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash + char) | 0;
+    }
+    return Math.abs(hash).toString(36);
+}
+//# sourceMappingURL=registry-consumer.js.map

package/dist/registry-consumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-consumer.js","sourceRoot":"","sources":["../src/registry-consumer.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -3,6 +3,7 @@
  *
  * Manages registered agents and handles callAgent requests.
  */
+import type { AgentEvent, EventCallback, EventType } from "./events.js";
 import type { AgentDefinition, CallAgentLoadRequest, CallAgentLoadResponse, CallAgentRequest, CallAgentResponse, Visibility } from "./types.js";
 /**
  * Middleware hooks for registry lifecycle actions.
@@ -43,6 +44,10 @@ export interface AgentRegistry {
     listPaths(): string[];
     /** Call an agent (execute action) */
     call(request: CallAgentRequest): Promise<CallAgentResponse>;
+    /** Register an event listener (global scope — fires for all agents) */
+    on<T extends EventType>(eventType: T, callback: EventCallback<T>): void;
+    /** Emit an event to all listeners. Used by the runtime to push lifecycle events. */
+    emit(event: AgentEvent): Promise<void>;
 }
 /**
  * Create an agent registry.

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAEV,eAAe,EAMf,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EAIjB,UAAU,EACX,MAAM,YAAY,CAAC;AAapB;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,CACL,SAAS,EAAE,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,qBAAqB,CAAC,EACpG,GAAG,EAAE;QAAE,KAAK,EAAE,eAAe,CAAC;QAAC,OAAO,EAAE,oBAAoB,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,KACpF,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,mEAAmE;IACnE,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,iCAAiC;IACjC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IAEvC,2BAA2B;IAC3B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IAE/C,+BAA+B;IAC/B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE3B,iCAAiC;IACjC,IAAI,IAAI,eAAe,EAAE,CAAC;IAE1B,sCAAsC;IACtC,SAAS,IAAI,MAAM,EAAE,CAAC;IAEtB,qCAAqC;IACrC,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC7D;AAMD;;;;;;;;;;;;;;;GAeG;AACH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,OAAO,YAAY,EAAE,WAAW,KAAK,OAAO,YAAY,EAAE,WAAW,CAAC;AAE7G,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,aAAa,CA8Zf"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EACV,UAAU,EACV,aAAa,EACb,SAAS,EACV,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAEV,eAAe,EAMf,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EAIjB,UAAU,EACX,MAAM,YAAY,CAAC;AAapB;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,CACL,SAAS,EAAE,CACT,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,oBAAoB,KAC1B,OAAO,CAAC,qBAAqB,CAAC,EACnC,GAAG,EAAE;QACH,KAAK,EAAE,eAAe,CAAC;QACvB,OAAO,EAAE,oBAAoB,CAAC;QAC9B,QAAQ,EAAE,aAAa,CAAC;KACzB,KACE,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,mEAAmE;IACnE,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,iCAAiC;IACjC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IAEvC,2BAA2B;IAC3B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IAE/C,+BAA+B;IAC/B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE3B,iCAAiC;IACjC,IAAI,IAAI,eAAe,EAAE,CAAC;IAE1B,sCAAsC;IACtC,SAAS,IAAI,MAAM,EAAE,CAAC;IAEtB,qCAAqC;IACrC,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE5D,uEAAuE;IACvE,EAAE,CAAC,CAAC,SAAS,SAAS,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAExE,oFAAoF;IACpF,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAMD;;;;;;;;;;;;;;;GAeG;AACH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,OAAO,EAAE,OAAO,YAAY,EAAE,WAAW,KACtC,OAAO,YAAY,EAAE,WAAW,CAAC;AAEtC,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,aAAa,CAmff"}

package/dist/registry.js

@@ -4,6 +4,7 @@
  * Manages registered agents and handles callAgent requests.
  */
 import { dirname, resolve } from "node:path";
+import { createEventBus } from "./events.js";
 /** Default supported actions if not specified */
 const DEFAULT_SUPPORTED_ACTIONS = [
     "execute_tool",
@@ -13,6 +14,7 @@ const DEFAULT_SUPPORTED_ACTIONS = [
 export function createAgentRegistry(options = {}) {
     const { defaultVisibility = "internal" } = options;
     const agents = new Map();
+    const eventBus = createEventBus();
     /**
      * Check if agent supports the requested action.
      */
@@ -167,6 +169,26 @@ export function createAgentRegistry(options = {}) {
     const registry = {
         register(agent) {
             agents.set(agent.path, agent);
+            // Collect agent-level listeners into the bus
+            if (agent._listeners) {
+                for (const entry of agent._listeners) {
+                    eventBus._onScoped(entry.eventType, entry.callback, {
+                        agentPath: agent.path,
+                        toolName: entry.toolScope,
+                    });
+                }
+            }
+            // Collect tool-level listeners into the bus
+            for (const tool of agent.tools) {
+                if (tool._listeners) {
+                    for (const entry of tool._listeners) {
+                        eventBus._onScoped(entry.eventType, entry.callback, {
+                            agentPath: agent.path,
+                            toolName: tool.name,
+                        });
+                    }
+                }
+            }
         },
         get(path) {
             return agents.get(path);
@@ -180,6 +202,12 @@ export function createAgentRegistry(options = {}) {
         listPaths() {
             return Array.from(agents.keys());
         },
+        on(eventType, callback) {
+            eventBus.on(eventType, callback);
+        },
+        async emit(event) {
+            await eventBus.emit(event);
+        },
         async call(request) {
             const agent = agents.get(request.path);
             if (!agent) {
@@ -266,16 +294,56 @@ export function createAgentRegistry(options = {}) {
                                 error: `Tool ${request.tool} has no execute function`,
                             };
                         }
-                        const result = await tool.execute(request.params, ctx);
+                        // Emit tool/call before execution
+                        const startMs = Date.now();
+                        await eventBus.emit({
+                            type: "tool/call",
+                            agentPath: agent.path,
+                            tool: request.tool,
+                            params: request.params,
+                            timestamp: startMs,
+                        });
+                        let result;
+                        try {
+                            result = await tool.execute(request.params, ctx);
+                        }
+                        catch (err) {
+                            // Emit tool/error on failure
+                            await eventBus.emit({
+                                type: "tool/error",
+                                agentPath: agent.path,
+                                tool: request.tool,
+                                params: request.params,
+                                error: err,
+                                durationMs: Date.now() - startMs,
+                                timestamp: Date.now(),
+                            }).catch(() => { }); // don't let emit error mask tool error
+                            return {
+                                success: false,
+                                error: err instanceof Error ? err.message : String(err),
+                                code: "TOOL_EXECUTION_ERROR",
+                            };
+                        }
+                        // Emit tool/result after success
+                        await eventBus.emit({
+                            type: "tool/result",
+                            agentPath: agent.path,
+                            tool: request.tool,
+                            params: request.params,
+                            result,
+                            durationMs: Date.now() - startMs,
+                            timestamp: Date.now(),
+                        });
                         return {
                             success: true,
                             result,
                         };
                     }
-                    catch (err) {
+                    catch (outerErr) {
+                        // Catch-all for unexpected errors (e.g., emit failures)
                         return {
                             success: false,
-                            error: err instanceof Error ? err.message : String(err),
+                            error: outerErr instanceof Error ? outerErr.message : String(outerErr),
                             code: "TOOL_EXECUTION_ERROR",
                         };
                     }
@@ -297,7 +365,11 @@ export function createAgentRegistry(options = {}) {
                 }
                 case "load": {
                     if (options.middleware?.load) {
-                        return options.middleware.load(defaultLoad, { agent, request, registry });
+                        return options.middleware.load(defaultLoad, {
+                            agent,
+                            request,
+                            registry,
+                        });
                     }
                     return defaultLoad(agent, request);
                 }