@animalabs/agent-framework 0.33.0 → 0.34.0

package/src/tool-presentation.ts

@@ -3,6 +3,7 @@ import { constants, fchmodSync, closeSync, fstatSync, lstatSync, openSync, readS
 import { closestNames } from './closest-names.js';
 import { boundedErrorMessage, errorMessage } from './error-message.js';
 import type { ToolDefinition, ToolResult } from './types/events.js';
+import { appendAll } from './append-all.js';
 
 export interface ToolPresentationConfig {
   /** Absolute path to shared editable JSON. Missing file means no overrides. */
@@ -36,6 +37,8 @@ const MAX_DESCRIPTION_CHARS = 32768;
 const protectedNames = new Set(['set_tool_visibility', 'set_tool_description', 'workspace--read', 'toolsets--open', 'toolsets--act', 'toolsets--look', 'toolsets--close']);
 export const isPresentationTool = (name: string): boolean => name === 'set_tool_visibility' || name === 'set_tool_description';
 const hash = (value: string): string => createHash('sha256').update(value).digest('hex');
+/** The catalogue's line layout, folded into its revision so a line reference saved under an earlier layout reads as stale. Raise it with any change to where the catalogue's lines fall. */
+const CATALOGUE_LAYOUT = 2;
 
 /**
  * A presentation or defaults file this host can't use. Each problem is a
@@ -61,9 +64,9 @@ const characters = (text: string): number => [...text].length;
 /** A text's first `n` characters, never splitting a code point. */
 const firstCharacters = (text: string, n: number): string => [...text].slice(0, n).join('');
 
-/** A name as a message quotes it: whole up to 60 characters, and past that cut, with its length, since a file can hold a key of any size. */
-function quoted(name: string): string {
-  return characters(name) <= 60 ? JSON.stringify(name) : `${JSON.stringify(firstCharacters(name, 57))}... (${count(characters(name))} characters)`;
+/** A text as a message quotes it: whole up to `limit` characters, and past that cut, with its length, since a file can hold a key, and a tool a description, of any size. */
+function quoted(name: string, limit = 60): string {
+  return characters(name) <= limit ? JSON.stringify(name) : `${JSON.stringify(firstCharacters(name, limit - 3))}... (${count(characters(name))} characters)`;
 }
 
 /** A file's problem as a message quotes it: its own clauses whole, and anything else bounded, since nobody wrote that text for its reader. */
@@ -246,7 +249,7 @@ export class ToolPresentation {
       return {name:tool.name,source:sources.get(tool.name) ?? 'Unattributed',visible:override?.visible ?? true,originalDescription:tool.description,description,descriptionSource,inputSchema:structuredClone(tool.inputSchema)};
     });
     const available = tools.map((tool,i) => ({...structuredClone(tool),description:entries[i].description}));
-    return {revision:hash(JSON.stringify({raw,entries,diagnostics})),source:this.config.path,cataloguePath:this.config.cataloguePath,diagnostics,available,
+    return {revision:hash(JSON.stringify({layout:CATALOGUE_LAYOUT,raw,entries,diagnostics})),source:this.config.path,cataloguePath:this.config.cataloguePath,diagnostics,available,
       advertised:available.filter((_,i)=>entries[i].visible),entries};
   }
   edit(tool: string, input: unknown, available: ToolDefinition[]): ToolResult {
@@ -336,7 +339,7 @@ export class ToolPresentation {
     const name = args.name as string;
     if (!available.some((t) => t.name === name)) {
       const near = closestNames(name, available.map((t) => t.name));
-      throw new PresentationRefusal(`Nothing was changed: no tool named ${quoted(name)} is available to you.${near.length ? ` Did you mean ${quotedList(near, 'or', JSON.stringify)}?` : ''}`
+      throw new PresentationRefusal(`Nothing was changed: you have no tool named ${quoted(name)} right now, shown or hidden.${near.length ? ` Did you mean ${quotedList(near, 'or', JSON.stringify)}?` : ''}`
         + ` Copy the exact name from your tool catalogue's index, workspace--read {"path":${JSON.stringify(this.config.cataloguePath)},"limit":140}, reading on with "offset" if the index runs past that.`);
     }
     if (field === 'description' && typeof args.description === 'string' && characters(args.description) > MAX_DESCRIPTION_CHARS)
@@ -346,6 +349,11 @@ export class ToolPresentation {
     return name;
   }
 }
+const SUMMARY_CHARACTERS = 200;
+function summaryOf(description: string): string {
+  const first = description.split(/\r\n|[\n\v\f\r\x85\u2028\u2029]/).find(line => line.trim() !== '');
+  return first === undefined ? '' : `: ${quoted(first, SUMMARY_CHARACTERS)}`;
+}
 export function renderCatalogue(snapshot: PresentationSnapshot): string {
   const groups = new Map<string, PresentationSnapshot['entries']>();
   for (const entry of snapshot.entries) {
@@ -360,12 +368,22 @@ export function renderCatalogue(snapshot: PresentationSnapshot): string {
     'Visible = not hidden by you: in your tool list, unless the host keeps it in its "settings" toolset or a server\'s tab (toolsets--look shows those). Hidden = moved into the "settings" toolset, or its MCPL server\'s tab: toolsets--look shows it, toolsets--act calls it once that toolset is open.',
     'These are your visibility choices, not fixed primary/secondary rankings.',
     'Copy exact names from the index; similar-sounding names may not exist.',
+    'Index by source: line N.',
     'Show a hidden tool: set_tool_visibility {"name":"EXACT_NAME","visible":true}.',
     `Read details: workspace--read {"path":${JSON.stringify(snapshot.cataloguePath)},"offset":LINE,"limit":LINES}.`,
     'Line references below belong to this revision; reread the index after changes.', '',
   ];
+  const indexLineAt = lines.indexOf('Index by source: line N.');
   // One line each: a quoted parse error can hold the file's own line breaks.
   for (const diagnostic of snapshot.diagnostics) lines.push('Diagnostic: '+diagnostic.replace(/\r\n|\r|\n/g, '\\n'));
+  const hidden = snapshot.entries.filter(e => !e.visible);
+  const hiddenAt = new Map<string, number>();
+  if (hidden.length) {
+    lines.push(`## Hidden (${hidden.length})`, '');
+    for (const entry of hidden) {hiddenAt.set(entry.name, lines.length); lines.push('');}
+    lines.push('');
+  }
+  lines[indexLineAt] = `Index by source: line ${lines.length + 1}.`;
   lines.push('## Index by source', '');
   const index = new Map<string, number>();
   for (const [source, entries] of groups) {
@@ -378,11 +396,18 @@ export function renderCatalogue(snapshot: PresentationSnapshot): string {
     lines.push(`### ${source}`, '');
     for (const entry of entries) {
       const start = lines.length + 1;
-      lines.push(`#### ${entry.name} (${entry.visible?'visible':'hidden'})`, '',
-        ...entry.description.split('\n'), '', `Description from: ${entry.descriptionSource ?? 'installed component'}`, '', `Schema: ${JSON.stringify(entry.inputSchema)}`);
-      if(entry.description!==entry.originalDescription) lines.push('', 'Original description:', ...entry.originalDescription.split('\n'));
+      lines.push(`#### ${entry.name} (${entry.visible?'visible':'hidden'})`, '');
+      appendAll(lines, entry.description.split('\n'));
+      lines.push('', `Description from: ${entry.descriptionSource ?? 'installed component'}`, '', `Schema: ${JSON.stringify(entry.inputSchema)}`);
+      if(entry.description!==entry.originalDescription) {
+        lines.push('', 'Original description:');
+        appendAll(lines, entry.originalDescription.split('\n'));
+      }
       lines.push('');
-      lines[index.get(entry.name)!] = `- [${entry.visible?'visible':'hidden'}] ${entry.name} — details: offset ${start}, limit ${lines.length-start+1}`;
+      const details = `details: offset ${start}, limit ${lines.length-start+1}`;
+      lines[index.get(entry.name)!] = `- [${entry.visible?'visible':'hidden'}] ${entry.name} — ${details}`;
+      const at = hiddenAt.get(entry.name);
+      if (at !== undefined) lines[at] = `- ${entry.name} (${entry.source})${summaryOf(entry.description)} — ${details}`;
     }
   }
   return lines.join('\n');

package/src/tune-out/coordinator.ts

@@ -1214,8 +1214,9 @@ export class TuneOutCoordinator {
    * runDeferredCancels runs them sooner.
    */
   private deferredRetry: ReturnType<typeof setTimeout> | undefined;
-  /** Timer key for the scope's cadence and expiry. */
-  private static readonly SCOPE_KEY = '\0all-except';
+  /** Timer key for the scope's cadence and expiry; never a channel's key,
+   *  which starts with `[`. */
+  private static readonly SCOPE_KEY = 'all-except';
 
   constructor(
     private readonly channelRegistry: ChannelRegistry,
@@ -1223,8 +1224,15 @@ export class TuneOutCoordinator {
     private readonly hooks: TuneOutFrameworkHooks,
   ) {}
 
+  /** A channel's key in the coordinator's maps and its stored last looks.
+   *  The store refuses an object key holding a NUL, so no separator: the
+   *  pair as JSON, which no server or channel id can make ambiguous. */
   private key(serverId: string, channelId: string): string {
-    return `${serverId}\0${channelId}`;
+    return JSON.stringify([serverId, channelId]);
+  }
+
+  private channelOf(key: string): [string, string] {
+    return JSON.parse(key) as [string, string];
   }
 
   /** The readers' hand-off bookkeeping's key: one epoch's reading of one channel. */
@@ -1367,7 +1375,7 @@ export class TuneOutCoordinator {
       if (!held.has(key) && this.holdFor(meta.serverId ?? '', meta.channelId)?.epochId === epochId) held.add(key);
     }
     for (const key of held) {
-      const [serverId, channelId] = key.split('\0') as [string, string];
+      const [serverId, channelId] = this.channelOf(key);
       this.rebuildTally(serverId, channelId);
     }
     this.pruneLooks();
@@ -1481,7 +1489,7 @@ export class TuneOutCoordinator {
   private anchorSubconscious(occasion: 'enter' | 'resume' = 'enter'): void {
     const active = this.activeStarts();
     if (active.length === 0) return;
-    const sequence = Math.min(...active.map((e) => e.sequence));
+    const sequence = active.reduce((min, e) => Math.min(min, e.sequence), Infinity);
     const epochIds = active.filter((e) => e.sequence === sequence).map((e) => e.epochId);
     const kept = this.ordinalsKept();
     const read = kept ? this.readWindowState() : { starts: {} };
@@ -3186,10 +3194,16 @@ export class TuneOutCoordinator {
    * of the record reads them in first (lossRecordUnread), and writes this
    * run's kept ones there too; where this run keeps any, that write is
    * made here, before the marker, and the last stop's bound is judged by
-   * the destination's record (carriedNeeded). Never throws.
+   * the destination's record (carriedNeeded). The subconscious's last
+   * looks are read again too, so the next look reads the destination's
+   * record (lastLooks), unless `sameBranch` says the store switched to the
+   * branch it was on, as a refusing manager's recovery does: no branch
+   * moved, and the cache keeps any look a refused write held only there.
+   * Never throws.
    */
-  branchMoved(): void {
+  branchMoved(sameBranch = false): void {
     if (this.stopped) return;
+    if (!sameBranch) this.lastLooksCache = undefined;
     try {
       const branch = this.branchNow();
       if (branch !== undefined && this.runStarts.has(branch)) {
@@ -4512,7 +4526,7 @@ export class TuneOutCoordinator {
         // One look per held channel with new traffic since the last look.
         for (const [channelKey, diverted] of this.divertedSinceInvocation) {
           if (diverted <= 0) continue;
-          const [serverId, channelId] = channelKey.split('\0') as [string, string];
+          const [serverId, channelId] = this.channelOf(channelKey);
           if (this.channelRegistry.getTuneOutState(serverId, channelId)) continue; // a per-channel epoch's own cadence
           this.invokeSubconscious(serverId, channelId, 'cadence', diverted);
         }
@@ -4686,7 +4700,7 @@ export class TuneOutCoordinator {
     this.writeScope(null);
     this.clearScopeTimers();
     for (const [key, pending] of this.pendingWakes) {
-      const [serverId, channelId] = key.split('\0') as [string, string];
+      const [serverId, channelId] = this.channelOf(key);
       if (this.channelRegistry.getTuneOutState(serverId, channelId)) continue;
       clearTimeout(pending.timer);
       this.pendingWakes.delete(key);
@@ -4730,7 +4744,7 @@ export class TuneOutCoordinator {
       }
     }
     for (const key of this.divertedSinceInvocation.keys()) {
-      const [serverId, channelId] = key.split('\0') as [string, string];
+      const [serverId, channelId] = this.channelOf(key);
       if (!this.channelRegistry.getTuneOutState(serverId, channelId)) this.divertedSinceInvocation.delete(key);
     }
     this.dropHandOffs(epochId);
@@ -5149,14 +5163,17 @@ export class TuneOutCoordinator {
     this.writeLooks(rest);
   }
 
-  /** At boot: the last looks of epochs no longer active go. */
   private pruneLooks(): void {
     if (this.hooks.subconsciousName() == null) return;
     const looks = this.lastLooks();
     if (!looks) return;
-    const active = new Set(this.listActive().map((e) => e.params.epochId));
-    const scope = this.getAllExcept();
-    if (scope) active.add(scope.params.epochId);
+    let active: Set<string>;
+    try {
+      active = new Set(this.holdsOnRecord().map((hold) => hold.epochId));
+    } catch (err) {
+      console.error(`[tune-out] the holds on record could not be read, so the subconscious's last looks are all kept: ${thrownReason(err)}`);
+      return;
+    }
     const kept = Object.fromEntries(Object.entries(looks).filter(([epochId]) => active.has(epochId)));
     if (Object.keys(kept).length !== Object.keys(looks).length) this.writeLooks(kept);
   }
@@ -5181,7 +5198,7 @@ export class TuneOutCoordinator {
     if (trigger === 'cadence' && backlog.length === 0) return false;
     // The cursor only moves forward: a returned row handed again can be
     // behind it.
-    const cursor = Math.max(this.readerCursor.get(key) ?? -1, ...backlog.map((m) => m.sequence));
+    const cursor = backlog.reduce((max, m) => Math.max(max, m.sequence), this.readerCursor.get(key) ?? -1);
     if (backlog.length > 0) this.readerCursor.set(key, cursor);
     const returned = this.readerReturned.get(key);
     if (returned) {

package/src/tune-out/tools.ts

@@ -1,6 +1,7 @@
 import type { ContentBlock } from '@animalabs/membrane';
 import { authorLine } from '../author-presentation.js';
 import type { StoredMessage } from '@animalabs/context-manager';
+import { appendAll } from '../append-all.js';
 /**
  * The subconscious's tool surface (issue #77).
  *
@@ -394,7 +395,7 @@ export function defaultReaderFraming(ctx: ReaderFramingContext): ContentBlock[]
     const media = message.content.filter((b) => b.type !== 'text');
     if (media.length > 0) {
       flush();
-      content.push(...media);
+      appendAll(content, media);
     }
   }
   flush();

package/src/types/agent.ts

@@ -221,11 +221,15 @@ export interface AgentConfig {
      * counts it. After a fold, each block after the stretch it rewrote is
      * bound to a conversation the request no longer holds. Where the context
      * strategy still sends such a block, the provider drops it on every call
-     * until a later fold takes it out of the context, and while such blocks
-     * are sent, no stream gives a sample and the calibration keeps the value
-     * it had. A strategy that leaves that thinking out at the fold sends none
-     * to drop. The direct API carries the control too, but reads no report: it
-     * traces no usage and feeds no calibration.
+     * until a later fold takes it out of the context, or, with `binds` set
+     * too, until the next compile after a note lands: the stream tells the
+     * context manager which stored reply's thinking was dropped
+     * (`noteThinkingDropped`), and once a note lands, the next compile sends
+     * that reply without it. While such blocks are sent,
+     * no stream gives a sample and the calibration keeps the value it had. A
+     * strategy that leaves that thinking out at the fold sends none to drop.
+     * The direct API carries the control too, but reads no report: it traces
+     * no usage, feeds no calibration and notes nothing.
      *
      * Default false: nothing is sent, and the account's default applies.
      */
@@ -249,6 +253,11 @@ export interface AgentConfig {
      *   thinking is kept at the next compile. The direct API
      *   (`runInference`) notes nothing, so each of its replies' thinking is
      *   left out at the compile after it's stored;
+     * - with `dropBlock` set too, each framework stream tells the context
+     *   manager which stored replies' thinking the provider reports dropping
+     *   (`noteThinkingDropped`), naming the compile it was built from, so
+     *   once a note lands, the next compile sends those replies without their
+     *   thinking;
      * - with `physicalWindowTokens` set too, `maxStreamTokens` no longer
      *   starts a new stream mid-turn, since the new stream's compile can take
      *   the turn's earlier reasoning out of the request;
@@ -753,6 +762,28 @@ export interface InferenceRequest {
    * channel (ambient-only batches leave it unset).
    */
   wakeChannelId?: string;
+  /**
+   * Framework-set on a gate wake whose batch held no message that addressed
+   * the agent, and which so took no route: the channels its messages came
+   * from (a `chat:system` notice names none, unless it's a coalesced
+   * render's latest occurrence), each once. A start merged from several
+   * requests carries every one's channels, or, when any of them comes from
+   * outside the framework, isn't a silent heartbeat tick and brought
+   * channels, only those requests' channels. A request a quiesce keeps in
+   * another's place, and one a provider hold takes another into, carry both
+   * requests' channels.
+   * The framework's own wakes that continue a
+   * turn (a restart, a re-inference, a continuation, a retry, a bounce, a
+   * re-arm), unless its own wake named a channel that resolves to none,
+   * carry the channels the turn's starts gathered, whether or not the turn
+   * had a locus, so a turn's trigger can name channels from several batches,
+   * and a turn they open with no locus can name them too.
+   * When such a turn's plain speech, or a sleep's announcement, is routed
+   * with no locus, the agent is told these channels, unless the turn's own
+   * wake named a channel that resolves to none, or the turn is an ephemeral
+   * run's, which is told nothing.
+   */
+  wakeChannels?: Array<{ serverId: string; channelId: string }>;
   /** Timestamp of the event the wake provenance was taken from (ms). */
   wakeAt?: number;
   /** Batched-wake lines the gate handed to this wake rather than wrote

package/src/types/framework.ts

@@ -191,18 +191,23 @@ export interface FrameworkConfig {
    * (architecture channel, 2026-10-06: the §3 carve-out accepted by the
    * residents).
    *
-   * - `'delivery'` (default): the locus comes only from the delivery that
-   *   woke the turn, a conversation fork's home channel, or a channel the
-   *   agent opened during the turn. Incoming traffic never moves it — not
-   *   between turns, not mid-turn. A turn with no such locus keeps its
-   *   prose private, and says so in a `[routing]` notice.
+   * - `'delivery'` (default): the locus comes from the delivery that woke
+   *   the turn, a conversation fork's home channel, or a channel the agent
+   *   opened during the turn, and past those only from an open all-except
+   *   hold's channel or `unpromptedChannel` (below), each for the turns that
+   *   take it. Incoming traffic never moves it — not between turns, not
+   *   mid-turn. A turn with no such locus keeps its prose private, and says
+   *   so in a `[routing]` notice.
    * - `'latest-inbound'`: the previous rule. The most recent delivered
    *   inbound message is a global fallback locus for turns without one, and
    *   an addressed message injected mid-turn re-pins the turn's locus.
    *
-   * Held traffic never moves the locus under either rule. Neither rule
-   * applies to an agent under locked prose routing (AgentConfig.proseRouting
-   * 'locked'): its turns speak at its lock, whatever arrives.
+   * Held traffic never moves the locus under either rule. Under either, a
+   * turn the agent's own timer starts takes `unpromptedChannel` where it's
+   * set, after an all-except hold's channel and before both rules' own
+   * fallbacks. Neither rule applies to an agent under locked prose routing
+   * (AgentConfig.proseRouting 'locked'): its turns speak at its lock,
+   * whatever arrives.
    */
   speech?: {
     locus?: 'delivery' | 'latest-inbound';
@@ -502,6 +507,35 @@ export interface FrameworkConfig {
    */
   inferenceRouting?: InferenceRoutingPolicy;
 
+  /**
+   * The channel for a turn the agent's own timer starts, which no message
+   * prompted: the wake `skip_reply` schedules, or the end of a `sleep`. Plain
+   * speech in locus or hybrid prose routing goes there, and so does
+   * `channel_publish` naming no channel in any prose routing mode but locked,
+   * which servers are told as the turn's default outgoing channel. An
+   * all-except hold's channel still comes first while one is open, and without
+   * the setting such a turn follows `speech.locus`. A turn the framework opens
+   * to continue such a turn that had no locus of its own, as in explicit or
+   * disabled routing, takes it too: a `!` continuation, autoContinue's next
+   * turn, or a bounced reply's wake. No other turn takes it: not one a message
+   * prompted, from a channel, a module, a person at a console or another agent;
+   * not a heartbeat's or a reminder's (its plain speech is held as drafts); not
+   * a conversation fork's or an ephemeral run's; not a locked agent's, which
+   * speaks at its lock or holds its speech as drafts; and not a start merged
+   * from a timer's wake and any other cause. One value, for every agent on the
+   * framework. A registered channel's id, e.g. `discord:{guildId}:{channelId}`,
+   * or, to pick one server's where two register that id,
+   * `{serverId}:{channelId}`. `create()` refuses a value that is neither a
+   * string nor null, or is blank; null reads as not set. A value that names no
+   * registered channel, several, or one its server declared inbound-only, when
+   * a turn would take it, is logged, and logged again only after a turn has
+   * used it since; the turn takes what it would without the setting.
+   * `channel_publish`'s description adds a default for such turns only on a
+   * framework with an event gate, the only one with such turns; on any other
+   * the description is as it is without the setting.
+   */
+  unpromptedChannel?: string | null;
+
   /** EventGate config. If omitted, all events trigger inference (unchanged default). */
   gate?: GateOptions;
   /**
@@ -677,6 +711,8 @@ export interface InferenceLogEntry {
   success: boolean;
   /** Why it didn't succeed: the failure's message, or what stopped it */
   error?: string;
+  /** `error` in the framework's words, with no provider's text: what an agent may be shown of it */
+  errorWords?: string;
   /** Request data or blob ID if large. A stream the framework ended at a
    *  tool boundary (stopReason 'turn_ended', 'context_budget' or
    *  'physical_window') records a note in place of the body. */

package/src/types/inference-log.ts

@@ -54,6 +54,7 @@ export interface InferenceLogSummary {
   requestId: string;
   success: boolean;
   error?: string;
+  errorWords?: string;
   durationMs: number;
   tokenUsage?: { input: number; output: number; cacheCreation?: number; cacheRead?: number };
   stopReason?: string;

package/src/types/trace.ts

@@ -142,6 +142,14 @@ export type TraceEvent =
       agentName: string;
       /** The failure's message, bounded as every trace event's `error` is (2,000 characters). */
       error: string;
+      /**
+       * The reason the agent's `[inference-failed]` note may give, before the
+       * note's own 600-character cut, and bounded as `error` is. Present only
+       * when the failure's message holds no provider's text: a progress
+       * bound's cut, a stream's abort, or context-manager's refusal of a
+       * compile. Absent otherwise, and a note then gives no reason.
+       */
+      shownReason?: string;
       /** Whether membrane classified the failure as retryable (observability). */
       retryable?: boolean;
       /**
@@ -156,6 +164,55 @@ export type TraceEvent =
       /** The provider's own error code, when it sent one (at most 128 characters). */
       providerErrorCode?: string;
     })
+  | (TraceEventBase & {
+      /**
+       * A start whose compile was refused for budget while compression was
+       * pending waits in the agent's budget hold, idle, instead of failing
+       * (#304). It follows the refused attempt's `inference:failed`. Once
+       * something the refused compile depends on has changed (compression's
+       * progress, nothing left pending, a surgery or an undo, the agent's
+       * budget or live context settings, or a quiesce's end), the hold ends,
+       * the held requests are queued, and its note is stored as the agent's
+       * own row, entering its window at once or, while a turn of the agent's
+       * is alive, at its next presentation point; a failed write stores
+       * none. Their start's own compile is the check: refused again while
+       * compression is pending, it waits in a new hold, with a new
+       * `inference:held`. `inference:hold_ended` follows each, once. An
+       * ephemeral run's start, and one before the framework's `start()`,
+       * never waits.
+       */
+      type: 'inference:held';
+      agentName: string;
+      /** 'over_budget', or 'context_refusal' when no summary covers a span the compile would drop. */
+      errorType: 'over_budget' | 'context_refusal';
+      /** The refusal's message, bounded as a trace event's `error` is (2,000 characters). */
+      error: string;
+      /** The refused compile's budget and size in tokens, when context-manager gave them. */
+      budget?: number;
+      actual?: number;
+      /** When this hold started (epoch ms). A wait held again after its
+       *  release starts a new hold; its `context-refusal` alert and the note
+       *  count from the wait's first hold. */
+      since: number;
+      /** Requests the hold holds as it starts: the refused start's own. */
+      heldRequests: number;
+    })
+  | (TraceEventBase & {
+      type: 'inference:hold_ended';
+      agentName: string;
+      /**
+       * 'released': something the refused compile depends on changed, so the
+       * held requests were queued and their start's compile is the check.
+       * 'stopped': the held turn was ended by `abortInference()`, `stop()` or
+       * its agent's end, reported after its `inference:aborted`. 'removed': a
+       * surgery or an undo removed what the held turn stood on, reported after
+       * its `inference:aborted`, and the wakes that joined it go back to the
+       * queue.
+       */
+      outcome: 'released' | 'stopped' | 'removed';
+      /** Since the hold started (`inference:held`'s `since`). */
+      waitedMs: number;
+    })
 
   // Streaming inference lifecycle
   | (TraceEventBase & {
@@ -1043,14 +1100,19 @@ export type TraceEvent =
   // this stream, not a separate system. See connectome docs/observability.md.
   | (TraceEventBase & {
       type: 'ops:alert';
-      /** Alert kind — open set: 'refusal' | 'hard-down' | 'mcpl-down' | … */
+      /** Alert kind — open set: 'refusal' | 'hard-down' | 'mcpl-down' | …
+       *  A kind ending in `-clear` ends the alert of the kind before it:
+       *  'context-refusal-clear' is raised when a budget hold whose wait
+       *  raised 'context-refusal' ends with its turn stopped or removed, so
+       *  the waiting start doesn't run. */
       kind: string;
       /** Agent name, or a server/component id for non-agent alerts (e.g. mcpl-down). */
       agentName: string;
       /** At most 2,000 characters. */
       message: string;
-      /** Kind-specific structured payload (mirrors the failures.log record),
-       *  bounded field by field as that record is. */
+      /** Kind-specific structured payload (mirrors the failures.log record,
+       *  where the alert writes one: a budget hold's 'context-refusal' and its
+       *  clear write none), bounded field by field as that record is. */
       data?: Record<string, unknown>;
     })
 
@@ -1560,7 +1622,7 @@ export type TraceEvent =
     });
 
 /** Why rows left an agent's window (`presentation:retracted`). */
-export type PresentationRetractReason = 'hide' | 'suppress' | 'coalescer' | 'module' | 'resume' | 'rewind' | 'shed' | 'boot' | 'elsewhere';
+export type PresentationRetractReason = 'hide' | 'suppress' | 'coalescer' | 'module' | 'resume' | 'rewind' | 'shed' | 'boot' | 'elsewhere' | 'unsent-injection';
 
 /**
  * Listener for trace events.