@animalabs/agent-framework 0.26.1 → 0.27.0

package/src/sent-rows.ts

@@ -0,0 +1,162 @@
+import type { ContentBlock, ToolResult as MembraneToolResult } from '@animalabs/membrane';
+import type { MessageId } from '@animalabs/context-manager';
+import { isDeepStrictEqual } from 'node:util';
+
+import { withoutTokenEstimates } from './thinking-token-stamp.js';
+
+/**
+ * A row a stream's later round carried after its compiled messages, as a context manager that keeps a
+ * thinking-binding record is told of it (`noteRequestSent`): the id of a stored body the next request carries as
+ * the stream sent it, or the marker for one it doesn't, after which nothing keeps its thinking.
+ */
+export type SentRow = MessageId | { unstored: true };
+
+const UNSTORED: SentRow = Object.freeze({ unstored: true as const });
+
+/**
+ * Whether a request carries a block: the sanitize pass leaves out an empty or whitespace text block, which the
+ * Anthropic API refuses (assembleActivationRequest). The `typeof` guard is runtime defense: history loaded from
+ * disk can carry a non-string `text` despite what the types claim.
+ */
+export function carriedBlock(block: ContentBlock): boolean {
+  return !(block.type === 'text' && (typeof block.text !== 'string' || block.text.trim() === ''));
+}
+
+/**
+ * A stored body's content as the agent's next request carries it: what the sanitize pass leaves of it, without
+ * the framework's pricing stamp. Null when the pass leaves nothing, so the request carries no message there.
+ */
+export function asNextRequestCarries(content: readonly ContentBlock[]): ContentBlock[] | null {
+  const kept = content.filter(carriedBlock);
+  if (kept.length === 0) return null;
+  return withoutTokenEstimates([{ content: kept }])[0]!.content;
+}
+
+/**
+ * Whether a block of what a stream sent counts in the comparison. membrane's native formatter leaves out an exactly
+ * empty text block, which the API refuses. An empty text block carrying a provider-native item (`rawItem`) it sends
+ * as that item where it's a server-tool block it knows, in an assistant turn, and leaves out otherwise; whitespace
+ * text it sends, behind the participant's name where a multiuser conversation shows names. The next request's
+ * sanitize pass leaves both out, so both count as differences. Where membrane, or the adapter's cleanup (whitespace in
+ * an assistant turn), leaves one out of both requests, that's a needless strip rather than a row named for bytes the
+ * provider didn't see.
+ */
+function sentBlock(block: ContentBlock): boolean {
+  if (block.type !== 'text' || block.text !== '') return true;
+  const raw = (block as { rawItem?: unknown }).rawItem;
+  return raw !== null && typeof raw === 'object';
+}
+
+/** A block's own cache marker left out: the provider's thinking binding doesn't count it, nor does the context
+ *  manager's record, and stored history can carry a stale one. */
+function withoutCacheMarker(block: ContentBlock): unknown {
+  if (!('cache_control' in block) && !('cacheControl' in block)) return block;
+  const { cache_control: _snake, cacheControl: _camel, ...rest } = block as ContentBlock & { cache_control?: unknown; cacheControl?: unknown };
+  return rest;
+}
+
+/** A value as JSON writes it: a non-finite number as null, and undefined, a function or a symbol as nothing
+ *  (undefined here), which an object leaves out and an array writes as null. */
+function asJson(value: unknown): unknown {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  return value === undefined || typeof value === 'function' || typeof value === 'symbol' ? undefined : value;
+}
+
+/** Whether JSON writes an object by walking it: an array, or a plain object without its own `toJSON`. */
+function walkable(value: object): boolean {
+  if (Array.isArray(value)) return true;
+  const proto = Object.getPrototypeOf(value);
+  return (proto === Object.prototype || proto === null) && typeof (value as { toJSON?: unknown }).toJSON !== 'function';
+}
+
+/**
+ * Blocks equal as JSON data, as the store keeps them and a request sends them: equal where `JSON.stringify` writes
+ * them alike, key order aside. So a non-finite number is null; a field whose value is undefined, a function or a
+ * symbol is absent; such an array element, or a hole, is null; and anything else an object can be (a Date, a Buffer)
+ * is compared as JSON writes it. It walks plain objects and arrays rather than serializing them, since a note compares
+ * every row of the stream so far, base64 images and long tool results included, at each boundary.
+ */
+export function sameData(a: unknown, b: unknown): boolean {
+  const left = asJson(a);
+  const right = asJson(b);
+  if (left === right) return true;
+  const unwalked = (value: unknown) => typeof value === 'object' && value !== null && !walkable(value);
+  if (unwalked(left) || unwalked(right)) {
+    return isDeepStrictEqual(JSON.parse(JSON.stringify(left) ?? 'null'), JSON.parse(JSON.stringify(right) ?? 'null'));
+  }
+  if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) return false;
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false;
+    for (let i = 0; i < left.length; i++) {
+      if (!sameData(asJson(left[i]) ?? null, asJson(right[i]) ?? null)) return false;
+    }
+    return true;
+  }
+  const l = left as Record<string, unknown>;
+  const r = right as Record<string, unknown>;
+  const keys = Object.keys(l).filter((key) => asJson(l[key]) !== undefined);
+  return keys.length === Object.keys(r).filter((key) => asJson(r[key]) !== undefined).length
+    && keys.every((key) => Object.hasOwn(r, key) && asJson(r[key]) !== undefined && sameData(l[key], r[key]));
+}
+
+/** What membrane builds a round's results message from: each submitted result as a `tool_result` block. */
+function submittedBlocks(results: readonly MembraneToolResult[]): ContentBlock[] {
+  return results.map((result) => ({
+    type: 'tool_result',
+    toolUseId: result.toolUseId,
+    content: result.content,
+    isError: result.isError === true,
+  }) as ContentBlock);
+}
+
+/** One stored row of a round, beside what the stream sent in its place. */
+export type RoundRow =
+  | { kind: 'reply'; id: MessageId | undefined; sent: readonly ContentBlock[] }
+  | { kind: 'results'; id: MessageId | undefined; sent: readonly MembraneToolResult[] }
+  | { kind: 'injected'; id: MessageId | undefined; participant: string; sent: readonly ContentBlock[] };
+
+/**
+ * A round's rows as noted: each stored row's id where the next request carries it as the stream sent it, the
+ * marker where it doesn't. `carried` gives each id's stored body as the next compile renders it (participant and
+ * content, or null where no compile can send it), so the comparison is the one the context manager's record
+ * makes, after the agent's own request passes (asNextRequestCarries). A row the store doesn't hold (no id), a reply
+ * that differs from the round's content as membrane held it, results that differ from those submitted (as while the
+ * tool-result guard holds a batch, storing placeholders and submitting the originals), or an injected message sent
+ * otherwise than its stored body renders, is the marker. Called again over the same rows once the store has
+ * changed, as when the guard's batch settles to the originals, it gives each row's verdict as of then.
+ */
+export function roundRows(
+  rows: readonly RoundRow[],
+  carried: (id: MessageId) => { participant: string; content: ContentBlock[] } | null,
+): SentRow[] {
+  return rows.map((row): SentRow => {
+    if (row.id === undefined) return UNSTORED;
+    const body = carried(row.id);
+    const content = body ? asNextRequestCarries(body.content) : null;
+    if (!body || !content) return UNSTORED;
+    // What the stream sent, as membrane's native formatter sends it (sentBlock): an exactly empty text block is in
+    // neither request.
+    const sent = row.kind === 'results' ? submittedBlocks(row.sent) : row.sent.filter(sentBlock);
+    const sameParticipant = row.kind !== 'injected' || body.participant === row.participant;
+    const sameContent = row.kind === 'results'
+      ? sameData(content.map(normalizedResult), sent.map(normalizedResult))
+      : sameData(content.map(withoutCacheMarker), sent.map(withoutCacheMarker));
+    return sameParticipant && sameContent ? row.id : UNSTORED;
+  });
+}
+
+/**
+ * A results block as compared: what a request sends of it, its id, content and error flag, with `isError` as a
+ * boolean, where a stored block may leave a false one out. A stream's envelope sends a submitted result's
+ * `is_error: false` and the next request, from the stored block, sends none; the provider's thinking binding takes
+ * the two alike (read from the provider on 2026-10-23: Haiku 5.5 with the drop control, on an enforcing API-key
+ * organization and on a subscription account, reported no drop for either, and dropped both replies' blocks when an
+ * earlier user message changed). The store's own fields beside them, such as
+ * `toolName`, don't reach the provider on membrane's native path, the only one noted (membrane 0.7.1's XML
+ * formatter reads `toolName`, and an XML stream is never noted).
+ */
+function normalizedResult(block: ContentBlock): unknown {
+  if (block.type !== 'tool_result') return block;
+  const { toolUseId, content, isError } = block as { toolUseId?: unknown; content?: unknown; isError?: unknown };
+  return { type: 'tool_result', toolUseId, content, isError: isError === true };
+}

package/src/silent-heartbeat.ts

@@ -7,19 +7,22 @@
  * - A silent heartbeat tick stores no prompt row (#216): its reply is written
  *   straight after whatever the window held before it — often the previous
  *   assistant message, since a suppressed tick leaves no delivery receipt
- *   behind. Every row a tick writes is stamped with `metadata.silentHeartbeat`,
- *   and a separator carrying the tick's instruction is rendered before the
- *   first of the tick's rows that survives compilation.
+ *   behind. Every row the tick's reply writes is stamped with
+ *   `metadata.silentHeartbeat`, and a separator carrying the tick's
+ *   instruction is rendered before the first of those rows that survives
+ *   compilation. A context injection its start stores (stored-injections.ts)
+ *   is unstamped: it's history the agent saw, not the tick's speech, so a
+ *   policy that drops a tick's rows leaves it.
  * - A compile that ends on the agent's own message gets a trailing
  *   `[Continue]` turn (some models reject a trailing assistant message). The
  *   reply it prompts is stored straight after that message, so the reply's
  *   rows are stamped `metadata.promptedBy` (`RequestOnlyPrompt`), and the turn
  *   is rendered before the first of them that survives. A reply follows the
  *   prompt when what it was sent ends on that `[Continue]`, or on the tool
- *   results of a reply that followed it (`toolLoopPrompt`): a stream start
- *   and each round of a stream alike. A reply sent anything else after the
- *   results (a message that arrived meanwhile) follows that, and carries no
- *   prompt.
+ *   results of a reply that followed it (`toolLoopPrompt`), stored context
+ *   injections after those results aside: a stream start and each round of
+ *   a stream alike. A reply sent anything else after the results (a message
+ *   that arrived meanwhile) follows that, and carries no prompt.
  *
  * Without the row, the wire formatter merges consecutive same-role messages:
  * the reply would read as an unprompted continuation of the earlier response,
@@ -75,9 +78,13 @@ export interface SilentHeartbeatTick {
   serverId: string;
 }
 
-/** `metadata.silentHeartbeat` on every row a tick's turn writes. Residents
- * share one message slot, so the stamp names the agent whose turn wrote it
- * (tool_result rows are stored as `user`). */
+/** `metadata.silentHeartbeat` on the rows of a tick's own turn (its reply,
+ * tool results and their wrappers). What the framework stores of its own
+ * accord is left unstamped, a clock row (at the turn's start or a tool
+ * boundary) or a context injection, so a retention policy that drops a
+ * tick's rows keeps it. Residents share one message
+ * slot, so the stamp names the agent whose turn wrote it (tool_result rows
+ * are stored as `user`). */
 export interface SilentHeartbeatStamp extends SilentHeartbeatTick {
   agentName: string;
   /** The separator text the tick's request rendered, which later compiles

package/src/stable-hash.ts

@@ -0,0 +1,14 @@
+import { createHash } from 'node:crypto';
+
+/** A SHA-256 of `value` that doesn't depend on its objects' key order. */
+export function stableHash(value: unknown): string {
+  const encode = (item: unknown): string => {
+    if (Array.isArray(item)) return `[${item.map(encode).join(',')}]`;
+    if (item && typeof item === 'object') {
+      const record = item as Record<string, unknown>;
+      return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${encode(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(item) ?? 'null';
+  };
+  return createHash('sha256').update(encode(value)).digest('hex');
+}

package/src/stored-injections.ts

@@ -0,0 +1,131 @@
+/**
+ * Context injections kept where they were placed (context-manager #155,
+ * part 5).
+ *
+ * `compile()` places an `afterUser` injection after the last user message
+ * each time it runs, and nothing stores it. So at the next start, a new turn
+ * or a restart after a tool result, it's gone from where the agent's replies
+ * saw it, and on a model that binds a reply's thinking to everything before
+ * it, every reply after the old place loses its thinking. A moved injection
+ * also rewrites the previous turn's cached prefix. So at each start that
+ * sends, the framework appends each `afterUser` injection to the agent's own
+ * window, as the message `compile()` would have placed, unless the copy the
+ * agent will read as current (the one its last request held, or a newer one
+ * a start stored whose compile then didn't record) has the same content,
+ * every part of it, and the compile
+ * then renders
+ * it from the store like any message, where it stays. While the window is
+ * held (AgentFramework's slotHeldFrom), `compile()` places it instead. Being a
+ * message, it's history to the strategy: capped by its per-message bound,
+ * sharded, selected by the budget and folded like any other.
+ *
+ * A stored injection's row carries `system: true`, `kind:
+ * 'context-injection'` and `contextInjection` in its metadata (the mark),
+ * naming the agent whose context it is and its source's namespace, so a
+ * reader can tell it from conversation, and so another agent reading the
+ * same slot leaves it out (AgentFramework's view filters). All three are
+ * keys only the host writes.
+ */
+
+import type { ContextInjection } from '@animalabs/context-manager';
+import { stableHash } from './stable-hash.js';
+import { injectionsAsStored } from './text-as-stored.js';
+
+/** The metadata key a stored injection's row is marked with. */
+export const STORED_INJECTION_KEY = 'contextInjection';
+
+/** The `kind` a stored injection's row carries beside `system: true`, as the
+ *  framework's other rows of its own do (a clock row, a notice). */
+export const STORED_INJECTION_KIND = 'context-injection';
+
+/**
+ * The mark: whose context the row is, its source's namespace, a hash of the
+ * content its source gave at that start (the unit), in its stored form
+ * (unitHash), and which of the unit's `parts` injections the row holds
+ * (`part`, from 0). Every row of one injection, a sharded one's too, carries
+ * the same `part`.
+ */
+export interface StoredInjectionMark {
+  agent: string;
+  namespace: string;
+  contentHash: string;
+  part: number;
+  parts: number;
+}
+
+/** The participant `compile()` gives an injection it places, which a stored
+ *  one keeps, so it renders as the placed one did. */
+export function injectionParticipant(namespace: string): string {
+  return `system_context:${namespace}`;
+}
+
+/**
+ * A stored injection's mark, read from a row's metadata, so a host's reader
+ * tells a stored injection from conversation by the rule the framework's own
+ * views use. Undefined for a row with no mark, and for one whose mark isn't
+ * whole (a string `agent`, `namespace` and `contentHash`, and integer
+ * `part` and `parts` with 0 <= part < parts): no view of the framework's
+ * treats such a row as a stored injection, so neither should a host's.
+ */
+export function storedInjectionMarkOf(metadata: unknown): StoredInjectionMark | undefined {
+  const mark = (metadata as Record<string, unknown> | undefined)?.[STORED_INJECTION_KEY];
+  if (mark === null || typeof mark !== 'object') return undefined;
+  const { agent, namespace, contentHash, part, parts } = mark as Record<string, unknown>;
+  return typeof agent === 'string' && typeof namespace === 'string' && typeof contentHash === 'string'
+    && Number.isInteger(part) && Number.isInteger(parts) && (part as number) >= 0 && (part as number) < (parts as number)
+    ? { agent, namespace, contentHash, part: part as number, parts: parts as number }
+    : undefined;
+}
+
+/** Whether a row is another agent's stored injection, which `agentName`'s
+ *  view leaves out: it's that agent's context, not conversation. */
+export function isAnotherAgentsInjection(metadata: unknown, agentName: string): boolean {
+  const mark = storedInjectionMarkOf(metadata);
+  return mark !== undefined && mark.agent !== agentName;
+}
+
+/**
+ * Whether an injection is stored, rather than placed by `compile()` each
+ * time: an `afterUser` one, unless it opts out
+ * (ModuleContextInjection.placedEachCompile). Only a module's can: an MCPL
+ * server's is built from four fields alone (convertMcplInjection), so it
+ * never carries the field.
+ */
+export function isStoredKind(injection: ContextInjection): boolean {
+  return injection.position === 'afterUser'
+    && (injection as { placedEachCompile?: unknown }).placedEachCompile !== true;
+}
+
+/**
+ * Whether content leaves anything in a request: a block that isn't a text
+ * block, or a text block with non-blank text, as the request's sanitizer
+ * keeps (Agent's assembleActivationRequest drops blank text blocks, and a
+ * message left with none). An injection with none isn't stored: its row
+ * would vanish from every request, and the count of stored rows the
+ * request ends on, which keeps [Continue] last, would then be wrong.
+ * compile() places it, and the sanitizer drops it, as before.
+ */
+export function hasRenderedContent(content: ContextInjection['content']): boolean {
+  return Array.isArray(content) && content.some((block) =>
+    !((block as { type?: unknown }).type === 'text'
+      && (typeof (block as { text?: unknown }).text !== 'string' || ((block as { text: string }).text).trim() === '')));
+}
+
+/** One injection as its row would store it: its namespace as text (as
+ *  compile() writes it into the participant's name, so one that isn't a
+ *  string, an MCPL server's number or none, is read so), that participant,
+ *  and its content in the stored form (injectionsAsStored), as the compile
+ *  would have taken it. The store's write would mend the content the same
+ *  way; the namespace, which the mark carries too, it wouldn't. */
+export function asStoredRow(injection: ContextInjection): { namespace: string; participant: string; content: ContextInjection['content'] } {
+  const [stored] = injectionsAsStored([injection])!;
+  const namespace = `${stored!.namespace}`;
+  return { namespace, participant: injectionParticipant(namespace), content: stored!.content };
+}
+
+/** The hash of a unit's content in its stored form, which the same-content
+ *  skip compares: the mark's, from the gather that stored the unit, with
+ *  this gather's. */
+export function unitHash(rows: ReadonlyArray<{ content: ContextInjection['content'] }>): string {
+  return stableHash(rows.map((r) => r.content));
+}

package/src/text-as-stored.ts

@@ -4,9 +4,10 @@
  * request compiles comes from the store, which writes a lone UTF-16
  * surrogate as U+FFFD, and a provider refuses a request carrying one (#695).
  * Two things reach a request without the store, and each is made well formed
- * where it leaves for it: context injections, as an Agent compiles them into
- * a request, and the copies a tool boundary injects into the live round, as
- * they go to the stream.
+ * where it leaves for it: context injections compile() places (those not
+ * stored, stored-injections.ts), as an Agent compiles them into a request,
+ * and the copies a tool boundary injects into the live round, as they go to
+ * the stream. A stored injection takes the same form before it's stored.
  */
 
 import type { ContentBlock } from '@animalabs/membrane';

package/src/thinking-drops.ts

@@ -0,0 +1,141 @@
+import type { ContentBlock, NormalizedMessage, ThinkingBindingEntry } from '@animalabs/membrane';
+import type { CompileProvenance, MessageId } from '@animalabs/context-manager';
+
+/**
+ * Where a block the provider dropped (membrane's `RoundReport.thinking.dropped`) came from.
+ *
+ * - `reply`: a block of a stored reply the compile rendered. `bodies` are the stored bodies that compiled message
+ *   was rendered from (`CompileProvenance`'s raw bodies), each by the id `addMessage` returned for it and its
+ *   sequence (a body kept in shards is one, by its first shard): usually one. Where the block's signature is in
+ *   more than one compiled message, it's every one of theirs, since the block alone can't tell them apart.
+ * - `round`: a block of a round this stream appended itself (the entry's `round`), which no compile holds.
+ * - `unplaced`: membrane couldn't place it, or it names a block this request didn't send from a stored reply:
+ *   an injected message's, one whose compiled message has no raw body (a summary), or one whose signature no
+ *   compiled block carries.
+ */
+export type PlacedDrop =
+  | { kind: 'reply'; bodies: Array<{ messageId: MessageId; sequence: number }>; entry: ThinkingBindingEntry }
+  | { kind: 'round'; round: number; entry: ThinkingBindingEntry }
+  | { kind: 'unplaced'; entry: ThinkingBindingEntry };
+
+/**
+ * What a request was assembled from: the compile's messages as it returned them, its provenance, and, when the
+ * compile gave one, the sequence at or below which a reply was stored before the branch's thinking-binding record
+ * began (context-manager's `CompileResult.thinkingRecordedAfter`, where it keeps a thinking-binding record).
+ */
+export interface CompiledForRequest {
+  messages: readonly NormalizedMessage[];
+  provenance?: CompileProvenance;
+  recordedAfter?: number;
+}
+
+/** What a stream's driver reads a call's dropped blocks against (`StartStreamResult`'s two fields, together). */
+export interface StreamThinkingDrops {
+  place: (entries: readonly ThinkingBindingEntry[]) => PlacedDrop[];
+  recordedAfter?: number;
+}
+
+/** A signed block's identity on the wire: a thinking block's signature, a redacted block's data. */
+function bindingKey(block: ContentBlock | undefined): string | undefined {
+  const b = block as { type?: unknown; signature?: unknown; data?: unknown } | undefined;
+  if (b?.type === 'thinking' && typeof b.signature === 'string' && b.signature.length > 0) return `s:${b.signature}`;
+  if (b?.type === 'redacted_thinking' && typeof b.data === 'string' && b.data.length > 0) return `d:${b.data}`;
+  return undefined;
+}
+
+/**
+ * Place each dropped entry of one call. membrane places a block by the request's message and the block's
+ * index in it; the request holds copies of the compile's messages (the sanitize pass, `withoutTokenEstimates`,
+ * the request-only rows and `prepareRequest` each copy or move them), so the block is found again in the
+ * compile by its signature (or a redacted block's data), which every copy keeps, and the compiled message's
+ * provenance names the stored reply.
+ */
+export function placeThinkingDrops(
+  entries: readonly ThinkingBindingEntry[],
+  sent: readonly NormalizedMessage[],
+  compiled: CompiledForRequest,
+): PlacedDrop[] {
+  let byKey: Map<string, number[]> | undefined;
+  const compiledIndexes = (key: string): number[] => {
+    if (!byKey) {
+      byKey = new Map();
+      compiled.messages.forEach((message, i) => {
+        for (const block of message.content) {
+          const k = bindingKey(block);
+          if (k === undefined) continue;
+          const at = byKey!.get(k);
+          if (!at) byKey!.set(k, [i]);
+          else if (at.at(-1) !== i) at.push(i);
+        }
+      });
+    }
+    return byKey.get(key) ?? [];
+  };
+  return entries.map((entry): PlacedDrop => {
+    if (entry.round !== undefined) return { kind: 'round', round: entry.round, entry };
+    if (entry.message === undefined || entry.block === undefined) return { kind: 'unplaced', entry };
+    const key = bindingKey(sent[entry.message]?.content[entry.block]);
+    const bodies: Array<{ messageId: MessageId; sequence: number }> = [];
+    for (const at of key === undefined ? [] : compiledIndexes(key)) {
+      const source = compiled.provenance?.messages[at];
+      // A candidate with no stored body (a summary's) can't be placed, so neither can the block.
+      if (source?.kind !== 'raw' || source.bodies.length === 0) return { kind: 'unplaced', entry };
+      for (const body of source.bodies) bodies.push({ messageId: body.messageId, sequence: body.sequence });
+    }
+    if (bodies.length === 0) return { kind: 'unplaced', entry };
+    return { kind: 'reply', bodies, entry };
+  });
+}
+
+/**
+ * A call's placed drops against the branch's binding-record start (`thinkingRecordedAfter`). Expected: a block of a
+ * stored reply whose every body sits at or below it, minted before the context manager recorded what the branch
+ * sent, so the provider may drop its thinking with no strip having missed; and a drop for a binding the record
+ * doesn't track, the account's organization or end user (`organization_binding_mismatch`,
+ * `end_user_binding_mismatch`). Unexpected: everything else, which the record doesn't account for: a reply above
+ * the start, a block of the stream's own rounds, or one that couldn't be placed, for a conversation or model
+ * mismatch or a reason not known here.
+ */
+export function splitThinkingDrops(
+  placed: readonly PlacedDrop[],
+  recordedAfter: number,
+): { expected: PlacedDrop[]; unexpected: PlacedDrop[] } {
+  const expected: PlacedDrop[] = [];
+  const unexpected: PlacedDrop[] = [];
+  for (const drop of placed) {
+    const before = drop.kind === 'reply' && drop.bodies.every((body) => body.sequence <= recordedAfter);
+    (before || UNTRACKED_REASONS.has(drop.entry.reason) ? expected : unexpected).push(drop);
+  }
+  return { expected, unexpected };
+}
+
+/** Binding failures the context manager's record doesn't track: the account's, not the conversation's. */
+const UNTRACKED_REASONS = new Set(['organization_binding_mismatch', 'end_user_binding_mismatch']);
+
+/**
+ * When an agent's unexpected drops call for an operator alert: at the first call that shows any, and again only
+ * when a call shows more than the alert last counted. Each call of a stream, and each stream until a strip takes
+ * them out, drops the same blocks again, so an unchanged count isn't news. A call that shows no unexpected drop, its
+ * report empty, absent or naming only expected ones, ends the incident: the blocks it counted no longer drop. The next
+ * one alerts afresh. It's held in memory, so a restart mid-incident alerts once more, and an agent's removal ends its
+ * incident (`forget`).
+ */
+export class ThinkingLossIncidents {
+  private readonly alerted = new Map<string, number>();
+
+  /** A call's report of `unexpected` drops for `agent`: the count to alert with, or undefined for no alert. */
+  observe(agent: string, unexpected: number): number | undefined {
+    if (unexpected === 0) {
+      this.alerted.delete(agent);
+      return undefined;
+    }
+    if (unexpected <= (this.alerted.get(agent) ?? 0)) return undefined;
+    this.alerted.set(agent, unexpected);
+    return unexpected;
+  }
+
+  /** The agent is gone: its incident, if one is open, ends with it. */
+  forget(agent: string): void {
+    this.alerted.delete(agent);
+  }
+}

package/src/tool-image-ledger.ts

@@ -327,10 +327,10 @@ export interface StoredCut {
  * Where a tool result's text longer than `cap` is cut: by its stored copy
  * (cutStoredToolResult), by history's own truncation (truncateForHistory),
  * and by its live copy, for each text block beside an image
- * (tryNativeToolResultContent, framework.ts), so at one cap the stored copy
- * and the live copy cut alike. Under a readers' bound the stored copy's cut
- * can come earlier (cutStoredToolResultToFit). The text's length when it
- * isn't longer than `cap`.
+ * (toMembraneToolResult's nativeContent, framework.ts), so at one cap the
+ * stored copy and the live copy cut alike. Under a readers' bound the stored
+ * copy's cut can come earlier (cutStoredToolResultToFit). The text's length
+ * when it isn't longer than `cap`.
  *
  * The cut is made at the cap, or before it when the cap would split a
  * surrogate pair (safeSlice's rule), and that is where the moves back are
@@ -367,10 +367,11 @@ export function toolResultCutAt(text: string, cap: number): number {
  *
  * `shown` is what the live copy showed beside the stored text: null when the
  * live copy was the text itself, as for every result that carried no inline
- * image. Then what the cut keeps is exactly what the resident saw, and
- * nothing past it is kept (#403). A result that carried an inline image went
- * to the model as native blocks (tryNativeToolResultContent, framework.ts),
- * every image whatever the text's length, so its stored text is the only
+ * image, or whose links and markers came to more than the cap together, so
+ * goesNative said no.
+ * Then what the cut keeps is exactly what the resident saw, and nothing past
+ * it is kept (#403). A result whose live copy went to the model as native
+ * blocks (framework.ts) sent every image whatever the text's length, so its stored text is the only
  * place save_recent_image's inventory finds them, and a slot dropped by the
  * cut would be an image the resident saw that the index slides past (#104).
  * The image slots past the cut that lie wholly within what the live copy

package/src/tool-presentation.ts

@@ -124,7 +124,9 @@ function documentProblems(doc: unknown, descriptionsOnly: boolean): string[] {
 
 function parseDocument(raw: string, descriptionsOnly: boolean): PresentationDocument {
   let doc: unknown;
-  try { doc = JSON.parse(raw); }
+  // Some Windows editors save UTF-8 with a leading U+FEFF, which read() keeps
+  // and JSON.parse refuses; drop exactly one, as parseGateJson does (#758).
+  try { doc = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw); }
   catch (error) { throw new PresentationFileError([`it isn't valid JSON: ${errorMessage(error)}`]); }
   // An object with no keys carries no settings, so it's the empty document,
   // as a missing resident file is: it's what an operator writes by hand to

package/src/tool-result-guard.ts

@@ -4,7 +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 { ensureStateRegistered } from './module-registry.js';
-import { rfc005TextOf, toolResultDataToHistoryString } from './tool-result-history.js';
+import { classifyBlock } from './mcpl/references.js';
+import { resultClaimsOf, rfc005TextOf, 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.';
@@ -90,7 +91,9 @@ export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean
  * inline cap or less (storeResults' keptCap), 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
+ * (agent-framework #277), one whose claims can't be read whole
+ * (resultClaimsOf), or one whose data is MCP's embedded resource, whose
+ * fields can't be kept apart from its contents or its uri. 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.
  */
@@ -99,13 +102,23 @@ export function keptWhenWithheld(result: CompletedToolCall['result'], maxChars:
   if (!result.success || result.isError || !keys?.length || !data || typeof data !== 'object' || Array.isArray(data)) {
     return undefined;
   }
+  // MCP's embedded resource is its contents: shown as text, it's the very
+  // body the guard withheld, and a field picked out of it, such as
+  // `resource`, is data that shows its uri. So it keeps nothing.
+  if (classifyBlock(data).kind === 'embedded') return undefined;
   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;
   // Data that RFC-005 shows as text, such as a reference's stub, keeps that
   // text: picked out of it, a kept uri would lose the type that makes it a
   // reference, and be written out of the stub that hides it.
-  const whole = rfc005TextOf(fields) ?? toolResultDataToHistoryString(kept);
+  // The kept fields are shown as the whole result claims (resultClaimsOf), so
+  // a never elsewhere in it still withholds a kept link's uri. Where a value
+  // stops that walk, such as a getter that throws, which the audit's JSON
+  // doesn't read, what the rest claims is unknown, and nothing is kept.
+  const claims = resultClaimsOf(fields);
+  if (claims === null) return undefined;
+  const whole = rfc005TextOf(fields) ?? toolResultDataToHistoryString(kept, undefined, { claims });
   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.
@@ -500,7 +513,7 @@ 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 it has a
-   * writable mount without an include to take it, else kept in the audit
+   * writable mount without an include, not configured direct, to take 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
@@ -599,8 +612,8 @@ export class ToolResultGuard {
               if (block.type !== 'tool_result') return [];
               if (thrown.has(index)) return [{ toolUseId: block.toolUseId, error: thrown.get(index)! }];
               const spill = spills.get(index) ?? null;
-              // No file was written: no writable mount without an include,
-              // or the framework was stopping.
+              // No file was written: no writable mount without an include
+              // that isn't configured direct, or the framework was stopping.
               if (spill === null) return [{ toolUseId: block.toolUseId, skipped: 'no_workspace_file' }];
               if ('skipped' in spill) return [{ toolUseId: block.toolUseId, skipped: spill.skipped }];
               return [{ toolUseId: block.toolUseId, path: spill.path,