@lovelybunch/api 1.0.69 → 1.0.71-alpha.0

package/dist/routes/api/v1/ai/tools.js

@@ -0,0 +1,926 @@
+import { homedir } from 'os';
+import { join, resolve as pathResolve, basename } from 'path';
+import { existsSync, readFileSync, promises as fs, createReadStream } from 'fs';
+import readline from 'readline';
+import { getLogsDir } from '@lovelybunch/core';
+import { proposalsReadOnlyTool, knowledgeTool, normalizeKnowledgeMetadata, eventsTool, projectContextTool, architectureContextTool } from '@lovelybunch/mcp';
+import matter from 'gray-matter';
+import { FileStorageAdapter } from '../../../../lib/storage/file-storage.js';
+// Function to get global config API key as fallback
+function getGlobalApiKey(provider) {
+    try {
+        const platform = process.platform;
+        let configDir;
+        if (platform === 'win32') {
+            configDir = join(process.env.APPDATA || homedir(), 'coconuts');
+        }
+        else if (platform === 'darwin') {
+            configDir = join(homedir(), 'Library', 'Application Support', 'coconuts');
+        }
+        else {
+            configDir = join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'coconuts');
+        }
+        const configFile = join(configDir, 'config.json');
+        if (!existsSync(configFile)) {
+            return null;
+        }
+        const config = JSON.parse(readFileSync(configFile, 'utf-8'));
+        return config.apiKeys?.[provider] || null;
+    }
+    catch (error) {
+        return null;
+    }
+}
+/**
+ * POST /api/v1/ai/tools
+ * Execute tool calls that were detected during streaming
+ */
+export async function POST(c) {
+    try {
+        const { toolCalls, model, history, context, contextContent, agentPersona, attachedContextFiles, previousContent } = await c.req.json();
+        if (!toolCalls || !Array.isArray(toolCalls) || toolCalls.length === 0) {
+            return c.json({ error: "Tool calls are required" }, 400);
+        }
+        let openRouterKey = getGlobalApiKey('openrouter') || process.env.OPENROUTER_API_KEY;
+        if (!openRouterKey) {
+            return c.json({
+                error: "OpenRouter API key not configured",
+                hint: "Set via 'coconut config set-key -p openrouter -k <KEY>' or set OPENROUTER_API_KEY env var"
+            }, 500);
+        }
+        // Execute all tool calls
+        const toolResults = await executeToolCalls(toolCalls);
+        // Build the system prompt
+        const baseSystem = getSystemPrompt(context, contextContent);
+        const systemPrompt = agentPersona
+            ? `${baseSystem}\n\nThe following persona is authoritative and overrides general guidance above. You must strictly follow it.\n\n${agentPersona}`
+            : baseSystem;
+        // Build context messages from attached files
+        const contextMessages = Array.isArray(attachedContextFiles)
+            ? attachedContextFiles
+                .filter((file) => file && typeof file.content === 'string' && file.content.trim().length > 0)
+                .map((file) => ({
+                role: 'system',
+                content: `[ATTACHED CONTEXT - FULL CONTENT INCLUDED BELOW - DO NOT USE TOOLS TO FETCH THIS FILE]\nDocument: ${file.name || file.path || 'reference'}\nType: ${file.type || 'context'}\n\n--- BEGIN CONTENT ---\n${file.content}\n--- END CONTENT ---`
+            }))
+            : [];
+        // Reconstruct the conversation with tool results
+        const sanitizedHistory = Array.isArray(history)
+            ? history.filter((m) => m && (m.role === 'user' || m.role === 'assistant') && typeof m.content === 'string')
+            : [];
+        // Build the assistant message that triggered the tool calls
+        const assistantMessage = {
+            role: 'assistant',
+            content: previousContent || null,
+            tool_calls: toolCalls.map((tc) => ({
+                id: tc.id,
+                type: tc.type || 'function',
+                function: tc.function
+            }))
+        };
+        // Build tool result messages
+        const toolResultMessages = toolResults.map((result) => ({
+            role: 'tool',
+            content: result.content,
+            tool_call_id: result.tool_call_id
+        }));
+        let messagesPayload = [
+            { role: 'system', content: systemPrompt },
+            ...contextMessages,
+            ...sanitizedHistory,
+            assistantMessage,
+            ...toolResultMessages
+        ];
+        // Prepare tools for potential additional tool calls
+        // Note: proposals is read-only, knowledge/project/architecture are read+write, events is read-only
+        const tools = [
+            {
+                type: "function",
+                function: proposalsReadOnlyTool
+            },
+            {
+                type: "function",
+                function: knowledgeTool
+            },
+            {
+                type: "function",
+                function: eventsTool
+            },
+            {
+                type: "function",
+                function: projectContextTool
+            },
+            {
+                type: "function",
+                function: architectureContextTool
+            }
+        ];
+        // Accumulate all tool calls and results across multiple rounds
+        const allToolCalls = [...toolCalls];
+        const allToolResults = [...toolResults];
+        // Maximum iterations - keep at 1 for simplicity and reliability
+        // The AI is instructed to do one operation at a time
+        const MAX_TOOL_ITERATIONS = 1;
+        let iterations = 0;
+        let finalContent = '';
+        // Loop until AI gives a response without tool calls
+        while (iterations < MAX_TOOL_ITERATIONS) {
+            iterations++;
+            const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+                method: "POST",
+                headers: {
+                    "Authorization": `Bearer ${openRouterKey}`,
+                    "Content-Type": "application/json",
+                    "HTTP-Referer": process.env.NEXT_PUBLIC_SITE_URL || "http://localhost:3001",
+                    "X-Title": "Coconut AI Assistant",
+                },
+                body: JSON.stringify({
+                    model: model || "openai/gpt-4o",
+                    messages: messagesPayload,
+                    temperature: 0.5,
+                    max_tokens: 4000,
+                    tools: tools,
+                    tool_choice: "auto"
+                }),
+            });
+            if (!response.ok) {
+                const error = await response.text();
+                console.error("OpenRouter API error for tool follow-up:", error);
+                return c.json({ error: "Failed to get AI response after tool execution" }, 500);
+            }
+            const data = await response.json();
+            const message = data.choices?.[0]?.message;
+            if (!message) {
+                console.error("No message in tool follow-up response");
+                break;
+            }
+            // Accumulate content if present
+            if (message.content) {
+                finalContent += (finalContent ? '\n\n' : '') + message.content;
+            }
+            // Check if AI wants to make more tool calls
+            if (message.tool_calls && message.tool_calls.length > 0) {
+                console.log(`Tool iteration ${iterations}: AI requested ${message.tool_calls.length} more tool call(s)`);
+                // Execute the new tool calls
+                const newToolResults = await executeToolCalls(message.tool_calls);
+                // Accumulate tool calls and results
+                allToolCalls.push(...message.tool_calls);
+                allToolResults.push(...newToolResults);
+                // Add the assistant's tool call message and results to the conversation
+                messagesPayload = [
+                    ...messagesPayload,
+                    {
+                        role: 'assistant',
+                        content: message.content || null,
+                        tool_calls: message.tool_calls
+                    },
+                    ...newToolResults.map((result) => ({
+                        role: 'tool',
+                        content: result.content,
+                        tool_call_id: result.tool_call_id
+                    }))
+                ];
+                // Continue loop to get next response
+                continue;
+            }
+            // No more tool calls - we have the final response
+            break;
+        }
+        if (iterations >= MAX_TOOL_ITERATIONS && allToolCalls.length > 0) {
+            // Don't add the note if we completed successfully
+            const hasErrors = allToolResults.some(r => {
+                try {
+                    return !JSON.parse(r.content).success;
+                }
+                catch {
+                    return true;
+                }
+            });
+            if (!hasErrors) {
+                finalContent += '\n\nOperation completed. Let me know if you need anything else created.';
+            }
+        }
+        // Check if any tool results had errors
+        const failedResults = allToolResults.filter(r => {
+            try {
+                const parsed = JSON.parse(r.content);
+                return !parsed.success;
+            }
+            catch {
+                return true;
+            }
+        });
+        if (failedResults.length > 0 && !finalContent.includes('encountered')) {
+            finalContent += `\n\n*Note: ${failedResults.length} tool operation(s) encountered errors. You can ask me to retry those.*`;
+        }
+        return c.json({
+            response: finalContent || "Tool execution completed",
+            toolCalls: allToolCalls,
+            toolResults: allToolResults
+        });
+    }
+    catch (error) {
+        console.error("Tool execution API error:", error);
+        return c.json({ error: "Internal server error" }, 500);
+    }
+}
+async function executeToolCalls(toolCalls) {
+    const storage = new FileStorageAdapter();
+    const resultPromises = toolCalls.map(async (toolCall) => {
+        try {
+            const functionName = toolCall.function?.name || toolCall.name;
+            // Parse function arguments with error handling for malformed JSON
+            let functionArgs;
+            try {
+                if (toolCall.function?.arguments && typeof toolCall.function.arguments === 'string') {
+                    // Try to sanitize common JSON issues before parsing
+                    let argsStr = toolCall.function.arguments;
+                    // Remove trailing commas before ] or }
+                    argsStr = argsStr.replace(/,(\s*[}\]])/g, '$1');
+                    // Try parsing the sanitized string
+                    functionArgs = JSON.parse(argsStr);
+                }
+                else {
+                    functionArgs = toolCall.function?.arguments || toolCall.arguments;
+                }
+            }
+            catch (parseError) {
+                console.error('Failed to parse tool arguments:', {
+                    functionName,
+                    arguments: toolCall.function?.arguments?.substring(0, 500),
+                    error: parseError instanceof Error ? parseError.message : 'Unknown parse error'
+                });
+                return {
+                    tool_call_id: toolCall.id,
+                    content: JSON.stringify({
+                        success: false,
+                        error: `Invalid tool arguments: ${parseError instanceof Error ? parseError.message : 'JSON parse error'}. Please retry with simpler content.`
+                    })
+                };
+            }
+            let result = { success: false, error: 'Unknown tool' };
+            if (functionName === 'change_proposals') {
+                result = await executeProposalsToolDirect(functionArgs, storage);
+            }
+            else if (functionName === 'knowledge_documents') {
+                result = await executeKnowledgeToolDirect(functionArgs);
+            }
+            else if (functionName === 'activity_events') {
+                result = await executeEventsToolDirect(functionArgs);
+            }
+            else if (functionName === 'project_context') {
+                result = await executeProjectContextToolDirect(functionArgs);
+            }
+            else if (functionName === 'architecture_context') {
+                result = await executeArchitectureContextToolDirect(functionArgs);
+            }
+            return {
+                tool_call_id: toolCall.id,
+                content: JSON.stringify({
+                    success: result.success,
+                    data: result.data,
+                    message: result.message,
+                    error: result.error
+                })
+            };
+        }
+        catch (error) {
+            return {
+                tool_call_id: toolCall.id,
+                content: JSON.stringify({
+                    success: false,
+                    error: error instanceof Error ? error.message : 'Unknown error'
+                })
+            };
+        }
+    });
+    return Promise.all(resultPromises);
+}
+// Proposals tool is READ-ONLY - only list and get operations are supported
+async function executeProposalsToolDirect(args, storage) {
+    const { operation, id, filters } = args;
+    try {
+        switch (operation) {
+            case 'list': {
+                const proposals = await storage.listCPs(filters || {});
+                return {
+                    success: true,
+                    data: proposals,
+                    message: `Found ${proposals.length} proposals`
+                };
+            }
+            case 'get': {
+                if (!id) {
+                    return { success: false, error: 'Proposal ID is required for get operation' };
+                }
+                const proposal = await storage.getCP(id);
+                if (!proposal) {
+                    return { success: false, error: 'Proposal not found' };
+                }
+                return {
+                    success: true,
+                    data: proposal,
+                    message: `Retrieved proposal ${id}`
+                };
+            }
+            default:
+                return { success: false, error: `Proposals are read-only. Only 'list' and 'get' operations are supported. To create proposals, use a coding agent (Claude Code, Cursor, etc.) or the Proposals UI.` };
+        }
+    }
+    catch (error) {
+        console.error('Error executing proposals tool:', error);
+        return { success: false, error: error.message || 'Tool execution failed' };
+    }
+}
+// Helper to strip undefined/null values from an object (gray-matter can't handle them)
+function stripUndefined(obj) {
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        const value = obj[key];
+        if (value !== undefined && value !== null) {
+            if (Array.isArray(value)) {
+                // Filter out undefined/null from arrays too
+                result[key] = value.filter(v => v !== undefined && v !== null);
+            }
+            else if (typeof value === 'object' && !Array.isArray(value)) {
+                // Recursively strip nested objects
+                const stripped = stripUndefined(value);
+                if (Object.keys(stripped).length > 0) {
+                    result[key] = stripped;
+                }
+            }
+            else {
+                result[key] = value;
+            }
+        }
+    }
+    return result;
+}
+async function executeKnowledgeToolDirect(args) {
+    const { operation, filename, title, content, metadata, summary, query } = args;
+    try {
+        const knowledgePath = getKnowledgeBasePath();
+        await fs.mkdir(knowledgePath, { recursive: true });
+        switch (operation) {
+            case 'list': {
+                const searchQuery = query && typeof query === 'string' ? query : undefined;
+                const documents = await listKnowledgeDocuments(knowledgePath, searchQuery);
+                return {
+                    success: true,
+                    data: documents,
+                    message: searchQuery
+                        ? `Found ${documents.length} knowledge documents matching "${searchQuery}"`
+                        : `Found ${documents.length} knowledge documents`
+                };
+            }
+            case 'get': {
+                if (!filename) {
+                    return { success: false, error: 'Filename is required for get operation' };
+                }
+                const document = await readKnowledgeDocument(knowledgePath, filename);
+                if (!document) {
+                    return { success: false, error: 'Knowledge document not found' };
+                }
+                return {
+                    success: true,
+                    data: document,
+                    message: `Loaded knowledge document ${document.filename}`
+                };
+            }
+            case 'create': {
+                if (!title || !content) {
+                    return { success: false, error: 'Title and content are required for create operation' };
+                }
+                const targetFilename = resolveKnowledgeFilename(filename, title);
+                const filePath = join(knowledgePath, targetFilename);
+                try {
+                    await fs.access(filePath);
+                    return { success: false, error: 'A knowledge document with this filename already exists' };
+                }
+                catch {
+                    // File does not exist - good
+                }
+                // Build clean metadata with defaults, stripping any undefined values
+                const baseMetadata = {
+                    version: '1.0',
+                    updated: new Date().toISOString().split('T')[0],
+                    type: 'knowledge',
+                    tags: [],
+                    sources: [],
+                    related: [],
+                    audience: []
+                };
+                // Only add summary if it's a valid string
+                if (typeof summary === 'string' && summary.trim()) {
+                    baseMetadata.summary = summary.trim();
+                }
+                // Merge with provided metadata, but strip undefined values
+                const safeMetadata = metadata && typeof metadata === 'object'
+                    ? stripUndefined(metadata)
+                    : {};
+                const finalMetadata = stripUndefined({
+                    ...baseMetadata,
+                    ...safeMetadata
+                });
+                const markdown = matter.stringify(content, finalMetadata);
+                await fs.writeFile(filePath, markdown, 'utf-8');
+                return {
+                    success: true,
+                    data: {
+                        filename: targetFilename,
+                        title,
+                        metadata: finalMetadata,
+                        content
+                    },
+                    message: `Created knowledge document ${targetFilename}`
+                };
+            }
+            case 'update': {
+                if (!filename || !content) {
+                    return { success: false, error: 'Filename and content are required for update operation' };
+                }
+                const currentFilename = resolveKnowledgeFilename(filename, title || 'knowledge-entry');
+                const currentPath = join(knowledgePath, currentFilename);
+                let existingDocument = null;
+                try {
+                    existingDocument = await readKnowledgeDocument(knowledgePath, currentFilename);
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT') {
+                        return { success: false, error: 'Knowledge document not found' };
+                    }
+                    throw error;
+                }
+                if (!existingDocument) {
+                    return { success: false, error: 'Knowledge document not found' };
+                }
+                const nextTitle = title || existingDocument.title;
+                const shouldRename = Boolean(title && slugify(title) !== slugify(existingDocument.title));
+                const nextFilename = shouldRename ? resolveKnowledgeFilename(undefined, nextTitle) : currentFilename;
+                const nextPath = join(knowledgePath, nextFilename);
+                if (nextFilename !== currentFilename) {
+                    try {
+                        await fs.access(nextPath);
+                        return { success: false, error: 'A document with the requested title already exists' };
+                    }
+                    catch {
+                        // Safe to rename
+                    }
+                }
+                // Safely merge metadata, stripping undefined values
+                const safeExistingMetadata = stripUndefined(existingDocument.metadata || {});
+                const safeNewMetadata = metadata && typeof metadata === 'object'
+                    ? stripUndefined(metadata)
+                    : {};
+                const mergedMetadata = stripUndefined({
+                    ...safeExistingMetadata,
+                    ...safeNewMetadata,
+                    updated: new Date().toISOString().split('T')[0],
+                    ...(typeof summary === 'string' && summary.trim() ? { summary: summary.trim() } : {})
+                });
+                const markdown = matter.stringify(content, mergedMetadata);
+                await fs.writeFile(nextPath, markdown, 'utf-8');
+                if (nextFilename !== currentFilename) {
+                    await fs.unlink(currentPath);
+                }
+                return {
+                    success: true,
+                    data: {
+                        filename: nextFilename,
+                        title: nextTitle,
+                        metadata: mergedMetadata,
+                        content
+                    },
+                    message: `Updated knowledge document ${nextFilename}`
+                };
+            }
+            default:
+                return { success: false, error: `Unknown operation: ${operation}` };
+        }
+    }
+    catch (error) {
+        console.error('Error executing knowledge tool:', error);
+        return { success: false, error: error.message || 'Knowledge tool execution failed' };
+    }
+}
+// Events tool is READ-ONLY - returns recent activity events
+async function executeEventsToolDirect(args) {
+    const { operation, limit = 20, kind } = args;
+    if (operation !== 'list') {
+        return {
+            success: false,
+            error: `Events are read-only. Only 'list' operation is supported.`
+        };
+    }
+    try {
+        const eventsDir = getLogsDir();
+        const currentFile = join(eventsDir, 'events-current.jsonl');
+        // Check if file exists
+        try {
+            await fs.access(currentFile);
+        }
+        catch {
+            return {
+                success: true,
+                data: [],
+                message: 'No events found'
+            };
+        }
+        // Read all events from file
+        const allEvents = [];
+        const fileStream = createReadStream(currentFile);
+        const rl = readline.createInterface({
+            input: fileStream,
+            crlfDelay: Infinity,
+        });
+        for await (const line of rl) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                // Apply kind filter if specified
+                if (kind && typeof kind === 'string') {
+                    if (!event.kind || !event.kind.startsWith(kind)) {
+                        continue;
+                    }
+                }
+                allEvents.push(event);
+            }
+            catch {
+                // Skip malformed lines
+                continue;
+            }
+        }
+        // Sort by seq descending (most recent first) and limit
+        const cappedLimit = Math.min(Math.max(1, limit), 100);
+        const sortedEvents = allEvents
+            .sort((a, b) => (b.seq || 0) - (a.seq || 0))
+            .slice(0, cappedLimit);
+        // Format events for readability
+        const formattedEvents = sortedEvents.map(event => ({
+            seq: event.seq,
+            kind: event.kind,
+            actor: event.actor,
+            subject: event.subject,
+            timestamp: event.ts,
+            level: event.level,
+            tags: event.tags,
+            summary: event.payload?.summary || event.payload?.message || event.payload?.title || undefined
+        }));
+        return {
+            success: true,
+            data: formattedEvents,
+            message: kind
+                ? `Found ${formattedEvents.length} recent '${kind}' events`
+                : `Found ${formattedEvents.length} recent events`
+        };
+    }
+    catch (error) {
+        console.error('Error executing events tool:', error);
+        return { success: false, error: error.message || 'Events tool execution failed' };
+    }
+}
+// Project context tool - read/write the project definition document
+async function executeProjectContextToolDirect(args) {
+    const { operation, content, old_text, new_text } = args;
+    try {
+        const contextPath = getContextBasePath();
+        const filePath = join(contextPath, 'project.md');
+        switch (operation) {
+            case 'get': {
+                try {
+                    const fileContent = await fs.readFile(filePath, 'utf-8');
+                    const parsed = matter(fileContent);
+                    return {
+                        success: true,
+                        data: {
+                            content: parsed.content,
+                            frontmatter: parsed.data,
+                            raw: fileContent
+                        },
+                        message: 'Retrieved project context'
+                    };
+                }
+                catch (err) {
+                    if (err.code === 'ENOENT') {
+                        return {
+                            success: true,
+                            data: { content: '', frontmatter: {}, raw: '' },
+                            message: 'Project context document does not exist yet. You can create it with an update operation.'
+                        };
+                    }
+                    throw err;
+                }
+            }
+            case 'append': {
+                if (!content) {
+                    return { success: false, error: 'Content is required for append operation' };
+                }
+                await fs.mkdir(contextPath, { recursive: true });
+                // Read existing content if file exists
+                let existingContent = '';
+                try {
+                    existingContent = await fs.readFile(filePath, 'utf-8');
+                }
+                catch (err) {
+                    if (err.code !== 'ENOENT')
+                        throw err;
+                }
+                // Append new content with a newline separator
+                const newContent = existingContent
+                    ? existingContent.trimEnd() + '\n\n' + content
+                    : content;
+                await fs.writeFile(filePath, newContent, 'utf-8');
+                return {
+                    success: true,
+                    message: 'Appended content to project context document'
+                };
+            }
+            case 'replace_section': {
+                if (!old_text || !new_text) {
+                    return { success: false, error: 'Both old_text and new_text are required for replace_section operation' };
+                }
+                // Read existing content
+                let existingContent = '';
+                try {
+                    existingContent = await fs.readFile(filePath, 'utf-8');
+                }
+                catch (err) {
+                    if (err.code === 'ENOENT') {
+                        return { success: false, error: 'Project context document does not exist. Use append or update to create it first.' };
+                    }
+                    throw err;
+                }
+                // Check if old_text exists in the document
+                if (!existingContent.includes(old_text)) {
+                    return {
+                        success: false,
+                        error: 'Could not find the specified text in the document. The text may have been paraphrased or changed.',
+                        fallback_markdown: new_text,
+                        suggestion: 'Here is the replacement text. You can copy it and manually edit the document at /context/project'
+                    };
+                }
+                // Replace the text
+                const updatedContent = existingContent.replace(old_text, new_text);
+                await fs.writeFile(filePath, updatedContent, 'utf-8');
+                return {
+                    success: true,
+                    message: 'Replaced section in project context document'
+                };
+            }
+            case 'update': {
+                if (!content) {
+                    return { success: false, error: 'Content is required for update operation' };
+                }
+                await fs.mkdir(contextPath, { recursive: true });
+                await fs.writeFile(filePath, content, 'utf-8');
+                return {
+                    success: true,
+                    message: 'Updated project context document'
+                };
+            }
+            default:
+                return { success: false, error: `Unknown operation: ${operation}. Use 'get', 'append', 'replace_section', or 'update'.` };
+        }
+    }
+    catch (error) {
+        console.error('Error executing project context tool:', error);
+        return { success: false, error: error.message || 'Project context tool execution failed' };
+    }
+}
+// Architecture context tool - read/write the architecture document
+async function executeArchitectureContextToolDirect(args) {
+    const { operation, content, old_text, new_text } = args;
+    try {
+        const contextPath = getContextBasePath();
+        const filePath = join(contextPath, 'architecture.md');
+        switch (operation) {
+            case 'get': {
+                try {
+                    const fileContent = await fs.readFile(filePath, 'utf-8');
+                    const parsed = matter(fileContent);
+                    return {
+                        success: true,
+                        data: {
+                            content: parsed.content,
+                            frontmatter: parsed.data,
+                            raw: fileContent
+                        },
+                        message: 'Retrieved architecture context'
+                    };
+                }
+                catch (err) {
+                    if (err.code === 'ENOENT') {
+                        return {
+                            success: true,
+                            data: { content: '', frontmatter: {}, raw: '' },
+                            message: 'Architecture context document does not exist yet. You can create it with an update operation.'
+                        };
+                    }
+                    throw err;
+                }
+            }
+            case 'append': {
+                if (!content) {
+                    return { success: false, error: 'Content is required for append operation' };
+                }
+                await fs.mkdir(contextPath, { recursive: true });
+                // Read existing content if file exists
+                let existingContent = '';
+                try {
+                    existingContent = await fs.readFile(filePath, 'utf-8');
+                }
+                catch (err) {
+                    if (err.code !== 'ENOENT')
+                        throw err;
+                }
+                // Append new content with a newline separator
+                const newContent = existingContent
+                    ? existingContent.trimEnd() + '\n\n' + content
+                    : content;
+                await fs.writeFile(filePath, newContent, 'utf-8');
+                return {
+                    success: true,
+                    message: 'Appended content to architecture context document'
+                };
+            }
+            case 'replace_section': {
+                if (!old_text || !new_text) {
+                    return { success: false, error: 'Both old_text and new_text are required for replace_section operation' };
+                }
+                // Read existing content
+                let existingContent = '';
+                try {
+                    existingContent = await fs.readFile(filePath, 'utf-8');
+                }
+                catch (err) {
+                    if (err.code === 'ENOENT') {
+                        return { success: false, error: 'Architecture context document does not exist. Use append or update to create it first.' };
+                    }
+                    throw err;
+                }
+                // Check if old_text exists in the document
+                if (!existingContent.includes(old_text)) {
+                    return {
+                        success: false,
+                        error: 'Could not find the specified text in the document. The text may have been paraphrased or changed.',
+                        fallback_markdown: new_text,
+                        suggestion: 'Here is the replacement text. You can copy it and manually edit the document at /context/architecture'
+                    };
+                }
+                // Replace the text
+                const updatedContent = existingContent.replace(old_text, new_text);
+                await fs.writeFile(filePath, updatedContent, 'utf-8');
+                return {
+                    success: true,
+                    message: 'Replaced section in architecture context document'
+                };
+            }
+            case 'update': {
+                if (!content) {
+                    return { success: false, error: 'Content is required for update operation' };
+                }
+                await fs.mkdir(contextPath, { recursive: true });
+                await fs.writeFile(filePath, content, 'utf-8');
+                return {
+                    success: true,
+                    message: 'Updated architecture context document'
+                };
+            }
+            default:
+                return { success: false, error: `Unknown operation: ${operation}. Use 'get', 'append', 'replace_section', or 'update'.` };
+        }
+    }
+    catch (error) {
+        console.error('Error executing architecture context tool:', error);
+        return { success: false, error: error.message || 'Architecture context tool execution failed' };
+    }
+}
+function getContextBasePath() {
+    let basePath;
+    if (process.env.NODE_ENV === 'development' && process.env.GAIT_DEV_ROOT) {
+        basePath = process.env.GAIT_DEV_ROOT;
+    }
+    else if (process.env.GAIT_DATA_PATH) {
+        basePath = pathResolve(process.env.GAIT_DATA_PATH, '.nut');
+    }
+    else {
+        basePath = pathResolve(process.cwd(), '.nut');
+    }
+    return join(basePath, 'context');
+}
+function getKnowledgeBasePath() {
+    let basePath;
+    if (process.env.NODE_ENV === 'development' && process.env.GAIT_DEV_ROOT) {
+        basePath = process.env.GAIT_DEV_ROOT;
+    }
+    else if (process.env.GAIT_DATA_PATH) {
+        basePath = pathResolve(process.env.GAIT_DATA_PATH, '.nut');
+    }
+    else {
+        basePath = pathResolve(process.cwd(), '.nut');
+    }
+    return join(basePath, 'context', 'knowledge');
+}
+function slugify(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/--+/g, '-')
+        .replace(/^-|-$/g, '');
+    return slug || 'knowledge-entry';
+}
+function resolveKnowledgeFilename(input, fallbackTitle) {
+    if (input && input.trim().length > 0) {
+        const trimmed = basename(input.trim());
+        if (trimmed.endsWith('.md')) {
+            return trimmed;
+        }
+        return `${slugify(trimmed)}.md`;
+    }
+    const fallback = fallbackTitle && fallbackTitle.trim().length > 0
+        ? basename(fallbackTitle.trim())
+        : 'knowledge-entry';
+    return `${slugify(fallback)}.md`;
+}
+function extractKnowledgeTitle(content, fallback) {
+    const headingMatch = content.match(/^#\s+(.+)$/m);
+    if (headingMatch && headingMatch[1]) {
+        return headingMatch[1].trim();
+    }
+    const baseName = fallback.replace('.md', '').replace(/[_-]/g, ' ');
+    return baseName.replace(/\w\S*/g, (txt) => txt.charAt(0).toUpperCase() + txt.slice(1).toLowerCase());
+}
+async function readKnowledgeDocument(basePath, filename) {
+    const actualFilename = resolveKnowledgeFilename(filename, filename);
+    const filePath = join(basePath, actualFilename);
+    const raw = await fs.readFile(filePath, 'utf-8');
+    const { data, content } = matter(raw);
+    const normalizedMetadata = normalizeKnowledgeMetadata(data);
+    const title = extractKnowledgeTitle(content, actualFilename);
+    return {
+        filename: actualFilename,
+        title,
+        metadata: normalizedMetadata,
+        content
+    };
+}
+async function listKnowledgeDocuments(basePath, query) {
+    const files = await fs.readdir(basePath);
+    const markdownFiles = files.filter(file => file.endsWith('.md'));
+    const documents = await Promise.all(markdownFiles.map(async (file) => {
+        try {
+            return await readKnowledgeDocument(basePath, file);
+        }
+        catch (error) {
+            console.error(`Failed to read knowledge document ${file}:`, error);
+            return null;
+        }
+    }));
+    const validDocs = documents.filter((doc) => doc !== null);
+    if (!query?.trim()) {
+        return validDocs.sort((a, b) => a.filename.localeCompare(b.filename));
+    }
+    // Simple text search for the tools endpoint
+    const lowerQuery = query.toLowerCase();
+    return validDocs
+        .filter(doc => doc.title.toLowerCase().includes(lowerQuery) ||
+        doc.content.toLowerCase().includes(lowerQuery) ||
+        doc.metadata?.summary?.toLowerCase().includes(lowerQuery))
+        .sort((a, b) => a.filename.localeCompare(b.filename));
+}
+function getSystemPrompt(context, contextContent) {
+    const basePrompt = `You are the Coconut 🥥 AI assistant for agent-native development workflows. You help developers with proposals, architecture decisions, planning, and execution.`;
+    switch (context) {
+        case "proposals":
+        case "proposals-edit":
+        case "proposals-view":
+            let proposalPrompt = `${basePrompt} You are currently in the proposals section. Help users:
+- Refine and improve their change proposals
+- Suggest implementation approaches
+- Identify potential challenges or risks
+- Break down complex changes into manageable steps
+- Provide feedback on proposal clarity and completeness`;
+            if (contextContent) {
+                proposalPrompt += `\n\nYou have access to the following proposal data:\n\n${contextContent}`;
+            }
+            return proposalPrompt;
+        case "context":
+            return `${basePrompt} You are currently in the context section (architecture, decisions, knowledge). Help users:
+- Analyze architectural decisions and patterns
+- Suggest improvements to documentation
+- Identify gaps in knowledge or decisions
+- Recommend best practices
+- Help maintain consistency across the project`;
+        case "settings":
+            return `${basePrompt} You are currently in the settings section. Help users:
+- Configure their GAIT environment
+- Set up integrations and workflows
+- Optimize their development process
+- Understand configuration options
+- Troubleshoot setup issues`;
+        default:
+            return `${basePrompt} Provide helpful, contextual assistance based on the user's current needs in their GAIT workflow.`;
+    }
+}