@animalabs/agent-framework 0.6.6 → 0.6.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.6.6",
+  "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,7 +46,7 @@
   "license": "MIT",
   "dependencies": {
     "@animalabs/chronicle": "^0.2.2",
-    "@animalabs/context-manager": "^0.5.11",
+    "@animalabs/context-manager": "^0.5.12",
     "@animalabs/membrane": "^0.5.73",
     "chokidar": "^4.0.3",
     "discord.js": "^14.25.1",

package/src/agent.ts

@@ -1,10 +1,20 @@
 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,
@@ -13,10 +23,15 @@ import type {
   CompileResult,
   HotContextSettingsStatus,
   HotContextSettingsUpdate,
+  PrimarySummaryContract,
+  PrimarySummaryIdentity,
+  PrimarySummaryProjection,
 } from '@animalabs/context-manager';
 import type {
   AgentConfig,
   AgentState,
+  SameRoundThinkTextPolicy,
+  SameRoundThinkTextPolicySource,
   PendingToolCall,
   CompletedToolCall,
   ToolCallId,
@@ -31,8 +46,13 @@ import type {
   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.
@@ -63,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;
@@ -76,6 +97,7 @@ export class Agent {
   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;
@@ -97,6 +119,7 @@ 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;
@@ -105,6 +128,7 @@ export class Agent {
     const hot = this.getHotContextSettings();
     this.configuredTailTokens = hot?.tailTokens;
     this.configuredTransitionPaceTokens = hot?.transitionPaceTokens;
+    this.configuredSameRoundThinkTextPolicy = config.sameRoundThinkTextPolicy;
   }
 
   /**
@@ -191,6 +215,141 @@ export class Agent {
     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 {
@@ -202,6 +361,8 @@ export class Agent {
       ...(hot?.transitionPaceTokens !== undefined
         ? { transitionPaceTokens: hot.transitionPaceTokens }
         : {}),
+      sameRoundThinkTextPolicy: this.getEffectiveSameRoundThinkTextPolicy(),
+      sameRoundThinkTextPolicySource: this.getSameRoundThinkTextPolicySource(),
       transition: this.contextBudgetTargetTokens === undefined
         ? 'stable'
         : hot?.blocked
@@ -219,6 +380,68 @@ export class Agent {
     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;
@@ -263,13 +486,17 @@ export class Agent {
       this.runtimeSettingsOverrides.transitionPaceTokens = DEFAULT_TRANSITION_PACE_TOKENS;
     }
     for (const [key, value] of Object.entries(patch)) {
-      if (value !== undefined) (this.runtimeSettingsOverrides as Record<string, number>)[key] = value;
+      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']);
+    const reset = new Set(keys ?? ['contextBudgetTokens', 'tailTokens', 'transitionPaceTokens', 'sameRoundThinkTextPolicy']);
     let nextContextBudget = this.contextBudgetTokens;
     let nextContextTarget = this.contextBudgetTargetTokens;
     const hotPatch: {
@@ -312,6 +539,9 @@ export class Agent {
     if (reset.has('transitionPaceTokens')) {
       delete this.runtimeSettingsOverrides.transitionPaceTokens;
     }
+    if (reset.has('sameRoundThinkTextPolicy')) {
+      delete this.runtimeSettingsOverrides.sameRoundThinkTextPolicy;
+    }
     return this.getRuntimeSettings();
   }
 
@@ -348,6 +578,11 @@ export class Agent {
         (!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');
@@ -548,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;
   }
 
   /**
@@ -625,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,
@@ -634,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 };
   }
 
   /**

package/src/api/server.ts

@@ -468,6 +468,10 @@ export class ApiServer {
     store.switchBranch(params.name);
     this.currentBranch = params.name;
 
+    // Reversible Discord awareness markers are part of the branch projection.
+    // Do not acknowledge the switch until add/remove operations were attempted.
+    await this.framework.syncDiscordAwarenessMarkers();
+
     // Materialize config files from the new branch
     const ws = this.framework.getModule('workspace');
     if (ws && 'materializeMount' in ws) {
@@ -511,7 +515,7 @@ export class ApiServer {
   // Undo/Redo Commands
   // ==========================================================================
 
-  private cmdUndo(params: { agentName: string }): unknown {
+  private async cmdUndo(params: { agentName: string }): Promise<unknown> {
     if (!params.agentName) {
       throw new Error('agentName is required');
     }
@@ -520,6 +524,7 @@ export class ApiServer {
 
     if (result.undone) {
       this.currentBranch = result.toBranch!;
+      await this.framework.syncDiscordAwarenessMarkers();
       this.broadcast('branch:switched', {
         from: result.fromBranch,
         to: result.toBranch,
@@ -530,7 +535,7 @@ export class ApiServer {
     return result;
   }
 
-  private cmdRedo(params: { agentName: string }): unknown {
+  private async cmdRedo(params: { agentName: string }): Promise<unknown> {
     if (!params.agentName) {
       throw new Error('agentName is required');
     }
@@ -539,6 +544,7 @@ export class ApiServer {
 
     if (result.redone) {
       this.currentBranch = result.toBranch!;
+      await this.framework.syncDiscordAwarenessMarkers();
       this.broadcast('branch:switched', {
         from: result.fromBranch,
         to: result.toBranch,

package/src/canonical-json.ts

@@ -0,0 +1,22 @@
+function normalizeCanonicalJson(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => normalizeCanonicalJson(entry));
+  }
+  if (value && typeof value === 'object') {
+    const withToJson = value as { toJSON?: () => unknown };
+    if (typeof withToJson.toJSON === 'function') {
+      return normalizeCanonicalJson(withToJson.toJSON());
+    }
+    const normalized: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      const child = normalizeCanonicalJson((value as Record<string, unknown>)[key]);
+      if (child !== undefined) normalized[key] = child;
+    }
+    return normalized;
+  }
+  return value;
+}
+
+export function canonicalJsonStringify(value: unknown): string {
+  return JSON.stringify(normalizeCanonicalJson(value)) ?? 'null';
+}