@animalabs/agent-framework 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "repository": {
     "type": "git",
@@ -47,7 +47,7 @@
   "license": "MIT",
   "dependencies": {
     "@animalabs/chronicle": "^0.4.0",
-    "@animalabs/context-manager": "^0.11.0",
+    "@animalabs/context-manager": "^0.12.0",
     "@animalabs/membrane": "^0.5.78",
     "chokidar": "^4.0.3",
     "discord.js": "^14.25.1",

package/src/agent.ts

@@ -2,6 +2,7 @@ import type { Membrane, NormalizedMessage, NormalizedRequest, ContentBlock, Yiel
 import { isAbortedResponse } from '@animalabs/membrane';
 import { createHash } from 'node:crypto';
 import type { CacheWireReceipt, KvUnifiedRequestHooks } from './kv-unified-wire.js';
+import { ToolResultGuard, TOOL_RESULT_GUARD_NOTICE } from './tool-result-guard.js';
 import {
   toolResultDataToHistoryString,
   truncateForHistory,
@@ -82,6 +83,7 @@ export class Agent {
   readonly thinking: AgentConfig['thinking'];
   /** Refusal auto-rewind policy (see AgentConfig.refusalHandling). */
   readonly refusalHandling: AgentConfig['refusalHandling'];
+  readonly toolResultGuard: ToolResultGuard;
   /** Prose delivery mode (see AgentConfig.proseRouting). Default 'locus'. */
   readonly proseRouting: 'locus' | 'explicit' | 'hybrid' | 'disabled';
   /** Exact whole-response known-tool wrapper containment (default off). */
@@ -143,6 +145,7 @@ export class Agent {
     this.temperature = config.temperature;
     this.thinking = config.thinking;
     this.refusalHandling = config.refusalHandling;
+    this.toolResultGuard = new ToolResultGuard(config.name, contextManager, config.toolResultGuard);
     this.proseRouting = config.proseRouting ?? 'locus';
     this.toolWrapperProseGuard = config.toolWrapperProseGuard ?? false;
     this.cacheTtl = config.cacheTtl ?? '1h';
@@ -225,6 +228,20 @@ export class Agent {
     return { maxTokens: this.contextBudgetTokens, reserveForResponse: this.maxTokens };
   }
 
+  /** Compile budget with the tool-result guard's reservation applied. While
+   * a batch is pending the strategy selects against short placeholders, but
+   * prepareRequest substitutes the originals on the wire; reserve their real
+   * cost so the final request still fits (a budget restart that recompiles
+   * small must not re-inflate past the same window). */
+  private compileBudget(budget?: TokenBudget): TokenBudget | undefined {
+    const resolved = this.resolveBudget(budget);
+    const reserve = this.toolResultGuard.pendingWireReserveTokens;
+    if (reserve === 0) return resolved;
+    // Mirrors ContextManager.compile's own default when no budget is set.
+    const base = resolved ?? { maxTokens: 100_000, reserveForResponse: 4_000 };
+    return { ...base, reserveForResponse: base.reserveForResponse + reserve };
+  }
+
   /** Structural compatibility keeps lightweight test/host ContextManager
    * doubles working while making the new capability optional at runtime. */
   private getHotContextSettings(): HotContextSettingsStatus | null {
@@ -522,8 +539,50 @@ export class Agent {
     this.updateHotContextSettings({ preparedWindowTokens: null });
   }
 
+  /**
+   * RFC-006 consumed watermark: the newest stored message at the last compile
+   * of a model request, per branch. Everything above it has never been in a
+   * request and may still be replaced or withdrawn in place by its sender.
+   */
+  private consumedWatermark: { branch: string; sequence: number } | null = null;
+
+  getConsumedWatermark(): { branch: string; sequence: number } | null {
+    return this.consumedWatermark;
+  }
+
+  /** Mark everything currently stored as consumed (boot, branch switch). */
+  markContextConsumed(): void {
+    // Tolerates partial context-manager doubles (tests build Agents over
+    // stubs): without a watermark nothing is ever treated as unread.
+    this.consumedWatermark = this.pendingWatermark();
+  }
+
+  /** The watermark a successful compile will establish (taken before, applied after). */
+  private pendingWatermark(): { branch: string; sequence: number } | null {
+    const cm = this.contextManager as Partial<ContextManager>;
+    try {
+      if (typeof cm.currentBranch !== 'function' || typeof cm.getAllMessages !== 'function') return null;
+      // The chronicle head, not this slot's last message: a compile reads
+      // everything stored on the branch so far, including messages merged in
+      // from another slot (the subconscious reads the residents' shared slot).
+      const store = typeof cm.getStore === 'function' ? cm.getStore() as { currentSequence?: () => number } : undefined;
+      let sequence = typeof store?.currentSequence === 'function' ? store.currentSequence() : undefined;
+      if (sequence === undefined) {
+        const count = typeof cm.getMessageCount === 'function' ? cm.getMessageCount() : cm.getAllMessages().length;
+        sequence = count > 0 ? cm.getAllMessages().at(-1)?.sequence ?? 0 : 0;
+      }
+      return { branch: cm.currentBranch().name, sequence };
+    } catch {
+      return null;
+    }
+  }
+
   async compileContext(budget?: TokenBudget): Promise<CompileResult> {
-    const result = await this.contextManager.compile(this.resolveBudget(budget));
+    // RFC-006 §3.3: consumption is determined at assembly — a compile that
+    // fails assembled nothing, so the watermark moves only on success.
+    const watermark = this.pendingWatermark();
+    const result = await this.contextManager.compile(this.compileBudget(budget));
+    if (watermark) this.consumedWatermark = watermark;
     if (!budget) this.settleRuntimeSettingsTransition();
     return result;
   }
@@ -538,9 +597,11 @@ export class Agent {
     injections?: ContextInjection[],
     opts?: { kvUnifiedImmutablePrefixHash?: string },
   ): Promise<CompileResult> {
+    const watermark = this.pendingWatermark();
     const result = await this.contextManager.compile(
-      this.resolveBudget(budget), injections, opts as never,
+      this.compileBudget(budget), injections, opts as never,
     );
+    if (watermark) this.consumedWatermark = watermark;
     if (!budget) this.settleRuntimeSettingsTransition();
     return result;
   }
@@ -579,20 +640,33 @@ export class Agent {
       throw new Error(`Agent ${this.name} is waiting for tool results`);
     }
 
+    this.toolResultGuard.flushUnrecorded();
+
     // Filter tools to only allowed ones
     const tools = availableTools.filter((t) => this.canUseTool(t.name));
 
+    // The direct Agent API uses the same admission rules as framework-driven
+    // streams. Stage before compiling so compression only sees placeholders.
+    const guardedResults = this._state.status === 'ready' && this.toolResultGuard.enabled;
+    if (guardedResults && this._state.status === 'ready') {
+      const content = this.buildToolResultMessages(this._state.toolResults)[0].content;
+      const wireResults = content.flatMap((block) => block.type === 'tool_result'
+        // buildToolResultMessages serializes every payload to a string.
+        ? [{ toolUseId: block.toolUseId, content: block.content as string, isError: block.isError }] : []);
+      this.toolResultGuard.storeResults(content, wireResults, this._state.toolResults);
+    }
+
     // Compile context (with optional injections)
     const { messages, systemInjections } = await this.compileWithInjections(budget, injections);
 
     // If we have pending tool results, add them
-    if (this._state.status === 'ready') {
+    if (this._state.status === 'ready' && !guardedResults) {
       const toolResultMessages = this.buildToolResultMessages(this._state.toolResults);
       messages.push(...toolResultMessages);
     }
 
     const request: NormalizedRequest = {
-      messages,
+      messages: this.toolResultGuard.prepareRequest(messages, true),
       system: this.buildSystemPrompt(systemInjections),
       config: {
         model: this.model,
@@ -648,6 +722,7 @@ export class Agent {
     } catch (error) {
       // On error, go back to idle
       this._state = { status: 'idle' };
+      this.toolResultGuard.recovering = false;
       throw error;
     }
   }
@@ -773,7 +848,7 @@ export class Agent {
     }
 
     return {
-      messages,
+      messages: this.toolResultGuard.prepareRequest(messages),
       system: this.buildSystemPrompt(systemInjections),
       config: {
         model: this.model,
@@ -804,6 +879,10 @@ export class Agent {
       throw new Error(`Agent ${this.name} cannot start stream in state ${this._state.status}`);
     }
 
+    // Retry accepted history edits before assembling a real request. Pure
+    // preview/compile entry points must not perform these writes.
+    this.toolResultGuard.flushUnrecorded();
+
     // A new activation supersedes every receipt flight the previous one left
     // open. Membrane fires the kv-unified wire receipt per provider attempt,
     // BEFORE the adapter call; only that attempt's usage event settles it.
@@ -830,6 +909,7 @@ export class Agent {
     this.lastStreamOutputTokens = 0;
 
     const request = await this.buildActivationRequest(availableTools, injections, budget);
+    request.messages = this.toolResultGuard.prepareRequest(request.messages, true);
 
     const receiptAware = (this.contextManager as unknown as { getStrategy?: () => unknown })
       .getStrategy?.() as {
@@ -854,6 +934,7 @@ export class Agent {
       };
     }
 
+    const agent = this;
     const stream = this.membrane.streamYielding(request, {
       emitTokens: true,
       emitBlocks: false,
@@ -863,7 +944,13 @@ export class Agent {
       // (cache-warm), where a framework-level requeue would recompile and
       // land a different window. The framework's driveStream handles the
       // resulting `retrying` event by discarding the abandoned attempt.
-      ...(this.refusalHandling?.retries ? { refusalRetries: this.refusalHandling.retries } : {}),
+      // Membrane reads this per physical round, including after settings
+      // tools run. A guarded result must reach the host on its FIRST refusal;
+      // never spend retries resubmitting unchanged guarded content.
+      get refusalRetries() {
+        return agent.toolResultGuard.hasSubmittedPending || agent.toolResultGuard.recovering
+          ? 0 : agent.refusalHandling?.retries ?? 0;
+      },
     });
 
     this._state = { status: 'streaming', stream };
@@ -1041,9 +1128,32 @@ export class Agent {
     request: NormalizedRequest,
     signal?: AbortSignal
   ): Promise<InferenceResult> {
-    const response = await this.membrane.stream(request, { signal });
+    let response = await this.membrane.stream(request, { signal });
+    // Usage of a refused attempt abandoned by the guard; it was billed and
+    // is added to the retry's usage below rather than overwritten.
+    let abandonedUsage: { inputTokens: number; outputTokens: number } | undefined;
+    if (!isAbortedResponse(response) && response.stopReason === 'refusal') {
+      // A staged batch never on the wire cannot have caused the refusal.
+      this.toolResultGuard.settleUnsubmitted('unknown');
+      const ids = this.toolResultGuard.withhold('unknown');
+      if (ids) {
+        abandonedUsage = response.usage;
+        const withheld = new Set(ids);
+        request = { ...request, messages: request.messages.map((message) => ({
+          ...message, content: message.content.map((block) => block.type === 'tool_result' && withheld.has(block.toolUseId)
+            ? { type: 'tool_result', toolUseId: block.toolUseId, content: TOOL_RESULT_GUARD_NOTICE, isError: block.isError } : block),
+        })) };
+        response = await this.membrane.stream(request, { signal });
+      }
+    }
 
     if (isAbortedResponse(response)) {
+      // Interrupted before a clean response: settle, never leave pending.
+      try {
+        this.toolResultGuard.abandon('aborted');
+      } catch (error) {
+        console.error(`[tool-result-guard] agent=${this.name} failed to record aborted batch:`, error);
+      }
       const partialContent = response.partialContent ?? [];
       const { toolCalls, speechContent } = this.extractToolCallsAndSpeech(partialContent);
       return {
@@ -1056,16 +1166,24 @@ export class Agent {
       };
     }
 
-    const { toolCalls, speechContent } = this.extractToolCallsAndSpeech(response.content);
+    const guardedRefusal = response.stopReason === 'refusal' && this.toolResultGuard.recovering;
+    if (response.stopReason !== 'refusal') this.toolResultGuard.accept();
+    this.toolResultGuard.recovering = false;
+    const content = guardedRefusal ? [] : response.content;
+    const { toolCalls, speechContent } = this.extractToolCallsAndSpeech(content);
 
     // Add assistant response to context
-    this.contextManager.addMessage(this.name, response.content);
+    if (!guardedRefusal) this.contextManager.addMessage(this.name, content);
 
     return {
       toolCalls,
       speechContent,
       raw: response.raw,
-      usage: response.usage,
+      usage: abandonedUsage && response.usage ? {
+        ...response.usage,
+        inputTokens: response.usage.inputTokens + abandonedUsage.inputTokens,
+        outputTokens: response.usage.outputTokens + abandonedUsage.outputTokens,
+      } : response.usage,
       stopReason: response.stopReason,
     };
   }

package/src/api/types.ts

@@ -369,6 +369,8 @@ export type ApiEventType =
   | 'module:added'
   | 'module:removed'
   | 'message:added'
+  | 'message:removed'
+  | 'mcpl:coalescing'
   // Server-specific events
   | 'connected'
   | 'speech'

package/src/code-execution/py-runner.ts

@@ -77,12 +77,24 @@ const DEFAULT_SCRIPT_TIMEOUT_MS = 600_000;
 const DEFAULT_IDLE_RECLAIM_MS = 300_000;
 const CANCEL_GRACE_MS = 10_000;
 
+/** The longest delay Node's timers honour (~24.8 days); a longer one fires after ~1 ms. */
+export const MAX_TIMER_MS = 2_147_483_647;
+
+/** A time limit for a message: "45s", "10 min", "2.5 h". */
+export function formatLimit(ms: number): string {
+  if (ms < 120_000) return `${Math.round(ms / 1000)}s`;
+  if (ms < 7_200_000) return `${Math.round(ms / 6_000) / 10} min`;
+  return `${Math.round(ms / 360_000) / 10} h`;
+}
+
 interface PendingExec {
   id: string;
   resolve: (result: ExecResult) => void;
   deadlineTimer: ReturnType<typeof setTimeout> | null;
   killTimer: ReturnType<typeof setTimeout> | null;
   settled: boolean;
+  /** Set once the deadline fired: the result then says the script ran out of time. */
+  deadlineMs: number | null;
 }
 
 export class PyRunner {
@@ -125,8 +137,16 @@ export class PyRunner {
    * log file, wake_agent() is available in-script, and the deadline is the
    * background lifetime. A background runner should be DEDICATED to that one
    * script (the framework creates one per background script).
+   *
+   * `opts.deadlineMs` replaces the runner's scriptTimeoutMs for this exec (a
+   * per-call time limit); a background exec uses its `lifetimeMs` instead.
    */
-  async exec(code: string, tools: InjectedTool[], background?: BackgroundExecOptions): Promise<ExecResult> {
+  async exec(
+    code: string,
+    tools: InjectedTool[],
+    background?: BackgroundExecOptions,
+    opts?: { deadlineMs?: number },
+  ): Promise<ExecResult> {
     if (this.disposed) {
       return { stdout: '', stderr: 'code_execution runner disposed', returnCode: 1, aborted: true };
     }
@@ -154,7 +174,8 @@ export class PyRunner {
     }
 
     const execId = `e${++this.execCounter}`;
-    const deadlineMs = background?.lifetimeMs ?? this.scriptTimeoutMs;
+    // Clamped: a deadline past Node's timer range would fire at once instead of never.
+    const deadlineMs = Math.min(MAX_TIMER_MS, background?.lifetimeMs ?? opts?.deadlineMs ?? this.scriptTimeoutMs);
     this.onWake = background?.onWake ?? null;
     const result = await new Promise<ExecResult>((resolve) => {
       const pending: PendingExec = {
@@ -163,14 +184,17 @@ export class PyRunner {
         deadlineTimer: null,
         killTimer: null,
         settled: false,
+        deadlineMs: null,
       };
       this.pending = pending;
 
       pending.deadlineTimer = setTimeout(() => {
+        pending.deadlineMs = deadlineMs;
         // Deadline: ask politely first (script sees CancelledError and its
         // exec_result still flows back), then kill on unresponsiveness.
         this.send({ op: 'cancel', id: execId, reason: 'deadline' });
         pending.killTimer = setTimeout(() => {
+          pending.deadlineMs = null; // this message already says why
           this.settlePending({
             stdout: '',
             stderr: `script killed after exceeding ${Math.round(deadlineMs / 1000)}s deadline`,
@@ -380,6 +404,14 @@ export class PyRunner {
     const pending = this.pending;
     if (!pending || pending.settled) return;
     pending.settled = true;
+    // Say why the script stopped: the in-script cancellation only reads "cancelled by host".
+    // Only a script that ended unsuccessfully was stopped: one that caught the cancellation
+    // and finished its work returns 0, and must not read as stopped.
+    if (pending.deadlineMs !== null && result.returnCode !== 0) {
+      const note = `script stopped: it reached its ${formatLimit(pending.deadlineMs)} time limit\n`;
+      // A background script reports its output tail, so the note goes there too.
+      result = { ...result, stderr: result.stderr + note, ...(result.tail !== undefined ? { tail: result.tail + note } : {}) };
+    }
     if (pending.deadlineTimer) clearTimeout(pending.deadlineTimer);
     if (pending.killTimer) clearTimeout(pending.killTimer);
     this.pending = null;

package/src/code-execution/tool-definition.ts

@@ -9,15 +9,20 @@
  */
 
 import type { ToolDefinition } from '../types/index.js';
+import { formatLimit, MAX_TIMER_MS } from './py-runner.js';
 
 export const CODE_EXECUTION_TOOL_NAME = 'code_execution';
 
 export function buildCodeExecutionToolDefinition(opts?: {
   idleReclaimMs?: number;
   toolCallTimeoutMs?: number;
+  scriptTimeoutMs?: number;
+  maxScriptTimeoutMs?: number;
+  backgroundMaxLifetimeMs?: number;
 }): ToolDefinition {
   const idleMinutes = Math.max(1, Math.round((opts?.idleReclaimMs ?? 300_000) / 60_000));
   const callTimeoutSeconds = Math.round((opts?.toolCallTimeoutMs ?? 270_000) / 1000);
+  const limits = scriptTimeLimits(opts);
   return {
     name: CODE_EXECUTION_TOOL_NAME,
     description:
@@ -36,6 +41,9 @@ export function buildCodeExecutionToolDefinition(opts?: {
       'what you need. Interpreter state (variables, imports) persists across code_execution ' +
       `calls but is reclaimed after ~${idleMinutes} minutes idle. A tool call that receives no ` +
       `response within ~${callTimeoutSeconds}s raises TimeoutError inside the script. ` +
+      `A foreground script is stopped after ${formatLimit(limits.defaultMs)}; pass time_limit_ms to set this call's limit ` +
+      `(at most ${formatLimit(limits.maxMs)}; a background script runs up to ${formatLimit(limits.backgroundMaxMs)}). ` +
+      'Stopping a script does not stop tools it already called. ' +
       'Use this when fanning out across many items, looping over tool calls, or when tool ' +
       'results are large and you only need a slice or summary. Call tools directly (not via ' +
       'code) when a single call answers the question or when you need to reason about each ' +
@@ -72,8 +80,46 @@ export function buildCodeExecutionToolDefinition(opts?: {
           type: 'string',
           description: 'Background script id (for action: cancel).',
         },
+        time_limit_ms: {
+          type: 'integer',
+          description:
+            `Time limit for this script in milliseconds; it is stopped when the limit is reached. ` +
+            `Default ${limits.defaultMs}, at most ${limits.maxMs}; a background script defaults to and is capped at ` +
+            `its ${formatLimit(limits.backgroundMaxMs)} lifetime.`,
+        },
       },
       required: [],
     },
   };
 }
+
+/**
+ * A script's time limits: the default, the most an agent may ask for with
+ * `time_limit_ms`, and the background lifetime (default and ceiling at once).
+ */
+export function scriptTimeLimits(opts?: {
+  scriptTimeoutMs?: number;
+  maxScriptTimeoutMs?: number;
+  backgroundMaxLifetimeMs?: number;
+}): { defaultMs: number; maxMs: number; backgroundMaxMs: number } {
+  // Every limit fits Node's timer range (MAX_TIMER_MS, ~24.8 days).
+  const defaultMs = Math.min(MAX_TIMER_MS, opts?.scriptTimeoutMs ?? 600_000);
+  return {
+    defaultMs,
+    // A ceiling below the default is refused when the framework is created
+    // (validateCodeExecutionConfig); never below the default here either.
+    maxMs: Math.min(MAX_TIMER_MS, Math.max(defaultMs, opts?.maxScriptTimeoutMs ?? defaultMs)),
+    backgroundMaxMs: Math.min(MAX_TIMER_MS, opts?.backgroundMaxLifetimeMs ?? 86_400_000),
+  };
+}
+
+/** Refuse a configuration whose time limits contradict each other. */
+export function validateCodeExecutionConfig(cfg: { scriptTimeoutMs?: number; maxScriptTimeoutMs?: number }): void {
+  const defaultMs = cfg.scriptTimeoutMs ?? 600_000;
+  if (cfg.maxScriptTimeoutMs !== undefined && !(cfg.maxScriptTimeoutMs >= defaultMs)) {
+    throw new Error(
+      `codeExecution.maxScriptTimeoutMs (${cfg.maxScriptTimeoutMs}) must be at least scriptTimeoutMs (${defaultMs}): ` +
+        'it is the most an agent may ask for, and the default is always allowed',
+    );
+  }
+}