@animalabs/agent-framework 0.27.0 → 0.28.0

package/src/heartbeat/reminder-time.ts

@@ -0,0 +1,107 @@
+/**
+ * Reading a reminder's `atIso` in the agent's time zone, ported from heartbeat-mcpl
+ * (src/reminder-time.ts) when the heartbeat moved into the framework: a time
+ * without an offset is read in the zone, and a wall time a clock change skips
+ * or repeats is refused, naming the offsets that would say which instant.
+ */
+const DAY_MS = 86_400_000;
+const MAX_DATE_MS = 8_640_000_000_000_000;
+
+export const FIRST_REMINDER_TIME = '-271821-04-20T00:00:00Z';
+export const LAST_REMINDER_TIME = '+275760-09-13T00:00:00Z';
+
+export function canHoldTime(ms: number): boolean {
+  return Math.abs(ms) <= MAX_DATE_MS;
+}
+
+function isCalendarDay(year: number, month: number, day: number): boolean {
+  if (month < 1 || month > 12 || day < 1) return false;
+  const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+  return day <= [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+}
+
+/** ISO 8601 reads 24:00 as the end of the day. */
+function isClockTime(hour: number, minute: number, second: number, fraction: number): boolean {
+  if (hour === 24) return minute === 0 && second === 0 && fraction === 0;
+  return hour <= 23 && minute <= 59 && second <= 59;
+}
+
+/** Intl names offsets with a GMT prefix, with seconds for the historical ones, and ICU 76,
+ *  which Node 22.12.0 has, names the zero offset GMT alone. */
+function offsetMilliseconds(offset: string): number | null {
+  if (/^(Z|GMT)$/i.test(offset)) return 0;
+  const match = /^(?:GMT)?([+-])(\d{2})(?:(:?)(\d{2})(?:\3(\d{2}))?)?$/.exec(offset);
+  if (!match || +match[2] > 23 || +(match[4] ?? 0) > 59 || +(match[5] ?? 0) > 59) return null;
+  return (match[1] === '-' ? -1 : 1)
+    * (+match[2] * 3600 + +(match[4] ?? 0) * 60 + +(match[5] ?? 0)) * 1000;
+}
+
+export function parseReminderTime(atIso: string, timeZone: string): number {
+  const shown = JSON.stringify(atIso);
+  const parts = /^([+-]\d{6}|\d{4})-(\d{2})-(\d{2})(?:[Tt ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d+))?)?([Zz]|[+-][\d:]+)?)?$/.exec(atIso);
+  // ECMAScript's date-time format refuses -000000 for year zero.
+  if (!parts || parts[1] === '-000000') {
+    throw new Error(`"atIso" ${shown} isn't a time this tool reads. Give a date and time like "2030-07-15T09:00", read in `
+      + `${timeZone}, or end it with an offset, like "2030-07-15T09:00Z" or "2030-07-15T09:00+01:00". A date alone is `
+      + `midnight in ${timeZone}. For a delay from now, give inSeconds, inMinutes or inHours instead.`);
+  }
+  const givenOffset = parts[8] ? offsetMilliseconds(parts[8]) : null;
+  if (parts[8] && givenOffset === null) {
+    throw new Error(`"atIso" ${shown} ends in ${JSON.stringify(parts[8])}, which isn't a UTC offset. `
+      + 'End it with Z for UTC, or an offset like +05:30, +0530 or +05.');
+  }
+  const calendarDate = `${parts[1]}-${parts[2]}-${parts[3]}`;
+  const readIn = parts[8] ? '' : `, read in ${timeZone}`;
+  const example = (time: string) => `"${time}${parts[8] ?? ''}"${readIn}`;
+  if (!isCalendarDay(+parts[1], +parts[2], +parts[3])) {
+    throw new Error(`"atIso" ${shown} names a day the calendar doesn't have, ${calendarDate}. Give a real date, like ${example('2030-03-01T09:00')}.`);
+  }
+  // A Date keeps milliseconds, so digits past them don't count.
+  if (!isClockTime(+(parts[4] ?? 0), +(parts[5] ?? 0), +(parts[6] ?? 0), +(parts[7] ?? '0').slice(0, 3))) {
+    throw new Error(`"atIso" ${shown} has a time no clock shows: hours run 00 to 23 and minutes and seconds 00 to 59, `
+      + `and 24:00, the end of the day, takes no minutes, seconds or milliseconds after it. Give one like ${example(`${calendarDate}T09:00`)}.`);
+  }
+  const outOfRange = new Error(`"atIso" ${shown}${readIn ? `${readIn},` : ''} is outside the times a reminder can hold, `
+    + `${FIRST_REMINDER_TIME} to ${LAST_REMINDER_TIME}. Give a time inside that range.`);
+  // Date.parse reads 24:00 as the start of the next day.
+  const wall = Date.parse(`${calendarDate}T${parts[4] ?? '00'}:${parts[5] ?? '00'}:${parts[6] ?? '00'}.${(parts[7] ?? '0').slice(0, 3).padEnd(3, '0')}Z`);
+  if (!Number.isFinite(Date.parse(`${calendarDate}T00:00:00Z`)) || !Number.isFinite(wall)) throw outOfRange;
+
+  if (givenOffset !== null) {
+    const instant = wall - givenOffset;
+    if (Math.abs(instant) > MAX_DATE_MS) throw outOfRange;
+    return instant;
+  }
+
+  const asTime = parts[4] === undefined ? `${calendarDate}T00:00` : atIso;
+  const withOffsets = (labels: string[]) => labels.map((label) => JSON.stringify(`${asTime}${label}`)).join(' or ');
+  const formatter = new Intl.DateTimeFormat('en-US', { timeZone, timeZoneName: 'longOffset' });
+  const offsetAt = (ms: number) => {
+    const name = formatter.formatToParts(new Date(ms)).find((part) => part.type === 'timeZoneName')?.value;
+    const offset = name ? offsetMilliseconds(name) : null;
+    if (!name || offset === null) {
+      throw new Error(`"atIso" ${shown} has no offset, and the zone it would be read in, ${timeZone}, can't be read here. `
+        + `End it with an offset, like ${withOffsets(['Z', '+01:00'])}, or give a delay from now in inSeconds, inMinutes or inHours.`);
+    }
+    return { ms: offset, label: name === 'GMT' ? '+00:00' : name.slice(3) };
+  };
+
+  // Around a clock change a wall time has no instant (a gap) or two (a fold).
+  const offsets = new Map<number, string>();
+  for (const delta of [-DAY_MS, DAY_MS]) {
+    const sample = Math.abs(wall + delta) <= MAX_DATE_MS ? wall + delta : wall;
+    const offset = offsetAt(sample);
+    offsets.set(offset.ms, offset.label);
+  }
+  const inRange = [...offsets].filter(([offset]) => Math.abs(wall - offset) <= MAX_DATE_MS);
+  if (inRange.length === 0) throw outOfRange;
+  const candidates = inRange.filter(([offset]) => offsetAt(wall - offset).ms === offset);
+  if (candidates.length === 1) return wall - candidates[0][0];
+  const read = parts[4] === undefined ? `${shown} is read as ${asTime}, which` : shown;
+  if (candidates.length > 1) {
+    throw new Error(`"atIso" ${read} happens twice in ${timeZone}, where the clocks go back over it. `
+      + `End it with the offset you mean: ${withOffsets(candidates.map(([, label]) => label))}.`);
+  }
+  throw new Error(`"atIso" ${read} doesn't exist in ${timeZone}, where the clocks skip over it. Give a time that exists `
+    + `there, or end it with an offset to say which instant you mean, like ${withOffsets([...offsets.values()])}.`);
+}

package/src/index.ts

@@ -70,6 +70,10 @@ export type { SessionUsage, AgentUsage, SessionUsageSnapshot, UsageUpdatedEvent
 // EventGate
 export { EventGate, wakeLineText, type WakeProvenance, type WritePlacement } from './gate/index.js';
 export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior, WakeLine } from './gate/index.js';
+export { ReplyJudge, DEFAULT_JUDGE_MODEL, DEFAULT_JUDGE_MAX_INPUT_TOKENS, MIN_JUDGE_INPUT_TOKENS } from './gate/index.js';
+export type { JudgeConfig, JudgeEventSummary, JudgeFn, JudgeRequest, JudgeVerdict, ReplyJudgeOptions, ReplyJudgeDeps, UpcomingWake } from './gate/index.js';
+export { Heartbeat, DEFAULT_HEARTBEAT, HEARTBEAT_TOOL_PREFIX } from './heartbeat/heartbeat.js';
+export type { HeartbeatOptions, HeartbeatSettings, HeartbeatWake, HeartbeatDeliveryMode, Reminder } from './heartbeat/heartbeat.js';
 
 // MCPL channel registry (exposed for modules that need channel-level operations)
 export { ChannelRegistry } from './mcpl/index.js';

package/src/mcpl/capability-mask.ts

@@ -81,8 +81,9 @@ function anyMatches(patterns: string[], path: string): boolean {
   return patterns.some((pattern) => patternMatchesPath(pattern, path));
 }
 
-/** Keys that are negotiation metadata, not grantable capabilities. */
-const UNMASKABLE_KEYS = new Set(['version', 'featureSets']);
+/** Keys that are negotiation metadata, or RFC-014 declarations (toolHints,
+ *  toolsets, surface), not grantable capabilities. */
+const UNMASKABLE_KEYS = new Set(['version', 'featureSets', 'toolHints', 'toolsets', 'surface']);
 
 /**
  * Interior object paths whose object value is itself the capability, with

package/src/mcpl/channel-registry.ts

@@ -1909,7 +1909,8 @@ export class ChannelRegistry {
       const incomingEntry = this.channels.get(incomingKey)!;
       const markAccepted = (firstView = false) => {
         // Non-conversational markers (a reaction added or removed, an edit, a
-        // deletion) are ABOUT a message, not one the agent replies to: they
+        // deletion, and a chat:system notice such as a join or the weather)
+        // are ABOUT a message or the place, not one the agent replies to: they
         // must not retarget the default publish locus or become
         // `context.incoming`'s reply anchor. An edit the coalescer delivered
         // as the agent's first view counts as the message it replaced.

package/src/mcpl/inbound-source.ts

@@ -22,6 +22,8 @@
  */
 
 import { createHash } from 'node:crypto';
+import { blockAsStored, MalformedContentError } from '@animalabs/context-manager';
+import { logDetail, logValue } from './log-value.js';
 
 /** The MCPL admission lane that accepted an item. Its contract decides what
  *  an `eventId` is worth: `push/event` deduplicates by eventId, and RFC-006
@@ -192,68 +194,23 @@ export function canonicalJson(value: unknown): string {
 }
 
 /**
- * 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.
+ * blockAsStored throws a `MalformedContentError` for a block the store
+ * refuses on write, a caller-supplied `blob_ref` among them. Such a block
+ * has no stored form, and whatever is thrown, it is digested as given.
  */
 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';
+  try {
+    return blockAsStored(block as Parameters<typeof blockAsStored>[0]);
+  } catch (err) {
+    if (!(err instanceof MalformedContentError)) {
+      const { name, message } = (err ?? {}) as { name?: unknown; message?: unknown };
+      console.error(
+        `[stored-digest-as-given] error=${logValue(typeof name === 'string' ? name : typeof err)}: ` +
+        logDetail(typeof message === 'string' ? message : ''),
+      );
+    }
+    return block;
   }
-  return null;
 }
 
 /**
@@ -261,23 +218,39 @@ function sniffRasterImageMediaType(bytes: Uint8Array): string | null {
  * 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.
+ * each block as the store keeps it, which context-manager's `blockAsStored`
+ * gives. So a body hashes alike as delivered, as handed to storage, and as
+ * read back unsharded from the store with its blobs resolved, except one
+ * whose blocks the store changes together: when it mends a `tool_use` whose
+ * input isn't an object, it also releases a raw replay form (`rawXml`,
+ * `rawItem`) that the message's other blocks share, which no one block's
+ * stored form shows. A body an MCPL lane stamps is never one. A block the
+ * store refuses on write, a `blob_ref` among them, is digested as given. 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 where the store keeps the body as it did then.
+ *
+ * A digest is a digest under the context-manager release that computed it: a
+ * release that changes what the store keeps, such as its set of image
+ * signatures, changes the digest of a body it touches.
  *
  * 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
+ * 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.
+ * metadata), or holds blocks the store changes together, or its digest was
+ * taken under a release that kept some block of it differently: a
+ * context-manager release that changed a stored form, or an agent-framework
+ * release from 0.24.0 up to the one that brought in blockAsStored, which
+ * took stored forms from a copy of the store's transform. Digests already
+ * stamped are never recomputed. 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.

package/src/mcpl/server-connection.ts

@@ -240,19 +240,29 @@ export function toolsetDeclarationsOf(advertised: unknown): Record<string, unkno
 /** What the RFC-014 read tap is handed as the connection reads a message
  *  that can carry hint changes (see McplServerConnection.setReadTap). */
 export type HintRead =
-  /** A response to a request that can carry hints (RFC-014 §6.1 carrier 1).
-   *  `awaited`: whoever sent it still waits for it; false for a result that
-   *  arrives after its timeout. A JSON-RPC error carries no state and isn't
-   *  tapped. */
-  | { kind: 'result'; method: string; params: Record<string, unknown>; result: unknown; awaited: boolean }
+  /** A response to a request that can carry hints (RFC-014 §6.1 carrier 1),
+   *  or a `tools/list`'s whole inventory (§4.1), its pages joined by
+   *  sendToolsList, `straddled` when its pages carry different revs.
+   *  `awaited`: whoever sent it still waits for it; false for a
+   *  result that arrives after its timeout. A JSON-RPC error carries no state
+   *  and isn't tapped. */
+  | { kind: 'result'; method: string; params: Record<string, unknown>; result: unknown; awaited: boolean; straddled?: boolean }
   /** A push/event (carrier 2), as read, before the plane gate or the grant
    *  admit or refuse it. */
   | { kind: 'push'; params: unknown }
   /** A standalone tools/hints (carrier 3). */
   | { kind: 'hints'; params: unknown };
 
-/** Requests whose results can carry hint state (RFC-014 §6.1, §4.1). */
-const HINTED_METHODS: ReadonlySet<string> = new Set(['tools/call', 'toolsets/open', 'toolsets/close', 'toolsets/list', 'tools/list']);
+/** Requests whose results can carry hint state, remembered for a late answer (RFC-014 §6.1). */
+const HINTED_METHODS: ReadonlySet<string> = new Set(['tools/call', 'toolsets/open', 'toolsets/close', 'toolsets/list']);
+
+function hintedParams(method: string, params: Record<string, unknown>): { toolset?: string; instance?: string } {
+  if (method !== 'toolsets/open' && method !== 'toolsets/close') return {};
+  return {
+    ...(typeof params.toolset === 'string' ? { toolset: params.toolset } : {}),
+    ...(typeof params.instance === 'string' ? { instance: params.instance } : {}),
+  };
+}
 
 /**
  * A handshake that failed, and whose cleanup couldn't confirm that the child
@@ -330,6 +340,7 @@ interface PendingRequest {
   resolve: (result: unknown) => void;
   reject: (error: Error) => void;
   method: string;
+  onRead?: (result: unknown) => void;
   /** Per-request timeout timer; cleared on response/close/timeout. */
   timer?: ReturnType<typeof setTimeout>;
 }
@@ -339,6 +350,9 @@ interface RequestOptions {
   timeoutMs?: number;
   /** Surface a late response even when it carries no checkpoint state. */
   surfaceOrphanedResponse?: boolean;
+  /** Called with a successful result as its response is read, before
+   *  anything read after it and before the request's promise settles. */
+  onRead?: (result: unknown) => void;
 }
 
 /** A server→host message held while its plane is closed. `kept`: it came on
@@ -452,15 +466,18 @@ export class McplServerConnection extends EventEmitter {
    * the message: a push the plane holds or the grant refuses, a result its
    * caller stopped waiting for. The tap sees every such message of the
    * current transport, synchronously, before anything routes it; a late
-   * answer's request is remembered past its timeout (hintedRequests) so its
-   * hints still apply. Null (the default) taps nothing, and the connection
+   * answer's request is remembered past its timeout (hintedRequests, while
+   * no more than 1,000 hinted requests await an answer) so its hints still
+   * apply. Null (the default) taps nothing, and the connection
    * behaves as it always has.
    */
   private readTap: ((read: HintRead, epoch: number) => void) | null = null;
   /** The hinted requests sent on this transport, by id, kept past a timeout
-   *  so a late result is still tapped; bounded. Cleared at each boundary,
+   *  so a late result is still tapped: each one's method, and an open's or
+   *  close's toolset and instance, which are all the read of its result
+   *  uses; never a call's arguments. Bounded. Cleared at each boundary,
    *  since the next transport numbers its requests afresh. */
-  private hintedRequests = new Map<string | number, { method: string; params: Record<string, unknown> }>();
+  private hintedRequests = new Map<string | number, { method: string; params: { toolset?: string; instance?: string } }>();
 
   /** Install (or, with null, remove) the RFC-014 read tap (see readTap). */
   setReadTap(tap: ((read: HintRead, epoch: number) => void) | null): void {
@@ -1708,22 +1725,40 @@ export class McplServerConnection extends EventEmitter {
    * read it as a complete page). A page that isn't well formed (no `tools` array, a cursor
    * that isn't a string), or cursors that don't terminate (a repeat, or more
    * than {@link MAX_TOOL_LIST_PAGES} pages), are errors, never a partial or
-   * empty inventory published as complete.
+   * empty inventory published as complete. The read tap (RFC-014) is handed
+   * the complete inventory once, with the last page's `_meta`, as the last
+   * page's response is read, before anything read after it; a list that
+   * fails or times out hands it nothing. It's `straddled` when its pages
+   * carry different `mcpl/rev`s.
    */
   async sendToolsList(): Promise<{ tools: McpToolDefinition[] }> {
     const tools: McpToolDefinition[] = [];
     const seen = new Set<string>();
     let cursor: string | undefined;
     let first: Record<string, unknown> | undefined;
+    const read: McpToolDefinition[] = [];
+    const revs = new Set<unknown>();
+    const onRead = (result: unknown) => {
+      if (!result || typeof result !== 'object' || !Array.isArray((result as { tools?: unknown }).tools)) return;
+      const r = result as { tools: McpToolDefinition[]; nextCursor?: unknown; _meta?: unknown };
+      for (const t of r.tools) read.push(t);
+      const rev = (r._meta as Record<string, unknown> | undefined)?.['mcpl/rev'];
+      if (typeof rev === 'number') revs.add(rev);
+      if (r.nextCursor !== undefined && r.nextCursor !== null) return;
+      this.tap({
+        kind: 'result', method: 'tools/list', params: {}, ...(revs.size > 1 ? { straddled: true } : {}),
+        result: { tools: read, ...(r._meta !== undefined ? { _meta: r._meta } : {}) }, awaited: true,
+      });
+    };
     for (let page = 0; page < MAX_TOOL_LIST_PAGES; page++) {
-      const result = await this.sendRequest('tools/list', cursor === undefined ? {} : { cursor }) as Record<string, unknown> | null;
+      const result = await this.sendRequest('tools/list', cursor === undefined ? {} : { cursor }, { onRead }) as Record<string, unknown> | null;
       const malformed = (why: string) =>
         new Error(`MCPL server "${this.id}" sent a malformed tools/list page ${page + 1}: ${why}`);
       if (!result || typeof result !== 'object' || !Array.isArray(result.tools)) {
         throw malformed('no tools array');
       }
       first ??= result;
-      tools.push(...(result.tools as McpToolDefinition[]));
+      for (const t of result.tools as McpToolDefinition[]) tools.push(t);
       if (result.nextCursor === undefined || result.nextCursor === null) {
         // The first page's other fields are kept as they came, so a
         // single-page answer is returned exactly as before.
@@ -2176,7 +2211,7 @@ export class McplServerConnection extends EventEmitter {
     }
 
     return new Promise((resolve, reject) => {
-      const pending: PendingRequest = { resolve, reject, method };
+      const pending: PendingRequest = { resolve, reject, method, ...(options.onRead ? { onRead: options.onRead } : {}) };
       const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
       if (timeoutMs > 0) {
         pending.timer = setTimeout(() => {
@@ -2218,7 +2253,7 @@ export class McplServerConnection extends EventEmitter {
       // RFC-014: a request whose result can carry hints is remembered past
       // its timeout, so a late result's hints still apply (readTap).
       if (this.readTap && HINTED_METHODS.has(method)) {
-        this.hintedRequests.set(id, { method, params });
+        this.hintedRequests.set(id, { method, params: hintedParams(method, params) });
         if (this.hintedRequests.size > 1000) this.hintedRequests.delete(this.hintedRequests.keys().next().value!);
       }
       try {
@@ -2654,6 +2689,11 @@ export class McplServerConnection extends EventEmitter {
         logValueRedacted(response.error.message, redact),
       );
     } else {
+      try {
+        pending.onRead?.(response.result);
+      } catch (error) {
+        console.error(`MCPL server "${this.id}": reading ${pending.method}'s result failed: ${logDetail(describeCause(error))}`);
+      }
       pending.resolve(response.result);
     }
   }

package/src/mcpl/tags.ts

@@ -21,8 +21,10 @@ const CORE_IMPLIES: Readonly<Record<string, readonly string[]>> = {
 /**
  * RFC-001 core tags that mark a message as being ABOUT the conversation
  * rather than part of it: reactions (added or removed), edits and deletions
- * of an existing message. These are markers, not turns — they must not clear
- * explicit-send suppression, count as a new conversational round, or
+ * of an existing message, and (revision 3) `chat:system` notices from the
+ * platform or the place: a join, a pin, the weather changing in a world.
+ * These are markers, not turns — they must not clear explicit-send
+ * suppression, count as a new conversational round, or
  * retarget the default publish channel. An edit can also be the first
  * version of a message the agent sees, and then counts as that message:
  * isMarkerTagged reads the host's mark for the case the coalescer knows
@@ -36,6 +38,7 @@ export const NON_CONVERSATIONAL_TAGS: ReadonlySet<string> = new Set([
   'chat:reaction-remove',
   'chat:edited',
   'chat:deleted',
+  'chat:system',
 ]);
 
 /** True when a (possibly untyped) tag list carries a non-conversational marker tag. */
@@ -54,11 +57,19 @@ export function isMarkerTagged(tags: unknown, firstView: boolean): boolean {
   return hasNonConversationalTag(firstView && Array.isArray(tags) ? tags.filter((t) => t !== 'chat:edited') : tags);
 }
 
+/** True when a (possibly untyped) tag list marks a `chat:system` notice: an
+ *  event about the place, not a message anyone sent (RFC-001 rev 3). */
+export function isSystemNotice(tags: unknown): boolean {
+  return Array.isArray(tags) && tags.includes('chat:system');
+}
+
 /**
  * Expand a raw tag list over the normative core closure, then resolve the
  * §16.2 mutual exclusion: `chat:addressed` and `chat:ambient` cannot both
  * stand after expansion, and addressed wins — a message that is both
  * specifically-to-you and background noise is specifically-to-you.
+ * `chat:system` is another facet (kind, not addressing) and stands beside
+ * either: a pin in a DM is addressed by its place and still a notice.
  *
  * Pure; input order is preserved for the tags that survive, with implied
  * tags appended in first-cause order. Unknown and producer-namespaced tags