@animalabs/agent-framework 0.22.4 → 0.22.6

package/src/framework.ts

@@ -238,6 +238,29 @@ const silenceCauseOf = (calls: Array<{ name: string; input?: unknown }>): 'send'
   return calls.some(isSilencingCall) ? 'send' : null;
 };
 
+/**
+ * The keys of a stored message's metadata that only the host writes and that
+ * some reader takes on its own as what the message is: `system` makes it a
+ * host notice, `draftOwner` and `draftIds` one that names those drafts,
+ * `tuneOut` a message a tune-out holds from the residents,
+ * `coalescingSubject` (beside the occurrence's `eventId`) the delivery of a
+ * coalesced occurrence, `deferredWriteId` the landed copy of a deferred
+ * write, `external` a module's own row for an outside message,
+ * `silentHeartbeat` a row of a silent heartbeat tick, which marks the tick
+ * started whoever's row it is (indexSilentTickRows), and
+ * `openaiResponsesItems` membrane's mark of an imported Responses history. A
+ * server's metadata, a channel message's `metadata` or a push event's
+ * `origin`, is stored without them, and the host writes its own after it:
+ * MCPL SPEC §16.6 makes metadata the producer's untrusted claims, which a
+ * host may disbelieve. Keys a server writes by protocol, such as `tags` and
+ * `mentioned`, stay. So does the Discord module's `discordTextFirst`, which
+ * it reads only on a row it found by `external`.
+ */
+const HOST_METADATA_KEYS = [
+  'system', 'draftOwner', 'draftIds', 'tuneOut', 'coalescingSubject', 'deferredWriteId', 'external',
+  'silentHeartbeat', 'openaiResponsesItems',
+] as const;
+
 /**
  * True when an injected message is real conversational input — something the
  * agent might actually be replying to — rather than ambient machinery.
@@ -731,6 +754,31 @@ interface TurnRouting {
    * sent Sol's DM reply to a stale guild channel (2026-07-22).
    */
   triggerChannel?: string;
+  /**
+   * The trigger's channel with the server whose message it was, frozen when
+   * the turn opens and never moved: a channel_open moves triggerChannel and
+   * a re-pin moves the locus, but neither carries this server with it. Every
+   * send of the turn whose destination id is this channel resolves with this
+   * server (triggerServerFor): speech, a channel_publish naming it or taking
+   * it as its default, a drafts resend, and the refusal reaction. So a
+   * message one server sent can't have its reply go out through another
+   * server that registers the same id, whatever the registry holds by then;
+   * the reply is refused where its server no longer registers the channel.
+   * Unset for a turn with no channel trigger, and where the requests batched
+   * into the trigger name its channel from more than one server: a bare id
+   * then resolves only where exactly one server registers it.
+   */
+  triggerOrigin?: { channelId: string; serverId: string };
+  /**
+   * The locus with the server of the message that put it there, where that
+   * isn't the trigger: the latest accepted message's (the global fallback a
+   * turn with no trigger channel takes), an arrival's or a mid-turn
+   * message's (a re-pin), or the server a channel_open opened it on. Set
+   * with the locus (setTurnLocus), and cleared when the locus moves to a
+   * channel no one server put there. A send into this channel resolves with
+   * this server, as one into the trigger's channel does with the trigger's.
+   */
+  locusOrigin?: { channelId: string; serverId: string };
   /**
    * Locus and hybrid mode: where the turn's unpinned plain prose lands.
    * Frozen when the turn opens (home channel for a fork, else the trigger
@@ -807,11 +855,60 @@ interface Arrival {
   messageId: MessageId;
   /** The channel it re-pins the locus to. */
   channelId: string;
+  /** The server whose message it is. */
+  serverId?: string;
+}
+
+/** The server a stored channel message came from, as the host wrote it. */
+function messageServerId(metadata: MessageMetadata | undefined): string | undefined {
+  const serverId = (metadata as { serverId?: unknown } | undefined)?.serverId;
+  return typeof serverId === 'string' && serverId ? serverId : undefined;
 }
 
 /** The last TurnRouting.turnId given out: ids increase, and are unique within the process. */
 let lastTurnId = 0;
 
+/**
+ * The server every request naming `channelId` came from, or undefined where
+ * one names no server or they name more than one (TurnRouting.triggerOrigin).
+ */
+function onlyServerFor(requests: readonly InferenceRequest[], channelId: string): string | undefined {
+  let serverId: string | undefined;
+  for (const r of requests) {
+    if (r.channelId !== channelId) continue;
+    if (!r.serverId || (serverId !== undefined && r.serverId !== serverId)) return undefined;
+    serverId = r.serverId;
+  }
+  return serverId;
+}
+
+/**
+ * The server a send in `routing`'s turn resolves `channelId` with: the
+ * trigger's, where `channelId` is the trigger's channel
+ * (TurnRouting.triggerOrigin), else the locus's, where it's the channel the
+ * locus's server put there (TurnRouting.locusOrigin).
+ */
+function triggerServerFor(routing: TurnRouting | undefined, channelId: string | null | undefined): string | undefined {
+  if (routing === undefined || !channelId) return undefined;
+  if (routing.triggerOrigin?.channelId === channelId) return routing.triggerOrigin.serverId;
+  if (routing.locusOrigin?.channelId === channelId) return routing.locusOrigin.serverId;
+  return undefined;
+}
+
+/** Move a turn's locus, with the server of the message that put it there
+ *  (TurnRouting.locusOrigin), or none. */
+function setTurnLocus(routing: TurnRouting, channelId: string, serverId: string | undefined): void {
+  routing.locus = channelId;
+  routing.locusOrigin = serverId !== undefined ? { channelId, serverId } : undefined;
+}
+
+/** routeSpeech's options for speech into `channelId` in `routing`'s turn:
+ *  the trigger's server, where it's the trigger's channel (triggerServerFor). */
+function speechServerOpts(routing: TurnRouting | undefined, channelId: string | null | undefined): { locusServerId: string } | undefined {
+  const serverId = triggerServerFor(routing, channelId);
+  return serverId !== undefined ? { locusServerId: serverId } : undefined;
+}
+
 function freshTurnRouting(): TurnRouting {
   return {
     turnId: ++lastTurnId,
@@ -2704,8 +2801,8 @@ export class AgentFramework {
             // route applies to a fork only when it IS that home, and never to
             // another agent when a fork owns that channel. Otherwise a fork
             // bound elsewhere would show typing where it isn't replying.
-            ...(provenance?.routeChannelId && framework.mayTakeGateRoute(agentName, provenance.routeChannelId)
-              ? { channelId: provenance.routeChannelId, addressed: true }
+            ...(provenance?.routeChannelId && framework.mayTakeGateRoute(agentName, provenance.routeChannelId, provenance.routeServerId)
+              ? { channelId: provenance.routeChannelId, serverId: provenance.routeServerId, addressed: true }
               : {}),
           });
         },
@@ -7937,7 +8034,9 @@ export class AgentFramework {
       // tools/call directly on its connection (bare tool name — no prefix
       // games), bypassing the agent event queue so no synthetic tool-result
       // is injected into a turn the agent never took.
-      const serverId = this.channelRegistry?.getChannelServerId(incoming.channelId);
+      // Through the server whose message it marks: the latest accepted
+      // message's, kept beside its channel and id (fallbackServerFor).
+      const serverId = this.channelRegistry?.fallbackServerFor(incoming.channelId);
       const server = serverId ? this.mcplServerRegistry?.getServer(serverId) : null;
       if (!server) {
         console.error(
@@ -8110,7 +8209,9 @@ export class AgentFramework {
       const parts = incoming.channelId.split(':');
       if (parts[0] !== 'discord') return;
       const channelId = parts[parts.length - 1];
-      const serverId = this.channelRegistry?.getChannelServerId(incoming.channelId);
+      // As reactToRefusal resolves it: through the server whose message the
+      // latest inbound is (fallbackServerFor).
+      const serverId = this.channelRegistry?.fallbackServerFor(incoming.channelId);
       const server = serverId ? this.mcplServerRegistry?.getServer(serverId) : null;
       if (!server) return;
       await server.sendToolsCall('send_message', {
@@ -10345,9 +10446,9 @@ export class AgentFramework {
           // turn ends. The window stores them here, right after the
           // tool_result message, which is exactly where the membrane appends
           // them in the live conversation — same participant, same content
-          // blocks, same metadata, and compile() emits recent messages
-          // verbatim, so the next turn's compiled prefix byte-matches the
-          // live request (prompt-cache safe).
+          // blocks, and neither carries the row's metadata — and compile()
+          // emits recent messages verbatim, so the next turn's compiled prefix
+          // byte-matches the live request (prompt-cache safe).
           //
           // The queue is drained ONLY at the target agent's own boundary:
           // draining at another agent's boundary would store the messages
@@ -10506,12 +10607,19 @@ export class AgentFramework {
             // The last injection that qualifies wins (repinChannel).
             const routing = this.routingOf(agent.name);
             let newLocus: string | undefined;
-            for (const inj of midTurnInjections) newLocus = this.repinChannel(inj.metadata, routing) ?? newLocus;
+            let newLocusServer: string | undefined;
+            for (const inj of midTurnInjections) {
+              const channelId = this.repinChannel(inj.metadata, routing);
+              if (channelId) {
+                newLocus = channelId;
+                newLocusServer = messageServerId(inj.metadata);
+              }
+            }
             if (newLocus) {
               // What this boundary just stored is newer than any arrival the
               // turn holds, so the arrivals can't move the locus back.
               routing.arrivals = [];
-              const notice = this.repinTurnLocus(agent, routing, newLocus, 'mid-turn addressed');
+              const notice = this.repinTurnLocus(agent, routing, newLocus, 'mid-turn addressed', newLocusServer);
               if (notice) midTurnInjections.push(notice);
             }
           } else if (routesLocus && !shouldEndTurn) {
@@ -10589,9 +10697,13 @@ export class AgentFramework {
             // Mid-turn messages collected above ride along as injected user
             // messages (membrane ≥0.5.72) — appended after the tool_result
             // envelope so the next round of THIS turn hears them.
+            // Each goes as its participant and content alone: a stored row's
+            // metadata is the host's record, not input for membrane.
             currentState.stream.provideToolResults(
               agent.toolResultGuard.submissionResults(membraneResults),
-              midTurnInjections.length > 0 ? { injectedMessages: midTurnInjections } : undefined,
+              midTurnInjections.length > 0
+                ? { injectedMessages: midTurnInjections.map(({ participant, content }) => ({ participant, content })) }
+                : undefined,
             );
             // RFC-006 §3.3: consumption is determined at assembly, and this
             // is assembly too when the stream carries the injected messages
@@ -10789,6 +10901,31 @@ export class AgentFramework {
   // Built-in MCPL event → context message conversion
   // ==========================================================================
 
+  /** The servers and keys whose drop withoutHostKeys has logged, each as
+   *  `${serverId}\u0000${key}`. */
+  private readonly hostKeysDropped = new Set<string>();
+
+  /**
+   * A server's metadata as it is stored: a copy without HOST_METADATA_KEYS.
+   * A server may use one of those names for something of its own, so the
+   * first drop of each key from each server is logged.
+   */
+  private withoutHostKeys(serverId: string, given: Record<string, unknown> | undefined): Record<string, unknown> {
+    const kept: Record<string, unknown> = { ...given };
+    for (const key of HOST_METADATA_KEYS) {
+      if (!Object.hasOwn(kept, key)) continue;
+      delete kept[key];
+      const logged = `${serverId}\u0000${key}`;
+      if (this.hostKeysDropped.has(logged)) continue;
+      this.hostKeysDropped.add(logged);
+      console.error(
+        `[mcpl] ${serverId}: dropped "${key}" from a message, since only the host writes that key ` +
+        `(logged once for each server and key)`,
+      );
+    }
+    return kept;
+  }
+
   /**
    * Convert an incoming MCPL channel message to a context message.
    * This replaces the old MCPLModule.onProcess() message conversion.
@@ -10825,7 +10962,7 @@ export class AgentFramework {
       return undefined;
     }
     const metadata: Record<string, unknown> = {
-      ...event.metadata,
+      ...this.withoutHostKeys(event.serverId, event.metadata),
       ...(event.eventId ? { eventId: event.eventId } : {}),
       ...(event.coalescingSubject ? { coalescingSubject: event.coalescingSubject } : {}),
       channelId: event.channelId,
@@ -10865,14 +11002,15 @@ export class AgentFramework {
         const id = target.getContextManager().addMessage('user', event.content, metadata);
         // A correction may target an older engagement. Refresh only the
         // binding whose agent actually received the message.
-        if (this.conversationRouter.getBinding(event.channelId)?.agentName === target.name) {
-          this.conversationRouter.touch(event.channelId);
+        const channel = { serverId: event.serverId, channelId: event.channelId };
+        if (this.conversationRouter.getBinding(channel)?.agentName === target.name) {
+          this.conversationRouter.touch(channel);
         }
         this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
         if (event.triggerInference) {
           this.pendingRequests.push({
             agentName: target.name, reason: 'mcpl:channel-incoming', source: event.serverId, timestamp: Date.now(),
-            channelId: event.channelId,
+            channelId: event.channelId, serverId: event.serverId,
             counterparty: event.author?.id ? `${event.serverId}:user:${event.author.id}` : undefined,
             addressed: isAddressedMessage(event.tags, event.metadata),
             ...(event.coalescingSubject ? { coalescingSubject: event.coalescingSubject } : {}),
@@ -10951,8 +11089,10 @@ export class AgentFramework {
           source: event.serverId,
           timestamp: Date.now(),
           // Route this turn's auto-published speech back to THIS channel, not
-          // the global most-recent-inbound locus (item-3 redux, trunk agents).
+          // the global most-recent-inbound locus (item-3 redux, trunk agents),
+          // through the server that sent it.
           channelId: event.channelId,
+          serverId: event.serverId,
           counterparty: event.author?.id ? `${event.serverId}:user:${event.author.id}` : undefined,
           // Addressed messages outrank ambient chatter when a batched wake
           // picks the turn's frozen speech locus.
@@ -11030,7 +11170,7 @@ export class AgentFramework {
       if (!agent) {
         // Bound agent vanished (e.g. external reset) — unbind so the next
         // qualifying message respawns a fresh fork.
-        router.unbind(event.channelId);
+        router.unbind({ serverId: event.serverId, channelId: event.channelId });
         this.emitTrace({
           type: 'mcpl:conversation-binding-orphaned',
           channelId: event.channelId,
@@ -11046,7 +11186,7 @@ export class AgentFramework {
     messageMetadata.triggered = trigger;
 
     const id = agent.getContextManager().addMessage('user', event.content, messageMetadata);
-    router.touch(event.channelId);
+    router.touch({ serverId: event.serverId, channelId: event.channelId });
     this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
 
     if (trigger) {
@@ -11058,6 +11198,7 @@ export class AgentFramework {
         // A fork's home channel wins in routeSpeech regardless, but carry the
         // triggering channel too so the trunk/active path stays consistent.
         channelId: event.channelId,
+        serverId: event.serverId,
         counterparty: event.author?.id ? `${event.serverId}:user:${event.author.id}` : undefined,
         addressed: isAddressedMessage(event.tags, event.metadata),
         ...(event.coalescingSubject ? { coalescingSubject: event.coalescingSubject } : {}),
@@ -11202,7 +11343,7 @@ export class AgentFramework {
       }
       const decision = this.conversationRouter!.route(facts);
       if (decision.kind !== 'spawn') return decision;
-      return { ...decision, spawned: this.spawnConversationAgent(facts.channelId, decision) };
+      return { ...decision, spawned: this.spawnConversationAgent(facts, decision) };
     }
   }
 
@@ -11218,11 +11359,12 @@ export class AgentFramework {
    * so the entry it removes is its own. It's removed before anyone waiting
    * on it resumes, so a waiter that decides again doesn't find it.
    */
-  private spawnConversationAgent(channelId: string, decision: { agentName: string; generation: number }): Promise<Agent> {
+  private spawnConversationAgent(facts: IncomingMessageFacts, decision: { agentName: string; generation: number }): Promise<Agent> {
+    const channelId = facts.channelId;
     const spawn = (async () => {
       this.storeConversationGeneration(channelId, decision.generation);
       const agent = await this.createConversationAgent(decision.agentName, channelId);
-      this.conversationRouter!.bind(channelId, decision.agentName, decision.generation);
+      this.conversationRouter!.bind({ serverId: facts.serverId, channelId }, decision.agentName, decision.generation);
       return agent;
     })();
     const done = (): void => { this.conversationSpawns.delete(channelId); };
@@ -11351,7 +11493,7 @@ export class AgentFramework {
     this.lastConversationSweep = now;
 
     for (const binding of this.conversationRouter.expired(now)) {
-      this.conversationRouter.unbind(binding.channelId);
+      this.conversationRouter.unbind(binding);
       this.emitTrace({
         type: 'mcpl:conversation-closed',
         channelId: binding.channelId,
@@ -12020,7 +12162,7 @@ export class AgentFramework {
     if (explicit) return explicit.filter((n) => this.agents.has(n));
     if (occ.scope.kind === 'channel' && this.conversationRouter) {
       const router = this.conversationRouter;
-      const bound = router.getBinding(occ.scope.id)?.agentName;
+      const bound = router.getBinding({ serverId: occ.serverId, channelId: occ.scope.id })?.agentName;
       if (bound) return this.agents.has(bound) ? [bound] : [];
       // No fork yet: the same bind decision an incoming message would get. A
       // batch that qualifies spawns its fork now so it has someone to wake.
@@ -12128,6 +12270,7 @@ export class AgentFramework {
         source: occ.serverId,
         timestamp: Date.now(),
         channelId,
+        serverId: channelId !== undefined ? occ.serverId : undefined,
         counterparty: authorId ? `${occ.serverId}:user:${authorId}` : undefined,
         addressed: isAddressedMessage(occ.tags, origin),
         coalescingSubject: subject,
@@ -12267,7 +12410,7 @@ export class AgentFramework {
     }
 
     const metadata: Record<string, unknown> = {
-      ...event.origin,
+      ...this.withoutHostKeys(event.serverId, event.origin),
       serverId: event.serverId,
       featureSet: event.featureSet,
       eventId: event.eventId,
@@ -12342,6 +12485,7 @@ export class AgentFramework {
           source: event.serverId,
           timestamp: Date.now(),
           channelId: triggerChannel?.channelId,
+          serverId: triggerChannel ? event.serverId : undefined,
           // DMs and addressed-while-closed messages arrive as push events;
           // they must outrank ambient chatter in a batched wake's locus
           // selection just like their channels/incoming counterparts.
@@ -12364,17 +12508,49 @@ export class AgentFramework {
    * Whether a batched gate wake's addressed route may become `agentName`'s
    * speech locus. The gate broadcasts to every agent, conversation forks
    * included. A fork speaks only in its home channel, and a channel bound to
-   * a fork is that fork's conversation, so no other agent takes it.
+   * a fork is that fork's conversation, so no other agent takes it. Two
+   * servers' channels with one id are two conversations, each bound to its
+   * own fork with that id as its home, so a fork takes the route only where
+   * the router binds the route's channel, its server and id, to it; a route
+   * with no server names a fork only where one fork is bound to that id.
    */
-  private mayTakeGateRoute(agentName: string, routeChannelId: string): boolean {
+  private mayTakeGateRoute(agentName: string, routeChannelId: string, routeServerId?: string): boolean {
     const home = this.conversationAgentHomes.get(agentName);
-    if (home !== undefined) return home === routeChannelId;
+    if (home !== undefined) {
+      return home === routeChannelId
+        && this.conversationRouter?.getBinding({ serverId: routeServerId, channelId: routeChannelId })?.agentName === agentName;
+    }
     for (const boundChannel of this.conversationAgentHomes.values()) {
       if (boundChannel === routeChannelId) return false;
     }
     return true;
   }
 
+  /**
+   * The channel a push names, and a server that registers it, when another
+   * server registers that channel id and the pushing server doesn't. A
+   * channel's id is the agent's locus on its own, so the reply to such a
+   * push would go out through the server that registers it: the push
+   * boundary refuses it (PushHandler). A push naming a channel no server
+   * registers isn't refused, and registers it for the pushing server
+   * (ensureChannelRegistered).
+   */
+  private channelOfAnotherServer(
+    serverId: string,
+    origin: Record<string, unknown> | undefined,
+  ): { channelId: string; holder: string } | undefined {
+    if (!this.channelRegistry) return undefined;
+    const channel = this.derivePushEventChannel(origin);
+    if (!channel) return undefined;
+    let holder: string | undefined;
+    for (const entry of this.channelRegistry.listChannelsRaw()) {
+      if (entry.descriptor.id !== channel.channelId) continue;
+      if (entry.serverId === serverId) return undefined;
+      holder ??= entry.serverId;
+    }
+    return holder === undefined ? undefined : { channelId: channel.channelId, holder };
+  }
+
   /**
    * Derive the MCPL composite channel id (the outbound routing locus) for a
    * push event from its server-defined `origin`, if it carries one.
@@ -12699,6 +12875,7 @@ export class AgentFramework {
         ephemeralSystemPrompt: silentOnly ? trigger?.ephemeralSystemPrompt : undefined,
         silentHeartbeat: silentOnly ? trigger?.silentHeartbeat : undefined,
         channelId: channelReq?.channelId,
+        serverId: channelReq?.channelId !== undefined ? onlyServerFor(requests, channelReq.channelId) : undefined,
         addressed: addressedReq !== undefined,
         // A context-budget restart continues the same logical turn: it keeps
         // the channel for routing but names no author — the restart is its
@@ -13145,8 +13322,8 @@ export class AgentFramework {
   /** The drafts tool's answer to a resident's call, from the model's own
    *  dispatch or an agent-origin call through executeToolCall (a puppet's):
    *  a failure the handler throws is answered as one. */
-  private draftsToolResult(agentName: string, rawInput: unknown): Promise<ToolResult> {
-    return this.handleDraftsTool(agentName, rawInput).catch((err): ToolResult => ({
+  private draftsToolResult(agentName: string, rawInput: unknown, callerTurnId?: number): Promise<ToolResult> {
+    return this.handleDraftsTool(agentName, rawInput, callerTurnId).catch((err): ToolResult => ({
       success: false,
       error: `drafts failed: ${thrownText(err)}`,
       isError: true,
@@ -13159,7 +13336,7 @@ export class AgentFramework {
    * each draft is published verbatim, in order, through the normal publish
    * executor, its attempt journaled durably before the request leaves.
    */
-  private async handleDraftsTool(agentName: string, rawInput: unknown): Promise<ToolResult> {
+  private async handleDraftsTool(agentName: string, rawInput: unknown, callerTurnId?: number): Promise<ToolResult> {
     const input = (rawInput && typeof rawInput === 'object' && !Array.isArray(rawInput) ? rawInput : {}) as Record<string, unknown>;
     // The turn that sends: a resent draft's channel is recorded as engaged on
     // it, as a send tool's is, even when the result comes after the turn.
@@ -13326,7 +13503,17 @@ export class AgentFramework {
       const cand = resolved.candidates?.length ? ` It could mean: ${resolved.candidates.join(', ')}.` : '';
       return refuse(`Destination "${spec}" did not resolve: ${resolved.error}.${cand} Nothing was sent.`);
     }
-    const target = registry.resolveDestination({ channelId: resolved.channelId });
+    // A resend into a channel the calling turn recorded a server for goes
+    // through that server (triggerServerFor), where the call was made inside
+    // that turn; a background script's call carries no turn.
+    const callingRouting = this.turnRouting.get(agentName);
+    const triggerServer = callerTurnId !== undefined && callingRouting?.turnId === callerTurnId
+      ? triggerServerFor(callingRouting, resolved.channelId)
+      : undefined;
+    const target = registry.resolveDestination({
+      ...(triggerServer !== undefined ? { serverId: triggerServer } : {}),
+      channelId: resolved.channelId,
+    });
     if ('error' in target) return refuse(`Destination "${spec}": ${target.error}. Nothing was sent.`);
     const destination = target.destination;
     if (home && destination.channelId !== home) {
@@ -13672,7 +13859,10 @@ export class AgentFramework {
     if (!open) return;
     if ((metadata as { tuneOut?: unknown } | undefined)?.tuneOut) return;
     const channelId = this.repinChannel(metadata, open);
-    if (channelId) open.arrivals.push({ messageId, channelId });
+    if (channelId) {
+      const serverId = messageServerId(metadata);
+      open.arrivals.push({ messageId, channelId, ...(serverId !== undefined ? { serverId } : {}) });
+    }
   }
 
   /**
@@ -13708,14 +13898,14 @@ export class AgentFramework {
    * message in the store; the last compile can't be the test, since an
    * arrival between the turn's streams isn't in it yet.
    */
-  private remainingArrival(agent: Agent, routing: TurnRouting): string | undefined {
+  private remainingArrival(agent: Agent, routing: TurnRouting): Arrival | undefined {
     const cm = agent.getContextManager();
     for (let i = routing.arrivals.length - 1; i >= 0; i--) {
-      const { messageId, channelId } = routing.arrivals[i]!;
+      const arrival = routing.arrivals[i]!;
       // The store answers null for a message that isn't there. A store that
       // can't be read throws here, as anywhere else in the start, rather
       // than have its candidates read as withdrawn.
-      if (cm.getMessage(messageId)) return channelId;
+      if (cm.getMessage(arrival.messageId)) return arrival;
     }
     return undefined;
   }
@@ -13737,10 +13927,12 @@ export class AgentFramework {
     routing: TurnRouting,
     channelId: string,
     cause: string,
+    /** The server of the message that moved it. */
+    serverId?: string,
   ): { participant: string; content: ContentBlock[]; metadata: MessageMetadata } | undefined {
     if (routing.locus === channelId) return undefined;
     const prevPin = routing.locus ?? null;
-    routing.locus = channelId;
+    setTurnLocus(routing, channelId, serverId);
     const label = this.channelRegistry?.getDescriptor(channelId)?.label;
     const shown = label && label !== channelId
       ? `${label.startsWith('#') ? label : `#${label}`} (${channelId})`
@@ -14002,11 +14194,13 @@ export class AgentFramework {
     body: string,
     channelId: string,
     unsent: Draft | undefined,
+    /** The server the channel resolves with (triggerServerFor). */
+    serverId: string | undefined,
   ): Promise<PublishOutcome> {
     const registry = this.channelRegistry!;
     let attemptId: string | undefined;
     if (unsent) {
-      const target = registry.resolveDestination({ channelId });
+      const target = registry.resolveDestination({ ...(serverId !== undefined ? { serverId } : {}), channelId });
       if (!('error' in target)) {
         try {
           attemptId = this.proseDrafts.beginAttempt(agent.name, unsent.id, target.destination, 'unsent-token', false);
@@ -14027,7 +14221,8 @@ export class AgentFramework {
     try {
       // Both callers hold a failed delivery's words as a bounce draft, whose
       // notice says what happened, so the registry writes no second marker.
-      outcome = await registry.deliverSpeech(agent.name, body, channelId, { heldOnFailure: true });
+      outcome = await registry.deliverSpeech(agent.name, body, channelId,
+        { heldOnFailure: true, ...(serverId !== undefined ? { locusServerId: serverId } : {}) });
     } finally {
       if (flight) {
         this.draftsInFlight.delete(flight);
@@ -14125,7 +14320,7 @@ export class AgentFramework {
           continue;
         }
         try {
-          const outcome = await this.deliverWithUnsent(agent, body, resolved.channelId, unsent.draft);
+          const outcome = await this.deliverWithUnsent(agent, body, resolved.channelId, unsent.draft, triggerServerFor(routing, resolved.channelId));
           this.recordProseDelivery(routing, outcome.status === 'delivered' ? { delivered: true, channelId: outcome.destination!.channelId } : null);
           if (outcome.status === 'delivered') {
             this.proseBounceStreaks.delete(agent.name);
@@ -14167,7 +14362,7 @@ export class AgentFramework {
       }
       const target = sticky ?? locus;
       try {
-        const outcome = await this.channelRegistry!.routeSpeech(agent.name, envelope, target);
+        const outcome = await this.channelRegistry!.routeSpeech(agent.name, envelope, target, speechServerOpts(routing, target));
         this.recordProseDelivery(routing, outcome);
       } catch (err) {
         console.error('hybrid locus delivery failed:', err);
@@ -14288,7 +14483,7 @@ export class AgentFramework {
     }
 
     try {
-      const outcome = await this.deliverWithUnsent(agent, body, targetChannel, unsent.draft);
+      const outcome = await this.deliverWithUnsent(agent, body, targetChannel, unsent.draft, triggerServerFor(routing, targetChannel));
       if (outcome.status === 'delivered') {
         this.proseBounceStreaks.delete(name);
       } else if (outcome.status === 'failed') {
@@ -14879,6 +15074,9 @@ export class AgentFramework {
       // turn, which falls back to the global default rather than inheriting
       // a previous turn's channel.
       routing.triggerChannel = trigger?.channelId;
+      routing.triggerOrigin = trigger?.channelId && trigger.serverId
+        ? { channelId: trigger.channelId, serverId: trigger.serverId }
+        : undefined;
       // FREEZE the turn's outbound locus now (turn-frozen routing): the home
       // channel for forks, else the trigger channel, else the global default.
       // Mid-turn injections must not redirect the agent's plain prose
@@ -14893,7 +15091,14 @@ export class AgentFramework {
       // stability).
       if (turnProseRouting !== 'explicit' && turnProseRouting !== 'disabled') {
         const locus = this.channelRegistry?.resolveLocus(agent.name) ?? null;
-        if (locus !== null) routing.locus = locus;
+        // A locus that is neither the trigger's channel nor the agent's home
+        // is the global fallback: its server is the latest accepted
+        // message's, taken now, with the locus.
+        if (locus !== null) {
+          setTurnLocus(routing, locus, locus !== routing.triggerChannel && !this.conversationAgentHomes.has(agent.name)
+            ? this.channelRegistry?.fallbackServerFor(locus)
+            : undefined);
+        }
         if (attempt === 0) this.announceLocusIfChanged(agent.name, locus);
       }
     } else {
@@ -14906,7 +15111,7 @@ export class AgentFramework {
         ? this.remainingArrival(agent, routing)
         : undefined;
       routing.arrivals = [];
-      if (arrival) this.repinTurnLocus(agent, routing, arrival, 'arrival');
+      if (arrival) this.repinTurnLocus(agent, routing, arrival.channelId, 'arrival', arrival.serverId);
     }
     // A silent start, or a disabled agent's, has no locus to show, whatever a
     // channel_open in a silent turn left on its object.
@@ -15386,7 +15591,7 @@ export class AgentFramework {
     };
     const enqueueSpeech = (text: string, locus: string | null): void => {
       chainSpeech(async () => {
-        const outcome = await this.channelRegistry!.routeSpeech(agent.name, text, locus);
+        const outcome = await this.channelRegistry!.routeSpeech(agent.name, text, locus, speechServerOpts(streamRouting, locus));
         this.recordProseDelivery(streamRouting, outcome);
       }, 'mid-turn speech routing failed:');
     };
@@ -15506,6 +15711,7 @@ export class AgentFramework {
       for (const rd of deltas) {
         this.channelRegistry!.sendOutgoingChunk(
           rd.channelId, agent.name, outgoingInferenceId, outgoingIndex++, rd.delta,
+          triggerServerFor(streamRouting, rd.channelId),
         );
       }
     };
@@ -16311,7 +16517,7 @@ export class AgentFramework {
                   );
                   for (const segment of speechSegments) {
                     try {
-                      const outcome = await this.channelRegistry.routeSpeech(agent.name, segment, locus);
+                      const outcome = await this.channelRegistry.routeSpeech(agent.name, segment, locus, speechServerOpts(streamRouting, locus));
                       this.recordProseDelivery(streamRouting, outcome);
                     } catch (err) {
                       console.error('speech routing failed:', err);
@@ -16407,7 +16613,7 @@ export class AgentFramework {
                 // Deliver sequentially (await each) so the segments land in order.
                 for (const seg of segments) {
                   try {
-                    const outcome = await this.channelRegistry.routeSpeech(agent.name, seg, locus);
+                    const outcome = await this.channelRegistry.routeSpeech(agent.name, seg, locus, speechServerOpts(streamRouting, locus));
                     this.recordProseDelivery(streamRouting, outcome);
                   } catch (err) {
                     console.error('speech routing failed:', err);
@@ -17051,7 +17257,7 @@ export class AgentFramework {
       if (frameReachedTerminal && proseStream) {
         emitOutgoing(proseStream.finish());
         for (const [channelId, text] of proseStream.byChannel()) {
-          this.channelRegistry!.sendOutgoingComplete(channelId, agent.name, outgoingInferenceId, text);
+          this.channelRegistry!.sendOutgoingComplete(channelId, agent.name, outgoingInferenceId, text, triggerServerFor(streamRouting, channelId));
         }
       }
       this.frameworkCancelledStreams.delete(`${agent.name}:${myStreamId}`);
@@ -17343,7 +17549,7 @@ export class AgentFramework {
     // agent origin and acts as that resident, as the model's own call does
     // through dispatchToolCall. A module holds no drafts.
     if (call.name === 'drafts' && this.channelRegistry && origin.kind === 'agent') {
-      return this.draftsToolResult(origin.agentName, call.input);
+      return this.draftsToolResult(origin.agentName, call.input, call.callerTurnId);
     }
 
     // The utils meta-tool — programmatic callers (code_execution scripts,
@@ -18813,7 +19019,7 @@ export class AgentFramework {
     if (enrichedCall.name === 'drafts' && this.channelRegistry) {
       const startedAt = Date.now();
       this.emitTrace({ type: 'tool:started', module: 'framework', tool: 'drafts', callId: enrichedCall.id, input: enrichedCall.input });
-      void this.draftsToolResult(agentName, enrichedCall.input)
+      void this.draftsToolResult(agentName, enrichedCall.input, enrichedCall.callerTurnId)
         .then((result) => {
           this.emitTrace({ type: 'tool:completed', module: 'framework', tool: 'drafts', callId: enrichedCall.id, durationMs: Date.now() - startedAt });
           this.pushEvent({ type: 'tool-result', callId: enrichedCall.id, toolName: enrichedCall.name, agentName, moduleName: 'framework', result });
@@ -19965,6 +20171,7 @@ export class AgentFramework {
         this.noteInboundAccepted(source);
         return source;
       },
+      (serverId, params) => this.channelOfAnotherServer(serverId, params.origin),
     );
 
     // Server-initiated inference router (Step 6)
@@ -22423,8 +22630,17 @@ export class AgentFramework {
     // ordinary wake, starts only once its over-budget boundary has every
     // result of the round.
     const callingTurn = this.routingOf(agentName);
+    const inTurn = call.callerTurnId !== undefined && call.callerTurnId === callingTurn.turnId;
 
-    this.channelRegistry!.handleChannelToolCall(call.name, call.input, { kind: 'agent', agentName })
+    this.channelRegistry!.handleChannelToolCall(call.name, call.input, {
+      kind: 'agent',
+      agentName,
+      // The turn's recorded servers go only with a call made inside that
+      // turn: a background script's call carries no turn, and takes a bare
+      // id only where exactly one server registers it.
+      ...(inTurn && callingTurn.triggerOrigin !== undefined ? { trigger: callingTurn.triggerOrigin } : {}),
+      ...(inTurn && callingTurn.locusOrigin !== undefined ? { locus: callingTurn.locusOrigin } : {}),
+    })
       .then((result) => {
         const durationMs = Date.now() - startTime;
         this.emitTrace({
@@ -22462,7 +22678,13 @@ export class AgentFramework {
             if (openerAgent
               && (openerAgent.proseRouting === 'locus' || openerAgent.proseRouting === 'hybrid')
               && this.openLogical.get(agentName) === callingTurn) {
-              callingTurn.locus = opened;
+              const openedOn = this.channelRegistry!.resolveDestination({
+                ...(typeof (call.input as { serverId?: unknown } | undefined)?.serverId === 'string'
+                  ? { serverId: (call.input as { serverId: string }).serverId }
+                  : {}),
+                channelId: opened,
+              });
+              setTurnLocus(callingTurn, opened, 'error' in openedOn ? undefined : openedOn.destination.serverId);
               this.lastAnnouncedLocus.set(agentName, opened);
               result = {
                 ...result,
@@ -22736,17 +22958,21 @@ export class AgentFramework {
       } else if (agent?.proseRouting === 'explicit') {
         // Explicit mode: announce to the turn's sticky prose target if the
         // model has set one; otherwise stay quiet — never guess a channel.
-        const target = this.turnRouting.get(agentName)?.pin;
+        const routing = this.turnRouting.get(agentName);
+        const target = routing?.pin;
         if (target) {
-          this.channelRegistry.routeSpeech(agentName, text, target).catch((err) => {
+          this.channelRegistry.routeSpeech(agentName, text, target,
+            speechServerOpts(call.callerTurnId === routing?.turnId ? routing : undefined, target)).catch((err) => {
             console.error('[sleep] announce failed:', err instanceof Error ? err.message : err);
           });
         } else {
           console.error(`[sleep] ${agentName}: no prose target this turn — sleep announcement not posted (explicit mode never guesses)`);
         }
       } else {
-        const locus = this.turnRouting.get(agentName)?.locus ?? null;
-        this.channelRegistry.routeSpeech(agentName, text, locus).catch((err) => {
+        const routing = this.turnRouting.get(agentName);
+        const locus = routing?.locus ?? null;
+        this.channelRegistry.routeSpeech(agentName, text, locus,
+          speechServerOpts(call.callerTurnId === routing?.turnId ? routing : undefined, locus)).catch((err) => {
           console.error('[sleep] announce failed:', err instanceof Error ? err.message : err);
         });
       }