@yeaft/webchat-agent 0.1.705 → 0.1.707

package/package.json

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

package/unify/archive/tool-results.js

@@ -151,7 +151,15 @@ export async function archiveToolResults({
   };
 }
 
-function formatSize(bytes) {
+/**
+ * Format a byte count as a short human-readable string ("1.5KB", "2.0MB").
+ * Exported so other size-aware helpers (tool-result truncation in the
+ * registry) format identically.
+ *
+ * @param {number} bytes
+ * @returns {string}
+ */
+export function formatSize(bytes) {
   if (bytes < 1024) return `${bytes}B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
   return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;

package/unify/engine.js

@@ -34,9 +34,11 @@ import { runStopHooks } from './stop-hooks.js';
 // the constant 'main'.
 const MAIN_THREAD_ID = 'main';
 import { pickEffort, parseEffortPrefix } from './effort.js';
-import { normalizeEffort } from './models.js';
+import { normalizeEffort, resolveContextWindow } from './models.js';
 import { attachRouterPlan, extractPriorPlan, stripMetaForWire } from './router/continuity.js';
 import { resolveThinking } from './router/thinking.js';
+import { approxTokens } from './memory/budget.js';
+import { truncateToolResultIfNeeded } from './tools/registry.js';
 import {
   TOOL_BATCH_SIZE,
   TURN_SUMMARY_THRESHOLD,
@@ -100,6 +102,64 @@ export function mapDebugMessage(m) {
   return out;
 }
 
+/**
+ * task-704b — estimate the total token cost of a system prompt + a
+ * messages array. Used by the pre-flight guard before adapter.stream()
+ * to decide whether to run an emergency archive sweep.
+ *
+ * Why estimate, not exact: a real tokenizer (tiktoken, claude-tokenizer)
+ * adds a heavy dep + per-turn cost for what is fundamentally a guard
+ * rail. `approxTokens` (char/4 with CJK weighting) is the same
+ * estimator the AMS budget code uses; it is monotonic in payload size
+ * and that is the only property the guard rail needs. False positives
+ * cost an unnecessary archive sweep (cheap); false negatives let a
+ * runaway request through (expensive — that is exactly the bug we are
+ * fixing).
+ *
+ * Multi-modal messages: `content` may be an array of content parts
+ * (Anthropic / OpenAI Responses shape). Text parts use approxTokens;
+ * image parts get a fixed 1024-token estimate — a rough average across
+ * vision pricing models. Exact pricing isn't the goal; "this is roughly
+ * how much of the window the message will consume" is.
+ *
+ * @param {string} system
+ * @param {Array<{role:string, content?:any, toolCalls?:Array}>} messages
+ * @returns {number}
+ */
+export function estimateMessagesTokens(system, messages) {
+  let total = approxTokens(typeof system === 'string' ? system : '');
+  if (!Array.isArray(messages)) return total;
+  for (const m of messages) {
+    if (!m) continue;
+    const c = m.content;
+    if (typeof c === 'string') {
+      total += approxTokens(c);
+    } else if (Array.isArray(c)) {
+      for (const part of c) {
+        if (!part) continue;
+        if (part.type === 'text') {
+          // Coerce defensively — a non-string `text` (number, Buffer,
+          // object) would otherwise throw inside approxTokens and abort
+          // the pre-flight estimate, defeating the guard rail.
+          total += approxTokens(typeof part.text === 'string' ? part.text : '');
+        } else if (part.type === 'image') {
+          total += 1024;
+        }
+        // Other multi-modal parts (audio etc.) — skip; not produced today.
+      }
+    }
+    if (Array.isArray(m.toolCalls)) {
+      for (const tc of m.toolCalls) {
+        try {
+          total += approxTokens(JSON.stringify(tc.input || {}));
+        } catch { /* circular — ignore */ }
+        total += approxTokens(typeof tc.name === 'string' ? tc.name : '');
+      }
+    }
+  }
+  return total;
+}
+
 // ─── Engine Events (superset of adapter events) ──────────────────
 
 /**
@@ -603,6 +663,11 @@ export class Engine {
       conversationStore: this.#conversationStore,
       adapter: this.#adapter,
       config: this.#config,
+      // task-704b: per-tool-result hard cap derives from this. Threaded
+      // from the live model (resolveModel(currentModel)) every turn so
+      // fallbackModel switches see the new window. Falls back to
+      // config.maxContextTokens, then 200K, in registry.js.
+      contextWindow: vpCtx?.contextWindow,
       // ViewImage (task-333b PR-B rev-3 P1-A): expose size cap + allowlist
       // via tool ctx so hosts can override via ~/.yeaft/config.json without
       // touching the tool impl.
@@ -617,6 +682,11 @@ export class Engine {
       inboundEnvelope: vpCtx?.inboundEnvelope,
       taskId: vpCtx?.taskId,
       taskMembers: vpCtx?.taskMembers,
+      // task-707: tool-callable end-turn signal. The engine threads this
+      // setter when constructing toolCtx so a tool (e.g. route_forward)
+      // can mark "after this batch, end the turn — do NOT call adapter
+      // again". Honored at the top of the tool-loop continuation.
+      requestEndTurn: vpCtx?.requestEndTurn,
       // Sub-agent plumbing — Agent tool needs these to spawn a child
       // Engine that inherits the parent's adapter / stores / toolset.
       parentEngineDeps: {
@@ -1115,6 +1185,13 @@ export class Engine {
     let currentModel = this.#config.model;
     let cumulativeInputTokens = 0;
     let cumulativeOutputTokens = 0;
+    // task-707: tool-callable end-turn signal. Tools (currently only
+    // `route_forward`) can set this via toolCtx.requestEndTurn(reason)
+    // to break out of the tool-loop after the current batch finishes
+    // — without invoking another adapter.stream(). Used to hand off
+    // control to other VPs cleanly. Reset to null at the top of every
+    // outer-loop iteration so the flag never carries across turns.
+    let endTurnRequested = null;
 
     while (true) {
       turnNumber++;
@@ -1152,6 +1229,17 @@ export class Engine {
         if (exchange?.rawResponse) rawResponse = exchange.rawResponse;
       };
 
+      // task-704b: resolve the live model's context window for this turn.
+      // Used by the per-tool-result cap (passed via toolCtx) and the
+      // pre-flight total-token guard inside the try-block. Hoisted out of
+      // the try so toolCtx (built after the adapter stream) can see it.
+      // Re-resolved every turn because fallbackModel switches change
+      // `currentModel` mid query() — the cap MUST track the model we're
+      // actually about to call. Single resolver in models.js owns the
+      // fallback ladder (registry → config → default) so engine.js and
+      // tools/registry.js can never disagree.
+      const currentContextWindow = resolveContextWindow(currentModel, this.#config);
+
       yield { type: 'turn_start', turnNumber };
 
       try {
@@ -1203,6 +1291,7 @@ export class Engine {
         // message_trace can fetch it on demand. The stub keeps the
         // OpenAI/Anthropic toolCallId pairing intact.
         let wireMessages = stripMetaForWire([...conversationMessages]);
+
         if (this.#yeaftDir && (this.#config?.archive?.toolResults !== false)) {
           try {
             const swept = await archiveToolResults({
@@ -1224,6 +1313,52 @@ export class Engine {
           } catch { /* best-effort */ }
         }
 
+        // task-704b: pre-flight total-token guard. Even with the per-tool
+        // cap (registry.js: 10% of contextWindow per result), N tool
+        // results plus history can still breach the wire limit before we
+        // ever call adapter.stream(). Estimate the total token cost; if
+        // it exceeds PREFLIGHT_RATIO of the live context window, run an
+        // emergency archive sweep with `turnAgeMin: 0` so even
+        // current-turn-but-not-this-call bulky results get stubbed. The
+        // normal sweep above only stubs results older than 5 user turns
+        // — that's the wrong cadence when the *current* turn already has
+        // 4 large grep results.
+        //
+        // PREFLIGHT_RATIO = 0.85 leaves ~15% of the window for the model's
+        // own output tokens + tools metadata + light future history.
+        // The estimator (`estimateMessagesTokens`) is approxTokens
+        // (char/4 with CJK weighting) — good enough for a guard rail; a
+        // real tokenizer would be exact but adds a heavy dep.
+        if (this.#yeaftDir && (this.#config?.archive?.toolResults !== false)) {
+          const PREFLIGHT_RATIO = 0.85;
+          const threshold = Math.floor(currentContextWindow * PREFLIGHT_RATIO);
+          const estimate = estimateMessagesTokens(systemPrompt, wireMessages);
+          if (estimate > threshold) {
+            try {
+              const sweep = await archiveToolResults({
+                root: `${this.#yeaftDir}/memory`,
+                scopeDir: 'user',
+                messages: wireMessages,
+                turnAgeMin: 0,
+                lengthMin: this.#config?.archive?.lengthMin ?? 2000,
+              });
+              wireMessages = sweep.nextMessages;
+              if (sweep.archivedCount > 0) {
+                for (let i = 0; i < conversationMessages.length; i += 1) {
+                  conversationMessages[i] = wireMessages[i];
+                }
+                this.#trace.log?.('preflight_sweep', {
+                  archivedCount: sweep.archivedCount,
+                  archivedBytes: sweep.archivedBytes,
+                  estimateBefore: estimate,
+                  threshold,
+                  contextWindow: currentContextWindow,
+                });
+              }
+            } catch { /* best-effort */ }
+          }
+        }
+
         // Stream from adapter
         for await (const event of this.#adapter.stream({
           model: currentModel,
@@ -1555,7 +1690,28 @@ export class Engine {
       }
 
       // Execute tool calls and feed results back
-      const toolCtx = this.#buildToolContext(signal, { router, senderVpId, inboundEnvelope, taskId, taskMembers, vpPersona });
+      // task-707: requestEndTurn is a per-batch closure that lets a tool
+      // signal "end this turn after the current batch — no adapter retry".
+      // We re-create the closure each iteration because endTurnRequested
+      // is a per-query local (reset implicitly at the top of #runQuery).
+      const toolCtx = this.#buildToolContext(signal, {
+        router,
+        senderVpId,
+        inboundEnvelope,
+        taskId,
+        taskMembers,
+        vpPersona,
+        contextWindow: currentContextWindow,
+        requestEndTurn: (reason) => {
+          // First call wins — preserve the kind/reason of the first tool
+          // that asked to end the turn. Late callers (a second
+          // route_forward in the same batch) keep dispatching but don't
+          // overwrite the recorded reason.
+          if (endTurnRequested == null) {
+            endTurnRequested = reason || { kind: 'tool_handoff' };
+          }
+        },
+      });
 
       // task-325a: track whether we aborted mid tool-loop so we can
       // break out of the outer while-loop cleanly once the current
@@ -1624,7 +1780,14 @@ export class Engine {
               output = await this.#toolRegistry.execute(tc.name, tc.input, toolCtx);
             } else {
               const tool = this.#tools.get(tc.name);
-              output = await tool.execute(tc.input, { signal });
+              const rawOutput = await tool.execute(tc.input, { signal });
+              // task-704b: legacy #tools branch must apply the same per-tool
+              // cap as ToolRegistry.execute. Otherwise a deployment using
+              // the legacy registration path bypasses the defense entirely.
+              output = truncateToolResultIfNeeded(rawOutput, {
+                contextWindow: currentContextWindow,
+                toolName: tc.name,
+              });
             }
             yield { type: 'tool_end', id: tc.id, name: tc.name, output, isError: false, threadId: this.currentThreadId };
           } catch (err) {
@@ -1692,6 +1855,31 @@ export class Engine {
         conversationMessages.push({ role: 'user', content: reminder });
       }
 
+      // task-707: tool-callable end-turn signal. If a tool in this batch
+      // called toolCtx.requestEndTurn(reason), break out of the outer
+      // while-loop now — DON'T call adapter.stream() again. The
+      // assistant(tool_use)+tool(tool_result) pairs are already in
+      // conversationMessages, so the next user-initiated turn sees a
+      // clean wire shape. Used by `route_forward` to hand off control
+      // to other VPs without continuing to generate.
+      //
+      // Order matters: this runs BEFORE T1 reflection (which would
+      // collapse the arc into a summary that's only valuable across
+      // multi-iteration tool loops) and BEFORE the abortedDuringTools
+      // check (so a clean handoff doesn't get reported as 'aborted').
+      if (endTurnRequested) {
+        const handoffDetail = typeof endTurnRequested === 'object'
+          ? endTurnRequested
+          : { kind: 'tool_handoff', reason: String(endTurnRequested) };
+        yield {
+          type: 'turn_end',
+          turnNumber,
+          stopReason: 'tool_handoff',
+          detail: handoffDetail,
+        };
+        break;
+      }
+
       // PR-L: T1 in-turn (synchronous) reflection. Fires exactly once per
       // query() lifetime, the moment queryToolCount crosses
       // TOOL_BATCH_SIZE (13). Generates a markdown reflection over the

package/unify/models.js

@@ -213,6 +213,43 @@ export function resolveModel(modelName) {
   return info ? { ...info } : null;
 }
 
+/**
+ * Default context window when neither the model registry nor the engine
+ * config has a value. 200K is a conservative middle-ground — most modern
+ * production models (Claude, GPT-5, Gemini) have ≥ 128K.
+ *
+ * Single source of truth: callers (engine.js pre-flight guard,
+ * tools/registry.js per-result cap) MUST use this constant or
+ * {@link resolveContextWindow} instead of hardcoding 200_000.
+ */
+export const DEFAULT_CONTEXT_WINDOW = 200_000;
+
+/**
+ * Resolve the live context window for a model, with an explicit fallback
+ * ladder:
+ *   1. MODEL_REGISTRY entry's `contextWindow` (most accurate)
+ *   2. caller-supplied config override (e.g. `config.maxContextTokens`)
+ *   3. {@link DEFAULT_CONTEXT_WINDOW}
+ *
+ * Used by the per-tool-result cap and the pre-flight token guard so the
+ * defense layers always see the same number, regardless of which seam
+ * resolves it first.
+ *
+ * @param {string} modelName
+ * @param {{ maxContextTokens?: number }} [config]
+ * @returns {number}
+ */
+export function resolveContextWindow(modelName, config) {
+  const info = resolveModel(modelName);
+  if (info && Number.isFinite(info.contextWindow) && info.contextWindow > 0) {
+    return info.contextWindow;
+  }
+  const cfg = config && Number.isFinite(config.maxContextTokens) && config.maxContextTokens > 0
+    ? config.maxContextTokens : null;
+  if (cfg !== null) return cfg;
+  return DEFAULT_CONTEXT_WINDOW;
+}
+
 /**
  * List all known models.
  *

package/unify/tools/registry.js

@@ -9,6 +9,73 @@
  * still carry a `modes` field, but the registry ignores it.
  */
 
+import { formatSize } from '../archive/tool-results.js';
+import { DEFAULT_CONTEXT_WINDOW } from '../models.js';
+
+/**
+ * Per-tool-result hard cap.
+ *
+ * A single tool can return megabytes (a grep over a large repo, a large
+ * file read, a paginated web fetch). If we forward that verbatim into the
+ * next LLM request the model returns LLMContextError ("context_length_exceeded")
+ * and the user sees a hard failure mid-turn. Cap at a fraction of the
+ * model's context window so even a runaway tool can't kill the request.
+ *
+ * Cap = max(MIN_CAP, floor(contextWindow * RATIO))
+ *   - RATIO = 10%: leaves 90% of context for system prompt, history, the
+ *     model's own output, and other tools called this turn. Generous in
+ *     absolute terms (25.6 KB on a 256 K window, ~20 K on a 200 K window),
+ *     plenty for a real tool result; small enough that 5 such results
+ *     still fit alongside everything else.
+ *   - MIN_CAP = 8 KB: sanity floor for tiny test fixtures (4 K context
+ *     models in tests would otherwise cap at 409 chars, defeating the
+ *     test's purpose). Real production models all have ≥ 32 K context, so
+ *     the floor never bites in practice.
+ *
+ * The truncation lands HERE (not in engine.js when pushing tool results
+ * into messages) so the UI's `tool_end` event, the exec log, AND the
+ * model all see the same truncated content. Truncating later would mean
+ * the user sees the full 2 MB output but the model gets a stub —
+ * confusing.
+ */
+const TOOL_RESULT_CAP_RATIO = 0.10;
+const TOOL_RESULT_MIN_CAP = 8 * 1024;
+
+/**
+ * Truncate a tool result if it exceeds the per-result cap. Non-string
+ * outputs are JSON-stringified first (matching what engine.js eventually
+ * pushes into `content`), then capped.
+ *
+ * Edge cases handled:
+ *   - `undefined` → `JSON.stringify(undefined)` returns `undefined`, not
+ *     a string, so we coerce to `'undefined'` and let the cap apply.
+ *   - circular refs / `JSON.stringify` throws → fall back to `String(...)`.
+ *
+ * @param {unknown} output
+ * @param {{ contextWindow?: number, toolName: string }} opts
+ * @returns {string}
+ */
+export function truncateToolResultIfNeeded(output, { contextWindow, toolName }) {
+  let text;
+  if (typeof output === 'string') {
+    text = output;
+  } else {
+    try {
+      const json = JSON.stringify(output);
+      text = typeof json === 'string' ? json : String(output);
+    } catch {
+      text = String(output);
+    }
+  }
+  const ctx = Number.isFinite(contextWindow) && contextWindow > 0
+    ? contextWindow : DEFAULT_CONTEXT_WINDOW;
+  const cap = Math.max(TOOL_RESULT_MIN_CAP, Math.floor(ctx * TOOL_RESULT_CAP_RATIO));
+  if (text.length <= cap) return text;
+  const head = text.slice(0, cap);
+  const marker = `\n\n[truncated: ${toolName} returned ${formatSize(text.length)}, capped at ${formatSize(cap)}; the model will not see the rest of this output]`;
+  return head + marker;
+}
+
 export class ToolRegistry {
   /** @type {Map<string, import('./types.js').ToolDef>} */
   #tools = new Map();
@@ -93,6 +160,12 @@ export class ToolRegistry {
 
   /**
    * Execute a tool by name.
+   *
+   * The result is passed through {@link truncateToolResultIfNeeded} so that
+   * a single tool can never blow the context window. The cap derives from
+   * `ctx.contextWindow` (the live model's window, threaded by engine.js);
+   * fall back to a 200K default for callers that don't supply it.
+   *
    * @param {string} name
    * @param {object} input
    * @param {import('./types.js').ToolContext} [ctx={}]
@@ -101,7 +174,11 @@ export class ToolRegistry {
   async execute(name, input, ctx = {}) {
     const tool = this.#tools.get(name);
     if (!tool) throw new Error(`Unknown tool: ${name}`);
-    return tool.execute(input, ctx);
+    const output = await tool.execute(input, ctx);
+    return truncateToolResultIfNeeded(output, {
+      contextWindow: ctx.contextWindow,
+      toolName: name,
+    });
   }
 
   /** Number of registered tools. */

package/unify/tools/route-forward.js

@@ -106,6 +106,24 @@ Returns JSON: { ok, dispatched?, error?, detail? }.`,
         detail: result.detail || null,
       });
     }
+    // task-707: hand off control. Successful forward means the originating
+    // turn should NOT continue generating — the target VPs are now in
+    // charge. Signal the engine to break the tool-loop after this batch.
+    // The structured payload feeds web-bridge's `group_handoff` UX event
+    // so the frontend can render "↪ 已转交给 @vp-x、@vp-y" without
+    // re-parsing a string.
+    if (typeof ctx.requestEndTurn === 'function') {
+      try {
+        ctx.requestEndTurn({
+          kind: 'route_forward',
+          fromVpId: senderVpId,
+          dispatched: result.dispatched.slice(),
+          broadcast: Boolean(result.report?.broadcast),
+          text,
+          reason: reason || null,
+        });
+      } catch { /* never block the tool path on a UX hint */ }
+    }
     return JSON.stringify({
       ok: true,
       dispatched: result.dispatched,

package/unify/tools/types.js

@@ -24,6 +24,26 @@
  * @property {(groupId: string) => string[]|null} [getGroupRoster]
  *   — R6: resolve a group's roster (used by TaskCreate / route_forward to
  *   validate `members` ⊆ roster without importing group-store directly).
+ * @property {number} [contextWindow] — current model's context window in
+ *   tokens (used by ToolRegistry.execute to cap a single tool result at a
+ *   fraction of the window so one runaway grep can't blow the wire).
+ * @property {(reason?: string|object) => void} [requestEndTurn]
+ *   — tool-callable signal that the current engine turn should end after
+ *   this batch of tool calls completes (no follow-up adapter.stream call).
+ *   Used by `route_forward` to hand off control to other VPs without
+ *   continuing to generate. The engine wires this when it builds toolCtx
+ *   and yields a `turn_end` event with `stopReason: 'tool_handoff'` and
+ *   the supplied reason as `detail`. `reason` may be a structured object
+ *   `{kind, ...}` so downstream observers (web-bridge) can render UI hints
+ *   (e.g. "↪ 已转交给 @vp-b") without re-parsing strings.
+ * @property {string} [senderVpId] — id of the VP whose turn is currently
+ *   running. Used by `route_forward` to stamp the forwarded message and
+ *   by the loop guard to key per-sender throttling.
+ * @property {object} [inboundEnvelope] — the envelope that triggered this
+ *   turn (groupId / msgId / causedBy chain). Threaded into route_forward
+ *   so causedBy chains extend correctly.
+ * @property {object} [router] — per-group router (createRouter() output)
+ *   for VP-to-VP forwarding. Set by the bridge when running inside a group.
  */
 
 /**