@animalabs/agent-framework 0.6.5 → 0.6.7

package/src/recovery/offline-branch.ts

@@ -0,0 +1,510 @@
+import { JsStore } from '@animalabs/chronicle';
+import { ContextManager } from '@animalabs/context-manager';
+import {
+  DEFAULT_DISCORD_AWARENESS_EMOJI,
+  DiscordAwarenessOutbox,
+  defaultDiscordAwarenessOutboxPath,
+  extractDiscordAwarenessRefs,
+  type DiscordAwarenessRef,
+} from './discord-awareness-outbox.js';
+
+export interface OfflineRecoveryBranchOptions {
+  storePath: string;
+  agentName: string;
+  /** Preferred: Discord message that remains as the last visible anchor. */
+  messageId?: string;
+  /** Exact internal ContextManager message ID that remains as the anchor. */
+  contextId?: string;
+  /** Backward-compatible alternative: remove the newest N context entries. */
+  messages?: number;
+  /** Exact Discord messages to suppress on the new branch. */
+  suppressMessageIds?: string[];
+  /** Inclusive context-order ranges between Discord message endpoints. */
+  suppressRanges?: Array<{ fromMessageId: string; toMessageId: string }>;
+  branchName?: string;
+  /** Defaults to the primary-agent namespace `agents/{agentName}`. */
+  namespace?: string;
+  /** Use for old message records that do not carry metadata.serverId. */
+  discordServerId?: string;
+  outboxPath?: string;
+  emoji?: string;
+  dryRun?: boolean;
+}
+
+export interface OfflineRecoveryBranchResult {
+  dryRun: boolean;
+  sourceBranch: string;
+  targetBranch: string;
+  messagesRemoved: number;
+  messagesSuppressed: number;
+  discordMarkersQueued: number;
+  refs: DiscordAwarenessRef[];
+  outboxPath: string;
+}
+
+/**
+ * Create a safe Chronicle branch while the normal agent host is stopped.
+ *
+ * History is scanned in bounded windows and blobs are not re-inlined. The
+ * affected messages are never compiled and their content is never written to
+ * the recovery outbox; only Discord addressing metadata leaves Chronicle.
+ */
+export async function createOfflineRecoveryBranch(
+  options: OfflineRecoveryBranchOptions,
+): Promise<OfflineRecoveryBranchResult> {
+  const anchorCount = Number(!!options.messageId)
+    + Number(!!options.contextId)
+    + Number(options.messages !== undefined);
+  if (anchorCount !== 1) {
+    throw new Error('Specify exactly one of messageId, contextId, or messages');
+  }
+  const count = options.messages === undefined ? undefined : Math.floor(options.messages);
+  if (count !== undefined && (!Number.isFinite(count) || count < 1)) {
+    throw new Error('messages must be a positive integer');
+  }
+
+  const store = JsStore.openOrCreate({ path: options.storePath });
+  let contextManager: ContextManager | null = null;
+  try {
+    contextManager = await ContextManager.open({
+      store,
+      namespace: options.namespace ?? `agents/${options.agentName}`,
+    });
+
+    const total = contextManager.getMessageCount();
+    if (count !== undefined && count >= total) {
+      throw new Error(
+        `Cannot remove ${count} message(s) — history has ${total}; at least one must remain.`,
+      );
+    }
+
+    let target: StoredWindowMessage;
+    let targetIndex: number;
+    let removedCount: number;
+    let refs: DiscordAwarenessRef[];
+
+    if (options.messageId) {
+      // Search backward in bounded windows: recovery anchors are normally near
+      // the tail, and even a very large Chronicle is never materialized all at
+      // once. If an adaptive strategy sharded the Discord message, choosing the
+      // newest matching shard keeps the complete message at the branch point.
+      const anchorId = normalizeDiscordMessageId(options.messageId);
+      const located = findDiscordMessageFromTail(contextManager, total, anchorId);
+      if (!located) {
+        throw new Error(
+          `Discord message ${anchorId} is not an addressable message in this context.`,
+        );
+      }
+      target = located.message;
+      targetIndex = located.index;
+      removedCount = total - located.index - 1;
+      refs = collectDiscordRefs(
+        contextManager,
+        located.index + 1,
+        total,
+        options.discordServerId,
+      );
+    } else if (options.contextId) {
+      const located = findInternalMessageFromTail(contextManager, total, options.contextId.trim());
+      if (!located) {
+        throw new Error(`Internal context message ${options.contextId} was not found.`);
+      }
+      target = located.message;
+      targetIndex = located.index;
+      removedCount = total - located.index - 1;
+      refs = collectDiscordRefs(
+        contextManager,
+        located.index + 1,
+        total,
+        options.discordServerId,
+      );
+    } else {
+      // Count mode remains for compatibility. Read only the target plus suffix,
+      // avoiding full-history materialization and attachment blob inflation.
+      const window = contextManager.getMessageWindow(total - count! - 1, count! + 1, {
+        resolveBlobs: false,
+      }).messages;
+      const countTarget = window[0];
+      const discarded = window.slice(1);
+      if (!countTarget || discarded.length !== count) {
+        throw new Error('Could not read the requested recovery window from Chronicle');
+      }
+      target = countTarget;
+      targetIndex = total - count! - 1;
+      removedCount = count!;
+      refs = extractDiscordAwarenessRefs(discarded, options.discordServerId);
+    }
+
+    validateAnchorBoundary(contextManager, targetIndex, total, target);
+
+    const suppression = buildSuppressionPlan(
+      contextManager,
+      targetIndex,
+      options.suppressMessageIds ?? [],
+      options.suppressRanges ?? [],
+      options.discordServerId,
+    );
+    validateRemovalIntegrity(
+      contextManager,
+      total,
+      [
+        ...(removedCount > 0 ? [{
+          start: targetIndex + 1,
+          end: total - 1,
+          fromId: '',
+          toId: '',
+        }] : []),
+        ...suppression.intervals,
+      ],
+    );
+    refs = dedupeDiscordRefs([...refs, ...suppression.refs]);
+
+    const sourceBranch = store.currentBranch().name;
+    const targetBranch = options.branchName
+      ?? `recovery/${options.agentName}/${Date.now()}`;
+    if (targetBranch === sourceBranch) {
+      throw new Error('Recovery branch name must differ from the active source branch');
+    }
+    const outboxPath = options.outboxPath
+      ?? defaultDiscordAwarenessOutboxPath(options.storePath);
+
+    const result: OfflineRecoveryBranchResult = {
+      dryRun: options.dryRun === true,
+      sourceBranch,
+      targetBranch,
+      messagesRemoved: removedCount,
+      messagesSuppressed: suppression.messageCount,
+      discordMarkersQueued: refs.length,
+      refs,
+      outboxPath,
+    };
+    if (options.dryRun) return result;
+
+    const outbox = new DiscordAwarenessOutbox(outboxPath);
+    const batch = outbox.prepare({
+      agentName: options.agentName,
+      sourceBranch,
+      targetBranch,
+      refs,
+      emoji: options.emoji ?? DEFAULT_DISCORD_AWARENESS_EMOJI,
+      // Merely seeing targetBranch active does not prove branch-local
+      // suppressions finished. Only the recovery operation may activate this
+      // batch after every removal below succeeds.
+      activationPolicy: suppression.intervals.length > 0 ? 'explicit' : 'target-branch',
+      suppressionIntervals: suppression.intervals.map((interval) => ({
+        fromId: String(interval.fromId),
+        toId: String(interval.toId),
+      })),
+    });
+
+    // branchAt uses the target message's origin sequence. No message content is
+    // compiled or submitted to Membrane during this operation.
+    const createdBranch = contextManager.branchAt(target.id, targetBranch);
+    try {
+      await contextManager.switchBranch(createdBranch);
+      // Work from newest to oldest so earlier redactions never perturb the
+      // live positions used by later range endpoints.
+      for (const interval of [...suppression.intervals].reverse()) {
+        if (interval.fromId === interval.toId) contextManager.removeMessage(interval.fromId);
+        else contextManager.removeMessages(interval.fromId, interval.toId);
+      }
+      if (batch) outbox.activate(batch.id);
+    } catch (error) {
+      // A partially suppressed branch is not safe to boot into. Preserve it
+      // for diagnosis, but leave Chronicle on the untouched source branch and
+      // keep the explicit outbox batch non-deliverable.
+      if (store.currentBranch().name === createdBranch) {
+        await contextManager.switchBranch(sourceBranch);
+      }
+      throw error;
+    }
+
+    return result;
+  } finally {
+    contextManager?.close();
+    store.close();
+  }
+}
+
+const RECOVERY_SCAN_WINDOW = 1_000;
+type StoredWindowMessage = ReturnType<ContextManager['getMessageWindow']>['messages'][number];
+
+interface SuppressionInterval {
+  start: number;
+  end: number;
+  fromId: StoredWindowMessage['id'];
+  toId: StoredWindowMessage['id'];
+}
+
+interface MessageLocation {
+  first: number;
+  last: number;
+  firstId: StoredWindowMessage['id'];
+  lastId: StoredWindowMessage['id'];
+  /** Usually one run; multiple runs tolerate duplicate external metadata. */
+  runs: SuppressionInterval[];
+}
+
+function normalizeDiscordMessageId(input: string): string {
+  const trimmed = input.trim();
+  const link = trimmed.match(/channels\/\d+\/\d+\/(\d+)/);
+  return link?.[1] ?? trimmed;
+}
+
+function findDiscordMessageFromTail(
+  contextManager: ContextManager,
+  total: number,
+  messageId: string,
+): { message: ReturnType<ContextManager['getMessageWindow']>['messages'][number]; index: number } | null {
+  let end = total;
+  while (end > 0) {
+    const start = Math.max(0, end - RECOVERY_SCAN_WINDOW);
+    const messages = contextManager.getMessageWindow(start, end - start, {
+      resolveBlobs: false,
+    }).messages;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (String(messages[i].metadata?.messageId ?? '') === messageId) {
+        return { message: messages[i], index: start + i };
+      }
+    }
+    end = start;
+  }
+  return null;
+}
+
+function findInternalMessageFromTail(
+  contextManager: ContextManager,
+  total: number,
+  contextId: string,
+): { message: StoredWindowMessage; index: number } | null {
+  let end = total;
+  while (end > 0) {
+    const start = Math.max(0, end - RECOVERY_SCAN_WINDOW);
+    const messages = contextManager.getMessageWindow(start, end - start, {
+      resolveBlobs: false,
+    }).messages;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (String(messages[i].id) === contextId) {
+        return { message: messages[i], index: start + i };
+      }
+    }
+    end = start;
+  }
+  return null;
+}
+
+function validateAnchorBoundary(
+  contextManager: ContextManager,
+  targetIndex: number,
+  total: number,
+  target: StoredWindowMessage,
+): void {
+  const groupId = (target as StoredWindowMessage & { bodyGroupId?: string }).bodyGroupId;
+  if (!groupId || targetIndex + 1 >= total) return;
+  const next = contextManager.getMessageWindow(targetIndex + 1, 1, {
+    resolveBlobs: false,
+  }).messages[0] as (StoredWindowMessage & { bodyGroupId?: string }) | undefined;
+  if (next?.bodyGroupId === groupId) {
+    throw new Error(
+      `Recovery anchor ${String(target.id)} splits body group ${groupId}; choose its final shard.`,
+    );
+  }
+}
+
+function validateRemovalIntegrity(
+  contextManager: ContextManager,
+  total: number,
+  intervals: SuppressionInterval[],
+): void {
+  if (intervals.length === 0) return;
+  const removed = (index: number) => intervals.some((interval) =>
+    index >= interval.start && index <= interval.end);
+  const toolUses = new Map<string, boolean>();
+  const toolResults = new Map<string, boolean>();
+  const groupMembership = new Map<string, boolean>();
+
+  for (let offset = 0; offset < total; offset += RECOVERY_SCAN_WINDOW) {
+    const messages = contextManager.getMessageWindow(
+      offset,
+      Math.min(RECOVERY_SCAN_WINDOW, total - offset),
+      { resolveBlobs: false },
+    ).messages;
+    for (let i = 0; i < messages.length; i++) {
+      const index = offset + i;
+      const isRemoved = removed(index);
+      const message = messages[i] as StoredWindowMessage & { bodyGroupId?: string };
+      if (message.bodyGroupId) {
+        const prior = groupMembership.get(message.bodyGroupId);
+        if (prior !== undefined && prior !== isRemoved) {
+          throw new Error(
+            `Recovery selection splits body group ${message.bodyGroupId}; adjust the anchor or suppression boundary.`,
+          );
+        }
+        groupMembership.set(message.bodyGroupId, isRemoved);
+      }
+      for (const rawBlock of message.content) {
+        const block = rawBlock as { type?: unknown; id?: unknown; toolUseId?: unknown };
+        if (block.type === 'tool_use' && typeof block.id === 'string') {
+          toolUses.set(block.id, isRemoved);
+        } else if (block.type === 'tool_result' && typeof block.toolUseId === 'string') {
+          toolResults.set(block.toolUseId, isRemoved);
+        }
+      }
+    }
+  }
+
+  for (const [toolUseId, useRemoved] of toolUses) {
+    const resultRemoved = toolResults.get(toolUseId);
+    if (resultRemoved !== undefined && resultRemoved !== useRemoved) {
+      throw new Error(
+        `Recovery selection would split tool exchange ${toolUseId}; suppress or retain both tool_use and tool_result.`,
+      );
+    }
+  }
+}
+
+function buildSuppressionPlan(
+  contextManager: ContextManager,
+  targetIndex: number,
+  rawMessageIds: string[],
+  rawRanges: Array<{ fromMessageId: string; toMessageId: string }>,
+  forcedServerId?: string,
+): { intervals: SuppressionInterval[]; refs: DiscordAwarenessRef[]; messageCount: number } {
+  const messageIds = rawMessageIds.map(normalizeDiscordMessageId);
+  const ranges = rawRanges.map((range) => ({
+    fromMessageId: normalizeDiscordMessageId(range.fromMessageId),
+    toMessageId: normalizeDiscordMessageId(range.toMessageId),
+  }));
+  const wanted = new Set([
+    ...messageIds,
+    ...ranges.flatMap((range) => [range.fromMessageId, range.toMessageId]),
+  ]);
+  if (wanted.size === 0) return { intervals: [], refs: [], messageCount: 0 };
+
+  const locations = new Map<string, MessageLocation>();
+  for (let offset = 0; offset <= targetIndex; offset += RECOVERY_SCAN_WINDOW) {
+    const messages = contextManager.getMessageWindow(
+      offset,
+      Math.min(RECOVERY_SCAN_WINDOW, targetIndex - offset + 1),
+      { resolveBlobs: false },
+    ).messages;
+    for (let i = 0; i < messages.length; i++) {
+      const externalId = String(messages[i].metadata?.messageId ?? '');
+      if (!wanted.has(externalId)) continue;
+      const index = offset + i;
+      const location = locations.get(externalId);
+      if (!location) {
+        const run = {
+          start: index,
+          end: index,
+          fromId: messages[i].id,
+          toId: messages[i].id,
+        };
+        locations.set(externalId, {
+          first: index,
+          last: index,
+          firstId: messages[i].id,
+          lastId: messages[i].id,
+          runs: [run],
+        });
+      } else {
+        const lastRun = location.runs.at(-1)!;
+        if (index === lastRun.end + 1) {
+          lastRun.end = index;
+          lastRun.toId = messages[i].id;
+        } else {
+          location.runs.push({
+            start: index,
+            end: index,
+            fromId: messages[i].id,
+            toId: messages[i].id,
+          });
+        }
+        location.last = index;
+        location.lastId = messages[i].id;
+      }
+    }
+  }
+
+  for (const id of wanted) {
+    if (!locations.has(id)) {
+      throw new Error(
+        `Suppression endpoint ${id} is not visible at the selected branch point.`,
+      );
+    }
+  }
+
+  const intervals: SuppressionInterval[] = [];
+  for (const id of messageIds) {
+    const location = locations.get(id)!;
+    intervals.push(...location.runs.map((run) => ({ ...run })));
+  }
+  for (const range of ranges) {
+    const from = locations.get(range.fromMessageId)!;
+    const to = locations.get(range.toMessageId)!;
+    const earlier = from.first <= to.first ? from : to;
+    const later = from.first <= to.first ? to : from;
+    intervals.push({
+      start: earlier.first,
+      end: later.last,
+      fromId: earlier.firstId,
+      toId: later.lastId,
+    });
+  }
+
+  intervals.sort((a, b) => a.start - b.start || a.end - b.end);
+  const merged: SuppressionInterval[] = [];
+  for (const interval of intervals) {
+    const previous = merged.at(-1);
+    if (previous && interval.start <= previous.end + 1) {
+      if (interval.end > previous.end) {
+        previous.end = interval.end;
+        previous.toId = interval.toId;
+      }
+    } else {
+      merged.push({ ...interval });
+    }
+  }
+
+  const refs: DiscordAwarenessRef[] = [];
+  for (const interval of merged) {
+    refs.push(...collectDiscordRefs(
+      contextManager,
+      interval.start,
+      interval.end + 1,
+      forcedServerId,
+    ));
+  }
+  return {
+    intervals: merged,
+    refs: dedupeDiscordRefs(refs),
+    messageCount: merged.reduce((sum, interval) => sum + interval.end - interval.start + 1, 0),
+  };
+}
+
+function collectDiscordRefs(
+  contextManager: ContextManager,
+  start: number,
+  end: number,
+  forcedServerId?: string,
+): DiscordAwarenessRef[] {
+  const refs: DiscordAwarenessRef[] = [];
+  for (let offset = start; offset < end; offset += RECOVERY_SCAN_WINDOW) {
+    const messages = contextManager.getMessageWindow(
+      offset,
+      Math.min(RECOVERY_SCAN_WINDOW, end - offset),
+      { resolveBlobs: false },
+    ).messages;
+    refs.push(...extractDiscordAwarenessRefs(messages, forcedServerId));
+  }
+  // A sharded message may repeat Discord metadata across adjacent records.
+  return dedupeDiscordRefs(refs);
+}
+
+function dedupeDiscordRefs(refs: DiscordAwarenessRef[]): DiscordAwarenessRef[] {
+  const deduped = new Map<string, DiscordAwarenessRef>();
+  for (const ref of refs) {
+    deduped.set(`${ref.serverId}\0${ref.channelId}\0${ref.messageId}`, ref);
+  }
+  return [...deduped.values()];
+}

package/src/recovery/recover-cli.ts

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+import { createOfflineRecoveryBranch } from './offline-branch.js';
+
+interface CliOptions {
+  storePath?: string;
+  agentName?: string;
+  messageId?: string;
+  contextId?: string;
+  messages?: number;
+  suppressMessageIds: string[];
+  suppressRanges: Array<{ fromMessageId: string; toMessageId: string }>;
+  branchName?: string;
+  namespace?: string;
+  discordServerId?: string;
+  outboxPath?: string;
+  emoji?: string;
+  dryRun: boolean;
+}
+
+function usage(): string {
+  return `Usage:
+  agent-framework-recover --store <path> --agent <name> <anchor> [options]
+
+Creates and activates a Chronicle recovery branch while the normal host is down,
+then queues Discord reactions for addressable messages removed from awareness.
+Message content is never compiled or written to the recovery outbox.
+
+Options:
+  --message-id <id|link>      Last Discord message the agent should still see
+  --context-id <internal-id>  Exact internal context message to retain as anchor
+  --messages <count>          Legacy alternative: remove N context entries
+  --suppress <id|link>        Suppress one Discord message; repeat or comma-separate
+  --suppress-range <a>..<b>   Suppress an inclusive context range; repeatable
+  --branch <name>             Recovery branch name (generated by default)
+  --namespace <namespace>     Context namespace (default: agents/<agent>)
+  --discord-server <id>       Override/inject the Discord MCPL server id
+  --outbox <path>             Override the branch-independent outbox path
+  --emoji <emoji>             Marker reaction (default: 💤)
+  --dry-run                   Inspect counts/addresses without writing
+  --help                      Show this help
+
+The agent host must be stopped before running this command.`;
+}
+
+function parseArgs(args: string[]): CliOptions {
+  const options: CliOptions = { dryRun: false, suppressMessageIds: [], suppressRanges: [] };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const value = () => {
+      const next = args[++i];
+      if (!next) throw new Error(`${arg} requires a value`);
+      return next;
+    };
+    switch (arg) {
+      case '--store': options.storePath = value(); break;
+      case '--agent': options.agentName = value(); break;
+      case '--message-id':
+      case '--message': options.messageId = value(); break;
+      case '--context-id': options.contextId = value(); break;
+      case '--messages': options.messages = Number(value()); break;
+      case '--suppress':
+      case '--suppress-message':
+        options.suppressMessageIds.push(...value().split(',').map((item) => item.trim()).filter(Boolean));
+        break;
+      case '--suppress-range': {
+        const raw = value();
+        const separator = raw.indexOf('..');
+        if (separator <= 0 || separator >= raw.length - 2) {
+          throw new Error('--suppress-range must be formatted as <first>..<last>');
+        }
+        options.suppressRanges.push({
+          fromMessageId: raw.slice(0, separator),
+          toMessageId: raw.slice(separator + 2),
+        });
+        break;
+      }
+      case '--branch': options.branchName = value(); break;
+      case '--namespace': options.namespace = value(); break;
+      case '--discord-server': options.discordServerId = value(); break;
+      case '--outbox': options.outboxPath = value(); break;
+      case '--emoji': options.emoji = value(); break;
+      case '--dry-run': options.dryRun = true; break;
+      case '--help':
+      case '-h':
+        console.log(usage());
+        process.exit(0);
+      default: throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2));
+  if (
+    !options.storePath
+    || !options.agentName
+    || (!options.messageId && !options.contextId && options.messages === undefined)
+  ) {
+    throw new Error(`--store, --agent, and one anchor (--message-id, --context-id, or --messages) are required\n\n${usage()}`);
+  }
+
+  const result = await createOfflineRecoveryBranch({
+    storePath: options.storePath,
+    agentName: options.agentName,
+    messageId: options.messageId,
+    contextId: options.contextId,
+    messages: options.messages,
+    suppressMessageIds: options.suppressMessageIds,
+    suppressRanges: options.suppressRanges,
+    branchName: options.branchName,
+    namespace: options.namespace,
+    discordServerId: options.discordServerId,
+    outboxPath: options.outboxPath,
+    emoji: options.emoji,
+    dryRun: options.dryRun,
+  });
+
+  console.log(JSON.stringify({
+    ...result,
+    // Keep the output useful for ops without ever exposing message content.
+    refs: result.refs.map(({ serverId, channelId, messageId }) => ({ serverId, channelId, messageId })),
+  }, null, 2));
+}
+
+main().catch((error) => {
+  console.error(`[agent-framework-recover] ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});

package/src/types/agent.ts

@@ -2,6 +2,12 @@ import type { ContentBlock, YieldingStream } from '@animalabs/membrane';
 import type { ContextStrategy } from '@animalabs/context-manager';
 import type { ToolCallId, ToolResult, ToolCall } from './events.js';
 
+export type SameRoundThinkTextPolicy = 'public' | 'private';
+export type SameRoundThinkTextPolicySource =
+  | 'runtime_override'
+  | 'recipe'
+  | 'compatibility_default';
+
 /**
  * Configuration for an agent.
  */
@@ -65,6 +71,11 @@ export interface AgentConfig {
   /** Provider-specific request parameters (for example Responses reasoning
    * and server-side compaction settings). */
   providerParams?: Record<string, unknown>;
+  /**
+   * Same-round routing policy for ordinary text emitted beside `think`.
+   * Omitted preserves the compatibility carry-forward: public.
+   */
+  sameRoundThinkTextPolicy?: SameRoundThinkTextPolicy;
   /**
    * Extended thinking config. When `enabled: true`, the agent runs with
    * Anthropic's native extended thinking; responses include `thinking` blocks
@@ -104,9 +115,42 @@ export interface AgentConfig {
      * than dropping it silently. Default true.
      */
     announceHumanTurns?: boolean;
+    /**
+     * Primary-lane autobiographical summary refusal fallback. Disabled by
+     * default: when enabled, the framework may compare the refused primary
+     * request against the latest compatible healthy request on the same branch
+     * generation, expand newly admitted summary pairs back to exact raw
+     * source, and issue at most one retry.
+     */
+    primarySummaryFallback?: {
+      enabled?: boolean;
+      maxNewSummaries?: number;
+      requestBudgetTokens?: number;
+    };
   };
 }
 
+/** The intentionally small set of agent settings that may change in-process. */
+export interface AgentRuntimeSettingsPatch {
+  contextBudgetTokens?: number;
+  tailTokens?: number;
+  transitionPaceTokens?: number;
+  sameRoundThinkTextPolicy?: SameRoundThinkTextPolicy;
+}
+
+export interface AgentRuntimeSettingsSnapshot {
+  contextBudgetTokens: number;
+  tailTokens?: number;
+  transitionPaceTokens?: number;
+  sameRoundThinkTextPolicy: SameRoundThinkTextPolicy;
+  sameRoundThinkTextPolicySource: SameRoundThinkTextPolicySource;
+  transition: 'stable' | 'converging' | 'blocked';
+  transitionReason?: 'transition_pace_too_small' | 'protected_context_exceeds_target';
+}
+
+/** Persisted values differ from recipe defaults; omitted keys inherit config. */
+export type AgentRuntimeSettingsOverrides = AgentRuntimeSettingsPatch;
+
 /**
  * Result of running inference.
  */