@animalabs/agent-framework 0.29.0 → 0.31.0

package/src/tune-out/tools.ts

@@ -1,3 +1,6 @@
+import type { ContentBlock } from '@animalabs/membrane';
+import { authorLine } from '../author-presentation.js';
+import type { StoredMessage } from '@animalabs/context-manager';
 /**
  * The subconscious's tool surface (issue #77).
  *
@@ -11,7 +14,7 @@
  * never leak bare prose to the default locus.
  */
 
-import type { ToolDefinition } from '../types/index.js';
+import type { AgentConfig, ToolDefinition } from '../types/index.js';
 
 export const SUBCONSCIOUS_TOOL_NAMES = [
   'deliver_summary',
@@ -51,11 +54,13 @@ export const SUBCONSCIOUS_TOOLS: ToolDefinition[] = [
       'End the tune-out on a channel now — use when something needs the ' +
       'resident\'s full attention. The diverted backlog is delivered to ' +
       'them (capped), and normal attention resumes. Add your own note in ' +
-      '`text`; it arrives alongside the backlog, in your voice.',
+      '`text`; it arrives alongside the backlog, in your voice. If you were ' +
+      'started to read one hold, you can end only that hold.',
     inputSchema: {
       type: 'object',
       properties: {
-        channelId: { type: 'string' },
+        channelId: { type: 'string', description: 'A tuned-out channel, or a channel held by the all-except hold (which ends that hold, unless scope is "channel").' },
+        scope: { type: 'string', enum: ['channel', 'all-except'], description: '"all-except" ends the all-except hold outright; "channel" ends only the channel\'s own tune-out.' },
         text: {
           type: 'string',
           description: 'Your accompanying note to the resident (optional).',
@@ -86,10 +91,14 @@ export const SUBCONSCIOUS_TOOLS: ToolDefinition[] = [
   {
     name: 'speak_in_channel',
     description:
-      'Post a message into a tuned-out channel, clearly as yourself (not ' +
-      'as the resident). Use sparingly — e.g. to tell someone the resident ' +
-      'is tuned out and when to expect them. Disabled unless the resident\'s ' +
-      'configuration allows it.',
+      'Post a message into a tuned-out channel, in your own words and ' +
+      'clearly as yourself (not as the resident); it goes out through the ' +
+      'resident\'s publish path, so the channel sees it under their account. ' +
+      'Use sparingly — e.g. to tell someone the resident is tuned out and ' +
+      'when to expect them. If you were started to read one hold, you can ' +
+      'post only into a channel that hold still holds, and a post made once ' +
+      'it has ended is refused; your report can say it instead. Disabled unless ' +
+      'the resident\'s configuration allows it.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -102,11 +111,53 @@ export const SUBCONSCIOUS_TOOLS: ToolDefinition[] = [
 ];
 
 /**
- * Configuration for the subconscious resident (FrameworkConfig.subconscious).
+ * Configuration for the subconscious (FrameworkConfig.subconscious). Two
+ * shapes, by `reader`:
+ *
+ * - `'persistent'` (default): one persistent side-agent with an isolated
+ *   slot and a windowed read-only view of the residents' timeline, as
+ *   issue #77 built it. Its `systemPrompt` is a system prompt.
+ * - `'forks'`: a succession of forks of the resident (Dendrite). Each
+ *   cadence tick, coalesced wake and cancel derives a short-lived fork at
+ *   the resident's head — the resident's whole prefix, its refusals
+ *   included, ending with it — hands it the traffic held since the last
+ *   look as the first message after the fork point, and lets it report
+ *   back as attributed mail. No agent persists between invocations;
+ *   dispositions do, in the coordinator's state. Its `voice` is framing,
+ *   not a system prompt, and residents are shown the reader's four tools
+ *   in their tool block (refused at dispatch), so the fork's request is
+ *   the resident's up to the fork point.
  */
-export interface SubconsciousConfig {
+export type SubconsciousConfig = PersistentReaderConfig | ForkReaderConfig;
+
+interface SubconsciousConfigBase {
   /** Master switch. */
   enabled: boolean;
+  /**
+   * Allow speak_in_channel. Default false until the voice block has passed
+   * its canary round. A reader's post goes out through the resident's own
+   * publish path, so the channel sees it under the resident's account, in
+   * the reader's words; nothing in the request names the reader. With it
+   * off, a reader fork can post nowhere: every tool but its own is refused
+   * at dispatch (the block it is shown stays the resident's, for the
+   * shared prefix).
+   */
+  allowChannelSpeech?: boolean;
+  /** The reader's model's context window, as AgentConfig.physicalWindowTokens,
+   *  in place of the primary's. Left out or null, a reader on the primary's
+   *  model has the primary's; on another model, the persistent reader has
+   *  none and a fork has the primary's. */
+  physicalWindowTokens?: AgentConfig['physicalWindowTokens'];
+  /** The reader's model's thinking binding, as AgentConfig.thinkingBinding,
+   *  in place of the primary's. Left out, null or false, a reader on the
+   *  primary's model has the primary's; on another model, the persistent
+   *  reader has none and a fork has the primary's. `{ binds: false }` gives
+   *  a reader none. */
+  thinkingBinding?: AgentConfig['thinkingBinding'];
+}
+
+export interface PersistentReaderConfig extends SubconsciousConfigBase {
+  reader?: 'persistent';
   /**
    * Registry + participant name. Default 'Subconscious' — following the
    * Context Manager precedent: a title-case functional voice, not an
@@ -116,7 +167,8 @@ export interface SubconsciousConfig {
   /** Model id; defaults to the primary agent's (same-model side-process).
    *  Another id, compared exactly, makes the subconscious leave out the
    *  fields that describe the primary's model, its window and its thinking
-   *  binding (SUBCONSCIOUS_MODEL_FIELDS); nothing here sets its own. */
+   *  binding (SUBCONSCIOUS_MODEL_FIELDS); `physicalWindowTokens` and
+   *  `thinkingBinding` set its own. */
   model?: string;
   /**
    * The voice/criteria mode block — recipe-side and co-authored with the
@@ -124,9 +176,110 @@ export interface SubconsciousConfig {
    * person toward the resident. Canary before fleet use (issue #77).
    */
   systemPrompt: string;
-  /** Allow speak_in_channel. Default false until the voice block has
-   *  passed its canary round. */
-  allowChannelSpeech?: boolean;
   /** WindowedPassthroughStrategy re-anchor fraction (default 0.5). */
   reAnchorFraction?: number;
 }
+
+export interface ForkReaderConfig extends SubconsciousConfigBase {
+  reader: 'forks';
+  /**
+   * Whose weights run the fork. Required, never defaulted: a fork holds the
+   * resident's whole prefix, and which model reads it is the one fact the
+   * resident's consent names. The resident's own model is the copy; another
+   * model is allowed when stated here. `create` refuses the omission.
+   */
+  model: string;
+  /**
+   * The reader's voice block — report-shaped, second person toward the
+   * resident, co-authored with them. Delivered as the first message after
+   * the fork point, with the notice, the standing dispositions and the held
+   * traffic; never a system prompt.
+   */
+  voice: string;
+  /**
+   * A fresh context strategy instance for each fork, same class and
+   * configuration as the resident's, so the fork reuses the resident's fold
+   * state and rendering. Required unless the resident runs a passthrough
+   * strategy.
+   */
+  strategyFactory?: () => import('@animalabs/context-manager').ContextStrategy;
+  /** Idle timeout for one reader fork (default 10 minutes). */
+  forkIdleTimeoutMs?: number;
+  /**
+   * How a reader fork is prompted: the content of the one message it
+   * receives after the fork point. Default `defaultReaderFraming`. The
+   * framework stores whatever this returns as a user message with
+   * `metadata.kind = 'tune-out-reader-framing'`; the notice, voice,
+   * dispositions and held traffic are in the context, and nothing else
+   * about the fork's prompt is fixed by the path.
+   */
+  framing?: (context: ReaderFramingContext) => ContentBlock[];
+}
+
+/** What a reader fork's framing is built from. */
+export interface ReaderFramingContext {
+  /** The resident the fork was derived from. */
+  resident: string;
+  /** The fork's own name. */
+  fork: string;
+  /** `ForkReaderConfig.voice`. */
+  voice: string;
+  channelId: string;
+  epochId: string;
+  trigger: 'cadence' | 'wake' | 'cancel';
+  /** The coordinator's notice for this invocation (`[Tune-out wake: …]` etc.). */
+  notice: string;
+  /** Standing dispositions recorded on the epoch, or null. */
+  dispositions: string | null;
+  /**
+   * The traffic held since the last look, oldest first; empty when nothing
+   * arrived. It includes the messages still queued behind the resident's
+   * turn (admitted, not yet stored), last: their ids are held handles and
+   * their sequences provisional, as a module's held rows are.
+   */
+  backlog: StoredMessage[];
+  /** How many of `backlog`'s last entries are still queued behind the resident's turn. Absent is none. */
+  queuedCount?: number;
+}
+
+/**
+ * The default reader-fork framing: a header naming the channel, epoch and
+ * trigger; the notice; the voice block; standing dispositions if any; then
+ * the held traffic as `author: text` lines with non-text blocks (images,
+ * documents) preserved in order as the source supplied them.
+ */
+export function defaultReaderFraming(ctx: ReaderFramingContext): ContentBlock[] {
+  const header =
+    `[Tune-out reader — ${ctx.channelId}, epoch ${ctx.epochId.slice(0, 8)}, ${ctx.trigger}]\n` +
+    `${ctx.notice}\n\n${ctx.voice}` +
+    (ctx.dispositions ? `\n\n[Standing dispositions]\n${ctx.dispositions}` : '');
+  const content: ContentBlock[] = [{ type: 'text', text: header }];
+  if (ctx.backlog.length === 0) {
+    content.push({ type: 'text', text: '\n[Nothing new has been held since your last look.]' });
+    return content;
+  }
+  const n = ctx.backlog.length;
+  const q = Math.min(Math.max(0, Math.floor(ctx.queuedCount ?? 0)), n);
+  const lines: string[] = [`\n[Held in ${ctx.channelId} since your last look: ${n} message${n === 1 ? '' : 's'}]`];
+  const flush = () => {
+    if (lines.length > 0) content.push({ type: 'text', text: lines.splice(0).join('\n') });
+  };
+  const which = q === n ? (q === 1 ? 'It' : 'They') : (q === 1 ? 'The last one' : `The last ${q}`);
+  const queuedNote = `[${which} arrived while ${ctx.resident}'s turn was running, so ${q === 1 ? 'it is' : 'they are'} still queued, not yet stored.]`;
+  for (const [i, message] of ctx.backlog.entries()) {
+    if (q > 0 && i === n - q) lines.push(queuedNote);
+    const author = (message.metadata as { author?: { name?: string } } | undefined)?.author?.name ?? message.participant;
+    const text = message.content
+      .filter((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text')
+      .map((b) => b.text)
+      .join('\n');
+    lines.push(authorLine(author, text));
+    const media = message.content.filter((b) => b.type !== 'text');
+    if (media.length > 0) {
+      flush();
+      content.push(...media);
+    }
+  }
+  flush();
+  return content;
+}

package/src/types/agent.ts

@@ -340,6 +340,34 @@ export interface AgentConfig {
    */
   proseRouting?: 'locus' | 'explicit' | 'hybrid' | 'disabled';
 
+  /**
+   * Stored participants that are this agent's own voice, in addition to its
+   * name: their turns are presented to the model as this agent's assistant
+   * turns. A derived agent sets this to the agent it inherited from, so the
+   * parent's turns read as its own history. Model-facing role assignment
+   * only, applied at request assembly — stored authorship is never rewritten.
+   */
+  selfParticipants?: string[];
+
+  /**
+   * The participant name this agent's own turns are presented under at
+   * request assembly. Defaults to `name`. A derived agent that should share
+   * its parent's provider prefix sets the parent's name, so the two
+   * requests are identical in formatters that render participant names as
+   * well as in those that only assign roles. New turns are still STORED
+   * under the agent's own name.
+   */
+  presentAs?: string;
+
+  /**
+   * Tools refused when this agent calls them, although they stay advertised.
+   * Restricts a derived agent without changing the tool block at the front
+   * of its request — removing a tool from `allowedTools` instead would
+   * change those bytes and forfeit the provider prefix it shares with its
+   * parent.
+   */
+  denyToolsAtDispatch?: string[];
+
   /**
    * Fail-closed containment for a text response whose entire visible prose is
    * an invocation-shaped wrapper naming a tool registered on that exact turn.
@@ -511,7 +539,8 @@ export interface InferenceOptions {
  * `supportsInjectedMessages` is what the stream declared with the round's
  * tool calls (membrane's `ToolContext.supportsInjectedMessages`): whether it
  * can carry messages injected with that round's results. It's absent when
- * the stream doesn't say, as on membrane 0.5.87 and earlier.
+ * the stream doesn't say, which reads as a stream that can't, and when there
+ * is no stream, as for the direct API.
  */
 export type AgentState =
   | { status: 'idle' }

package/src/types/framework.ts

@@ -6,6 +6,7 @@ import type { ProcessEvent } from './events.js';
 import type { McplServerConfig, InferenceRoutingPolicy } from '../mcpl/types.js';
 import type { ConversationRouterConfig } from '../mcpl/conversation-router.js';
 import type { GateOptions } from '../gate/types.js';
+import type { InferenceBoundsOptions } from '../inference-bounds.js';
 
 // Re-export trace types
 export type { TraceEvent, TraceEventListener } from './trace.js';
@@ -116,6 +117,48 @@ export type ProviderHoldHook = (
 ) => ProviderHold | undefined;
 
 export interface FrameworkConfig {
+  /**
+   * Dendrite agent lifecycle options.
+   */
+  dendrite?: {
+    /**
+     * When an agent ends while task work it spawned is still running, the
+     * orphan is always told. With this on (the default), the first agent
+     * that could adopt it — its nearest live ancestor, else the primary —
+     * also receives a factual notice, which is what makes the reparenting
+     * offer visible to a model. Turn it off when the host makes adoption
+     * decisions itself from the `dendrite:agent-orphaned` trace.
+     */
+    announceOrphans?: boolean;
+    /**
+     * By default every derivation tells the agent it was made from, in one
+     * host-framed line. After this many derivations of one kind from one
+     * agent, that agent hears a count line every so many instead of a line
+     * per fork, so a reader loop that forks a hundred times a session doesn't
+     * fill its source's context with stamps; every derivation still emits its
+     * `dendrite:agent-created` trace. Default 10; 0 never collapses.
+     */
+    collapseDerivationNoticesAfter?: number;
+    /**
+     * A host's say over each derivation, ephemeral spawn and resume, before the
+     * agent or its new incarnation exists, given the spec of what is about to
+     * exist (name, kind, spawner, route, inheritance, metadata). A shared
+     * derivation's record then adds the child's branch, and names the
+     * parent's namespace as its own. Return nothing to allow, or `{ refuse }`
+     * with the reason, which the caller gets as the error. The framework
+     * attaches no meaning to the decision: consent, budget, hours, a mind's
+     * standing instruction, a use not yet imagined are all the host's.
+     */
+    beforeDerive?: (spec: import('../dendrite/types.js').AgentSpec) => void | { refuse: string };
+    /**
+     * What an agent is told when something is derived from it. Given the
+     * record, the agent it was derived from and the framework's default line,
+     * return the text to add, or null to add nothing. Absent, the default
+     * line is used. The `dendrite:agent-created` trace is emitted either way.
+     */
+    derivationNotice?: (record: import('../dendrite/types.js').AgentRecord, from: string, defaultText: string) => string | null;
+  };
+
   /**
    * The subconscious resident (issue #77): a persistent side-agent that
    * receives diverted traffic from tuned-out channels and reports to the
@@ -123,6 +166,46 @@ export interface FrameworkConfig {
    */
   subconscious?: import('../tune-out/tools.js').SubconsciousConfig;
 
+  /**
+   * Tune-out without a reader (issue #232 §3.3). The hold machinery always
+   * runs when MCPL channels exist, so a persisted epoch is resumed and
+   * released whatever the configuration; this switch only decides whether
+   * residents are offered `tune_out` when no reader is configured. Without
+   * a reader a tune-out is a silent hold: no cadence, no wake budget,
+   * mentions are acknowledged, the backlog is released on cancel.
+   */
+  tuneOut?: {
+    /** Offer `tune_out` without a subconscious. Default: only with one. */
+    enabled?: boolean;
+    /**
+     * Announce the all-except scope in the excepted channel: one bracketed
+     * line under the resident's name when it opens (who, for how long) and
+     * one when it closes. Default true — a hold the room cannot see is the
+     * failure the scope exists to prevent. `false` keeps both quiet.
+     */
+    announce?: boolean;
+  };
+
+  /**
+   * Where a turn's plain prose lands when nothing names a destination
+   * (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.
+   * - `'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.
+   */
+  speech?: {
+    locus?: 'delivery' | 'latest-inbound';
+  };
+
   /**
    * IANA zone of the agent's wall clock: it renders wall-clock times for the
    * agent, and it sets where clock rows' boundaries fall (AgentConfig.clock,
@@ -160,6 +243,26 @@ export interface FrameworkConfig {
    */
   deferredWritesPath?: string;
 
+  /**
+   * The Dendrite agent registry's recovery file: its live records and the
+   * results it holds for delivery, written atomically and fsynced, and read
+   * first at boot. Defaults to `<storePath>/recovery/dendrite-registry.json`.
+   * Outside the chronicle for the reason `hostModePath` is: a branch switch
+   * or historical rollback would otherwise take back held results. Set
+   * explicitly when providing an app-owned `store` without `storePath`;
+   * without either, the registry persists only in the branch-local store,
+   * with a warning at create.
+   */
+  agentRegistryPath?: string;
+
+  /**
+   * The registry's ended-record log recovery file (its newest records, as
+   * many as a restart reads). Defaults to
+   * `<storePath>/recovery/dendrite-ended.json`; same rationale and fallback
+   * as `agentRegistryPath`.
+   */
+  agentRegistryEndedPath?: string;
+
   /** Emoji used for branch-awareness markers (default: 💤). */
   discordAwarenessEmoji?: string;
 
@@ -197,6 +300,30 @@ export interface FrameworkConfig {
   /** Custom error policy */
   errorPolicy?: ErrorPolicy;
 
+  /**
+   * How long a model call may go without progress before it is cut. A
+   * resident's streamed call, and an MCPL server's, gets membrane's progress
+   * bounds where its adapter's stream reports content (Anthropic, Bedrock),
+   * and on every adapter a flat bound from its last provider event: the
+   * larger of a setup term (the larger of `beforeContentMs` and
+   * `betweenEventsMs`) plus the request's `maxTokens` at
+   * `thinkTokensPerSecond`, and `flatMinimumMs`. An auxiliary call
+   * (compression, the reply judge) and an MCPL server's non-streamed call get
+   * a bound on the whole call from its send, the setup term plus that
+   * allowance (the larger of the setup term and `flatMinimumMs` when it
+   * names no `maxTokens`), unless its
+   * caller passed a `progressTimeoutMs` of its own; where an adapter's
+   * `complete()` streams under the hood, membrane renews it at each parsed
+   * provider event. A call a bound cuts fails
+   * with type `timeout`, and on an agent's turn DefaultErrorPolicy gives each
+   * such call one fresh call, except in a turn that re-arms an exhausted one,
+   * where `exhaustedTurnRearmMs` says what a cut does. One setting covers
+   * every agent. `false` sets
+   * none of these bounds. Default: membrane's PROGRESS_BOUNDS and
+   * FLAT_MINIMUM_MS.
+   */
+  inferenceBounds?: false | InferenceBoundsOptions;
+
   /**
    * Host verdict on a failed inference: "this cannot succeed until later".
    * Consulted before the error policy and before the built-in
@@ -235,20 +362,32 @@ export interface FrameworkConfig {
    * channel isn't sent again: one whose turn was woken for a channel id that
    * names no one registered channel and never found one, and whose request
    * names none of its own. A failure that states a wait is held for that wait
-   * first, as any turn's is, and a deadline ends the turn as before, whether
-   * the host set it or membrane marks one as run out: the runtime's or
-   * undici's on a sent request, the Anthropic adapter's watchdogs, or the
-   * Anthropic SDK's timeout, which covers its connect timeout too. Until one
-   * of the re-armed turn's rounds has run or had its tool calls cut off, its
-   * failure gets no retries from the error policy: on another transient
-   * failure the next delay follows, until the list runs out, and a failure of
-   * any other kind ends the re-arming. A wake for the agent while it waits
-   * starts its turn at once, with the re-armed trigger merged in. That turn is
-   * the wake's: the error policy retries its failures. A completed turn starts
-   * the count again, and so does a message said to the agent: not a system
-   * message or notice; not an edit, reaction or deletion, unless an edit is
-   * the first version of a message the agent sees; not a message its own view
-   * leaves out, such as one a tune-out holds from it; and not the agent's own
+   * first, as any turn's is, and a turn that ends on a deadline, whether the
+   * host set it or membrane marks one as run out (the runtime's or undici's
+   * on a sent request, the Anthropic adapter's watchdogs, or the Anthropic
+   * SDK's timeout, which covers its connect timeout too), isn't re-armed,
+   * save the exception below. Until one of the re-armed turn's rounds has run
+   * or had its tool calls cut off, its failure gets no retries from the error
+   * policy: on another transient failure the next delay follows, until the
+   * list runs out, and a failure of any other kind ends the re-arming. The
+   * one exception is a re-armed turn's send that fails with a deadline marked
+   * as run out, membrane's or a bound the host sets on the call
+   * (`inferenceBounds`), as when a stream stalls. Such a cut counts as a
+   * transient failure, so a turn that ends on it is re-armed as for a
+   * transient failure, unless it follows another such cut with no transient
+   * failure, answered round or message said to the agent between them: two
+   * such cuts in a row end the re-arming, and the second gets no retry from
+   * the error policy, even in a re-armed turn that got partway. A transient
+   * failure or an answered round in any of the agent's turns clears an
+   * earlier cut, and so does a message said to the agent, or the agent's end.
+   * Every such cut counts, including one the error policy retries or a host's
+   * provider hold takes. A wake for the agent while it waits starts its turn
+   * at once, with the re-armed trigger merged in. That turn is the
+   * wake's: the error policy retries its failures. A completed turn starts the
+   * count again, and so does a message said to the agent: not a system message
+   * or notice; not an edit, reaction or deletion, unless an edit is the first
+   * version of a message the agent sees; not a message its own view leaves
+   * out, such as one a tune-out holds from it; and not the agent's own
    * schedule, the heartbeat's tick or reminder, a self-wake timer it set, or a
    * script's wake. A notice a module or an MCPL server stores as a message
    * counts. A message in the residents' shared slot counts for each resident
@@ -456,7 +595,10 @@ export interface InferencePolicy {
  */
 export interface ErrorPolicy {
   /**
-   * Handle an inference error.
+   * Handle an inference error. `attempt` is how many times the turn's
+   * request has failed before this one; for a deadline expiry (a progress
+   * bound's cut, or one membrane marks), how many times that call's request
+   * has expired in a row before this one.
    */
   onInferenceError(
     error: Error,

package/src/types/module.ts

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