@animalabs/agent-framework 0.32.0 → 0.34.0

package/src/dendrite/registry.ts

@@ -16,10 +16,14 @@ import type {
   AgentRecord,
   AgentRef,
   AgentSpec,
+  ContextInheritance,
   EndOutcome,
   HeldMail,
+  MessageSlotRef,
+  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 {
@@ -76,6 +80,123 @@ function clone<T>(value: T): T {
   return value === undefined ? value : (JSON.parse(JSON.stringify(value)) as T);
 }
 
+/** AgentRegistry.register's options (see there). */
+export interface RegisterOptions {
+  resume?: boolean;
+  after?: number;
+  declaredWith?: readonly AgentName[];
+}
+
+/** The residents' shared un-namespaced slot, on the host's current branch. */
+export const RESIDENTS_SLOT: Readonly<MessageSlotRef> = Object.freeze({ namespace: null });
+
+/** Whether two refs name one slot: the same namespace on the same branch. */
+export function sameSlot(a: MessageSlotRef | undefined, b: MessageSlotRef | undefined): boolean {
+  return !!a && !!b && a.namespace === b.namespace && a.branch === b.branch;
+}
+
+/**
+ * The slot an observe edge reads. An edge that names a slot reads that
+ * namespace on the host's current branch. One that names an agent and no
+ * slot reads that agent's own slot, wherever it is (a shared fork's is on its
+ * own branch), as `ownSlotOf` looks it up: undefined where the lookup doesn't
+ * know the agent, or none is given. The registry's `observedSlotOf` passes its
+ * records. An edge that names neither reads the residents' shared slot.
+ */
+export function observedSlot(
+  edge: ObserveEdge,
+  ownSlotOf?: (agent: AgentName) => MessageSlotRef | undefined,
+): MessageSlotRef | undefined {
+  if (edge.slot !== undefined) return { namespace: edge.slot };
+  if (edge.agent === undefined) return { namespace: null };
+  const own = ownSlotOf?.(edge.agent);
+  return own ? { namespace: own.namespace, ...(own.branch !== undefined ? { branch: own.branch } : {}) } : undefined;
+}
+
+/**
+ * The slot a shared derivation's own rows are stored in: the parent's
+ * message slot, as context-manager's derivation record names it, on the
+ * child's own branch. Undefined for any other inheritance, or one whose
+ * record doesn't say.
+ */
+function derivedSlot(inherit: ContextInheritance | undefined): MessageSlotRef | undefined {
+  if (inherit?.mode !== 'shared' || typeof inherit.ownBranch !== 'string') return undefined;
+  const slots = (inherit.derivation as { slots?: { messageNamespace?: unknown } } | undefined)?.slots;
+  const namespace = slots?.messageNamespace;
+  if (namespace !== null && typeof namespace !== 'string') return undefined;
+  return { namespace, branch: inherit.ownBranch };
+}
+
+/**
+ * The own slot a spec or record declares, or, where it declares none (one
+ * written before `ownSlot` existed), the slot it meant: the shared slot for
+ * one that reads that slot with no observe edge on it, which is how a
+ * resident was declared; a shared derivation's slot; else the isolated slot
+ * of its namespace. A subconscious declared its reading of the shared slot
+ * as an observe edge from the start (subconsciousSpec), so it reads as
+ * isolated, as it was opened. An edge on the shared slot here is one with
+ * no `slot`, whatever agent it names: when the flag was all there was, such
+ * an edge read the shared slot, and that is how withOwnSlot restores it, so
+ * a spec reads as the same record does when it is restored.
+ */
+function resolveOwnSlot(declared: {
+  ownSlot?: MessageSlotRef;
+  readsSharedSlot?: boolean;
+  observes?: ObserveEdge[];
+  inherit?: ContextInheritance;
+  namespace?: string;
+}): MessageSlotRef | undefined {
+  const own = declared.ownSlot;
+  if (own) return { namespace: own.namespace, ...(own.branch !== undefined ? { branch: own.branch } : {}) };
+  const derived = derivedSlot(declared.inherit);
+  if (derived) return derived;
+  if (declared.readsSharedSlot === true && !(declared.observes ?? []).some((edge) => edge.slot === undefined)) {
+    return { namespace: null };
+  }
+  return typeof declared.namespace === 'string' ? { namespace: declared.namespace } : undefined;
+}
+
+/** What a record's deprecated `readsSharedSlot` says: it owns the residents' slot or observes it. */
+function readsResidentsSlot(
+  ownSlot: MessageSlotRef | undefined,
+  observes: ObserveEdge[],
+  ownSlotOf: (agent: AgentName) => MessageSlotRef | undefined,
+): boolean {
+  return sameSlot(ownSlot, RESIDENTS_SLOT) || observes.some((edge) => sameSlot(observedSlot(edge, ownSlotOf), RESIDENTS_SLOT));
+}
+
+/**
+ * A restored record with its own slot: one written before `ownSlot` existed
+ * gets the slot its `readsSharedSlot`, observe edges, inheritance and
+ * namespace meant (resolveOwnSlot). Its `readsSharedSlot` is kept as written.
+ *
+ * Its observe edges are read as that code read them too: an edge with no
+ * `slot` read the residents' shared slot, whatever agent it named, so one
+ * naming an agent is restored without the name, an edge on the shared slot
+ * (which names neither), rather than one on that agent's own slot, which is
+ * what such an edge reads since own slots. A host that wants the agent's
+ * slot read declares the edge again (`{ agent }` in a spec now reads it).
+ */
+function withOwnSlot(record: AgentRecord): AgentRecord {
+  if (record.ownSlot !== undefined) return record;
+  const observes = record.relationships?.observes;
+  if (Array.isArray(observes)) {
+    record.relationships.observes = observes.map((edge) => {
+      if (edge.slot !== undefined || edge.agent === undefined) return edge;
+      const { agent: _named, ...onShared } = edge;
+      return onShared;
+    });
+  }
+  const ownSlot = resolveOwnSlot({
+    readsSharedSlot: record.readsSharedSlot,
+    observes: record.relationships?.observes,
+    inherit: record.inherit,
+    namespace: record.namespace,
+  });
+  if (ownSlot) record.ownSlot = ownSlot;
+  return record;
+}
+
 export class AgentRegistry {
   private readonly live = new Map<AgentName, AgentRecord>();
   /** Ended records, oldest first. */
@@ -128,19 +249,25 @@ export class AgentRegistry {
    * spawner's orphan, as if it had been live when the spawner ended.
    * `after` is the incarnation a resumption continues from: the new one is
    * past it, since the counter of a name that aged out of memory isn't kept.
+   * `declaredWith` names the agents declared with this one, such as a
+   * configuration's residents, which register one after another: an observe
+   * edge may name one of them before it is registered (two residents may
+   * observe each other). The edge reads that agent's slot once it is.
    */
-  register(spec: AgentSpec, options: { resume?: boolean; after?: number } = {}): AgentRecord {
+  register(spec: AgentSpec, options: RegisterOptions = {}): AgentRecord {
     return this.requested(() => this.registerUnguarded(spec, options));
   }
 
-  private registerUnguarded(spec: AgentSpec, options: { resume?: boolean; after?: number } = {}): AgentRecord {
-    this.validate(spec, options.resume === true);
+  private registerUnguarded(spec: AgentSpec, options: RegisterOptions = {}): AgentRecord {
+    this.validate(spec, options.resume === true, options.declaredWith ?? []);
     const previous = this.awaiting.get(spec.name);
     this.awaiting.delete(spec.name);
 
     const incarnation = Math.max(this.incarnations.get(spec.name) ?? 0, options.after ?? 0) + 1;
     this.incarnations.set(spec.name, incarnation);
 
+    const observes = (spec.observes ?? []).map((edge) => ({ ...edge }));
+    const ownSlot = resolveOwnSlot({ ...spec, observes });
     const record: AgentRecord = {
       name: spec.name,
       kind: spec.kind,
@@ -152,7 +279,7 @@ export class AgentRegistry {
       onParentEnd: spec.onParentEnd ?? 'orphan',
       relationships: {
         ...(spec.spawnedBy ? { spawnedBy: spec.spawnedBy } : {}),
-        observes: (spec.observes ?? []).map((edge) => ({ ...edge })),
+        observes,
         // Explicit message paths accumulate over an identity's life.
         messagePeers: previous ? [...previous.relationships.messagePeers] : [],
         ...(spec.resultTo ? { resultTo: { ...spec.resultTo } } : {}),
@@ -161,7 +288,10 @@ export class AgentRegistry {
       ...(spec.selfParticipants?.length ? { selfParticipants: [...spec.selfParticipants] } : {}),
       ...(spec.presentAs ? { presentAs: spec.presentAs } : {}),
       ...(spec.homeChannel ? { homeChannel: { serverId: spec.homeChannel.serverId, channelId: spec.homeChannel.channelId } } : {}),
-      readsSharedSlot: spec.readsSharedSlot ?? false,
+      ...(ownSlot ? { ownSlot } : {}),
+      // Kept for readers of the record from before the split: derived from
+      // it, and again as agents register (refreshReadsSharedSlot).
+      readsSharedSlot: readsResidentsSlot(ownSlot, observes, (name) => this.recordedSlotOf(name)),
       ...(spec.namespace ? { namespace: spec.namespace } : {}),
       ...(spec.metadata ? { metadata: clone(spec.metadata) } : {}),
       createdAt: previous?.createdAt ?? this.now(),
@@ -181,11 +311,22 @@ export class AgentRegistry {
       };
     }
     this.live.set(spec.name, record);
+    // The deprecated flag of each live record, the new one's included, as
+    // the slots it names read now: an edge on an agent declared with it
+    // (declaredWith) reads that agent's slot only once it is registered.
+    this.refreshReadsSharedSlot();
     this.persist();
     return record;
   }
 
-  private validate(spec: AgentSpec, resume = false): void {
+  /** Each live record's deprecated `readsSharedSlot`, derived again from its own slot and edges (readsResidentsSlot). */
+  private refreshReadsSharedSlot(): void {
+    for (const record of this.live.values()) {
+      record.readsSharedSlot = readsResidentsSlot(record.ownSlot, record.relationships.observes, (name) => this.recordedSlotOf(name));
+    }
+  }
+
+  private validate(spec: AgentSpec, resume = false, declaredWith: readonly AgentName[] = []): void {
     const fail = (problem: string): never => {
       throw new AgentSpecError(spec.name || '(unnamed)', problem);
     };
@@ -233,7 +374,7 @@ export class AgentRegistry {
       fail(`context source "${spec.inherit.from}" is not a registered agent`);
     }
     for (const edge of spec.observes ?? []) {
-      if (edge.agent !== undefined && !this.live.has(edge.agent)) {
+      if (edge.agent !== undefined && !this.live.has(edge.agent) && !declaredWith.includes(edge.agent)) {
         fail(`observed agent "${edge.agent}" is not a registered agent`);
       }
     }
@@ -265,7 +406,9 @@ export class AgentRegistry {
     for (const { ended } of this.interruptedPending.values()) {
       if (ended.name === name && (!newest || ended.incarnation > newest.incarnation)) newest = ended;
     }
-    return newest ?? this.findEnded?.(name);
+    if (newest) return newest;
+    const logged = this.findEnded?.(name);
+    return logged && withOwnSlot(clone(logged));
   }
 
   /** Flat list of agents — the discovery surface. Ended ones on request. */
@@ -322,15 +465,65 @@ export class AgentRegistry {
     return this.live.get(name)?.roles.ownsProviderScheduling === true;
   }
 
-  /** Agents reading the residents' shared message slot. */
+  /**
+   * Agents reading the residents' shared message slot.
+   *
+   * @deprecated Use `readersOf(RESIDENTS_SLOT)`, or `slotOwners` and
+   * `observersOf` where owning and observing differ.
+   */
   sharedSlotReaders(): AgentName[] {
     return this.namesWhere((r) => r.readsSharedSlot);
   }
 
+  /** @deprecated Use `ownSlotOf` and `observersOf`. */
   readsSharedSlot(name: AgentName): boolean {
     return this.live.get(name)?.readsSharedSlot === true;
   }
 
+  /** The slot a live agent's own rows are stored in, if it names one. */
+  ownSlotOf(name: AgentName): MessageSlotRef | undefined {
+    const slot = this.live.get(name)?.ownSlot;
+    return slot ? { ...slot } : undefined;
+  }
+
+  /** Live agents whose own rows are stored in `slot`, in registration order. */
+  slotOwners(slot: MessageSlotRef): AgentName[] {
+    return this.namesWhere((r) => sameSlot(r.ownSlot, slot));
+  }
+
+  /**
+   * The slot an observe edge reads (observedSlot): an edge that names an
+   * agent and no slot reads that agent's own slot, as its record names it,
+   * the live one, else the one awaiting re-declaration, else its newest
+   * ended one, so an edge on an agent that ended still reads the slot it
+   * read. Undefined for an agent the registry doesn't know.
+   */
+  observedSlotOf(edge: ObserveEdge): MessageSlotRef | undefined {
+    return observedSlot(edge, (name) => this.recordedSlotOf(name));
+  }
+
+  /**
+   * Live agents that read `slot` through an observe edge, in registration
+   * order. With `held`, only those whose edge shows held (policy-diverted)
+   * traffic.
+   */
+  observersOf(slot: MessageSlotRef, options: { held?: boolean } = {}): AgentName[] {
+    return this.namesWhere((r) => r.relationships.observes.some(
+      (edge) => sameSlot(this.observedSlotOf(edge), slot) && (!options.held || edge.includeHeld === true),
+    ));
+  }
+
+  /** Every live agent that reads `slot`, as its own or through an observe edge, in registration order. */
+  readersOf(slot: MessageSlotRef): AgentName[] {
+    return this.namesWhere((r) => sameSlot(r.ownSlot, slot)
+      || r.relationships.observes.some((edge) => sameSlot(this.observedSlotOf(edge), slot)));
+  }
+
+  /** The own slot an agent's record names: live, else awaiting re-declaration, else its newest ended record. */
+  private recordedSlotOf(name: AgentName): MessageSlotRef | undefined {
+    return (this.live.get(name) ?? this.awaiting.get(name) ?? this.inspect(name))?.ownSlot;
+  }
+
   /** The channel an agent is bound to, if it has one. */
   homeChannel(name: AgentName): AgentRecord['homeChannel'] {
     return this.live.get(name)?.homeChannel;
@@ -427,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 };
@@ -598,7 +792,7 @@ export class AgentRegistry {
   restore(snapshot: RegistrySnapshot | null | undefined, endedHistory: AgentRecord[] = []): RestoreOutcome {
     const interrupted: AgentRecord[] = [];
     for (const raw of endedHistory.slice(-this.endedRetention)) {
-      if (raw && typeof raw === 'object' && raw.ended) this.ended.push(clone(raw));
+      if (raw && typeof raw === 'object' && raw.ended) this.ended.push(withOwnSlot(clone(raw)));
     }
     if (!snapshot) return { interrupted };
     if (snapshot.version !== 1) {
@@ -623,7 +817,7 @@ export class AgentRegistry {
     const endedKeys = new Set(this.ended.map((record) => `${record.name}#${record.incarnation}`));
     let dropped = false;
     for (const raw of snapshot.records) {
-      const record = clone(raw);
+      const record = withOwnSlot(clone(raw));
       if (record.ended) continue; // history lives in the ended log
       if (record.lifetime.kind === 'persistent') {
         this.awaiting.set(record.name, record);
@@ -649,12 +843,17 @@ export class AgentRegistry {
    * the newest `endedRetention`. An end whose write fails is reported and
    * stays pending, so the snapshot still lists it and a later settlement (the
    * next boot's) writes it; a failed snapshot write is reported too.
+   * `unsettled` names jobs the host couldn't tell of yet, or whose notices
+   * for the primary it couldn't pass on (by name and incarnation): they stay
+   * pending, as such a failed end does.
    * @internal For the framework's boot, once the interrupted jobs'
    * recipients are told; not a host API.
    */
-  settleInterrupted(): void {
+  settleInterrupted(unsettled: ReadonlyArray<Pick<AgentRecord, 'name' | 'incarnation'>> = []): void {
     if (this.interruptedPending.size === 0) return;
+    const kept = new Set(unsettled.map((record) => `${record.name}#${record.incarnation}`));
     for (const [key, { ended }] of [...this.interruptedPending]) {
+      if (kept.has(key)) continue;
       try {
         this.appendEndedFn?.(clone(ended));
       } catch (error) {

package/src/dendrite/types.ts

@@ -122,14 +122,57 @@ export interface ResultRoute {
   as: 'message' | 'tool-result';
 }
 
-/** Read access to another slot, merged into this agent's view. */
+/**
+ * A message slot: where an agent's rows are stored, or a slot another agent
+ * reads. `namespace` null is the residents' shared un-namespaced slot; a
+ * string is the isolated slot of that namespace. `branch` is set for a
+ * derived agent, whose slot is its parent's slot on a Chronicle branch of
+ * its own; without it the slot is the one on the host's current branch,
+ * where residents and the agents beside them write. Two refs name one slot
+ * when both fields are equal (sameSlot).
+ */
+export interface MessageSlotRef {
+  namespace: string | null;
+  branch?: string;
+}
+
+/**
+ * Read access to a slot that isn't the agent's own, merged into its view:
+ * the relationship a watcher has with the slot it watches (the subconscious
+ * with the residents' slot). The slot read is the one `slot` names, else the
+ * own slot of the agent `agent` names, else the residents' shared slot (the
+ * registry's `observedSlotOf`).
+ */
 export interface ObserveEdge {
-  /** The agent whose slot is read, when the slot belongs to one. */
+  /**
+   * The agent whose slot is read. With no `slot`, the edge reads that
+   * agent's own slot (its `ownSlot`), on whatever branch that slot is, not
+   * the residents' shared slot. Where that slot is the observer's own too (a
+   * resident observing another, AgentConfig.observes), the edge shows the
+   * observer that agent's own rows there, and no other agent's. It must be
+   * registered when the edge is, or declared with it
+   * (AgentRegistry.register's `declaredWith`).
+   */
   agent?: AgentName;
-  /** Message-slot namespace; undefined = the shared un-namespaced slot. */
+  /**
+   * Message-slot namespace, on the host's current branch. Undefined: the
+   * own slot of the agent `agent` names, or the shared un-namespaced slot
+   * when it names none.
+   */
   slot?: string;
-  /** Only messages at or after this sequence. */
+  /**
+   * Only messages at or after this sequence.
+   *
+   * @deprecated A sequence is a coordinate of one branch's record, not of
+   * what an agent was shown; use `fromMessageId`. Nothing reads either yet.
+   */
   fromSequence?: number;
+  /**
+   * Only messages from this one on, by message id, which names one row on
+   * every branch and in every agent's presentation order (#291). Not read
+   * yet: an edge that sets it shows the rows one without it shows.
+   */
+  fromMessageId?: string;
   /** Whether held (policy-diverted) traffic in that slot is visible. */
   includeHeld?: boolean;
 }
@@ -163,7 +206,15 @@ export interface ContextInheritance {
    *   (requires store support; refused when unavailable).
    */
   mode: 'copy' | 'shared';
-  /** The parent checkpoint (sequence on the parent's branch). Filled at creation. */
+  /**
+   * The parent checkpoint: a sequence on the parent's branch. Filled at
+   * creation, from the derived context (its derivation's checkpoint). One a
+   * host sets, for a resume or a derive from an earlier state, is a
+   * presentation boundary (#291), such as `currentSequence()` read after a
+   * presentation into the parent's window, not a row's own sequence: a row
+   * enters the window at a write after its own, so a cut at its own
+   * sequence holds the row in the child's record and not in its window.
+   */
   atSequence?: number;
   /** The parent branch the checkpoint is on. Filled at creation. */
   branch?: string;
@@ -213,9 +264,10 @@ export interface AgentSpec {
   kind: AgentKind;
   /**
    * The model the agent runs on — "whose weights", next to `inherit.from`
-   * for "whose context". Together they are what a consent decision about a
-   * derived agent is made on. Filled by the framework from the agent's
-   * configuration.
+   * for "whose context". Both are on the `dendrite:agent-created` trace and
+   * in the spec a host's `dendrite.beforeDerive` decides on, which the
+   * framework gives no meaning of its own. Filled by the framework from the
+   * agent's configuration.
    */
   model?: string;
   roles: AgentRoles;
@@ -242,9 +294,27 @@ export interface AgentSpec {
    * registry's `ChannelRef`).
    */
   homeChannel?: { serverId: string; channelId: string };
+  /**
+   * The slot this agent's own rows are stored in: the residents' shared
+   * slot for a resident, its own namespace's slot for an isolated agent, the
+   * parent's slot on its own branch for a shared fork. The resident and
+   * subconscious presets set it (the others leave it to the reading below),
+   * and the framework fills it for the agents it derives or creates from
+   * how it opens their context. Absent, the registry reads it as an older
+   * spec meant it: a shared derivation's slot; the shared slot when
+   * `readsSharedSlot` is set and no observe edge without a `slot` explains
+   * it (one naming an agent reads as on the shared slot here);
+   * else the isolated slot of `namespace`. A slot it reads without owning
+   * it is an observe edge (`observes`).
+   */
+  ownSlot?: MessageSlotRef;
   /**
    * Whether the agent reads the residents' shared un-namespaced message
    * slot (as its own slot or through an observe edge).
+   *
+   * @deprecated One flag for two relationships: owning the shared slot and
+   * observing it. Use `ownSlot` and `observes`. Still read for a spec that
+   * sets no `ownSlot` (see there).
    */
   readsSharedSlot?: boolean;
   /** Chronicle namespace owning this agent's context. */
@@ -315,6 +385,20 @@ export interface AgentRecord {
    * as a wake that names a channel without its server is.
    */
   homeChannel?: { serverId: string; channelId: string } | string;
+  /**
+   * The slot the agent's own rows are stored in (see AgentSpec.ownSlot). A
+   * record written before the field existed has it filled at restore from
+   * what the record says. Absent only for an agent whose spec named neither
+   * a slot nor a namespace.
+   */
+  ownSlot?: MessageSlotRef;
+  /**
+   * Whether the agent reads the residents' shared slot, as its own slot or
+   * through an observe edge: derived from `ownSlot` and `relationships.observes`
+   * at each registration of the record (a restored one included), not once.
+   *
+   * @deprecated Use `ownSlot` and `relationships.observes`.
+   */
   readsSharedSlot: boolean;
   namespace?: string;
   metadata?: Record<string, unknown>;

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(', ')})` : ''}`;
+}