@animalabs/agent-framework 0.30.0 → 0.31.0

package/src/tune-out/coordinator.ts

@@ -98,6 +98,69 @@ function writeIdOf(m: Pick<StoredMessage, 'metadata'>): string | undefined {
   return typeof writeId === 'string' ? writeId : undefined;
 }
 
+type HeldRow = Pick<StoredMessage, 'participant' | 'content' | 'metadata'> & { id?: string; writeId?: string };
+
+interface RowKeys {
+  ids: string[];
+  writeIds: string[];
+}
+
+interface ReleaseRecord extends RowKeys {
+  total: number;
+  truncated: number;
+  report: RowKeys;
+}
+
+function keysOf(rows: readonly HeldRow[]): RowKeys {
+  const keys: RowKeys = { ids: [], writeIds: [] };
+  for (const m of rows) {
+    const writeId = m.writeId ?? writeIdOf(m);
+    if (writeId !== undefined) keys.writeIds.push(writeId);
+    else if (m.id !== undefined) keys.ids.push(m.id);
+  }
+  return keys;
+}
+
+function keyedBy(keys: readonly RowKeys[]): (m: HeldRow) => boolean {
+  const ids = new Set(keys.flatMap((k) => k.ids));
+  const writeIds = new Set(keys.flatMap((k) => k.writeIds));
+  return (m) => {
+    const writeId = m.writeId ?? writeIdOf(m);
+    return writeId !== undefined ? writeIds.has(writeId) : m.id !== undefined && ids.has(m.id);
+  };
+}
+
+const isStrings = (value: unknown): value is string[] => Array.isArray(value) && value.every((v) => typeof v === 'string');
+const isRowKeys = (value: unknown): value is RowKeys =>
+  typeof value === 'object' && value !== null && isStrings((value as RowKeys).ids) && isStrings((value as RowKeys).writeIds);
+
+function isReleaseRecord(value: unknown): value is ReleaseRecord {
+  if (!isRowKeys(value)) return false;
+  const record = value as Partial<ReleaseRecord>;
+  return typeof record.total === 'number' && typeof record.truncated === 'number' && isRowKeys(record.report);
+}
+
+function releaseRecordsOf(rows: readonly HeldRow[], epochId: string): ReleaseRecord[] {
+  const records: ReleaseRecord[] = [];
+  for (const m of rows) {
+    const meta = m.metadata as { kind?: unknown; epochId?: unknown; released?: unknown } | undefined;
+    if (meta?.kind !== 'tune-out-cancel' || meta.epochId !== epochId) continue;
+    if (isReleaseRecord(meta.released) && !records.some((r) => JSON.stringify(r) === JSON.stringify(meta.released))) {
+      records.push(meta.released);
+    }
+  }
+  return records;
+}
+
+function truncationNote(records: readonly ReleaseRecord[]): string {
+  const truncated = records.reduce((n, r) => n + r.truncated, 0);
+  if (truncated === 0) return '';
+  const total = records.reduce((n, r) => n + r.total, 0);
+  return records.length === 1
+    ? ` ${truncated} of ${total} diverted messages, the oldest, weren't delivered raw to the resident.`
+    : ` ${truncated} of ${total} diverted messages across ${records.length} dumps, the oldest in each dump that left any out, weren't delivered raw to the resident.`;
+}
+
 /**
  * Whether a held message is one of this channel's: by its channel id, and by
  * its server where it records one, since two servers can register the same
@@ -145,7 +208,7 @@ export interface TuneOutCheck {
   peek?: string[];
 }
 
-/** How long after an end time whose cancel threw the cancel is tried again. */
+/** How long after an end time's or a wake budget's cancel threw the cancel is tried again. */
 const EXPIRY_RETRY_MS = 60_000;
 
 /** Ends a backlog line cut to fit in one of the residents' messages. */
@@ -215,12 +278,7 @@ export interface TuneOutFrameworkHooks {
    * message held mid-turn is in the backlog it belongs to (#232 gap 7).
    */
   getDeferredMessages?: () => Array<Pick<StoredMessage, 'participant' | 'content' | 'metadata'> & { writeId?: string; heldAt?: number }>;
-  /**
-   * Make what was just delivered durable, including anything the delivery
-   * left in the deferred queue: a release flips durable epoch state, so its
-   * dump must survive a crash in the same window (#232 gap 6).
-   */
-  commitDeliveries?: () => void;
+  commitDeliveries?: () => boolean;
   /**
    * The history-reading tool the resident actually has (e.g. a server's
    * `fetch_history`), or null. A truncation note names it only when it exists
@@ -321,8 +379,6 @@ export class TuneOutCoordinator {
   private lateForks = new WeakSet<object>();
   /** The all-except scope's durable record, cached (undefined = not read yet). */
   private scopeCache: AllExceptState | null | undefined;
-  /** The epoch whose release this process delivered and whose hold is not yet recorded as cleared. */
-  private scopeReleased: string | undefined;
   /** Timer key for the scope's cadence and expiry. */
   private static readonly SCOPE_KEY = '\0all-except';
 
@@ -378,25 +434,53 @@ export class TuneOutCoordinator {
       // An epoch whose deadline passed while the process was down cancels
       // immediately — the resident gets their backlog on the schedule they
       // committed to, not whenever the host happened to restart.
-      if (params.expiresAtMs !== undefined && params.expiresAtMs <= Date.now()) {
-        this.cancel(serverId, channelId, 'duration', 'duration elapsed');
-        continue;
+      const inForce = (): boolean => this.channelRegistry.getTuneOutState(serverId, channelId)?.params.epochId === params.epochId;
+      const expired = params.expiresAtMs !== undefined && params.expiresAtMs <= Date.now();
+      if (expired) {
+        try {
+          this.cancel(serverId, channelId, 'duration', 'duration elapsed');
+          continue;
+        } catch (err) {
+          if (!inForce()) {
+            console.error(`[tune-out] ${this.shown(serverId, channelId)} reached its end time while the process was down and its cancel ended it, but a step after the end failed:`, err);
+            continue;
+          }
+          console.error(`[tune-out] ${this.shown(serverId, channelId)} reached its end time while the process was down, and its cancel failed, so it stays tuned out and its cancel is tried again in ${EXPIRY_RETRY_MS / 1000} s:`, err);
+        }
       }
       this.startCadence(serverId, channelId, params.cadenceSeconds);
-      this.armExpiry(serverId, channelId, params);
+      const wakeCount = this.channelRegistry.getTuneOutState(serverId, channelId)?.wakeCount ?? 0;
+      if (wakeCount > params.maxWakes) {
+        this.cancelPastBudget(serverId, channelId, params.maxWakes, 'start');
+        if (!inForce()) continue;
+      } else {
+        this.armExpiry(serverId, channelId, expired ? { ...params, expiresAtMs: Date.now() + EXPIRY_RETRY_MS } : params);
+      }
       if (oldestAnchor === null || params.startedAtSequence < oldestAnchor) {
         oldestAnchor = params.startedAtSequence;
       }
     }
     const scope = this.getAllExcept();
     if (scope) {
+      let inForce = true;
       if (scope.params.expiresAtMs <= Date.now()) {
-        this.cancelAllExcept('duration', 'duration elapsed');
+        try {
+          this.cancelAllExcept('duration', 'duration elapsed');
+          inForce = false;
+        } catch (err) {
+          if (this.getAllExcept()?.params.epochId !== scope.params.epochId) {
+            console.error('[tune-out] the all-except hold reached its end time while the process was down and its release ended it, but a step after the end failed:', err);
+            inForce = false;
+          } else {
+            console.error(`[tune-out] the all-except hold reached its end time while the process was down, and its release failed, so it stays in force and its release is tried again in ${EXPIRY_RETRY_MS / 1000} s:`, err);
+            this.armScopeTimers({ ...scope.params, expiresAtMs: Date.now() + EXPIRY_RETRY_MS });
+          }
+        }
       } else {
         this.armScopeTimers(scope.params);
-        if (oldestAnchor === null || scope.params.startedAtSequence < oldestAnchor) {
-          oldestAnchor = scope.params.startedAtSequence;
-        }
+      }
+      if (inForce && (oldestAnchor === null || scope.params.startedAtSequence < oldestAnchor)) {
+        oldestAnchor = scope.params.startedAtSequence;
       }
     }
     if (oldestAnchor !== null) {
@@ -600,13 +684,6 @@ export class TuneOutCoordinator {
     return this.readerAvailable();
   }
 
-  /**
-   * End a tune-out: durable flip, system-framed backlog dump into the
-   * resident's window (capped), lifecycle notice, one wake for the
-   * resident. `subconsciousNote` is the subconscious's own text (from its
-   * cancel_tuneout call) — delivered verbatim under its name, never
-   * synthesized here.
-   */
   cancel(
     serverId: string,
     channelId: string,
@@ -618,31 +695,25 @@ export class TuneOutCoordinator {
     /** The lifecycle state the channel returns to (a tool close ends in 'closed'). */
     nextState: 'open' | 'closed' = 'open',
   ): { ok: true } | { ok: false; error: string } {
-    const ended = this.channelRegistry.cancelTuneOut(serverId, channelId, nextState, source);
-    if (!ended) {
+    const ending = this.channelRegistry.getTuneOutState(serverId, channelId);
+    if (!ending) {
       // Its reader is the resident's tune_out: cancel_tuneout finds the channel first.
       return { ok: false, error: this.notTunedOut(this.quotedShown(serverId, channelId), 'you') };
     }
-    this.clearTimers(serverId, channelId);
-    this.divertedSinceInvocation.delete(this.key(serverId, channelId));
 
-    // Backlog: every message held under this epoch. The stored ones come in
-    // store order, then those still in the deferred queue (held mid-turn,
-    // not yet written), oldest first. That's arrival order, except when a
-    // held message stays queued while a later one is stored: a store write
-    // refused at a turn-start flush leaves it queued, and that turn's
-    // assembly can then store later coalesced messages directly.
-    const epochId = ended.params.epochId;
+    const epochId = ending.params.epochId;
     const ofEpoch = (m: Pick<StoredMessage, 'metadata'>): boolean =>
       (m.metadata as { tuneOut?: { epochId?: string } } | undefined)?.tuneOut?.epochId === epochId;
-    const held = (this.hooks.getDeferredMessages?.() ?? []).filter(ofEpoch);
-    const backlog: Array<Pick<StoredMessage, 'participant' | 'content' | 'metadata'>> = [
-      ...this.hooks.getStoredMessages().filter(ofEpoch),
-      ...held,
-    ];
+    const storedRows: HeldRow[] = this.hooks.getStoredMessages();
+    const queuedRows: HeldRow[] = this.hooks.getDeferredMessages?.() ?? [];
+    const earlier = releaseRecordsOf([...storedRows, ...queuedRows], epochId);
+    const dumpedEarlier = keyedBy(earlier);
+    const unreleased = (m: HeldRow): boolean => ofEpoch(m) && !dumpedEarlier(m);
+    const held = queuedRows.filter(unreleased);
+    const backlog: HeldRow[] = [...storedRows.filter(unreleased), ...held];
     // Whole messages: a cap below one shows none, where slice(-0.5) would
     // start at 0 and take them all.
-    const cap = Math.floor(ended.params.backlogCap);
+    const cap = Math.floor(ending.params.backlogCap);
     const authorOf = (m: Pick<StoredMessage, 'participant' | 'metadata'>): string =>
       suppliedValue((m.metadata as { author?: { name?: string } } | undefined)?.author?.name ?? m.participant);
     // A line names its author as the resident knows them and marks what a
@@ -653,7 +724,7 @@ export class TuneOutCoordinator {
     const historyTool = this.hooks.historyTool ? this.hooks.historyTool() : 'fetch_history';
     // The channel as the resident and the subconscious are shown it.
     const name = this.shown(serverId, channelId);
-    const lifecycle = `[${NOTICE_TAG.tuneOut}: ${name} cancelled — ${reason}, ${ended.wakeCount} wake${ended.wakeCount === 1 ? '' : 's'}]`;
+    const lifecycle = `[${NOTICE_TAG.tuneOut}: ${name} cancelled — ${reason}, ${ending.wakeCount} wake${ending.wakeCount === 1 ? '' : 's'}]`;
     const render = (lines: string[], truncated: number): string => {
       const attrs = [
         `channel=${this.quotedShown(serverId, channelId)}`,
@@ -725,14 +796,30 @@ export class TuneOutCoordinator {
         m.content.some((b) => b.type !== 'text') || (newestCut && m === shown[0])),
     ];
 
-    // Host-framed system artifacts — never voiced as anyone.
-    this.hooks.addMessage(
-      'user',
-      [{ type: 'text', text: render(lines, truncated) }],
-      { system: true, kind: 'tune-out-cancel', channelId, epochId },
-    );
-    // The epoch is already ended durably; the release must be as durable.
-    this.hooks.commitDeliveries?.();
+    const records = [...earlier];
+    if (earlier.length === 0 || backlog.length > 0) {
+      const record: ReleaseRecord = { ...keysOf(backlog), total: backlog.length, truncated, report: keysOf(heldForReport) };
+      this.hooks.addMessage(
+        'user',
+        [{ type: 'text', text: render(lines, truncated) }],
+        { system: true, kind: 'tune-out-cancel', channelId, epochId, released: record },
+      );
+      records.push(record);
+    }
+    if (this.hooks.commitDeliveries?.() === false) {
+      throw new Error(`the backlog of ${this.quotedShown(serverId, channelId)} could not be made durable, so its tune-out stays in force`);
+    }
+    this.channelRegistry.cancelTuneOut(serverId, channelId, nextState, source);
+    this.clearTimers(serverId, channelId);
+    this.divertedSinceInvocation.delete(this.key(serverId, channelId));
+    const reportedEarlier = keyedBy(earlier.map((r) => r.report));
+    const release = {
+      truncated: records.reduce((n, r) => n + r.truncated, 0),
+      heldForReport: [
+        ...[...storedRows, ...queuedRows].filter((m) => ofEpoch(m) && reportedEarlier(m)),
+        ...(records.length > earlier.length ? heldForReport : []),
+      ],
+    };
     // The subconscious's own words, under its own name, verbatim.
     const subName = this.hooks.subconsciousName();
     if (subconsciousNote && subName) {
@@ -766,12 +853,10 @@ export class TuneOutCoordinator {
     // and when it wrote no note and the dump left any message out, since
     // nothing else then covers it. Otherwise its note speaks for what it saw.
     const selfCancel = source === 'subconscious';
-    if (subName && (!selfCancel || heldForReport.length > 0 || (!subconsciousNote && truncated > 0))) {
-      const truncNote = truncated > 0
-        ? ` ${truncated} of ${backlog.length} diverted messages, the oldest, weren't delivered raw to the resident.`
-        : '';
-      const heldNote = heldForReport.length > 0
-        ? ` Still held at the cancel, so your view may not have them yet: the ${heldForReport.length} message${heldForReport.length === 1 ? '' : 's'} after this one.`
+    if (subName && (!selfCancel || release.heldForReport.length > 0 || (!subconsciousNote && release.truncated > 0))) {
+      const truncNote = truncationNote(records);
+      const heldNote = release.heldForReport.length > 0
+        ? ` Still held at the cancel, so your view may not have them yet: the ${release.heldForReport.length} message${release.heldForReport.length === 1 ? '' : 's'} after this one.`
         : '';
       this.hooks.addMessage(
         'user',
@@ -781,7 +866,7 @@ export class TuneOutCoordinator {
       );
       // Each held message is a row of its own, so a per-message cap cuts each
       // one on its own, its author's label included, not the batch's newest.
-      for (const m of heldForReport) {
+      for (const m of release.heldForReport) {
         this.hooks.addMessage(
           'user',
           [{ type: 'text', text: `${authorOf(m)}:` }, ...m.content],
@@ -803,9 +888,7 @@ export class TuneOutCoordinator {
       const rest = this.unhandedBacklog(this.handOffKey(epochId, serverId, channelId), stored, queued);
       const unread = rest.backlog.length + rest.queued.length;
       if (!selfCancel || unread > 0) {
-        const truncNote = truncated > 0
-          ? ` ${truncated} of ${backlog.length} diverted messages, the oldest, weren't delivered raw to the resident.`
-          : '';
+        const truncNote = truncationNote(records);
         const lateNote = selfCancel
           ? ` ${unread === 1 ? 'This message' : `These ${unread} messages`} arrived after the reader that cancelled was handed its own.`
           : '';
@@ -818,7 +901,7 @@ export class TuneOutCoordinator {
     // there that its reader hasn't looked at are counted again, as the
     // channel's own tune-out's count stood in for theirs.
     this.rebuildTally(serverId, channelId);
-    this.hooks.emitTrace({ type: 'tune-out:cancelled', serverId, channelId, epochId, reason, wakeCount: ended.wakeCount });
+    this.hooks.emitTrace({ type: 'tune-out:cancelled', serverId, channelId, epochId, reason, wakeCount: ending.wakeCount });
     return { ok: true };
   }
 
@@ -1043,11 +1126,6 @@ export class TuneOutCoordinator {
     return counts;
   }
 
-  /**
-   * End the all-except hold: durable flip, one release notice with a
-   * per-channel backlog (each capped), the reader's note if any, one wake
-   * for the resident, and the reader's own look at what it had not seen.
-   */
   cancelAllExcept(
     source: string,
     reason: string,
@@ -1060,9 +1138,14 @@ export class TuneOutCoordinator {
 
     const ofEpoch = (m: Pick<StoredMessage, 'metadata'>): boolean =>
       (m.metadata as { tuneOut?: { epochId?: string } } | undefined)?.tuneOut?.epochId === epochId;
-    const all = [...this.hooks.getStoredMessages().filter(ofEpoch), ...(this.hooks.getDeferredMessages?.() ?? []).filter(ofEpoch)];
-    const byChannel = new Map<string, { serverId: string; channelId: string; backlog: Array<Pick<StoredMessage, 'participant' | 'content' | 'metadata'>> }>();
-    for (const m of all) {
+    const storedRows: HeldRow[] = this.hooks.getStoredMessages();
+    const queuedRows: HeldRow[] = this.hooks.getDeferredMessages?.() ?? [];
+    const all: HeldRow[] = [...storedRows.filter(ofEpoch), ...queuedRows.filter(ofEpoch)];
+    const earlier = releaseRecordsOf([...storedRows, ...queuedRows], epochId);
+    const releasedEarlier = keyedBy(earlier);
+    const fresh = all.filter((m) => !releasedEarlier(m));
+    const byChannel = new Map<string, { serverId: string; channelId: string; backlog: HeldRow[] }>();
+    for (const m of fresh) {
       const meta = m.metadata as { channelId?: string; serverId?: string } | undefined;
       const serverId = meta?.serverId ?? '';
       const channelId = meta?.channelId ?? '(unknown channel)';
@@ -1072,12 +1155,14 @@ export class TuneOutCoordinator {
       byChannel.set(k, entry);
     }
     const historyTool = this.hooks.historyTool?.() ?? null;
+    let truncatedInAll = 0;
     const dumps = [...byChannel.values()].map(({ serverId, channelId, backlog }) => {
       // Floored here too: a hold stored before entry floored its cap can hold
       // a fraction.
       const cap = Math.floor(backlogCap);
       const shown = cap > 0 ? backlog.slice(-cap) : [];
       const truncated = backlog.length - shown.length;
+      truncatedInAll += truncated;
       const attrs = [
         `channel=${quotedValue(this.shown(serverId, channelId))}`,
         `messages=${backlog.length}`,
@@ -1087,22 +1172,19 @@ export class TuneOutCoordinator {
     });
     const summary = byChannel.size === 0
       ? 'Nothing was held.'
-      : `${all.length} message${all.length === 1 ? '' : 's'} held in ${byChannel.size} channel${byChannel.size === 1 ? '' : 's'}.`;
-    if (this.scopeReleased !== epochId) {
+      : `${fresh.length} message${fresh.length === 1 ? '' : 's'} held in ${byChannel.size} channel${byChannel.size === 1 ? '' : 's'}.`;
+    if (earlier.length === 0 || fresh.length > 0) {
+      const record: ReleaseRecord = { ...keysOf(fresh), total: fresh.length, truncated: truncatedInAll, report: { ids: [], writeIds: [] } };
       this.hooks.addMessage(
         'user',
         [{ type: 'text', text: `[${NOTICE_TAG.tuneOut}: all channels except ${this.shown(except.serverId, except.channelId)} released — ${reason}, ${scope.wakeCount} wake${scope.wakeCount === 1 ? '' : 's'}]\n\n${summary}${dumps.length > 0 ? '\n\n' + dumps.join('\n\n') : ''}` }],
-        { system: true, kind: 'tune-out-cancel', scope: 'all-except', channelId: except.channelId, epochId },
+        { system: true, kind: 'tune-out-cancel', scope: 'all-except', channelId: except.channelId, epochId, released: record },
       );
-      this.hooks.commitDeliveries?.();
-      this.scopeReleased = epochId;
     }
-    // The release is recorded before the hold is: a failure past this point
-    // leaves the hold in force with its release already delivered. A retry in
-    // this process records only the hold's end; a restart between the two
-    // delivers the release again, where the other order lost it outright.
+    if (this.hooks.commitDeliveries?.() === false) {
+      throw new Error('the all-except release could not be made durable, so the hold stays in force');
+    }
     this.writeScope(null);
-    this.scopeReleased = undefined;
     this.clearScopeTimers();
     for (const [key, pending] of this.pendingWakes) {
       const [serverId, channelId] = key.split('\0') as [string, string];
@@ -1335,6 +1417,31 @@ export class TuneOutCoordinator {
     this.pendingWakes.set(key, { count: 1, timer });
   }
 
+  private cancelPastBudget(serverId: string, channelId: string, maxWakes: number, from: 'wake' | 'start' = 'wake'): void {
+    const key = this.key(serverId, channelId);
+    const existing = this.expiryTimers.get(key);
+    if (existing) clearTimeout(existing);
+    const end = (first: boolean): void => {
+      try {
+        this.expiryTimers.set(key, setTimeout(() => end(false), EXPIRY_RETRY_MS));
+        if (!this.cancel(serverId, channelId, 'tune-out-max-wakes', `wake budget exhausted (${maxWakes})`).ok) {
+          this.clearTimers(serverId, channelId);
+        }
+      } catch (err) {
+        if (first && from === 'start') {
+          if (this.channelRegistry.getTuneOutState(serverId, channelId)) {
+            console.error(`[tune-out] ${this.shown(serverId, channelId)} was past its wake budget at start, and its cancel failed, so it stays tuned out and its cancel is tried again in ${EXPIRY_RETRY_MS / 1000} s:`, err);
+          } else {
+            console.error(`[tune-out] ${this.shown(serverId, channelId)} was past its wake budget at start and its cancel ended it, but a step after the end failed:`, err);
+          }
+        } else {
+          this.timerFailed('wake', serverId, channelId, err);
+        }
+      }
+    };
+    end(true);
+  }
+
   /** One coalesced wake: counted durably against the epoch that holds the channel. */
   private fireWake(serverId: string, channelId: string, count: number): void {
     if (this.channelRegistry.getTuneOutState(serverId, channelId)) {
@@ -1342,12 +1449,7 @@ export class TuneOutCoordinator {
       const counted = this.channelRegistry.recordTuneOutWake(serverId, channelId);
       if (!counted) return; // cancelled inside the window
       if (counted.wakeCount > counted.params.maxWakes) {
-        this.cancel(
-          serverId,
-          channelId,
-          'tune-out-max-wakes',
-          `wake budget exhausted (${counted.params.maxWakes})`,
-        );
+        this.cancelPastBudget(serverId, channelId, counted.params.maxWakes);
         return;
       }
       this.invokeSubconscious(serverId, channelId, 'wake', count);

package/src/tune-out/tools.ts

@@ -14,7 +14,7 @@ import type { StoredMessage } from '@animalabs/context-manager';
  * never leak bare prose to the default locus.
  */
 
-import type { ToolDefinition } from '../types/index.js';
+import type { AgentConfig, ToolDefinition } from '../types/index.js';
 
 export const SUBCONSCIOUS_TOOL_NAMES = [
   'deliver_summary',
@@ -143,6 +143,17 @@ interface SubconsciousConfigBase {
    * shared prefix).
    */
   allowChannelSpeech?: boolean;
+  /** The reader's model's context window, as AgentConfig.physicalWindowTokens,
+   *  in place of the primary's. Left out or null, a reader on the primary's
+   *  model has the primary's; on another model, the persistent reader has
+   *  none and a fork has the primary's. */
+  physicalWindowTokens?: AgentConfig['physicalWindowTokens'];
+  /** The reader's model's thinking binding, as AgentConfig.thinkingBinding,
+   *  in place of the primary's. Left out, null or false, a reader on the
+   *  primary's model has the primary's; on another model, the persistent
+   *  reader has none and a fork has the primary's. `{ binds: false }` gives
+   *  a reader none. */
+  thinkingBinding?: AgentConfig['thinkingBinding'];
 }
 
 export interface PersistentReaderConfig extends SubconsciousConfigBase {
@@ -156,7 +167,8 @@ export interface PersistentReaderConfig extends SubconsciousConfigBase {
   /** Model id; defaults to the primary agent's (same-model side-process).
    *  Another id, compared exactly, makes the subconscious leave out the
    *  fields that describe the primary's model, its window and its thinking
-   *  binding (SUBCONSCIOUS_MODEL_FIELDS); nothing here sets its own. */
+   *  binding (SUBCONSCIOUS_MODEL_FIELDS); `physicalWindowTokens` and
+   *  `thinkingBinding` set its own. */
   model?: string;
   /**
    * The voice/criteria mode block — recipe-side and co-authored with the

package/src/types/agent.ts

@@ -539,7 +539,8 @@ export interface InferenceOptions {
  * `supportsInjectedMessages` is what the stream declared with the round's
  * tool calls (membrane's `ToolContext.supportsInjectedMessages`): whether it
  * can carry messages injected with that round's results. It's absent when
- * the stream doesn't say, as on membrane 0.5.87 and earlier.
+ * the stream doesn't say, which reads as a stream that can't, and when there
+ * is no stream, as for the direct API.
  */
 export type AgentState =
   | { status: 'idle' }

package/src/types/framework.ts

@@ -6,6 +6,7 @@ import type { ProcessEvent } from './events.js';
 import type { McplServerConfig, InferenceRoutingPolicy } from '../mcpl/types.js';
 import type { ConversationRouterConfig } from '../mcpl/conversation-router.js';
 import type { GateOptions } from '../gate/types.js';
+import type { InferenceBoundsOptions } from '../inference-bounds.js';
 
 // Re-export trace types
 export type { TraceEvent, TraceEventListener } from './trace.js';
@@ -299,6 +300,30 @@ export interface FrameworkConfig {
   /** Custom error policy */
   errorPolicy?: ErrorPolicy;
 
+  /**
+   * How long a model call may go without progress before it is cut. A
+   * resident's streamed call, and an MCPL server's, gets membrane's progress
+   * bounds where its adapter's stream reports content (Anthropic, Bedrock),
+   * and on every adapter a flat bound from its last provider event: the
+   * larger of a setup term (the larger of `beforeContentMs` and
+   * `betweenEventsMs`) plus the request's `maxTokens` at
+   * `thinkTokensPerSecond`, and `flatMinimumMs`. An auxiliary call
+   * (compression, the reply judge) and an MCPL server's non-streamed call get
+   * a bound on the whole call from its send, the setup term plus that
+   * allowance (the larger of the setup term and `flatMinimumMs` when it
+   * names no `maxTokens`), unless its
+   * caller passed a `progressTimeoutMs` of its own; where an adapter's
+   * `complete()` streams under the hood, membrane renews it at each parsed
+   * provider event. A call a bound cuts fails
+   * with type `timeout`, and on an agent's turn DefaultErrorPolicy gives each
+   * such call one fresh call, except in a turn that re-arms an exhausted one,
+   * where `exhaustedTurnRearmMs` says what a cut does. One setting covers
+   * every agent. `false` sets
+   * none of these bounds. Default: membrane's PROGRESS_BOUNDS and
+   * FLAT_MINIMUM_MS.
+   */
+  inferenceBounds?: false | InferenceBoundsOptions;
+
   /**
    * Host verdict on a failed inference: "this cannot succeed until later".
    * Consulted before the error policy and before the built-in
@@ -337,20 +362,32 @@ export interface FrameworkConfig {
    * channel isn't sent again: one whose turn was woken for a channel id that
    * names no one registered channel and never found one, and whose request
    * names none of its own. A failure that states a wait is held for that wait
-   * first, as any turn's is, and a deadline ends the turn as before, whether
-   * the host set it or membrane marks one as run out: the runtime's or
-   * undici's on a sent request, the Anthropic adapter's watchdogs, or the
-   * Anthropic SDK's timeout, which covers its connect timeout too. Until one
-   * of the re-armed turn's rounds has run or had its tool calls cut off, its
-   * failure gets no retries from the error policy: on another transient
-   * failure the next delay follows, until the list runs out, and a failure of
-   * any other kind ends the re-arming. A wake for the agent while it waits
-   * starts its turn at once, with the re-armed trigger merged in. That turn is
-   * the wake's: the error policy retries its failures. A completed turn starts
-   * the count again, and so does a message said to the agent: not a system
-   * message or notice; not an edit, reaction or deletion, unless an edit is
-   * the first version of a message the agent sees; not a message its own view
-   * leaves out, such as one a tune-out holds from it; and not the agent's own
+   * first, as any turn's is, and a turn that ends on a deadline, whether the
+   * host set it or membrane marks one as run out (the runtime's or undici's
+   * on a sent request, the Anthropic adapter's watchdogs, or the Anthropic
+   * SDK's timeout, which covers its connect timeout too), isn't re-armed,
+   * save the exception below. Until one of the re-armed turn's rounds has run
+   * or had its tool calls cut off, its failure gets no retries from the error
+   * policy: on another transient failure the next delay follows, until the
+   * list runs out, and a failure of any other kind ends the re-arming. The
+   * one exception is a re-armed turn's send that fails with a deadline marked
+   * as run out, membrane's or a bound the host sets on the call
+   * (`inferenceBounds`), as when a stream stalls. Such a cut counts as a
+   * transient failure, so a turn that ends on it is re-armed as for a
+   * transient failure, unless it follows another such cut with no transient
+   * failure, answered round or message said to the agent between them: two
+   * such cuts in a row end the re-arming, and the second gets no retry from
+   * the error policy, even in a re-armed turn that got partway. A transient
+   * failure or an answered round in any of the agent's turns clears an
+   * earlier cut, and so does a message said to the agent, or the agent's end.
+   * Every such cut counts, including one the error policy retries or a host's
+   * provider hold takes. A wake for the agent while it waits starts its turn
+   * at once, with the re-armed trigger merged in. That turn is the
+   * wake's: the error policy retries its failures. A completed turn starts the
+   * count again, and so does a message said to the agent: not a system message
+   * or notice; not an edit, reaction or deletion, unless an edit is the first
+   * version of a message the agent sees; not a message its own view leaves
+   * out, such as one a tune-out holds from it; and not the agent's own
    * schedule, the heartbeat's tick or reminder, a self-wake timer it set, or a
    * script's wake. A notice a module or an MCPL server stores as a message
    * counts. A message in the residents' shared slot counts for each resident
@@ -558,7 +595,10 @@ export interface InferencePolicy {
  */
 export interface ErrorPolicy {
   /**
-   * Handle an inference error.
+   * Handle an inference error. `attempt` is how many times the turn's
+   * request has failed before this one; for a deadline expiry (a progress
+   * bound's cut, or one membrane marks), how many times that call's request
+   * has expired in a row before this one.
    */
   onInferenceError(
     error: Error,

package/src/types/module.ts

@@ -120,7 +120,10 @@ export interface Module {
 
   /**
    * Start the module.
-   * Called when the framework starts or when the module is added.
+   * Called when the module is added: create() adds the modules it is given,
+   * so for those it runs before create() returns. Its own removal and the
+   * framework's stop() wait for it to settle before the module's stop()
+   * runs, so it mustn't await either.
    */
   start(ctx: ModuleContext): Promise<void>;
 
@@ -132,6 +135,8 @@ export interface Module {
    * a host wires up after create() returns, such as a WorkspaceModule's
    * initStore(). A stop() that saves state can therefore run before that
    * wiring, and shouldn't then save over state it was handed and hasn't used.
+   * It isn't called before the module's start() has settled, so it can end
+   * what start() set up.
    */
   stop(): Promise<void>;
 
@@ -259,6 +264,41 @@ export interface AgentSettingsExtension {
 
 /**
  * Context provided to modules for interacting with the framework.
+ *
+ * Once the module's `stop()` has completed, through `removeModule()` or the
+ * framework's `stop()`, its context has no effect on the framework:
+ * - each push is dropped with a log line, as a push after the framework's
+ *   `stop()` is;
+ * - `setState`, `registerLogState`, `appendToLog`, `editLogItem`,
+ *   `editMessage`, `removeMessage`, `notifyOps`, `registerSpeechHandler` and
+ *   `unregisterSpeechHandler` do nothing; `addMessage` returns `''` and adds
+ *   nothing; `callTool` resolves with an error result and runs nothing;
+ *   `getModule` returns `null`; and `onTrace` subscribes nothing, while the
+ *   subscriptions made through the context end. None of these throws, and
+ *   the first such call of each method logs one line naming the module and
+ *   the method;
+ * - `findMessageByExternalId` answers without updating its mapping, and logs
+ *   nothing.
+ *
+ * Its reads (`getState`, `getLog`, `getLogLength`, `getMessage`,
+ * `queryMessages`, `getAgents`, `getActiveTools`, `findMessageByExternalId`)
+ * answer, and fail, as before; one that meets a held write may record that
+ * the write has landed, as any reader's does. The framework calls none of the
+ * module's `onProcess`, `onAgentSpeech` and `onToolBatchComplete` again; it
+ * drops whole a response of its that hadn't been applied by then, with a line
+ * naming what the response asked for if it asked for anything; and it leaves
+ * its `gatherContext` answer out of a turn whose answers it hadn't merged by
+ * then, with a line if it held injections. After `removeModule()`, the result
+ * its `handleToolCall` returns for a call it was running when its `stop()`
+ * completed is still delivered while the framework runs. The framework's
+ * `stop()` closes its event queue before it stops any module, so through the
+ * framework's `stop()` that result is dropped, with the line any tool result
+ * arriving after the framework's `stop()` gets. A result it pushes through
+ * its context after its `stop()` completes is dropped, as its other pushes
+ * are. A module whose `stop()` fails stays registered, and its context keeps
+ * working.
+ * References the module already holds, to other modules or to its own
+ * timers, stay as they are.
  */
 export interface ModuleContext {
   /**
@@ -366,8 +406,7 @@ export interface ModuleContext {
    * and a tool round moves when it injects messages into a stream that
    * declares it carries them. So one that waited for its target's end (a
    * run's end, or a fork's last turn), one stored while it was idle and
-   * never sent, one stored at a tool round that ended the turn, and one
-   * injected into a stream that didn't declare it carries injections go to
+   * never sent, and one stored at a tool round that ended the turn go to
    * the primary. The framework's own
    * writes for a run or a fork are unchanged: they stay in its store,
    * unless they're notices the primary already takes in their place (a