@animalabs/agent-framework 0.22.2 → 0.22.3

package/src/mcpl/server-registry.ts

@@ -42,14 +42,16 @@ export class McplServerRegistry {
       throw new Error(`MCPL server "${config.id}" is already registered`);
     }
 
-    const connection = config.reconnect
+    const connection = config.reconnect === true
       ? await McplServerConnection.connectWithReconnect(config, hostCapabilities)
       : await McplServerConnection.connect(config, hostCapabilities);
     this.servers.set(config.id, connection);
 
-    // Auto-remove on unexpected close (unless reconnect will re-add)
+    // Auto-remove on close unless the connection will reconnect. That was
+    // decided once, from `reconnect === true` at connect, and a close() the
+    // host asks for disarms it first, so a server closed for good goes too.
     connection.on('close', () => {
-      if (!config.reconnect) {
+      if (!connection.willReconnect) {
         this.servers.delete(config.id);
       }
     });
@@ -146,7 +148,16 @@ export class McplServerRegistry {
     })), timeoutMs);
   }
 
-  private closeServer(id: string, connection: McplServerConnection): Promise<void> {
+  /**
+   * Close a server for good and drop its entry, if this connection is still
+   * the one registered under `id`. The entry goes when close() resolves,
+   * whatever the connection reports: close() emits no 'close' for a
+   * connection that's down between retries, such as a reconnect stub waiting
+   * for its next retry, so the 'close' listener alone would leave it
+   * registered. A close that fails keeps the entry and rejects; a close
+   * already under way is shared.
+   */
+  closeServer(id: string, connection: McplServerConnection): Promise<void> {
     const existing = this.closing.get(connection);
     if (existing) return existing;
     const attempt = Promise.resolve().then(() => connection.close()).then(() => {

package/src/mcpl/skip-reply-wake.ts

@@ -0,0 +1,73 @@
+/**
+ * How `skip_reply` reads its `wake_in_seconds`, for every site that acts on
+ * it: the framework arms the EventGate's timer or refuses the call, the turn's
+ * bookkeeping of a refused round asks whether it was refused, and the channel
+ * registry words the confirmation. One reading, so a value can't arm a timer
+ * at one site and read as no wake at another, and the confirmation names the
+ * seconds the timer is set for.
+ */
+import { safeSlice } from '../safe-slice.js';
+
+/** The range the tool's schema offers, in seconds: a larger number waits the most. */
+export const SKIP_REPLY_WAKE_MIN_SECONDS = 1;
+export const SKIP_REPLY_WAKE_MAX_SECONDS = 3600;
+
+/**
+ * What a `skip_reply` call's `wake_in_seconds` asks for:
+ * - `none`: absent or `null`, an ordinary skip;
+ * - `wake`: a number of at least 1, or a string that `Number()` reads as one,
+ *   in whole seconds and at most 3600, so 90.7 waits 90 s and anything over
+ *   3600, Infinity included, waits 3600 s;
+ * - `invalid`: anything else, which asks for no number of seconds the host can
+ *   set: a number below 1, such as 0, a negative or 0.5, and "soon", "",
+ *   `true`, an array or an object. Below 1 is refused rather than raised to 1:
+ *   0 is a value a model may write when it fills an optional number with a
+ *   default, and as a 1 s wake it would wake the agent again a second after
+ *   each turn, for as long as it kept skipping with 0.
+ */
+export type SkipReplyWake =
+  | { kind: 'none' }
+  | { kind: 'wake'; seconds: number }
+  | { kind: 'invalid'; value: unknown };
+
+export function readSkipReplyWake(input: unknown): SkipReplyWake {
+  const value = input !== null && typeof input === 'object'
+    ? (input as Record<string, unknown>).wake_in_seconds
+    : undefined;
+  if (value === undefined || value === null) return { kind: 'none' };
+  // A blank string reads as 0, so it's refused as a number below 1.
+  const seconds = typeof value === 'number' ? value
+    : typeof value === 'string' ? Number(value)
+    : Number.NaN;
+  if (Number.isNaN(seconds) || seconds < SKIP_REPLY_WAKE_MIN_SECONDS) return { kind: 'invalid', value };
+  return { kind: 'wake', seconds: Math.floor(Math.min(SKIP_REPLY_WAKE_MAX_SECONDS, seconds)) };
+}
+
+/** The refusal the model reads when its host has no EventGate to set a timer. */
+export const SKIP_REPLY_WAKE_NO_GATE_REFUSAL =
+  "Your turn didn't end, and no wake was set: this host can't wake you on a timer, so skip_reply can't take wake_in_seconds here. To end the turn and wait for the next message, call skip_reply without it. Anything you meant to come back to, do now.";
+
+/**
+ * Why a `skip_reply` call is refused, as the model will read it, or undefined
+ * when it isn't: without an EventGate, any `wake_in_seconds` but absent or
+ * `null`, since the host offers none; with one, a value that isn't a number of
+ * seconds. A refused call arms nothing and doesn't end the turn.
+ */
+export function skipReplyWakeRefusal(wake: SkipReplyWake, gatePresent: boolean): string | undefined {
+  if (wake.kind === 'none') return undefined;
+  if (!gatePresent) return SKIP_REPLY_WAKE_NO_GATE_REFUSAL;
+  if (wake.kind === 'wake') return undefined;
+  return `Your turn didn't end, and no wake was set: wake_in_seconds takes a number of seconds from ${SKIP_REPLY_WAKE_MIN_SECONDS} to ${SKIP_REPLY_WAKE_MAX_SECONDS}, and ${describeValue(wake.value)} isn't one. Call skip_reply with a number of seconds to come back on your own, or without wake_in_seconds to end the turn and wait for the next message.`;
+}
+
+/**
+ * A value as the model wrote it, as JSON, cut to keep the refusal short,
+ * never between the halves of a surrogate pair. A tool call's input is parsed
+ * JSON, so it always has a JSON text, but JSON writes a number that isn't
+ * finite as `null`, and `-1e400` parses as -Infinity, so a number prints as
+ * `String()` of it.
+ */
+function describeValue(value: unknown): string {
+  const text = typeof value === 'number' ? String(value) : JSON.stringify(value);
+  return text.length > 80 ? `${safeSlice(text, 0, 80)}…` : text;
+}

package/src/mcpl/transport.ts

@@ -23,6 +23,8 @@ import { StringDecoder } from 'node:string_decoder';
 import WebSocket from 'ws';
 
 import type { McplServerConfig } from './types.js';
+import { assertBooleanSetting } from '../config-checks.js';
+import { logDetail } from './log-value.js';
 
 /** Why/how a transport closed. `code`/`signal` are populated for stdio child
  *  exits; `reason` carries a WebSocket close reason or an error message. */
@@ -55,7 +57,10 @@ export abstract class McplTransport extends EventEmitter {
   private lineBuffer: string[] = [];
   private stderrBuffer: string[] = [];
 
-  protected constructor() {
+  /** The server's id from its config, so a line the transport logs names it.
+   *  The stdio and WebSocket transports always give it; a test's stand-in
+   *  transport may leave it out. */
+  protected constructor(protected readonly serverId?: string) {
     super();
     // Flush buffered inbound lines the moment a consumer subscribes.
     this.on('newListener', (event) => {
@@ -85,6 +90,15 @@ export abstract class McplTransport extends EventEmitter {
     return '';
   }
 
+  /**
+   * Resolves once the server's diagnostic stream has ended or closed, so that
+   * {@link stderrTail} holds what arrived on it, or once `ms` have passed while
+   * it hasn't. At once for a transport that has none.
+   */
+  stderrEnded(_ms: number): Promise<void> {
+    return Promise.resolve();
+  }
+
   /** Deliver an inbound line, buffering it if nobody is listening yet. */
   protected pushLine(line: string): void {
     if (this.listenerCount('line') > 0) this.emit('line', line);
@@ -97,6 +111,23 @@ export abstract class McplTransport extends EventEmitter {
     else this.stderrBuffer.push(line);
   }
 
+  /**
+   * Report a transport error: to the 'error' listeners if there are any, else
+   * as a log line. EventEmitter throws an 'error' that nothing listens for,
+   * and a transport reports its errors from I/O callbacks, where nothing
+   * catches that throw, so it would end the process. A transport has no
+   * listener from its creation until the handshake attaches one, and a
+   * WebSocket server that sends a malformed frame with its upgrade response
+   * makes ws raise an 'error' in that window.
+   */
+  protected reportError(err: Error): void {
+    if (this.listenerCount('error') > 0) this.emit('error', err);
+    else {
+      const server = this.serverId === undefined ? '' : `${this.serverId}: `;
+      console.error(`[mcpl] ${server}a ${this.kind} transport error, with nothing listening for it: ${logDetail(err.message)}`);
+    }
+  }
+
   /** Emit 'close' exactly once. */
   protected markClosed(info: TransportCloseInfo): void {
     if (this._closed) return;
@@ -141,15 +172,17 @@ export const CHILD_ENV_ALLOWLIST = [
 
 /** Environment for a stdio child: allowlisted host vars (+ LC_*), then the
  *  server's declared `env` on top. Windows names merge case-insensitively;
- *  POSIX names remain case-sensitive. `inheritEnv: true` restores full inheritance. */
+ *  POSIX names remain case-sensitive. `inheritEnv: true` restores full inheritance,
+ *  and only `true` does: a direct caller can pass any value, unchecked. */
 export function buildChildEnv(
   config: Pick<McplServerConfig, 'env' | 'inheritEnv'>,
   hostEnv: NodeJS.ProcessEnv = process.env,
   platform: NodeJS.Platform = process.platform,
 ): NodeJS.ProcessEnv {
   const win = platform === 'win32';
-  const env: NodeJS.ProcessEnv = config.inheritEnv ? { ...hostEnv } : {};
-  if (!config.inheritEnv) {
+  const inherit = config.inheritEnv === true;
+  const env: NodeJS.ProcessEnv = inherit ? { ...hostEnv } : {};
+  if (!inherit) {
     for (const [key, value] of Object.entries(hostEnv)) {
       if (value === undefined) continue;
       // Windows commonly enumerates Path/SystemRoot rather than PATH/SYSTEMROOT.
@@ -184,22 +217,58 @@ export function buildChildEnv(
 /** The most of a stdio child's stderr a transport keeps for {@link McplTransport.stderrTail}. */
 export const STDERR_TAIL_CHARS = 2_048;
 
+/**
+ * How long a refusal at a stdio child's exit waits for the child's stderr to
+ * end, so that its `stderrTail` holds what the child wrote. Node can emit a
+ * child's `exit` before it has read the last of the child's stderr. When the
+ * child held the stream alone, the stream ends with it, and the wait is short.
+ * The bound binds when another process still holds the stream, such as one the
+ * server started that inherited it, or when the host's loop stalls past it
+ * before reading an end that is waiting. The tail then holds what had arrived.
+ * A process that keeps the stream open, such as one the server started and
+ * left running, holds the refusal up by the bound, a fifth of the reconnect's
+ * default first interval.
+ */
+export const STDERR_END_WAIT_MS = 1_000;
+
 export class StdioTransport extends McplTransport {
   readonly kind = 'stdio' as const;
   /** The first error on the child's stdin or stdout, named in the close reason. */
   private pipeError: Error | undefined;
   private stderrEnd = '';
   private stderrCut = false;
+  /** True once the child's stderr has ended or closed. */
+  private stderrDone = false;
 
   override get stderrTail(): string {
     return (this.stderrCut ? '…' : '') + this.stderrEnd;
   }
 
+  override stderrEnded(ms: number): Promise<void> {
+    const stderr = this.child.stderr;
+    if (!stderr || this.stderrDone) return Promise.resolve();
+    return new Promise((resolve) => {
+      let timer: NodeJS.Timeout | undefined;
+      const done = () => {
+        clearTimeout(timer);
+        stderr.off('end', done);
+        stderr.off('close', done);
+        resolve();
+      };
+      // Added after the constructor's listeners, so the tail already holds the
+      // stream's last characters when these run.
+      stderr.once('end', done);
+      stderr.once('close', done);
+      timer = setTimeout(done, ms);
+    });
+  }
+
   private constructor(
     private readonly child: ChildProcess,
     private readonly rl: ReadlineInterface,
+    serverId: string,
   ) {
-    super();
+    super(serverId);
 
     this.rl.on('line', (line: string) => this.pushLine(line));
 
@@ -224,9 +293,12 @@ export class StdioTransport extends McplTransport {
     this.child.stderr?.on('end', () => {
       received(decoder.end());
       if (carry.length > 0) this.pushStderr(carry);
+      this.stderrDone = true;
     });
+    // A stream destroyed by an error closes without ending: nothing more comes.
+    this.child.stderr?.on('close', () => { this.stderrDone = true; });
 
-    this.child.on('error', (err) => this.emit('error', err));
+    this.child.on('error', (err) => this.reportError(err));
     // The child's stdin and stdout carry the protocol, so after an error on
     // either, a write's EPIPE or a read error, this transport can't reach the
     // child even if it's still running. The handler sends a running child
@@ -247,13 +319,11 @@ export class StdioTransport extends McplTransport {
     // listener absorbs that copy.
     this.child.stdout?.on('error', endOnPipeError);
     this.rl.on('error', () => { /* readline's copy of a stdout error, handled above */ });
-    // stderr carries diagnostics only: a read error on it is reported if
-    // anyone listens and never thrown. It ends nothing once the connection
-    // is wired; during a handshake the listener is the handshake's, which
-    // fails it.
-    this.child.stderr?.on('error', (err) => {
-      if (this.listenerCount('error') > 0) this.emit('error', err);
-    });
+    // stderr carries diagnostics only: a read error on it is reported, to the
+    // listeners or else in the log, and never thrown. It ends nothing once
+    // the connection is wired; during a handshake the listener is the
+    // handshake's, which fails it.
+    this.child.stderr?.on('error', (err) => this.reportError(err));
     this.child.on('exit', (code, signal) => this.markClosed({
       code,
       signal,
@@ -293,7 +363,7 @@ export class StdioTransport extends McplTransport {
       });
     });
     const rl = createInterface({ input: child.stdout! });
-    return new StdioTransport(child, rl);
+    return new StdioTransport(child, rl, config.id);
   }
 
   writeLine(json: string): void {
@@ -332,8 +402,8 @@ const WS_OPEN_TIMEOUT_MS = 15_000;
 export class WebSocketTransport extends McplTransport {
   readonly kind = 'websocket' as const;
 
-  private constructor(private readonly ws: WebSocket) {
-    super();
+  private constructor(private readonly ws: WebSocket, serverId: string) {
+    super(serverId);
 
     this.ws.on('message', (data: WebSocket.RawData, isBinary: boolean) => {
       // MCPL frames are UTF-8 JSON text. A frame MAY contain multiple
@@ -345,7 +415,7 @@ export class WebSocketTransport extends McplTransport {
       }
     });
 
-    this.ws.on('error', (err: Error) => this.emit('error', err));
+    this.ws.on('error', (err: Error) => this.reportError(err));
     this.ws.on('close', (code: number, reason: Buffer) => {
       const text = reason?.toString('utf8');
       this.markClosed(text ? { code, reason: text, reasonFromPeer: true } : { code, reason: 'websocket closed' });
@@ -404,7 +474,7 @@ export class WebSocketTransport extends McplTransport {
         settled = true;
         clearTimeout(timer);
         ws.removeAllListeners('error'); // the instance re-attaches its own handlers
-        resolve(new WebSocketTransport(ws));
+        resolve(new WebSocketTransport(ws, config.id));
       });
 
       ws.once('error', (err: Error) => {
@@ -481,6 +551,38 @@ export function isWebSocketTransport(config: McplServerConfig): boolean {
   return Boolean(config.url) && !config.command;
 }
 
+/** The settings of McplServerConfig whose type is boolean. */
+type BooleanSetting = {
+  [K in keyof McplServerConfig]-?: NonNullable<McplServerConfig[K]> extends boolean ? K : never;
+}[keyof McplServerConfig];
+
+/** What `true` does for each boolean setting, as its refusal says it. A
+ *  boolean setting added to McplServerConfig doesn't compile until it has
+ *  an entry here, so the check below covers it too. */
+const SERVER_CONFIG_BOOLEANS: Record<BooleanSetting, string> = {
+  inheritEnv: 'true passes the server the host\'s whole environment, and false or leaving it out passes only the allowlisted and LC_* host variables',
+  reconnect: 'true retries in the background when the server can\'t be reached or its connection drops, and false or leaving it out doesn\'t',
+  allowHostCommands: 'true lets the server run the host\'s admin commands, such as undo, hide, unstick and quiesce, and false or leaving it out refuses them',
+};
+
+/**
+ * Refuse a server config whose `inheritEnv`, `reconnect` or `allowHostCommands`
+ * holds anything but true or false. A config read from JSON can carry a quoted
+ * "false" where the type says boolean, and every reader of these settings takes
+ * only `true` as on, so the quotes would hide what the value does. null counts
+ * as not set, so a generated config that writes an unset setting as null
+ * keeps working. `inheritEnv` is checked only for a stdio server, since a
+ * WebSocket server never reads it. The error names the server, the setting
+ * and the value's kind, not the value, which could be a secret pasted into
+ * the wrong field.
+ */
+export function assertServerConfigBooleans(config: McplServerConfig): void {
+  for (const [setting, whatTrueDoes] of Object.entries(SERVER_CONFIG_BOOLEANS) as Array<[BooleanSetting, string]>) {
+    if (setting === 'inheritEnv' && isWebSocketTransport(config)) continue;
+    assertBooleanSetting(`MCPL server "${config.id}" ${setting}`, config[setting], whatTrueDoes);
+  }
+}
+
 /**
  * Open the transport selected by `config` (WebSocket when `transport` is
  * 'websocket' or a bare `url` is given; stdio otherwise). The returned transport

package/src/mcpl/types.ts

@@ -238,7 +238,10 @@ export interface McplServerConfig {
   /**
    * Escape hatch: pass the host's entire environment (including secrets) to
    * the stdio child, as older versions did. Only for servers that genuinely
-   * need it. Default false.
+   * need it. Default false. Only `true` turns it on, and null counts as not
+   * set. For a stdio server, `create()`, `connectMcplServer` and
+   * `restartMcplServer` refuse any other value, such as a quoted "false". A
+   * WebSocket server never reads it.
    */
   inheritEnv?: boolean;
 
@@ -278,7 +281,9 @@ export interface McplServerConfig {
    * unstick). DEFAULT FALSE: no §6.2 capability path exists for it, and the
    * grant cannot confer it — only this config, decided by the operator, can
    * (PR #79 review blocker 9). The one legitimate fleet user is
-   * discord-mcpl's slash-command relay.
+   * discord-mcpl's slash-command relay. Only `true` turns it on, and null
+   * counts as not set. `create()`, `connectMcplServer` and
+   * `restartMcplServer` refuse any other value, such as a quoted "true".
    */
   allowHostCommands?: boolean;
 
@@ -351,6 +356,9 @@ export interface McplServerConfig {
    * When true, connect() resolves immediately (with null capabilities) if the
    * server is unavailable, and retries in the background.
    * Adapted from Anarchid/agent-framework@mcpl-module-proto.
+   * Only `true` turns it on, and null counts as not set. `create()`,
+   * `connectMcplServer` and `restartMcplServer` refuse any other value, such
+   * as a quoted "false".
    */
   reconnect?: boolean;
 
@@ -378,7 +386,10 @@ export interface McplServerConfig {
    * stops reading its stdin without closing it: the host's writes are
    * buffered, no error is raised, and the connection stays up. This is the
    * timeout of every request that names none; the handshake's initialize has
-   * its own. Set 0 to disable. Default: 60000 (60 seconds).
+   * its own. Set 0 to disable, except for channels/publish and the
+   * channels/open a delivery may send first, which keep the 60 s default: a
+   * publish's outcome is reported to the resident and recorded for its
+   * draft, so it must end. Default: 60000 (60 seconds).
    */
   requestTimeoutMs?: number;
 

package/src/mcpl/visible-content.ts

@@ -31,6 +31,33 @@ export function isVisiblyEmptyContent(content: readonly unknown[] | null | undef
   return true;
 }
 
+/**
+ * What the converter (convertBlock, on every lane) shows for a text
+ * block whose text isn't a string, which only a nonconformant sender writes,
+ * so the agent learns that a block was there. It is the host's word, not the
+ * sender's, so it never makes content visible (isVisiblyEmptyConversion).
+ */
+export const NON_STRING_TEXT_PLACEHOLDER = "[Text not shown: the server's text block had no string text.]";
+
+/** A wire text block whose text isn't a string, which the converter shows as
+ *  NON_STRING_TEXT_PLACEHOLDER. */
+function isNonStringTextBlock(block: unknown): boolean {
+  if (!block || typeof block !== 'object') return false;
+  const b = block as { type?: unknown; text?: unknown };
+  return b.type === 'text' && typeof b.text !== 'string';
+}
+
+/**
+ * isVisiblyEmptyContent for content as a converter showed it, `wire` being
+ * the content as it arrived, block for block: a block shown as
+ * NON_STRING_TEXT_PLACEHOLDER counts as the nothing it held. So content that
+ * is only such blocks (or blank text) is still empty, and anything else is
+ * judged as the converted blocks show it, placeholders included.
+ */
+export function isVisiblyEmptyConversion(wire: readonly unknown[], converted: readonly unknown[]): boolean {
+  return isVisiblyEmptyContent(converted.filter((_, i) => !isNonStringTextBlock(wire[i])));
+}
+
 /** The server id and feature set the marker must carry. */
 export const SILENT_HEARTBEAT_SERVER_ID = 'heartbeat';
 export const SILENT_HEARTBEAT_FEATURE_SET = 'heartbeat';

package/src/module-registry.ts

@@ -1,4 +1,4 @@
-import type { JsStore } from '@animalabs/chronicle';
+import type { JsStateRegistration, JsStore } from '@animalabs/chronicle';
 import type { ContentBlock } from '@animalabs/membrane';
 import type {
   MessageId,
@@ -25,6 +25,7 @@ import type {
 } from './types/index.js';
 import type { Agent } from './agent.js';
 import { DEFAULT_SHUTDOWN_TIMEOUT_MS, validateShutdownTimeout, waitForShutdown } from './shutdown.js';
+import { logValue } from './mcpl/log-value.js';
 
 /** How the registry queues a module's event: its push names the module. A
  * `ProcessQueue` serves too, ignoring the name. */
@@ -44,6 +45,25 @@ export function isStateExistsError(err: unknown): boolean {
   return err instanceof Error && err.message.includes('State already exists');
 }
 
+/**
+ * Register a state, treating "already exists" as done: a store reopened after
+ * a restart already holds it. Every other failure is thrown here, where it
+ * happened, naming the state, with the store's own error as its cause. Each
+ * state the framework registers goes through this.
+ */
+export function ensureStateRegistered(
+  store: Pick<JsStore, 'registerState'>,
+  registration: JsStateRegistration,
+): void {
+  try {
+    store.registerState(registration);
+  } catch (error) {
+    if (isStateExistsError(error)) return;
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Registering state '${registration.id}' failed: ${reason}`, { cause: error });
+  }
+}
+
 /**
  * Hard ceiling for a single module's gatherContext budget, regardless of the
  * `contextTimeoutMs` it declares. gatherContext runs on the critical path of
@@ -81,6 +101,8 @@ export class ModuleRegistry {
 
   private modules: Map<string, Module> = new Map();
   private stopping = new Map<Module, Promise<void>>();
+  /** Module and namespace pairs already told that a system injection held a block that isn't text. */
+  private notShownWarned = new Set<string>();
   private moduleContexts: Map<string, ModuleContextImpl> = new Map();
   private speechHandlers: SpeechHandler[] = [];
   private store: JsStore;
@@ -146,14 +168,7 @@ export class ModuleRegistry {
 
     // Register module state in store
     const stateId = this.getStateId(module.name);
-    try {
-      this.store.registerState({
-        id: stateId,
-        strategy: 'snapshot',
-      });
-    } catch {
-      // State already registered (from previous run)
-    }
+    ensureStateRegistered(this.store, { id: stateId, strategy: 'snapshot' });
 
     // Check if this is a restart (state exists)
     const existingState = this.store.getStateJson(stateId);
@@ -318,12 +333,13 @@ export class ModuleRegistry {
       };
     }
 
-    // Create a call with the un-prefixed name (preserving caller identity)
+    // Create a call with the un-prefixed name (preserving caller identity and turn)
     const moduleCall: ToolCall = {
       id: call.id,
       name: toolName,
       input: call.input,
       callerAgentName: call.callerAgentName,
+      ...(call.callerTurnId !== undefined ? { callerTurnId: call.callerTurnId } : {}),
     };
 
     try {
@@ -425,7 +441,10 @@ export class ModuleRegistry {
       );
       let timer: ReturnType<typeof setTimeout> | undefined;
       const promise = Promise.race([
-        module.gatherContext(agentName).then(r => injections.push(...r)),
+        module.gatherContext(agentName).then(r => {
+          injections.push(...r);
+          this.noteBlocksNotShown(module.name, r);
+        }),
         new Promise<void>((_, rej) => {
           timer = setTimeout(
             () => rej(new Error(`gatherContext timed out after ${budgetMs}ms`)),
@@ -443,6 +462,28 @@ export class ModuleRegistry {
     return injections;
   }
 
+  /**
+   * The system prompt is text, so an agent given a `system` injection reads
+   * a line in place of each of its blocks that isn't text (the agent's
+   * buildSystemPrompt), though `ContextInjection`'s content may be any
+   * block. The module meant those blocks for the model, so its operator is
+   * told, once per module and namespace, as the module's injections are
+   * gathered, whichever agents are given them.
+   */
+  private noteBlocksNotShown(moduleName: string, injections: ContextInjection[]): void {
+    for (const injection of injections) {
+      if (injection.position !== 'system' || !injection.content.some((block) => block.type !== 'text')) continue;
+      const key = `${moduleName}\u0000${injection.namespace}`;
+      if (this.notShownWarned.has(key)) continue;
+      this.notShownWarned.add(key);
+      console.error(
+        `[${moduleName}] gatherContext: a system injection in namespace ${logValue(injection.namespace)} holds a block that ` +
+          "isn't text, which the system prompt can't carry, so an agent given the injection reads a line in place of each such block; " +
+          'this line prints once per module and namespace while the host runs',
+      );
+    }
+  }
+
   /**
    * Tell modules an agent's tool batch completed (see
    * Module.onToolBatchComplete). Hooks run in parallel, each awaited up to
@@ -640,18 +681,12 @@ class ModuleContextImpl implements ModuleContext {
     name: string,
     opts?: { deltaSnapshotEvery?: number; fullSnapshotEvery?: number }
   ): void {
-    const id = this.logStateId(name);
-    try {
-      this.store.registerState({
-        id,
-        strategy: 'append_log',
-        deltaSnapshotEvery: opts?.deltaSnapshotEvery ?? 100,
-        fullSnapshotEvery: opts?.fullSnapshotEvery ?? 20,
-      });
-    } catch (err) {
-      if (!isStateExistsError(err)) throw err;
-      // Already registered (previous run) — idempotent path.
-    }
+    ensureStateRegistered(this.store, {
+      id: this.logStateId(name),
+      strategy: 'append_log',
+      deltaSnapshotEvery: opts?.deltaSnapshotEvery ?? 100,
+      fullSnapshotEvery: opts?.fullSnapshotEvery ?? 20,
+    });
     this.registeredLogStates.add(name);
   }
 

package/src/modules/api/index.ts

@@ -40,7 +40,7 @@ export class ApiModule implements Module {
 
   async handleToolCall(_call: ToolCall): Promise<ToolResult> {
     // API module has no tools
-    return { success: false, error: 'Unknown tool' };
+    return { success: false, error: 'Unknown tool', isError: true };
   }
 
   async onProcess(event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {

package/src/modules/discord/discord-js-client.ts

@@ -29,6 +29,17 @@ export interface DiscordJsClientConfig {
   channelIds?: string[];
 }
 
+/** An attachment as both a live message and history carry it. */
+function toAttachment(a: Attachment): DiscordAttachment {
+  return {
+    id: a.id,
+    filename: a.name ?? 'unknown',
+    url: a.url,
+    contentType: a.contentType ?? undefined,
+    size: a.size,
+  };
+}
+
 export class DiscordJsClient implements DiscordClientInterface {
   private client: Client;
   private token: string;
@@ -68,7 +79,11 @@ export class DiscordJsClient implements DiscordClientInterface {
     });
 
     this.client.on('messageUpdate', (_oldMessage, newMessage) => {
-      if (!newMessage.content || !this.editHandler) return;
+      // content is null for a partial message, one discord.js hadn't cached
+      // and whose update carried no text, so there's no text to compare; a
+      // cached message keeps the text it had. An edit that leaves no text,
+      // beside an attachment, is '' and is still an edit.
+      if (typeof newMessage.content !== 'string' || !this.editHandler) return;
       this.editHandler(newMessage.id, newMessage.content);
     });
 
@@ -114,13 +129,7 @@ export class DiscordJsClient implements DiscordClientInterface {
   }
 
   private convertMessage(message: Message): DiscordMessageData {
-    const attachments: DiscordAttachment[] = message.attachments.map((a: Attachment) => ({
-      id: a.id,
-      filename: a.name ?? 'unknown',
-      url: a.url,
-      contentType: a.contentType ?? undefined,
-      size: a.size,
-    }));
+    const attachments = message.attachments.map(toAttachment);
 
     // Extract mentioned user IDs
     const mentionedUserIds = message.mentions.users.map((u: User) => u.id);
@@ -160,7 +169,7 @@ export class DiscordJsClient implements DiscordClientInterface {
     channelId: string,
     content: string,
     options?: { replyTo?: string; createThread?: { name: string } }
-  ): Promise<{ messageId: string }> {
+  ): Promise<{ messageId: string; threadFailure?: string }> {
     const channel = await this.client.channels.fetch(channelId);
     if (!channel || !('send' in channel)) {
       throw new Error(`Channel ${channelId} not found or not a text channel`);
@@ -173,7 +182,13 @@ export class DiscordJsClient implements DiscordClientInterface {
     });
 
     if (options?.createThread && 'threads' in textChannel) {
-      await message.startThread({ name: options.createThread.name });
+      try {
+        await message.startThread({ name: options.createThread.name });
+      } catch (error) {
+        // The message is out, so the caller counts it as sent before it
+        // reports why its thread wasn't started.
+        return { messageId: message.id, threadFailure: error instanceof Error ? error.message : String(error) };
+      }
     }
 
     return { messageId: message.id };
@@ -341,6 +356,7 @@ export class DiscordJsClient implements DiscordClientInterface {
       authorName: m.author.username,
       isBot: m.author.bot,
       content: m.content,
+      attachments: m.attachments.map(toAttachment),
       timestamp: m.createdAt,
       replyTo: m.reference
         ? {