telecodex 0.1.3 → 0.1.5

package/dist/bot/auth.js

@@ -1,3 +1,4 @@
+import { replyError, replyNotice } from "../telegram/formatted.js";
 export function authMiddleware(input) {
     return async (ctx, next) => {
         const userId = ctx.from?.id;
@@ -10,7 +11,7 @@ export function authMiddleware(input) {
                 hasTextMessage: Boolean(ctx.message?.text),
             });
             if (ctx.message?.text && ctx.chat?.type !== "private") {
-                await ctx.reply("This message was sent as the group identity or as an anonymous admin. telecodex cannot verify the operator. Send it from your personal account instead.");
+                await replyError(ctx, "This message was sent as the group identity or as an anonymous admin. telecodex cannot verify the operator. Send it from your personal account instead.");
             }
             return;
         }
@@ -31,7 +32,7 @@ export function authMiddleware(input) {
                     store: input.store,
                     success: async () => {
                         input.store.rebindAuthorizedUserId(userId);
-                        await ctx.reply("Admin handoff succeeded. This Telegram account is now authorized to use telecodex.");
+                        await replyNotice(ctx, "Admin handoff succeeded. This Telegram account is now authorized to use telecodex.");
                     },
                     mismatchLabel: "Admin handoff code did not match.",
                     exhaustedLabel: "Admin handoff code exhausted its attempt limit and was invalidated. Issue a new one from the currently authorized account.",
@@ -68,7 +69,7 @@ export function authMiddleware(input) {
                     const claimedUserId = input.store.claimAuthorizedUserId(userId);
                     if (claimedUserId === userId) {
                         input.onAdminBound?.(userId);
-                        await ctx.reply("Admin binding succeeded. Only this Telegram account can use this bot from now on.");
+                        await replyNotice(ctx, "Admin binding succeeded. Only this Telegram account can use this bot from now on.");
                         return;
                     }
                     await deny(ctx, "An admin account has already claimed this bot.");
@@ -79,7 +80,7 @@ export function authMiddleware(input) {
             if (handled)
                 return;
         }
-        await ctx.reply("This bot is not initialized yet. Send the binding code shown in the startup logs to complete the one-time admin binding.");
+        await replyNotice(ctx, "This bot is not initialized yet. Send the binding code shown in the startup logs to complete the one-time admin binding.");
     };
 }
 async function handleBindingCodeMessage(input) {
@@ -92,14 +93,14 @@ async function handleBindingCodeMessage(input) {
     }
     const attempt = input.store.recordBindingCodeFailure();
     if (!attempt) {
-        await input.ctx.reply("The binding code is no longer active. Issue a new one and try again.");
+        await replyError(input.ctx, "The binding code is no longer active. Issue a new one and try again.");
         return true;
     }
     if (attempt.exhausted) {
-        await input.ctx.reply(input.exhaustedLabel);
+        await replyError(input.ctx, input.exhaustedLabel);
         return true;
     }
-    await input.ctx.reply(`${input.mismatchLabel}\nRemaining attempts: ${attempt.remaining}`);
+    await replyError(input.ctx, input.mismatchLabel, `Remaining attempts: ${attempt.remaining}`);
     return true;
 }
 async function deny(ctx, text) {
@@ -108,6 +109,6 @@ async function deny(ctx, text) {
         return;
     }
     if (ctx.chat?.type === "private") {
-        await ctx.reply(text);
+        await replyError(ctx, text);
     }
 }

package/dist/bot/commandSupport.js

@@ -2,7 +2,7 @@ import { realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { APPROVAL_POLICIES, MODE_PRESETS, REASONING_EFFORTS, SANDBOX_MODES, } from "../config.js";
 import { makeSessionKey } from "../store/sessions.js";
-import { sendPlainChunks } from "../telegram/delivery.js";
+import { replyNotice, sendReplyNotice } from "../telegram/formatted.js";
 import { numericChatId, numericMessageThreadId, sessionFromContext } from "./session.js";
 import { truncateSingleLine } from "./sessionFlow.js";
 export function getProjectForContext(ctx, projects) {
@@ -12,20 +12,12 @@ export function getProjectForContext(ctx, projects) {
     return projects.get(String(chatId));
 }
 export function getScopedSession(ctx, store, projects, config, options) {
-    if (isPrivateChat(ctx)) {
-        void ctx.reply("Private chat is only for admin binding and project overview. Do actual work inside project supergroup topics.");
-        return null;
-    }
     const project = getProjectForContext(ctx, projects);
-    if (!project) {
-        void ctx.reply("This supergroup has no project bound yet.\nRun /project bind <absolute-path> first.");
+    if (!project || isPrivateChat(ctx))
         return null;
-    }
     const requireTopic = options?.requireTopic ?? true;
-    if (requireTopic && !hasTopicContext(ctx)) {
-        void ctx.reply("Use this inside a forum topic. The root chat is only for project-level commands; work happens inside topics.");
+    if (requireTopic && !hasTopicContext(ctx))
         return null;
-    }
     const session = sessionFromContext(ctx, store, config);
     if (!isPathWithinRoot(session.cwd, project.cwd)) {
         store.setCwd(session.sessionKey, project.cwd);
@@ -33,6 +25,13 @@ export function getScopedSession(ctx, store, projects, config, options) {
     }
     return session;
 }
+export async function requireScopedSession(ctx, store, projects, config, options) {
+    const session = getScopedSession(ctx, store, projects, config, options);
+    if (session)
+        return session;
+    await replyScopedSessionRequirement(ctx, projects, options);
+    return null;
+}
 export function formatHelpText(ctx, projects) {
     if (isPrivateChat(ctx)) {
         return [
@@ -163,11 +162,10 @@ export function ensureTopicSession(input) {
     return input.store.get(session.sessionKey) ?? session;
 }
 export async function postTopicReadyMessage(bot, session, text, logger) {
-    await sendPlainChunks(bot, {
+    await sendReplyNotice(bot, {
         chatId: numericChatId(session),
         messageThreadId: numericMessageThreadId(session),
-        text,
-    }, logger);
+    }, text, logger);
 }
 export function parseSubcommand(input) {
     const trimmed = input.trim();
@@ -252,3 +250,18 @@ function canonicalizeBoundaryPath(input) {
         return resolved;
     }
 }
+async function replyScopedSessionRequirement(ctx, projects, options) {
+    if (isPrivateChat(ctx)) {
+        await replyNotice(ctx, "Private chat is only for admin binding and project overview. Do actual work inside project supergroup topics.");
+        return;
+    }
+    const project = getProjectForContext(ctx, projects);
+    if (!project) {
+        await replyNotice(ctx, "This supergroup has no project bound yet.\nRun /project bind <absolute-path> first.");
+        return;
+    }
+    const requireTopic = options?.requireTopic ?? true;
+    if (requireTopic && !hasTopicContext(ctx)) {
+        await replyNotice(ctx, "Use this inside a forum topic. The root chat is only for project-level commands; work happens inside topics.");
+    }
+}

package/dist/bot/handlers/messageHandlers.js

@@ -1,9 +1,11 @@
-import { contextLogFields, getScopedSession, } from "../commandSupport.js";
+import { contextLogFields, requireScopedSession, } from "../commandSupport.js";
 import { handleUserInput, handleUserText } from "../inputService.js";
 import { telegramImageMessageToCodexInput } from "../../telegram/attachments.js";
+import { replyError, replyNotice } from "../../telegram/formatted.js";
+import { wrapUserFacingHandler } from "../userFacingErrors.js";
 export function registerMessageHandlers(deps) {
     const { bot, config, store, projects, codex, buffers, logger } = deps;
-    bot.on("message:text", async (ctx) => {
+    bot.on("message:text", wrapUserFacingHandler("message:text", logger, async (ctx) => {
         const text = ctx.message.text;
         logger?.info("received telegram text message", {
             ...contextLogFields(ctx),
@@ -12,7 +14,7 @@ export function registerMessageHandlers(deps) {
         });
         if (text.startsWith("/"))
             return;
-        const session = getScopedSession(ctx, store, projects, config);
+        const session = await requireScopedSession(ctx, store, projects, config);
         if (!session) {
             logger?.warn("ignored telegram text message because no scoped session was available", {
                 ...contextLogFields(ctx),
@@ -29,9 +31,9 @@ export function registerMessageHandlers(deps) {
             bot,
             ...(logger ? { logger } : {}),
         });
-    });
-    bot.on(["message:photo", "message:document"], async (ctx) => {
-        const session = getScopedSession(ctx, store, projects, config);
+    }));
+    bot.on(["message:photo", "message:document"], wrapUserFacingHandler("message:attachment", logger, async (ctx) => {
+        const session = await requireScopedSession(ctx, store, projects, config);
         if (!session) {
             logger?.warn("ignored telegram attachment because no scoped session was available", {
                 ...contextLogFields(ctx),
@@ -47,7 +49,7 @@ export function registerMessageHandlers(deps) {
                 message: ctx.message,
             });
             if (!prompt) {
-                await ctx.reply("Only image attachments are supported.");
+                await replyNotice(ctx, "Only image attachments are supported.");
                 return;
             }
             await handleUserInput({
@@ -65,7 +67,7 @@ export function registerMessageHandlers(deps) {
                 ...contextLogFields(ctx),
                 error,
             });
-            await ctx.reply(error instanceof Error ? error.message : String(error));
+            await replyError(ctx, error instanceof Error ? error.message : String(error));
         }
-    });
+    }));
 }

package/dist/bot/handlers/operationalHandlers.js

@@ -2,34 +2,38 @@ import { presetFromProfile } from "../../config.js";
 import { generateBindingCode } from "../../runtime/bindingCodes.js";
 import { formatSessionRuntimeStatus } from "../../runtime/sessionRuntime.js";
 import { refreshSessionIfActiveTurnIsStale } from "../inputService.js";
-import { contextLogFields, formatHelpText, formatPrivateStatus, formatProjectStatus, formatReasoningEffort, getProjectForContext, getScopedSession, hasTopicContext, isPrivateChat, parseSubcommand, } from "../commandSupport.js";
+import { contextLogFields, formatHelpText, formatPrivateStatus, formatProjectStatus, formatReasoningEffort, getProjectForContext, hasTopicContext, isPrivateChat, parseSubcommand, requireScopedSession, } from "../commandSupport.js";
 import { formatIsoTimestamp, sessionLogFields } from "../sessionFlow.js";
+import { codeField, replyDocument, replyError, replyNotice, replyUsage, textField } from "../../telegram/formatted.js";
+import { wrapUserFacingHandler } from "../userFacingErrors.js";
 export function registerOperationalHandlers(deps) {
     const { bot, config, store, projects, codex, logger } = deps;
-    bot.command(["start", "help"], async (ctx) => {
-        await ctx.reply(formatHelpText(ctx, projects));
-    });
-    bot.command("admin", async (ctx) => {
+    bot.command(["start", "help"], wrapUserFacingHandler("help", logger, async (ctx) => {
+        await replyNotice(ctx, formatHelpText(ctx, projects));
+    }));
+    bot.command("admin", wrapUserFacingHandler("admin", logger, async (ctx) => {
         if (!isPrivateChat(ctx)) {
-            await ctx.reply("Use /admin in the bot private chat.");
+            await replyNotice(ctx, "Use /admin in the bot private chat.");
             return;
         }
         const authorizedUserId = store.getAuthorizedUserId();
         if (authorizedUserId == null) {
-            await ctx.reply("Admin binding is not completed yet.");
+            await replyNotice(ctx, "Admin binding is not completed yet.");
             return;
         }
         const { command } = parseSubcommand(ctx.match.trim());
         const binding = store.getBindingCodeState();
         if (!command || command === "status") {
-            await ctx.reply([
-                "Admin status",
-                `authorized telegram user id: ${authorizedUserId}`,
-                binding?.mode === "rebind"
-                    ? `pending handoff: active until ${formatIsoTimestamp(binding.expiresAt)} (${binding.maxAttempts - binding.attempts} attempts remaining)`
-                    : "pending handoff: none",
-                "Usage: /admin | /admin rebind | /admin cancel",
-            ].join("\n"));
+            await replyDocument(ctx, {
+                title: "Admin status",
+                fields: [
+                    textField("authorized telegram user id", authorizedUserId),
+                    textField("pending handoff", binding?.mode === "rebind"
+                        ? `active until ${formatIsoTimestamp(binding.expiresAt)} (${binding.maxAttempts - binding.attempts} attempts remaining)`
+                        : "none"),
+                ],
+                footer: "Usage: /admin | /admin rebind | /admin cancel",
+            });
             return;
         }
         if (command === "rebind") {
@@ -38,124 +42,133 @@ export function registerOperationalHandlers(deps) {
                 mode: "rebind",
                 issuedByUserId: authorizedUserId,
             });
-            await ctx.reply([
-                "Admin handoff code created.",
-                `expires at: ${formatIsoTimestamp(next.expiresAt)}`,
-                `max failed attempts: ${next.maxAttempts}`,
-                "",
-                next.code,
-                "",
-                "Send this code from the target Telegram account in this bot's private chat to transfer control.",
-            ].join("\n"));
+            await replyDocument(ctx, {
+                title: "Admin handoff code created.",
+                fields: [
+                    textField("expires at", formatIsoTimestamp(next.expiresAt)),
+                    textField("max failed attempts", next.maxAttempts),
+                    codeField("code", next.code),
+                ],
+                footer: "Send this code from the target Telegram account in this bot's private chat to transfer control.",
+            });
             return;
         }
         if (command === "cancel") {
             if (binding?.mode !== "rebind") {
-                await ctx.reply("No pending admin handoff.");
+                await replyNotice(ctx, "No pending admin handoff.");
                 return;
             }
             store.clearBindingCode();
-            await ctx.reply("Cancelled the pending admin handoff.");
+            await replyNotice(ctx, "Cancelled the pending admin handoff.");
             return;
         }
-        await ctx.reply("Usage: /admin | /admin rebind | /admin cancel");
-    });
-    bot.command("status", async (ctx) => {
+        await replyUsage(ctx, "/admin | /admin rebind | /admin cancel");
+    }));
+    bot.command("status", wrapUserFacingHandler("status", logger, async (ctx) => {
         if (isPrivateChat(ctx)) {
-            await ctx.reply(formatPrivateStatus(store, projects));
+            await replyNotice(ctx, formatPrivateStatus(store, projects));
             return;
         }
         const project = getProjectForContext(ctx, projects);
         if (!project) {
-            await ctx.reply("This supergroup has no project bound yet.\nRun /project bind <absolute-path> first.");
+            await replyNotice(ctx, "This supergroup has no project bound yet.\nRun /project bind <absolute-path> first.");
             return;
         }
         if (!hasTopicContext(ctx)) {
-            await ctx.reply(formatProjectStatus(project));
+            await replyNotice(ctx, formatProjectStatus(project));
             return;
         }
-        const session = getScopedSession(ctx, store, projects, config);
+        const session = await requireScopedSession(ctx, store, projects, config);
         if (!session)
             return;
         const latestSession = await refreshSessionIfActiveTurnIsStale(session, store, codex, bot, logger);
         const queueDepth = store.getQueuedInputCount(latestSession.sessionKey);
         const queuedPreview = store.listQueuedInputs(latestSession.sessionKey, 3);
         const activeRun = codex.getActiveRun(latestSession.sessionKey);
-        await ctx.reply([
-            "Status",
-            `project: ${project.name}`,
-            `root: ${project.cwd}`,
-            `thread: ${latestSession.codexThreadId ?? "not created"}`,
-            `state: ${formatSessionRuntimeStatus(latestSession.runtimeStatus)}`,
-            `state detail: ${latestSession.runtimeStatusDetail ?? "none"}`,
-            `state updated: ${formatIsoTimestamp(latestSession.runtimeStatusUpdatedAt)}`,
-            `active turn: ${latestSession.activeTurnId ?? "none"}`,
-            `active run: ${activeRun ? formatIsoTimestamp(activeRun.startedAt) : "none"}`,
-            `active run thread: ${activeRun?.threadId ?? "none"}`,
-            `active run last event: ${activeRun?.lastEventType ?? "none"}`,
-            `active run last update: ${activeRun ? formatIsoTimestamp(activeRun.lastEventAt) : "none"}`,
-            `queue: ${queueDepth}`,
-            `queue next: ${formatQueuedPreview(queuedPreview)}`,
-            `cwd: ${latestSession.cwd}`,
-            `preset: ${presetFromProfile(latestSession)}`,
-            `sandbox: ${latestSession.sandboxMode}`,
-            `approval: ${latestSession.approvalPolicy}`,
-            `network: ${latestSession.networkAccessEnabled ? "on" : "off"}`,
-            `web: ${latestSession.webSearchMode ?? "codex-default"}`,
-            `git check: ${latestSession.skipGitRepoCheck ? "skip" : "enforce"}`,
-            `add dirs: ${latestSession.additionalDirectories.length}`,
-            `schema: ${latestSession.outputSchema ? "set" : "none"}`,
-            `model: ${latestSession.model}`,
-            `effort: ${formatReasoningEffort(latestSession.reasoningEffort)}`,
-        ].join("\n"));
-    });
-    bot.command("queue", async (ctx) => {
-        const session = getScopedSession(ctx, store, projects, config);
+        await replyDocument(ctx, {
+            title: "Status",
+            fields: [
+                codeField("project", project.name),
+                codeField("root", project.cwd),
+                codeField("thread", latestSession.codexThreadId ?? "not created"),
+                textField("state", formatSessionRuntimeStatus(latestSession.runtimeStatus)),
+                textField("state detail", latestSession.runtimeStatusDetail ?? "none"),
+                textField("state updated", formatIsoTimestamp(latestSession.runtimeStatusUpdatedAt)),
+                codeField("active turn", latestSession.activeTurnId ?? "none"),
+                textField("active run", activeRun ? formatIsoTimestamp(activeRun.startedAt) : "none"),
+                codeField("active run thread", activeRun?.threadId ?? "none"),
+                textField("active run last event", activeRun?.lastEventType ?? "none"),
+                textField("active run last update", activeRun ? formatIsoTimestamp(activeRun.lastEventAt) : "none"),
+                textField("queue", queueDepth),
+                textField("queue next", formatQueuedPreview(queuedPreview)),
+                codeField("cwd", latestSession.cwd),
+                textField("preset", presetFromProfile(latestSession)),
+                textField("sandbox", latestSession.sandboxMode),
+                textField("approval", latestSession.approvalPolicy),
+                textField("network", latestSession.networkAccessEnabled ? "on" : "off"),
+                textField("web", latestSession.webSearchMode ?? "codex-default"),
+                textField("git check", latestSession.skipGitRepoCheck ? "skip" : "enforce"),
+                textField("add dirs", latestSession.additionalDirectories.length),
+                textField("schema", latestSession.outputSchema ? "set" : "none"),
+                textField("model", latestSession.model),
+                textField("effort", formatReasoningEffort(latestSession.reasoningEffort)),
+            ],
+        });
+    }));
+    bot.command("queue", wrapUserFacingHandler("queue", logger, async (ctx) => {
+        const session = await requireScopedSession(ctx, store, projects, config);
         if (!session)
             return;
         const { command, args } = parseSubcommand(ctx.match.trim());
         if (!command) {
             const queued = store.listQueuedInputs(session.sessionKey, 5);
             const queueDepth = store.getQueuedInputCount(session.sessionKey);
-            await ctx.reply([
-                "Queue",
-                `state: ${formatSessionRuntimeStatus(session.runtimeStatus)}`,
-                `active turn: ${session.activeTurnId ?? "none"}`,
-                `queue: ${queueDepth}`,
-                queued.length > 0 ? `items:\n${formatQueuedItems(queued)}` : "items: none",
-                "Usage: /queue | /queue drop <id> | /queue clear",
-            ].join("\n"));
+            await replyDocument(ctx, {
+                title: "Queue",
+                fields: [
+                    textField("state", formatSessionRuntimeStatus(session.runtimeStatus)),
+                    codeField("active turn", session.activeTurnId ?? "none"),
+                    textField("queue", queueDepth),
+                ],
+                sections: [
+                    {
+                        title: "Items",
+                        lines: queued.length > 0 ? [formatQueuedItems(queued)] : ["none"],
+                    },
+                ],
+                footer: "Usage: /queue | /queue drop <id> | /queue clear",
+            });
             return;
         }
         if (command === "clear") {
             const removed = store.clearQueuedInputs(session.sessionKey);
-            await ctx.reply(`Cleared the queue and removed ${removed} pending message(s).`);
+            await replyNotice(ctx, `Cleared the queue and removed ${removed} pending message(s).`);
             return;
         }
         if (command === "drop") {
             const id = Number(args);
             if (!Number.isInteger(id) || id <= 0) {
-                await ctx.reply("Usage: /queue drop <id>");
+                await replyUsage(ctx, "/queue drop <id>");
                 return;
             }
             const removed = store.removeQueuedInputForSession(session.sessionKey, id);
-            await ctx.reply(removed ? `Removed queued item #${id}.` : `Queued item #${id} was not found.`);
+            await replyNotice(ctx, removed ? `Removed queued item #${id}.` : `Queued item #${id} was not found.`);
             return;
         }
-        await ctx.reply("Usage: /queue | /queue drop <id> | /queue clear");
-    });
-    bot.command("stop", async (ctx) => {
-        const session = getScopedSession(ctx, store, projects, config);
+        await replyUsage(ctx, "/queue | /queue drop <id> | /queue clear");
+    }));
+    bot.command("stop", wrapUserFacingHandler("stop", logger, async (ctx) => {
+        const session = await requireScopedSession(ctx, store, projects, config);
         if (!session)
             return;
         const latest = store.get(session.sessionKey) ?? session;
         if (!codex.isRunning(session.sessionKey)) {
-            await ctx.reply("There is no active Codex SDK turn right now.");
+            await replyNotice(ctx, "There is no active Codex SDK turn right now.");
             return;
         }
         try {
             codex.interrupt(session.sessionKey);
-            await ctx.reply("Interrupt requested for the current run. Waiting for Codex SDK to stop.");
+            await replyNotice(ctx, "Interrupt requested for the current run. Waiting for Codex SDK to stop.");
         }
         catch (error) {
             logger?.warn("interrupt turn failed", {
@@ -163,9 +176,9 @@ export function registerOperationalHandlers(deps) {
                 ...sessionLogFields(latest),
                 error,
             });
-            await ctx.reply(`Interrupt failed: ${error instanceof Error ? error.message : String(error)}`);
+            await replyError(ctx, `Interrupt failed: ${error instanceof Error ? error.message : String(error)}`);
         }
-    });
+    }));
 }
 function formatQueuedPreview(items) {
     if (items.length === 0)