@animalabs/agent-framework 0.31.0 → 0.33.0

package/src/mcpl/server-connection.ts

@@ -16,6 +16,7 @@ import { maskNegotiatedCapabilities } from './capability-mask.js';
 import { CapabilityGrant, expandAdvertisementShorthand } from './capability-grant.js';
 import { CAPABILITY_DISABLED, boundedForLog, describeCause } from './errors.js';
 import { logDetail, logValue, logValueRedacted, loggedCode } from './log-value.js';
+import { jsonKind, readEnvelope } from '../jsonrpc-envelope.js';
 import {
   LEGACY_MCP_PROTOCOL_VERSION,
   MODERN_MCP_PROTOCOL_VERSION,
@@ -367,11 +368,32 @@ interface HeldItem {
   kept?: true;
 }
 
-/** A request's method for a log line, whatever the server sent there. */
-function describeMethod(method: unknown): string {
-  return typeof method === 'string'
-    ? `method ${logValue(method)}`
-    : `a method of type ${method === null ? 'null' : typeof method}`;
+/** Whether a response that can't be matched to a request of ours, its id
+ *  being neither a string nor a number or missing, is logged: only a
+ *  JSON-RPC 2.0 error is, since that's how a server says it couldn't read a
+ *  message of ours (JSON-RPC 2.0 §5). Anything else id-less, such as a
+ *  server's own JSON log line with `"id": null`, is ignored silently, as it
+ *  was before #475, so a server's log output can't fill the host's. */
+function isJsonRpcError(response: object): boolean {
+  return (response as { jsonrpc?: unknown }).jsonrpc === '2.0' && Object.hasOwn(response, 'error');
+}
+
+/** The log line for such an error. The host's own request ids are numbers,
+ *  so it can't be matched to one. Once connected it may be the answer to a
+ *  request of ours, which gets nothing from it and ends as any unanswered
+ *  request does, by its timeout where it has one. (During the handshake an
+ *  error with id null or no id answers initialize.) Its error member is the
+ *  server's text, whatever JSON value it is, so it's printed redacted with
+ *  `redact`, the server's redaction (logValueRedacted), as handleResponse
+ *  prints a matched error's code and message. */
+function unmatchedResponse(
+  serverId: string,
+  response: { id?: unknown; error?: unknown },
+  redact: (text: string) => string,
+): string {
+  const which = Object.hasOwn(response, 'id') ? `whose id is ${jsonKind(response.id)}` : 'with no id';
+  return `[mcpl] ${serverId}: ignored a response ${which}, which can't be matched to a request of ours; ` +
+    `its error: ${logValueRedacted(response.error, redact)}`;
 }
 
 /**
@@ -700,13 +722,14 @@ export class McplServerConnection extends EventEmitter {
   // Reconnect state (adapted from Anarchid/agent-framework@mcpl-module-proto)
   private config: McplServerConfig | null = null;
   /** The redactor of the server's text for `config`, made at its first error
-   *  answer, by when `config` is set, and kept: a framework-launched child's
-   *  `env` is a getter that reads the awareness ledger, so a redactor built
-   *  per answer would read it per answer (#540's review, R1-2). An answer
-   *  takes one build of it for its words, data and log line (`now()`), so
-   *  it reads the ledger at most once. It builds again only after a build
-   *  that failed, which withholds that answer's text, or once a dial notes
-   *  something new (serverTextRedactor). */
+   *  answer or response it can't match (handleResponse), by when `config`
+   *  is set, and kept: a framework-launched child's `env` is a getter that
+   *  reads the awareness ledger, so a redactor built per answer would read
+   *  it per answer (#540's review, R1-2). An answer takes one build of it
+   *  for its words, data and log line (`now()`), so it reads the ledger at
+   *  most once. It builds again only after a build that failed, which
+   *  withholds that answer's text, or once a dial notes something new
+   *  (serverTextRedactor). */
   private redactor: ServerTextRedactor | null = null;
   private hostCapabilities: McplHostCapabilities | null = null;
   private reconnectEnabled = false;
@@ -1358,15 +1381,35 @@ export class McplServerConnection extends EventEmitter {
           // initialize response, whatever its id: a server's own ids can start
           // at 0, this handshake's. MCP lets a server ping before
           // initialization completes, and the ping gets its empty result, as
-          // on a connected transport. Anything else it sends now is ignored.
-          if ('method' in msg) {
-            const request = msg as unknown as JsonRpcRequest;
-            if (request.method === 'ping' && request.id != null) {
-              transport.writeLine(JSON.stringify({ jsonrpc: '2.0', id: request.id, result: {} }));
+          // on a connected transport, `"id": null` included
+          // (src/jsonrpc-envelope.ts). Anything else it sends now is ignored,
+          // an invalid request included. Of its responses, the one with
+          // initialize's id answers it, and so does a JSON-RPC 2.0 error with
+          // id null or with no id: a peer answers a request it couldn't read
+          // that way (JSON-RPC 2.0 §5; MCP 2025-11-25, Basic), initialize is
+          // the only request this host has out, and a peer never answers a
+          // response. Such an error means the server can't read this host's
+          // messages, so the handshake fails at once, with the error's message.
+          // `"jsonrpc": "2.0"` keeps a server's own JSON log line with an
+          // error key and id null, or no id, from failing it; one with
+          // initialize's id is taken for the answer, whatever its jsonrpc. Of
+          // the other responses, a JSON-RPC 2.0 error whose id is neither a
+          // string nor a number is logged, as on a connected transport, and
+          // any other is ignored.
+          const envelope = readEnvelope(msg as unknown as Record<string, unknown>);
+          if (envelope.kind === 'request' && envelope.method === 'ping') {
+            transport.writeLine(JSON.stringify({ jsonrpc: '2.0', id: envelope.id, result: {} }));
+            return;
+          }
+          if (envelope.kind !== 'response') return;
+          const namesNoRequest = msg.id === null || !Object.hasOwn(msg, 'id');
+          const answersInitialize = msg.id === initId || (namesNoRequest && msg.jsonrpc === '2.0' && Boolean(msg.error));
+          if (!answersInitialize) {
+            if (typeof msg.id !== 'string' && typeof msg.id !== 'number' && isJsonRpcError(msg)) {
+              console.error(unmatchedResponse(config.id, msg, (text) => redactServerText(text, config)));
             }
             return;
           }
-          if (msg.id !== initId) return;
           cleanup();
           if (msg.error) {
             // describeCause rather than the template's own conversion: the
@@ -1739,8 +1782,9 @@ export class McplServerConnection extends EventEmitter {
    * following `nextCursor` across pages (2024-11-05 pagination). Cursors are
    * opaque strings, `''` included: only an absent or null `nextCursor` ends
    * the inventory (a null one is how some servers say "no more", and main
-   * read it as a complete page). A page that isn't well formed (no `tools` array, a cursor
-   * that isn't a string), or cursors that don't terminate (a repeat, or more
+   * read it as a complete page). A page that isn't well formed (no `tools` array, an entry
+   * that isn't an object with a string `name`, a cursor that isn't a string), or cursors
+   * that don't terminate (a repeat, or more
    * than {@link MAX_TOOL_LIST_PAGES} pages), are errors, never a partial or
    * empty inventory published as complete. The read tap (RFC-014) is handed
    * the complete inventory once, with the last page's `_meta`, as the last
@@ -1755,9 +1799,12 @@ export class McplServerConnection extends EventEmitter {
     let first: Record<string, unknown> | undefined;
     const read: McpToolDefinition[] = [];
     const revs = new Set<unknown>();
+    const isTool = (entry: unknown): boolean =>
+      !!entry && typeof entry === 'object' && typeof (entry as { name?: unknown }).name === 'string';
     const onRead = (result: unknown) => {
       if (!result || typeof result !== 'object' || !Array.isArray((result as { tools?: unknown }).tools)) return;
       const r = result as { tools: McpToolDefinition[]; nextCursor?: unknown; _meta?: unknown };
+      if (!r.tools.every(isTool)) return;
       for (const t of r.tools) read.push(t);
       const rev = (r._meta as Record<string, unknown> | undefined)?.['mcpl/rev'];
       if (typeof rev === 'number') revs.add(rev);
@@ -1774,6 +1821,8 @@ export class McplServerConnection extends EventEmitter {
       if (!result || typeof result !== 'object' || !Array.isArray(result.tools)) {
         throw malformed('no tools array');
       }
+      const unreadable = (result.tools as unknown[]).findIndex((entry) => !isTool(entry));
+      if (unreadable !== -1) throw malformed(`entry ${unreadable + 1} isn't an object with a string name`);
       first ??= result;
       for (const t of result.tools as McpToolDefinition[]) tools.push(t);
       if (result.nextCursor === undefined || result.nextCursor === null) {
@@ -2389,10 +2438,10 @@ export class McplServerConnection extends EventEmitter {
     // passed is the dead process's (afterBoundary).
     const epoch = this.transportEpoch;
     transport.on('line', (line: string) => {
-      const msg = messageFromLine(this.id, line, transport) as JsonRpcRequest | JsonRpcResponse | undefined;
+      const msg = messageFromLine(this.id, line, transport);
       if (!msg) return;
       try {
-        this.dispatchMessage(msg, epoch);
+        this.dispatchMessage(msg as Record<string, unknown>, epoch);
       } catch (error) {
         const request = msg as { method?: unknown; id?: unknown };
         this.reportInboundFailure(error, {
@@ -2404,25 +2453,47 @@ export class McplServerConnection extends EventEmitter {
   }
 
   /** Contain synchronous dispatch failures; async RPC handlers own their promises. */
-  private dispatchMessage(msg: JsonRpcRequest | JsonRpcResponse, epoch: number): void {
-    // Is this a response to one of our outbound requests?
-    if ('id' in msg && msg.id != null && !('method' in msg)) {
-      const late = epoch !== this.transportEpoch;
-      // RFC-014: its hints apply as it's read, whether or not anyone still
-      // waits for it. A dead transport's revs are its own, so a response
-      // read after its boundary is never tapped.
-      if (!late) this.tapResponse(msg as JsonRpcResponse);
-      this.handleResponse(msg as JsonRpcResponse, late);
-      return;
+  private dispatchMessage(msg: Record<string, unknown>, epoch: number): void {
+    // The envelope is read once, here (src/jsonrpc-envelope.ts says how).
+    const envelope = readEnvelope(msg);
+    switch (envelope.kind) {
+      case 'response': {
+        // Never answered, so a server that answers what it can't read, with
+        // id null, can't start an exchange of errors with us. One read after
+        // its transport's boundary is late (handleResponse).
+        const late = epoch !== this.transportEpoch;
+        // RFC-014: its hints apply as it's read, whether or not anyone still
+        // waits for it. A dead transport's revs are its own, so a response
+        // read after its boundary is never tapped.
+        if (!late) this.tapResponse(msg as unknown as JsonRpcResponse);
+        this.handleResponse(msg as unknown as JsonRpcResponse, late);
+        return;
+      }
+      case 'neither':
+        // Not JSON-RPC: ignored like the server's other unrelated output.
+        return;
+      case 'invalid': {
+        // Answered on the transport it came on, as every request is. One
+        // read after that transport's boundary is the dead process's and
+        // isn't answered: sendErrorResponse logs the answer it didn't send.
+        this.sendErrorResponse(envelope.id, envelope.error.code, envelope.error.message, undefined, epoch);
+        if (epoch !== this.transportEpoch) return;
+        const forMethod = envelope.method !== undefined ? ` for method ${logValue(envelope.method)}` : '';
+        console.error(`[mcpl] ${this.id}: answered -32600 to an invalid request${forMethod}: ${envelope.problems}`);
+        return;
+      }
     }
 
-    // It is an inbound request or notification from the server
-    const request = msg as JsonRpcRequest;
+    // It is an inbound request or notification from the server, its method
+    // a string. A request's id is a string, a number or null, and `"id": null`
+    // is answered with id null; a notification has none.
+    const request = msg as unknown as JsonRpcRequest;
+    const requestId = envelope.kind === 'request' ? envelope.id : undefined;
 
     // Read after its transport's boundary, it is the dead process's: the
     // boundary's rule applies (afterBoundary).
     if (epoch !== this.transportEpoch) {
-      this.afterBoundary(request, epoch);
+      this.afterBoundary(request, requestId, epoch);
       return;
     }
 
@@ -2432,7 +2503,7 @@ export class McplServerConnection extends EventEmitter {
     // paused plane mustn't hold that answer. A ping sent as a notification
     // has nothing to answer. The handshake answers one too.
     if (request.method === 'ping') {
-      if (request.id != null) this.sendResponse(request.id, {});
+      if (requestId !== undefined) this.sendResponse(requestId, {});
       return;
     }
 
@@ -2443,11 +2514,11 @@ export class McplServerConnection extends EventEmitter {
     if (request.method === 'push/event') this.tap({ kind: 'push', params: request.params });
     else if (request.method === 'tools/hints' && this.readTap) {
       this.tap({ kind: 'hints', params: request.params });
-      if (request.id != null) this.sendResponse(request.id, {});
+      if (requestId !== undefined) this.sendResponse(requestId, {});
       return;
     }
 
-    const eventName = typeof request.method === 'string' && Object.hasOwn(McplServerConnection.METHOD_TO_EVENT, request.method)
+    const eventName = Object.hasOwn(McplServerConnection.METHOD_TO_EVENT, request.method)
       ? McplServerConnection.METHOD_TO_EVENT[request.method] : undefined;
 
     // §7 is removed in 0.5.0: scope/elevate is no longer a method. Answer
@@ -2459,8 +2530,8 @@ export class McplServerConnection extends EventEmitter {
     // routed, control-plane classified, and mutating declarations — a
     // live ungated self-attestation path (PR #79 review blocker 4).
     if (request.method === McplMethod.FeatureSetsChanged) {
-      if (request.id != null) {
-        this.sendErrorResponse(request.id, -32601, 'featureSets/changed removed in MCPL 0.5.0 (superseded by mcpl/manifestChanged, SPEC §17)');
+      if (requestId !== undefined) {
+        this.sendErrorResponse(requestId, -32601, 'featureSets/changed removed in MCPL 0.5.0 (superseded by mcpl/manifestChanged, SPEC §17)');
       } else {
         console.error(`[mcpl] ${this.id}: discarded featureSets/changed — removed in 0.5.0 (§6.7/§17)`);
       }
@@ -2468,8 +2539,8 @@ export class McplServerConnection extends EventEmitter {
     }
 
     if (request.method === McplMethod.ScopeElevate) {
-      if (request.id != null) {
-        this.sendErrorResponse(request.id, -32601, 'scope/elevate removed in MCPL 0.5.0 (SPEC §7)');
+      if (requestId !== undefined) {
+        this.sendErrorResponse(requestId, -32601, 'scope/elevate removed in MCPL 0.5.0 (SPEC §7)');
       }
       return;
     }
@@ -2481,20 +2552,19 @@ export class McplServerConnection extends EventEmitter {
 
     if (!eventName) {
       // §6.6: a request that will never be answered MUST get an error, so a
-      // request (it has an id) whose method isn't a string, or isn't one this
-      // host handles, is answered -32601. A notification nobody handles is
-      // ignored, as JSON-RPC asks.
-      if (request.id != null) {
-        this.sendErrorResponse(request.id, -32601, 'Method not found');
-        console.error(`[mcpl] ${this.id}: answered -32601 to a request for ${describeMethod(request.method)}, which this host doesn't handle`);
+      // request whose method isn't one this host handles is answered -32601.
+      // A notification nobody handles is ignored, as JSON-RPC asks.
+      if (requestId !== undefined) {
+        this.sendErrorResponse(requestId, -32601, 'Method not found');
+        console.error(`[mcpl] ${this.id}: answered -32601 to a request for method ${logValue(request.method)}, which this host doesn't handle`);
       }
       return;
     }
 
     // Emit the typed event with params and (for requests) a respond callback
-    if (request.id != null) {
+    if (requestId !== undefined) {
       // Server expects a response — provide a respond helper
-      this.dispatchInboundEvent(eventName, request.params, this.responderFor(request.id, epoch));
+      this.dispatchInboundEvent(eventName, request.params, this.responderFor(requestId, epoch));
     } else {
       // Notification — no response expected
       this.dispatchInboundEvent(eventName, request.params);
@@ -2504,9 +2574,10 @@ export class McplServerConnection extends EventEmitter {
   /**
    * A request's responder, bound to the transport it came on (`epoch`): an
    * answer, or a streamed inference's chunk, sent after that transport has
-   * closed reaches nothing, never a server that didn't ask it.
+   * closed reaches nothing, never a server that didn't ask it. A request
+   * sent with id null is answered with id null.
    */
-  private responderFor(id: string | number, epoch: number) {
+  private responderFor(id: string | number | null, epoch: number) {
     return {
       id,
       signal: epoch === this.transportEpoch ? this.transportEnded.signal : AbortSignal.abort(),
@@ -2531,17 +2602,17 @@ export class McplServerConnection extends EventEmitter {
    * it while its writer lives, with no grant to come, so it drops and logs
    * all of it; hold's bounds cap what any other keeps.
    */
-  private afterBoundary(request: JsonRpcRequest, epoch: number): void {
-    const event = typeof request.method === 'string' && Object.hasOwn(McplServerConnection.METHOD_TO_EVENT, request.method)
+  private afterBoundary(request: JsonRpcRequest, requestId: string | number | null | undefined, epoch: number): void {
+    const event = Object.hasOwn(McplServerConnection.METHOD_TO_EVENT, request.method)
       ? McplServerConnection.METHOD_TO_EVENT[request.method] : undefined;
     if (this.closedForGood || event === undefined || !McplServerConnection.WORLD_EVENTS.has(event)) {
       console.error(
         `[mcpl] ${this.id}: dropped a message read after its transport closed` +
-        `${this.closedForGood ? ', with no transport to come' : ''}: ${describeMethod(request.method)}`,
+        `${this.closedForGood ? ', with no transport to come' : ''}: method ${logValue(request.method)}`,
       );
       return;
     }
-    this.hold(event, request.id != null ? [request.params, this.responderFor(request.id, epoch)] : [request.params], true);
+    this.hold(event, requestId !== undefined ? [request.params, this.responderFor(requestId, epoch)] : [request.params], true);
   }
 
   /** Live delivery and delayed plane flushes share the same containment boundary. */
@@ -2596,7 +2667,7 @@ export class McplServerConnection extends EventEmitter {
   /** Tap a response to a hinted request (RFC-014): its result's hints, or a
    *  list's statement, apply now, awaited or not. */
   private tapResponse(response: JsonRpcResponse): void {
-    if (!this.readTap) return;
+    if (!this.readTap || response.id === null) return;
     const sent = this.hintedRequests.get(response.id);
     if (!sent) return;
     this.hintedRequests.delete(response.id);
@@ -2609,6 +2680,16 @@ export class McplServerConnection extends EventEmitter {
    * Handle a JSON-RPC response by resolving/rejecting the corresponding pending request.
    */
   private handleResponse(response: JsonRpcResponse, late = false): void {
+    // A response whose id is neither a string nor a number, or that has
+    // none, can't be matched to a request of ours, on this transport or an
+    // earlier one. It isn't an orphan, which is a late answer to one, so
+    // it's ignored, and logged when it's a JSON-RPC 2.0 error.
+    if (typeof response.id !== 'string' && typeof response.id !== 'number') {
+      if (isJsonRpcError(response)) {
+        console.error(unmatchedResponse(this.id, response, (this.redactor ??= serverTextRedactor(this.config ?? {})).now()));
+      }
+      return;
+    }
     // One read after its transport's boundary answers a request the close
     // ended. It's matched against none of this connection's request records,
     // since the next transport numbers its requests afresh, and goes the way
@@ -2706,7 +2787,7 @@ export class McplServerConnection extends EventEmitter {
   /**
    * Send a successful JSON-RPC response back to the server.
    */
-  private sendResponse(id: string | number, result: unknown, epoch = this.transportEpoch): void {
+  private sendResponse(id: string | number | null, result: unknown, epoch = this.transportEpoch): void {
     // A closed connection's epoch is past every request's, so a refusal
     // while it is closed is logged too.
     if (!this.sameTransport(id, epoch) || this.closed) return;
@@ -2717,7 +2798,7 @@ export class McplServerConnection extends EventEmitter {
   /** Whether a response to a request received on `epoch` may go out now.
    *  The id is the server's, so it's logged as a field; `answer`, which the
    *  caller has formatted for the log, ends the line. */
-  private sameTransport(id: string | number, epoch: number, answer?: string): boolean {
+  private sameTransport(id: string | number | null, epoch: number, answer?: string): boolean {
     if (epoch === this.transportEpoch) return true;
     console.error(
       `[mcpl] ${this.id}: not answering request ${logValue(id)}: the transport it came on has closed${answer ? `, with ${answer}` : ''}`,
@@ -2729,7 +2810,7 @@ export class McplServerConnection extends EventEmitter {
    * Send a JSON-RPC error response back to the server.
    */
   private sendErrorResponse(
-    id: string | number,
+    id: string | number | null,
     code: number,
     message: string,
     data?: unknown,

package/src/mcpl/tool-classes.ts

@@ -87,8 +87,11 @@ export const BUILTIN_TOOL_CLASSES: Readonly<Record<string, readonly ToolClass[]>
   wake: ['control'],
   wake_add_rule: ['control'],
   wake_remove_rule: ['control'],
+  wake_accept_suggestions: ['control'],
+  wake_decline: ['control'],
   event_tags: ['control'],
   prose_help: ['control'],
+  prose_locus: ['control'],
   // Files and blobs in the agent's own stores.
   save_recent_image: ['files'],
   read_image: ['files'],

package/src/mcpl/types.ts

@@ -22,7 +22,8 @@
 export interface JsonRpcRequest {
   jsonrpc: '2.0';
   method: string;
-  id?: string | number;
+  /** A request's id; null is allowed, though JSON-RPC 2.0 discourages it. */
+  id?: string | number | null;
   params?: Record<string, unknown>;
 }
 
@@ -31,7 +32,8 @@ export interface JsonRpcRequest {
  */
 export interface JsonRpcResponse {
   jsonrpc: '2.0';
-  id: string | number;
+  /** The request's id, or null when the request's own couldn't be read. */
+  id: string | number | null;
   result?: unknown;
   error?: JsonRpcError;
 }
@@ -596,6 +598,10 @@ export interface FeatureSetDeclaration {
     coreTags?: string[];
     tags?: Record<string, unknown>;
     keyed?: Record<string, unknown>;
+    /** Ordered suggested rules (RFC-001 §5.1). Advisory: applied only on
+     *  acceptance (§5.2), which wake onboarding asks the agent for. */
+    suggestedTreatment?: unknown[];
+    /** @deprecated RFC-001 revision 1's name for suggestedTreatment; still read. */
     defaultTreatment?: unknown[];
     open?: boolean;
   };

package/src/module-registry.ts

@@ -1,11 +1,15 @@
 import type { JsStateRegistration, JsStore } from '@animalabs/chronicle';
 import type { ContentBlock } from '@animalabs/membrane';
 import type {
+  ContextManager,
   MessageId,
   MessageMetadata,
   MessageQuery,
   ContextInjection,
+  StoredMessage,
+  WindowStatus,
 } from '@animalabs/context-manager';
+import { WriteOutcomeUnknownError } from './context-manager-errors.js';
 import type {
   Module,
   ModuleContext,
@@ -25,7 +29,6 @@ import type {
   ModuleContextInjection,
   MessageQueryResult,
 } from './types/index.js';
-import { heldWriteId } from './held-writes.js';
 import { boundedErrorMessage } from './error-message.js';
 import type { Agent } from './agent.js';
 import { DEFAULT_SHUTDOWN_TIMEOUT_MS, validateShutdownTimeout, waitForShutdown } from './shutdown.js';
@@ -150,6 +153,13 @@ export class ModuleRegistry {
     message: string,
     data?: Record<string, unknown>,
   ) => void;
+  /** The window lookups ModuleContext.windowStatusOf, observes, viewKeeps
+   *  and agentNameOf give modules (#291), when the framework offers them.
+   *  Readonly-public, as notifyOpsFn is. */
+  readonly windowStatusOfFn?: (id: MessageId, opts?: { forAgent?: string }) => WindowStatus;
+  readonly observesFn?: (observer: string, observed: string) => boolean;
+  readonly viewKeepsFn?: (row: StoredMessage, opts?: { forAgent?: string }) => boolean;
+  readonly agentNameOfFn?: (contextManager: ContextManager) => string | undefined;
 
   constructor(
     store: JsStore,
@@ -170,6 +180,14 @@ export class ModuleRegistry {
       onTrace: (listener: TraceEventListener) => () => void;
       callTool: (call: ToolCall) => Promise<ToolResult>;
       notifyOps?: (kind: string, agentName: string, message: string, data?: Record<string, unknown>) => void;
+      /** Where a row stands with an agent's window (ModuleContext.windowStatusOf). */
+      windowStatusOf?: (id: MessageId, opts?: { forAgent?: string }) => WindowStatus;
+      /** Whether one agent observes another's own rows (ModuleContext.observes). */
+      observes?: (observer: string, observed: string) => boolean;
+      /** Whether an agent's view keeps a stored row (ModuleContext.viewKeeps). */
+      viewKeeps?: (row: StoredMessage, opts?: { forAgent?: string }) => boolean;
+      /** The live agent whose context a context manager is (ModuleContext.agentNameOf). */
+      agentNameOf?: (contextManager: ContextManager) => string | undefined;
     }
   ) {
     this.store = store;
@@ -184,6 +202,10 @@ export class ModuleRegistry {
     this.onTraceFn = options.onTrace;
     this.callToolFn = options.callTool;
     this.notifyOpsFn = options.notifyOps;
+    this.windowStatusOfFn = options.windowStatusOf;
+    this.observesFn = options.observes;
+    this.viewKeepsFn = options.viewKeeps;
+    this.agentNameOfFn = options.agentNameOf;
     this.dropRetiredPushFn = options.dropRetiredPush;
   }
 
@@ -748,6 +770,12 @@ class ModuleContextImpl implements ModuleContext {
   private pushEventFn: (event: ProcessEvent, moduleName?: string) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
   private callToolFn: (call: ToolCall) => Promise<ToolResult>;
+  /** Offered only when the registry was given the framework's lookups, so
+   *  a module can tell a framework that has them from one that hasn't. */
+  readonly windowStatusOf?: (id: MessageId, opts?: { forAgent?: string }) => WindowStatus;
+  readonly observes?: (observer: string, observed: string) => boolean;
+  readonly viewKeeps?: (row: StoredMessage, opts?: { forAgent?: string }) => boolean;
+  readonly agentNameOf?: (contextManager: ContextManager) => string | undefined;
 
   // External ID mapping stored in module state
   private externalIdMap: Map<string, MessageId> = new Map();
@@ -794,6 +822,14 @@ class ModuleContextImpl implements ModuleContext {
     this.pushEventFn = pushEvent;
     this.onTraceFn = onTrace;
     this.callToolFn = callTool;
+    const windowStatusOf = registry.windowStatusOfFn;
+    if (windowStatusOf) this.windowStatusOf = (id, opts) => windowStatusOf(id, opts);
+    const observes = registry.observesFn;
+    if (observes) this.observes = (observer, observed) => observes(observer, observed);
+    const viewKeeps = registry.viewKeepsFn;
+    if (viewKeeps) this.viewKeeps = (row, opts) => viewKeeps(row, opts);
+    const agentNameOf = registry.agentNameOfFn;
+    if (agentNameOf) this.agentNameOf = (contextManager) => agentNameOf(contextManager);
 
     // Load external ID map from state if exists
     const state = this.getState<{ externalIdMap?: Record<string, string> }>();
@@ -951,15 +987,35 @@ class ModuleContextImpl implements ModuleContext {
       throw new Error(`A message for agent ${JSON.stringify(opts.forAgent)} can't carry metadata.external: `
         + "its external id would be looked up in the primary's window. Leave forAgent out, or the external id.");
     }
-    const id = this.addMessageFn(participant, content, metadata, opts);
+    let id: MessageId;
+    try {
+      id = this.addMessageFn(participant, content, metadata, opts);
+    } catch (error) {
+      // A write whose store threw where context-manager can't tell whether
+      // it landed (WriteOutcomeUnknownError, which the write is answered by)
+      // may be stored: its external id maps to '', as a write kept in memory
+      // does, so findMessageByExternalId looks it up in the store. A mapping
+      // that can't be persisted is logged, and the write's own error thrown.
+      if (metadata?.external && error instanceof WriteOutcomeUnknownError) {
+        this.externalIdMap.set(`${metadata.external.source}:${metadata.external.id}`, '');
+        try {
+          this.persistExternalIdMap();
+        } catch (persist) {
+          console.error(`[module:${this.moduleName}] the external id of a write that may be stored could not be persisted:`, persist);
+        }
+      }
+      throw error;
+    }
 
-    // Track external ID if provided. A write the framework holds keeps '',
-    // as it did before held writes had handles: the map is module state an
-    // earlier release reads back, and a handle is no id to it.
-    // findMessageByExternalId finds the held write by its external id.
+    // Track external ID if provided: the stored id the write was given
+    // (#291 stores every write at once), or '' for one kept in memory (a
+    // surgery's hold, or the wait for its agent's recovery), as earlier
+    // releases kept '' for a write they held.
+    // findMessageByExternalId finds such a write by its external id once it
+    // is stored.
     if (metadata?.external) {
       const key = `${metadata.external.source}:${metadata.external.id}`;
-      this.externalIdMap.set(key, heldWriteId(id) === undefined ? id : '');
+      this.externalIdMap.set(key, id);
       // Persist the mapping
       this.persistExternalIdMap();
     }
@@ -991,15 +1047,16 @@ class ModuleContextImpl implements ModuleContext {
     if (entry === undefined) return null;
     // A stored id answers while the store holds its row, and once the row is
     // gone the entry goes, as removeMessage drops it, except from a context
-    // whose module has stopped, which keeps its mapping as it was. The '' a held
-    // write keeps here (addMessage) names no row, so the message is looked up in
-    // the store by its external id, held rows included, and the first row found
-    // is taken, as context-manager's findByExternalId takes it: a held row
-    // answers by its handle and leaves the entry as it is, and a stored row's id
-    // becomes the entry. With nothing found, '' stays, as earlier releases kept
-    // it: in a module's start(), the writes the last process held don't show
-    // yet, since create() restores them after the modules start, and a write
-    // that shows later finds its entry.
+    // whose module has stopped, which keeps its mapping as it was. A '' here
+    // names no row: a write kept in memory (a surgery's hold, or the wait for
+    // its agent's recovery), or one an earlier release held, whose map it
+    // persisted with ''. So the message is looked up in the store by its
+    // external id, and the first row found is taken, as context-manager's
+    // findByExternalId takes it, and its id becomes the entry (but in a
+    // stopped module's context). With nothing found, '' stays: in a module's
+    // start(), a write an earlier release left queued isn't stored yet, since
+    // create() imports those after the modules start, and a write that shows
+    // later finds its entry.
     if (entry !== '') {
       if (this.getMessageFn(entry)) return entry;
       if (!this.retired) {
@@ -1009,7 +1066,6 @@ class ModuleContextImpl implements ModuleContext {
       return null;
     }
     const row = this.queryMessagesFn({ source, externalIds: [externalId] }).messages[0];
-    if (row?.held) return row.id;
     if (!row) return null;
     if (!this.retired) {
       this.externalIdMap.set(key, row.id);