@agntk/core 0.3.0 → 0.3.1

package/dist/presets/role-registry.js

@@ -0,0 +1,213 @@
+/**
+ * @fileoverview Role Registry - manages built-in and custom roles.
+ */
+import { z } from 'zod';
+import { createLogger } from '@agntk/logger';
+import { getConfig } from '../config/index.js';
+import { applyTemplate } from '../prompts/template.js';
+const log = createLogger('@agntk/core:roles');
+// ============================================================================
+// Registry State
+// ============================================================================
+const roleRegistry = new Map();
+let configRolesLoaded = false;
+// ============================================================================
+// Base System Prompt
+// ============================================================================
+const BASE_SYSTEM_PROMPT = `You are an AI assistant with access to tools for completing tasks.
+
+**Guidelines:**
+- Be direct and concise in your responses
+- Use tools when they would help accomplish the task
+- Explain your reasoning when making decisions
+- Ask for clarification if the request is ambiguous
+- Complete tasks step by step, validating progress`;
+// ============================================================================
+// Built-in Role Prompts
+// ============================================================================
+const ROLE_PROMPTS = {
+    generic: '',
+    researcher: `
+# Role: Research Specialist
+
+You excel at gathering, verifying, and synthesizing information from multiple sources.
+
+**Core competencies:**
+- Web search and documentation retrieval
+- Cross-referencing claims across sources
+- Distinguishing fact from speculation
+- Summarizing complex topics clearly
+
+**Quality standards:**
+- Cite sources for factual claims
+- Explicitly state confidence levels
+- Acknowledge when information is incomplete`,
+    coder: `
+# Role: Software Engineer
+
+You write production-quality code that integrates cleanly with existing systems.
+
+**Core competencies:**
+- Reading and understanding existing codebases
+- Writing clean, maintainable code
+- Testing and validation
+- Debugging and error diagnosis
+
+**Quality standards:**
+- Follow patterns established in the codebase
+- Write tests for new functionality
+- Consistent formatting with the codebase
+- Meaningful variable and function names`,
+    analyst: `
+# Role: Data Analyst
+
+You analyze information to extract insights and support decision-making.
+
+**Core competencies:**
+- Pattern recognition across datasets
+- Statistical reasoning
+- Hypothesis formation and testing
+- Clear communication of findings
+
+**Quality standards:**
+- Distinguish correlation from causation
+- Quantify uncertainty in conclusions
+- Consider alternative explanations`,
+};
+// ============================================================================
+// Built-in Roles
+// ============================================================================
+const BUILT_IN_ROLES = {
+    generic: {
+        systemPrompt: BASE_SYSTEM_PROMPT,
+        defaultTools: ['shell', 'glob', 'grep'],
+        recommendedModel: 'standard',
+    },
+    researcher: {
+        systemPrompt: `${BASE_SYSTEM_PROMPT}\n${ROLE_PROMPTS.researcher}`,
+        defaultTools: ['glob', 'grep', 'deep_reasoning'],
+        recommendedModel: 'standard',
+    },
+    coder: {
+        systemPrompt: `${BASE_SYSTEM_PROMPT}\n${ROLE_PROMPTS.coder}`,
+        defaultTools: ['shell', 'glob', 'grep'],
+        recommendedModel: 'powerful',
+    },
+    analyst: {
+        systemPrompt: `${BASE_SYSTEM_PROMPT}\n${ROLE_PROMPTS.analyst}`,
+        defaultTools: ['glob', 'grep', 'deep_reasoning'],
+        recommendedModel: 'standard',
+    },
+};
+// ============================================================================
+// Registry Functions
+// ============================================================================
+/**
+ * Register a role in the registry.
+ */
+export function registerRole(name, definition) {
+    log.debug('Registering role', { name, hasPrompt: !!definition.systemPrompt });
+    roleRegistry.set(name, definition);
+}
+/**
+ * Get a role from the registry.
+ * Falls back to built-in roles, then generic.
+ * Templates are applied to the system prompt.
+ */
+export function getRole(name) {
+    loadConfigRoles();
+    let role;
+    // Check registry first
+    if (roleRegistry.has(name)) {
+        role = roleRegistry.get(name);
+    }
+    else if (name in BUILT_IN_ROLES) {
+        role = BUILT_IN_ROLES[name];
+    }
+    else {
+        log.warn('Unknown role, using generic', { role: name });
+        role = BUILT_IN_ROLES.generic;
+    }
+    // Apply template substitution
+    return {
+        ...role,
+        systemPrompt: applyTemplate(role.systemPrompt),
+    };
+}
+/**
+ * Get all registered role names.
+ */
+export function getAllRoleNames() {
+    loadConfigRoles();
+    const builtIn = Object.keys(BUILT_IN_ROLES);
+    const custom = Array.from(roleRegistry.keys());
+    return [...new Set([...builtIn, ...custom])];
+}
+/**
+ * Check if a role exists.
+ */
+export function hasRole(name) {
+    loadConfigRoles();
+    return roleRegistry.has(name) || name in BUILT_IN_ROLES;
+}
+// ============================================================================
+// Config Loading
+// ============================================================================
+/**
+ * Load roles from config file (called lazily on first access).
+ */
+function loadConfigRoles() {
+    if (configRolesLoaded)
+        return;
+    configRolesLoaded = true;
+    const config = getConfig();
+    const roles = config.roles;
+    if (!roles)
+        return;
+    for (const [name, roleConfig] of Object.entries(roles)) {
+        if (!roleConfig)
+            continue;
+        // Build the full prompt
+        let systemPrompt = roleConfig.systemPrompt ?? '';
+        // If it's an override of a built-in role, inherit the base
+        if (name in BUILT_IN_ROLES && !roleConfig.systemPrompt) {
+            systemPrompt = BUILT_IN_ROLES[name].systemPrompt;
+        }
+        else if (systemPrompt && !systemPrompt.includes('Guidelines:')) {
+            // Prepend base prompt if custom prompt doesn't include it
+            systemPrompt = `${BASE_SYSTEM_PROMPT}\n\n${systemPrompt}`;
+        }
+        const definition = {
+            systemPrompt,
+            defaultTools: roleConfig.defaultTools,
+            recommendedModel: roleConfig.recommendedModel,
+        };
+        log.info('Loading role from config', { name });
+        registerRole(name, definition);
+    }
+}
+/**
+ * Reset the registry (for testing).
+ */
+export function resetRoleRegistry() {
+    roleRegistry.clear();
+    configRolesLoaded = false;
+}
+// ============================================================================
+// Helpers for backward compatibility
+// ============================================================================
+export const SPAWNED_AGENT_CONTEXT = `
+# Context: Spawned Sub-Agent
+
+You are running as a sub-agent spawned by a parent agent to handle a delegated task.
+
+**Constraints:**
+- The delegate tool is disabled to prevent infinite recursion
+- Focus on completing the delegated task autonomously
+`;
+export function buildSpawnedAgentPrompt(role) {
+    const def = getRole(role);
+    return `${def.systemPrompt}\n${SPAWNED_AGENT_CONTEXT}`;
+}
+export { BASE_SYSTEM_PROMPT };
+//# sourceMappingURL=role-registry.js.map

package/dist/presets/role-registry.js.map

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

package/dist/presets/roles.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @agntk/core - Role Configurations
+ *
+ * Agent role presets with system prompts and call options.
+ * Adapted from packages/core/src/agents/roles.ts
+ */
+import { z } from 'zod';
+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- You still have access to fs, shell, web, memory, and task tools\n- Focus on completing the delegated task, then call task_complete\n\nWork autonomously until the task is complete.";
+export declare const rolePrompts: {
+    generic: string;
+    researcher: string;
+    coder: string;
+    analyst: string;
+};
+export declare const systemPrompts: {
+    generic: string;
+    researcher: string;
+    coder: string;
+    analyst: string;
+};
+export type AgentRole = keyof typeof systemPrompts;
+export declare const AGENT_ROLES: readonly ["generic", "researcher", "coder", "analyst"];
+export declare const roleCallOptionsSchemas: {
+    generic: z.ZodObject<{
+        userId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        workspaceRoot: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        workspaceRoot?: string | undefined;
+        sessionId?: string | undefined;
+        userId?: string | undefined;
+    }, {
+        workspaceRoot?: string | undefined;
+        sessionId?: string | undefined;
+        userId?: string | undefined;
+    }>;
+    researcher: z.ZodObject<{
+        userId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        workspaceRoot: z.ZodOptional<z.ZodString>;
+        searchDepth: z.ZodOptional<z.ZodEnum<["shallow", "deep"]>>;
+        sourceTypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        workspaceRoot?: string | undefined;
+        sessionId?: string | undefined;
+        userId?: string | undefined;
+        searchDepth?: "shallow" | "deep" | undefined;
+        sourceTypes?: string[] | undefined;
+    }, {
+        workspaceRoot?: string | undefined;
+        sessionId?: string | undefined;
+        userId?: string | undefined;
+        searchDepth?: "shallow" | "deep" | undefined;
+        sourceTypes?: string[] | undefined;
+    }>;
+    coder: z.ZodObject<{
+        userId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        workspaceRoot: z.ZodOptional<z.ZodString>;
+        language: z.ZodOptional<z.ZodString>;
+        testingStrategy: z.ZodOptional<z.ZodEnum<["unit", "integration", "both", "none"]>>;
+    }, "strip", z.ZodTypeAny, {
+        workspaceRoot?: string | undefined;
+        sessionId?: string | undefined;
+        userId?: string | undefined;
+        language?: string | undefined;
+        testingStrategy?: "none" | "unit" | "integration" | "both" | undefined;
+    }, {
+        workspaceRoot?: string | undefined;
+        sessionId?: string | undefined;
+        userId?: string | undefined;
+        language?: string | undefined;
+        testingStrategy?: "none" | "unit" | "integration" | "both" | undefined;
+    }>;
+    analyst: z.ZodObject<{
+        userId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        workspaceRoot: z.ZodOptional<z.ZodString>;
+        analysisType: z.ZodOptional<z.ZodEnum<["exploratory", "confirmatory"]>>;
+        outputFormat: z.ZodOptional<z.ZodEnum<["summary", "detailed", "visual"]>>;
+    }, "strip", z.ZodTypeAny, {
+        workspaceRoot?: string | undefined;
+        sessionId?: string | undefined;
+        userId?: string | undefined;
+        analysisType?: "exploratory" | "confirmatory" | undefined;
+        outputFormat?: "summary" | "detailed" | "visual" | undefined;
+    }, {
+        workspaceRoot?: string | undefined;
+        sessionId?: string | undefined;
+        userId?: string | undefined;
+        analysisType?: "exploratory" | "confirmatory" | undefined;
+        outputFormat?: "summary" | "detailed" | "visual" | undefined;
+    }>;
+};
+export interface RoleConfig {
+    systemPrompt: string;
+    callOptionsSchema: z.ZodType;
+    defaultTools?: string[];
+    recommendedModel?: string;
+}
+export declare const roleConfigs: Record<AgentRole, RoleConfig>;
+export declare function buildSpawnedAgentPrompt(role: AgentRole): string;
+export declare function getRoleSystemPrompt(role: AgentRole): string;
+export declare function getRoleCallOptionsSchema(role: AgentRole): z.ZodType;
+//# sourceMappingURL=roles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../src/presets/roles.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,qBAAqB,qYAUY,CAAC;AAE/C,eAAO,MAAM,WAAW;;;;;CA+EvB,CAAC;AAsCF,eAAO,MAAM,aAAa;;;;;CAKzB,CAAC;AAMF,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,aAAa,CAAC;AACnD,eAAO,MAAM,WAAW,wDAAyD,CAAC;AAMlF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BlC,CAAC;AAMF,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,CAAC,CAAC,OAAO,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,SAAS,EAAE,UAAU,CAyBrD,CAAC;AAMF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAE/D;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAE3D;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,SAAS,GAAG,CAAC,CAAC,OAAO,CAEnE"}

package/dist/presets/roles.js

@@ -0,0 +1,207 @@
+/**
+ * @agntk/core - Role Configurations
+ *
+ * Agent role presets with system prompts and call options.
+ * Adapted from packages/core/src/agents/roles.ts
+ */
+import { z } from 'zod';
+// ============================================================================
+// Role Prompts
+// ============================================================================
+export const SPAWNED_AGENT_CONTEXT = `
+# Context: Spawned Sub-Agent
+
+You are running as a sub-agent spawned by a parent agent to handle a delegated task.
+
+**Constraints:**
+- The delegate tool is disabled to prevent infinite recursion
+- You still have access to fs, shell, web, memory, and task tools
+- Focus on completing the delegated task, then call task_complete
+
+Work autonomously until the task is complete.`;
+export const rolePrompts = {
+    generic: '',
+    researcher: `
+# Role: Research Specialist
+
+You excel at gathering, verifying, and synthesizing information from multiple sources.
+
+**Core competencies:**
+- Web search and documentation retrieval
+- Cross-referencing claims across sources
+- Distinguishing fact from speculation
+- Summarizing complex topics clearly
+- Identifying knowledge gaps and uncertainties
+
+**Approach:**
+1. Start with broad searches to understand the landscape
+2. Drill into authoritative sources for specifics
+3. Verify claims by finding corroborating evidence
+4. Note conflicting information and assess credibility
+5. Synthesize findings into clear, structured summaries
+
+**Quality standards:**
+- Cite sources for factual claims
+- Explicitly state confidence levels
+- Acknowledge when information is incomplete or uncertain
+- Prefer primary sources over secondary summaries`,
+    coder: `
+# Role: Software Engineer
+
+You write production-quality code that integrates cleanly with existing systems.
+
+**Core competencies:**
+- Reading and understanding existing codebases
+- Writing clean, maintainable code
+- Testing and validation
+- Debugging and error diagnosis
+- Git operations and version control
+
+**Approach:**
+1. Read existing code before writing new code
+2. Follow patterns established in the codebase
+3. Write tests for new functionality
+4. Validate changes compile and pass tests
+5. Make atomic, focused commits
+
+**Quality standards:**
+- No commented-out code or TODOs without context
+- Consistent formatting with the codebase
+- Meaningful variable and function names
+- Error handling for edge cases
+- Type safety where applicable`,
+    analyst: `
+# Role: Data Analyst
+
+You analyze information to extract insights and support decision-making.
+
+**Core competencies:**
+- Pattern recognition across datasets
+- Statistical reasoning
+- Data visualization concepts
+- Hypothesis formation and testing
+- Clear communication of findings
+
+**Approach:**
+1. Understand what question needs answering
+2. Gather relevant data from available sources
+3. Clean and validate data quality
+4. Apply appropriate analysis methods
+5. Present findings with supporting evidence
+
+**Quality standards:**
+- Distinguish correlation from causation
+- Quantify uncertainty in conclusions
+- Consider alternative explanations
+- Present data honestly without cherry-picking
+- Make recommendations actionable`,
+};
+// ============================================================================
+// Base System Prompt (standalone version)
+// ============================================================================
+const baseSystemPrompt = `You are an autonomous AI agent operating in a software development workspace. You have access to tools for reading, writing, and searching files, running shell commands, browsing the web, and delegating to sub-agents. You are in a multi-step execution loop — you will keep working until the task is complete.
+
+# Identity and Approach
+
+You are a hands-on agent. When given a task, you use your tools to accomplish it directly rather than explaining what the user could do. You think through problems step by step, writing out your reasoning before each tool call so your decision-making is transparent. When a task requires multiple steps, you persist through all of them — you do not stop partway or ask for permission to continue unless the request is genuinely ambiguous.
+
+CRITICAL RULES:
+- Never say "I can't", "I don't have access", or "I don't know" without trying a tool first.
+- If you don't know how to answer something, your default action is to use a tool — not to give up.
+- Always prefer action over asking for clarification.
+
+# Working with Code
+
+Before modifying any file, you read it first to understand its current state and context. You make targeted, minimal edits rather than rewriting entire files. After making changes, you verify they work by running builds, tests, or other validation as appropriate. When exploring an unfamiliar codebase, you start broad (glob for file patterns, grep for content) and narrow down progressively.
+
+# Tool Awareness
+
+Your tool calls and their results are displayed directly to the user. Because of this, you do not echo or restate tool output in your text responses. Instead, you provide brief interpretation — what the results mean, what you noticed, or what you plan to do next. This keeps the conversation focused and avoids redundancy.
+
+# Problem Solving
+
+When something goes wrong — a failed command, an unexpected error, a tool call that returns nothing useful — you read the error output, reason about what happened, and try a different approach. You never give up after one failure. If one path doesn't work, you try alternative approaches before concluding something isn't possible. When the user asks you to do something and you're not sure how, try the most obvious approach first — action beats deliberation.
+
+# Communication
+
+You are direct and concise. You lead with actions and results rather than preamble. After completing work, you briefly summarize what you did and why. If you're uncertain about something, you say so clearly rather than guessing. Never ask the user to clarify something you could figure out by using your tools.`;
+// ============================================================================
+// Combined System Prompts
+// ============================================================================
+export const systemPrompts = {
+    generic: baseSystemPrompt,
+    researcher: `${baseSystemPrompt}\n${rolePrompts.researcher}`,
+    coder: `${baseSystemPrompt}\n${rolePrompts.coder}`,
+    analyst: `${baseSystemPrompt}\n${rolePrompts.analyst}`,
+};
+export const AGENT_ROLES = ['generic', 'researcher', 'coder', 'analyst'];
+// ============================================================================
+// Call Options Schema per Role
+// ============================================================================
+export const roleCallOptionsSchemas = {
+    generic: z.object({
+        userId: z.string().optional(),
+        sessionId: z.string().optional(),
+        workspaceRoot: z.string().optional(),
+    }),
+    researcher: z.object({
+        userId: z.string().optional(),
+        sessionId: z.string().optional(),
+        workspaceRoot: z.string().optional(),
+        searchDepth: z.enum(['shallow', 'deep']).optional(),
+        sourceTypes: z.array(z.string()).optional(),
+    }),
+    coder: z.object({
+        userId: z.string().optional(),
+        sessionId: z.string().optional(),
+        workspaceRoot: z.string().optional(),
+        language: z.string().optional(),
+        testingStrategy: z.enum(['unit', 'integration', 'both', 'none']).optional(),
+    }),
+    analyst: z.object({
+        userId: z.string().optional(),
+        sessionId: z.string().optional(),
+        workspaceRoot: z.string().optional(),
+        analysisType: z.enum(['exploratory', 'confirmatory']).optional(),
+        outputFormat: z.enum(['summary', 'detailed', 'visual']).optional(),
+    }),
+};
+export const roleConfigs = {
+    generic: {
+        systemPrompt: systemPrompts.generic,
+        callOptionsSchema: roleCallOptionsSchemas.generic,
+        defaultTools: ['fs', 'shell', 'web'],
+        recommendedModel: 'standard',
+    },
+    researcher: {
+        systemPrompt: systemPrompts.researcher,
+        callOptionsSchema: roleCallOptionsSchemas.researcher,
+        defaultTools: ['web', 'fs', 'reasoning'],
+        recommendedModel: 'standard',
+    },
+    coder: {
+        systemPrompt: systemPrompts.coder,
+        callOptionsSchema: roleCallOptionsSchemas.coder,
+        defaultTools: ['fs', 'shell', 'grep', 'glob'],
+        recommendedModel: 'powerful',
+    },
+    analyst: {
+        systemPrompt: systemPrompts.analyst,
+        callOptionsSchema: roleCallOptionsSchemas.analyst,
+        defaultTools: ['fs', 'reasoning', 'shell'],
+        recommendedModel: 'standard',
+    },
+};
+// ============================================================================
+// Helpers
+// ============================================================================
+export function buildSpawnedAgentPrompt(role) {
+    return `${systemPrompts[role]}\n${SPAWNED_AGENT_CONTEXT}`;
+}
+export function getRoleSystemPrompt(role) {
+    return systemPrompts[role];
+}
+export function getRoleCallOptionsSchema(role) {
+    return roleCallOptionsSchemas[role];
+}
+//# sourceMappingURL=roles.js.map

package/dist/presets/roles.js.map

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

package/dist/prompts/templates.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @agntk/core - System Prompt Templates
+ * Core system prompts for agent behavior
+ *
+ * @deprecated Use `presets/role-registry.ts` instead. That module is the canonical
+ * source of truth for role prompts, used by `createAgent()` via `getRole()`.
+ * This file is kept for backward compatibility of public exports only.
+ */
+export declare const systemPrompt = "You are an autonomous agent. Your purpose is to accomplish the user's goal using whatever approach makes sense.\n\n# Philosophy\n\nYou have a mind and you have tools. Tools extend your thinking - use them fluidly as part of reasoning, not as separate mechanical steps.\n\nThere is no single correct workflow. Match your approach to the problem:\n- Reason through it, gather information, reason more, then act\n- Act immediately if the path is obvious\n- Start one approach, realize it's wrong, switch to another\n- Call multiple tools in parallel when they don't depend on each other\n\nWhen something doesn't work, adapt. When you need information, go get it. When uncertain, reason carefully. When clear, act directly.\n\nWhen errors occur, read them carefully. The error message usually points to the fix.\n\n# Action\n\nDo things, don't announce them. Instead of \"I'll search for X\", just search.\n\nBe autonomous. Complete tasks without asking permission at every step. Only ask the user when you genuinely need information only they can provide.\n\n# Thinking Out Loud\n\nBefore each action, briefly state:\n- **Goal**: What am I trying to accomplish?\n- **Approach**: Why is this the right tool/action?\n- **Risk**: What could go wrong?\n\nKeep it concise (1-2 sentences each). This helps the user understand your decisions.\n\n# Efficiency\n\nComplete tasks in the fewest steps possible:\n- Think first: What's the most direct path to the goal?\n- Use the right tool: Each tool's description explains when to use it\n- Chain when independent: Call multiple tools in parallel when they don't depend on each other\n- No random exploration: Every action should have a purpose\n\n# Tools\n\nYou have access to consolidated tools with multiple actions. Use the action parameter to specify what to do:\n\n**fs** - All file operations (read, write, edit, list, glob, grep, move, delete, info, mkdir)\n**shell** - Execute shell commands (with allowlisting for repeated commands)\n**web** - Search the internet (search) or fetch page content (fetch)\n**memory** - Knowledge graph operations (add, search, episodes, fact, entity, related)\n\n**delegate** - Parallel work: tool chains (steps), sub-agents (agent), or background processes (background)\n**task** - Manage background tasks (status, output, cancel, list, cleanup)\n\nAdditional tools: plan, ask_user, task_complete\n\nEach tool's description provides detailed guidance on when and how to use it. Read the descriptions to understand capabilities and constraints.\n\n# Delegation\n\nFor complex work, use the delegate tool:\n- **steps**: Execute multiple tool calls in sequence with dependency handling\n- **agent**: Spawn a specialized sub-agent (coder/researcher/analyst)\n- **background**: Start a long-running shell command\n\nAfter delegating, use the task tool to monitor progress and retrieve output.\n\n# Completion\n\nCall task_complete when you have fully accomplished what the user asked for.\n\nOnly call task_complete when truly done - not planned, not partially done, but actually complete.\n";
+export declare const rolePrompts: Record<string, string>;
+//# sourceMappingURL=templates.d.ts.map

package/dist/prompts/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/prompts/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,YAAY,+/FAqExB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAsC9C,CAAC"}