@animalabs/agent-framework 0.21.1 → 0.22.1

package/src/tool-result-guard.ts

@@ -1,13 +1,115 @@
 import { randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
-import type { ContextManager, MessageId } from '@animalabs/context-manager';
+import type { ContextManager, MessageId, MessageMetadata } from '@animalabs/context-manager';
 import type { ContentBlock, NormalizedMessage, ToolResult } from '@animalabs/membrane';
 import type { CompletedToolCall } from './types/index.js';
 import { isStateExistsError } from './module-registry.js';
+import { toolResultDataToHistoryString } from './tool-result-history.js';
+import { safeSlice } from './safe-slice.js';
 
 export const TOOL_RESULT_GUARD_NOTICE = 'Tool result withheld by the guard. The tool has already executed.';
 export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
 
+/** Where a withheld result's original went: a workspace path; the path a
+ *  write to it failed at (`error`); the path a write was still under way to
+ *  when the host stopped waiting for it (`unfinished`); no write, because the
+ *  workspace isn't answering (`workspace_unanswered`: an earlier write is
+ *  still under way past the host's deadline) or because the workspace had
+ *  left the stub's branch when the file would have been committed
+ *  (`branch_changed`), or because the batch used its deadline before this
+ *  write could start (`batch_deadline`); or null when no file is written at all (no writable
+ *  workspace, or the host is stopping). */
+export type WithheldSpill =
+  | { path: string; error?: string; unfinished?: true }
+  | { skipped: 'workspace_unanswered' | 'branch_changed' | 'batch_deadline' }
+  | null;
+
+/**
+ * Writes one withheld original as a workspace file, using what remains of
+ * the batch's absolute deadline. A write still running then is unfinished.
+ * Once a write reaches that deadline, later spills are workspace_unanswered
+ * until all overdue writes settle. Other batches can start before that gate
+ * closes. An exhausted batch starts no write (batch_deadline).
+ * The tree entry lands on branch or the write is declined (branch_changed).
+ * The mount's disk directory is shared across branches.
+ */
+export type WithheldSpiller = (label: string, text: string, branch: string, deadline: number) => Promise<WithheldSpill>;
+
+/** What a host gives a guard for its withheld results: where originals are
+ *  written, where each annotation is registered, so the host's stop can
+ *  wait for it even after the agent itself was disposed, and where the
+ *  guard says whether it has work left. */
+export interface WithheldHost {
+  spill: WithheldSpiller;
+  /** Absolute deadline for one batch (Date.now() time), taken when the batch is queued. */
+  deadline(): number;
+  track(annotation: Promise<void>): void;
+  /** Whether the guard is idle (see ToolResultGuard.idle), told after each
+   *  change that can alter it: when an annotation starts or ends, and after
+   *  each pass over the storage queue. A host keeps a guard that isn't idle
+   *  within reach for retries, whatever has become of its agent, and lets
+   *  an idle one go. */
+  idle(idle: boolean): void;
+}
+
+/**
+ * The stub a withheld result settles to: #159's neutral notice, then where
+ * the original is, then, when its tool marked any, the fields kept from its
+ * result (`kept`, from keptWhenWithheld). It names no refusal and no
+ * category (#159 keeps those in operational logs), so reading the rest back
+ * is the agent's deliberate choice (agent-framework #277). The place holds
+ * the result as stored, which for one over the inline cap is its capped
+ * text, whose own note names the file with the whole output; so the stub
+ * says "its result", not its full result. A failed write's own error text
+ * stays in the audit record and the logs, not here. The audit record is
+ * said to keep the original only when it was saved: a staged record whose
+ * save failed is still queued in memory, and a restart before its retry
+ * loses it.
+ */
+export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean, kept?: string): string {
+  const audit = `the guard's audit record (${TOOL_RESULT_GUARD_AUDIT_STATE}), for an operator`;
+  const keptIn = (only: string) => auditDurable
+    ? `is kept ${only}in ${audit}`
+    : `went ${only}to ${audit}, though saving that record had failed when the result arrived`;
+  const place = !spill || 'skipped' in spill
+    ? `Its result ${keptIn('')}.`
+    : spill.unfinished
+      ? `Its result was still being written to workspace file ${spill.path} when this note was made; ` +
+        `if that file is missing, it ${keptIn('')}.`
+      : spill.error === undefined
+        ? `Its result is in workspace file ${spill.path}.`
+        : `Writing its result to workspace file ${spill.path} failed, so it ${keptIn('only ')}.`;
+  const fields = kept === undefined ? '' : ` Kept from its result: ${kept}`;
+  return `${TOOL_RESULT_GUARD_NOTICE} ${place}${fields}`;
+}
+
+/**
+ * What a withheld result's stub keeps of it: the fields of its data that its
+ * tool marked as saying what it acted on (ToolResult.keepWhenWithheld), in
+ * the order marked, serialized as a stored result is. Past the inline cap
+ * they're cut, with a note that says so and where the whole result is, since
+ * a later field can then be cut away entirely. Undefined when it keeps
+ * nothing, as for a failed result (agent-framework #277). A write's file
+ * list is evidence of what it did, rarely what drew a refusal, and keeping it
+ * is what shows a clobbered file when the receipt is withheld.
+ */
+export function keptWhenWithheld(result: CompletedToolCall['result'], maxChars: number | undefined): string | undefined {
+  const { data, keepWhenWithheld: keys } = result;
+  if (!result.success || result.isError || !keys?.length || !data || typeof data !== 'object' || Array.isArray(data)) {
+    return undefined;
+  }
+  const fields = data as Record<string, unknown>;
+  const kept = Object.fromEntries(keys.filter((key) => Object.hasOwn(fields, key)).map((key) => [key, fields[key]]));
+  if (Object.keys(kept).length === 0) return undefined;
+  const whole = toolResultDataToHistoryString(kept);
+  if (!maxChars || whole.length <= maxChars) return whole;
+  // Never half a surrogate pair: the stub goes to the provider as text, so
+  // the cut can be one character short of the cap.
+  const head = safeSlice(whole, 0, maxChars);
+  return `${head} [cut at the inline cap: ${head.length} of these fields' ${whole.length} ` +
+    'characters; the whole result is where this note says]';
+}
+
 interface PendingBatch {
   id: string;
   messageId: MessageId;
@@ -18,6 +120,9 @@ interface PendingBatch {
   submitted: boolean;
   /** False when the audit sync failed: originals then never go on the wire. */
   durable: boolean;
+  /** What each result's stub keeps if the batch is withheld, by its index in
+   *  content: the fields its tool marked (keptWhenWithheld). */
+  kept: Map<number, string>;
 }
 
 interface AuditOperation {
@@ -43,6 +148,13 @@ export class ToolResultGuard {
   private override: boolean | undefined;
   /** True until a recovery produces a clean response/new tool round. */
   recovering = false;
+  /** Writes withheld originals where the agent can read them; without it,
+   *  a stub names only the audit record. */
+  private host: WithheldHost | undefined;
+  /** Annotations of withheld stubs, chained in settlement order. */
+  private annotating: Promise<void> | undefined;
+  /** Annotations started so far, so a read can tell one began during it. */
+  private annotationsStarted = 0;
 
   constructor(
     private readonly agentName: string,
@@ -51,6 +163,51 @@ export class ToolResultGuard {
   ) {}
 
   get enabled(): boolean { return this.override ?? this.configured; }
+  setHost(host: WithheldHost | undefined): void { this.host = host; }
+  /** Settles once every annotation started so far has finished: each of
+   *  those stubs has been edited to say where its original is, or its edit
+   *  failed and waits in the storage queue, retried in order until it lands
+   *  or an operator's change supersedes it (until then the stub is the bare
+   *  notice, kept out of summaries by its compression hold, and the audit
+   *  record names the place). It never rejects. Each batch has one deadline
+   *  for all its workspace writes; queued batches are annotated in order.
+   *  A request may carry an unfinished-write notice once that deadline passes. */
+  whenAnnotated(): Promise<void> { return this.annotating ?? Promise.resolve(); }
+
+  /**
+   * Runs `read` (a compile of the context) once no withheld stub is still
+   * being annotated, and again if an annotation began while it ran, since a
+   * settlement can land during the compile's own awaits, such as a previous
+   * frame's teardown abandoning its batch. The framework's sent-request
+   * compiles go through it: the agent's activations, its direct
+   * API calls and their refusal retry, and a conversation fork's seed from its
+   * template. A request preview doesn't, so it never waits on a
+   * workspace write.
+   *
+   * Before `read`, a stub edit that failed gets another try with the rest of
+   * the storage queue; a store that is still failing then compiles the bare
+   * notice, which its hold keeps out of summaries.
+   */
+  async afterAnnotations<T>(read: () => Promise<T>): Promise<T> {
+    for (;;) {
+      // Counted before the wait, so an annotation that starts while this one
+      // is awaited is waited for too.
+      const started = this.annotationsStarted;
+      await this.whenAnnotated();
+      if (this.annotationsStarted !== started) continue;
+      try {
+        this.flushUnrecorded();
+      } catch (error) {
+        console.error(`[tool-result-guard] agent=${this.agentName} storage retry before a compile failed:`, error);
+      }
+      const result = await read();
+      if (this.annotationsStarted === started) return result;
+    }
+  }
+
+  /** No annotation is running and no storage work is queued: nothing of this
+   *  guard is left for a host to wait on or retry. */
+  get idle(): boolean { return this.annotating === undefined && this.unrecorded.length === 0; }
   setOverride(value: boolean | undefined): void { this.override = value; }
   get settingOverride(): boolean | undefined { return this.override; }
   get hasPending(): boolean { return this.pending !== undefined; }
@@ -81,39 +238,52 @@ export class ToolResultGuard {
 
   /** Ordered storage work, separate from batches awaiting a provider verdict.
    * A failed acceptance edit retains both the payload and its compression
-   * hold here; it can never re-arm refusal handling or tool submission. */
+   * hold here; it can never re-arm refusal handling or tool submission.
+   * Any failed head, including an audit-only record, blocks later queued
+   * edits and their holds until that operation succeeds. */
   private unrecorded: AuditOperation[] = [];
 
-  /** Retry edits and audit writes before a new activation, audit write,
-   * maintenance pass, or shutdown. A failed operation stays at the head. */
+  /** Retry edits and audit writes before a new activation, a compile of a
+   * request that is sent (afterAnnotations), an audit write, a maintenance
+   * pass, or shutdown. A failed operation stays at the head. */
   flushUnrecorded(): void {
-    while (this.unrecorded.length > 0) {
-      const operation = this.unrecorded[0];
-      try {
-        if (operation.admission) {
-          const { messageId, content, expected, branch } = operation.admission;
-          const sameBranch = this.cm.currentBranch().name === branch;
-          const current = sameBranch ? this.cm.getMessage(messageId) : null;
-          // A retry must not undo an operator's later edit/removal/rollback.
-          // Reapplying our own payload is safe if an earlier edit wrote the
-          // message and then failed while propagating to context entries.
-          // Chronicle normalizes object-key order and drops undefined fields.
-          if (!sameBranch || !current ||
-            (!isDeepStrictEqual(current.content, JSON.parse(JSON.stringify(expected)))
-              && !isDeepStrictEqual(current.content, JSON.parse(JSON.stringify(content))))) {
-            operation.record.historyUpdate = 'superseded';
-          } else {
-            this.cm.editMessage(messageId, content);
-          }
-          // An audit-only retry must not repeat an edit that already succeeded.
-          operation.admission = undefined;
+    try {
+      while (this.unrecorded.length > 0) {
+        const operation = this.unrecorded[0];
+        try {
+          this.applyEdit(operation);
+          this.write(operation.record);
+          this.unrecorded.shift();
+        } finally {
+          if (!operation.admission) this.releaseOperationHold(operation);
         }
-        this.write(operation.record);
-        this.unrecorded.shift();
-      } finally {
-        if (!operation.admission) this.releaseOperationHold(operation);
       }
+    } finally {
+      this.host?.idle(this.idle);
+    }
+  }
+
+  /** Make an operation's history edit, if it still has one: once it is made,
+   *  or superseded by an operator's change, only its record is left to
+   *  write, and its hold can go. */
+  private applyEdit(operation: AuditOperation): void {
+    if (!operation.admission) return;
+    const { messageId, content, expected, branch } = operation.admission;
+    const sameBranch = this.cm.currentBranch().name === branch;
+    const current = sameBranch ? this.cm.getMessage(messageId) : null;
+    // A retry must not undo an operator's later edit/removal/rollback.
+    // Reapplying our own payload is safe if an earlier edit wrote the
+    // message and then failed while propagating to context entries.
+    // Chronicle normalizes object-key order and drops undefined fields.
+    if (!sameBranch || !current ||
+      (!isDeepStrictEqual(current.content, JSON.parse(JSON.stringify(expected)))
+        && !isDeepStrictEqual(current.content, JSON.parse(JSON.stringify(content))))) {
+      operation.record.historyUpdate = 'superseded';
+    } else {
+      this.cm.editMessage(messageId, content);
     }
+    // An audit-only retry must not repeat an edit that already succeeded.
+    operation.admission = undefined;
   }
 
   private append(record: Record<string, unknown>): void {
@@ -144,8 +314,17 @@ export class ToolResultGuard {
       : JSON.parse(json);
   }
 
-  storeResults(content: ContentBlock[], wireResults: ToolResult[], originals: CompletedToolCall[]): MessageId {
-    if (!this.enabled) return this.cm.addMessage('user', content);
+  /** `inlineCap` is the cap the caller stored `content` under; what a stub
+   *  keeps of a withheld result is cut at it too. */
+  storeResults(
+    content: ContentBlock[],
+    wireResults: ToolResult[],
+    originals: CompletedToolCall[],
+    metadata: MessageMetadata | undefined,
+    /** The cap the results were stored under: what a stub keeps is cut there too. */
+    inlineCap: number | undefined,
+  ): MessageId {
+    if (!this.enabled) return this.cm.addMessage('user', content, metadata);
     if (this.pending) {
       // Idempotent for the same not-yet-submitted batch: a caller that
       // retries after a failure between staging and submission (e.g. a
@@ -171,13 +350,22 @@ export class ToolResultGuard {
     const withheld: ContentBlock[] = content.map((block) => block.type === 'tool_result'
       ? { type: 'tool_result', toolUseId: block.toolUseId, content: TOOL_RESULT_GUARD_NOTICE, isError: block.isError }
       : block);
+    // What each stub keeps if the batch is withheld, matched to its tool's
+    // result by tool use id, keyed by index as the stubs and files are.
+    const results = new Map(originals.map((call) => [call.id, call.result]));
+    const kept = new Map<number, string>();
+    for (const [index, block] of content.entries()) {
+      const result = block.type === 'tool_result' ? results.get(block.toolUseId) : undefined;
+      const text = result ? keptWhenWithheld(result, inlineCap) : undefined;
+      if (text !== undefined) kept.set(index, text);
+    }
     // Compression hold (CM >= 0.12): placed BEFORE onNewMessage fires, so no
     // chunk is ever summarized from the placeholder; released after the
     // settlement edit. Holds are in-memory only — a reopened manager has none,
     // which is correct since a reopened guard has no pending batch.
-    const messageId = this.cm.addMessage('user', withheld, undefined, undefined, { holdCompression: true });
+    const messageId = this.cm.addMessage('user', withheld, metadata, undefined, { holdCompression: true });
     this.pending = { id, messageId, content, withheld, wireResults,
-      branch: this.cm.currentBranch().name, submitted: false, durable: false };
+      branch: this.cm.currentBranch().name, submitted: false, durable: false, kept };
     // Durability barrier: the audit must reach Chronicle's chain heads before
     // the originals can go to a provider. On a failed sync the batch fails
     // CLOSED: the placeholders go on the wire instead (the turn continues,
@@ -285,7 +473,9 @@ export class ToolResultGuard {
 
   /** Transfer ownership from provider admission to an ordered storage job.
    * Failure retains the accepted payload and its hold until the edit succeeds.
-   * Withheld content is final already, so audit failures cannot keep it held. */
+   * A withheld batch's hold passes to its annotation instead, and from there
+   * to its stub's edit, so no summary is made of a stub that doesn't yet say
+   * where its original went. */
   private settle(pending: PendingBatch, record: Record<string, unknown>, admit: boolean): void {
     this.pending = undefined;
     const operation: AuditOperation = {
@@ -293,8 +483,9 @@ export class ToolResultGuard {
         batchId: pending.id, messageId: pending.messageId, sourceBranch: pending.branch },
       ...(admit ? { admission: { messageId: pending.messageId, content: pending.content,
         expected: pending.withheld, branch: pending.branch } } : {}),
-      heldMessageId: pending.messageId,
+      heldMessageId: admit ? pending.messageId : undefined,
     };
+    if (!admit) this.annotate(pending);
     this.unrecorded.push(operation);
     try {
       this.flushUnrecorded();
@@ -305,6 +496,165 @@ export class ToolResultGuard {
     }
   }
 
+  /**
+   * Turn a withheld batch's notices into stubs that say where each original
+   * is (agent-framework #277): written to the workspace when a writable mount
+   * takes it, else kept in the audit record. A stub also keeps the file
+   * lists its tool marked. Its own unedited placeholder is
+   * the only thing it edits: an operator's later edit, removal or rollback
+   * stands.
+   *
+   * Where each original went is queued first, on its own ('annotated'), so
+   * a stub edit that fails can't take the record of a written file with it.
+   * The edit is then made at once, so no storage work queued ahead of it
+   * holds it, not even that record if its write is failing, and its record
+   * ('stub_updated') is written in order after the others. An
+   * edit that fails joins the ordered storage queue like an admission's, with
+   * the batch's compression hold: retried before the next activation, compile,
+   * maintenance pass or stop until it lands or an operator's change supersedes
+   * it. Until then the stub is the bare notice, which the hold keeps out of
+   * summaries, and the audit record names the file.
+   */
+  private annotate(pending: PendingBatch): void {
+    const previous = this.annotating ?? Promise.resolve();
+    this.annotationsStarted += 1;
+    // The batch's deadline runs from when it's queued, not from when the
+    // batches ahead of it finish, so a request waiting on a chain of batches
+    // waits at most one deadline past the latest one's arrival.
+    let deadline = Infinity;
+    try { deadline = this.host?.deadline() ?? Infinity; } catch { /* the spill then takes its own deadline, rather than losing the record */ }
+    const run = previous.then(async () => {
+      // Set once the stub's edit is queued with the hold: the queue releases
+      // it when the edit lands or is superseded.
+      let holdQueued = false;
+      try {
+        const date = new Date().toISOString().slice(0, 10);
+        // A file is named by its batch and its place in the batch, ahead of
+        // anything the writer may cut or substitute: results of one batch
+        // never share a file, and results of two batches share one only if 48
+        // random bits of their batch ids agree. The tool use id after them is
+        // for whoever lists the directory.
+        const batch = pending.id.replace(/-/g, '').slice(0, 12);
+        // Keyed by the result's index in the batch, which the stub and the
+        // original share.
+        const spills = new Map<number, WithheldSpill>();
+        // A spill that threw, by index: its error, for the record.
+        const thrown = new Map<number, string>();
+        // Set once the branch has changed: no more is written.
+        let branchLeft = false;
+        let deadlineSpent = false;
+        for (const [index, block] of pending.content.entries()) {
+          if (block.type !== 'tool_result') continue;
+          // Once the store has left the batch's branch (a rollback, an undo, a
+          // host's switch), write no more. This result and every later one is
+          // skipped, and its original stays in the audit record. Nothing
+          // yields from here to the edit's own branch check, so while the
+          // store is away the stub stays as it is. A write already under way
+          // when the branch changes is refused before its tree entry is set,
+          // since it names the batch's branch. Once set, that entry stays on
+          // its branch; its disk copy uses the mount's shared directory.
+          if (branchLeft || this.cm.currentBranch().name !== pending.branch) {
+            branchLeft = true;
+            spills.set(index, { skipped: 'branch_changed' });
+            continue;
+          }
+          // The result as stored. Both paths that store a tool result store
+          // its text; content stored as blocks would be written as their JSON.
+          const original = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
+          let spill: WithheldSpill = null;
+          if (this.host) {
+            try {
+              spill = await this.host.spill(`${date}-withheld-${batch}-${index}-${block.toolUseId}`, original, pending.branch, deadline);
+            } catch (error) {
+              // The host reports a failed write rather than throwing; a throw
+              // is recorded all the same, without a path.
+              thrown.set(index, (error instanceof Error ? error.message : String(error)).slice(0, 200));
+              console.error(`[tool-result-guard] agent=${this.agentName} could not spill withheld result ` +
+                `${block.toolUseId}:`, error);
+            }
+          }
+          // Declined where it would have committed, since the workspace had
+          // left the batch's branch. Nothing was written, and no more are, as
+          // for the results the branch check above stops. If the branch is
+          // back by the edit, as after an undo and a redo, the stubs of this
+          // result and the later ones name the audit record.
+          if (spill && 'skipped' in spill && spill.skipped === 'branch_changed') branchLeft = true;
+          // A batch that used its deadline is said once, here, where the
+          // batch is known; the host returns the skip without a line.
+          if (spill && 'skipped' in spill && spill.skipped === 'batch_deadline' && !deadlineSpent) {
+            deadlineSpent = true;
+            console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} used its deadline before all its originals were written; the rest name the audit record (batch_deadline)`);
+          }
+          spills.set(index, spill);
+        }
+        const annotated: ContentBlock[] = pending.withheld.map((block, index) => block.type === 'tool_result'
+          ? { ...block, content: withheldResultNotice(spills.get(index) ?? null, pending.durable, pending.kept.get(index)) }
+          : block);
+        try {
+          this.append({
+            type: 'annotated', batchId: pending.id, messageId: pending.messageId, sourceBranch: pending.branch,
+            results: pending.content.flatMap((block, index): Array<Record<string, string | true>> => {
+              if (block.type !== 'tool_result') return [];
+              if (thrown.has(index)) return [{ toolUseId: block.toolUseId, error: thrown.get(index)! }];
+              const spill = spills.get(index) ?? null;
+              // No file was written: no writable workspace, or the framework
+              // was stopping.
+              if (spill === null) return [{ toolUseId: block.toolUseId, skipped: 'no_workspace_file' }];
+              if ('skipped' in spill) return [{ toolUseId: block.toolUseId, skipped: spill.skipped }];
+              return [{ toolUseId: block.toolUseId, path: spill.path,
+                ...(spill.error !== undefined ? { error: spill.error } : {}),
+                ...(spill.unfinished ? { unfinished: true as const } : {}) }];
+            }),
+          });
+        } catch (error) {
+          // It stays queued and is retried in order with the storage work
+          // ahead of it; the stub's record is written after it.
+          console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} annotation record queued for retry:`, error);
+        }
+        const stub: AuditOperation = {
+          record: { agentName: this.agentName, timestamp: Date.now(), type: 'stub_updated',
+            batchId: pending.id, messageId: pending.messageId, sourceBranch: pending.branch },
+          admission: { messageId: pending.messageId, content: annotated, expected: pending.withheld, branch: pending.branch },
+          heldMessageId: pending.messageId,
+        };
+        try {
+          this.applyEdit(stub);
+        } catch (error) {
+          console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} stub edit queued for retry:`, error);
+        }
+        this.unrecorded.push(stub);
+        holdQueued = true;
+        try {
+          // A made edit's hold goes now, whatever storage work is still
+          // queued ahead of its record.
+          if (!stub.admission) this.releaseOperationHold(stub);
+          this.flushUnrecorded();
+        } catch (error) {
+          console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} stub's storage work queued for retry:`, error);
+        }
+      } catch (error) {
+        console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} could not annotate withheld results:`, error);
+      } finally {
+        // Never rejects: a compile and stop() wait on this chain. With no
+        // stub edit queued, nothing else holds the batch.
+        if (!holdQueued) {
+          try {
+            this.releaseHold(pending.messageId);
+          } catch (error) {
+            console.error(`[tool-result-guard] agent=${this.agentName} could not release a withheld batch's hold:`, error);
+          }
+        }
+      }
+    });
+    this.annotating = run;
+    void run.finally(() => {
+      if (this.annotating === run) this.annotating = undefined;
+      this.host?.idle(this.idle);
+    });
+    this.host?.track(run);
+    this.host?.idle(false);
+  }
+
   private releaseOperationHold(operation: AuditOperation): void {
     if (operation.heldMessageId !== undefined) {
       this.releaseHold(operation.heldMessageId);

package/src/tool-result-history.ts

@@ -52,10 +52,34 @@ export function toolResultDataToHistoryString(
   options?: HistorySerializeOptions,
 ): string {
   const fromArray = tryHistoryStringFromContentArray(data, options);
-  const str = fromArray ?? JSON.stringify(data);
+  // JSON leaves out undefined, a function and a symbol: a result with no data
+  // is stored as no text, as an empty content array is.
+  const str = fromArray ?? (JSON.stringify(data) as string | undefined) ?? '';
   return maxChars ? truncateForHistory(str, maxChars) : str;
 }
 
+/**
+ * The text of a tool result that isn't an error result: its data, as history
+ * stores it, or, when it has no data, its error text. A tool can answer
+ * `{ success: false, error, isError: false }`, a failure it doesn't flag as
+ * an error for the model, and the model still reads what failed.
+ *
+ * Each field is read once: the direct Agent API passes its caller's own
+ * result here, unchecked, and a getter needn't answer the same way twice.
+ */
+export function nonErrorResultText(
+  result: { data?: unknown; error?: string },
+  maxChars?: number,
+  options?: HistorySerializeOptions,
+): string {
+  const data = result.data;
+  if (data === undefined || data === null) {
+    const error = result.error;
+    if (typeof error === 'string' && error) return maxChars ? truncateForHistory(error, maxChars) : error;
+  }
+  return toolResultDataToHistoryString(data, maxChars, options);
+}
+
 /** Bounded copy of an arbitrary string with the standard truncation notice.
  *  Image slots past the cut are re-appended, never dropped (issue #104). */
 export function truncateForHistory(str: string, maxChars: number): string {

package/src/types/agent.ts

@@ -1,6 +1,7 @@
 import type { ContentBlock, YieldingStream } from '@animalabs/membrane';
 import type { ContextStrategy } from '@animalabs/context-manager';
 import type { ToolCallId, ToolResult, ToolCall } from './events.js';
+import type { SilentHeartbeatTick } from '../silent-heartbeat.js';
 
 export type SameRoundThinkTextPolicy = 'public' | 'private';
 export type SameRoundThinkTextPolicySource =
@@ -12,6 +13,7 @@ export type SameRoundThinkTextPolicySource =
  * Configuration for an agent.
  */
 export interface AgentConfig {
+  toolPresentation?: import("../tool-presentation.js").ToolPresentationConfig;
   /** Unique name for this agent */
   name: string;
 
@@ -305,6 +307,14 @@ export interface InferenceRequest {
   /** Host-owned identity for withdrawal of an unconsumed coalesced wake. */
   coalescingSubject?: string;
   coalescingEventId?: string;
+  /** Host-owned: this wake's cause is an RFC-006 deferred batch, which has
+   *  no model-visible content until it renders at the turn's assembly. */
+  coalescingBatch?: boolean;
+  /** Host-owned, set on a turn's trigger when EVERY request batched into it
+   *  was a deferred-batch wake: these are their subjects. If assembly settles
+   *  all of them without materializing content, the turn has no cause left
+   *  and does not run. */
+  coalescingBatchSubjects?: string[];
   agentName: string;
   reason: string;
   source: string;
@@ -339,8 +349,10 @@ export interface InferenceRequest {
    * Where the wake came from, for telemetry ONLY — never a speech locus.
    * Set by the EventGate for batched wakes (composite channel id of the
    * chosen event when the event carried one; push-event raw ids are not
-   * used). Routing keeps reading `channelId`, which only the direct channel
-   * paths set from normalized ids — a gate wake leaves it unset, as before.
+   * used). Routing keeps reading `channelId`, set from registered ids: by
+   * the direct channel paths, and by a gate wake only when its chosen event
+   * addressed the agent and the host resolved that event's registered
+   * channel (ambient-only batches leave it unset).
    */
   wakeChannelId?: string;
   /** Timestamp of the event the wake provenance was taken from (ms). */
@@ -351,4 +363,8 @@ export interface InferenceRequest {
   /** Ephemeral system-position prompt for this turn only. Never written to
    * Chronicle; callers must supply bounded non-secret control text. */
   ephemeralSystemPrompt?: string;
+  /** The authenticated silent heartbeat tick this turn answers. Every row the
+   * turn stores is stamped `metadata.silentHeartbeat` with it, and request
+   * builds render a request-only separator before the tick's first row. */
+  silentHeartbeat?: SilentHeartbeatTick;
 }

package/src/types/events.ts

@@ -92,6 +92,10 @@ export interface ToolResultEvent {
   agentName: string;
   /** Module that handled the call */
   moduleName: string;
+  /** The tool's name, as its call named it. The framework's own
+   *  producers set it, so a result nothing can take any more (one arriving
+   *  after stop()) is still logged by tool. */
+  toolName?: string;
   /** Result of the tool call */
   result: ToolResult;
 }
@@ -195,6 +199,18 @@ export interface ToolResult {
    * Adapted from Anarchid/agent-framework@mcpl-module-proto.
    */
   endTurn?: boolean;
+  /**
+   * Fields of `data` that say what the tool acted on, such as the paths a
+   * write wrote, removed or took from disk, the path it deleted, or a mount
+   * whose root it accepted, in the order they should be kept. When the
+   * tool-result guard withholds this result, these fields stay in its stub,
+   * so the agent still sees what the tool did; the result as stored goes
+   * where every withheld original goes (agent-framework #277). Past the
+   * inline cap they're cut, in this order, so a later field can be cut away
+   * entirely; put the short, telling ones first. Only data's own fields can
+   * be kept, and a failed result (success false) keeps nothing.
+   */
+  keepWhenWithheld?: string[];
 }
 
 /**

package/src/types/framework.ts

@@ -237,6 +237,11 @@ export interface FrameworkConfig {
    * effective class (first matching pattern wins); replaces, never merges
    * with, what the providing server declared. Use it to correct or tighten a
    * misclassed tool.
+   *
+   * MCPL tools are named `<toolPrefix>--<tool>`, and toolPrefix defaults to
+   * `mcpl--<serverId>`: server `search` without a toolPrefix needs
+   * `mcpl--search--*`, not `search--*`. A pattern that matches no tool is
+   * reported once its servers have listed their tools.
    */
   toolClassOverrides?: Record<string, string[]>;
 
@@ -274,6 +279,13 @@ export interface FrameworkConfig {
    * messages route to per-channel fork agents spawned from the template
    * agent instead of the primary conversation. If omitted, behavior is
    * unchanged (all messages go to the primary agent).
+   *
+   * @deprecated Per-channel conversation routing is deprecated and will be
+   * removed (anima-research/agent-framework#235). Its 'mention' bind/trigger
+   * rule reads `metadata.mentioned`, which not every channel server sets
+   * (discord-mcpl does not), so on those channels an @-mention neither binds
+   * a fork nor triggers a bound one. Routing still works for now; the
+   * framework logs one `[deprecated]` line at creation when this is set.
    */
   conversations?: ConversationRouterConfig;
 }