@animalabs/agent-framework 0.22.1 → 0.22.3

package/src/mcpl/reference-fetcher.ts

@@ -3,7 +3,8 @@
  * dereferences a reference, and it fails closed on every axis the RFC names:
  *
  *  - **origin binding (§6.1, revision 3):** authenticated fetches go only to
- *    the origin the reference's server connection was dialed to. This v1 does
+ *    the origin a server's connection was dialed to, for a reference that
+ *    server delivered, with that server's credential. This v1 does
  *    not fetch third-party origins at all (deferred with declared reference
  *    origins); the connection credential is applied as an Authorization
  *    header by this code alone and never surfaces to model, script, or URI.
@@ -29,15 +30,22 @@
  */
 import { createHash } from 'node:crypto';
 import type { ReferenceRecord } from './references.js';
-import { EXPIRY_REASON, isReferenceExpired, referenceExpiry, REFERENCE_LIMITS, sanitizeLabel } from './references.js';
+import { EXPIRY_REASON, isReferenceExpired, referenceExpiry, REFERENCE_LIMITS, sanitizeLabel, UNBOUND_REASON } from './references.js';
 
 /** Per-fetch hard ceiling on actual bytes (overridable per server / call). */
 export const DEFAULT_FETCH_MAX_BYTES = 256 * 1024 * 1024;
 /** Eager (autofetch) threshold: at most what could have shipped inline. */
 export const DEFAULT_EAGER_FETCH_MAX_BYTES = 256 * 1024;
-/** Cumulative per-server budget for this process. */
+/** Cumulative per-server budget for this process: every byte a fetch dialed
+ *  through a server reads counts against that server's, whether or not it's
+ *  kept. */
 export const DEFAULT_MAX_TOTAL_BYTES = 1024 * 1024 * 1024;
 const FETCH_TIMEOUT_MS = 60_000;
+/** What a refusal by the per-server budget adds. The total lives as long as
+ *  this fetcher, one per framework, so only someone running the host renews
+ *  it, by starting a new one, or raises the budget (the server's config's
+ *  autofetch.maxTotalBytes, which each fetch reads afresh). */
+const BUDGET_LASTS = "the budget doesn't renew on its own, so calling again won't change that unless whoever runs this host raises or renews it";
 const EAGER_FETCH_TIMEOUT_MS = 10_000;
 
 export interface ResolvedServerBinding {
@@ -102,6 +110,10 @@ export function normalizedOrigin(url: string): string | null {
 }
 
 export class ReferenceFetcher {
+  /** Bytes read through each server in this process, charged to the server a
+   *  fetch dials through as each chunk is read, kept or not. Concurrent
+   *  fetches through one server share the total, so each checks what the
+   *  others have taken. */
   private totals = new Map<string, number>();
   private inFlight = new Map<string, Promise<FetchOutcome>>();
 
@@ -113,16 +125,34 @@ export class ReferenceFetcher {
   ) {}
 
   /** Would the eager (autofetch) default fetch this record? Not one the
-   *  fetcher refuses as expired, which would only take an eager slot. */
+   *  fetcher refuses as expired, which would only take an eager slot. It
+   *  takes the eager limit of the server the fetch would dial. */
   isEagerEligible(record: ReferenceRecord): boolean {
     if (record.fetchedPath) return false;
     if (isReferenceExpired(record.testimony)) return false;
-    if (record.serverId === undefined) return false;
-    const binding = this.resolveServer(record.serverId);
-    if (!binding) return false;
-    const cap = binding.autofetch?.maxBytes ?? DEFAULT_EAGER_FETCH_MAX_BYTES;
-    if (record.testimony.sizeBytes === undefined || record.testimony.sizeBytes > cap) return false;
-    return this.originCheck(record, binding) === null;
+    const server = this.serverFor(record);
+    if ('refusal' in server) return false;
+    const cap = server.binding.autofetch?.maxBytes ?? DEFAULT_EAGER_FETCH_MAX_BYTES;
+    return record.testimony.sizeBytes !== undefined && record.testimony.sizeBytes <= cap;
+  }
+
+  /** The server to dial for a record (§6.2): the first, in the order they
+   *  delivered it, whose address is on the uri's origin. When none is, the
+   *  first server's refusal (unknown to this host, or the origin check's),
+   *  and for a record no server delivered, that it's unbound. */
+  private serverFor(record: ReferenceRecord): { serverId: string; binding: ResolvedServerBinding } | { refusal: string } {
+    let refusal: string | undefined;
+    for (const serverId of record.serverIds) {
+      const binding = this.resolveServer(serverId);
+      if (!binding) {
+        refusal ??= `unknown server: ${serverId}`;
+        continue;
+      }
+      const offOrigin = this.originCheck(record, binding);
+      if (offOrigin === null) return { serverId, binding };
+      refusal ??= offOrigin;
+    }
+    return { refusal: refusal ?? `reference ${UNBOUND_REASON}` };
   }
 
   /** §6.1/§7.1 policy check; returns a refusal reason or null. */
@@ -158,24 +188,33 @@ export class ReferenceFetcher {
 
   private async doFetch(record: ReferenceRecord, opts?: { maxBytes?: number; timeoutMs?: number }): Promise<FetchOutcome> {
     const t = record.testimony;
-    if (record.serverId === undefined) return { ok: false, error: 'reference has no server binding' };
-    const binding = this.resolveServer(record.serverId);
-    if (!binding) return { ok: false, error: `unknown server: ${record.serverId}` };
-
-    const refusal = this.originCheck(record, binding);
-    if (refusal) return { ok: false, error: refusal };
+    const server = this.serverFor(record);
+    if ('refusal' in server) return { ok: false, error: server.refusal };
+    const { serverId, binding } = server;
     const expiry = referenceExpiry(t);
     if (expiry) return { ok: false, error: `reference ${EXPIRY_REASON[expiry]}` };
 
     const ceiling = opts?.maxBytes ?? DEFAULT_FETCH_MAX_BYTES;
-    // Vector 4: a claim already over the ceiling refuses without dialing.
-    if (t.sizeBytes !== undefined && t.sizeBytes > ceiling) {
-      return { ok: false, error: `claimed ${t.sizeBytes} bytes exceeds fetch ceiling ${ceiling}` };
-    }
+    // The budget is checked before the ceiling, here and while reading: a
+    // larger max_bytes lifts the ceiling, and nothing the caller does lifts
+    // the budget, so a fetch past both is told about the budget.
     const budget = binding.autofetch?.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
-    const used = this.totals.get(record.serverId) ?? 0;
+    const used = this.totals.get(serverId) ?? 0;
     if (used >= budget) {
-      return { ok: false, error: `per-server fetch budget exhausted (${used}/${budget} bytes)` };
+      return { ok: false, error: `per-server fetch budget exhausted (${used}/${budget} bytes); ${BUDGET_LASTS}` };
+    }
+    // Vector 4: a claim already over the ceiling refuses without dialing. One
+    // that's also over what's left of the budget is told about the budget,
+    // which no max_bytes lifts. A claim over what's left but within the
+    // ceiling still dials, and the budget stops it at its first chunk past.
+    if (t.sizeBytes !== undefined && t.sizeBytes > ceiling) {
+      if (t.sizeBytes > budget - used) {
+        return {
+          ok: false,
+          error: `claimed ${t.sizeBytes} bytes exceeds what's left of the per-server fetch budget (${used}/${budget} bytes); ${BUDGET_LASTS}`,
+        };
+      }
+      return { ok: false, error: `claimed ${t.sizeBytes} bytes exceeds fetch ceiling ${ceiling}` };
     }
 
     const controller = new AbortController();
@@ -198,10 +237,17 @@ export class ReferenceFetcher {
         const { done, value } = await reader.read();
         if (done) break;
         received += value.byteLength;
-        if (received > ceiling || received > budget - used) {
+        // What's read is charged at once, kept or not: other fetches from
+        // this server read the same total, so none spends what another took.
+        const total = (this.totals.get(serverId) ?? 0) + value.byteLength;
+        this.totals.set(serverId, total);
+        if (total > budget) {
+          controller.abort();
+          return { ok: false, error: `aborted: per-server fetch budget exhausted (${total}/${budget} bytes); ${BUDGET_LASTS}` };
+        }
+        if (received > ceiling) {
           controller.abort();
-          const which = received > ceiling ? 'ceiling' : 'per-server budget';
-          return { ok: false, error: `aborted: actual bytes exceeded ${which} at ${received}` };
+          return { ok: false, error: `aborted: actual bytes exceeded ceiling at ${received}` };
         }
         const buf = Buffer.from(value);
         hash.update(buf);
@@ -232,7 +278,6 @@ export class ReferenceFetcher {
       const path = await this.saveFile(`${record.refId}.${ext}`, data, observedMime);
       if (path === null) return { ok: false, error: 'no writable workspace mount to store the payload' };
 
-      this.totals.set(record.serverId, used + data.length);
       record.fetchedPath = path;
       record.verifiedBytes = data.length;
       record.verifiedMimeType = observedMime;

package/src/mcpl/references.ts

@@ -30,6 +30,10 @@ export const REFERENCE_LIMITS = { uri: 4096, mimeType: 255, name: 255, expiresAt
 export const DIGEST_PATTERN = /^sha256:[A-Za-z0-9_-]{43}$/;
 const MAX_SAFE = 9007199254740991; // 2^53 - 1
 const STUB_FIELD_CHARS = 120;
+/** A saved copy's path, as its stub shows it. */
+const SAVED_PATH_CHARS = 256;
+/** A reference id's random suffix (see ReferenceRegistry.register). */
+const REF_ID_SUFFIX_CHARS = 4;
 
 export type ReferenceDisposition = 'never' | 'ref';
 
@@ -93,7 +97,7 @@ export function classifyBlock(block: unknown): BlockClassification {
         return { kind: 'inline', contradiction: block.disposition !== undefined || hasUri };
       }
       if (hasUri) return parseReferenceFields(block);
-      return { kind: 'invalid', reason: `${block.type} block with neither data nor uri` };
+      return { kind: 'invalid', reason: `${block.type} block ${mediaWithoutStringReason(block)}` };
     }
     case 'resource':
       return parseReferenceFields(block);
@@ -102,6 +106,14 @@ export function classifyBlock(block: unknown): BlockClassification {
   }
 }
 
+/** What a media block with neither string data nor a string uri has instead:
+ *  nothing, or a field that isn't a string. */
+function mediaWithoutStringReason(block: Record<string, unknown>): string {
+  const notString = (['data', 'uri'] as const).filter((f) => block[f] !== undefined && block[f] !== null);
+  if (notString.length === 0) return 'with neither data nor uri';
+  return notString.length === 2 ? "whose data and uri aren't strings" : `whose ${notString[0]} isn't a string`;
+}
+
 function parseReferenceFields(block: Record<string, unknown>): BlockClassification {
   if (typeof block.uri !== 'string' || block.uri.length === 0) {
     return { kind: 'invalid', reason: 'reference without string uri' };
@@ -140,7 +152,7 @@ export function isInlineContradiction(block: unknown): boolean {
 }
 
 export const INLINE_WITHHELD_TEXT =
-  '[inline content withheld: nonconformant bulk disposition on inline data]';
+  '[inline content withheld: inline data that also claims a uri or a bulk disposition]';
 
 /**
  * Why a reference counts as expired, or null when it doesn't: its expiresAt
@@ -172,6 +184,11 @@ export const EXPIRY_REASON = {
   rejected: `treated as expired: its expiresAt was rejected as a field, over ${REFERENCE_LIMITS.expiresAt} characters or not a string (fail closed)`,
 } as const;
 
+/** A reference registered with no server, as the stub, the fetcher's refusal
+ *  and save_recent_image's all say it: the fetcher dials only through a
+ *  server that delivered the reference. */
+export const UNBOUND_REASON = 'unbound: no server is recorded to fetch it from';
+
 /** Strip control characters (C0, DEL, C1) and every bidi control (marks,
  *  embeddings, overrides, isolates, and the Arabic letter mark), trim the
  *  whitespace (a BOM included) left at either end, and bound the length.
@@ -199,7 +216,11 @@ export function formatSizeBytes(n: number): string {
 
 export interface ReferenceRecord {
   refId: string;
-  serverId?: string;
+  /** The servers whose content delivered this uri, each once, in the order
+   *  they did (§6.2). The fetcher dials through the first whose address is on
+   *  the uri's origin. Empty when no server delivered it, as for a reference
+   *  in a module's own tool result. */
+  serverIds: string[];
   testimony: ReferenceTestimony;
   receivedAt: number;
   /** Set by the host-mediated fetcher after a successful, verified fetch. */
@@ -220,20 +241,27 @@ const MAX_RECORDS = 2000;
  * defined miss, never a different record.
  *
  * Process-wide singleton by design: ids are host-local *names*, not
- * capabilities, and the record itself carries serverId for any future
+ * capabilities, and the record carries the servers that delivered it for the
  * origin-bound fetcher.
  */
 export class ReferenceRegistry {
   private records = new Map<string, ReferenceRecord>();
-  /** uri → refId. The uri ALONE is the identity key: stub sites (the two
-   *  tool-result serializers and the three converters) are free functions
-   *  with no server context, while dispatch-time pre-registration carries a
-   *  serverId — keying on both split every reference into two records, the
-   *  model-visible one unbound (fetch_reference failed on it) and the bound
-   *  one invisible. One key, and a later registration that knows the server
-   *  UPGRADES the record's binding instead of forking it. If two servers ever
-   *  reference the same uri, the first binding wins (the record's serverId
-   *  feeds the origin check, which fails closed on a mismatch). */
+  /** uri → refId. The uri ALONE is the identity key: a tool result's stubs
+   *  (tool-result-history.ts's, and framework.ts's tryNativeToolResultContent)
+   *  and a script's demand fetch register with no server context,
+   *  while the registrations that know the server carry its id: a tool
+   *  result's, before it's shown, whether the agent's dispatch or an
+   *  in-process caller made the call, and convertBlock's, for push events,
+   *  render results, channel messages and context injections. Keying on both
+   *  split every reference into two records, the model-visible one unbound
+   *  (fetch_reference failed on it) and the bound one invisible. One key, and
+   *  each registration that knows its server ADDS that server to the record,
+   *  once, in the order they came, instead of forking it. When several
+   *  servers deliver one uri, the fetcher dials through the first whose
+   *  address is on the uri's origin, so a server off that origin delivering
+   *  it first doesn't decide whether it can be fetched; among servers on that
+   *  origin, the first to deliver it is dialed. A server's token goes only to
+   *  its own origin, for a uri it delivered. */
   private byKey = new Map<string, string>();
   private counter = 0;
 
@@ -242,8 +270,8 @@ export class ReferenceRegistry {
     if (existingId !== undefined) {
       const existing = this.records.get(existingId);
       if (existing) {
-        if (serverId !== undefined && existing.serverId === undefined) {
-          existing.serverId = serverId;
+        if (serverId !== undefined && !existing.serverIds.includes(serverId)) {
+          existing.serverIds.push(serverId);
         }
         // Refresh testimony while unfetched: a re-issued reference with a new
         // digest/expiry supersedes the stale claims. Once fetched, the record
@@ -256,8 +284,8 @@ export class ReferenceRegistry {
         return existing;
       }
     }
-    const refId = `ref_${(++this.counter).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
-    const record: ReferenceRecord = { refId, serverId, testimony, receivedAt: Date.now() };
+    const refId = `ref_${(++this.counter).toString(36)}_${Math.random().toString(36).slice(2, 2 + REF_ID_SUFFIX_CHARS)}`;
+    const record: ReferenceRecord = { refId, serverIds: serverId === undefined ? [] : [serverId], testimony, receivedAt: Date.now() };
     this.records.set(refId, record);
     this.byKey.set(testimony.uri, refId);
     if (this.records.size > MAX_RECORDS) {
@@ -294,6 +322,22 @@ export function referenceTypeLabel(mimeType: string | undefined): string {
   return mimeType ? sanitizeLabel(mimeType, STUB_FIELD_CHARS) : '';
 }
 
+/**
+ * The longest line buildReferenceStub writes, in UTF-16 code units, from its
+ * own bounds: the longest id the registry mints, then the name, the type with
+ * the largest size it shows, and the origin, each at its bound, and the
+ * longest ending, a saved copy's path, with their separators. The other
+ * endings, the fetch hint and the reasons a fetch would be refused, are
+ * shorter. A line shaped like a stub but longer than this is quoted text the
+ * writer can't have written, and no image slot (tool-image-ledger.ts).
+ */
+export const REFERENCE_STUB_MAX_CHARS =
+  `[ref_${MAX_SAFE.toString(36)}_] `.length + REF_ID_SUFFIX_CHARS
+  + STUB_FIELD_CHARS
+  + ' — '.length + STUB_FIELD_CHARS + ', '.length + `${formatSizeBytes(MAX_SAFE)} claimed`.length
+  + ' — '.length + STUB_FIELD_CHARS
+  + ' — '.length + 'saved: '.length + SAVED_PATH_CHARS;
+
 /**
  * Build the model-visible stub for a reference. Output length is bounded by
  * host constants and independent of every server-supplied field length.
@@ -317,16 +361,31 @@ export function buildReferenceStub(t: ReferenceTestimony, provenance?: string, s
   if (record.fetchedPath) {
     // Already materialized by the host-mediated fetcher: hand the model the
     // workspace path (host-generated, §7.3) so existing tools just work.
-    parts.push(`saved: ${sanitizeLabel(record.fetchedPath, 256)}`);
+    parts.push(`saved: ${sanitizeLabel(record.fetchedPath, SAVED_PATH_CHARS)}`);
   } else {
-    // An expired reference says so rather than inviting a fetch_reference
-    // call the fetcher can only refuse.
-    const expiry = referenceExpiry(record.testimony);
-    parts.push(expiry ? EXPIRY_REASON[expiry] : 'fetch with fetch_reference');
+    // A reference whose record shows the fetcher would refuse it says why,
+    // rather than inviting a fetch_reference call.
+    parts.push(unfetchableReason(record) ?? 'fetch with fetch_reference');
   }
   return `[${record.refId}] ${parts.join(' — ') || 'referenced content'}`;
 }
 
+/**
+ * Why the fetcher would refuse a reference, as far as its record shows: no
+ * server registered for it, which the fetcher checks first, or its expiry.
+ * Null for a saved copy, which the fetcher serves before any check, and when
+ * the record shows neither. The fetcher's other refusals rest on what a record
+ * doesn't hold: whether any of its servers is still known to the host and on
+ * the uri's origin, a claimed size over the ceiling a fetch is given, or the
+ * dialed server's fetch budget spent, and it gives those in its own words.
+ */
+export function unfetchableReason(record: ReferenceRecord, nowMs = Date.now()): string | null {
+  if (record.fetchedPath) return null;
+  if (record.serverIds.length === 0) return UNBOUND_REASON;
+  const expiry = referenceExpiry(record.testimony, nowMs);
+  return expiry ? EXPIRY_REASON[expiry] : null;
+}
+
 /**
  * RFC-005 treatment for one MCPL wire block, for the model-visible text
  * lanes. Returns a replacement string, or null when the block should keep

package/src/mcpl/refusal-lines.ts

@@ -0,0 +1,59 @@
+import { logValue } from './log-value.js';
+
+/**
+ * At most one host line a minute for a refusal a server keeps repeating for
+ * as long as a standing condition lasts: messages for a channel it never
+ * registered, or channel-scoped pushes to a channel it hasn't declared or may
+ * not use. A server that never registered a busy channel would otherwise
+ * print a line for every message in it. Only the line is held back: every
+ * refusal is still answered and traced. Each lane keeps its own records, as
+ * its lines are its own.
+ *
+ * Per server and channel, the first refusal prints. After that a refusal
+ * prints only once a minute has passed since that channel's last line, and
+ * its line names how many were held back since. The minute is timed with a
+ * monotonic clock, so a step of the wall clock can't silence a channel. A
+ * refusal within a minute of the channel's last line is counted into its
+ * next line, whatever happens to the channel in between (it may be
+ * registered, unregistered or reconnected).
+ *
+ * A record is keyed by the channel as its line prints it (logValue), so two
+ * ids share one exactly when their lines name them alike, which only ids
+ * over 256 units can. The records cover the 1,000 most recently refused
+ * channels: a new channel evicts the least recently refused one, with its
+ * minute and any count it held, and that channel's next refusal prints as a
+ * first.
+ */
+export class RefusalLines {
+  /** By key, from the least recently refused channel to the most. */
+  private readonly records = new Map<string, { at: number; since: number }>();
+
+  constructor(private readonly now: () => number = () => performance.now()) {}
+
+  /**
+   * Record one refusal for a server's channel. Returns null when its line is
+   * held back, or else how many of the channel's refusals were held back
+   * since its last line (0 for its first).
+   */
+  admit(serverId: string, channelId: string): number | null {
+    // logValue never prints a NUL, so the key's last NUL keeps the two apart
+    // whatever a server id holds.
+    const key = `${serverId}\u0000${logValue(channelId)}`;
+    const now = this.now();
+    const record = this.records.get(key);
+    if (record) this.records.delete(key);
+    else if (this.records.size >= MAX_CHANNELS) this.records.delete(this.records.keys().next().value!);
+    if (!record || now - record.at >= EVERY_MS) {
+      this.records.set(key, { at: now, since: 0 });
+      return record?.since ?? 0;
+    }
+    record.since++;
+    this.records.set(key, record);
+    return null;
+  }
+}
+
+/** A channel's line prints at most this often. */
+const EVERY_MS = 60_000;
+/** The channels the records cover at once. */
+const MAX_CHANNELS = 1_000;