@animalabs/agent-framework 0.6.5 → 0.6.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "repository": {
     "type": "git",
@@ -21,10 +21,12 @@
     "src"
   ],
   "bin": {
-    "agent-framework-mcp": "./dist/src/api/mcp-server.js"
+    "agent-framework-mcp": "./dist/src/api/mcp-server.js",
+    "agent-framework-recover": "./dist/src/recovery/recover-cli.js"
   },
   "scripts": {
     "build": "tsc",
+    "postbuild": "node -e \"const fs=require('node:fs'); for (const p of ['dist/src/api/mcp-server.js','dist/src/recovery/recover-cli.js']) fs.chmodSync(p, 0o755)\"",
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit",
@@ -44,8 +46,8 @@
   "license": "MIT",
   "dependencies": {
     "@animalabs/chronicle": "^0.2.2",
-    "@animalabs/context-manager": "^0.5.5",
-    "@animalabs/membrane": "^0.5.64",
+    "@animalabs/context-manager": "^0.5.12",
+    "@animalabs/membrane": "^0.5.73",
     "chokidar": "^4.0.3",
     "discord.js": "^14.25.1",
     "ws": "^8.18.0"

package/src/agent.ts

@@ -1,15 +1,37 @@
 import type { Membrane, NormalizedMessage, NormalizedRequest, ContentBlock, YieldingStream } from '@animalabs/membrane';
 import { isAbortedResponse } from '@animalabs/membrane';
+import { createHash } from 'node:crypto';
 import { toolResultDataToHistoryString } from './tool-result-history.js';
+import { canonicalJsonStringify } from './canonical-json.js';
+
+export interface ActivationCompileArtifacts {
+  compileResult: CompileResult;
+  contract: PrimarySummaryContract & {
+    systemHash: string;
+  };
+}
 
 export interface StartStreamResult {
   stream: YieldingStream;
   request: NormalizedRequest;
+  artifacts: ActivationCompileArtifacts;
 }
-import type { ContextManager, TokenBudget, ContextInjection, CompileResult } from '@animalabs/context-manager';
+import type {
+  ContextManager,
+  TokenBudget,
+  ContextInjection,
+  CompileResult,
+  HotContextSettingsStatus,
+  HotContextSettingsUpdate,
+  PrimarySummaryContract,
+  PrimarySummaryIdentity,
+  PrimarySummaryProjection,
+} from '@animalabs/context-manager';
 import type {
   AgentConfig,
   AgentState,
+  SameRoundThinkTextPolicy,
+  SameRoundThinkTextPolicySource,
   PendingToolCall,
   CompletedToolCall,
   ToolCallId,
@@ -19,8 +41,19 @@ import type {
   AgentInfo,
   InferenceResult,
   InferenceOptions,
+  AgentRuntimeSettingsPatch,
+  AgentRuntimeSettingsSnapshot,
+  AgentRuntimeSettingsOverrides,
 } from './types/index.js';
 
+type PrimarySummaryContractWithSystemHash = PrimarySummaryContract & {
+  systemHash: string;
+};
+
+const DEFAULT_CONTEXT_BUDGET_TOKENS = 100_000;
+const DEFAULT_TRANSITION_PACE_TOKENS = 16_000;
+const DEFAULT_SAME_ROUND_THINK_TEXT_POLICY: SameRoundThinkTextPolicy = 'public';
+
 /**
  * An agent wraps a context manager and manages inference state.
  */
@@ -50,6 +83,7 @@ export class Agent {
   readonly cacheTtl: NonNullable<AgentConfig['cacheTtl']>;
   /** Provider-specific request parameters forwarded unchanged by Membrane. */
   readonly providerParams?: Record<string, unknown>;
+  readonly sameRoundThinkTextPolicy: AgentConfig['sameRoundThinkTextPolicy'];
 
   private _state: AgentState = { status: 'idle' };
   private _inferenceStartedAt = 0;
@@ -60,6 +94,12 @@ export class Agent {
    * ContextManager's built-in default applies. reserveForResponse uses
    * this agent's maxTokens. */
   contextBudgetTokens?: number;
+  private readonly configuredContextBudgetTokens?: number;
+  private readonly configuredTailTokens?: number;
+  private readonly configuredTransitionPaceTokens?: number;
+  private readonly configuredSameRoundThinkTextPolicy?: SameRoundThinkTextPolicy;
+  private contextBudgetTargetTokens?: number;
+  private runtimeSettingsOverrides: AgentRuntimeSettingsOverrides = {};
   private contextManager: ContextManager;
   private membrane: Membrane;
 
@@ -79,10 +119,16 @@ export class Agent {
     this.refusalHandling = config.refusalHandling;
     this.cacheTtl = config.cacheTtl ?? '1h';
     this.providerParams = config.providerParams;
+    this.sameRoundThinkTextPolicy = config.sameRoundThinkTextPolicy;
     this.maxStreamTokens = config.maxStreamTokens ?? 150_000;
     this.contextBudgetTokens = config.contextBudgetTokens;
+    this.configuredContextBudgetTokens = config.contextBudgetTokens;
     this.contextManager = contextManager;
     this.membrane = membrane;
+    const hot = this.getHotContextSettings();
+    this.configuredTailTokens = hot?.tailTokens;
+    this.configuredTransitionPaceTokens = hot?.transitionPaceTokens;
+    this.configuredSameRoundThinkTextPolicy = config.sameRoundThinkTextPolicy;
   }
 
   /**
@@ -148,8 +194,414 @@ export class Agent {
     return { maxTokens: this.contextBudgetTokens, reserveForResponse: this.maxTokens };
   }
 
+  /** Structural compatibility keeps lightweight test/host ContextManager
+   * doubles working while making the new capability optional at runtime. */
+  private getHotContextSettings(): HotContextSettingsStatus | null {
+    const manager = this.contextManager as ContextManager & {
+      getHotContextSettings?: () => HotContextSettingsStatus | null;
+    };
+    return typeof manager.getHotContextSettings === 'function'
+      ? manager.getHotContextSettings()
+      : null;
+  }
+
+  private updateHotContextSettings(update: HotContextSettingsUpdate): HotContextSettingsStatus {
+    const manager = this.contextManager as ContextManager & {
+      updateHotContextSettings?: (value: HotContextSettingsUpdate) => HotContextSettingsStatus;
+    };
+    if (typeof manager.updateHotContextSettings !== 'function') {
+      throw new Error('The active context strategy does not support live context settings');
+    }
+    return manager.updateHotContextSettings(update);
+  }
+
+  private hashJson(value: unknown): string {
+    return createHash('sha256').update(canonicalJsonStringify(value), 'utf8').digest('hex');
+  }
+
+  private primarySummaryFallbackEnabled(): boolean {
+    return this.refusalHandling?.primarySummaryFallback?.enabled === true;
+  }
+
+  private buildPrimarySummaryContractForRequest(request: NormalizedRequest): PrimarySummaryContractWithSystemHash {
+    return {
+      systemHash: this.hashJson(request.system ?? ''),
+      modelConfigHash: this.hashJson({
+        requestConfig: request.config,
+        providerParams: request.providerParams,
+        promptCaching: request.promptCaching,
+        cacheTtl: request.cacheTtl,
+        assistantParticipant: request.assistantParticipant,
+      }),
+      toolContractHash: this.hashJson(request.tools ?? []),
+    };
+  }
+
+  private setPrimaryLaneContract(contract: PrimarySummaryContract | undefined): void {
+    const manager = this.contextManager as ContextManager & {
+      setPrimaryLaneContract?: (value: PrimarySummaryContract | undefined) => void;
+    };
+    manager.setPrimaryLaneContract?.(contract);
+  }
+
+  private matchingPrimarySummaryQuarantine(
+    projection: PrimarySummaryProjection,
+    contract: PrimarySummaryContract,
+  ): PrimarySummaryIdentity[] {
+    const manager = this.contextManager as ContextManager & {
+      matchingPrimarySummaryQuarantine?: (
+        projection: PrimarySummaryProjection,
+        contract?: PrimarySummaryContract,
+      ) => PrimarySummaryIdentity[];
+    };
+    return manager.matchingPrimarySummaryQuarantine?.(projection, contract) ?? [];
+  }
+
+  private expandPrimarySummaryProjectionRaw(
+    compiled: CompileResult,
+    summaries: ReadonlyArray<PrimarySummaryIdentity>,
+  ): CompileResult {
+    const manager = this.contextManager as ContextManager & {
+      expandPrimarySummaryProjectionRaw?: (
+        compiled: CompileResult,
+        summaries: ReadonlyArray<PrimarySummaryIdentity>,
+      ) => CompileResult;
+    };
+    if (typeof manager.expandPrimarySummaryProjectionRaw !== 'function') return compiled;
+    return manager.expandPrimarySummaryProjectionRaw(compiled, summaries);
+  }
+
+  private primarySummaryIdentityKey(identity: PrimarySummaryIdentity): string {
+    return [
+      identity.id,
+      identity.contentHash,
+      identity.carrierHash,
+      identity.sourceLeafHash,
+    ].join('\u0000');
+  }
+
+  private buildRequestFromCompileResult(
+    compileResult: CompileResult,
+    availableTools: ToolDefinition[],
+  ): NormalizedRequest {
+    let { messages, systemInjections } = compileResult;
+
+    messages = messages
+      .map((m) => ({
+        ...m,
+        content: m.content.filter(
+          (b: ContentBlock) => !(b.type === "text" && (typeof b.text !== "string" || b.text.trim() === "")),
+        ),
+      }))
+      .filter((m) => m.content.length > 0);
+
+    if (messages.length > 0 && messages[messages.length - 1]!.participant === this.name) {
+      messages = [...messages, {
+        participant: 'user',
+        content: [{ type: 'text', text: '[Continue]' }],
+      }];
+    }
+
+    return {
+      messages,
+      system: this.buildSystemPrompt(systemInjections),
+      config: {
+        model: this.model,
+        maxTokens: this.maxTokens,
+        ...(this.temperature !== undefined && { temperature: this.temperature }),
+        ...(this.thinking !== undefined && { thinking: this.thinking }),
+      },
+      tools: availableTools.length > 0 ? availableTools : undefined,
+      promptCaching: true,
+      cacheTtl: this.cacheTtl,
+      ...(this.providerParams && { providerParams: this.providerParams }),
+      assistantParticipant: this.name,
+    };
+  }
+
+  async prepareActivationRequest(
+    availableTools: ToolDefinition[],
+    injections?: ContextInjection[],
+    budget?: TokenBudget,
+  ): Promise<{ request: NormalizedRequest; artifacts: ActivationCompileArtifacts }> {
+    (this.contextManager as unknown as { setToolDefinitions?: (t: ToolDefinition[]) => void })
+      .setToolDefinitions?.(availableTools);
+
+    let compileResult = await this.compileWithInjections(budget, injections);
+    let request = this.buildRequestFromCompileResult(compileResult, availableTools);
+    const contract = this.buildPrimarySummaryContractForRequest(request);
+    this.setPrimaryLaneContract(contract);
+
+    const projection = compileResult.primarySummaryProjection;
+    if (this.primarySummaryFallbackEnabled() && projection) {
+      const quarantined = this.matchingPrimarySummaryQuarantine(projection, contract);
+      if (quarantined.length > 0) {
+        compileResult = this.expandPrimarySummaryProjectionRaw(compileResult, quarantined);
+        request = this.buildRequestFromCompileResult(compileResult, availableTools);
+      }
+    }
+
+    return {
+      request,
+      artifacts: {
+        compileResult,
+        contract,
+      },
+    };
+  }
+
+  getRuntimeSettings(): AgentRuntimeSettingsSnapshot {
+    const hot = this.getHotContextSettings();
+    return {
+      contextBudgetTokens:
+        this.contextBudgetTargetTokens ??
+        this.contextBudgetTokens ??
+        DEFAULT_CONTEXT_BUDGET_TOKENS,
+      ...(hot ? { tailTokens: hot.tailTokens } : {}),
+      ...(hot?.transitionPaceTokens !== undefined
+        ? { transitionPaceTokens: hot.transitionPaceTokens }
+        : {}),
+      sameRoundThinkTextPolicy: this.getEffectiveSameRoundThinkTextPolicy(),
+      sameRoundThinkTextPolicySource: this.getSameRoundThinkTextPolicySource(),
+      transition: this.contextBudgetTargetTokens === undefined
+        ? 'stable'
+        : hot?.blocked
+          ? 'blocked'
+          : 'converging',
+      ...(hot?.blocked === 'transition-pace-floor'
+        ? { transitionReason: 'transition_pace_too_small' as const }
+        : hot?.blocked === 'prepared-window-floor'
+          ? { transitionReason: 'protected_context_exceeds_target' as const }
+          : {}),
+    };
+  }
+
+  getRuntimeSettingsOverrides(): AgentRuntimeSettingsOverrides {
+    return { ...this.runtimeSettingsOverrides };
+  }
+
+  getEffectiveSameRoundThinkTextPolicy(): SameRoundThinkTextPolicy {
+    return this.runtimeSettingsOverrides.sameRoundThinkTextPolicy
+      ?? this.configuredSameRoundThinkTextPolicy
+      ?? DEFAULT_SAME_ROUND_THINK_TEXT_POLICY;
+  }
+
+  getSameRoundThinkTextPolicySource(): SameRoundThinkTextPolicySource {
+    if (this.runtimeSettingsOverrides.sameRoundThinkTextPolicy !== undefined) {
+      return 'runtime_override';
+    }
+    if (this.configuredSameRoundThinkTextPolicy !== undefined) {
+      return 'recipe';
+    }
+    return 'compatibility_default';
+  }
+
+  getCurrentBranchGeneration():
+    | { id: string; name: string; head: number; generation: number; parentId?: string; branchPoint?: number; created: Date }
+    | null {
+    const manager = this.contextManager as ContextManager & {
+      currentBranchGeneration?: () => {
+        id: string;
+        name: string;
+        head: number;
+        generation: number;
+        parentId?: string;
+        branchPoint?: number;
+        created: Date;
+      };
+    };
+    return manager.currentBranchGeneration?.() ?? null;
+  }
+
+  buildPrimarySummaryRawExpansionRequest(
+    artifacts: ActivationCompileArtifacts,
+    summaries: ReadonlyArray<PrimarySummaryIdentity>,
+    availableTools: ToolDefinition[],
+  ): { request: NormalizedRequest; artifacts: ActivationCompileArtifacts } {
+    this.setPrimaryLaneContract(artifacts.contract);
+    const alreadyExpanded = new Set(
+      artifacts.compileResult.primarySummaryProjection?.selectedSummaries
+        .filter((selection) => selection.renderedAs === 'raw_expansion')
+        .map((selection) => this.primarySummaryIdentityKey(selection.identity)) ?? [],
+    );
+    const expandable = summaries.filter((summary) =>
+      !alreadyExpanded.has(this.primarySummaryIdentityKey(summary)),
+    );
+    const compileResult = expandable.length > 0
+      ? this.expandPrimarySummaryProjectionRaw(
+          artifacts.compileResult,
+          expandable,
+        )
+      : artifacts.compileResult;
+    return {
+      request: this.buildRequestFromCompileResult(compileResult, availableTools),
+      artifacts: {
+        compileResult,
+        contract: artifacts.contract,
+      },
+    };
+  }
+
+  updateRuntimeSettings(patch: AgentRuntimeSettingsPatch): AgentRuntimeSettingsSnapshot {
+    this.validateRuntimeSettingsPatch(patch);
+    let nextContextBudget = this.contextBudgetTokens;
+    let nextContextTarget = this.contextBudgetTargetTokens;
+    let appliedDefaultPace = false;
+    const hotPatch: {
+      tailTokens?: number;
+      transitionPaceTokens?: number | null;
+      preparedWindowTokens?: number | null;
+    } = {};
+    if (patch.tailTokens !== undefined) hotPatch.tailTokens = patch.tailTokens;
+    if (patch.transitionPaceTokens !== undefined) {
+      hotPatch.transitionPaceTokens = patch.transitionPaceTokens;
+    }
+
+    if (patch.contextBudgetTokens !== undefined) {
+      const live = this.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
+      if (patch.contextBudgetTokens >= live) {
+        nextContextBudget = patch.contextBudgetTokens;
+        nextContextTarget = undefined;
+        if (this.getHotContextSettings()) hotPatch.preparedWindowTokens = null;
+      } else {
+        const hot = this.getHotContextSettings();
+        if (!hot) {
+          throw new Error('The active context strategy cannot prepare a smaller window live');
+        }
+        if (patch.transitionPaceTokens === undefined && hot.transitionPaceTokens === undefined) {
+          hotPatch.transitionPaceTokens = DEFAULT_TRANSITION_PACE_TOKENS;
+          appliedDefaultPace = true;
+        }
+        hotPatch.preparedWindowTokens = patch.contextBudgetTokens - this.maxTokens;
+        nextContextTarget = patch.contextBudgetTokens;
+      }
+    }
+
+    if (Object.keys(hotPatch).length > 0) {
+      this.updateHotContextSettings(hotPatch);
+    }
+    this.contextBudgetTokens = nextContextBudget;
+    this.contextBudgetTargetTokens = nextContextTarget;
+    if (appliedDefaultPace) {
+      this.runtimeSettingsOverrides.transitionPaceTokens = DEFAULT_TRANSITION_PACE_TOKENS;
+    }
+    for (const [key, value] of Object.entries(patch)) {
+      if (key === 'sameRoundThinkTextPolicy') continue;
+      if (value !== undefined) (this.runtimeSettingsOverrides as Record<string, unknown>)[key] = value;
+    }
+    if (patch.sameRoundThinkTextPolicy !== undefined) {
+      this.runtimeSettingsOverrides.sameRoundThinkTextPolicy = patch.sameRoundThinkTextPolicy;
+    }
+    return this.getRuntimeSettings();
+  }
+
+  resetRuntimeSettings(keys?: Array<keyof AgentRuntimeSettingsPatch>): AgentRuntimeSettingsSnapshot {
+    const reset = new Set(keys ?? ['contextBudgetTokens', 'tailTokens', 'transitionPaceTokens', 'sameRoundThinkTextPolicy']);
+    let nextContextBudget = this.contextBudgetTokens;
+    let nextContextTarget = this.contextBudgetTargetTokens;
+    const hotPatch: {
+      tailTokens?: number;
+      transitionPaceTokens?: number | null;
+      preparedWindowTokens?: number | null;
+    } = {};
+
+    if (reset.has('contextBudgetTokens')) {
+      const configured = this.configuredContextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
+      const live = this.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
+      if (configured < live) {
+        const hot = this.getHotContextSettings();
+        if (!hot) throw new Error('The active context strategy cannot prepare a smaller window live');
+        hotPatch.preparedWindowTokens = configured - this.maxTokens;
+        if (hot.transitionPaceTokens === undefined) {
+          hotPatch.transitionPaceTokens = DEFAULT_TRANSITION_PACE_TOKENS;
+        }
+        nextContextTarget = configured;
+      } else {
+        nextContextBudget = this.configuredContextBudgetTokens;
+        nextContextTarget = undefined;
+        if (this.getHotContextSettings()) hotPatch.preparedWindowTokens = null;
+      }
+    }
+    if (reset.has('tailTokens')) {
+      if (this.configuredTailTokens !== undefined) hotPatch.tailTokens = this.configuredTailTokens;
+    }
+    if (reset.has('transitionPaceTokens') && this.getHotContextSettings()) {
+      hotPatch.transitionPaceTokens =
+        nextContextTarget !== undefined && this.configuredTransitionPaceTokens === undefined
+          ? DEFAULT_TRANSITION_PACE_TOKENS
+          : this.configuredTransitionPaceTokens ?? null;
+    }
+    if (Object.keys(hotPatch).length > 0) this.updateHotContextSettings(hotPatch);
+    this.contextBudgetTokens = nextContextBudget;
+    this.contextBudgetTargetTokens = nextContextTarget;
+    if (reset.has('contextBudgetTokens')) delete this.runtimeSettingsOverrides.contextBudgetTokens;
+    if (reset.has('tailTokens')) delete this.runtimeSettingsOverrides.tailTokens;
+    if (reset.has('transitionPaceTokens')) {
+      delete this.runtimeSettingsOverrides.transitionPaceTokens;
+    }
+    if (reset.has('sameRoundThinkTextPolicy')) {
+      delete this.runtimeSettingsOverrides.sameRoundThinkTextPolicy;
+    }
+    return this.getRuntimeSettings();
+  }
+
+  cancelRuntimeSettingsTransition(): AgentRuntimeSettingsSnapshot {
+    if (this.contextBudgetTargetTokens !== undefined) {
+      this.updateHotContextSettings({ preparedWindowTokens: null });
+      this.contextBudgetTargetTokens = undefined;
+      const live = this.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
+      if (live === (this.configuredContextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS)) {
+        delete this.runtimeSettingsOverrides.contextBudgetTokens;
+      } else {
+        this.runtimeSettingsOverrides.contextBudgetTokens = live;
+      }
+    }
+    return this.getRuntimeSettings();
+  }
+
+  restoreRuntimeSettings(overrides: AgentRuntimeSettingsOverrides): AgentRuntimeSettingsSnapshot {
+    return this.updateRuntimeSettings(overrides);
+  }
+
+  private validateRuntimeSettingsPatch(patch: AgentRuntimeSettingsPatch): void {
+    if (Object.keys(patch).length === 0) throw new Error('At least one setting is required');
+    if (patch.contextBudgetTokens !== undefined) {
+      if (!Number.isSafeInteger(patch.contextBudgetTokens) || patch.contextBudgetTokens <= this.maxTokens) {
+        throw new Error(`contextBudgetTokens must be a safe integer greater than max response tokens (${this.maxTokens})`);
+      }
+    }
+    if (patch.tailTokens !== undefined &&
+        (!Number.isSafeInteger(patch.tailTokens) || patch.tailTokens < 0)) {
+      throw new Error('tailTokens must be a non-negative safe integer');
+    }
+    if (patch.transitionPaceTokens !== undefined &&
+        (!Number.isSafeInteger(patch.transitionPaceTokens) || patch.transitionPaceTokens <= 0)) {
+      throw new Error('transitionPaceTokens must be a positive safe integer');
+    }
+    if (patch.sameRoundThinkTextPolicy !== undefined &&
+        patch.sameRoundThinkTextPolicy !== 'public' &&
+        patch.sameRoundThinkTextPolicy !== 'private') {
+      throw new Error("sameRoundThinkTextPolicy must be 'public' or 'private'");
+    }
+    if ((patch.tailTokens !== undefined || patch.transitionPaceTokens !== undefined) &&
+        !this.getHotContextSettings()) {
+      throw new Error('The active context strategy does not support live tail/transition settings');
+    }
+  }
+
+  private settleRuntimeSettingsTransition(): void {
+    if (this.contextBudgetTargetTokens === undefined) return;
+    const hot = this.getHotContextSettings();
+    if (!hot?.prepared) return;
+    this.contextBudgetTokens = this.contextBudgetTargetTokens;
+    this.contextBudgetTargetTokens = undefined;
+    this.updateHotContextSettings({ preparedWindowTokens: null });
+  }
+
   async compileContext(budget?: TokenBudget): Promise<CompileResult> {
-    return this.contextManager.compile(this.resolveBudget(budget));
+    const result = await this.contextManager.compile(this.resolveBudget(budget));
+    if (!budget) this.settleRuntimeSettingsTransition();
+    return result;
   }
 
   /**
@@ -161,7 +613,9 @@ export class Agent {
     budget?: TokenBudget,
     injections?: ContextInjection[]
   ): Promise<CompileResult> {
-    return this.contextManager.compile(this.resolveBudget(budget), injections);
+    const result = await this.contextManager.compile(this.resolveBudget(budget), injections);
+    if (!budget) this.settleRuntimeSettingsTransition();
+    return result;
   }
 
   // ==========================================================================
@@ -329,64 +783,8 @@ export class Agent {
     injections?: ContextInjection[],
     budget?: TokenBudget
   ): Promise<NormalizedRequest> {
-    // Keep the context manager's view of the live tool surface current: the
-    // autobiographical strategy must declare the same tools on its
-    // summarizer/compression requests, or transcripts containing tool blocks
-    // are refused by Anthropic's reasoning_extraction classifier (labclaude
-    // incident, 2026-07-09). Optional chaining: older context-manager
-    // versions don't have the hook.
-    (this.contextManager as unknown as { setToolDefinitions?: (t: ToolDefinition[]) => void })
-      .setToolDefinitions?.(availableTools);
-
-    let { messages, systemInjections } = await this.compileWithInjections(budget, injections);
-
-    // Sanitize: strip empty/whitespace text blocks and drop messages left with
-    // no content. The Anthropic API rejects empty text blocks with 400
-    // "messages: text content blocks must be non-empty"; when such a block
-    // reaches a live activation request the agent cannot complete ANY turn
-    // ([inference-failed] on every attempt) until the offending message ages
-    // out of the window. Empty text blocks occur naturally: tool-only turns,
-    // delivery-failure placeholders, silent/skip turns. Non-text blocks pass
-    // through unchanged, so tool pairing is unaffected. (Field-observed
-    // 2026-07-10 on a resident agent: one empty block muted the agent's live
-    // path entirely; twin of context-manager's stripEmptyTextBlocks on the
-    // compression path.)
-    messages = messages
-      .map((m) => ({
-        ...m,
-        content: m.content.filter(
-          // typeof guard is deliberate runtime defense: history loaded from
-          // disk can carry a non-string `text` despite what the types claim.
-          (b: ContentBlock) => !(b.type === "text" && (typeof b.text !== "string" || b.text.trim() === "")),
-        ),
-      }))
-      .filter((m) => m.content.length > 0);
-
-    // Safety: ensure messages don't end with an assistant message.
-    // Some models reject trailing assistant messages ("prefill not supported"),
-    // and after context compression a stale assistant turn can end up last.
-    if (messages.length > 0 && messages[messages.length - 1]!.participant === this.name) {
-      messages = [...messages, {
-        participant: 'user',
-        content: [{ type: 'text', text: '[Continue]' }],
-      }];
-    }
-
-    return {
-      messages,
-      system: this.buildSystemPrompt(systemInjections),
-      config: {
-        model: this.model,
-        maxTokens: this.maxTokens,
-        ...(this.temperature !== undefined && { temperature: this.temperature }),
-        ...(this.thinking !== undefined && { thinking: this.thinking }),
-      },
-      tools: availableTools.length > 0 ? availableTools : undefined,
-      promptCaching: true,
-      cacheTtl: this.cacheTtl,
-      ...(this.providerParams && { providerParams: this.providerParams }),
-      assistantParticipant: this.name,
-    };
+    const { request } = await this.prepareActivationRequest(availableTools, injections, budget);
+    return request;
   }
 
   /**
@@ -406,7 +804,11 @@ export class Agent {
     this._inferenceStartedAt = Date.now();
     this.lastStreamInputTokens = 0;
 
-    const request = await this.buildActivationRequest(availableTools, injections, budget);
+    const { request, artifacts } = await this.prepareActivationRequest(
+      availableTools,
+      injections,
+      budget,
+    );
 
     const stream = this.membrane.streamYielding(request, {
       emitTokens: true,
@@ -415,7 +817,27 @@ export class Agent {
     });
 
     this._state = { status: 'streaming', stream };
-    return { stream, request };
+    return { stream, request, artifacts };
+  }
+
+  startStreamFromRequest(
+    request: NormalizedRequest,
+    artifacts: ActivationCompileArtifacts,
+  ): StartStreamResult {
+    if (this._state.status !== 'streaming' && this._state.status !== 'idle') {
+      throw new Error(`Agent ${this.name} cannot replace stream in state ${this._state.status}`);
+    }
+    this._streamId++;
+    this._inferenceStartedAt = Date.now();
+    this.lastStreamInputTokens = 0;
+    this.setPrimaryLaneContract(artifacts.contract);
+    const stream = this.membrane.streamYielding(request, {
+      emitTokens: true,
+      emitBlocks: false,
+      emitUsage: true,
+    });
+    this._state = { status: 'streaming', stream };
+    return { stream, request, artifacts };
   }
 
   /**