@animalabs/agent-framework 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.11.0",
+  "version": "0.13.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.3.0",
-    "@animalabs/context-manager": "^0.6.0",
+    "@animalabs/context-manager": "^0.8.0",
     "@animalabs/membrane": "^0.5.78",
     "chokidar": "^4.0.3",
     "discord.js": "^14.25.1",

package/src/agent.ts

@@ -1,5 +1,7 @@
 import type { Membrane, NormalizedMessage, NormalizedRequest, ContentBlock, YieldingStream } from '@animalabs/membrane';
 import { isAbortedResponse } from '@animalabs/membrane';
+import { createHash } from 'node:crypto';
+import type { CacheWireReceipt, KvUnifiedRequestHooks } from './kv-unified-wire.js';
 import {
   toolResultDataToHistoryString,
   truncateForHistory,
@@ -9,6 +11,8 @@ import {
 export interface StartStreamResult {
   stream: YieldingStream;
   request: NormalizedRequest;
+  takeKvSubmission?: () => { submissionId: string; wireReceipt: CacheWireReceipt } | undefined;
+  drainKvSubmissionIds?: () => string[];
 }
 import type {
   ContextManager,
@@ -37,6 +41,18 @@ import type {
   AgentRuntimeSettingsOverrides,
 } from './types/index.js';
 
+function stableHash(value: unknown): string {
+  const encode = (item: unknown): string => {
+    if (Array.isArray(item)) return `[${item.map(encode).join(',')}]`;
+    if (item && typeof item === 'object') {
+      const record = item as Record<string, unknown>;
+      return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${encode(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(item) ?? 'null';
+  };
+  return createHash('sha256').update(encode(value)).digest('hex');
+}
+
 const DEFAULT_CONTEXT_BUDGET_TOKENS = 100_000;
 const DEFAULT_TRANSITION_PACE_TOKENS = 16_000;
 const DEFAULT_SAME_ROUND_THINK_TEXT_POLICY: SameRoundThinkTextPolicy = 'public';
@@ -68,6 +84,8 @@ export class Agent {
   readonly refusalHandling: AgentConfig['refusalHandling'];
   /** Prose delivery mode (see AgentConfig.proseRouting). Default 'locus'. */
   readonly proseRouting: 'locus' | 'explicit' | 'hybrid' | 'disabled';
+  /** Exact whole-response known-tool wrapper containment (default off). */
+  readonly toolWrapperProseGuard: boolean;
   /** Prompt-cache TTL forwarded to the provider (see AgentConfig.cacheTtl). */
   readonly cacheTtl: NonNullable<AgentConfig['cacheTtl']>;
   /** Emit prompt-cache markers on requests (see AgentConfig.promptCaching). */
@@ -121,6 +139,7 @@ export class Agent {
     this.thinking = config.thinking;
     this.refusalHandling = config.refusalHandling;
     this.proseRouting = config.proseRouting ?? 'locus';
+    this.toolWrapperProseGuard = config.toolWrapperProseGuard ?? false;
     this.cacheTtl = config.cacheTtl ?? '1h';
     this.promptCaching = config.promptCaching ?? true;
     this.prefillUserMessage = config.prefillUserMessage;
@@ -442,9 +461,12 @@ export class Agent {
    */
   async compileWithInjections(
     budget?: TokenBudget,
-    injections?: ContextInjection[]
+    injections?: ContextInjection[],
+    opts?: { kvUnifiedImmutablePrefixHash?: string },
   ): Promise<CompileResult> {
-    const result = await this.contextManager.compile(this.resolveBudget(budget), injections);
+    const result = await this.contextManager.compile(
+      this.resolveBudget(budget), injections, opts as never,
+    );
     if (!budget) this.settleRuntimeSettingsTransition();
     return result;
   }
@@ -623,7 +645,26 @@ export class Agent {
     (this.contextManager as unknown as { setToolDefinitions?: (t: ToolDefinition[]) => void })
       .setToolDefinitions?.(availableTools);
 
-    let { messages, systemInjections } = await this.compileWithInjections(budget, injections);
+    const strategy = (this.contextManager as unknown as { getStrategy?: () => unknown })
+      .getStrategy?.() as {
+      beginKvUnifiedSubmission?: (args: { submissionId: string; requestHash: string; layoutHash: string }) => void;
+      isKvUnifiedEnabled?: () => boolean;
+    };
+    const kvUnified = strategy?.isKvUnifiedEnabled?.() === true;
+    const prospectiveSystemInjections = (injections ?? [])
+      .filter((injection) => injection.position === 'system')
+      .flatMap((injection) => injection.content);
+    const immutablePrefixHash = kvUnified
+      ? stableHash({
+          tools: availableTools.length > 0 ? availableTools : undefined,
+          system: this.buildSystemPrompt(prospectiveSystemInjections),
+        })
+      : undefined;
+    let { messages, systemInjections } = await this.compileWithInjections(
+      budget,
+      injections,
+      immutablePrefixHash ? { kvUnifiedImmutablePrefixHash: immutablePrefixHash } : undefined,
+    );
 
     // Sanitize: strip empty/whitespace text blocks and drop messages left with
     // no content. The Anthropic API rejects empty text blocks with 400
@@ -668,6 +709,7 @@ export class Agent {
       },
       tools: availableTools.length > 0 ? availableTools : undefined,
       promptCaching: this.promptCaching,
+      ...(kvUnified ? { cacheMarkers: 'cm-owned' as const } : {}),
       cacheTtl: this.cacheTtl,
       ...(this.prefillUserMessage && { prefillUserMessage: this.prefillUserMessage }),
       ...(this.providerParams && { providerParams: this.providerParams }),
@@ -702,6 +744,28 @@ export class Agent {
 
     const request = await this.buildActivationRequest(availableTools, injections, budget);
 
+    const receiptAware = (this.contextManager as unknown as { getStrategy?: () => unknown })
+      .getStrategy?.() as {
+      beginKvUnifiedSubmission?: (args: { submissionId: string; requestHash: string; layoutHash: string }) => void;
+      isKvUnifiedEnabled?: () => boolean;
+    };
+    const kvEnabled = receiptAware?.isKvUnifiedEnabled?.() === true;
+    const kvQueue: Array<{ submissionId: string; wireReceipt: CacheWireReceipt }> = [];
+    let kvCall = 0;
+    if (kvEnabled) {
+      const layoutHash = stableHash(request.messages);
+      const kvRequest = request as NormalizedRequest & KvUnifiedRequestHooks;
+      kvRequest.onCacheWireReceipt = (receipt) => {
+        const submissionId = `${this.name}:${this._streamId}:${Date.now()}:${kvCall++}`;
+        receiptAware.beginKvUnifiedSubmission!({
+          submissionId,
+          requestHash: receipt.requestHash,
+          layoutHash,
+        });
+        kvQueue.push({ submissionId, wireReceipt: receipt });
+      };
+    }
+
     const stream = this.membrane.streamYielding(request, {
       emitTokens: true,
       emitBlocks: false,
@@ -715,7 +779,16 @@ export class Agent {
     });
 
     this._state = { status: 'streaming', stream };
-    return { stream, request };
+    return {
+      stream,
+      request,
+      ...(kvEnabled
+        ? {
+            takeKvSubmission: () => kvQueue.shift(),
+            drainKvSubmissionIds: () => kvQueue.splice(0).map((item) => item.submissionId),
+          }
+        : {}),
+    };
   }
 
   /**