@toolpack-sdk/agents 2.0.0-alpha.1

package/dist/registry/index.d.cts

@@ -0,0 +1,159 @@
+/**
+ * Types for the toolpack-agents registry.
+ * Used for discovering and publishing community agents.
+ */
+/**
+ * Metadata that should be included in a package.json to identify
+ * a package as a toolpack agent.
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "toolpack-agent-fintech-research",
+ *   "version": "1.0.0",
+ *   "keywords": ["toolpack-agent"],
+ *   "toolpack": {
+ *     "agent": true,
+ *     "category": "research",
+ *     "description": "Research agent focused on fintech news and regulatory updates",
+ *     "tags": ["fintech", "research", "news"],
+ *     "author": "John Doe",
+ *     "repository": "https://github.com/johndoe/toolpack-agent-fintech-research",
+ *     "homepage": "https://example.com/fintech-agent"
+ *   }
+ * }
+ * ```
+ */
+interface ToolpackAgentMetadata {
+    /** Must be true to be recognized as an agent */
+    agent: true;
+    /** Category for grouping (e.g., 'research', 'coding', 'data', 'custom') */
+    category?: string;
+    /** Short description of what the agent does */
+    description?: string;
+    /** Tags for searchability */
+    tags?: string[];
+    /** Author name or organization */
+    author?: string;
+    /** Repository URL */
+    repository?: string;
+    /** Homepage URL */
+    homepage?: string;
+}
+/**
+ * An agent entry returned from the registry search.
+ */
+interface RegistryAgent {
+    /** Package name */
+    name: string;
+    /** Package version */
+    version: string;
+    /** Package description from npm */
+    description?: string;
+    /** Toolpack-specific metadata */
+    toolpack?: ToolpackAgentMetadata;
+    /** NPM keywords */
+    keywords?: string[];
+    /** Package author */
+    author?: string | {
+        name?: string;
+        email?: string;
+    };
+    /** NPM registry date */
+    date?: string;
+    /** NPM registry links */
+    links?: {
+        npm?: string;
+        homepage?: string;
+        repository?: string;
+        bugs?: string;
+    };
+    /** NPM registry publisher info */
+    publisher?: {
+        username?: string;
+        email?: string;
+    };
+    /** NPM maintainers */
+    maintainers?: Array<{
+        username?: string;
+        email?: string;
+    }>;
+}
+/**
+ * Options for searching the registry.
+ */
+interface SearchRegistryOptions {
+    /** Search query string */
+    keyword?: string;
+    /** Filter by category */
+    category?: string;
+    /** Filter by tag */
+    tag?: string;
+    /** Maximum number of results (default: 20) */
+    limit?: number;
+    /** Offset for pagination (default: 0) */
+    offset?: number;
+    /** NPM registry URL (default: https://registry.npmjs.org) */
+    registryUrl?: string;
+}
+/**
+ * Result from a registry search.
+ */
+interface SearchRegistryResult {
+    /** List of matching agents */
+    agents: RegistryAgent[];
+    /** Total number of results (may be approximate) */
+    total: number;
+    /** Offset used for this query */
+    offset: number;
+    /** Limit used for this query */
+    limit: number;
+    /** Whether more results are available */
+    hasMore: boolean;
+}
+
+/**
+ * Searches the NPM registry for toolpack agents.
+ *
+ * Queries packages with the "toolpack-agent" keyword and filters
+ * by optional category, tags, and search keywords.
+ *
+ * @example
+ * ```ts
+ * import { searchRegistry } from '@toolpack-sdk/agents/registry';
+ *
+ * // Search all agents
+ * const results = await searchRegistry();
+ *
+ * // Search by keyword
+ * const results = await searchRegistry({ keyword: 'fintech' });
+ *
+ * // Filter by category
+ * const results = await searchRegistry({ category: 'research' });
+ *
+ * // Combined search
+ * const results = await searchRegistry({
+ *   keyword: 'stock',
+ *   category: 'research',
+ *   limit: 10,
+ * });
+ *
+ * // Display results
+ * for (const agent of results.agents) {
+ *   console.log(`${agent.name}: ${agent.toolpack?.description || agent.description}`);
+ *   console.log(`  Install: npm install ${agent.name}`);
+ * }
+ * ```
+ *
+ * @param options Search options
+ * @returns Search results with agents and pagination info
+ */
+declare function searchRegistry(options?: SearchRegistryOptions): Promise<SearchRegistryResult>;
+/**
+ * Error thrown when registry operations fail.
+ */
+declare class RegistryError extends Error {
+    constructor(message: string);
+}
+
+export { type RegistryAgent, RegistryError, type SearchRegistryOptions, type SearchRegistryResult, type ToolpackAgentMetadata, searchRegistry };

package/dist/registry/index.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Types for the toolpack-agents registry.
+ * Used for discovering and publishing community agents.
+ */
+/**
+ * Metadata that should be included in a package.json to identify
+ * a package as a toolpack agent.
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "toolpack-agent-fintech-research",
+ *   "version": "1.0.0",
+ *   "keywords": ["toolpack-agent"],
+ *   "toolpack": {
+ *     "agent": true,
+ *     "category": "research",
+ *     "description": "Research agent focused on fintech news and regulatory updates",
+ *     "tags": ["fintech", "research", "news"],
+ *     "author": "John Doe",
+ *     "repository": "https://github.com/johndoe/toolpack-agent-fintech-research",
+ *     "homepage": "https://example.com/fintech-agent"
+ *   }
+ * }
+ * ```
+ */
+interface ToolpackAgentMetadata {
+    /** Must be true to be recognized as an agent */
+    agent: true;
+    /** Category for grouping (e.g., 'research', 'coding', 'data', 'custom') */
+    category?: string;
+    /** Short description of what the agent does */
+    description?: string;
+    /** Tags for searchability */
+    tags?: string[];
+    /** Author name or organization */
+    author?: string;
+    /** Repository URL */
+    repository?: string;
+    /** Homepage URL */
+    homepage?: string;
+}
+/**
+ * An agent entry returned from the registry search.
+ */
+interface RegistryAgent {
+    /** Package name */
+    name: string;
+    /** Package version */
+    version: string;
+    /** Package description from npm */
+    description?: string;
+    /** Toolpack-specific metadata */
+    toolpack?: ToolpackAgentMetadata;
+    /** NPM keywords */
+    keywords?: string[];
+    /** Package author */
+    author?: string | {
+        name?: string;
+        email?: string;
+    };
+    /** NPM registry date */
+    date?: string;
+    /** NPM registry links */
+    links?: {
+        npm?: string;
+        homepage?: string;
+        repository?: string;
+        bugs?: string;
+    };
+    /** NPM registry publisher info */
+    publisher?: {
+        username?: string;
+        email?: string;
+    };
+    /** NPM maintainers */
+    maintainers?: Array<{
+        username?: string;
+        email?: string;
+    }>;
+}
+/**
+ * Options for searching the registry.
+ */
+interface SearchRegistryOptions {
+    /** Search query string */
+    keyword?: string;
+    /** Filter by category */
+    category?: string;
+    /** Filter by tag */
+    tag?: string;
+    /** Maximum number of results (default: 20) */
+    limit?: number;
+    /** Offset for pagination (default: 0) */
+    offset?: number;
+    /** NPM registry URL (default: https://registry.npmjs.org) */
+    registryUrl?: string;
+}
+/**
+ * Result from a registry search.
+ */
+interface SearchRegistryResult {
+    /** List of matching agents */
+    agents: RegistryAgent[];
+    /** Total number of results (may be approximate) */
+    total: number;
+    /** Offset used for this query */
+    offset: number;
+    /** Limit used for this query */
+    limit: number;
+    /** Whether more results are available */
+    hasMore: boolean;
+}
+
+/**
+ * Searches the NPM registry for toolpack agents.
+ *
+ * Queries packages with the "toolpack-agent" keyword and filters
+ * by optional category, tags, and search keywords.
+ *
+ * @example
+ * ```ts
+ * import { searchRegistry } from '@toolpack-sdk/agents/registry';
+ *
+ * // Search all agents
+ * const results = await searchRegistry();
+ *
+ * // Search by keyword
+ * const results = await searchRegistry({ keyword: 'fintech' });
+ *
+ * // Filter by category
+ * const results = await searchRegistry({ category: 'research' });
+ *
+ * // Combined search
+ * const results = await searchRegistry({
+ *   keyword: 'stock',
+ *   category: 'research',
+ *   limit: 10,
+ * });
+ *
+ * // Display results
+ * for (const agent of results.agents) {
+ *   console.log(`${agent.name}: ${agent.toolpack?.description || agent.description}`);
+ *   console.log(`  Install: npm install ${agent.name}`);
+ * }
+ * ```
+ *
+ * @param options Search options
+ * @returns Search results with agents and pagination info
+ */
+declare function searchRegistry(options?: SearchRegistryOptions): Promise<SearchRegistryResult>;
+/**
+ * Error thrown when registry operations fail.
+ */
+declare class RegistryError extends Error {
+    constructor(message: string);
+}
+
+export { type RegistryAgent, RegistryError, type SearchRegistryOptions, type SearchRegistryResult, type ToolpackAgentMetadata, searchRegistry };

package/dist/registry/index.js

@@ -0,0 +1 @@
+async function w(g={}){let{keyword:e,category:c,tag:p,limit:u=20,offset:o=0,registryUrl:m="https://registry.npmjs.org"}=g,d=["toolpack-agent"];e&&d.push(e),p&&d.push(p);let l=d.join(" "),y=new URL("/-/v1/search",m);y.searchParams.set("text",l),y.searchParams.set("size",String(Math.min(u+o,250))),y.searchParams.set("from",String(0));try{let r=await fetch(y.toString(),{headers:{Accept:"application/json"}});if(!r.ok)throw new a(`NPM registry search failed: ${r.status} ${r.statusText}`);let s=(await r.json()).objects.map(n=>{let t=n.package,i=R(t);return{name:t.name,version:t.version,description:t.description,toolpack:i,keywords:t.keywords,author:t.author,date:t.date,links:t.links,publisher:t.publisher,maintainers:t.maintainers}});if(c&&(s=s.filter(n=>n.toolpack?.category?.toLowerCase()===c.toLowerCase())),p){let n=p.toLowerCase();s=s.filter(t=>t.toolpack?.tags?.some(i=>i.toLowerCase()===n)||t.keywords?.some(i=>i.toLowerCase()===n))}s=s.filter(n=>n.toolpack?.agent===!0);let h=s.length;return s=s.slice(o,o+u),{agents:s,total:h,offset:o,limit:u,hasMore:h>o+u}}catch(r){throw r instanceof a?r:new a(`Failed to search registry: ${r instanceof Error?r.message:String(r)}`)}}function R(g){let e=g.toolpack;if(!(!e||e.agent!==!0))return{agent:!0,category:typeof e.category=="string"?e.category:void 0,description:typeof e.description=="string"?e.description:void 0,tags:Array.isArray(e.tags)?e.tags.filter(c=>typeof c=="string"):void 0,author:typeof e.author=="string"?e.author:void 0,repository:typeof e.repository=="string"?e.repository:void 0,homepage:typeof e.homepage=="string"?e.homepage:void 0}}var a=class extends Error{constructor(e){super(e),this.name="RegistryError"}};export{a as RegistryError,w as searchRegistry};

package/dist/testing/index.cjs

@@ -0,0 +1,3 @@
+"use strict";var C=Object.create;var l=Object.defineProperty;var _=Object.getOwnPropertyDescriptor;var b=Object.getOwnPropertyNames;var x=Object.getPrototypeOf,R=Object.prototype.hasOwnProperty;var T=(o,e)=>{for(var t in e)l(o,t,{get:e[t],enumerable:!0})},v=(o,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of b(e))!R.call(o,i)&&i!==t&&l(o,i,{get:()=>e[i],enumerable:!(r=_(e,i))||r.enumerable});return o};var h=(o,e,t)=>(t=o!=null?C(x(o)):{},v(e||!o||!o.__esModule?l(t,"default",{value:o,enumerable:!0}):t,o)),N=o=>v(l({},"__esModule",{value:!0}),o);var $={};T($,{MockChannel:()=>p,MockKnowledge:()=>d,captureEvents:()=>M,createMockKnowledge:()=>k,createMockKnowledgeSync:()=>f,createMockToolpackSequence:()=>A,createMockToolpackSimple:()=>E,createTestAgent:()=>w,registerEventMatchers:()=>y});module.exports=N($);var p=class{name="mock-channel";isTriggerChannel=!1;_handler;_outputs=[];_inputs=[];_listening=!1;get outputs(){return[...this._outputs]}get lastOutput(){return this._outputs[this._outputs.length-1]}get inputs(){return[...this._inputs]}get lastInput(){return this._inputs[this._inputs.length-1]}get receivedCount(){return this._inputs.length}get sentCount(){return this._outputs.length}get isListening(){return this._listening}onMessage(e){this._handler=e}listen(){this._listening=!0}stop(){this._listening=!1}async send(e){this._outputs.push(e)}normalize(e){let t=e;return{intent:t.intent,message:t.message,data:t.data,context:t.context||{},conversationId:t.conversationId||"test-conversation-1"}}async receive(e){if(!this._handler)throw new Error("MockChannel: no message handler registered. Call onMessage() first or ensure channel is registered with AgentRegistry.");let t=this.normalize(e);this._inputs.push(t),await this._handler(t)}async receiveMessage(e,t="test-conversation-1",r,i){await this.receive({message:e,conversationId:t,intent:r,context:i})}clear(){this._inputs=[],this._outputs=[]}assertOutputContains(e){if(!this._outputs.some(r=>r.output.includes(e)))throw new Error(`MockChannel: no output containing "${e}" found. Outputs: ${JSON.stringify(this._outputs.map(r=>r.output))}`)}assertLastOutput(e){let t=this.lastOutput;if(!t)throw new Error(`MockChannel: no output sent. Expected: "${e}"`);if(t.output!==e)throw new Error(`MockChannel: last output mismatch.
+Expected: "${e}"
+Actual: "${t.output}"`)}};async function k(o={}){let{Knowledge:e}=await import("@toolpack-sdk/knowledge"),{MemoryProvider:t}=await import("@toolpack-sdk/knowledge"),r=o.dimensions??384,i={dimensions:r,async embed(s){let a=[],u=0;for(let c=0;c<s.length;c++)u=(u+s.charCodeAt(c))%1e3;for(let c=0;c<r;c++){let g=Math.sin(u*(c+1))*.5+.5;a.push(g)}return a},async embedBatch(s){return Promise.all(s.map(a=>this.embed(a)))}},n=new t;if(await n.validateDimensions(r),o.initialChunks&&o.initialChunks.length>0){let s=[];for(let a of o.initialChunks){let u=await i.embed(a.content);s.push({id:`mock-${Date.now()}-${Math.random().toString(36).slice(2)}`,content:a.content,metadata:a.metadata||{},vector:u})}await n.add(s)}return e.create({provider:n,embedder:i,sources:[],description:o.description??"Mock knowledge base for testing",reSync:!1})}function f(o={}){let e=o.dimensions??384,t=[],r=i=>{let n=[],s=0;for(let a=0;a<i.length;a++)s=(s+i.charCodeAt(a))%1e3;for(let a=0;a<e;a++){let u=Math.sin(s*(a+1))*.5+.5;n.push(u)}return n};if(o.initialChunks)for(let i of o.initialChunks)t.push({id:`mock-${Date.now()}-${Math.random().toString(36).slice(2)}`,content:i.content,metadata:i.metadata||{},vector:r(i.content)});return new d(t,r,o.description)}var d=class{chunks;generateVector;_description;constructor(e=[],t,r="Mock knowledge base"){this.chunks=[...e],this.generateVector=t,this._description=r}async query(e,t){let r=t?.limit??10,i=t?.filter,n=e.toLowerCase().split(/\s+/);return this.chunks.filter(a=>{if(i){for(let[u,c]of Object.entries(i))if(a.metadata[u]!==c)return!1}return!0}).map(a=>{let u=a.content.toLowerCase(),c=0;for(let g of n)u.includes(g)&&(c+=.3,new RegExp(`\\b${g}\\b`).test(u)&&(c+=.2));return c=Math.min(c,1),{chunk:{id:a.id,content:a.content,metadata:t?.includeMetadata===!1?{}:a.metadata,vector:t?.includeVectors?a.vector:void 0},score:c,distance:1-c}}).filter(a=>a.score>0).sort((a,u)=>u.score-a.score).slice(0,r)}async add(e,t){let r=`mock-${Date.now()}-${Math.random().toString(36).slice(2)}`;return this.chunks.push({id:r,content:e,metadata:t||{},vector:this.generateVector(e)}),r}getAllChunks(){return[...this.chunks]}clear(){this.chunks=[]}toTool(){return{name:"knowledge_search",displayName:"Knowledge Search",description:this._description,category:"search",cacheable:!1,parameters:{type:"object",properties:{query:{type:"string",description:"Search query to find relevant information"},limit:{type:"number",description:"Maximum number of results to return (default: 10)"},threshold:{type:"number",description:"Minimum similarity threshold 0-1 (default: 0.7)"},filter:{type:"object",description:"Optional metadata filters"}},required:["query"]},execute:async e=>(await this.query(e.query,{limit:e.limit,filter:e.filter})).map(r=>({content:r.chunk.content,score:r.score,metadata:r.chunk.metadata}))}}};function w(o,e={}){let t=[...e.mockResponses??[]],r=e.defaultResponse??"Mock AI response",i=O(t,r,e.provider,e.model),n=new o({toolpack:i}),s=new p;return s.onMessage(async u=>{n._triggeringChannel=s.name,n._conversationId=u.conversationId,n._isTriggerChannel=!1;let c=await n.invokeAgent(u);await s.send({output:c.output,metadata:c.metadata})}),s.listen(),{agent:n,channel:s,toolpack:i,addMockResponse:u=>{t.push(u)}}}function O(o,e,t="openai",r){return{generate:async(i,n)=>{let u=i.messages.filter(c=>c.role==="user").pop()?.content??"";for(let c of o)if(typeof c.trigger=="string"){if(u.toLowerCase().includes(c.trigger.toLowerCase()))return{content:c.response,usage:c.usage??{prompt_tokens:10,completion_tokens:5,total_tokens:15}}}else if(c.trigger instanceof RegExp&&c.trigger.test(u))return{content:c.response,usage:c.usage??{prompt_tokens:10,completion_tokens:5,total_tokens:15}};return{content:e,usage:{prompt_tokens:10,completion_tokens:5,total_tokens:15}}},setMode:()=>{},registerMode:()=>{},setProvider:()=>{},setModel:()=>{},get provider(){return t},get model(){return r||"gpt-4"}}}function E(o="Mock AI response"){return{generate:async()=>({content:o,usage:{prompt_tokens:10,completion_tokens:5,total_tokens:15}}),setMode:()=>{},registerMode:()=>{},setProvider:()=>{},setModel:()=>{}}}function A(o){let e=0;return{generate:async()=>{let t=o[e]??"No more mock responses";return e++,{content:t,usage:{prompt_tokens:10,completion_tokens:5,total_tokens:15}}},setMode:()=>{},registerMode:()=>{},setProvider:()=>{},setModel:()=>{}}}function M(o){let e=[],t=[],r=n=>s=>{e.push({name:n,data:s,timestamp:Date.now()})},i=["agent:start","agent:complete","agent:error"];for(let n of i){let s=r(n);o.on(n,s),t.push({event:n,handler:s})}return{get events(){return[...e]},get count(){return e.length},clear(){e.length=0},stop(){for(let{event:n,handler:s}of t)o.off(n,s);t.length=0},hasEvent(n){return e.some(s=>s.name===n)},getEvents(n){return e.filter(s=>s.name===n)},getFirstEvent(n){return e.find(s=>s.name===n)},getLastEvent(n){let s=e.filter(a=>a.name===n);return s[s.length-1]},assertEvent(n){if(!this.hasEvent(n)){let s=e.map(a=>a.name).join(", ")||"(none)";throw new Error(`captureEvents: expected event "${n}" was not captured. Captured events: ${s}`)}},assertNoEvent(n){if(this.hasEvent(n)){let s=e.filter(a=>a.name===n).length;throw new Error(`captureEvents: unexpected event "${n}" was captured ${s} time(s)`)}}}}function y(o){o.extend({toContainEvent(...e){let t=e[0],r=e[1],i=t.hasEvent(r);return{message:()=>i?`expected events to NOT contain "${r}"`:`expected events to contain "${r}". Captured events: ${t.events.map(n=>n.name).join(", ")||"(none)"}`,pass:i}},toContainEventTimes(...e){let t=e[0],r=e[1],i=e[2],n=t.getEvents(r).length,s=n===i;return{message:()=>s?`expected event "${r}" to NOT be captured ${i} time(s), but it was`:`expected event "${r}" to be captured ${i} time(s), but it was captured ${n} time(s)`,pass:s}}})}0&&(module.exports={MockChannel,MockKnowledge,captureEvents,createMockKnowledge,createMockKnowledgeSync,createMockToolpackSequence,createMockToolpackSimple,createTestAgent,registerEventMatchers});