charness 0.0.0-stage → 3.1.0

package/dist/scheduler/mcpSurface.js

@@ -0,0 +1,1297 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schedulerMcpPendingCancellationMax = exports.schedulerMcpPendingCancellationTtlMs = exports.schedulerMcpBindRetryDelayMs = exports.schedulerMcpBindRetryCount = exports.schedulerMcpClientIdHeader = exports.schedulerMcpPath = exports.defaultSchedulerMcpPort = void 0;
+exports.buildMcpServerInstructions = buildMcpServerInstructions;
+exports.getSchedulerMcpPort = getSchedulerMcpPort;
+exports.resolveSchedulerMcpPort = resolveSchedulerMcpPort;
+exports.getSchedulerScopePlatform = getSchedulerScopePlatform;
+exports.serializeSchedulerScope = serializeSchedulerScope;
+exports.parseSchedulerScope = parseSchedulerScope;
+exports.buildSchedulerMcpToken = buildSchedulerMcpToken;
+exports.verifySchedulerMcpToken = verifySchedulerMcpToken;
+exports.extractBearerToken = extractBearerToken;
+exports.buildBotMcpToolDigest = buildBotMcpToolDigest;
+exports.getBotMcpToolDigest = getBotMcpToolDigest;
+exports.resolveTargetThreadKey = resolveTargetThreadKey;
+exports.buildSpecFromCreateArgs = buildSpecFromCreateArgs;
+exports.checkIsConversationInScope = checkIsConversationInScope;
+exports.createSchedulerMcpCancellationLifecycle = createSchedulerMcpCancellationLifecycle;
+exports.createSchedulerMcpServer = createSchedulerMcpServer;
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const zod_1 = require("zod");
+const sessionKey_1 = require("../sessionKey");
+const isoTimestamp_1 = require("../utils/isoTimestamp");
+const messageSendService_1 = require("../utils/messageSendService");
+const utils_1 = require("../utils");
+const checkRun_1 = require("./checkRun");
+const deliveryKind_1 = require("./deliveryKind");
+const recurrence_1 = require("./recurrence");
+const store_1 = require("./store");
+const answerRequest_1 = require("../requests/answerRequest");
+/**
+ * @description The bot-owned MCP server exposes the agent-facing tools —
+ * `schedule_create`, `schedule_list`, `schedule_cancel`, `send_file_to_user`,
+ * `send_messages_to_user`, `compact_conversation` and `answer_request` — over
+ * streamable HTTP on a loopback port. The server is
+ * INERT until `bot.ts` wires {@link createSchedulerMcpServer}; this module
+ * imports nothing from `bot.ts` (every side effect is injected via
+ * {@link SchedulerMcpDeps}).
+ *
+ * Transport: STATELESS streamable HTTP (`sessionIdGenerator: undefined`) — a
+ * research-locked choice (plan S5) that dodges the SDK's session-loss bugs and
+ * suits a single local host. The SDK binds one `McpServer` to one transport per
+ * connection, so every request builds a FRESH `McpServer` + transport (see
+ * {@link buildRequestServer}) that registers the same handlers, and they
+ * are closed when the response finishes. MCP cancellation arrives as a separate
+ * HTTP notification, so {@link createSchedulerMcpServer} keeps only the active
+ * request abort controllers plus one bounded, expiring lifecycle-tombstone cache
+ * across those otherwise-stateless transports. A pending-cancellation tombstone
+ * handles a cancellation that genuinely leads first registration; a
+ * recently-completed tombstone suppresses an unmatched late cancellation only
+ * while that key is inactive. An active request always takes precedence so its
+ * own legitimate cancellation can abort it even after typed JSON-RPC id reuse.
+ *
+ * Auth/scoping: a request carries `Authorization: Bearer <token>`. The token is
+ * self-describing — `<scopeB64url>.<hmacHex>` — so the bot need not know every
+ * valid scope up front (an OpenCode directory scope is any bound folder). The
+ * scope rides in cleartext (base64url) next to an HMAC-SHA256 signature over the
+ * decoded scope string; {@link verifySchedulerMcpToken} recomputes the HMAC and
+ * compares it timing-safely. A scope is one of:
+ *   - `thread:<threadKey>` — a Claude session, pinned to its exact thread.
+ *   - `dir:<directory>`    — an OpenCode instance, granular to a bound folder.
+ * Every tool call resolves a single target thread from the scope (see
+ * {@link resolveTargetThreadKey}) and can only touch that thread's jobs —
+ * except `answer_request`, whose request id already names the conversation: it
+ * only checks that conversation is inside the scope
+ * ({@link checkIsConversationInScope}).
+ */
+/**
+ * Default loopback port for the scheduler MCP server. Zero asks the OS for a
+ * free ephemeral port, so independent bot instances never compete for 4097.
+ */
+exports.defaultSchedulerMcpPort = 0;
+/** HTTP path the streamable transport is served on (matches the injected `--mcp-config` url, S6). */
+exports.schedulerMcpPath = '/mcp';
+/** Per-registration identity used to isolate equal JSON-RPC request IDs. */
+exports.schedulerMcpClientIdHeader = 'x-telegramcode-mcp-client-id';
+/**
+ * A port that is in use at the start is retried this many times, this far apart,
+ * before the bot binds another one. Another port orphans every Claude session
+ * launched before (it keeps the MCP address of its launch), and the holder may
+ * let go soon: the previous process still exiting, or a short connection of
+ * another process that was handed the port as its local one while the bot was
+ * down. Together they span the shutdown watchdog's bound (`DEFAULT_WATCHDOG_MS`),
+ * the longest the previous generation can take to exit.
+ */
+exports.schedulerMcpBindRetryCount = 20;
+exports.schedulerMcpBindRetryDelayMs = 500;
+/** Pending cancellations and recent completions remain correlatable for this window. */
+exports.schedulerMcpPendingCancellationTtlMs = 30_000;
+/** Global memory bound shared by pending-cancellation and recent-completion tombstones. */
+exports.schedulerMcpPendingCancellationMax = 1_000;
+const schedulerMcpClientIdMaxLength = 128;
+const schedulerMcpClientIdPattern = /^[A-Za-z0-9._:-]+$/;
+/** Server identity reported in the MCP `initialize` handshake. */
+const mcpServerName = 'telegram-bot-scheduler';
+const mcpServerVersion = '1.0.0';
+/** The instruction bullets that hold on every platform (the two platform-neutral tools). */
+const compactConversationInstruction = '• The user EXPLICITLY asks to compact/shrink/summarize this conversation\'s context → compact_conversation. Only on an explicit request, never on your own judgement.';
+const answerRequestInstruction = '• A message carries a "[Request <id> · from: …]" header → answer it through answer_request with that id: kind "final" with the full result at the end of your turn, "question" when you need the requester before you can go on (their reply arrives as a new request), "progress" for an interim note. You may call it several times; only question/final close the request.';
+const claudeProfilesInstruction = '• Before you start a child `claude` process (a detached worker, reviewer, planner) → claude_profiles with the model you will launch: it lists the signed-in Claude accounts with their usage windows and names the one with the most headroom (`recommended`). Launch the child with `CLAUDE_CONFIG_DIR=<its configDir>` in its environment (nothing when configDir is null); without it the child inherits YOUR account and drains the same limits.';
+const telegramInstructions = `This MCP lets the agent act on its own Telegram topic.
+
+When to use it:
+• The user asks to run/finish a plan or task LATER ("in 2h", "tomorrow 9am", "every weekday") → schedule_create. Put the work in \`prompt\`; the future run is a fresh session with no memory of this chat.
+• You produced a file/chart/screenshot/video to deliver → send_file_to_user. Videos MUST be H.264 .mp4 sent as video (never as_file/document, never .webm/.mov — those render as GIFs or don't play); transcode first if needed (the tool description has the ffmpeg recipe).
+• You want to deliver SEVERAL discrete messages (each as its own Telegram message, e.g. a per-item news digest) → send_messages_to_user. Each item can optionally attach ONE file/photo/video (text becomes its caption).
+${compactConversationInstruction}
+• You need to review or remove scheduled jobs → schedule_list / schedule_cancel.
+• You need a watchdog — keep an eye on a service, process, build, deploy, disk, URL… → schedule_create with \`checkCommand\` (cron). The bot runs the command in this folder on schedule, stays silent while it exits 0, and on the first failure pins an alert and wakes you with \`prompt\` + the exit code and output tail. Checks survive bot restarts and crashes. NEVER build your own watcher (a background loop, nohup, a sleep loop, a tmux pane, a shell crontab): it dies with your session or a restart and then fails silently.
+${answerRequestInstruction} The requester may not see your plain text, so anything they must read goes through answer_request. Your plain text is relayed into the topic too, so after answer_request end the turn WITHOUT a plain-text recap of what you answered — it would show up twice.
+${claudeProfilesInstruction}
+
+Each tool's own description has the exact argument recipe (one-shot vs cron vs N-times, checks).`;
+/** What a Jira session's instructions add: the tool that reaches the issue's original files (C10). */
+const jiraAttachmentInstruction = '• The issue lists a file (an attachment id in the attachments list, or in a placeholder such as "[image: shot.png — attachment 10234]") you need to look at → jira_get_attachment with that id; it saves the original file and returns its path.';
+/** For a conversation on a tracker: the requester sees nothing but the answers; `extraInstructions` name the platform's own tools. */
+function buildTrackerInstructions(extraInstructions) {
+    return `This MCP connects the agent to the conversation that asked for its work.
+
+When to use it:
+${[
+        `${answerRequestInstruction} The requester never sees your plain text or tool output: anything they must read goes through answer_request.`,
+        ...extraInstructions,
+        compactConversationInstruction,
+        claudeProfilesInstruction,
+    ].join('\n')}
+
+Each tool's own description has the exact argument recipe.`;
+}
+const neutralInstructions = buildTrackerInstructions([]);
+const jiraInstructions = buildTrackerInstructions([jiraAttachmentInstruction]);
+/**
+ * Connect-time `instructions` returned in the MCP `initialize` handshake — a
+ * short, high-level pointer the client surfaces to the agent BEFORE any call.
+ * Deliberately use-case oriented (when to reach for this server, what it can do)
+ * and does NOT repeat the per-tool argument recipes: each tool's own description
+ * already carries those in full. Kept terse on purpose.
+ *
+ * @description The connect-time instructions for a session of `platform`: only
+ * a Telegram session has the scheduling and send-to-topic tools, so only its
+ * instructions name them (Jira connector plan J2, D18).
+ */
+function buildMcpServerInstructions(platform, isJiraAttachmentToolOffered = false) {
+    if (platform === 'telegram')
+        return telegramInstructions;
+    return platform === 'jira' && isJiraAttachmentToolOffered ? jiraInstructions : neutralInstructions;
+}
+/** Max characters of a free-text job name / prompt accepted by a tool (defensive bound). */
+const maxNameLength = 200;
+const maxPromptLength = 8000;
+/** Read the configured scheduler MCP port once, mirroring the OPENCODE_URL env read. */
+function getSchedulerMcpPort() {
+    const raw = process.env.SCHEDULER_MCP_PORT;
+    if (!raw)
+        return exports.defaultSchedulerMcpPort;
+    const parsed = Number(raw);
+    return Number.isInteger(parsed) && parsed >= 0 && parsed <= 65535
+        ? parsed
+        : exports.defaultSchedulerMcpPort;
+}
+/**
+ * @description Resolve the scheduler MCP listen port with a fixed precedence:
+ * an explicit env port (`SCHEDULER_MCP_PORT`, a non-zero {@link getSchedulerMcpPort})
+ * WINS; else the port persisted from a prior boot (so an ephemeral port, once
+ * chosen, is reused — the registrations injected into agent sessions point at
+ * it, and an ephemeral port changing every restart would orphan them); else `0`
+ * (ask the OS for a fresh ephemeral port). A persisted `0` / non-positive value
+ * is ignored (nothing worth reusing).
+ */
+function resolveSchedulerMcpPort(envPort, persistedPort) {
+    if (envPort !== exports.defaultSchedulerMcpPort)
+        return envPort;
+    if (persistedPort !== undefined && persistedPort > 0)
+        return persistedPort;
+    return exports.defaultSchedulerMcpPort;
+}
+/**
+ * @description The platform of the conversations a scope reaches. A `dir:`
+ * scope is an OpenCode registration, which only Telegram topics use today. A
+ * thread key no codec reads gets the narrower, platform-neutral tool set.
+ */
+function getSchedulerScopePlatform(scope) {
+    if (scope.kind === 'dir')
+        return 'telegram';
+    return (0, sessionKey_1.tryKeyFromString)(scope.threadKey)?.platform ?? null;
+}
+/** Serialise a scope to its canonical cleartext form (the string the HMAC signs). */
+function serializeSchedulerScope(scope) {
+    return scope.kind === 'thread' ? `thread:${scope.threadKey}` : `dir:${scope.directory}`;
+}
+/** Parse the canonical cleartext scope string back into a {@link SchedulerScope}, or `null`. */
+function parseSchedulerScope(serialized) {
+    const sep = serialized.indexOf(':');
+    if (sep <= 0)
+        return null;
+    const kind = serialized.slice(0, sep);
+    const rest = serialized.slice(sep + 1);
+    if (rest.length === 0)
+        return null;
+    if (kind === 'thread')
+        return { kind: 'thread', threadKey: rest };
+    if (kind === 'dir')
+        return { kind: 'dir', directory: rest };
+    return null;
+}
+/** HMAC-SHA256(secret, message) as lowercase hex. */
+function computeHmacHex(secret, message) {
+    return (0, node_crypto_1.createHmac)('sha256', secret).update(message).digest('hex');
+}
+/**
+ * @description Mint a bearer token for a scope: `<scopeB64url>.<hmacHex>`. The
+ * scope rides in cleartext (base64url of the canonical scope string) so the
+ * verifier can recover it without a lookup table; the HMAC over the DECODED
+ * scope string is the unforgeable part. Document/keep in sync with
+ * {@link verifySchedulerMcpToken}.
+ */
+function buildSchedulerMcpToken(secret, scope) {
+    const serialized = serializeSchedulerScope(scope);
+    const scopeB64 = Buffer.from(serialized, 'utf8').toString('base64url');
+    const signature = computeHmacHex(secret, serialized);
+    return `${scopeB64}.${signature}`;
+}
+/**
+ * @description Verify a bearer token and recover its scope. Splits on the single
+ * `.`, base64url-decodes the scope half, recomputes the HMAC over the decoded
+ * scope string, and compares it to the token's signature with a constant-time
+ * {@link timingSafeEqual} (equal-length hex buffers). Returns the parsed scope on
+ * success, or `null` for any malformed / tampered token. A tampered scope half
+ * changes the HMAC input so the recomputed signature won't match; a tampered
+ * signature half fails the compare directly.
+ */
+function verifySchedulerMcpToken(secret, token) {
+    const dot = token.indexOf('.');
+    if (dot <= 0 || dot === token.length - 1)
+        return null;
+    const scopeB64 = token.slice(0, dot);
+    const providedSignature = token.slice(dot + 1);
+    let serialized;
+    try {
+        serialized = Buffer.from(scopeB64, 'base64url').toString('utf8');
+    }
+    catch {
+        return null;
+    }
+    const scope = parseSchedulerScope(serialized);
+    if (!scope)
+        return null;
+    const expectedSignature = computeHmacHex(secret, serialized);
+    // timingSafeEqual throws on length mismatch, so length-gate first (hex of a
+    // SHA-256 is always 64 chars, but a tampered token could be any length).
+    const expectedBuffer = Buffer.from(expectedSignature, 'utf8');
+    const providedBuffer = Buffer.from(providedSignature, 'utf8');
+    if (expectedBuffer.length !== providedBuffer.length)
+        return null;
+    if (!(0, node_crypto_1.timingSafeEqual)(expectedBuffer, providedBuffer))
+        return null;
+    return scope;
+}
+/** Pull the bearer token out of an `Authorization` header value, or `null`. */
+function extractBearerToken(authorizationHeader) {
+    if (!authorizationHeader)
+        return null;
+    const match = authorizationHeader.match(/^Bearer\s+(.+)$/i);
+    return match ? match[1].trim() : null;
+}
+/**
+ * @description Hash what a client caches when it connects — the server
+ * instructions and the tool definitions it would list — into a stable id of
+ * "what this bot build offers a session of one platform". Lifecycle plan L4:
+ * persisted when a json-stream process starts and compared when the process is
+ * adopted after a bot restart, since the stateless server cannot tell a running
+ * client that any of it changed.
+ */
+function buildBotMcpToolDigest(instructions, definitions) {
+    const canonical = [...definitions]
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map(({ name, title, description, inputKeys }) => ({ name, title: title ?? '', description: description ?? '', inputKeys }));
+    return (0, node_crypto_1.createHash)('sha256').update(JSON.stringify({ instructions, tools: canonical })).digest('hex');
+}
+/** A scope of no conversation: only the digest registers against it, and the digest never runs a handler. */
+const digestScope = { kind: 'dir', directory: '' };
+/**
+ * @description The digest of the tools a session of `platform` gets — built by
+ * the SAME registration the request path runs, recorded instead of served, so
+ * a tool added, renamed, re-described or re-shaped changes it and nothing else
+ * has to be kept in step by hand.
+ */
+function getBotMcpToolDigest(deps, platform) {
+    const definitions = [];
+    const recorder = {
+        registerTool: (name, config) => {
+            definitions.push({ name, title: config.title, description: config.description, inputKeys: Object.keys(config.inputSchema ?? {}).sort() });
+        },
+    };
+    registerBotTools(recorder, deps, digestScope, platform, undefined);
+    return buildBotMcpToolDigest(buildMcpServerInstructions(platform, deps.fetchJiraAttachment !== undefined), definitions);
+}
+/**
+ * @description Resolve the single thread a tool call targets, from its scope and
+ * an optional caller-supplied `threadKey`:
+ *  - `thread` scope → that exact thread; a supplied `threadKey` must match it.
+ *  - `dir` scope → the threads bound to the directory: exactly 1 → implicit;
+ *    >1 → `threadKey` REQUIRED and must be one of them; 0 → error.
+ * Pure given the injected `getThreadsForDirectory`.
+ */
+function resolveTargetThreadKey(scope, suppliedThreadKey, getThreadsForDirectory) {
+    if (scope.kind === 'thread') {
+        if (suppliedThreadKey && suppliedThreadKey !== scope.threadKey) {
+            return {
+                ok: false,
+                error: `threadKey "${suppliedThreadKey}" does not match this session's thread (${scope.threadKey})`,
+            };
+        }
+        return { ok: true, threadKey: scope.threadKey };
+    }
+    const bound = getThreadsForDirectory(scope.directory);
+    if (bound.length === 0) {
+        return { ok: false, error: `no thread is bound to directory "${scope.directory}"` };
+    }
+    if (bound.length === 1) {
+        if (suppliedThreadKey && suppliedThreadKey !== bound[0]) {
+            return {
+                ok: false,
+                error: `threadKey "${suppliedThreadKey}" is not bound to directory "${scope.directory}"`,
+            };
+        }
+        return { ok: true, threadKey: bound[0] };
+    }
+    // >1 bound thread → an explicit, valid threadKey is mandatory.
+    if (!suppliedThreadKey) {
+        return {
+            ok: false,
+            error: `directory "${scope.directory}" has ${bound.length} bound threads; ` +
+                `pass threadKey (one of: ${bound.join(', ')})`,
+        };
+    }
+    if (!bound.includes(suppliedThreadKey)) {
+        return {
+            ok: false,
+            error: `threadKey "${suppliedThreadKey}" is not bound to directory "${scope.directory}"`,
+        };
+    }
+    return { ok: true, threadKey: suppliedThreadKey };
+}
+// ─── tool input schemas + spec building ──────────────────────────────
+const scheduleCreateShape = {
+    name: zod_1.z.string().min(1).max(maxNameLength).describe('Short human name for the job (shown in announcements/lists).'),
+    cron: zod_1.z
+        .string()
+        .optional()
+        .describe('5-field host-local cron expression for a RECURRING job (e.g. "0 9 * * 1-5"). ' +
+        'For a single future run use onceAt instead, NOT a cron (a cron has no year and would ' +
+        'fire on the same date every year). Omit onceAt when you pass cron.'),
+    onceAt: zod_1.z
+        .string()
+        .optional()
+        .describe('ISO 8601 instant for a ONE-SHOT run (e.g. "2026-06-07T09:00:00"). This is the right field for ' +
+        '"run it once at <time>". Omit cron AND repeatCount when you pass onceAt — a one-shot always runs ' +
+        'exactly once.'),
+    repeatCount: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Number of CRON fires before the job auto-deletes (N-times recurring). ONLY for cron jobs. ' +
+        'Do NOT set it for a one-shot (onceAt) — a one-shot already runs exactly once, so repeatCount ' +
+        'is ignored there.'),
+    prompt: zod_1.z
+        .string()
+        .min(1)
+        .max(maxPromptLength)
+        .describe('The prompt forwarded to the agent at fire time (for a check: only when the check fails, after ' +
+        'the failure details). Make it SELF-CONTAINED — the future run starts ' +
+        'with no memory of this conversation. Bake in everything it needs: the plan file path + scope, ' +
+        'whether to delegate to a sub-agent, and any constraints. Put the WORK in the prompt; do the ' +
+        'investigation later, when it fires.'),
+    checkCommand: zod_1.z
+        .string()
+        .max(checkRun_1.maxCheckCommandLength)
+        .optional()
+        .describe('Makes the job a WATCHDOG CHECK: a shell command (run with /bin/sh -c in the bound folder) the bot ' +
+        'executes at every fire instead of waking you. Exit 0 = healthy, nothing is posted. The first ' +
+        'non-zero exit or timeout pins an alert in the topic and wakes you with `prompt` plus the exit ' +
+        'code and output tail; later failures stay silent until a run passes again (the topic is told). ' +
+        'Keep it a quick probe, e.g. `systemctl --user is-active myapp`, `curl -fsS -m 10 http://127.0.0.1:8080/health`, ' +
+        '`test $(df --output=pcent / | tail -1 | tr -dc 0-9) -lt 90`.'),
+    checkTimeoutSeconds: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(checkRun_1.maxCheckTimeoutSec)
+        .optional()
+        .describe(`Seconds a check run may take before it is stopped and counted as a failure (default ${checkRun_1.defaultCheckTimeoutSec}). ` +
+        'Only with checkCommand.'),
+    isPinSilent: zod_1.z
+        .boolean()
+        .optional()
+        .describe('Pin the fire announcement silently (no member notification). Default false = notify all.'),
+    threadKey: zod_1.z
+        .string()
+        .optional()
+        .describe('Target thread "<chatId>:<threadId>". Required when a directory scope has more than one bound thread.'),
+};
+const scheduleListShape = {
+    threadKey: zod_1.z
+        .string()
+        .optional()
+        .describe('Target thread "<chatId>:<threadId>". Required when a directory scope has more than one bound thread.'),
+};
+const scheduleCancelShape = {
+    id: zod_1.z.string().min(1).describe('The schedule id to cancel (from schedule_list).'),
+    threadKey: zod_1.z
+        .string()
+        .optional()
+        .describe('Target thread "<chatId>:<threadId>". Required when a directory scope has more than one bound thread.'),
+};
+/**
+ * Coerces an ARRAY tool argument into an actual array before validation. Some
+ * MCP bridges (observed: Claude-agent harnesses AND OpenCode) serialize an array
+ * argument as a raw JSON STRING (`'["a","b"]'`, or a mixed
+ * `'[{"path":"p"},"txt"]'`) instead of a JSON array, which a plain `z.array()`
+ * rejects. Accept: a real array (pass-through), a JSON-array string (parsed —
+ * per-element validation still runs on the union afterward), or a single plain
+ * string (wrapped into a one-element array). Shared by `paths` and `messages`.
+ */
+const coerceJsonArrayArg = (value) => {
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    if (trimmed.startsWith('[')) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return value;
+        }
+    }
+    return [value];
+};
+const sendFileShape = {
+    paths: zod_1.z.preprocess(coerceJsonArrayArg, zod_1.z
+        .array(zod_1.z.string().min(1))
+        .min(1)
+        .max(10))
+        .describe('Files to send, as 1..10 paths RELATIVE to this topic\'s bound folder (absolute paths are accepted ' +
+        'only if they resolve inside it). A path outside the folder is rejected and nothing is sent. ' +
+        '2..10 paths are delivered as ONE album.'),
+    caption: zod_1.z
+        .string()
+        .optional()
+        .describe('Optional caption (Telegram caps it at 1024 chars; longer is trimmed). For an album it rides the first file.'),
+    as_file: zod_1.z
+        .boolean()
+        .optional()
+        .describe('Explicitly force sendDocument (original quality, no inline preview), including for MP4s that use sendVideo by default.'),
+    threadKey: zod_1.z
+        .string()
+        .optional()
+        .describe('Target thread "<chatId>:<threadId>". Required when a directory scope has more than one bound thread.'),
+};
+/**
+ * One batch item: EITHER a plain non-empty string (text-only message,
+ * backward-compatible with the original string-array tool) OR an object that may
+ * carry a text body, an attachment `path`, or both. The `.refine` rejects an
+ * all-empty object so a stray `{}` never posts nothing.
+ */
+const sendMessageItemObjectSchema = zod_1.z
+    .object({
+    text: zod_1.z
+        .string()
+        .optional()
+        .describe('Message body. On an ATTACHMENT item (path set) it is the media caption, trimmed to 1024 chars — put long ' +
+        'prose in its OWN text-only item instead of an attachment caption.'),
+    path: zod_1.z
+        .string()
+        .optional()
+        .describe("Optional attachment, RELATIVE to this topic's bound folder (an absolute path is accepted only if it " +
+        'resolves inside it; a path outside is rejected). Supported photos and MP4 videos are sent as native ' +
+        'media, GIFs as animations, and everything else as a document.'),
+    as_file: zod_1.z
+        .boolean()
+        .optional()
+        .describe('Force sendDocument for THIS attachment (original quality, no inline preview), including for MP4s.'),
+})
+    .refine((item) => (item.text?.trim().length ?? 0) > 0 || (item.path?.trim().length ?? 0) > 0, { message: 'each message object must set a non-empty text or path' });
+const sendMessageShape = {
+    messages: zod_1.z
+        .preprocess(coerceJsonArrayArg, zod_1.z
+        .array(zod_1.z.union([zod_1.z.string().min(1), sendMessageItemObjectSchema]))
+        .min(1)
+        .max(messageSendService_1.maxDiscreteMessages))
+        .describe(`1..${messageSendService_1.maxDiscreteMessages} items; EACH item is posted as its OWN separate Telegram message, in order (never ` +
+        'merged). An item is EITHER a plain string (a text message) OR an object {text?, path?, as_file?}. When ' +
+        'path is set the item is delivered as an ATTACHMENT: supported photos render inline, .gif uses ' +
+        'sendAnimation, and .mp4 uses sendVideo (other video containers like .mov/.webm render as a GIF, so remux ' +
+        'to .mp4 first); everything else is a document, and text becomes the media caption (trimmed to 1024 chars ' +
+        '— send long prose as its OWN ' +
+        "text-only item). path is RELATIVE to this topic's bound folder; as_file forces the document override. " +
+        'Use this when you deliberately want several distinct messages (e.g. a per-item news digest: one message ' +
+        'per headline). Do NOT also print the same content as your normal reply, or it posts twice. Text supports ' +
+        'the usual markdown (links, bold); an over-long text item is split automatically.'),
+    threadKey: zod_1.z
+        .string()
+        .optional()
+        .describe('Target thread "<chatId>:<threadId>". Required when a directory scope has more than one bound thread.'),
+};
+/**
+ * The three valid call shapes, appended to structural errors so a bad first call
+ * teaches the corrected next call (the model spirals when an error says only what
+ * is wrong, not what shape to use instead — observed in the live transcript).
+ */
+const scheduleRecipes = 'Recipes — one-shot: pass onceAt (ISO), omit cron and repeatCount. ' +
+    'Recurring: pass cron, omit onceAt. ' +
+    'Recurring N times: pass cron and repeatCount, omit onceAt.';
+/**
+ * @description Collapse an optional free-text field to `undefined` when it is
+ * absent OR blank (empty / whitespace-only). MCP bridges can render an omitted
+ * optional as an empty string (`cron=""` on a one-shot, `onceAt=""` on a cron),
+ * and an empty string must NOT count as a supplied value for the exactly-one-of
+ * check. Trimming also tolerates accidental surrounding whitespace.
+ */
+function normalizeOptionalArg(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * @description Validate the create args and build a {@link ScheduleSpec}: exactly
+ * one of `cron`/`onceAt` (empty/whitespace fields normalised away first); then run
+ * the shared {@link validateScheduleSpec} (cron parse + min-interval + past-one-shot).
+ * `nowMs` is injected so the past-one-shot check is deterministic.
+ *
+ * A `repeatCount` supplied alongside `onceAt` is IGNORED (not rejected): a one-shot
+ * is by definition a single run, so the count is meaningless there. The model
+ * naturally reaches for `repeatCount: 1` to express "run once" and, when that was
+ * a hard error, spiralled into absurd counts / a wrong-year cron workaround
+ * (live transcript). Accepting the natural call removes that failure mode; the
+ * returned `note` teaches the agent the field was redundant.
+ */
+function buildSpecFromCreateArgs(args, nowMs) {
+    const cron = normalizeOptionalArg(args.cron);
+    const onceAt = normalizeOptionalArg(args.onceAt);
+    const { repeatCount } = args;
+    if (cron && onceAt) {
+        return { ok: false, error: `Pass either cron OR onceAt, not both. ${scheduleRecipes}` };
+    }
+    if (!cron && !onceAt) {
+        return { ok: false, error: `Pass exactly one of cron or onceAt. ${scheduleRecipes}` };
+    }
+    let note;
+    if (onceAt && repeatCount !== undefined) {
+        note = 'repeatCount was ignored — a one-shot (onceAt) always runs exactly once.';
+    }
+    const spec = cron
+        ? { kind: 'cron', cronExpr: cron, ...(repeatCount !== undefined ? { remainingRuns: repeatCount } : {}) }
+        : { kind: 'once', onceAtIso: onceAt };
+    const validationError = (0, recurrence_1.validateScheduleSpec)(spec, nowMs);
+    if (validationError)
+        return { ok: false, error: validationError };
+    return { ok: true, spec, note };
+}
+// ─── tool result helpers ─────────────────────────────────────────────
+/** Wrap text as a successful MCP tool result (plain text content block). */
+function textResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+/** Wrap a readable message as an MCP tool ERROR result the agent relays to the user. */
+function errorResult(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+/** Report an ambiguous delivery without inviting MCP clients to retry it. */
+function deliveryUnknownResult(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        structuredContent: { kind: 'deliveryUnknown', retryable: false },
+    };
+}
+/** One-line human summary of a record for `schedule_list` / create confirmations. */
+function summarizeRecord(record) {
+    // Local-offset ISO, never `toISOString()`'s UTC `Z`: the operator declared a
+    // timezone and the agent reads this back to them, so a next-run stamp in some
+    // other zone than the one the job actually fires in is actively misleading.
+    const next = record.nextRunAt !== null ? (0, isoTimestamp_1.formatIsoLocalOffset)(record.nextRunAt) : 'none';
+    const pausedNote = record.isPaused ? ' [paused]' : '';
+    const checkNote = (0, deliveryKind_1.checkIsCheckSchedule)(record)
+        ? `; check: \`${record.checkCommand ?? ''}\` (${record.isCheckFailing ? 'FAILING' : 'passing'})`
+        : '';
+    return `${record.name} (id: ${record.id}) — ${(0, recurrence_1.describeSchedule)(record.spec)}${checkNote}; next run: ${next}${pausedNote}`;
+}
+// ─── tool handlers (scope-bound) ─────────────────────────────────────
+/**
+ * @description Register the three scoped tools onto a fresh {@link McpServer}.
+ * Every handler resolves the target thread from `scope` first (scope isolation),
+ * then operates only on that thread's jobs. Bound to `deps` + the request's
+ * verified `scope`.
+ */
+function registerSchedulerTools(server, deps, scope) {
+    server.registerTool('schedule_create', {
+        title: 'Create a scheduled prompt',
+        description: 'Schedule a prompt to be delivered to this topic later. The bot announces, pins, and ' +
+            'forwards the prompt to the agent at fire time.\n\n' +
+            'Pick exactly ONE mode:\n' +
+            '• one-shot (run once at a time): pass onceAt (ISO 8601); omit cron and repeatCount.\n' +
+            '• recurring: pass cron (5-field); omit onceAt.\n' +
+            '• recurring N times: pass cron AND repeatCount; omit onceAt.\n' +
+            'For a single future run ALWAYS use onceAt — never a cron with repeatCount:1 ' +
+            '(a cron has no year, so it would fire on that date every year). repeatCount counts CRON ' +
+            'fires only and is ignored for a one-shot.\n\n' +
+            'USE THIS whenever the user asks to schedule execution of a plan or task for later ' +
+            "(e.g. \"schedule finishing plan X in 2h\", \"run this plan tomorrow morning\"). " +
+            'Schedule IMMEDIATELY: write the request straight into `prompt` and create the job FIRST — ' +
+            'do NOT read code, explore the repo, or deliberate before scheduling. Plan now, figure out the ' +
+            'details at fire time. The future run does the investigation, not this call.\n\n' +
+            'WATCHDOG: to monitor something (a service, process, build, deploy, disk, URL), pass checkCommand ' +
+            'with a cron — the bot runs it in this folder and wakes you only when it starts failing. This is ' +
+            'the ONLY reliable watcher: it survives bot restarts and crashes. Never build your own (a ' +
+            'background loop, nohup, a sleep loop, a tmux pane, a shell crontab) — it dies with your session ' +
+            'or a restart and then fails silently.',
+        inputSchema: scheduleCreateShape,
+    }, async (args) => {
+        const resolved = resolveTargetThreadKey(scope, args.threadKey, deps.getThreadsForDirectory);
+        if (!resolved.ok)
+            return errorResult(resolved.error);
+        const nowMs = Date.now();
+        const built = buildSpecFromCreateArgs(args, nowMs);
+        if (!built.ok)
+            return errorResult(built.error);
+        let threadKey;
+        try {
+            threadKey = (0, sessionKey_1.keyFromString)(resolved.threadKey);
+        }
+        catch {
+            return errorResult(`invalid threadKey "${resolved.threadKey}"`);
+        }
+        const checkCommand = normalizeOptionalArg(args.checkCommand);
+        const notes = built.note ? [built.note] : [];
+        if (!checkCommand && args.checkTimeoutSeconds !== undefined) {
+            notes.push('checkTimeoutSeconds was ignored — it only applies with checkCommand.');
+        }
+        const created = await (0, store_1.createScheduleForThread)(deps.store, {
+            threadKey,
+            name: args.name,
+            spec: built.spec,
+            prompt: args.prompt,
+            createdBy: 'agent',
+            nowMs,
+            lastAdapterName: deps.getThreadAdapterName(resolved.threadKey),
+            isPinSilent: args.isPinSilent,
+            ...(checkCommand
+                ? { deliveryKind: 'check', checkCommand, checkTimeoutSec: args.checkTimeoutSeconds }
+                : {}),
+        });
+        if (!created.ok) {
+            // The cap counts only the agent-prompt jobs `schedule_list` shows, so the
+            // plain sentence is the whole truth: every slot it names is one this agent
+            // can see and cancel itself.
+            return errorResult(`cannot create: thread already has the maximum of ${created.limit} schedules`);
+        }
+        const record = created.record;
+        deps.armJob(record);
+        const noteSuffix = notes.map((note) => `\n\nℹ️ ${note}`).join('');
+        return textResult(`Scheduled "${record.name}".\n${summarizeRecord(record)}${noteSuffix}`);
+    });
+    server.registerTool('schedule_list', {
+        title: 'List scheduled prompts',
+        description: 'List the scheduled prompts for this topic (id, name, schedule, next run, paused flag).',
+        inputSchema: scheduleListShape,
+    }, async (args) => {
+        const resolved = resolveTargetThreadKey(scope, args.threadKey, deps.getThreadsForDirectory);
+        if (!resolved.ok)
+            return errorResult(resolved.error);
+        let threadKey;
+        try {
+            threadKey = (0, sessionKey_1.keyFromString)(resolved.threadKey);
+        }
+        catch {
+            return errorResult(`invalid threadKey "${resolved.threadKey}"`);
+        }
+        // Reminders are invisible to the agent BY DESIGN: a `/reminders` job is
+        // bot-local (posted + pinned, no session touched), so listing one here
+        // would describe it to the agent as a "scheduled prompt" it could act on —
+        // and `schedule_cancel` below would let it delete something the operator
+        // created with buttons and never handed to any agent.
+        const records = deps.store
+            .getThreadSchedules(threadKey)
+            .filter((record) => !(0, deliveryKind_1.checkIsReminderSchedule)(record));
+        if (records.length === 0) {
+            return textResult('No schedules for this topic.');
+        }
+        const lines = records.map((record, index) => `${index + 1}. ${summarizeRecord(record)}`);
+        return textResult(lines.join('\n'));
+    });
+    server.registerTool('schedule_cancel', {
+        title: 'Cancel a scheduled prompt',
+        description: 'Cancel (delete) a scheduled prompt by its id. Only schedules owned by this topic can be cancelled.',
+        inputSchema: scheduleCancelShape,
+    }, async (args) => {
+        const resolved = resolveTargetThreadKey(scope, args.threadKey, deps.getThreadsForDirectory);
+        if (!resolved.ok)
+            return errorResult(resolved.error);
+        const record = deps.store.getSchedules()[args.id];
+        // Scope isolation: the record must exist AND belong to the resolved thread.
+        // A reminder answers the SAME "not found" as a missing id rather than a new
+        // error kind: `schedule_list` never showed it, so from the agent's side it
+        // genuinely does not exist, and a distinct refusal would only tell it there
+        // is an id here worth retrying.
+        if (!record || record.threadKey !== resolved.threadKey || (0, deliveryKind_1.checkIsReminderSchedule)(record)) {
+            return errorResult(`no schedule with id "${args.id}" in this topic`);
+        }
+        await deps.store.removeSchedule(args.id);
+        deps.disarmJob(args.id);
+        return textResult(`Cancelled "${record.name}" (id: ${record.id}).`);
+    });
+}
+/**
+ * @description Register the agent→Telegram `send_file_to_user` tool onto a fresh
+ * {@link McpServer}. Kept separate from {@link registerSchedulerTools} so the
+ * scheduler tools stay cohesive. Like every tool here it resolves the target
+ * thread from `scope` first (scope isolation — the agent can never name another
+ * topic); the actual path-safety + Telegraf send live in `deps.sendFilesToThread`.
+ */
+function registerFileSendTool(server, deps, scope, requestSignal) {
+    server.registerTool('send_file_to_user', {
+        title: 'Send a file or image to this topic',
+        description: 'Send one or more files/images from THIS topic\'s bound folder back to the user in the topic. ' +
+            'Use it to deliver a generated chart, screenshot, report, etc. Paths are relative to the bound ' +
+            'folder; a path outside it is rejected and nothing is sent. Images (.png/.jpg/.jpeg/.webp) preview ' +
+            'inline, .gif autoplays, and a single .mp4 uses sendVideo by default. as_file:true is the explicit sendDocument ' +
+            'override for previewable media; no fake audio track is needed for a silent MP4. Everything else arrives ' +
+            'as a document. VIDEO RULE: to deliver a playable video, pass a .mp4 path and do NOT set as_file — any other ' +
+            'container (.mov/.webm/.mkv) or a document fallback makes Telegram render it as a GIF instead; remux to .mp4 first ' +
+            '(e.g. `ffmpeg -i in.webm -c:v libx264 -pix_fmt yuv420p -movflags +faststart out.mp4`; if no full ffmpeg is ' +
+            'installed, `npm i ffmpeg-static` provides one — Playwright\'s bundled ffmpeg has no H.264 encoder). ' +
+            '2..10 paths use sendMediaGroup: eligible photos and MP4 videos stay native in ' +
+            'all-video and mixed photo/video groups; as_file:true, any animation/document, or an over-cap photo makes ' +
+            'the whole album documents — which turns its MP4s into GIFs, so send videos in their own call. ' +
+            'Secure outbound traversal currently requires Linux; other platforms fail closed. ' +
+            'Caption is optional (trimmed to 1024 chars; on the first album item).',
+        inputSchema: sendFileShape,
+    }, async (args, extra) => {
+        const signal = requestSignal
+            ? AbortSignal.any([extra.signal, requestSignal])
+            : extra.signal;
+        const resolved = resolveTargetThreadKey(scope, args.threadKey, deps.getThreadsForDirectory);
+        if (!resolved.ok)
+            return errorResult(resolved.error);
+        if (signal.aborted)
+            throw (0, utils_1.getAbortError)(signal);
+        const result = await deps.sendFilesToThread(resolved.threadKey, {
+            paths: args.paths,
+            caption: args.caption,
+            asFile: args.as_file,
+            ...(scope.kind === 'dir' ? { authorizedWorkDir: scope.directory } : {}),
+            signal,
+        });
+        if (result.ok)
+            return textResult(result.summary);
+        return 'kind' in result && result.kind === 'deliveryUnknown'
+            ? deliveryUnknownResult(result.error)
+            : errorResult(result.error);
+    });
+}
+/**
+ * @description Register the agent→Telegram `send_messages_to_user` tool onto a
+ * fresh {@link McpServer}. The discrete-message sibling of `send_file_to_user`:
+ * each array element is delivered as its OWN Telegram message (never merged),
+ * for a per-item digest and similar. Like every tool here it resolves the target
+ * thread from `scope` first (scope isolation); the paced send lives in
+ * `deps.sendMessagesToThread`.
+ */
+function registerMessageSendTool(server, deps, scope, requestSignal) {
+    server.registerTool('send_messages_to_user', {
+        title: 'Send several separate messages to this topic',
+        description: 'Deliver a batch of DISCRETE messages into THIS topic — each item of `messages` is posted as its own ' +
+            'separate Telegram message, in order (never merged). Use it when you deliberately want several messages ' +
+            'instead of one, e.g. a per-item news digest (header, a date separator, then one message per headline). ' +
+            'An item is EITHER a plain string (text message) OR an object {text?, path?, as_file?} — set `path` to ' +
+            "attach ONE file (RELATIVE to this topic's bound folder): supported photos render inline, .gif uses " +
+            'sendAnimation, and .mp4 uses sendVideo (.mov/.webm render as a GIF, so remux to .mp4 first); everything ' +
+            'else is a document, and `text` ' +
+            'becomes the media caption (trimmed to 1024 chars — send long prose as its OWN text-only item). ' +
+            '`as_file:true` forces the document override for that attachment. Markdown (links, bold) works on text ' +
+            'items; an over-long text item is split automatically. Note: this does NOT replace your normal single ' +
+            'reply — only reach for it when multiple discrete messages are wanted, and do not also print the same ' +
+            'content as your reply text (that would post it twice).',
+        inputSchema: sendMessageShape,
+    }, async (args, extra) => {
+        const signal = requestSignal
+            ? AbortSignal.any([extra.signal, requestSignal])
+            : extra.signal;
+        const resolved = resolveTargetThreadKey(scope, args.threadKey, deps.getThreadsForDirectory);
+        if (!resolved.ok)
+            return errorResult(resolved.error);
+        if (signal.aborted)
+            throw (0, utils_1.getAbortError)(signal);
+        // Map the wire shape (snake-case `as_file`) to the service's item type.
+        const items = args.messages.map((item) => typeof item === 'string'
+            ? item
+            : {
+                ...(item.text !== undefined ? { text: item.text } : {}),
+                ...(item.path !== undefined ? { path: item.path } : {}),
+                ...(item.as_file !== undefined ? { asFile: item.as_file } : {}),
+            });
+        const result = await deps.sendMessagesToThread(resolved.threadKey, {
+            messages: items,
+            ...(scope.kind === 'dir' ? { authorizedWorkDir: scope.directory } : {}),
+            signal,
+        });
+        if (result.ok)
+            return textResult(result.summary);
+        return 'kind' in result && result.kind === 'deliveryUnknown'
+            ? deliveryUnknownResult(result.error)
+            : errorResult(result.error);
+    });
+}
+/**
+ * @description Register the agent→bot `compact_conversation` tool (F1). Like
+ * every tool here it resolves the target thread from `scope` first (scope
+ * isolation — the agent can only compact ITS OWN topic's session). The actual
+ * arm + deferred compaction lives in `deps.compactConversation`; this surface
+ * only routes the resolved thread and relays the status text.
+ */
+function registerCompactConversationTool(server, deps, scope) {
+    server.registerTool('compact_conversation', {
+        title: 'Compact this conversation',
+        description: 'Compact (summarize) THIS topic\'s own session context so the conversation can continue in a ' +
+            'smaller window. Call this ONLY when the user EXPLICITLY asks to compact / shrink / summarize the ' +
+            'context (e.g. "compact our conversation", "сожми контекст") — never on your own judgement, and ' +
+            'never to "clean up". It does NOT compact mid-turn: it arms compaction and returns immediately; the ' +
+            'bot runs the real compaction the moment this turn finishes. There is nothing for you to do ' +
+            'afterwards — do not call it again for the same request.',
+        inputSchema: {
+            reason: zod_1.z
+                .string()
+                .optional()
+                .describe('Optional short note on why the user asked to compact (for the bot log only).'),
+        },
+    }, async (args) => {
+        // A surviving session may call this before boot re-attached it.
+        await deps.whenSessionsRestored();
+        const resolved = resolveTargetThreadKey(scope, undefined, deps.getThreadsForDirectory);
+        if (!resolved.ok)
+            return errorResult(resolved.error);
+        if (args.reason)
+            console.log(`[compact_conversation] ${resolved.threadKey}: ${args.reason}`);
+        const outcome = deps.compactConversation(resolved.threadKey);
+        return outcome.ok ? textResult(outcome.message) : errorResult(outcome.message);
+    });
+}
+/**
+ * `jira_get_attachment`: the issue is the conversation this session's token names — never an argument —
+ * so a file of any other issue cannot be asked for, however the id got into the agent's head.
+ */
+function registerJiraAttachmentTool(server, deps, fetchJiraAttachment, scope) {
+    server.registerTool('jira_get_attachment', {
+        title: 'Get a Jira attachment',
+        description: 'Download the ORIGINAL of one attachment of THIS issue and get the local path it was saved at. The ' +
+            'attachment ids are in the issue\'s attachments list and in placeholders like ' +
+            '"[image: shot.png — attachment 10234]". There is no size limit. What you do with the file is up to ' +
+            'you: view an image with your file-reading tool, take frames or the audio of a video with ffmpeg ' +
+            '(when it is on your PATH). Only this issue\'s own attachments can be fetched.',
+        inputSchema: {
+            attachmentId: zod_1.z.string().min(1).describe('The attachment id, e.g. "10234" from "[image: shot.png — attachment 10234]".'),
+        },
+    }, async (args) => {
+        await deps.whenSessionsRestored();
+        const resolved = resolveTargetThreadKey(scope, undefined, deps.getThreadsForDirectory);
+        if (!resolved.ok)
+            return errorResult(resolved.error);
+        const outcome = await fetchJiraAttachment(resolved.threadKey, args.attachmentId);
+        return outcome.ok ? textResult(outcome.message) : errorResult(outcome.error);
+    });
+}
+/**
+ * @description Whether a token's scope covers a conversation (serialized key): a
+ * `thread:` token covers exactly its thread, a `dir:` token every thread bound to
+ * its directory. Unlike {@link resolveTargetThreadKey} it never picks a target —
+ * the request id already names the conversation, this only checks the caller may
+ * act on it.
+ */
+function checkIsConversationInScope(scope, conversationKey, getThreadsForDirectory) {
+    if (scope.kind === 'thread')
+        return scope.threadKey === conversationKey;
+    return getThreadsForDirectory(scope.directory).includes(conversationKey);
+}
+const answerRequestShape = {
+    requestId: zod_1.z
+        .string()
+        .trim()
+        .min(1)
+        .describe('The id from the "[Request <id> · from: …]" header of the message you are answering.'),
+    kind: zod_1.z
+        .enum(['progress', 'question', 'final'])
+        .describe('"final" — the full result, at the end of your turn (closes the request); "question" — you need the ' +
+        'requester before you can go on (closes the request; their reply is a new request); "progress" — an ' +
+        'interim note (the request stays open).'),
+    body: zod_1.z
+        .string()
+        .trim()
+        .min(1)
+        .max(answerRequest_1.answerBodyMaxLength)
+        .describe('The answer itself, in Markdown. Write it for the requester: they do not see your other output.'),
+};
+/**
+ * @description Register `answer_request` (request/answer core S3): the agent's
+ * answer to a request, delivered to the surface the request came from. The
+ * scope check is passed in so a session can only answer requests of the
+ * conversations its token covers; an id outside it reads as unknown.
+ */
+function registerAnswerRequestTool(server, deps, scope) {
+    server.registerTool('answer_request', {
+        title: 'Answer a request',
+        description: 'Send your answer to a request — a message that carries a "[Request <id> · from: …]" header — to ' +
+            'the person who made it, on the surface it came from. The requester may not see your plain text, so ' +
+            'anything they must read goes through this tool. Call it with kind "final" and the full result at the ' +
+            'end of your turn; "question" when you need them before you can continue; "progress" for an interim ' +
+            'note. You may call it several times for one request; only "question" and "final" close it. Do not ' +
+            'restate the answer in plain text afterwards: where your plain text is relayed as well, a recap shows twice.',
+        inputSchema: answerRequestShape,
+    }, async (args) => {
+        const outcome = await deps.answerRequest({
+            requestId: args.requestId,
+            kind: args.kind,
+            body: args.body,
+            checkIsConversationInScope: (conversationKey) => checkIsConversationInScope(scope, conversationKey, deps.getThreadsForDirectory),
+        });
+        return outcome.ok ? textResult(outcome.message) : errorResult(outcome.error);
+    });
+}
+/**
+ * @description Correlate stateless MCP requests with cancellation notifications.
+ * Active controllers are isolated by verified token + validated client identity
+ * + typed JSON-RPC id. One bounded TTL cache stores mutually-exclusive terminal
+ * states for inactive keys:
+ *
+ * - `pendingCancellation` aborts the first matching registration, then is consumed.
+ * - `recentlyCompleted` ignores only an unmatched late cancellation while no
+ *   matching request is active, preventing it from becoming pending poison.
+ *
+ * Active controllers always take precedence over tombstones because generations
+ * that reuse one client identity and request id are otherwise indistinguishable.
+ *
+ * The clock and cache limit are injectable only at construction so expiry and
+ * oldest-entry eviction stay deterministic in tests; production uses the fixed
+ * exported defaults.
+ */
+function createSchedulerMcpCancellationLifecycle(options = {}) {
+    const getNowMs = options.getNowMs ?? Date.now;
+    const maxTombstones = options.maxTombstones ?? exports.schedulerMcpPendingCancellationMax;
+    if (!Number.isSafeInteger(maxTombstones) || maxTombstones <= 0) {
+        throw new RangeError('maxTombstones must be a positive safe integer');
+    }
+    const requestAbortControllers = new Map();
+    const tombstones = new Map();
+    function getRequestCorrelationKey(clientIdentity, requestId) {
+        return JSON.stringify([clientIdentity, typeof requestId, requestId]);
+    }
+    function pruneTombstones(now) {
+        for (const [correlationKey, tombstone] of tombstones) {
+            if (tombstone.expiresAt <= now)
+                tombstones.delete(correlationKey);
+        }
+    }
+    function setTombstone(correlationKey, tombstone, now) {
+        pruneTombstones(now);
+        tombstones.delete(correlationKey);
+        while (tombstones.size >= maxTombstones) {
+            const oldestKey = tombstones.keys().next().value;
+            if (oldestKey === undefined)
+                break;
+            tombstones.delete(oldestKey);
+        }
+        tombstones.set(correlationKey, tombstone);
+    }
+    function registerRequest(clientIdentity, requestId) {
+        const correlationKey = getRequestCorrelationKey(clientIdentity, requestId);
+        const controller = new AbortController();
+        const controllers = requestAbortControllers.get(correlationKey) ?? new Set();
+        controllers.add(controller);
+        requestAbortControllers.set(correlationKey, controllers);
+        const now = getNowMs();
+        pruneTombstones(now);
+        const tombstone = tombstones.get(correlationKey);
+        if (tombstone?.kind === 'pendingCancellation') {
+            tombstones.delete(correlationKey);
+            controller.abort(tombstone.reason);
+        }
+        let isTerminal = false;
+        return {
+            controller,
+            markTerminal: () => {
+                if (isTerminal)
+                    return;
+                isTerminal = true;
+                const completedAt = getNowMs();
+                setTombstone(correlationKey, {
+                    kind: 'recentlyCompleted',
+                    expiresAt: completedAt + exports.schedulerMcpPendingCancellationTtlMs,
+                }, completedAt);
+            },
+            unregister: () => {
+                controllers.delete(controller);
+                if (controllers.size === 0)
+                    requestAbortControllers.delete(correlationKey);
+            },
+        };
+    }
+    function cancelRequest(clientIdentity, requestId, reason) {
+        const correlationKey = getRequestCorrelationKey(clientIdentity, requestId);
+        const now = getNowMs();
+        pruneTombstones(now);
+        const controllers = requestAbortControllers.get(correlationKey);
+        if (controllers && controllers.size > 0) {
+            for (const controller of controllers)
+                controller.abort(reason);
+            return;
+        }
+        if (tombstones.get(correlationKey)?.kind === 'recentlyCompleted')
+            return;
+        setTombstone(correlationKey, {
+            kind: 'pendingCancellation',
+            expiresAt: now + exports.schedulerMcpPendingCancellationTtlMs,
+            ...(reason !== undefined ? { reason } : {}),
+        }, now);
+    }
+    return { registerRequest, cancelRequest };
+}
+/**
+ * @description Build a fresh {@link McpServer} for one request, registering the
+ * scope-bound scheduler tools plus the `send_file_to_user` tool. The SDK binds one server
+ * per transport per connection, so a new instance is built (and closed) per
+ * request in the stateless flow.
+ */
+function buildRequestServer(deps, scope, requestSignal) {
+    const platform = getSchedulerScopePlatform(scope);
+    const server = new mcp_js_1.McpServer({ name: mcpServerName, version: mcpServerVersion }, { instructions: buildMcpServerInstructions(platform, deps.fetchJiraAttachment !== undefined) });
+    registerBotTools(server, deps, scope, platform, requestSignal);
+    return server;
+}
+/** The tools a session of `platform` gets — the one list the request path serves and the digest records. */
+function registerBotTools(server, deps, scope, platform, requestSignal) {
+    // These deliver into a Telegram topic; for another platform's key they would throw (D18).
+    if (platform === 'telegram') {
+        registerSchedulerTools(server, deps, scope);
+        registerFileSendTool(server, deps, scope, requestSignal);
+        registerMessageSendTool(server, deps, scope, requestSignal);
+    }
+    // The original files of the conversation's own issue: only a Jira session, and only with the connector loaded.
+    if (platform === 'jira' && deps.fetchJiraAttachment)
+        registerJiraAttachmentTool(server, deps, deps.fetchJiraAttachment, scope);
+    registerCompactConversationTool(server, deps, scope);
+    registerAnswerRequestTool(server, deps, scope);
+    if (deps.listClaudeProfiles)
+        registerClaudeProfilesTool(server, deps.listClaudeProfiles);
+}
+/**
+ * `claude_profiles`: which Claude account a child process should run on. Reads the bot's per-profile usage
+ * cache (refreshed on demand by the port); touches no conversation, so it needs no scope resolution. The
+ * answer is the report as JSON with a one-line verdict first, so an agent can act on it without parsing.
+ */
+function registerClaudeProfilesTool(server, listClaudeProfiles) {
+    server.registerTool('claude_profiles', {
+        title: 'Claude accounts and their usage',
+        description: 'The Claude account profiles signed in on this host, each with its usage windows — session (5 h), weekly ' +
+            '(all models) and weekly Fable — as percent used + reset instant, and `recommended`: the profile with the most ' +
+            'headroom for the model you pass (Fable → its own weekly window + the session window; any other model → the ' +
+            'shared weekly window + the session window; signed-out and limited profiles are skipped). Call it BEFORE ' +
+            'launching a child `claude` and start the child with CLAUDE_CONFIG_DIR=<configDir> in its environment — ' +
+            'configDir null means the default profile: set nothing. Without the variable the child inherits the account ' +
+            'of this very session.',
+        inputSchema: {
+            model: zod_1.z
+                .string()
+                .max(64)
+                .optional()
+                .describe('The model the child will run (e.g. "fable", "opus", "sonnet"); decides which weekly window counts. Omit for the shared windows.'),
+        },
+    }, async (args) => {
+        const report = await listClaudeProfiles(args.model?.trim() || null);
+        const verdict = report.recommended === null
+            ? 'No eligible profile: every signed-in account is limited or at 100 % on a relevant window.'
+            : (() => {
+                const entry = report.profiles.find((profile) => profile.name === report.recommended);
+                const dir = entry?.configDir ?? null;
+                return `recommended: ${report.recommended} → ${dir === null ? 'default profile, set no CLAUDE_CONFIG_DIR' : `CLAUDE_CONFIG_DIR=${dir}`}`;
+            })();
+        return textResult(`${verdict}\n${JSON.stringify(report, null, 1)}`);
+    });
+}
+/** Read the whole request body into a string (the SDK wants the parsed JSON body). */
+function readRequestBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+/** Write a JSON-RPC error response (used for the 401 / not-found paths the SDK doesn't reach). */
+function writeJsonRpcError(res, httpStatus, code, message) {
+    res.writeHead(httpStatus, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ jsonrpc: '2.0', error: { code, message }, id: null }));
+}
+/**
+ * @description Create the bot-owned scheduler MCP server. Returns a handle with
+ * `start`/`stop` and the bound `port`. The HTTP listener is plain `node:http`
+ * (no web framework) on `127.0.0.1`; each request verifies the bearer token,
+ * builds a fresh stateless transport + `McpServer`, and tears them down when the
+ * response finishes. Invalid/missing tokens get a JSON-RPC 401 without touching
+ * any tool.
+ */
+function createSchedulerMcpServer(deps) {
+    const requestedPort = deps.port ?? getSchedulerMcpPort();
+    let boundPort = requestedPort;
+    let httpServer = null;
+    const sockets = new Set();
+    const cancellationLifecycle = createSchedulerMcpCancellationLifecycle();
+    function getClientIdentity(req, verifiedToken) {
+        const clientId = req.headers[exports.schedulerMcpClientIdHeader];
+        if (typeof clientId === 'string' &&
+            clientId.length > 0 &&
+            clientId.length <= schedulerMcpClientIdMaxLength &&
+            schedulerMcpClientIdPattern.test(clientId)) {
+            return `token:${verifiedToken}:client:${clientId}`;
+        }
+        return `token:${verifiedToken}`;
+    }
+    async function handleMcpRequest(req, res) {
+        const secret = await deps.getSecret();
+        const token = extractBearerToken(req.headers.authorization);
+        const scope = token ? verifySchedulerMcpToken(secret, token) : null;
+        if (!scope || token === null) {
+            // -32001 (SDK's "unauthorized" convention) + HTTP 401, no tool touched.
+            writeJsonRpcError(res, 401, -32001, 'Unauthorized: missing or invalid scheduler token');
+            return;
+        }
+        if (req.method === 'GET') {
+            // This server NEVER initiates a message: it is stateless, has no event
+            // store, and every transport is built and closed around ONE request. The
+            // spec's answer for exactly that case is 405, and the SDK client treats it
+            // as expected and simply does not open a stream.
+            //
+            // Answering the SDK's way instead (200 + `text/event-stream`) hands the
+            // client a standalone SSE stream that carries nothing and only ever ends
+            // one way: the bot restarts, the socket dies, and the client burns its
+            // reconnect budget against a port that is not listening yet. Hot mode
+            // rebuilds on every code change, so that is a frequent event — and a
+            // client that gives up latches the whole server `failed`, stranding the
+            // bot's own tools in a session that was deliberately built to survive the
+            // restart. Refusing the GET removes the thing that breaks.
+            res.writeHead(405, { Allow: 'POST', 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                jsonrpc: '2.0',
+                error: { code: -32000, message: 'Method Not Allowed: this endpoint does not offer an SSE stream' },
+                id: null,
+            }));
+            return;
+        }
+        const clientIdentity = getClientIdentity(req, token);
+        const bodyText = await readRequestBody(req);
+        let parsedBody;
+        try {
+            parsedBody = bodyText.length > 0 ? JSON.parse(bodyText) : undefined;
+        }
+        catch {
+            writeJsonRpcError(res, 400, -32700, 'Parse error: request body is not valid JSON');
+            return;
+        }
+        const cancellation = types_js_1.CancelledNotificationSchema.safeParse(parsedBody);
+        if (cancellation.success && cancellation.data.params.requestId !== undefined) {
+            cancellationLifecycle.cancelRequest(clientIdentity, cancellation.data.params.requestId, cancellation.data.params.reason);
+        }
+        const request = types_js_1.JSONRPCRequestSchema.safeParse(parsedBody);
+        const registeredRequest = request.success
+            ? cancellationLifecycle.registerRequest(clientIdentity, request.data.id)
+            : undefined;
+        const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        const server = buildRequestServer(deps, scope, registeredRequest?.controller.signal);
+        // Stateless: the transport + server live only for this request; close both
+        // when the response finishes so no connection state lingers.
+        const markRequestTerminal = () => registeredRequest?.markTerminal();
+        res.once('finish', markRequestTerminal);
+        res.once('close', () => {
+            res.off('finish', markRequestTerminal);
+            registeredRequest?.markTerminal();
+            registeredRequest?.controller.abort();
+            registeredRequest?.unregister();
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, parsedBody);
+    }
+    function start() {
+        return new Promise((resolve, reject) => {
+            const server = (0, node_http_1.createServer)((req, res) => {
+                if (req.url && req.url.split('?')[0] === exports.schedulerMcpPath) {
+                    handleMcpRequest(req, res).catch((error) => {
+                        console.error('[scheduler-mcp] request handling failed:', error);
+                        if (!res.headersSent) {
+                            writeJsonRpcError(res, 500, -32603, 'Internal error');
+                        }
+                        else {
+                            res.end();
+                        }
+                    });
+                    return;
+                }
+                writeJsonRpcError(res, 404, -32601, 'Not found');
+            });
+            server.on('connection', (socket) => {
+                sockets.add(socket);
+                socket.once('close', () => sockets.delete(socket));
+            });
+            const portBindRetry = deps.portBindRetry ?? { count: exports.schedulerMcpBindRetryCount, delayMs: exports.schedulerMcpBindRetryDelayMs };
+            let retryCount = 0;
+            let isFallenBack = false;
+            const handleListening = () => {
+                const address = server.address();
+                if (address && typeof address === 'object')
+                    boundPort = address.port;
+                httpServer = server;
+                server.off('error', handleError);
+                resolve();
+            };
+            const handleError = (error) => {
+                // A non-zero requested port already in use (a persisted port a prior
+                // generation still holds, or a sibling instance) must not wedge boot: it
+                // is retried (`portBindRetry`), then bound on an ephemeral port ONCE.
+                // Port 0 can never hit EADDRINUSE.
+                if (error.code === 'EADDRINUSE' && requestedPort !== 0 && !isFallenBack) {
+                    // Track the server before the retry so a stop() in the retry window
+                    // still closes the eventually-bound listener (no orphan).
+                    httpServer = server;
+                    if (retryCount < portBindRetry.count) {
+                        if (retryCount === 0) {
+                            console.warn(`[scheduler-mcp] requested port ${requestedPort} is in use; retrying for up to ${portBindRetry.count * portBindRetry.delayMs} ms`);
+                        }
+                        retryCount += 1;
+                        setTimeout(() => {
+                            // A stop() during the wait already settled this server: binding now
+                            // would leave a listener nobody closes.
+                            if (httpServer !== server) {
+                                server.off('listening', handleListening);
+                                reject(new Error(`stopped while waiting for port ${requestedPort}`));
+                                return;
+                            }
+                            server.listen(requestedPort, '127.0.0.1');
+                        }, portBindRetry.delayMs);
+                        return;
+                    }
+                    isFallenBack = true;
+                    console.error(`[scheduler-mcp] requested port ${requestedPort} is still in use after ${portBindRetry.count * portBindRetry.delayMs} ms; ` +
+                        `falling back to an ephemeral port. A Claude session that was already running keeps the MCP address of its launch ` +
+                        `(127.0.0.1:${requestedPort}) and loses the bot's tools until it is restarted.`);
+                    server.listen(0, '127.0.0.1');
+                    return;
+                }
+                server.off('listening', handleListening);
+                reject(error);
+            };
+            server.on('listening', handleListening);
+            server.on('error', handleError);
+            server.listen(requestedPort, '127.0.0.1');
+        });
+    }
+    function stop() {
+        return new Promise((resolve) => {
+            if (!httpServer) {
+                resolve();
+                return;
+            }
+            httpServer.close(() => {
+                httpServer = null;
+                resolve();
+            });
+            // Streamable HTTP clients may retain an idle keep-alive connection after
+            // their request completes; server.close() otherwise waits for it forever.
+            for (const socket of sockets)
+                socket.destroy();
+        });
+    }
+    return {
+        start,
+        stop,
+        getToolDigest: (platform) => getBotMcpToolDigest(deps, platform),
+        get port() {
+            return boundPort;
+        },
+    };
+}
+//# sourceMappingURL=mcpSurface.js.map