hanseol-dev 4.0.12

package/dist/agents/docs-search/index.js

@@ -0,0 +1,244 @@
+import { BaseAgent } from '../base/base-agent.js';
+import { DOCS_SEARCH_SYSTEM_PROMPT, buildDocsSearchUserMessage } from '../../prompts/agents/docs-search.js';
+import { DOCS_SEARCH_TOOLS, createDocsToolExecutor } from '../../tools/llm/agents/docs-search-tools.js';
+import { logger } from '../../utils/logger.js';
+let globalProgressCallback = null;
+export function setDocsSearchProgressCallback(callback) {
+    globalProgressCallback = callback;
+}
+const DEFAULT_CONFIG = {
+    temperature: 0.3,
+    maxTokens: 4000,
+};
+const SOFT_ITERATION_LIMIT = 50;
+const HARD_ITERATION_LIMIT = 100;
+export class DocsSearchAgent extends BaseAgent {
+    name = 'DocsSearchAgent';
+    description = 'Searches ~/.hanseol/docs using hierarchical navigation';
+    constructor(llmClient, config) {
+        super(llmClient, { ...DEFAULT_CONFIG, ...config });
+    }
+    getTools() {
+        return DOCS_SEARCH_TOOLS;
+    }
+    buildSystemPrompt(_context) {
+        return DOCS_SEARCH_SYSTEM_PROMPT;
+    }
+    async execute(input, _context) {
+        logger.enter('DocsSearchAgent.execute', { query: input });
+        logger.startTimer('docs-search-total');
+        const progressCallback = globalProgressCallback;
+        progressCallback?.('info', `Searching: "${input.slice(0, 50)}${input.length > 50 ? '...' : ''}"`);
+        let finalResult = null;
+        const toolExecutor = createDocsToolExecutor((message) => {
+            progressCallback?.('tell_user', message);
+            logger.debug('tell_to_user', { message });
+        }, (summary, findings, sources) => {
+            finalResult = { summary, findings, sources };
+            progressCallback?.('complete', summary, { summary, findings, sources });
+            logger.debug('submit_findings', { summary, sourcesCount: sources.length });
+        });
+        try {
+            const messages = [
+                { role: 'system', content: DOCS_SEARCH_SYSTEM_PROMPT },
+                { role: 'user', content: buildDocsSearchUserMessage(input) },
+            ];
+            let iterations = 0;
+            while (!finalResult) {
+                iterations++;
+                if (iterations === SOFT_ITERATION_LIMIT) {
+                    messages.push({
+                        role: 'system',
+                        content: `You have made ${SOFT_ITERATION_LIMIT} tool calls. Please wrap up your search and call submit_findings soon.`,
+                    });
+                    logger.warn('Docs search soft limit reached', { iterations });
+                }
+                if (iterations > HARD_ITERATION_LIMIT) {
+                    logger.error('Docs search hard limit exceeded', { iterations });
+                    return {
+                        success: false,
+                        error: `Search exceeded maximum iterations (${HARD_ITERATION_LIMIT}). Please try a more specific query.`,
+                    };
+                }
+                logger.flow(`Search iteration ${iterations}`);
+                const response = await this.llmClient.chatCompletion({
+                    messages,
+                    tools: DOCS_SEARCH_TOOLS,
+                    temperature: this.config.temperature,
+                    max_tokens: this.config.maxTokens,
+                });
+                const assistantMessage = response.choices[0]?.message;
+                if (!assistantMessage) {
+                    throw new Error('No response from LLM');
+                }
+                messages.push(assistantMessage);
+                if (assistantMessage.tool_calls && assistantMessage.tool_calls.length > 0) {
+                    for (const toolCall of assistantMessage.tool_calls) {
+                        const toolName = toolCall.function.name;
+                        let args;
+                        try {
+                            args = JSON.parse(toolCall.function.arguments);
+                        }
+                        catch {
+                            logger.warn('Failed to parse tool arguments', { toolName });
+                            messages.push({
+                                role: 'tool',
+                                content: 'Error: Invalid tool arguments',
+                                tool_call_id: toolCall.id,
+                            });
+                            continue;
+                        }
+                        progressCallback?.('info', `${toolName}: ${this.formatToolArgs(toolName, args)}`);
+                        const result = await toolExecutor(toolName, args);
+                        messages.push({
+                            role: 'tool',
+                            content: result.success ? (result.result || 'Success') : `Error: ${result.error}`,
+                            tool_call_id: toolCall.id,
+                        });
+                        if (result.terminate) {
+                            break;
+                        }
+                    }
+                }
+                else {
+                    logger.warn('LLM responded without tool calls');
+                    messages.push({
+                        role: 'system',
+                        content: 'You must use tools to search documentation. Call list_directory to explore, or submit_findings to complete.',
+                    });
+                }
+            }
+            const totalElapsed = logger.endTimer('docs-search-total');
+            logger.exit('DocsSearchAgent.execute', { success: true, iterations });
+            return {
+                success: true,
+                result: finalResult ? this.formatFinalResult(finalResult) : 'Error: Search completed without findings.',
+                metadata: {
+                    iterations,
+                    duration: totalElapsed,
+                },
+            };
+        }
+        catch (error) {
+            logger.endTimer('docs-search-total');
+            logger.error('Documentation Search Failed', error instanceof Error ? error : new Error(String(error)));
+            progressCallback?.('complete', 'Search failed', { summary: 'Error occurred', findings: '', sources: [] });
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error in docs search',
+            };
+        }
+    }
+    formatToolArgs(toolName, args) {
+        const reason = args['reason'];
+        switch (toolName) {
+            case 'list_directory':
+                return reason || (args['path'] ? `"${args['path']}"` : '(root)');
+            case 'read_docs_file':
+            case 'preview_file':
+                return reason || `"${args['path']}"`;
+            case 'tell_to_user':
+                return args['message']?.slice(0, 50) || '';
+            case 'submit_findings':
+                return 'Submitting report...';
+            default:
+                return JSON.stringify(args).slice(0, 50);
+        }
+    }
+    formatFinalResult(result) {
+        const parts = [];
+        parts.push(`## Summary\n${result.summary}`);
+        parts.push(`\n## Findings\n${result.findings}`);
+        if (result.sources.length > 0) {
+            parts.push(`\n## Sources`);
+            result.sources.forEach(source => {
+                parts.push(`- ${source}`);
+            });
+        }
+        return parts.join('\n');
+    }
+}
+export function createDocsSearchAgent(llmClient, config) {
+    return new DocsSearchAgent(llmClient, config);
+}
+export async function executeDocsSearchAgent(llmClient, query) {
+    const agent = new DocsSearchAgent(llmClient);
+    return agent.execute(query);
+}
+export async function initializeDocsDirectory() {
+    const fs = await import('fs/promises');
+    const path = await import('path');
+    const os = await import('os');
+    const docsPath = path.join(os.homedir(), '.hanseol', 'docs');
+    try {
+        await fs.mkdir(docsPath, { recursive: true });
+        const readmePath = path.join(docsPath, 'README.md');
+        try {
+            await fs.access(readmePath);
+        }
+        catch {
+            const sampleReadme = `# 한설 Documentation
+
+Welcome to the 한설 documentation directory!
+
+## Overview
+
+This directory contains local documentation that can be searched by the AI assistant.
+
+## Adding Documentation
+
+Simply place your markdown (.md) files in this directory. The AI will be able to search and reference them.
+
+## Folder Structure
+
+Organize your documentation hierarchically:
+- Create folders for major categories
+- Use sub-folders for specific topics
+- Place .md files at appropriate levels
+
+Example:
+\`\`\`
+~/.hanseol/docs/
+├── README.md
+├── tutorials/
+│   ├── getting-started.md
+│   └── advanced-usage.md
+├── reference/
+│   ├── api.md
+│   └── configuration.md
+└── agent_framework/
+    ├── agno/
+    │   ├── overview.md
+    │   └── examples.md
+    └── langchain/
+        └── setup.md
+\`\`\`
+`;
+            await fs.writeFile(readmePath, sampleReadme, 'utf-8');
+        }
+    }
+    catch (error) {
+        logger.error('Failed to initialize docs directory', error instanceof Error ? error : new Error(String(error)));
+    }
+}
+export async function addDocumentationFile(filename, content) {
+    try {
+        const fs = await import('fs/promises');
+        const pathModule = await import('path');
+        const os = await import('os');
+        const docsPath = pathModule.join(os.homedir(), '.hanseol', 'docs');
+        await fs.mkdir(docsPath, { recursive: true });
+        const sanitizedFilename = pathModule.basename(filename);
+        const filePath = pathModule.join(docsPath, sanitizedFilename);
+        await fs.writeFile(filePath, content, 'utf-8');
+        return { success: true, path: filePath };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to add documentation',
+        };
+    }
+}
+export default DocsSearchAgent;
+//# sourceMappingURL=index.js.map

package/dist/agents/docs-search/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agents/docs-search/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,SAAS,EAA0C,MAAM,uBAAuB,CAAC;AAG1F,OAAO,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AAC5G,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACxG,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAc/C,IAAI,sBAAsB,GAAsC,IAAI,CAAC;AAKrE,MAAM,UAAU,6BAA6B,CAAC,QAA2C;IACvF,sBAAsB,GAAG,QAAQ,CAAC;AACpC,CAAC;AAKD,MAAM,cAAc,GAAgB;IAClC,WAAW,EAAE,GAAG;IAChB,SAAS,EAAE,IAAI;CAEhB,CAAC;AAKF,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAChC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAKjC,MAAM,OAAO,eAAgB,SAAQ,SAAS;IACnC,IAAI,GAAG,iBAAiB,CAAC;IACzB,WAAW,GAAG,wDAAwD,CAAC;IAEhF,YAAY,SAAoB,EAAE,MAA6B;QAC7D,KAAK,CAAC,SAAS,EAAE,EAAE,GAAG,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IACrD,CAAC;IAES,QAAQ;QAChB,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IAES,iBAAiB,CAAC,QAAuB;QACjD,OAAO,yBAAyB,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,KAAa,EAAE,QAAuB;QAClD,MAAM,CAAC,KAAK,CAAC,yBAAyB,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1D,MAAM,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC;QAEvC,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;QAChD,gBAAgB,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAGlG,IAAI,WAAW,GAIJ,IAAI,CAAC;QAGhB,MAAM,YAAY,GAAG,sBAAsB,CAEzC,CAAC,OAAe,EAAE,EAAE;YAClB,gBAAgB,EAAE,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YACzC,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAC5C,CAAC,EAED,CAAC,OAAe,EAAE,QAAgB,EAAE,OAAiB,EAAE,EAAE;YACvD,WAAW,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;YAC7C,gBAAgB,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;YACxE,MAAM,CAAC,KAAK,CAAC,iBAAiB,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7E,CAAC,CACF,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,QAAQ,GAAc;gBAC1B,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,yBAAyB,EAAE;gBACtD,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,CAAC,KAAK,CAAC,EAAE;aAC7D,CAAC;YAEF,IAAI,UAAU,GAAG,CAAC,CAAC;YAGnB,OAAO,CAAC,WAAW,EAAE,CAAC;gBACpB,UAAU,EAAE,CAAC;gBAGb,IAAI,UAAU,KAAK,oBAAoB,EAAE,CAAC;oBACxC,QAAQ,CAAC,IAAI,CAAC;wBACZ,IAAI,EAAE,QAAQ;wBACd,OAAO,EAAE,iBAAiB,oBAAoB,wEAAwE;qBACvH,CAAC,CAAC;oBACH,MAAM,CAAC,IAAI,CAAC,gCAAgC,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;gBAChE,CAAC;gBAGD,IAAI,UAAU,GAAG,oBAAoB,EAAE,CAAC;oBACtC,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;oBAChE,OAAO;wBACL,OAAO,EAAE,KAAK;wBACd,KAAK,EAAE,uCAAuC,oBAAoB,sCAAsC;qBACzG,CAAC;gBACJ,CAAC;gBAED,MAAM,CAAC,IAAI,CAAC,oBAAoB,UAAU,EAAE,CAAC,CAAC;gBAG9C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC;oBACnD,QAAQ;oBACR,KAAK,EAAE,iBAAiB;oBACxB,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;oBACpC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;iBAClC,CAAC,CAAC;gBAEH,MAAM,gBAAgB,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC;gBACtD,IAAI,CAAC,gBAAgB,EAAE,CAAC;oBACtB,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;gBAC1C,CAAC;gBAED,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;gBAGhC,IAAI,gBAAgB,CAAC,UAAU,IAAI,gBAAgB,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC1E,KAAK,MAAM,QAAQ,IAAI,gBAAgB,CAAC,UAAU,EAAE,CAAC;wBACnD,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;wBACxC,IAAI,IAA6B,CAAC;wBAElC,IAAI,CAAC;4BACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;wBACjD,CAAC;wBAAC,MAAM,CAAC;4BACP,MAAM,CAAC,IAAI,CAAC,gCAAgC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;4BAC5D,QAAQ,CAAC,IAAI,CAAC;gCACZ,IAAI,EAAE,MAAM;gCACZ,OAAO,EAAE,+BAA+B;gCACxC,YAAY,EAAE,QAAQ,CAAC,EAAE;6BAC1B,CAAC,CAAC;4BACH,SAAS;wBACX,CAAC;wBAGD,gBAAgB,EAAE,CAAC,MAAM,EAAE,GAAG,QAAQ,KAAK,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;wBAGlF,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;wBAElD,QAAQ,CAAC,IAAI,CAAC;4BACZ,IAAI,EAAE,MAAM;4BACZ,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,UAAU,MAAM,CAAC,KAAK,EAAE;4BACjF,YAAY,EAAE,QAAQ,CAAC,EAAE;yBAC1B,CAAC,CAAC;wBAGH,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;4BACrB,MAAM;wBACR,CAAC;oBACH,CAAC;gBACH,CAAC;qBAAM,CAAC;oBAGN,MAAM,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;oBAChD,QAAQ,CAAC,IAAI,CAAC;wBACZ,IAAI,EAAE,QAAQ;wBACd,OAAO,EAAE,6GAA6G;qBACvH,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YAED,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;YAC1D,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;YAEtE,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,2CAA2C;gBACvG,QAAQ,EAAE;oBACR,UAAU;oBACV,QAAQ,EAAE,YAAY;iBACvB;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;YACrC,MAAM,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACvG,gBAAgB,EAAE,CAAC,UAAU,EAAE,eAAe,EAAE,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;YAE1G,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,8BAA8B;aAC/E,CAAC;QACJ,CAAC;IACH,CAAC;IAMO,cAAc,CAAC,QAAgB,EAAE,IAA6B;QACpE,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAuB,CAAC;QAEpD,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,gBAAgB;gBACnB,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YACnE,KAAK,gBAAgB,CAAC;YACtB,KAAK,cAAc;gBACjB,OAAO,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;YACvC,KAAK,cAAc;gBACjB,OAAQ,IAAI,CAAC,SAAS,CAAY,EAAE,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;YACzD,KAAK,iBAAiB;gBACpB,OAAO,sBAAsB,CAAC;YAChC;gBACE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAKO,iBAAiB,CAAC,MAAgE;QACxF,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,KAAK,CAAC,IAAI,CAAC,eAAe,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5C,KAAK,CAAC,IAAI,CAAC,kBAAkB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEhD,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAC3B,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;gBAC9B,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;YAC5B,CAAC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF;AAKD,MAAM,UAAU,qBAAqB,CAAC,SAAoB,EAAE,MAA6B;IACvF,OAAO,IAAI,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAChD,CAAC;AAKD,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,SAAoB,EACpB,KAAa;IAEb,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC,SAAS,CAAC,CAAC;IAC7C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAKD,MAAM,CAAC,KAAK,UAAU,uBAAuB;IAC3C,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;IAE9B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAE7D,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE9C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoC1B,CAAC;YACI,MAAM,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,qCAAqC,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACjH,CAAC;AACH,CAAC;AAKD,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,QAAgB,EAChB,OAAe;IAEf,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACvC,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QAE9B,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;QACnE,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE9C,MAAM,iBAAiB,GAAG,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACxD,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;QAE9D,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAE/C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,6BAA6B;SAC9E,CAAC;IACJ,CAAC;AACH,CAAC;AAED,eAAe,eAAe,CAAC"}

package/dist/agents/index.d.ts

@@ -0,0 +1,4 @@
+export { BaseAgent, type AgentContext, type AgentResult, type AgentConfig, } from './base/base-agent.js';
+export { PlanningLLM, type PlanningWithDocsResult, } from './planner/index.js';
+export { DocsSearchAgent, createDocsSearchAgent, executeDocsSearchAgent, initializeDocsDirectory, addDocumentationFile, setDocsSearchProgressCallback, type DocsSearchProgressCallback, } from './docs-search/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,GACjB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,WAAW,EACX,KAAK,sBAAsB,GAC5B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,6BAA6B,EAC7B,KAAK,0BAA0B,GAChC,MAAM,wBAAwB,CAAC"}

package/dist/agents/index.js

@@ -0,0 +1,4 @@
+export { BaseAgent, } from './base/base-agent.js';
+export { PlanningLLM, } from './planner/index.js';
+export { DocsSearchAgent, createDocsSearchAgent, executeDocsSearchAgent, initializeDocsDirectory, addDocumentationFile, setDocsSearchProgressCallback, } from './docs-search/index.js';
+//# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,SAAS,GAIV,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,WAAW,GAEZ,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,6BAA6B,GAE9B,MAAM,wBAAwB,CAAC"}

package/dist/agents/planner/index.d.ts

@@ -0,0 +1,19 @@
+import { LLMClient } from '../../core/llm/llm-client.js';
+import { Message, PlanningResult } from '../../types/index.js';
+import { AskUserCallback } from '../../tools/llm/simple/user-interaction-tools.js';
+export interface PlanningWithDocsResult extends PlanningResult {
+    docsSearchNeeded: boolean;
+}
+export declare class PlanningLLM {
+    private llmClient;
+    private askUserCallback;
+    constructor(llmClient: LLMClient);
+    setAskUserCallback(callback: AskUserCallback): void;
+    clearAskUserCallback(): void;
+    generateTODOList(userRequest: string, contextMessages?: Message[]): Promise<PlanningResult>;
+    generateTODOListWithDocsDecision(userRequest: string, contextMessages?: Message[]): Promise<PlanningWithDocsResult>;
+    private shouldSearchDocs;
+    private getDocsFolderStructure;
+}
+export default PlanningLLM;
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/planner/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/planner/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAAE,OAAO,EAAY,cAAc,EAAc,MAAM,sBAAsB,CAAC;AASrF,OAAO,EAEL,eAAe,EAChB,MAAM,kDAAkD,CAAC;AAK1D,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAOD,qBAAa,WAAW;IACtB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,eAAe,CAAgC;gBAE3C,SAAS,EAAE,SAAS;IAQhC,kBAAkB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAQnD,oBAAoB,IAAI,IAAI;IAatB,gBAAgB,CACpB,WAAW,EAAE,MAAM,EACnB,eAAe,CAAC,EAAE,OAAO,EAAE,GAC1B,OAAO,CAAC,cAAc,CAAC;IA8RpB,gCAAgC,CACpC,WAAW,EAAE,MAAM,EACnB,eAAe,CAAC,EAAE,OAAO,EAAE,GAC1B,OAAO,CAAC,sBAAsB,CAAC;YA+CpB,gBAAgB;YA+DhB,sBAAsB;CA2CrC;AAED,eAAe,WAAW,CAAC"}

package/dist/agents/planner/index.js

@@ -0,0 +1,339 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { logger } from '../../utils/logger.js';
+import { buildPlanningSystemPrompt } from '../../prompts/agents/planning.js';
+import { toolRegistry } from '../../tools/registry.js';
+import { buildDocsSearchDecisionPrompt, parseDocsSearchDecision, DOCS_SEARCH_DECISION_RETRY_PROMPT, } from '../../prompts/agents/docs-search-decision.js';
+export class PlanningLLM {
+    llmClient;
+    askUserCallback = null;
+    constructor(llmClient) {
+        this.llmClient = llmClient;
+    }
+    setAskUserCallback(callback) {
+        logger.flow('Setting ask-user callback for Planning LLM');
+        this.askUserCallback = callback;
+    }
+    clearAskUserCallback() {
+        logger.flow('Clearing ask-user callback for Planning LLM');
+        this.askUserCallback = null;
+    }
+    async generateTODOList(userRequest, contextMessages) {
+        const toolSummary = toolRegistry.getToolSummaryForPlanning();
+        const optionalToolsInfo = toolRegistry.getEnabledOptionalToolsInfo();
+        const systemPrompt = buildPlanningSystemPrompt(toolSummary, optionalToolsInfo);
+        const clarificationMessages = [];
+        const messages = [
+            {
+                role: 'system',
+                content: systemPrompt,
+            },
+        ];
+        if (contextMessages && contextMessages.length > 0) {
+            const conversationMsgs = contextMessages.filter(m => m.role !== 'system');
+            messages.push(...conversationMsgs);
+        }
+        const lastMsg = messages[messages.length - 1];
+        if (!(lastMsg?.role === 'user' && lastMsg?.content === userRequest)) {
+            messages.push({
+                role: 'user',
+                content: `[NEW REQUEST]\n${userRequest}`,
+            });
+        }
+        const planningTools = toolRegistry.getLLMPlanningToolDefinitions();
+        const MAX_RETRIES = 3;
+        let lastError = null;
+        while (true) {
+            let shouldContinueMainLoop = false;
+            for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+                try {
+                    if (attempt > 1) {
+                        messages.push({
+                            role: 'user',
+                            content: `[RETRY ${attempt}/${MAX_RETRIES}] ⚠️ CRITICAL: You are the PLANNING LLM, not the Execution LLM.
+
+You have ONLY 3 tools available:
+1. 'ask_to_user' - To clarify ambiguous requirements (use FIRST if unclear)
+2. 'create_todos' - For ANY action/implementation request
+3. 'respond_to_user' - For pure knowledge questions/greetings only
+
+❌ DO NOT use tools like 'write_todos', 'read_file', 'bash', etc. Those are for Execution LLM, NOT you.
+❌ You saw those tools in conversation history, but they are NOT available to you.
+
+Previous error: ${lastError?.message || 'Invalid response'}
+
+Choose one of your 3 tools now.`,
+                        });
+                        logger.warn(`Planning LLM retry attempt ${attempt}/${MAX_RETRIES}`, { lastError: lastError?.message });
+                    }
+                    const response = await this.llmClient.chatCompletion({
+                        messages,
+                        tools: planningTools,
+                        tool_choice: 'required',
+                        temperature: 0.7,
+                        max_tokens: 2000,
+                    });
+                    const choicesCount = response.choices?.length ?? 0;
+                    const message = response.choices?.[0]?.message;
+                    const toolCalls = message?.tool_calls;
+                    const finishReason = response.choices?.[0]?.finish_reason;
+                    logger.debug('Planning LLM response', {
+                        choicesCount,
+                        hasMessage: !!message,
+                        hasToolCalls: !!(toolCalls && toolCalls.length > 0),
+                        hasContent: !!message?.content,
+                        contentLength: message?.content?.length ?? 0,
+                        finishReason,
+                        toolCallsCount: toolCalls?.length ?? 0,
+                    });
+                    if (toolCalls && toolCalls.length > 0) {
+                        const toolCall = toolCalls[0];
+                        const toolName = toolCall.function?.name;
+                        let toolArgs;
+                        try {
+                            toolArgs = JSON.parse(toolCall.function?.arguments || '{}');
+                        }
+                        catch (error) {
+                            logger.warn('Failed to parse tool arguments', { args: toolCall.function?.arguments, error });
+                            lastError = error;
+                            continue;
+                        }
+                        if (toolName === 'ask_to_user') {
+                            logger.flow('Planning LLM asking user for clarification');
+                            const question = toolArgs.question;
+                            const options = toolArgs.options;
+                            if (!question || !Array.isArray(options) || options.length < 2) {
+                                logger.warn('ask_to_user called with invalid parameters', { toolArgs });
+                                lastError = new Error('ask_to_user requires a question and 2-4 options');
+                                continue;
+                            }
+                            if (!this.askUserCallback) {
+                                logger.warn('ask_to_user called but no callback is set, skipping to create_todos');
+                                messages.push({
+                                    role: 'assistant',
+                                    content: `[Planning LLM attempted to ask: "${question}" but user interaction is not available. Proceeding with best judgment.]`,
+                                });
+                                shouldContinueMainLoop = true;
+                                break;
+                            }
+                            try {
+                                const assistantMsg = {
+                                    role: 'assistant',
+                                    content: `[Clarification needed] ${question}\nOptions: ${options.join(', ')}`,
+                                };
+                                messages.push(assistantMsg);
+                                clarificationMessages.push(assistantMsg);
+                                const userResponse = await this.askUserCallback({ question, options });
+                                const userAnswerText = userResponse.isOther && userResponse.customText
+                                    ? userResponse.customText
+                                    : userResponse.selectedOption;
+                                const userMsg = {
+                                    role: 'user',
+                                    content: `[User's answer] ${userAnswerText}`,
+                                };
+                                messages.push(userMsg);
+                                clarificationMessages.push(userMsg);
+                                logger.flow('User responded to clarification question', {
+                                    question,
+                                    answer: userAnswerText,
+                                    isCustom: userResponse.isOther,
+                                });
+                                shouldContinueMainLoop = true;
+                                break;
+                            }
+                            catch (error) {
+                                logger.error('Error during ask_to_user', error);
+                                lastError = error;
+                                continue;
+                            }
+                        }
+                        if (toolName === 'create_todos') {
+                            logger.flow('TODO list created via create_todos tool');
+                            let rawTodos = toolArgs.todos;
+                            if (typeof rawTodos === 'string') {
+                                try {
+                                    rawTodos = JSON.parse(rawTodos);
+                                    logger.debug('Parsed string-wrapped todos array');
+                                }
+                                catch {
+                                    logger.warn('Failed to parse string todos as JSON', { todos: rawTodos });
+                                }
+                            }
+                            if (!Array.isArray(rawTodos)) {
+                                logger.warn('create_todos called with non-array todos', { toolArgs });
+                                lastError = new Error('Planning LLM returned invalid todos format (expected array).');
+                                continue;
+                            }
+                            const todos = rawTodos.map((todo, index) => ({
+                                id: todo.id || `todo-${Date.now()}-${index}`,
+                                title: todo.title || 'Untitled task',
+                                status: (index === 0 ? 'in_progress' : 'pending'),
+                            }));
+                            return {
+                                todos,
+                                complexity: toolArgs.complexity || 'moderate',
+                                clarificationMessages: clarificationMessages.length > 0 ? clarificationMessages : undefined,
+                            };
+                        }
+                        if (toolName === 'respond_to_user') {
+                            logger.flow('Direct response via respond_to_user tool');
+                            const responseText = toolArgs.response || '';
+                            if (!responseText) {
+                                logger.warn('respond_to_user called with empty response');
+                                lastError = new Error('Planning LLM returned empty response.');
+                                continue;
+                            }
+                            return {
+                                todos: [],
+                                complexity: 'simple',
+                                directResponse: responseText,
+                                clarificationMessages: clarificationMessages.length > 0 ? clarificationMessages : undefined,
+                            };
+                        }
+                        logger.warn(`Unknown tool called: ${toolName}`);
+                        lastError = new Error(`Invalid tool "${toolName}". You only have 3 tools: ask_to_user, create_todos, or respond_to_user. Tools like write_todos are for Execution LLM, not Planning LLM.`);
+                        continue;
+                    }
+                    const contentOnly = message?.content;
+                    if (contentOnly) {
+                        logger.warn(`Planning LLM returned content without tool call (attempt ${attempt}/${MAX_RETRIES})`, {
+                            contentPreview: contentOnly.substring(0, 100),
+                        });
+                        lastError = new Error('You MUST call one of your tools: ask_to_user, create_todos, or respond_to_user. Do NOT respond with plain text.');
+                    }
+                    else {
+                        logger.warn(`Planning LLM returned no tool call and no content (attempt ${attempt}/${MAX_RETRIES})`);
+                        lastError = new Error('Planning LLM must use one of: ask_to_user, create_todos, or respond_to_user');
+                    }
+                }
+                catch (error) {
+                    logger.warn(`Planning LLM error (attempt ${attempt}/${MAX_RETRIES}):`, error);
+                    lastError = error;
+                }
+            }
+            if (shouldContinueMainLoop) {
+                continue;
+            }
+            break;
+        }
+        logger.warn('All planning retries exhausted, using fallback TODO', { lastError: lastError?.message });
+        return {
+            todos: [
+                {
+                    id: `todo-${Date.now()}`,
+                    title: userRequest.length > 100 ? userRequest.substring(0, 100) + '...' : userRequest,
+                    status: 'in_progress',
+                },
+            ],
+            complexity: 'simple',
+            clarificationMessages: clarificationMessages.length > 0 ? clarificationMessages : undefined,
+        };
+    }
+    async generateTODOListWithDocsDecision(userRequest, contextMessages) {
+        logger.enter('PlanningLLM.generateTODOListWithDocsDecision', { requestLength: userRequest.length });
+        logger.startTimer('parallel-planning');
+        const [planningResult, docsSearchNeeded] = await Promise.all([
+            this.generateTODOList(userRequest, contextMessages),
+            this.shouldSearchDocs(userRequest),
+        ]);
+        logger.vars({ name: 'todoCount', value: planningResult.todos.length }, { name: 'docsSearchNeeded', value: docsSearchNeeded });
+        if (docsSearchNeeded) {
+            const docsSearchTodo = {
+                id: `todo-docs-${Date.now()}`,
+                title: 'Search local documentation (use call_docs_search_agent)',
+                status: 'pending',
+            };
+            logger.flow('Prepended docs search TODO');
+            logger.endTimer('parallel-planning');
+            logger.exit('PlanningLLM.generateTODOListWithDocsDecision', { docsSearchNeeded: true });
+            return {
+                ...planningResult,
+                todos: [docsSearchTodo, ...planningResult.todos],
+                docsSearchNeeded: true,
+            };
+        }
+        logger.endTimer('parallel-planning');
+        logger.exit('PlanningLLM.generateTODOListWithDocsDecision', { docsSearchNeeded: false });
+        return {
+            ...planningResult,
+            docsSearchNeeded: false,
+        };
+    }
+    async shouldSearchDocs(userMessage) {
+        logger.enter('PlanningLLM.shouldSearchDocs', { messageLength: userMessage.length });
+        const folderStructure = await this.getDocsFolderStructure();
+        if (folderStructure.includes('empty') ||
+            folderStructure.includes('does not exist')) {
+            logger.flow('No docs available, skipping search decision');
+            logger.exit('PlanningLLM.shouldSearchDocs', { decision: false, reason: 'no-docs' });
+            return false;
+        }
+        const prompt = buildDocsSearchDecisionPrompt(folderStructure, userMessage);
+        const messages = [
+            { role: 'user', content: prompt },
+        ];
+        let retries = 0;
+        const MAX_RETRIES = 2;
+        while (retries <= MAX_RETRIES) {
+            logger.flow(`Asking LLM for docs search decision (attempt ${retries + 1})`);
+            const response = await this.llmClient.chatCompletion({
+                messages,
+                temperature: 0.1,
+                max_tokens: 10,
+            });
+            const content = response.choices[0]?.message?.content || '';
+            logger.debug('LLM decision response', { content });
+            const decision = parseDocsSearchDecision(content);
+            if (decision !== null) {
+                logger.exit('PlanningLLM.shouldSearchDocs', { decision, attempts: retries + 1 });
+                return decision;
+            }
+            retries++;
+            if (retries <= MAX_RETRIES) {
+                messages.push({ role: 'assistant', content });
+                messages.push({ role: 'user', content: DOCS_SEARCH_DECISION_RETRY_PROMPT });
+                logger.warn('Invalid decision response, retrying', { response: content });
+            }
+        }
+        logger.warn('All decision retries failed, defaulting to no search');
+        logger.exit('PlanningLLM.shouldSearchDocs', { decision: false, reason: 'retries-exhausted' });
+        return false;
+    }
+    async getDocsFolderStructure() {
+        const docsBasePath = path.join(os.homedir(), '.hanseol', 'docs');
+        try {
+            const entries = await fs.readdir(docsBasePath, { withFileTypes: true });
+            const lines = [];
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    lines.push(`📁 ${entry.name}/`);
+                    try {
+                        const subPath = path.join(docsBasePath, entry.name);
+                        const subEntries = await fs.readdir(subPath, { withFileTypes: true });
+                        const subDirs = subEntries.filter(e => e.isDirectory());
+                        if (subDirs.length > 0) {
+                            const subDirNames = subDirs.map(d => d.name).join(', ');
+                            lines.push(`   └── [${subDirNames}]`);
+                        }
+                    }
+                    catch {
+                    }
+                }
+            }
+            if (lines.length === 0) {
+                return '(empty - no documentation available)';
+            }
+            return lines.join('\n');
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === 'ENOENT') {
+                return '(docs directory does not exist)';
+            }
+            return '(error reading docs directory)';
+        }
+    }
+}
+export default PlanningLLM;
+//# sourceMappingURL=index.js.map