@animalabs/agent-framework 0.5.4 → 0.5.7

package/src/agent.ts

@@ -1,5 +1,6 @@
 import type { Membrane, NormalizedMessage, NormalizedRequest, ContentBlock, YieldingStream } from '@animalabs/membrane';
 import { isAbortedResponse } from '@animalabs/membrane';
+import { toolResultDataToHistoryString } from './tool-result-history.js';
 
 export interface StartStreamResult {
   stream: YieldingStream;
@@ -42,13 +43,17 @@ export class Agent {
    * request native thinking from the provider. Signatures on response thinking
    * blocks are preserved through Chronicle.
    */
-  readonly thinking: { enabled: boolean; budgetTokens?: number } | undefined;
+  readonly thinking: AgentConfig['thinking'];
 
   private _state: AgentState = { status: 'idle' };
   private _inferenceStartedAt = 0;
   private _streamId = 0;
   lastStreamInputTokens = 0;
   maxStreamTokens: number;
+  /** Per-agent context compile budget (input tokens). When unset, the
+   * ContextManager's built-in default applies. reserveForResponse uses
+   * this agent's maxTokens. */
+  contextBudgetTokens?: number;
   private contextManager: ContextManager;
   private membrane: Membrane;
 
@@ -66,6 +71,7 @@ export class Agent {
     this.temperature = config.temperature;
     this.thinking = config.thinking;
     this.maxStreamTokens = config.maxStreamTokens ?? 150_000;
+    this.contextBudgetTokens = config.contextBudgetTokens;
     this.contextManager = contextManager;
     this.membrane = membrane;
   }
@@ -125,8 +131,16 @@ export class Agent {
    * Step 1 of the inference pipeline — callers can inspect/modify the result
    * before building a request.
    */
+  /** Resolve the compile budget: explicit arg wins, else the per-agent
+   * configured context budget (if any), else the ContextManager default. */
+  private resolveBudget(budget?: TokenBudget): TokenBudget | undefined {
+    if (budget) return budget;
+    if (this.contextBudgetTokens === undefined) return undefined;
+    return { maxTokens: this.contextBudgetTokens, reserveForResponse: this.maxTokens };
+  }
+
   async compileContext(budget?: TokenBudget): Promise<CompileResult> {
-    return this.contextManager.compile(budget);
+    return this.contextManager.compile(this.resolveBudget(budget));
   }
 
   /**
@@ -138,7 +152,7 @@ export class Agent {
     budget?: TokenBudget,
     injections?: ContextInjection[]
   ): Promise<CompileResult> {
-    return this.contextManager.compile(budget, injections);
+    return this.contextManager.compile(this.resolveBudget(budget), injections);
   }
 
   // ==========================================================================
@@ -290,22 +304,21 @@ export class Agent {
   }
 
   /**
-   * Start a yielding stream with context injections.
-   * Same as startStream but passes injections through to compile.
+   * Build the membrane-normalized request that WOULD be emitted for this
+   * agent's next activation, given the supplied tools and injections.
+   *
+   * This is the single source of truth for request assembly, shared by the
+   * real activation path (`startStreamWithInjections`) and debug/preview
+   * tooling (`Framework.previewActivation`). It is pure and non-mutating:
+   * it does not touch agent state and does not call the membrane, and
+   * `ContextManager.compile` is itself side-effect-free (compression runs in
+   * the background). Safe to call regardless of the agent's current status.
    */
-  async startStreamWithInjections(
+  async buildActivationRequest(
     availableTools: ToolDefinition[],
     injections?: ContextInjection[],
     budget?: TokenBudget
-  ): Promise<StartStreamResult> {
-    if (this._state.status !== 'idle') {
-      throw new Error(`Agent ${this.name} cannot start stream in state ${this._state.status}`);
-    }
-
-    this._streamId++;
-    this._inferenceStartedAt = Date.now();
-    this.lastStreamInputTokens = 0;
-
+  ): Promise<NormalizedRequest> {
     let { messages, systemInjections } = await this.compileWithInjections(budget, injections);
 
     // Safety: ensure messages don't end with an assistant message.
@@ -318,7 +331,7 @@ export class Agent {
       }];
     }
 
-    const request: NormalizedRequest = {
+    return {
       messages,
       system: this.buildSystemPrompt(systemInjections),
       config: {
@@ -331,6 +344,26 @@ export class Agent {
       promptCaching: true,
       assistantParticipant: this.name,
     };
+  }
+
+  /**
+   * Start a yielding stream with context injections.
+   * Same as startStream but passes injections through to compile.
+   */
+  async startStreamWithInjections(
+    availableTools: ToolDefinition[],
+    injections?: ContextInjection[],
+    budget?: TokenBudget
+  ): Promise<StartStreamResult> {
+    if (this._state.status !== 'idle') {
+      throw new Error(`Agent ${this.name} cannot start stream in state ${this._state.status}`);
+    }
+
+    this._streamId++;
+    this._inferenceStartedAt = Date.now();
+    this.lastStreamInputTokens = 0;
+
+    const request = await this.buildActivationRequest(availableTools, injections, budget);
 
     const stream = this.membrane.streamYielding(request, {
       emitTokens: true,
@@ -509,13 +542,15 @@ export class Agent {
   }
 
   private buildToolResultMessages(results: CompletedToolCall[]): NormalizedMessage[] {
-    // Tool results go as a user message with tool_result blocks
+    // Tool results go as a user message with tool_result blocks. The history
+    // serializer turns MCP image blocks into `[image: type, size]` so the
+    // persisted transcript stays small and survives truncation.
     const content = results.map((r) => ({
       type: 'tool_result' as const,
       toolUseId: r.id,
       content: r.result.isError
         ? r.result.error ?? 'Unknown error'
-        : JSON.stringify(r.result.data),
+        : toolResultDataToHistoryString(r.result.data),
       isError: r.result.isError,
     }));