@yeaft/webchat-agent 0.1.662 → 0.1.664

package/unify/memory/scan.js

@@ -1,273 +0,0 @@
-/**
- * scan.js — Memory header scanning and scope/tag matching
- *
- * Fast in-memory scanning of entry frontmatter for:
- * - Scope tree traversal
- * - Tag overlap scoring
- * - Kind-based filtering
- * - Stale entry detection (for Dream)
- *
- * Reference: yeaft-unify-core-systems.md §3.3, yeaft-unify-design.md §5.1
- */
-
-import { KINDS, KIND_PRIORITY, IMPORTANCE_WEIGHT, getAncestorScopes } from './types.js';
-
-// ─── Scan Results ──────────────────────────────────────────
-
-/**
- * @typedef {Object} ScanResult
- * @property {object[]} entries — all parsed entries
- * @property {Map<string, number>} scopeCount — scope → entry count
- * @property {Map<string, number>} kindCount — kind → entry count
- * @property {Map<string, Set<string>>} tagIndex — tag → set of entry names
- * @property {number} totalEntries — total count
- */
-
-/**
- * Scan all entries from a MemoryStore and build indexes.
- *
- * @param {import('./store.js').MemoryStore} memoryStore
- * @returns {ScanResult}
- */
-export function scanEntries(memoryStore) {
-  const entries = memoryStore.listEntries();
-
-  const scopeCount = new Map();
-  const kindCount = new Map();
-  const tagIndex = new Map();
-
-  for (const entry of entries) {
-    // Scope count
-    const scope = entry.scope || 'global';
-    scopeCount.set(scope, (scopeCount.get(scope) || 0) + 1);
-
-    // Kind count
-    const kind = entry.kind || 'fact';
-    kindCount.set(kind, (kindCount.get(kind) || 0) + 1);
-
-    // Tag index
-    const tags = entry.tags || [];
-    for (const tag of tags) {
-      const lowerTag = tag.toLowerCase();
-      if (!tagIndex.has(lowerTag)) tagIndex.set(lowerTag, new Set());
-      tagIndex.get(lowerTag).add(entry.name);
-    }
-  }
-
-  return {
-    entries,
-    scopeCount,
-    kindCount,
-    tagIndex,
-    totalEntries: entries.length,
-  };
-}
-
-// ─── Scoring Functions ─────────────────────────────────────
-
-/**
- * Score an entry for relevance to a query context.
- *
- * Scoring factors:
- *   - Scope match: exact=5, parent/child=3, global=1
- *   - Tag overlap: 2 per matching tag
- *   - Kind priority: see KIND_PRIORITY
- *   - Importance weight: see IMPORTANCE_WEIGHT
- *   - Frequency bonus: log2(frequency)
- *   - Recency bonus: entries updated in last 7 days get +2
- *
- * @param {object} entry — memory entry
- * @param {{ scope?: string, tags?: string[], preferKinds?: string[] }} context
- * @returns {number} — relevance score
- */
-export function scoreEntry(entry, context = {}) {
-  let score = 0;
-
-  // Scope match
-  if (context.scope && entry.scope) {
-    if (entry.scope === context.scope) {
-      score += 5; // exact match
-    } else {
-      const ancestors = getAncestorScopes(context.scope);
-      if (ancestors.includes(entry.scope)) {
-        score += 3; // ancestor match
-      } else if (entry.scope.startsWith(context.scope + '/')) {
-        score += 3; // descendant match
-      } else if (entry.scope === 'global') {
-        score += 1; // global fallback
-      }
-    }
-  }
-
-  // Tag overlap
-  if (context.tags && context.tags.length > 0 && entry.tags) {
-    const entryTags = new Set(entry.tags.map(t => t.toLowerCase()));
-    for (const tag of context.tags) {
-      if (entryTags.has(tag.toLowerCase())) {
-        score += 2;
-      }
-    }
-  }
-
-  // Kind priority
-  const kindPriority = KIND_PRIORITY[entry.kind] || 0;
-  score += kindPriority * 0.5;
-
-  // Preferred kinds bonus
-  if (context.preferKinds && context.preferKinds.includes(entry.kind)) {
-    score += 2;
-  }
-
-  // Importance weight
-  const impWeight = IMPORTANCE_WEIGHT[entry.importance] || IMPORTANCE_WEIGHT.normal;
-  score += impWeight * 0.5;
-
-  // Frequency bonus (logarithmic)
-  const freq = entry.frequency || 1;
-  score += Math.log2(Math.max(freq, 1));
-
-  // Recency bonus
-  if (entry.updated_at) {
-    const daysSince = (Date.now() - new Date(entry.updated_at).getTime()) / (1000 * 60 * 60 * 24);
-    if (daysSince <= 7) score += 2;
-    else if (daysSince <= 30) score += 1;
-  }
-
-  return score;
-}
-
-// ─── Stale Detection (for Dream) ────────────────────────────
-
-/**
- * Find entries that are potentially stale.
- *
- * Stale criteria:
- * - context entries older than 30 days
- * - entries never recalled (frequency = 1) and older than 60 days
- * - relation entries older than 90 days
- *
- * @param {object[]} entries
- * @returns {object[]} — stale entries
- */
-export function findStaleEntries(entries) {
-  const now = Date.now();
-  const stale = [];
-
-  for (const entry of entries) {
-    const updatedAt = entry.updated_at ? new Date(entry.updated_at).getTime() : 0;
-    const daysSince = (now - updatedAt) / (1000 * 60 * 60 * 24);
-
-    let isStale = false;
-
-    // Context entries become stale fast
-    if (entry.kind === 'context' && daysSince > 30) {
-      isStale = true;
-    }
-
-    // Entries never recalled and old
-    if ((entry.frequency || 1) <= 1 && daysSince > 60) {
-      isStale = true;
-    }
-
-    // Relations are volatile
-    if (entry.kind === 'relation' && daysSince > 90) {
-      isStale = true;
-    }
-
-    if (isStale) {
-      stale.push({ ...entry, _daysSinceUpdate: Math.round(daysSince) });
-    }
-  }
-
-  return stale;
-}
-
-// ─── Duplicate Detection (for Dream Merge) ──────────────────
-
-/**
- * Find groups of entries that are potentially duplicates.
- * Entries are grouped if they share ≥2 tags AND the same kind.
- *
- * @param {object[]} entries
- * @returns {object[][]} — groups of potentially duplicate entries
- */
-export function findDuplicateGroups(entries) {
-  const groups = [];
-  const visited = new Set();
-
-  for (let i = 0; i < entries.length; i++) {
-    if (visited.has(i)) continue;
-
-    const group = [entries[i]];
-    const eTags = new Set((entries[i].tags || []).map(t => t.toLowerCase()));
-
-    for (let j = i + 1; j < entries.length; j++) {
-      if (visited.has(j)) continue;
-      if (entries[i].kind !== entries[j].kind) continue;
-
-      const jTags = new Set((entries[j].tags || []).map(t => t.toLowerCase()));
-      let overlap = 0;
-      for (const tag of eTags) {
-        if (jTags.has(tag)) overlap++;
-      }
-
-      if (overlap >= 2) {
-        group.push(entries[j]);
-        visited.add(j);
-      }
-    }
-
-    if (group.length > 1) {
-      visited.add(i);
-      groups.push(group);
-    }
-  }
-
-  return groups;
-}
-
-// ─── Stats Summary ──────────────────────────────────────────
-
-/**
- * Generate a text summary of memory state (for Dream prompts).
- *
- * @param {ScanResult} scan
- * @returns {string}
- */
-export function summarizeScan(scan) {
-  const lines = [];
-
-  lines.push(`Total entries: ${scan.totalEntries}`);
-
-  // Kind breakdown
-  const kindLines = [];
-  for (const kind of KINDS) {
-    const count = scan.kindCount.get(kind) || 0;
-    if (count > 0) kindLines.push(`${kind}: ${count}`);
-  }
-  if (kindLines.length > 0) {
-    lines.push(`Kinds: ${kindLines.join(', ')}`);
-  }
-
-  // Scope breakdown (top 10)
-  const scopeEntries = [...scan.scopeCount.entries()]
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, 10);
-  if (scopeEntries.length > 0) {
-    lines.push('Top scopes:');
-    for (const [scope, count] of scopeEntries) {
-      lines.push(`  ${scope}: ${count}`);
-    }
-  }
-
-  // Tag cloud (top 20)
-  const tagEntries = [...scan.tagIndex.entries()]
-    .map(([tag, names]) => [tag, names.size])
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, 20);
-  if (tagEntries.length > 0) {
-    lines.push(`Top tags: ${tagEntries.map(([t, c]) => `${t}(${c})`).join(', ')}`);
-  }
-
-  return lines.join('\n');
-}

package/unify/router/vp-planner.js

@@ -1,341 +0,0 @@
-/**
- * router/vp-planner.js — DESIGN.md Phase 3a (router per-VP plans).
- *
- * The legacy `intent-classifier.js` decides "which thread continues this
- * turn" — single-VP, single-plan. The multi-VP redesign (DESIGN.md §1.2.1)
- * generalises that into a `plans[]` array: one plan per VP that should act
- * this turn, in execution order. This module is the per-VP planner.
- *
- * Phase 3a scope: schema + validation + sequential fan-out runner. The LLM
- * call itself is wired in Phase 3b along with `priorPlan` continuity. Until
- * then, callers either (a) construct plans directly from override paths, or
- * (b) wrap the legacy single-plan classifier and call `wrapLegacyDecision`.
- *
- * Non-goals here:
- *   - parallel fan-out (Phase 3.5).
- *   - thinking-mode resolution (handled at the dispatcher level alongside
- *     the UI > Router > VP > Global precedence chain — DESIGN.md §9.16).
- *   - `priorPlan` skip-router heuristic (Phase 3b).
- *
- * Shape contract (DESIGN.md §1.2.1):
- *
- *   {
- *     action: 'continue' | 'switch_vp' | 'fork_task' | 'join_task' |
- *             'broadcast' | 'noop',
- *     targetTaskId: string | null,
- *     plans: [
- *       {
- *         vpId: string,
- *         forwardQuery: { userOriginal: string, intent: string },
- *         preselect: { memoryPaths: string[], taskIds: string[] },
- *         thinking: 'high' | 'max' | null,
- *         thinkingReason: string,
- *       }
- *     ],
- *     reason: string,
- *   }
- */
-
-import { isVpForeign } from '../memory/store-v2.js';
-
-/** @typedef {{ userOriginal: string, intent: string }} ForwardQuery */
-/** @typedef {{ memoryPaths: string[], taskIds: string[] }} Preselect */
-/** @typedef {{
- *    vpId: string,
- *    forwardQuery: ForwardQuery,
- *    preselect: Preselect,
- *    thinking: 'high'|'max'|null,
- *    thinkingReason: string,
- *  }} VpPlan
- */
-/** @typedef {{
- *    action: 'continue'|'switch_vp'|'fork_task'|'join_task'|'broadcast'|'noop',
- *    targetTaskId: string | null,
- *    plans: VpPlan[],
- *    reason: string,
- *  }} RouterDecisionV2
- */
-
-const ALLOWED_ACTIONS = new Set([
-  'continue', 'switch_vp', 'fork_task', 'join_task', 'broadcast', 'noop',
-]);
-
-const ALLOWED_THINKING = new Set([null, 'high', 'max']);
-
-/**
- * Validate + canonicalise a router decision. Throws on truly malformed
- * input (we want loud failures during Phase 3 wiring), but tolerates
- * missing optional fields by filling defaults.
- *
- * @param {*} raw
- * @returns {RouterDecisionV2}
- */
-export function validateDecision(raw) {
-  if (!raw || typeof raw !== 'object') {
-    throw new Error('validateDecision: decision must be an object');
-  }
-  const action = ALLOWED_ACTIONS.has(raw.action) ? raw.action : 'continue';
-  const targetTaskId = (typeof raw.targetTaskId === 'string' && raw.targetTaskId)
-    ? raw.targetTaskId : null;
-  if (!Array.isArray(raw.plans)) {
-    throw new Error('validateDecision: plans must be an array');
-  }
-  const plans = raw.plans.map(validatePlan);
-  const reason = typeof raw.reason === 'string' ? raw.reason : '';
-  return { action, targetTaskId, plans, reason };
-}
-
-/**
- * @param {*} raw
- * @returns {VpPlan}
- */
-export function validatePlan(raw) {
-  if (!raw || typeof raw !== 'object') {
-    throw new Error('validatePlan: plan must be an object');
-  }
-  if (typeof raw.vpId !== 'string' || !raw.vpId) {
-    throw new Error('validatePlan: vpId required');
-  }
-  const fq = raw.forwardQuery && typeof raw.forwardQuery === 'object'
-    ? raw.forwardQuery : {};
-  const userOriginal = typeof fq.userOriginal === 'string' ? fq.userOriginal : '';
-  const intent = typeof fq.intent === 'string' ? fq.intent : '';
-  const pre = raw.preselect && typeof raw.preselect === 'object'
-    ? raw.preselect : {};
-  const memoryPaths = Array.isArray(pre.memoryPaths)
-    ? pre.memoryPaths.filter(p => typeof p === 'string' && p)
-    : [];
-  const taskIds = Array.isArray(pre.taskIds)
-    ? pre.taskIds.filter(t => typeof t === 'string' && t)
-    : [];
-  const thinkingRaw = raw.thinking === undefined ? null : raw.thinking;
-  const thinking = ALLOWED_THINKING.has(thinkingRaw) ? thinkingRaw : null;
-  const thinkingReason = typeof raw.thinkingReason === 'string'
-    ? raw.thinkingReason : '';
-  return {
-    vpId: raw.vpId,
-    forwardQuery: { userOriginal, intent },
-    preselect: { memoryPaths, taskIds },
-    thinking,
-    thinkingReason,
-  };
-}
-
-/**
- * Strip `vp/<other>/` paths from a plan's `preselect.memoryPaths`. The
- * planner runs BEFORE the worker so this is the right place to enforce
- * the cross-VP private-memory hard block (DESIGN.md §2.2). Returns a new
- * plan; original is not mutated.
- *
- * @param {VpPlan} plan
- * @returns {VpPlan}
- */
-export function stripForeignVpPaths(plan) {
-  if (!plan) return plan;
-  const own = plan.vpId;
-  const filtered = plan.preselect.memoryPaths.filter(p => !isVpForeign(p, own));
-  if (filtered.length === plan.preselect.memoryPaths.length) return plan;
-  return {
-    ...plan,
-    preselect: { ...plan.preselect, memoryPaths: filtered },
-  };
-}
-
-/**
- * Produce a default single-plan decision for "explicit @vp" or "no router
- * needed" paths. The dispatcher uses this when it has decided not to call
- * the LLM router (DESIGN.md §1.2.1 scenario A — explicit @vp; or §9.15
- * priorPlan skip).
- *
- * @param {{
- *   vpId: string,
- *   userOriginal: string,
- *   intent?: string,
- *   memoryPaths?: string[],
- *   taskIds?: string[],
- *   targetTaskId?: string | null,
- *   thinking?: 'high'|'max'|null,
- *   thinkingReason?: string,
- *   action?: RouterDecisionV2['action'],
- *   reason?: string,
- * }} args
- * @returns {RouterDecisionV2}
- */
-export function buildDirectDecision(args) {
-  const {
-    vpId, userOriginal, intent = '',
-    memoryPaths = [], taskIds = [],
-    targetTaskId = null,
-    thinking = null, thinkingReason = '',
-    action = 'continue', reason = 'direct',
-  } = args || {};
-  if (!vpId) throw new Error('buildDirectDecision: vpId required');
-  return validateDecision({
-    action,
-    targetTaskId,
-    plans: [{
-      vpId,
-      forwardQuery: { userOriginal, intent },
-      preselect: { memoryPaths, taskIds },
-      thinking,
-      thinkingReason,
-    }],
-    reason,
-  });
-}
-
-/**
- * Translate a legacy `intent-classifier` single-thread decision (action +
- * targetThreadId) into the V2 plans schema. We treat the old `targetThreadId`
- * as the `vpId` because — in the multi-VP redesign — every "thread" is a VP
- * (groups are sessions, see DESIGN.md §0.1). Callers that still produce
- * legacy decisions can pipe them through this until Phase 3b.
- *
- * Mapping:
- *   continue / switch → continue / switch_vp (single-VP plan)
- *   fork              → fork_task   (single-VP plan)
- *   anything else     → continue
- *
- * @param {{
- *   action?: string,
- *   targetThreadId?: string,
- *   reason?: string,
- *   source?: string,
- * }} legacy
- * @param {string} userOriginal
- * @returns {RouterDecisionV2}
- */
-export function wrapLegacyDecision(legacy, userOriginal = '') {
-  if (!legacy || typeof legacy !== 'object') {
-    return validateDecision({ action: 'noop', targetTaskId: null, plans: [], reason: '' });
-  }
-  const vpId = typeof legacy.targetThreadId === 'string' ? legacy.targetThreadId : '';
-  if (!vpId) {
-    return validateDecision({ action: 'noop', targetTaskId: null, plans: [], reason: legacy.reason || '' });
-  }
-  let action = 'continue';
-  if (legacy.action === 'switch') action = 'switch_vp';
-  else if (legacy.action === 'fork') action = 'fork_task';
-  else if (legacy.action === 'continue') action = 'continue';
-  return validateDecision({
-    action,
-    targetTaskId: null,
-    reason: legacy.reason || '',
-    plans: [{
-      vpId,
-      forwardQuery: { userOriginal, intent: '' },
-      preselect: { memoryPaths: [], taskIds: [] },
-      thinking: null,
-      thinkingReason: '',
-    }],
-  });
-}
-
-/**
- * Sequential fan-out runner. Calls `runOne(plan, index, prior)` for each
- * plan in order, awaiting each before starting the next. The previous
- * plans' results are passed via `prior` so a later plan can read what an
- * earlier plan emitted (DESIGN.md §1.2.1 — "ordering is load bearing").
- *
- * Plans whose `vpId` is missing from `groupMemberIds` (when the caller
- * supplies that whitelist) are skipped with a logged `skipped:not_member`
- * entry — never silently routed to a non-member.
- *
- * Errors from `runOne` are caught, recorded, and the loop continues; the
- * report holds whatever each plan produced. The dispatcher decides whether
- * to surface or retry.
- *
- * @param {VpPlan[]} plans
- * @param {(plan: VpPlan, index: number, prior: any[]) => Promise<*>} runOne
- * @param {{ groupMemberIds?: string[] }} [opts]
- * @returns {Promise<{ results: any[], errors: Array<{ index: number, error: Error }> }>}
- */
-export async function runPlansSequential(plans, runOne, opts = {}) {
-  if (!Array.isArray(plans)) throw new Error('runPlansSequential: plans array required');
-  if (typeof runOne !== 'function') throw new Error('runPlansSequential: runOne fn required');
-  const memberSet = Array.isArray(opts.groupMemberIds)
-    ? new Set(opts.groupMemberIds) : null;
-  const results = [];
-  const errors = [];
-  const prior = [];
-  for (let i = 0; i < plans.length; i += 1) {
-    const plan = plans[i];
-    if (memberSet && !memberSet.has(plan.vpId)) {
-      const skip = { index: i, vpId: plan.vpId, skipped: 'not_member' };
-      results.push(skip);
-      prior.push(skip);
-      continue;
-    }
-    try {
-      const out = await runOne(plan, i, prior);
-      results.push(out);
-      prior.push(out);
-    } catch (err) {
-      errors.push({ index: i, error: err });
-      // Insert a sentinel into prior so a later plan can see "the previous
-      // VP errored" rather than nothing — useful when a fallback VP is
-      // queued behind a primary.
-      prior.push({ index: i, vpId: plan.vpId, error: err });
-    }
-  }
-  return { results, errors };
-}
-
-/**
- * Parallel fan-out runner (Phase 3.5). Calls `runOne(plan, index)` for each
- * plan concurrently, with optional `concurrency` cap. Results are returned
- * in input order regardless of completion order. Errors from `runOne` are
- * caught per-plan and DO NOT abort siblings (DESIGN.md §9.1 — concurrent
- * VP turns must be independent).
- *
- * NOTE: parallel mode loses the `prior[]` channel that the sequential
- * runner provides. Callers that need plan N to read plan N-1's output must
- * use `runPlansSequential`. The dispatcher chooses based on whether the
- * plans share a `targetTaskId` (parallel-safe) or pipeline data
- * (sequential-only).
- *
- * @param {VpPlan[]} plans
- * @param {(plan: VpPlan, index: number) => Promise<*>} runOne
- * @param {{ groupMemberIds?: string[], concurrency?: number }} [opts]
- * @returns {Promise<{ results: any[], errors: Array<{ index: number, error: Error }> }>}
- */
-export async function runPlansParallel(plans, runOne, opts = {}) {
-  if (!Array.isArray(plans)) throw new Error('runPlansParallel: plans array required');
-  if (typeof runOne !== 'function') throw new Error('runPlansParallel: runOne fn required');
-  const memberSet = Array.isArray(opts.groupMemberIds)
-    ? new Set(opts.groupMemberIds) : null;
-  const concurrency = Number.isFinite(opts.concurrency) && opts.concurrency > 0
-    ? Math.floor(opts.concurrency) : Infinity;
-
-  const results = new Array(plans.length);
-  const errors = [];
-  let nextIdx = 0;
-
-  const runSlot = async () => {
-    // Workers pull tasks from a shared queue index — preserves backpressure
-    // when concurrency < plans.length without per-task scheduling overhead.
-    while (true) {
-      const i = nextIdx;
-      nextIdx += 1;
-      if (i >= plans.length) return;
-      const plan = plans[i];
-      if (memberSet && !memberSet.has(plan.vpId)) {
-        results[i] = { index: i, vpId: plan.vpId, skipped: 'not_member' };
-        continue;
-      }
-      try {
-        results[i] = await runOne(plan, i);
-      } catch (err) {
-        errors.push({ index: i, error: err });
-        results[i] = { index: i, vpId: plan.vpId, error: err };
-      }
-    }
-  };
-
-  const workerCount = Math.min(plans.length, concurrency);
-  const workers = [];
-  for (let w = 0; w < workerCount; w += 1) workers.push(runSlot());
-  await Promise.all(workers);
-
-  return { results, errors };
-}