@yeaft/webchat-agent 0.1.705 → 0.1.706

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.705",
+  "version": "0.1.706",
   "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.
@@ -1152,6 +1217,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 +1279,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 +1301,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 +1678,7 @@ export class Engine {
       }
 
       // Execute tool calls and feed results back
-      const toolCtx = this.#buildToolContext(signal, { router, senderVpId, inboundEnvelope, taskId, taskMembers, vpPersona });
+      const toolCtx = this.#buildToolContext(signal, { router, senderVpId, inboundEnvelope, taskId, taskMembers, vpPersona, contextWindow: currentContextWindow });
 
       // 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 +1747,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) {

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/types.js

@@ -24,6 +24,9 @@
  * @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).
  */
 
 /**