telecodex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 telecodex contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# telecodex
+
+Telegram bridge for local Codex built on the official TypeScript SDK.
+
+## Model
+
+```text
+Telegram private chat
+  -> one-time admin bootstrap
+
+Telegram forum supergroup
+  -> one project per supergroup
+  -> one topic per Codex thread
+
+Telegram
+  -> grammY bot + runner
+  -> CodexSdkRuntime
+  -> @openai/codex-sdk
+  -> local Codex login
+```
+
+The bot talks to local Codex through `@openai/codex-sdk`, which wraps the local
+`codex` CLI. It does not depend on `codex app-server`.
+
+## Runtime contract
+
+- Telegram is treated as a remote task interface, not a clone of Codex Desktop.
+- One topic maps to one Codex SDK thread.
+- Each topic has at most one active SDK run.
+- Follow-up messages during an active run are queued and processed in order.
+- Text and image messages are mapped to Codex SDK input.
+- A run immediately creates a normal Telegram status message; progress edits that message.
+- telecodex does not use pinned messages for live state.
+- While a run is pending, the bot sends Telegram `typing` activity so the chat does not look dead during long SDK gaps.
+- `/status` is the source of truth for runtime state, active thread id, last SDK event, and queue depth.
+
+## Requirements
+
+- Node.js 24 or newer.
+- A local `codex` CLI installation available on `PATH`.
+- A valid local Codex login:
+
+```bash
+codex login status
+```
+
+- A Telegram bot token.
+
+## Install from npm
+
+```bash
+npm install -g telecodex
+telecodex
+```
+
+`telecodex` uses the local `codex` CLI at runtime, so installing this package
+does not replace the separate Codex CLI installation.
+
+## Local development
+
+1. Install dependencies:
+
+```bash
+npm install
+```
+
+2. Start it:
+
+```bash
+npm run dev
+```
+
+For a production-style local install during development, `npm link` exposes the
+same `telecodex` command globally from the current checkout.
+
+## First launch
+
+On first launch, `telecodex`:
+
+1. Finds or asks for the local `codex` binary path.
+2. Verifies Codex login.
+3. Asks for a Telegram bot token if none is stored yet.
+4. Generates a one-time bootstrap code if no Telegram admin is bound yet.
+5. Waits for that code in a private chat. The first successful sender becomes the permanent admin for this bot instance.
+
+There are no required environment variables in the normal startup path.
+
+Optional security override:
+
+- `TELECODEX_ALLOW_PLAINTEXT_TOKEN_FALLBACK=1` allows storing the Telegram bot token unencrypted in local state when the system keychain is unavailable. This is disabled by default.
+
+## Working model
+
+- Private chat is only for bootstrap and lightweight management.
+- One forum supergroup represents one project.
+- The project root is bound once with `/project bind <absolute-path>`.
+- Each topic in that supergroup is one Codex thread.
+- Work happens by sending normal messages inside the topic.
+- `/thread new <topic-name>` automatically creates a new topic; the first normal message inside it starts a fresh Codex thread.
+- `/thread resume <threadId>` automatically creates a new topic and binds it to an existing thread id.
+
+## Stored state
+
+- Telegram bot token: stored in the system keychain when available. Plaintext local fallback is disabled by default and must be opted into explicitly.
+- Admin binding, project bindings, and topic/session state: stored in a local SQLite database under `~/.telecodex/`.
+- Runtime logs: written by `pino` to `~/.telecodex/logs/telecodex.log`.
+- Working directory: defaults to the directory where you ran `telecodex`.
+
+## Logs
+
+- Startup prints the active log file path.
+- Telegram middleware errors and message edit failures are appended to the log file.
+- When you need to debug a running instance later, inspect `~/.telecodex/logs/telecodex.log` first.
+
+## Commands
+
+- `/start` or `/help` - show the current usage model.
+- `/status` - in private chat shows global state; in a project topic shows project/thread runtime state.
+- `/project` - show the current supergroup's project binding.
+- `/project bind <absolute-path>` - bind the current supergroup to a project root.
+- `/project unbind` - remove the current supergroup's project binding.
+- `/thread` - in a topic, show the current attached thread id.
+- `/thread new <topic-name>` - create a new topic for a fresh Codex thread.
+- `/thread resume <threadId>` - create a new topic and bind it to an existing Codex thread id.
+- Normal text in a topic - send that message to the current Codex thread.
+- `/stop` - interrupt the active SDK run.
+- `/cwd <absolute-path>` - switch the topic working directory inside the current project root.
+- `/mode read|write|danger|yolo` - switch runtime presets for the current topic.
+- `/sandbox <read-only|workspace-write|danger-full-access>` - set sandbox explicitly for the current topic.
+- `/approval <on-request|on-failure|never>` - set approval policy explicitly for the current topic.
+- `/yolo on|off` - quick toggle for `danger-full-access + never` on the current topic.
+- `/model <model-id>` - set model for the current topic.
+- `/effort default|minimal|low|medium|high|xhigh` - set model reasoning effort for the current topic.
+- `/web default|disabled|cached|live` - set Codex SDK web search mode.
+- `/network on|off` - set workspace network access for Codex SDK runs.
+- `/gitcheck skip|enforce` - control Codex SDK git repository checks.
+- `/adddir list|add <absolute-path>|drop <index>|clear` - manage Codex SDK additional directories.
+- `/schema show|set <JSON object>|clear` - manage Codex SDK output schema for the current topic.
+- `/codexconfig show|set <JSON object>|clear` - manage global non-auth Codex SDK config overrides for future runs.
+- Image messages in a topic - download the Telegram image locally and send it as SDK `local_image` input.
+
+## Notes
+
+- Long polling is managed by `@grammyjs/runner`.
+- Streaming updates are throttled before editing Telegram messages.
+- Final answers are rendered from Markdown to Telegram-safe HTML.
+- Because the SDK run is in-process, a telecodex restart cannot resume a partially streamed Telegram turn; the topic is reset and the user is asked to resend.
+- Authentication and provider switching remain owned by the local Codex installation; telecodex does not manage API keys or login state.
+- Interactive terminal stdin bridging and native Codex approval UI are intentionally not part of the Telegram contract. For unattended remote work, use the topic's sandbox/approval preset deliberately.

package/dist/bot/auth.js

@@ -0,0 +1,64 @@
+export function authMiddleware(input) {
+    return async (ctx, next) => {
+        const userId = ctx.from?.id;
+        if (!userId) {
+            input.logger?.warn("telegram update ignored because it has no from.id", {
+                chatId: ctx.chat?.id ?? null,
+                chatType: ctx.chat?.type ?? null,
+                messageThreadId: ctx.message?.message_thread_id ?? ctx.callbackQuery?.message?.message_thread_id ?? null,
+                senderChatId: ctx.message?.sender_chat?.id ?? ctx.callbackQuery?.message?.sender_chat?.id ?? null,
+                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.");
+            }
+            return;
+        }
+        const authorizedUserId = input.store.getAuthorizedUserId();
+        if (authorizedUserId != null) {
+            if (authorizedUserId === userId) {
+                await next();
+                return;
+            }
+            input.logger?.warn("telegram update denied because user is not authorized", {
+                chatId: ctx.chat?.id ?? null,
+                chatType: ctx.chat?.type ?? null,
+                messageThreadId: ctx.message?.message_thread_id ?? ctx.callbackQuery?.message?.message_thread_id ?? null,
+                fromId: userId,
+                authorizedUserId,
+            });
+            await deny(ctx, "Unauthorized.");
+            return;
+        }
+        if (!input.bootstrapCode) {
+            await deny(ctx, "Authentication is not configured for this bot yet.");
+            return;
+        }
+        if (ctx.chat?.type !== "private") {
+            await deny(ctx, "Send the admin bootstrap code to the bot in a private chat first.");
+            return;
+        }
+        const messageText = ctx.message?.text?.trim();
+        if (messageText === input.bootstrapCode) {
+            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.");
+            }
+            else {
+                await deny(ctx, "An admin account has already claimed this bot.");
+            }
+            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.");
+    };
+}
+async function deny(ctx, text) {
+    if (ctx.callbackQuery) {
+        await ctx.answerCallbackQuery({ text, show_alert: false });
+        return;
+    }
+    if (ctx.chat?.type === "private") {
+        await ctx.reply(text);
+    }
+}

package/dist/bot/commandSupport.js

@@ -0,0 +1,239 @@
+import { 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 { numericChatId, numericMessageThreadId, sessionFromContext } from "./session.js";
+import { truncateSingleLine } from "./sessionFlow.js";
+export function getProjectForContext(ctx, projects) {
+    const chatId = ctx.chat?.id;
+    if (chatId == null || isPrivateChat(ctx))
+        return null;
+    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.");
+        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.");
+        return null;
+    }
+    const session = sessionFromContext(ctx, store, config);
+    if (!isPathWithinRoot(session.cwd, project.cwd)) {
+        store.setCwd(session.sessionKey, project.cwd);
+        return store.get(session.sessionKey) ?? session;
+    }
+    return session;
+}
+export function formatHelpText(ctx, projects) {
+    if (isPrivateChat(ctx)) {
+        return [
+            "telecodex is ready.",
+            "",
+            "Primary workflow:",
+            "1. One forum supergroup = one project",
+            "2. One topic = one Codex thread",
+            "3. Send normal messages directly inside the topic",
+            "",
+            "Run this first in the project group:",
+            "/project bind <absolute-path>",
+            "",
+            "Then manage threads in the group:",
+            "/thread new <topic-name>",
+            "/thread resume <threadId>",
+            "",
+            "Inside a topic, send messages directly:",
+            "/status",
+            "/queue",
+            "/queue drop <id>",
+            "/queue clear",
+            "/stop",
+            "",
+            formatPrivateProjectSummary(projects),
+        ].join("\n");
+    }
+    const project = getProjectForContext(ctx, projects);
+    if (!project) {
+        return [
+            "This supergroup has no project bound yet.",
+            "",
+            "Run this first:",
+            "/project bind <absolute-path>",
+            "",
+            "After binding, each topic acts as an independent Codex thread.",
+        ].join("\n");
+    }
+    return [
+        "telecodex is ready.",
+        "",
+        `project: ${project.name}`,
+        `root: ${project.cwd}`,
+        "",
+        "/project show the project binding",
+        "/project bind <absolute-path> update the project root",
+        "/thread new <topic-name> create a new topic; the first message starts a new thread",
+        "/thread resume <threadId> create a topic bound to an existing thread",
+        "send a normal message inside a topic to the current thread",
+        "/status show topic state, recent SDK events, and queue depth",
+        "/queue show queued messages for the current topic",
+        "/queue drop <id> remove one queued message",
+        "/queue clear clear the current topic queue",
+        "/stop interrupt the current SDK run",
+        "/cwd <path> switch to a working subdirectory inside the project root",
+        `/mode ${MODE_PRESETS.join("|")}`,
+        `/sandbox ${SANDBOX_MODES.join("|")}`,
+        `/approval ${APPROVAL_POLICIES.join("|")}`,
+        "/yolo on|off",
+        "/model <id>",
+        `/effort default|${REASONING_EFFORTS.join("|")}`,
+        "/web default|disabled|cached|live",
+        "/network on|off",
+        "/gitcheck skip|enforce",
+        "/adddir list|add|drop|clear",
+        "/schema show|set|clear",
+        "/codexconfig show|set|clear",
+    ].join("\n");
+}
+export function formatPrivateStatus(store, projects) {
+    return [
+        "telecodex admin",
+        `authorized telegram user id: ${store.getAuthorizedUserId() ?? "not bound"}`,
+        "",
+        formatPrivateProjectSummary(projects),
+    ].join("\n");
+}
+export function formatPrivateProjectSummary(projects) {
+    const bound = projects.list();
+    if (bound.length === 0) {
+        return "No project supergroups are currently bound.";
+    }
+    return `Bound project supergroups: ${bound.length}`;
+}
+export function formatPrivateProjectList(projects) {
+    const bound = projects.list();
+    if (bound.length === 0) {
+        return "No project supergroups are currently bound.";
+    }
+    return [
+        "Bound projects:",
+        ...bound.map((project, index) => `${index + 1}. ${project.name}\n   root: ${project.cwd}\n   chat: ${project.chatId}`),
+    ].join("\n");
+}
+export function formatProjectStatus(project) {
+    return [
+        "Project status",
+        `project: ${project.name}`,
+        `root: ${project.cwd}`,
+        "This supergroup represents one project. Use /thread new or /thread resume to create topics.",
+    ].join("\n");
+}
+export function ensureTopicSession(input) {
+    const sessionKey = makeSessionKey(input.chatId, input.messageThreadId);
+    const session = input.store.getOrCreate({
+        sessionKey,
+        chatId: String(input.chatId),
+        messageThreadId: String(input.messageThreadId),
+        telegramTopicName: input.topicName ?? null,
+        defaultCwd: input.project.cwd,
+        defaultModel: input.config.defaultModel,
+    });
+    if (input.topicName && session.telegramTopicName !== input.topicName) {
+        input.store.setTelegramTopicName(session.sessionKey, input.topicName);
+    }
+    if (input.threadId && session.codexThreadId !== input.threadId) {
+        input.store.bindThread(session.sessionKey, input.threadId);
+    }
+    if (!isPathWithinRoot(session.cwd, input.project.cwd)) {
+        input.store.setCwd(session.sessionKey, input.project.cwd);
+        return input.store.get(session.sessionKey) ?? session;
+    }
+    return input.store.get(session.sessionKey) ?? session;
+}
+export async function postTopicReadyMessage(bot, session, text, logger) {
+    await sendPlainChunks(bot, {
+        chatId: numericChatId(session),
+        messageThreadId: numericMessageThreadId(session),
+        text,
+    }, logger);
+}
+export function parseSubcommand(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return { command: null, args: "" };
+    const firstSpace = trimmed.indexOf(" ");
+    if (firstSpace < 0) {
+        return {
+            command: trimmed.toLowerCase(),
+            args: "",
+        };
+    }
+    return {
+        command: trimmed.slice(0, firstSpace).toLowerCase(),
+        args: trimmed.slice(firstSpace + 1).trim(),
+    };
+}
+export function formatTopicName(rawName, fallback) {
+    const normalized = rawName?.trim() || fallback;
+    return truncateSingleLine(normalized, 128);
+}
+export function resolveExistingDirectory(input) {
+    const resolved = path.resolve(input.trim());
+    if (!resolved) {
+        throw new Error("Project path cannot be empty.");
+    }
+    let stat;
+    try {
+        stat = statSync(resolved);
+    }
+    catch {
+        throw new Error(`Directory does not exist: ${resolved}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`Not a directory: ${resolved}`);
+    }
+    return resolved;
+}
+export function assertProjectScopedPath(input, projectRoot) {
+    const resolved = path.resolve(input.trim());
+    if (!isPathWithinRoot(resolved, projectRoot)) {
+        throw new Error(["Path must stay within the project root.", `project root: ${projectRoot}`, `input: ${resolved}`].join("\n"));
+    }
+    return resolved;
+}
+export function formatProfileReply(prefix, sandboxMode, approvalPolicy) {
+    return [prefix, `sandbox: ${sandboxMode}`, `approval: ${approvalPolicy}`].join("\n");
+}
+export function formatReasoningEffort(value) {
+    return value ?? "codex-default";
+}
+export function contextLogFields(ctx) {
+    return {
+        chatId: ctx.chat?.id ?? null,
+        chatType: ctx.chat?.type ?? null,
+        messageThreadId: ctx.message?.message_thread_id ?? ctx.callbackQuery?.message?.message_thread_id ?? null,
+        fromId: ctx.from?.id ?? null,
+        updateId: ctx.update.update_id,
+    };
+}
+export function isPrivateChat(ctx) {
+    return ctx.chat?.type === "private";
+}
+export function isSupergroupChat(ctx) {
+    return ctx.chat?.type === "supergroup";
+}
+export function hasTopicContext(ctx) {
+    return ctx.message?.message_thread_id != null || ctx.callbackQuery?.message?.message_thread_id != null;
+}
+export function isPathWithinRoot(candidate, root) {
+    const resolvedCandidate = path.resolve(candidate);
+    const resolvedRoot = path.resolve(root);
+    return resolvedCandidate === resolvedRoot || resolvedCandidate.startsWith(`${resolvedRoot}${path.sep}`);
+}

package/dist/bot/createBot.js

@@ -0,0 +1,51 @@
+import { Bot } from "grammy";
+import { MessageBuffer } from "../telegram/messageBuffer.js";
+import { authMiddleware } from "./auth.js";
+import { recoverActiveTopicSessions } from "./inputService.js";
+import { registerHandlers } from "./registerHandlers.js";
+export { handleUserText, refreshSessionIfActiveTurnIsStale } from "./inputService.js";
+export function wireBot(input) {
+    const { bot, config, store, projects, codex, bootstrapCode, logger, onAdminBound } = input;
+    const buffers = new MessageBuffer(bot, config.updateIntervalMs, logger?.child("message-buffer"));
+    bot.use(authMiddleware({
+        bootstrapCode,
+        store,
+        ...(logger ? { logger: logger.child("auth") } : {}),
+        ...(onAdminBound ? { onAdminBound } : {}),
+    }));
+    if (logger) {
+        bot.catch((error) => {
+            logger.error("grammy bot error", {
+                updateId: error.ctx.update.update_id,
+                chatId: error.ctx.chat?.id ?? null,
+                chatType: error.ctx.chat?.type ?? null,
+                messageThreadId: error.ctx.message?.message_thread_id ?? error.ctx.callbackQuery?.message?.message_thread_id ?? null,
+                fromId: error.ctx.from?.id ?? null,
+                error: error.error,
+            });
+        });
+    }
+    registerHandlers({
+        bot,
+        config,
+        store,
+        projects,
+        codex,
+        buffers,
+        ...(logger ? { logger } : {}),
+    });
+    void recoverActiveTopicSessions(store, codex, buffers, bot, logger);
+    return {
+        bot,
+        buffers,
+    };
+}
+export function createBot(input) {
+    const { config } = input;
+    const bot = new Bot(config.telegramBotToken);
+    wireBot({
+        bot,
+        ...input,
+    });
+    return bot;
+}

package/dist/bot/handlerDeps.js

@@ -0,0 +1 @@
+export {};

package/dist/bot/handlers/messageHandlers.js

@@ -0,0 +1,71 @@
+import { contextLogFields, getScopedSession, } from "../commandSupport.js";
+import { handleUserInput, handleUserText } from "../inputService.js";
+import { telegramImageMessageToCodexInput } from "../../telegram/attachments.js";
+export function registerMessageHandlers(deps) {
+    const { bot, config, store, projects, codex, buffers, logger } = deps;
+    bot.on("message:text", async (ctx) => {
+        const text = ctx.message.text;
+        logger?.info("received telegram text message", {
+            ...contextLogFields(ctx),
+            textLength: text.length,
+            isCommand: text.startsWith("/"),
+        });
+        if (text.startsWith("/"))
+            return;
+        const session = getScopedSession(ctx, store, projects, config);
+        if (!session) {
+            logger?.warn("ignored telegram text message because no scoped session was available", {
+                ...contextLogFields(ctx),
+                textLength: text.length,
+            });
+            return;
+        }
+        await handleUserText({
+            text,
+            session,
+            store,
+            codex,
+            buffers,
+            bot,
+            ...(logger ? { logger } : {}),
+        });
+    });
+    bot.on(["message:photo", "message:document"], async (ctx) => {
+        const session = getScopedSession(ctx, store, projects, config);
+        if (!session) {
+            logger?.warn("ignored telegram attachment because no scoped session was available", {
+                ...contextLogFields(ctx),
+            });
+            return;
+        }
+        try {
+            const prompt = await telegramImageMessageToCodexInput({
+                bot,
+                config,
+                chatId: ctx.chat.id,
+                messageThreadId: ctx.message.message_thread_id ?? null,
+                message: ctx.message,
+            });
+            if (!prompt) {
+                await ctx.reply("Only image attachments are supported.");
+                return;
+            }
+            await handleUserInput({
+                prompt,
+                session,
+                store,
+                codex,
+                buffers,
+                bot,
+                ...(logger ? { logger } : {}),
+            });
+        }
+        catch (error) {
+            logger?.warn("failed to handle telegram image attachment", {
+                ...contextLogFields(ctx),
+                error,
+            });
+            await ctx.reply(error instanceof Error ? error.message : String(error));
+        }
+    });
+}