@animalabs/agent-framework 0.11.0 → 0.13.0

package/src/mcpl/reference-fetcher.ts

@@ -0,0 +1,240 @@
+/**
+ * RFC-005 host-mediated reference fetcher (§6, §7) — the only code that ever
+ * 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
+ *    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.
+ *  - **scheme allowlist (§7.1, vector 11):** https; http only when the dialed
+ *    origin itself is plaintext (a ws:// server references its own origin).
+ *  - **no redirect traversal (§7.2, vector 12):** any 3xx refuses.
+ *  - **actual-byte ceiling (§7.3 list, vector 10):** streamed with abort the
+ *    moment real octets exceed the ceiling, regardless of claimed sizeBytes.
+ *    A claim already over the ceiling refuses without dialing (vector 4).
+ *  - **digest verification (§7.4 list, vector 5):** sha256 computed while
+ *    streaming; a mismatch is discarded, never presented.
+ *  - **expiry (§7.4, vector 16):** expired testimony refuses locally.
+ *  - **storage naming (§7.3):** the file name is host-generated from the
+ *    reference id + verified type; the server's `name` is display-only.
+ *
+ * Autofetch policy (host default, not protocol): eager only below
+ * DEFAULT_EAGER_FETCH_MAX_BYTES from the connection origin — anything under
+ * that threshold the server could legitimately have inlined, so eager
+ * materialization is never worse than the status quo. Everything larger is
+ * fetched on demand (the fetch_reference tool, or the code-execution result
+ * hook, where a script receiving a result is the strongest available signal
+ * that the bytes are wanted). Per-server budgets cap cumulative appetite.
+ */
+import { createHash } from 'node:crypto';
+import type { ReferenceRecord } from './references.js';
+import { isReferenceExpired } 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. */
+export const DEFAULT_MAX_TOTAL_BYTES = 1024 * 1024 * 1024;
+const FETCH_TIMEOUT_MS = 60_000;
+const EAGER_FETCH_TIMEOUT_MS = 10_000;
+
+export interface ResolvedServerBinding {
+  /** The url the connection was dialed to (ws/wss/http/https). */
+  url: string;
+  /** Connection credential, applied host-side as Authorization: Bearer. */
+  token?: string;
+  autofetch?: { maxBytes?: number; maxTotalBytes?: number };
+}
+
+export interface FetchOutcome {
+  ok: boolean;
+  /** Mount-prefixed workspace path of the saved payload (on success). */
+  path?: string;
+  bytes?: number;
+  mimeType?: string;
+  digestVerified?: boolean;
+  error?: string;
+}
+
+/** Magic-byte sniff for the formats this pipeline actually moves. The
+ *  header is testimony too (vector 13): sniffed type wins for the storage
+ *  extension and the record's verified type; header, then testimony, are
+ *  fallbacks for containers the sniffer doesn't know. */
+export function sniffMime(data: Buffer): string | null {
+  if (data.length < 12) return null;
+  if (data.subarray(0, 4).toString('latin1') === 'RIFF' && data.subarray(8, 12).toString('latin1') === 'WAVE') return 'audio/wav';
+  if (data.subarray(0, 4).toString('latin1') === 'RIFF') return 'audio/wav';
+  if (data.subarray(0, 4).toString('latin1') === 'fLaC') return 'audio/flac';
+  if (data.subarray(0, 4).toString('latin1') === 'OggS') return 'audio/ogg';
+  if (data.subarray(0, 4).toString('latin1') === 'MThd') return 'audio/midi';
+  if (data.subarray(0, 3).toString('latin1') === 'ID3' || (data[0] === 0xff && (data[1] & 0xe0) === 0xe0)) return 'audio/mpeg';
+  if (data[0] === 0x89 && data.subarray(1, 4).toString('latin1') === 'PNG') return 'image/png';
+  if (data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) return 'image/jpeg';
+  if (data.subarray(0, 6).toString('latin1') === 'GIF87a' || data.subarray(0, 6).toString('latin1') === 'GIF89a') return 'image/gif';
+  if (data.subarray(4, 8).toString('latin1') === 'ftyp') return 'video/mp4';
+  if (data.subarray(0, 5).toString('latin1') === '%PDF-') return 'application/pdf';
+  if (data[0] === 0x50 && data[1] === 0x4b) return 'application/zip';
+  return null;
+}
+
+const EXT_BY_MIME: Record<string, string> = {
+  'audio/wav': 'wav', 'audio/x-wav': 'wav', 'audio/mpeg': 'mp3', 'audio/mp4': 'm4a',
+  'audio/flac': 'flac', 'audio/midi': 'mid', 'audio/ogg': 'ogg',
+  'image/png': 'png', 'image/jpeg': 'jpg', 'image/gif': 'gif', 'image/webp': 'webp',
+  'video/mp4': 'mp4', 'application/json': 'json', 'text/plain': 'txt',
+  'application/pdf': 'pdf', 'application/zip': 'zip',
+};
+
+/** ws→http / wss→https with default ports elided, for origin comparison. */
+export function normalizedOrigin(url: string): string | null {
+  try {
+    const u = new URL(url);
+    const scheme = u.protocol === 'ws:' ? 'http:' : u.protocol === 'wss:' ? 'https:' : u.protocol;
+    const defaultPort = scheme === 'https:' ? '443' : '80';
+    const port = u.port === '' || u.port === defaultPort ? '' : `:${u.port}`;
+    return `${scheme}//${u.hostname.toLowerCase()}${port}`;
+  } catch {
+    return null;
+  }
+}
+
+export class ReferenceFetcher {
+  private totals = new Map<string, number>();
+  private inFlight = new Map<string, Promise<FetchOutcome>>();
+
+  constructor(
+    private readonly resolveServer: (serverId: string) => ResolvedServerBinding | undefined,
+    /** Persist the payload; returns a mount-prefixed path or null when no
+     *  writable workspace exists. File name is host-generated (§7.3). */
+    private readonly saveFile: (fileName: string, data: Buffer, mimeType: string) => Promise<string | null>,
+  ) {}
+
+  /** Would the eager (autofetch) default fetch this record? */
+  isEagerEligible(record: ReferenceRecord): boolean {
+    if (record.fetchedPath) 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;
+  }
+
+  /** §6.1/§7.1 policy check; returns a refusal reason or null. */
+  private originCheck(record: ReferenceRecord, binding: ResolvedServerBinding): string | null {
+    const refOrigin = normalizedOrigin(record.testimony.uri);
+    const dialedOrigin = normalizedOrigin(binding.url);
+    if (!refOrigin) return 'reference uri does not parse';
+    if (!dialedOrigin) return 'server url does not parse';
+    const scheme = refOrigin.split('//')[0];
+    if (scheme !== 'https:' && scheme !== 'http:') return `scheme not allowed: ${scheme}`;
+    if (refOrigin !== dialedOrigin) {
+      return `third-party origin (${refOrigin} != dialed ${dialedOrigin}); not fetched by this host`;
+    }
+    if (scheme === 'http:' && dialedOrigin.startsWith('https:')) {
+      return 'plaintext reference from a secure origin';
+    }
+    return null;
+  }
+
+  /** Fetch a reference to workspace storage. Idempotent per record; concurrent
+   *  callers share one in-flight fetch. */
+  fetch(record: ReferenceRecord, opts?: { maxBytes?: number; timeoutMs?: number }): Promise<FetchOutcome> {
+    if (record.fetchedPath) {
+      return Promise.resolve({ ok: true, path: record.fetchedPath, bytes: record.verifiedBytes,
+        mimeType: record.verifiedMimeType, digestVerified: record.digestVerified });
+    }
+    const existing = this.inFlight.get(record.refId);
+    if (existing) return existing;
+    const p = this.doFetch(record, opts).finally(() => this.inFlight.delete(record.refId));
+    this.inFlight.set(record.refId, p);
+    return p;
+  }
+
+  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 };
+    if (isReferenceExpired(t)) return { ok: false, error: 'reference expired (or unparseable expiry — fail closed)' };
+
+    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}` };
+    }
+    const budget = binding.autofetch?.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
+    const used = this.totals.get(record.serverId) ?? 0;
+    if (used >= budget) {
+      return { ok: false, error: `per-server fetch budget exhausted (${used}/${budget} bytes)` };
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts?.timeoutMs ?? FETCH_TIMEOUT_MS);
+    try {
+      const headers: Record<string, string> = {};
+      if (binding.token) headers.authorization = `Bearer ${binding.token}`;
+      const resp = await fetch(t.uri, { headers, redirect: 'manual', signal: controller.signal });
+      if (resp.status >= 300 && resp.status < 400) {
+        return { ok: false, error: `redirect refused (HTTP ${resp.status}) — no redirect traversal` };
+      }
+      if (!resp.ok) return { ok: false, error: `HTTP ${resp.status}` };
+      if (!resp.body) return { ok: false, error: 'no response body' };
+
+      const hash = createHash('sha256');
+      const chunks: Buffer[] = [];
+      let received = 0;
+      const reader = resp.body.getReader();
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        received += value.byteLength;
+        if (received > ceiling || received > budget - used) {
+          controller.abort();
+          const which = received > ceiling ? 'ceiling' : 'per-server budget';
+          return { ok: false, error: `aborted: actual bytes exceeded ${which} at ${received}` };
+        }
+        const buf = Buffer.from(value);
+        hash.update(buf);
+        chunks.push(buf);
+      }
+      const data = Buffer.concat(chunks);
+
+      let digestVerified: boolean | undefined;
+      if (t.digest) {
+        const got = 'sha256:' + hash.digest('base64url');
+        if (got !== t.digest) {
+          // Vector 5: never presented as the described content.
+          return { ok: false, error: `digest mismatch (claimed ${t.digest.slice(0, 20)}…, got ${got.slice(0, 20)}…)` };
+        }
+        digestVerified = true;
+      }
+
+      const headerMime = resp.headers.get('content-type')?.split(';')[0].trim() || null;
+      const observedMime = sniffMime(data) ?? headerMime ?? t.mimeType ?? 'application/octet-stream';
+      const ext = EXT_BY_MIME[observedMime] ?? EXT_BY_MIME[headerMime ?? ''] ?? EXT_BY_MIME[t.mimeType ?? ''] ?? 'bin';
+      // §7.3: host-generated storage name; the server's `name` is display-only.
+      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;
+      record.digestVerified = digestVerified;
+      return { ok: true, path, bytes: data.length, mimeType: observedMime, digestVerified };
+    } catch (e) {
+      const msg = (e as Error).name === 'AbortError' ? 'fetch timed out or aborted' : (e as Error).message;
+      return { ok: false, error: msg };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+export { EAGER_FETCH_TIMEOUT_MS };

package/src/mcpl/references.ts

@@ -0,0 +1,292 @@
+/**
+ * RFC-005 bulk content references — host treatment (agent-framework side).
+ *
+ * Mirrors the pure module in mcpl-core-ts `src/references.ts` (this framework
+ * deliberately does not depend on that package; hand-maintained MCPL types
+ * are the house convention — see types.ts header). Semantics are the RFC's,
+ * revision 3:
+ *
+ *  - every parsed field is server *testimony*, never a fact (§3);
+ *  - the one invalid-field rule (§8): a bad optional field is dropped while
+ *    the block and its subtractive `disposition` survive; a bad `uri`
+ *    rejects the block whole;
+ *  - `disposition:"never"` withholds payload AND uri from model context
+ *    unconditionally — enforced in code here, not by caller discipline (§5);
+ *  - stub size is independent of every server-supplied field length (§5);
+ *  - unparseable `expiresAt` fails closed (§7.4);
+ *  - unknown block types never propagate `undefined` (the pre-existing
+ *    convertBlock switches had no default — a latent corruption this module
+ *    retires).
+ *
+ * The ReferenceRegistry is the host-private reference record (§6.2): raw
+ * URIs and testimony live here and never in model-visible content. Fetching
+ * (§6/§7 origin binding, ceilings, redirects) is deliberately not here yet —
+ * the registry is what makes a future host-mediated fetcher and the
+ * code-execution materialization hook possible.
+ */
+
+export const REFERENCE_LIMITS = { uri: 4096, mimeType: 255, name: 255, expiresAt: 64 } as const;
+export const DIGEST_PATTERN = /^sha256:[A-Za-z0-9_-]{43}$/;
+const MAX_SAFE = 9007199254740991; // 2^53 - 1
+const STUB_FIELD_CHARS = 120;
+
+export type ReferenceDisposition = 'never' | 'ref';
+
+export interface ReferenceTestimony {
+  uri: string;
+  mimeType?: string;
+  sizeBytes?: number;
+  digest?: string;
+  expiresAt?: string;
+  name?: string;
+  disposition?: ReferenceDisposition;
+  rejectedFields: string[];
+  truncatedFields: string[];
+}
+
+export type BlockClassification =
+  | { kind: 'text' }
+  | { kind: 'inline'; contradiction: boolean }
+  | { kind: 'reference'; testimony: ReferenceTestimony }
+  | { kind: 'invalid'; reason: string };
+
+function isRecord(x: unknown): x is Record<string, unknown> {
+  return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+
+function takeString(
+  raw: unknown, field: keyof typeof REFERENCE_LIMITS & string,
+  out: { rejected: string[]; truncated: string[] },
+): string | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'string') { out.rejected.push(field); return undefined; }
+  const limit = REFERENCE_LIMITS[field];
+  if (raw.length > limit) { out.truncated.push(field); return raw.slice(0, limit); }
+  return raw;
+}
+
+export function classifyBlock(block: unknown): BlockClassification {
+  if (!isRecord(block) || typeof block.type !== 'string') {
+    return { kind: 'invalid', reason: 'not a content block' };
+  }
+  switch (block.type) {
+    case 'text':
+      return typeof block.text === 'string'
+        ? { kind: 'text' }
+        : { kind: 'invalid', reason: 'text block without string text' };
+    case 'image':
+    case 'audio': {
+      const hasData = typeof block.data === 'string';
+      const hasUri = typeof block.uri === 'string';
+      if (hasData) {
+        // Inline form claiming bulk disposition (or smuggling a uri beside
+        // the data) is the vector-2 contradiction: fail closed, withhold.
+        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` };
+    }
+    case 'resource':
+      return parseReferenceFields(block);
+    default:
+      return { kind: 'invalid', reason: `unknown block type: ${block.type}` };
+  }
+}
+
+function parseReferenceFields(block: Record<string, unknown>): BlockClassification {
+  if (typeof block.uri !== 'string' || block.uri.length === 0) {
+    return { kind: 'invalid', reason: 'reference without string uri' };
+  }
+  if (block.uri.length > REFERENCE_LIMITS.uri) {
+    return { kind: 'invalid', reason: 'uri exceeds schema maximum' };
+  }
+  const out = { rejected: [] as string[], truncated: [] as string[] };
+  const t: ReferenceTestimony = { uri: block.uri, rejectedFields: out.rejected, truncatedFields: out.truncated };
+  t.mimeType = takeString(block.mimeType, 'mimeType', out);
+  t.name = takeString(block.name, 'name', out);
+  t.expiresAt = takeString(block.expiresAt, 'expiresAt', out);
+  if (block.sizeBytes !== undefined) {
+    const n = block.sizeBytes;
+    if (typeof n === 'number' && Number.isInteger(n) && n >= 0 && n <= MAX_SAFE) t.sizeBytes = n;
+    else out.rejected.push('sizeBytes');
+  }
+  if (block.digest !== undefined) {
+    if (typeof block.digest === 'string' && DIGEST_PATTERN.test(block.digest)) t.digest = block.digest;
+    else out.rejected.push('digest');
+  }
+  if (block.disposition !== undefined) {
+    if (block.disposition === 'never' || block.disposition === 'ref') t.disposition = block.disposition;
+    else out.rejected.push('disposition');
+  }
+  return { kind: 'reference', testimony: t };
+}
+
+/** RFC-005 vector 2: an inline-data block claiming bulk disposition (or
+ *  smuggling a uri beside its data) is an emitter contradiction — the host
+ *  fails closed by withholding the inline data from context. Every lane that
+ *  handles inline media MUST consult this before its data branch. */
+export function isInlineContradiction(block: unknown): boolean {
+  const c = classifyBlock(block);
+  return c.kind === 'inline' && c.contradiction;
+}
+
+export const INLINE_WITHHELD_TEXT =
+  '[inline content withheld: nonconformant bulk disposition on inline data]';
+
+export function isReferenceExpired(t: Pick<ReferenceTestimony, 'expiresAt'>, nowMs = Date.now()): boolean {
+  if (t.expiresAt === undefined) return false;
+  const exp = Date.parse(t.expiresAt);
+  return Number.isNaN(exp) ? true : exp <= nowMs;
+}
+
+/** Strip C0/C1 controls plus bidi marks/overrides/isolates; bound length.
+ *  Labels are labels — storage naming is host-generated elsewhere (§7.3). */
+export function sanitizeLabel(s: string, maxChars: number): string {
+  const cleaned = s.replace(/[\u0000-\u001F\u007F-\u009F\u200E\u200F\u202A-\u202E\u2066-\u2069]/g, '');
+  if (cleaned.length <= maxChars) return cleaned;
+  let cut = cleaned.slice(0, Math.max(0, maxChars - 1));
+  // never split a surrogate pair at the truncation boundary
+  const last = cut.charCodeAt(cut.length - 1);
+  if (last >= 0xd800 && last <= 0xdbff) cut = cut.slice(0, -1);
+  return cut + '…';
+}
+
+export function formatSizeBytes(n: number): string {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `~${Math.round(n / 1024)}KB`;
+  if (n < 1024 * 1024 * 1024) return `~${(n / (1024 * 1024)).toFixed(1)}MB`;
+  return `~${(n / (1024 * 1024 * 1024)).toFixed(1)}GB`;
+}
+
+// ============================================================================
+// Host-private reference record (§6.2) + reference ids (§5)
+// ============================================================================
+
+export interface ReferenceRecord {
+  refId: string;
+  serverId?: string;
+  testimony: ReferenceTestimony;
+  receivedAt: number;
+  /** Set by the host-mediated fetcher after a successful, verified fetch. */
+  fetchedPath?: string;
+  verifiedBytes?: number;
+  verifiedMimeType?: string;
+  digestVerified?: boolean;
+}
+
+const MAX_RECORDS = 2000;
+
+/**
+ * Host-private store of received references. Raw URIs live here and in stubs
+ * never (under `never`) or by policy only (`ref`/absent). Ids are stable and
+ * never reused within the process (vector 20); eviction is FIFO past
+ * MAX_RECORDS and a stale lookup returns undefined — a 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
+ * 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). */
+  private byKey = new Map<string, string>();
+  private counter = 0;
+
+  register(testimony: ReferenceTestimony, serverId?: string): ReferenceRecord {
+    const existingId = this.byKey.get(testimony.uri);
+    if (existingId !== undefined) {
+      const existing = this.records.get(existingId);
+      if (existing) {
+        if (serverId !== undefined && existing.serverId === undefined) {
+          existing.serverId = serverId;
+        }
+        // Refresh testimony while unfetched: a re-issued reference with a new
+        // digest/expiry supersedes the stale claims. Once fetched, the record
+        // describes verified bytes on disk and keeps the testimony they were
+        // verified against.
+        if (!existing.fetchedPath) existing.testimony = testimony;
+        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() };
+    this.records.set(refId, record);
+    this.byKey.set(testimony.uri, refId);
+    if (this.records.size > MAX_RECORDS) {
+      const oldest = this.records.keys().next().value;
+      if (oldest !== undefined) {
+        const old = this.records.get(oldest);
+        this.records.delete(oldest);
+        if (old) this.byKey.delete(old.testimony.uri);
+      }
+    }
+    return record;
+  }
+
+  get(refId: string): ReferenceRecord | undefined {
+    return this.records.get(refId);
+  }
+
+  /** Find the record for a uri. */
+  findByUri(uri: string): ReferenceRecord | undefined {
+    const id = this.byKey.get(uri);
+    return id !== undefined ? this.records.get(id) : undefined;
+  }
+}
+
+export const referenceRegistry = new ReferenceRegistry();
+
+// ============================================================================
+// Stub building (§5)
+// ============================================================================
+
+/**
+ * Build the model-visible stub for a reference. Output length is bounded by
+ * host constants and independent of every server-supplied field length.
+ * Under `disposition:"never"` the uri is omitted unconditionally; under
+ * `ref`/absent it is omitted too — this host's default policy is the opaque
+ * id everywhere (the safe default of §5), with retrieval via the record.
+ */
+export function buildReferenceStub(t: ReferenceTestimony, provenance?: string, serverId?: string): string {
+  const record = referenceRegistry.register(t, serverId);
+  const parts: string[] = [];
+  if (t.name) parts.push(sanitizeLabel(t.name, STUB_FIELD_CHARS));
+  const meta: string[] = [];
+  if (t.mimeType) meta.push(sanitizeLabel(t.mimeType, STUB_FIELD_CHARS));
+  if (t.sizeBytes !== undefined) meta.push(`${formatSizeBytes(t.sizeBytes)} claimed`);
+  if (meta.length) parts.push(meta.join(', '));
+  if (provenance) parts.push(sanitizeLabel(provenance, STUB_FIELD_CHARS));
+  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)}`);
+  } else {
+    parts.push('fetch with fetch_reference');
+  }
+  return `[${record.refId}] ${parts.join(' — ') || 'referenced content'}`;
+}
+
+/**
+ * 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
+ * its existing (inline/text) handling.
+ */
+export function referenceStubOrNull(block: unknown, provenance?: string, serverId?: string): string | null {
+  const c = classifyBlock(block);
+  switch (c.kind) {
+    case 'text': return null;
+    case 'inline':
+      return c.contradiction ? INLINE_WITHHELD_TEXT : null;
+    case 'reference': return buildReferenceStub(c.testimony, provenance, serverId);
+    case 'invalid': return `[unrecognized content block: ${sanitizeLabel(c.reason, STUB_FIELD_CHARS)}]`;
+  }
+}

package/src/mcpl/types.ts

@@ -72,6 +72,12 @@ export interface McplImageContent {
   mimeType?: string;
   /** URI reference (present when using URI form) */
   uri?: string;
+  /** RFC-005 reference testimony (uri form only). */
+  sizeBytes?: number;
+  digest?: string;
+  expiresAt?: string;
+  name?: string;
+  disposition?: 'never' | 'ref';
 }
 
 export interface McplAudioContent {
@@ -82,12 +88,25 @@ export interface McplAudioContent {
   mimeType?: string;
   /** URI reference (present when using URI form) */
   uri?: string;
+  /** RFC-005 reference testimony (uri form only). */
+  sizeBytes?: number;
+  digest?: string;
+  expiresAt?: string;
+  name?: string;
+  disposition?: 'never' | 'ref';
 }
 
 export interface McplResourceContent {
   type: 'resource';
   /** Resource URI (e.g., "memory://facts/12345") */
   uri: string;
+  /** RFC-005 §3 reference testimony (all optional, all server claims). */
+  mimeType?: string;
+  sizeBytes?: number;
+  digest?: string;
+  expiresAt?: string;
+  name?: string;
+  disposition?: 'never' | 'ref';
 }
 
 // ============================================================================
@@ -355,6 +374,10 @@ export interface McplServerConfig {
    * Chronicle and changed with channel_open/channel_close.
    */
   channelSubscription?: 'auto' | 'manual' | string[];
+  /** RFC-005 autofetch envelope for this server: per-fetch eager ceiling and
+   *  cumulative per-server byte budget (reference-fetcher.ts defaults apply
+   *  when absent). */
+  autofetch?: { maxBytes?: number; maxTotalBytes?: number };
 }
 
 // ============================================================================
@@ -1233,4 +1256,10 @@ export interface McpToolResultContent {
   data?: string;
   mimeType?: string;
   uri?: string;
+  /** RFC-005 §3 reference testimony (uri form only; server claims). */
+  sizeBytes?: number;
+  digest?: string;
+  expiresAt?: string;
+  name?: string;
+  disposition?: 'never' | 'ref';
 }

package/src/modules/index.ts

@@ -8,7 +8,8 @@ export type { ApiEvent } from './api/index.js';
 export { HealthModule } from './health/index.js';
 export type { HealthModuleConfig } from './health/index.js';
 
-export { WorkspaceModule } from './workspace/index.js';
+export { WorkspaceModule, WorkspaceReadError } from './workspace/index.js';
+export type { WorkspaceReadErrorCode, WorkspaceReadStage, WorkspaceDiskReadResult, ReadFileFromDiskOptions } from './workspace/index.js';
 export type {
   WorkspaceConfig,
   MountConfig,