telecodex 0.1.1 → 0.1.3

package/README.md

@@ -1,179 +1,151 @@
 # telecodex
 
-Telegram bridge for local Codex built on the official TypeScript SDK.
+Use Telegram forum topics as a remote interface for local Codex.
 
-## 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.
+`telecodex` connects a Telegram bot to your local `codex` CLI through the
+official TypeScript SDK. It is meant for remote task execution, not as a full
+clone of Codex Desktop.
 
 ## Requirements
 
-- Node.js 24 or newer.
-- A local `codex` CLI installation available on `PATH`.
-- A valid local Codex login:
+- Node.js 24 or newer
+- A local `codex` CLI installation available on `PATH`
+- A valid local Codex login
+- A Telegram bot token
+
+Check Codex login first:
 
 ```bash
 codex login status
 ```
 
-- A Telegram bot token.
-
-## Install from npm
+## Install
 
 ```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.
+Installing `telecodex` does not replace the separate `codex` CLI. The bot uses
+your local Codex installation at runtime.
 
-## Local development
+## First Launch
 
-1. Install dependencies:
+On first launch, `telecodex`:
 
-```bash
-npm install
-```
+1. Finds or asks for the local `codex` binary path.
+2. Verifies local Codex login.
+3. Prompts 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 Telegram chat with the bot.
 
-2. Start it:
+The first successful sender becomes the admin for that bot instance.
 
-```bash
-npm run dev
-```
+Optional security override:
 
-For a production-style local install during development, `npm link` exposes the
-same `telecodex` command globally from the current checkout.
+- `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.
 
-## Automated npm release
+## How It Works
 
-This repository is set up for npm trusted publishing from GitHub Actions.
+- One Telegram forum supergroup represents one project.
+- One topic inside that supergroup represents one Codex thread.
+- Work happens by sending normal messages inside the topic.
+- While a run is active, follow-up messages are queued automatically.
+- `/status` shows the current runtime state.
 
-1. On npm, open the `telecodex` package settings and configure a trusted publisher:
-   - Organization or user: `jiangege`
-   - Repository: `telecodex`
-   - Workflow filename: `publish.yml`
-2. Bump the version locally:
+Private chat is only for bootstrap and lightweight admin actions.
 
-```bash
-npm version patch
+## Quick Start
+
+Inside a Telegram forum supergroup:
+
+1. Bind the group to a project root:
+
+```text
+/project bind /absolute/path/to/project
 ```
 
-3. Push the branch and tag:
+2. Create a fresh topic for a new Codex thread:
 
-```bash
-git push origin main --follow-tags
+```text
+/thread new My Task
 ```
 
-Pushing a `v*` tag runs `.github/workflows/publish.yml`, which installs dependencies,
-runs `npm run check`, runs `npm test`, and publishes the package to npm when the tag
-matches the version in `package.json`.
+3. Or resume an existing thread:
 
-## First launch
+```text
+/thread list
+/thread resume <threadId>
+```
 
-On first launch, `telecodex`:
+4. Send normal messages in the topic to work with Codex.
 
-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.
+## Commands
 
-Bootstrap codes are time-limited and attempt-limited. When a code expires or is exhausted, start telecodex again locally to issue a fresh one.
+### General
 
-There are no required environment variables in the normal startup path.
+- `/start` or `/help` - show usage help
+- `/status` - show current state
+- `/stop` - interrupt the active run in the current topic
 
-Optional security override:
+### Admin
 
-- `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.
+- `/admin` - show admin binding and handoff state
+- `/admin rebind` - issue a temporary handoff code
+- `/admin cancel` - cancel a pending handoff
 
-## Working model
+### Project
 
-- 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.
+- `/project` - show the current project binding
+- `/project bind <absolute-path>` - bind the current supergroup to a project root
+- `/project unbind` - remove the project binding
 
-## Stored state
+### Threads
 
-- 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`.
+- `/thread` - show the current attached thread id in a topic
+- `/thread list` - list saved Codex threads for the current project
+- `/thread new <topic-name>` - create a fresh topic for a new thread
+- `/thread resume <threadId>` - create a topic and bind it to an existing thread
 
-## Logs
+### Session Configuration
 
-- 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.
+- `/cwd <absolute-path>`
+- `/mode read|write|danger|yolo`
+- `/sandbox <read-only|workspace-write|danger-full-access>`
+- `/approval <on-request|on-failure|never>`
+- `/yolo on|off`
+- `/model <model-id>`
+- `/effort default|minimal|low|medium|high|xhigh`
+- `/web default|disabled|cached|live`
+- `/network on|off`
+- `/gitcheck skip|enforce`
+- `/adddir list|add <path-inside-project>|add-external <absolute-path>|drop <index>|clear`
+- `/schema show|set <JSON object>|clear`
+- `/codexconfig show|set <JSON object>|clear`
 
-## Commands
+## Images
+
+- Sending an image in a topic is supported.
+- Telegram photos and image documents are downloaded locally and sent to Codex as
+  `local_image` input.
+- Image output is not rendered inline in Telegram text messages.
+
+## Storage
+
+- Telegram bot token: stored in the system keychain when available
+- Durable local state: `~/.telecodex/state/`
+- Runtime logs: `~/.telecodex/logs/telecodex.log`
+- Codex thread history: read from Codex session files under `$CODEX_HOME/sessions`
+  (or `~/.codex/sessions` by default)
+
+If an older `~/.telecodex/state.sqlite` exists, telecodex imports it once into
+the JSON state files and then removes the old SQLite files.
+
+## Troubleshooting
+
+- If startup reports a login problem, run `codex login`.
+- If the bot appears idle for a long time, check `/status`.
+- If you need logs, inspect `~/.telecodex/logs/telecodex.log`.
 
-- `/start` or `/help` - show the current usage model.
-- `/status` - in private chat shows global state; in a project topic shows project/thread runtime state.
-- `/admin` - in private chat, show admin binding and handoff status.
-- `/admin rebind` - in private chat, issue a time-limited handoff code for transferring control to another Telegram account.
-- `/admin cancel` - in private chat, cancel a pending admin handoff code.
-- `/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 <path-inside-project>|add-external <absolute-path>|drop <index>|clear` - manage Codex SDK additional directories. `add` stays inside the project root; `add-external` is the explicit escape hatch.
-- `/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.
-- Project-scoped path checks resolve symlinks before enforcing the root boundary, so topic cwd changes cannot escape the bound project through symlink paths.
-- 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/commandSupport.js

@@ -47,6 +47,7 @@ export function formatHelpText(ctx, projects) {
             "/project bind <absolute-path>",
             "",
             "Then manage threads in the group:",
+            "/thread list",
             "/thread new <topic-name>",
             "/thread resume <threadId>",
             "",
@@ -80,6 +81,7 @@ export function formatHelpText(ctx, projects) {
         "",
         "/project show the project binding",
         "/project bind <absolute-path> update the project root",
+        "/thread list show saved Codex threads already recorded for this project",
         "/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",
@@ -135,7 +137,7 @@ export function formatProjectStatus(project) {
         "Project status",
         `project: ${project.name}`,
         `root: ${project.cwd}`,
-        "This supergroup represents one project. Use /thread new or /thread resume to create topics.",
+        "This supergroup represents one project. Use /thread list, /thread new, or /thread resume to manage topics.",
     ].join("\n");
 }
 export function ensureTopicSession(input) {

package/dist/bot/createBot.js

@@ -3,9 +3,10 @@ import { MessageBuffer } from "../telegram/messageBuffer.js";
 import { authMiddleware } from "./auth.js";
 import { recoverActiveTopicSessions } from "./inputService.js";
 import { registerHandlers } from "./registerHandlers.js";
+import { cleanupMissingTopicBindings } from "./topicCleanup.js";
 export { handleUserText, refreshSessionIfActiveTurnIsStale } from "./inputService.js";
 export function wireBot(input) {
-    const { bot, config, store, projects, codex, bootstrapCode, logger, onAdminBound } = input;
+    const { bot, config, store, projects, codex, threadCatalog, bootstrapCode, logger, onAdminBound } = input;
     const buffers = new MessageBuffer(bot, config.updateIntervalMs, logger?.child("message-buffer"));
     bot.use(authMiddleware({
         store,
@@ -30,10 +31,24 @@ export function wireBot(input) {
         store,
         projects,
         codex,
+        threadCatalog,
         buffers,
         ...(logger ? { logger } : {}),
     });
-    void recoverActiveTopicSessions(store, codex, buffers, bot, logger);
+    void (async () => {
+        try {
+            await syncBotCommands(bot, logger);
+            await cleanupMissingTopicBindings({
+                bot,
+                store,
+                ...(logger ? { logger: logger.child("topic-cleanup") } : {}),
+            });
+            await recoverActiveTopicSessions(store, codex, buffers, bot, logger);
+        }
+        catch (error) {
+            logger?.error("startup topic reconciliation failed", error);
+        }
+    })();
     return {
         bot,
         buffers,
@@ -48,3 +63,45 @@ export function createBot(input) {
     });
     return bot;
 }
+async function syncBotCommands(bot, logger) {
+    try {
+        await bot.api.setMyCommands(privateCommands, {
+            scope: { type: "all_private_chats" },
+        });
+        await bot.api.setMyCommands(groupCommands, {
+            scope: { type: "all_group_chats" },
+        });
+    }
+    catch (error) {
+        logger?.warn("failed to sync telegram bot commands", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+const privateCommands = [
+    { command: "start", description: "Show help" },
+    { command: "help", description: "Show help" },
+    { command: "status", description: "Show bot status" },
+    { command: "admin", description: "Show or hand off admin access" },
+];
+const groupCommands = [
+    { command: "help", description: "Show help" },
+    { command: "status", description: "Show project or topic status" },
+    { command: "project", description: "Show, bind, or unbind project" },
+    { command: "thread", description: "List, resume, or create topics" },
+    { command: "queue", description: "List, drop, or clear queued inputs" },
+    { command: "stop", description: "Stop the active run" },
+    { command: "cwd", description: "Show or set topic directory" },
+    { command: "mode", description: "Switch preset mode" },
+    { command: "sandbox", description: "Show or set sandbox mode" },
+    { command: "approval", description: "Show or set approval mode" },
+    { command: "yolo", description: "Enable or disable YOLO mode" },
+    { command: "model", description: "Show or set model" },
+    { command: "effort", description: "Show or set reasoning effort" },
+    { command: "web", description: "Show or set web search" },
+    { command: "network", description: "Show or set network access" },
+    { command: "gitcheck", description: "Show or set git repo check" },
+    { command: "adddir", description: "List or manage extra directories" },
+    { command: "schema", description: "Show or set output schema" },
+    { command: "codexconfig", description: "Show or set Codex config" },
+];

package/dist/bot/handlers/projectHandlers.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { contextLogFields, ensureTopicSession, formatPrivateProjectList, formatProjectStatus, formatTopicName, getProjectForContext, getScopedSession, hasTopicContext, isPrivateChat, isSupergroupChat, parseSubcommand, postTopicReadyMessage, resolveExistingDirectory, } from "../commandSupport.js";
 import { formatSessionRuntimeStatus } from "../../runtime/sessionRuntime.js";
 const PROJECT_REQUIRED_MESSAGE = "This supergroup has no project bound yet.\nRun /project bind <absolute-path> first.";
@@ -82,12 +83,17 @@ export function registerProjectHandlers(deps) {
                     `queue: ${store.getQueuedInputCount(session.sessionKey)}`,
                     `cwd: ${session.cwd}`,
                     "Manage threads in this project:",
+                    "/thread list",
                     "/thread resume <threadId>",
                     "/thread new <topic-name>",
                 ].join("\n"));
                 return;
             }
-            await ctx.reply("Usage:\n/thread resume <threadId>\n/thread new <topic-name>");
+            await ctx.reply("Usage:\n/thread list\n/thread resume <threadId>\n/thread new <topic-name>");
+            return;
+        }
+        if (command === "list") {
+            await listProjectThreads(ctx, deps);
             return;
         }
         if (command === "resume") {
@@ -102,7 +108,7 @@ export function registerProjectHandlers(deps) {
             await createFreshThreadTopic(ctx, deps, args);
             return;
         }
-        await ctx.reply("Usage:\n/thread resume <threadId>\n/thread new <topic-name>");
+        await ctx.reply("Usage:\n/thread list\n/thread resume <threadId>\n/thread new <topic-name>");
     });
     bot.on(["message:forum_topic_created", "message:forum_topic_edited"], async (ctx) => {
         const threadId = ctx.message.message_thread_id;
@@ -119,13 +125,26 @@ export function registerProjectHandlers(deps) {
     });
 }
 async function resumeThreadIntoTopic(ctx, deps, threadId) {
-    const { bot, config, store, projects, logger } = deps;
+    const { bot, config, store, projects, logger, threadCatalog } = deps;
     const project = getProjectForContext(ctx, projects);
     if (!project) {
         await ctx.reply(PROJECT_REQUIRED_MESSAGE);
         return;
     }
-    const topicName = formatTopicName(`Resumed ${threadId.slice(0, 8)}`, "Resumed Thread");
+    const thread = await threadCatalog.findProjectThreadById({
+        projectRoot: project.cwd,
+        threadId,
+    });
+    if (!thread) {
+        await ctx.reply([
+            "Could not find a saved Codex thread with that id under this project.",
+            `project root: ${project.cwd}`,
+            `thread: ${threadId}`,
+            "Run /thread list to inspect the saved project threads first.",
+        ].join("\n"));
+        return;
+    }
+    const topicName = formatTopicName(thread.preview, `Resumed ${thread.id.slice(0, 8)}`);
     const forumTopic = await bot.api.createForumTopic(ctx.chat.id, topicName);
     const session = ensureTopicSession({
         store,
@@ -134,24 +153,25 @@ async function resumeThreadIntoTopic(ctx, deps, threadId) {
         chatId: ctx.chat.id,
         messageThreadId: forumTopic.message_thread_id,
         topicName: forumTopic.name,
-        threadId,
+        threadId: thread.id,
     });
     logger?.info("thread id bound into topic", {
         ...contextLogFields(ctx),
         sessionKey: session.sessionKey,
-        threadId,
+        threadId: thread.id,
         topicName: forumTopic.name,
     });
     await ctx.reply([
         "Created a topic and bound it to the existing thread id.",
         `topic: ${forumTopic.name}`,
         `topic id: ${forumTopic.message_thread_id}`,
-        `thread: ${threadId}`,
+        `thread: ${thread.id}`,
+        `cwd: ${thread.cwd}`,
         "Future messages in this topic will continue on that thread through the Codex SDK.",
     ].join("\n"));
     await postTopicReadyMessage(bot, session, [
         "This topic is now bound to an existing Codex thread id.",
-        `thread: ${threadId}`,
+        `thread: ${thread.id}`,
         "Send a message to continue.",
     ].join("\n"));
 }
@@ -190,3 +210,42 @@ async function createFreshThreadTopic(ctx, deps, requestedName) {
         `model: ${session.model}`,
     ].join("\n"));
 }
+async function listProjectThreads(ctx, deps) {
+    const { projects, store, threadCatalog } = deps;
+    const project = getProjectForContext(ctx, projects);
+    if (!project) {
+        await ctx.reply(PROJECT_REQUIRED_MESSAGE);
+        return;
+    }
+    const threads = await threadCatalog.listProjectThreads({
+        projectRoot: project.cwd,
+        limit: 8,
+    });
+    if (threads.length === 0) {
+        await ctx.reply([
+            "No saved Codex threads were found for this project yet.",
+            `project root: ${project.cwd}`,
+        ].join("\n"));
+        return;
+    }
+    const lines = [
+        `Saved Codex threads for ${project.name}:`,
+        ...threads.flatMap((thread, index) => {
+            const relativeCwd = path.relative(project.cwd, thread.cwd) || ".";
+            const bound = store.getByThreadId(thread.id);
+            return [
+                `${index + 1}. ${thread.preview}`,
+                `   id: ${thread.id}`,
+                `   cwd: ${relativeCwd}`,
+                `   updated: ${thread.updatedAt}`,
+                `   source: ${thread.source ?? "unknown"}`,
+                ...(bound
+                    ? [`   bound: ${bound.telegramTopicName ?? bound.messageThreadId ?? bound.sessionKey}`]
+                    : []),
+            ];
+        }),
+        "",
+        "Resume one with /thread resume <threadId>",
+    ];
+    await ctx.reply(lines.join("\n"));
+}

package/dist/bot/topicCleanup.js

@@ -0,0 +1,80 @@
+import { GrammyError } from "grammy";
+import { sendTypingAction } from "../telegram/delivery.js";
+export async function cleanupMissingTopicBindings(input) {
+    const sessions = input.store.listTopicSessions();
+    const summary = {
+        total: sessions.length,
+        checked: 0,
+        kept: 0,
+        removed: 0,
+        skipped: 0,
+        failed: 0,
+    };
+    for (const session of sessions) {
+        const chatId = Number(session.chatId);
+        const messageThreadId = Number(session.messageThreadId);
+        if (!Number.isSafeInteger(chatId) || !Number.isSafeInteger(messageThreadId)) {
+            summary.skipped += 1;
+            input.logger?.warn("skipped topic binding cleanup for non-numeric telegram identifiers", {
+                sessionKey: session.sessionKey,
+                chatId: session.chatId,
+                messageThreadId: session.messageThreadId,
+            });
+            continue;
+        }
+        summary.checked += 1;
+        try {
+            await sendTypingAction(input.bot, {
+                chatId,
+                messageThreadId,
+            }, input.logger);
+            summary.kept += 1;
+        }
+        catch (error) {
+            if (!isMissingTopicBindingError(error)) {
+                summary.failed += 1;
+                input.logger?.warn("topic binding cleanup probe failed", {
+                    sessionKey: session.sessionKey,
+                    chatId,
+                    messageThreadId,
+                    error,
+                });
+                continue;
+            }
+            input.store.remove(session.sessionKey);
+            summary.removed += 1;
+            input.logger?.info("removed stale telegram topic binding", {
+                sessionKey: session.sessionKey,
+                chatId,
+                messageThreadId,
+                codexThreadId: session.codexThreadId,
+                topicName: session.telegramTopicName,
+            });
+        }
+    }
+    input.logger?.info("topic binding cleanup finished", summary);
+    return summary;
+}
+export function isMissingTopicBindingError(error) {
+    const description = describeError(error);
+    if (!description)
+        return false;
+    return [
+        "message thread not found",
+        "message thread was not found",
+        "forum topic not found",
+        "topic not found",
+        "thread not found",
+        "topic deleted",
+        "topic_deleted",
+    ].some((fragment) => description.includes(fragment));
+}
+function describeError(error) {
+    if (error instanceof GrammyError) {
+        return typeof error.description === "string" ? error.description.toLowerCase() : null;
+    }
+    if (error instanceof Error) {
+        return error.message.toLowerCase();
+    }
+    return typeof error === "string" ? error.toLowerCase() : null;
+}