@animalabs/agent-framework 0.26.1 → 0.27.0

package/src/mcpl/conversation-router.ts

@@ -37,6 +37,7 @@
 import { createHash } from 'node:crypto';
 import type { ContextStrategy } from '@animalabs/context-manager';
 import type { ChannelDescriptor } from './types.js';
+import { destinationKey, type ChannelRef } from './channel-registry.js';
 
 // ============================================================================
 // Config & types
@@ -108,6 +109,9 @@ export interface ConversationRouterConfig {
 
 export interface ConversationBinding {
   channelId: string;
+  /** The channel's server: 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;
@@ -157,11 +161,15 @@ export const DEFAULT_CLOSURE_PROMPT =
 export class ConversationRouter {
   private config: ConversationRouterConfig;
 
-  /** Active bindings, keyed by channelId. */
+  /** Active bindings, keyed by the channel's server and id (destinationKey):
+   *  two servers' channels with one id are two conversations. */
   private bindings = new Map<string, ConversationBinding>();
 
-  /** Engagement counter per channel — survives unbind, so a re-bound channel
-   * gets a distinct fork agent name. */
+  /** 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). */
   private generations = new Map<string, number>();
 
   constructor(config: ConversationRouterConfig) {
@@ -191,7 +199,7 @@ export class ConversationRouter {
    * unchanged; a failed spawn doesn't leave a dangling route.
    */
   route(facts: IncomingMessageFacts): RoutingDecision {
-    const existing = this.bindings.get(facts.channelId);
+    const existing = this.bindings.get(bindingKey({ serverId: facts.serverId ?? '', channelId: facts.channelId }));
 
     if (existing) {
       return {
@@ -223,39 +231,44 @@ export class ConversationRouter {
    * Record a binding after the framework successfully spawned the fork.
    * Returns the new binding.
    */
-  bind(channelId: string, agentName: string, generation: number, now = Date.now()): ConversationBinding {
-    this.generations.set(channelId, generation);
+  bind(channel: ChannelRef, agentName: string, generation: number, now = Date.now()): ConversationBinding {
+    // The counter is kept by bare id, and two servers' spawns on one id 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(channel.channelId, Math.max(this.generations.get(channel.channelId) ?? 0, generation));
     const binding: ConversationBinding = {
-      channelId,
+      channelId: channel.channelId,
+      serverId: channel.serverId,
       agentName,
       generation,
       boundAt: now,
       lastActivity: now,
     };
-    this.bindings.set(channelId, binding);
+    this.bindings.set(bindingKey(channel), 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(channelId: string, now = Date.now()): void {
-    const binding = this.bindings.get(channelId);
+  touch(channel: ChannelRef, now = Date.now()): void {
+    const binding = this.bindings.get(bindingKey(channel));
     if (binding) binding.lastActivity = now;
   }
 
-  unbind(channelId: string): void {
-    this.bindings.delete(channelId);
+  unbind(channel: ChannelRef): void {
+    this.bindings.delete(bindingKey(channel));
   }
 
-  getBinding(channelId: string): ConversationBinding | undefined {
-    return this.bindings.get(channelId);
+  getBinding(channel: ChannelRef): ConversationBinding | undefined {
+    return this.bindings.get(bindingKey(channel));
   }
 
   /** Reverse lookup: the channel an agent is bound to, if any. */
-  channelForAgent(agentName: string): string | undefined {
+  channelForAgent(agentName: string): ChannelRef | undefined {
     for (const binding of this.bindings.values()) {
-      if (binding.agentName === agentName) return binding.channelId;
+      if (binding.agentName === agentName) return { serverId: binding.serverId, channelId: binding.channelId };
     }
     return undefined;
   }
@@ -325,6 +338,11 @@ export class ConversationRouter {
 /** The readable part of a fork's name stops here: uniqueness rides on the hash. */
 const FORK_NAME_READABLE_MAX = 64;
 
+/** A binding's key: its channel's server and id (destinationKey). */
+function bindingKey(channel: ChannelRef): string {
+  return destinationKey(channel);
+}
+
 /**
  * A fork's agent name: `<prefix>-<readable>-g<generation>-<hash>`, such as
  * `conversation-C123-g2-e08e564271867d16` for Slack's channel `C123` on the

package/src/mcpl/convert-block.ts

@@ -11,6 +11,7 @@ import {
   IMAGE_NO_DATA_TEXT,
   IMAGE_NO_MEDIA_TYPE_TEXT,
   INLINE_WITHHELD_TEXT,
+  classifyBlock,
   isInlineContradiction,
   referenceStubOrNull,
   unknownBlockText,
@@ -85,12 +86,24 @@ export function convertBlock(block: McplContentBlock, provenance: string, server
       }
       return { type: 'text', text: isFilledString(block.data) ? AUDIO_NO_MEDIA_TYPE_TEXT : AUDIO_NO_DATA_TEXT };
 
-    case 'resource':
+    case 'resource': {
+      // MCP's embedded resource shows as the block its contents make would
+      // show here (RFC-005 §8.1), its uri never.
+      const c = classifyBlock(block);
+      if (c.kind === 'embedded' && c.contents.kind === 'block') {
+        return convertBlock(c.contents.block as McplContentBlock, provenance, serverId);
+      }
       // RFC-005: reference blocks become bounded stubs — never raw URIs
       // (a signed URL is a bearer credential that looks like a location).
       return { type: 'text', text: referenceStubOrNull(block, provenance, serverId) ?? '[reference]' };
+    }
 
     default: {
+      // MCP's link to a resource isn't one of MCPL's own blocks, but a server
+      // can send one, and RFC-005 §8.1 makes it a reference, shown as one.
+      if ((block as { type?: unknown }).type === 'resource_link') {
+        return { type: 'text', text: referenceStubOrNull(block, provenance, serverId) ?? '[reference]' };
+      }
       // Unknown wire block types previously fell off the exhaustive switch
       // and propagated `undefined` into ContentBlock[]. Fail visibly. A type
       // that isn't a string is no type, and is never converted to one: an

package/src/mcpl/hook-orchestrator.ts

@@ -71,7 +71,9 @@ function convertContent(content: string | McplContentBlock[], serverId: string):
 
 /**
  * Convert an MCPL wire-format context injection, from the server `serverId`,
- * to a context-manager ContextInjection.
+ * to a context-manager ContextInjection. It builds only these four fields,
+ * so a server can't opt an injection out of being stored
+ * (ModuleContextInjection.placedEachCompile, which only a module may set).
  */
 function convertMcplInjection(mcplInj: McplContextInjection, serverId: string): ContextInjection {
   return {
@@ -114,8 +116,17 @@ export class HookOrchestrator {
    *
    * Returns aggregated ContextInjection[] ready for context-manager's compile().
    * Fail-open: servers that time out or error are silently skipped.
+   *
+   * `channelsFor` gives each server its own channel context (§14.4), in
+   * place of `params.channels`: channel ids are unique only within one
+   * server's connection (§14.2), so each server is told only of its own
+   * channels (ChannelRegistry.buildChannelContext). Undefined from it leaves
+   * the field out for that server.
    */
-  async beforeInference(params: BeforeInferenceParams): Promise<ContextInjection[]> {
+  async beforeInference(
+    params: BeforeInferenceParams,
+    channelsFor?: (serverId: string) => BeforeInferenceParams['channels'],
+  ): Promise<ContextInjection[]> {
     // §5.4: the GRANT decides fan-out, not the raw advertisement — which
     // also fixes selection for the recursive §5.1 shape, where
     // `beforeInference: {observe: true, …}` is an object, not `true`. A
@@ -132,7 +143,7 @@ export class HookOrchestrator {
 
     this._isInHook = true;
     try {
-      return await this.fanOutBeforeInference(servers, params);
+      return await this.fanOutBeforeInference(servers, params, channelsFor);
     } finally {
       this._isInHook = false;
     }
@@ -163,17 +174,33 @@ export class HookOrchestrator {
   private async fanOutBeforeInference(
     servers: McplServerConnection[],
     params: BeforeInferenceParams,
+    channelsFor?: (serverId: string) => BeforeInferenceParams['channels'],
   ): Promise<ContextInjection[]> {
     const results = await Promise.allSettled(
-      servers.map((server) => {
+      // Async, so a throw building one server's channel context fails that
+      // server alone, as its timeout or transport error would.
+      servers.map(async (server) => {
+        let base = params;
+        if (channelsFor) {
+          const { channels: _shared, ...rest } = params;
+          let channels: BeforeInferenceParams['channels'];
+          try {
+            channels = channelsFor(server.id);
+          } catch (err) {
+            // A bug, not a server's failure: said, then this server is skipped.
+            console.error(`[beforeInference] the channel context for "${server.id}" couldn't be built, so it isn't called:`, err);
+            throw err;
+          }
+          base = channels ? { ...rest, channels } : rest;
+        }
         // §10.1: a server not granted observe MUST receive
         // `userMessage: null` — the field is ABSENT authority, not merely
         // discouraged — while the hook is still invoked so granted
         // injection positions keep working (write-without-read).
         const perServer: BeforeInferenceParams =
           CapabilityGrant.of(server).has('contextHooks.beforeInference.observe')
-            ? params
-            : { ...params, userMessage: null };
+            ? base
+            : { ...base, userMessage: null };
         return withTimeout(
           server.sendBeforeInference(perServer),
           BEFORE_INFERENCE_TIMEOUT_MS,

package/src/mcpl/index.ts

@@ -88,6 +88,11 @@ export type {
 } from './types.js';
 
 export { McplMethod } from './types.js';
+// RFC-014 tool presence and toolsets (host side).
+export { ToolsetHub, ToolsetController, TOOLSETS_MODULE, META_TOOL_NAMES } from './toolset-host.js';
+export { ToolsetsModule, TOOLSETS_REMINDER_NAMESPACE } from './toolsets-module.js';
+export { ToolPresence } from './tool-presence.js';
+export type { ChangeSet, MetaToolNames, ToolsetDecl } from './tool-presence.js';
 
 // Error codes and factories
 export {
@@ -171,7 +176,7 @@ 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';
+export type { ChannelRef, PublishRefusalReason } from './channel-registry.js';
 
 // Inbound source envelope: where each accepted item came from, stamped once;
 // and the digest of a delivered or stored body

package/src/mcpl/inference-router.ts

@@ -26,6 +26,7 @@ import type {
 import type { FeatureSetManager } from './feature-set-manager.js';
 import { McplFeatureSetError } from './feature-set-manager.js';
 import type { HookOrchestrator } from './hook-orchestrator.js';
+import { logValue } from './log-value.js';
 
 // ============================================================================
 // Responder interface
@@ -181,6 +182,10 @@ export class InferenceRouter {
   private featureSetManager: FeatureSetManager;
   private routingPolicy: InferenceRoutingPolicy | null;
   private emitTraceFn: (event: { type: string; [key: string]: unknown }) => void;
+  /** The refusals for want of a model that have been logged: one line per
+   *  server with no policy, and per server and feature set with one, so a
+   *  server that keeps asking doesn't flood the operator's log. */
+  private loggedRefusals = new Set<string>();
 
   constructor(
     membrane: Membrane,
@@ -201,7 +206,7 @@ export class InferenceRouter {
    *
    * 1. Validate feature set
    * 2. Check loop prevention (reject if inside a hook)
-   * 3. Resolve model from routing policy
+   * 3. Resolve model from routing policy, refusing when it names none
    * 4. Build membrane request
    * 5. Run inference, streaming its visible text as chunks when asked
    * 6. Answer with the result, or with the error for any ending that isn't
@@ -233,11 +238,62 @@ export class InferenceRouter {
       return;
     }
 
-    // 3. Resolve model
+    // Streaming needs a way to send chunks and an id to tag them with;
+    // without either, the request is answered whole.
+    const sendChunk = params.stream ? responder.sendChunk?.bind(responder) : undefined;
+    const chunkRequestId = sendChunk ? responder.requestId : undefined;
+    const streamed = chunkRequestId != null;
+
+    // 3. Resolve model. With no routing policy, or one that names no model
+    // for this feature set, the operator has chosen no model for this
+    // server's inference: refused rather than guessed, since a model picked
+    // here would run, on whatever credentials and at whatever price it
+    // carries, for a server the operator never chose it for. The answer is
+    // -32603, the code the router answers a failed inference with, as it
+    // answered this request when it reached the provider with no model; the
+    // server's grant can still list inferenceRequest, so not -32002.
     const model = this.resolveModel(
       params.featureSet,
       params.conversationId,
     );
+    if (model === undefined) {
+      const policy = Boolean(this.routingPolicy);
+      // One reason, quoted for where it goes: JSON for the server, logValue
+      // for the host log.
+      const reason = (quote: (value: string) => string) => policy
+        ? `the inference routing policy (inferenceRouting) names no model for feature set ${quote(params.featureSet)}`
+        : 'the host sets no inference routing policy (inferenceRouting)';
+      const message = `inference/request refused: ${reason(JSON.stringify)}, so the host has no model to run it on; ` +
+        "it stays refused until the host's operator configures one";
+      // Logged once per server with no policy, and once per server and
+      // feature set with one, since each feature set the policy misses is
+      // its own entry to add; validateInbound (step 1) bounds feature sets
+      // to those the server declares.
+      const key = JSON.stringify(policy ? [serverId, params.featureSet] : [serverId]);
+      if (!this.loggedRefusals.has(key)) {
+        this.loggedRefusals.add(key);
+        console.error(
+          `[mcpl] ${logValue(serverId)}: inference/request refused: ${reason(logValue)}; ` +
+            (policy
+              ? 'give it a default, or a byFeature or wildcards entry for that feature set. ' +
+                'This line prints once per server and feature set'
+              : 'set inferenceRouting in the framework config to choose the model server-initiated inference runs on. ' +
+                'This line prints once per server') +
+            '; later refusals are answered and traced but not logged.',
+        );
+      }
+      // The failure a trace watcher saw when this request failed at the
+      // provider, still seen; no inference_start, since none started.
+      this.emitTraceFn({
+        type: 'mcpl:inference_fail',
+        serverId,
+        model: null,
+        error: message,
+        streamed,
+      });
+      responder.respondError(-32603, message);
+      return;
+    }
 
     // Emit trace: inference start
     this.emitTraceFn({
@@ -263,12 +319,6 @@ export class InferenceRouter {
       },
     };
 
-    // Streaming needs a way to send chunks and an id to tag them with;
-    // without either, the request is answered whole.
-    const sendChunk = params.stream ? responder.sendChunk?.bind(responder) : undefined;
-    const chunkRequestId = sendChunk ? responder.requestId : undefined;
-    const streamed = chunkRequestId != null;
-
     try {
       // 5. Run inference. Both modes end in membrane's response, and one
       // builder makes the result from it.
@@ -325,37 +375,32 @@ export class InferenceRouter {
    * 2. Exact feature set match
    * 3. Wildcard pattern match (first match wins)
    * 4. Default from policy
-   * 5. Fallback string 'default'
+   *
+   * Only an entry naming a model counts: one that is empty or not a string
+   * names none and is passed over, as a missing one is. That includes what a
+   * server-sent conversation id or feature set such as `constructor` or
+   * `__proto__` finds on Object.prototype, which is never a string. A
+   * conversation id that is falsy reads no override.
+   *
+   * Undefined with no policy, or when none of these names a model: the
+   * request is then refused.
    */
   private resolveModel(
     featureSet: string,
     conversationId?: string,
-  ): string {
-    if (!this.routingPolicy) {
-      return 'default';
+  ): string | undefined {
+    const policy = this.routingPolicy;
+    if (!policy) {
+      return undefined;
     }
-
-    // Check per-conversation override
-    if (conversationId && this.routingPolicy.overrides?.[conversationId]) {
-      return this.routingPolicy.overrides[conversationId];
-    }
-
-    // Check exact feature set match
-    if (this.routingPolicy.byFeature?.[featureSet]) {
-      return this.routingPolicy.byFeature[featureSet];
-    }
-
-    // Check wildcard patterns
-    if (this.routingPolicy.wildcards) {
-      for (const [pattern, matchedModel] of Object.entries(this.routingPolicy.wildcards)) {
-        if (wildcardMatch(pattern, featureSet)) {
-          return matchedModel;
-        }
-      }
-    }
-
-    // Default
-    return this.routingPolicy.default;
+    const named = (value: unknown): string | undefined =>
+      typeof value === 'string' && value !== '' ? value : undefined;
+
+    return (conversationId ? named(policy.overrides?.[conversationId]) : undefined)
+      ?? named(policy.byFeature?.[featureSet])
+      // First wildcard that matches and names a model.
+      ?? Object.entries(policy.wildcards ?? {}).find(([pattern, m]) => named(m) && wildcardMatch(pattern, featureSet))?.[1]
+      ?? named(policy.default);
   }
 
   // ==========================================================================

package/src/mcpl/prose-grammar.ts

@@ -19,6 +19,13 @@ export interface ProsePrefix {
   body: string;
 }
 
+/** Whether a `>>` (or `>>>`) prefix line reads `name` as a target: one token,
+ *  and not `skip_reply`, which the line reads as private speech. For a name
+ *  offered to an agent to write after `>>`. */
+export function isProseTargetToken(name: string): boolean {
+  return /^\S+$/.test(name) && name !== 'skip_reply';
+}
+
 /** A REAL prefix line: `>>` immediately followed by a target token. */
 export const PROSE_PREFIX_LINE = /^>>\S/;
 

package/src/mcpl/protocol-family.ts

@@ -641,6 +641,8 @@ function isPlainRecord(value: unknown): value is Record<string, unknown> {
 export function mcplPolicyGrants(config: McplServerConfig): string[] {
   const grants: string[] = [];
   if (isEffective(config.allowHostCommands)) grants.push('allowHostCommands');
+  // RFC-014 tool hints are an MCPL advertisement.
+  if (config.toolHints === true) grants.push('toolHints');
   // An allow-list, except that a pattern matching a path denied by default
   // grants it (computeGrant's explicitlyEnabled), named by the path.
   const enabled = config.enabledCapabilities as unknown;

package/src/mcpl/push-coalescer.ts

@@ -127,6 +127,14 @@ interface DeferredBatch<E> {
   latest: CoalescedOccurrence<E>;
   notices: DeferredNotice[];
   dropped: number;
+  /** Every notice folded into the batch, a dropped one included, and a
+   *  plain occurrence a notice displaced unread (Occupant.ambient), was
+   *  tagged `chat:ambient` (RFC-001), so its render asks nothing of the agent
+   *  (CoalescerHost.wakeToRead). Snapshots carry it. A batch restored
+   *  without it, from a snapshot written before it existed or from an
+   *  acceptance receipt, which doesn't carry it, reads as not all ambient:
+   *  the side that keeps a wake. */
+  allAmbient?: true;
   /** Set on a batch restored from a snapshot whose render may have started. */
   noRender?: boolean;
   /** The batch opened on the agent's first view of its subject: a fresh
@@ -184,10 +192,22 @@ interface Occupant {
    *  render that joins a run finds a version placed. In memory only: a
    *  snapshot's occupant comes back as read. */
   firstView?: true;
+  /** A plain occurrence its server tagged `chat:ambient`. A notice that
+   *  displaces it unread stands its batch's render in its place, so that
+   *  render is all ambient only if this was (DeferredBatch.allAmbient). In
+   *  memory only, as `firstView`: a snapshot's occupant comes back as read,
+   *  and only an unread one is displaced. */
+  ambient?: true;
   /** The run's earlier renders, oldest first, each placed ahead of this one. */
   before?: Array<Omit<Occupant, 'before'>>;
 }
 
+/** An occupant's `ambient` mark, for a plain occurrence its server tagged
+ *  `chat:ambient`. */
+function ambientOccupant(occurrence: { tags?: string[] }): { ambient?: true } {
+  return occurrence.tags?.includes('chat:ambient') === true ? { ambient: true } : {};
+}
+
 /** The occupant holding a run's renders, given oldest first: the newest,
  *  carrying the rest as `before`. */
 function runOf(members: Array<Omit<Occupant, 'before'>>): Occupant | undefined {
@@ -246,7 +266,7 @@ export interface CoalescingSnapshot {
     firstViewEnded?: true;
     /** `firstView` only on a batch that wasn't rendering: one that was may
      *  have been shown. */
-    batch?: { latest: CoalescedOccurrence<unknown>; notices: DeferredNotice[]; dropped: number; rendering?: boolean; firstView?: true };
+    batch?: { latest: CoalescedOccurrence<unknown>; notices: DeferredNotice[]; dropped: number; rendering?: boolean; firstView?: true; allAmbient?: true };
   }>;
 }
 /** One receipt, written synchronously at acceptance (bridges the snapshot throttle). */
@@ -299,8 +319,11 @@ export interface CoalescerHost<E> {
   /** Queue an ordinary push wake for `agent`, under the batch's own wake
    *  policy, to read a render of the batch placed in its deferred queue that
    *  no request consumed, at `deferredId`. It carries no subject, so the
-   *  subject's other wakes, and later withdrawals of them, leave it. */
-  wakeToRead(occurrence: CoalescedOccurrence<E>, agent: string, deferredId?: string): Promise<void>;
+   *  subject's other wakes, and later withdrawals of them, leave it.
+   *  `allAmbient`: every notice the render stands for was tagged
+   *  `chat:ambient` (DeferredBatch.allAmbient), so the wake is marked
+   *  ambient. */
+  wakeToRead(occurrence: CoalescedOccurrence<E>, agent: string, deferredId?: string, allAmbient?: boolean): Promise<void>;
   /** Withdraw unstarted wakes whose sole cause is this subject. */
   cancelWake(subject: string): void;
   /** The batch's audience still holds the authority it was admitted under. */
@@ -416,14 +439,20 @@ export function validateCoalescedContent(
 /**
  * Whether the converter (`convertBlock` in convert-block.ts, which every lane
  * uses) shows a block as itself, its text or its image or
- * audio source, or as a reference stub, and not as a placeholder: an
+ * audio source (for MCP's embedded resource, its contents'), or as a
+ * reference stub, and not as a placeholder: an
  * unrecognized block, a no-data or no-media-type one, withheld inline data,
  * or a text block whose text isn't a string. This follows its branches in
  * their order.
  */
 function showsAsItself(b: Record<string, unknown>): boolean {
   if (b.type === 'text') return typeof b.text === 'string';
-  if (b.type === 'resource') return classifyBlock(b).kind === 'reference';
+  if (b.type === 'resource' || b.type === 'resource_link') {
+    const c = classifyBlock(b);
+    // MCP's embedded resource shows as the block its contents make.
+    if (c.kind === 'embedded') return c.contents.kind === 'block' && showsAsItself(c.contents.block);
+    return c.kind === 'reference';
+  }
   if (b.type !== 'image' && b.type !== 'audio') return false;
   if (isInlineContradiction(b)) return false;
   if (isFilledString(b.uri) && b.disposition !== undefined) return classifyBlock(b).kind === 'reference';
@@ -833,7 +862,7 @@ export class PushCoalescer<E = unknown> {
     // context that read a version, never a new one (§3.2).
     const placement = await this.deliver({ ...occurrence, deliverTo: state.audienceAgent });
     if (placement) {
-      state.occupant = { eventId: occurrence.eventId, placement };
+      state.occupant = { eventId: occurrence.eventId, placement, ...ambientOccupant(occurrence) };
       state.audienceAgent = placement.agent;
     }
     return 'noted';
@@ -858,7 +887,7 @@ export class PushCoalescer<E = unknown> {
           ...occurrence, deliverTo: prior.placement.agent,
           ...(firstView ? { firstView: true } : {}),
         });
-        state.occupant = placement ? { eventId: occurrence.eventId, placement, ...(firstView ? { firstView: true as const } : {}) } : undefined;
+        state.occupant = placement ? { eventId: occurrence.eventId, placement, ...(firstView ? { firstView: true as const } : {}), ...ambientOccupant(occurrence) } : undefined;
         if (placement) state.audienceAgent = placement.agent;
         return 'replaced';
       }
@@ -872,7 +901,7 @@ export class PushCoalescer<E = unknown> {
     // batch's place (a batch's own first view ends with the subject's).
     const firstView = hadBatch ? batchFirstView && state.history === 'none' : outcome === 'first' && !state.firstViewEnded;
     const placement = await this.deliver(hadBatch && firstView ? { ...occurrence, firstView: true } : occurrence);
-    state.occupant = placement ? { eventId: occurrence.eventId, placement, ...(firstView ? { firstView: true as const } : {}) } : undefined;
+    state.occupant = placement ? { eventId: occurrence.eventId, placement, ...(firstView ? { firstView: true as const } : {}), ...ambientOccupant(occurrence) } : undefined;
     if (placement) state.audienceAgent = placement.agent;
     return outcome;
   }
@@ -887,6 +916,10 @@ export class PushCoalescer<E = unknown> {
     // batches already open too). A render still under way is weighed when a
     // batch's first delivery is.
     let firstView = state.history === 'none' && !state.firstViewEnded;
+    // Whether every notice the batch's render stands for was tagged
+    // `chat:ambient` (DeferredBatch.allAmbient): this one, and a plain
+    // occurrence it displaces unread, whose place the render takes.
+    let ambient = occurrence.tags?.includes('chat:ambient') === true;
     if (occupantUnread && state.occupant?.rendered) {
       // An unread render is a delta the next render builds on (§5.2), not a
       // plain occurrence: it stays, and the batch follows its agent (§3.2), so
@@ -897,6 +930,7 @@ export class PushCoalescer<E = unknown> {
       // §5.1: a notice displaces an unread plain occurrence and opens a batch
       // — in the audience that held the plain occurrence (§3.2).
       if (!this.occupantLeaves(state, state.occupant)) firstView = false;
+      if (state.occupant.ambient !== true) ambient = false;
       this.host.audit({ kind: 'displaced', subject, eventId: state.occupant.eventId });
       if (this.host.remove(state.occupant.placement)) {
         outcome = 'replaced';
@@ -913,10 +947,11 @@ export class PushCoalescer<E = unknown> {
       state.batch.notices.push(notice);
       if (state.batch.notices.length > this.maxNotices) { state.batch.notices.shift(); state.batch.dropped++; }
       state.batch.latest = occurrence;
+      if (!ambient) delete state.batch.allAmbient;
       outcome = 'replaced';
     } else {
       // Rule 1: a notice during a render opens a NEW batch ("first").
-      state.batch = { latest: occurrence, notices: [notice], dropped: 0, ...(firstView ? { firstView: true as const } : {}) };
+      state.batch = { latest: occurrence, notices: [notice], dropped: 0, ...(firstView ? { firstView: true as const } : {}), ...(ambient ? { allAmbient: true as const } : {}) };
     }
     await this.host.wakeForBatch(occurrence);
     return outcome;
@@ -1122,7 +1157,9 @@ export class PushCoalescer<E = unknown> {
           // agent's wake for this batch; give it an ordinary wake, as any
           // delivery during its turn has, beside any wakes a newer batch has,
           // so that its next turn reads the content (the wake starts no turn
-          // once the agent has read it, or it's removed).
+          // once a request that carried it is answered and, if the wake
+          // carries a channel and the batch wasn't all ambient, the agent has
+          // published there since, or once it's removed).
           // The run's renders keep their own records, whatever else an
           // occupant carries, a first view's mark included.
           let before: Occupant['before'];
@@ -1136,7 +1173,7 @@ export class PushCoalescer<E = unknown> {
             await this.host.wakeForBatch(state.batch.latest);
           }
           state.audienceAgent = placement.agent;
-          await this.host.wakeToRead(occurrence, placement.agent, placement.deferredId);
+          await this.host.wakeToRead(occurrence, placement.agent, placement.deferredId, batch.allAmbient === true);
           return;
         }
         // The materialized occurrence is consumed by the request being
@@ -1180,6 +1217,7 @@ export class PushCoalescer<E = unknown> {
         state.batch = {
           latest: s.batch.latest as CoalescedOccurrence<E>, notices: s.batch.notices, dropped: s.batch.dropped,
           ...(s.batch.rendering ? { noRender: true } : s.batch.firstView ? { firstView: true as const } : {}),
+          ...(s.batch.allAmbient ? { allAmbient: true as const } : {}),
         };
       }
       this.subjects.set(s.subject, state);
@@ -1265,8 +1303,8 @@ export class PushCoalescer<E = unknown> {
         // restore() reads only these. After a restart nothing of the subject
         // is tracked as unread, a run included: its history counts as read.
         ...(s.occupant ? { occupant: { eventId: s.occupant.eventId, placement: s.occupant.placement } } : {}),
-        ...(s.batch ? { batch: { latest: s.batch.latest as CoalescedOccurrence<unknown>, notices: s.batch.notices, dropped: s.batch.dropped, ...(s.batch.noRender ? { rendering: true } : s.batch.firstView ? { firstView: true as const } : {}) } }
-          : s.rendering ? { batch: { latest: s.rendering.batch.latest as CoalescedOccurrence<unknown>, notices: s.rendering.batch.notices, dropped: s.rendering.batch.dropped, rendering: true } }
+        ...(s.batch ? { batch: { latest: s.batch.latest as CoalescedOccurrence<unknown>, notices: s.batch.notices, dropped: s.batch.dropped, ...(s.batch.noRender ? { rendering: true } : s.batch.firstView ? { firstView: true as const } : {}), ...(s.batch.allAmbient ? { allAmbient: true as const } : {}) } }
+          : s.rendering ? { batch: { latest: s.rendering.batch.latest as CoalescedOccurrence<unknown>, notices: s.rendering.batch.notices, dropped: s.rendering.batch.dropped, rendering: true, ...(s.rendering.batch.allAmbient ? { allAmbient: true as const } : {}) } }
           : {}),
       })),
     };