@yeaft/webchat-agent 0.1.531 → 0.1.533

package/unify/tasks/summary.js

@@ -0,0 +1,338 @@
+/**
+ * summary.js — task-334n: Task multi-VP collaboration summary protocol.
+ *
+ * Owns:
+ *   - postSummary()       — write a `type=summary` message to the group jsonl
+ *                           and run the extractor (B + C)
+ *   - extractTaskMemory() — turn a summary body into 2-5 task-memory entries
+ *                           via 334f task-memory shard lib (C)
+ *   - buildSummaryReminder() — compute the §Δ31.4 3-AND soft reminder shape
+ *                              consumed by 334e's `taskCtx.summaryReminder` (D)
+ *   - buildTaskCtxMemories() — assemble task-memory top-5 (pinned + recent +
+ *                              tag relevance) for task_ctx (E)
+ *
+ * Hard boundaries:
+ *   - does NOT touch 334o jsonl rotation internals (calls group.appendMessage)
+ *   - does NOT touch 334f shard-store impl (calls openMemoryShardStore API)
+ *   - does NOT touch 334e prompts main frame (returns plain shapes that feed
+ *     the existing renderTaskCtx contract)
+ *   - does NOT self-loop-write VP-memory (extractor writes task-memory only;
+ *     VP-level synthesis is deferred to 334g dream)
+ *   - softCap overflow does NOT create new shards (334f already routes into
+ *     dream queue via projectDeriveHint; we just surface `needsRecompression`)
+ */
+
+import { join } from 'path';
+import { openMemoryShardStore } from '../memory/shard-store.js';
+import { AUTHORED_BY } from '../memory/schema.js';
+
+// ─── §Δ31.4 soft-reminder thresholds ─────────────────────────────
+/** Must be initiator AND members>1 AND (age≥20min OR turns≥10). */
+export const SUMMARY_REMINDER_MIN_MEMBERS  = 2;
+export const SUMMARY_REMINDER_MIN_TURNS    = 10;
+export const SUMMARY_REMINDER_MIN_AGE_MS   = 20 * 60 * 1000;
+
+// ─── extractor limits ────────────────────────────────────────────
+export const EXTRACT_MIN_ENTRIES = 2;
+export const EXTRACT_MAX_ENTRIES = 5;
+
+/** Whitelist of R6 kinds emitted by the summary-extractor. */
+const EXTRACT_KINDS = Object.freeze(['progress', 'decision']);
+
+/** Shard routing for each extracted kind (§Δ25.2 task-memory fixed set). */
+const KIND_TO_SHARD = Object.freeze({
+  progress: 'progress',
+  decision: 'decision',
+});
+
+// ─── (B) postSummary ─────────────────────────────────────────────
+
+/**
+ * Write a `type=summary` message to the group log, then auto-run the
+ * extractor to derive task-memory entries.
+ *
+ * @param {{
+ *   group: import('../groups/group-store.js').GroupHandle,
+ *   taskId: string,
+ *   fromVpId: string,
+ *   body: string,
+ *   progress?: number,            // 0..100
+ *   supersedes?: string[],        // prior summary msgIds being superseded
+ *   memoryDir: string,            // groups/<g>/tasks/<t>/memory/
+ *   now?: () => number,           // test clock
+ *   extractor?: (body:string) => Array<{kind:string,body:string,tags?:string[]}>
+ *     // optional hook; default uses `defaultExtractor` (heuristic, no LLM)
+ * }} opts
+ * @returns {{ message: any, memoryIds: string[], supersededSummaryIds: string[] }}
+ */
+export function postSummary(opts) {
+  const {
+    group,
+    taskId,
+    fromVpId,
+    body,
+    progress,
+    supersedes,
+    memoryDir,
+    now = () => Date.now(),
+    extractor = defaultExtractor,
+  } = opts || {};
+
+  if (!group || typeof group.appendMessage !== 'function') {
+    throw new Error('postSummary: group handle required');
+  }
+  if (!taskId)   throw new Error('postSummary: taskId required');
+  if (!fromVpId) throw new Error('postSummary: fromVpId required');
+  if (typeof body !== 'string' || !body.trim()) {
+    throw new Error('postSummary: body required (non-empty string)');
+  }
+  if (progress != null) {
+    const p = Number(progress);
+    if (!Number.isFinite(p) || p < 0 || p > 100) {
+      throw new Error('postSummary: progress must be number in [0,100]');
+    }
+  }
+  const supersedesArr = Array.isArray(supersedes)
+    ? supersedes.filter((s) => typeof s === 'string' && s)
+    : [];
+
+  // 1) Append the summary message to the group jsonl log (type=summary).
+  const stored = group.appendMessage({
+    from: fromVpId,
+    role: 'assistant',
+    text: body,
+    taskId,
+    meta: {
+      type: 'summary',
+      progress: progress == null ? null : Number(progress),
+      supersedes: supersedesArr,
+    },
+  });
+
+  // 2) Run the extractor → write task-memory entries (C).
+  const memoryIds = [];
+  try {
+    const store = openMemoryShardStore(memoryDir, 'task');
+    const raw = extractor(body) || [];
+    const bounded = clampExtracted(raw);
+    for (const [i, item] of bounded.entries()) {
+      const kind = EXTRACT_KINDS.includes(item.kind) ? item.kind : 'progress';
+      const shard = KIND_TO_SHARD[kind] || 'progress';
+      const id = `mem-${stored.id}-${i + 1}`;
+      store.put({
+        id,
+        shard,
+        kind,
+        taskId,
+        body: typeof item.body === 'string' ? item.body.trim() : '',
+        tags: Array.isArray(item.tags) ? item.tags.slice(0, 5) : [],
+        authoredBy: AUTHORED_BY.SUMMARY,
+        sourceRef: { taskId, msgIds: [stored.id] },
+        createdAt: new Date(now()).toISOString(),
+      });
+      memoryIds.push(id);
+    }
+  } catch (err) {
+    // Extractor failures must not fail the summary post; the message is
+    // already persisted (audit property). We return the empty memoryIds so
+    // callers can surface a warning if they want.
+    // eslint-disable-next-line no-console
+    console.warn('[task-334n] summary-extractor failed:', err?.message || err);
+  }
+
+  return {
+    message: stored,
+    memoryIds,
+    supersededSummaryIds: supersedesArr,
+  };
+}
+
+/** Clamp raw extractor output to [EXTRACT_MIN_ENTRIES..EXTRACT_MAX_ENTRIES]. */
+function clampExtracted(arr) {
+  const cleaned = arr.filter((x) => x && typeof x.body === 'string' && x.body.trim());
+  if (cleaned.length === 0) return [];
+  return cleaned.slice(0, EXTRACT_MAX_ENTRIES);
+}
+
+// ─── (C) default extractor ───────────────────────────────────────
+
+/**
+ * Heuristic extractor — no LLM, deterministic, safe for tests.
+ *
+ * Strategy:
+ *   - Split body into non-empty lines (trim bullets).
+ *   - Lines starting with keywords "decide/decision/chose/chosen" → kind=decision.
+ *   - Lines starting with "progress/ship/shipped/done/completed/blocker/todo"
+ *     → kind=progress.
+ *   - Everything else → kind=progress (default).
+ *   - Emit up to EXTRACT_MAX_ENTRIES.
+ */
+export function defaultExtractor(body) {
+  if (typeof body !== 'string') return [];
+  const lines = body
+    .split(/\r?\n/)
+    .map((l) => l.replace(/^[\s*\-•]+/, '').trim())
+    .filter(Boolean);
+  const out = [];
+  for (const line of lines) {
+    const lower = line.toLowerCase();
+    let kind = 'progress';
+    if (/^(decide|decision|chose|chosen|pick|choose)\b/.test(lower)) {
+      kind = 'decision';
+    }
+    out.push({ kind, body: line });
+    if (out.length >= EXTRACT_MAX_ENTRIES) break;
+  }
+  // If we ended up with fewer than MIN and there was a body, collapse to
+  // one "progress" entry carrying the trimmed full body so we never emit 0
+  // when the caller gave us real content and asked for 2-5.
+  if (out.length < EXTRACT_MIN_ENTRIES && lines.length === 0 && body.trim()) {
+    out.push({ kind: 'progress', body: body.trim() });
+  }
+  return out;
+}
+
+// ─── (D) soft reminder builder ───────────────────────────────────
+
+/**
+ * Build the `taskCtx.summaryReminder` shape consumed by 334e's prompt.
+ * Returns null when the 3-AND conditions do not all hold. The prompt layer
+ * adds a 4th check (currentVpId === initiatorVpId) so we gate here too so
+ * callers can debug-log why it was suppressed.
+ *
+ * §Δ31.4 conditions:
+ *   (1) task.members.length > 1
+ *   (2) caller role === 'initiator'  (i.e. currentVpId === task.initiator)
+ *   (3) (now - lastSummaryAt) ≥ 20 min  OR  nonSummaryTurns ≥ 10
+ *
+ * @param {{
+ *   task: { initiator?: string, members?: string[] },
+ *   currentVpId: string,
+ *   lastSummaryAt: number,     // epoch ms, 0 = never
+ *   nonSummaryTurns: number,
+ *   now?: number,
+ * }} input
+ * @returns {{ triggered: boolean, nonSummaryCount: number, lastSummaryAt: number,
+ *             now: number, reasons: string[] }}
+ */
+export function buildSummaryReminder(input) {
+  const { task, currentVpId, lastSummaryAt = 0, nonSummaryTurns = 0 } = input || {};
+  const now = typeof input?.now === 'number' ? input.now : Date.now();
+  const reasons = [];
+
+  if (!task || typeof task !== 'object') {
+    return { triggered: false, reasons: ['no-task'], nonSummaryCount: nonSummaryTurns, lastSummaryAt, now };
+  }
+  const members = Array.isArray(task.members) ? task.members : [];
+  const isInitiator = !!currentVpId && task.initiator === currentVpId;
+
+  if (!isInitiator) reasons.push('not-initiator');
+  if (members.length <= SUMMARY_REMINDER_MIN_MEMBERS - 1) reasons.push('solo-task');
+
+  const ageMs = lastSummaryAt > 0 ? now - lastSummaryAt : Number.POSITIVE_INFINITY;
+  const ageOk = ageMs >= SUMMARY_REMINDER_MIN_AGE_MS;
+  const turnsOk = nonSummaryTurns >= SUMMARY_REMINDER_MIN_TURNS;
+  if (!ageOk && !turnsOk) reasons.push('too-soon');
+
+  const triggered = isInitiator && members.length >= SUMMARY_REMINDER_MIN_MEMBERS && (ageOk || turnsOk);
+  return {
+    triggered,
+    reasons,
+    nonSummaryCount: nonSummaryTurns,
+    lastSummaryAt,
+    now,
+  };
+}
+
+// ─── (E) task_ctx top-5 task-memory builder ──────────────────────
+
+/**
+ * Assemble task-memory top-5 for 334e's `taskCtx.memories` field.
+ * Ordering (§Δ16.5): pinned first → recent → tag-relevant. Supersedes are
+ * hidden (entries with supersededBy != null are filtered out).
+ *
+ * @param {string} memoryDir  groups/<g>/tasks/<t>/memory/
+ * @param {{ tags?: string[], top?: number }} [opts]
+ *   tags : optional tag hints to boost relevance
+ *   top  : default 5
+ * @returns {Array<{body:string, shard:string}>}
+ */
+export function buildTaskCtxMemories(memoryDir, opts = {}) {
+  const top = Number.isFinite(opts.top) ? Number(opts.top) : 5;
+  const tagHints = Array.isArray(opts.tags) ? opts.tags : [];
+  let results = [];
+  try {
+    const store = openMemoryShardStore(memoryDir, 'task');
+    const q = store.query({});
+    // query() returns thin entries (id/shard/kind/tags/pinned/groupId/taskId/supersededBy);
+    // we need the body too.
+    const hits = (q.results || [])
+      .filter((r) => !r.supersededBy)
+      .map((r) => {
+        const full = store.get(r.id);
+        return {
+          id: r.id,
+          shard: r.shard || 'general',
+          body: full?.body || '',
+          tags: Array.isArray(r.tags) ? r.tags : [],
+          pinned: !!r.pinned,
+          createdAt: full?.createdAt || null,
+        };
+      })
+      .filter((r) => r.body && r.body.trim());
+
+    const score = (r) => {
+      let s = 0;
+      if (r.pinned) s += 1000;
+      // recency proxy (ISO string compare works lexicographically)
+      if (r.createdAt) s += 10;
+      // tag relevance
+      for (const t of tagHints) if (r.tags.includes(t)) s += 5;
+      return s;
+    };
+    hits.sort((a, b) => {
+      const ds = score(b) - score(a);
+      if (ds !== 0) return ds;
+      // stable recency tie-break
+      return String(b.createdAt || '').localeCompare(String(a.createdAt || ''));
+    });
+    results = hits.slice(0, top).map((r) => ({ body: r.body, shard: r.shard }));
+  } catch {
+    results = [];
+  }
+  return results;
+}
+
+// ─── (F) related-task ACL fail-closed gate ───────────────────────
+
+/**
+ * Return memory/summary hints for a related task only when ACL grants.
+ * Caller passes the TaskStore so we can ask `canAccessRelated()`.
+ *
+ * @param {{
+ *   taskStore: import('./store.js').TaskStore,
+ *   currentTaskId: string,
+ *   otherTaskId: string,
+ *   vpId: string,
+ *   groupsRoot: string,
+ *   top?: number,
+ * }} input
+ * @returns {null | { id:string, title:string, members:string[], updatedAt?:number, memories:Array<{body:string,shard:string}> }}
+ *   null iff ACL denies — NEVER leak taskId in that case.
+ */
+export function getRelatedTaskCtx(input) {
+  const { taskStore, currentTaskId, otherTaskId, vpId, groupsRoot, top = 2 } = input || {};
+  if (!taskStore || !currentTaskId || !otherTaskId || !vpId || !groupsRoot) return null;
+  if (!taskStore.canAccessRelated(currentTaskId, otherTaskId, vpId)) return null;
+  const other = taskStore.get(otherTaskId);
+  if (!other || !other.groupId) return null;
+  const memoryDir = join(groupsRoot, other.groupId, 'tasks', other.id, 'memory');
+  const mems = buildTaskCtxMemories(memoryDir, { top });
+  return {
+    id: other.id,
+    title: other.title || other.id,
+    members: Array.isArray(other.members) ? other.members.slice() : [],
+    updatedAt: other.updatedAt || 0,
+    memories: mems,
+  };
+}

package/unify/tools/index.js

@@ -22,6 +22,8 @@ import memoryRead from './memory-read.js';
 import memoryWrite from './memory-write.js';
 import memorySearch, { memorySearchAlias } from './memory-search.js';
 import memoryQuery from './memory-query.js';
+import memoryTrace from './memory-trace.js';
+import openSourceMessage from './open-source-message.js';
 import webSearch from './web-search.js';
 import webFetch from './web-fetch.js';
 import historySearch from './history-search.js';
@@ -98,6 +100,8 @@ export const allTools = [
   memorySearch,
   memorySearchAlias,
   memoryQuery,
+  memoryTrace,
+  openSourceMessage,
   webSearch,
   webFetch,
   historySearch,

package/unify/tools/memory-trace.js

@@ -0,0 +1,135 @@
+/**
+ * memory-trace.js — task-334f R6 §Δ24.3.
+ *
+ * Given a memory id, return the full entry (including sourceRef) plus the
+ * original source messages referenced by sourceRef.msgIds / timeWindow.
+ *
+ * Hard guardrails (task-334f):
+ *   - Results are returned to the current turn ONLY. Nothing is written back
+ *     to memory; the extraction lane sees its own copy.
+ *   - Does not do cross-group fan-out. A trace is anchored to one groupId.
+ */
+
+import { defineTool } from './types.js';
+
+const MAX_BYTES = 64 * 1024;
+
+export default defineTool({
+  name: 'memory_trace',
+  description: `Trace a memory entry back to its original source messages.
+
+Use this when a recalled memory body is insufficient and you need the raw
+discussion. Returns the full memory entry (with sourceRef) plus the source
+messages from the group jsonl log.
+
+Parameters:
+  - memId (required): the memory id (from recall)
+  - expand: "full" (default, exact msgIds) | "window" (expand around timeWindow)
+
+Returns JSON: { memory, messages[], truncated? }.
+The result is NOT written back to memory — it is context for the current turn
+only.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      memId:  { type: 'string', description: 'Memory entry id' },
+      expand: { type: 'string', enum: ['full', 'window'], default: 'full' },
+    },
+    required: ['memId'],
+  },
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input, ctx) {
+    const memId = input?.memId;
+    if (!memId || typeof memId !== 'string') {
+      return JSON.stringify({ error: 'memId required (string)' });
+    }
+    const expand = input?.expand === 'window' ? 'window' : 'full';
+
+    const store = ctx?.memoryShardStore;
+    if (!store) {
+      return JSON.stringify({ error: 'R6 memory shard store not initialised' });
+    }
+    const entry = store.get(memId);
+    if (!entry) {
+      return JSON.stringify({ error: `memory entry not found: ${memId}` });
+    }
+
+    const sourceRef = entry.sourceRef || null;
+    if (!sourceRef) {
+      return JSON.stringify({
+        memory: entry,
+        messages: [],
+        note: 'entry has no sourceRef (pure declaration)',
+      });
+    }
+
+    const coordinator = ctx?.coordinator;
+    const groupId = sourceRef.groupId;
+    if (!coordinator || !groupId) {
+      return JSON.stringify({
+        memory: entry,
+        messages: [],
+        note: 'no group coordinator available',
+      });
+    }
+
+    const group = typeof coordinator.openGroup === 'function'
+      ? coordinator.openGroup(groupId)
+      : null;
+    if (!group) {
+      return JSON.stringify({
+        memory: entry,
+        messages: [],
+        note: `group ${groupId} not resolvable`,
+      });
+    }
+
+    const messages = [];
+    let bytes = 0;
+    let truncated = false;
+
+    if (expand === 'full' && Array.isArray(sourceRef.msgIds) && sourceRef.msgIds.length) {
+      const targetSet = new Set(sourceRef.msgIds);
+      // Walk only the smallest overlapping range instead of streaming all.
+      const first = sourceRef.msgIds[0];
+      const last  = sourceRef.msgIds[sourceRef.msgIds.length - 1];
+      const iter = typeof group.readMessageRange === 'function'
+        ? group.readMessageRange(first, last)
+        : group.streamMessages();
+      for (const msg of iter) {
+        if (!targetSet.has(msg.id)) continue;
+        const chunk = estimateBytes(msg);
+        if (bytes + chunk > MAX_BYTES) { truncated = true; break; }
+        messages.push(msg);
+        bytes += chunk;
+      }
+    } else if (expand === 'window' && sourceRef.timeWindow) {
+      // timeWindow is "ISO..ISO"; best-effort textual compare works for ULIDs/ISO.
+      const [t0, t1] = String(sourceRef.timeWindow).split('..');
+      for (const msg of group.streamMessages()) {
+        const ts = msg.ts || '';
+        if (t0 && ts < t0) continue;
+        if (t1 && ts > t1) break;
+        const chunk = estimateBytes(msg);
+        if (bytes + chunk > MAX_BYTES) { truncated = true; break; }
+        messages.push(msg);
+        bytes += chunk;
+      }
+    }
+
+    return JSON.stringify({
+      memory: entry,
+      messages,
+      ...(truncated ? { truncated: true } : {}),
+    });
+  },
+});
+
+function estimateBytes(msg) {
+  try {
+    return Buffer.byteLength(JSON.stringify(msg), 'utf8');
+  } catch {
+    return 512;
+  }
+}

package/unify/tools/open-source-message.js

@@ -0,0 +1,49 @@
+/**
+ * open-source-message.js — task-334f R6 §Δ24.4.
+ *
+ * Low-level random access: given a (groupId, msgId), fetch the raw message
+ * from the group's jsonl log. Used when a VP has an exact pointer but does
+ * not want to run the memory_trace wrapper (5% case: audit / debug).
+ */
+
+import { defineTool } from './types.js';
+
+export default defineTool({
+  name: 'open_source_message',
+  description: `Open a single source message by (groupId, msgId).
+
+This is the low-level random-access primitive. Prefer memory_trace if you are
+starting from a memory entry. Returns JSON: { message } or { error }.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      groupId: { type: 'string', description: 'Group id' },
+      msgId:   { type: 'string', description: 'Message id' },
+    },
+    required: ['groupId', 'msgId'],
+  },
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input, ctx) {
+    const { groupId, msgId } = input || {};
+    if (!groupId || !msgId) {
+      return JSON.stringify({ error: 'groupId and msgId required' });
+    }
+    const coordinator = ctx?.coordinator;
+    if (!coordinator || typeof coordinator.openGroup !== 'function') {
+      return JSON.stringify({ error: 'group coordinator not available' });
+    }
+    const group = coordinator.openGroup(groupId);
+    if (!group) return JSON.stringify({ error: `group not found: ${groupId}` });
+
+    const iter = typeof group.readMessageRange === 'function'
+      ? group.readMessageRange(msgId, msgId)
+      : group.streamMessages();
+    for (const msg of iter) {
+      if (msg.id === msgId) {
+        return JSON.stringify({ message: msg });
+      }
+    }
+    return JSON.stringify({ error: `message not found: ${msgId} in ${groupId}` });
+  },
+});

package/unify/tools/task-tools.js

@@ -515,3 +515,88 @@ approach, steps, and status of the current work.`,
     }
   },
 });
+
+// ─── TaskSummaryPost (task-334n) ────────────────────────
+
+import { postSummary } from '../tasks/summary.js';
+import { openGroup } from '../groups/group-store.js';
+import { join } from 'path';
+
+/**
+ * task-334n §B — initiator posts a progress summary to the group log.
+ * Triggers the summary-extractor automatically (§C).
+ */
+export const taskSummaryPost = defineTool({
+  name: 'task_summary_post',
+  description: `Post a progress summary for a multi-VP task (task-334n).
+
+Only the task initiator should call this. The summary is written to the
+group message log as \`type=summary\` and auto-extracts 2-5 task-memory
+entries (kind=progress|decision) via the task-memory shard lib.
+
+To revise a prior summary, pass its msgId in \`supersedes\` — the old
+summary is marked \`supersededBy\` while staying on disk for audit.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      taskId:   { type: 'string', description: 'Target task id' },
+      body:     { type: 'string', description: 'Summary body (markdown)' },
+      progress: { type: 'number', description: '0..100, optional' },
+      supersedes: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Prior summary msgIds this revision supersedes',
+      },
+    },
+    required: ['taskId', 'body'],
+  },
+  isConcurrencySafe: () => false,
+  isReadOnly: () => false,
+  async execute(input, ctx) {
+    const err = requireStore();
+    if (err) return err;
+    const { taskId, body, progress, supersedes } = input || {};
+    if (!taskId || !body) {
+      return JSON.stringify({ error: 'taskId and body are required' });
+    }
+    const task = taskStore.get(taskId);
+    if (!task) return JSON.stringify({ error: `task not found: ${taskId}` });
+    if (!task.groupId) {
+      return JSON.stringify({ error: 'task has no groupId; summary requires a group' });
+    }
+
+    const currentVpId = ctx?.currentVpId;
+    if (currentVpId && task.initiator && currentVpId !== task.initiator) {
+      return JSON.stringify({ error: 'only the task initiator may post summaries' });
+    }
+
+    const yeaftDir = ctx?.yeaftDir;
+    if (!yeaftDir) {
+      return JSON.stringify({ error: 'yeaftDir missing from tool context' });
+    }
+    const groupsRoot = join(yeaftDir, 'groups');
+    const memoryDir = join(groupsRoot, task.groupId, 'tasks', task.id, 'memory');
+
+    const group = openGroup(groupsRoot, task.groupId);
+    try {
+      const res = postSummary({
+        group,
+        taskId,
+        fromVpId: currentVpId || task.initiator || 'unknown',
+        body,
+        progress,
+        supersedes,
+        memoryDir,
+      });
+      return JSON.stringify({
+        success: true,
+        messageId: res.message.id,
+        memoryIds: res.memoryIds,
+        supersededSummaryIds: res.supersededSummaryIds,
+      });
+    } finally {
+      group.close();
+    }
+  },
+});
+