@yeaft/webchat-agent 0.1.399 → 0.1.409

package/unify/engine.js

@@ -0,0 +1,511 @@
+/**
+ * engine.js — Yeaft query loop
+ *
+ * The engine is the core orchestrator:
+ *   1. Before first turn: recall memories → inject into system prompt
+ *   2. Build messages array (with compact summary if available)
+ *   3. Call adapter.stream()
+ *   4. Collect text + tool_calls from stream events
+ *   5. If tool_calls → execute tools → append results → goto 3
+ *   6. If end_turn → persist messages → check consolidation → done
+ *   7. If max_tokens → auto-continue (up to maxContinueTurns)
+ *   8. On LLMContextError → force compact → retry
+ *   9. On retryable error with fallbackModel → switch model → retry
+ *
+ * Pattern derived from Claude Code's query loop (src/query.ts).
+ *
+ * Reference: yeaft-unify-implementation-plan.md §3.1, §4 (Phase 2)
+ */
+
+import { randomUUID } from 'crypto';
+import { buildSystemPrompt } from './prompts.js';
+import { LLMContextError } from './llm/adapter.js';
+import { recall } from './memory/recall.js';
+import { shouldConsolidate, consolidate } from './memory/consolidate.js';
+
+/** Maximum number of turns before the engine stops to prevent infinite loops. */
+const MAX_TURNS = 25;
+
+/** Maximum auto-continue turns when stopReason is 'max_tokens'. */
+const MAX_CONTINUE_TURNS = 3;
+
+// ─── Engine Events (superset of adapter events) ──────────────────
+
+/**
+ * @typedef {{ type: 'turn_start', turnNumber: number }} TurnStartEvent
+ * @typedef {{ type: 'turn_end', turnNumber: number, stopReason: string }} TurnEndEvent
+ * @typedef {{ type: 'tool_start', id: string, name: string, input: object }} ToolStartEvent
+ * @typedef {{ type: 'tool_end', id: string, name: string, output: string, isError: boolean }} ToolEndEvent
+ * @typedef {{ type: 'consolidate', archivedCount: number, extractedCount: number }} ConsolidateEvent
+ * @typedef {{ type: 'recall', entryCount: number, cached: boolean }} RecallEvent
+ * @typedef {{ type: 'fallback', from: string, to: string, reason: string }} FallbackEvent
+ *
+ * @typedef {import('./llm/adapter.js').StreamEvent | TurnStartEvent | TurnEndEvent | ToolStartEvent | ToolEndEvent | ConsolidateEvent | RecallEvent | FallbackEvent} EngineEvent
+ */
+
+// ─── Engine ──────────────────────────────────────────────────────
+
+export class Engine {
+  /** @type {import('./llm/adapter.js').LLMAdapter} */
+  #adapter;
+
+  /** @type {import('./debug-trace.js').DebugTrace | import('./debug-trace.js').NullTrace} */
+  #trace;
+
+  /** @type {object} */
+  #config;
+
+  /** @type {Map<string, { name: string, description: string, parameters: object, execute: function }>} */
+  #tools;
+
+  /** @type {string} */
+  #traceId;
+
+  /** @type {import('./conversation/persist.js').ConversationStore|null} */
+  #conversationStore;
+
+  /** @type {import('./memory/store.js').MemoryStore|null} */
+  #memoryStore;
+
+  /**
+   * @param {{
+   *   adapter: import('./llm/adapter.js').LLMAdapter,
+   *   trace: object,
+   *   config: object,
+   *   conversationStore?: import('./conversation/persist.js').ConversationStore,
+   *   memoryStore?: import('./memory/store.js').MemoryStore
+   * }} params
+   */
+  constructor({ adapter, trace, config, conversationStore, memoryStore }) {
+    this.#adapter = adapter;
+    this.#trace = trace;
+    this.#config = config;
+    this.#tools = new Map();
+    this.#traceId = randomUUID();
+    this.#conversationStore = conversationStore || null;
+    this.#memoryStore = memoryStore || null;
+  }
+
+  /**
+   * Register a tool that the LLM can call.
+   *
+   * @param {{ name: string, description: string, parameters: object, execute: (input: object, ctx?: { signal?: AbortSignal }) => Promise<string> }} tool
+   */
+  registerTool(tool) {
+    this.#tools.set(tool.name, tool);
+  }
+
+  /**
+   * Unregister a tool.
+   *
+   * @param {string} name
+   */
+  unregisterTool(name) {
+    this.#tools.delete(name);
+  }
+
+  /**
+   * Get the list of registered tool definitions (for passing to the adapter).
+   *
+   * @returns {import('./llm/adapter.js').UnifiedToolDef[]}
+   */
+  #getToolDefs() {
+    const defs = [];
+    for (const [, tool] of this.#tools) {
+      defs.push({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+      });
+    }
+    return defs;
+  }
+
+  /**
+   * Build the system prompt with memory and compact summary.
+   *
+   * @param {string} mode
+   * @param {{ profile?: string, entries?: object[] }} [memory]
+   * @param {string} [compactSummary]
+   * @returns {string}
+   */
+  #buildSystemPrompt(mode, memory, compactSummary) {
+    return buildSystemPrompt({
+      language: this.#config.language || 'en',
+      mode,
+      toolNames: Array.from(this.#tools.keys()),
+      memory,
+      compactSummary,
+    });
+  }
+
+  /**
+   * Perform memory recall for a given prompt.
+   *
+   * @param {string} prompt
+   * @returns {Promise<{ profile: string, entries: object[] }|null>}
+   */
+  async #recallMemory(prompt) {
+    if (!this.#memoryStore) return null;
+
+    const memory = { profile: '', entries: [] };
+
+    // Read user profile
+    memory.profile = this.#memoryStore.readProfile();
+
+    // Recall relevant entries
+    try {
+      const result = await recall({
+        prompt,
+        adapter: this.#adapter,
+        config: this.#config,
+        memoryStore: this.#memoryStore,
+      });
+      memory.entries = result.entries;
+    } catch {
+      // Recall failure is non-critical
+    }
+
+    return memory;
+  }
+
+  /**
+   * Read compact summary from conversation store.
+   *
+   * @returns {string}
+   */
+  #getCompactSummary() {
+    if (!this.#conversationStore) return '';
+    return this.#conversationStore.readCompactSummary();
+  }
+
+  /**
+   * Persist user message and assistant response to conversation store.
+   *
+   * @param {string} userContent
+   * @param {string} assistantContent
+   * @param {string} mode
+   * @param {object[]} [toolCalls]
+   */
+  #persistMessages(userContent, assistantContent, mode, toolCalls) {
+    if (!this.#conversationStore) return;
+
+    // Persist user message
+    this.#conversationStore.append({
+      role: 'user',
+      content: userContent,
+      mode,
+    });
+
+    // Persist assistant message
+    const assistantMsg = {
+      role: 'assistant',
+      content: assistantContent,
+      mode,
+      model: this.#config.model,
+    };
+    if (toolCalls && toolCalls.length > 0) {
+      assistantMsg.toolCalls = toolCalls;
+    }
+    this.#conversationStore.append(assistantMsg);
+  }
+
+  /**
+   * Check and trigger consolidation if needed.
+   *
+   * @returns {Promise<{ archivedCount: number, extractedCount: number }|null>}
+   */
+  async #maybeConsolidate() {
+    if (!this.#conversationStore || !this.#memoryStore) return null;
+
+    const budget = this.#config.messageTokenBudget || 8192;
+    if (!shouldConsolidate(this.#conversationStore, budget)) return null;
+
+    try {
+      const result = await consolidate({
+        conversationStore: this.#conversationStore,
+        memoryStore: this.#memoryStore,
+        adapter: this.#adapter,
+        config: this.#config,
+        budget,
+      });
+      return { archivedCount: result.archivedCount, extractedCount: result.extractedEntries.length };
+    } catch {
+      // Consolidation failure is non-critical
+      return null;
+    }
+  }
+
+  /**
+   * Run a query — the main loop.
+   *
+   * Yields EngineEvent objects that the caller (CLI, web) can consume
+   * to render output in real-time.
+   *
+   * @param {{ prompt: string, mode?: string, messages?: Array, signal?: AbortSignal }} params
+   * @yields {EngineEvent}
+   */
+  async *query({ prompt, mode = 'chat', messages = [], signal }) {
+    if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
+      yield {
+        type: 'error',
+        error: new Error('prompt is required and must be a non-empty string'),
+        retryable: false,
+      };
+      return;
+    }
+
+    // ─── Pre-query: Recall + Compact Summary ────────────────
+    const memory = await this.#recallMemory(prompt);
+    if (memory && memory.entries.length > 0) {
+      yield { type: 'recall', entryCount: memory.entries.length, cached: false };
+    }
+
+    const compactSummary = this.#getCompactSummary();
+    const systemPrompt = this.#buildSystemPrompt(mode, memory, compactSummary);
+
+    // Build conversation: existing messages + new user message
+    const conversationMessages = [
+      ...messages,
+      { role: 'user', content: prompt },
+    ];
+
+    const toolDefs = this.#getToolDefs();
+    let turnNumber = 0;
+    let continueTurns = 0; // auto-continue counter
+    let fullResponseText = '';
+    let currentModel = this.#config.model;
+
+    while (true) {
+      turnNumber++;
+
+      // Safety: prevent infinite loops
+      if (turnNumber > MAX_TURNS) {
+        yield {
+          type: 'error',
+          error: new Error(`Max turns (${MAX_TURNS}) reached — stopping to prevent infinite loop`),
+          retryable: false,
+        };
+        break;
+      }
+
+      const turnId = this.#trace.startTurn({
+        traceId: this.#traceId,
+        mode,
+        turnNumber,
+      });
+
+      const startTime = Date.now();
+      let responseText = '';
+      const toolCalls = [];
+      let stopReason = 'end_turn';
+      const totalUsage = { inputTokens: 0, outputTokens: 0 };
+
+      yield { type: 'turn_start', turnNumber };
+
+      try {
+        // Stream from adapter
+        for await (const event of this.#adapter.stream({
+          model: currentModel,
+          system: systemPrompt,
+          messages: [...conversationMessages],
+          tools: toolDefs.length > 0 ? toolDefs : undefined,
+          maxTokens: this.#config.maxOutputTokens || 16384,
+          signal,
+        })) {
+          switch (event.type) {
+            case 'text_delta':
+              responseText += event.text;
+              yield event;
+              break;
+            case 'thinking_delta':
+              yield event;
+              break;
+            case 'tool_call':
+              toolCalls.push(event);
+              yield event;
+              break;
+            case 'usage':
+              totalUsage.inputTokens += event.inputTokens;
+              totalUsage.outputTokens += event.outputTokens;
+              yield event;
+              break;
+            case 'stop':
+              stopReason = event.stopReason;
+              yield event;
+              break;
+            case 'error':
+              yield event;
+              break;
+          }
+        }
+      } catch (err) {
+        const latencyMs = Date.now() - startTime;
+        this.#trace.endTurn(turnId, {
+          model: currentModel,
+          inputTokens: totalUsage.inputTokens,
+          outputTokens: totalUsage.outputTokens,
+          stopReason: 'error',
+          latencyMs,
+          responseText,
+        });
+
+        // ─── LLMContextError → force compact → retry ──────
+        if (err instanceof LLMContextError && this.#conversationStore && this.#memoryStore) {
+          const consolidated = await this.#maybeConsolidate();
+          if (consolidated && consolidated.archivedCount > 0) {
+            yield { type: 'consolidate', archivedCount: consolidated.archivedCount, extractedCount: consolidated.extractedCount };
+            yield { type: 'turn_end', turnNumber, stopReason: 'context_overflow_retry' };
+            continue; // retry with fewer messages
+          }
+        }
+
+        // ─── Fallback model ──────────────────────────────
+        const fallbackModel = this.#config.fallbackModel;
+        if (fallbackModel && fallbackModel !== currentModel &&
+            (err.name === 'LLMRateLimitError' || err.name === 'LLMServerError')) {
+          yield { type: 'fallback', from: currentModel, to: fallbackModel, reason: err.message };
+          currentModel = fallbackModel;
+          yield { type: 'turn_end', turnNumber, stopReason: 'fallback_retry' };
+          continue; // retry with fallback model
+        }
+
+        yield {
+          type: 'error',
+          error: err,
+          retryable: err.name === 'LLMRateLimitError' || err.name === 'LLMServerError',
+        };
+        yield { type: 'turn_end', turnNumber, stopReason: 'error' };
+        break;
+      }
+
+      const latencyMs = Date.now() - startTime;
+
+      // Record turn in debug trace
+      this.#trace.endTurn(turnId, {
+        model: currentModel,
+        inputTokens: totalUsage.inputTokens,
+        outputTokens: totalUsage.outputTokens,
+        stopReason,
+        latencyMs,
+        responseText,
+      });
+
+      // Append assistant message to conversation
+      const assistantMsg = { role: 'assistant', content: responseText };
+      if (toolCalls.length > 0) {
+        assistantMsg.toolCalls = toolCalls.map(tc => ({
+          id: tc.id,
+          name: tc.name,
+          input: tc.input,
+        }));
+      }
+      conversationMessages.push(assistantMsg);
+      fullResponseText += responseText;
+
+      // ─── Handle max_tokens → auto-continue ────────────
+      if (stopReason === 'max_tokens' && continueTurns < MAX_CONTINUE_TURNS) {
+        continueTurns++;
+        // Append a "Continue" user message
+        conversationMessages.push({ role: 'user', content: 'Continue' });
+        yield { type: 'turn_end', turnNumber, stopReason: 'max_tokens_continue' };
+        continue; // loop back to call adapter again
+      }
+
+      // If no tool calls, we're done
+      if (stopReason !== 'tool_use' || toolCalls.length === 0) {
+        yield { type: 'turn_end', turnNumber, stopReason };
+
+        // ─── Post-query: Persist + Consolidate ────────────
+        this.#persistMessages(prompt, fullResponseText, mode, assistantMsg.toolCalls);
+
+        const consolidated = await this.#maybeConsolidate();
+        if (consolidated && consolidated.archivedCount > 0) {
+          yield { type: 'consolidate', archivedCount: consolidated.archivedCount, extractedCount: consolidated.extractedCount };
+        }
+
+        break;
+      }
+
+      // Execute tool calls and feed results back
+      for (const tc of toolCalls) {
+        const tool = this.#tools.get(tc.name);
+        const toolStartTime = Date.now();
+
+        let output;
+        let isError = false;
+
+        if (!tool) {
+          output = `Error: unknown tool "${tc.name}"`;
+          isError = true;
+          yield { type: 'tool_end', id: tc.id, name: tc.name, output, isError: true };
+        } else {
+          try {
+            yield { type: 'tool_start', id: tc.id, name: tc.name, input: tc.input };
+            output = await tool.execute(tc.input, { signal });
+            yield { type: 'tool_end', id: tc.id, name: tc.name, output, isError: false };
+          } catch (err) {
+            output = `Error: ${err.message}`;
+            isError = true;
+            yield { type: 'tool_end', id: tc.id, name: tc.name, output, isError: true };
+          }
+        }
+
+        const toolDurationMs = Date.now() - toolStartTime;
+
+        // Log tool to debug trace
+        this.#trace.logTool(turnId, {
+          toolName: tc.name,
+          toolInput: JSON.stringify(tc.input),
+          toolOutput: output,
+          durationMs: toolDurationMs,
+          isError,
+        });
+
+        // Append tool result to conversation
+        conversationMessages.push({
+          role: 'tool',
+          toolCallId: tc.id,
+          content: output,
+          isError,
+        });
+      }
+
+      yield { type: 'turn_end', turnNumber, stopReason: 'tool_use' };
+
+      // Loop back to call adapter again with tool results
+    }
+  }
+
+  /**
+   * Get the trace ID for this engine instance.
+   * @returns {string}
+   */
+  get traceId() {
+    return this.#traceId;
+  }
+
+  /**
+   * Get registered tool names.
+   * @returns {string[]}
+   */
+  get toolNames() {
+    return Array.from(this.#tools.keys());
+  }
+
+  /**
+   * Get the conversation store (for external access, e.g., CLI commands).
+   * @returns {import('./conversation/persist.js').ConversationStore|null}
+   */
+  get conversationStore() {
+    return this.#conversationStore;
+  }
+
+  /**
+   * Get the memory store (for external access, e.g., CLI commands).
+   * @returns {import('./memory/store.js').MemoryStore|null}
+   */
+  get memoryStore() {
+    return this.#memoryStore;
+  }
+}

package/unify/index.js

@@ -0,0 +1,27 @@
+/**
+ * index.js — Yeaft Unify module entry point
+ *
+ * Re-exports all public APIs for external consumption.
+ */
+
+export { initYeaftDir, DEFAULT_YEAFT_DIR } from './init.js';
+export { loadConfig, parseFrontmatter } from './config.js';
+export { DebugTrace, NullTrace, createTrace } from './debug-trace.js';
+export {
+  LLMAdapter,
+  LLMRateLimitError,
+  LLMAuthError,
+  LLMContextError,
+  LLMServerError,
+  LLMAbortError,
+  createLLMAdapter,
+} from './llm/adapter.js';
+export { MODEL_REGISTRY, resolveModel, listModels, isKnownModel } from './models.js';
+export { buildSystemPrompt, SUPPORTED_LANGUAGES } from './prompts.js';
+export { Engine } from './engine.js';
+export { ConversationStore, parseMessage, estimateTokens } from './conversation/persist.js';
+export { searchMessages } from './conversation/search.js';
+export { MemoryStore, parseEntry, serializeEntry, MEMORY_KINDS } from './memory/store.js';
+export { recall, extractKeywords, computeFingerprint, clearRecallCache } from './memory/recall.js';
+export { extractMemories } from './memory/extract.js';
+export { consolidate, shouldConsolidate } from './memory/consolidate.js';

package/unify/init.js

@@ -0,0 +1,147 @@
+/**
+ * init.js — Yeaft directory structure initialization
+ *
+ * Ensures ~/.yeaft/ and all required subdirectories exist.
+ * Creates default config.md, MEMORY.md, and conversation/index.md if missing.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+/** Default directory for Yeaft data. */
+export const DEFAULT_YEAFT_DIR = join(homedir(), '.yeaft');
+
+/** Subdirectories that must exist inside the Yeaft data directory. */
+const SUBDIRS = [
+  'conversation/messages',
+  'conversation/cold',
+  'conversation/blobs',
+  'memory/entries',
+  'tasks',
+  'dream',
+  'skills',
+];
+
+/** Default config.md content (YAML frontmatter + markdown body). */
+const DEFAULT_CONFIG = `---
+model: claude-sonnet-4-20250514
+language: en
+debug: false
+maxContextTokens: 200000
+---
+
+# Yeaft Config
+
+Edit the YAML frontmatter above to change settings.
+The \`model\` field is a model ID (e.g. \`gpt-5\`, \`claude-sonnet-4-20250514\`).
+Yeaft auto-detects the correct API adapter and endpoint from the model ID.
+
+## Language
+
+Set \`language\` in frontmatter or \`YEAFT_LANGUAGE\` env var:
+- \`en\` — English system prompts (default)
+- \`zh\` — Chinese system prompts (中文系统提示)
+
+## Model IDs
+
+- \`claude-sonnet-4-20250514\` (default)
+- \`claude-opus-4-20250514\`
+- \`gpt-5\`, \`gpt-5.4\`, \`gpt-4.1\`, \`gpt-4.1-mini\`
+- \`o3\`, \`o4-mini\`
+- \`deepseek-chat\`, \`deepseek-reasoner\`
+- \`gemini-2.5-pro\`, \`gemini-2.5-flash\`
+
+## API Keys
+
+Store API keys in \`~/.yeaft/.env\` (recommended) or export as env vars:
+
+\`\`\`bash
+# ~/.yeaft/.env
+YEAFT_API_KEY=sk-ant-...          # Anthropic
+YEAFT_OPENAI_API_KEY=sk-...       # OpenAI / DeepSeek / Gemini
+\`\`\`
+
+## Environment Variables
+
+Shell env vars take precedence over .env and config.md:
+
+- \`YEAFT_MODEL\` — override model ID
+- \`YEAFT_LANGUAGE\` — language for system prompts (en/zh)
+- \`YEAFT_API_KEY\` — Anthropic API key
+- \`YEAFT_OPENAI_API_KEY\` — OpenAI-compatible API key
+- \`YEAFT_PROXY_URL\` — CopilotProxy URL (default: http://localhost:6628)
+- \`YEAFT_DEBUG\` — enable debug mode (1/true)
+- \`YEAFT_DIR\` — data directory (default: ~/.yeaft)
+`;
+
+/** Default MEMORY.md content. */
+const DEFAULT_MEMORY = `# Yeaft Memory
+
+This file stores persistent memory entries. The agent will read and update this file.
+
+## Facts
+
+## Preferences
+
+## Project Context
+
+`;
+
+/** Default conversation/index.md content. */
+const DEFAULT_CONVERSATION_INDEX = `---
+lastMessageId: null
+totalMessages: 0
+---
+
+# Conversation Index
+
+This file tracks the conversation state for the "one eternal conversation" model.
+`;
+
+/**
+ * Initialize the Yeaft data directory structure.
+ *
+ * @param {string} [dir] — Root directory path. Defaults to ~/.yeaft/
+ * @returns {{ dir: string, created: string[] }} — The root dir and list of created paths
+ */
+export function initYeaftDir(dir) {
+  const root = dir || DEFAULT_YEAFT_DIR;
+  const created = [];
+
+  // Ensure root exists
+  if (!existsSync(root)) {
+    mkdirSync(root, { recursive: true });
+    created.push(root);
+  }
+
+  // Ensure all subdirectories exist
+  for (const sub of SUBDIRS) {
+    const fullPath = join(root, sub);
+    if (!existsSync(fullPath)) {
+      mkdirSync(fullPath, { recursive: true });
+      created.push(fullPath);
+    }
+  }
+
+  // Create default files if they don't exist
+  const configPath = join(root, 'config.md');
+  if (!existsSync(configPath)) {
+    writeFileSync(configPath, DEFAULT_CONFIG, 'utf8');
+    created.push(configPath);
+  }
+
+  const memoryPath = join(root, 'memory', 'MEMORY.md');
+  if (!existsSync(memoryPath)) {
+    writeFileSync(memoryPath, DEFAULT_MEMORY, 'utf8');
+    created.push(memoryPath);
+  }
+
+  const indexPath = join(root, 'conversation', 'index.md');
+  if (!existsSync(indexPath)) {
+    writeFileSync(indexPath, DEFAULT_CONVERSATION_INDEX, 'utf8');
+    created.push(indexPath);
+  }
+
+  return { dir: root, created };
+}