codeep 1.2.17 → 1.2.18

package/dist/utils/agentChat.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Agent chat API layer and prompt building.
+ *
+ * Exported:
+ *   loadProjectRules()       — loads .codeep/rules.md or CODEEP.md
+ *   formatChatHistoryForAgent() — trims history to fit context window
+ *   getAgentSystemPrompt()   — builds system prompt for native-tool mode
+ *   getFallbackSystemPrompt() — builds system prompt for text-tool mode
+ *   agentChat()              — native tool-calling API call
+ *   agentChatFallback()      — text-based tool format fallback
+ *   AgentChatResponse        — response type (re-export from agentStream)
+ *   TimeoutError             — distinguishes timeout from user abort
+ */
+import { ProjectContext } from './project';
+import { Message } from '../config/index';
+import { AgentChatResponse } from './agentStream';
+export { AgentChatResponse };
+/**
+ * Custom error class for timeout
+ */
+export declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Load project rules from .codeep/rules.md or CODEEP.md
+ */
+export declare function loadProjectRules(projectRoot: string): string;
+/**
+ * Format chat session history for inclusion in agent system prompt.
+ * Keeps the most recent messages within a character budget.
+ */
+export declare function formatChatHistoryForAgent(history?: Array<{
+    role: 'user' | 'assistant';
+    content: string;
+}>, maxChars?: number): string;
+export declare function getAgentSystemPrompt(projectContext: ProjectContext): string;
+export declare function getFallbackSystemPrompt(projectContext: ProjectContext): string;
+/**
+ * Make a chat API call for agent mode with native tool support.
+ * Falls back to agentChatFallback() if provider doesn't support tools.
+ */
+export declare function agentChat(messages: Message[], systemPrompt: string, onChunk?: (chunk: string) => void, abortSignal?: AbortSignal, dynamicTimeout?: number): Promise<AgentChatResponse>;
+/**
+ * Fallback chat without native tools (text-based tool format)
+ */
+export declare function agentChatFallback(messages: Message[], systemPrompt: string, onChunk?: (chunk: string) => void, abortSignal?: AbortSignal, dynamicTimeout?: number): Promise<AgentChatResponse>;

package/dist/utils/agentChat.js

@@ -0,0 +1,343 @@
+/**
+ * Agent chat API layer and prompt building.
+ *
+ * Exported:
+ *   loadProjectRules()       — loads .codeep/rules.md or CODEEP.md
+ *   formatChatHistoryForAgent() — trims history to fit context window
+ *   getAgentSystemPrompt()   — builds system prompt for native-tool mode
+ *   getFallbackSystemPrompt() — builds system prompt for text-tool mode
+ *   agentChat()              — native tool-calling API call
+ *   agentChatFallback()      — text-based tool format fallback
+ *   AgentChatResponse        — response type (re-export from agentStream)
+ *   TimeoutError             — distinguishes timeout from user abort
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { config, getApiKey } from '../config/index.js';
+import { getProviderBaseUrl, getProviderAuthHeader, supportsNativeTools } from '../config/providers.js';
+import { recordTokenUsage, extractOpenAIUsage, extractAnthropicUsage } from './tokenTracker.js';
+import { parseOpenAIToolCalls, parseAnthropicToolCalls, parseToolCalls } from './toolParsing.js';
+import { formatToolDefinitions, getOpenAITools, getAnthropicTools } from './tools.js';
+import { handleStream, handleOpenAIAgentStream, handleAnthropicAgentStream } from './agentStream.js';
+const debug = (...args) => {
+    if (process.env.CODEEP_DEBUG === '1') {
+        console.error('[DEBUG]', ...args);
+    }
+};
+/**
+ * Custom error class for timeout
+ */
+export class TimeoutError extends Error {
+    constructor(message = 'Request timed out') {
+        super(message);
+        this.name = 'TimeoutError';
+    }
+}
+/**
+ * Load project rules from .codeep/rules.md or CODEEP.md
+ */
+export function loadProjectRules(projectRoot) {
+    const candidates = [
+        join(projectRoot, '.codeep', 'rules.md'),
+        join(projectRoot, 'CODEEP.md'),
+    ];
+    for (const filePath of candidates) {
+        if (existsSync(filePath)) {
+            try {
+                const content = readFileSync(filePath, 'utf-8').trim();
+                if (content) {
+                    debug('Loaded project rules from', filePath);
+                    return `\n\n## Project Rules\nThe following rules are defined by the project owner. You MUST follow these rules:\n\n${content}`;
+                }
+            }
+            catch (err) {
+                debug('Failed to read project rules from', filePath, err);
+            }
+        }
+    }
+    return '';
+}
+/**
+ * Format chat session history for inclusion in agent system prompt.
+ * Keeps the most recent messages within a character budget.
+ */
+export function formatChatHistoryForAgent(history, maxChars = 16000) {
+    if (!history || history.length === 0)
+        return '';
+    const filtered = history.filter(m => {
+        const content = m.content.trimStart();
+        if (content.startsWith('[AGENT]') || content.startsWith('[DRY RUN]'))
+            return false;
+        if (content.startsWith('Agent completed') || content.startsWith('Agent failed') || content.startsWith('Agent stopped'))
+            return false;
+        return true;
+    });
+    if (filtered.length === 0)
+        return '';
+    const selected = [];
+    let totalChars = 0;
+    for (let i = filtered.length - 1; i >= 0; i--) {
+        const msg = filtered[i];
+        const entry = `${msg.role === 'user' ? 'User' : 'Assistant'}: ${msg.content}`;
+        if (totalChars + entry.length > maxChars && selected.length > 0)
+            break;
+        if (entry.length > maxChars) {
+            selected.unshift({ role: msg.role, content: msg.content.slice(0, maxChars - 100) + '\n[truncated]' });
+            break;
+        }
+        selected.unshift(msg);
+        totalChars += entry.length;
+    }
+    if (selected.length === 0)
+        return '';
+    const lines = selected.map(m => `**${m.role === 'user' ? 'User' : 'Assistant'}:** ${m.content}`).join('\n\n');
+    return `\n\n## Prior Conversation Context\nThe following is the recent chat history from this session. Use it as background context to understand the user's intent, but focus on completing the current task.\n\n${lines}`;
+}
+export function getAgentSystemPrompt(projectContext) {
+    return `You are an AI coding agent with FULL autonomous access to this project.
+
+## Your Capabilities
+- Read, write, edit, and delete files and directories
+- Create directories with create_directory tool
+- Execute shell commands (npm, git, build tools, etc.)
+- Search code in the project
+- List directory contents
+
+## IMPORTANT: Follow User Instructions Exactly
+- Do EXACTLY what the user asks
+- If user says "create a website" -> create ALL necessary files (HTML, CSS, JS, images, etc.)
+- If user says "create folder X" -> use create_directory tool to create folder X
+- If user says "delete file X" -> use delete_file tool to delete file X
+- The user may write in any language - understand their request and execute it
+- Tool names and parameters must ALWAYS be in English (e.g., "create_directory", not "kreiraj_direktorij")
+- KEEP WORKING until the ENTIRE task is finished - do NOT stop after creating just directories or partial files
+- Only stop when you have created ALL files needed for a complete, working solution
+
+## Rules
+1. Always read files before editing them to understand the current content
+2. Use edit_file for modifications to existing files (preserves other content)
+3. Use write_file only for creating new files or complete overwrites
+4. Use create_directory to create new folders/directories
+5. Use list_files to see directory contents
+6. Use search_code to find files or search patterns
+7. NEVER use execute_command for: ls, find, cat, grep, mkdir, rm, cp, mv, touch
+8. Use execute_command ONLY for: npm, git, composer, pip, cargo (build/package managers)
+9. When the task is complete, respond with a summary WITHOUT any tool calls
+
+## Project Information
+Name: ${projectContext.name || 'Unknown'}
+Type: ${projectContext.type || 'unknown'}
+Root: ${projectContext.root || process.cwd()}
+${projectContext.structure ? `\n## Project Structure\n${projectContext.structure}` : ''}`;
+}
+export function getFallbackSystemPrompt(projectContext) {
+    return getAgentSystemPrompt(projectContext) + '\n\n' + formatToolDefinitions();
+}
+/**
+ * Make a chat API call for agent mode with native tool support.
+ * Falls back to agentChatFallback() if provider doesn't support tools.
+ */
+export async function agentChat(messages, systemPrompt, onChunk, abortSignal, dynamicTimeout) {
+    const protocol = config.get('protocol');
+    const model = config.get('model');
+    const apiKey = getApiKey();
+    const providerId = config.get('provider');
+    const baseUrl = getProviderBaseUrl(providerId, protocol);
+    const authHeader = getProviderAuthHeader(providerId, protocol);
+    if (!baseUrl)
+        throw new Error(`Provider ${providerId} does not support ${protocol} protocol`);
+    if (!supportsNativeTools(providerId, protocol)) {
+        return await agentChatFallback(messages, systemPrompt, onChunk, abortSignal);
+    }
+    const controller = new AbortController();
+    const timeoutMs = dynamicTimeout || config.get('apiTimeout');
+    let isTimeout = false;
+    const timeout = setTimeout(() => { isTimeout = true; controller.abort(); }, timeoutMs);
+    if (abortSignal) {
+        abortSignal.addEventListener('abort', () => { isTimeout = false; controller.abort(); });
+    }
+    const headers = { 'Content-Type': 'application/json' };
+    if (authHeader === 'Bearer') {
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    }
+    else {
+        headers['x-api-key'] = apiKey;
+    }
+    if (protocol === 'anthropic')
+        headers['anthropic-version'] = '2023-06-01';
+    try {
+        let endpoint;
+        let body;
+        const useStreaming = Boolean(onChunk);
+        if (protocol === 'openai') {
+            endpoint = `${baseUrl}/chat/completions`;
+            body = {
+                model, messages: [{ role: 'system', content: systemPrompt }, ...messages],
+                tools: getOpenAITools(), tool_choice: 'auto', stream: useStreaming,
+                temperature: config.get('temperature'), max_tokens: Math.max(config.get('maxTokens'), 16384),
+            };
+        }
+        else {
+            endpoint = `${baseUrl}/v1/messages`;
+            body = {
+                model, system: systemPrompt, messages,
+                tools: getAnthropicTools(), stream: useStreaming,
+                temperature: config.get('temperature'), max_tokens: Math.max(config.get('maxTokens'), 16384),
+            };
+        }
+        const response = await fetch(endpoint, {
+            method: 'POST', headers, body: JSON.stringify(body), signal: controller.signal,
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            if (errorText.includes('tools') || errorText.includes('function') || response.status === 400) {
+                return await agentChatFallback(messages, systemPrompt, onChunk, abortSignal);
+            }
+            throw new Error(`API error: ${response.status} - ${errorText}`);
+        }
+        if (useStreaming && response.body) {
+            if (protocol === 'openai')
+                return await handleOpenAIAgentStream(response.body, onChunk, model, providerId);
+            else
+                return await handleAnthropicAgentStream(response.body, onChunk, model, providerId);
+        }
+        const data = await response.json();
+        const usageExtractor = protocol === 'openai' ? extractOpenAIUsage : extractAnthropicUsage;
+        const usage = usageExtractor(data);
+        if (usage)
+            recordTokenUsage(usage, model, providerId);
+        if (protocol === 'openai') {
+            const message = data.choices?.[0]?.message;
+            const content = message?.content || '';
+            const rawToolCalls = message?.tool_calls || [];
+            const toolCalls = parseOpenAIToolCalls(rawToolCalls);
+            debug('Parsed tool calls:', toolCalls.length, toolCalls.map((t) => t.tool));
+            if (toolCalls.length === 0 && content) {
+                const textToolCalls = parseToolCalls(content);
+                if (textToolCalls.length > 0)
+                    return { content, toolCalls: textToolCalls, usedNativeTools: false };
+            }
+            if (onChunk && content)
+                onChunk(content);
+            return { content, toolCalls, usedNativeTools: true };
+        }
+        else {
+            const contentBlocks = data.content || [];
+            let textContent = '';
+            for (const block of contentBlocks) {
+                if (block.type === 'text') {
+                    textContent += block.text;
+                    if (onChunk)
+                        onChunk(block.text);
+                }
+            }
+            const toolCalls = parseAnthropicToolCalls(contentBlocks);
+            return { content: textContent, toolCalls, usedNativeTools: true };
+        }
+    }
+    catch (error) {
+        const err = error;
+        if (err.name === 'AbortError') {
+            if (isTimeout)
+                throw new TimeoutError(`API request timed out after ${timeoutMs}ms`);
+            throw error;
+        }
+        if (err.message.includes('tools') || err.message.includes('function')) {
+            return await agentChatFallback(messages, systemPrompt, onChunk, abortSignal);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Fallback chat without native tools (text-based tool format)
+ */
+export async function agentChatFallback(messages, systemPrompt, onChunk, abortSignal, dynamicTimeout) {
+    const protocol = config.get('protocol');
+    const model = config.get('model');
+    const apiKey = getApiKey();
+    const providerId = config.get('provider');
+    const baseUrl = getProviderBaseUrl(providerId, protocol);
+    const authHeader = getProviderAuthHeader(providerId, protocol);
+    if (!baseUrl)
+        throw new Error(`Provider ${providerId} does not support ${protocol} protocol`);
+    const controller = new AbortController();
+    const timeoutMs = dynamicTimeout || config.get('apiTimeout');
+    let isTimeout = false;
+    const timeout = setTimeout(() => { isTimeout = true; controller.abort(); }, timeoutMs);
+    if (abortSignal) {
+        abortSignal.addEventListener('abort', () => { isTimeout = false; controller.abort(); });
+    }
+    const headers = { 'Content-Type': 'application/json' };
+    if (authHeader === 'Bearer') {
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    }
+    else {
+        headers['x-api-key'] = apiKey;
+    }
+    if (protocol === 'anthropic')
+        headers['anthropic-version'] = '2023-06-01';
+    const fallbackPrompt = systemPrompt.includes('## Available Tools')
+        ? systemPrompt
+        : systemPrompt + '\n\n' + formatToolDefinitions();
+    try {
+        let endpoint;
+        let body;
+        if (protocol === 'openai') {
+            endpoint = `${baseUrl}/chat/completions`;
+            body = {
+                model, messages: [{ role: 'system', content: fallbackPrompt }, ...messages],
+                stream: Boolean(onChunk), temperature: config.get('temperature'),
+                max_tokens: Math.max(config.get('maxTokens'), 16384),
+            };
+        }
+        else {
+            endpoint = `${baseUrl}/v1/messages`;
+            body = {
+                model,
+                messages: [
+                    { role: 'user', content: fallbackPrompt },
+                    { role: 'assistant', content: 'Understood. I will use the tools as specified.' },
+                    ...messages,
+                ],
+                stream: Boolean(onChunk), temperature: config.get('temperature'),
+                max_tokens: Math.max(config.get('maxTokens'), 16384),
+            };
+        }
+        const response = await fetch(endpoint, {
+            method: 'POST', headers, body: JSON.stringify(body), signal: controller.signal,
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`API error: ${response.status} - ${error}`);
+        }
+        let content;
+        if (onChunk && response.body) {
+            content = await handleStream(response.body, protocol, onChunk);
+        }
+        else {
+            const data = await response.json();
+            const fallbackUsageExtractor = protocol === 'openai' ? extractOpenAIUsage : extractAnthropicUsage;
+            const fallbackUsage = fallbackUsageExtractor(data);
+            if (fallbackUsage)
+                recordTokenUsage(fallbackUsage, model, providerId);
+            content = protocol === 'openai' ? (data.choices?.[0]?.message?.content || '') : (data.content?.[0]?.text || '');
+        }
+        const toolCalls = parseToolCalls(content);
+        return { content, toolCalls, usedNativeTools: false };
+    }
+    catch (error) {
+        const err = error;
+        if (err.name === 'AbortError') {
+            if (isTimeout)
+                throw new TimeoutError(`API request timed out after ${timeoutMs}ms`);
+            throw error;
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/utils/agentStream.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Agent streaming handlers for OpenAI and Anthropic protocols.
+ *
+ * Parses SSE streams and accumulates tool calls from deltas.
+ */
+import { ToolCall } from './tools';
+export interface AgentChatResponse {
+    content: string;
+    toolCalls: ToolCall[];
+    usedNativeTools: boolean;
+}
+/**
+ * Handle streaming response (text-based fallback, no native tools)
+ */
+export declare function handleStream(body: ReadableStream<Uint8Array>, protocol: string, onChunk: (chunk: string) => void): Promise<string>;
+/**
+ * Handle OpenAI streaming response with tool call accumulation
+ */
+export declare function handleOpenAIAgentStream(body: ReadableStream<Uint8Array>, onChunk: (chunk: string) => void, model: string, providerId: string): Promise<AgentChatResponse>;
+/**
+ * Handle Anthropic streaming response with tool call accumulation
+ */
+export declare function handleAnthropicAgentStream(body: ReadableStream<Uint8Array>, onChunk: (chunk: string) => void, model: string, providerId: string): Promise<AgentChatResponse>;

package/dist/utils/agentStream.js

@@ -0,0 +1,216 @@
+/**
+ * Agent streaming handlers for OpenAI and Anthropic protocols.
+ *
+ * Parses SSE streams and accumulates tool calls from deltas.
+ */
+import { recordTokenUsage, extractOpenAIUsage, extractAnthropicUsage } from './tokenTracker.js';
+import { parseOpenAIToolCalls, parseAnthropicToolCalls, parseToolCalls } from './toolParsing.js';
+// Debug logging helper - only logs when CODEEP_DEBUG=1
+const debug = (...args) => {
+    if (process.env.CODEEP_DEBUG === '1') {
+        console.error('[DEBUG]', ...args);
+    }
+};
+function tryParseJSON(str) {
+    try {
+        return JSON.parse(str);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Handle streaming response (text-based fallback, no native tools)
+ */
+export async function handleStream(body, protocol, onChunk) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    const chunks = [];
+    let buffer = '';
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+        for (const line of lines) {
+            if (line.startsWith('data: ')) {
+                const data = line.slice(6);
+                if (data === '[DONE]')
+                    continue;
+                try {
+                    const parsed = JSON.parse(data);
+                    let content;
+                    if (protocol === 'openai') {
+                        content = parsed.choices?.[0]?.delta?.content;
+                    }
+                    else if (parsed.type === 'content_block_delta') {
+                        content = parsed.delta?.text;
+                    }
+                    if (content) {
+                        chunks.push(content);
+                        onChunk(content);
+                    }
+                }
+                catch {
+                    // Skip parse errors
+                }
+            }
+        }
+    }
+    return chunks.join('');
+}
+/**
+ * Handle OpenAI streaming response with tool call accumulation
+ */
+export async function handleOpenAIAgentStream(body, onChunk, model, providerId) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let content = '';
+    const toolCallMap = new Map();
+    let usageData = null;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+        for (const line of lines) {
+            if (!line.startsWith('data: '))
+                continue;
+            const data = line.slice(6);
+            if (data === '[DONE]')
+                continue;
+            try {
+                const parsed = JSON.parse(data);
+                if (parsed.usage) {
+                    usageData = parsed;
+                }
+                const delta = parsed.choices?.[0]?.delta;
+                if (!delta)
+                    continue;
+                if (delta.content) {
+                    content += delta.content;
+                    onChunk(delta.content);
+                }
+                if (delta.tool_calls) {
+                    for (const tc of delta.tool_calls) {
+                        const idx = tc.index ?? 0;
+                        if (!toolCallMap.has(idx)) {
+                            toolCallMap.set(idx, { id: tc.id || '', name: tc.function?.name || '', arguments: '' });
+                        }
+                        const entry = toolCallMap.get(idx);
+                        if (tc.id)
+                            entry.id = tc.id;
+                        if (tc.function?.name)
+                            entry.name = tc.function.name;
+                        if (tc.function?.arguments)
+                            entry.arguments += tc.function.arguments;
+                    }
+                }
+            }
+            catch {
+                // Ignore parse errors
+            }
+        }
+    }
+    if (usageData) {
+        const usage = extractOpenAIUsage(usageData);
+        if (usage)
+            recordTokenUsage(usage, model, providerId);
+    }
+    const rawToolCalls = Array.from(toolCallMap.values()).map(tc => ({
+        id: tc.id,
+        type: 'function',
+        function: { name: tc.name, arguments: tc.arguments },
+    }));
+    const toolCalls = parseOpenAIToolCalls(rawToolCalls);
+    debug('Stream parsed tool calls:', toolCalls.length, toolCalls.map(t => t.tool));
+    if (toolCalls.length === 0 && content) {
+        const textToolCalls = parseToolCalls(content);
+        if (textToolCalls.length > 0) {
+            return { content, toolCalls: textToolCalls, usedNativeTools: false };
+        }
+    }
+    return { content, toolCalls, usedNativeTools: true };
+}
+/**
+ * Handle Anthropic streaming response with tool call accumulation
+ */
+export async function handleAnthropicAgentStream(body, onChunk, model, providerId) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let content = '';
+    const contentBlocks = [];
+    let currentBlockType = '';
+    let currentToolName = '';
+    let currentToolId = '';
+    let currentToolInput = '';
+    let usageData = null;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+        for (const line of lines) {
+            if (!line.startsWith('data: '))
+                continue;
+            const data = line.slice(6);
+            try {
+                const parsed = JSON.parse(data);
+                if (parsed.usage)
+                    usageData = parsed;
+                if (parsed.type === 'message_delta' && parsed.usage)
+                    usageData = parsed;
+                if (parsed.type === 'content_block_start') {
+                    const block = parsed.content_block;
+                    if (block.type === 'text') {
+                        currentBlockType = 'text';
+                    }
+                    else if (block.type === 'tool_use') {
+                        currentBlockType = 'tool_use';
+                        currentToolName = block.name || '';
+                        currentToolId = block.id || '';
+                        currentToolInput = '';
+                    }
+                }
+                else if (parsed.type === 'content_block_delta') {
+                    if (currentBlockType === 'text' && parsed.delta?.text) {
+                        content += parsed.delta.text;
+                        onChunk(parsed.delta.text);
+                    }
+                    else if (currentBlockType === 'tool_use' && parsed.delta?.partial_json) {
+                        currentToolInput += parsed.delta.partial_json;
+                    }
+                }
+                else if (parsed.type === 'content_block_stop') {
+                    if (currentBlockType === 'tool_use') {
+                        contentBlocks.push({
+                            type: 'tool_use',
+                            id: currentToolId,
+                            name: currentToolName,
+                            input: tryParseJSON(currentToolInput),
+                        });
+                    }
+                    currentBlockType = '';
+                }
+            }
+            catch {
+                // Ignore parse errors
+            }
+        }
+    }
+    if (usageData) {
+        const usage = extractAnthropicUsage(usageData);
+        if (usage)
+            recordTokenUsage(usage, model, providerId);
+    }
+    const toolCalls = parseAnthropicToolCalls(contentBlocks);
+    return { content, toolCalls, usedNativeTools: true };
+}

package/dist/utils/keychain.js

@@ -90,7 +90,8 @@ class SmartStorage {
         }
         catch {
             this.useKeychain = false;
-            // Silently fallback - don't warn user
+            logger.warn('System keychain is unavailable. API keys will be stored as plaintext in the config file. ' +
+                'Consider installing libsecret (Linux) or ensuring Keychain Access is available (macOS).');
         }
         this.keychainTested = true;
     }
@@ -113,8 +114,8 @@ class SmartStorage {
                 return;
             }
             catch (error) {
-                // Keychain failed, fall back to config
                 this.useKeychain = false;
+                logger.warn(`Keychain write failed for '${providerId}'. API key will be stored as plaintext in config. Error: ${error}`);
             }
         }
         await this.fallback.setApiKey(providerId, apiKey);

package/dist/utils/learning.js

@@ -94,9 +94,15 @@ export function loadProjectPreferences(projectRoot) {
 export function saveProjectPreferences(projectRoot, prefs) {
     ensureLearningDir();
     const projectPrefsPath = getProjectPrefsPath(projectRoot);
-    const existing = existsSync(projectPrefsPath)
-        ? JSON.parse(readFileSync(projectPrefsPath, 'utf-8'))
-        : {};
+    let existing = {};
+    if (existsSync(projectPrefsPath)) {
+        try {
+            existing = JSON.parse(readFileSync(projectPrefsPath, 'utf-8'));
+        }
+        catch {
+            // Corrupt prefs file — start fresh
+        }
+    }
     const merged = { ...existing, ...prefs, lastUpdated: Date.now() };
     writeFileSync(projectPrefsPath, JSON.stringify(merged, null, 2));
 }