@mast-ai/core 0.2.0 → 0.3.0

package/dist/tool.d.ts

@@ -45,9 +45,27 @@ export interface ToolProvider {
     /** Returns the tool registered under `name`, or `undefined` if not found or out of scope. */
     getTool(name: string): Tool | undefined;
 }
+/**
+ * Events emitted by {@link ToolRegistry} (and {@link ToolRegistryView}) when its
+ * contents change at runtime. UI components and adapters can subscribe via
+ * `addEventListener` to refresh toolbars, re-advertise capabilities, or trigger
+ * a new agent turn.
+ */
+export type ToolRegistryEventMap = {
+    /** Fired after a tool is successfully added. */
+    'tool-registered': {
+        tool: Tool;
+    };
+    /** Fired after a tool is removed. Not fired for no-op `unregister` calls. */
+    'tool-unregistered': {
+        name: string;
+    };
+};
+type ToolRegistryListener<K extends keyof ToolRegistryEventMap> = (event: ToolRegistryEventMap[K]) => void;
 /** Holds all tools available to an {@link AgentRunner} and resolves them by name during execution. */
 export declare class ToolRegistry implements ToolProvider {
     private _tools;
+    private _emitter;
     /**
      * Registers a tool. Throws if a tool with the same name is already registered.
      * Returns `this` for chaining.
@@ -61,6 +79,10 @@ export declare class ToolRegistry implements ToolProvider {
     getTools(): ToolDefinition[];
     /** Returns a live read-only view filtered to tools with `scope: 'read'`. */
     readOnly(): ToolRegistryView;
+    /** Subscribe to registry mutation events. */
+    addEventListener<K extends keyof ToolRegistryEventMap>(type: K, listener: ToolRegistryListener<K>): void;
+    /** Unsubscribe a previously registered listener. */
+    removeEventListener<K extends keyof ToolRegistryEventMap>(type: K, listener: ToolRegistryListener<K>): void;
 }
 /**
  * A live filtered projection of a {@link ToolRegistry}.
@@ -71,7 +93,18 @@ export declare class ToolRegistry implements ToolProvider {
 export declare class ToolRegistryView implements ToolProvider {
     private readonly parent;
     private readonly scope;
+    private _emitter;
+    private _scopedNames?;
     constructor(parent: ToolRegistry, scope: 'read' | 'write');
     getTools(): ToolDefinition[];
     getTool(name: string): Tool | undefined;
+    /**
+     * Subscribe to mutation events forwarded from the parent registry. Only
+     * events for tools whose `scope` matches this view's scope are delivered.
+     */
+    addEventListener<K extends keyof ToolRegistryEventMap>(type: K, listener: ToolRegistryListener<K>): void;
+    /** Unsubscribe a previously registered listener. */
+    removeEventListener<K extends keyof ToolRegistryEventMap>(type: K, listener: ToolRegistryListener<K>): void;
+    private ensureParentSubscription;
 }
+export {};

package/dist/tool.js

@@ -1,8 +1,28 @@
 // Copyright 2026 Andre Cipriani Bandarra
 // SPDX-License-Identifier: Apache-2.0
+class ToolRegistryEventEmitter {
+    registered = new Set();
+    unregistered = new Set();
+    on(type, listener) {
+        this.bucket(type).add(listener);
+    }
+    off(type, listener) {
+        this.bucket(type).delete(listener);
+    }
+    emit(type, event) {
+        for (const listener of [...this.bucket(type)])
+            listener(event);
+    }
+    // The cast is contained here: each generic call resolves `K` to one of the
+    // literal keys, and the matching bucket has a compatible listener type.
+    bucket(type) {
+        return (type === 'tool-registered' ? this.registered : this.unregistered);
+    }
+}
 /** Holds all tools available to an {@link AgentRunner} and resolves them by name during execution. */
 export class ToolRegistry {
     _tools = new Map();
+    _emitter = new ToolRegistryEventEmitter();
     /**
      * Registers a tool. Throws if a tool with the same name is already registered.
      * Returns `this` for chaining.
@@ -13,11 +33,14 @@ export class ToolRegistry {
             throw new Error(`Tool '${name}' is already registered.`);
         }
         this._tools.set(name, tool);
+        this._emitter.emit('tool-registered', { tool });
         return this;
     }
     /** Removes the tool registered under `name`. No-op if not found. */
     unregister(name) {
-        this._tools.delete(name);
+        if (!this._tools.delete(name))
+            return;
+        this._emitter.emit('tool-unregistered', { name });
     }
     /** Returns the tool registered under `name`, or `undefined` if not found. */
     getTool(name) {
@@ -31,6 +54,14 @@ export class ToolRegistry {
     readOnly() {
         return new ToolRegistryView(this, 'read');
     }
+    /** Subscribe to registry mutation events. */
+    addEventListener(type, listener) {
+        this._emitter.on(type, listener);
+    }
+    /** Unsubscribe a previously registered listener. */
+    removeEventListener(type, listener) {
+        this._emitter.off(type, listener);
+    }
 }
 /**
  * A live filtered projection of a {@link ToolRegistry}.
@@ -41,6 +72,8 @@ export class ToolRegistry {
 export class ToolRegistryView {
     parent;
     scope;
+    _emitter = new ToolRegistryEventEmitter();
+    _scopedNames;
     constructor(parent, scope) {
         this.parent = parent;
         this.scope = scope;
@@ -54,4 +87,38 @@ export class ToolRegistryView {
             return undefined;
         return tool.definition().scope === this.scope ? tool : undefined;
     }
+    /**
+     * Subscribe to mutation events forwarded from the parent registry. Only
+     * events for tools whose `scope` matches this view's scope are delivered.
+     */
+    addEventListener(type, listener) {
+        this.ensureParentSubscription();
+        this._emitter.on(type, listener);
+    }
+    /** Unsubscribe a previously registered listener. */
+    removeEventListener(type, listener) {
+        this._emitter.off(type, listener);
+    }
+    ensureParentSubscription() {
+        if (this._scopedNames)
+            return;
+        const scoped = new Set();
+        for (const def of this.parent.getTools()) {
+            if (def.scope === this.scope)
+                scoped.add(def.name);
+        }
+        this._scopedNames = scoped;
+        this.parent.addEventListener('tool-registered', (event) => {
+            const def = event.tool.definition();
+            if (def.scope !== this.scope)
+                return;
+            scoped.add(def.name);
+            this._emitter.emit('tool-registered', event);
+        });
+        this.parent.addEventListener('tool-unregistered', (event) => {
+            if (!scoped.delete(event.name))
+                return;
+            this._emitter.emit('tool-unregistered', event);
+        });
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mast-ai/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",