@yeaft/webchat-agent 0.1.481 → 0.1.482

package/package.json

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

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,
+    }),
+  });
+}