@animalabs/agent-framework 0.33.0 → 0.34.0

package/src/agent.ts

@@ -35,6 +35,7 @@ import {
   truncateForHistory,
   DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS,
 } from './tool-result-history.js';
+import { appendAll } from './append-all.js';
 
 export interface ActivationRequestOptions {
   /** The silent heartbeat tick this request answers, if any. */
@@ -112,6 +113,11 @@ export interface StartStreamResult {
    *  far in sent order, with this request's head (context-manager's `noteRequestSent`). Present only where the
    *  model binds its thinking and the context manager keeps a record it can be told of. */
   noteRequestSent?: (rows: readonly SentRow[]) => boolean;
+  /** Tells the context manager which stored bodies' thinking the provider dropped from a call of this stream, by the
+   *  ids `placeDrops` gives for a `reply` drop, with the compile the stream was built from (context-manager's
+   *  `noteThinkingDropped`), so, once the context manager takes the note, its record leaves them without their
+   *  thinking from the next compile on. Present only where `noteRequestSent` is. */
+  noteThinkingDropped?: (messageIds: readonly MessageId[]) => boolean;
   /** The stored bodies the request's compile carried, by each body's first message id (its provenance's raw bodies).
    *  Absent when the compile reports no provenance. */
   carriedBodies?: ReadonlySet<MessageId>;
@@ -435,6 +441,7 @@ export class Agent {
    * the next change.
    */
   private liveBudgetEpoch = 0;
+  private contextSettingsChangeCount = 0;
   /**
    * Counts changes of the descent (each arm of one, the same target included,
    * a reset, a cancel, a settle). A settle proves its target only to a
@@ -696,7 +703,19 @@ export class Agent {
     if (typeof manager.updateHotContextSettings !== 'function') {
       throw new Error('The active context strategy does not support live context settings');
     }
-    return manager.updateHotContextSettings(update);
+    const settings = (s: HotContextSettingsStatus | null) =>
+      JSON.stringify([s?.tailTokens, s?.transitionPaceTokens, s?.preparedWindowTokens]);
+    const before = settings(this.getHotContextSettings());
+    const status = manager.updateHotContextSettings(update);
+    if (settings(status) !== before) this.contextSettingsChangeCount++;
+    return status;
+  }
+
+  /** How many times the live budget, its descent target or the hot context
+   *  settings have changed.
+   *  @internal For the framework's budget holds; not a host API. */
+  contextSettingsChanges(): number {
+    return this.contextSettingsChangeCount;
   }
 
   getRuntimeSettings(): AgentRuntimeSettingsSnapshot {
@@ -763,6 +782,7 @@ export class Agent {
   private setContextBudget(budget: number | undefined, target: number | undefined, armed = false): void {
     if (budget !== this.contextBudgetTokens) this.liveBudgetEpoch++;
     if (armed || target !== this.contextBudgetTargetTokens) this.descentEpoch++;
+    if (budget !== this.contextBudgetTokens || target !== this.contextBudgetTargetTokens) this.contextSettingsChangeCount++;
     this.contextBudgetTokens = budget;
     this.contextBudgetTargetTokens = target;
   }
@@ -802,7 +822,7 @@ export class Agent {
       return await this.compileAtLiveBudgetNoting(compile, started);
     } finally {
       this.compilesRunning.delete(started);
-      const earliest = Math.min(...this.compilesRunning);
+      const earliest = [...this.compilesRunning].reduce((min, start) => Math.min(min, start), Infinity);
       for (const [budget, start] of this.latestEndedStart) {
         if (start < earliest) this.latestEndedStart.delete(budget);
       }
@@ -1582,8 +1602,8 @@ export class Agent {
   /**
    * A host's hook, called with each committing compile's `thinkingStrip` (never a dry run's) and the key of the
    * branch it read (`branchKey`), as the compile returns, whether or not its request is then sent, since the
-   * context manager's binding record takes the strip either way. One that throws is logged. The framework sets none
-   * of its own, and tells the agent nothing of a strip.
+   * context manager's binding record takes the strip either way. One that throws is logged. It is observational only;
+   * the framework does not write agent-facing reasoning-loss notices.
    */
   onThinkingStrip?: (strip: ThinkingStrip, branch: string) => void;
 
@@ -1611,12 +1631,9 @@ export class Agent {
   unsentInjection(namespace: string): { contentHash: string; whole: boolean } | undefined {
     let newest: { contentHash: string; parts: number; held: Set<number> } | undefined;
     try {
-      const branch = branchKey(this.contextManager.currentBranchRef());
-      const since = this.unsentSince.get(branch);
+      const since = this.unsentSince.get(branchKey(this.contextManager.currentBranchRef()));
       if (since === undefined) {
-        const count = this.contextManager.getMessageCount();
-        const top = count > 0 ? this.contextManager.getMessageWindow(count - 1, 1, { resolveBlobs: false }).messages[0]?.sequence ?? 0 : 0;
-        this.unsentSince.set(branch, top);
+        this.markUnsentPoint();
         return undefined;
       }
       scan: for (let end = this.contextManager.getMessageCount(); end > 0;) {
@@ -1652,6 +1669,42 @@ export class Agent {
     return newest && { contentHash: newest.contentHash, whole: newest.held.size === newest.parts };
   }
 
+  /** Set the unsent point where it isn't set, as a start's plan does: a row
+   *  stored after it counts as in no request until a compile built to send.
+   *  @internal For the framework's budget holds; not a host API. */
+  markUnsentPoint(): void {
+    const branch = branchKey(this.contextManager.currentBranchRef());
+    if (this.unsentSince.has(branch)) return;
+    const count = this.contextManager.getMessageCount();
+    const top = count > 0 ? this.contextManager.getMessageWindow(count - 1, 1, { resolveBlobs: false }).messages[0]?.sequence ?? 0 : 0;
+    this.unsentSince.set(branch, top);
+  }
+
+  /** The ids of this agent's stored injections, of every namespace, stored
+   *  on its branch since its last compile built to send and in its window
+   *  where it's presented, in the record's order, a sharded body's first
+   *  shard first: the rows unsentInjection counts, which no request has
+   *  carried. Reads only, so an unset point gives none. */
+  unsentInjectionRows(): MessageId[] {
+    const ids: MessageId[] = [];
+    const since = this.unsentSince.get(branchKey(this.contextManager.currentBranchRef()));
+    if (since === undefined) return ids;
+    const presented = this.contextManager.windowMode?.() === 'presented';
+    scan: for (let end = this.contextManager.getMessageCount(); end > 0;) {
+      const span = Math.min(end, 64);
+      const { messages } = this.contextManager.getMessageWindow(end - span, span, { resolveBlobs: false });
+      for (let i = messages.length - 1; i >= 0; i--) {
+        const row = messages[i]!;
+        if (row.sequence <= since) break scan;
+        if (storedInjectionMarkOf(row.metadata)?.agent !== this.name) continue;
+        if (presented && this.contextManager.windowStatusOf(row.id) !== 'in') continue;
+        ids.push(row.id);
+      }
+      end -= span;
+    }
+    return ids.reverse();
+  }
+
   /** Record which of this agent's stored injections a compile built to send
    *  rendered. Another agent's stored rows never reach this agent's compile,
    *  since every compile of a shared store leaves them out by its view
@@ -1925,7 +1978,7 @@ export class Agent {
       // inferring, sends the same ones.
       unguardedResults ??= this._state.status === 'ready' && !guardedResults
         ? this.buildToolResultMessages(this._state.toolResults) : [];
-      messages.push(...unguardedResults);
+      appendAll(messages, unguardedResults);
       return {
         messages: this.toolResultGuard.prepareRequest(messages, true),
         system: this.buildSystemPrompt(systemInjections),
@@ -2268,9 +2321,10 @@ export class Agent {
     return { ...own, blockBinding: { prefixMismatchBehavior: 'drop_block' } };
   }
 
-  /** The stream's way to tell the context manager what its later rounds sent, with the head its compile was given:
-   *  where the agent's model binds its thinking (context-manager's `noteRequestSent`). */
-  private requestNotes(binding: BindingCompileOptions, compiled: CompiledForRequest): Pick<StartStreamResult, 'noteRequestSent'> {
+  /** The stream's way to tell the context manager what its later rounds sent, with the head its compile was given,
+   *  and which stored bodies' thinking the provider dropped: where the agent's model binds its thinking
+   *  (context-manager's `noteRequestSent` and `noteThinkingDropped`). */
+  private requestNotes(binding: BindingCompileOptions, compiled: CompiledForRequest): Pick<StartStreamResult, 'noteRequestSent' | 'noteThinkingDropped'> {
     const identity = binding.identity;
     // Each note names the compile the stream was built from, so a note can't vouch for this stream under a record a
     // later committing compile with binds wrote. A compile that reports no provenance gives the stream nothing to name, and the
@@ -2278,7 +2332,10 @@ export class Agent {
     const compileId = compiled.provenance?.compileId;
     if (!identity || compileId === undefined) return {};
     const cm = this.contextManager;
-    return { noteRequestSent: (rows) => cm.noteRequestSent(rows, identity, compileId) };
+    return {
+      noteRequestSent: (rows) => cm.noteRequestSent(rows, identity, compileId),
+      noteThinkingDropped: (messageIds) => cm.noteThinkingDropped(messageIds, compileId),
+    };
   }
 
   /**

package/src/append-all.ts

@@ -0,0 +1,6 @@
+/** `into.push(...items)` passes each item as a call argument, and V8 throws a
+ *  RangeError past about 125,000 arguments, so this pushes them one at a
+ *  time. */
+export function appendAll<T>(into: T[], items: readonly T[]): void {
+  for (let i = 0, n = items.length; i < n; i++) into.push(items[i]!);
+}

package/src/context-options.ts

@@ -19,7 +19,7 @@
  *   (heldFromResidents), what a suppress rule hid (suppressedRow), and the
  *   other residents' stored context injections (isAnotherAgentsInjection):
  *   their context, which they share the slot with it but never its
- *   conversation.
+ *   conversation. Both views also omit legacy reasoning-loss notices.
  * - The subconscious keeps its rows in a slot of its own,
  *   `subconscious/<serves>`, and reads the residents' slot beside it
  *   (`auxiliaryMessageViews: [{}]`), held traffic included, which is what it
@@ -27,7 +27,7 @@
  *   window by its observe edge's rule, and the merged slot is still the
  *   record its window is presented from. Its view leaves out only the
  *   residents' stored context injections and what a suppress rule hid,
- *   which renders for no reader, this one included. Its strategy is a windowed
+ *   in this shared view, along with legacy notices. Its strategy is a windowed
  *   passthrough, anchored at the oldest active tune-out's start, or at an
  *   earlier start kept in force: a cancelled tune-out's, kept while another
  *   stays active and across a restart, until the next enter sets the oldest
@@ -37,6 +37,7 @@
  * a strategy keeps state for the manager it is opened with.
  */
 import { WindowedPassthroughStrategy, type ContextManagerConfig, type StoredMessage } from '@animalabs/context-manager';
+import { isReasoningLoss } from './reasoning-loss.js';
 import { heldFromResidents, suppressedRow } from './dendrite/audience.js';
 import { persistentReaderName } from './tune-out/tools.js';
 import { isAnotherAgentsInjection } from './stored-injections.js';
@@ -44,17 +45,26 @@ import { isAnotherAgentsInjection } from './stored-injections.js';
 /** ContextManager.open's options over a store the caller gives: everything but the store. */
 export type ContextManagerOpenOptions = Omit<Extract<ContextManagerConfig, { store: unknown }>, 'store'>;
 
-/** What a resident's view leaves out: held traffic, suppressed rows, and another agent's stored context injections. */
-export function residentViewFilter(name: string): (message: StoredMessage) => boolean {
+/** A resident's view: no held traffic, suppressed rows, foreign injections or legacy notices.
+ * Supports both a reusable named predicate and a direct metadata-only probe. */
+export function residentViewFilter(message: Pick<StoredMessage, 'metadata'>, name: string): boolean;
+export function residentViewFilter(name: string): (message: Pick<StoredMessage, 'metadata'>) => boolean;
+export function residentViewFilter(messageOrName: Pick<StoredMessage, 'metadata'> | string, name?: string): boolean | ((message: Pick<StoredMessage, 'metadata'>) => boolean) {
+  if (typeof messageOrName !== 'string') return residentViewFilter(name!)(messageOrName);
   return (message) => !heldFromResidents(message.metadata as Record<string, unknown> | undefined)
     && !suppressedRow(message.metadata as Record<string, unknown> | undefined)
-    && !isAnotherAgentsInjection(message.metadata, name);
+    && !isAnotherAgentsInjection(message.metadata, messageOrName)
+    && !isReasoningLoss(message.metadata);
 }
 
-/** What the subconscious's view leaves out: the residents' stored context injections and suppressed rows, and nothing it reads for. */
-export function subconsciousViewFilter(name: string): (message: StoredMessage) => boolean {
+/** The subconscious includes held traffic, but not suppressed rows, foreign injections or legacy notices. */
+export function subconsciousViewFilter(message: Pick<StoredMessage, 'metadata'>, name: string): boolean;
+export function subconsciousViewFilter(name: string): (message: Pick<StoredMessage, 'metadata'>) => boolean;
+export function subconsciousViewFilter(messageOrName: Pick<StoredMessage, 'metadata'> | string, name?: string): boolean | ((message: Pick<StoredMessage, 'metadata'>) => boolean) {
+  if (typeof messageOrName !== 'string') return subconsciousViewFilter(name!)(messageOrName);
   return (message) => !suppressedRow(message.metadata as Record<string, unknown> | undefined)
-    && !isAnotherAgentsInjection(message.metadata, name);
+    && !isAnotherAgentsInjection(message.metadata, messageOrName)
+    && !isReasoningLoss(message.metadata);
 }
 
 /** The options a resident named `agentName` is opened with: the residents' slot, through its view. The caller gives its strategy. */

package/src/cut-off-round.ts

@@ -45,10 +45,10 @@ export function cutOffRound(response: NormalizedResponse): CutOffRound | undefin
 }
 
 /**
- * Membrane 0.8.0's grammar (unchanged from 0.7.2) for the anthropic-xml
- * formatter's XML tool mode. Membrane exports two of its predicates,
- * hasUnclosedToolBlock and endsWithPartialToolBlock, but not the grammar
- * itself (dist/utils/tool-parser.js, INVOKE_REGEX): a block opens
+ * Membrane 0.8.0's and 0.9.0's grammar (unchanged from 0.7.2) for the
+ * anthropic-xml formatter's XML tool mode. Membrane exports two of its
+ * predicates, hasUnclosedToolBlock and endsWithPartialToolBlock, but not the
+ * grammar itself (dist/utils/tool-parser.js, INVOKE_REGEX): a block opens
  * with `<function_calls>` and each call with `<invoke name="…">`, either tag
  * optionally `antml:` prefixed, and a closer ends the innermost block still
  * open. Its parser takes spans out of an unclosed block's text, which leaves

package/src/dendrite/registry.ts

@@ -23,6 +23,7 @@ import type {
   ObserveEdge,
   RegistrySnapshot,
 } from './types.js';
+import { appendAll } from '../append-all.js';
 
 /** Thrown for a spec the registry refuses to load. */
 export class AgentSpecError extends Error {
@@ -619,8 +620,9 @@ export class AgentRegistry {
       if (!this.live.has(child.name)) continue; // ended by an earlier cascade
       if (child.onParentEnd === 'end') {
         const inner = this.endRecursive(child, 'parent-ended', record.name);
-        cascaded.push(...inner.cascaded, inner.ended);
-        orphaned.push(...inner.orphaned);
+        appendAll(cascaded, inner.cascaded);
+        cascaded.push(inner.ended);
+        appendAll(orphaned, inner.orphaned);
       } else {
         const candidates = adopters.filter((candidate) => candidate !== child.name);
         child.orphaned = { since: this.now(), formerParent, reason, candidates };

package/src/failure-text.ts

@@ -0,0 +1,88 @@
+import { MembraneError } from '@animalabs/membrane';
+import { OverBudgetError, UncoveredDropError } from '@animalabs/context-manager';
+import { isDeadlineCut } from './inference-bounds.js';
+
+/**
+ * Longest failure text the inference-failure pipeline writes to one sink: the
+ * reason in the exhaustion stderr line, a field of a logs/failures.log record,
+ * an ops alert's message, the inference log's `error`, and a trace event's
+ * `error` and `stack`. A failure's text is whatever its source put in
+ * `Error.message`, and a provider can echo the entire rejected request there
+ * (one OpenAI-compatible 400 echoed ~1.7 MB). The sinks with shorter bounds
+ * name their own, and every cut goes through boundFailureText. This bound
+ * doesn't depend on membrane bounding its own errors.
+ */
+export const FAILURE_TEXT_MAX_CHARS = 2_000;
+
+/** Longest provider error code recorded verbatim; real codes are short tokens.
+ *  A failure's name and type are bounded the same way. */
+export const PROVIDER_ERROR_CODE_MAX_CHARS = 128;
+
+const isHighSurrogate = (text: string, index: number): boolean => {
+  const code = text.charCodeAt(index);
+  return code >= 0xd800 && code <= 0xdbff;
+};
+const isLowSurrogate = (text: string, index: number): boolean => {
+  const code = text.charCodeAt(index);
+  return code >= 0xdc00 && code <= 0xdfff;
+};
+/** Whether a cut before `index` would separate the halves of a surrogate pair. */
+const splitsPair = (text: string, index: number): boolean =>
+  index > 0 && index < text.length && isHighSurrogate(text, index - 1) && isLowSurrogate(text, index);
+
+/**
+ * `text` when it fits within `max` characters; otherwise its head and tail
+ * around a marker stating how many of how many characters were omitted, the
+ * whole within `max`. A cut that would separate a surrogate pair moves toward
+ * omission, so the result never holds half of a pair the text held whole, and
+ * bounding bounded text returns it as is. Each sink cuts the whole text, so
+ * its marker states the whole length.
+ */
+export function boundFailureText(text: string, max: number = FAILURE_TEXT_MAX_CHARS): string {
+  if (text.length <= max) return text;
+  const markerLength = ` …[${text.length} of ${text.length} characters omitted]… `.length;
+  const budget = Math.max(0, max - markerLength);
+  const tailLength = Math.floor(budget / 4);
+  let headEnd = budget - tailLength;
+  if (splitsPair(text, headEnd)) headEnd--;
+  let tailStart = text.length - tailLength;
+  if (splitsPair(text, tailStart)) tailStart++;
+  return `${text.slice(0, headEnd)} …[${tailStart - headEnd} of ${text.length} characters omitted]… ${text.slice(tailStart)}`;
+}
+
+/**
+ * A MembraneError, from this framework's copy of membrane or from another: the
+ * host supplies the Membrane instance (config.membrane), so with two copies
+ * installed its errors are instances of a class this framework's `instanceof`
+ * doesn't match. Recognised by name as well, as context-manager's errors are;
+ * its fields are the same, so callers still check each one's type.
+ */
+export function isMembraneError(error: unknown): error is MembraneError {
+  return error instanceof MembraneError || (error instanceof Error && error.name === 'MembraneError');
+}
+
+export function compileRefusalType(err: Error): 'over_budget' | 'context_refusal' | undefined {
+  if (err instanceof OverBudgetError || err.name === 'OverBudgetError') return 'over_budget';
+  // context-manager's fatal coverage invariant (fix/coverage-invariant-fatal,
+  // 2026-07-26): a compile REFUSES rather than shipping a context with
+  // silently-dropped messages. Recovery is identical to over_budget — kick
+  // the compression drain so summaries cover the un-represented span.
+  if (err instanceof UncoveredDropError || err.name === 'UncoveredDropError') return 'context_refusal';
+  return undefined;
+}
+
+export function houseReason(err: Error): string | undefined {
+  return isDeadlineCut(err) || compileRefusalType(err) !== undefined ? String(err.message) : undefined;
+}
+
+export function failureWords(err: Error, otherwise = 'the turn failed'): string {
+  const own = houseReason(err);
+  if (own !== undefined) return own;
+  if (!isMembraneError(err)) return otherwise;
+  if (err.type === 'safety') return "the request couldn't be completed";
+  const status = typeof err.httpStatus === 'number' ? `HTTP ${err.httpStatus}` : undefined;
+  if (err.type === 'timeout') return `the model call timed out${status ? ` (${status})` : ''}`;
+  const type = typeof err.type === 'string' ? boundFailureText(err.type, PROVIDER_ERROR_CODE_MAX_CHARS) : undefined;
+  const parts = [type, status].filter((part): part is string => part !== undefined);
+  return `the model call failed${parts.length > 0 ? ` (${parts.join(', ')})` : ''}`;
+}