@yeaft/webchat-agent 0.1.481 → 0.1.483

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.481",
+  "version": "0.1.483",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/conversation/migrate-messages-threadid.js

@@ -0,0 +1,116 @@
+/**
+ * migrate-messages-threadid.js — task-307 one-shot migration.
+ *
+ * For every message under <yeaftDir>/conversation/messages/ and cold/ that
+ * does NOT yet carry a `threadId:` frontmatter field, stamp it with
+ * `threadId: main`. This matches design §5 semantics: pre-Phase-2 messages
+ * predate threading and belong to the root conversation.
+ *
+ * Idempotency:
+ *   A marker file `<yeaftDir>/conversation/.migrations/messagesThreadId`
+ *   is written on successful completion. Subsequent runs observe the
+ *   marker and short-circuit with `{ ran: false }`.
+ *
+ * Safety:
+ *   - Messages that already carry a threadId are left untouched.
+ *   - If a file is unreadable / unparseable it is skipped (never rewritten).
+ *   - Write errors are swallowed so a half-successful migration can resume
+ *     on the next boot by re-running.
+ *
+ * Usage (programmatic):
+ *   import { migrateMessagesThreadId } from './migrate-messages-threadid.js';
+ *   const res = migrateMessagesThreadId('/home/me/.yeaft');
+ *   // { ran: true, migrated: 42, skipped: 3 }
+ *
+ * Usage (CLI):
+ *   node agent/unify/conversation/migrate-messages-threadid.js [yeaftDir]
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export function migrateMessagesThreadId(yeaftDir) {
+  const root = yeaftDir || join(homedir(), '.yeaft');
+  const convDir = join(root, 'conversation');
+  const markerDir = join(convDir, '.migrations');
+  const markerPath = join(markerDir, 'messagesThreadId');
+
+  if (!existsSync(convDir)) {
+    return { ran: false, reason: 'no conversation dir', migrated: 0, skipped: 0 };
+  }
+  try {
+    if (existsSync(markerPath)) {
+      return { ran: false, reason: 'already migrated', migrated: 0, skipped: 0 };
+    }
+  } catch { /* best-effort */ }
+
+  const dirs = [join(convDir, 'messages'), join(convDir, 'cold')];
+  let migrated = 0;
+  let skipped = 0;
+
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    let files;
+    try {
+      files = readdirSync(dir).filter(f => f.endsWith('.md'));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      const path = join(dir, f);
+      let raw;
+      try {
+        raw = readFileSync(path, 'utf8');
+      } catch {
+        skipped += 1;
+        continue;
+      }
+      if (!raw || !raw.startsWith('---')) { skipped += 1; continue; }
+      const endIdx = raw.indexOf('\n---', 3);
+      if (endIdx === -1) { skipped += 1; continue; }
+      const frontmatter = raw.slice(4, endIdx);
+      const body = raw.slice(endIdx); // leading '\n---' ...
+      if (/^threadId:/m.test(frontmatter)) {
+        skipped += 1;
+        continue; // already has threadId
+      }
+      const newFm = frontmatter.replace(/\s*$/, '') + '\nthreadId: main';
+      const rebuilt = '---\n' + newFm.trimStart() + body;
+      try {
+        writeFileSync(path, rebuilt, { encoding: 'utf8', mode: 0o644 });
+        migrated += 1;
+      } catch {
+        skipped += 1;
+      }
+    }
+  }
+
+  try {
+    mkdirSync(markerDir, { recursive: true, mode: 0o755 });
+    writeFileSync(
+      markerPath,
+      `migrated: ${new Date().toISOString()}\ncount: ${migrated}\nskipped: ${skipped}\n`,
+      { encoding: 'utf8', mode: 0o644 },
+    );
+  } catch {
+    // Without the marker the migration will re-run; it's idempotent per-file
+    // (files already carrying threadId are skipped) so that's acceptable.
+  }
+
+  return { ran: true, migrated, skipped };
+}
+
+// CLI entry point.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const dir = process.argv[2];
+  const res = migrateMessagesThreadId(dir);
+  // eslint-disable-next-line no-console
+  console.log(JSON.stringify(res, null, 2));
+}

package/unify/conversation/persist.js

@@ -56,6 +56,10 @@ function serializeMessage(msg) {
   if (msg.turnNumber != null) fm.push(`turnNumber: ${msg.turnNumber}`);
   if (msg.toolCallId) fm.push(`toolCallId: ${msg.toolCallId}`);
   if (msg.isError) fm.push(`isError: true`);
+  // task-307: every message is stamped with a threadId so multi-thread
+  // routing can filter/replay by thread without rescanning JSON blobs.
+  // Defaults to 'main' for legacy messages (see migrate-messages-threadid.js).
+  fm.push(`threadId: ${msg.threadId || 'main'}`);
 
   // Token estimate
   const content = msg.content || '';
@@ -111,10 +115,14 @@ export function parseMessage(raw) {
       case 'toolCallId': msg.toolCallId = value; break;
       case 'isError': msg.isError = value === 'true'; break;
       case 'tokens_est': msg.tokens_est = parseInt(value, 10); break;
+      case 'threadId': msg.threadId = value; break;
       // toolCalls are multi-line YAML — handled separately below
     }
   }
 
+  // task-307: legacy messages written before threadId existed default to 'main'.
+  if (!msg.threadId) msg.threadId = 'main';
+
   // Parse toolCalls if present (simplified multi-line YAML)
   if (frontmatter.includes('toolCalls:')) {
     const toolCalls = [];

package/unify/input-queue/store.js

@@ -0,0 +1,322 @@
+/**
+ * input-queue/store.js — Persistent FIFO input queue for Yeaft Unify.
+ *
+ * task-307b (Phase 2): a disk-backed queue of user inputs waiting to be
+ * routed to a thread/engine. Each entry is one JSON file at
+ *   <yeaftDir>/input-queue/<id>.json
+ * so that crashing during a routing decision never loses a queued input.
+ *
+ * Schema follows design doc §5:
+ *   {
+ *     id:         'iq-xxxxxxxx',
+ *     text:       '<the user-typed input>',
+ *     createdAt:  1234567890123,            // epoch ms
+ *     status:     'pending' | 'routing' | 'dispatched',
+ *     routedTo:   '<threadId>' | null,      // set when status === 'dispatched'
+ *     routedAt:   1234567890456 | null,
+ *     error:      '<message>' | null,       // optional — populated when a
+ *                                           //   routing attempt fails and
+ *                                           //   the entry is put back to
+ *                                           //   'pending' for retry.
+ *   }
+ *
+ * State machine:
+ *        enqueue(text)
+ *             │
+ *             ▼
+ *         pending ─────claim()─────► routing ─────markRouted()────► dispatched
+ *             ▲                        │
+ *             └──────markFailed()──────┘  (status back to pending; error field recorded)
+ *
+ *   - pending    : waiting for a dispatcher
+ *   - routing    : a dispatcher has taken responsibility; crash here means
+ *                  boot-time recovery will still see the entry and can
+ *                  re-claim it (the row is still on disk).
+ *   - dispatched : routed to a thread — the file is removed because the
+ *                  durable audit trail now lives in the messages.
+ *
+ * API (task-307b per PM):
+ *   - enqueue(text)                → entry          Create + persist pending.
+ *   - dequeue()                    → entry | null   Peek at oldest pending
+ *                                                   (non-mutating — see
+ *                                                   claim() for the mutating
+ *                                                   transition).
+ *   - claim()                      → entry | null   Oldest pending → 'routing'
+ *                                                   (atomic w.r.t. disk).
+ *   - list(status?)                → entry[]        Snapshot filtered by status.
+ *   - markRouted(id, routedTo)     → entry | null   routing → dispatched;
+ *                                                   file deleted.
+ *   - markFailed(id, err)          → entry | null   routing → pending; error
+ *                                                   recorded; kept on disk.
+ *   - peek() / get(id) / remove(id) / size() / pendingCount()
+ *
+ * Persistence:
+ *   - Writes are synchronous. The queue is a durability boundary, not a
+ *     hot path (one write per state transition).
+ *   - Permission/FS failures don't throw: they are swallowed and logged once
+ *     per process (matches ConversationStore's philosophy).
+ *   - If `yeaftDir` is omitted, the store operates purely in memory.
+ */
+
+import { randomUUID } from 'crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+} from 'fs';
+import { join } from 'path';
+
+/** All valid status values, per design §5. */
+export const INPUT_QUEUE_STATUSES = ['pending', 'routing', 'dispatched'];
+
+export class InputQueueStore {
+  /** @type {Map<string, object>} */
+  #entries;
+  /** @type {string|null} */
+  #dir;
+  /** @type {boolean} */
+  #persistent;
+  /** @type {boolean} */
+  #warned;
+
+  /**
+   * @param {string|null} [yeaftDir]
+   */
+  constructor(yeaftDir = null) {
+    this.#entries = new Map();
+    this.#warned = false;
+
+    if (yeaftDir) {
+      this.#dir = join(yeaftDir, 'input-queue');
+      this.#persistent = true;
+      this.#ensureDir();
+      this.#loadAll();
+    } else {
+      this.#dir = null;
+      this.#persistent = false;
+    }
+  }
+
+  get persistent() { return this.#persistent; }
+  size() { return this.#entries.size; }
+
+  pendingCount() {
+    let n = 0;
+    for (const e of this.#entries.values()) if (e.status === 'pending') n += 1;
+    return n;
+  }
+
+  /**
+   * Append a new pending entry and persist it.
+   * @param {string} text
+   * @returns {object} the entry
+   */
+  enqueue(text) {
+    if (typeof text !== 'string') throw new Error('text must be a string');
+    const id = `iq-${randomUUID().slice(0, 8)}`;
+    const entry = {
+      id,
+      text,
+      createdAt: Date.now(),
+      status: 'pending',
+      routedTo: null,
+      routedAt: null,
+      error: null,
+    };
+    this.#entries.set(id, entry);
+    this.#writeEntry(entry);
+    return entry;
+  }
+
+  /** Oldest pending entry (no state change). null if empty. */
+  peek() {
+    let oldest = null;
+    for (const e of this.#entries.values()) {
+      if (e.status !== 'pending') continue;
+      if (!oldest || e.createdAt < oldest.createdAt) oldest = e;
+    }
+    return oldest;
+  }
+
+  /**
+   * Return the oldest pending entry without mutating state. Kept as a
+   * separate method from claim() because some consumers only want to
+   * observe the head of the queue (e.g. UI preview).
+   */
+  dequeue() {
+    return this.peek();
+  }
+
+  /**
+   * Transition the oldest pending entry → 'routing' and persist. This is
+   * the real consumer-facing take: after claim() the caller must eventually
+   * call markRouted() (success) or markFailed() (→ put back as pending).
+   *
+   * @returns {object|null} the claimed entry, or null if nothing pending
+   */
+  claim() {
+    const e = this.peek();
+    if (!e) return null;
+    e.status = 'routing';
+    this.#writeEntry(e);
+    return e;
+  }
+
+  /**
+   * Mark an entry as successfully dispatched to a thread. Persists the
+   * updated state then removes the file — the authoritative record now
+   * lives in the conversation/messages log.
+   *
+   * @param {string} id
+   * @param {string} routedTo — thread id (e.g. 'main' or 'thr-xxxxxxxx')
+   * @returns {object|null}
+   */
+  markRouted(id, routedTo) {
+    const e = this.#entries.get(id);
+    if (!e) return null;
+    if (!routedTo || typeof routedTo !== 'string') throw new Error('routedTo required');
+    e.status = 'dispatched';
+    e.routedTo = routedTo;
+    e.routedAt = Date.now();
+    // Persist the transition before removing (crash-safe ordering).
+    this.#writeEntry(e);
+    this.#removeFile(id);
+    this.#entries.delete(id);
+    return e;
+  }
+
+  /**
+   * Mark a routing attempt failed. The entry returns to 'pending' so the
+   * next claim() can retry it; the error string is retained for diagnostics.
+   *
+   * @param {string} id
+   * @param {string|Error} err
+   */
+  markFailed(id, err) {
+    const e = this.#entries.get(id);
+    if (!e) return null;
+    e.status = 'pending';
+    e.error = typeof err === 'string' ? err : (err?.message || String(err));
+    this.#writeEntry(e);
+    return e;
+  }
+
+  /** Remove an entry entirely (memory + disk). */
+  remove(id) {
+    if (!this.#entries.has(id)) return false;
+    this.#entries.delete(id);
+    this.#removeFile(id);
+    return true;
+  }
+
+  /**
+   * Snapshot of all entries, optionally filtered by status. Chronological.
+   * @param {'pending'|'routing'|'dispatched'} [status]
+   */
+  list(status) {
+    let arr = [...this.#entries.values()];
+    if (status) arr = arr.filter(e => e.status === status);
+    arr.sort((a, b) => a.createdAt - b.createdAt);
+    return arr;
+  }
+
+  get(id) { return this.#entries.get(id) || null; }
+
+  // ─── Persistence internals ────────────────────────────
+
+  #ensureDir() {
+    try {
+      if (!existsSync(this.#dir)) mkdirSync(this.#dir, { recursive: true, mode: 0o755 });
+    } catch (err) {
+      this.#warn(`Cannot create input-queue dir: ${err?.code || err?.message}`);
+    }
+  }
+
+  #loadAll() {
+    if (!existsSync(this.#dir)) return;
+    let files;
+    try {
+      files = readdirSync(this.#dir);
+    } catch (err) {
+      this.#warn(`Cannot read input-queue dir: ${err?.code || err?.message}`);
+      return;
+    }
+    for (const f of files) {
+      if (!f.endsWith('.json')) continue;
+      const path = join(this.#dir, f);
+      try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || !parsed.id) continue;
+        if (!INPUT_QUEUE_STATUSES.includes(parsed.status)) continue;
+        // Crash recovery: an entry left in 'routing' at startup had a
+        // dispatcher claim it right before the crash. Put it back to
+        // 'pending' so the next claim() can retry it.
+        const status = parsed.status === 'routing' ? 'pending' : parsed.status;
+        this.#entries.set(parsed.id, {
+          id: parsed.id,
+          text: typeof parsed.text === 'string' ? parsed.text : '',
+          createdAt: Number(parsed.createdAt) || Date.now(),
+          status,
+          routedTo: parsed.routedTo || null,
+          routedAt: parsed.routedAt || null,
+          error: parsed.error || null,
+        });
+      } catch {
+        // Skip corrupt file.
+      }
+    }
+  }
+
+  #writeEntry(entry) {
+    if (!this.#persistent) return;
+    const path = join(this.#dir, `${entry.id}.json`);
+    try {
+      writeFileSync(path, JSON.stringify(entry, null, 2), { encoding: 'utf8', mode: 0o644 });
+    } catch (err) {
+      this.#warn(`Cannot write ${entry.id}: ${err?.code || err?.message}`);
+    }
+  }
+
+  #removeFile(id) {
+    if (!this.#persistent) return;
+    const path = join(this.#dir, `${id}.json`);
+    if (!existsSync(path)) return;
+    try {
+      unlinkSync(path);
+    } catch (err) {
+      this.#warn(`Cannot remove ${id}: ${err?.code || err?.message}`);
+    }
+  }
+
+  #warn(msg) {
+    if (this.#warned) return;
+    this.#warned = true;
+    // eslint-disable-next-line no-console
+    console.warn(`[Yeaft InputQueue] ${msg}`);
+  }
+}
+
+// ─── Singleton helpers ────────────────────────────────────
+
+/** @type {InputQueueStore|null} */
+let inputQueueStore = null;
+
+export function initInputQueueStore(opts = {}) {
+  if (!inputQueueStore || opts.force) {
+    inputQueueStore = new InputQueueStore(opts.yeaftDir || null);
+  }
+  return inputQueueStore;
+}
+
+export function getInputQueueStore() {
+  if (!inputQueueStore) inputQueueStore = new InputQueueStore(null);
+  return inputQueueStore;
+}
+
+export function _resetInputQueueStoreForTests() {
+  inputQueueStore = null;
+}

package/unify/session.js

@@ -25,6 +25,8 @@ import { createFullRegistry } from './tools/index.js';
 import { initTaskStore } from './tools/task-tools.js';
 import { initThreadStore } from './threads/store.js';
 import { Engine } from './engine.js';
+import { createThreadEngineRegistry } from './threads/engine-registry.js';
+import { MAIN_THREAD_ID } from './threads/store.js';
 import { join } from 'path';
 
 /**
@@ -166,6 +168,25 @@ export async function loadSession(options = {}) {
     yeaftDir,
   });
 
+  // task-308 Phase 2: thread-aware engine registry.
+  // Each thread gets its own EngineInstance (lazy-created) that owns its
+  // messages array and tags all events with the bound threadId. Legacy
+  // single-engine callers keep working via `session.engine`; multi-thread
+  // callers use `session.engineRegistry.ensure(threadId)`.
+  const engineRegistry = createThreadEngineRegistry({
+    adapter,
+    trace,
+    config,
+    conversationStore,
+    memoryStore,
+    toolRegistry,
+    skillManager,
+    mcpManager,
+    yeaftDir,
+  });
+  // Seed the main-thread instance so listActive() is non-empty from T=0.
+  engineRegistry.ensure(MAIN_THREAD_ID);
+
   // ─── 10. Build session ─────────────────────────────────
   const status = {
     skills: skillManager.size,
@@ -176,6 +197,11 @@ export async function loadSession(options = {}) {
 
   /** Graceful shutdown: disconnect MCP, close trace DB. */
   async function shutdown() {
+    try {
+      engineRegistry.terminateAll();
+    } catch {
+      // Best-effort cleanup
+    }
     try {
       await mcpManager.disconnectAll();
     } catch {
@@ -190,6 +216,7 @@ export async function loadSession(options = {}) {
 
   return {
     engine,
+    engineRegistry,
     adapter,
     config,
     conversationStore,

package/unify/threads/engine-instance.js

@@ -0,0 +1,218 @@
+/**
+ * engine-instance.js — task-308 Phase 2.
+ *
+ * An EngineInstance binds a single `threadId` to an Engine + an independent
+ * per-thread `messages` array + an independent memory scope ref. Multiple
+ * EngineInstance objects can run .query() concurrently on the same unify
+ * session without cross-contaminating state:
+ *
+ *   - The underlying Engine's query loop is a pure async generator that
+ *     takes `messages` as a parameter — it holds no mutable turn state on
+ *     `this` during a run, so concurrent generators cannot alias each
+ *     other's conversation or tool-call arrays.
+ *   - All yielded events are re-tagged with the instance's bound
+ *     `threadId` (not with the global current-thread marker from the
+ *     singleton ThreadStore), so the web-bridge can route them to the
+ *     right pane even while several threads stream simultaneously.
+ *   - `messages` is owned by the instance: user/assistant messages
+ *     appended during a query are persisted to the instance's own array,
+ *     not to a global.
+ *
+ * Memory scope: Phase 2 design doc §6 — the memory store is shared across
+ * threads (one user, one brain), but the EngineInstance carries a
+ * `memoryScope` ref that can later be used to namespace recall/query
+ * results by thread. Today the ref is the threadId itself; downstream
+ * memory adapters can opt in.
+ *
+ * Q2 decision (PM brief): all threads use session primaryModel. No
+ * per-thread model override is accepted.
+ */
+
+import { Engine } from '../engine.js';
+import { MAIN_THREAD_ID } from './store.js';
+
+export class EngineInstance {
+  /** @type {string} */
+  #threadId;
+
+  /** @type {Engine} */
+  #engine;
+
+  /** @type {Array<object>} owned per-thread conversation messages */
+  #messages;
+
+  /** @type {string} memory scope ref — today simply the threadId */
+  #memoryScope;
+
+  /** @type {boolean} */
+  #terminated = false;
+
+  /**
+   * @param {{
+   *   threadId: string,
+   *   engine: Engine,
+   *   memoryScope?: string,
+   *   initialMessages?: Array<object>,
+   * }} params
+   */
+  constructor({ threadId, engine, memoryScope, initialMessages }) {
+    if (!threadId || typeof threadId !== 'string') {
+      throw new Error('EngineInstance: threadId is required');
+    }
+    if (!engine) {
+      throw new Error('EngineInstance: engine is required');
+    }
+    this.#threadId = threadId;
+    this.#engine = engine;
+    this.#memoryScope = memoryScope || threadId;
+    this.#messages = Array.isArray(initialMessages) ? [...initialMessages] : [];
+  }
+
+  /** @returns {string} */
+  get threadId() { return this.#threadId; }
+
+  /** @returns {string} */
+  get memoryScope() { return this.#memoryScope; }
+
+  /** @returns {boolean} */
+  get terminated() { return this.#terminated; }
+
+  /** Number of messages recorded on this instance. */
+  get messageCount() { return this.#messages.length; }
+
+  /** Snapshot of the current messages array (copy, safe for callers). */
+  get messages() { return [...this.#messages]; }
+
+  /** Underlying Engine (for tool registration, trace access, etc.). */
+  get engine() { return this.#engine; }
+
+  /**
+   * Run a query on this thread's engine. Yields events tagged with this
+   * instance's bound threadId. After the run, user + assistant messages
+   * are appended to the owned messages array.
+   *
+   * @param {object} params
+   * @param {string} params.prompt
+   * @param {'dream'} [params.mode]
+   * @param {AbortSignal} [params.signal]
+   * @yields {object} EngineEvent with { ...event, threadId }
+   */
+  async *query({ prompt, mode, signal }) {
+    if (this.#terminated) {
+      yield {
+        type: 'error',
+        threadId: this.#threadId,
+        error: new Error(`EngineInstance(${this.#threadId}) has been terminated`),
+        retryable: false,
+      };
+      return;
+    }
+
+    // Snapshot of messages passed to the engine; the engine treats this
+    // as read-only (it builds its own conversation array internally).
+    const snapshot = [...this.#messages];
+    let assistantText = '';
+    const assistantToolCalls = [];
+
+    for await (const event of this.#engine.query({ prompt, mode, messages: snapshot, signal })) {
+      // Re-tag every event with the bound threadId. Non-object events
+      // (shouldn't happen — all engine events are objects) are passed
+      // through untouched.
+      const tagged = event && typeof event === 'object'
+        ? { ...event, threadId: this.#threadId }
+        : event;
+      yield tagged;
+
+      // Track assistant reply to persist after stream ends. Only tag the
+      // natural stream types — not our injected turn_start/turn_end.
+      if (event && typeof event === 'object') {
+        if (event.type === 'text_delta' && typeof event.text === 'string') {
+          assistantText += event.text;
+        } else if (event.type === 'tool_call') {
+          assistantToolCalls.push({ id: event.id, name: event.name, input: event.input });
+        }
+      }
+    }
+
+    // Append user + assistant to the owned messages array so subsequent
+    // queries on this thread carry conversational context.
+    this.#messages.push({ role: 'user', content: prompt });
+    const assistantMsg = { role: 'assistant', content: assistantText };
+    if (assistantToolCalls.length > 0) {
+      assistantMsg.toolCalls = assistantToolCalls;
+    }
+    this.#messages.push(assistantMsg);
+  }
+
+  /**
+   * Terminate this engine instance. Further .query() calls will emit an
+   * error event and return early. Does NOT tear down the underlying
+   * Engine (engines are shared across instances via composition from
+   * the registry — only the instance's per-thread state is dropped).
+   */
+  terminate() {
+    this.#terminated = true;
+    this.#messages = [];
+  }
+
+  /**
+   * Reset the owned messages array. Used by the registry for crash
+   * recovery / test cleanup. Does NOT terminate the instance.
+   * @param {Array<object>} [messages=[]]
+   */
+  resetMessages(messages = []) {
+    this.#messages = Array.isArray(messages) ? [...messages] : [];
+  }
+}
+
+/**
+ * Factory helper — builds an EngineInstance that owns a fresh Engine,
+ * sharing the given dependency bag across all threads of a session.
+ *
+ * @param {{
+ *   threadId: string,
+ *   adapter: object,
+ *   trace: object,
+ *   config: object,
+ *   conversationStore?: object,
+ *   memoryStore?: object,
+ *   toolRegistry?: object,
+ *   skillManager?: object,
+ *   mcpManager?: object,
+ *   yeaftDir?: string,
+ *   initialMessages?: Array<object>,
+ * }} deps
+ * @returns {EngineInstance}
+ */
+export function createEngineInstance(deps) {
+  const {
+    threadId,
+    adapter,
+    trace,
+    config,
+    conversationStore,
+    memoryStore,
+    toolRegistry,
+    skillManager,
+    mcpManager,
+    yeaftDir,
+    initialMessages,
+  } = deps;
+  const engine = new Engine({
+    adapter,
+    trace,
+    config,
+    conversationStore,
+    memoryStore,
+    toolRegistry,
+    skillManager,
+    mcpManager,
+    yeaftDir,
+  });
+  return new EngineInstance({
+    threadId: threadId || MAIN_THREAD_ID,
+    engine,
+    memoryScope: threadId || MAIN_THREAD_ID,
+    initialMessages,
+  });
+}

package/unify/threads/engine-registry.js

@@ -0,0 +1,192 @@
+/**
+ * engine-registry.js — task-308 Phase 2.
+ *
+ * A ThreadEngineRegistry is a per-session Map<threadId, EngineInstance>.
+ * It owns instance lifecycles:
+ *
+ *   - `get(threadId)` returns the existing instance for a thread.
+ *   - `ensure(threadId, opts)` lazily creates one via the configured
+ *     factory if it does not yet exist. This is the primary entry point
+ *     for routing a user message to the correct thread engine.
+ *   - `listActive()` enumerates non-terminated instances, useful for
+ *     the web-bridge to show "active threads" indicators.
+ *   - `terminate(threadId)` tears down a single thread engine without
+ *     disturbing the rest.
+ *   - `terminateAll()` is called on session shutdown.
+ *
+ * The registry holds no LLM/tool state itself — it delegates to the
+ * factory, which in production will be the closure over the shared
+ * session deps (adapter, trace, config, stores, tool registry, …).
+ *
+ * Concurrency note: Node's single-threaded event loop means the
+ * registry's Map mutations are race-free. Concurrent .query() calls
+ * interleave only at await points, and each EngineInstance keeps its
+ * per-turn state inside the async generator's local scope, not on
+ * `this` — so two threads can stream simultaneously without stepping
+ * on each other.
+ */
+
+import { MAIN_THREAD_ID } from './store.js';
+import { createEngineInstance } from './engine-instance.js';
+
+export class ThreadEngineRegistry {
+  /** @type {Map<string, import('./engine-instance.js').EngineInstance>} */
+  #instances;
+
+  /** @type {(threadId: string, opts?: object) => import('./engine-instance.js').EngineInstance} */
+  #factory;
+
+  /** @type {string} */
+  #currentThreadId;
+
+  /**
+   * @param {{
+   *   factory: (threadId: string, opts?: object) => import('./engine-instance.js').EngineInstance,
+   * }} params
+   */
+  constructor({ factory } = {}) {
+    if (typeof factory !== 'function') {
+      throw new Error('ThreadEngineRegistry: factory function is required');
+    }
+    this.#instances = new Map();
+    this.#factory = factory;
+    this.#currentThreadId = MAIN_THREAD_ID;
+  }
+
+  /** @returns {string} */
+  get currentThreadId() { return this.#currentThreadId; }
+
+  /** Total number of registered (including terminated) instances. */
+  get size() { return this.#instances.size; }
+
+  /**
+   * Get an existing instance for a thread. Returns null if not yet
+   * created. Does NOT lazy-create — use ensure() for that.
+   * @param {string} threadId
+   */
+  get(threadId) {
+    return this.#instances.get(threadId) || null;
+  }
+
+  /**
+   * Lazy-get-or-create an instance for a thread. If one already exists
+   * and is not terminated, it is returned; if it was terminated, a new
+   * one replaces it. Any `opts` are forwarded to the factory.
+   *
+   * @param {string} threadId
+   * @param {object} [opts]
+   * @returns {import('./engine-instance.js').EngineInstance}
+   */
+  ensure(threadId, opts) {
+    if (!threadId || typeof threadId !== 'string') {
+      throw new Error('ThreadEngineRegistry.ensure: threadId required');
+    }
+    const existing = this.#instances.get(threadId);
+    if (existing && !existing.terminated) return existing;
+    const instance = this.#factory(threadId, opts);
+    if (!instance || typeof instance.query !== 'function') {
+      throw new Error(`ThreadEngineRegistry.ensure: factory did not return an EngineInstance for ${threadId}`);
+    }
+    this.#instances.set(threadId, instance);
+    return instance;
+  }
+
+  /**
+   * Set the current thread marker. Does not lazy-create — caller must
+   * ensure() if they want an instance for an unseen thread.
+   * @param {string} threadId
+   */
+  setCurrent(threadId) {
+    if (!threadId || typeof threadId !== 'string') {
+      throw new Error('ThreadEngineRegistry.setCurrent: threadId required');
+    }
+    this.#currentThreadId = threadId;
+  }
+
+  /**
+   * List all non-terminated instances. The order is insertion order.
+   * @returns {Array<import('./engine-instance.js').EngineInstance>}
+   */
+  listActive() {
+    const out = [];
+    for (const inst of this.#instances.values()) {
+      if (!inst.terminated) out.push(inst);
+    }
+    return out;
+  }
+
+  /**
+   * All instances including terminated ones (for inspection / tests).
+   * @returns {Array<import('./engine-instance.js').EngineInstance>}
+   */
+  listAll() {
+    return [...this.#instances.values()];
+  }
+
+  /**
+   * Terminate a single thread's instance. Safe on unknown threadId.
+   * @param {string} threadId
+   * @returns {boolean} true if a live instance was terminated
+   */
+  terminate(threadId) {
+    const inst = this.#instances.get(threadId);
+    if (!inst) return false;
+    if (inst.terminated) return false;
+    inst.terminate();
+    return true;
+  }
+
+  /**
+   * Terminate all instances. Used on session shutdown.
+   * @returns {number} count terminated
+   */
+  terminateAll() {
+    let n = 0;
+    for (const inst of this.#instances.values()) {
+      if (!inst.terminated) {
+        inst.terminate();
+        n += 1;
+      }
+    }
+    return n;
+  }
+
+  /**
+   * Remove a thread's instance from the map entirely. The registry
+   * will no longer return it from listAll / listActive. Primarily used
+   * after terminate() when the caller wants a full forget.
+   * @param {string} threadId
+   * @returns {boolean}
+   */
+  delete(threadId) {
+    const inst = this.#instances.get(threadId);
+    if (!inst) return false;
+    if (!inst.terminated) inst.terminate();
+    return this.#instances.delete(threadId);
+  }
+}
+
+/**
+ * Build a registry whose factory constructs full Engine instances using
+ * a shared dependency bag. This is the production entry point used by
+ * session.js:
+ *
+ *   const registry = createThreadEngineRegistry({
+ *     adapter, trace, config, conversationStore, memoryStore,
+ *     toolRegistry, skillManager, mcpManager, yeaftDir,
+ *   });
+ *   const inst = registry.ensure(threadId);
+ *   for await (const event of inst.query({ prompt })) { ... }
+ *
+ * @param {object} deps — shared session deps (see session.js §9)
+ * @returns {ThreadEngineRegistry}
+ */
+export function createThreadEngineRegistry(deps) {
+  return new ThreadEngineRegistry({
+    factory: (threadId, opts = {}) => createEngineInstance({
+      ...deps,
+      ...opts,
+      threadId,
+    }),
+  });
+}