@yeaft/webchat-agent 0.1.487 → 0.1.488

package/package.json

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

package/unify/pipeline/dispatcher.js

@@ -0,0 +1,373 @@
+/**
+ * pipeline/dispatcher.js — task-310 Phase 2 integration.
+ *
+ * Composes the three Phase-2 building blocks into a single linear pipeline:
+ *
+ *     unify_chat input
+ *            │
+ *            ▼
+ *    ┌──────────────┐   (task-307b)
+ *    │ InputQueue   │   persistent FIFO of pending user inputs
+ *    └──────┬───────┘
+ *           │ claim()                (transition pending → routing)
+ *           ▼
+ *    ┌──────────────┐   (task-309)
+ *    │ IntentClass. │   explicit @prefix / override / LLM / fallback
+ *    └──────┬───────┘
+ *           │ { action, targetThreadId, source, reason }
+ *           ▼
+ *    ┌──────────────┐   (task-308)
+ *    │ EngineReg.   │   ensure(threadId) → EngineInstance
+ *    └──────┬───────┘
+ *           │ inst.query({ prompt })
+ *           ▼
+ *    ┌──────────────┐
+ *    │ Engine events│   text_delta / tool_call / tool_end / …
+ *    └──────┬───────┘
+ *           │ each event tagged { ...ev, threadId } by EngineInstance
+ *           ▼
+ *      web-bridge forwards to `unify_output`
+ *
+ * ### Responsibilities
+ *
+ * This module OWNS the pipeline's control-flow decisions:
+ *
+ *   - `submit(input)` — enqueue + return the queue entry, non-streaming.
+ *     The caller either invokes `drain()` to actually dispatch, or lets a
+ *     future background worker pick it up. (We go with the simple "drain
+ *     on submit" default because the web-bridge is the sole producer and
+ *     cannot afford a stuck pending entry.)
+ *
+ *   - `dispatch(entry)` async-generator — runs one entry through router +
+ *     engine. Yields a stream of bridge events:
+ *
+ *       { type: 'input_queue_updated', pending, routing, … }
+ *       { type: 'routing_decision', entryId, action, targetThreadId, source, reason }
+ *       { type: 'thread_list_updated', threads, currentThreadId }  (on fork)
+ *       { type: 'engine_event', threadId, event }     // raw Engine event
+ *       { type: 'error', error: Error, retryable }
+ *
+ *     The web-bridge translates `engine_event`s into claude_output (the
+ *     existing code path) and forwards the pipeline-level events as
+ *     `unify_output.event`.
+ *
+ *   - `drain()` — convenience: claim + dispatch repeatedly until the queue
+ *     is empty. Web-bridge calls this after every submit().
+ *
+ * ### What this module does NOT own
+ *
+ *   - Persistence of messages (Engine / EngineInstance).
+ *   - ThreadStore mutations beyond incrementing currentId on 'switch' /
+ *     creating a fork thread on 'fork'.
+ *   - WebSocket framing (web-bridge does that).
+ *   - Abort semantics — each caller wraps `dispatch()` with its own
+ *     AbortController / signal (we forward it to EngineInstance.query).
+ *
+ * ### Concurrent reflow (spec point 5)
+ *
+ * Node's single-thread event loop means two concurrent `dispatch()` calls
+ * interleave at await points. Every yielded `engine_event` carries a
+ * `threadId` (EngineInstance re-tags), so the web-bridge can render events
+ * into the correct UI bubble. The dispatcher itself holds NO per-turn
+ * state on `this` — all state lives in the async generator's closure, so
+ * two pipelines can be in-flight at the same time without aliasing.
+ */
+
+import { MAIN_THREAD_ID } from '../threads/store.js';
+import { getTaskStore } from '../tools/task-tools.js';
+
+/**
+ * Per-entry transient metadata (messageId, override) lives here — a
+ * WeakMap keyed by the queue entry object so it is NEVER persisted to
+ * disk by InputQueueStore.#writeEntry. Entries are GC'd together with
+ * the entry once the queue drops the strong reference.
+ * @type {WeakMap<object, {messageId?: string, override?: {threadId: string}}>}
+ */
+const transientMeta = new WeakMap();
+
+/**
+ * @typedef {'continue'|'interrupt'|'fork'|'switch'} RouterAction
+ *
+ * @typedef {Object} SubmitOptions
+ * @property {string} [messageId]   — optional stable id for override()
+ * @property {{ threadId: string }} [override] — UI-side `@thread-name` hint
+ *   or user correction: skip router, go straight to `switch`/`continue`
+ *   targeting the given threadId.
+ *
+ * @typedef {Object} DispatcherDeps
+ * @property {import('../input-queue/store.js').InputQueueStore} inputQueue
+ * @property {import('../router/intent-classifier.js').IntentClassifier} router
+ * @property {import('../threads/engine-registry.js').ThreadEngineRegistry} engineRegistry
+ * @property {import('../threads/store.js').ThreadStore} threadStore
+ * @property {object} [trace]
+ */
+
+export class Dispatcher {
+  /** @type {DispatcherDeps} */
+  #deps;
+
+  constructor(deps) {
+    const { inputQueue, router, engineRegistry, threadStore } = deps || {};
+    if (!inputQueue || typeof inputQueue.enqueue !== 'function') {
+      throw new Error('Dispatcher: inputQueue is required');
+    }
+    if (!router || typeof router.classify !== 'function') {
+      throw new Error('Dispatcher: router is required');
+    }
+    if (!engineRegistry || typeof engineRegistry.ensure !== 'function') {
+      throw new Error('Dispatcher: engineRegistry is required');
+    }
+    if (!threadStore || typeof threadStore.list !== 'function') {
+      throw new Error('Dispatcher: threadStore is required');
+    }
+    this.#deps = deps;
+  }
+
+  /** Snapshot of queue counters for the UI, post-mutation. */
+  #queueSnapshot() {
+    const { inputQueue } = this.#deps;
+    const entries = inputQueue.list();
+    const counts = { pending: 0, routing: 0, dispatched: 0 };
+    for (const e of entries) {
+      if (counts[e.status] !== undefined) counts[e.status] += 1;
+    }
+    return {
+      type: 'input_queue_updated',
+      total: entries.length,
+      pending: counts.pending,
+      routing: counts.routing,
+      dispatched: counts.dispatched,
+      head: entries[0] ? { id: entries[0].id, status: entries[0].status, text: entries[0].text.slice(0, 80) } : null,
+    };
+  }
+
+  /**
+   * Enqueue a user input. Does NOT dispatch — caller invokes `drain()` or
+   * `dispatch(entry)` next. Separated so callers can atomically observe
+   * the `input_queue_updated` snapshot before the first router call fires.
+   *
+   * @param {string} text
+   * @param {SubmitOptions} [opts]
+   * @returns {{ entry: object, snapshot: object }}
+   */
+  submit(text, opts = {}) {
+    if (typeof text !== 'string' || !text.trim()) {
+      throw new Error('Dispatcher.submit: text required');
+    }
+    const { inputQueue } = this.#deps;
+    const entry = inputQueue.enqueue(text);
+    // Transient metadata lives in a WeakMap keyed by the entry — it is
+    // intentionally off the entry object itself so InputQueueStore's
+    // JSON.stringify write path does NOT leak `_messageId`/`_override`
+    // to disk. The WeakMap entry is dropped when the queue releases the
+    // entry reference (after markRouted removes it from memory).
+    transientMeta.set(entry, {
+      messageId: opts.messageId || undefined,
+      override: opts.override || undefined,
+    });
+    const snapshot = this.#queueSnapshot();
+    return { entry, snapshot };
+  }
+
+  /**
+   * Drain the queue: claim → dispatch in a loop until empty.
+   * Yields the union of every `dispatch()`'s events, interleaved naturally.
+   *
+   * @param {{ signal?: AbortSignal }} [opts]
+   * @yields {object} bridge events
+   */
+  async *drain(opts = {}) {
+    const { inputQueue } = this.#deps;
+    while (true) {
+      const head = inputQueue.peek();
+      if (!head) return;
+      if (head.status !== 'pending') return; // another dispatcher holds it
+      for await (const ev of this.dispatch(head, opts)) yield ev;
+    }
+  }
+
+  /**
+   * Dispatch one queue entry through router + engine. Transitions the
+   * entry: pending → routing (on claim) → dispatched (on success) or back
+   * to pending (on router exception, which is already guarded inside the
+   * classifier — so in practice this branch is very rare).
+   *
+   * @param {object} entry — from inputQueue.peek() or inputQueue.enqueue()
+   * @param {{ signal?: AbortSignal }} [opts]
+   * @yields {object} bridge events
+   */
+  async *dispatch(entry, opts = {}) {
+    const { inputQueue, router, engineRegistry, threadStore } = this.#deps;
+    const { signal } = opts;
+
+    // ── Step 1: claim (pending → routing) ──
+    // Note: we assume the caller already found `entry` as the head. A
+    // concurrent dispatcher would have claimed it first; we check for that.
+    let claimed = entry;
+    if (entry.status === 'pending') {
+      claimed = inputQueue.claim();
+      if (!claimed || claimed.id !== entry.id) {
+        // Another worker took it. Treat as a no-op success.
+        yield this.#queueSnapshot();
+        return;
+      }
+    }
+    yield this.#queueSnapshot();
+
+    // ── Step 2: gather router context ──
+    const currentThreadId = threadStore.currentId || MAIN_THREAD_ID;
+    const allThreads = threadStore.list().map(t => ({
+      id: t.id, name: t.name, goal: t.goal, status: t.status,
+    }));
+    const pendingTasks = this.#listPendingTasks();
+
+    // ── Step 3: classify (explicit override > classifier) ──
+    /** @type {import('../router/intent-classifier.js').RouterDecision} */
+    let decision;
+    const meta = transientMeta.get(entry) || {};
+    const ov = meta.override;
+    if (ov && typeof ov.threadId === 'string' && ov.threadId) {
+      const known = allThreads.some(t => t.id === ov.threadId) || ov.threadId === currentThreadId;
+      if (known) {
+        const action = ov.threadId === currentThreadId ? 'continue' : 'switch';
+        decision = {
+          action,
+          targetThreadId: ov.threadId,
+          reason: 'ui_override',
+          source: 'override',
+        };
+      }
+    }
+    if (!decision) {
+      try {
+        decision = await router.classify({
+          userMessage: claimed.text,
+          currentThreadId,
+          allThreads,
+          pendingTasks,
+          messageId: meta.messageId || undefined,
+        });
+      } catch (err) {
+        // Classifier is wrapped in its own try/catch already; reaching here
+        // means a truly unexpected failure. Degrade to continue.
+        decision = {
+          action: 'continue',
+          targetThreadId: currentThreadId,
+          reason: `dispatcher_classify_exception: ${err.message}`,
+          source: 'fallback',
+        };
+      }
+    }
+
+    yield {
+      type: 'routing_decision',
+      entryId: claimed.id,
+      action: decision.action,
+      targetThreadId: decision.targetThreadId,
+      source: decision.source || 'llm',
+      reason: decision.reason || '',
+    };
+
+    // ── Step 4: resolve target thread (fork may create a new one) ──
+    let targetThreadId = decision.targetThreadId;
+    if (decision.action === 'fork') {
+      const parentId = decision.targetThreadId || currentThreadId;
+      const forked = this.#spawnForkedThread(parentId, claimed.text);
+      if (forked) {
+        targetThreadId = forked.id;
+        yield this.#threadListSnapshot();
+      }
+    } else if (decision.action === 'switch') {
+      // Move the ThreadStore cursor so subsequent tool-originated events
+      // see the right thread for persistence hooks. Guard: not every
+      // ThreadStore implementation exposes has() (e.g. historic mocks).
+      const hasFn = typeof threadStore.has === 'function' ? (id) => threadStore.has(id) : () => true;
+      if (hasFn(targetThreadId)) {
+        try { threadStore.switch(targetThreadId); } catch { /* ignore */ }
+      }
+    }
+
+    // ── Step 5: dispatch to EngineInstance ──
+    let instance;
+    try {
+      instance = engineRegistry.ensure(targetThreadId);
+    } catch (err) {
+      inputQueue.markFailed(claimed.id, err);
+      yield this.#queueSnapshot();
+      yield { type: 'error', error: err, retryable: false };
+      return;
+    }
+
+    try {
+      for await (const event of instance.query({ prompt: claimed.text, signal })) {
+        yield { type: 'engine_event', threadId: targetThreadId, event };
+      }
+      inputQueue.markRouted(claimed.id, targetThreadId);
+      yield this.#queueSnapshot();
+    } catch (err) {
+      inputQueue.markFailed(claimed.id, err);
+      yield this.#queueSnapshot();
+      yield { type: 'error', error: err, retryable: true };
+    }
+  }
+
+  // ──────────────────────────────────────────────────────────────
+
+  #threadListSnapshot() {
+    const { threadStore } = this.#deps;
+    const threads = threadStore.list().map(t => ({
+      id: t.id,
+      name: t.name,
+      goal: t.goal || '',
+      parentThreadId: t.parentThreadId || null,
+      status: t.status,
+      archived: !!t.archived,
+      messageCount: t.messageCount || 0,
+      lastMessageAt: t.lastMessageAt || null,
+    }));
+    return {
+      type: 'thread_list_updated',
+      threads,
+      currentThreadId: threadStore.currentId,
+    };
+  }
+
+  #spawnForkedThread(parentId, promptText) {
+    const { threadStore } = this.#deps;
+    if (!threadStore.create) return null;
+    // Short label from first non-empty line, capped at 40 chars.
+    const firstLine = (promptText || '').split(/\r?\n/).find(l => l.trim()) || 'fork';
+    const name = firstLine.trim().slice(0, 40);
+    try {
+      return threadStore.create({ name, parentThreadId: parentId });
+    } catch {
+      return null;
+    }
+  }
+
+  #listPendingTasks() {
+    // Best-effort: the TaskStore is a singleton initialised in loadSession().
+    // If the store isn't available (e.g. unit tests without a session) we
+    // just return []. Never let a TaskStore exception break routing.
+    try {
+      const store = getTaskStore();
+      if (!store || typeof store.list !== 'function') return [];
+      const pending = store.list({ status: 'pending' }) || [];
+      return pending.map(t => ({
+        id: t.id,
+        title: t.title || '',
+        threadId: t.threadId || null,
+      }));
+    } catch { /* ignore */ }
+    return [];
+  }
+}
+
+/**
+ * Build a Dispatcher from session-level deps.
+ * @param {DispatcherDeps} deps
+ * @returns {Dispatcher}
+ */
+export function createDispatcher(deps) {
+  return new Dispatcher(deps);
+}

package/unify/session.js

@@ -27,7 +27,10 @@ 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 { getThreadStore } from './threads/store.js';
 import { createIntentClassifier } from './router/intent-classifier.js';
+import { initInputQueueStore } from './input-queue/store.js';
+import { createDispatcher } from './pipeline/dispatcher.js';
 import { join } from 'path';
 
 /**
@@ -193,6 +196,22 @@ export async function loadSession(options = {}) {
   // config as the engines so it can use primaryModel for classification.
   const router = createIntentClassifier({ adapter, trace, config });
 
+  // task-310 Phase 2 integration: wire InputQueue + Dispatcher so the
+  // web-bridge can submit `unify_chat` inputs through the unified pipeline
+  // (queue → router → engineRegistry → EngineInstance). In read-only mode
+  // the queue is memory-only (no disk writes).
+  const inputQueue = initInputQueueStore({
+    yeaftDir: config._readOnly ? null : yeaftDir,
+    force: true,
+  });
+  const dispatcher = createDispatcher({
+    inputQueue,
+    router,
+    engineRegistry,
+    threadStore: getThreadStore(),
+    trace,
+  });
+
   // ─── 10. Build session ─────────────────────────────────
   const status = {
     skills: skillManager.size,
@@ -224,6 +243,8 @@ export async function loadSession(options = {}) {
     engine,
     engineRegistry,
     router,
+    inputQueue,
+    dispatcher,
     adapter,
     config,
     conversationStore,

package/unify/web-bridge.js

@@ -116,6 +116,254 @@ const THREAD_MUTATING_TOOLS = new Set([
   'AttachThreadToTask',
 ]);
 
+/**
+ * task-310: parse a leading `@thread-<id>` or `@thread-<name>` marker on
+ * the user's input and return it as a dispatcher override. The marker
+ * itself is STRIPPED from the prompt before it reaches the engine —
+ * users don't want to see `@thread-foo` echoed back into their
+ * conversation.
+ *
+ * Thread IDs are `main` or `thr-<8 hex>`, so the match captures the id
+ * name AFTER the literal `@thread-`. The returned `override.threadId`
+ * is the fully-qualified thread id (e.g. `thread-main`, `thread-thr-abcd1234`).
+ *
+ * Returns { prompt, override? } where override = { threadId } if matched.
+ */
+export function parseThreadPrefix(text) {
+  if (!text || typeof text !== 'string') return { prompt: text || '', override: null };
+  // Capture the id portion after the literal `@thread-` prefix.
+  const m = text.match(/^\s*@thread-([A-Za-z0-9_-]+)\b\s*/);
+  if (!m) return { prompt: text, override: null };
+  const rest = text.slice(m[0].length);
+  // The captured id may already include a `thr-` sub-prefix (for non-main
+  // threads). For the canonical `main` thread, the override is the bare
+  // string `main`; for `thr-xxxxxxxx` threads, pass through verbatim.
+  const threadId = m[1];
+  return { prompt: rest || text, override: { threadId } };
+}
+
+/**
+ * Translate a pipeline event (from Dispatcher) into web-bridge outputs.
+ * Pipeline events are distinct from engine events — they carry queue /
+ * routing state for the UI. Engine events are unwrapped and forwarded
+ * through the existing sendUnifyOutput / sendUnifyEvent path.
+ *
+ * Returns whether the pipeline is complete (terminal error / no more).
+ */
+function forwardPipelineEvent(ev, ctx) {
+  if (!ev || typeof ev !== 'object') return false;
+  switch (ev.type) {
+    case 'input_queue_updated':
+      sendUnifyEvent({
+        type: 'input_queue_updated',
+        total: ev.total,
+        pending: ev.pending,
+        routing: ev.routing,
+        dispatched: ev.dispatched,
+        head: ev.head,
+      });
+      return false;
+    case 'routing_decision':
+      sendUnifyEvent({
+        type: 'routing_decision',
+        entryId: ev.entryId,
+        action: ev.action,
+        targetThreadId: ev.targetThreadId,
+        source: ev.source,
+        reason: ev.reason,
+      });
+      return false;
+    case 'thread_list_updated':
+      // Dispatcher built it already; just forward.
+      sendUnifyEvent({
+        type: 'thread_list_updated',
+        threads: ev.threads,
+        currentThreadId: ev.currentThreadId,
+      });
+      return false;
+    case 'engine_event':
+      ctx.onEngineEvent(ev.event, ev.threadId);
+      return false;
+    case 'error':
+      ctx.onError(ev.error);
+      return true;
+    default:
+      return false;
+  }
+}
+
+/**
+ * Handle a single engine event unwrapped from an `engine_event` pipeline
+ * envelope. Contains the event-type switch previously inlined in the
+ * streaming loop. `threadId` is propagated onto tool_use / tool_result
+ * blocks so the UI can render per-thread bubbles.
+ *
+ * @param {object} event — engine event (text_delta / tool_call / …)
+ * @param {string} threadId — owning thread id (from envelope)
+ * @param {{assistantTextParts:string[], resetQueryTimer:Function}} hctx
+ */
+function handleEngineEvent(event, threadId, hctx) {
+  hctx.resetQueryTimer();
+  switch (event.type) {
+    case 'text_delta':
+      hctx.assistantTextParts.push(event.text);
+      sendUnifyOutput({
+        type: 'assistant',
+        message: { content: [{ type: 'text', text: event.text }] },
+        threadId,
+      });
+      break;
+
+    case 'thinking_delta':
+      sendUnifyEvent({ type: 'thinking_delta', text: event.text, threadId });
+      break;
+
+    case 'tool_call':
+      // Finish any in-progress text streaming so UI shows typing dots
+      sendUnifyOutput({
+        type: 'assistant',
+        message: { content: [] },
+        threadId,
+      });
+      sendUnifyOutput({
+        type: 'assistant',
+        message: {
+          content: [{
+            type: 'tool_use',
+            id: event.id,
+            name: event.name,
+            input: event.input,
+          }],
+        },
+        threadId: event.threadId || threadId,
+      });
+      break;
+
+    case 'tool_start':
+      sendUnifyEvent({
+        type: 'tool_start',
+        id: event.id,
+        name: event.name,
+        threadId: event.threadId || threadId,
+      });
+      break;
+
+    case 'tool_end':
+      sendUnifyOutput({
+        type: 'user',
+        tool_use_result: [{
+          type: 'tool_result',
+          tool_use_id: event.id,
+          content: event.output || '',
+          is_error: event.isError || false,
+        }],
+        threadId: event.threadId || threadId,
+      });
+      if (THREAD_MUTATING_TOOLS.has(event.name)) {
+        sendThreadListUpdate();
+      }
+      break;
+
+    case 'turn_start':
+    case 'turn_end':
+    case 'stop':
+      // No UI action needed; outer loop sends the final result.
+      break;
+
+    case 'usage':
+      sendUnifyEvent({
+        type: 'context_usage',
+        inputTokens: event.inputTokens,
+        outputTokens: event.outputTokens,
+        threadId,
+      });
+      break;
+
+    case 'recall':
+      sendUnifyEvent({
+        type: 'recall',
+        entryCount: event.entryCount,
+        cached: event.cached,
+        threadId,
+      });
+      break;
+
+    case 'consolidate':
+      // Engine compressed the context — clear our accumulated history.
+      conversationMessages = [];
+      sendUnifyEvent({
+        type: 'consolidate',
+        archivedCount: event.archivedCount,
+        extractedCount: event.extractedCount,
+        threadId,
+      });
+      break;
+
+    case 'fallback':
+      sendUnifyEvent({
+        type: 'fallback',
+        from: event.from,
+        to: event.to,
+        reason: event.reason,
+        threadId,
+      });
+      break;
+
+    case 'debug_turn':
+      sendUnifyEvent({
+        type: 'debug_turn',
+        turnNumber: event.turnNumber,
+        model: event.model,
+        systemPrompt: event.systemPrompt,
+        messages: event.messages,
+        response: event.response,
+        toolCalls: event.toolCalls,
+        usage: event.usage,
+        latencyMs: event.latencyMs,
+        ttfbMs: event.ttfbMs,
+        stopReason: event.stopReason,
+        threadId,
+      });
+      break;
+
+    case 'error': {
+      const errMsg = event.error?.message || 'Unknown error';
+      // Filter permission errors: show friendly one-time diagnostic
+      // instead of raw error. Subsequent permission errors are suppressed
+      // — the user already saw the actionable message once.
+      if (isPermissionErrorMsg(errMsg)) {
+        if (!_permissionDiagnosticSent) {
+          _permissionDiagnosticSent = true;
+          sendUnifyOutput({
+            type: 'assistant',
+            message: {
+              content: [{
+                type: 'text',
+                text: '⚠️ Cannot write to ~/.yeaft/ directory — some features (memory, history) are unavailable. Please check directory permissions: `chmod -R u+rw ~/.yeaft/`',
+              }],
+            },
+            threadId,
+          });
+        }
+        // Don't show subsequent permission errors.
+      } else {
+        sendUnifyOutput({
+          type: 'assistant',
+          message: {
+            content: [{ type: 'text', text: `⚠️ Error: ${errMsg}` }],
+          },
+          threadId,
+        });
+      }
+      break;
+    }
+
+    default:
+      // Silently consume unknown events.
+      break;
+  }
+}
+
 /**
  * Handle a unify_chat message from the web UI.
  *
@@ -193,192 +441,44 @@ export async function handleUnifyChat(msg) {
     // ─── Collect assistant response for conversation history ──
     let assistantTextParts = [];
 
-    // ─── Stream Engine events → claude_output format ──
-    for await (const event of session.engine.query({
-      prompt,
-      messages: conversationMessages,
-      signal: currentAbort.signal,
-    })) {
-      // Reset timeout on every event — activity means the query is alive
-      resetQueryTimer();
-      switch (event.type) {
-        // ── Text streaming ──
-        case 'text_delta':
-          assistantTextParts.push(event.text);
-          sendUnifyOutput({
-            type: 'assistant',
-            message: {
-              content: [{ type: 'text', text: event.text }],
-            },
-          });
-          break;
-
-        // ── Thinking streaming (extended thinking) ──
-        case 'thinking_delta':
-          // Currently not rendered in UI, but forward for future use
-          sendUnifyEvent({ type: 'thinking_delta', text: event.text });
-          break;
+    // task-310: route via Dispatcher pipeline (queue → router → registry →
+    // EngineInstance). The input is enqueued first so the UI observes the
+    // `input_queue_updated` snapshot before the router runs. An explicit
+    // `@thread-xxx` prefix on the message or an `override` field on the
+    // `unify_chat` payload becomes a dispatcher override — skipping the LLM.
+    const { prompt: cleanedPrompt, override: prefixOverride } = parseThreadPrefix(prompt);
+    const override = msg.override && typeof msg.override === 'object' && msg.override.threadId
+      ? msg.override
+      : prefixOverride;
+
+    const { entry } = session.dispatcher.submit(cleanedPrompt, {
+      messageId: msg.messageId,
+      override: override || undefined,
+    });
+    sendUnifyEvent({
+      type: 'input_queue_updated',
+      total: 1,
+      pending: 1,
+      routing: 0,
+      dispatched: 0,
+      head: { id: entry.id, status: entry.status, text: entry.text.slice(0, 80) },
+    });
 
-        // ── Tool call announced by LLM ──
-        case 'tool_call':
-          // Finish any in-progress text streaming so UI shows typing dots
-          sendUnifyOutput({
-            type: 'assistant',
-            message: { content: [] },
-          });
-          // Send tool_use block
-          sendUnifyOutput({
-            type: 'assistant',
-            message: {
-              content: [{
-                type: 'tool_use',
-                id: event.id,
-                name: event.name,
-                input: event.input,
-              }],
-            },
-            threadId: event.threadId,
-          });
-          break;
-
-        // ── Tool execution started ──
-        case 'tool_start':
-          // Tool is running — the UI already shows it from tool_use block above.
-          // Forward threadId so the UI can group tool activity by thread (Phase 1).
-          sendUnifyEvent({ type: 'tool_start', id: event.id, name: event.name, threadId: event.threadId });
-          break;
-
-        // ── Tool execution completed ──
-        case 'tool_end':
-          // Send tool_result as a user message (matches Claude CLI format)
-          sendUnifyOutput({
-            type: 'user',
-            tool_use_result: [{
-              type: 'tool_result',
-              tool_use_id: event.id,
-              content: event.output || '',
-              is_error: event.isError || false,
-            }],
-            threadId: event.threadId,
-          });
-          // task-301 Part 2: if this tool mutates ThreadStore, push a
-          // fresh snapshot to the sidebar immediately.
-          if (THREAD_MUTATING_TOOLS.has(event.name)) {
-            sendThreadListUpdate();
-          }
-          break;
-
-        // ── Turn boundaries ──
-        case 'turn_start':
-          // No UI action needed
-          break;
-
-        case 'turn_end':
-          // Don't send result/done here — wait for the outermost loop to finish
-          break;
-
-        // ── Token usage ──
-        case 'usage':
-          sendUnifyEvent({
-            type: 'context_usage',
-            inputTokens: event.inputTokens,
-            outputTokens: event.outputTokens,
-          });
-          break;
-
-        // ── Stop reason from LLM ──
-        case 'stop':
-          // Intermediate signal — final done is sent after the loop
-          break;
-
-        // ── Memory recall ──
-        case 'recall':
-          sendUnifyEvent({
-            type: 'recall',
-            entryCount: event.entryCount,
-            cached: event.cached,
-          });
-          break;
-
-        // ── Context consolidation ──
-        case 'consolidate':
-          // Engine has compressed the context — clear our accumulated history.
-          // The engine's compactSummary will provide context on next query.
-          conversationMessages = [];
-          sendUnifyEvent({
-            type: 'consolidate',
-            archivedCount: event.archivedCount,
-            extractedCount: event.extractedCount,
-          });
-          break;
-
-        // ── Model fallback ──
-        case 'fallback':
-          sendUnifyEvent({
-            type: 'fallback',
-            from: event.from,
-            to: event.to,
-            reason: event.reason,
-          });
-          break;
-
-        // ── Debug turn data for web debug panel ──
-        case 'debug_turn':
-          sendUnifyEvent({
-            type: 'debug_turn',
-            turnNumber: event.turnNumber,
-            model: event.model,
-            systemPrompt: event.systemPrompt,
-            messages: event.messages,
-            response: event.response,
-            toolCalls: event.toolCalls,
-            usage: event.usage,
-            latencyMs: event.latencyMs,
-            ttfbMs: event.ttfbMs,
-            stopReason: event.stopReason,
-          });
-          break;
-
-        // ── Errors ──
-        case 'error': {
-          const errMsg = event.error?.message || 'Unknown error';
-          // Filter permission errors: show friendly one-time diagnostic instead of raw error
-          if (isPermissionErrorMsg(errMsg)) {
-            if (!_permissionDiagnosticSent) {
-              _permissionDiagnosticSent = true;
-              sendUnifyOutput({
-                type: 'assistant',
-                message: {
-                  content: [{
-                    type: 'text',
-                    text: '⚠️ Cannot write to ~/.yeaft/ directory — some features (memory, history) are unavailable. Please check directory permissions: `chmod -R u+rw ~/.yeaft/`',
-                  }],
-                },
-              });
-            }
-            // Don't show subsequent permission errors
-          } else {
-            sendUnifyOutput({
-              type: 'assistant',
-              message: {
-                content: [{
-                  type: 'text',
-                  text: `⚠️ Error: ${errMsg}`,
-                }],
-              },
-            });
-          }
-          break;
-        }
+    const pipelineCtx = {
+      onEngineEvent: (event, threadId) => handleEngineEvent(event, threadId, {
+        assistantTextParts,
+        resetQueryTimer,
+      }),
+      onError: (err) => { throw err; },
+    };
 
-        default:
-          // Silently consume unknown events
-          break;
-      }
+    for await (const pev of session.dispatcher.drain({ signal: currentAbort.signal })) {
+      resetQueryTimer();
+      forwardPipelineEvent(pev, pipelineCtx);
     }
 
     // ─── Query complete — accumulate messages for context continuity ──
-    conversationMessages.push({ role: 'user', content: prompt });
+    conversationMessages.push({ role: 'user', content: cleanedPrompt });
 
     const fullText = assistantTextParts.join('');
     if (fullText) {