@animalabs/agent-framework 0.23.2 → 0.24.0

package/src/mcpl/conversation-router.ts

@@ -16,10 +16,10 @@
  * - Everything else is left unrouted and dropped by the framework — the
  *   trunk is a dormant template, not a listener.
  *
- * Bindings expire after an idle TTL. Expiry runs a final closure turn on the
- * fork (see framework wiring) and unbinds; the next qualifying message on
- * that channel spawns a *fresh* fork (generation + 1) from the current
- * trunk, so handbook/template updates propagate between engagements.
+ * Bindings expire after an idle TTL. Expiry unbinds the channel and runs a
+ * final closure turn on the fork (see framework wiring); the next qualifying
+ * message on that channel spawns a *fresh* fork (generation + 1) from the
+ * current trunk, so handbook/template updates propagate between engagements.
  *
  * The binding table is in-memory — bindings are re-established by the next
  * qualifying message after a restart. The generation counters, by contrast,
@@ -264,8 +264,10 @@ export class ConversationRouter {
     return Array.from(this.bindings.values());
   }
 
-  /** Bindings whose idle TTL has elapsed. Does not unbind — the framework
-   * runs the closure turn first, then calls unbind(). */
+  /** Bindings whose idle TTL has elapsed. Does not unbind: the framework
+   * unbinds each one first, so the channel's next message goes to a newer
+   * fork, or nowhere, and then runs the old fork's closure turn
+   * (sweepExpiredConversations). */
   expired(now = Date.now()): ConversationBinding[] {
     const ttl = this.idleTtlMs;
     return this.getBindings().filter((b) => now - b.lastActivity >= ttl);
@@ -301,7 +303,10 @@ export class ConversationRouter {
     return Object.fromEntries(this.generations);
   }
 
-  /** Restore persisted engagement counters (see exportGenerations). */
+  /** Raise each channel's engagement counter to at least the given
+   * generation, never lowering one: the persisted counters at startup (see
+   * exportGenerations), or a spawn's generation whose fork ended before the
+   * spawn could bind it. */
   hydrateGenerations(generations: Record<string, number>): void {
     for (const [channelId, generation] of Object.entries(generations)) {
       if (typeof generation === 'number' && generation > (this.generations.get(channelId) ?? 0)) {

package/src/mcpl/convert-block.ts

@@ -43,9 +43,12 @@ export function convertBlock(block: McplContentBlock, provenance: string, server
         // closed, withhold the data (checked BEFORE the data branch).
         return { type: 'text', text: INLINE_WITHHELD_TEXT };
       }
-      if (isFilledString(block.uri) && block.disposition) {
+      if (isFilledString(block.uri) && block.disposition !== undefined) {
         // RFC-005 uri-form media with a disposition claim: stub, do not
-        // hand the URI to the provider or inline it.
+        // hand the URI to the provider or inline it. Any disposition given
+        // is a claim, one the reference rejects included, as classifyBlock
+        // and isInlineContradiction read it: a falsy one such as 0, false
+        // or '' stubs too, rather than sending the URI as the image's source.
         return { type: 'text', text: referenceStubOrNull(block, provenance, serverId) ?? '[reference]' };
       }
       if (isFilledString(block.data) && isFilledString(block.mimeType)) {
@@ -68,9 +71,10 @@ export function convertBlock(block: McplContentBlock, provenance: string, server
         // closed, withhold the data (checked BEFORE the data branch).
         return { type: 'text', text: INLINE_WITHHELD_TEXT };
       }
-      if (isFilledString(block.uri) && block.disposition) {
-        // RFC-005 uri-form media with a disposition claim: stub, do not
-        // hand the URI to the provider or inline it.
+      if (isFilledString(block.uri) && block.disposition !== undefined) {
+        // RFC-005 uri-form media with a disposition claim, a falsy one
+        // included, as for an image (above): stub, do not hand the URI to
+        // the provider or inline it.
         return { type: 'text', text: referenceStubOrNull(block, provenance, serverId) ?? '[reference]' };
       }
       if (isFilledString(block.data) && isFilledString(block.mimeType)) {

package/src/mcpl/inbound-source.ts

@@ -21,6 +21,8 @@
  * key: `eventId` is present only when the producer supplied one.
  */
 
+import { createHash } from 'node:crypto';
+
 /** The MCPL admission lane that accepted an item. Its contract decides what
  *  an `eventId` is worth: `push/event` deduplicates by eventId, and RFC-006
  *  coalesced admission (`coalesced: true`) guarantees stable retries and
@@ -154,3 +156,132 @@ export function conversationKey(source: InboundSource): string | undefined {
   if (source.kind === 'surface') return JSON.stringify(['surface', source.surface]);
   return undefined;
 }
+
+/**
+ * JSON with object keys sorted at every level, written as the store's append
+ * keeps a value (its native UTF-8 write, which the real-store digest table
+ * checks): an `undefined` object entry is dropped; a string is well-formed
+ * (each lone surrogate comes back as U+FFFD); and an entry whose key isn't
+ * well-formed is dropped (the store doesn't keep it). An `undefined` array
+ * element is written as `null`, as JSON writes it: the store's append
+ * refuses a body holding one, so no stored copy does. So a value
+ * hashes alike however its keys were ordered (content read back from the
+ * store has them in a different order than it was written), and alike
+ * before and after the store. editMessage writes JSON instead, so an edited
+ * copy can keep what an append wouldn't; it has changed anyway.
+ *
+ * It expects JSON-shaped values, as the MCPL lanes deliver them (parsed from
+ * JSON). Any other object is written by its own enumerable entries, unlike
+ * JSON.stringify: a Date becomes `{}`, as the store's own write keeps it, but
+ * a deferred write recovered from its JSON file brings it back as a string.
+ *
+ * sourceBodyDigest's serializer, kept out of the package API: serialization
+ * and framing both stay inside sourceBodyDigest, so consumers don't
+ * duplicate either (`canonicalJson(blocks)` alone hashes differently).
+ */
+export function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([k, v]) => v !== undefined && k.isWellFormed())
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+  }
+  if (typeof value === 'string') return JSON.stringify(value.toWellFormed());
+  return JSON.stringify(value) ?? 'null';
+}
+
+/**
+ * A block as the store hands it back. Context-manager keeps inline media as
+ * blobs (blob-manager.ts): an image whose source isn't a URL, and every
+ * document, audio or video block, comes back as `{ type, source: { type:
+ * 'base64', data, mediaType } }` and nothing else, its data re-encoded from
+ * the decoded bytes, and an image's media type taken from its bytes'
+ * signature where they have one. Any other block comes back as it was given,
+ * except a store-internal `blob_ref` from an unresolved read, which resolves
+ * to inline media by default. It is digested as given here, so an unresolved
+ * read and its resolved form differ. Context-manager refuses caller-supplied
+ * blob_ref writes; the MCPL lanes never store one.
+ */
+function storedBlock(block: unknown): unknown {
+  const media = block as { type?: unknown; source?: { type?: unknown; data?: unknown; mediaType?: unknown } } | null;
+  const blob = media?.type === 'image'
+    ? media.source?.type !== 'url'
+    : media?.type === 'document' || media?.type === 'audio' || media?.type === 'video';
+  const source = media?.source;
+  if (!blob || typeof source?.data !== 'string') return block;
+  const data = canonicalBase64(source.data);
+  const mediaType = media!.type === 'image'
+    ? sniffRasterImageMediaType(Buffer.from(data.slice(0, 32), 'base64')) ?? source.mediaType
+    : source.mediaType;
+  return { type: media!.type, source: { type: 'base64', data, mediaType } };
+}
+
+/**
+ * Base64 as the store writes it back from the decoded bytes: padded, with no
+ * whitespace, the standard alphabet and zero unused bits. Data already in
+ * that form, as every stored copy's is, is returned without decoding it all.
+ */
+function canonicalBase64(data: string): string {
+  if (data.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(data)) {
+    const last = data.slice(-4);
+    if (Buffer.from(last, 'base64').toString('base64') === last) return data;
+  }
+  return Buffer.from(data, 'base64').toString('base64');
+}
+
+/**
+ * The store's own test for raster image types with an unambiguous byte
+ * signature, copied from context-manager's blob-manager.ts (it isn't
+ * exported): the store relabels an image whose bytes match one of these.
+ */
+function sniffRasterImageMediaType(bytes: Uint8Array): string | null {
+  if (bytes.length >= 8 &&
+      bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47 &&
+      bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a) {
+    return 'image/png';
+  }
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+    return 'image/jpeg';
+  }
+  if (bytes.length >= 6) {
+    const signature = Buffer.from(bytes.subarray(0, 6)).toString('ascii');
+    if (signature === 'GIF87a' || signature === 'GIF89a') return 'image/gif';
+  }
+  if (bytes.length >= 12 &&
+      Buffer.from(bytes.subarray(0, 4)).toString('ascii') === 'RIFF' &&
+      Buffer.from(bytes.subarray(8, 12)).toString('ascii') === 'WEBP') {
+    return 'image/webp';
+  }
+  return null;
+}
+
+/**
+ * The version identity of a delivered body (agreed with the receipts lane,
+ * room-220 #46752–#47210): SHA-256 hex of `canonicalJson([blocks])` over the
+ * ContentBlock[] the framework stores for the body — after MCPL conversion,
+ * before any host decoration is added and before storage shards it — with
+ * each block as the store keeps it (storedBlock, canonicalJson). So a body
+ * hashes alike as delivered, as handed to storage, and as read back from
+ * the store. The one-element array keeps the framing an undecorated,
+ * unsharded stored copy has always hashed to, so a stamped copy and an
+ * older copy of the same body share a version.
+ *
+ * Ingestion stamps it as `metadata.sourceBodyDigest`, and the same function
+ * over exactly the blocks handed to storage (decorations included) as
+ * `metadata.storedBodyDigest`, on both MCPL lanes. Both live outside the
+ * frozen admission envelope: they describe the body actually delivered (a
+ * materialization, a correction), not the admission. Neither proves later
+ * presence or completeness; an unsharded stored copy that no longer hashes
+ * to its storedBodyDigest was changed after delivery (editMessage keeps
+ * metadata). A body the store shards carries the whole body's two digests
+ * on every shard, and no shard hashes to them. Check a copy read back with
+ * its blobs resolved (getAllMessages, getMessage, or getMessageWindow
+ * without `resolveBlobs: false`): a blob reference never matches.
+ *
+ * Exported from the package root, so a consumer checks a copy against either
+ * field with this same function rather than a copy of it.
+ */
+export function sourceBodyDigest(blocks: readonly unknown[]): string {
+  return createHash('sha256').update(canonicalJson([blocks.map(storedBlock)])).digest('hex');
+}

package/src/mcpl/index.ts

@@ -171,9 +171,11 @@ export { InferenceRouter } from './inference-router.js';
 
 // Channel registry (channel lifecycle, incoming messages, synthesized tools)
 export { ChannelRegistry } from './channel-registry.js';
+export type { PublishRefusalReason } from './channel-registry.js';
 
-// Inbound source envelope: where each accepted item came from, stamped once
-export { INBOUND_SOURCE_KEY, readInboundSource, conversationKey } from './inbound-source.js';
+// Inbound source envelope: where each accepted item came from, stamped once;
+// and the digest of a delivered or stored body
+export { INBOUND_SOURCE_KEY, readInboundSource, conversationKey, sourceBodyDigest } from './inbound-source.js';
 export type {
   InboundSource,
   InboundChannelSource,

package/src/mcpl/log-value.ts

@@ -55,6 +55,15 @@ export function logValueRedacted(value: unknown, redact: (text: string) => strin
   return printed(redact(textOf(value)), FIELD);
 }
 
+/**
+ * A JSON-RPC error answer's code as a log line prints it: a number, as
+ * JSON-RPC says a code is, as logValue prints it; any other JSON value a
+ * server sends there redacted (logValueRedacted), since the server wrote it.
+ */
+export function loggedCode(code: unknown, redact: (text: string) => string): string {
+  return typeof code === 'number' ? logValue(code) : logValueRedacted(code, redact);
+}
+
 /**
  * The host's own message, as the free text that ends a log line after its
  * fields: `reason=coalesce-invalid field=payload.content: "content must be an