@animalabs/agent-framework 0.23.1 → 0.23.3

package/dist/src/framework.js

@@ -180,6 +180,27 @@ const silenceCauseOf = (calls) => {
         return 'private';
     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` and `kind`
+ * make it a host notice of that kind, `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, 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 do the keys a reader takes only beside one of these:
+ * a failed reply's `reason` and `detail` beside its `kind`, and the Discord
+ * module's `discordTextFirst` on a row it found by `external`.
+ */
+const HOST_METADATA_KEYS = [
+    'system', 'kind', 'draftOwner', 'draftIds', 'tuneOut', 'coalescingSubject', 'deferredWriteId',
+    'external', 'openaiResponsesItems',
+];
 /**
  * True when an injected message is real conversational input — something the
  * agent might actually be replying to — rather than ambient machinery.
@@ -502,8 +523,55 @@ function announcedDomainsOf(announce) {
 function resumesLogicalTurn(reason) {
     return reason === 'context_budget_restart' || reason === 'tool_result_guard_retry';
 }
+/** The server a stored channel message came from, as the host wrote it. */
+function messageServerId(metadata) {
+    const serverId = metadata?.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, channelId) {
+    let serverId;
+    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, channelId) {
+    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, channelId, serverId) {
+    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, channelId) {
+    const serverId = triggerServerFor(routing, channelId);
+    return serverId !== undefined ? { locusServerId: serverId } : undefined;
+}
 function freshTurnRouting() {
     return {
         turnId: ++lastTurnId,
@@ -2129,8 +2197,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 }
                             : {}),
                     });
                 },
@@ -7430,7 +7498,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(`[inference-refusal] reaction skipped: no MCPL server for locus ${logValue(incoming.channelId)} (agent=${agentName})`);
@@ -9495,9 +9565,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
@@ -9664,13 +9734,19 @@ export class AgentFramework {
                         // The last injection that qualifies wins (repinChannel).
                         const routing = this.routingOf(agent.name);
                         let newLocus;
-                        for (const inj of midTurnInjections)
-                            newLocus = this.repinChannel(inj.metadata, routing) ?? newLocus;
+                        let newLocusServer;
+                        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);
                         }
@@ -9750,8 +9826,12 @@ export class AgentFramework {
                         // Streaming path: convert results and resume the stream.
                         // 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.
-                        currentState.stream.provideToolResults(agent.toolResultGuard.submissionResults(membraneResults), midTurnInjections.length > 0 ? { injectedMessages: midTurnInjections } : undefined);
+                        // 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.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
                         // into its next request. Without the mark they would sit above
@@ -9921,6 +10001,29 @@ export class AgentFramework {
     // ==========================================================================
     // Built-in MCPL event → context message conversion
     // ==========================================================================
+    /** The servers and keys whose drop withoutHostKeys has logged, each as
+     *  `${serverId}\u0000${key}`. */
+    hostKeysDropped = new Set();
+    /**
+     * 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.
+     */
+    withoutHostKeys(serverId, given) {
+        const kept = { ...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.
@@ -9937,7 +10040,7 @@ export class AgentFramework {
             return undefined;
         }
         const metadata = {
-            ...event.metadata,
+            ...this.withoutHostKeys(event.serverId, event.metadata),
             ...(event.eventId ? { eventId: event.eventId } : {}),
             ...(event.coalescingSubject ? { coalescingSubject: event.coalescingSubject } : {}),
             channelId: event.channelId,
@@ -9980,14 +10083,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 } : {}),
@@ -10059,8 +10163,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.
@@ -10123,7 +10229,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,
@@ -10137,7 +10243,7 @@ export class AgentFramework {
         const trigger = decision.trigger && event.triggerInference !== false;
         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) {
             this.pendingRequests.push({
@@ -10148,6 +10254,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 } : {}),
@@ -10286,7 +10393,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) };
         }
     }
     /**
@@ -10301,11 +10408,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.
      */
-    spawnConversationAgent(channelId, decision) {
+    spawnConversationAgent(facts, decision) {
+        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 = () => { this.conversationSpawns.delete(channelId); };
@@ -10428,7 +10536,7 @@ export class AgentFramework {
             return;
         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,
@@ -11076,7 +11184,7 @@ export class AgentFramework {
             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
@@ -11188,6 +11296,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),
                 ...(plain ? {} : { coalescingSubject: subject, coalescingBatch: true }),
@@ -11334,7 +11443,7 @@ export class AgentFramework {
             this.channelRegistry.ensureChannelRegistered(event.serverId, triggerChannel.channelId, triggerChannel.label, triggerChannel.metadata);
         }
         const metadata = {
-            ...event.origin,
+            ...this.withoutHostKeys(event.serverId, event.origin),
             serverId: event.serverId,
             featureSet: event.featureSet,
             eventId: event.eventId,
@@ -11405,6 +11514,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.
@@ -11428,18 +11538,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.
      */
-    mayTakeGateRoute(agentName, routeChannelId) {
+    mayTakeGateRoute(agentName, routeChannelId, routeServerId) {
         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).
+     */
+    channelOfAnotherServer(serverId, origin) {
+        if (!this.channelRegistry)
+            return undefined;
+        const channel = this.derivePushEventChannel(origin);
+        if (!channel)
+            return undefined;
+        let holder;
+        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.
@@ -11758,6 +11899,7 @@ export class AgentFramework {
                 suppressProse: silentOnly ? trigger?.suppressProse : 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
@@ -12207,8 +12349,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. */
-    draftsToolResult(agentName, rawInput) {
-        return this.handleDraftsTool(agentName, rawInput).catch((err) => ({
+    draftsToolResult(agentName, rawInput, callerTurnId) {
+        return this.handleDraftsTool(agentName, rawInput, callerTurnId).catch((err) => ({
             success: false,
             error: `drafts failed: ${thrownText(err)}`,
             isError: true,
@@ -12220,7 +12362,7 @@ export class AgentFramework {
      * each draft is published verbatim, in order, through the normal publish
      * executor, its attempt journaled durably before the request leaves.
      */
-    async handleDraftsTool(agentName, rawInput) {
+    async handleDraftsTool(agentName, rawInput, callerTurnId) {
         const input = (rawInput && typeof rawInput === 'object' && !Array.isArray(rawInput) ? rawInput : {});
         // 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.
@@ -12391,7 +12533,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;
@@ -12735,8 +12887,10 @@ export class AgentFramework {
         if (metadata?.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 } : {}) });
+        }
     }
     /**
      * Whether `agent`'s store is the residents' one message slot, which every
@@ -12773,12 +12927,12 @@ export class AgentFramework {
     remainingArrival(agent, routing) {
         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;
     }
@@ -12794,11 +12948,13 @@ export class AgentFramework {
      * stored. The locus has moved then too, but the announce baseline hasn't,
      * so the agent's next turn announces where its speech lands.
      */
-    repinTurnLocus(agent, routing, channelId, cause) {
+    repinTurnLocus(agent, routing, channelId, cause, 
+    /** The server of the message that moved it. */
+    serverId) {
         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})`
@@ -13054,11 +13210,13 @@ export class AgentFramework {
      * draft's attempt is journaled durably before the request leaves, and its
      * outcome after, exactly as a drafts resend would.
      */
-    async deliverWithUnsent(agent, body, channelId, unsent) {
+    async deliverWithUnsent(agent, body, channelId, unsent, 
+    /** The server the channel resolves with (triggerServerFor). */
+    serverId) {
         const registry = this.channelRegistry;
         let attemptId;
         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);
@@ -13080,7 +13238,7 @@ 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) {
@@ -13172,7 +13330,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);
@@ -13216,7 +13374,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) {
@@ -13338,7 +13496,7 @@ export class AgentFramework {
             return;
         }
         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);
             }
@@ -14025,6 +14183,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,
             // which an ephemeral run never takes (takesGlobalFallback).
@@ -14040,8 +14201,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);
             }
@@ -14057,7 +14224,7 @@ export class AgentFramework {
                 : undefined;
             routing.arrivals = [];
             if (arrival)
-                this.repinTurnLocus(agent, routing, arrival, '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.
@@ -14576,7 +14743,7 @@ export class AgentFramework {
         };
         const enqueueSpeech = (text, locus) => {
             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:');
         };
@@ -14691,7 +14858,7 @@ export class AgentFramework {
             : null;
         const emitOutgoing = (deltas) => {
             for (const rd of deltas) {
-                this.channelRegistry.sendOutgoingChunk(rd.channelId, agent.name, outgoingInferenceId, outgoingIndex++, rd.delta);
+                this.channelRegistry.sendOutgoingChunk(rd.channelId, agent.name, outgoingInferenceId, outgoingIndex++, rd.delta, triggerServerFor(streamRouting, rd.channelId));
             }
         };
         // Tool-result-guard publication boundary. While a SUBMITTED batch is
@@ -15539,7 +15706,7 @@ export class AgentFramework {
                                     console.error(`[routing] ${agent.name}: text-only turn -> routing speech -> ${locus ?? '(none)'}`);
                                     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) {
@@ -15633,7 +15800,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) {
@@ -16279,7 +16446,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}`);
@@ -16554,7 +16721,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,
         // ephemerals, ModuleContext.callTool) reach utilities the same way the
@@ -18031,7 +18198,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 });
@@ -19423,7 +19590,7 @@ export class AgentFramework {
             const source = this.pushSource(event);
             this.noteInboundAccepted(source);
             return source;
-        });
+        }, (serverId, params) => this.channelOfAnotherServer(serverId, params.origin));
         // Server-initiated inference router (Step 6)
         this.inferenceRouter = new InferenceRouter(this.membrane, this.hookOrchestrator, this.featureSetManager, inferenceRouting ?? null, (event) => this.emitTrace(event));
         // Checkpoint manager (Step 8), built and loaded at the top
@@ -22688,7 +22855,16 @@ export class AgentFramework {
         // ordinary wake, starts only once its over-budget boundary has every
         // result of the round.
         const callingTurn = this.routingOf(agentName);
-        this.channelRegistry.handleChannelToolCall(call.name, call.input, { kind: 'agent', agentName })
+        const inTurn = call.callerTurnId !== undefined && call.callerTurnId === callingTurn.turnId;
+        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({
@@ -22725,7 +22901,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?.serverId === 'string'
+                                ? { serverId: call.input.serverId }
+                                : {}),
+                            channelId: opened,
+                        });
+                        setTurnLocus(callingTurn, opened, 'error' in openedOn ? undefined : openedOn.destination.serverId);
                         this.lastAnnouncedLocus.set(agentName, opened);
                         result = {
                             ...result,
@@ -22978,9 +23160,10 @@ 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);
                     });
                 }
@@ -22989,8 +23172,9 @@ export class AgentFramework {
                 }
             }
             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);
                 });
             }