@yeaft/webchat-agent 0.1.502 → 0.1.504

package/package.json

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

package/unify/engine.js

@@ -19,7 +19,7 @@
 
 import { randomUUID } from 'crypto';
 import { buildSystemPrompt } from './prompts.js';
-import { LLMContextError } from './llm/adapter.js';
+import { LLMContextError, LLMAbortError } from './llm/adapter.js';
 import { recall } from './memory/recall.js';
 import { shouldConsolidate, consolidate } from './memory/consolidate.js';
 import { buildMemoryInjection } from './memory/layout.js';
@@ -94,6 +94,32 @@ export class Engine {
   /** @type {object|null} — Config override for internal tasks (recall, consolidation, dream) using fastModel */
   #fastConfig;
 
+  /**
+   * task-325a — abort state.
+   *
+   * The engine exposes a first-class abort surface: `engine.abort(reason)`
+   * aborts the currently running `query()` loop. Internally we keep:
+   *
+   *   • `#currentAbortCtrl` — the per-query AbortController created (or
+   *     reused from the caller's signal) when query() starts. Used to
+   *     propagate abort to the LLM adapter stream and to tool execution.
+   *   • `#abortReason`       — the reason string passed to abort(), surfaced
+   *     on the emitted `aborted` event so the UI can render a meaningful
+   *     stop banner (`user`, `timeout`, `thread_reset`, etc.).
+   *
+   * State machine convergence: when the signal fires, the loop catches the
+   * LLMAbortError (or a synthetic abort check) and yields exactly one pair
+   * of events — `{type:'aborted', reason}` followed by
+   * `{type:'turn_end', stopReason:'aborted'}` — then returns without
+   * persisting partial tool calls, consolidation, or stop-hook side-effects.
+   *
+   * @type {AbortController|null}
+   */
+  #currentAbortCtrl = null;
+
+  /** @type {string|null} */
+  #abortReason = null;
+
   /**
    * @param {{
    *   adapter: import('./llm/adapter.js').LLMAdapter,
@@ -139,6 +165,46 @@ export class Engine {
     this.#tools.set(tool.name, tool);
   }
 
+  /**
+   * task-325a — abort the currently running query().
+   *
+   * Idempotent and safe to call when no query is in flight (no-op).
+   * The abort is cooperative: the in-flight adapter stream receives the
+   * signal immediately (fetch aborts), the tool loop checks the signal
+   * between invocations, and the loop emits a typed `aborted` event
+   * before returning so the caller can distinguish "user stopped" from
+   * "LLM returned end_turn".
+   *
+   * @param {string} [reason='user'] — Human-tagged reason surfaced on the
+   *   emitted `aborted` event. Common values: `'user'`, `'timeout'`,
+   *   `'thread_reset'`, `'session_reset'`.
+   * @returns {boolean} true if an in-flight query was aborted, false if
+   *   nothing was running (no-op).
+   */
+  abort(reason = 'user') {
+    if (!this.#currentAbortCtrl) return false;
+    if (this.#currentAbortCtrl.signal.aborted) return false;
+    this.#abortReason = reason || 'user';
+    try {
+      this.#currentAbortCtrl.abort();
+    } catch {
+      // AbortController.abort never throws in practice, but swallow
+      // defensively so abort() never takes down the caller.
+    }
+    return true;
+  }
+
+  /**
+   * task-325a — whether there is an in-flight query that has NOT been
+   * aborted. Useful for callers that want to know "is this engine busy?"
+   * without racing on the signal.
+   * @returns {boolean}
+   */
+  get isRunning() {
+    return !!this.#currentAbortCtrl && !this.#currentAbortCtrl.signal.aborted;
+  }
+
+
   /**
    * Unregister a tool.
    *
@@ -370,6 +436,58 @@ export class Engine {
       return;
     }
 
+    // ─── task-325a: engine-owned AbortController ─────────────
+    // We create our own controller for this query run so `engine.abort()`
+    // can trigger cancellation without requiring the caller to hand in a
+    // signal. If the caller DID provide a signal, we mirror its state onto
+    // our controller (honouring both entry points). The linked signal
+    // forwarded to the adapter/tools is always `abortCtrl.signal`, so
+    // there is exactly one place that actually stops work in flight.
+    const abortCtrl = new AbortController();
+    this.#currentAbortCtrl = abortCtrl;
+    this.#abortReason = null;
+
+    const onExternalAbort = () => {
+      if (!abortCtrl.signal.aborted) {
+        // Tag the reason so the emitted `aborted` event reflects the
+        // external trigger. Callers that pass a signal without invoking
+        // engine.abort() get the neutral tag 'external'.
+        if (!this.#abortReason) this.#abortReason = 'external';
+        try { abortCtrl.abort(); } catch { /* ignore */ }
+      }
+    };
+    if (signal) {
+      if (signal.aborted) {
+        this.#abortReason = 'external';
+        try { abortCtrl.abort(); } catch { /* ignore */ }
+      } else {
+        signal.addEventListener('abort', onExternalAbort, { once: true });
+      }
+    }
+    // The signal passed down to adapter.stream() + tool execution.
+    const runSignal = abortCtrl.signal;
+
+    try {
+      yield* this.#runQuery({ prompt, messages, signal: runSignal });
+    } finally {
+      if (signal) {
+        try { signal.removeEventListener('abort', onExternalAbort); } catch { /* ignore */ }
+      }
+      // Clear current-run state so engine.isRunning flips back to false
+      // and a subsequent query() starts with a clean slate.
+      this.#currentAbortCtrl = null;
+      this.#abortReason = null;
+    }
+  }
+
+  /**
+   * Internal: the original query loop body. Split out of `query()` so the
+   * public method can own the per-run AbortController + abort lifecycle
+   * in a try/finally without indenting the whole loop.
+   * @private
+   */
+  async *#runQuery({ prompt, messages, signal }) {
+
     // ─── Pre-query: Memory Injection (task-287) + Compact Summary ──
     // New layout: always inject Memory Index + user-preferences + project
     // header excerpt. No per-turn fuzzy recall — LLM calls memory_search /
@@ -414,6 +532,16 @@ export class Engine {
       // non-retryable error, LLMContextError (after compact retry), or
       // caller abort. Keeping this comment so the removal is traceable.
 
+      // task-325a: check for user abort at the top of every turn so a
+      // signal that fires between turns (e.g. during tool execution in
+      // the previous iteration) cleanly ends the loop instead of
+      // launching another adapter stream.
+      if (signal?.aborted) {
+        yield { type: 'aborted', reason: this.#abortReason || 'external', turnNumber };
+        yield { type: 'turn_end', turnNumber, stopReason: 'aborted' };
+        break;
+      }
+
       const turnId = this.#trace.startTurn({
         traceId: this.#traceId,
         turnNumber,
@@ -491,6 +619,22 @@ export class Engine {
           stopReason: 'error',
         };
 
+        // ─── task-325a: abort short-circuit ────────────────
+        // If the adapter threw LLMAbortError, or the signal fired during
+        // stream() (fetch throws AbortError / DOMException), we converge
+        // the state machine on the 'aborted' terminal state — no retry,
+        // no fallback, no persistence. One `aborted` event + one
+        // `turn_end` with stopReason='aborted' and we're done.
+        const isAbort = err instanceof LLMAbortError
+          || err?.name === 'AbortError'
+          || err?.name === 'LLMAbortError'
+          || (signal?.aborted && /abort/i.test(err?.message || ''));
+        if (isAbort || signal?.aborted) {
+          yield { type: 'aborted', reason: this.#abortReason || 'external', turnNumber };
+          yield { type: 'turn_end', turnNumber, stopReason: 'aborted' };
+          break;
+        }
+
         // ─── LLMContextError → force compact → retry ──────
         if (err instanceof LLMContextError && this.#conversationStore && this.#memoryStore) {
           const consolidated = await this.#maybeConsolidate();
@@ -613,7 +757,21 @@ export class Engine {
       // Execute tool calls and feed results back
       const toolCtx = this.#buildToolContext(signal);
 
+      // task-325a: track whether we aborted mid tool-loop so we can
+      // break out of the outer while-loop cleanly once the current
+      // tool batch finishes reporting.
+      let abortedDuringTools = false;
+
       for (const tc of toolCalls) {
+        // task-325a: honour abort between tools. We don't cancel a tool
+        // that's already running (the signal is passed in, tools decide
+        // themselves whether to bail early), but we stop dispatching
+        // any remaining tools the moment abort fires.
+        if (signal?.aborted) {
+          abortedDuringTools = true;
+          break;
+        }
+
         const toolStartTime = Date.now();
 
         let output;
@@ -665,6 +823,15 @@ export class Engine {
         });
       }
 
+      // task-325a: if abort fired between tools, converge now — emit
+      // the typed `aborted` event + a final turn_end with stopReason
+      // 'aborted' instead of looping back to a new adapter call.
+      if (abortedDuringTools || signal?.aborted) {
+        yield { type: 'aborted', reason: this.#abortReason || 'external', turnNumber };
+        yield { type: 'turn_end', turnNumber, stopReason: 'aborted' };
+        break;
+      }
+
       yield { type: 'turn_end', turnNumber, stopReason: 'tool_use' };
 
       // Loop back to call adapter again with tool results

package/unify/web-bridge.js

@@ -243,6 +243,109 @@ const THREAD_MUTATING_TOOLS = new Set([
   'AttachThreadToTask',
 ]);
 
+/**
+ * task-325b — Working Status event stream.
+ *
+ * Surfaces Engine lifecycle events (emitted by 325a) as a single
+ * `thread_status` event for the frontend Working Status panel, plus
+ * `thread_list_snapshot` for cold-start / reconnect.
+ *
+ * Contract (aligned with designer spec):
+ *   thread_status   → { type: 'thread_status', threadId, state,
+ *                       startedAt?, completedAt?, toolName?, reason? }
+ *     state ∈ 'running' | 'idle' | 'aborted' | 'error'
+ *   thread_list_snapshot → { type: 'thread_list_snapshot', threads[],
+ *                            currentThreadId, serverTime }
+ *
+ * Red lines (per PM): do NOT mutate engine state; this layer is a pure
+ * observer + translator. Event names match designer doc verbatim.
+ */
+
+/** Map Engine event name → Working Status state string. */
+function engineEventToState(engineEventType) {
+  switch (engineEventType) {
+    case 'thread_started':   return 'running';
+    case 'thread_completed': return 'idle';
+    case 'thread_aborted':   return 'aborted';
+    case 'thread_error':     return 'error';
+    default:                 return null;
+  }
+}
+
+/**
+ * Build and broadcast a `thread_status` payload translated from a raw
+ * engine lifecycle event. The engine event shape (325a) is:
+ *   { type, threadId, startedAt?, completedAt?, toolName?, reason? }
+ * Unknown fields pass through untouched so future engine additions
+ * (e.g. `attempt`) flow to the UI without another bridge change.
+ *
+ * @param {object} ev — engine event
+ * @returns {boolean} true if a thread_status was emitted
+ */
+function emitThreadStatusFromEngineEvent(ev) {
+  if (!ev || typeof ev !== 'object') return false;
+  const state = engineEventToState(ev.type);
+  if (!state) return false;
+  const payload = { type: 'thread_status', threadId: ev.threadId, state };
+  if (ev.startedAt != null)   payload.startedAt   = ev.startedAt;
+  if (ev.completedAt != null) payload.completedAt = ev.completedAt;
+  if (ev.toolName)            payload.toolName    = ev.toolName;
+  if (ev.reason)              payload.reason      = ev.reason;
+  if (ev.error?.message)      payload.error       = ev.error.message;
+  sendUnifyEvent(payload);
+  return true;
+}
+
+/**
+ * task-325b: full-snapshot push distinct from `thread_list_updated`.
+ * Emits `thread_list_snapshot` — a complete state dump the client uses
+ * on page load / WebSocket reconnect to rebuild the Working Status panel
+ * without missing any in-flight thread.
+ *
+ * Snapshot includes per-thread `state` (idle / running / aborted) resolved
+ * from the engine registry's live inflight set. Threads the registry has
+ * no entry for default to 'idle'.
+ */
+function sendThreadListSnapshot() {
+  try {
+    const store = getThreadStore();
+    const registry = session?.engineRegistry || null;
+    const inflight = new Set(
+      typeof registry?.inflightThreadIds === 'function'
+        ? registry.inflightThreadIds()
+        : [],
+    );
+    const threads = store.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,
+      lastActivityAt: t.lastActivityAt || t.lastMessageAt || t.updatedAt || null,
+      unread: t.unread || 0,
+      preview: t.preview || '',
+      createdAt: t.createdAt,
+      updatedAt: t.updatedAt,
+      taskId: (typeof store.attachedTask === 'function')
+        ? (store.attachedTask(t.id) || null)
+        : null,
+      running: t.id === store.currentId,
+      state: inflight.has(t.id) ? 'running' : 'idle',
+    }));
+    sendUnifyEvent({
+      type: 'thread_list_snapshot',
+      threads,
+      currentThreadId: store.currentId,
+      serverTime: Date.now(),
+    });
+  } catch (err) {
+    console.warn('[Unify] sendThreadListSnapshot failed:', err?.message || err);
+  }
+}
+
 /**
  * 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
@@ -331,6 +434,23 @@ function forwardPipelineEvent(ev, ctx) {
  */
 function handleEngineEvent(event, threadId, hctx) {
   hctx.resetQueryTimer();
+
+  // task-325b: translate Engine lifecycle events into a single
+  // `thread_status` event for the frontend Working Status panel. These
+  // events are observer-only — they never mutate bridge state. The raw
+  // engine event is NOT forwarded further; the switch below handles
+  // anything the UI still needs.
+  if (event && (
+    event.type === 'thread_started' ||
+    event.type === 'thread_completed' ||
+    event.type === 'thread_aborted' ||
+    event.type === 'thread_error'
+  )) {
+    // Engine events carry their own threadId; fall back to envelope id.
+    emitThreadStatusFromEngineEvent({ ...event, threadId: event.threadId || threadId });
+    return;
+  }
+
   switch (event.type) {
     case 'text_delta':
       hctx.assistantTextParts.push(event.text);
@@ -562,6 +682,10 @@ export async function handleUnifyChat(msg) {
       // task-301 Part 2: initial thread snapshot so sidebar V2 renders
       // the real 'main' thread (and any restored threads) right away.
       sendThreadListUpdate();
+      // task-325b: full Working Status snapshot (superset with state +
+      // serverTime) so a freshly-connected client can restore inflight
+      // status without waiting for the next engine event.
+      sendThreadListSnapshot();
     }
 
     // ─── Per-call AbortController (task-320) ──
@@ -945,6 +1069,12 @@ export async function handleUnifyLoadHistory(msg) {
     tools: session.status.tools,
   });
   sendThreadListUpdate();
+  // task-325b: after a page refresh / reconnect the frontend needs the
+  // full Working Status snapshot to rebuild the panel (which thread is
+  // running, idle, aborted). `thread_list_updated` is intentionally a
+  // mutation-delta stream; `thread_list_snapshot` is the single
+  // authoritative "everything right now" payload.
+  sendThreadListSnapshot();
 
   const limit = msg.limit || 50;
   const messages = session.conversationStore.loadRecent(limit);
@@ -1030,6 +1160,9 @@ export async function resetUnifySession() {
     });
     // task-301 Part 2: re-push thread snapshot after session reset.
     sendThreadListUpdate();
+    // task-325b: also push the full Working Status snapshot so the UI
+    // doesn't retain stale "running" badges from the prior session.
+    sendThreadListSnapshot();
   } catch (err) {
     console.error('[Unify] Failed to re-initialize session after reset:', err.message);
   }