@agntk/core 0.1.0

package/dist/pool/specialist-pool.js

@@ -0,0 +1,224 @@
+/**
+ * @fileoverview SpecialistPool — LRU+TTL cache of domain specialists.
+ *
+ * Spawns (or reuses) specialist agents keyed by domain name.
+ * Each specialist can have skills injected and maintains conversation history.
+ */
+import { createLogger } from '@agntk/logger';
+import { loadSkillsFromPaths, buildSkillsSystemPrompt } from '../skills/index.js';
+const log = createLogger('@agntk/core:pool');
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_MAX_AGENTS = 10;
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const DEFAULT_HISTORY_STRATEGY = 'full';
+const DEFAULT_WINDOW_SIZE = 20;
+// ============================================================================
+// SpecialistPool
+// ============================================================================
+export class SpecialistPool {
+    cache = new Map();
+    maxAgents;
+    ttlMs;
+    defaultHistoryStrategy;
+    defaultWindowSize;
+    createAgent;
+    constructor(config) {
+        this.maxAgents = config.maxAgents ?? DEFAULT_MAX_AGENTS;
+        this.ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+        this.defaultHistoryStrategy = config.defaultHistoryStrategy ?? DEFAULT_HISTORY_STRATEGY;
+        this.defaultWindowSize = config.defaultWindowSize ?? DEFAULT_WINDOW_SIZE;
+        this.createAgent = config.createAgent;
+        log.info('SpecialistPool created', {
+            maxAgents: this.maxAgents,
+            ttlMs: this.ttlMs,
+            defaultHistoryStrategy: this.defaultHistoryStrategy,
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Public API
+    // --------------------------------------------------------------------------
+    /**
+     * Spawn or reuse a specialist for the given domain.
+     * Returns the cached specialist if not expired; otherwise creates a new one.
+     */
+    async spawn(config) {
+        const { domain } = config;
+        // Check for existing cached specialist
+        const existing = this.cache.get(domain);
+        if (existing && !this.isExpired(existing)) {
+            log.debug('Cache hit', { domain, useCount: existing.useCount });
+            existing.lastUsedAt = Date.now();
+            existing.useCount += 1;
+            return existing;
+        }
+        // Remove expired entry if present
+        if (existing) {
+            log.debug('Cache expired, recreating', { domain });
+            this.cache.delete(domain);
+        }
+        // Evict LRU if at capacity
+        this.evictIfNeeded();
+        // Create new specialist
+        const specialist = await this.createSpecialist(config);
+        this.cache.set(domain, specialist);
+        log.info('Specialist spawned', { domain, skills: config.skills?.length ?? 0 });
+        return specialist;
+    }
+    /**
+     * Generate a response from a specialist, managing conversation history.
+     */
+    async generate(domain, prompt) {
+        const cached = this.cache.get(domain);
+        if (!cached) {
+            throw new Error(`No specialist found for domain: ${domain}. Call spawn() first.`);
+        }
+        if (this.isExpired(cached)) {
+            this.cache.delete(domain);
+            throw new Error(`Specialist for domain "${domain}" has expired. Call spawn() again.`);
+        }
+        cached.lastUsedAt = Date.now();
+        cached.useCount += 1;
+        // Build prompt with history context
+        const contextualPrompt = this.buildContextualPrompt(cached, prompt);
+        const result = await cached.agent.generate({ prompt: contextualPrompt });
+        const text = result.text ?? '';
+        // Update history
+        cached.history.push({ role: 'user', content: prompt, timestamp: Date.now() }, { role: 'assistant', content: text, timestamp: Date.now() });
+        return text;
+    }
+    /**
+     * List all cached specialists with their metadata.
+     */
+    list() {
+        return Array.from(this.cache.values()).map((entry) => ({
+            domain: entry.domain,
+            createdAt: entry.createdAt,
+            lastUsedAt: entry.lastUsedAt,
+            useCount: entry.useCount,
+            historyLength: entry.history.length,
+            expired: this.isExpired(entry),
+            skills: entry.agent.skills,
+        }));
+    }
+    /**
+     * Remove a specialist from the cache.
+     */
+    remove(domain) {
+        const deleted = this.cache.delete(domain);
+        if (deleted) {
+            log.info('Specialist removed', { domain });
+        }
+        return deleted;
+    }
+    /**
+     * Clear all cached specialists.
+     */
+    clear() {
+        const count = this.cache.size;
+        this.cache.clear();
+        log.info('Pool cleared', { removedCount: count });
+    }
+    /**
+     * Get the current number of cached specialists.
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Get a cached specialist by domain (without modifying LRU state).
+     */
+    get(domain) {
+        return this.cache.get(domain);
+    }
+    // --------------------------------------------------------------------------
+    // Private
+    // --------------------------------------------------------------------------
+    isExpired(entry) {
+        return Date.now() - entry.createdAt > this.ttlMs;
+    }
+    evictIfNeeded() {
+        while (this.cache.size >= this.maxAgents) {
+            // Find LRU: oldest lastUsedAt
+            let lruKey;
+            let lruTime = Infinity;
+            for (const [key, entry] of this.cache) {
+                if (entry.lastUsedAt < lruTime) {
+                    lruTime = entry.lastUsedAt;
+                    lruKey = key;
+                }
+            }
+            if (lruKey) {
+                log.info('Evicting LRU specialist', { domain: lruKey, lastUsedAt: lruTime });
+                this.cache.delete(lruKey);
+            }
+            else {
+                break;
+            }
+        }
+    }
+    async createSpecialist(config) {
+        const role = config.role ?? 'generic';
+        const skills = config.skills ?? [];
+        // Build system prompt with skills
+        let systemPrompt = config.instructions ?? '';
+        if (skills.length > 0) {
+            const loadedSkills = loadSkillsFromPaths(skills);
+            if (loadedSkills.length > 0) {
+                const skillsPrompt = buildSkillsSystemPrompt(loadedSkills);
+                systemPrompt = systemPrompt ? `${systemPrompt}\n${skillsPrompt}` : skillsPrompt;
+            }
+        }
+        // Create the agent via the factory
+        const agentOptions = {
+            role,
+            ...(systemPrompt && { systemPrompt }),
+            ...config.agentOptions,
+        };
+        const rawAgent = this.createAgent(agentOptions);
+        const agent = {
+            generate: rawAgent.generate,
+            domain: config.domain,
+            skills,
+        };
+        const now = Date.now();
+        return {
+            domain: config.domain,
+            agent,
+            createdAt: now,
+            lastUsedAt: now,
+            useCount: 1,
+            history: [],
+        };
+    }
+    buildContextualPrompt(cached, prompt) {
+        const history = this.getRelevantHistory(cached);
+        if (history.length === 0)
+            return prompt;
+        const historyText = history
+            .map((msg) => `${msg.role === 'user' ? 'User' : 'Assistant'}: ${msg.content}`)
+            .join('\n\n');
+        return `Previous conversation:\n${historyText}\n\nCurrent request: ${prompt}`;
+    }
+    getRelevantHistory(cached) {
+        const strategy = this.defaultHistoryStrategy;
+        const history = cached.history;
+        switch (strategy) {
+            case 'full':
+                return history;
+            case 'sliding-window': {
+                const windowSize = this.defaultWindowSize;
+                return history.slice(-windowSize);
+            }
+            case 'summary':
+                // Summary strategy: keep first message + last few for context
+                if (history.length <= 4)
+                    return history;
+                return [...history.slice(0, 2), ...history.slice(-2)];
+            default:
+                return history;
+        }
+    }
+}
+//# sourceMappingURL=specialist-pool.js.map

package/dist/pool/specialist-pool.js.map

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

package/dist/pool/tools.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview AI SDK tools for SpecialistPool interaction.
+ *
+ * - spawn_specialist: Spawn or reuse a cached domain specialist.
+ * - list_specialists: List all cached specialists and their state.
+ */
+import type { SpecialistPool } from './specialist-pool.js';
+export declare function createSpawnSpecialistTool(pool: SpecialistPool): import("ai").Tool<{
+    prompt: string;
+    domain: string;
+    role?: "generic" | "coder" | "researcher" | "analyst" | undefined;
+    skills?: string[] | undefined;
+    instructions?: string | undefined;
+}, {
+    domain: string;
+    response: string;
+    useCount: number;
+    skills: string[];
+    fromCache: boolean;
+}>;
+export declare function createListSpecialistsTool(pool: SpecialistPool): import("ai").Tool<{}, {
+    count: number;
+    specialists: {
+        domain: string;
+        useCount: number;
+        historyLength: number;
+        expired: boolean;
+        skills: string[];
+        ageMs: number;
+        lastUsedMs: number;
+    }[];
+}>;
+/**
+ * Create all pool tools for use with an Agent's tool set.
+ */
+export declare function createPoolTools(pool: SpecialistPool): {
+    spawn_specialist: import("ai").Tool<{
+        prompt: string;
+        domain: string;
+        role?: "generic" | "coder" | "researcher" | "analyst" | undefined;
+        skills?: string[] | undefined;
+        instructions?: string | undefined;
+    }, {
+        domain: string;
+        response: string;
+        useCount: number;
+        skills: string[];
+        fromCache: boolean;
+    }>;
+    list_specialists: import("ai").Tool<{}, {
+        count: number;
+        specialists: {
+            domain: string;
+            useCount: number;
+            historyLength: number;
+            expired: boolean;
+            skills: string[];
+            ageMs: number;
+            lastUsedMs: number;
+        }[];
+    }>;
+};
+//# sourceMappingURL=tools.d.ts.map

package/dist/pool/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/pool/tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,cAAc;;;;;;;;;;;;GAmC7D;AAMD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,cAAc;;;;;;;;;;;GAsB7D;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;EAKnD"}

package/dist/pool/tools.js

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview AI SDK tools for SpecialistPool interaction.
+ *
+ * - spawn_specialist: Spawn or reuse a cached domain specialist.
+ * - list_specialists: List all cached specialists and their state.
+ */
+import { z } from 'zod';
+import { tool } from 'ai';
+// ============================================================================
+// spawn_specialist
+// ============================================================================
+export function createSpawnSpecialistTool(pool) {
+    return tool({
+        description: 'Spawn or reuse a cached domain specialist. If a specialist for the given domain ' +
+            'already exists and has not expired, it is reused. Otherwise a new specialist is created ' +
+            'with the specified role, skills, and instructions.',
+        inputSchema: z.object({
+            domain: z.string().describe('Domain/specialty name (used as cache key).'),
+            role: z
+                .enum(['generic', 'coder', 'researcher', 'analyst'])
+                .optional()
+                .describe('Agent role. Default: generic.'),
+            skills: z
+                .array(z.string())
+                .optional()
+                .describe('Skill directory paths or skill names to inject.'),
+            instructions: z
+                .string()
+                .optional()
+                .describe('Custom system prompt instructions for this specialist.'),
+            prompt: z.string().describe('The prompt/task to send to the specialist.'),
+        }),
+        execute: async ({ domain, role, skills, instructions, prompt }) => {
+            const cached = await pool.spawn({ domain, role, skills, instructions });
+            const response = await pool.generate(domain, prompt);
+            return {
+                domain: cached.domain,
+                response,
+                useCount: cached.useCount,
+                skills: cached.agent.skills,
+                fromCache: cached.useCount > 1,
+            };
+        },
+    });
+}
+// ============================================================================
+// list_specialists
+// ============================================================================
+export function createListSpecialistsTool(pool) {
+    return tool({
+        description: 'List all cached specialists in the pool with their domain, age, usage count, ' +
+            'history length, and expiration status.',
+        inputSchema: z.object({}),
+        execute: async () => {
+            const specialists = pool.list();
+            return {
+                count: specialists.length,
+                specialists: specialists.map((s) => ({
+                    domain: s.domain,
+                    useCount: s.useCount,
+                    historyLength: s.historyLength,
+                    expired: s.expired,
+                    skills: s.skills,
+                    ageMs: Date.now() - s.createdAt,
+                    lastUsedMs: Date.now() - s.lastUsedAt,
+                })),
+            };
+        },
+    });
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create all pool tools for use with an Agent's tool set.
+ */
+export function createPoolTools(pool) {
+    return {
+        spawn_specialist: createSpawnSpecialistTool(pool),
+        list_specialists: createListSpecialistsTool(pool),
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/pool/tools.js.map

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

package/dist/pool/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Types for the SpecialistPool.
+ */
+import type { AgentOptions, AgentRole } from '../types/agent.js';
+/** History management strategy for cached specialists. */
+export type HistoryStrategy = 'full' | 'sliding-window' | 'summary';
+/** Configuration for a specialist in the pool. */
+export interface SpecialistConfig {
+    /** Domain/specialty name (used as cache key). */
+    domain: string;
+    /** Agent role. Default: 'generic'. */
+    role?: AgentRole;
+    /** Skills to inject (directory paths or skill names). */
+    skills?: string[];
+    /** Custom system prompt (appended to role prompt + skills). */
+    instructions?: string;
+    /** History strategy for conversation continuity. Default: 'full'. */
+    historyStrategy?: HistoryStrategy;
+    /** Max messages for sliding-window strategy. Default: 20. */
+    historyWindowSize?: number;
+    /** Additional agent options. */
+    agentOptions?: Partial<AgentOptions>;
+}
+/** A cached specialist entry. */
+export interface CachedSpecialist {
+    /** Domain name. */
+    domain: string;
+    /** The specialist agent. */
+    agent: SpecialistAgent;
+    /** When this specialist was created. */
+    createdAt: number;
+    /** When this specialist was last used. */
+    lastUsedAt: number;
+    /** Number of times this specialist has been used. */
+    useCount: number;
+    /** Conversation history (for stateful specialists). */
+    history: ConversationMessage[];
+}
+/** A message in conversation history. */
+export interface ConversationMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp: number;
+}
+/** A specialist agent with metadata. */
+export interface SpecialistAgent {
+    /** Generate a response. */
+    generate: (input: {
+        prompt: string;
+    }) => Promise<{
+        text: string;
+        [key: string]: unknown;
+    }>;
+    /** The domain this specialist serves. */
+    domain: string;
+    /** Skills loaded for this specialist. */
+    skills: string[];
+}
+/** Configuration for the SpecialistPool. */
+export interface SpecialistPoolConfig {
+    /** Maximum number of cached specialists. Default: 10. */
+    maxAgents?: number;
+    /** TTL for cached specialists (ms). Default: 30 minutes. */
+    ttlMs?: number;
+    /** Default history strategy. Default: 'full'. */
+    defaultHistoryStrategy?: HistoryStrategy;
+    /** Default sliding-window size. Default: 20. */
+    defaultWindowSize?: number;
+    /** Factory function to create agent instances. */
+    createAgent: (options: AgentOptions) => {
+        generate: (input: {
+            prompt: string;
+        }) => Promise<{
+            text: string;
+            [key: string]: unknown;
+        }>;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/pool/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pool/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE9D,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAEpE,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gCAAgC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;CACtC;AAED,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,KAAK,EAAE,eAAe,CAAC;IACvB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,OAAO,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAED,yCAAyC;AACzC,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IAC3F,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,sBAAsB,CAAC,EAAE,eAAe,CAAC;IACzC,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,WAAW,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK;QAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,KAAK,OAAO,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;CACxI"}

package/dist/pool/types.js

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Types for the SpecialistPool.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/pool/types.js.map

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

package/dist/presets/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @agntk/core - Presets Module Index
+ */
+export { roleConfigs, rolePrompts, systemPrompts, roleCallOptionsSchemas, AGENT_ROLES, SPAWNED_AGENT_CONTEXT, buildSpawnedAgentPrompt, getRoleSystemPrompt, getRoleCallOptionsSchema, type AgentRole, type RoleConfig, } from './roles.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/presets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/presets/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,WAAW,EACX,WAAW,EACX,aAAa,EACb,sBAAsB,EACtB,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,SAAS,EACd,KAAK,UAAU,GAChB,MAAM,SAAS,CAAC"}

package/dist/presets/index.js

@@ -0,0 +1,5 @@
+/**
+ * @agntk/core - Presets Module Index
+ */
+export { roleConfigs, rolePrompts, systemPrompts, roleCallOptionsSchemas, AGENT_ROLES, SPAWNED_AGENT_CONTEXT, buildSpawnedAgentPrompt, getRoleSystemPrompt, getRoleCallOptionsSchema, } from './roles.js';
+//# sourceMappingURL=index.js.map

package/dist/presets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/presets/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,WAAW,EACX,WAAW,EACX,aAAa,EACb,sBAAsB,EACtB,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,GAGzB,MAAM,SAAS,CAAC"}

package/dist/presets/role-registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Role Registry - manages built-in and custom roles.
+ */
+import { z } from 'zod';
+export interface RoleDefinition {
+    /** System prompt for this role */
+    systemPrompt: string;
+    /** Zod schema for call options */
+    callOptionsSchema?: z.ZodType;
+    /** Default tools to include */
+    defaultTools?: string[];
+    /** Recommended model tier */
+    recommendedModel?: 'fast' | 'standard' | 'reasoning' | 'powerful';
+}
+declare const BASE_SYSTEM_PROMPT = "You are an AI assistant with access to tools for completing tasks.\n\n**Guidelines:**\n- Be direct and concise in your responses\n- Use tools when they would help accomplish the task\n- Explain your reasoning when making decisions\n- Ask for clarification if the request is ambiguous\n- Complete tasks step by step, validating progress";
+/**
+ * Register a role in the registry.
+ */
+export declare function registerRole(name: string, definition: RoleDefinition): void;
+/**
+ * Get a role from the registry.
+ * Falls back to built-in roles, then generic.
+ * Templates are applied to the system prompt.
+ */
+export declare function getRole(name: string): RoleDefinition;
+/**
+ * Get all registered role names.
+ */
+export declare function getAllRoleNames(): string[];
+/**
+ * Check if a role exists.
+ */
+export declare function hasRole(name: string): boolean;
+/**
+ * Reset the registry (for testing).
+ */
+export declare function resetRoleRegistry(): void;
+export declare const SPAWNED_AGENT_CONTEXT = "\n# Context: Spawned Sub-Agent\n\nYou are running as a sub-agent spawned by a parent agent to handle a delegated task.\n\n**Constraints:**\n- The delegate tool is disabled to prevent infinite recursion\n- Focus on completing the delegated task autonomously\n";
+export declare function buildSpawnedAgentPrompt(role: string): string;
+export { BASE_SYSTEM_PROMPT };
+//# sourceMappingURL=role-registry.d.ts.map

package/dist/presets/role-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-registry.d.ts","sourceRoot":"","sources":["../../src/presets/role-registry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,iBAAiB,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IAC9B,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,6BAA6B;IAC7B,gBAAgB,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;CACnE;AAaD,QAAA,MAAM,kBAAkB,oVAO2B,CAAC;AA0FpD;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,GAAG,IAAI,CAG3E;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAoBpD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAK1C;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG7C;AA2CD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC;AAMD,eAAO,MAAM,qBAAqB,uQAQjC,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED,OAAO,EAAE,kBAAkB,EAAE,CAAC"}