@strands-agents/sdk 0.6.0 → 1.0.0-rc.0

package/dist/src/plugins/__tests__/plugin.test.js

@@ -0,0 +1,114 @@
+import { describe, it, expect } from 'vitest';
+import { BeforeInvocationEvent } from '../../hooks/events.js';
+import { ToolRegistry } from '../../registry/tool-registry.js';
+import { createRandomTool } from '../../__fixtures__/tool-helpers.js';
+/**
+ * Concrete implementation of Plugin for testing purposes.
+ */
+class TestPlugin {
+    callbacks = [];
+    get name() {
+        return 'test-plugin';
+    }
+    initAgent(agent) {
+        agent.addHook(BeforeInvocationEvent, () => {
+            // No-op for testing
+        });
+    }
+}
+/**
+ * Plugin with custom name for testing.
+ */
+class CustomNamePlugin {
+    _name;
+    constructor(name) {
+        this._name = name;
+    }
+    get name() {
+        return this._name;
+    }
+    initAgent(_agent) { }
+}
+/**
+ * Plugin with initAgent implementation for testing.
+ */
+class InitializablePlugin {
+    initialized = false;
+    get name() {
+        return 'initializable-plugin';
+    }
+    initAgent(_agent) {
+        this.initialized = true;
+    }
+}
+describe('Plugin', () => {
+    describe('name', () => {
+        it('returns the plugin name', () => {
+            const plugin = new TestPlugin();
+            expect(plugin.name).toBe('test-plugin');
+        });
+        it('supports custom names via constructor', () => {
+            const plugin = new CustomNamePlugin('my-custom-plugin');
+            expect(plugin.name).toBe('my-custom-plugin');
+        });
+    });
+    describe('initAgent', () => {
+        it('registers callbacks via agent.addHook', () => {
+            const plugin = new TestPlugin();
+            const callbacks = [];
+            const mockAgent = {
+                addHook: (eventType, callback) => {
+                    callbacks.push({
+                        eventType: eventType,
+                        callback: callback,
+                    });
+                    return () => { };
+                },
+                toolRegistry: new ToolRegistry(),
+            };
+            plugin.initAgent(mockAgent);
+            expect(callbacks).toHaveLength(1);
+            expect(callbacks[0]?.eventType).toBe(BeforeInvocationEvent);
+        });
+        it('has a no-op default when not overridden', () => {
+            const plugin = new CustomNamePlugin('test');
+            const mockAgent = {
+                addHook: () => () => { },
+                toolRegistry: new ToolRegistry(),
+            };
+            // Should not throw and return undefined
+            const result = plugin.initAgent(mockAgent);
+            expect(result).toBeUndefined();
+        });
+        it('can be implemented for custom initialization', () => {
+            const plugin = new InitializablePlugin();
+            const mockAgent = {
+                addHook: () => () => { },
+                toolRegistry: new ToolRegistry(),
+            };
+            expect(plugin.initialized).toBe(false);
+            plugin.initAgent(mockAgent);
+            expect(plugin.initialized).toBe(true);
+        });
+    });
+    describe('getTools', () => {
+        it('is optional — plugins without getTools are valid', () => {
+            const plugin = new TestPlugin();
+            expect(plugin.getTools).toBeUndefined();
+        });
+        it('can be implemented to provide tools', () => {
+            const mockTool = createRandomTool();
+            class ToolPlugin {
+                get name() {
+                    return 'tool-plugin';
+                }
+                initAgent(_agent) { }
+                getTools() {
+                    return [mockTool];
+                }
+            }
+            expect(new ToolPlugin().getTools()).toStrictEqual([mockTool]);
+        });
+    });
+});
+//# sourceMappingURL=plugin.test.js.map

package/dist/src/plugins/__tests__/plugin.test.js.map

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

package/dist/src/plugins/__tests__/registry.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=registry.test.d.ts.map

package/dist/src/plugins/__tests__/registry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.test.d.ts","sourceRoot":"","sources":["../../../../src/plugins/__tests__/registry.test.ts"],"names":[],"mappings":""}

package/dist/src/plugins/__tests__/registry.test.js

@@ -0,0 +1,147 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { PluginRegistry } from '../registry.js';
+import { BeforeInvocationEvent } from '../../hooks/events.js';
+import { createMockAgent } from '../../__fixtures__/agent-helpers.js';
+import { createRandomTool } from '../../__fixtures__/tool-helpers.js';
+/**
+ * Test plugin implementation.
+ */
+class TestPlugin {
+    hookRegistered = false;
+    _name;
+    constructor(name = 'test-plugin') {
+        this._name = name;
+    }
+    get name() {
+        return this._name;
+    }
+    initAgent(agent) {
+        agent.addHook(BeforeInvocationEvent, () => {
+            this.hookRegistered = true;
+        });
+    }
+}
+/**
+ * Plugin with initAgent for testing initialization.
+ */
+class InitializableTestPlugin {
+    _name;
+    initialized = false;
+    constructor(_name = 'initializable-plugin') {
+        this._name = _name;
+    }
+    get name() {
+        return this._name;
+    }
+    initAgent(_agent) {
+        this.initialized = true;
+    }
+}
+/**
+ * Plugin that provides tools.
+ */
+class ToolProviderPlugin {
+    _name;
+    _tools;
+    constructor(_name, _tools) {
+        this._name = _name;
+        this._tools = _tools;
+    }
+    get name() {
+        return this._name;
+    }
+    initAgent(_agent) { }
+    getTools() {
+        return this._tools;
+    }
+}
+describe('PluginRegistry', () => {
+    let registry;
+    let mockAgent;
+    let registeredHooks;
+    beforeEach(() => {
+        registeredHooks = [];
+        mockAgent = createMockAgent({
+            extra: {
+                addHook: (eventType, callback) => {
+                    registeredHooks.push({
+                        eventType: eventType,
+                        callback: callback,
+                    });
+                    return () => { };
+                },
+            },
+        });
+    });
+    describe('initialize', () => {
+        it('initializes a plugin and calls initAgent', async () => {
+            const plugin = new InitializableTestPlugin();
+            registry = new PluginRegistry([plugin]);
+            await registry.initialize(mockAgent);
+            expect(plugin.initialized).toBe(true);
+        });
+        it('registers hooks via agent.addHook', async () => {
+            const plugin = new TestPlugin();
+            registry = new PluginRegistry([plugin]);
+            await registry.initialize(mockAgent);
+            expect(registeredHooks).toHaveLength(1);
+            expect(registeredHooks[0]?.eventType).toBe(BeforeInvocationEvent);
+        });
+        it('throws error when plugins have duplicate names', async () => {
+            const plugin1 = new TestPlugin('duplicate-name');
+            const plugin2 = new TestPlugin('duplicate-name');
+            registry = new PluginRegistry([plugin1, plugin2]);
+            await expect(registry.initialize(mockAgent)).rejects.toThrow('plugin_name=<duplicate-name> | plugin already registered');
+        });
+        it('initializes multiple plugins with different names', async () => {
+            const plugin1 = new TestPlugin('plugin-1');
+            const plugin2 = new TestPlugin('plugin-2');
+            registry = new PluginRegistry([plugin1, plugin2]);
+            await registry.initialize(mockAgent);
+            expect(registeredHooks).toHaveLength(2);
+        });
+        it('auto-registers tools from plugin.getTools()', async () => {
+            const mockTool = createRandomTool('mock-tool');
+            const plugin = new ToolProviderPlugin('tool-provider', [mockTool]);
+            registry = new PluginRegistry([plugin]);
+            await registry.initialize(mockAgent);
+            expect(mockAgent.toolRegistry.get(mockTool.name)).toBe(mockTool);
+        });
+        it('handles async initAgent', async () => {
+            class AsyncPlugin {
+                initialized = false;
+                get name() {
+                    return 'async-plugin';
+                }
+                async initAgent(_agent) {
+                    await vi.waitFor(() => Promise.resolve());
+                    this.initialized = true;
+                }
+            }
+            const plugin = new AsyncPlugin();
+            registry = new PluginRegistry([plugin]);
+            await registry.initialize(mockAgent);
+            expect(plugin.initialized).toBe(true);
+        });
+        it('is idempotent — calling initialize twice only runs plugins once', async () => {
+            const plugin = new InitializableTestPlugin();
+            registry = new PluginRegistry([plugin]);
+            await registry.initialize(mockAgent);
+            plugin.initialized = false; // reset to detect a second call
+            await registry.initialize(mockAgent);
+            expect(plugin.initialized).toBe(false);
+        });
+    });
+    describe('hook invocation', () => {
+        it('hooks are invoked when callbacks are called', async () => {
+            const plugin = new TestPlugin();
+            registry = new PluginRegistry([plugin]);
+            await registry.initialize(mockAgent);
+            const callback = registeredHooks[0]?.callback;
+            const mockAgentData = {};
+            callback?.(new BeforeInvocationEvent({ agent: mockAgentData }));
+            expect(plugin.hookRegistered).toBe(true);
+        });
+    });
+});
+//# sourceMappingURL=registry.test.js.map

package/dist/src/plugins/__tests__/registry.test.js.map

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

package/dist/src/plugins/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Plugin system for extending agent functionality.
+ *
+ * This module provides the Plugin base class for extending agent behavior
+ * through hook callbacks and tool registration.
+ *
+ * @example
+ * ```typescript
+ * import { Plugin, BeforeInvocationEvent } from '@strands-agents/sdk'
+ *
+ * class MyPlugin extends Plugin {
+ *   get name(): string {
+ *     return 'my-plugin'
+ *   }
+ *
+ *   override initAgent(agent: LocalAgent): void {
+ *     agent.addHook(BeforeInvocationEvent, (event) => {
+ *       console.log('Before invocation')
+ *     })
+ *   }
+ * }
+ *
+ * const agent = new Agent({
+ *   model,
+ *   plugins: [new MyPlugin()],
+ * })
+ * ```
+ */
+export type { Plugin } from './plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/plugins/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA"}

package/dist/src/plugins/index.js

@@ -0,0 +1,30 @@
+/**
+ * Plugin system for extending agent functionality.
+ *
+ * This module provides the Plugin base class for extending agent behavior
+ * through hook callbacks and tool registration.
+ *
+ * @example
+ * ```typescript
+ * import { Plugin, BeforeInvocationEvent } from '@strands-agents/sdk'
+ *
+ * class MyPlugin extends Plugin {
+ *   get name(): string {
+ *     return 'my-plugin'
+ *   }
+ *
+ *   override initAgent(agent: LocalAgent): void {
+ *     agent.addHook(BeforeInvocationEvent, (event) => {
+ *       console.log('Before invocation')
+ *     })
+ *   }
+ * }
+ *
+ * const agent = new Agent({
+ *   model,
+ *   plugins: [new MyPlugin()],
+ * })
+ * ```
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/src/plugins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/plugins/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}

package/dist/src/plugins/plugin.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Plugin interface for extending agent functionality.
+ *
+ * This module defines the Plugin interface, which provides a composable way to
+ * add behavior changes to agents through hook registration and custom initialization.
+ */
+import type { Tool } from '../tools/tool.js';
+import type { LocalAgent } from '../types/agent.js';
+/**
+ * Interface for objects that extend agent functionality.
+ *
+ * Plugins provide a composable way to add behavior changes to agents by registering
+ * hook callbacks in their `initAgent` method. Each plugin must have a unique name
+ * for identification, logging, and duplicate prevention.
+ *
+ * @example
+ * ```typescript
+ * class LoggingPlugin implements Plugin {
+ *   get name(): string {
+ *     return 'logging-plugin'
+ *   }
+ *
+ *   initAgent(agent: LocalAgent): void {
+ *     agent.addHook(BeforeInvocationEvent, (event) => {
+ *       console.log('Agent invocation started')
+ *     })
+ *   }
+ * }
+ *
+ * const agent = new Agent({
+ *   model,
+ *   plugins: [new LoggingPlugin()],
+ * })
+ * ```
+ *
+ * @example With tools
+ * ```typescript
+ * class MyToolPlugin implements Plugin {
+ *   get name(): string {
+ *     return 'my-tool-plugin'
+ *   }
+ *
+ *   getTools(): Tool[] {
+ *     return [myTool]
+ *   }
+ * }
+ * ```
+ */
+export interface Plugin {
+    /**
+     * A stable string identifier for the plugin.
+     * Used for logging, duplicate detection, and plugin management.
+     *
+     * For strands-vended plugins, names should be prefixed with `strands:`.
+     */
+    readonly name: string;
+    /**
+     * Initialize the plugin with the agent instance.
+     *
+     * Implement this method to register hooks and perform custom initialization.
+     * Tool registration from {@link getTools} is handled automatically by the PluginRegistry.
+     *
+     * @param agent - The agent instance this plugin is being attached to
+     */
+    initAgent(agent: LocalAgent): void | Promise<void>;
+    /**
+     * Returns tools provided by this plugin for auto-registration.
+     * Implement to provide plugin-specific tools.
+     *
+     * @returns Array of tools to register with the agent
+     */
+    getTools?(): Tool[];
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/src/plugins/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,WAAW,MAAM;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAElD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAA;CACpB"}

package/dist/src/plugins/plugin.js

@@ -0,0 +1,8 @@
+/**
+ * Plugin interface for extending agent functionality.
+ *
+ * This module defines the Plugin interface, which provides a composable way to
+ * add behavior changes to agents through hook registration and custom initialization.
+ */
+export {};
+//# sourceMappingURL=plugin.js.map

package/dist/src/plugins/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../../src/plugins/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/src/plugins/registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Plugin registry for managing plugins attached to an agent.
+ */
+import type { Plugin } from './plugin.js';
+import type { LocalAgent } from '../types/agent.js';
+/**
+ * Registry for managing plugins attached to an agent.
+ *
+ * Holds pending plugins and initializes them on first use.
+ * Handles duplicate detection, tool registration, and calls each plugin's initAgent method.
+ */
+export declare class PluginRegistry {
+    private readonly _plugins;
+    private readonly _pending;
+    constructor(plugins?: Plugin[]);
+    /**
+     * Initialize all pending plugins with the agent.
+     * Safe to call multiple times — only runs once per pending batch.
+     *
+     * @param agent - The agent instance to initialize plugins with
+     */
+    initialize(agent: LocalAgent): Promise<void>;
+    private _addAndInit;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/plugins/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/plugins/registry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;gBAEvB,OAAO,GAAE,MAAM,EAAO;IAKlC;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;YAOpC,WAAW;CAa1B"}

package/dist/src/plugins/registry.js

@@ -0,0 +1,41 @@
+/**
+ * Plugin registry for managing plugins attached to an agent.
+ */
+/**
+ * Registry for managing plugins attached to an agent.
+ *
+ * Holds pending plugins and initializes them on first use.
+ * Handles duplicate detection, tool registration, and calls each plugin's initAgent method.
+ */
+export class PluginRegistry {
+    _plugins;
+    _pending;
+    constructor(plugins = []) {
+        this._plugins = new Map();
+        this._pending = [...plugins];
+    }
+    /**
+     * Initialize all pending plugins with the agent.
+     * Safe to call multiple times — only runs once per pending batch.
+     *
+     * @param agent - The agent instance to initialize plugins with
+     */
+    async initialize(agent) {
+        while (this._pending.length > 0) {
+            const plugin = this._pending.shift();
+            await this._addAndInit(plugin, agent);
+        }
+    }
+    async _addAndInit(plugin, agent) {
+        if (this._plugins.has(plugin.name)) {
+            throw new Error(`plugin_name=<${plugin.name}> | plugin already registered`);
+        }
+        this._plugins.set(plugin.name, plugin);
+        const tools = plugin.getTools?.() ?? [];
+        if (tools.length > 0) {
+            agent.toolRegistry.add(tools);
+        }
+        await plugin.initAgent(agent);
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/plugins/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/plugins/registry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IACR,QAAQ,CAAqB;IAC7B,QAAQ,CAAU;IAEnC,YAAY,UAAoB,EAAE;QAChC,IAAI,CAAC,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAA;QACzB,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,OAAO,CAAC,CAAA;IAC9B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,KAAiB;QAChC,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAG,CAAA;YACrC,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;QACvC,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,MAAc,EAAE,KAAiB;QACzD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,gBAAgB,MAAM,CAAC,IAAI,+BAA+B,CAAC,CAAA;QAC7E,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QAEtC,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAA;QACvC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAC/B,CAAC;QAED,MAAM,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IAC/B,CAAC;CACF"}