@yeaft/webchat-agent 0.1.873 → 0.1.875

package/yeaft/groups/coordinator.js

@@ -1,221 +0,0 @@
-/**
- * coordinator.js — Group Coordinator (task-334b).
- *
- * Consumes user/VP messages, persists them to the group's 334o jsonl-log,
- * and dispatches user-text turns to target RoleInstances'
- * `inputQueue`.
- *
- * As of GC.1 Commit B, VP-selection (parseMentions + dispatch matrix:
- * mention / @all / fallback / vp-author no-op) lives in
- * `groups/pre-flow.js` so the same logic can be invoked directly by
- * the parallel fan-out path in web-bridge.js. Coordinator's job is now
- * narrower: persist the message and translate the selection result
- * into deliver() calls.
- *
- * This module DOES NOT run the engine. It only:
- *   1. Persists the message (via GroupHandle.appendMessage)
- *   2. Asks pre-flow for the list of target vpIds
- *   3. Calls a user-supplied deliver(vpId, envelope) per target
- */
-
-import { parseMentions, selectRespondingVps } from './pre-flow.js';
-
-// Re-export so existing importers (`createCoordinator(...).parseMentions`,
-// or modules importing `parseMentions` from coordinator) keep working
-// without churn. New code should import from `./pre-flow.js` directly.
-export { parseMentions };
-
-/**
- * Build a Group Coordinator bound to a single GroupHandle.
- *
- * @param {import('./group-store.js').GroupHandle} group
- * @param {Object} [options]
- * @param {(vpId:string, envelope:any)=>void} [options.deliver]  called per target
- * @param {number} [options.perGroupFanOut=16]   @all cap (arch §5.3)
- * @returns {GroupCoordinator}
- */
-export function createCoordinator(group, options = {}) {
-  const deliver = options.deliver || (() => {});
-  const fanOutCap = options.perGroupFanOut ?? 16;
-
-  /**
-   * Ingest one message. Returns a dispatch report describing what would/did
-   * go out to RoleInstances.
-   *
-   * @param {{
-   *   from: string,              // 'user' | vpId
-   *   role?: 'user'|'assistant',
-   *   text: string,
-   *   taskId?: string|null,
-   *   meta?: any,
-   *   id?: string, ts?: string,
-   * }} input
-   * @param {{ taskMembers?: string[] }} [opts]
-   *   When taskId is set, restricts dispatch to vps in taskMembers (334n owns
-   *   the list). If omitted, coordinator will not filter.
-   */
-  function ingest(input, opts = {}) {
-    if (!input || typeof input !== 'object') {
-      throw new Error('ingest: input required');
-    }
-    if (typeof input.text !== 'string') {
-      throw new Error('ingest: input.text required (string)');
-    }
-    const meta = group.getMeta();
-    if (!meta) throw new Error('group not initialised (call createGroup first)');
-
-    // `fromUser` drives `selectRespondingVps` — when true, the @-mention
-    // matrix runs (mention/broadcast/fallback). When false, VPs cannot
-    // text-@-route (VP-authored free text is surface noise per arch §6).
-    //
-    // route_forward injection is a special case: the message is VP-authored
-    // (role='assistant') but it MUST trigger dispatch (target VP needs to
-    // run). We detect it via `meta.injectedBy === 'route_forward'` and
-    // treat it as "user-like" for dispatch purposes only. Persistence still
-    // honours the caller's `role` field so the on-disk record correctly
-    // attributes the turn to the sending VP, not to the user.
-    const isRouteForwardInjection = input?.meta?.injectedBy === 'route_forward';
-    const fromUser = input.from === 'user'
-      || input.role === 'user'
-      || isRouteForwardInjection;
-    const mentions = parseMentions(input.text);
-
-    // Persist first — audit log / replay works even if dispatch has bugs.
-    //
-    // Convention: any field on `input` that starts with `_` is treated
-    // as ephemeral and is forwarded to the envelope (so per-turn driver
-    // payloads — image base64 blocks, prompt suffixes — reach the LLM
-    // call) but is NEVER passed to appendMessage. The jsonl-log must
-    // stay lean: base64 in audit history would blow up replay.
-    //
-    // The split is enforced structurally — see the assertion below the
-    // partition loop. Don't loosen it. If a new ephemeral key is added,
-    // it gets the `_` prefix at its source and inherits the protection
-    // for free; no allowlist to maintain.
-    const persistInput = {};
-    const ephemeral = {};
-    for (const [k, v] of Object.entries(input)) {
-      if (typeof k === 'string' && k.startsWith('_')) {
-        ephemeral[k] = v;
-      } else {
-        persistInput[k] = v;
-      }
-    }
-    // Structural guarantee: nothing with a `_` prefix may reach the
-    // jsonl-log via `persistInput`. If this ever throws, the `_` rule
-    // got bypassed — fix the caller, not this assertion.
-    {
-      const leaked = Object.keys(persistInput).filter((k) => typeof k === 'string' && k.startsWith('_'));
-      if (leaked.length > 0) {
-        throw new Error(`coordinator.ingest: ephemeral fields leaked into persisted record: ${leaked.join(', ')}`);
-      }
-    }
-    const stored = group.appendMessage({
-      ...persistInput,
-      mentions,
-      role: input.role || (fromUser ? 'user' : 'assistant'),
-    });
-
-    // Ask pre-flow which VPs (if any) should respond.
-    const selection = selectRespondingVps({
-      meta,
-      fromUser,
-      mentions,
-      sender: input.from,
-      fanOutCap,
-      taskMembers: opts.taskMembers,
-    });
-
-    // VP-authored: persist but no dispatch.
-    if (selection.reason === 'vp-author-no-text-routing') {
-      return {
-        message: stored,
-        dispatched: [],
-        fallback: null,
-        errors: [],
-        skipped: 'vp-author-no-text-routing',
-      };
-    }
-
-    if (selection.reason === 'broadcast') {
-      const envelope = makeEnvelope(stored, meta, 'broadcast', ephemeral);
-      for (const vpId of selection.dispatched) deliver(vpId, envelope);
-      return {
-        message: stored,
-        dispatched: selection.dispatched,
-        fallback: null,
-        errors: selection.errors,
-        broadcast: true,
-        truncatedAtFanOutCap: !!selection.truncatedAtFanOutCap,
-      };
-    }
-
-    if (selection.reason === 'mention') {
-      for (const vpId of selection.dispatched) {
-        deliver(vpId, makeEnvelope(stored, meta, 'mention', ephemeral));
-      }
-      return {
-        message: stored,
-        dispatched: selection.dispatched,
-        fallback: null,
-        errors: selection.errors,
-      };
-    }
-
-    if (selection.reason === 'fallback' && selection.fallback) {
-      deliver(selection.fallback, makeEnvelope(stored, meta, 'fallback', ephemeral));
-      return {
-        message: stored,
-        dispatched: selection.dispatched,
-        fallback: selection.fallback,
-        errors: selection.errors,
-      };
-    }
-
-    // no-default / nothing to dispatch
-    return {
-      message: stored,
-      dispatched: [],
-      fallback: null,
-      errors: selection.errors,
-    };
-  }
-
-  return {
-    group,
-    ingest,
-    parseMentions,
-  };
-}
-
-function makeEnvelope(msg, meta, trigger, ephemeral = {}) {
-  return {
-    groupId: meta.id,
-    taskId: msg.taskId || null,
-    msg,
-    trigger, // 'broadcast' | 'mention' | 'fallback'
-    // Ephemeral fields (any `_`-prefixed key on coord.ingest input).
-    // Used to ferry per-turn payloads (e.g. image base64 blocks) that
-    // must reach the driver but must NOT be persisted to the group log.
-    ...ephemeral,
-  };
-}
-
-/**
- * @typedef {Object} GroupCoordinator
- * @property {import('./group-store.js').GroupHandle} group
- * @property {(input:any, opts?:any)=>DispatchReport} ingest
- * @property {(text:string)=>string[]} parseMentions
- */
-
-/**
- * @typedef {Object} DispatchReport
- * @property {any}       message
- * @property {string[]}  dispatched
- * @property {string|null} fallback
- * @property {Array<{vpId?:string, error:string}>} errors
- * @property {boolean=}  broadcast
- * @property {boolean=}  truncatedAtFanOutCap
- * @property {string=}   skipped
- */
-

package/yeaft/groups/group-store.js

@@ -1,212 +0,0 @@
-/**
- * group-store.js — Per-group persistent store for task-334b.
- *
- * Layout (see architecture §2):
- *   ~/.yeaft/groups/<group-id>/
- *     group.json          # { id, name, roster: [vpId...], defaultVpId, createdAt }
- *     messages/           # JSONL size-rotation log (334o openLog)
- *       000001.jsonl
- *       index.json
- *     tasks/              # populated by 334n — reserved here
- *     vps/                # populated by 334c RoleInstance runtime — reserved here
- *
- * This module owns only the group.json + messages/ log. Roster mutation
- * logic lives in roster.js so coordinator and group-store both compose it.
- *
- * Hard constraint: the store does not parse @-mentions, does not dispatch,
- * and has no knowledge of VP/RoleInstance. It is pure persistence over 334o.
- */
-
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  statSync,
-} from 'fs';
-import { join } from 'path';
-import { writeAtomic, openLog } from '../storage/index.js';
-import { nextMsgId, isReservedVpId, ReservedVpIdError, validateVpId, InvalidVpIdError } from './ids.js';
-
-const GROUP_FILE = 'group.json';
-const MESSAGES_DIR = 'messages';
-
-/**
- * Load (or create) the directory for a single group.
- *
- * @param {string} groupsRoot  e.g. `${yeaftDir}/groups`
- * @param {string} groupId
- * @returns {GroupHandle}
- */
-export function openGroup(groupsRoot, groupId) {
-  if (!groupId || typeof groupId !== 'string') {
-    throw new Error('openGroup: groupId required (string)');
-  }
-  const dir = join(groupsRoot, groupId);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-
-  let meta = loadGroupMeta(dir);
-  if (!meta) {
-    // Fresh group — caller must call initGroup() next; we return a handle
-    // with meta=null so createGroup() can write the initial file.
-  }
-
-  const messagesDir = join(dir, MESSAGES_DIR);
-  if (!existsSync(messagesDir)) mkdirSync(messagesDir, { recursive: true });
-  const log = openLog(messagesDir);
-
-  return {
-    dir,
-    id: groupId,
-    /** Return current meta (reads fresh from memory after last save). */
-    getMeta() { return meta ? structuredClone(meta) : null; },
-    /** Overwrite group.json atomically. */
-    saveMeta(next) {
-      validateMeta(next);
-      meta = next;
-      writeAtomic(join(dir, GROUP_FILE), JSON.stringify(meta, null, 2));
-    },
-    /**
-     * Append a message to the group log. Assigns an id if absent.
-     * Returns the stored record (with id + ts).
-     *
-     * Structural invariant: NO field on `record` may start with `_`.
-     * The `_` prefix is reserved for ephemeral per-turn payloads (image
-     * base64, prompt suffixes) that must reach the driver but must
-     * never hit the persisted jsonl-log. If this throws, the caller
-     * forgot to partition ephemeral fields off — fix the caller.
-     */
-    appendMessage(record) {
-      if (!record || typeof record !== 'object') {
-        throw new Error('appendMessage: record required');
-      }
-      {
-        const leaked = Object.keys(record).filter((k) => typeof k === 'string' && k.startsWith('_'));
-        if (leaked.length > 0) {
-          throw new Error(`appendMessage: ephemeral fields leaked into log: ${leaked.join(', ')}`);
-        }
-      }
-      const stored = {
-        id: record.id || nextMsgId(),
-        ts: record.ts || new Date().toISOString(),
-        from: record.from,   // vpId | 'user'
-        role: record.role || (record.from === 'user' ? 'user' : 'assistant'),
-        text: record.text ?? '',
-        taskId: record.taskId || null,
-        mentions: Array.isArray(record.mentions) ? record.mentions.slice() : [],
-        meta: record.meta || {},
-      };
-      log.append(stored);
-      return stored;
-    },
-    /** Iterate all messages oldest→newest. */
-    *streamMessages() {
-      yield* log.streamAll();
-    },
-    /** Iterate a message id range inclusive. */
-    *readMessageRange(firstId, lastId) {
-      yield* log.readRange(firstId, lastId);
-    },
-    /** Flush + close underlying log (on shutdown). */
-    close() { log.close(); },
-  };
-}
-
-/**
- * Create a fresh group on disk. Fails if group.json already exists.
- * @returns {GroupHandle}
- */
-export function createGroup(groupsRoot, spec) {
-  if (!spec || !spec.id) throw new Error('createGroup: spec.id required');
-  const h = openGroup(groupsRoot, spec.id);
-  if (h.getMeta()) {
-    throw new Error(`group ${spec.id} already exists`);
-  }
-  const roster = Array.isArray(spec.roster) ? spec.roster.slice() : [];
-  for (const v of roster) {
-    if (isReservedVpId(v)) throw new ReservedVpIdError(v);
-    const verdict = validateVpId(v);
-    if (!verdict.ok) throw new InvalidVpIdError(v, verdict.reason);
-  }
-  if (spec.defaultVpId) {
-    if (isReservedVpId(spec.defaultVpId)) throw new ReservedVpIdError(spec.defaultVpId);
-    const dverdict = validateVpId(spec.defaultVpId);
-    if (!dverdict.ok) throw new InvalidVpIdError(spec.defaultVpId, dverdict.reason);
-  }
-  const meta = {
-    id: spec.id,
-    name: spec.name || spec.id,
-    roster,
-    defaultVpId: spec.defaultVpId || null,
-    announcement: typeof spec.announcement === 'string' ? spec.announcement : '',
-    workDir: typeof spec.workDir === 'string' ? spec.workDir.trim() : '',
-    createdAt: spec.createdAt || new Date().toISOString(),
-  };
-  h.saveMeta(meta);
-  return h;
-}
-
-/** Non-destructive load — returns null if group.json is missing/corrupt. */
-export function loadGroupMeta(dir) {
-  const path = join(dir, GROUP_FILE);
-  if (!existsSync(path)) return null;
-  try {
-    const raw = readFileSync(path, 'utf8');
-    const parsed = JSON.parse(raw);
-    validateMeta(parsed);
-    // Legacy groups created before optional fields were added are
-    // forward-compat: missing fields read back as safe empty strings.
-    if (typeof parsed.announcement !== 'string') parsed.announcement = '';
-    if (typeof parsed.workDir !== 'string') parsed.workDir = '';
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-/** List every group directory under `groupsRoot`. */
-export function listGroups(groupsRoot) {
-  if (!existsSync(groupsRoot)) return [];
-  const out = [];
-  for (const name of readdirSync(groupsRoot)) {
-    // Skip dotfiles and legacy soft-archive dirs (`.archived-*`).
-    if (name.startsWith('.')) continue;
-    const p = join(groupsRoot, name);
-    try {
-      if (!statSync(p).isDirectory()) continue;
-    } catch { continue; }
-    const meta = loadGroupMeta(p);
-    if (meta) out.push(meta);
-  }
-  return out;
-}
-
-function validateMeta(meta) {
-  if (!meta || typeof meta !== 'object') throw new Error('group.json must be object');
-  if (!meta.id || typeof meta.id !== 'string') throw new Error('group.id required');
-  if (!Array.isArray(meta.roster)) throw new Error('group.roster must be array');
-  for (const v of meta.roster) {
-    if (typeof v !== 'string') throw new Error('group.roster must be string[]');
-  }
-  if (meta.defaultVpId != null && typeof meta.defaultVpId !== 'string') {
-    throw new Error('group.defaultVpId must be string|null');
-  }
-  if (meta.announcement != null && typeof meta.announcement !== 'string') {
-    throw new Error('group.announcement must be string');
-  }
-  if (meta.workDir != null && typeof meta.workDir !== 'string') {
-    throw new Error('group.workDir must be string');
-  }
-}
-
-/**
- * @typedef {Object} GroupHandle
- * @property {string} dir
- * @property {string} id
- * @property {() => any} getMeta
- * @property {(next:any)=>void} saveMeta
- * @property {(record:any)=>any} appendMessage
- * @property {() => Generator<any>} streamMessages
- * @property {(first:string,last:string)=>Generator<any>} readMessageRange
- * @property {() => void} close
- */