@yeaft/webchat-agent 0.1.399 → 0.1.409

package/unify/llm/chat-completions.js

@@ -0,0 +1,315 @@
+/**
+ * chat-completions.js — OpenAI Chat Completions API adapter
+ *
+ * Covers ALL OpenAI-compatible backends via baseUrl:
+ *   - https://api.openai.com/v1           → OpenAI direct
+ *   - https://api.deepseek.com            → DeepSeek
+ *   - http://localhost:6628/v1            → CopilotProxy
+ *   - Azure, Ollama, LMStudio, etc.
+ *
+ * Key translation responsibilities:
+ *   Request:  UnifiedToolDef → { type: "function", function: { name, description, parameters } }
+ *   Response: delta.tool_calls[i].function.arguments (JSON string) → accumulate → JSON.parse → UnifiedToolCall
+ *   Result:   UnifiedToolResult → { role: "tool", tool_call_id, content }
+ *   Finish:   "tool_calls" → "tool_use", "stop" → "end_turn", "length" → "max_tokens"
+ */
+
+import {
+  LLMAdapter,
+  LLMRateLimitError,
+  LLMAuthError,
+  LLMContextError,
+  LLMServerError,
+  LLMAbortError,
+} from './adapter.js';
+
+/**
+ * ChatCompletionsAdapter — Talks to OpenAI Chat Completions API and compatibles.
+ */
+export class ChatCompletionsAdapter extends LLMAdapter {
+  #apiKey;
+  #baseUrl;
+
+  /**
+   * @param {{ apiKey: string, baseUrl: string }} config
+   */
+  constructor({ apiKey, baseUrl }) {
+    super({ apiKey, baseUrl });
+    this.#apiKey = apiKey;
+    this.#baseUrl = baseUrl.replace(/\/+$/, ''); // strip trailing slash
+  }
+
+  /**
+   * Translate UnifiedToolDef[] → Chat Completions tool format.
+   * @param {import('./adapter.js').UnifiedToolDef[]} tools
+   * @returns {object[]|undefined}
+   */
+  #translateTools(tools) {
+    if (!tools || tools.length === 0) return undefined;
+    return tools.map(t => ({
+      type: 'function',
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      },
+    }));
+  }
+
+  /**
+   * Translate UnifiedMessage[] → Chat Completions message format.
+   * @param {string} system — System prompt
+   * @param {import('./adapter.js').UnifiedMessage[]} messages
+   * @returns {object[]}
+   */
+  #translateMessages(system, messages) {
+    const result = [];
+
+    // System message first
+    if (system) {
+      result.push({ role: 'system', content: system });
+    }
+
+    for (const msg of messages) {
+      if (msg.role === 'system') {
+        result.push({ role: 'system', content: msg.content });
+      } else if (msg.role === 'user') {
+        result.push({ role: 'user', content: msg.content });
+      } else if (msg.role === 'assistant') {
+        const entry = { role: 'assistant' };
+        // Some OpenAI-compatible APIs require `content: null` when tool_calls are present
+        entry.content = msg.content || null;
+        if (msg.toolCalls && msg.toolCalls.length > 0) {
+          entry.tool_calls = msg.toolCalls.map(tc => ({
+            id: tc.id,
+            type: 'function',
+            function: {
+              name: tc.name,
+              arguments: JSON.stringify(tc.input),
+            },
+          }));
+        }
+        result.push(entry);
+      } else if (msg.role === 'tool') {
+        result.push({
+          role: 'tool',
+          tool_call_id: msg.toolCallId,
+          content: msg.content,
+        });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Classify HTTP errors.
+   * @param {number} status
+   * @param {string} body
+   */
+  #classifyError(status, body) {
+    if (status === 401 || status === 403) {
+      return new LLMAuthError(`Auth error: ${body}`, status);
+    }
+    if (status === 429) {
+      return new LLMRateLimitError(`Rate limit: ${body}`, status);
+    }
+    if (status === 529) {
+      return new LLMRateLimitError(`Overloaded: ${body}`, status);
+    }
+    if (status === 413 || body.includes('context_length_exceeded') || body.includes('maximum context length')) {
+      return new LLMContextError(`Context too long: ${body}`);
+    }
+    if (status >= 500) {
+      return new LLMServerError(`Server error: ${body}`, status);
+    }
+    return new Error(`API error ${status}: ${body}`);
+  }
+
+  /**
+   * Map Chat Completions finish_reason → unified stop reason.
+   * @param {string|null} reason
+   * @returns {'end_turn' | 'tool_use' | 'max_tokens'}
+   */
+  #mapFinishReason(reason) {
+    switch (reason) {
+      case 'tool_calls': return 'tool_use';
+      case 'stop': return 'end_turn';
+      case 'length': return 'max_tokens';
+      default: return 'end_turn';
+    }
+  }
+
+  /**
+   * @param {{ model: string, system: string, messages: import('./adapter.js').UnifiedMessage[], tools?: import('./adapter.js').UnifiedToolDef[], maxTokens?: number, signal?: AbortSignal }} params
+   * @returns {AsyncGenerator<import('./adapter.js').StreamEvent>}
+   */
+  async *stream({ model, system, messages, tools, maxTokens = 16384, signal }) {
+    if (signal?.aborted) throw new LLMAbortError();
+
+    const body = {
+      model,
+      messages: this.#translateMessages(system, messages),
+      max_tokens: maxTokens,
+      stream: true,
+      stream_options: { include_usage: true },
+    };
+
+    const translatedTools = this.#translateTools(tools);
+    if (translatedTools) body.tools = translatedTools;
+
+    const response = await fetch(`${this.#baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.#apiKey}`,
+      },
+      body: JSON.stringify(body),
+      signal,
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      throw this.#classifyError(response.status, errorBody);
+    }
+
+    // Parse SSE stream
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    // Tool call accumulation — Chat Completions sends tool args as fragments
+    // keyed by index within the delta.tool_calls array
+    /** @type {Map<number, { id: string, name: string, arguments: string }>} */
+    const toolCallAccum = new Map();
+
+    try {
+      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).trim();
+          if (data === '[DONE]') continue;
+
+          let chunk;
+          try {
+            chunk = JSON.parse(data);
+          } catch {
+            continue;
+          }
+
+          // Usage (from stream_options: include_usage)
+          if (chunk.usage) {
+            yield {
+              type: 'usage',
+              inputTokens: chunk.usage.prompt_tokens || 0,
+              outputTokens: chunk.usage.completion_tokens || 0,
+              cacheReadTokens: chunk.usage.prompt_tokens_details?.cached_tokens || 0,
+              cacheWriteTokens: 0,
+            };
+          }
+
+          const choice = chunk.choices?.[0];
+          if (!choice) continue;
+
+          const delta = choice.delta;
+          if (!delta) continue;
+
+          // Text content
+          if (delta.content) {
+            yield { type: 'text_delta', text: delta.content };
+          }
+
+          // Tool calls (streamed as fragments)
+          if (delta.tool_calls) {
+            for (const tc of delta.tool_calls) {
+              const idx = tc.index;
+              if (!toolCallAccum.has(idx)) {
+                toolCallAccum.set(idx, {
+                  id: tc.id || '',
+                  name: tc.function?.name || '',
+                  arguments: '',
+                });
+              }
+              const accum = toolCallAccum.get(idx);
+              if (tc.id) accum.id = tc.id;
+              if (tc.function?.name) accum.name = tc.function.name;
+              if (tc.function?.arguments) accum.arguments += tc.function.arguments;
+            }
+          }
+
+          // Finish reason
+          if (choice.finish_reason) {
+            // Emit accumulated tool calls before stop
+            for (const [, accum] of toolCallAccum) {
+              let parsedInput = {};
+              try {
+                parsedInput = accum.arguments ? JSON.parse(accum.arguments) : {};
+              } catch {
+                parsedInput = {};
+              }
+              yield {
+                type: 'tool_call',
+                id: accum.id,
+                name: accum.name,
+                input: parsedInput,
+              };
+            }
+            toolCallAccum.clear();
+
+            yield {
+              type: 'stop',
+              stopReason: this.#mapFinishReason(choice.finish_reason),
+            };
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  /**
+   * Non-streaming call for side queries.
+   */
+  async call({ model, system, messages, maxTokens = 4096, signal }) {
+    if (signal?.aborted) throw new LLMAbortError();
+
+    const body = {
+      model,
+      messages: this.#translateMessages(system, messages),
+      max_tokens: maxTokens,
+    };
+
+    const response = await fetch(`${this.#baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.#apiKey}`,
+      },
+      body: JSON.stringify(body),
+      signal,
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      throw this.#classifyError(response.status, errorBody);
+    }
+
+    const result = await response.json();
+    const text = result.choices?.[0]?.message?.content || '';
+
+    return {
+      text,
+      usage: {
+        inputTokens: result.usage?.prompt_tokens || 0,
+        outputTokens: result.usage?.completion_tokens || 0,
+      },
+    };
+  }
+}

package/unify/memory/consolidate.js

@@ -0,0 +1,187 @@
+/**
+ * consolidate.js — Consolidate = compact + extract (one LLM call)
+ *
+ * Triggered when hot_tokens > MESSAGE_TOKEN_BUDGET.
+ * One LLM call does two things simultaneously:
+ *   1. Generate compact summary → append to compact.md ("short-term memory")
+ *   2. Extract memory entries → write to entries/ ("long-term memory")
+ *
+ * After consolidation:
+ *   - Processed messages moved from messages/ to cold/
+ *   - index.md + scopes.md updated
+ *
+ * Reference: yeaft-unify-core-systems.md §3.1, §4.2
+ *            yeaft-unify-design.md §6.1
+ */
+
+import { extractMemories } from './extract.js';
+
+// ─── Constants ──────────────────────────────────────────────────
+
+/** Default MESSAGE_TOKEN_BUDGET (context * 4%, default ~8192). */
+export const DEFAULT_MESSAGE_TOKEN_BUDGET = 8192;
+
+/** After compact, keep this fraction of the budget. */
+export const COMPACT_KEEP_RATIO = 0.4;
+
+/** Minimum messages to keep hot (newest). */
+const MIN_KEEP_MESSAGES = 3;
+
+// ─── Consolidate ────────────────────────────────────────────────
+
+/**
+ * Check if consolidation should be triggered.
+ *
+ * @param {import('../conversation/persist.js').ConversationStore} conversationStore
+ * @param {number} [budget] — MESSAGE_TOKEN_BUDGET
+ * @returns {boolean}
+ */
+export function shouldConsolidate(conversationStore, budget = DEFAULT_MESSAGE_TOKEN_BUDGET) {
+  const hotTokens = conversationStore.hotTokens();
+  return hotTokens > budget;
+}
+
+/**
+ * Determine which messages to archive (move to cold).
+ * Strategy: from oldest, accumulate tokens until remaining ≤ budget * 40%.
+ * Always keep at least MIN_KEEP_MESSAGES.
+ *
+ * @param {object[]} messages — all hot messages, sorted chronologically
+ * @param {number} budget — MESSAGE_TOKEN_BUDGET
+ * @returns {{ toArchive: object[], toKeep: object[] }}
+ */
+export function partitionMessages(messages, budget = DEFAULT_MESSAGE_TOKEN_BUDGET) {
+  if (messages.length <= MIN_KEEP_MESSAGES) {
+    return { toArchive: [], toKeep: messages };
+  }
+
+  const keepBudget = Math.floor(budget * COMPACT_KEEP_RATIO);
+
+  // Work backwards from newest: accumulate tokens until we hit keepBudget
+  let keepTokens = 0;
+  let keepStart = messages.length;
+
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msgTokens = messages[i].tokens_est || 0;
+    if (keepTokens + msgTokens > keepBudget && (messages.length - i) >= MIN_KEEP_MESSAGES) {
+      keepStart = i + 1;
+      break;
+    }
+    keepTokens += msgTokens;
+    if (i === 0) keepStart = 0;
+  }
+
+  // Ensure at least MIN_KEEP_MESSAGES are kept
+  keepStart = Math.min(keepStart, messages.length - MIN_KEEP_MESSAGES);
+  keepStart = Math.max(keepStart, 0);
+
+  return {
+    toArchive: messages.slice(0, keepStart),
+    toKeep: messages.slice(keepStart),
+  };
+}
+
+/**
+ * Generate a compact summary of messages.
+ *
+ * @param {object[]} messages — messages to summarize
+ * @param {object} adapter — LLM adapter with .call()
+ * @param {object} config — { model }
+ * @returns {Promise<string>} — compact summary text
+ */
+async function generateSummary(messages, adapter, config) {
+  const conversation = messages.map(m => {
+    const prefix = m.role === 'user' ? 'User' : m.role === 'assistant' ? 'Assistant' : m.role;
+    return `[${prefix}]: ${(m.content || '').slice(0, 500)}`;
+  }).join('\n\n');
+
+  const system = 'You are a conversation summarizer. Summarize the conversation concisely in 2-3 paragraphs, preserving key decisions, facts, and context. Write in the same language as the conversation.';
+
+  try {
+    const result = await adapter.call({
+      model: config.model,
+      system,
+      messages: [{ role: 'user', content: `Summarize this conversation:\n\n${conversation}` }],
+      maxTokens: 1024,
+    });
+    return result.text.trim();
+  } catch {
+    // Fallback: simple concatenation of first/last messages
+    const first = messages[0]?.content?.slice(0, 200) || '';
+    const last = messages[messages.length - 1]?.content?.slice(0, 200) || '';
+    return `[Auto-summary failed] Started with: ${first}... Ended with: ${last}`;
+  }
+}
+
+/**
+ * Run the full Consolidate pipeline.
+ *
+ * 1. Partition messages (what to archive vs keep)
+ * 2. Generate compact summary (LLM call)
+ * 3. Extract memory entries (LLM call)
+ * 4. Move archived messages to cold/
+ * 5. Update compact.md, index.md, scopes.md
+ *
+ * @param {{
+ *   conversationStore: import('../conversation/persist.js').ConversationStore,
+ *   memoryStore: import('./store.js').MemoryStore,
+ *   adapter: object,
+ *   config: object,
+ *   budget?: number
+ * }} params
+ * @returns {Promise<{ compactSummary: string, extractedEntries: string[], archivedCount: number }>}
+ */
+export async function consolidate({ conversationStore, memoryStore, adapter, config, budget = DEFAULT_MESSAGE_TOKEN_BUDGET }) {
+  // Load all hot messages
+  const messages = conversationStore.loadAll();
+
+  if (messages.length <= MIN_KEEP_MESSAGES) {
+    return { compactSummary: '', extractedEntries: [], archivedCount: 0 };
+  }
+
+  // Step 1: Partition
+  const { toArchive, toKeep } = partitionMessages(messages, budget);
+
+  if (toArchive.length === 0) {
+    return { compactSummary: '', extractedEntries: [], archivedCount: 0 };
+  }
+
+  // Step 2: Generate compact summary
+  const compactSummary = await generateSummary(toArchive, adapter, config);
+
+  // Step 3: Extract memory entries
+  const extracted = await extractMemories({ messages: toArchive, adapter, config });
+
+  // Step 4: Move archived messages to cold
+  const archiveIds = toArchive.map(m => m.id).filter(Boolean);
+  conversationStore.moveToColdBatch(archiveIds);
+
+  // Step 5a: Update compact.md
+  if (compactSummary) {
+    conversationStore.updateCompactSummary(compactSummary);
+  }
+
+  // Step 5b: Write extracted memory entries
+  const entryNames = [];
+  for (const entry of extracted) {
+    const slug = memoryStore.writeEntry(entry);
+    entryNames.push(slug);
+  }
+
+  // Step 5c: Update index.md
+  const lastMsg = toKeep[toKeep.length - 1];
+  conversationStore.updateIndex({
+    lastMessageId: lastMsg?.id || null,
+  });
+
+  // Step 5d: Rebuild scopes.md
+  if (entryNames.length > 0) {
+    memoryStore.rebuildScopes();
+  }
+
+  return {
+    compactSummary,
+    extractedEntries: entryNames,
+    archivedCount: archiveIds.length,
+  };
+}

package/unify/memory/extract.js

@@ -0,0 +1,97 @@
+/**
+ * extract.js — Extract memory-worthy entries from conversation
+ *
+ * Called by consolidate.js during the Consolidate lifecycle.
+ * Uses a single LLM call to identify facts, preferences, skills,
+ * lessons, contexts, and relations from conversation messages.
+ *
+ * Reference: yeaft-unify-core-systems.md §3.1, yeaft-unify-design.md §6.1
+ */
+
+import { MEMORY_KINDS } from './store.js';
+
+/**
+ * Build the extraction prompt.
+ * @param {object[]} messages — conversation messages to analyze
+ * @returns {string}
+ */
+function buildExtractionPrompt(messages) {
+  const conversation = messages.map(m => {
+    const prefix = m.role === 'user' ? 'User' : m.role === 'assistant' ? 'Assistant' : 'System';
+    return `[${prefix}]: ${m.content}`;
+  }).join('\n\n');
+
+  return `Analyze the following conversation and extract any memorable information worth saving to long-term memory.
+
+For each memory, provide:
+- **name**: A short slug-friendly name (e.g., "user-prefers-typescript", "project-uses-vue3")
+- **kind**: One of: ${MEMORY_KINDS.join(', ')}
+- **scope**: A tree path (e.g., "global", "tech/typescript", "work/project-name")
+- **tags**: Relevant keywords as an array
+- **importance**: "high", "normal", or "low"
+- **content**: 1-3 sentences describing the memory
+
+Memory kinds explained:
+- fact: Objective facts (project structure, tech stack)
+- preference: User preferences (coding style, tools)
+- skill: How to do something (patterns, techniques)
+- lesson: Lessons learned (bugs, pitfalls)
+- context: Temporal context (current OKR, progress)
+- relation: People and relationships (teammates, roles)
+
+Do NOT extract:
+- Specific code snippets (too large, will become stale)
+- Temporary debugging information
+- Trivial greetings or small talk
+
+Return a JSON array of memory objects. If nothing is worth remembering, return an empty array [].
+
+Conversation:
+${conversation}`;
+}
+
+/**
+ * Extract memory entries from a set of conversation messages.
+ *
+ * @param {{ messages: object[], adapter: object, config: object }} params
+ * @returns {Promise<object[]>} — extracted memory entries
+ */
+export async function extractMemories({ messages, adapter, config }) {
+  if (!messages || messages.length === 0) return [];
+
+  const system = 'You are a memory extraction assistant. Analyze conversations and extract important facts, preferences, and lessons. Return ONLY a valid JSON array, no other text.';
+
+  const extractionPrompt = buildExtractionPrompt(messages);
+
+  try {
+    const result = await adapter.call({
+      model: config.model,
+      system,
+      messages: [{ role: 'user', content: extractionPrompt }],
+      maxTokens: 2048,
+    });
+
+    const text = result.text.trim();
+
+    // Try to parse JSON array from the response
+    const jsonMatch = text.match(/\[[\s\S]*\]/);
+    if (!jsonMatch) return [];
+
+    const entries = JSON.parse(jsonMatch[0]);
+
+    // Validate and normalize entries
+    return entries
+      .filter(e => e && typeof e === 'object' && e.name && e.content)
+      .map(e => ({
+        name: String(e.name).slice(0, 80),
+        kind: MEMORY_KINDS.includes(e.kind) ? e.kind : 'fact',
+        scope: String(e.scope || 'global'),
+        tags: Array.isArray(e.tags) ? e.tags.map(String) : [],
+        importance: ['high', 'normal', 'low'].includes(e.importance) ? e.importance : 'normal',
+        content: String(e.content),
+      }));
+  } catch {
+    // LLM failure — return empty (non-critical operation)
+    return [];
+  }
+}