@animalabs/agent-framework 0.6.10 → 0.7.0

package/src/mcpl/channel-registry.ts

@@ -101,6 +101,10 @@ interface McplChannelIncomingEvent {
   content: ContentBlock[];
   timestamp: string;
   metadata?: Record<string, unknown>;
+  /** MCPL RFC-001 event tags (`chat:addressed`, `chat:ambient`, …) — carried
+   *  through so the host can rank addressed messages over ambient chatter
+   *  when picking a turn's frozen speech locus. */
+  tags?: string[];
   triggerInference?: boolean;
   targetAgents?: string[];
 }
@@ -286,6 +290,22 @@ interface ChannelRegistryOptions {
     reason: string;
     textLen: number;
   }) => void;
+  /**
+   * Called when channels were opened WITHOUT the agent asking (subscription
+   * policy admitting a newly discovered channel, or delivery into a closed
+   * locus). The host wires this to drop a durable notice into the agent's
+   * window — the agent must always learn that new traffic will start
+   * flowing, and that `channel_close` opts out (their decision outranks
+   * policy). Fires ONCE per channel ever: the desired-state decision is
+   * durable, so reboots do not re-announce. Must not trigger inference.
+   */
+  onChannelAutoOpened?: (info: {
+    /** Agent whose action caused the open (delivery); absent for policy opens. */
+    conversationId?: string;
+    serverId: string;
+    source: 'subscription-policy' | 'opened-by-delivery';
+    channels: Array<{ channelId: string; label?: string }>;
+  }) => void;
   /**
    * Resolve a conversation fork's HOME channel from its agent name. Conversation
    * forks are spawned bound to a single channel (the framework tracks this in
@@ -335,6 +355,12 @@ export class ChannelRegistry {
     reason: string;
     textLen: number;
   }) => void;
+  private onChannelAutoOpened?: (info: {
+    conversationId?: string;
+    serverId: string;
+    source: 'subscription-policy' | 'opened-by-delivery';
+    channels: Array<{ channelId: string; label?: string }>;
+  }) => void;
   private homeChannelResolver?: (agentName: string) => string | undefined;
   private activeChannelResolver?: (agentName: string) => string | undefined;
   private store?: JsStore;
@@ -386,6 +412,7 @@ export class ChannelRegistry {
     this.sendTypingFn = options?.sendTypingFn;
     this.shouldTriggerInference = options?.shouldTriggerInference;
     this.onRouteFailure = options?.onRouteFailure;
+    this.onChannelAutoOpened = options?.onChannelAutoOpened;
     this.homeChannelResolver = options?.homeChannelResolver;
     this.activeChannelResolver = options?.activeChannelResolver;
     this.store = options?.store;
@@ -595,6 +622,7 @@ export class ChannelRegistry {
         content: convertedContent,
         timestamp: message.timestamp,
         metadata: message.metadata,
+        ...(message.tags ? { tags: message.tags } : {}),
         triggerInference,
       };
 
@@ -636,9 +664,26 @@ export class ChannelRegistry {
    * channels/register or channels/changed overwrites this descriptor with the
    * richer one.
    */
-  ensureChannelRegistered(serverId: string, channelId: string, label?: string): void {
+  ensureChannelRegistered(
+    serverId: string,
+    channelId: string,
+    label?: string,
+    extraMetadata?: Record<string, unknown>,
+  ): void {
     const existing = this.findChannelEntry(channelId);
     if (existing) {
+      // Backfill identity onto a bare lazy registration: a DM that first
+      // arrived with no label/recipient info gets a usable name the next
+      // time a message reveals it (labels must show people, not ids).
+      if (
+        (existing.descriptor.metadata as { lazyRegistered?: boolean } | undefined)?.lazyRegistered &&
+        label && existing.descriptor.label === channelId
+      ) {
+        existing.descriptor.label = label;
+        if (extraMetadata) {
+          existing.descriptor.metadata = { ...existing.descriptor.metadata, ...extraMetadata };
+        }
+      }
       return;
     }
 
@@ -650,7 +695,7 @@ export class ChannelRegistry {
         type: serverId,
         label: label ?? channelId,
         direction: 'bidirectional',
-        metadata: { lazyRegistered: true },
+        metadata: { lazyRegistered: true, ...(extraMetadata ?? {}) },
       },
       open: false,
     });
@@ -1037,23 +1082,60 @@ export class ChannelRegistry {
     });
   }
 
-  private ensureInitialDesiredState(serverId: string, channel: ChannelDescriptor): void {
+  /**
+   * True when the server's recipe subscription policy wants this channel
+   * open. This is an ONGOING admission policy (subscribed ⇒ open, no matter
+   * when the channel is discovered) — not just a bootstrap seed. Allow-list
+   * entries may be composite MCPL ids or raw server-internal ids.
+   */
+  private policyWantsOpen(serverId: string, channel: ChannelDescriptor): boolean {
+    const policy = this.legacyPolicies.get(serverId) ?? 'manual';
+    if (policy === 'auto') return true;
+    if (Array.isArray(policy)) {
+      if (policy.includes(channel.id)) return true;
+      const raw = (channel.address as { channelId?: string } | undefined)?.channelId;
+      return typeof raw === 'string' && raw.length > 0 && policy.includes(raw);
+    }
+    return false;
+  }
+
+  /**
+   * Returns true when this call made a FRESH subscription-policy decision to
+   * open the channel — the caller announces those to the agent (once per
+   * channel ever: the decision persists in chronicle, so reboots see an
+   * existing non-default source and never re-fire).
+   */
+  private ensureInitialDesiredState(serverId: string, channel: ChannelDescriptor): boolean {
+    const byPolicy = this.policyWantsOpen(serverId, channel);
+    const wantsOpen = channel.initiallyOpen === true || byPolicy;
     const existing = this.desiredStates.get(this.lifecycleKey(serverId, channel.id));
     if (existing) {
-      // A server upgrading its descriptor to initiallyOpen may lift a pure
-      // default — 'default-closed' means nobody ever decided. Real decisions
+      // A server upgrading its descriptor to initiallyOpen — or a channel
+      // matching the subscription policy — may lift a pure default:
+      // 'default-closed' means nobody ever decided. Real decisions
       // (agent-tool, invitation-declined, legacy migration, …) always stick.
-      if (channel.initiallyOpen === true && existing.state === 'closed' && existing.source === 'default-closed') {
-        this.setDesiredState(serverId, channel.id, 'open', 'server-bootstrap');
+      if (wantsOpen && existing.state === 'closed' && existing.source === 'default-closed') {
+        this.setDesiredState(
+          serverId,
+          channel.id,
+          'open',
+          channel.initiallyOpen === true ? 'server-bootstrap' : 'subscription-policy',
+        );
+        return channel.initiallyOpen !== true && byPolicy;
       }
-      return;
+      return false;
     }
     this.setDesiredState(
       serverId,
       channel.id,
-      channel.initiallyOpen === true ? 'open' : 'closed',
-      channel.initiallyOpen === true ? 'server-bootstrap' : 'default-closed',
+      wantsOpen ? 'open' : 'closed',
+      channel.initiallyOpen === true
+        ? 'server-bootstrap'
+        : wantsOpen
+          ? 'subscription-policy'
+          : 'default-closed',
     );
+    return channel.initiallyOpen !== true && byPolicy;
   }
 
   private async reconcileChannels(
@@ -1063,8 +1145,15 @@ export class ChannelRegistry {
     const server = this.serverRegistry.getServer(serverId);
     if (!server) return;
 
+    // Channels the subscription policy freshly admitted in THIS pass —
+    // announced to the agent as one batched notice after the loop, so a
+    // first boot on a new policy doesn't produce one notice per channel.
+    const policyOpened: Array<{ channelId: string; label?: string }> = [];
+
     for (const channel of channels) {
-      this.ensureInitialDesiredState(serverId, channel);
+      if (this.ensureInitialDesiredState(serverId, channel)) {
+        policyOpened.push({ channelId: channel.id, label: channel.label });
+      }
       const key = `${serverId}:${channel.id}`;
       const desired = this.getDesiredState(serverId, channel.id);
       const entry = this.channels.get(key);
@@ -1102,6 +1191,21 @@ export class ChannelRegistry {
         });
       }
     }
+
+    // Announce policy admissions to the agent — nothing may start flowing
+    // traffic into their window without them being told, and told how to
+    // opt out (channel_close; their decision outranks policy).
+    if (policyOpened.length > 0) {
+      try {
+        this.onChannelAutoOpened?.({
+          serverId,
+          source: 'subscription-policy',
+          channels: policyOpened,
+        });
+      } catch (err) {
+        console.error('onChannelAutoOpened (policy) failed:', err);
+      }
+    }
   }
 
   // ==========================================================================
@@ -1211,6 +1315,229 @@ export class ChannelRegistry {
     };
   }
 
+  /**
+   * The single open executor: record durable desired-open intent, tell the
+   * server to subscribe, mark the live entry open. Every path that opens a
+   * channel — the agent's channel_open tool, delivery into a closed locus,
+   * an explicit send into a closed channel — funnels here, so lifecycle
+   * events, desired state, and live state can never diverge by path.
+   * Desired state is recorded BEFORE the server round-trip: intent sticks
+   * even if the subscribe fails, and reconciliation retries later.
+   */
+  private async openChannelNow(
+    entry: ChannelEntry,
+    source: string,
+    history?: ChannelHistoryRequest,
+  ): Promise<ChannelsOpenResult> {
+    this.setDesiredState(entry.serverId, entry.descriptor.id, 'open', source);
+    const server = this.serverRegistry.getServer(entry.serverId);
+    if (!server) {
+      throw new Error(`Server not found: ${entry.serverId}`);
+    }
+    const result: ChannelsOpenResult = await server.sendChannelsOpen({
+      channelId: entry.descriptor.id,
+      type: entry.descriptor.type,
+      address: entry.descriptor.address,
+      ...(history ? { history } : {}),
+    });
+    entry.open = true;
+    return result;
+  }
+
+  /**
+   * Resolve a `>>` prose-routing target (explicit prose routing —
+   * docs/explicit-prose-routing.md) to a registered channel.
+   *
+   * Accepted spellings, tried in order:
+   *   1. exact descriptor id (`discord:guild:123`, always unambiguous)
+   *   2. exact raw server-internal id (`address.channelId`)
+   *   3. `#label` / bare label — case-insensitive match on descriptor label
+   *      with any leading '#' stripped from both sides
+   *   4. `@name` — DM descriptor labels (`DM: name`), case-insensitive
+   *
+   * Ambiguity is an error carrying candidates — never a guess: this is the
+   * mechanism that makes prose misdelivery structurally impossible.
+   */
+  resolveProseTarget(
+    spec: string,
+  ): { channelId: string; label?: string } | { error: string; candidates?: string[] } {
+    const entries = [...this.channels.values()];
+    const trimmed = spec.trim();
+    if (!trimmed) return { error: 'empty target' };
+
+    const exact = entries.filter((e) => e.descriptor.id === trimmed);
+    if (exact.length === 1) {
+      return { channelId: exact[0]!.descriptor.id, label: exact[0]!.descriptor.label };
+    }
+    if (exact.length > 1) {
+      return {
+        error: `channel id "${trimmed}" is ambiguous across servers`,
+        candidates: exact.map((e) => `${e.serverId}:${e.descriptor.id}`),
+      };
+    }
+
+    const raw = entries.filter(
+      (e) => (e.descriptor.address as { channelId?: string } | undefined)?.channelId === trimmed,
+    );
+    if (raw.length === 1) {
+      return { channelId: raw[0]!.descriptor.id, label: raw[0]!.descriptor.label };
+    }
+    if (raw.length > 1) {
+      return {
+        error: `raw id "${trimmed}" is ambiguous`,
+        candidates: raw.map((e) => e.descriptor.id),
+      };
+    }
+
+    const norm = (s: string) => s.replace(/^#/, '').toLowerCase();
+
+    // DM addressing is PEOPLE-first: usernames and mention tokens, never
+    // ids-only (2026-07-24, antra + Fable's live-canary bug report). A DM
+    // entry is matched by, in order: recipientId (from a `<@id>` mention
+    // token), exact recipient/label name, then prefix-lenient name (handles
+    // "@antra_tessera" vs a display name "antra" and vice versa).
+    const mention = /^<@!?(\d+)>$/.exec(trimmed);
+    if (trimmed.startsWith('@') || mention) {
+      const dmMeta = (e: ChannelEntry) =>
+        e.descriptor.metadata as { channelType?: string; recipientId?: string; recipientName?: string } | undefined;
+      const dmName = (e: ChannelEntry) => {
+        const meta = dmMeta(e);
+        if (meta?.recipientName) return meta.recipientName.toLowerCase();
+        const label = (e.descriptor.label ?? '').toLowerCase();
+        return label.startsWith('dm: ') ? label.slice(4) : label;
+      };
+      const isDmEntry = (e: ChannelEntry) =>
+        dmMeta(e)?.channelType === 'dm' ||
+        (e.descriptor.label ?? '').toLowerCase().startsWith('dm: ') ||
+        e.descriptor.id.includes(':dm:');
+      const dms = entries.filter(isDmEntry);
+
+      if (mention) {
+        const id = mention[1]!;
+        const byId = dms.filter((e) => dmMeta(e)?.recipientId === id);
+        if (byId.length === 1) {
+          return { channelId: byId[0]!.descriptor.id, label: byId[0]!.descriptor.label };
+        }
+        return {
+          error: `no registered DM matches the mention <@${id}>`,
+          candidates: dms.map((e) => e.descriptor.label ?? e.descriptor.id).slice(0, 6),
+        };
+      }
+
+      const name = trimmed.slice(1).toLowerCase();
+      const exact = dms.filter((e) => dmName(e) === name);
+      const pool = exact.length > 0
+        ? exact
+        : dms.filter((e) => {
+            const n = dmName(e);
+            return n.length >= 3 && (n.startsWith(name) || name.startsWith(n) || n.includes(name));
+          });
+      if (pool.length === 1) {
+        return { channelId: pool[0]!.descriptor.id, label: pool[0]!.descriptor.label };
+      }
+      if (pool.length > 1) {
+        return {
+          error: `"${trimmed}" matches several DMs`,
+          candidates: pool.map((e) => e.descriptor.label ?? e.descriptor.id),
+        };
+      }
+      return {
+        error: `no registered DM found for "${trimmed}" — for someone without a registered DM channel, use the send_dm tool`,
+        ...(dms.length ? { candidates: dms.map((e) => e.descriptor.label ?? e.descriptor.id).slice(0, 6) } : {}),
+      };
+    }
+
+    const byLabel = entries.filter(
+      (e) => norm(e.descriptor.label ?? '') === norm(trimmed),
+    );
+    if (byLabel.length === 1) {
+      return { channelId: byLabel[0]!.descriptor.id, label: byLabel[0]!.descriptor.label };
+    }
+    if (byLabel.length > 1) {
+      return {
+        error: `label "${trimmed}" matches several channels`,
+        candidates: byLabel.map((e) => e.descriptor.id),
+      };
+    }
+
+    // Name-segment match: server labels carry a disambiguating suffix
+    // (`#fable (antra's server)`) that agents naturally omit — `>>#fable`
+    // must resolve. Strip a trailing parenthetical from the stored label and
+    // compare the bare channel name. Same name in several guilds is a real
+    // ambiguity: error with full labels so the agent can use the exact id.
+    const nameOf = (label: string) => norm(label.replace(/\s*\([^)]*\)\s*$/, ''));
+    const byName = entries.filter((e) => nameOf(e.descriptor.label ?? '') === norm(trimmed));
+    if (byName.length === 1) {
+      return { channelId: byName[0]!.descriptor.id, label: byName[0]!.descriptor.label };
+    }
+    if (byName.length > 1) {
+      return {
+        error: `"${trimmed}" matches several channels`,
+        candidates: byName.map((e) => `${e.descriptor.label} = ${e.descriptor.id}`),
+      };
+    }
+
+    // No match: offer near-candidates (labels containing the name) so the
+    // bounce notice is self-healing rather than a dead end.
+    const near = entries
+      .filter((e) => norm(e.descriptor.label ?? '').includes(norm(trimmed)))
+      .slice(0, 5)
+      .map((e) => `${e.descriptor.label} = ${e.descriptor.id}`);
+    return { error: `no channel matches "${trimmed}"`, ...(near.length ? { candidates: near } : {}) };
+  }
+
+  /**
+   * Open a channel because something was DELIVERED into it (explicit send
+   * tool or routed speech). Sending into a closed channel is not a thing:
+   * engaging a channel opens it, so typing indicators, reaction machinery,
+   * and inbound forwarding all come alive with the first outbound message.
+   * Accepts composite MCPL ids or raw server-internal ids (explicit send
+   * tools receive whatever the agent typed).
+   */
+  async openIfClosedForSend(
+    rawChannelId: string,
+    serverId?: string,
+  ): Promise<{
+    status: 'opened' | 'already-open' | 'unknown-channel' | 'ambiguous' | 'open-failed';
+    channelId?: string;
+    label?: string;
+  }> {
+    let matches = [...this.channels.values()].filter(
+      (e) => e.descriptor.id === rawChannelId && (!serverId || e.serverId === serverId),
+    );
+    if (matches.length === 0) {
+      matches = [...this.channels.values()].filter(
+        (e) =>
+          (e.descriptor.address as { channelId?: string } | undefined)?.channelId === rawChannelId &&
+          (!serverId || e.serverId === serverId),
+      );
+    }
+    if (matches.length === 0) return { status: 'unknown-channel' };
+    if (matches.length > 1) return { status: 'ambiguous' };
+    const entry = matches[0]!;
+    const resolved = { channelId: entry.descriptor.id, label: entry.descriptor.label };
+    if (entry.open && this.getDesiredState(entry.serverId, entry.descriptor.id) === 'open') {
+      return { status: 'already-open', ...resolved };
+    }
+    try {
+      await this.openChannelNow(entry, 'opened-by-reply');
+      this.emitTraceFn({
+        type: 'mcpl:channel-opened-by-send',
+        serverId: entry.serverId,
+        channelId: entry.descriptor.id,
+      });
+      return { status: 'opened', ...resolved };
+    } catch (err) {
+      this.emitTraceFn({
+        type: 'mcpl:channel-open-failed',
+        serverId: entry.serverId,
+        channelId: entry.descriptor.id,
+        error: (err as Error).message,
+      });
+      return { status: 'open-failed', ...resolved };
+    }
+  }
+
   private async handleToolOpen(input: {
     channelId: string;
     serverId?: string;
@@ -1235,17 +1562,6 @@ export class ChannelRegistry {
       };
     }
 
-    this.setDesiredState(entry.serverId, input.channelId, 'open', 'agent-tool');
-
-    const server = this.serverRegistry.getServer(entry.serverId);
-    if (!server) {
-      return {
-        success: false,
-        error: `Server not found: ${entry.serverId}`,
-        isError: true,
-      };
-    }
-
     try {
       const history: ChannelHistoryRequest | undefined = input.backscroll
         ? {
@@ -1253,13 +1569,7 @@ export class ChannelRegistry {
             ...(input.beforeMessageId ? { beforeMessageId: input.beforeMessageId } : {}),
           }
         : undefined;
-      const result: ChannelsOpenResult = await server.sendChannelsOpen({
-        channelId: entry.descriptor.id,
-        type: entry.descriptor.type,
-        address: entry.descriptor.address,
-        ...(history ? { history } : {}),
-      });
-      entry.open = true;
+      const result = await this.openChannelNow(entry, 'agent-tool', history);
       return {
         success: true,
         data: {
@@ -1462,13 +1772,15 @@ export class ChannelRegistry {
   async routeSpeech(
     conversationId: string,
     text: string,
-    /** Pin the outbound locus, skipping resolution. Callers delivering MULTIPLE
-     *  segments of ONE turn snapshot resolveLocus() once and pass it here, so a
-     *  new turn starting mid-dispatch (segments run after the agent is idle,
-     *  PR #32) can't overwrite the per-agent triggering channel between segments
-     *  and split one reply across channels. */
-    overrideChannelId?: string | null,
-  ): Promise<{ delivered: boolean; channelId: string } | null> {
+    /** The turn's FROZEN locus, snapshotted once by the caller (resolveLocus
+     *  at turn start) and passed to every segment of the turn. Mandatory:
+     *  there is deliberately no live-resolution fallback here — a late
+     *  dispatch resolving live can read the NEXT turn's trigger state or a
+     *  stale global default and land the reply in the wrong channel (item-3,
+     *  PR #32, and the 2026-07-22 Sol DM misroute). Explicit `null` means
+     *  "this turn is pinned to no locus": fail loudly rather than guess. */
+    locusChannelId: string | null,
+  ): Promise<{ delivered: boolean; channelId: string; messageId?: string } | null> {
     // Surface a routing failure: emit a trace AND notify the host (which drops
     // a `[discord-send-failed]` marker into chronicle) so the agent learns her
     // reply never reached the human, instead of it vanishing silently.
@@ -1476,6 +1788,7 @@ export class ChannelRegistry {
       console.error(`[routeSpeech] ${conversationId}: ${reason} — speech NOT routed (${text.length} chars stay in chronicle)`);
       this.emitTraceFn({
         type: 'mcpl:speech-route-failed',
+        conversationId,
         channelId: channelId ?? '',
         reason,
         textLen: text.length,
@@ -1484,24 +1797,18 @@ export class ChannelRegistry {
       return null;
     };
 
-    // Resolve the outbound locus, in precedence order:
-    //   1. fork HOME channel — a conversation fork always replies in the channel
-    //      it was spawned to serve (item 3, forks).
-    //   2. this turn's TRIGGERING channel — a single trunk agent (connectome-
-    //      host's only mode) replies in the channel whose message woke THIS
-    //      inference, so a concurrent inbound elsewhere can't hijack the reply
-    //      (item-3 redux, trunk agents). Also carries DM channels, which arrive
-    //      as push/events and never touch `defaultPublishChannel`.
-    //   3. the process-global `defaultPublishChannel` — last resort for turns
-    //      with no triggering channel (heartbeats, timers).
-    // Using the global for a fork or a concurrent trunk turn is the item-3 bug:
-    // it tracks the most-recent inbound across ALL channels, so a reply lands
-    // wherever a message last happened to arrive rather than where it belongs.
-    const channelId = overrideChannelId ?? this.resolveLocus(conversationId);
+    // Runtime backstop for JS callers the compiler can't see: an omitted
+    // locus is a routing bug at the call site, never something to paper over
+    // with a live re-resolution.
+    if (locusChannelId === undefined) {
+      return fail(null, 'caller passed no locus (routing bug: every speech path must snapshot the turn locus)');
+    }
+    const channelId = locusChannelId;
     if (!channelId) {
-      // Reached only when the agent has no home, no active triggering channel,
-      // AND no global inbound was ever seen.
-      return fail(null, 'no locus (no home/active channel, defaultPublishChannel null)');
+      // The turn froze with no locus (no home, no triggering channel, no
+      // global inbound ever seen) — the agent was told its prose stays in
+      // the archive; honor that.
+      return fail(null, 'turn has no locus (no home/trigger channel; nothing to deliver into)');
     }
 
     const entry = this.findChannelEntry(channelId);
@@ -1509,6 +1816,38 @@ export class ChannelRegistry {
       return fail(channelId, `no registered channel for locus "${channelId}"`);
     }
 
+    // INVARIANT: it is not possible to send into a closed channel. Speech
+    // routed into a closed-but-registered locus (the canonical case: a DM
+    // that woke the agent — DMs register closed) OPENS the channel first,
+    // so typing indicators, reaction machinery, and inbound forwarding come
+    // alive with the reply. If the open fails, the speech does NOT go out:
+    // a half-alive delivery is worse than a loud marker.
+    if (!entry.open) {
+      try {
+        await this.openChannelNow(entry, 'opened-by-delivery');
+        console.error(
+          `[routeSpeech] ${conversationId}: locus ${channelId} was closed — opened by delivery (speech implies engagement)`,
+        );
+        this.emitTraceFn({
+          type: 'mcpl:channel-opened-by-send',
+          serverId: entry.serverId,
+          channelId,
+        });
+        try {
+          this.onChannelAutoOpened?.({
+            conversationId,
+            serverId: entry.serverId,
+            source: 'opened-by-delivery',
+            channels: [{ channelId, label: entry.descriptor.label }],
+          });
+        } catch (err) {
+          console.error('onChannelAutoOpened (delivery) failed:', err);
+        }
+      } catch (err) {
+        return fail(channelId, `locus channel is closed and open failed: ${(err as Error).message}`);
+      }
+    }
+
     const server = this.serverRegistry.getServer(entry.serverId);
     if (!server) {
       return fail(channelId, `server "${entry.serverId}" not found`);
@@ -1521,6 +1860,11 @@ export class ChannelRegistry {
     };
     const result = await server.sendChannelsPublish(publishParams);
     const delivered = (result as { delivered?: boolean } | undefined)?.delivered ?? true;
+    // Surface the posted message's id (ChannelsPublishResult.messageId) so
+    // trace consumers can act on the just-posted message — e.g. a TTS-relay
+    // tap editing it down to the words actually voiced on interruption.
+    // Previously this was silently dropped here.
+    const messageId = (result as { messageId?: string } | undefined)?.messageId;
 
     // The server accepted the publish RPC but reported the message was not
     // actually delivered (e.g. missing Send Messages permission). Previously
@@ -1532,13 +1876,16 @@ export class ChannelRegistry {
     console.error(`[routeSpeech] ${conversationId}: routed ${text.length} chars -> ${channelId} (server=${entry.serverId}, delivered=${delivered})`);
     this.emitTraceFn({
       type: 'mcpl:speech-routed',
+      conversationId,
       serverId: entry.serverId,
       channelId,
       delivered,
       textLen: text.length,
+      text,
+      ...(messageId !== undefined ? { messageId } : {}),
     });
 
-    return { delivered, channelId };
+    return { delivered, channelId, ...(messageId !== undefined ? { messageId } : {}) };
   }
 
   private async handleToolPublish(input: { channelId?: string; content?: string; text?: string }): Promise<ToolResult> {

package/src/modules/workspace/index.ts

@@ -733,13 +733,13 @@ export class WorkspaceModule implements Module {
     return [
       {
         name: 'read',
-        description: 'Read a file from the workspace. Returns content with line numbers.',
+        description: 'Read a file from the workspace. Returns content with line numbers. Reads at most 2000 lines per call by default — use offset/limit to page through larger files.',
         inputSchema: {
           type: 'object' as const,
           properties: {
             path: { type: 'string', description: 'File path (mount-prefixed, e.g., "project/src/main.ts")' },
             offset: { type: 'number', description: 'Starting line number (1-indexed)' },
-            limit: { type: 'number', description: 'Maximum number of lines to return' },
+            limit: { type: 'number', description: 'Maximum number of lines to return (default 2000)' },
           },
           required: ['path'],
         },
@@ -1344,10 +1344,16 @@ export class WorkspaceModule implements Module {
     const content = blob.toString('utf-8');
     const lines = content.split('\n');
 
-    // Apply offset/limit
+    // Apply offset/limit. An unlimited read of a large file would inject the
+    // whole thing into the turn (a 2MB file ≈ 600k tokens → the request blows
+    // past the model context and 400s), so an omitted limit falls back to a
+    // default cap; the result reports total/from/to so the agent can page.
+    const DEFAULT_READ_LINE_LIMIT = 2000;
     const startLine = (input.offset ?? 1) - 1; // Convert to 0-indexed
-    const endLine = input.limit ? startLine + input.limit : lines.length;
+    const effectiveLimit = input.limit ?? DEFAULT_READ_LINE_LIMIT;
+    const endLine = startLine + effectiveLimit;
     const slice = lines.slice(startLine, endLine);
+    const truncated = endLine < lines.length;
 
     // Format with line numbers (cat -n style)
     const formatted = slice
@@ -1361,6 +1367,9 @@ export class WorkspaceModule implements Module {
         totalLines: lines.length,
         fromLine: startLine + 1,
         toLine: Math.min(endLine, lines.length),
+        ...(truncated
+          ? { note: `Truncated at ${effectiveLimit} lines (file has ${lines.length}). Use offset/limit to read more.` }
+          : {}),
         content: formatted,
       },
     };

package/src/types/agent.ts

@@ -133,6 +133,16 @@ export interface AgentConfig {
      */
     announceHumanTurns?: boolean;
   };
+
+  /**
+   * How the agent's PLAIN PROSE (non-tool output) reaches channels.
+   * - 'locus' (default): host-inferred — the turn-frozen locus machinery.
+   * - 'explicit': the model prefixes prose with a destination
+   *   (`>>#channel` / `>>@person` / `>>skip_reply`); unprefixed prose is never
+   *   delivered — it bounces to a clipboard for a cheap prefixed resend.
+   *   See docs/explicit-prose-routing.md.
+   */
+  proseRouting?: 'locus' | 'explicit';
 }
 
 /** The intentionally small set of agent settings that may change in-process. */
@@ -239,4 +249,12 @@ export interface InferenceRequest {
    * which correctly fall back to the global default channel.
    */
   channelId?: string;
+  /**
+   * True when the triggering message explicitly addressed the agent (mention,
+   * reply-to-bot, DM — `chat:addressed` in MCPL RFC-001 terms). When a wake
+   * batch spans several channels, an addressed channel outranks ambient
+   * chatter for the turn's frozen speech locus: overheard conversation must
+   * not capture the agent's voice just by being newest.
+   */
+  addressed?: boolean;
 }