@animalabs/agent-framework 0.23.3 → 0.24.1

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,
@@ -108,10 +108,6 @@ export interface ConversationRouterConfig {
 
 export interface ConversationBinding {
   channelId: string;
-  /** The channel's MCPL server, where the binding was made with one: channel
-   *  ids are unique only within one server's connection (MCPL §14.2), so each
-   *  server's channel has its own binding. */
-  serverId?: string;
   agentName: string;
   /** Engagement counter per channel — fresh forks get a new generation. */
   generation: number;
@@ -161,15 +157,11 @@ export const DEFAULT_CLOSURE_PROMPT =
 export class ConversationRouter {
   private config: ConversationRouterConfig;
 
-  /** Active bindings, keyed by the channel's server and id (bindingKey):
-   *  two servers' channels with one id are two conversations. */
+  /** Active bindings, keyed by channelId. */
   private bindings = new Map<string, ConversationBinding>();
 
-  /** Engagement counter per channel id — survives unbind, so a re-bound
-   * channel gets a distinct fork agent name. Kept by bare id, as it's
-   * persisted: two servers sharing an id share a counter, which still never
-   * repeats a name, and their forks' names differ anyway, since each hashes
-   * its server (forkAgentName). */
+  /** Engagement counter per channel — survives unbind, so a re-bound channel
+   * gets a distinct fork agent name. */
   private generations = new Map<string, number>();
 
   constructor(config: ConversationRouterConfig) {
@@ -199,7 +191,7 @@ export class ConversationRouter {
    * unchanged; a failed spawn doesn't leave a dangling route.
    */
   route(facts: IncomingMessageFacts): RoutingDecision {
-    const existing = this.bindings.get(bindingKey(facts));
+    const existing = this.bindings.get(facts.channelId);
 
     if (existing) {
       return {
@@ -231,57 +223,33 @@ export class ConversationRouter {
    * Record a binding after the framework successfully spawned the fork.
    * Returns the new binding.
    */
-  bind(channel: string | ConversationChannel, agentName: string, generation: number, now = Date.now()): ConversationBinding {
-    const { channelId, serverId } = asChannel(channel);
-    // The counter is kept by bare id, and two servers' spawns on one id can
-    // run beside each other, so a bind can finish after a later spawn's: the
-    // counter keeps the higher, or the next spawn would propose a fork name
-    // already used.
-    this.generations.set(channelId, Math.max(this.generations.get(channelId) ?? 0, generation));
+  bind(channelId: string, agentName: string, generation: number, now = Date.now()): ConversationBinding {
+    this.generations.set(channelId, generation);
     const binding: ConversationBinding = {
       channelId,
-      ...(serverId !== undefined ? { serverId } : {}),
       agentName,
       generation,
       boundAt: now,
       lastActivity: now,
     };
-    this.bindings.set(bindingKey({ channelId, serverId }), binding);
+    this.bindings.set(channelId, binding);
     return binding;
   }
 
   /** Record delivered activity on an existing binding. Does not bind a
    * channel or advance its generation. Call after successful delivery, not
    * when previewing a route. The optional clock supports deterministic use. */
-  touch(channel: string | ConversationChannel, now = Date.now()): void {
-    const found = this.findBinding(channel);
-    if (found) found[1].lastActivity = now;
-  }
-
-  unbind(channel: string | ConversationChannel): void {
-    const found = this.findBinding(channel);
-    if (found) this.bindings.delete(found[0]);
+  touch(channelId: string, now = Date.now()): void {
+    const binding = this.bindings.get(channelId);
+    if (binding) binding.lastActivity = now;
   }
 
-  getBinding(channel: string | ConversationChannel): ConversationBinding | undefined {
-    return this.findBinding(channel)?.[1];
+  unbind(channelId: string): void {
+    this.bindings.delete(channelId);
   }
 
-  /**
-   * The binding a caller names, with its key. A channel given with its server
-   * names that server's binding only. A bare id, as callers gave it before
-   * bindings had servers, names the binding made with no server, else the one
-   * binding for that id; where several servers' channels with that id are
-   * bound, it names none.
-   */
-  private findBinding(channel: string | ConversationChannel): [string, ConversationBinding] | undefined {
-    const named = asChannel(channel);
-    const key = bindingKey(named);
-    const exact = this.bindings.get(key);
-    if (exact) return [key, exact];
-    if (named.serverId !== undefined) return undefined;
-    const matches = [...this.bindings.entries()].filter(([, b]) => b.channelId === named.channelId);
-    return matches.length === 1 ? matches[0] : undefined;
+  getBinding(channelId: string): ConversationBinding | undefined {
+    return this.bindings.get(channelId);
   }
 
   /** Reverse lookup: the channel an agent is bound to, if any. */
@@ -296,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);
@@ -333,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)) {
@@ -349,25 +322,6 @@ export class ConversationRouter {
   }
 }
 
-/**
- * A channel as the router's bindings take it: its id, with the MCPL server it
- * belongs to where the caller has one. A bare id, as callers gave it before,
- * is the channel with no server.
- */
-export interface ConversationChannel {
-  channelId: string;
-  serverId?: string;
-}
-
-function asChannel(channel: string | ConversationChannel): ConversationChannel {
-  return typeof channel === 'string' ? { channelId: channel } : channel;
-}
-
-/** A binding's key: its channel's server and id, unambiguous whatever either holds. */
-function bindingKey(channel: ConversationChannel): string {
-  return JSON.stringify([channel.serverId ?? null, channel.channelId]);
-}
-
 /** The readable part of a fork's name stops here: uniqueness rides on the hash. */
 const FORK_NAME_READABLE_MAX = 64;
 

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