@yeaft/webchat-agent 0.1.398 → 0.1.408

package/unify/engine.js

@@ -0,0 +1,319 @@
+/**
+ * engine.js — Yeaft query loop
+ *
+ * The engine is the core orchestrator:
+ *   1. Build messages array
+ *   2. Call adapter.stream()
+ *   3. Collect text + tool_calls from stream events
+ *   4. If tool_calls → execute tools → append results → goto 2
+ *   5. If end_turn → done
+ *   6. If max_tokens → done (Phase 2: auto-continue)
+ *
+ * Pattern derived from Claude Code's query loop (src/query.ts).
+ */
+
+import { randomUUID } from 'crypto';
+import { buildSystemPrompt } from './prompts.js';
+
+/** Maximum number of turns before the engine stops to prevent infinite loops. */
+const MAX_TURNS = 25;
+
+// ─── 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 {import('./llm/adapter.js').StreamEvent | TurnStartEvent | TurnEndEvent | ToolStartEvent | ToolEndEvent} 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;
+
+  /**
+   * @param {{ adapter: import('./llm/adapter.js').LLMAdapter, trace: object, config: object }} params
+   */
+  constructor({ adapter, trace, config }) {
+    this.#adapter = adapter;
+    this.#trace = trace;
+    this.#config = config;
+    this.#tools = new Map();
+    this.#traceId = randomUUID();
+  }
+
+  /**
+   * 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.
+   *
+   * @param {string} mode — 'chat' | 'work' | 'dream'
+   * @returns {string}
+   */
+  #buildSystemPrompt(mode) {
+    return buildSystemPrompt({
+      language: this.#config.language || 'en',
+      mode,
+      toolNames: Array.from(this.#tools.keys()),
+    });
+  }
+
+  /**
+   * 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;
+    }
+
+    const systemPrompt = this.#buildSystemPrompt(mode);
+
+    // Build conversation: existing messages + new user message
+    const conversationMessages = [
+      ...messages,
+      { role: 'user', content: prompt },
+    ];
+
+    const toolDefs = this.#getToolDefs();
+    let turnNumber = 0;
+
+    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
+        // Note: pass a snapshot of messages so later mutations don't affect the adapter
+        for await (const event of this.#adapter.stream({
+          model: this.#config.model,
+          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) {
+        // Adapter threw an exception (network, auth, etc.)
+        const latencyMs = Date.now() - startTime;
+        this.#trace.endTurn(turnId, {
+          model: this.#config.model,
+          inputTokens: totalUsage.inputTokens,
+          outputTokens: totalUsage.outputTokens,
+          stopReason: 'error',
+          latencyMs,
+          responseText,
+        });
+
+        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: this.#config.model,
+        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);
+
+      // If no tool calls, we're done
+      if (stopReason !== 'tool_use' || toolCalls.length === 0) {
+        yield { type: 'turn_end', turnNumber, stopReason };
+        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());
+  }
+}

package/unify/index.js

@@ -0,0 +1,21 @@
+/**
+ * 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';

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 };
+}

package/unify/llm/adapter.js

@@ -0,0 +1,186 @@
+/**
+ * adapter.js — LLM Adapter base class, unified types, and factory
+ *
+ * Design decision (2026-04-10): Only two adapters needed:
+ *   1. AnthropicAdapter — Anthropic Messages API
+ *   2. ChatCompletionsAdapter — OpenAI Chat Completions API (covers GPT, DeepSeek, CopilotProxy, etc.)
+ *
+ * The engine sees only unified types — it never knows which API is underneath.
+ */
+
+// ─── Unified Types ─────────────────────────────────────────────
+
+/**
+ * @typedef {Object} UnifiedToolDef
+ * @property {string} name
+ * @property {string} description
+ * @property {object} parameters — JSON Schema
+ */
+
+/**
+ * @typedef {Object} UnifiedToolCall
+ * @property {string} id
+ * @property {string} name
+ * @property {object} input — Parsed object (not JSON string)
+ */
+
+/**
+ * @typedef {Object} UnifiedToolResult
+ * @property {string} toolCallId
+ * @property {string} output
+ * @property {boolean} [isError]
+ */
+
+// ─── Unified Event Stream ──────────────────────────────────────
+
+/**
+ * @typedef {{ type: 'text_delta', text: string }} TextDeltaEvent
+ * @typedef {{ type: 'thinking_delta', text: string }} ThinkingDeltaEvent
+ * @typedef {{ type: 'tool_call', id: string, name: string, input: object }} ToolCallEvent
+ * @typedef {{ type: 'usage', inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheWriteTokens?: number }} UsageEvent
+ * @typedef {{ type: 'stop', stopReason: 'end_turn' | 'tool_use' | 'max_tokens' }} StopEvent
+ * @typedef {{ type: 'error', error: Error, retryable: boolean }} ErrorEvent
+ *
+ * @typedef {TextDeltaEvent | ThinkingDeltaEvent | ToolCallEvent | UsageEvent | StopEvent | ErrorEvent} StreamEvent
+ */
+
+// ─── Unified Message Types ─────────────────────────────────────
+
+/**
+ * @typedef {{ role: 'system', content: string }} SystemMessage
+ * @typedef {{ role: 'user', content: string }} UserMessage
+ * @typedef {{ role: 'assistant', content: string, toolCalls?: UnifiedToolCall[] }} AssistantMessage
+ * @typedef {{ role: 'tool', toolCallId: string, content: string, isError?: boolean }} ToolMessage
+ *
+ * @typedef {SystemMessage | UserMessage | AssistantMessage | ToolMessage} UnifiedMessage
+ */
+
+// ─── Error Types ───────────────────────────────────────────────
+
+/** Rate limit error (429, 529) — retryable with backoff. */
+export class LLMRateLimitError extends Error {
+  constructor(message, statusCode, retryAfterMs = null) {
+    super(message);
+    this.name = 'LLMRateLimitError';
+    this.statusCode = statusCode;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+/** Authentication error (401, 403) — need to re-authenticate. */
+export class LLMAuthError extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.name = 'LLMAuthError';
+    this.statusCode = statusCode;
+  }
+}
+
+/** Context too long error (413 or API-specific) — need compaction. */
+export class LLMContextError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'LLMContextError';
+  }
+}
+
+/** Server error (500, 502, 503) — retryable. */
+export class LLMServerError extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.name = 'LLMServerError';
+    this.statusCode = statusCode;
+  }
+}
+
+/** Abort error — signal was aborted. */
+export class LLMAbortError extends Error {
+  constructor() {
+    super('Request aborted');
+    this.name = 'LLMAbortError';
+  }
+}
+
+// ─── Base Class ────────────────────────────────────────────────
+
+/**
+ * LLMAdapter — Abstract base class for LLM API adapters.
+ *
+ * Subclasses implement stream() and call() to talk to a specific API,
+ * translating between the unified types and the wire format.
+ */
+export class LLMAdapter {
+  /**
+   * @param {object} config — Adapter-specific configuration
+   */
+  constructor(config = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Stream a model response with tool support (the query loop call).
+   *
+   * @param {{ model: string, system: string, messages: UnifiedMessage[], tools?: UnifiedToolDef[], maxTokens?: number, signal?: AbortSignal }} params
+   * @returns {AsyncGenerator<StreamEvent>}
+   */
+  async *stream(params) { // eslint-disable-line no-unused-vars
+    throw new Error('stream() must be implemented by subclass');
+  }
+
+  /**
+   * Make a single model call without tools (for side queries like summarization).
+   *
+   * @param {{ model: string, system: string, messages: UnifiedMessage[], maxTokens?: number, signal?: AbortSignal }} params
+   * @returns {Promise<{ text: string, usage: { inputTokens: number, outputTokens: number } }>}
+   */
+  async call(params) { // eslint-disable-line no-unused-vars
+    throw new Error('call() must be implemented by subclass');
+  }
+}
+
+// ─── Factory ───────────────────────────────────────────────────
+
+/**
+ * Create an LLM adapter based on configuration.
+ *
+ * @param {object} config — From loadConfig()
+ * @returns {Promise<LLMAdapter>}
+ */
+export async function createLLMAdapter(config) {
+  // Normalize adapter name — accept 'chat-completions' as alias for 'openai'
+  const adapter = config.adapter === 'chat-completions' ? 'openai' : config.adapter;
+
+  if (adapter === 'anthropic' || (!adapter && config.apiKey)) {
+    if (!config.apiKey) {
+      throw new Error('Anthropic adapter requires YEAFT_API_KEY');
+    }
+    const { AnthropicAdapter } = await import('./anthropic.js');
+    return new AnthropicAdapter({
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl || undefined, // AnthropicAdapter has its own default
+    });
+  }
+
+  if (adapter === 'openai' || (!adapter && config.openaiApiKey)) {
+    if (!config.openaiApiKey && !config.apiKey) {
+      throw new Error('OpenAI adapter requires YEAFT_OPENAI_API_KEY (or YEAFT_API_KEY as fallback)');
+    }
+    const { ChatCompletionsAdapter } = await import('./chat-completions.js');
+    return new ChatCompletionsAdapter({
+      apiKey: config.openaiApiKey || config.apiKey,
+      baseUrl: config.baseUrl || 'https://api.openai.com/v1',
+    });
+  }
+
+  if (adapter === 'proxy' || (!adapter && config.proxyUrl)) {
+    const { ChatCompletionsAdapter } = await import('./chat-completions.js');
+    return new ChatCompletionsAdapter({
+      apiKey: 'proxy', // CopilotProxy handles auth
+      baseUrl: `${config.proxyUrl}/v1`,
+    });
+  }
+
+  throw new Error(
+    'No LLM adapter configured. Set YEAFT_API_KEY (Anthropic), YEAFT_OPENAI_API_KEY (OpenAI), or YEAFT_PROXY_URL (CopilotProxy).',
+  );
+}