@vellumai/assistant 0.12.1-staging.1 → 0.12.1

package/src/{calls → live-voice}/progress-narration.ts

@@ -5,7 +5,7 @@
  * The voice front door owns hold, escalation, and direct-response behavior.
  */
 
-import type { VoiceProgressConfig } from "../config/schemas/voice.js";
+import type { LiveVoiceProgressConfig } from "../config/schemas/live-voice.js";
 import {
   extractToolUse,
   getConfiguredProvider,
@@ -216,7 +216,7 @@ export function effectiveSpokenTextMaxChars(
 }
 
 export function createVoiceProgressNarrator(options: {
-  config: VoiceProgressConfig;
+  config: LiveVoiceProgressConfig;
   /** Provider resolver, injectable for tests. */
   getProvider?: () => Promise<Provider | null>;
 }): VoiceProgressNarrator {

package/src/live-voice/protocol.ts

@@ -627,6 +627,8 @@ export interface LiveVoiceMetricsServerFrame extends LiveVoiceServerFrameBase {
    * condition as the two fields above.
    */
   readonly endpointDecisionSource?: "front-door" | "provider";
+  /** Which floor-holding ack actually spoke during the turn, if any. */
+  readonly ackSpoken?: "first_delta" | "tool_use";
   /**
    * Spoken progress narrations during the turn. Present only when at least
    * one progress update spoke (otherwise the field is absent, keeping frames

package/src/mcp/__tests__/effective-config.test.ts

@@ -4,8 +4,8 @@
  * The properties worth pinning are the ones a refactor could quietly
  * break, each of which fails silently rather than loudly:
  *
- * 1. Plugin servers reach the manager at all. Reading only the workspace
- *    `mcp.json` leaves a plugin's tools missing with nothing logged.
+ * 1. Plugin servers reach the manager at all. Reading only `config.mcp`
+ *    leaves a plugin's tools missing with nothing logged.
  * 2. A workspace entry of the same id wins, so a plugin cannot redirect a
  *    server the user configured by hand.
  * 3. Every server is attributed. `source` is what `McpClient` reads to

package/src/mcp/effective-config.ts

@@ -1,11 +1,11 @@
 /**
  * The MCP configuration the daemon actually runs.
  *
- * Two sources contribute servers: the workspace `mcp.json`, which the
+ * Two sources contribute servers: the workspace `config.json`, which the
  * user owns, and each installed plugin's `mcp.json`, which its author
  * owns. Both must reach the MCP manager, so every consumer that starts
- * servers builds its config through here rather than reading the
- * workspace file directly — a path that only reads the workspace half
+ * servers builds its config through here rather than reading
+ * `config.mcp` directly — a path that only reads the workspace half
  * leaves a plugin's tools silently missing.
  *
  * Every server comes out attributed with its {@link McpServerSource}, so

package/src/mcp/mcp-header-store.ts

@@ -3,21 +3,18 @@
  *
  * Follows the same pattern as mcp-oauth-provider.ts: headers are stored in
  * the secure credential store (CES or encrypted file fallback) rather than
- * in plaintext mcp.json, keeping secrets out of workspace config files.
+ * in plaintext config.json, keeping secrets out of workspace config files.
  *
  * Key format: mcp:{serverId}:headers — stores JSON-serialized Record<string, string>.
  */
 
+import { loadRawConfig, saveRawConfig } from "../config/loader.js";
 import {
   deleteSecureKeyAsync,
   getSecureKeyAsync,
   setSecureKeyAsync,
 } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
-import {
-  loadWorkspaceMcpConfig,
-  saveWorkspaceMcpConfig,
-} from "./workspace-mcp-config.js";
 
 const log = getLogger("mcp-header-store");
 
@@ -76,45 +73,64 @@ export async function deleteMcpHeaders(serverId: string): Promise<boolean> {
 }
 
 /**
- * Move leftover plaintext headers from mcp.json into the credential store
- * and rewrite the file without them. Safe to call on every MCP reload.
+ * One-time lazy migration: move any plaintext headers from config.json
+ * transport entries into the credential store and strip them from config.
+ * Safe to call on every MCP reload — no-ops when no legacy headers remain.
  */
 export async function migrateLegacyMcpHeaders(): Promise<void> {
-  const config = loadWorkspaceMcpConfig();
-  const servers = config.servers;
-  let dirty = false;
+  const raw = loadRawConfig();
+  const mcpConfig = raw.mcp as
+    | { servers?: Record<string, Record<string, unknown>> }
+    | undefined;
+  const servers = mcpConfig?.servers;
+  if (!servers) {
+    return;
+  }
 
+  let configDirty = false;
   for (const [id, server] of Object.entries(servers)) {
-    const transport = server.transport;
-    if (transport.type !== "sse" && transport.type !== "streamable-http") {
+    const transport = server?.transport as Record<string, unknown> | undefined;
+    if (
+      !transport ||
+      (transport.type !== "sse" && transport.type !== "streamable-http")
+    ) {
       continue;
     }
-    const leftoverHeaders = transport.headers;
-    if (!leftoverHeaders || Object.keys(leftoverHeaders).length === 0) {
+    const legacyHeaders = transport.headers as
+      | Record<string, string>
+      | undefined;
+    if (!legacyHeaders || Object.keys(legacyHeaders).length === 0) {
       continue;
     }
 
+    // Only migrate if credential store doesn't already have headers for
+    // this server (idempotent — safe to re-run after partial failure).
     const existing = await getMcpHeaders(id);
-    if (!existing) {
-      const ok = await setMcpHeaders(id, leftoverHeaders);
-      if (!ok) {
-        log.warn(
-          { serverId: id },
-          "Skipping leftover header migration: credential store write failed; will retry on next reload",
-        );
-        continue;
-      }
+    if (existing) {
+      // Credential store already has headers; just strip the config copy.
+      delete transport.headers;
+      configDirty = true;
+      continue;
+    }
+
+    const ok = await setMcpHeaders(id, legacyHeaders);
+    if (ok) {
+      delete transport.headers;
+      configDirty = true;
       log.info(
         { serverId: id },
-        "Moved leftover MCP headers to credential store",
+        "Migrated legacy MCP headers to credential store",
+      );
+    } else {
+      log.warn(
+        { serverId: id },
+        "Skipping legacy header migration — credential store write failed; will retry on next reload",
       );
     }
-    delete transport.headers;
-    dirty = true;
   }
 
-  if (dirty) {
-    saveWorkspaceMcpConfig(config);
-    log.info("mcp.json updated: leftover MCP headers removed after migration");
+  if (configDirty) {
+    saveRawConfig(raw);
+    log.info("Config updated: legacy MCP headers removed after migration");
   }
 }

package/src/mcp/startup.ts

@@ -13,14 +13,13 @@
  * further process that starts hosting turns has one call to make.
  */
 
-import { invalidateConfigCache } from "../config/loader.js";
+import { getConfig, invalidateConfigCache } from "../config/loader.js";
 import type { McpConfig } from "../config/schemas/mcp.js";
 import { createMcpToolsFromServer } from "../tools/mcp/mcp-tool-factory.js";
 import { registerMcpTools, unregisterAllMcpTools } from "../tools/registry.js";
 import { getLogger } from "../util/logger.js";
 import { buildEffectiveMcpConfig } from "./effective-config.js";
 import { getMcpServerManager, stopMcpServerManager } from "./manager.js";
-import { loadWorkspaceMcpConfig } from "./workspace-mcp-config.js";
 
 const log = getLogger("mcp-startup");
 
@@ -37,8 +36,7 @@ const log = getLogger("mcp-startup");
  * is a startup step in processes whose other work must not be held hostage to
  * a third-party server being up.
  *
- * @param workspaceMcpConfig The projected workspace MCP config. Callers
- * that omit it read `/workspace/mcp.json`.
+ * @param workspaceMcpConfig The `mcp` block of the assistant config, if any.
  * @returns The number of tools registered across all servers.
  */
 export async function startConfiguredMcpServers(
@@ -46,9 +44,7 @@ export async function startConfiguredMcpServers(
 ): Promise<number> {
   let registered = 0;
   try {
-    const mcpConfig = buildEffectiveMcpConfig(
-      workspaceMcpConfig ?? loadWorkspaceMcpConfig(),
-    );
+    const mcpConfig = buildEffectiveMcpConfig(workspaceMcpConfig);
     if (Object.keys(mcpConfig.servers).length === 0) {
       return 0;
     }
@@ -101,5 +97,5 @@ export async function restartConfiguredMcpServers(): Promise<number> {
   }
   unregisterAllMcpTools();
   invalidateConfigCache();
-  return startConfiguredMcpServers(loadWorkspaceMcpConfig());
+  return startConfiguredMcpServers(getConfig().mcp);
 }

package/src/messaging/provider.ts

@@ -56,22 +56,15 @@ export interface MessagingProvider {
     query: string,
     options?: SearchOptions,
   ): Promise<SearchResult>;
-
-  // ── Optional operations (platforms implement what they support) ───
-
-  /**
-   * Send through the provider's own API. A provider whose channel has a
-   * direct transport omits this: its sends go through the transport, which
-   * is the one send implementation per addressable channel, and the
-   * messaging tool routes there before it looks for this method.
-   */
-  sendMessage?(
+  sendMessage(
     connection: OAuthConnection | undefined,
     conversationId: string,
     text: string,
     options?: SendOptions,
   ): Promise<SendResult>;
 
+  // ── Optional operations (platforms implement what they support) ───
+
   getThreadReplies?(
     connection: OAuthConnection | undefined,
     conversationId: string,

package/src/messaging/providers/callback-routing.ts

@@ -1,5 +1,4 @@
 import type { ChannelId } from "../../channels/types.js";
-import type { CallbackContext } from "./channel-transport.js";
 
 /**
  * Channels whose outbound replies the assistant delivers directly to the
@@ -23,23 +22,6 @@ export type DirectDeliveryChannel = (typeof DIRECT_DELIVERY_CHANNELS)[number];
 
 const CALLBACK_PREFIX = "/deliver/";
 
-/**
- * The callback context a channel's operations read for a direct delivery
- * that no inbound message brought a callback for: the channel's `/deliver`
- * path with its per-channel params, spelled the way `channelForCallback`
- * resolves it and the way the transports read it.
- */
-export function directDeliveryContext(
-  channel: DirectDeliveryChannel,
-  params: Readonly<Record<string, string>> = {},
-): CallbackContext {
-  const query = new URLSearchParams(params).toString();
-  return {
-    callbackUrl: `${CALLBACK_PREFIX}${channel}${query ? `?${query}` : ""}`,
-    params,
-  };
-}
-
 /**
  * Resolve a gateway callback URL to the direct-delivery channel that owns it, or
  * `undefined` when no channel delivers it directly.

package/src/messaging/providers/channel-transport.ts

@@ -97,35 +97,6 @@ export interface ReactionTarget {
   readonly action: "add" | "remove";
 }
 
-/**
- * Where a proactive send goes, in the caller's vocabulary rather than any
- * channel's: a chat the caller already knows, optionally a thread within it.
- * How a thread is spelled is each channel's own business.
- *
- * Tagged with its kind so a second way of naming a destination is additive
- * rather than a reinterpretation of `chatId`. Reaching a person who has not
- * been named as a chat is deliberately not a kind here: on Slack and Discord
- * it costs a platform call whose result must be resolved at send time rather
- * than stored, and nothing asks for it yet.
- */
-export type ProactiveTarget = {
-  readonly kind: "chat";
-  readonly chatId: string;
-  readonly threadId?: string;
-};
-
-/**
- * A proactive target resolved into what this channel's operations read: the
- * callback context carrying the channel's routing state, the chat id
- * `deliver` posts to, and the thread the post lands in, absent when it is
- * not in one.
- */
-export interface ProactiveAddress {
-  readonly ctx: CallbackContext;
-  readonly chatId: string;
-  readonly threadId?: string;
-}
-
 /**
  * Direct outbound delivery for one channel, wrapping the channel's provider-API
  * send functions behind a uniform surface. Transports are registered statically
@@ -140,33 +111,6 @@ export interface ChannelTransport {
   /** Canonical source channel id, e.g. `"slack"`. */
   readonly channel: ChannelId;
 
-  /**
-   * Resolve a target the caller names into this channel's own routing state,
-   * for a send that no inbound message brought a callback for.
-   *
-   * Implementing it is the whole of declaring that the channel can be
-   * addressed from a named chat. A transport that can only answer on the
-   * callback an inbound message carried omits it, and a caller reads the
-   * omission as "not addressable" rather than switching on the channel's
-   * name. Returning `undefined` for a target this channel cannot address is
-   * the same answer for that target alone.
-   *
-   * Resolution is local: it reads the target and the channel's own
-   * vocabulary, and makes no platform call. A destination that has to be
-   * resolved over the network belongs behind its own capability, so this one
-   * stays cheap enough to call on every send.
-   */
-  addressFor?(target: ProactiveTarget): ProactiveAddress | undefined;
-
-  /**
-   * Whether a proactive send to a chat must also bind that chat's inbound
-   * conversation, so the next message from the chat resolves to the same
-   * conversation the post lives in. Declared by a channel whose inbound
-   * conversations are keyed per chat and can be reset between sends; omitted
-   * by one whose inbound binding is made at ingress and keyed by thread.
-   */
-  readonly bindsChatOnProactiveSend?: boolean;
-
   /** Deliver a rendered reply (text / approval / attachments). */
   deliver(
     ctx: CallbackContext,

package/src/messaging/providers/discord/transport.ts

@@ -1,7 +1,6 @@
 import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
 
 import { getLogger } from "../../../util/logger.js";
-import { directDeliveryContext } from "../callback-routing.js";
 import type {
   CallbackContext,
   ChannelTransport,
@@ -52,22 +51,6 @@ async function sendTarget(
 export const discordTransport: ChannelTransport = {
   channel: "discord",
 
-  /**
-   * A chat is a channel id, with `threadId` naming the thread, which is its
-   * own channel. Reaching a person who has not been named as a chat would
-   * mean opening their DM first, a platform call this resolution does not
-   * make; the inbound `dm` param below is how an event-carried callback says
-   * its `chatId` is a recipient rather than a room.
-   */
-  addressFor(target) {
-    const threadId = target.threadId?.trim();
-    return {
-      ctx: directDeliveryContext("discord", threadId ? { threadId } : {}),
-      chatId: target.chatId,
-      ...(threadId ? { threadId } : {}),
-    };
-  },
-
   // Discord clears a typing indicator after ten seconds.
   activityRefreshMs: 8_000,
 

package/src/messaging/providers/slack/__tests__/adapter-token-routing.test.ts

@@ -162,11 +162,10 @@ describe("Slack adapter token routing", () => {
     globalThis.fetch = originalFetch;
   });
 
-  test("bot-token only: reads authenticate with the bot token (regression guard for pre-user-token behavior)", async () => {
+  test("bot-token only: reads and writes both authenticate with the bot token (regression guard for pre-user-token behavior)", async () => {
     // With only a bot token stored, reads must fall back to the bot token
     // so the adapter keeps working for installs that haven't re-consented
-    // the user scope. Writes are not the adapter's: they go through the
-    // channel transport's senders, which always post as the bot.
+    // the user scope. Writes stay on the bot token always.
     const resolved = await slackProvider.resolveConnection!();
     expect(resolved).toBeUndefined();
 
@@ -177,12 +176,18 @@ describe("Slack adapter token routing", () => {
     );
     expect(readCall).toBeDefined();
     expect(readCall!.authorization).toBe(`Bearer ${BOT_TOKEN}`);
+
+    // Write path: sendMessage → /chat.postMessage must also use bot token.
+    await slackProvider.sendMessage(undefined, "C123", "hello");
+    const writeCall = captured.find((c) => c.url.includes("/chat.postMessage"));
+    expect(writeCall).toBeDefined();
+    expect(writeCall!.authorization).toBe(`Bearer ${BOT_TOKEN}`);
   });
 
-  test("bot + user tokens: reads authenticate with the user token", async () => {
+  test("bot + user tokens: reads authenticate with the user token, writes with the bot token", async () => {
     // With both tokens stored, reads MUST flip to the user token so the
-    // adapter can see channels the user is in but the bot isn't. Posts are
-    // the transport's and come from the bot identity there.
+    // adapter can see channels the user is in but the bot isn't. Writes
+    // MUST stay on the bot token so posts come from the bot identity.
     getSecureKeyAsyncMock.mockImplementation(async (key: string) => {
       if (key === credentialKey("slack_channel", "bot_token")) {
         return BOT_TOKEN;
@@ -212,6 +217,12 @@ describe("Slack adapter token routing", () => {
     expect(historyCall).toBeDefined();
     expect(historyCall!.authorization).toBe(`Bearer ${USER_TOKEN}`);
 
+    // Writes: sendMessage → bot token.
+    await slackProvider.sendMessage(undefined, "C123", "hello");
+    const sendCall = captured.find((c) => c.url.includes("/chat.postMessage"));
+    expect(sendCall).toBeDefined();
+    expect(sendCall!.authorization).toBe(`Bearer ${BOT_TOKEN}`);
+
     // markRead → user token. conversations.mark sets the read cursor for
     // the authenticated identity, so it must use the same token whose unread
     // counts the adapter exposes.

package/src/messaging/providers/slack/adapter.ts

@@ -28,6 +28,8 @@ import type {
   Message,
   SearchOptions,
   SearchResult,
+  SendOptions,
+  SendResult,
 } from "../../provider-types.js";
 import { resolveSlackAuth } from "./auth.js";
 import * as slack from "./client.js";
@@ -142,12 +144,24 @@ function getReadAuth(connection?: OAuthConnection): OAuthConnection | string {
   return getSlackAuth(connection);
 }
 
-// SAFETY: content-creating writes (posts, updates, deletes, reactions) go
-// through the channel transport's senders, which authenticate with the bot
-// token so posts come from the bot identity. State-changing methods that
-// target the authenticated identity's own state (e.g. conversations.mark)
-// use the read auth so the cursor matches the perspective the adapter
-// exposes.
+// SAFETY: content-creating writes (postMessage, updateMessage, deleteMessage,
+// reactions) MUST use the bot token. Using the user token would post as the
+// user, not as the bot. State-changing methods that target the authenticated
+// identity's own state (e.g. conversations.mark) should use the read auth so
+// the cursor matches the perspective the adapter exposes.
+/**
+ * Resolve auth for content-creating write operations (postMessage and any
+ * future reactions, joins, leaves, updates, or deletes).
+ */
+function getWriteAuth(connection?: OAuthConnection): OAuthConnection | string {
+  if (connection) {
+    return connection;
+  }
+  if (_cachedSlackWriteAuth) {
+    return _cachedSlackWriteAuth;
+  }
+  return getSlackAuth(connection);
+}
 
 /**
  * Resolve the bot token (raw string) and pass it to `fn`. Returns the
@@ -157,7 +171,7 @@ function getReadAuth(connection?: OAuthConnection): OAuthConnection | string {
  * (`OAuthConnection.withToken`) for callers that need a raw token to hand
  * to a non-Slack-client API call — currently `downloadSlackFile` for inline
  * file/image fetches. Slack-client method calls should keep going through
- * `getReadAuth` and pass the union through.
+ * `getReadAuth` / `getWriteAuth` and pass the union through.
  */
 export async function withSlackBotToken<T>(
   account: string | undefined,
@@ -816,6 +830,29 @@ export const slackProvider: MessagingProvider = {
     };
   },
 
+  async sendMessage(
+    connection: OAuthConnection | undefined,
+    conversationId: string,
+    text: string,
+    options?: SendOptions,
+  ): Promise<SendResult> {
+    const auth = getWriteAuth(connection);
+    const resp = await slack.postMessage(
+      auth,
+      conversationId,
+      text,
+      options?.threadId,
+    );
+    // The thread reported is the one the post landed in, which is the one
+    // requested, since chat.postMessage threads exactly where it is told.
+    return {
+      id: resp.ts,
+      timestamp: parseFloat(resp.ts) * 1000,
+      conversationId: resp.channel,
+      ...(options?.threadId ? { threadId: options.threadId } : {}),
+    };
+  },
+
   async getThreadReplies(
     connection: OAuthConnection | undefined,
     conversationId: string,

package/src/messaging/providers/slack/transport.ts

@@ -3,7 +3,6 @@ import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
 
 import { extractThreadTsFromCallbackUrl } from "../../../channels/slack-callback-url.js";
 import { getLogger } from "../../../util/logger.js";
-import { directDeliveryContext } from "../callback-routing.js";
 import type { ChannelTransport } from "../channel-transport.js";
 import { SLACK_STREAM_MARKDOWN_LIMIT } from "./api.js";
 import {
@@ -26,21 +25,6 @@ function mutedBlocks(text: string): KnownBlock[] {
 export const slackTransport: ChannelTransport = {
   channel: "slack",
 
-  /**
-   * A chat is a channel or DM id, with `threadTs` naming the thread to post
-   * under. Reaching a person who has not been named as a chat would mean
-   * opening the DM first (`conversations.open`), a platform call this
-   * resolution does not make.
-   */
-  addressFor(target) {
-    const threadTs = target.threadId?.trim();
-    return {
-      ctx: directDeliveryContext("slack", threadTs ? { threadTs } : {}),
-      chatId: target.chatId,
-      ...(threadTs ? { threadId: threadTs } : {}),
-    };
-  },
-
   describeReactionEmoji: describeSlackReactionEmoji,
 
   async react(target) {

package/src/messaging/providers/telegram-bot/adapter.ts

@@ -6,6 +6,9 @@
 
 import type { OAuthConnection } from "../../../oauth/connection.js";
 import { getConnectionByProvider } from "../../../oauth/oauth-store.js";
+import { getOrCreateConversation } from "../../../persistence/conversation-key-store.js";
+import { buildScopedConversationKey } from "../../../persistence/delivery-crud.js";
+import { upsertOutboundBinding } from "../../../persistence/external-conversation-store.js";
 import { credentialKey } from "../../../security/credential-key.js";
 import { getSecureKeyAsync } from "../../../security/secure-keys.js";
 import type { MessagingProvider } from "../../provider.js";
@@ -17,6 +20,8 @@ import type {
   Message,
   SearchOptions,
   SearchResult,
+  SendOptions,
+  SendResult,
 } from "../../provider-types.js";
 import * as telegram from "./client.js";
 
@@ -29,7 +34,7 @@ export const telegramBotMessagingProvider: MessagingProvider = {
   id: "telegram",
   displayName: "Telegram",
   credentialService: "telegram",
-  capabilities: new Set(),
+  capabilities: new Set(["send"]),
 
   async isConnected(): Promise<boolean> {
     const conn = getConnectionByProvider("telegram");
@@ -90,6 +95,48 @@ export const telegramBotMessagingProvider: MessagingProvider = {
     }
   },
 
+  async sendMessage(
+    _connection: OAuthConnection | undefined,
+    conversationId: string,
+    text: string,
+    _options?: SendOptions,
+  ): Promise<SendResult> {
+    const sent = await telegram.sendMessage(conversationId, text);
+    if (!sent.lastMessageId) {
+      throw new Error(
+        "Telegram accepted the message but returned no message id",
+      );
+    }
+
+    // Upsert external conversation binding so deleted/reset syncs are
+    // resurrected when an outbound message is sent. This ensures the
+    // conversation key mapping and binding exist for the next inbound.
+    try {
+      const sourceChannel = "telegram";
+      const conversationKey = buildScopedConversationKey(
+        sourceChannel,
+        conversationId,
+      );
+      const { conversationId: internalId } =
+        getOrCreateConversation(conversationKey);
+      upsertOutboundBinding({
+        conversationId: internalId,
+        sourceChannel,
+        externalChatId: conversationId,
+      });
+    } catch {
+      // Best-effort — don't fail the send if binding upsert fails
+    }
+
+    // The id is the one Telegram assigned, so a later reaction, edit, or
+    // delete carrying that id resolves to this send.
+    return {
+      id: sent.lastMessageId,
+      timestamp: Date.now(),
+      conversationId,
+    };
+  },
+
   async listConversations(
     _connection?: OAuthConnection,
     _options?: ListOptions,

package/src/messaging/providers/telegram-bot/client.ts

@@ -41,3 +41,29 @@ export async function getMe(botToken: string): Promise<TelegramGetMeResponse> {
 
   return resp.json() as Promise<TelegramGetMeResponse>;
 }
+
+/** Result returned by sendMessage. */
+export interface TelegramSendResult {
+  ok: boolean;
+  /**
+   * The `message_id` Telegram assigned to the last chunk sent. Telegram
+   * returns the sent Message on every successful `sendMessage`, so this is
+   * absent only when the API answered with an unexpected shape.
+   */
+  lastMessageId?: string;
+}
+
+/**
+ * Send a Telegram text message via the Bot API directly.
+ *
+ * Delegates to sendTelegramReply which handles text splitting (Telegram's
+ * sendMessage API has a 4096-char limit per call).
+ */
+export async function sendMessage(
+  chatId: string,
+  text: string,
+): Promise<TelegramSendResult> {
+  const { sendTelegramReply } = await import("./send.js");
+  const sent = await sendTelegramReply(chatId, text);
+  return { ok: true, lastMessageId: sent.lastMessageId };
+}