@animalabs/agent-framework 0.26.0 → 0.26.2

package/src/mcpl/channel-registry.ts

@@ -1708,6 +1708,9 @@ export class ChannelRegistry {
     responder?: Responder,
   ): Promise<void> {
     const results: ChannelIncomingMessageResult[] = [];
+    // Set when a coalesced message was admitted but its acknowledgement
+    // failed: the request is then answered with this error (below).
+    let requestError: { code: number; message: string; field?: string } | undefined;
     // The batch came on the transport open now: a close after this point
     // (transportClosed) leaves its traffic nothing to confirm.
     const closesAtArrival = this.transportCloses.get(serverId) ?? 0;
@@ -1919,10 +1922,26 @@ export class ChannelRegistry {
           if (result.accepted) markAccepted(firstView === true);
           results.push(result);
         } catch (error) {
-          const err = error as Error & { code?: number; field?: string };
+          const err = error as Error & { code?: number; field?: string; admitted?: boolean };
           // -32602 is answered coalesce_invalid; anything else as its message,
           // a plain Error standing for an internal error (-32603).
-          this.traceCoalesceRejection(serverId, message, err, typeof err.code === 'number' ? err.code : -32603);
+          const code = typeof err.code === 'number' ? err.code : -32603;
+          this.traceCoalesceRejection(serverId, message, err, code);
+          if (err.admitted && responder?.respondError) {
+            // Admitted, with its effects in: only the acknowledgement failed,
+            // so `accepted: false`, which says the message wasn't admitted,
+            // would be untrue, and a producer would hold it as never
+            // delivered. A per-message result can't say "may have been
+            // admitted" (§14.3); an error for the request is the spec's
+            // answer for that. Nothing after this message is admitted, since
+            // the producer sends the request's messages again: a coalesced
+            // one is answered from its receipt, and an uncoalesced one
+            // before this message is admitted again. (A responder without
+            // respondError, which only an in-process caller passes, gets the
+            // per-message answer below: it can't be told anything else.)
+            requestError = { code, message: err.message, ...(err.field ? { field: err.field } : {}) };
+            break;
+          }
           results.push({
             messageId: message.messageId,
             accepted: false,
@@ -1950,8 +1969,8 @@ export class ChannelRegistry {
       });
     }
 
-    const result: ChannelsIncomingResult = { results };
-    responder?.respond(result);
+    if (requestError) responder!.respondError!(requestError.code, requestError.message, { field: requestError.field });
+    else responder?.respond({ results } satisfies ChannelsIncomingResult);
 
     this.emitTraceFn({
       type: 'mcpl:channels-incoming',

package/src/mcpl/push-coalescer.ts

@@ -32,9 +32,14 @@ export type CoalesceOutcome = typeof COALESCE_OUTCOMES[number];
 class CancelledRender extends Error {}
 
 export class CoalesceError extends Error {
-  constructor(readonly field: string, message: string, readonly code = -32602) {
+  /** Set on a failure that came after the occurrence's effects: it was
+   *  admitted, and only its acknowledgement failed (acknowledge). A lane
+   *  must not answer it as not admitted. */
+  readonly admitted: boolean;
+  constructor(readonly field: string, message: string, readonly code = -32602, options: { admitted?: true } = {}) {
     super(message);
     this.name = 'CoalesceError';
+    this.admitted = options.admitted === true;
   }
 }
 
@@ -210,7 +215,16 @@ interface SubjectState<E> {
   touchedAt: number;
 }
 
-interface ReceiptEntry { result: PushEventResult; at: number; committed: boolean; firstView?: true }
+interface ReceiptEntry {
+  result: PushEventResult;
+  at: number;
+  committed: boolean;
+  firstView?: true;
+  /** Set while the receipt's record isn't written (recordReceipt failed):
+   *  what a rewrite keeps from the admission. The rest of the record is the
+   *  subject's state when it's written. */
+  unwritten?: { subject: string; born?: SubjectState<unknown>['history'] };
+}
 
 export interface CoalescingSnapshot {
   version: 1;
@@ -244,15 +258,18 @@ export interface CoalescingReceiptRecord {
   /** History the subject was created with, for a subject first seen by this receipt. */
   born?: SubjectState<unknown>['history'];
   /** The subject's first view had ended by this acceptance
-   *  (SubjectState.firstViewEnded), so a crash before the snapshot flush
-   *  can't forget the end. A record written before this field existed has
-   *  none and reads as not ended, as a snapshot does. */
+   *  (SubjectState.firstViewEnded), or by the time a retry wrote the record,
+   *  so a crash before the snapshot flush can't forget the end. A record
+   *  written before this field existed has none and reads as not ended, as a
+   *  snapshot does. */
   firstViewEnded?: true;
   /** The subject's pending batch AFTER this acceptance: the accepted work
    *  itself (so a crash before the snapshot flush cannot lose it while keeping
    *  the receipt that suppresses its retry), or `null` when the acceptance
    *  left no batch — a retraction or plain replacement must be recoverable
-   *  too. Records replay in order, so the last one per subject wins. */
+   *  too. Records replay in order, so the last one per subject wins. A
+   *  record a retry writes (its first write failed) takes the batch the
+   *  subject has then, a rendering one included. */
   batch: { latest: CoalescedOccurrence<unknown>; notices: DeferredNotice[]; dropped: number } | null;
 }
 
@@ -298,11 +315,13 @@ export interface CoalescerHost<E> {
    *  be recoverable before the RPC is issued, §3.2). Throws on failure. */
   saveNow?(snapshot: CoalescingSnapshot): void;
   /** Persist one receipt now, before the acceptance is acknowledged. Throws
-   *  on failure, which fails the acceptance (the producer retries). */
+   *  on failure, which fails that answer: the receipt is kept unwritten, and
+   *  the producer's retry writes it again rather than admitting it again. */
   recordReceipt?(record: CoalescingReceiptRecord): void;
   /** One call per ADMITTED occurrence (never for a producer retry the receipt
-   *  deduplicates), after its receipt is recorded. Observation only: a throw
-   *  is contained here and never fails the acceptance. */
+   *  deduplicates), after its effects, whether or not its receipt could be
+   *  written. Observation only: a throw is contained here and never fails the
+   *  acceptance. */
   accepted?(occurrence: CoalescedOccurrence<E>): void;
   /** Make every write so far DURABLE (an fsync; the coalescer requests each
    *  commit under its lock, so no two acceptances share one).
@@ -540,17 +559,27 @@ export class PushCoalescer<E = unknown> {
     return entry;
   }
 
-  /** Acknowledge a receipt: durable first. A receipt whose commit failed is
-   *  committed now (no effects are repeated); if that fails again, so does
-   *  the acknowledgement, and the producer retries once more. */
+  /** Acknowledge a receipt: durable first. A receipt whose record couldn't be
+   *  written is written now, and one whose commit failed is committed now (no
+   *  effects are repeated); if either fails again, so does the
+   *  acknowledgement, and the producer retries once more. */
   private async acknowledge(key: string, entry: ReceiptEntry, subject: string, eventId: string): Promise<PushEventResult> {
+    if (entry.unwritten) {
+      try {
+        this.recordReceipt(key, entry, entry.unwritten);
+      } catch (error) {
+        this.host.audit({ kind: 'persist-failed', subject, eventId, error: String(error) });
+        throw new CoalesceError('eventId', 'host could not persist the acceptance; retry', -32000, { admitted: true });
+      }
+      delete entry.unwritten;
+    }
     if (!entry.committed) {
       try {
         await this.host.commit?.();
         entry.committed = true;
       } catch (error) {
         this.host.audit({ kind: 'persist-failed', subject, eventId, error: String(error) });
-        throw new CoalesceError('eventId', 'host could not make the acceptance durable; retry', -32000);
+        throw new CoalesceError('eventId', 'host could not make the acceptance durable; retry', -32000, { admitted: true });
       }
     }
     return structuredClone(entry.result);
@@ -571,9 +600,11 @@ export class PushCoalescer<E = unknown> {
   }
 
   private async admit(occurrence: CoalescedOccurrence<E>): Promise<PushEventResult> {
-    if (this.suspended) throw new CoalesceError('serverId', 'host is stopping', -32000);
-    const subject = coalescingSubjectKey(occurrence.serverId, occurrence.binding, occurrence.scope, occurrence.key);
     const duplicate = this.receiptEntry(coalescingReceiptKey(occurrence.serverId, occurrence.binding, occurrence.eventId));
+    // A retry of an occurrence admitted before the stop is refused too, but
+    // as one admitted: its effects are in, so no lane may say it wasn't.
+    if (this.suspended) throw new CoalesceError('serverId', 'host is stopping', -32000, duplicate ? { admitted: true } : {});
+    const subject = coalescingSubjectKey(occurrence.serverId, occurrence.binding, occurrence.scope, occurrence.key);
     if (duplicate) {
       // A producer retrying acknowledged work is also a chance to notice a
       // batch left asleep by a failed freeze: wake it now, without effects.
@@ -605,19 +636,18 @@ export class PushCoalescer<E = unknown> {
     state.touchedAt = this.now();
     const result: PushEventResult = { accepted: true, coalesce: { outcome, ...(priorEventId ? { priorEventId } : {}) } };
     const receiptKey = coalescingReceiptKey(occurrence.serverId, occurrence.binding, occurrence.eventId);
-    const entry: ReceiptEntry = { result: structuredClone(result), at: this.now(), committed: false, ...(this.deliveredFirstView ? { firstView: true as const } : {}) };
-    try {
-      this.host.recordReceipt?.({
-        key: receiptKey, result: entry.result, at: entry.at, subject, ...(born ? { born } : {}),
-        ...(state.firstViewEnded ? { firstViewEnded: true as const } : {}),
-        batch: state.batch ? structuredClone({ latest: state.batch.latest as CoalescedOccurrence<unknown>, notices: state.batch.notices, dropped: state.batch.dropped }) : null,
-      });
-    } catch (error) {
-      // Not acknowledged: the work would be lost while its receipt suppressed
-      // a retry. The producer retries within the window.
-      this.host.audit({ kind: 'persist-failed', subject, eventId: occurrence.eventId, error: String(error) });
-      throw new CoalesceError('eventId', 'host could not persist the acceptance; retry', -32000);
-    }
+    // The effects are done, so the receipt is kept whatever its record's
+    // write does: a retry is answered from it, never admitted again (RFC-006
+    // §3.1). Its record is written and made durable before an acknowledgement
+    // (acknowledge), by this answer or a retry's. While this process lives,
+    // the in-memory receipt deduplicates a retry, which writes or commits
+    // what failed. The snapshot carries it too, so a later save and commit
+    // keep it across a restart; a kill before either leaves nothing of it,
+    // and the retry is a fresh acceptance.
+    const entry: ReceiptEntry = {
+      result: structuredClone(result), at: this.now(), committed: false, unwritten: { subject, ...(born ? { born } : {}) },
+      ...(this.deliveredFirstView ? { firstView: true as const } : {}),
+    };
     this.receipts.set(receiptKey, entry);
     try {
       this.host.accepted?.(occurrence);
@@ -626,12 +656,31 @@ export class PushCoalescer<E = unknown> {
     }
     this.prune();
     this.persist();
-    // Written but not yet durable: the in-memory receipt deduplicates a retry
-    // while this process lives, and the retry commits it (acknowledge); after
-    // a kill nothing of it exists and the retry is a fresh acceptance.
     return this.acknowledge(receiptKey, entry, subject, occurrence.eventId);
   }
 
+  /** Write a receipt's record: what the admission fixed (`fixed`), with the
+   *  subject's first-view end and pending batch as they are now. A record
+   *  written by a retry follows any written since its admission, and records
+   *  replay in order, so it carries the batch the subject has now, not the
+   *  one it had then. That includes a batch whose render has started, which
+   *  the render-start snapshot holds too: a `null` would clear it at a
+   *  restore, and a crash before the render's content is stored would lose
+   *  the accepted work. (At an admission no batch is rendering without a
+   *  pending one: a plain occurrence or a retraction cancels the render, and
+   *  a deferred notice opens a batch.) Throws when the host's write does. */
+  private recordReceipt(key: string, entry: ReceiptEntry, fixed: { subject: string; born?: SubjectState<unknown>['history'] }): void {
+    const state = this.subjects.get(fixed.subject);
+    const batch = state?.batch ?? state?.rendering?.batch;
+    this.host.recordReceipt?.({
+      // A birth is the subject's only while the coalescer still holds it: one
+      // evicted since its admission is untracked, `unknown` (prune).
+      key, result: entry.result, at: entry.at, subject: fixed.subject, ...(fixed.born && state ? { born: fixed.born } : {}),
+      ...(state?.firstViewEnded ? { firstViewEnded: true as const } : {}),
+      batch: batch ? structuredClone({ latest: batch.latest as CoalescedOccurrence<unknown>, notices: batch.notices, dropped: batch.dropped }) : null,
+    });
+  }
+
   private subjectFor(subject: string, occurrence: CoalescedOccurrence<E>): SubjectState<E> {
     let state = this.subjects.get(subject);
     if (!state) {
@@ -1193,9 +1242,9 @@ export class PushCoalescer<E = unknown> {
       if (r.batch === undefined) continue; // pre-round-3 record: no batch information
       // The subject's batch AFTER that acceptance, newer than the snapshot:
       // the accepted deferred work itself, or null for a withdrawal /
-      // replacement that cleared it. It never began rendering before the
-      // record was written, but the snapshot cannot say whether it did
-      // afterwards: take the fallback.
+      // replacement that cleared it. Its render may have started before the
+      // record was written (a retry's record) or after, and the snapshot
+      // cannot say whether it ran: take the fallback.
       const state = this.subjects.get(r.subject) ?? { history: 'unknown' as const, touchedAt: now };
       state.batch = r.batch
         ? { latest: r.batch.latest as CoalescedOccurrence<E>, notices: r.batch.notices, dropped: r.batch.dropped, noRender: true }

package/src/mcpl/references.ts

@@ -454,7 +454,9 @@ export function referenceStubOrNull(block: unknown, provenance?: string, serverI
  * RFC-005 treatment for one MCPL wire block, for a script's structured
  * result, which carries blocks rather than text. It makes the decision
  * referenceStubOrNull makes for the model's lanes, since what a script prints
- * comes back to the model. A reference becomes the stub's facts as data,
+ * comes back to the model, except that a script reads every field, so inline
+ * data beside a uri of any type but null or absent is withheld, where the
+ * model's lanes, which show no uri, withhold it beside a string one. A reference becomes the stub's facts as data,
  * without its URI: the host's reference id, what the server said about it in
  * this block (its labels stripped and bounded as in the stub), and `savedTo`,
  * the workspace path its payload was fetched to, or null when it wasn't
@@ -462,18 +464,31 @@ export function referenceStubOrNull(block: unknown, provenance?: string, serverI
  * counts as expired also carries `expired`, the reason the stub gives in
  * place of advising fetch_reference. The reference is registered bound to
  * `serverId`, the server whose tool returned it, as the model's lanes bind
- * a tool result's references, so the fetch its id offers can be made. A
- * block the classifier
+ * a tool result's references, so the fetch its id offers can be made. With
+ * no `serverId`, as for a module's result, it's registered as the model's
+ * history registers a module's: the record its uri already has, bound where
+ * it arrived (a module's ctx.callTool registers an MCPL peer's references),
+ * or a new one bound to no server. A block the classifier
  * rejects becomes the notice the model's lanes show, and inline data that
- * also claims a bulk disposition the withheld notice, each as a text block.
+ * also claims a bulk disposition, or a uri of any type but null or absent
+ * (an empty string included), the withheld notice, each as a text block.
  * A text block, or inline data that claims nothing, is returned as sent.
  */
-export function referenceBlockForScript(block: unknown, serverId: string): unknown {
+export function referenceBlockForScript(block: unknown, serverId?: string): unknown {
   const c = classifyBlock(block);
   switch (c.kind) {
     case 'text': return block;
-    case 'inline':
-      return c.contradiction ? { type: 'text', text: INLINE_WITHHELD_TEXT } : block;
+    case 'inline': {
+      // A script reads every field, as history's JSON writes it, so inline
+      // data beside a uri of any type is withheld here, not only beside a
+      // string one as in the model's lanes, which show no uri: an object can
+      // carry a credential. An absent or null uri carries none; a string one,
+      // an empty one included, is already the classifier's contradiction.
+      const uri = (block as { uri?: unknown }).uri;
+      return c.contradiction || (uri !== undefined && uri !== null)
+        ? { type: 'text', text: INLINE_WITHHELD_TEXT }
+        : block;
+    }
     case 'invalid': return { type: 'text', text: c.shown };
     case 'reference': {
       const t = c.testimony;

package/src/tool-result-history.ts

@@ -19,7 +19,7 @@
  * is withheld.
  */
 
-import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './mcpl/references.js';
+import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceBlockForScript, referenceStubOrNull } from './mcpl/references.js';
 import { NON_STRING_TEXT_PLACEHOLDER } from './mcpl/visible-content.js';
 import { formatToolImagePlaceholder, toolResultCutAt } from './tool-image-ledger.js';
 
@@ -229,14 +229,54 @@ function shownInHistory(value: unknown): unknown {
   const b = value as Record<string, unknown>;
   if (!governedByRfc005(b)) return value;
   if ((b.type === 'image' || b.type === 'audio') && typeof b.data === 'string') {
-    // JSON writes every field, so here inline data beside a uri of any value
+    // JSON writes every field, so here inline data beside a uri of any type
     // is withheld, not only beside a string one as in the lanes, which show
-    // no uri: an object can carry a credential. An empty uri carries none.
+    // no uri: an object can carry a credential. A null, absent or empty uri
+    // carries none (hasUri).
     return hasUri(b.uri) || b.disposition !== undefined ? INLINE_WITHHELD_TEXT : value;
   }
   return referenceStubOrNull(b, 'from tool result') ?? value;
 }
 
+/**
+ * A value of a tool result's data as a script reads it, by history's rules
+ * (shownInHistory), as a JSON replacer applies them at every depth: what
+ * RFC-005 governs is shown as the script lane shows it, a reference as its
+ * stub's facts without its uri and an invalid one as the notice
+ * (referenceBlockForScript), and inline data that also claims a uri of any
+ * type or a disposition as the withheld notice, each as a text block. A
+ * null, absent or empty uri claims none (hasUri), so inline data beside one
+ * is itself. Any
+ * other value is itself. What it gives is either a stub or a notice, which
+ * RFC-005 doesn't govern, or the value itself, which it gives again, so
+ * applying it twice gives what applying it once gave.
+ */
+export function shownToScript(value: unknown): unknown {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
+  const b = value as Record<string, unknown>;
+  if (!governedByRfc005(b)) return value;
+  if ((b.type === 'image' || b.type === 'audio') && typeof b.data === 'string') {
+    return hasUri(b.uri) || b.disposition !== undefined ? { type: 'text', text: INLINE_WITHHELD_TEXT } : value;
+  }
+  return referenceBlockForScript(b);
+}
+
+/**
+ * A value nested in an MCPL peer's content block as a script reads it, as a
+ * JSON replacer applies it inside the blocks: what RFC-005 governs
+ * (governedByRfc005, history's guard, since the classifier would make a
+ * notice of an object that isn't a content block, such as a peer's own
+ * nested data) gets the treatment the script lane gives a
+ * peer's block (referenceBlockForScript), its reference bound to the server
+ * that sent it, and any other value is itself. A stub or a notice isn't
+ * governed, so a block the top-level pass already treated is left as it is.
+ */
+export function shownToScriptFromServer(value: unknown, serverId: string): unknown {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
+  const b = value as Record<string, unknown>;
+  return governedByRfc005(b) ? referenceBlockForScript(b, serverId) : value;
+}
+
 /**
  * The text RFC-005 shows a value of a tool result's data as, when it shows it
  * as text rather than as its fields: a reference's stub, an invalid one's

package/src/types/events.ts

@@ -291,13 +291,18 @@ export interface ToolCall {
    * text answer's envelope, over six: 7,456,527 at the default 128 MiB. On
    * Node, past about 1.5 GiB, the host's longest string bounds it instead.
    * A result with a `structured` value reaches a script as its content's
-   * blocks as they are, beside that value as JSON, and the figure counts
+   * blocks, a module's or an MCPL peer's with RFC-005's treatment of what it
+   * governs (a reference as its stub's facts) and a standard peer's as sent,
+   * beside that value as JSON, and the figure counts
    * neither the value nor what the blocks carry past their text, such as each
    * further block's keys or an image's data, so a tool that returns one
    * leaves room for them; and a result nested past 2,000 levels, or whose parse
    * needs more of the script's memory than is free, doesn't reach the script
    * whatever its length. A result that doesn't reach it is answered
-   * ResultTooLarge, the call having taken effect. Nothing is cut or saved to
+   * ResultTooLarge, the call having taken effect. One the host can't convert
+   * to JSON at all, such as one nested deeper than its runtime's
+   * JSON.stringify can take, is answered instead as a failure naming the
+   * tool and saying the call itself completed. Nothing is cut or saved to
    * a file. A tool that pages or budgets its answer can stay under it. The
    * framework sets it on a model's, a script's and the operator's puppet's
    * call to a module, a utility run through `utils` included. A call