@animalabs/agent-framework 0.23.3 → 0.24.1

package/src/mcpl/tags.ts

@@ -18,6 +18,42 @@ const CORE_IMPLIES: Readonly<Record<string, readonly string[]>> = {
   'chat:dm': ['chat:addressed', 'chat:private'],
 };
 
+/**
+ * RFC-001 core tags that mark a message as being ABOUT the conversation
+ * rather than part of it: reactions (added or removed), edits and deletions
+ * of an existing message. These are markers, not turns — they must not clear
+ * explicit-send suppression, count as a new conversational round, or
+ * retarget the default publish channel. An edit can also be the first
+ * version of a message the agent sees, and then counts as that message:
+ * isMarkerTagged reads the host's mark for the case the coalescer knows
+ * (`firstView`), for isConversationalInjection and for the channel
+ * registry's publish channel and reply anchor. Tags are
+ * still never authority (§16.6): this set only ever WITHHOLDS default
+ * conversational treatment, it never grants anything.
+ */
+export const NON_CONVERSATIONAL_TAGS: ReadonlySet<string> = new Set([
+  'chat:reaction',
+  'chat:reaction-remove',
+  'chat:edited',
+  'chat:deleted',
+]);
+
+/** True when a (possibly untyped) tag list carries a non-conversational marker tag. */
+export function hasNonConversationalTag(tags: unknown): boolean {
+  return Array.isArray(tags) && tags.some((t) => typeof t === 'string' && NON_CONVERSATIONAL_TAGS.has(t));
+}
+
+/**
+ * True when a message is a marker by its tags. `firstView` is the host's own
+ * mark that the coalescer delivered the message as the agent's first view of
+ * it (a stored message's metadata `firstView`, or in the channel registry the
+ * admission's receipt), never a server's claim: an edit so delivered counts
+ * as the message it replaced, while a reaction or deletion stays a notice.
+ */
+export function isMarkerTagged(tags: unknown, firstView: boolean): boolean {
+  return hasNonConversationalTag(firstView && Array.isArray(tags) ? tags.filter((t) => t !== 'chat:edited') : tags);
+}
+
 /**
  * Expand a raw tag list over the normative core closure, then resolve the
  * §16.2 mutual exclusion: `chat:addressed` and `chat:ambient` cannot both

package/src/mcpl/tool-result-normalize.ts

@@ -36,7 +36,8 @@ export const MALFORMED_CONTENT_NOTICE =
   '[malformed result: its content is not a list of blocks; the tool may already have completed]';
 
 /** Saves a payload under a host-chosen name; resolves to its workspace path,
- *  or null when there is nowhere writable to put it. */
+ *  or null when there is no writable workspace mount without an include to
+ *  put it in. */
 export type SaveToolPayload = (fileName: string, bytes: Buffer, mimeType: string) => Promise<string | null>;
 
 /** Stub fields are bounded independently of anything the server sends. */

package/src/mcpl/transport.ts

@@ -12,7 +12,9 @@
  *  - StdioTransport      — spawns `config.command` and speaks over stdin/stdout;
  *                          child stderr is surfaced as 'stderr' lines.
  *  - WebSocketTransport  — dials `config.url` (ws:// or wss://) with the `ws`
- *                          library, appending `?token=` when `config.token` is
+ *                          library, sending the credential as `?token=` (or
+ *                          as an Authorization header, `tokenTransport:
+ *                          'header'`) when `config.token` is
  *                          set; each WS text frame is one JSON-RPC line.
  */
 
@@ -23,7 +25,7 @@ import { StringDecoder } from 'node:string_decoder';
 import WebSocket from 'ws';
 
 import type { McplServerConfig } from './types.js';
-import { describeCredentialError, noteDialSent, redactUrl, resolveServerBinding, urlAsDialed } from './protocol-family.js';
+import { WITHHELD_TEXT, describeCredentialError, headerCarries, maskedError, noteDialSent, redactServerText, redactUrl, resolveServerBinding, serverTextRedactor, tokenTransportProblem, urlAsDialed, type Redaction } from './protocol-family.js';
 import { assertBooleanSetting } from '../config-checks.js';
 import { logDetail } from './log-value.js';
 
@@ -94,6 +96,21 @@ export abstract class McplTransport extends EventEmitter {
     return '';
   }
 
+  /**
+   * {@link stderrTail} as an error a host gets carries it: the same
+   * characters, redacted with `redact`. The stream's last
+   * {@link STDERR_WINDOW_CHARS} are redacted together and the tail is taken
+   * from where it begins in them, so a credential that begins before the
+   * tail and reaches into it is matched whole and replaced whole
+   * ({@link Redaction}'s `from`). That holds for a credential of up to
+   * 14,336 characters, the window less the tail: a longer one that began
+   * before the window can't be matched, and the tail keeps what it holds of
+   * it. '' for a transport that has no diagnostic stream.
+   */
+  stderrTailRedacted(_redact: Redaction): string {
+    return '';
+  }
+
   /**
    * The error a stdio child's stdin or stdout failed with, once one has. The
    * transport is ending the child then, and stays open until it exits, but
@@ -230,9 +247,19 @@ export function buildChildEnv(
   return merged;
 }
 
-/** The most of a stdio child's stderr a transport keeps for {@link McplTransport.stderrTail}. */
+/** The most of a stdio child's stderr that {@link McplTransport.stderrTail} gives. */
 export const STDERR_TAIL_CHARS = 2_048;
 
+/** The most of a stdio child's stderr a transport keeps, for
+ *  {@link McplTransport.stderrTail} and
+ *  {@link McplTransport.stderrTailRedacted}: eight tails, so a credential of
+ *  up to 14,336 characters that reaches into the tail, a private key's PEM
+ *  of 8,192 bits (about 6,500 characters) included, is whole in it. */
+export const STDERR_WINDOW_CHARS = 8 * STDERR_TAIL_CHARS;
+
+/** A redaction that replaces nothing: the raw tail. */
+const unredacted: Redaction = (text, from = 0) => String(text).slice(from);
+
 /**
  * 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
@@ -251,13 +278,28 @@ 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;
+  /** The stream's last STDERR_WINDOW_CHARS, raw. */
+  private stderrWindow = '';
   /** True once the child's stderr has ended or closed. */
   private stderrDone = false;
 
   override get stderrTail(): string {
-    return (this.stderrCut ? '…' : '') + this.stderrEnd;
+    return this.stderrTailRedacted(unredacted);
+  }
+
+  override stderrTailRedacted(redact: Redaction): string {
+    // A child that wrote nothing has no tail, whatever its redaction.
+    if (this.stderrWindow === '') return '';
+    // The tail begins at its raw place in the window, so a redaction that
+    // shortens the window can't move its edge back toward the window's own
+    // cut. Something before the tail was dropped whenever the window is
+    // longer than the tail, which it always is once the window was cut.
+    const from = Math.max(0, this.stderrWindow.length - STDERR_TAIL_CHARS);
+    const cut = from > 0;
+    let kept = redact(this.stderrWindow, from);
+    // A cut between a surrogate pair's halves drops the low half too.
+    if (cut && /^[\uDC00-\uDFFF]/.test(kept)) kept = kept.slice(1);
+    return (cut ? '…' : '') + kept;
   }
 
   override get pipeFailure(): Error | undefined {
@@ -300,12 +342,8 @@ export class StdioTransport extends McplTransport {
     let carry = '';
     const decoder = new StringDecoder('utf8');
     const received = (text: string) => {
-      const end = this.stderrEnd + text;
-      this.stderrCut ||= end.length > STDERR_TAIL_CHARS;
-      let kept = end.slice(-STDERR_TAIL_CHARS);
-      // A cut between a surrogate pair's halves drops the low half too.
-      if (/^[\uDC00-\uDFFF]/.test(kept) && end.length > STDERR_TAIL_CHARS) kept = kept.slice(1);
-      this.stderrEnd = kept;
+      const window = this.stderrWindow + text;
+      this.stderrWindow = window.slice(-STDERR_WINDOW_CHARS);
       const lines = (carry + text).split('\n');
       carry = lines.pop() ?? '';
       for (const l of lines) if (l.length > 0) this.pushStderr(l);
@@ -374,10 +412,33 @@ export class StdioTransport extends McplTransport {
         `MCPL server "${config.id}": stdio transport requires "command" (none provided)`,
       );
     }
-    const child = spawn(config.command, config.args ?? [], {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      env: buildChildEnv(config),
-    });
+    // Node's error for a launch that failed reaches the host, and its words
+    // and its other properties (`spawnargs`, `path`) can repeat a credential
+    // the configuration holds. So it's handed on as its name and redacted
+    // words (maskedError), with its code, which says what failed. What
+    // spawn() refuses at once is one of the configuration's own arguments or
+    // options, which Node quotes after " Received", cut to 128 characters: a
+    // credential across that cut couldn't be matched, so the words stop
+    // before the quote, still saying which value Node refused and why.
+    const failed = (err: NodeJS.ErrnoException, refusedAtOnce: boolean): Error => {
+      const redact = serverTextRedactor(config).now();
+      const message = err instanceof Error ? err.message : String(err);
+      const words = refusedAtOnce ? message.split(' Received')[0] : message;
+      const shown = Object.assign(new Error(words), { name: err instanceof Error ? err.name : 'Error' });
+      const cause = Object.assign(maskedError(shown, redact), err.code === undefined ? {} : { code: err.code });
+      return new Error(`MCPL server "${config.id}" could not be started: ${redact(words)}`, { cause });
+    };
+    // The child's environment is read first, outside that: a configuration
+    // whose `env` can't be read throws the framework's own error, such as
+    // its awareness ledger's, which the framework acts on: its startup ends
+    // on it, and a reconnect reports it.
+    const env = buildChildEnv(config);
+    let child: ChildProcess;
+    try {
+      child = spawn(config.command, config.args ?? [], { stdio: ['pipe', 'pipe', 'pipe'], env });
+    } catch (error) {
+      throw failed(error as NodeJS.ErrnoException, true);
+    }
     // Node reports a failed spawn (a command that doesn't exist, say) as an
     // 'error' on a tick after spawn() returns, and no 'exit' follows. It is
     // settled here, where it is listened for. A caller that listens only once
@@ -385,12 +446,10 @@ export class StdioTransport extends McplTransport {
     // from a timer callback, as a reconnect is: Node runs that tick before the
     // caller's promise continuation, and throws an 'error' nothing listens for.
     await new Promise<void>((resolve, reject) => {
-      const failed = (err: Error) => {
-        reject(new Error(`MCPL server "${config.id}" could not be started: ${err.message}`, { cause: err }));
-      };
-      child.once('error', failed);
+      const fail = (err: NodeJS.ErrnoException) => reject(failed(err, false));
+      child.once('error', fail);
       child.once('spawn', () => {
-        child.off('error', failed);
+        child.off('error', fail);
         resolve();
       });
     });
@@ -504,7 +563,8 @@ function raceAbort<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
 export class WebSocketTransport extends McplTransport {
   readonly kind = 'websocket' as const;
 
-  private constructor(private readonly ws: WebSocket, serverId: string) {
+  private constructor(private readonly ws: WebSocket, config: McplServerConfig, dialed: string) {
+    const serverId = config.id;
     super(serverId);
 
     this.ws.on('message', (data: WebSocket.RawData, isBinary: boolean) => {
@@ -517,7 +577,9 @@ export class WebSocketTransport extends McplTransport {
       }
     });
 
-    this.ws.on('error', (err: Error) => this.reportError(err));
+    // The client's text can quote the url as dialed (Bun's does): reported
+    // masked, as a new error with no cause (clientErrorText).
+    this.ws.on('error', (err: Error) => this.reportError(new Error(clientErrorText(err, config, dialed))));
     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' });
@@ -525,8 +587,11 @@ export class WebSocketTransport extends McplTransport {
   }
 
   /**
-   * Dial `config.url` and resolve once the socket is OPEN. Appends `?token=`
-   * when `config.token` is set. Rejects on connect error / timeout (and tears
+   * Dial `config.url` and resolve once the socket is OPEN. Sends the
+   * credential (`config.token`, or the access provider's) as a `?token=`
+   * query parameter, or with `tokenTransport: 'header'` as an
+   * `Authorization: Bearer` header on the upgrade, refusing before the dial
+   * one a header can't carry as configured. Rejects on connect error / timeout (and tears
    * the socket down) so a failed dial never leaks an open handle. `signal`
    * ends a dial whose connection is closed meanwhile, at once, rather than
    * at the open timeout.
@@ -557,14 +622,32 @@ export class WebSocketTransport extends McplTransport {
       }
     }
     const url = buildWebSocketUrl(config, token);
-    // A provider's token is in this url, and the query may be re-encoded:
-    // the server's text is recorded with what the dial sent, the token in
-    // each form a token is replaced in.
+    // A provider's token is in this url when the dial sends it in the query,
+    // which may then be written again, and in the header alone in header
+    // mode: the server's text is recorded with what the dial sent, the token
+    // in each form a token is replaced in.
     noteDialSent(config, { url, token: token ?? undefined });
     // Error strings travel: traces, logs, tool results the model reads. They
     // get the endpoint, never the credential.
     const redacted = redactUrl(config.url);
-    const ws = new WebSocket(url);
+    // In header mode the url carries no credential (buildWebSocketUrl): the
+    // upgrade request does, if a header can carry it as configured
+    // (headerCarries). A static token is refused earlier, by
+    // serverConfigProblems; this refuses an access provider's, and a static
+    // one dialed past that check. A client that throws as the socket is
+    // constructed can quote the url, so its text is masked (clientErrorText).
+    const headerMode = config.tokenTransport === 'header' && !!token;
+    if (headerMode && token && !headerCarries(token)) {
+      throw new Error(`MCPL server "${config.id}" WebSocket connect failed: its credential isn't printable ASCII with no space at either end, which is all a header carries as configured (${redacted})`);
+    }
+    let ws: WebSocket;
+    try {
+      ws = headerMode
+        ? new WebSocket(url, { headers: { Authorization: `Bearer ${token}` } })
+        : new WebSocket(url);
+    } catch (err) {
+      throw new Error(`MCPL server "${config.id}" WebSocket connect failed: ${clientErrorText(err, config, url)} (${redacted})`);
+    }
 
     // A failed dial can emit 'error' MORE THAN ONCE on the raw socket (seen
     // live 2026-08-03: an HTTP 502 upgrade-reject emits the "Expected 101"
@@ -602,11 +685,11 @@ export class WebSocketTransport extends McplTransport {
         clearTimeout(timer);
         signal?.removeEventListener('abort', onAbort);
         ws.removeAllListeners('error'); // the instance re-attaches its own handlers
-        resolve(new WebSocketTransport(ws, config.id));
+        resolve(new WebSocketTransport(ws, config, url));
       });
 
       ws.once('error', (err: Error) => {
-        abandon(new Error(`MCPL server "${config.id}" WebSocket connect failed: ${err.message} (${redacted})`));
+        abandon(new Error(`MCPL server "${config.id}" WebSocket connect failed: ${clientErrorText(err, config, url)} (${redacted})`));
       });
     });
   }
@@ -635,10 +718,53 @@ export class WebSocketTransport extends McplTransport {
   }
 }
 
+/** A ws:// or wss:// url in a WebSocket client's text, to the next space or
+ *  quote: brackets (an IPv6 host) and parentheses can be part of one. */
+const WS_URL_IN_TEXT = /\bwss?:\/\/[^\s"'<>`]+/gi;
+
+/**
+ * A WebSocket client's error text (an Error under Node's ws, an ErrorEvent
+ * under Bun's), as the transport's own errors carry it: a failed dial's, and
+ * one after the socket opened. A client can quote the url as dialed: under
+ * Bun 1.3.13 and 1.4.3 a refused or unreachable dial's message holds it
+ * whole, its user, password, path and query, and the token, a static one or
+ * an access provider's. In order, so a credential is replaced while it's
+ * whole: the url as dialed and as configured, wherever they occur, are
+ * shown as {@link redactUrl} shows them; then the strings the configuration
+ * and its dials know to be credentials (the dial has noted what it sent by
+ * now) are replaced, in their encoded and decoded forms
+ * ({@link redactServerText}); then any other ws(s) url left is shown as
+ * {@link redactUrl} shows it. The caller makes a new error of it with no
+ * `cause`, so the client's own error, message and stack, isn't reachable.
+ * A configuration that can't be read withholds the text
+ * ({@link WITHHELD_TEXT}) rather than throw: this runs in a socket's
+ * 'error' listener, where a throw has nowhere to go.
+ */
+export function clientErrorText(err: unknown, config: McplServerConfig, dialed: string): string {
+  // Bun's ws emits an ErrorEvent, not an Error, its text in `message` too.
+  try {
+    const said = (err as { message?: unknown } | null)?.message;
+    let text = typeof said === 'string' ? said : String(err);
+    const configured = config.url;
+    const shown = redactUrl(configured);
+    for (const url of [dialed, configured]) {
+      if (url) text = text.split(url).join(shown);
+    }
+    text = redactServerText(text, config);
+    return text.replace(WS_URL_IN_TEXT, (found) => redactUrl(found));
+  } catch {
+    return WITHHELD_TEXT;
+  }
+}
+
 /**
  * Build the dial URL: validate it's a ws(s):// URL the ws library will dial,
  * which refuses one with a fragment, and append the auth token as a `token`
- * query param when provided (preserving any existing query).
+ * query param when provided (preserving any existing query). With
+ * `tokenTransport: 'header'` no token is appended: the dial sends it as a
+ * header, and a url that carries a `token` parameter of its own is refused,
+ * as is a `tokenTransport` that is neither mode, so a dial that skipped
+ * serverConfigProblems still can't fall back to the query.
  */
 export function buildWebSocketUrl(config: McplServerConfig, tokenOverride?: string | null): string {
   if (!config.url) {
@@ -659,7 +785,10 @@ export function buildWebSocketUrl(config: McplServerConfig, tokenOverride?: stri
   if (parsed.hash) {
     throw new Error(`MCPL server "${config.id}": websocket url must not have a fragment, got "${parsed.hash}"`);
   }
-  const token = tokenOverride !== undefined ? tokenOverride : config.token;
+  const problem = tokenTransportProblem(config, parsed);
+  if (problem) throw new Error(problem);
+  const token = config.tokenTransport === 'header' ? null
+    : tokenOverride !== undefined ? tokenOverride : config.token;
   return urlAsDialed(parsed, token).toString();
 }
 

package/src/mcpl/types.ts

@@ -285,12 +285,28 @@ export interface McplServerConfig {
   /**
    * Bearer token for a network server. Where it travels depends on the
    * transport: on a ws(s):// url it is appended as a `token` query parameter
-   * (`?token=…`) on connect; to an http(s):// server it is sent as an
-   * `Authorization: Bearer` header and never put in the url. A legacy stdio
-   * server ignores it, and a modern stdio server refuses it.
+   * (`?token=…`) on connect, unless `tokenTransport` is `'header'`; to an
+   * http(s):// server it is sent as an `Authorization: Bearer` header and
+   * never put in the url. A legacy stdio server ignores it, and a modern
+   * stdio server refuses it.
    */
   token?: string;
 
+  /**
+   * How a ws(s):// server's credential, `token` or what `accessProvider`
+   * returns for the dial, is sent on the WebSocket upgrade. `'query'`, the
+   * default: as a `token` query parameter (`?token=…`). `'header'`: as an
+   * `Authorization: Bearer …` header, with no query parameter, so the
+   * credential stays out of the url and of the access logs that record it.
+   * A header carries a credential as configured only if it is printable
+   * ASCII (U+0020 to U+007E) with no space at either end, so header mode
+   * refuses any other: a static `token` when the server is added, an access
+   * provider's at the dial. Set only on a WebSocket server; an http(s)://
+   * server always sends the header, and a stdio server sends no credential.
+   * `null` counts as not set.
+   */
+  tokenTransport?: 'query' | 'header';
+
   /**
    * Lazily resolves the connection credential at EVERY dial — first connect
    * and each background reconnect — overriding `token` when it returns a
@@ -414,9 +430,10 @@ export interface McplServerConfig {
    * are also the only bound for one that closes its stdin, since Bun emits no
    * 'error' event for the writes to it. requestTimeoutMs is the timeout of
    * every request that names none; the handshake's initialize has 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.
+   * Set 0 to disable, except for channels/publish, channels/open and
+   * channels/close, which keep the 60 s default: a publish's outcome is
+   * reported to the resident and recorded for its draft, so it must end, and
+   * a delivery waits for a channel's queued opens and closes.
    * Default: 60000 (60 seconds). A value above 2^31−1 is refused: Node runs a
    * longer timer after about 1 ms, so every request would time out at once.
    *

package/src/module-registry.ts

@@ -310,7 +310,8 @@ export class ModuleRegistry {
    * Handle a tool call by routing to the appropriate module: the module's own
    * result, unchecked, as it returned it, for a caller that uses the result
    * in process (`ModuleContext.callTool`, `executeToolCall`, or a host
-   * calling the registry). A module's throw is answered as an error result.
+   * calling the registry), less a refusal it claims (withoutRefusal). A
+   * module's throw is answered as an error result.
    * A call whose input isn't an object, or lacks a key the tool's schema
    * requires, is answered before the module runs, with an error result that
    * opens "Nothing was done:" and names what to send (toolArgsProblems).
@@ -324,7 +325,7 @@ export class ModuleRegistry {
     if (sepIndex === -1) {
       return {
         success: false,
-        error: `Invalid tool name format: ${call.name}`,
+        error: `Invalid tool name format: ${call.name}, so nothing was done`,
         isError: true,
       };
     }
@@ -336,19 +337,14 @@ export class ModuleRegistry {
     if (!module) {
       return {
         success: false,
-        error: `Module not found: ${moduleName}`,
+        error: `Module not found: ${moduleName}, so nothing was done`,
         isError: true,
       };
     }
 
-    // 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 } : {}),
-    };
+    // The call as it came, with the un-prefixed name: the caller's identity
+    // and everything else the dispatch set on it reach the module.
+    const moduleCall: ToolCall = { ...call, name: toolName };
 
     try {
       // The call against the tool's declared schema, before the module runs:
@@ -372,7 +368,9 @@ export class ModuleRegistry {
           isError: true,
         };
       }
-      return await module.handleToolCall(moduleCall);
+      // A refusal is the dispatcher's to say (RFC-007), so a module's result
+      // can't claim one on this route either.
+      return withoutRefusal(call, await module.handleToolCall(moduleCall));
     } catch (error) {
       return thrownResult(error);
     }
@@ -900,6 +898,83 @@ class ProcessStateImpl implements ProcessState {
   }
 }
 
+/** The fields ToolResult declares, read by name, so a result class's getters count: endTurn first and the error next, so a failure keeps them. */
+const TOOL_RESULT_FIELDS = ['endTurn', 'error', 'success', 'isError', 'data', 'structured', 'keepWhenWithheld'] as const;
+
+/**
+ * A module's result for an in-process caller: the module's own object, unless
+ * it claims a refusal, which is the dispatcher's to say (RFC-007). Then it's a
+ * copy, less the claim: a plain object of every field ToolResult declares,
+ * read by name, so a result class's getters count, each read once, and every
+ * other own enumerable field, string or symbol, as a spread takes them, so
+ * non-enumerable own fields and inherited undeclared ones are left out. A
+ * result that can't be read, its claim included, is a failure saying so, as
+ * on the stored route (checkedToolResult),
+ * keeping the turn's end and the module's error if those could be read: the
+ * module's call completed, and the claim never reaches the caller.
+ */
+function withoutRefusal(call: ToolCall, result: ToolResult): ToolResult {
+  // Not an object: nothing to claim, and the caller gets it as it came.
+  if (!result || (typeof result !== 'object' && typeof result !== 'function')) return result;
+  const source = result as unknown as Record<PropertyKey, unknown>;
+  const copy: Record<PropertyKey, unknown> = {};
+  // Each field is read once: one whose getter threw isn't asked again.
+  const read = new Set<PropertyKey>();
+  // Defined, not assigned, so a field named __proto__ is a field.
+  const keep = (key: PropertyKey): void => {
+    read.add(key);
+    Object.defineProperty(copy, key, { value: source[key], enumerable: true, writable: true, configurable: true });
+  };
+  const once = (key: string): unknown => {
+    if (key in copy) return copy[key];
+    if (read.has(key)) return undefined;
+    return source[key];
+  };
+  // A failure keeps what could be read of the turn's end and the module's
+  // error, each read on its own, whatever else couldn't be.
+  const unreadable = (error: unknown): ToolResult => {
+    let endTurn: unknown;
+    let own: string | undefined;
+    try {
+      endTurn = once('endTurn');
+    } catch {
+      // Not readable: the failure doesn't end the turn.
+    }
+    try {
+      own = errorText(once('error'));
+    } catch {
+      // An error whose own text can't be read: the failure says only why.
+    }
+    return {
+      success: false,
+      isError: true,
+      error: `Tool '${call.name}' returned a result that couldn't be read (${thrownText(error).split('\n')[0] || 'no reason given'}). ` +
+        `The call itself completed${own ? `, with this error: ${own}` : '.'}`,
+      ...(endTurn ? { endTurn: true } : {}),
+    };
+  };
+  let claim: unknown;
+  try {
+    claim = source.refused;
+  } catch (error) {
+    return unreadable(error);
+  }
+  if (!claim) return result;
+  try {
+    const copied = new Set<PropertyKey>(['refused']);
+    for (const key of TOOL_RESULT_FIELDS) {
+      copied.add(key);
+      if (key in source) keep(key);
+    }
+    for (const key of Reflect.ownKeys(source)) {
+      if (!copied.has(key) && Object.prototype.propertyIsEnumerable.call(source, key)) keep(key);
+    }
+    return copy as unknown as ToolResult;
+  } catch (error) {
+    return unreadable(error);
+  }
+}
+
 /** A result's flags, which consumers read for their truth: booleans here. */
 const RESULT_FLAGS = ['success', 'isError', 'endTurn'] as const;
 
@@ -921,7 +996,8 @@ const RESULT_FLAGS = ['success', 'isError', 'endTurn'] as const;
  * runs again. It's taken where the framework stores or sends a result
  * ({@link ModuleRegistry.storableToolCall}). A caller that uses the result
  * in process (`ModuleContext.callTool`, `executeToolCall`) gets the module's
- * own result, as the module returned it ({@link ModuleRegistry.handleToolCall}).
+ * own result, as the module returned it, less a refusal it claims
+ * ({@link ModuleRegistry.handleToolCall}).
  * The flags are booleans, read for their truth as consumers read them.
  * `error` is its text form, which is all a consumer reads of it, so an error
  * value JSON can't hold costs nothing. An error that says nothing (null,
@@ -977,6 +1053,9 @@ export function checkedToolResult(call: ToolCall, result: unknown): { result: To
     }
     // The error is kept as its text, which consumers read; its value isn't.
     delete fields.error;
+    // A refusal is the dispatcher's to say, before the call opens (RFC-007):
+    // a module answers after that, so its result can't claim one.
+    delete fields.refused;
     // The flags are kept as their truth, which is all consumers read of them,
     // before anything is serialized, so a flag's own value (a BigInt, a
     // function, an object with a toJSON) neither breaks nor runs anything.

package/src/modules/discord/index.ts

@@ -8,7 +8,7 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
-import type { StoredMessage } from '@animalabs/context-manager';
+import { continuesBody, type StoredMessage } from '@animalabs/context-manager';
 import type {
   Module,
   ModuleContext,
@@ -322,19 +322,14 @@ function withoutGoneAttachments(content: ContentBlock[], attachments: readonly D
   return textFirst(first.text, kept);
 }
 
-/** The ids to remove for a message's rows: each row once, and a body stored
- *  in shards once, since removing one shard takes out its whole body. */
+/** The ids to remove for a message's rows, in store order: each row once,
+ *  and a body stored in shards once, by its first shard, since removing one
+ *  shard takes out its whole body. Which rows make up a body is
+ *  context-manager's rule (continuesBody), read pairwise: a group id names
+ *  the text, so a message stored twice in shards is two bodies under one id,
+ *  and each is removed. */
 function oncePerBody(rows: readonly StoredMessage[]): string[] {
-  const bodies = new Set<string>();
-  const ids: string[] = [];
-  for (const row of rows) {
-    if (row.bodyGroupId) {
-      if (bodies.has(row.bodyGroupId)) continue;
-      bodies.add(row.bodyGroupId);
-    }
-    ids.push(row.id);
-  }
-  return ids;
+  return rows.filter((row, i) => !continuesBody(rows[i - 1], row)).map((row) => row.id);
 }
 
 /** A live create on its way to the store (DiscordModule.creating). */