@toolpack-sdk/agents 2.2.0 → 2.4.0

package/dist/{intent-classifier-agent-0JZDlhpk.d.ts → intent-classifier-agent-ACQSotfT.d.ts}

@@ -1,5 +1,5 @@
-import { B as BaseAgentOptions, A as AgentInput, a as AgentResult } from './types-TB6yypig.js';
-import { B as BaseAgent } from './base-agent-nU8pr4nu.js';
+import { B as BaseAgentOptions, A as AgentInput, a as AgentResult } from './types-C3EZvpe0.js';
+import { B as BaseAgent } from './base-agent-C4fYjHPu.js';
 import { ModeConfig } from 'toolpack-sdk';
 
 /**

package/dist/{intent-classifier-agent-DxyfJWcm.d.cts → intent-classifier-agent-CPKmOVJx.d.cts}

@@ -1,5 +1,5 @@
-import { B as BaseAgentOptions, A as AgentInput, a as AgentResult } from './types-TB6yypig.cjs';
-import { B as BaseAgent } from './base-agent-DPdK4Pnl.cjs';
+import { B as BaseAgentOptions, A as AgentInput, a as AgentResult } from './types-C3EZvpe0.cjs';
+import { B as BaseAgent } from './base-agent-Dqca3WLY.cjs';
 import { ModeConfig } from 'toolpack-sdk';
 
 /**

package/dist/interceptors/index.d.cts

@@ -1,9 +1,9 @@
-import { A as AgentInput, i as InterceptorResult, I as Interceptor, f as AgentInstance, C as ChannelInterface, c as IAgentRegistry, g as InterceptorChainConfig, a as AgentResult } from '../types-TB6yypig.cjs';
-export { h as InterceptorContext, N as NextFunction, S as SKIP_SENTINEL, j as isSkipSentinel, s as skip } from '../types-TB6yypig.cjs';
+import { A as AgentInput, k as InterceptorResult, I as Interceptor, g as AgentInstance, C as ChannelInterface, d as IAgentRegistry, i as InterceptorChainConfig, a as AgentResult } from '../types-C3EZvpe0.cjs';
+export { j as InterceptorContext, N as NextFunction, S as SKIP_SENTINEL, l as isSkipSentinel, s as skip } from '../types-C3EZvpe0.cjs';
 import { Participant, ConversationStore, ConversationScope, StoredMessage } from 'toolpack-sdk';
-import { I as IntentClassification } from '../intent-classifier-agent-DxyfJWcm.cjs';
+import { I as IntentClassification } from '../intent-classifier-agent-CPKmOVJx.cjs';
 import 'events';
-import '../base-agent-DPdK4Pnl.cjs';
+import '../base-agent-Dqca3WLY.cjs';
 import '@toolpack-sdk/knowledge';
 
 /**

package/dist/interceptors/index.d.ts

@@ -1,9 +1,9 @@
-import { A as AgentInput, i as InterceptorResult, I as Interceptor, f as AgentInstance, C as ChannelInterface, c as IAgentRegistry, g as InterceptorChainConfig, a as AgentResult } from '../types-TB6yypig.js';
-export { h as InterceptorContext, N as NextFunction, S as SKIP_SENTINEL, j as isSkipSentinel, s as skip } from '../types-TB6yypig.js';
+import { A as AgentInput, k as InterceptorResult, I as Interceptor, g as AgentInstance, C as ChannelInterface, d as IAgentRegistry, i as InterceptorChainConfig, a as AgentResult } from '../types-C3EZvpe0.js';
+export { j as InterceptorContext, N as NextFunction, S as SKIP_SENTINEL, l as isSkipSentinel, s as skip } from '../types-C3EZvpe0.js';
 import { Participant, ConversationStore, ConversationScope, StoredMessage } from 'toolpack-sdk';
-import { I as IntentClassification } from '../intent-classifier-agent-0JZDlhpk.js';
+import { I as IntentClassification } from '../intent-classifier-agent-ACQSotfT.js';
 import 'events';
-import '../base-agent-nU8pr4nu.js';
+import '../base-agent-C4fYjHPu.js';
 import '@toolpack-sdk/knowledge';
 
 /**

package/dist/testing/index.d.cts

@@ -1,8 +1,8 @@
-import { C as ChannelInterface, e as AgentOutput, A as AgentInput, B as BaseAgentOptions } from '../types-TB6yypig.cjs';
+import { C as ChannelInterface, f as AgentOutput, A as AgentInput, B as BaseAgentOptions } from '../types-C3EZvpe0.cjs';
 import { Chunk, QueryOptions, QueryResult, Knowledge } from '@toolpack-sdk/knowledge';
 import { Toolpack } from 'toolpack-sdk';
-import { B as BaseAgent } from '../base-agent-DPdK4Pnl.cjs';
-export { C as ContainsScorer, a as CustomScorer, E as EvalCase, b as EvalCaseResult, c as EvalDataset, d as EvalImprovement, e as EvalRegression, f as EvalReport, g as EvalRun, h as EvalRunner, i as EvalRunnerOptions, j as EvalScoredResult, k as EvalScoredRun, l as EvalScorer, m as EvalVerdict, n as ExactMatchScorer, L as LLMJudgeScorer, o as LLMJudgeScorerOptions, p as compareEvalRuns, q as formatEvalReport } from '../eval-report-BCGixIYd.cjs';
+import { B as BaseAgent } from '../base-agent-Dqca3WLY.cjs';
+export { C as ContainsScorer, a as CustomScorer, E as EvalCase, b as EvalCaseResult, c as EvalDataset, d as EvalImprovement, e as EvalRegression, f as EvalReport, g as EvalRun, h as EvalRunner, i as EvalRunnerOptions, j as EvalScoredResult, k as EvalScoredRun, l as EvalScorer, m as EvalVerdict, n as ExactMatchScorer, L as LLMJudgeScorer, o as LLMJudgeScorerOptions, p as compareEvalRuns, q as formatEvalReport } from '../eval-report-DV-wNcjW.cjs';
 import 'events';
 
 /**

package/dist/testing/index.d.ts

@@ -1,8 +1,8 @@
-import { C as ChannelInterface, e as AgentOutput, A as AgentInput, B as BaseAgentOptions } from '../types-TB6yypig.js';
+import { C as ChannelInterface, f as AgentOutput, A as AgentInput, B as BaseAgentOptions } from '../types-C3EZvpe0.js';
 import { Chunk, QueryOptions, QueryResult, Knowledge } from '@toolpack-sdk/knowledge';
 import { Toolpack } from 'toolpack-sdk';
-import { B as BaseAgent } from '../base-agent-nU8pr4nu.js';
-export { C as ContainsScorer, a as CustomScorer, E as EvalCase, b as EvalCaseResult, c as EvalDataset, d as EvalImprovement, e as EvalRegression, f as EvalReport, g as EvalRun, h as EvalRunner, i as EvalRunnerOptions, j as EvalScoredResult, k as EvalScoredRun, l as EvalScorer, m as EvalVerdict, n as ExactMatchScorer, L as LLMJudgeScorer, o as LLMJudgeScorerOptions, p as compareEvalRuns, q as formatEvalReport } from '../eval-report-CpdAMa2b.js';
+import { B as BaseAgent } from '../base-agent-C4fYjHPu.js';
+export { C as ContainsScorer, a as CustomScorer, E as EvalCase, b as EvalCaseResult, c as EvalDataset, d as EvalImprovement, e as EvalRegression, f as EvalReport, g as EvalRun, h as EvalRunner, i as EvalRunnerOptions, j as EvalScoredResult, k as EvalScoredRun, l as EvalScorer, m as EvalVerdict, n as ExactMatchScorer, L as LLMJudgeScorer, o as LLMJudgeScorerOptions, p as compareEvalRuns, q as formatEvalReport } from '../eval-report-CO98LRUC.js';
 import 'events';
 
 /**

package/dist/{types-TB6yypig.d.cts → types-C3EZvpe0.d.cts}

@@ -1,4 +1,4 @@
-import { Participant, ModeConfig, Toolpack } from 'toolpack-sdk';
+import { Participant, ModeConfig, ToolpackInitConfig, Toolpack } from 'toolpack-sdk';
 import { EventEmitter } from 'events';
 
 /**
@@ -110,16 +110,14 @@ interface InterceptorChainConfig {
 /**
  * Options for constructing a BaseAgent.
  *
- * - `{ apiKey, provider?, model? }` — agent creates and owns its own Toolpack instance.
+ * - `ToolpackInitConfig` — agent creates and owns its own Toolpack instance using
+ *   the supplied config. Accepts everything `Toolpack.init()` accepts: `apiKey`,
+ *   `provider`, `model`, `customTools`, `tools`, `knowledge`, `customModes`, etc.
  *   The instance is initialised lazily in `start()`.
  * - `{ toolpack }` — agent uses a shared Toolpack instance (e.g. passed from AgentRegistry
- *   for multi-agent setups where API client and config are shared).
+ *   for multi-agent setups where the API client and config are shared).
  */
-type BaseAgentOptions = {
-    apiKey: string;
-    provider?: string;
-    model?: string;
-} | {
+type BaseAgentOptions = ToolpackInitConfig | {
     toolpack: Toolpack;
 };
 /**
@@ -152,6 +150,53 @@ interface AgentDelegationConfig {
      */
     mode?: 'await' | 'forget';
 }
+/**
+ * Definition of a single spawnable agent template.
+ * Templates are config objects — no subclassing required.
+ * The SDK instantiates an EphemeralAgent from this at spawn time.
+ */
+interface AgentSpawnTemplate {
+    /** Unique name for this template; use `'self'` as a reserved name for self-replication. */
+    name: string;
+    /** Human-readable purpose shown to the LLM so it can pick the right template. */
+    description: string;
+    /**
+     * Factory that receives the task string and returns the system prompt for the
+     * spawned agent. Called once per spawn invocation.
+     */
+    systemPrompt: (task: string) => string;
+    /** Model override for spawned agents of this template. Inherits parent model when omitted. */
+    model?: string;
+    /**
+     * Allow the LLM to append extra instructions to this template's system prompt
+     * via the `systemPromptAddition` tool parameter. Defaults to `false`.
+     * Only enable this for templates where LLM-driven prompt customisation is safe.
+     */
+    allowPromptAddition?: boolean;
+}
+/**
+ * Configuration for AI-driven dynamic agent spawning.
+ * When enabled, a `spawn_agent` tool is injected into every `run()` call so
+ * the LLM can instantiate a one-off helper agent, get its result, and continue.
+ * Spawned agents are ephemeral: no channels, no registry entry, discarded after use.
+ */
+interface AgentSpawnConfig {
+    /** Must be true for the spawn tool to be injected. */
+    enabled: boolean;
+    /**
+     * List of agent templates available for spawning.
+     * The LLM sees each template's name and description to decide which to use.
+     * Add a template with `name: 'self'` to opt in to self-replication — without
+     * it, the `spawn_agent` tool will not advertise or accept `"self"` as a target.
+     */
+    templates: AgentSpawnTemplate[];
+    /**
+     * Maximum recursive spawn depth (default: 3).
+     * When a spawned agent reaches this depth, the spawn tool is not injected —
+     * stopping the chain without throwing an error.
+     */
+    maxDepth?: number;
+}
 /**
  * Input structure for agent invocation.
  * Channels normalize external events into this format.
@@ -427,6 +472,15 @@ interface IAgentRegistry {
      * @returns Number of asks cleaned up
      */
     cleanupExpiredAsks(): number;
+    /** Returns true when all registered agents have no in-progress conversations. */
+    isAllIdle?(): boolean;
+    /**
+     * Schedule a graceful restart once all agents become idle, or after maxWaitMinutes
+     * (default 30) if idle is never reached. Idempotent — subsequent calls are no-ops.
+     */
+    scheduleRestart?(options?: {
+        maxWaitMinutes?: number;
+    }): void;
 }
 
-export { type AgentInput as A, type BaseAgentOptions as B, type ChannelInterface as C, type Interceptor as I, type NextFunction as N, type PendingAsk as P, SKIP_SENTINEL as S, type WorkflowStep as W, type AgentResult as a, type AgentDelegationConfig as b, type IAgentRegistry as c, type AgentRunOptions as d, type AgentOutput as e, type AgentInstance as f, type InterceptorChainConfig as g, type InterceptorContext as h, type InterceptorResult as i, isSkipSentinel as j, skip as s };
+export { type AgentInput as A, type BaseAgentOptions as B, type ChannelInterface as C, type Interceptor as I, type NextFunction as N, type PendingAsk as P, SKIP_SENTINEL as S, type WorkflowStep as W, type AgentResult as a, type AgentDelegationConfig as b, type AgentSpawnConfig as c, type IAgentRegistry as d, type AgentRunOptions as e, type AgentOutput as f, type AgentInstance as g, type AgentSpawnTemplate as h, type InterceptorChainConfig as i, type InterceptorContext as j, type InterceptorResult as k, isSkipSentinel as l, skip as s };

package/dist/{types-TB6yypig.d.ts → types-C3EZvpe0.d.ts}

@@ -1,4 +1,4 @@
-import { Participant, ModeConfig, Toolpack } from 'toolpack-sdk';
+import { Participant, ModeConfig, ToolpackInitConfig, Toolpack } from 'toolpack-sdk';
 import { EventEmitter } from 'events';
 
 /**
@@ -110,16 +110,14 @@ interface InterceptorChainConfig {
 /**
  * Options for constructing a BaseAgent.
  *
- * - `{ apiKey, provider?, model? }` — agent creates and owns its own Toolpack instance.
+ * - `ToolpackInitConfig` — agent creates and owns its own Toolpack instance using
+ *   the supplied config. Accepts everything `Toolpack.init()` accepts: `apiKey`,
+ *   `provider`, `model`, `customTools`, `tools`, `knowledge`, `customModes`, etc.
  *   The instance is initialised lazily in `start()`.
  * - `{ toolpack }` — agent uses a shared Toolpack instance (e.g. passed from AgentRegistry
- *   for multi-agent setups where API client and config are shared).
+ *   for multi-agent setups where the API client and config are shared).
  */
-type BaseAgentOptions = {
-    apiKey: string;
-    provider?: string;
-    model?: string;
-} | {
+type BaseAgentOptions = ToolpackInitConfig | {
     toolpack: Toolpack;
 };
 /**
@@ -152,6 +150,53 @@ interface AgentDelegationConfig {
      */
     mode?: 'await' | 'forget';
 }
+/**
+ * Definition of a single spawnable agent template.
+ * Templates are config objects — no subclassing required.
+ * The SDK instantiates an EphemeralAgent from this at spawn time.
+ */
+interface AgentSpawnTemplate {
+    /** Unique name for this template; use `'self'` as a reserved name for self-replication. */
+    name: string;
+    /** Human-readable purpose shown to the LLM so it can pick the right template. */
+    description: string;
+    /**
+     * Factory that receives the task string and returns the system prompt for the
+     * spawned agent. Called once per spawn invocation.
+     */
+    systemPrompt: (task: string) => string;
+    /** Model override for spawned agents of this template. Inherits parent model when omitted. */
+    model?: string;
+    /**
+     * Allow the LLM to append extra instructions to this template's system prompt
+     * via the `systemPromptAddition` tool parameter. Defaults to `false`.
+     * Only enable this for templates where LLM-driven prompt customisation is safe.
+     */
+    allowPromptAddition?: boolean;
+}
+/**
+ * Configuration for AI-driven dynamic agent spawning.
+ * When enabled, a `spawn_agent` tool is injected into every `run()` call so
+ * the LLM can instantiate a one-off helper agent, get its result, and continue.
+ * Spawned agents are ephemeral: no channels, no registry entry, discarded after use.
+ */
+interface AgentSpawnConfig {
+    /** Must be true for the spawn tool to be injected. */
+    enabled: boolean;
+    /**
+     * List of agent templates available for spawning.
+     * The LLM sees each template's name and description to decide which to use.
+     * Add a template with `name: 'self'` to opt in to self-replication — without
+     * it, the `spawn_agent` tool will not advertise or accept `"self"` as a target.
+     */
+    templates: AgentSpawnTemplate[];
+    /**
+     * Maximum recursive spawn depth (default: 3).
+     * When a spawned agent reaches this depth, the spawn tool is not injected —
+     * stopping the chain without throwing an error.
+     */
+    maxDepth?: number;
+}
 /**
  * Input structure for agent invocation.
  * Channels normalize external events into this format.
@@ -427,6 +472,15 @@ interface IAgentRegistry {
      * @returns Number of asks cleaned up
      */
     cleanupExpiredAsks(): number;
+    /** Returns true when all registered agents have no in-progress conversations. */
+    isAllIdle?(): boolean;
+    /**
+     * Schedule a graceful restart once all agents become idle, or after maxWaitMinutes
+     * (default 30) if idle is never reached. Idempotent — subsequent calls are no-ops.
+     */
+    scheduleRestart?(options?: {
+        maxWaitMinutes?: number;
+    }): void;
 }
 
-export { type AgentInput as A, type BaseAgentOptions as B, type ChannelInterface as C, type Interceptor as I, type NextFunction as N, type PendingAsk as P, SKIP_SENTINEL as S, type WorkflowStep as W, type AgentResult as a, type AgentDelegationConfig as b, type IAgentRegistry as c, type AgentRunOptions as d, type AgentOutput as e, type AgentInstance as f, type InterceptorChainConfig as g, type InterceptorContext as h, type InterceptorResult as i, isSkipSentinel as j, skip as s };
+export { type AgentInput as A, type BaseAgentOptions as B, type ChannelInterface as C, type Interceptor as I, type NextFunction as N, type PendingAsk as P, SKIP_SENTINEL as S, type WorkflowStep as W, type AgentResult as a, type AgentDelegationConfig as b, type AgentSpawnConfig as c, type IAgentRegistry as d, type AgentRunOptions as e, type AgentOutput as f, type AgentInstance as g, type AgentSpawnTemplate as h, type InterceptorChainConfig as i, type InterceptorContext as j, type InterceptorResult as k, isSkipSentinel as l, skip as s };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolpack-sdk/agents",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Production AI agents for Toolpack SDK — 8 channel integrations (Slack, Discord, Telegram, SMS, Email, Webhook, Scheduled, MCP), AgentMind persistent cognitive layer (goals, beliefs, reflections), interceptors, evals, and multi-agent coordination",
   "engines": {
     "node": ">=20"
@@ -89,11 +89,11 @@
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.x",
-    "@toolpack-sdk/knowledge": "^2.2.0",
+    "@toolpack-sdk/knowledge": "^2.4.0",
     "better-sqlite3": "^12.6.2",
     "discord.js": "^14.x",
     "nodemailer": "^6.x",
-    "toolpack-sdk": "^2.2.0",
+    "toolpack-sdk": "^2.4.0",
     "twilio": "^5.x"
   },
   "peerDependenciesMeta": {