@mono-agent/agent-app 0.6.2 → 0.8.0

package/dist/adapter-send-tools.js

@@ -1,5 +1,6 @@
-import { readFile, stat } from "node:fs/promises";
-import { basename, resolve as resolvePath } from "node:path";
+import { constants as fsConstants } from "node:fs";
+import { lstat, mkdir, open, readFile, realpath, rm, stat } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
 import process from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -13,6 +14,8 @@ let telegramModule;
 const loadSlackModule = async () => (slackModule ??= await import("@mono-agent/slack-adapter"));
 const loadTelegramModule = async () => (telegramModule ??= await import("@mono-agent/telegram-adapter"));
 const SLACK_SEND_MESSAGE_MAX_CHARS = 40_000;
+/** Keep cancellation responsive even when the loopback bridge is wedged. */
+const ASK_BRIDGE_CLEANUP_TIMEOUT_MS = 1_000;
 /**
  * Model-visible send tools for explicitly allowed, already-enabled communication adapters.
  *
@@ -26,10 +29,13 @@ const SLACK_SEND_MESSAGE_MAX_CHARS = 40_000;
 export const ADAPTER_SEND_TOOLS_MCP_SERVER_NAME = "mono-agent-adapter-send";
 export async function resolveAdapterSendToolsSettings(input, options = {}) {
     const telegramSendAllowed = isAdapterToolAllowed("TelegramSendMessage", options);
-    const telegramAskAllowed = isAdapterToolAllowed("TelegramAskButtons", options);
+    const telegramAskAllowed = options.suppressInteractionTools !== true
+        && isAdapterToolAllowed("TelegramAskButtons", options);
     const telegramFileAllowed = isAdapterToolAllowed("TelegramSendFile", options);
     const telegramAnyAllowed = telegramSendAllowed || telegramAskAllowed || telegramFileAllowed;
-    const telegramAskBridge = telegramAskAllowed ? resolveAskUserToolSettings(input.env) : undefined;
+    const telegramAskBridge = telegramAskAllowed
+        ? resolveAskUserToolSettings(input.env, options.interaction)
+        : undefined;
     const [slack, telegram] = await Promise.all([
         isAdapterToolAllowed("SlackSendMessage", options)
             ? resolveSlackSendToolSettings(input, options)
@@ -42,8 +48,8 @@ export async function resolveAdapterSendToolsSettings(input, options = {}) {
             }, telegramAskBridge)
             : undefined,
     ]);
-    const askUser = isAdapterToolAllowed("AskUser", options)
-        ? resolveAskUserToolSettings(input.env)
+    const askUser = options.suppressInteractionTools !== true && isAdapterToolAllowed("AskUser", options)
+        ? resolveAskUserToolSettings(input.env, options.interaction)
         : undefined;
     if (slack === undefined && telegram === undefined && askUser === undefined) {
         return undefined;
@@ -59,20 +65,23 @@ export async function resolveAdapterSendToolsSettings(input, options = {}) {
  * into the environment (URL + bearer token). The producing conversation id is
  * per-request env, present in the spawned child.
  */
-function resolveAskUserToolSettings(env) {
-    const bridgeUrl = optionalString(env.MONO_AGENT_INTERACTION_BRIDGE_URL);
-    const bridgeToken = optionalString(env.MONO_AGENT_INTERACTION_BRIDGE_TOKEN);
+function resolveAskUserToolSettings(env, interaction) {
+    const bridgeUrl = interaction?.bridgeUrl ?? optionalString(env.MONO_AGENT_INTERACTION_BRIDGE_URL);
+    const bridgeToken = interaction?.bridgeToken ?? optionalString(env.MONO_AGENT_INTERACTION_BRIDGE_TOKEN);
     if (bridgeUrl === undefined || bridgeToken === undefined) {
         return undefined;
     }
     const timeoutRaw = Number(optionalString(env.MONO_AGENT_ASK_USER_TIMEOUT_MS));
-    const timeoutMs = Number.isFinite(timeoutRaw) && timeoutRaw >= 1000 ? timeoutRaw : 600_000;
+    const timeoutMs = interaction?.timeoutMs
+        ?? (Number.isFinite(timeoutRaw) && timeoutRaw >= 1000 ? timeoutRaw : 600_000);
     const conversationId = optionalString(env.MONO_AGENT_ADAPTER_TOOLS_PRODUCING_CONVERSATION_ID);
+    const runId = optionalString(env.MONO_AGENT_ADAPTER_TOOLS_PRODUCING_RUN_ID);
     return {
         bridgeUrl,
         bridgeToken,
         timeoutMs,
         ...(conversationId === undefined ? {} : { conversationId }),
+        ...(runId === undefined ? {} : { runId }),
     };
 }
 export function adapterSendToolNames(settings) {
@@ -109,9 +118,21 @@ export function adapterSendToolsMcpEnv(configPath, allowedTools, context, intera
         ...(context?.conversationId === undefined
             ? {}
             : { MONO_AGENT_ADAPTER_TOOLS_PRODUCING_CONVERSATION_ID: context.conversationId }),
+        ...(context?.runId === undefined
+            ? {}
+            : { MONO_AGENT_ADAPTER_TOOLS_PRODUCING_RUN_ID: context.runId }),
         ...(context?.indexPath === undefined
             ? {}
             : { MONO_AGENT_ADAPTER_TOOLS_POST_INDEX_PATH: context.indexPath }),
+        ...(context?.runOutputDir === undefined
+            ? {}
+            : { MONO_AGENT_ADAPTER_TOOLS_RUN_OUTPUT_DIR: context.runOutputDir }),
+        ...(context?.runOutputIdentity === undefined
+            ? {}
+            : {
+                MONO_AGENT_ADAPTER_TOOLS_RUN_OUTPUT_DEV: String(context.runOutputIdentity.dev),
+                MONO_AGENT_ADAPTER_TOOLS_RUN_OUTPUT_INO: String(context.runOutputIdentity.ino),
+            }),
         ...(interaction === undefined
             ? {}
             : {
@@ -137,13 +158,26 @@ export function adapterSendToolsChildConfigFromEnv(env, cwd) {
     };
 }
 export function adapterSendToolsMcpServerSpec(configPath, cwd, allowedTools, context, interaction) {
-    return {
+    const spec = {
         type: "stdio",
         command: process.execPath,
-        args: [fileURLToPath(new URL("./adapter-send-tools-main.js", import.meta.url))],
+        // Node 24 on macOS defaults to the system trust store, whose trustd access
+        // is intentionally unavailable inside strict SRT. Force Node's bundled CA
+        // set for this child while still honoring NODE_EXTRA_CA_CERTS when SRT TLS
+        // termination or an operator supplies an additional root.
+        args: ["--use-bundled-ca", fileURLToPath(new URL("./adapter-send-tools-main.js", import.meta.url))],
         cwd,
         env: adapterSendToolsMcpEnv(configPath, allowedTools, context, interaction),
     };
+    // Only the trusted app-owned adapter child receives SRT's coarse loopback
+    // capability. A symbol cannot be supplied by JSON MCP config and disappears
+    // from serialized provider/tool metadata, so ordinary Bash/project MCP
+    // processes keep the stricter no-bind allowlist policy.
+    Object.defineProperty(spec, Symbol.for("@mono-agent/app-owned-local-binding"), {
+        value: true,
+        enumerable: false,
+    });
+    return spec;
 }
 /**
  * Per-request runtime extension that injects the adapter-send stdio MCP server. It
@@ -151,14 +185,26 @@ export function adapterSendToolsMcpServerSpec(configPath, cwd, allowedTools, con
  * configured, forwards both to the child so a `SlackSendMessage` post is linked
  * back to this conversation (so a later in-thread reply resumes it).
  */
-export function createAdapterSendToolsRuntimeExtension(configPath, cwd, allowedTools, indexPath, interaction) {
+export function createAdapterSendToolsRuntimeExtension(configPath, cwd, allowedTools, indexPath, interaction, runOutputRoot) {
     return async (input) => {
         const conversationId = input?.request?.conversationId;
+        const runId = input?.runId;
         const hasConversation = typeof conversationId === "string" && conversationId.trim().length > 0;
+        const hasRunId = typeof runId === "string" && runId.trim().length > 0;
+        const runOutput = runOutputRoot === undefined || !hasRunId
+            ? undefined
+            : await ensureAdapterRunOutputDir(runOutputRoot, runId);
         // The conversation id is forwarded whenever known — AskUser targets it even
         // without indexing; the index path additionally enables posted-message links.
-        const context = hasConversation
-            ? { conversationId, ...(indexPath === undefined ? {} : { indexPath }) }
+        const context = hasConversation || hasRunId
+            ? {
+                ...(hasConversation ? { conversationId } : {}),
+                ...(hasRunId ? { runId } : {}),
+                ...(indexPath === undefined ? {} : { indexPath }),
+                ...(runOutput === undefined
+                    ? {}
+                    : { runOutputDir: runOutput.path, runOutputIdentity: runOutput.identity }),
+            }
             : undefined;
         return {
             runtimeOptions: {
@@ -167,27 +213,37 @@ export function createAdapterSendToolsRuntimeExtension(configPath, cwd, allowedT
                 },
             },
             cleanup: async () => { },
+            settleCleanup: async () => {
+                if (runOutput !== undefined) {
+                    await removeOwnedDirectory(runOutput.path, runOutput.identity);
+                }
+            },
         };
     };
 }
-export async function createAdapterSendToolsClients(settings) {
+export async function createAdapterSendToolsClients(settings, options = {}) {
     const slack = settings.slack === undefined
         ? undefined
-        : new (await loadSlackModule()).SlackWebApiClient({ botToken: settings.slack.botToken });
+        : new (await loadSlackModule()).SlackWebApiClient({
+            botToken: settings.slack.botToken,
+            ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+        });
     const telegram = settings.telegram === undefined
         ? undefined
         : (await loadTelegramModule()).createTelegramMessageSender(settings.telegram.botToken, {
             ...(settings.telegram.apiRoot === undefined ? {} : { apiRoot: settings.telegram.apiRoot }),
+            ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
         });
     return {
         ...(slack === undefined ? {} : { slack }),
         ...(telegram === undefined ? {} : { telegram }),
     };
 }
-export async function createAdapterSendToolsServer(settings, clients, indexing) {
+export async function createAdapterSendToolsServer(settings, clients, indexing, options = {}) {
     const server = new McpServer({ name: "agent-adapter-send-tools", version: "0.3.0" });
     if (settings.slack !== undefined && clients.slack !== undefined) {
-        registerSlackSendTool(server, settings.slack, clients.slack, indexing);
+        const adapter = await loadSlackModule();
+        registerSlackSendTool(server, settings.slack, clients.slack, adapter.formatMarkdownForSlack, indexing);
     }
     if (settings.telegram !== undefined && clients.telegram !== undefined) {
         // Loaded once here (not per-register-call) because registerTelegramAskTool
@@ -198,7 +254,7 @@ export async function createAdapterSendToolsServer(settings, clients, indexing)
             registerTelegramSendTool(server, settings.telegram, clients.telegram);
         }
         if (settings.telegram.tools.ask) {
-            registerTelegramAskTool(server, settings.telegram, clients.telegram, adapter);
+            registerTelegramAskTool(server, settings.telegram, clients.telegram, adapter, options.fetchImpl ?? globalThis.fetch);
         }
         if (settings.telegram.tools.file) {
             registerTelegramSendFileTool(server, settings.telegram, clients.telegram, adapter);
@@ -207,13 +263,13 @@ export async function createAdapterSendToolsServer(settings, clients, indexing)
     // AskUser needs a target conversation; the parent app process resolves the
     // settings without one (for tool-name gating) and must not register the tool.
     if (settings.askUser?.conversationId !== undefined) {
-        registerAskUserTool(server, { ...settings.askUser, conversationId: settings.askUser.conversationId });
+        registerAskUserTool(server, { ...settings.askUser, conversationId: settings.askUser.conversationId }, options.fetchImpl ?? globalThis.fetch);
     }
     return server;
 }
 /** Long-poll wait per bridge request; the overall wait is bounded server-side by the ask's timeout. */
 const ASK_USER_POLL_WAIT_MS = 20_000;
-function registerAskUserTool(server, settings) {
+function registerAskUserTool(server, settings, fetchImpl) {
     server.registerTool("AskUser", {
         title: "Ask the user and wait",
         description: "Ask the user ONE consolidated free-text question on the current conversation and WAIT for their reply (blocking, up to the configured timeout — default 10 minutes). Returns the user's answer text. Consolidate everything you need into a single question — a second concurrent ask fails. If the wait times out, the tool returns without an answer and the user's late reply will arrive as their next message: finish the turn gracefully (proceed with sensible defaults and say what you assumed).",
@@ -221,11 +277,14 @@ function registerAskUserTool(server, settings) {
             question: z.string().min(1).describe("The full question to show the user (plain text, no markdown)."),
         },
     }, async (args, extra) => {
-        const created = await askBridgeRequest(settings, "POST", "/v1/asks", {
+        const created = await askBridgeRequest(settings, fetchImpl, "POST", "/v1/asks", {
             conversationId: settings.conversationId,
+            producerConversationId: settings.conversationId,
+            runId: settings.runId,
+            toolName: "AskUser",
             question: args.question,
             timeoutMs: settings.timeoutMs,
-        });
+        }, extra.signal);
         if (created.status === 409) {
             return askToolResult("A question is already pending for the user. Wait for its answer instead of asking again.", { answered: false, reason: "already_pending" });
         }
@@ -235,7 +294,7 @@ function registerAskUserTool(server, settings) {
         if (created.status !== 201 || typeof created.body.askId !== "string") {
             throw new Error(`AskUser: the interaction bridge rejected the ask (HTTP ${String(created.status)}).`);
         }
-        return await awaitBridgeAsk(settings, created.body.askId, "AskUser", extra);
+        return await awaitBridgeAsk(settings, created.body.askId, "AskUser", extra, fetchImpl, extra.signal);
     });
 }
 function askToolResult(text, structured, extraStructured = {}) {
@@ -244,42 +303,74 @@ function askToolResult(text, structured, extraStructured = {}) {
         structuredContent: { ok: true, ...extraStructured, ...structured },
     };
 }
-async function awaitBridgeAsk(settings, askId, toolName, extra, extraStructured = {}) {
+async function awaitBridgeAsk(settings, askId, toolName, extra, fetchImpl, signal, extraStructured = {}) {
     const startedMs = Date.now();
-    for (;;) {
-        const poll = await askBridgeRequest(settings, "GET", `/v1/asks/${encodeURIComponent(askId)}?waitMs=${String(ASK_USER_POLL_WAIT_MS)}`);
-        if (poll.status !== 200) {
-            throw new Error(`${toolName}: lost the pending ask (HTTP ${String(poll.status)}).`);
-        }
-        // Keep-alive: progress notifications reset the runtime's MCP inactivity
-        // timeout so a long human wait cannot kill the tool call.
-        await sendAskProgress(extra, Math.round((Date.now() - startedMs) / 1000));
-        const status = poll.body.status;
-        if (status === "answered" && typeof poll.body.answer === "string") {
-            const answeredText = toolName === "TelegramAskButtons"
-                ? `The user tapped:\n${poll.body.answer}`
-                : `The user answered:\n${poll.body.answer}`;
-            return askToolResult(answeredText, { answered: true, answer: poll.body.answer }, extraStructured);
-        }
-        if (status === "expired") {
-            return askToolResult("The user did not answer within the wait window. Their reply will arrive as their next message — wrap up this turn gracefully (proceed with sensible defaults and say what you assumed).", { answered: false, reason: "timeout" }, extraStructured);
-        }
-        if (status === "cancelled") {
-            return askToolResult("The user cancelled the current run. Stop this task.", {
-                answered: false,
-                reason: "cancelled",
-            }, extraStructured);
+    try {
+        for (;;) {
+            const poll = await askBridgeRequest(settings, fetchImpl, "GET", `/v1/asks/${encodeURIComponent(askId)}?waitMs=${String(ASK_USER_POLL_WAIT_MS)}`, undefined, signal);
+            if (poll.status !== 200) {
+                throw new Error(`${toolName}: lost the pending ask (HTTP ${String(poll.status)}).`);
+            }
+            // Keep-alive: progress notifications reset the runtime's MCP inactivity
+            // timeout so a long human wait cannot kill the tool call.
+            await sendAskProgress(extra, Math.round((Date.now() - startedMs) / 1000));
+            const status = poll.body.status;
+            if (status === "answered" && typeof poll.body.answer === "string") {
+                const answeredText = toolName === "TelegramAskButtons"
+                    ? `The user tapped:\n${poll.body.answer}`
+                    : `The user answered:\n${poll.body.answer}`;
+                return askToolResult(answeredText, { answered: true, answer: poll.body.answer }, extraStructured);
+            }
+            if (status === "expired") {
+                return askToolResult("The user did not answer within the wait window. Their reply will arrive as their next message — wrap up this turn gracefully (proceed with sensible defaults and say what you assumed).", { answered: false, reason: "timeout" }, extraStructured);
+            }
+            if (status === "cancelled") {
+                return askToolResult("The user cancelled the current run. Stop this task.", {
+                    answered: false,
+                    reason: "cancelled",
+                }, extraStructured);
+            }
         }
     }
+    catch (error) {
+        // A cancelled MCP call must not leave a bridge ask pending until its full
+        // human timeout. Cleanup gets its own bounded signal (not the aborted call
+        // signal), and its failure must never replace the primary tool failure.
+        await cleanupBridgeAskBestEffort(settings, fetchImpl, askId);
+        throw error;
+    }
 }
-async function askBridgeRequest(settings, method, path, body) {
-    const response = await fetch(new URL(path, settings.bridgeUrl), {
+async function cleanupBridgeAskBestEffort(settings, fetchImpl, askId) {
+    const controller = new AbortController();
+    let deadlineTimer;
+    const deadline = new Promise((resolve) => {
+        deadlineTimer = setTimeout(() => {
+            controller.abort(new Error("interaction bridge ask cleanup timed out"));
+            resolve();
+        }, ASK_BRIDGE_CLEANUP_TIMEOUT_MS);
+        deadlineTimer.unref?.();
+    });
+    // Attach the rejection handler before racing. If a test seam or nonstandard
+    // fetch ignores abort and rejects later, it cannot become an unhandled error.
+    const cleanup = askBridgeRequest(settings, fetchImpl, "DELETE", `/v1/asks/${encodeURIComponent(askId)}`, undefined, controller.signal).then(() => undefined, () => undefined);
+    try {
+        await Promise.race([cleanup, deadline]);
+    }
+    finally {
+        if (deadlineTimer !== undefined) {
+            clearTimeout(deadlineTimer);
+        }
+    }
+}
+async function askBridgeRequest(settings, fetchImpl, method, path, body, signal) {
+    const response = await fetchImpl(new URL(path, settings.bridgeUrl), {
         method,
         headers: {
             authorization: `Bearer ${settings.bridgeToken}`,
             ...(body === undefined ? {} : { "content-type": "application/json" }),
         },
         ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        ...(signal === undefined ? {} : { signal }),
     });
     let parsed;
     try {
@@ -313,31 +404,33 @@ async function sendAskProgress(extra, elapsedSeconds) {
         // Keep-alive only; a lost notification must never fail the ask.
     }
 }
-function registerSlackSendTool(server, settings, client, indexing) {
+function registerSlackSendTool(server, settings, client, formatMarkdownForSlack, indexing) {
     server.registerTool("SlackSendMessage", {
         title: "Send Slack message",
         description: "Send a message to an allowed Slack channel or DM ID using the configured Slack adapter bot token.",
         inputSchema: {
             channel: z.string().min(1).describe("Slack channel or DM ID, e.g. C123456 or D123456."),
-            text: z.string().min(1).describe("Message text to send."),
+            text: z.string().min(1).describe("Message text to send. Defaults to standard Markdown converted to Slack mrkdwn."),
             thread_ts: z.string().min(1).optional().describe("Optional Slack thread timestamp to reply in."),
-            mrkdwn: z.boolean().optional().describe("Whether Slack mrkdwn formatting is enabled."),
+            mrkdwn: z.boolean().optional().describe("Whether Slack mrkdwn formatting is enabled. Defaults to true; set false to send plain text unchanged."),
             unfurl_links: z.boolean().optional().describe("Whether Slack should unfurl links."),
             unfurl_media: z.boolean().optional().describe("Whether Slack should unfurl media."),
         },
-    }, async (args) => {
+    }, async (args, extra) => {
         assertSlackChannelAllowed(settings, args.channel);
-        const chunks = splitTextByCodePoints(args.text, SLACK_SEND_MESSAGE_MAX_CHARS);
+        const mrkdwn = args.mrkdwn ?? true;
+        const text = mrkdwn ? formatMarkdownForSlack(args.text) : args.text;
+        const chunks = splitTextByCodePoints(text, SLACK_SEND_MESSAGE_MAX_CHARS);
         const results = [];
         for (const chunk of chunks) {
             const result = await client.chatPostMessage({
                 channel: args.channel.trim(),
                 text: chunk,
                 ...(args.thread_ts === undefined ? {} : { thread_ts: args.thread_ts }),
-                ...(args.mrkdwn === undefined ? {} : { mrkdwn: args.mrkdwn }),
+                mrkdwn,
                 ...(args.unfurl_links === undefined ? {} : { unfurl_links: args.unfurl_links }),
                 ...(args.unfurl_media === undefined ? {} : { unfurl_media: args.unfurl_media }),
-            });
+            }, { signal: extra.signal });
             results.push(result);
             // Link every posted chunk back to this conversation so an in-thread reply can
             // resume it. Best-effort: appendPostedMessage never throws, so a failed index
@@ -383,7 +476,7 @@ function registerTelegramSendTool(server, settings, client) {
             reply_to_message_id: z.number().int().optional().describe("Optional message id to reply to."),
             disable_web_page_preview: z.boolean().optional().describe("Disable Telegram link previews."),
         },
-    }, async (args) => {
+    }, async (args, extra) => {
         assertTelegramChatAllowed(settings, args.chat_id);
         const result = await client.sendMessage({
             chat_id: args.chat_id,
@@ -391,17 +484,89 @@ function registerTelegramSendTool(server, settings, client) {
             ...(args.parse_mode === undefined ? {} : { parse_mode: args.parse_mode }),
             ...(args.reply_to_message_id === undefined ? {} : { reply_to_message_id: args.reply_to_message_id }),
             ...(args.disable_web_page_preview === undefined ? {} : { disable_web_page_preview: args.disable_web_page_preview }),
-        });
+        }, { signal: extra.signal });
         return {
             content: [{ type: "text", text: `Sent Telegram message ${result.message_id} to ${String(result.chat.id)}.` }],
             structuredContent: { ok: true, chat_id: result.chat.id, message_id: result.message_id },
         };
     });
 }
-function registerTelegramAskTool(server, settings, client, adapter) {
+/** Marker appended (buttons kept) when a Telegram ask times out. */
+const TELEGRAM_ASK_EXPIRED_MARKER = "⌛ Expired — tapping a button still reaches me and starts a new turn.";
+/** Marker appended (buttons kept) when a Telegram ask is cancelled. */
+const TELEGRAM_ASK_CANCELLED_MARKER = "🚫 Cancelled — tapping a button still reaches me and starts a new turn.";
+/** Bounded own-signal budget for the best-effort expiry edit — never the aborted call signal. */
+const TELEGRAM_ASK_EXPIRY_EDIT_TIMEOUT_MS = 2_000;
+/** A Telegram 400 is the parse-entity rejection we fall back from (raw text, no parse_mode). */
+function isTelegramParseError(error, adapter) {
+    return error instanceof adapter.TelegramApiError && error.errorCode === 400;
+}
+/**
+ * Send the ask keyboard rendered as MarkdownV2, retrying ONCE with the raw source and
+ * no parse_mode when Telegram rejects the entities with a 400 parse error. Any other
+ * failure propagates so the caller can clean up a pending bridge ask.
+ */
+async function sendTelegramAskKeyboard(client, adapter, params) {
+    try {
+        return await client.sendMessage({
+            chat_id: params.chat_id,
+            text: params.rendered,
+            parse_mode: "MarkdownV2",
+            reply_markup: params.replyMarkup,
+        }, { signal: params.signal });
+    }
+    catch (error) {
+        if (!isTelegramParseError(error, adapter)) {
+            throw error;
+        }
+        return await client.sendMessage({
+            chat_id: params.chat_id,
+            text: params.rawSource,
+            reply_markup: params.replyMarkup,
+        }, { signal: params.signal });
+    }
+}
+/**
+ * Best-effort: append an expiry/cancel note to the buttons message while KEEPING the
+ * inline keyboard (Telegram strips the keyboard on `editMessageText` unless reply_markup
+ * is re-sent). Renders through the same MarkdownV2-with-plain-fallback path. Uses its own
+ * bounded signal — never the aborted call signal — and swallows every failure so a failed
+ * edit can never replace the primary ask result.
+ */
+async function editExpiredTelegramAskMessage(client, adapter, params) {
+    try {
+        const source = `${params.rawSource}\n\n${params.marker}`;
+        const rendered = adapter.renderTelegramMarkdown(source);
+        const signal = AbortSignal.timeout(TELEGRAM_ASK_EXPIRY_EDIT_TIMEOUT_MS);
+        try {
+            await client.editMessageText({
+                chat_id: params.chat_id,
+                message_id: params.message_id,
+                text: rendered,
+                parse_mode: "MarkdownV2",
+                reply_markup: params.replyMarkup,
+            }, { signal });
+        }
+        catch (error) {
+            if (!isTelegramParseError(error, adapter)) {
+                throw error;
+            }
+            await client.editMessageText({
+                chat_id: params.chat_id,
+                message_id: params.message_id,
+                text: source,
+                reply_markup: params.replyMarkup,
+            }, { signal });
+        }
+    }
+    catch {
+        // Best-effort: a failed expiry edit must never replace the ask result.
+    }
+}
+function registerTelegramAskTool(server, settings, client, adapter, fetchImpl) {
     server.registerTool("TelegramAskButtons", {
         title: "Ask via Telegram buttons",
-        description: "Ask the owner a question in an allowed Telegram chat with tappable inline-keyboard buttons (e.g. a confirmation or a multiple-choice) and WAIT for their tap. Returns the tapped label. A second concurrent ask in the same chat fails.",
+        description: "Ask the owner a question in an allowed Telegram chat with tappable inline-keyboard buttons (e.g. a confirmation or a multiple-choice). By default WAITS for their tap (up to the ask timeout) and returns the tapped label; a second concurrent ask in the same chat fails. On a proactive or scheduled turn (cron/heartbeat) set `wait:false`: the buttons are sent and the tool returns immediately, and the tap arrives later as a new message quoting the question.",
         inputSchema: {
             chat_id: z.union([z.string().min(1), z.number().int()]).describe("Telegram chat id from the adapter allowlist."),
             question: z.string().min(1).describe("The question to show above the buttons."),
@@ -411,9 +576,34 @@ function registerTelegramAskTool(server, settings, client, adapter) {
                 .max(adapter.TELEGRAM_ASK_MAX_OPTIONS)
                 .describe("Button labels (2–8). The label the user taps is echoed back as a new message."),
             note: z.string().min(1).optional().describe("Optional extra context shown beneath the question."),
+            wait: z
+                .boolean()
+                .optional()
+                .describe("Default true: block until the user taps (up to the ask timeout). Set false on proactive/scheduled (cron/heartbeat) turns — send the buttons and return immediately; the tapped answer arrives later as a new message quoting the question."),
         },
     }, async (args, extra) => {
         assertTelegramChatAllowed(settings, args.chat_id);
+        const inlineKeyboard = args.options.map((label, index) => [
+            { text: label, callback_data: adapter.telegramAskCallbackData(index) },
+        ]);
+        const replyMarkup = { inline_keyboard: inlineKeyboard };
+        // Raw source is what the bridge records and what the plain-text fallback (and the
+        // expiry edit) re-send; the rendered form is only for the MarkdownV2 send.
+        const source = args.note === undefined ? args.question : `${args.question}\n\n${args.note}`;
+        const rendered = adapter.renderTelegramMarkdown(source);
+        // Non-blocking mode (proactive/scheduled turns): send the buttons and return.
+        // No bridge is consulted — this must work even with no bridge configured.
+        if (args.wait === false) {
+            const sent = await sendTelegramAskKeyboard(client, adapter, {
+                chat_id: args.chat_id,
+                rendered,
+                rawSource: source,
+                replyMarkup,
+                signal: extra.signal,
+            });
+            return askToolResult(`Sent the question with ${String(args.options.length)} buttons to ${String(sent.chat.id)} (message ${String(sent.message_id)}). Not waiting — the tapped answer will arrive as a new message.`, { answered: false, reason: "not_waiting" }, { chat_id: sent.chat.id, message_id: sent.message_id, options: args.options });
+        }
+        // Blocking mode requires the interaction bridge to correlate the tap.
         const bridge = settings.askBridge;
         if (bridge === undefined) {
             return askToolResult("TelegramAskButtons requires a live interaction bridge, but none is configured.", {
@@ -421,18 +611,18 @@ function registerTelegramAskTool(server, settings, client, adapter) {
                 reason: "unsupported_channel",
             });
         }
-        const inlineKeyboard = args.options.map((label, index) => [
-            { text: label, callback_data: adapter.telegramAskCallbackData(index) },
-        ]);
-        const text = args.note === undefined ? args.question : `${args.question}\n\n${args.note}`;
         const conversationId = `telegram:${String(args.chat_id)}`;
-        const created = await askBridgeRequest(bridge, "POST", "/v1/asks", {
+        const created = await askBridgeRequest(bridge, fetchImpl, "POST", "/v1/asks", {
             conversationId,
-            question: text,
+            producerConversationId: bridge.conversationId,
+            runId: bridge.runId,
+            toolName: "TelegramAskButtons",
+            question: source,
+            options: args.options,
             timeoutMs: bridge.timeoutMs,
             postQuestion: false,
             answerKind: "callback",
-        });
+        }, extra.signal);
         if (created.status === 409) {
             return askToolResult("A question is already pending for this Telegram chat. Wait for its answer instead of asking again.", { answered: false, reason: "already_pending" }, { chat_id: args.chat_id });
         }
@@ -445,21 +635,36 @@ function registerTelegramAskTool(server, settings, client, adapter) {
         const askId = created.body.askId;
         let result;
         try {
-            result = await client.sendMessage({
+            result = await sendTelegramAskKeyboard(client, adapter, {
                 chat_id: args.chat_id,
-                text,
-                reply_markup: { inline_keyboard: inlineKeyboard },
+                rendered,
+                rawSource: source,
+                replyMarkup,
+                signal: extra.signal,
             });
         }
         catch (error) {
-            await askBridgeRequest(bridge, "DELETE", `/v1/asks/${encodeURIComponent(askId)}`);
+            await cleanupBridgeAskBestEffort(bridge, fetchImpl, askId);
             throw error;
         }
-        return await awaitBridgeAsk(bridge, askId, "TelegramAskButtons", extra, {
+        const askResult = await awaitBridgeAsk(bridge, askId, "TelegramAskButtons", extra, fetchImpl, extra.signal, {
             chat_id: result.chat.id,
             message_id: result.message_id,
             options: args.options,
         });
+        // An expired/cancelled ask leaves a live-looking keyboard forever; append a note
+        // while keeping the buttons (a tap still starts a fresh turn). Best-effort only.
+        const reason = askResult.structuredContent.reason;
+        if (reason === "timeout" || reason === "cancelled") {
+            await editExpiredTelegramAskMessage(client, adapter, {
+                chat_id: result.chat.id,
+                message_id: result.message_id,
+                rawSource: source,
+                marker: reason === "timeout" ? TELEGRAM_ASK_EXPIRED_MARKER : TELEGRAM_ASK_CANCELLED_MARKER,
+                replyMarkup,
+            });
+        }
+        return askResult;
     });
 }
 /**
@@ -473,7 +678,7 @@ function registerTelegramAskTool(server, settings, client, adapter) {
 function registerTelegramSendFileTool(server, settings, client, adapter) {
     server.registerTool("TelegramSendFile", {
         title: "Send Telegram file",
-        description: "Upload and send a file to an allowed Telegram chat. Set `kind:\"document\"` to send any file (shown as a downloadable document) or `kind:\"photo\"` to send an image inline. Provide the bytes as base64 `data` (with a `filename` — required for a document), or a workspace `path` (preferred — with a self-hosted Bot API server a `path` upload streams from disk with no size buffering, up to the configured cap).",
+        description: "Upload and send a file to an allowed Telegram chat. Set `kind:\"document\"` to send any file (shown as a downloadable document) or `kind:\"photo\"` to send an image inline. Provide the bytes as base64 `data` (with a `filename` — required for a document), or a workspace `path`. A self-hosted Bot API can stream legacy path uploads; strict run-output paths are always read through a pinned descriptor.",
         inputSchema: {
             kind: z.enum(["document", "photo"]).describe("`document` for any file (downloadable), `photo` for an image shown inline."),
             chat_id: z.union([z.string().min(1), z.number().int()]).describe("Telegram chat id from the adapter allowlist."),
@@ -482,17 +687,27 @@ function registerTelegramSendFileTool(server, settings, client, adapter) {
             filename: z.string().min(1).optional().describe("Filename to present. Required with `data` for a document; derived from `path` otherwise."),
             caption: z.string().min(1).optional().describe("Optional caption shown with the file."),
         },
-    }, async (args) => {
+    }, async (args, extra) => {
+        extra.signal.throwIfAborted();
         const kind = args.kind;
         assertTelegramChatAllowed(settings, args.chat_id);
+        if ((args.data !== undefined) === (args.path !== undefined)) {
+            throw new Error("provide exactly one of `data` (base64) or `path`.");
+        }
         const maxUploadBytes = settings.maxUploadBytes ?? adapter.DEFAULT_ATTACHMENT_MAX_BYTES;
+        const strictPathUpload = args.path !== undefined && settings.sendTools?.pathScope === "run-output";
+        const strictFile = strictPathUpload
+            ? await readStrictTelegramFile(settings, args.path, maxUploadBytes, extra.signal, args.filename)
+            : undefined;
+        const uploadPath = args.path === undefined || strictPathUpload
+            ? undefined
+            : await resolveTelegramUploadPath(args.path);
         // file:// fast path: a --local self-hosted server reads the file straight
         // from disk, so a path upload needs no buffering at any size — only a
         // stat-level cap check. Falls back once to the buffered path when the
         // server rejects the URI (e.g. a non---local self-hosted root).
-        if (kind === "document" && settings.apiRoot !== undefined && args.path !== undefined && args.data === undefined) {
-            const resolved = resolvePath(process.cwd(), args.path);
-            const info = await stat(resolved);
+        if (kind === "document" && settings.apiRoot !== undefined && uploadPath !== undefined && args.data === undefined) {
+            const info = await stat(uploadPath);
             if (!info.isFile() || info.size === 0) {
                 throw new Error("file is empty or not a regular file.");
             }
@@ -502,10 +717,10 @@ function registerTelegramSendFileTool(server, settings, client, adapter) {
             try {
                 const sent = await client.sendDocument({
                     chat_id: args.chat_id,
-                    document: pathToFileURL(resolved).href,
+                    document: pathToFileURL(uploadPath).href,
                     ...(args.caption === undefined ? {} : { caption: args.caption }),
-                });
-                const name = basename(resolved);
+                }, { signal: extra.signal });
+                const name = basename(uploadPath);
                 return {
                     content: [{ type: "text", text: `Sent ${kind} ${sent.message_id} (${name}) to ${String(sent.chat.id)}.` }],
                     structuredContent: { ok: true, chat_id: sent.chat.id, message_id: sent.message_id, filename: name },
@@ -518,12 +733,14 @@ function registerTelegramSendFileTool(server, settings, client, adapter) {
                 }
             }
         }
-        const { bytes, filename } = await resolveTelegramFileBytes({
+        const { bytes, filename } = strictFile ?? await resolveTelegramFileBytes({
             data: args.data,
             path: args.path,
+            ...(uploadPath === undefined ? {} : { resolvedPath: uploadPath }),
             filename: args.filename,
             requireFilename: kind === "document",
             maxBytes: maxUploadBytes,
+            signal: extra.signal,
         });
         const result = kind === "document"
             ? await client.sendDocument({
@@ -531,13 +748,13 @@ function registerTelegramSendFileTool(server, settings, client, adapter) {
                 document: bytes,
                 filename,
                 ...(args.caption === undefined ? {} : { caption: args.caption }),
-            })
+            }, { signal: extra.signal })
             : await client.sendPhoto({
                 chat_id: args.chat_id,
                 photo: bytes,
                 filename,
                 ...(args.caption === undefined ? {} : { caption: args.caption }),
-            });
+            }, { signal: extra.signal });
         return {
             content: [{ type: "text", text: `Sent ${kind} ${result.message_id} (${filename}) to ${String(result.chat.id)}.` }],
             structuredContent: { ok: true, chat_id: result.chat.id, message_id: result.message_id, filename },
@@ -566,8 +783,8 @@ async function resolveTelegramFileBytes(input) {
         }
     }
     else {
-        const resolved = resolvePath(process.cwd(), input.path);
-        bytes = new Uint8Array(await readFile(resolved));
+        const resolved = input.resolvedPath ?? resolvePath(process.cwd(), input.path);
+        bytes = new Uint8Array(await readFile(resolved, { signal: input.signal }));
         filename = input.filename ?? basename(resolved);
     }
     if (bytes.byteLength === 0) {
@@ -578,6 +795,110 @@ async function resolveTelegramFileBytes(input) {
     }
     return { bytes, filename };
 }
+async function resolveTelegramUploadPath(inputPath) {
+    return resolvePath(process.cwd(), inputPath);
+}
+const STRICT_TELEGRAM_PATH_ERROR = "TelegramSendFile: path must be a regular file inside the current run output directory.";
+/**
+ * Read a strict upload through one no-follow file descriptor. Every path check
+ * deliberately collapses to the same error so callers cannot use the tool as
+ * an existence oracle for files outside the run directory.
+ */
+async function readStrictTelegramFile(settings, inputPath, maxBytes, signal, requestedFilename) {
+    try {
+        signal.throwIfAborted();
+        if (settings.runOutputDir === undefined || settings.runOutputIdentity === undefined) {
+            throw new Error(STRICT_TELEGRAM_PATH_ERROR);
+        }
+        const rootStats = await lstat(settings.runOutputDir);
+        if (!rootStats.isDirectory()
+            || rootStats.isSymbolicLink()
+            || !sameFileIdentity(rootStats, settings.runOutputIdentity)) {
+            throw new Error(STRICT_TELEGRAM_PATH_ERROR);
+        }
+        const rootReal = await realpath(settings.runOutputDir);
+        const candidate = resolvePath(process.cwd(), inputPath);
+        const candidateLinkStats = await lstat(candidate);
+        if (!candidateLinkStats.isFile()
+            || candidateLinkStats.isSymbolicLink()
+            || candidateLinkStats.nlink !== 1) {
+            throw new Error(STRICT_TELEGRAM_PATH_ERROR);
+        }
+        const candidateReal = await realpath(candidate);
+        if (!pathIsInside(rootReal, candidateReal))
+            throw new Error(STRICT_TELEGRAM_PATH_ERROR);
+        const handle = await open(candidateReal, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        try {
+            const openedStats = await handle.stat();
+            if (!openedStats.isFile()
+                || openedStats.nlink !== 1
+                || openedStats.size === 0
+                || openedStats.size > maxBytes) {
+                throw new Error(STRICT_TELEGRAM_PATH_ERROR);
+            }
+            if (!sameFileIdentity(openedStats, fileIdentity(candidateLinkStats))) {
+                throw new Error(STRICT_TELEGRAM_PATH_ERROR);
+            }
+            await assertPinnedCandidate(candidateReal, openedStats);
+            await assertUnchangedRunRoot(settings.runOutputDir, rootReal, settings.runOutputIdentity);
+            const bytes = await readPinnedBytes(handle, openedStats.size, signal);
+            await assertPinnedCandidate(candidateReal, openedStats);
+            await assertUnchangedRunRoot(settings.runOutputDir, rootReal, settings.runOutputIdentity);
+            const finalStats = await handle.stat();
+            if (!sameFileIdentity(finalStats, fileIdentity(openedStats))
+                || finalStats.nlink !== 1
+                || finalStats.size !== openedStats.size
+                || bytes.byteLength === 0
+                || bytes.byteLength > maxBytes) {
+                throw new Error(STRICT_TELEGRAM_PATH_ERROR);
+            }
+            return { bytes, filename: requestedFilename ?? basename(candidateReal) };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw signal.reason ?? error;
+        throw new Error(STRICT_TELEGRAM_PATH_ERROR);
+    }
+}
+async function readPinnedBytes(handle, size, signal) {
+    const bytes = Buffer.allocUnsafe(size);
+    let offset = 0;
+    while (offset < size) {
+        signal.throwIfAborted();
+        const read = await handle.read(bytes, offset, size - offset, offset);
+        if (read.bytesRead === 0)
+            break;
+        offset += read.bytesRead;
+    }
+    if (offset !== size)
+        throw new Error(STRICT_TELEGRAM_PATH_ERROR);
+    return new Uint8Array(bytes);
+}
+function pathIsInside(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    return fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot);
+}
+async function assertPinnedCandidate(path, opened) {
+    const current = await lstat(path);
+    if (!current.isFile()
+        || current.isSymbolicLink()
+        || current.nlink !== 1
+        || !sameFileIdentity(current, fileIdentity(opened))) {
+        throw new Error(STRICT_TELEGRAM_PATH_ERROR);
+    }
+}
+async function assertUnchangedRunRoot(path, expectedRealPath, expectedIdentity) {
+    const current = await lstat(path);
+    if (!current.isDirectory() || current.isSymbolicLink() || !sameFileIdentity(current, expectedIdentity)) {
+        throw new Error(STRICT_TELEGRAM_PATH_ERROR);
+    }
+    if (await realpath(path) !== expectedRealPath)
+        throw new Error(STRICT_TELEGRAM_PATH_ERROR);
+}
 async function resolveSlackSendToolSettings(input, options) {
     try {
         const adapter = await loadSlackModule();
@@ -605,6 +926,9 @@ async function resolveTelegramSendToolSettings(input, options, tools, askBridge)
         if (!config.enabled) {
             return undefined;
         }
+        const producingConversationId = optionalString(input.env.MONO_AGENT_ADAPTER_TOOLS_PRODUCING_CONVERSATION_ID);
+        const runOutputDir = optionalString(input.env.MONO_AGENT_ADAPTER_TOOLS_RUN_OUTPUT_DIR);
+        const runOutputIdentity = parseFileIdentity(input.env.MONO_AGENT_ADAPTER_TOOLS_RUN_OUTPUT_DEV, input.env.MONO_AGENT_ADAPTER_TOOLS_RUN_OUTPUT_INO);
         return {
             botToken: config.botToken,
             allowedChatIds: config.allowedChatIds,
@@ -613,6 +937,10 @@ async function resolveTelegramSendToolSettings(input, options, tools, askBridge)
             maxUploadBytes: config.attachments?.maxUploadBytes ?? adapter.DEFAULT_ATTACHMENT_MAX_BYTES,
             tools,
             ...(askBridge === undefined ? {} : { askBridge }),
+            ...(config.sendTools === undefined ? {} : { sendTools: config.sendTools }),
+            ...(producingConversationId === undefined ? {} : { producingConversationId }),
+            ...(runOutputDir === undefined ? {} : { runOutputDir }),
+            ...(runOutputIdentity === undefined ? {} : { runOutputIdentity }),
         };
     }
     catch (error) {
@@ -630,11 +958,81 @@ function assertSlackChannelAllowed(settings, channel) {
 }
 function assertTelegramChatAllowed(settings, chatId) {
     const normalized = String(chatId);
+    if (settings.sendTools?.scope === "producing-conversation") {
+        const producingChatId = telegramChatIdFromConversation(settings.producingConversationId);
+        if (producingChatId === undefined) {
+            throw new Error("TelegramSendMessage: producing Telegram conversation context is unavailable.");
+        }
+        if (normalized !== producingChatId) {
+            throw new Error("TelegramSendMessage: chat_id must match the producing Telegram conversation.");
+        }
+    }
     if (settings.allowAllChats || settings.allowedChatIds.includes(normalized)) {
         return;
     }
     throw new Error("TelegramSendMessage: chat_id is not allowed by Telegram adapter config.");
 }
+function telegramChatIdFromConversation(conversationId) {
+    if (conversationId === undefined)
+        return undefined;
+    const base = conversationId.split("#", 1)[0] ?? conversationId;
+    if (!base.startsWith("telegram:"))
+        return undefined;
+    const chatId = base.slice("telegram:".length);
+    return chatId.length === 0 ? undefined : chatId;
+}
+const SAFE_ADAPTER_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/u;
+async function ensureAdapterRunOutputDir(root, runId) {
+    if (!SAFE_ADAPTER_RUN_ID.test(runId)) {
+        throw new Error("adapter-send-tools: run id is unsafe for the run output directory.");
+    }
+    const outputRoot = resolvePath(root);
+    const runOutputDir = join(outputRoot, runId);
+    await mkdir(outputRoot, { recursive: true, mode: 0o700 });
+    try {
+        await mkdir(runOutputDir, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        const existing = await lstat(runOutputDir);
+        if (!existing.isDirectory() || existing.isSymbolicLink()) {
+            throw new Error("adapter-send-tools: run output path is not a real directory.");
+        }
+    }
+    const current = await lstat(runOutputDir);
+    if (!current.isDirectory() || current.isSymbolicLink()) {
+        throw new Error("adapter-send-tools: run output path is not a real directory.");
+    }
+    return { path: runOutputDir, identity: fileIdentity(current) };
+}
+function fileIdentity(stats) {
+    return { dev: stats.dev, ino: stats.ino };
+}
+function sameFileIdentity(stats, expected) {
+    return stats.dev === expected.dev && stats.ino === expected.ino;
+}
+function parseFileIdentity(devValue, inoValue) {
+    const dev = Number(devValue);
+    const ino = Number(inoValue);
+    return Number.isSafeInteger(dev) && dev >= 0 && Number.isSafeInteger(ino) && ino > 0
+        ? { dev, ino }
+        : undefined;
+}
+async function removeOwnedDirectory(path, expected) {
+    let current;
+    try {
+        current = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    if (!current.isDirectory() || current.isSymbolicLink() || !sameFileIdentity(current, expected))
+        return;
+    await rm(path, { recursive: true, force: true });
+}
 function optionalString(value) {
     if (value === undefined) {
         return undefined;