@yeaft/webchat-agent 0.1.409 → 0.1.410

package/unify/skills.js

@@ -0,0 +1,315 @@
+/**
+ * skills.js — Skill loading and management
+ *
+ * Skills are markdown files in ~/.yeaft/skills/ that define
+ * specialized behaviors or workflows. They are loaded at startup
+ * and injected into the system prompt when relevant.
+ *
+ * Skill format (skills/my-skill.md):
+ *   ---
+ *   name: my-skill
+ *   description: Does something useful
+ *   trigger: "when user asks about X"
+ *   mode: chat | work | both
+ *   ---
+ *   # Skill instructions here...
+ *
+ * Reference: yeaft-unify-design.md §8, yeaft-unify-core-systems.md
+ */
+
+import { existsSync, readFileSync, readdirSync, writeFileSync, unlinkSync } from 'fs';
+import { join, basename } from 'path';
+
+// ─── Skill Parsing ─────────────────────────────────────────
+
+/**
+ * @typedef {Object} Skill
+ * @property {string} name — unique skill name
+ * @property {string} description — human-readable description
+ * @property {string} trigger — when this skill should be invoked
+ * @property {string} mode — 'chat' | 'work' | 'both'
+ * @property {string} content — full skill instructions (markdown body)
+ * @property {string} _filename — source filename
+ */
+
+/**
+ * Parse a skill .md file.
+ *
+ * @param {string} raw — raw file content
+ * @param {string} filename — source filename
+ * @returns {Skill|null}
+ */
+export function parseSkill(raw, filename = '') {
+  if (!raw || !raw.startsWith('---')) return null;
+
+  const endIdx = raw.indexOf('\n---', 3);
+  if (endIdx === -1) return null;
+
+  const frontmatter = raw.slice(4, endIdx).trim();
+  const body = raw.slice(endIdx + 4).trim();
+
+  const skill = {
+    content: body,
+    _filename: filename,
+    mode: 'both',
+  };
+
+  for (const line of frontmatter.split('\n')) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+
+    switch (key) {
+      case 'name': skill.name = value; break;
+      case 'description': skill.description = value; break;
+      case 'trigger': skill.trigger = value; break;
+      case 'mode': skill.mode = value; break;
+    }
+  }
+
+  // Use filename as name fallback
+  if (!skill.name) {
+    skill.name = basename(filename, '.md');
+  }
+
+  return skill;
+}
+
+/**
+ * Serialize a skill to .md format.
+ *
+ * @param {Skill} skill
+ * @returns {string}
+ */
+export function serializeSkill(skill) {
+  const fm = [
+    '---',
+    `name: ${skill.name}`,
+    `description: ${skill.description || ''}`,
+    `trigger: ${skill.trigger || ''}`,
+    `mode: ${skill.mode || 'both'}`,
+    '---',
+  ];
+
+  return fm.join('\n') + '\n\n' + (skill.content || '');
+}
+
+// ─── SkillManager ──────────────────────────────────────────
+
+/**
+ * SkillManager — loads, indexes, and queries skills.
+ */
+export class SkillManager {
+  /** @type {Map<string, Skill>} */
+  #skills = new Map();
+
+  /** @type {string} */
+  #skillsDir;
+
+  /**
+   * @param {string} yeaftDir — Yeaft root directory (e.g. ~/.yeaft)
+   */
+  constructor(yeaftDir) {
+    this.#skillsDir = join(yeaftDir, 'skills');
+  }
+
+  /**
+   * Load all skills from the skills directory.
+   *
+   * @returns {{ loaded: number, errors: string[] }}
+   */
+  load() {
+    this.#skills.clear();
+    const errors = [];
+
+    if (!existsSync(this.#skillsDir)) {
+      return { loaded: 0, errors: [] };
+    }
+
+    const files = readdirSync(this.#skillsDir).filter(f => f.endsWith('.md'));
+
+    for (const file of files) {
+      try {
+        const raw = readFileSync(join(this.#skillsDir, file), 'utf8');
+        const skill = parseSkill(raw, file);
+        if (skill && skill.name) {
+          this.#skills.set(skill.name, skill);
+        } else {
+          errors.push(`Failed to parse skill: ${file}`);
+        }
+      } catch (err) {
+        errors.push(`Error loading ${file}: ${err.message}`);
+      }
+    }
+
+    return { loaded: this.#skills.size, errors };
+  }
+
+  /**
+   * Get a skill by name.
+   *
+   * @param {string} name
+   * @returns {Skill|null}
+   */
+  get(name) {
+    return this.#skills.get(name) || null;
+  }
+
+  /**
+   * Check if a skill exists.
+   *
+   * @param {string} name
+   * @returns {boolean}
+   */
+  has(name) {
+    return this.#skills.has(name);
+  }
+
+  /**
+   * List all skills, optionally filtered by mode.
+   *
+   * @param {string} [mode] — 'chat' | 'work' | undefined (all)
+   * @returns {Skill[]}
+   */
+  list(mode) {
+    const skills = [...this.#skills.values()];
+    if (!mode) return skills;
+
+    return skills.filter(s => s.mode === 'both' || s.mode === mode);
+  }
+
+  /**
+   * Find skills relevant to a prompt (simple keyword matching).
+   *
+   * @param {string} prompt — user's prompt
+   * @param {string} [mode] — filter by mode
+   * @returns {Skill[]}
+   */
+  findRelevant(prompt, mode) {
+    if (!prompt) return [];
+
+    const lowerPrompt = prompt.toLowerCase();
+    // Strip punctuation and split on whitespace for clean word matching
+    const cleanPrompt = lowerPrompt.replace(/[^\w\s]/g, '');
+    const promptWords = cleanPrompt.split(/\s+/).filter(w => w.length > 2);
+    const skills = this.list(mode);
+
+    return skills.filter(skill => {
+      // Check trigger match — any trigger keyword found in prompt
+      if (skill.trigger) {
+        const triggerWords = skill.trigger.toLowerCase().replace(/[^\w\s]/g, '').split(/\s+/).filter(w => w.length > 2);
+        // Count matches: exact word, substring, or shared stem (first 4 chars)
+        const matchCount = triggerWords.filter(tw => {
+          if (cleanPrompt.includes(tw)) return true;
+          // Stem matching: if trigger word and prompt word share a 4+ char prefix
+          const twStem = tw.slice(0, Math.min(tw.length, 4));
+          return promptWords.some(pw => {
+            if (pw.includes(tw) || tw.includes(pw)) return true;
+            const pwStem = pw.slice(0, Math.min(pw.length, 4));
+            return twStem.length >= 4 && pwStem.length >= 4 && twStem === pwStem;
+          });
+        }).length;
+        // At least 1 meaningful match and ≥30% of trigger words
+        if (matchCount >= 1 && matchCount >= Math.ceil(triggerWords.length * 0.3)) {
+          return true;
+        }
+      }
+
+      // Check name match
+      if (lowerPrompt.includes(skill.name.toLowerCase())) {
+        return true;
+      }
+
+      // Check description match
+      if (skill.description && lowerPrompt.includes(skill.description.toLowerCase())) {
+        return true;
+      }
+
+      return false;
+    });
+  }
+
+  /**
+   * Add or update a skill.
+   *
+   * @param {Skill} skill
+   * @returns {string} — filename
+   */
+  save(skill) {
+    if (!skill.name) throw new Error('Skill must have a name');
+
+    const filename = `${skill.name}.md`;
+    const filePath = join(this.#skillsDir, filename);
+
+    writeFileSync(filePath, serializeSkill(skill), 'utf8');
+    this.#skills.set(skill.name, { ...skill, _filename: filename });
+
+    return filename;
+  }
+
+  /**
+   * Remove a skill.
+   *
+   * @param {string} name
+   * @returns {boolean}
+   */
+  remove(name) {
+    const skill = this.#skills.get(name);
+    if (!skill) return false;
+
+    const filePath = join(this.#skillsDir, skill._filename || `${name}.md`);
+    try {
+      unlinkSync(filePath);
+    } catch {
+      // File might not exist
+    }
+
+    this.#skills.delete(name);
+    return true;
+  }
+
+  /**
+   * Get the skill content formatted for system prompt injection.
+   *
+   * @param {string} name
+   * @returns {string}
+   */
+  getPromptContent(name) {
+    const skill = this.#skills.get(name);
+    if (!skill) return '';
+
+    return `## Skill: ${skill.name}\n\n${skill.content}`;
+  }
+
+  /**
+   * Get all relevant skill contents for a prompt.
+   *
+   * @param {string} prompt
+   * @param {string} [mode]
+   * @returns {string}
+   */
+  getRelevantPromptContent(prompt, mode) {
+    const relevant = this.findRelevant(prompt, mode);
+    if (relevant.length === 0) return '';
+
+    return relevant.map(s => this.getPromptContent(s.name)).join('\n\n');
+  }
+
+  /** Number of loaded skills. */
+  get size() {
+    return this.#skills.size;
+  }
+}
+
+/**
+ * Create a SkillManager and load skills.
+ *
+ * @param {string} yeaftDir
+ * @returns {SkillManager}
+ */
+export function createSkillManager(yeaftDir) {
+  const manager = new SkillManager(yeaftDir);
+  manager.load();
+  return manager;
+}

package/unify/stop-hooks.js

@@ -0,0 +1,146 @@
+/**
+ * stop-hooks.js — Post-query lifecycle hooks
+ *
+ * Runs after each query loop completes:
+ *   1. Persist messages to conversation/messages/
+ *   2. Consolidate check (compact + extract) — only when budget exceeded
+ *   3. Dream gate check (background)
+ *   4. Increment dream query counter
+ *
+ * Reference: yeaft-unify-core-systems.md §4.4
+ */
+
+import { shouldConsolidate, consolidate } from './memory/consolidate.js';
+import { checkDreamGate, incrementQueryCount, dream } from './memory/dream.js';
+
+/**
+ * Run all stop hooks after a query completes.
+ *
+ * @param {{
+ *   yeaftDir: string,
+ *   mode: string,
+ *   conversationStore: import('./conversation/persist.js').ConversationStore,
+ *   memoryStore: import('./memory/store.js').MemoryStore,
+ *   adapter: object,
+ *   config: object,
+ *   messages?: object[],
+ *   taskId?: string,
+ *   workerId?: string,
+ *   trace?: object,
+ * }} context
+ * @returns {Promise<StopHookResult>}
+ */
+export async function runStopHooks(context) {
+  const {
+    yeaftDir,
+    mode,
+    conversationStore,
+    memoryStore,
+    adapter,
+    config,
+    messages = [],
+    taskId,
+    trace,
+  } = context;
+
+  const result = {
+    messagesPersisted: 0,
+    consolidated: false,
+    dreamTriggered: false,
+    errors: [],
+  };
+
+  // Workers don't run stop hooks (they persist to task workers/ dir)
+  if (mode === 'worker') {
+    return result;
+  }
+
+  // 1. Persist latest messages
+  try {
+    if (conversationStore && messages.length > 0) {
+      const recentMessages = messages.slice(-2); // last user + assistant pair
+      for (const msg of recentMessages) {
+        if (msg.role && msg.content) {
+          conversationStore.append({
+            role: msg.role,
+            content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+            mode,
+            model: config.model,
+          });
+          result.messagesPersisted++;
+        }
+      }
+    }
+  } catch (err) {
+    result.errors.push(`Persist failed: ${err.message}`);
+  }
+
+  // 2. Consolidate check (non-blocking, but awaited for correctness)
+  try {
+    if (conversationStore && memoryStore && adapter) {
+      if (shouldConsolidate(conversationStore, config.messageTokenBudget)) {
+        const consolidated = await consolidate({
+          conversationStore,
+          memoryStore,
+          adapter,
+          config,
+          budget: config.messageTokenBudget,
+        });
+        result.consolidated = true;
+        trace?.logEvent({
+          eventType: 'consolidate',
+          eventData: {
+            archivedCount: consolidated.archivedCount,
+            extractedEntries: consolidated.extractedEntries.length,
+          },
+        });
+      }
+    }
+  } catch (err) {
+    result.errors.push(`Consolidate failed: ${err.message}`);
+  }
+
+  // 3. Increment dream query counter
+  try {
+    if (yeaftDir) {
+      incrementQueryCount(yeaftDir);
+    }
+  } catch (err) {
+    result.errors.push(`Dream counter failed: ${err.message}`);
+  }
+
+  // 4. Dream gate check (fire-and-forget, background)
+  try {
+    if (yeaftDir && memoryStore && adapter) {
+      const gate = checkDreamGate(yeaftDir);
+      if (gate.shouldDream) {
+        result.dreamTriggered = true;
+        // Fire and forget — dream runs in background
+        dream({
+          yeaftDir,
+          memoryStore,
+          conversationStore,
+          adapter,
+          config,
+        }).catch(err => {
+          trace?.logEvent({
+            eventType: 'dream_error',
+            eventData: { error: err.message },
+          });
+        });
+      }
+    }
+  } catch (err) {
+    result.errors.push(`Dream gate check failed: ${err.message}`);
+  }
+
+  return result;
+}
+
+/**
+ * @typedef {Object} StopHookResult
+ * @property {number} messagesPersisted — how many messages were persisted
+ * @property {boolean} consolidated — whether consolidation ran
+ * @property {boolean} dreamTriggered — whether dream was triggered
+ * @property {string[]} errors — any non-fatal errors
+ */

package/unify/tools/enter-worktree.js

@@ -0,0 +1,97 @@
+/**
+ * enter-worktree.js — Create an isolated git worktree for development
+ *
+ * Creates a new git worktree with an isolated branch, useful for
+ * sub-agents that need to work on files without conflicting with
+ * the main working tree or other workers.
+ *
+ * Reference: yeaft-unify-design.md §8, yeaft-unify-core-systems.md §3.2
+ */
+
+import { defineTool } from './types.js';
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync } from 'fs';
+import { join, resolve } from 'path';
+import { randomUUID } from 'crypto';
+
+export default defineTool({
+  name: 'EnterWorktree',
+  description: `Create an isolated git worktree for development.
+
+Creates a new git worktree with a dedicated branch, allowing parallel
+development without file conflicts. Useful for:
+- Sub-agents working on independent subtasks
+- Testing changes in isolation before merging
+- Parallel feature development
+
+The worktree is created in .yeaft/worktrees/ with a new branch based on HEAD.
+Returns the worktree path and branch name.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'Name for the worktree (used in path and branch name). If omitted, a random name is generated.',
+      },
+      base_ref: {
+        type: 'string',
+        description: 'Git ref to base the worktree on (default: HEAD)',
+      },
+    },
+  },
+  modes: ['work'],
+  isDestructive: () => false,
+  async execute(input, ctx) {
+    const cwd = ctx?.cwd || process.cwd();
+
+    // Verify we're in a git repo
+    try {
+      execSync('git rev-parse --git-dir', { cwd, stdio: 'pipe' });
+    } catch {
+      return JSON.stringify({ error: 'Not in a git repository' });
+    }
+
+    // Generate worktree name and path
+    const name = input.name
+      ? input.name.replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 64)
+      : `wt-${randomUUID().slice(0, 8)}`;
+
+    const worktreeDir = join(cwd, '.yeaft', 'worktrees', name);
+    const branchName = `yeaft-wt/${name}`;
+    const baseRef = input.base_ref || 'HEAD';
+
+    // Check if worktree already exists
+    if (existsSync(worktreeDir)) {
+      return JSON.stringify({
+        error: `Worktree "${name}" already exists at ${worktreeDir}`,
+        path: worktreeDir,
+        branch: branchName,
+      });
+    }
+
+    // Ensure parent directory exists
+    const parentDir = join(cwd, '.yeaft', 'worktrees');
+    if (!existsSync(parentDir)) {
+      mkdirSync(parentDir, { recursive: true });
+    }
+
+    try {
+      // Create worktree with new branch
+      const cmd = `git worktree add -b "${branchName}" "${worktreeDir}" ${baseRef}`;
+      execSync(cmd, { cwd, stdio: 'pipe' });
+
+      return JSON.stringify({
+        success: true,
+        path: resolve(worktreeDir),
+        branch: branchName,
+        baseRef,
+        name,
+        message: `Created worktree "${name}" at ${worktreeDir} on branch ${branchName}`,
+      });
+    } catch (err) {
+      return JSON.stringify({
+        error: `Failed to create worktree: ${err.message}`,
+      });
+    }
+  },
+});

package/unify/tools/exit-worktree.js

@@ -0,0 +1,131 @@
+/**
+ * exit-worktree.js — Remove or keep a git worktree
+ *
+ * Exits and optionally removes a worktree created by EnterWorktree.
+ * Can keep the worktree (preserve branch) or remove it cleanly.
+ *
+ * Reference: yeaft-unify-design.md §8
+ */
+
+import { defineTool } from './types.js';
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+
+export default defineTool({
+  name: 'ExitWorktree',
+  description: `Exit a git worktree session.
+
+Options:
+- "keep": Leave the worktree and branch on disk (can return later)
+- "remove": Delete the worktree directory and its branch
+
+If removing and there are uncommitted changes, the operation will fail
+unless discard_changes is set to true.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Path to the worktree to exit (required)',
+      },
+      action: {
+        type: 'string',
+        enum: ['keep', 'remove'],
+        description: '"keep" leaves the worktree on disk; "remove" deletes it',
+      },
+      discard_changes: {
+        type: 'boolean',
+        description: 'Force remove even with uncommitted changes (default: false)',
+      },
+    },
+    required: ['path', 'action'],
+  },
+  modes: ['work'],
+  isDestructive: (input) => input?.action === 'remove',
+  async execute(input, ctx) {
+    const worktreePath = resolve(input.path);
+    const mainCwd = ctx?.cwd || process.cwd();
+
+    if (!existsSync(worktreePath)) {
+      return JSON.stringify({
+        error: `Worktree path does not exist: ${worktreePath}`,
+      });
+    }
+
+    if (input.action === 'keep') {
+      return JSON.stringify({
+        success: true,
+        action: 'keep',
+        path: worktreePath,
+        message: `Worktree at ${worktreePath} kept on disk. Branch preserved.`,
+      });
+    }
+
+    // action === 'remove'
+    try {
+      // Check for uncommitted changes
+      if (!input.discard_changes) {
+        try {
+          const status = execSync('git status --porcelain', {
+            cwd: worktreePath,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+          }).trim();
+
+          if (status) {
+            return JSON.stringify({
+              error: 'Worktree has uncommitted changes. Set discard_changes=true to force remove.',
+              uncommittedFiles: status.split('\n').slice(0, 10),
+            });
+          }
+        } catch {
+          // If we can't check status, proceed with caution
+        }
+      }
+
+      // Get branch name before removal
+      let branchName = null;
+      try {
+        branchName = execSync('git rev-parse --abbrev-ref HEAD', {
+          cwd: worktreePath,
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+      } catch {
+        // ignore
+      }
+
+      // Remove worktree
+      const forceFlag = input.discard_changes ? ' --force' : '';
+      execSync(`git worktree remove "${worktreePath}"${forceFlag}`, {
+        cwd: mainCwd,
+        stdio: 'pipe',
+      });
+
+      // Remove the branch if it was a yeaft worktree branch
+      if (branchName && branchName.startsWith('yeaft-wt/')) {
+        try {
+          execSync(`git branch -D "${branchName}"`, {
+            cwd: mainCwd,
+            stdio: 'pipe',
+          });
+        } catch {
+          // Branch might already be deleted or not exist
+        }
+      }
+
+      return JSON.stringify({
+        success: true,
+        action: 'remove',
+        path: worktreePath,
+        branch: branchName,
+        message: `Worktree removed: ${worktreePath}${branchName ? `, branch ${branchName} deleted` : ''}`,
+      });
+    } catch (err) {
+      return JSON.stringify({
+        error: `Failed to remove worktree: ${err.message}`,
+      });
+    }
+  },
+});