@animalabs/agent-framework 0.32.0 → 0.33.0

package/src/api/mcp-server-core.ts

@@ -14,6 +14,8 @@
 import WebSocket from 'ws';
 import { escapeLineSeparators, readLines } from '../line-reader.js';
 import type { ApiRequest, ApiResponse, ApiEvent } from './types.js';
+import { jsonKind, readEnvelope } from '../jsonrpc-envelope.js';
+import { logValue } from '../mcpl/log-value.js';
 
 // ============================================================================
 // MCP Protocol Types
@@ -21,7 +23,8 @@ import type { ApiRequest, ApiResponse, ApiEvent } from './types.js';
 
 interface JsonRpcRequest {
   jsonrpc: '2.0';
-  id: string | number;
+  /** null is allowed, though JSON-RPC 2.0 discourages it. */
+  id: string | number | null;
   method: string;
   params?: unknown;
 }
@@ -184,20 +187,58 @@ export class McpServer {
   }
 
   private handleInput(line: string): void {
+    let message: unknown;
     try {
-      const message = JSON.parse(line);
-      
-      // Check if this is a notification (no id) or a request (has id)
-      if (!('id' in message) || message.id === undefined) {
-        // This is a notification - handle silently without response
-        // Common notifications: notifications/initialized, notifications/cancelled
-        return;
-      }
-      
-      // This is a request - process and respond
-      this.handleRequest(message as JsonRpcRequest);
+      message = JSON.parse(line);
     } catch {
       this.sendError(null, -32700, 'Parse error');
+      return;
+    }
+    // A request is an object (JSON-RPC 2.0 §4), so any other JSON value is an
+    // invalid request, answered with id null (§5). An array is JSON-RPC's
+    // batch, which this server doesn't take.
+    if (Array.isArray(message)) {
+      this.sendError(null, -32600, "Invalid Request: this server doesn't accept batches, so send each message on a line of its own");
+      return;
+    }
+    if (message === null || typeof message !== 'object') {
+      this.sendError(null, -32600, `Invalid Request: a message must be an object, not ${jsonKind(message)}`);
+      return;
+    }
+
+    // The envelope is read once, here (src/jsonrpc-envelope.ts says how).
+    const envelope = readEnvelope(message as Record<string, unknown>);
+    switch (envelope.kind) {
+      case 'request':
+        void this.handleRequest(message as JsonRpcRequest);
+        return;
+      case 'invalid':
+        this.sendError(envelope.id, envelope.error.code, envelope.error.message);
+        return;
+      case 'response': {
+        // This server sends its client no requests, so a response can't be
+        // matched to one, and it's never answered. A client that couldn't
+        // read a line this server sent, whatever it was, may answer it with
+        // id null, or under MCP with no id. The error member, if it has one,
+        // is printed through logValue, which escapes and bounds the client's
+        // text, and so is the id when it's a string or a number; any other
+        // id is named by its kind.
+        const { id, error } = message as { id?: unknown; error?: unknown };
+        const which = !Object.hasOwn(message as object, 'id') ? 'with no id'
+          : `whose id is ${typeof id === 'string' || typeof id === 'number' ? logValue(id) : jsonKind(id)}`;
+        console.error(`[agent-framework-mcp] ignored a response ${which}, since this server sends no requests` +
+          (error !== undefined ? `; its error: ${logValue(error)}` : ''));
+        return;
+      }
+      case 'notification':
+        // notifications/initialized, notifications/cancelled and the like
+        // need no answer.
+        return;
+      case 'neither':
+        // Not a Request object, which needs a method, nor a response: an
+        // invalid request, as a value that isn't an object is.
+        this.sendError(null, -32600, 'Invalid Request: a message needs a method or an id');
+        return;
     }
   }
 
@@ -217,10 +258,6 @@ export class McpServer {
           });
           break;
 
-        case 'initialized':
-          // Client acknowledgment, no response needed
-          break;
-
         case 'tools/list':
           this.sendResult(request.id, { tools: this.getTools() });
           break;
@@ -635,7 +672,7 @@ export class McpServer {
     });
   }
 
-  private sendResult(id: string | number, result: unknown): void {
+  private sendResult(id: string | number | null, result: unknown): void {
     const response: JsonRpcResponse = {
       jsonrpc: '2.0',
       id,

package/src/api/server.ts

@@ -11,7 +11,7 @@ import { createServer, IncomingMessage, ServerResponse } from 'node:http';
 import { timingSafeEqual } from 'node:crypto';
 import type { ContentBlock } from '@animalabs/membrane';
 import type { AgentFramework } from '../framework.js';
-import { QuiesceBlockedError, ResumeBlockedError } from '../framework.js';
+import { ResumeBlockedError } from '../framework.js';
 import { isReleaseModel } from '../provider-waits.js';
 import type { TraceEvent, ProcessEvent } from '../types/index.js';
 import type {
@@ -601,12 +601,14 @@ export class ApiServer {
     // during a live turn or once stop() has begun, and stop() waits for one
     // already running. It moves the store once any maintenance already
     // running has finished, so the move can come after this call returns.
+    // It writes the switch to the operator log as a checkout over this
+    // surface.
     // The event names this switch's own move, from the branch read here to
     // the one it was asked for: another switch can move the store again
     // before this one continues.
     let switched = false;
     try {
-      await this.framework.switchBranch(params.name);
+      await this.framework.switchBranch(params.name, { requester: { via: 'api' } });
       switched = true;
     } finally {
       // A later step can fail after the store has moved: clients still hear
@@ -655,15 +657,6 @@ export class ApiServer {
 
     const { settled, ...result } = this.framework.undoLastTurn(params.agentName);
     await settled;
-
-    if (result.undone) {
-      this.broadcast('branch:switched', {
-        from: result.fromBranch,
-        to: result.toBranch,
-        reason: 'undo',
-      });
-    }
-
     return result;
   }
 
@@ -674,15 +667,6 @@ export class ApiServer {
 
     const { settled, ...result } = this.framework.redo(params.agentName);
     await settled;
-
-    if (result.redone) {
-      this.broadcast('branch:switched', {
-        from: result.fromBranch,
-        to: result.toBranch,
-        reason: 'redo',
-      });
-    }
-
     return result;
   }
 
@@ -1080,9 +1064,6 @@ export class ApiServer {
               verdicts: error.verdicts,
               hostMode: this.framework.getHostModeStatus(),
             });
-          } else if (error instanceof QuiesceBlockedError) {
-            // A refusal, as resume()'s is: the host's mode is as it was.
-            respond(409, { error: error.message, hostMode: this.framework.getHostModeStatus() });
           } else {
             respond(500, { error: error instanceof Error ? error.message : String(error) });
           }

package/src/code-execution/isolate/scripts.ts

@@ -29,6 +29,7 @@
 import { NOTICE_TAG } from '../../notice-tags.js';
 import { ChildCapacity, ScriptRun, type CallAnswer, type Ending, type ScriptRunOptions, type ToolAnswer } from './runner.js';
 import type { CallSummary } from './calls.js';
+import type { ReadMark } from '../../read-marks.js';
 import type { OutputBounds, OutputWindow } from './output.js';
 import type { PreludeTool } from './prelude.js';
 import { glimpse } from './render.js';
@@ -51,7 +52,7 @@ export interface ScriptCallContext {
   /** The turn the script's run call was made in, when one was: the turn its words were written in, which a later turn's wait doesn't change. */
   startTurnId?: number;
   /** What its agent had read when the run call started the script (the host's consumed watermark), given at run: what the script's words were written having read, which a later round's wait doesn't change. */
-  startReadThrough?: { branch: string; sequence: number } | null;
+  startReadThrough?: ReadMark | null;
 }
 
 export interface ScriptsHost {
@@ -119,7 +120,7 @@ interface Script {
   /** The code it runs. */
   code: string;
   run: ScriptRun;
-  context: { origin?: unknown; startReadThrough?: { branch: string; sequence: number } | null };
+  context: { origin?: unknown; startReadThrough?: ReadMark | null };
   /** The turn its run call was made in, when one was: its agent's turns end it by that. */
   turnId: number | undefined;
   startedAt: number;
@@ -182,7 +183,7 @@ export class AgentScripts {
     agentName: string,
     code: string,
     askedMs?: number,
-    options: { origin?: unknown; watch?: ScriptWatch; startReadThrough?: { branch: string; sequence: number } | null } = {},
+    options: { origin?: unknown; watch?: ScriptWatch; startReadThrough?: ReadMark | null } = {},
   ): Promise<ScriptReturn> {
     // Listed first, so a module whose tool list throws refuses the run with nothing taken.
     let tools: readonly PreludeTool[];
@@ -361,6 +362,30 @@ export class AgentScripts {
     return [...this.scripts.values()].filter((s) => s.agentName === agentName && !s.gone && !s.run.ended).length;
   }
 
+  /**
+   * The marks this agent's running scripts started with (their
+   * `startReadThrough`), which each one's sends are credited with having
+   * read: a redo on the agent's window gives them again, as it gives the
+   * agent's own (Agent.heldReadMarks), over the rows it puts back.
+   */
+  readMarksOf(agentName: string): ReadMark[] {
+    const marks: ReadMark[] = [];
+    for (const s of this.scripts.values()) {
+      const mark = s.context.startReadThrough;
+      if (mark && s.agentName === agentName && !s.gone && !s.run.ended) marks.push(mark);
+    }
+    return marks;
+  }
+
+  /** Put each mark `replacements` maps in place of the start mark of this agent's scripts that hold it (readMarksOf), as Agent.replaceReadMarks does the agent's own: their later calls carry it. */
+  replaceReadMarks(agentName: string, replacements: ReadonlyMap<ReadMark, ReadMark>): void {
+    for (const s of this.scripts.values()) {
+      const mark = s.context.startReadThrough;
+      const next = mark && s.agentName === agentName ? replacements.get(mark) : undefined;
+      if (next) s.context.startReadThrough = next;
+    }
+  }
+
   /** Running scripts that no call is watching: those acting outside any turn. */
   leftRunning(): number {
     return [...this.scripts.values()].filter((s) => !s.run.ended && s.watch === null).length;

package/src/config-checks.ts

@@ -34,6 +34,20 @@ export function assertBooleanSetting(setting: string, value: unknown, whatItDoes
   throw new Error(`${setting} must be ${wanted} not ${kindOf(value)}: ${whatItDoes}`);
 }
 
+/**
+ * Refuse a setting that holds anything but one of `allowed`. null counts as
+ * not set, as leaving it out does. `whatEachDoes` ends the refusal: what each
+ * value does, and what leaving it out does. A string that isn't one of them is
+ * named as another string, never quoted.
+ */
+export function assertOneOfSetting(setting: string, value: unknown, allowed: readonly string[], whatEachDoes: string): void {
+  if (value === undefined || value === null || (typeof value === 'string' && allowed.includes(value))) return;
+  const choices = allowed.map((a) => `'${a}'`);
+  const wanted = choices.length === 1 ? choices[0] : `${choices.slice(0, -1).join(', ')} or ${choices.at(-1)}`;
+  const kind = typeof value === 'string' ? 'another string' : kindOf(value);
+  throw new Error(`${setting} must be ${wanted}, not ${kind}: ${whatEachDoes}`);
+}
+
 /**
  * Whether a settings object holds settings to check: false when it's null,
  * false or left out, which count as not set. Each of those has every setting

package/src/context-manager-errors.ts

@@ -0,0 +1,37 @@
+/**
+ * context-manager's write-outcome errors, read so that this package still
+ * loads on a context-manager that has neither.
+ *
+ * WriteLandedError and WriteOutcomeUnknownError are 0.25.0's: 0.24.0 has
+ * neither. This package is ESM, and a named import of a name its module
+ * doesn't export is a SyntaxError when the module graph is linked, so a
+ * named import of either would fail the package's load on 0.24.0 before
+ * create() could say which context-manager it needs (it refuses one
+ * without a window index, naming ^0.25.0). A namespace import reads an
+ * absent name as undefined, and a stand-in takes its place: a class
+ * nothing throws, so an `instanceof` against it is false, as it is for
+ * every error that release throws.
+ *
+ * Import these two from here, not from '@animalabs/context-manager'
+ * (test/presentation-mandatory.test.ts scans for that).
+ */
+import * as contextManager from '@animalabs/context-manager';
+
+type Exports = typeof contextManager;
+const exported: Partial<Pick<Exports, 'WriteLandedError' | 'WriteOutcomeUnknownError'>> = contextManager;
+
+/** A stand-in for a class the installed context-manager lacks. */
+function absent<C>(name: string): C {
+  return class extends Error {
+    constructor() {
+      super(`${name} isn't in the installed @animalabs/context-manager`);
+      this.name = name;
+    }
+  } as unknown as C;
+}
+
+export const WriteLandedError: Exports['WriteLandedError'] = exported.WriteLandedError ?? absent('WriteLandedError');
+export type WriteLandedError = contextManager.WriteLandedError;
+export const WriteOutcomeUnknownError: Exports['WriteOutcomeUnknownError'] =
+  exported.WriteOutcomeUnknownError ?? absent('WriteOutcomeUnknownError');
+export type WriteOutcomeUnknownError = contextManager.WriteOutcomeUnknownError;

package/src/context-options.ts

@@ -0,0 +1,96 @@
+/**
+ * How the framework opens a resident's context and the persistent
+ * subconscious's (#291, AF-5): which slot each reads, and what its view
+ * leaves out. The framework opens its live agents with these, and opens an
+ * ended one's context again with the same view (reopenAgentContext). A host
+ * that opens one of these contexts itself, to audit a store say, opens it
+ * with them too, so what it reads is what the agent's compiles read (the
+ * requests then send other agents' rounds as a transcript, `foreignRounds`,
+ * which `transcribeForeignRounds` applies to what the context reads):
+ * `ContextManager.open({ store, ...subconsciousContextOptions({ serves,
+ * name, reAnchorFraction, maxMessageTokens }) })`, with `serves` the
+ * primary's name, `name` and `reAnchorFraction` the host's
+ * `subconscious.name` and `subconscious.reAnchorFraction`, and
+ * `maxMessageTokens` the primary's `strategy.maxMessageTokens`, which the
+ * framework mirrors.
+ *
+ * - A resident reads the residents' shared slot (no `isolate`), its context
+ *   state under `agents/<name>`. Its view leaves out what a tune-out holds
+ *   (heldFromResidents), what a suppress rule hid (suppressedRow), and the
+ *   other residents' stored context injections (isAnotherAgentsInjection):
+ *   their context, which they share the slot with it but never its
+ *   conversation.
+ * - The subconscious keeps its rows in a slot of its own,
+ *   `subconscious/<serves>`, and reads the residents' slot beside it
+ *   (`auxiliaryMessageViews: [{}]`), held traffic included, which is what it
+ *   reads for. With the presentation index the residents' rows enter its
+ *   window by its observe edge's rule, and the merged slot is still the
+ *   record its window is presented from. Its view leaves out only the
+ *   residents' stored context injections and what a suppress rule hid,
+ *   which renders for no reader, this one included. Its strategy is a windowed
+ *   passthrough, anchored at the oldest active tune-out's start, or at an
+ *   earlier start kept in force: a cancelled tune-out's, kept while another
+ *   stays active and across a restart, until the next enter sets the oldest
+ *   active one's (window-anchor.ts).
+ *
+ * Each call returns a new object and, for the subconscious, a new strategy:
+ * a strategy keeps state for the manager it is opened with.
+ */
+import { WindowedPassthroughStrategy, type ContextManagerConfig, type StoredMessage } from '@animalabs/context-manager';
+import { heldFromResidents, suppressedRow } from './dendrite/audience.js';
+import { persistentReaderName } from './tune-out/tools.js';
+import { isAnotherAgentsInjection } from './stored-injections.js';
+
+/** ContextManager.open's options over a store the caller gives: everything but the store. */
+export type ContextManagerOpenOptions = Omit<Extract<ContextManagerConfig, { store: unknown }>, 'store'>;
+
+/** What a resident's view leaves out: held traffic, suppressed rows, and another agent's stored context injections. */
+export function residentViewFilter(name: string): (message: StoredMessage) => boolean {
+  return (message) => !heldFromResidents(message.metadata as Record<string, unknown> | undefined)
+    && !suppressedRow(message.metadata as Record<string, unknown> | undefined)
+    && !isAnotherAgentsInjection(message.metadata, name);
+}
+
+/** What the subconscious's view leaves out: the residents' stored context injections and suppressed rows, and nothing it reads for. */
+export function subconsciousViewFilter(name: string): (message: StoredMessage) => boolean {
+  return (message) => !suppressedRow(message.metadata as Record<string, unknown> | undefined)
+    && !isAnotherAgentsInjection(message.metadata, name);
+}
+
+/** The options a resident named `agentName` is opened with: the residents' slot, through its view. The caller gives its strategy. */
+export function residentContextOptions(agentName: string): ContextManagerOpenOptions {
+  return {
+    namespace: `agents/${agentName}`,
+    viewFilter: residentViewFilter(agentName),
+  };
+}
+
+/**
+ * The options the persistent subconscious serving `serves` is opened with:
+ * its own slot, the residents' merged beside it, its view, and a new
+ * windowed passthrough strategy with `reAnchorFraction` and
+ * `maxMessageTokens` (the framework mirrors the primary's). `name` is the
+ * name the subconscious runs under, its configuration's `name`, which the
+ * host gives it: pass that. Left out, it is the name the framework runs a
+ * reader the host didn't name under (persistentReaderName), so a host that
+ * left its reader unnamed opens the view the live one reads; this export
+ * doesn't choose a name of its own.
+ */
+export function subconsciousContextOptions(options: {
+  serves: string;
+  name?: string;
+  reAnchorFraction?: number;
+  maxMessageTokens?: number;
+}): ContextManagerOpenOptions {
+  const name = persistentReaderName(options);
+  return {
+    namespace: `subconscious/${options.serves}`,
+    isolate: true,
+    auxiliaryMessageViews: [{}],
+    viewFilter: subconsciousViewFilter(name),
+    strategy: new WindowedPassthroughStrategy({
+      reAnchorFraction: options.reAnchorFraction,
+      maxMessageTokens: options.maxMessageTokens,
+    }),
+  };
+}

package/src/deferred-import.ts

@@ -0,0 +1,239 @@
+/**
+ * The deferred-write queue an earlier release left on disk, read once at
+ * boot (#291, AF-6).
+ *
+ * Releases before #291's presentation index held a context write in a queue
+ * while its agent's turn was alive or the host was quiesced, and stored it
+ * at that agent's next boundary. While quiesced, and from a write that
+ * reached or may have reached its record until the queue drained, the queue
+ * was mirrored to `recovery/deferred-writes.json` beside the store, or, with
+ * no recovery path, to the store's `framework/deferred-writes` slot. This
+ * release stores every write at once and keeps no queue, so a record such a
+ * release left is read here, and the framework stores each of its writes
+ * once at boot (AgentFramework.importPersistedDeferredWrites), passes on or
+ * drops, logged, a write for an agent gone or one refused as malformed,
+ * keeps for the next boot one it can't store or check, with what follows it
+ * for that agent, and rewrites the record with only those. Like that
+ * importer, this module is for one release: the release
+ * after it deletes both. A host boots this release until its record is
+ * empty (the `deferred-import` alert says when writes stay queued), and
+ * doesn't upgrade past it from a release that kept a queue.
+ *
+ * Nothing here touches a store. It reads the record's value, refuses one
+ * that isn't a queue, drops entries its readers can't handle, keeps one entry
+ * per id, and orders them as they arrived.
+ */
+import { randomUUID } from 'node:crypto';
+import type { ContentBlock } from '@animalabs/membrane';
+import type { MessageMetadata } from '@animalabs/context-manager';
+
+/** One write an earlier release queued, as its record held it. */
+export interface PersistedDeferredWrite {
+  /** Its durable identity: a copy of it that landed carries it as `metadata.deferredWriteId`. */
+  id: string;
+  /** Where it came in arrival order, 1..N over the entries kept. */
+  seq: number;
+  participant: string;
+  content: ContentBlock[];
+  metadata?: MessageMetadata;
+  /** The agent it was for. Absent means the primary. */
+  forAgent?: string;
+  /** When the earlier release first held it, in ms since the epoch, where the record says. */
+  heldAt?: number;
+  /**
+   * Set where a write of it threw and its store couldn't be read to tell
+   * whether it landed: before it is stored, its target's whole branch is
+   * searched for its id.
+   */
+  landing?: 'unknown';
+}
+
+/** What a queue's record held, as the importer takes it. */
+export interface PersistedQueue {
+  /** Its writes, in arrival order. */
+  entries: PersistedDeferredWrite[];
+  /**
+   * Per target agent, where its store stood when the oldest write handed to
+   * it and not yet acknowledged was handed over: the boot dedup scans from
+   * there (0 for an agent not named, the whole store).
+   */
+  scanFrom: Map<string, number>;
+  /**
+   * Whether reading it dropped, renumbered or named anything (a malformed
+   * entry, a repeated id, a missing or invalid seq, an entry given an id),
+   * so a record cleared or written again doesn't name those again.
+   */
+  changed: boolean;
+  /**
+   * The ids this read gave entries that had none. A read gives each a new
+   * one, so until the record holds it, a copy stored under it is one no
+   * later read finds by its id.
+   */
+  given: ReadonlySet<string>;
+}
+
+/** Where a queue's record is: the recovery file, or the store's slot. */
+export interface DeferredWritesRecord {
+  /** The recovery file the value was read from; absent where it was the slot's. */
+  file?: string;
+  /** The store's slot for it (framework/deferred-writes). */
+  slotId: string;
+}
+
+/** A stored JSON value's kind, for a refusal that names what it found without its content. */
+function jsonKind(value: unknown): string {
+  return value === null ? 'null'
+    : Array.isArray(value) ? 'an array'
+      : typeof value === 'object' ? 'an object'
+        : `a ${typeof value}`;
+}
+
+/**
+ * The refusal of a boot whose queue record can't be taken: it could not be
+ * read (`cause`), or it holds something other than a queue (`problem`
+ * alone). Either way the record is left as it is, and the error says what
+ * lets the framework start.
+ */
+export function deferredWritesRefusal(record: DeferredWritesRecord, problem: string, cause?: unknown): Error {
+  const { file, slotId } = record;
+  return new Error(
+    `the deferred context writes (${file ?? slotId}) ${problem}. The framework doesn't start without them: an earlier ` +
+      `version left them queued, and they are stored at boot, ahead of anything written once the modules have ` +
+      `started. ` +
+      (file
+        ? `The file is unchanged, and the framework starts once ${cause === undefined
+          ? 'it holds a queue of writes, such as {"version":1,"pending":[]} for none. Removing it reads the queue ' +
+            `from ${slotId} instead, which the file's writes don't keep, so it imports whatever older ` +
+            `queue is there, or none`
+          : 'it can be read'}.`
+        : cause === undefined
+          ? `They're unchanged, and starting again won't help until they're repaired.`
+          : `They're unchanged, and the framework starts once they can be read.`),
+    cause === undefined ? undefined : { cause },
+  );
+}
+
+/**
+ * Read a queue record's value: the recovery file's document, or the slot's
+ * value where there is no file (`record.file` absent).
+ *
+ * - Nothing stored is an empty queue: no file and nothing in the slot. A file
+ *   that holds null isn't a queue, since no release writes one.
+ * - The forms releases wrote are read: a bare array (the slot's first form),
+ *   and `{ pending, scanFrom? }` (version 1 and 2 files, version 2 slots).
+ *   Anything else is refused (deferredWritesRefusal).
+ * - An entry the importer can't store is dropped with a line naming it: one
+ *   whose participant isn't text, whose content isn't an array, that holds a
+ *   block that isn't an object, or whose `forAgent` is present but not a
+ *   name. A release wrote `forAgent` only as a non-empty name, so another
+ *   value is damage or a hand edit, and the agent it meant can't be known.
+ * - One entry per id: an id that comes again is dropped with a line, the
+ *   first entry with it kept. An entry with no id is given one, with a line
+ *   (`given`, and the queue reads as `changed`): a copy of it that landed
+ *   carries the id it lost, so the boot dedup can't find it, and it may be
+ *   stored again. Each read gives it a new id, so the importer writes the
+ *   record with the ids given before it stores any of them.
+ * - `heldAt` is kept where it is a time a Date can hold.
+ * - Arrival order: entries whose seq is a positive whole number up to
+ *   Number.MAX_SAFE_INTEGER by seq, then, in record order, those without one
+ *   (a record from before seq, in write order already) or with another value,
+ *   which is named. They are numbered 1..N in that order.
+ */
+export function readPersistedDeferredWrites(
+  raw: unknown,
+  record: DeferredWritesRecord,
+  log: (line: string) => void,
+): PersistedQueue {
+  const empty: PersistedQueue = { entries: [], scanFrom: new Map(), changed: false, given: new Set() };
+  if (!record.file && (raw === null || raw === undefined)) return empty;
+  const doc = (Array.isArray(raw) ? { pending: raw } : raw !== null && typeof raw === 'object' ? raw : undefined) as
+    { pending?: unknown; scanFrom?: unknown } | undefined;
+  if (!doc || !Array.isArray(doc.pending)) {
+    throw deferredWritesRefusal(record, doc
+      ? `hold an object whose pending is ${doc.pending === undefined ? 'missing' : jsonKind(doc.pending)}, not a list of writes`
+      : `hold ${jsonKind(raw)}, not a queue of writes`);
+  }
+  const data = doc.pending as unknown[];
+  if (data.length === 0) return empty;
+  const scanFrom = new Map<string, number>();
+  if (doc.scanFrom && typeof doc.scanFrom === 'object') {
+    for (const [k, v] of Object.entries(doc.scanFrom as Record<string, unknown>)) {
+      if (typeof v === 'number' && Number.isFinite(v)) scanFrom.set(k, Math.max(0, Math.floor(v)));
+    }
+  }
+  type Read = { participant: string; content: ContentBlock[]; metadata?: MessageMetadata; forAgent?: string; id?: unknown; seq?: unknown; heldAt?: unknown; landing?: unknown };
+  const wellFormed = (m: unknown): m is Read => {
+    if (!m || typeof m !== 'object') return false;
+    const { participant, content, forAgent } = m as { participant?: unknown; content?: unknown; forAgent?: unknown };
+    return typeof participant === 'string'
+      && Array.isArray(content) && content.every((b) => !!b && typeof b === 'object')
+      && (forAgent === undefined || (typeof forAgent === 'string' && forAgent !== ''));
+  };
+  const malformed = data.filter((m) => !wellFormed(m));
+  for (const m of malformed) {
+    // What the entry holds there: a value that isn't text by its type.
+    const field = (key: string): string => {
+      const value = m && typeof m === 'object' ? (m as Record<string, unknown>)[key] : undefined;
+      if (typeof value === 'string') return value;
+      if (value === undefined) return `no ${key}`;
+      return `${key} ${value === null ? 'null' : `of type ${typeof value}`}`;
+    };
+    log(`[host-mode] a recovered deferred context write is malformed and was dropped: ${field('id')} (${field('participant')})`);
+  }
+  const seen = new Set<string>();
+  const given = new Set<string>();
+  const kept: Array<Omit<PersistedDeferredWrite, 'seq'> & { seq?: unknown }> = [];
+  let duplicates = 0;
+  for (const m of data.filter(wellFormed)) {
+    const hasId = typeof m.id === 'string' && m.id !== '';
+    const id = hasId ? (m.id as string) : randomUUID();
+    if (!hasId) {
+      given.add(id);
+      log(`[host-mode] a recovered deferred context write (${m.participant}) has no id; it is given ${id}`);
+    }
+    if (seen.has(id)) {
+      duplicates++;
+      log(`[host-mode] a recovered deferred context write repeats id ${id} (${m.participant}) and was dropped; the first entry with that id is kept`);
+      continue;
+    }
+    seen.add(id);
+    kept.push({
+      id,
+      seq: m.seq,
+      participant: m.participant,
+      content: m.content,
+      ...(m.metadata !== undefined ? { metadata: m.metadata } : {}),
+      ...(m.forAgent !== undefined ? { forAgent: m.forAgent } : {}),
+      // A Date holds times within 8.64e15 ms of the epoch.
+      ...(typeof m.heldAt === 'number' && Math.abs(m.heldAt) <= 8.64e15 ? { heldAt: m.heldAt } : {}),
+      ...(m.landing === 'unknown' ? { landing: 'unknown' as const } : {}),
+    });
+  }
+  const validSeq = (seq: unknown): seq is number => Number.isSafeInteger(seq) && (seq as number) > 0;
+  const unnumbered = kept.filter((m) => !validSeq(m.seq));
+  for (const m of unnumbered) {
+    if (m.seq === undefined) continue;
+    // A value that isn't a number is named by its type: it could be any size.
+    const seq = typeof m.seq === 'number' ? String(m.seq) : m.seq === null ? 'null' : `of type ${typeof m.seq}`;
+    log(
+      `[host-mode] a recovered deferred context write (${m.id}) has seq ${seq}, not a positive ` +
+        `whole number up to Number.MAX_SAFE_INTEGER; it is queued after the others`,
+    );
+  }
+  const ordered = [...kept.filter((m) => validSeq(m.seq)).sort((a, b) => (a.seq as number) - (b.seq as number)), ...unnumbered];
+  return {
+    entries: ordered.map((m, i) => ({ ...m, seq: i + 1 })),
+    scanFrom,
+    changed: malformed.length > 0 || duplicates > 0 || unnumbered.length > 0 || given.size > 0,
+    given,
+  };
+}
+
+/**
+ * Whether an entry holds a tool block (tool_use or tool_result): of what a
+ * release queued, only the puppet's pair, which was the agent's own round,
+ * queued behind a turn that had replaced the puppet's reservation.
+ */
+export function isToolBlockEntry(entry: Pick<PersistedDeferredWrite, 'content'>): boolean {
+  return entry.content.some((block) => block.type === 'tool_use' || block.type === 'tool_result');
+}