@animalabs/agent-framework 0.22.0 → 0.22.2

package/src/recovery/offline-branch.ts

@@ -1,5 +1,6 @@
 import { JsStore } from '@animalabs/chronicle';
-import { ContextManager } from '@animalabs/context-manager';
+import { ContextManager, continuesBody, type BodyShard } from '@animalabs/context-manager';
+import { removeStoredInterval } from '../stored-removal.js';
 import {
   DEFAULT_DISCORD_AWARENESS_EMOJI,
   DiscordAwarenessOutbox,
@@ -202,11 +203,12 @@ export async function createOfflineRecoveryBranch(
     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.
+      // Each interval is removed by its messages' ids, so the order doesn't
+      // change the result. removeStoredInterval takes a single message outside
+      // any body through removeMessage, and a shard or a longer interval as a
+      // range, which refuses one that splits a body.
       for (const interval of [...suppression.intervals].reverse()) {
-        if (interval.fromId === interval.toId) contextManager.removeMessage(interval.fromId);
-        else contextManager.removeMessages(interval.fromId, interval.toId);
+        removeStoredInterval(contextManager, interval.fromId, interval.toId);
       }
       if (batch) outbox.activate(batch.id);
     } catch (error) {
@@ -238,9 +240,7 @@ interface SuppressionInterval {
 
 interface MessageLocation {
   first: number;
-  last: number;
   firstId: StoredWindowMessage['id'];
-  lastId: StoredWindowMessage['id'];
   /** Usually one run; multiple runs tolerate duplicate external metadata. */
   runs: SuppressionInterval[];
 }
@@ -299,14 +299,15 @@ function validateAnchorBoundary(
   total: number,
   target: StoredWindowMessage,
 ): void {
-  const groupId = (target as StoredWindowMessage & { bodyGroupId?: string }).bodyGroupId;
-  if (!groupId || targetIndex + 1 >= total) return;
+  if (targetIndex + 1 >= total) return;
   const next = contextManager.getMessageWindow(targetIndex + 1, 1, {
     resolveBlobs: false,
-  }).messages[0] as (StoredWindowMessage & { bodyGroupId?: string }) | undefined;
-  if (next?.bodyGroupId === groupId) {
+  }).messages[0];
+  // A body continues only into a later shard of the same ingestion: a
+  // reposted document shares its group id but starts a body of its own.
+  if (continuesBody(target as BodyShard, next as BodyShard | undefined)) {
     throw new Error(
-      `Recovery anchor ${String(target.id)} splits body group ${groupId}; choose its final shard.`,
+      `Recovery anchor ${String(target.id)} splits body group ${(target as BodyShard).bodyGroupId}; choose its final shard.`,
     );
   }
 }
@@ -321,7 +322,9 @@ function validateRemovalIntegrity(
     index >= interval.start && index <= interval.end);
   const toolUses = new Map<string, boolean>();
   const toolResults = new Map<string, boolean>();
-  const groupMembership = new Map<string, boolean>();
+  // The message before, in store order: a selection splits a body when a
+  // message continuing the one before it lands on the other side.
+  let previous: { message: BodyShard; removed: boolean } | null = null;
 
   for (let offset = 0; offset < total; offset += RECOVERY_SCAN_WINDOW) {
     const messages = contextManager.getMessageWindow(
@@ -332,16 +335,14 @@ function validateRemovalIntegrity(
     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);
+      const message = messages[i];
+      const shard = message as BodyShard;
+      if (previous && previous.removed !== isRemoved && continuesBody(previous.message, shard)) {
+        throw new Error(
+          `Recovery selection splits body group ${shard.bodyGroupId}; adjust the anchor or suppression boundary.`,
+        );
       }
+      previous = { message: shard, removed: 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') {
@@ -402,9 +403,7 @@ function buildSuppressionPlan(
         };
         locations.set(externalId, {
           first: index,
-          last: index,
           firstId: messages[i].id,
-          lastId: messages[i].id,
           runs: [run],
         });
       } else {
@@ -420,8 +419,6 @@ function buildSuppressionPlan(
             toId: messages[i].id,
           });
         }
-        location.last = index;
-        location.lastId = messages[i].id;
       }
     }
   }
@@ -444,12 +441,19 @@ function buildSuppressionPlan(
     const to = locations.get(range.toMessageId)!;
     const earlier = from.first <= to.first ? from : to;
     const later = from.first <= to.first ? to : from;
+    // What's between the two messages, after the earlier one began and
+    // before the later one began: from the earlier one's first stored copy
+    // through the later one's first. Each end is every copy of it besides,
+    // as a single suppression is, so a copy stored outside that span (a
+    // write cut short and retried later) is taken on its own, and nothing
+    // else stored after the later one began is taken.
     intervals.push({
       start: earlier.first,
-      end: later.last,
+      end: later.first,
       fromId: earlier.firstId,
-      toId: later.lastId,
+      toId: later.firstId,
     });
+    for (const end of [from, to]) intervals.push(...end.runs.map((run) => ({ ...run })));
   }
 
   intervals.sort((a, b) => a.start - b.start || a.end - b.end);

package/src/refusal-reactions.ts

@@ -1,17 +1,20 @@
 /**
  * Refusal-reaction markers — the single source of truth for the emoji the
  * framework places on a message when inference is refused (see
- * AgentFramework.reactToRefusal), exported so host composition can derive
- * a protective suppression baseline from the exact set the framework emits.
+ * AgentFramework.reactToRefusal).
  *
  * These annotations are placed by the framework on the resident's account
  * and must never re-enter a resident's context as reaction events — that is
  * the self-amplifying loop behind the 8/3 Mythos incident. The Discord
- * adapter suppresses them when its operator config or the host-injected
- * `DISCORD_SUPPRESSED_REACTIONS_BASELINE` names them; keeping the emitted
- * set and the exported baseline as one constant is what makes drift between
- * "what we stamp" and "what we suppress" structurally impossible, rather
- * than a promise kept in two files.
+ * adapter suppresses them when its operator config or
+ * `DISCORD_SUPPRESSED_REACTIONS_BASELINE` names them. That variable's
+ * protective default, which the framework injects into stdio children, is
+ * `framework.getPlacedReactionBaseline()` on an instance: these refusal
+ * markers plus the awareness markers. REFUSAL_REACTION_BASELINE below is the
+ * refusal set only. Keeping the emitted refusal set and the exported one as
+ * one constant is what makes drift between "what we stamp" and "what we
+ * suppress" structurally impossible, rather than a promise kept in two
+ * files.
  */
 
 /** Refusal category → Discord reaction emoji. Unknown categories get the
@@ -27,11 +30,10 @@ export const REFUSAL_REACTIONS: Readonly<Record<string, string>> = {
 /** Marker used when the refusal category has no dedicated emoji. */
 export const REFUSAL_REACTION_FALLBACK = '🛑';
 
-/** Every marker the framework can emit — the category map plus the
- *  fallback, deduplicated, in stable declaration order. This IS the
- *  protective baseline: host composition serializes it (comma-joined) into
- *  `DISCORD_SUPPRESSED_REACTIONS_BASELINE` for adapters that render
- *  reactions. */
+/** Every refusal marker the framework can emit: the category map plus the
+ *  fallback, deduplicated in stable declaration order. For the deployment's
+ *  complete protective default, including awareness markers, use
+ *  `framework.getPlacedReactionBaseline()` on an instance. */
 export const REFUSAL_REACTION_BASELINE: readonly string[] = [
   ...new Set([...Object.values(REFUSAL_REACTIONS), REFUSAL_REACTION_FALLBACK]),
 ];

package/src/stored-removal.ts

@@ -0,0 +1,126 @@
+import { bodyBoundsIn, type BodyShard, type ContextManager, type MessageId } from '@animalabs/context-manager';
+
+type StoredLike = BodyShard & { id: MessageId };
+type Removals = Pick<ContextManager, 'removeMessage' | 'removeMessages'>;
+
+/** Minimal read surface the live-surgery helpers need from a ContextManager. */
+export interface SurgeryReadableCm {
+  getMessageCount(): number;
+  getMessageWindow(
+    offset: number,
+    limit: number,
+    opts?: { resolveBlobs?: boolean; alignToBodyGroups?: boolean },
+  ): { messages: Array<{ id: unknown; bodyGroupId?: string }>; startIndex: number };
+}
+
+const SURGERY_SCAN_WINDOW = 500;
+
+/**
+ * Slot index of `messageId` on the active branch, or -1. Scans from the tail
+ * in blob-free windows: operator targets are almost always recent, and a
+ * full `getAllMessages()` re-inflates every attachment on the branch.
+ */
+export function locateMessageIndex(cm: SurgeryReadableCm, messageId: string): number {
+  const hit = locateMessageIndices(cm, new Set([messageId])).get(messageId);
+  return hit ? hit.index : -1;
+}
+
+/** Tail-first scan resolving many ids at once; stops as soon as all are found. */
+export function locateMessageIndices(
+  cm: SurgeryReadableCm,
+  ids: Set<string>,
+): Map<string, { index: number; bodyGroupId?: string }> {
+  const found = new Map<string, { index: number; bodyGroupId?: string }>();
+  const total = cm.getMessageCount();
+  for (let end = total; end > 0 && found.size < ids.size; end -= SURGERY_SCAN_WINDOW) {
+    const start = Math.max(0, end - SURGERY_SCAN_WINDOW);
+    const { messages, startIndex } = cm.getMessageWindow(start, end - start, { resolveBlobs: false });
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const id = String(messages[i].id);
+      if (ids.has(id) && !found.has(id)) {
+        found.set(id, {
+          index: startIndex + i,
+          ...(messages[i].bodyGroupId ? { bodyGroupId: messages[i].bodyGroupId } : {}),
+        });
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Inclusive slot range of the body-group run containing `index` (the slot
+ * itself when it is not sharded). Delegates to the store's own
+ * `alignToBodyGroups` edge walk — one contiguity assumption, not two.
+ */
+export function bodyGroupRun(
+  cm: SurgeryReadableCm,
+  index: number,
+): { from: number; to: number; fromId: string; toId: string; group: boolean } {
+  const win = cm.getMessageWindow(index, 1, { alignToBodyGroups: true, resolveBlobs: false });
+  const from = win.startIndex;
+  const to = win.startIndex + win.messages.length - 1;
+  return {
+    from,
+    to,
+    fromId: String(win.messages[0].id),
+    toId: String(win.messages[win.messages.length - 1].id),
+    group: win.messages[0].bodyGroupId !== undefined,
+  };
+}
+
+/**
+ * Remove the stored messages `first`..`last` (inclusive, in store order).
+ *
+ * A single message outside any body goes through `removeMessage`.
+ * context-manager's `removeMessage` refuses any message that carries a body
+ * group id, a one-shard body's included, so a shard, and any longer interval,
+ * goes through `removeMessages`, which refuses an interval that splits a
+ * body.
+ */
+export function removeStoredMessages(cm: Removals, first: StoredLike, last: StoredLike): void {
+  if (first.id === last.id && !first.bodyGroupId) {
+    cm.removeMessage(first.id);
+    return;
+  }
+  cm.removeMessages(first.id, last.id);
+}
+
+/**
+ * Remove one stored message by its id, with the rest of its body when it's
+ * in one: a module or a coalescer removes a message it added by the id
+ * `addMessage` returned, which for a long message stored in shards is its
+ * first shard's.
+ */
+export function removeStoredMessage(cm: ContextManager, id: MessageId): void {
+  const message = cm.getMessage(id) as StoredLike | null;
+  if (!message?.bodyGroupId) {
+    cm.removeMessage(id);
+    return;
+  }
+  // Found in blob-free windows: a full read of the branch would inflate every
+  // attachment on it, once for each message a sweep removes.
+  const index = locateMessageIndex(cm, String(id));
+  if (index < 0) {
+    cm.removeMessage(id);
+    return;
+  }
+  const run = bodyGroupRun(cm, index);
+  cm.removeMessages(run.fromId as MessageId, run.toId as MessageId);
+}
+
+/** removeStoredMessages for an interval known by its ids. */
+export function removeStoredInterval(cm: ContextManager, fromId: MessageId, toId: MessageId): void {
+  const first = cm.getMessage(fromId) as StoredLike | null;
+  removeStoredMessages(cm, first ?? { id: fromId }, { id: toId });
+}
+
+/**
+ * The first and last positions (inclusive) of the body that holds
+ * `messages[index]`, read the way context-manager 0.14.0 reads bodies
+ * (`continuesBody`, pairwise in store order). A message outside any body is a
+ * body of its own.
+ */
+export function bodyRangeIn(messages: readonly unknown[], index: number): { from: number; to: number } {
+  return bodyBoundsIn(messages as readonly (BodyShard | null | undefined)[], index);
+}

package/src/tool-result-guard.ts

@@ -4,6 +4,8 @@ import type { ContextManager, MessageId, MessageMetadata } from '@animalabs/cont
 import type { ContentBlock, NormalizedMessage, ToolResult } from '@animalabs/membrane';
 import type { CompletedToolCall } from './types/index.js';
 import { isStateExistsError } from './module-registry.js';
+import { toolResultDataToHistoryString } from './tool-result-history.js';
+import { safeSlice } from './safe-slice.js';
 
 export const TOOL_RESULT_GUARD_NOTICE = 'Tool result withheld by the guard. The tool has already executed.';
 export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
@@ -52,31 +54,60 @@ export interface WithheldHost {
 
 /**
  * The stub a withheld result settles to: #159's neutral notice, then where
- * the original is. It names no refusal and no category (#159 keeps those in
- * operational logs), only the place, so reading it back is the agent's
- * deliberate choice (agent-framework #277). The place holds the result as
- * stored, which for one over the inline cap is its capped text, whose own
- * note names the file with the whole output; so the stub says "its result",
- * not its full result. A failed write's own error text
- * stays in the audit record and the logs, not here. The audit
- * record is said to keep the original only when it was saved: a staged
- * record whose save failed is still queued in memory, and a restart before
- * its retry loses it.
+ * the original is, then, when its tool marked any, the fields kept from its
+ * result (`kept`, from keptWhenWithheld). It names no refusal and no
+ * category (#159 keeps those in operational logs), so reading the rest back
+ * is the agent's deliberate choice (agent-framework #277). The place holds
+ * the result as stored, which for one over the inline cap is its capped
+ * text, whose own note names the file with the whole output; so the stub
+ * says "its result", not its full result. A failed write's own error text
+ * stays in the audit record and the logs, not here. The audit record is
+ * said to keep the original only when it was saved: a staged record whose
+ * save failed is still queued in memory, and a restart before its retry
+ * loses it.
  */
-export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean): string {
+export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean, kept?: string): string {
   const audit = `the guard's audit record (${TOOL_RESULT_GUARD_AUDIT_STATE}), for an operator`;
-  const kept = (only: string) => auditDurable
+  const keptIn = (only: string) => auditDurable
     ? `is kept ${only}in ${audit}`
     : `went ${only}to ${audit}, though saving that record had failed when the result arrived`;
-  if (!spill || 'skipped' in spill) return `${TOOL_RESULT_GUARD_NOTICE} Its result ${kept('')}.`;
-  if (spill.unfinished) {
-    return `${TOOL_RESULT_GUARD_NOTICE} Its result was still being written to workspace file ${spill.path} ` +
-      `when this note was made; if that file is missing, it ${kept('')}.`;
-  }
-  if (spill.error === undefined) {
-    return `${TOOL_RESULT_GUARD_NOTICE} Its result is in workspace file ${spill.path}.`;
+  const place = !spill || 'skipped' in spill
+    ? `Its result ${keptIn('')}.`
+    : spill.unfinished
+      ? `Its result was still being written to workspace file ${spill.path} when this note was made; ` +
+        `if that file is missing, it ${keptIn('')}.`
+      : spill.error === undefined
+        ? `Its result is in workspace file ${spill.path}.`
+        : `Writing its result to workspace file ${spill.path} failed, so it ${keptIn('only ')}.`;
+  const fields = kept === undefined ? '' : ` Kept from its result: ${kept}`;
+  return `${TOOL_RESULT_GUARD_NOTICE} ${place}${fields}`;
+}
+
+/**
+ * What a withheld result's stub keeps of it: the fields of its data that its
+ * tool marked as saying what it acted on (ToolResult.keepWhenWithheld), in
+ * the order marked, serialized as a stored result is. Past the inline cap
+ * they're cut, with a note that says so and where the whole result is, since
+ * a later field can then be cut away entirely. Undefined when it keeps
+ * nothing, as for a failed result (agent-framework #277). A write's file
+ * list is evidence of what it did, rarely what drew a refusal, and keeping it
+ * is what shows a clobbered file when the receipt is withheld.
+ */
+export function keptWhenWithheld(result: CompletedToolCall['result'], maxChars: number | undefined): string | undefined {
+  const { data, keepWhenWithheld: keys } = result;
+  if (!result.success || result.isError || !keys?.length || !data || typeof data !== 'object' || Array.isArray(data)) {
+    return undefined;
   }
-  return `${TOOL_RESULT_GUARD_NOTICE} Writing its result to workspace file ${spill.path} failed, so it ${kept('only ')}.`;
+  const fields = data as Record<string, unknown>;
+  const kept = Object.fromEntries(keys.filter((key) => Object.hasOwn(fields, key)).map((key) => [key, fields[key]]));
+  if (Object.keys(kept).length === 0) return undefined;
+  const whole = toolResultDataToHistoryString(kept);
+  if (!maxChars || whole.length <= maxChars) return whole;
+  // Never half a surrogate pair: the stub goes to the provider as text, so
+  // the cut can be one character short of the cap.
+  const head = safeSlice(whole, 0, maxChars);
+  return `${head} [cut at the inline cap: ${head.length} of these fields' ${whole.length} ` +
+    'characters; the whole result is where this note says]';
 }
 
 interface PendingBatch {
@@ -89,6 +120,9 @@ interface PendingBatch {
   submitted: boolean;
   /** False when the audit sync failed: originals then never go on the wire. */
   durable: boolean;
+  /** What each result's stub keeps if the batch is withheld, by its index in
+   *  content: the fields its tool marked (keptWhenWithheld). */
+  kept: Map<number, string>;
 }
 
 interface AuditOperation {
@@ -280,11 +314,15 @@ export class ToolResultGuard {
       : JSON.parse(json);
   }
 
+  /** `inlineCap` is the cap the caller stored `content` under; what a stub
+   *  keeps of a withheld result is cut at it too. */
   storeResults(
     content: ContentBlock[],
     wireResults: ToolResult[],
     originals: CompletedToolCall[],
-    metadata?: MessageMetadata,
+    metadata: MessageMetadata | undefined,
+    /** The cap the results were stored under: what a stub keeps is cut there too. */
+    inlineCap: number | undefined,
   ): MessageId {
     if (!this.enabled) return this.cm.addMessage('user', content, metadata);
     if (this.pending) {
@@ -312,13 +350,22 @@ export class ToolResultGuard {
     const withheld: ContentBlock[] = content.map((block) => block.type === 'tool_result'
       ? { type: 'tool_result', toolUseId: block.toolUseId, content: TOOL_RESULT_GUARD_NOTICE, isError: block.isError }
       : block);
+    // What each stub keeps if the batch is withheld, matched to its tool's
+    // result by tool use id, keyed by index as the stubs and files are.
+    const results = new Map(originals.map((call) => [call.id, call.result]));
+    const kept = new Map<number, string>();
+    for (const [index, block] of content.entries()) {
+      const result = block.type === 'tool_result' ? results.get(block.toolUseId) : undefined;
+      const text = result ? keptWhenWithheld(result, inlineCap) : undefined;
+      if (text !== undefined) kept.set(index, text);
+    }
     // Compression hold (CM >= 0.12): placed BEFORE onNewMessage fires, so no
     // chunk is ever summarized from the placeholder; released after the
     // settlement edit. Holds are in-memory only — a reopened manager has none,
     // which is correct since a reopened guard has no pending batch.
     const messageId = this.cm.addMessage('user', withheld, metadata, undefined, { holdCompression: true });
     this.pending = { id, messageId, content, withheld, wireResults,
-      branch: this.cm.currentBranch().name, submitted: false, durable: false };
+      branch: this.cm.currentBranch().name, submitted: false, durable: false, kept };
     // Durability barrier: the audit must reach Chronicle's chain heads before
     // the originals can go to a provider. On a failed sync the batch fails
     // CLOSED: the placeholders go on the wire instead (the turn continues,
@@ -452,7 +499,8 @@ export class ToolResultGuard {
   /**
    * Turn a withheld batch's notices into stubs that say where each original
    * is (agent-framework #277): written to the workspace when a writable mount
-   * takes it, else kept in the audit record. Its own unedited placeholder is
+   * takes it, else kept in the audit record. A stub also keeps the file
+   * lists its tool marked. Its own unedited placeholder is
    * the only thing it edits: an operator's later edit, removal or rollback
    * stands.
    *
@@ -540,7 +588,7 @@ export class ToolResultGuard {
           spills.set(index, spill);
         }
         const annotated: ContentBlock[] = pending.withheld.map((block, index) => block.type === 'tool_result'
-          ? { ...block, content: withheldResultNotice(spills.get(index) ?? null, pending.durable) }
+          ? { ...block, content: withheldResultNotice(spills.get(index) ?? null, pending.durable, pending.kept.get(index)) }
           : block);
         try {
           this.append({

package/src/types/agent.ts

@@ -53,11 +53,14 @@ export interface AgentConfig {
   /**
    * The model's PHYSICAL context window (provider hard cap, e.g. 200000).
    * When set, the framework projects each continuation round's real size
-   * (cache-inclusive input of the prior round + the blocks about to be
-   * appended + reserve for response) and restarts the stream through a fresh
-   * compile instead of dispatching a request the provider will 400
-   * (issue #92: a legal compile can walk past the physical window mid-turn).
-   * Unset → no projection; only the maxStreamTokens restart applies.
+   * (cache-inclusive input of the latest call that reported its prompt +
+   * that call's output + what the stream has grown by since, if later calls
+   * reported none + the blocks about to be appended + reserve for response)
+   * and restarts the stream through a fresh compile instead of dispatching a
+   * request the provider will 400 (issue #92: a legal compile can walk past
+   * the physical window mid-turn). The projection runs once a call on the
+   * stream has reported its prompt. Unset → no projection; only the
+   * maxStreamTokens restart applies.
    */
   physicalWindowTokens?: number;
 
@@ -223,7 +226,20 @@ export interface AgentRuntimeSettingsPatch {
 }
 
 export interface AgentRuntimeSettingsSnapshot {
+  /**
+   * The budget the agent is set to: while a lower one converges, its target,
+   * and while a persisted one the agent couldn't apply is kept, that one.
+   */
   contextBudgetTokens: number;
+  /**
+   * The budget compiles plan at now: the live budget, or the default when the
+   * recipe sets none (the context manager's own default is the same). It
+   * equals `contextBudgetTokens` except while a lower budget converges, when
+   * it is still the budget the descent started from (context-manager #162),
+   * and while a budget the agent couldn't apply is kept, when it is the
+   * budget the agent runs at instead.
+   */
+  effectiveContextBudgetTokens: number;
   tailTokens?: number;
   transitionPaceTokens?: number;
   sameRoundThinkTextPolicy: SameRoundThinkTextPolicy;
@@ -233,7 +249,27 @@ export interface AgentRuntimeSettingsSnapshot {
 }
 
 /** Persisted values differ from recipe defaults; omitted keys inherit config. */
-export type AgentRuntimeSettingsOverrides = AgentRuntimeSettingsPatch;
+export type AgentRuntimeSettingsOverrides = AgentRuntimeSettingsPatch & {
+  /**
+   * The record's own `contextBudgetTokens`, written when a compile at the
+   * agent's live budget fits at it, with nothing about the budget changed
+   * while it ran (a paced descent's settle included): the store fit that
+   * budget. A compile the context manager refuses at it as over budget
+   * withdraws it, unless a compile at it that started later has already
+   * ended.
+   * When it equals `contextBudgetTokens`, a restore applies that budget at
+   * once, rather than pacing a descent again from the recipe's budget
+   * (context-manager #162), if a preview at boot says it still fits; if not,
+   * a budget below the recipe's restores paced, and if a compile at one that
+   * the boot applied at once is refused, the agent restores it paced then.
+   * Since the store fit it when the field was written, the planner can fold
+   * to it at once even if its carried frontier was lost. Any other value is
+   * stale (the budget changed since, or an earlier release carried the field
+   * forward), and a budget below the recipe's restores paced, as it does
+   * without the field. Never part of a patch.
+   */
+  contextBudgetReachedTokens?: number;
+};
 
 /**
  * Result of running inference.

package/src/types/events.ts

@@ -199,6 +199,18 @@ export interface ToolResult {
    * Adapted from Anarchid/agent-framework@mcpl-module-proto.
    */
   endTurn?: boolean;
+  /**
+   * Fields of `data` that say what the tool acted on, such as the paths a
+   * write wrote, removed or took from disk, the path it deleted, or a mount
+   * whose root it accepted, in the order they should be kept. When the
+   * tool-result guard withholds this result, these fields stay in its stub,
+   * so the agent still sees what the tool did; the result as stored goes
+   * where every withheld original goes (agent-framework #277). Past the
+   * inline cap they're cut, in this order, so a later field can be cut away
+   * entirely; put the short, telling ones first. Only data's own fields can
+   * be kept, and a failed result (success false) keeps nothing.
+   */
+  keepWhenWithheld?: string[];
 }
 
 /**

package/src/types/framework.ts

@@ -302,6 +302,10 @@ export interface ContextMaintenanceAgentRun {
   pendingAfter?: string;
   progressBefore?: Record<string, unknown>;
   progressAfter?: Record<string, unknown>;
+  /**
+   * The agent's failure in this pass: a tick that threw, or its readiness
+   * that couldn't be read, before the ticks or after them.
+   */
   error?: string;
 }
 
@@ -323,6 +327,12 @@ export interface ContextMaintenanceSnapshot {
     agentName: string;
     ready: boolean;
     pending?: string;
+    /**
+     * Why the agent's readiness can't be read: the context manager refuses
+     * while its strategy's initialization is pending or has failed, and a
+     * strategy can refuse on its own. `ready` is false then.
+     */
+    error?: string;
     progress?: Record<string, unknown>;
   }>;
 }

package/src/types/module.ts

@@ -217,14 +217,19 @@ export interface ModuleContext {
   getLogLength(name: string): number;
 
   /**
-   * Process queue for pushing events from external listeners.
+   * Process queue for pushing events from external listeners. Once stop()
+   * has begun, a push is dropped with a log line naming this module, as
+   * pushEvent()'s is.
    * @deprecated Use pushEvent() instead — it also emits process:received traces.
    */
   readonly queue: ProcessQueue;
 
   /**
    * Push a process event to the queue and emit a process:received trace.
-   * Preferred over direct queue.push() for proper observability.
+   * Preferred over direct queue.push() for proper observability. Once stop()
+   * has begun, nothing will process the event: it's dropped with a log line
+   * naming this module, untraced, rather than thrown into the listener or
+   * stop() that pushed it.
    */
   pushEvent(event: ProcessEvent): void;
 
@@ -316,10 +321,14 @@ export interface ModuleContext {
    *
    * Modules use this to react to agent lifecycle without polling — e.g. an
    * adapter that wants to show a "typing" indicator can bracket it between
-   * `inference:started` and the terminal events (`inference:turn_ended`,
-   * `inference:aborted`, `inference:failed`, `inference:exhausted`), all of
-   * which carry `agentName`. The terminal events fire once per turn, after any
-   * tool-call cycles, so a single start/stop bracket spans the whole turn.
+   * `inference:started` and the terminal events: `inference:completed` (the
+   * normal end), `inference:turn_ended` (a tool result ended the turn),
+   * `inference:aborted`, `inference:failed` and `inference:exhausted`, all of
+   * which carry `agentName`. A turn's tool-call cycles stay inside its
+   * stream, so one bracket spans them. A context-budget restart emits
+   * `inference:started` again with no terminal event for the stream it
+   * replaced, and a failing turn can emit `inference:failed` and then
+   * `inference:exhausted`, so a bracket should allow a repeated start or end.
    *
    * Returns an unsubscribe function. Call it in the module's `stop()` to avoid
    * leaking listeners across teardown/recreate (e.g. session switch).
@@ -370,14 +379,17 @@ export interface ProcessState {
   getActiveTools(): ToolDefinition[];
 
   /**
-   * Queue for emitting follow-up events.
+   * Queue for emitting follow-up events. Once stop() has begun, a push is
+   * dropped with a log line naming the module, as pushEvent()'s is.
    * @deprecated Use pushEvent() instead — it also emits process:received traces.
    */
   readonly queue: ProcessQueue;
 
   /**
    * Push a process event to the queue and emit a process:received trace.
-   * Preferred over direct queue.push() for proper observability.
+   * Preferred over direct queue.push() for proper observability. Once stop()
+   * has begun, the event is dropped with a log line naming the module,
+   * untraced.
    */
   pushEvent(event: ProcessEvent): void;
 }