@animalabs/agent-framework 0.26.1 → 0.27.0

package/src/tune-out/coordinator.ts

@@ -18,7 +18,7 @@
 import { randomUUID } from 'node:crypto';
 import type { ContentBlock } from '@animalabs/membrane';
 import type { StoredMessage } from '@animalabs/context-manager';
-import type { ChannelRegistry, TuneOutParams } from '../mcpl/channel-registry.js';
+import type { ChannelRef, 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';
@@ -45,7 +45,7 @@ const CUT_MARK = " [cut to fit; the whole message is in the channel's history]";
  * its transport is now where the repeat tried to open it again (`transport`,
  * from the framework's dispatch), then how to change the settings.
  */
-export function alreadyTunedOutText(channelId: string, p: TuneOutParams, transport?: string): string {
+export function alreadyTunedOutText(shown: string, p: TuneOutParams, transport?: string): string {
   // 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())
@@ -53,7 +53,7 @@ export function alreadyTunedOutText(channelId: string, p: TuneOutParams, transpo
     : '';
   // A thrown error's words may end without a stop.
   const now = transport === undefined ? '' : /[.!?]$/.test(transport) ? `${transport} ` : `${transport}. `;
-  return `Nothing changed${transport !== undefined ? ' in the tune-out' : ''}: ${JSON.stringify(channelId)} is already `
+  return `Nothing changed${transport !== undefined ? ' in the tune-out' : ''}: ${JSON.stringify(shown)} is already `
     + `tuned out, with cadenceSeconds ${p.cadenceSeconds}, backlogCap ${p.backlogCap} and maxWakes ${p.maxWakes}${until}. `
     + now
     + 'To change those, cancel it first with tune_out mode "cancel", which delivers its backlog to you now, then call '
@@ -113,7 +113,7 @@ export interface TuneOutFrameworkHooks {
   /** Move the subconscious window anchor (never forward past active epochs). */
   setSubconsciousAnchor: (sequence: number) => void;
   /** True when a channel is bound to a conversation-fork agent. */
-  isForkBound: (channelId: string) => boolean;
+  isForkBound: (channel: ChannelRef) => boolean;
   /** Gate privileged-users list (#77: privileged authors wake, like mentions). */
   isPrivilegedAuthor: (authorId: string | null | undefined) => boolean;
   /** speak_in_channel master switch (recipe-side, canary-gated). */
@@ -144,6 +144,15 @@ export class TuneOutCoordinator {
     return `${serverId}\0${channelId}`;
   }
 
+  /** A channel as the resident and the subconscious are shown it
+   *  (ChannelRegistry.nameShown): its id, or, where another server registers
+   *  the same id, its server-qualified name, which tune_out and
+   *  cancel_tuneout take back; or, for a channel no string picks alone, its
+   *  id and its server. */
+  private shown(serverId: string, channelId: string): string {
+    return this.channelRegistry.nameShown({ serverId, channelId });
+  }
+
   /** Restart cadence + expiry timers and re-anchor after a process restart. */
   resumeActiveEpochs(): void {
     let oldestAnchor: number | null = null;
@@ -232,17 +241,17 @@ export class TuneOutCoordinator {
           + 'whoever runs this host.',
       };
     }
-    if (this.hooks.isForkBound(channelId)) {
+    if (this.hooks.isForkBound({ serverId, channelId })) {
       return {
         ok: false,
-        error: `Nothing changed: a conversation is bound to ${JSON.stringify(channelId)}, so its messages go to that `
+        error: `Nothing changed: a conversation is bound to ${JSON.stringify(this.shown(serverId, 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) return { ok: false, error: alreadyTunedOutText(channelId, current.params), alreadyTunedOut: true };
+    if (current) return { ok: false, error: alreadyTunedOutText(this.shown(serverId, channelId), current.params), alreadyTunedOut: true };
     // 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
@@ -328,7 +337,7 @@ export class TuneOutCoordinator {
     const ended = this.channelRegistry.cancelTuneOut(serverId, channelId, 'open', source);
     if (!ended) {
       // Its reader is the resident's tune_out: cancel_tuneout finds the channel first.
-      return { ok: false, error: this.notTunedOut(channelId, 'you') };
+      return { ok: false, error: this.notTunedOut(this.shown(serverId, channelId), 'you') };
     }
     this.clearTimers(serverId, channelId);
     this.divertedSinceInvocation.delete(this.key(serverId, channelId));
@@ -359,10 +368,12 @@ export class TuneOutCoordinator {
         .join('\n');
       return `${authorOf(m)}: ${text}`;
     };
-    const lifecycle = `[Tune-out: ${channelId} cancelled — ${reason}, ${ended.wakeCount} wake${ended.wakeCount === 1 ? '' : 's'}]`;
+    // The channel as the resident and the subconscious are shown it.
+    const name = this.shown(serverId, channelId);
+    const lifecycle = `[Tune-out: ${name} cancelled — ${reason}, ${ended.wakeCount} wake${ended.wakeCount === 1 ? '' : 's'}]`;
     const render = (lines: string[], truncated: number): string => {
       const attrs = [
-        `channel="${channelId}"`,
+        `channel="${name}"`,
         `messages=${backlog.length}`,
         ...(truncated > 0 ? [`truncated=${truncated} (oldest; fetch_history covers the rest)`] : []),
       ];
@@ -441,7 +452,9 @@ export class TuneOutCoordinator {
       this.hooks.addMessage(
         subName,
         [{ type: 'text', text: subconsciousNote }],
-        { kind: 'subconscious-note', channelId, epochId },
+        // With its server: a conversational row whose channel the framework
+        // reads (repinChannel), where another server's channel can share the id.
+        { kind: 'subconscious-note', channelId, serverId, epochId },
       );
     }
     const primary = this.hooks.primaryName();
@@ -467,7 +480,7 @@ export class TuneOutCoordinator {
         : '';
       this.hooks.addMessage(
         'user',
-        [{ type: 'text', text: `[Tune-out cancelled: ${channelId} — ${reason}.${truncNote}${heldNote}]` }],
+        [{ type: 'text', text: `[Tune-out cancelled: ${this.shown(serverId, channelId)} — ${reason}.${truncNote}${heldNote}]` }],
         { system: true, kind: 'tune-out-cancel-report', channelId },
         subName,
       );
@@ -481,7 +494,7 @@ export class TuneOutCoordinator {
           subName,
         );
       }
-      this.hooks.requestInference(subName, `tune-out cancelled: ${channelId}`, 'tune-out');
+      this.hooks.requestInference(subName, `tune-out cancelled: ${name}`, 'tune-out');
     }
     this.hooks.emitTrace({ type: 'tune-out:cancelled', serverId, channelId, epochId, reason, wakeCount: ended.wakeCount });
     return { ok: true };
@@ -649,16 +662,17 @@ export class TuneOutCoordinator {
     if (!subName) return;
     const key = this.key(serverId, channelId);
 
+    const shown = this.shown(serverId, channelId);
     const notice = trigger === 'wake'
-      ? `[Tune-out wake: ${channelId} — ${count} addressed message${count === 1 ? '' : 's'}]`
-      : `[Tune-out cadence: ${channelId} — ${count} diverted message${count === 1 ? '' : 's'} since your last look]`;
+      ? `[Tune-out wake: ${shown} — ${count} addressed message${count === 1 ? '' : 's'}]`
+      : `[Tune-out cadence: ${shown} — ${count} diverted message${count === 1 ? '' : 's'} since your last look]`;
     this.hooks.addMessage(
       'user',
       [{ type: 'text', text: notice }],
       { system: true, kind: `tune-out-${trigger}`, channelId },
       subName,
     );
-    this.hooks.requestInference(subName, `tune-out ${trigger}: ${channelId}`, 'tune-out');
+    this.hooks.requestInference(subName, `tune-out ${trigger}: ${shown}`, '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);
@@ -740,6 +754,8 @@ export class TuneOutCoordinator {
   async handleSubconsciousTool(
     name: string,
     input: Record<string, unknown>,
+    /** The calling turn's own channels, for a call made inside it (the framework's callOwnChannels). */
+    own: readonly ChannelRef[] = [],
   ): Promise<{ success: boolean; data?: unknown; error?: string; isError?: boolean }> {
     switch (name) {
       case 'deliver_summary': {
@@ -755,19 +771,48 @@ export class TuneOutCoordinator {
         }
         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.
+        // Verbatim, under its own participant name, into the resident's window,
+        // tagged with the channel the name means and its server, since the
+        // framework reads a conversational row's channel (repinChannel). The
+        // name means what it means to every channel tool: inside the calling
+        // turn, the id of one of the turn's own channels means that channel,
+        // refused where its server no longer registers it or the turn has
+        // channels with that id on two servers (ownChannelFor); otherwise a
+        // name several registered channels answer to is refused with them
+        // (sharedNameRefusalFor). So no row is left for a re-pin to read as
+        // another server's channel. A name no registered channel answers to
+        // is kept as given, with no server, which a re-pin reads by name when
+        // it weighs the row, as it reads any message without its server.
+        const mine = this.channelRegistry.ownChannelFor(channelId, own, 'deliver');
+        if (mine && 'error' in mine) return { success: false, error: mine.error, isError: true };
+        const shared = mine ? undefined : this.channelRegistry.sharedNameRefusalFor(channelId, 'nothing was delivered');
+        if (shared) return { success: false, error: shared, isError: true };
+        const [named] = mine ? [mine.channel] : this.channelRegistry.channelsNamed(channelId);
         this.hooks.addMessage(subName, [{ type: 'text', text }], {
           kind: 'subconscious-summary',
-          channelId,
+          ...(named ? { channelId: named.channelId, serverId: named.serverId } : { channelId }),
         });
         return { success: true, data: { delivered: true } };
       }
       case 'cancel_tuneout': {
-        const channelId = String(input.channelId ?? '');
-        const located = this.findByChannel(channelId);
-        if (!located) return { success: false, error: this.notTunedOut(channelId, 'the resident'), isError: true };
+        const name = String(input.channelId ?? '');
+        // The name means what it means to every channel tool, the
+        // resident's tune_out included: inside the calling turn, the id of
+        // one of the turn's own channels means that channel (ownChannelFor);
+        // otherwise a name several registered channels answer to is refused
+        // (channelsNamed), whichever of them is tuned out, never taken to be
+        // the tuned-out one.
+        const mine = this.channelRegistry.ownChannelFor(name, own);
+        if (mine && 'error' in mine) return { success: false, error: mine.error, isError: true };
+        const named = mine ? [mine.channel] : this.channelRegistry.channelsNamed(name);
+        const shared = mine ? undefined : this.channelRegistry.sharedNameRefusalFor(name);
+        if (shared) return { success: false, error: shared, isError: true };
+        const channel = named[0];
+        if (!channel || !this.channelRegistry.getTuneOutState(channel.serverId, channel.channelId)) {
+          return { success: false, error: this.notTunedOut(name, '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);
+        const result = this.cancel(channel.serverId, channel.channelId, 'subconscious', 'subconscious judgment', note);
         return result.ok
           ? { success: true, data: { cancelled: true } }
           : { success: false, error: result.error, isError: true };
@@ -817,7 +862,11 @@ export class TuneOutCoordinator {
         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');
+        // Inside the calling turn, the id of one of the turn's own channels
+        // means that channel, as for every channel tool (ownChannelFor).
+        const mine = this.channelRegistry.ownChannelFor(channelId, own, 'publish');
+        if (mine && 'error' in mine) return { success: false, error: mine.error, isError: true };
+        return this.channelRegistry.publishForAgent(mine ? mine.channel : channelId, text, this.hooks.subconsciousName() ?? 'Subconscious');
       }
       default:
         return { success: false, error: `unknown subconscious tool: ${name}`, isError: true };
@@ -825,32 +874,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`
+   * A cancel of a channel that isn't tuned out, by the name the caller gave
+   * or knows it by: 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.
+   * neither this list nor the name's lookup (channelsNamed, which reads the
+   * registered channels too), 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));
+  private notTunedOut(name: string, backlogTo: 'you' | 'the resident'): string {
+    const active = this.listActive().map((e) => JSON.stringify(this.shown(e.serverId, 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: `
+      : `no connected channel ${JSON.stringify(name)} 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 };
-    }
-    return null;
-  }
-
   /** Stop all timers (framework shutdown). */
   stop(): void {
     for (const timer of this.cadenceTimers.values()) clearTimeout(timer);

package/src/types/agent.ts

@@ -2,6 +2,7 @@ import type { ContentBlock, YieldingStream } from '@animalabs/membrane';
 import type { ContextStrategy } from '@animalabs/context-manager';
 import type { ToolCallId, ToolResult, ToolCall } from './events.js';
 import type { SilentHeartbeatTick } from '../silent-heartbeat.js';
+import type { WakeLine } from '../gate/types.js';
 
 export type SameRoundThinkTextPolicy = 'public' | 'private';
 export type SameRoundThinkTextPolicySource =
@@ -9,6 +10,24 @@ export type SameRoundThinkTextPolicySource =
   | 'recipe'
   | 'compatibility_default';
 
+/** What a continuation's `[continue]` row says (InferenceRequest.autoContinueRun). */
+export interface AutoContinueRun {
+  /** How the agent stops, as the row puts it ("call skip_reply"). */
+  stop: string;
+  /** The turn before ended in words that were held, not sent, because it
+   *  had already sent with a send tool. */
+  heldAfterSend?: boolean;
+  /** Set by the scheduler: the continuation is the turn's only cause. */
+  sole?: boolean;
+}
+
+/** `AgentConfig.autoContinue` as an object (`true` means `{}`). */
+export interface AutoContinueConfig {
+  /** Continuations in a row before the agent waits for the next event:
+   *  a whole number, 1 to 20. Default 3. */
+  maxConsecutive?: number;
+}
+
 /**
  * Configuration for an agent.
  */
@@ -62,7 +81,11 @@ export interface AgentConfig {
   temperature?: number;
 
   /** Max input tokens before framework breaks a yielding stream and
-   *  restarts with recompiled (compressed) context. Default: 150000. */
+   *  restarts with recompiled (compressed) context. Default: 150000. Not
+   *  checked mid-turn for an agent whose model binds its thinking
+   *  (`thinkingBinding.binds`) with `physicalWindowTokens` set: a new stream
+   *  there would take the turn's own earlier reasoning out of the request, and
+   *  the window projection still guards the provider's hard cap. */
   maxStreamTokens?: number;
 
   /**
@@ -75,7 +98,9 @@ export interface AgentConfig {
    * request the provider will 400 (issue #92: a legal compile can walk past
    * the physical window mid-turn). The projection runs once a call on the
    * stream has reported its prompt. Unset → no projection; only the
-   * maxStreamTokens restart applies.
+   * maxStreamTokens restart applies. A value is converted to a number as a
+   * comparison converts it, so a string such as "200000" reads as its number;
+   * one whose number isn't finite, such as null, reads as unset.
    */
   physicalWindowTokens?: number;
 
@@ -133,7 +158,9 @@ export interface AgentConfig {
    * Extended thinking config. When `enabled: true`, the agent runs with
    * Anthropic's native extended thinking; responses include `thinking` blocks
    * with cryptographic signatures, and the API enforces `temperature: 1`
-   * (Membrane handles this). Omit or set `enabled: false` to disable.
+   * (Membrane handles this). Omit or set `enabled: false` to disable, except
+   * on a model whose thinking is always on (Fable, Mythos), which thinks
+   * whatever this says.
    */
   thinking?: {
     enabled: boolean;
@@ -143,10 +170,98 @@ export interface AgentConfig {
     /**
      * How thinking content is returned: 'summarized' (readable summary) or
      * 'omitted' (empty thinking field, signature only). Fable 5 / Opus 4.7+
-     * default to 'omitted' — set 'summarized' to receive thinking text.
+     * default to 'omitted' — set 'summarized' to receive thinking text. A
+     * model whose thinking is always on (Fable, Mythos) is sent a thinking
+     * config only to carry `thinkingBinding.dropBlock`, so this reaches it
+     * only with that set.
      */
     display?: 'summarized' | 'omitted';
   };
+  /**
+   * How the provider binds this agent's signed thinking to the conversation
+   * before it. A host sets it from what it knows of the agent's model and
+   * route.
+   */
+  thinkingBinding?: {
+    /**
+     * Ask the provider to drop a signed thinking block whose earlier
+     * conversation has changed, as a fold changes it, rather than refuse the
+     * request. An account that enforces the binding otherwise answers such a
+     * request with a 400. One that doesn't decides for itself: the four
+     * accounts tried on 2026-10-18 dropped such blocks silently, so there the
+     * model sees nothing different and the report is what's new, and one
+     * that would show such a block to the model is asked to drop it instead.
+     *
+     * It's sent as `thinking.block_binding.prefix_mismatch_behavior:
+     * "drop_block"` with the `thinking-binding-controls-2026-08-01` beta,
+     * which membrane's Anthropic and Bedrock adapters carry (Bedrock's
+     * acceptance of the beta hasn't been tried). On any other adapter it does
+     * nothing, so a host should refuse it there. A thinking config the host
+     * sends itself, through `request.extra` or as `thinking` in
+     * `providerParams`, replaces the one membrane builds, control included.
+     *
+     * On a model whose thinking is always on (Fable, Mythos), membrane
+     * carries it in an adaptive thinking config whatever `thinking.enabled`
+     * says, with `thinking.display` when that's set, so such an agent's
+     * `display` takes effect only with this setting. On any other model, it
+     * goes only in the thinking config membrane sends while thinking is on.
+     * Membrane tells the first kind by its id, which names `fable` or
+     * `mythos`. Opus 5.5, Haiku 5.5, Sonnet 5.5, Sonnet 5, Fable 5 and Fable
+     * 5.1 accepted the config on 2026-10-18. Mythos hasn't been tried, and
+     * membrane notes that the family has refused thinking configs with a 400
+     * before, so for a Mythos model the setting may fail every request.
+     *
+     * On a framework turn, each call's report of the blocks the provider
+     * dropped goes to its `inference:usage` trace, and neither that call nor
+     * its stream's later calls feed the context strategy's calibration, since
+     * the provider doesn't bill a block it dropped and the strategy still
+     * 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.
+     *
+     * Default false: nothing is sent, and the account's default applies.
+     */
+    dropBlock?: boolean;
+    /**
+     * Whether this agent's model binds its signed thinking to the
+     * conversation before it, as the host knows from its own model records.
+     * A context manager that keeps a record of what each branch sent can
+     * then leave out thinking whose earlier conversation changed before the
+     * provider sees it. Set:
+     * - each compile the agent sends tells the context manager so
+     *   (`thinkingBinding`: `binds`, `dropBlock` as set here, and the agent's
+     *   name as the `participant` whose replies are its own), with digests
+     *   of what the request carries ahead of its messages (`identity`: the
+     *   system text with its system-position injections, the tools in the
+     *   order sent, the model, and the thinking config, `maxTokens`,
+     *   `providerParams` and `prefillUserMessage`);
+     * - each framework stream tells the context manager which stored rows
+     *   its later rounds and its last reply carried as stored
+     *   (`noteRequestSent`), naming the compile it was built from, so their
+     *   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 `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;
+     * - with `dropBlock` set too, where a compile reports where the branch's
+     *   record began (`thinkingRecordedAfter`), a block the provider drops
+     *   that the record doesn't account for raises the
+     *   `thinking-binding-loss` ops alert, once per incident and again if a
+     *   call drops more. The provider reports drops only on a request that
+     *   carries the drop control; without it, such a block is refused.
+     * The record and the notes
+     * vouch for requests as agent-framework hands them to membrane, so a
+     * membrane `beforeRequest` hook that changes a request must change every
+     * request alike. Default false: compiles and streams are as they were.
+     */
+    binds?: boolean;
+  };
   /**
    * How to handle a model content-policy refusal (`stop_reason: refusal`).
    * When `autoRewind` is on, a refused turn triggers an automatic rewind: the
@@ -219,6 +334,34 @@ export interface AgentConfig {
    */
   toolWrapperProseGuard?: boolean;
 
+  /**
+   * Continue on the agent's own turn ending (off when left out): a turn the
+   * model ends itself (stop reason `end_turn` or `stop_sequence`), whether
+   * its last response is prose or empty, is followed by another turn,
+   * instead of a pause until the next event. A turn ended through
+   * `skip_reply` (or another tool that ends the turn, such as `sleep`), or
+   * whose last prose envelope is `>>skip_reply` (explicit) or `>>>skip_reply`
+   * (hybrid), pauses as usual. So does one whose closing prose bounced (the
+   * bounce and its cap answer it), and an agent offered no way to stop
+   * (locus or disabled mode without an offered `skip_reply`).
+   *
+   * As the next turn starts, a short `[continue]` system row naming the agent
+   * joins the window: another turn starts, how to stop, and that unmarked
+   * words are sent as usual; on the last continuation of a run, that the
+   * agent waits for the next event after it. It's written only when the
+   * continuation is that turn's whole cause: a message batched with it makes
+   * it that message's turn, with no row, in the message's channel. Otherwise
+   * the next turn keeps the turn's locus (locus and hybrid modes). At most
+   * `maxConsecutive` (default 3) continuations run in a row: the count
+   * starts again when a turn starts with a cause of its own (a message, a
+   * timer, a heartbeat that isn't a silent tick) or a tool ends one. Silent
+   * heartbeat ticks, refusals, `max_tokens` cut-offs, the stall guard's
+   * ends, ephemeral runs, conversation forks and a quiesce never continue. A
+   * ` !` continuation the turn asked for runs instead, and counts toward
+   * nothing. See docs/auto-continue.md.
+   */
+  autoContinue?: boolean | AutoContinueConfig;
+
   /**
    * Clock rows (off when left out): when a boundary of this interval on the
    * agent's local wall clock (counted from local midnight, in the
@@ -399,9 +542,13 @@ export interface InferenceRequest {
    *  all of them without materializing content, the turn has no cause left
    *  and does not run. */
   coalescingBatchSubjects?: string[];
-  /** Host-owned: this wake's sole cause is reading this deferred write, a
-   *  coalesced render placed in its agent's queue (wakeToRead). Once the
-   *  agent has read the write, or it was removed, the wake starts no turn. */
+  /** Host-owned: this wake's sole cause is this write, deferred for its
+   *  agent while a turn was alive: a coalesced render placed in its queue
+   *  (wakeToRead), or a message, notice or event whose wake was queued with
+   *  it. Once a request that carried the write was answered and, for a wake
+   *  that carries a channel, the agent has since published into that
+   *  channel having read it, or once the write is in neither the agent's
+   *  queue nor its store's current branch, the wake starts no turn. */
   readsDeferredWrite?: string;
   agentName: string;
   reason: string;
@@ -418,6 +565,25 @@ export interface InferenceRequest {
    * ephemeral run's (a subagent's), which takes no global fallback.
    */
   channelId?: string;
+  /**
+   * The server of `channelId`'s channel. MCPL requires a channel id to be
+   * unique only within one server's connection (§14.2), so where two
+   * servers register the same id only the pair names one channel. The
+   * framework's own wakes set it beside `channelId`. A host's request that
+   * gives `channelId` alone names the one channel that id, or its
+   * server-qualified name (`serverId:channelId`), means; one that two
+   * servers' channels answer to names none, and the turn's speech has no
+   * channel of its own.
+   */
+  channelServerId?: string;
+  /**
+   * Framework-set: this wake carries an autoContinue continuation
+   * (AgentConfig.autoContinue), with what its `[continue]` row says. The
+   * scheduler keeps the mark on the turn's trigger only when the
+   * continuation is that turn's whole cause, and the turn writes the row as
+   * it starts. Hosts don't set it.
+   */
+  autoContinueRun?: AutoContinueRun;
   /**
    * True when the triggering message explicitly addressed the agent (mention,
    * reply-to-bot, DM — `chat:addressed` in MCPL RFC-001 terms). When a wake
@@ -426,6 +592,16 @@ export interface InferenceRequest {
    * not capture the agent's voice just by being newest.
    */
   addressed?: boolean;
+  /**
+   * Host-owned: true when the triggering message's server marked it ambient
+   * (`chat:ambient`). A coalesced push's wake carries it only to read a
+   * render, and only when every notice the render stands for was. Such a
+   * message asked nothing of the agent, so a wake for it that carries
+   * `readsDeferredWrite` is dropped once a request that carried the message
+   * was answered, with no publish asked of the agent. A message with neither
+   * tag is in doubt, and is judged as an addressed one.
+   */
+  ambient?: true;
   /**
    * Who spoke the message that triggered this inference, as an adapter-
    * namespaced opaque id (`<serverId>:user:<authorId>`) — never a display
@@ -446,6 +622,12 @@ export interface InferenceRequest {
   wakeChannelId?: 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
+   *  (WakeLine), decided by a fresh start of its turn as WakeLine says: each
+   *  written once into the window it names, or left for a later fresh start
+   *  of the same wake. A retry, or a start that resumes a logical turn,
+   *  decides none. */
+  wakeLines?: WakeLine[];
   /** Suppress every automatic plain-prose delivery for this logical turn.
    * Explicit tool calls remain available. Used by authenticated silent wakes. */
   suppressProse?: boolean;

package/src/types/events.ts

@@ -194,6 +194,18 @@ export interface ToolResult {
    * it reads the result's error text, if any.
    */
   data?: unknown;
+  /**
+   * Whether `data` is a protocol result's content: an array in which every
+   * element is a content block, of a type this host can show or not. The
+   * framework sets it on an MCPL tool's result, and a module that returns a
+   * content array can set it too. When it's set, each element reaches the
+   * model as itself, as a reference's stub, or as a marker saying what it was
+   * and why it isn't shown, never as JSON. When it isn't, an array counts as
+   * content only when every element is a block of one of MCP's types (text,
+   * image, audio, resource, resource_link), and any other array is data,
+   * written as JSON.
+   */
+  dataIsContent?: boolean;
   /** Error message (if failure) */
   error?: string;
   /** Whether this was an error (for LLM) */
@@ -299,7 +311,10 @@ export interface ToolCall {
    * leaves room for them; and a result nested past 2,000 levels, or whose parse
    * needs more of the script's memory than is free, doesn't reach the script
    * whatever its length. A result that doesn't reach it is answered
-   * ResultTooLarge, the call having taken effect. Nothing is cut or saved to
+   * ResultTooLarge, the call having taken effect. One the host can't convert
+   * to JSON at all, such as one nested deeper than its runtime's
+   * JSON.stringify can take, is answered instead as a failure naming the
+   * tool and saying the call itself completed. Nothing is cut or saved to
    * a file. A tool that pages or budgets its answer can stay under it. The
    * framework sets it on a model's, a script's and the operator's puppet's
    * call to a module, a utility run through `utils` included. A call
@@ -308,7 +323,9 @@ export interface ToolCall {
    * read_image tool passes a model's call to the workspace without it; and a
    * utility run through `utils` carries what its `utils` call carried.
    * Without it, a module holds its answer to a bound of its own, if any: the
-   * workspace's is the house default, 24,000.
+   * workspace's `edit` and `edit_many` answers hold to the house default,
+   * 24,000, and a `read` holds its page to its line limit alone, with every
+   * line whole, since such a caller takes the data itself.
    */
   resultMaxChars?: number;
 }

package/src/types/framework.ts

@@ -16,6 +16,13 @@ export type { TraceEvent, TraceEventListener } from './trace.js';
 export interface ModuleProcessResponse {
   moduleName: string;
   response: EventResponse;
+  /**
+   * Set when applying the response threw: the operation it threw at, such
+   * as `the edit of <id>`, and the error's message. What the response asked
+   * for before that was applied, that operation may have taken effect in
+   * part or whole, and the rest of it wasn't (EventResponse).
+   */
+  threw?: { at: string; error: string };
 }
 
 /**
@@ -241,8 +248,9 @@ export interface FrameworkConfig {
    * workspace file under `tool-results/` (deterministic `<date>-<callId>.txt`
    * name, overwritten on collision, retained until the workspace owner
    * deletes it — never auto-GC'd) and replaced inline by a bounded preview
-   * plus the file reference; with no writable mount without an include, the
-   * fallback is explicit plain truncation. Default 24000 (house-safe; issue #89). Must be
+   * plus the file reference; with no writable mount without an include that
+   * keeps its files in the store (not configured direct), the fallback is
+   * explicit plain truncation. Default 24000 (house-safe; issue #89). Must be
    * >= 1000. A resident's own agent_settings value
    * `tool_result_inline_max_chars` (durable, persisted in framework state)
    * takes precedence over this for that agent; the EFFECTIVE cap for every
@@ -276,7 +284,17 @@ export interface FrameworkConfig {
    */
   hostToolClasses?: Record<string, string[]>;
 
-  /** Inference routing policy for server-initiated inference (optional). */
+  /**
+   * Inference routing policy for server-initiated inference (optional): the
+   * model an MCPL server's inference/request runs on. Without one, each such
+   * request is refused with -32603 and a message naming this setting; the
+   * framework doesn't choose a model for a server. A server's effective
+   * grant can still list `inferenceRequest` then, since the grant comes from
+   * what the server advertises and `enabledCapabilities`, not from this
+   * policy. A policy that names no model for a request's feature set (no
+   * override, byFeature or wildcards entry that names one, and an empty
+   * `default`) refuses that request the same way, naming the feature set.
+   */
   inferenceRouting?: InferenceRoutingPolicy;
 
   /** EventGate config. If omitted, all events trigger inference (unchanged default). */