@letta-ai/letta-code 0.34.1 → 0.34.2

package/dist/gateway-core.js

@@ -485,6 +485,117 @@ class ChannelControlRequestCoordinator {
     return true;
   }
 }
+// src/channels/gateway-assistant-relay.ts
+class GatewayAssistantTextAccumulator {
+  currentMessageId;
+  currentText;
+  deltaKeys;
+  finalizedMessageIds;
+  constructor(state) {
+    this.currentMessageId = state?.currentMessageId ?? null;
+    this.currentText = state?.currentText ?? "";
+    this.deltaKeys = new Set(state?.deltaKeys ?? []);
+    this.finalizedMessageIds = new Set(state?.finalizedMessageIds ?? []);
+  }
+  snapshot() {
+    return {
+      currentMessageId: this.currentMessageId,
+      currentText: this.currentText,
+      deltaKeys: [...this.deltaKeys],
+      finalizedMessageIds: [...this.finalizedMessageIds]
+    };
+  }
+  handleDelta(message) {
+    const delta = message.delta;
+    if (delta.message_type === "assistant_message") {
+      const messageId = delta.otid || delta.id;
+      if (!messageId || this.finalizedMessageIds.has(messageId))
+        return [];
+      const finalized = this.currentMessageId && this.currentMessageId !== messageId ? this.finalizeCurrent() : null;
+      if (!this.currentMessageId)
+        this.currentMessageId = messageId;
+      if (!this.deltaKeys.has(message.idempotency_key)) {
+        const text = typeof delta.content === "string" ? delta.content : delta.content.map((part) => part.text ?? "").join("");
+        this.deltaKeys.add(message.idempotency_key);
+        this.currentText += text;
+      }
+      return finalized ? [finalized] : [];
+    }
+    if (delta.message_type === "tool_call_message" || delta.message_type === "approval_request_message") {
+      const finalized = this.finalizeCurrent();
+      return finalized ? [finalized] : [];
+    }
+    if (delta.message_type === "reasoning_message") {
+      const boundaryId = delta.otid || delta.id;
+      if (this.currentMessageId && (!boundaryId || boundaryId !== this.currentMessageId)) {
+        const finalized = this.finalizeCurrent();
+        return finalized ? [finalized] : [];
+      }
+    }
+    return [];
+  }
+  finalizeCurrent() {
+    const messageId = this.currentMessageId;
+    if (!messageId)
+      return null;
+    const text = this.currentText.trim();
+    this.currentMessageId = null;
+    this.currentText = "";
+    this.finalizedMessageIds.add(messageId);
+    return text ? { messageId, text } : null;
+  }
+}
+function relayFinalizedAssistantMessage(options) {
+  if (options.sources.length !== 1 || !options.relay)
+    return;
+  const warn = (error) => {
+    const detail = error instanceof Error ? error.message : String(error);
+    console.warn(`[channels] Automatic relay failed: ${detail}`);
+  };
+  try {
+    const pending = options.relay({
+      text: options.message.text,
+      sources: options.sources,
+      idempotencyScope: options.idempotencyScope
+    });
+    if (pending)
+      return pending.catch(warn);
+  } catch (error) {
+    warn(error);
+  }
+}
+function stopReasonFromDelta(message) {
+  const delta = message.delta;
+  return delta.message_type === "stop_reason" && "stop_reason" in delta && typeof delta.stop_reason === "string" ? delta.stop_reason : null;
+}
+function runIdFromDelta(message) {
+  const runId = "run_id" in message.delta ? message.delta.run_id : undefined;
+  return typeof runId === "string" && runId.length > 0 ? runId : undefined;
+}
+function channelTurnOutcome(stopReason) {
+  if (stopReason === "cancelled")
+    return "cancelled";
+  return stopReason === "end_turn" || stopReason === "tool_rule" ? "completed" : "error";
+}
+
+// src/channels/gateway-registration-policy.ts
+async function prepareGatewayRegistrationPolicy(options) {
+  const automaticRelay = options.override ?? (options.hooks.resolveAssistantRelayPolicy ? await options.hooks.resolveAssistantRelayPolicy(options.runtime, options.sources) : Boolean(options.hooks.relayAssistantText));
+  const tool = await options.hooks.buildExternalTool(options.runtime, options.sources, { automaticRelay });
+  return { automaticRelay, tool };
+}
+function modelStatusFromRuntimeStart(response, runtime) {
+  const agent = response.agent;
+  const conversation = response.conversation;
+  const agentModel = typeof agent?.model === "string" ? agent.model : response.agent?.llm_config?.model ?? null;
+  const conversationModel = typeof conversation?.model === "string" ? conversation.model : null;
+  const isAgentScope = runtime.conversation_id === "default";
+  return {
+    modelHandle: isAgentScope ? agentModel : conversationModel ?? agentModel,
+    scope: isAgentScope ? "agent" : "conversation"
+  };
+}
+
 // src/channels/gateway-sources.ts
 function sourceRouteKey(source) {
   return [
@@ -514,6 +625,229 @@ function uniqueRoutedSources(sources) {
 function uniqueLifecycleSources(sources) {
   return uniqueSourcesBy(sources, sourceLifecycleKey);
 }
+function channelTagsForSources(sources) {
+  return [...new Set(sources.map((source) => `channel:${source.channel}`))];
+}
+
+// src/channels/gateway-runtime-registration.ts
+async function performGatewayRuntimeRegistration(options) {
+  const {
+    client,
+    hooks,
+    state,
+    delivery,
+    policyOverride,
+    externalToolsOverride
+  } = options;
+  const prepared = externalToolsOverride ? { automaticRelay: policyOverride ?? false, tool: null } : await prepareGatewayRegistrationPolicy({
+    hooks,
+    runtime: delivery.runtime,
+    sources: delivery.sources,
+    ...policyOverride === undefined ? {} : { override: policyOverride }
+  });
+  const { automaticRelay, tool } = prepared;
+  const externalTools = externalToolsOverride ?? (tool ? [{ tools: [tool] }] : []);
+  const conversationTags = channelTagsForSources(delivery.sources);
+  const signature = JSON.stringify({
+    mode: delivery.defaultPermissionMode ?? null,
+    automaticRelay,
+    externalTools,
+    conversationTags
+  });
+  if (state.registrationSignature === signature && state.registration) {
+    await state.registration;
+    return automaticRelay;
+  }
+  const registration = client.runtimeStart({
+    agent_id: delivery.runtime.agent_id,
+    conversation_id: delivery.runtime.conversation_id,
+    ...conversationTags.length > 0 ? { conversation_source_tags: conversationTags } : {},
+    ...delivery.defaultPermissionMode ? { mode: delivery.defaultPermissionMode } : {},
+    recover_approvals: true,
+    force_device_status: false,
+    wait_for_replay: true,
+    preserve_skill_sources: true,
+    client_info: { name: "channel-gateway", title: "Channel Gateway" },
+    external_tools: externalTools
+  }).then((response) => {
+    if (!response.success) {
+      throw new Error(response.error ?? "Failed to register channel runtime");
+    }
+    state.modelStatus = modelStatusFromRuntimeStart(response, delivery.runtime);
+  });
+  state.registrationSignature = signature;
+  state.registration = registration;
+  try {
+    await registration;
+  } catch (error) {
+    if (state.registration === registration) {
+      state.registration = null;
+      state.registrationSignature = null;
+    }
+    throw error;
+  }
+  return automaticRelay;
+}
+
+// src/channels/gateway-runtime-state.ts
+var MAX_ACCEPTED_CLIENT_MESSAGE_IDS = 2048;
+function gatewayRuntimeKey(runtime) {
+  return `${runtime.agent_id}:${runtime.conversation_id}`;
+}
+function hasAgentRuntime(value) {
+  return !!value.runtime?.agent_id;
+}
+function hasGatewayRuntimeWork(state) {
+  return Boolean(state && (state.active || state.pendingSourcesByClientMessageId.size > 0));
+}
+function rememberAcceptedClientMessageId(state, clientMessageId) {
+  state.acceptedClientMessageIds.delete(clientMessageId);
+  state.acceptedClientMessageIds.add(clientMessageId);
+  if (state.acceptedClientMessageIds.size <= MAX_ACCEPTED_CLIENT_MESSAGE_IDS)
+    return;
+  const oldest = state.acceptedClientMessageIds.values().next().value;
+  if (oldest)
+    state.acceptedClientMessageIds.delete(oldest);
+}
+function remainingGatewaySources(state) {
+  return uniqueLifecycleSources([
+    ...state.active?.lifecycleSources ?? [],
+    ...Array.from(state.pendingSourcesByClientMessageId.values()).flatMap((pending) => pending.sources)
+  ]);
+}
+
+// src/channels/gateway-runtime-tool-scopes.ts
+var RETRY_DELAY_MS = 1000;
+function runtimeKey(runtime) {
+  return `${runtime.agent_id}:${runtime.conversation_id}`;
+}
+
+class GatewayRuntimeToolScopes {
+  client;
+  states = new Map;
+  retryTimers = new Set;
+  closed = false;
+  constructor(client) {
+    this.client = client;
+  }
+  create(runtime, sources, automaticRelay, tool) {
+    const id = `channel-turn-${crypto.randomUUID()}`;
+    const scope = {
+      id,
+      runtime,
+      sources: structuredClone(sources),
+      automaticRelay,
+      ...tool ? { group: { scope_id: id, tools: [structuredClone(tool)] } } : {}
+    };
+    this.retain(scope);
+    return scope;
+  }
+  retain(scope) {
+    this.getState(scope.runtime).scopes.set(scope.id, scope);
+  }
+  detach(scope) {
+    this.states.get(runtimeKey(scope.runtime))?.scopes.delete(scope.id);
+    return scope;
+  }
+  release(scope) {
+    this.states.get(runtimeKey(scope.runtime))?.scopes.delete(scope.id);
+  }
+  resolve(runtime, scopeId) {
+    return this.states.get(runtimeKey(runtime))?.scopes.get(scopeId) ?? null;
+  }
+  selection(scope) {
+    return [scope.id];
+  }
+  hasRetainedScopes(runtime) {
+    return (this.states.get(runtimeKey(runtime))?.scopes.size ?? 0) > 0;
+  }
+  registrationGroups(runtime, includeUnscoped) {
+    const state = this.states.get(runtimeKey(runtime));
+    if (!state)
+      return [];
+    const scoped = [...state.scopes.values()].flatMap((scope) => scope.group ? [scope.group] : []);
+    return includeUnscoped ? [...scoped, ...state.desiredUnscoped] : scoped;
+  }
+  setDesiredUnscoped(runtime, groups) {
+    this.getState(runtime).desiredUnscoped = groups;
+  }
+  async updateDesiredUnscoped(updates, isBusy) {
+    const immediateByTools = new Map;
+    for (const update of updates) {
+      for (const runtime of update.runtimes) {
+        this.getState(runtime).desiredUnscoped = update.external_tools;
+        if (!isBusy(runtime)) {
+          const externalTools = this.registrationGroups(runtime, true);
+          const signature = JSON.stringify(externalTools);
+          const existing = immediateByTools.get(signature);
+          if (existing)
+            existing.runtimes.push(runtime);
+          else
+            immediateByTools.set(signature, {
+              runtimes: [runtime],
+              external_tools: externalTools
+            });
+        }
+      }
+    }
+    const immediate = [...immediateByTools.values()];
+    if (immediate.length === 0)
+      return;
+    const response = await this.client.runtimeExternalToolsUpdate({
+      updates: immediate
+    });
+    if (!response.success) {
+      throw new Error(response.error ?? "Failed to update routed runtime tools");
+    }
+  }
+  flushWhenIdle(runtime, isBusy, schedule) {
+    if (isBusy() || this.closed)
+      return;
+    schedule(async () => {
+      if (isBusy())
+        return;
+      const response = await this.client.runtimeExternalToolsUpdate({
+        updates: [
+          {
+            runtimes: [runtime],
+            external_tools: this.registrationGroups(runtime, true)
+          }
+        ]
+      });
+      if (!response.success) {
+        throw new Error(response.error ?? "Failed to update routed runtime tools");
+      }
+    }).catch(() => {
+      if (this.closed)
+        return;
+      const timer = setTimeout(() => {
+        this.retryTimers.delete(timer);
+        this.flushWhenIdle(runtime, isBusy, schedule);
+      }, RETRY_DELAY_MS);
+      timer.unref?.();
+      this.retryTimers.add(timer);
+    });
+  }
+  forgetRuntime(runtime) {
+    this.states.delete(runtimeKey(runtime));
+  }
+  close() {
+    this.closed = true;
+    for (const timer of this.retryTimers)
+      clearTimeout(timer);
+    this.retryTimers.clear();
+    this.states.clear();
+  }
+  getState(runtime) {
+    const key = runtimeKey(runtime);
+    let state = this.states.get(key);
+    if (!state) {
+      state = { runtime, scopes: new Map, desiredUnscoped: [] };
+      this.states.set(key, state);
+    }
+    return state;
+  }
+}
 
 // src/channels/message-channel-idempotency.ts
 class MessageChannelDuplicateActionError extends Error {
@@ -526,38 +860,108 @@ class MessageChannelDuplicateActionError extends Error {
 function isErrorResult(result) {
   return result.startsWith("Error:");
 }
-function createMessageChannelIdempotencyScope() {
-  const inFlight = new Map;
-  let lastSuccessful = null;
+function createMessageChannelIdempotencyScope(state) {
+  const inFlightActionKeys = new Map;
+  const inFlightTextDeliveryKeys = new Map;
+  const inFlightRelayTextDeliveryKeys = new Set;
+  const successfulActionKeys = new Set(state?.successfulActionKeys ?? []);
+  const successfulTextDeliveryKeys = new Set(state?.successfulTextDeliveryKeys ?? []);
+  const successfulRelayTextDeliveryKeys = new Set(state?.successfulRelayTextDeliveryKeys ?? []);
+  let lastSuccessfulActionKey = state?.lastSuccessfulActionKey ?? null;
   let latestInvocation = 0;
+  const addInFlightTextDelivery = (key) => {
+    if (key) {
+      inFlightTextDeliveryKeys.set(key, (inFlightTextDeliveryKeys.get(key) ?? 0) + 1);
+    }
+  };
+  const removeInFlightTextDelivery = (key) => {
+    if (!key)
+      return;
+    const remaining = (inFlightTextDeliveryKeys.get(key) ?? 1) - 1;
+    if (remaining > 0)
+      inFlightTextDeliveryKeys.set(key, remaining);
+    else
+      inFlightTextDeliveryKeys.delete(key);
+  };
   return {
-    async execute(key, effect) {
-      if (!key) {
+    async execute(actionKey, textDeliveryKey, effect) {
+      if (!actionKey) {
         latestInvocation += 1;
-        lastSuccessful = null;
+        lastSuccessfulActionKey = null;
         return await effect();
       }
-      const pendingDuplicate = inFlight.get(key);
-      if (pendingDuplicate) {
+      if (inFlightActionKeys.has(actionKey) || textDeliveryKey && inFlightRelayTextDeliveryKeys.has(textDeliveryKey)) {
         throw new MessageChannelDuplicateActionError("in-flight");
       }
-      if (lastSuccessful?.key === key) {
+      if (lastSuccessfulActionKey === actionKey || textDeliveryKey && successfulRelayTextDeliveryKeys.has(textDeliveryKey)) {
         throw new MessageChannelDuplicateActionError("completed");
       }
       const invocation = ++latestInvocation;
-      lastSuccessful = null;
+      lastSuccessfulActionKey = null;
       const pending = Promise.resolve().then(effect);
-      inFlight.set(key, pending);
+      inFlightActionKeys.set(actionKey, pending);
+      addInFlightTextDelivery(textDeliveryKey);
       try {
         const result = await pending;
-        if (invocation === latestInvocation && !isErrorResult(result)) {
-          lastSuccessful = { key };
+        if (!isErrorResult(result)) {
+          successfulActionKeys.add(actionKey);
+          if (textDeliveryKey)
+            successfulTextDeliveryKeys.add(textDeliveryKey);
+          if (invocation === latestInvocation) {
+            lastSuccessfulActionKey = actionKey;
+          }
         }
         return result;
       } finally {
-        if (inFlight.get(key) === pending)
-          inFlight.delete(key);
+        if (inFlightActionKeys.get(actionKey) === pending) {
+          inFlightActionKeys.delete(actionKey);
+        }
+        removeInFlightTextDelivery(textDeliveryKey);
       }
+    },
+    async executeRelay(actionKey, textDeliveryKey, effect) {
+      if (!actionKey)
+        return await effect();
+      if (inFlightActionKeys.has(actionKey) || textDeliveryKey && inFlightTextDeliveryKeys.has(textDeliveryKey)) {
+        throw new MessageChannelDuplicateActionError("in-flight");
+      }
+      if (successfulActionKeys.has(actionKey) || textDeliveryKey && successfulTextDeliveryKeys.has(textDeliveryKey)) {
+        throw new MessageChannelDuplicateActionError("completed");
+      }
+      const pending = Promise.resolve().then(effect);
+      inFlightActionKeys.set(actionKey, pending);
+      addInFlightTextDelivery(textDeliveryKey);
+      if (textDeliveryKey)
+        inFlightRelayTextDeliveryKeys.add(textDeliveryKey);
+      try {
+        const result = await pending;
+        if (!isErrorResult(result)) {
+          successfulActionKeys.add(actionKey);
+          if (textDeliveryKey) {
+            successfulTextDeliveryKeys.add(textDeliveryKey);
+            successfulRelayTextDeliveryKeys.add(textDeliveryKey);
+          }
+        }
+        return result;
+      } finally {
+        if (inFlightActionKeys.get(actionKey) === pending) {
+          inFlightActionKeys.delete(actionKey);
+        }
+        removeInFlightTextDelivery(textDeliveryKey);
+        if (textDeliveryKey)
+          inFlightRelayTextDeliveryKeys.delete(textDeliveryKey);
+      }
+    },
+    snapshot() {
+      if (inFlightActionKeys.size > 0 || inFlightTextDeliveryKeys.size > 0) {
+        return null;
+      }
+      return {
+        successfulActionKeys: [...successfulActionKeys],
+        successfulTextDeliveryKeys: [...successfulTextDeliveryKeys],
+        successfulRelayTextDeliveryKeys: [...successfulRelayTextDeliveryKeys],
+        lastSuccessfulActionKey
+      };
     }
   };
 }
@@ -1344,50 +1748,40 @@ function createChannelTurnProgressBuilder(options = {}) {
 }
 
 // src/channels/gateway-core.ts
-var MAX_ACCEPTED_CLIENT_MESSAGE_IDS = 2048;
-function runtimeKey(runtime) {
-  return `${runtime.agent_id}:${runtime.conversation_id}`;
-}
-function hasAgentRuntime(value) {
-  return !!value.runtime?.agent_id;
-}
-function channelTagsForSources(sources) {
-  return [...new Set(sources.map((source) => `channel:${source.channel}`))];
-}
-function stopReasonFromDelta(message) {
-  const delta = message.delta;
-  return delta.message_type === "stop_reason" && "stop_reason" in delta && typeof delta.stop_reason === "string" ? delta.stop_reason : null;
-}
-function runIdFromDelta(message) {
-  const runId = "run_id" in message.delta ? message.delta.run_id : undefined;
-  return typeof runId === "string" && runId.length > 0 ? runId : undefined;
-}
-function lifecycleOutcome(stopReason) {
-  if (stopReason === "cancelled")
-    return "cancelled";
-  if (stopReason === "end_turn" || stopReason === "tool_rule") {
-    return "completed";
-  }
-  return "error";
-}
-
 class ChannelGateway {
   client;
   hooks;
   states = new Map;
   disposers = [];
+  runtimeToolScopes;
   registrationQueue = Promise.resolve();
   constructor(client, hooks) {
     this.client = client;
     this.hooks = hooks;
-    this.disposers.push(client.onMessage((message) => this.handleMessage(message)), client.onExternalToolCall((request) => {
-      const state = hasAgentRuntime(request) ? this.states.get(runtimeKey(request.runtime)) : undefined;
+    this.runtimeToolScopes = new GatewayRuntimeToolScopes(client);
+    this.disposers.push(client.onMessage((message) => this.handleMessage(message)), client.onExternalToolCall(async (request) => {
+      const state = hasAgentRuntime(request) ? this.states.get(gatewayRuntimeKey(request.runtime)) : undefined;
       const active = state?.active;
-      const sources = active?.routingSources ?? state?.routedSources ?? [];
-      return hooks.executeExternalTool(request, sources, active?.idempotencyScope ?? null);
+      const scoped = hasAgentRuntime(request) && request.scope_id ? this.runtimeToolScopes.resolve(request.runtime, request.scope_id) : null;
+      if (request.scope_id && !scoped) {
+        throw new Error(`Unknown or stale external tool scope: ${request.scope_id}`);
+      }
+      const sources = scoped?.sources ?? active?.routingSources ?? state?.routedSources ?? [];
+      const activeOwnsScope = Boolean(scoped && active?.toolScopes.some((scope) => scope.id === scoped.id));
+      try {
+        return await hooks.executeExternalTool(request, sources, activeOwnsScope || !request.scope_id && active ? active?.idempotencyScope : null);
+      } catch (error) {
+        if (!(error instanceof MessageChannelDuplicateActionError))
+          throw error;
+        return {
+          content: [{ type: "text", text: error.message }],
+          is_error: true
+        };
+      }
     }));
   }
   close() {
+    this.runtimeToolScopes.close();
     for (const dispose of this.disposers.splice(0))
       dispose();
     this.client.close();
@@ -1412,16 +1806,34 @@ class ChannelGateway {
     const workAtSubmit = state.active || state.pendingSourcesByClientMessageId.size > 0;
     state.pendingSourcesByClientMessageId.set(delivery.clientMessageId, {
       sources: uniqueLifecycleSources(delivery.sources),
-      disposition: "submitting"
+      disposition: "submitting",
+      automaticRelay: false
     });
     try {
-      await this.enqueueRegistration(async () => {
+      const toolScope = await this.enqueueRegistration(async () => {
         state.routedSources = uniqueRoutedSources([
           ...state.routedSources,
           ...delivery.sources
         ]);
-        await this.performRuntimeRegistration(state, delivery);
+        const { automaticRelay, tool } = await prepareGatewayRegistrationPolicy({
+          hooks: this.hooks,
+          runtime: delivery.runtime,
+          sources: delivery.sources
+        });
+        const scope = this.runtimeToolScopes.create(delivery.runtime, delivery.sources, automaticRelay, tool);
+        try {
+          await this.performRuntimeRegistration(state, delivery, automaticRelay, this.runtimeToolScopes.registrationGroups(delivery.runtime, false));
+          return scope;
+        } catch (error) {
+          this.runtimeToolScopes.release(scope);
+          throw error;
+        }
       });
+      const submitted = state.pendingSourcesByClientMessageId.get(delivery.clientMessageId);
+      if (submitted) {
+        submitted.automaticRelay = toolScope.automaticRelay;
+        submitted.toolScope = toolScope;
+      }
       const response = await this.client.submitInput({
         runtime: delivery.runtime,
         payload: {
@@ -1434,21 +1846,24 @@ class ChannelGateway {
             }
           ],
           image_failure_mode: "drop",
-          client_preferences: {}
+          client_preferences: {},
+          external_tool_scope_ids: this.runtimeToolScopes.selection(toolScope)
         }
       });
       if (!response.accepted) {
         state.pendingSourcesByClientMessageId.delete(delivery.clientMessageId);
+        this.runtimeToolScopes.release(toolScope);
+        this.finishToolScopesIfIdle(state);
         if (workAtSubmit && !state.active)
           this.finishRejectedDelivery(state, delivery);
         return false;
       }
-      this.rememberAcceptedClientMessageId(state, delivery.clientMessageId);
+      rememberAcceptedClientMessageId(state, delivery.clientMessageId);
       for (const source of delivery.sources) {
         this.enqueueHook(state, () => this.hooks.onLifecycle({ type: "queued", source }));
       }
       if (response.disposition === "started") {
-        this.activateSources(state, delivery.clientMessageId, delivery.sources);
+        this.activateSources(state, delivery.clientMessageId, delivery.sources, toolScope.automaticRelay, toolScope);
         state.pendingSourcesByClientMessageId.delete(delivery.clientMessageId);
       } else if (response.disposition === "queued") {
         const pending = state.pendingSourcesByClientMessageId.get(delivery.clientMessageId);
@@ -1459,20 +1874,19 @@ class ChannelGateway {
       }
       return true;
     } catch (error) {
+      const failed = state.pendingSourcesByClientMessageId.get(delivery.clientMessageId);
       state.pendingSourcesByClientMessageId.delete(delivery.clientMessageId);
+      if (failed?.toolScope) {
+        this.runtimeToolScopes.release(failed.toolScope);
+      }
+      this.finishToolScopesIfIdle(state);
       if (workAtSubmit && !state.active)
         this.finishRejectedDelivery(state, delivery);
       throw error;
     }
   }
-  remainingSources(state) {
-    return uniqueLifecycleSources([
-      ...state.active?.lifecycleSources ?? [],
-      ...Array.from(state.pendingSourcesByClientMessageId.values()).flatMap((pending) => pending.sources)
-    ]);
-  }
   finishRejectedDelivery(state, delivery) {
-    const remainingSources = this.remainingSources(state);
+    const remainingSources = remainingGatewaySources(state);
     this.enqueueHook(state, () => this.hooks.onLifecycle({
       type: "finished",
       batchId: `channel-${delivery.clientMessageId}`,
@@ -1497,13 +1911,14 @@ class ChannelGateway {
     }
     state.pendingSourcesByClientMessageId.set(delivery.clientMessageId, {
       sources,
-      disposition: "queued"
+      disposition: "queued",
+      automaticRelay: false
     });
     state.routedSources = uniqueRoutedSources([
       ...state.routedSources,
       ...delivery.sources
     ]);
-    this.rememberAcceptedClientMessageId(state, delivery.clientMessageId);
+    rememberAcceptedClientMessageId(state, delivery.clientMessageId);
   }
   async restoreRuntime(runtime, sources) {
     const state = this.getState(runtime);
@@ -1516,7 +1931,10 @@ class ChannelGateway {
         lifecycleSources: uniqueLifecycleSources(sources),
         progress: createChannelTurnProgressBuilder(),
         richDraft: null,
-        idempotencyScope: createMessageChannelIdempotencyScope()
+        assistantText: new GatewayAssistantTextAccumulator,
+        idempotencyScope: createMessageChannelIdempotencyScope(),
+        relayEligible: false,
+        toolScopes: []
       };
       state.active = recoveredTurn;
     }
@@ -1534,7 +1952,7 @@ class ChannelGateway {
     return replayedRequestIds;
   }
   async adoptActiveDelivery(delivery) {
-    const key = runtimeKey(delivery.runtime);
+    const key = gatewayRuntimeKey(delivery.runtime);
     const stateExisted = this.states.has(key);
     const state = this.getState(delivery.runtime);
     const batchId = `channel-${delivery.clientMessageId}`;
@@ -1543,8 +1961,8 @@ class ChannelGateway {
         if (state.active.batchId !== batchId) {
           throw new Error(`Cannot adopt ${batchId}; ${state.active.batchId} is already active`);
         }
-        this.activateSources(state, delivery.clientMessageId, delivery.sources);
-        this.rememberAcceptedClientMessageId(state, delivery.clientMessageId);
+        this.activateSources(state, delivery.clientMessageId, delivery.sources, state.active.relayEligible);
+        rememberAcceptedClientMessageId(state, delivery.clientMessageId);
         return;
       }
       const previousRoutedSources = state.routedSources;
@@ -1556,19 +1974,21 @@ class ChannelGateway {
         lifecycleSources: uniqueLifecycleSources(delivery.sources),
         progress: createChannelTurnProgressBuilder(),
         richDraft: null,
-        idempotencyScope: createMessageChannelIdempotencyScope()
+        assistantText: new GatewayAssistantTextAccumulator(delivery.activeTurnState?.assistantText),
+        idempotencyScope: createMessageChannelIdempotencyScope(delivery.activeTurnState?.idempotency),
+        relayEligible: delivery.activeTurnState?.automaticRelay ?? Boolean(delivery.activeTurnState),
+        toolScopes: delivery.activeTurnState?.toolScopes ?? []
       };
       state.active = active;
+      for (const scope of active.toolScopes)
+        this.runtimeToolScopes.retain(scope);
       state.routedSources = uniqueRoutedSources([
         ...state.routedSources,
         ...delivery.sources
       ]);
-      this.rememberAcceptedClientMessageId(state, delivery.clientMessageId);
+      rememberAcceptedClientMessageId(state, delivery.clientMessageId);
       try {
-        await this.performRuntimeRegistration(state, {
-          ...delivery,
-          content: ""
-        });
+        await this.performRuntimeRegistration(state, { ...delivery, content: "" }, active.relayEligible, this.runtimeToolScopes.registrationGroups(delivery.runtime, false));
         if (state.active !== active)
           return;
         active.richDraft = this.hooks.createRichDraft?.({
@@ -1582,6 +2002,9 @@ class ChannelGateway {
         }));
       } catch (error) {
         active.richDraft?.dispose();
+        for (const scope of active.toolScopes) {
+          this.runtimeToolScopes.release(scope);
+        }
         if (state.active === active)
           state.active = null;
         state.routedSources = previousRoutedSources;
@@ -1595,51 +2018,67 @@ class ChannelGateway {
     });
   }
   releaseActiveDelivery(runtime, clientMessageId) {
-    const key = runtimeKey(runtime);
+    const key = gatewayRuntimeKey(runtime);
     const state = this.states.get(key);
     const active = state?.active;
     if (!state || active?.batchId !== `channel-${clientMessageId}`) {
-      return false;
+      return null;
     }
+    if (state.hookQueue)
+      return null;
+    const idempotency = active.idempotencyScope.snapshot();
+    if (!idempotency)
+      return null;
+    const toolScopes = active.toolScopes.map((scope) => this.runtimeToolScopes.detach(scope));
+    const handoffState = {
+      assistantText: active.assistantText.snapshot(),
+      idempotency,
+      automaticRelay: active.relayEligible,
+      ...toolScopes.length > 0 ? { toolScopes } : {}
+    };
     active.richDraft?.dispose();
     this.states.delete(key);
-    return true;
+    return handoffState;
   }
   async registerRuntime(runtime, sources = [], defaultPermissionMode) {
     const state = this.getState(runtime);
     await this.enqueueRegistration(async () => {
       this.setRoutedSources(runtime, sources);
+      const prepared = await prepareGatewayRegistrationPolicy({
+        hooks: this.hooks,
+        runtime,
+        sources
+      });
+      const externalTools = prepared.tool ? [{ tools: [prepared.tool] }] : [];
+      this.runtimeToolScopes.setDesiredUnscoped(runtime, externalTools);
+      if (this.runtimeToolScopes.hasRetainedScopes(runtime))
+        return;
       await this.performRuntimeRegistration(state, {
         runtime,
         content: "",
         sources,
         clientMessageId: "recovered",
         ...defaultPermissionMode ? { defaultPermissionMode } : {}
-      });
+      }, prepared.automaticRelay, externalTools);
     });
   }
   async publishRuntimeTools(runtime, sources = []) {
     return await this.enqueueRegistration(async () => {
-      if (this.states.has(runtimeKey(runtime)))
+      if (this.states.has(gatewayRuntimeKey(runtime)))
         return false;
       const tool = await this.hooks.buildExternalTool(runtime, sources);
-      const response = await this.client.runtimeExternalToolsUpdate({
-        updates: [
-          {
-            runtimes: [runtime],
-            external_tools: tool ? [{ tools: [tool] }] : []
-          }
-        ]
-      });
-      if (!response.success) {
-        throw new Error(response.error ?? "Failed to publish channel runtime tools");
-      }
+      await this.runtimeToolScopes.updateDesiredUnscoped([
+        {
+          runtimes: [runtime],
+          external_tools: tool ? [{ tools: [tool] }] : []
+        }
+      ], () => false);
       return tool !== null;
     });
   }
   async releaseRuntimeTools(runtime, routedSources = [], options = {}) {
     await this.enqueueRegistration(async () => {
-      const key = runtimeKey(runtime);
+      const key = gatewayRuntimeKey(runtime);
       const state = this.states.get(key);
       if (options.cleanupIdleRuntime) {
         if (routedSources.length > 0 || (state?.routedSources.length ?? 0) > 0) {
@@ -1661,6 +2100,7 @@ class ChannelGateway {
       if (!response.success) {
         throw new Error(response.error ?? "Failed to release channel runtime tools");
       }
+      this.runtimeToolScopes.forgetRuntime(runtime);
     });
   }
   async submitApprovalResponse(runtime, response) {
@@ -1678,21 +2118,14 @@ class ChannelGateway {
   }
   updateRoutedRuntimeTools(updates, routedSources) {
     return this.enqueueRegistration(async () => {
-      if (updates.length > 0) {
-        const response = await this.client.runtimeExternalToolsUpdate({
-          updates
-        });
-        if (!response.success) {
-          throw new Error(response.error ?? "Failed to update routed runtime tools");
-        }
-      }
+      await this.runtimeToolScopes.updateDesiredUnscoped(updates, (runtime) => hasGatewayRuntimeWork(this.states.get(gatewayRuntimeKey(runtime))));
       for (const update of routedSources) {
         this.setRoutedSources(update.runtime, update.sources);
       }
     });
   }
   getModelStatus(runtime) {
-    return this.states.get(runtimeKey(runtime))?.modelStatus ?? null;
+    return this.states.get(gatewayRuntimeKey(runtime))?.modelStatus ?? null;
   }
   updateModelStatus(runtime, modelHandle) {
     const state = this.getState(runtime);
@@ -1702,7 +2135,7 @@ class ChannelGateway {
     };
   }
   getState(runtime) {
-    const key = runtimeKey(runtime);
+    const key = gatewayRuntimeKey(runtime);
     let state = this.states.get(key);
     if (!state) {
       state = {
@@ -1722,14 +2155,10 @@ class ChannelGateway {
     }
     return state;
   }
-  rememberAcceptedClientMessageId(state, clientMessageId) {
-    state.acceptedClientMessageIds.delete(clientMessageId);
-    state.acceptedClientMessageIds.add(clientMessageId);
-    if (state.acceptedClientMessageIds.size <= MAX_ACCEPTED_CLIENT_MESSAGE_IDS)
+  finishToolScopesIfIdle(state) {
+    if (state.active || state.pendingSourcesByClientMessageId.size > 0)
       return;
-    const oldest = state.acceptedClientMessageIds.values().next().value;
-    if (oldest)
-      state.acceptedClientMessageIds.delete(oldest);
+    this.runtimeToolScopes.flushWhenIdle(state.runtime, () => hasGatewayRuntimeWork(this.states.get(gatewayRuntimeKey(state.runtime))), (task) => this.enqueueRegistration(task));
   }
   enqueueHook(state, hook) {
     let pending;
@@ -1763,52 +2192,15 @@ class ChannelGateway {
     });
     return result;
   }
-  async performRuntimeRegistration(state, delivery) {
-    const tool = await this.hooks.buildExternalTool(delivery.runtime, delivery.sources);
-    const conversationTags = channelTagsForSources(delivery.sources);
-    const signature = JSON.stringify({
-      mode: delivery.defaultPermissionMode ?? null,
-      tool,
-      conversationTags
+  async performRuntimeRegistration(state, delivery, policyOverride, externalToolsOverride) {
+    return await performGatewayRuntimeRegistration({
+      client: this.client,
+      hooks: this.hooks,
+      state,
+      delivery,
+      ...policyOverride === undefined ? {} : { policyOverride },
+      ...externalToolsOverride === undefined ? {} : { externalToolsOverride }
     });
-    if (state.registrationSignature === signature && state.registration) {
-      return state.registration;
-    }
-    const registration = this.client.runtimeStart({
-      agent_id: delivery.runtime.agent_id,
-      conversation_id: delivery.runtime.conversation_id,
-      ...conversationTags.length > 0 ? { conversation_source_tags: conversationTags } : {},
-      ...delivery.defaultPermissionMode ? { mode: delivery.defaultPermissionMode } : {},
-      recover_approvals: true,
-      force_device_status: false,
-      wait_for_replay: true,
-      preserve_skill_sources: true,
-      client_info: { name: "channel-gateway", title: "Channel Gateway" },
-      external_tools: tool ? [{ tools: [tool] }] : []
-    }).then((response) => {
-      if (!response.success) {
-        throw new Error(response.error ?? "Failed to register channel runtime");
-      }
-      const agentRecord = response.agent;
-      const conversationRecord = response.conversation;
-      const agentModel = typeof agentRecord?.model === "string" ? agentRecord.model : response.agent?.llm_config?.model ?? null;
-      const conversationModel = typeof conversationRecord?.model === "string" ? conversationRecord.model : null;
-      state.modelStatus = {
-        modelHandle: delivery.runtime.conversation_id === "default" ? agentModel : conversationModel ?? agentModel,
-        scope: delivery.runtime.conversation_id === "default" ? "agent" : "conversation"
-      };
-    });
-    state.registrationSignature = signature;
-    state.registration = registration;
-    try {
-      await registration;
-    } catch (error) {
-      if (state.registration === registration) {
-        state.registration = null;
-        state.registrationSignature = null;
-      }
-      throw error;
-    }
   }
   handleMessage(message) {
     if (message.type === "update_queue") {
@@ -1856,15 +2248,25 @@ class ChannelGateway {
         continue;
       }
       const target = pending.removalDisposition === "dequeued" ? dequeued : cancelled;
-      target.push({ clientMessageId, sources: pending.sources });
+      target.push({
+        clientMessageId,
+        sources: pending.sources,
+        automaticRelay: pending.automaticRelay,
+        ...pending.toolScope ? { toolScope: pending.toolScope } : {}
+      });
       state.pendingSourcesByClientMessageId.delete(clientMessageId);
     }
     const firstDequeued = dequeued[0];
     if (firstDequeued) {
-      this.activateSources(state, firstDequeued.clientMessageId, dequeued.flatMap((entry) => entry.sources));
+      const dequeuedScopes = dequeued.flatMap((entry) => entry.toolScope ? [entry.toolScope] : []);
+      this.activateSources(state, firstDequeued.clientMessageId, dequeued.flatMap((entry) => entry.sources), dequeued.every((entry) => entry.automaticRelay), dequeuedScopes[0]);
+      if (state.active)
+        state.active.toolScopes.push(...dequeuedScopes.slice(1));
     }
     for (const entry of cancelled) {
-      const remainingSources = this.remainingSources(state);
+      if (entry.toolScope)
+        this.runtimeToolScopes.release(entry.toolScope);
+      const remainingSources = remainingGatewaySources(state);
       this.enqueueHook(state, () => this.hooks.onLifecycle({
         type: "finished",
         batchId: `channel-${entry.clientMessageId}`,
@@ -1874,9 +2276,12 @@ class ChannelGateway {
         ...remainingSources.length ? { remainingSources } : {}
       }));
     }
+    this.finishToolScopesIfIdle(state);
   }
-  activateSources(state, clientMessageId, sources) {
+  activateSources(state, clientMessageId, sources, automaticRelay, toolScope) {
     if (state.active) {
+      if (toolScope)
+        state.active.toolScopes.push(toolScope);
       const knownLifecycleKeys = new Set(state.active.lifecycleSources.map(sourceLifecycleKey));
       const addedLifecycleSources = uniqueLifecycleSources(sources).filter((source) => !knownLifecycleKeys.has(sourceLifecycleKey(source)));
       if (addedLifecycleSources.length === 0)
@@ -1889,6 +2294,7 @@ class ChannelGateway {
         ...state.active.routingSources,
         ...sources
       ]);
+      state.active.relayEligible &&= automaticRelay;
       const processingEvent2 = {
         type: "processing",
         batchId: state.active.batchId,
@@ -1908,7 +2314,10 @@ class ChannelGateway {
         batchId: `channel-${clientMessageId}`,
         sources: routingSources
       }) ?? null,
-      idempotencyScope: createMessageChannelIdempotencyScope()
+      assistantText: new GatewayAssistantTextAccumulator,
+      idempotencyScope: createMessageChannelIdempotencyScope(),
+      relayEligible: automaticRelay,
+      toolScopes: toolScope ? [toolScope] : []
     };
     const processingEvent = {
       type: "processing",
@@ -1927,6 +2336,7 @@ class ChannelGateway {
     const runId = runIdFromDelta(message);
     if (runId)
       active.runId = runId;
+    this.enqueueFinalizedAssistantMessages(state, active, active.assistantText.handleDelta(message));
     for (const update of active.progress.buildUpdates(message.delta)) {
       this.enqueueHook(state, () => this.hooks.onProgress({
         type: "progress",
@@ -1937,23 +2347,46 @@ class ChannelGateway {
     }
     active.richDraft?.handleDelta(message.delta);
     const stopReason = stopReasonFromDelta(message);
-    if (stopReason === "requires_approval" || stopReason === "end_turn") {
+    if (stopReason === "requires_approval" || stopReason === "end_turn" || stopReason === "tool_rule") {
       active.richDraft?.flushPending();
+      const finalized = active.assistantText.finalizeCurrent();
+      if (finalized) {
+        this.enqueueFinalizedAssistantMessages(state, active, [finalized]);
+      }
     }
   }
+  enqueueFinalizedAssistantMessages(state, active, messages) {
+    const relay = active.relayEligible ? this.hooks.relayAssistantText : undefined;
+    for (const message of messages)
+      this.enqueueHook(state, () => relayFinalizedAssistantMessage({
+        message,
+        sources: active.routingSources,
+        idempotencyScope: active.idempotencyScope,
+        relay
+      }));
+  }
   handleTurnFinished(runtime, terminal) {
     const state = this.getState(runtime);
     const active = state.active;
     if (!active)
       return;
+    if (terminal.stopReason === "end_turn" || terminal.stopReason === "tool_rule") {
+      const finalized = active.assistantText.finalizeCurrent();
+      if (finalized) {
+        this.enqueueFinalizedAssistantMessages(state, active, [finalized]);
+      }
+    }
     state.active = null;
     active.richDraft?.dispose();
-    const remainingSources = lifecycleOutcome(terminal.stopReason) === "completed" ? this.remainingSources(state) : [];
+    for (const scope of active.toolScopes)
+      this.runtimeToolScopes.release(scope);
+    this.finishToolScopesIfIdle(state);
+    const remainingSources = channelTurnOutcome(terminal.stopReason) === "completed" ? remainingGatewaySources(state) : [];
     this.enqueueHook(state, () => this.hooks.onLifecycle({
       type: "finished",
       batchId: active.batchId,
       sources: active.lifecycleSources,
-      outcome: lifecycleOutcome(terminal.stopReason),
+      outcome: channelTurnOutcome(terminal.stopReason),
       stopReason: terminal.stopReason,
       ...remainingSources.length ? { remainingSources } : {},
       ...terminal.runId ?? active.runId ? { runId: terminal.runId ?? active.runId } : {},
@@ -1963,7 +2396,7 @@ class ChannelGateway {
   handleControlRequest(message) {
     if (!message.agent_id || !message.conversation_id)
       return;
-    const state = this.states.get(runtimeKey({
+    const state = this.states.get(gatewayRuntimeKey({
       agent_id: message.agent_id,
       conversation_id: message.conversation_id
     }));
@@ -2703,6 +3136,20 @@ function messageIdempotencyKey(request, route) {
     replyToMessageId: effectiveTextReplyId(request, route)
   });
 }
+function textDeliveryFingerprint(request, route) {
+  if (request.action !== "send" && request.action !== "send-rich" || request.mediaPath) {
+    return null;
+  }
+  return JSON.stringify({
+    channel: request.channel,
+    chatId: route.chatId,
+    accountId: route.accountId ?? null,
+    chatType: route.chatType ?? null,
+    threadId: effectiveTextThreadId(request, route),
+    message: request.message?.trim() ?? null,
+    replyToMessageId: effectiveTextReplyId(request, route)
+  });
+}
 async function executeMessageChannel(input, options) {
   const normalized = normalizeMessageChannelInput(input, options.resolver);
   if (typeof normalized === "string")
@@ -2771,7 +3218,7 @@ async function executeMessageChannel(input, options) {
       });
       const requestThreadId = normalized.action === "download-file" ? normalized.threadId : inferredThreadId ?? (normalized.channel === "telegram" && context2.route.chatType === "direct" ? normalized.threadId : context2.route.threadId ?? normalized.threadId);
       const request2 = buildMessageChannelRequest(normalized, normalized.chatId, requestThreadId);
-      return await dispatchWithIdempotency(request2, context2, options.idempotencyScope);
+      return await dispatchWithIdempotency(request2, context2, options.idempotencyScope, options.idempotencyMode);
     }
     if (normalized.channel !== "slack") {
       return `Error: Explicit MessageChannel targets are not supported on ${normalized.channel}.`;
@@ -2804,10 +3251,13 @@ async function executeMessageChannel(input, options) {
 async function executeMessageChannelExternalTool(input, options) {
   return createMessageChannelExternalToolResult(await executeMessageChannel(input, options));
 }
-function dispatchWithIdempotency(request, context, scope) {
+function dispatchWithIdempotency(request, context, scope, mode = "explicit") {
   const dispatch = () => dispatchMessageChannelAction({ request, context });
-  const key = messageIdempotencyKey(request, context.route);
-  return scope ? scope.execute(key, dispatch) : dispatch();
+  const actionKey = messageIdempotencyKey(request, context.route);
+  const deliveryKey = textDeliveryFingerprint(request, context.route);
+  if (!scope)
+    return dispatch();
+  return mode === "relay" ? scope.executeRelay(actionKey, deliveryKey, dispatch) : scope.execute(actionKey, deliveryKey, dispatch);
 }
 // src/tools/descriptions/MessageChannel.md
 var MessageChannel_default = '# MessageChannel\n\nSend a message or channel action to an external channel.\n\nWhen you receive a `<channel-notification>`, use this tool to reply directly to the user on the same external channel. A normal assistant response is not delivered back to the external channel automatically.\n\nThere are two supported send modes:\n- Reply mode: use `channel` + `chat_id` from the notification to respond in the current routed chat.\n- Proactive mode: use `channel` + `target` on supported channels to send to an explicit outbound destination.\n\nPreferred reply pattern:\n- `action="send"` to send a normal reply\n- `channel` + `chat_id` from the notification attributes\n- `message` for the text body\n\nParameters:\n- `action`: The action to perform. The exact available actions depend on the active channel plugins and are reflected in the JSON schema.\n- `channel`: The platform to send to.\n- `chat_id`: Reply target for the current routed chat. Use this when responding to a channel notification.\n- `target`: Explicit outbound target for proactive sends on supported channels.\n- `accountId`: Optional channel account selector when multiple eligible accounts are available.\n- `message`: Text body for `action="send"`.\n- `replyTo`: Optional message ID to reply to. Omit this unless you intentionally want the platform\'s quote/reply UI.\n- `messageId`: Optional target message id for message-scoped actions like reactions.\n- `emoji`: Optional reaction payload for channels that support reactions.\n- `remove`: Optional boolean to remove a reaction instead of adding it.\n- `media`: Optional absolute local file path for file/media uploads on channels that support uploads.\n- `filename`: Optional uploaded filename override when supported by the channel.\n- `title`: Optional uploaded attachment title when supported by the channel.\n\nRules:\n- Always pass `action` explicitly, even for a normal reply.\n- Pass exactly one of `chat_id` or `target`.\n- `react` should be its own call.\n- `upload-file` can include both `media` and `message` so the uploaded file has a caption/comment when the channel supports it.\n- Telegram supports `action="send-rich"` for Bot API Rich Messages from Markdown content. Use it for headings, lists, tables, rich block quotes, details blocks, formulas, and longer structured messages; use `upload-file` for local media files.\n\nTelegram rich messages:\n- In Telegram private chats, normal `action="send"` messages are sent through Bot API Rich Messages by default when the Telegram account enables `rich_private_chat_default`; with that setting disabled, use explicit `action="send-rich"` for rich delivery.\n- Use `action="send-rich"` with `channel="telegram"` for structured Markdown rendered by Telegram Bot API Rich Messages.\n- Use this when the output benefits from real headings, tables, block quotes, collapsible details, footnotes, task lists, or formulas.\n- The `message` field is passed as Telegram rich Markdown. Supported examples include:\n  - headings: `# Heading`, `## Heading`\n  - lists: `- item`, `1. item`, `- [ ] task`, `- [x] done`\n  - tables: GitHub-style pipe tables\n  - block quotes: `> quoted text`\n  - collapsible details: `<details><summary>Title</summary>content</details>`\n  - inline math: `$E = mc^2$`\n  - display math: `$$E = mc^2$$` or fenced `math` code blocks\n  - footnotes: `text[^id]` with `[^id]: definition`\n- Prefer dollar-delimited math. `\\(...\\)` and `\\[...\\]` do not reliably render as formulas in Telegram rich Markdown.\n- Do not use `send-rich` for local file uploads. Use `upload-file`; rich Markdown media blocks only support HTTP/HTTPS URLs.\n- Rich messages persist only when the final `send-rich` call executes. If Telegram draft streaming is enabled for the account, the channel runtime may show ephemeral previews automatically; do not try to manage draft lifecycle from the tool call.\n';
@@ -2907,12 +3357,15 @@ function resolveMessageChannelToolChannels(channels) {
       actions.add(action);
     schemaContributions.push(...asSchemaContributionArray(discovery?.schema));
   }
+  const routedDestinationKeys = new Set(channels.map((channel) => channel.routedDestinationKey).filter(Boolean));
+  const hasCompleteDestinationKeys = channels.every((channel) => channel.routedDestinationKey);
   return {
     activeChannels: [...uniqueChannels.keys()],
     displayNames: [...uniqueChannels.values()].map((channel) => channel.displayName),
     accountIds: [...accountIds],
     actions: [...actions],
-    schemaContributions
+    schemaContributions,
+    automaticRelay: channels.length > 0 && channels.every((channel) => channel.replyMode === "relay") && (hasCompleteDestinationKeys ? routedDestinationKeys.size === 1 : channels.length === 1)
   };
 }
 function mergeSchemaContributions(schema, contributions) {
@@ -2990,7 +3443,9 @@ No external channel adapters are currently running.`;
   const channelList = discovery.displayNames.join(", ");
   const actionList = discovery.actions.join(", ");
   const hasAction = (action) => discovery.actions.includes(action);
-  const scopedReplyContract = scoped ? '\n\nThis tool is currently scoped to a routed external channel turn. Plain assistant text is not delivered to that external user. If a user-visible reply is appropriate, your final action for the turn must be one MessageChannel call with action="send", channel from the notification, chat_id from the notification, and message containing the reply. After that final send succeeds, do not repeat or paraphrase the sent message in assistant text; finish with only `Sent.` as the internal confirmation. This does not apply to a short acknowledgement sent before continuing substantive work. If no user-visible response is appropriate, do not call MessageChannel and do not send an empty acknowledgement. For lightweight acknowledgement, prefer action="react" when supported. If the useful response belongs later, schedule the follow-up instead of sending a placeholder.' : "";
+  const scopedReplyContract = scoped ? discovery.automaticRelay ? `
+
+This routed external channel turn uses automatic relay. Plain assistant text is delivered to the external user as each assistant message is finalized, so write the user-visible reply normally and do not make a duplicate MessageChannel send. When a host exposes MessageChannel alongside relay, use it only for explicit actions such as reactions and files; exact duplicate final text is suppressed.` : '\n\nThis tool is currently scoped to a routed external channel turn. Plain assistant text is not delivered to that external user. If a user-visible reply is appropriate, your final action for the turn must be one MessageChannel call with action="send", channel from the notification, chat_id from the notification, and message containing the reply. After that final send succeeds, do not repeat or paraphrase the sent message in assistant text; finish with only `Sent.` as the internal confirmation. This does not apply to a short acknowledgement sent before continuing substantive work. If no user-visible response is appropriate, do not call MessageChannel and do not send an empty acknowledgement. For lightweight acknowledgement, prefer action="react" when supported. If the useful response belongs later, schedule the follow-up instead of sending a placeholder.' : "";
   const slackWorkAcknowledgement = discovery.activeChannels.includes("slack") ? `
 
 For Slack requests that require nontrivial work or several tool calls, send one short MessageChannel call with action="send" before starting other tools. This gives the Slack user verbal acknowledgement and a View in web link. Do not do this for no-ops, reaction-only responses, or simple no-tool answers.` : "";
@@ -3061,4 +3516,4 @@ export {
   ChannelControlRequestCoordinator
 };
 
-//# debugId=B90B3E001C72BB3264756E2164756E21
+//# debugId=88EE0831E20B6BB164756E2164756E21