@animalabs/agent-framework 0.22.2 → 0.22.3

package/src/tune-out/coordinator.ts

@@ -21,6 +21,7 @@ import type { StoredMessage } from '@animalabs/context-manager';
 import type { ChannelRegistry, TuneOutParams } from '../mcpl/channel-registry.js';
 import type { McplServerRegistry } from '../mcpl/server-registry.js';
 import { CapabilityGrant } from '../mcpl/capability-grant.js';
+import { armAfter, armAt } from '../deadline-timer.js';
 
 /** Defaults for tune_out tool params. */
 export const TUNE_OUT_DEFAULTS = {
@@ -33,6 +34,19 @@ export const TUNE_OUT_DEFAULTS = {
  *  subconscious turn, and max-wakes counts invocations, not messages. */
 const WAKE_COALESCE_MS = 2_000;
 
+/** How long after an end time whose cancel threw the cancel is tried again. */
+const EXPIRY_RETRY_MS = 60_000;
+
+/** What a thrown value says, without throwing: an Error's message, or the
+ *  value as text, which String() can't give for an object with no prototype. */
+function thrownReason(error: unknown): string {
+  try {
+    return error instanceof Error ? error.message : String(error);
+  } catch {
+    return '(a value that could not be read)';
+  }
+}
+
 export interface TuneOutFrameworkHooks {
   /** Deliver a message into an agent's window (per-agent seam). */
   addMessage: (
@@ -64,7 +78,11 @@ export interface TuneOutFrameworkHooks {
 
 export class TuneOutCoordinator {
   private cadenceTimers = new Map<string, ReturnType<typeof setTimeout>>();
-  /** Duration-expiry timers (params.expiresAtMs); cleared on any cancel. */
+  /** Each duration's pending timer: a step toward its end time
+   *  (params.expiresAtMs), or the retry of an end-time cancel that threw.
+   *  stop clears it, cancel does when it finds the tune-out in the registry,
+   *  the end time does when its cancel finds the tune-out already ended,
+   *  and the channel's next accepted enter does in any case. */
   private expiryTimers = new Map<string, ReturnType<typeof setTimeout>>();
   /** Channels with a wake invocation pending inside the coalescing window. */
   private pendingWakes = new Map<string, { count: number; timer: ReturnType<typeof setTimeout> }>();
@@ -108,11 +126,36 @@ export class TuneOutCoordinator {
     const key = this.key(serverId, channelId);
     const existing = this.expiryTimers.get(key);
     if (existing) clearTimeout(existing);
-    const remaining = Math.max(0, params.expiresAtMs - Date.now());
-    this.expiryTimers.set(key, setTimeout(() => {
-      this.expiryTimers.delete(key);
-      this.cancel(serverId, channelId, 'duration', 'duration elapsed');
-    }, remaining));
+    const hold = (timer: ReturnType<typeof setTimeout>): void => { this.expiryTimers.set(key, timer); };
+    const end = (): void => {
+      try {
+        // The retry is armed before the cancel, as the cadence arms its next
+        // period before its turn, so a cancel that throws is tried again. A
+        // cancel that ends the tune-out clears it with the channel's other
+        // timers, and so does finding the tune-out already ended.
+        hold(setTimeout(end, EXPIRY_RETRY_MS));
+        if (!this.cancel(serverId, channelId, 'duration', 'duration elapsed').ok) {
+          this.clearTimers(serverId, channelId);
+        }
+      } catch (err) {
+        this.timerFailed('expiry', serverId, channelId, err);
+      }
+    };
+    armAt(params.expiresAtMs, hold, end);
+  }
+
+  /** A timer callback's work threw. Report it on stderr and as a trace rather
+   *  than throw it into the event loop, where an uncaught exception ends the
+   *  host process. */
+  private timerFailed(timer: 'cadence' | 'wake' | 'expiry', serverId: string, channelId: string, err: unknown): void {
+    console.error(`[tune-out] the ${timer} timer for ${channelId} on ${serverId} failed:`, err);
+    this.hooks.emitTrace({
+      type: 'tune-out:timer-failed',
+      timer,
+      serverId,
+      channelId,
+      error: thrownReason(err),
+    });
   }
 
   private listActive(): Array<{ serverId: string; channelId: string; params: TuneOutParams }> {
@@ -137,24 +180,89 @@ export class TuneOutCoordinator {
     source: string,
   ): { ok: true; params: TuneOutParams } | { ok: false; error: string } {
     if (!this.hooks.subconsciousName()) {
-      return { ok: false, error: 'tune-out requires the subconscious resident (framework config `subconscious`)' };
+      return {
+        ok: false,
+        error: 'Nothing was tuned out: this host has no subconscious resident to watch a channel, so tune_out '
+          + "isn't available here, and calling it again won't change that. If you need channels diverted, ask "
+          + 'whoever runs this host.',
+      };
     }
     if (this.hooks.isForkBound(channelId)) {
-      return { ok: false, error: `channel ${channelId} is bound to a conversation fork; tune-out and fork routing are mutually exclusive` };
+      return {
+        ok: false,
+        error: `Nothing changed: a conversation is bound to ${JSON.stringify(channelId)}, so its messages go to that `
+          + "conversation, and tune_out won't divert a channel while one is. Calling tune_out on it again won't change "
+          + 'that until the conversation ends, which happens only once the channel has been quiet for a while. Tune '
+          + 'out a different channel, or ask whoever runs this host if this one should be diverted.',
+      };
+    }
+    const current = this.channelRegistry.getTuneOutState(serverId, channelId);
+    if (current) {
+      const p = current.params;
+      // A duration so long its end is past what a Date can hold has no time to show.
+      const expires = p.expiresAtMs !== undefined ? new Date(p.expiresAtMs) : undefined;
+      const until = expires && Number.isFinite(expires.getTime())
+        ? `, until ${expires.toISOString().replace(/\.\d+Z$/, 'Z')}`
+        : '';
+      return {
+        ok: false,
+        error: `Nothing changed: ${JSON.stringify(channelId)} is already tuned out, with cadenceSeconds `
+          + `${p.cadenceSeconds}, backlogCap ${p.backlogCap} and maxWakes ${p.maxWakes}${until}. To change those, `
+          + 'cancel it first with tune_out mode "cancel", which delivers its backlog to you now, then call tune_out '
+          + 'again with the new settings.',
+      };
     }
-    if (this.channelRegistry.getTuneOutState(serverId, channelId)) {
-      return { ok: false, error: `channel ${channelId} is already tuned out (cancel first to change params)` };
+    // A tool's input reaches here as the model wrote it, and the store can't
+    // keep a NaN or an Infinity: its append would throw after the registry
+    // had marked the channel tuned out. So each option is read as a number
+    // before anything changes, a numeric string included, as the sleep tool
+    // reads its seconds; null counts as left out. A value that gives no
+    // finite number is refused.
+    const leftOut = {
+      durationSeconds: 'to stay tuned out until you cancel',
+      cadenceSeconds: `for the default, ${TUNE_OUT_DEFAULTS.cadenceSeconds}`,
+      backlogCap: `for the default, ${TUNE_OUT_DEFAULTS.backlogCap}`,
+      maxWakes: `for the default, ${TUNE_OUT_DEFAULTS.maxWakes}`,
+    } as const;
+    const given: Partial<Record<keyof typeof leftOut, number>> = {};
+    for (const name of Object.keys(leftOut) as Array<keyof typeof leftOut>) {
+      const value: unknown = opts[name];
+      if (value == null) continue;
+      const n = Number(value);
+      if (!Number.isFinite(n)) {
+        const got = typeof value === 'number'
+          ? String(value)
+          : `${typeof value === 'string' ? 'the string' : 'the value'} ${JSON.stringify(value)}`;
+        return {
+          ok: false,
+          error: `Nothing was tuned out: ${name} must be a finite number${name.endsWith('Seconds') ? ' of seconds' : ''}, `
+            + `and it was ${got}. Leave it out ${leftOut[name]}.`,
+        };
+      }
+      given[name] = n;
+    }
+    const expiresAtMs = given.durationSeconds === undefined
+      ? undefined
+      : Date.now() + Math.max(60, given.durationSeconds) * 1000;
+    if (expiresAtMs !== undefined && !Number.isFinite(expiresAtMs)) {
+      return {
+        ok: false,
+        error: `Nothing was tuned out: durationSeconds ${given.durationSeconds} is longer than an end time can be kept. `
+          + `Leave it out ${leftOut.durationSeconds}.`,
+      };
     }
     const params: TuneOutParams = {
       epochId: randomUUID(),
-      cadenceSeconds: Math.max(30, opts.cadenceSeconds ?? TUNE_OUT_DEFAULTS.cadenceSeconds),
-      backlogCap: Math.max(0, opts.backlogCap ?? TUNE_OUT_DEFAULTS.backlogCap),
-      maxWakes: Math.max(1, opts.maxWakes ?? TUNE_OUT_DEFAULTS.maxWakes),
+      cadenceSeconds: Math.max(30, given.cadenceSeconds ?? TUNE_OUT_DEFAULTS.cadenceSeconds),
+      backlogCap: Math.max(0, given.backlogCap ?? TUNE_OUT_DEFAULTS.backlogCap),
+      maxWakes: Math.max(1, given.maxWakes ?? TUNE_OUT_DEFAULTS.maxWakes),
       startedAtSequence: this.hooks.currentSequence(),
-      ...(opts.durationSeconds !== undefined
-        ? { expiresAtMs: Date.now() + Math.max(60, opts.durationSeconds) * 1000 }
-        : {}),
+      ...(expiresAtMs !== undefined ? { expiresAtMs } : {}),
     };
+    // A tune-out can end in the registry without cancel (a send into the
+    // channel or a close sets its state there), leaving its timers armed:
+    // clear them, so none of them acts on this one.
+    this.clearTimers(serverId, channelId);
     this.channelRegistry.enterTuneOut(serverId, channelId, params, source);
     this.armExpiry(serverId, channelId, params);
 
@@ -188,19 +296,10 @@ export class TuneOutCoordinator {
   ): { ok: true } | { ok: false; error: string } {
     const ended = this.channelRegistry.cancelTuneOut(serverId, channelId, 'open', source);
     if (!ended) {
-      return { ok: false, error: `channel ${channelId} is not tuned out` };
-    }
-    this.stopCadence(serverId, channelId);
-    const expiry = this.expiryTimers.get(this.key(serverId, channelId));
-    if (expiry) {
-      clearTimeout(expiry);
-      this.expiryTimers.delete(this.key(serverId, channelId));
-    }
-    const pending = this.pendingWakes.get(this.key(serverId, channelId));
-    if (pending) {
-      clearTimeout(pending.timer);
-      this.pendingWakes.delete(this.key(serverId, channelId));
+      // Its reader is the resident's tune_out: cancel_tuneout finds the channel first.
+      return { ok: false, error: this.notTunedOut(channelId, 'you') };
     }
+    this.clearTimers(serverId, channelId);
     this.divertedSinceInvocation.delete(this.key(serverId, channelId));
 
     // Backlog: every message stamped with this epoch, oldest first.
@@ -326,11 +425,12 @@ export class TuneOutCoordinator {
         intent: 'suppressed-tuned-out',
       });
     } catch (err) {
+      console.error(`[tune-out] acknowledging ${messageId} in ${channelId} on ${serverId} failed:`, err);
       this.hooks.emitTrace({
         type: 'tune-out:ack-failed',
         serverId,
         channelId,
-        error: (err as Error).message,
+        error: thrownReason(err),
       });
     }
   }
@@ -342,17 +442,37 @@ export class TuneOutCoordinator {
   private startCadence(serverId: string, channelId: string, cadenceSeconds: number): void {
     this.stopCadence(serverId, channelId);
     const key = this.key(serverId, channelId);
+    const hold = (timer: ReturnType<typeof setTimeout>): void => { this.cadenceTimers.set(key, timer); };
     const tick = () => {
-      const state = this.channelRegistry.getTuneOutState(serverId, channelId);
-      if (!state) return; // cancelled meanwhile
-      const diverted = this.divertedSinceInvocation.get(key) ?? 0;
-      // An empty period needs no turn at all — skip silently.
-      if (diverted > 0) {
-        this.invokeSubconscious(serverId, channelId, 'cadence', diverted);
+      try {
+        const state = this.channelRegistry.getTuneOutState(serverId, channelId);
+        if (!state) return; // cancelled meanwhile
+        // The next period is armed before this one's turn, so a turn that
+        // fails can't end the cadence.
+        armAfter(cadenceSeconds * 1000, hold, tick);
+        const diverted = this.divertedSinceInvocation.get(key) ?? 0;
+        // An empty period needs no turn at all — skip silently.
+        if (diverted > 0) {
+          this.invokeSubconscious(serverId, channelId, 'cadence', diverted);
+        }
+      } catch (err) {
+        this.timerFailed('cadence', serverId, channelId, err);
       }
-      this.cadenceTimers.set(key, setTimeout(tick, cadenceSeconds * 1000));
     };
-    this.cadenceTimers.set(key, setTimeout(tick, cadenceSeconds * 1000));
+    armAfter(cadenceSeconds * 1000, hold, tick);
+  }
+
+  /** Clear a channel's tune-out timers: its cadence, its end time and a wake
+   *  still coalescing. */
+  private clearTimers(serverId: string, channelId: string): void {
+    const key = this.key(serverId, channelId);
+    this.stopCadence(serverId, channelId);
+    const expiry = this.expiryTimers.get(key);
+    if (expiry) clearTimeout(expiry);
+    this.expiryTimers.delete(key);
+    const pending = this.pendingWakes.get(key);
+    if (pending) clearTimeout(pending.timer);
+    this.pendingWakes.delete(key);
   }
 
   private stopCadence(serverId: string, channelId: string): void {
@@ -370,21 +490,25 @@ export class TuneOutCoordinator {
       return;
     }
     const timer = setTimeout(() => {
-      const entry = this.pendingWakes.get(key);
-      this.pendingWakes.delete(key);
-      // Count ONE durable wake per coalesced invocation.
-      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})`,
-        );
-        return;
+      try {
+        const entry = this.pendingWakes.get(key);
+        this.pendingWakes.delete(key);
+        // Count ONE durable wake per coalesced invocation.
+        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})`,
+          );
+          return;
+        }
+        this.invokeSubconscious(serverId, channelId, 'wake', entry?.count ?? 1);
+      } catch (err) {
+        this.timerFailed('wake', serverId, channelId, err);
       }
-      this.invokeSubconscious(serverId, channelId, 'wake', entry?.count ?? 1);
     }, WAKE_COALESCE_MS);
     this.pendingWakes.set(key, { count: 1, timer });
   }
@@ -403,7 +527,6 @@ export class TuneOutCoordinator {
     const subName = this.hooks.subconsciousName();
     if (!subName) return;
     const key = this.key(serverId, channelId);
-    this.divertedSinceInvocation.set(key, 0);
 
     const notice = trigger === 'wake'
       ? `[Tune-out wake: ${channelId} — ${count} addressed message${count === 1 ? '' : 's'}]`
@@ -415,6 +538,9 @@ export class TuneOutCoordinator {
       subName,
     );
     this.hooks.requestInference(subName, `tune-out ${trigger}: ${channelId}`, 'tune-out');
+    // Counted from here only once the turn has been asked for, so a turn that
+    // throws leaves its messages for the next period's turn.
+    this.divertedSinceInvocation.set(key, 0);
   }
 
   // ==========================================================================
@@ -432,6 +558,8 @@ export class TuneOutCoordinator {
    * subconscious's compiles (antra: deliver changes, never let them wash
    * away — it has no long-term memory, so they must not live in window
    * content). Bytes change only when a disposition changes: KV-friendly.
+   * A failed read of the stored map throws, so the compile stops rather than
+   * run without them.
    */
   getDispositionsInjection(): {
     namespace: string;
@@ -453,12 +581,17 @@ export class TuneOutCoordinator {
 
   private readDispositions(): Record<string, string> {
     if (this.dispositionsCache) return this.dispositionsCache;
+    let raw: unknown;
     try {
-      const raw = this.channelRegistry.readCoordinatorState(this.dispositionsStateId);
-      this.dispositionsCache = (raw && typeof raw === 'object') ? raw as Record<string, string> : {};
-    } catch {
-      this.dispositionsCache = {};
+      raw = this.channelRegistry.readCoordinatorState(this.dispositionsStateId);
+    } catch (error) {
+      // A failed read is not an empty map, and nothing is cached, so the next
+      // read asks the store again. Taken as empty, it would compile the
+      // subconscious without its dispositions until a restart, and the next
+      // noteDisposition would write that empty map over the stored one.
+      throw new Error(`the stored dispositions (${this.dispositionsStateId}) could not be read: ${thrownReason(error)}`, { cause: error });
     }
+    this.dispositionsCache = (raw && typeof raw === 'object') ? raw as Record<string, string> : {};
     return this.dispositionsCache;
   }
 
@@ -469,8 +602,14 @@ export class TuneOutCoordinator {
     } else {
       dispositions[key] = text;
     }
+    // Stored before it's cached: a write that fails leaves the cache and the
+    // store as they were, so the note is in effect nowhere.
+    try {
+      this.channelRegistry.writeCoordinatorState(this.dispositionsStateId, dispositions);
+    } catch (error) {
+      throw new Error(`the dispositions (${this.dispositionsStateId}) could not be stored: ${thrownReason(error)}`, { cause: error });
+    }
     this.dispositionsCache = dispositions;
-    this.channelRegistry.writeCoordinatorState(this.dispositionsStateId, dispositions);
   }
 
   // ==========================================================================
@@ -485,7 +624,14 @@ export class TuneOutCoordinator {
       case 'deliver_summary': {
         const text = String(input.text ?? '').trim();
         const channelId = String(input.channelId ?? '');
-        if (!text) return { success: false, error: 'empty summary', isError: false };
+        if (!text) {
+          return {
+            success: false,
+            error: 'Nothing was delivered: deliver_summary needs the summary in "text". If there\'s nothing to '
+              + "report, don't call it: staying silent is allowed.",
+            isError: true,
+          };
+        }
         const subName = this.hooks.subconsciousName();
         if (!subName) return { success: false, error: 'subconscious not configured', isError: true };
         // Verbatim, under its own participant name, into the resident's window.
@@ -498,30 +644,58 @@ export class TuneOutCoordinator {
       case 'cancel_tuneout': {
         const channelId = String(input.channelId ?? '');
         const located = this.findByChannel(channelId);
-        if (!located) return { success: false, error: `channel ${channelId} is not tuned out`, isError: false };
+        if (!located) return { success: false, error: this.notTunedOut(channelId, 'the resident'), isError: true };
         const note = typeof input.text === 'string' && input.text.trim() ? input.text.trim() : undefined;
         const result = this.cancel(located.serverId, channelId, 'subconscious', 'subconscious judgment', note);
         return result.ok
           ? { success: true, data: { cancelled: true } }
-          : { success: false, error: result.error, isError: false };
+          : { success: false, error: result.error, isError: true };
       }
       case 'note_disposition': {
         const key = String(input.key ?? '').trim();
-        if (!key) return { success: false, error: 'key required', isError: false };
-        this.noteDisposition(key, String(input.text ?? ''));
+        if (!key) {
+          return {
+            success: false,
+            error: 'Nothing was recorded: note_disposition needs a "key", a short stable name for the note, such as '
+              + '"busy-channels". To delete a note, call it with that note\'s key and an empty "text".',
+            isError: true,
+          };
+        }
+        try {
+          this.noteDisposition(key, String(input.text ?? ''));
+        } catch (error) {
+          // For the subconscious first: what became of its note, and that a
+          // later call may land. The store's own reason follows, for an operator.
+          // The note may set, change or remove a disposition, so what stays in
+          // effect is whatever was there before, if anything.
+          return {
+            success: false,
+            isError: true,
+            error: `The change to the disposition ${JSON.stringify(key)} wasn't recorded, so the dispositions stay as they were. ` +
+              `Noting it again may work once the store can be read and written. The store's error: ${thrownReason(error)}`,
+          };
+        }
         return { success: true, data: { noted: key } };
       }
       case 'speak_in_channel': {
         if (!this.hooks.allowChannelSpeech()) {
+          // The setting's name is the host's, for its log; the subconscious
+          // reads what it can do instead.
+          console.warn('[tune-out] speak_in_channel refused: FrameworkConfig.subconscious.allowChannelSpeech is off');
           return {
             success: false,
-            isError: false,
-            error: 'channel speech is disabled for the subconscious (recipe: subconscious.allowChannelSpeech)',
+            isError: true,
+            error: "Nothing was posted: speak_in_channel is turned off for you in the resident's configuration, and "
+              + "calling it again won't change that. The resident can speak there: tell it what's needed with "
+              + 'deliver_summary, or, if the channel is tuned out and needs the resident now, end the tune-out with '
+              + 'cancel_tuneout.',
           };
         }
         const channelId = String(input.channelId ?? '');
         const text = String(input.text ?? '').trim();
-        if (!text) return { success: false, error: 'empty message', isError: false };
+        if (!text) {
+          return { success: false, error: 'Nothing was posted: speak_in_channel needs the message in "text".', isError: true };
+        }
         return this.channelRegistry.publishForAgent(channelId, text, this.hooks.subconsciousName() ?? 'Subconscious');
       }
       default:
@@ -529,6 +703,26 @@ export class TuneOutCoordinator {
     }
   }
 
+  /**
+   * A cancel of a channel that isn't tuned out: which channels are, so the
+   * next call can name one, and how a tune-out ends without one. `backlogTo`
+   * names the resident as the message's reader knows it: "you" to the
+   * resident, "the resident" to the subconscious. It speaks of connected
+   * channels because listActive reads the registered ones: removing a server
+   * drops its channels and keeps their tune-outs, so a tune-out there is in
+   * neither this list nor findByChannel's lookup, and the text claims nothing
+   * about it.
+   */
+  private notTunedOut(channelId: string, backlogTo: 'you' | 'the resident'): string {
+    const active = this.listActive().map((e) => JSON.stringify(e.channelId));
+    const opening = active.length === 0
+      ? 'no connected channel is tuned out now.'
+      : `no connected channel ${JSON.stringify(channelId)} is tuned out. Connected channels tuned out now: `
+        + `${active.join(', ')}.`;
+    return `Nothing was cancelled: ${opening} A tune-out also ends by itself when its duration runs out, or at the `
+      + `first wake past its wake budget, and its backlog goes to ${backlogTo} then.`;
+  }
+
   private findByChannel(channelId: string): { serverId: string } | null {
     for (const entry of this.listActive()) {
       if (entry.channelId === channelId) return { serverId: entry.serverId };

package/src/types/agent.ts

@@ -93,11 +93,16 @@ export interface AgentConfig {
   promptCaching?: boolean;
 
   /**
-   * Prefill-formatter support: a synthetic user message appended after the
-   * conversation (e.g. chapterx's `<cmd>cat untitled.txt</cmd>` CLI-sim
-   * scaffold). Forwarded verbatim to membrane's prefill formatters; ignored
-   * by native formatting. Part of reproducing a prefill-era bot's exact
-   * prompting structure when migrating it into a resident.
+   * A synthetic user message for a request whose formatted conversation
+   * would otherwise begin with the assistant (e.g. chapterx's
+   * `<cmd>cat untitled.txt</cmd>` CLI-sim scaffold). A non-empty value is
+   * forwarded verbatim to membrane, on framework turns and the direct API
+   * alike. Membrane's anthropic-xml formatter makes it the first message,
+   * ahead of the assistant turn that carries the conversation. Its native
+   * formatter uses it as the text of a leading user turn that its tool-pair
+   * normalizer adds, in place of `[continuing]`. Part of reproducing a
+   * prefill-era bot's exact prompting structure when migrating it into a
+   * resident.
    */
   prefillUserMessage?: string;
 
@@ -307,13 +312,18 @@ export interface InferenceOptions {
 
 /**
  * Internal state of an agent.
+ *
+ * `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.
  */
 export type AgentState =
   | { status: 'idle' }
   | { status: 'inferring'; promise: Promise<InferenceResult>; abortController: AbortController }
   | { status: 'streaming'; stream: YieldingStream }
-  | { status: 'waiting_for_tools'; pending: Map<ToolCallId, PendingToolCall>; completed: CompletedToolCall[]; stream?: YieldingStream }
-  | { status: 'ready'; toolResults: CompletedToolCall[]; stream?: YieldingStream };
+  | { status: 'waiting_for_tools'; pending: Map<ToolCallId, PendingToolCall>; completed: CompletedToolCall[]; stream?: YieldingStream; supportsInjectedMessages?: boolean }
+  | { status: 'ready'; toolResults: CompletedToolCall[]; stream?: YieldingStream; supportsInjectedMessages?: boolean };
 
 /**
  * A tool call that's in progress.

package/src/types/events.ts

@@ -225,6 +225,19 @@ export interface ToolCall {
   input: unknown;
   /** The agent that made this tool call. Set by the framework dispatch layer. */
   callerAgentName?: string;
+  /**
+   * The turn the call was made in, the same id as that turn's
+   * `SpeechContext.turnId`. Set by the framework dispatch layer, beside
+   * `callerAgentName`: a model's call carries the turn whose stream made it, a
+   * foreground script's inner call the turn of the code_execution call whose
+   * script is running when the call arrives, and a utility run its `utils`
+   * call's. A background script runs apart from any turn, so its calls carry
+   * none. Ids increase, so a later turn's is larger, and they're unique only
+   * within one run of the process. A call made with `executeToolCall` or a
+   * module's `callTool` skips that layer and carries whatever turn its caller
+   * put on the call, usually none.
+   */
+  callerTurnId?: number;
 }
 
 // ============================================================================
@@ -247,6 +260,8 @@ export interface McplPushEvent {
   inferenceId: string;
   triggerInference?: boolean;
   targetAgents?: string[];
+  /** Host acceptance time (epoch ms), stamped where the push is admitted. */
+  acceptedAt?: number;
 }
 
 /**
@@ -265,4 +280,6 @@ export interface McplChannelIncomingEvent {
   metadata?: Record<string, unknown>;
   triggerInference?: boolean;
   targetAgents?: string[];
+  /** Host acceptance time (epoch ms), stamped where the message is admitted. */
+  acceptedAt?: number;
 }

package/src/types/framework.ts

@@ -41,7 +41,9 @@ export interface ProcessLoggingConfig {
  * the agent already has broader host access through its tools).
  */
 export interface CodeExecutionConfig {
-  /** Master switch — the tool is only synthesized when true. */
+  /** Master switch — only `true` synthesizes the tool. `create()` refuses a
+   *  value that isn't a boolean, a quoted "false" included; `null` or leaving
+   *  it out counts as off. */
   enabled: boolean;
   /** Python interpreter to spawn (default: 'python3' from PATH). */
   pythonPath?: string;
@@ -210,7 +212,9 @@ export interface FrameworkConfig {
 
   /**
    * Client-side programmatic tool calling (`code_execution` tool). Omitted or
-   * `enabled: false` → tool absent, no python is ever spawned.
+   * `enabled: false` → tool absent, no python is ever spawned. At runtime,
+   * untyped configs may also use `null` or `false` to omit this setting.
+   * Other values that aren't objects are refused at `create()`.
    */
   codeExecution?: CodeExecutionConfig;
 
@@ -411,20 +415,32 @@ export interface InferenceLogEntry {
   requestId: string;
   /** Whether inference succeeded */
   success: boolean;
-  /** Error message if failed */
+  /** Why it didn't succeed: the failure's message, or what stopped it */
   error?: string;
-  /** Request data or blob ID if large */
+  /** 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. */
   request: unknown | { blobId: string };
   /** Response data or blob ID if large (only if successful) */
   response?: unknown | { blobId: string };
   durationMs: number;
+  /** The stream's usage: its final response's, or, for a stream that ended
+   *  without one, the provider rounds it finished before it ended. Exactly
+   *  one entry of a stream carries it, the one its end wrote, a stop's
+   *  included; a stream whose end writes none (a superseded stream, a
+   *  disposed agent's stream) gets a failure entry that carries it, when it
+   *  had finished a round. One that hadn't has nothing to carry and gets no
+   *  entry. */
   tokenUsage?: {
     input: number;
     output: number;
     cacheCreation?: number;
     cacheRead?: number;
   };
-  /** Stop reason from the model */
+  /** Stop reason from the model, or why the framework ended the stream at a
+   *  tool boundary: 'turn_ended' (a tool result with endTurn), or
+   *  'context_budget' / 'physical_window' (a context-budget or
+   *  physical-window restart). */
   stopReason?: string;
 }
 

package/src/types/inference-log.ts

@@ -17,7 +17,7 @@ export interface InferenceLogQuery {
   offset?: number;
   /** Search pattern for content (regex) */
   pattern?: string;
-  /** Only show failures */
+  /** Only show inferences that didn't succeed: failed or stopped */
   errorsOnly?: boolean;
 }