@lapage/codex-telegram-bridge 0.1.0 → 0.1.1

package/.env.example

@@ -1,17 +1,29 @@
+# Required. Telegram bot token from BotFather.
 TELEGRAM_BOT_TOKEN=123456:replace_me
+
+# Required. Allowed Telegram user IDs, comma-separated.
 TELEGRAM_ALLOWED_USER_IDS=123456789
+
+# Codex workspace path. Options: ~, /absolute/path.
 CODEX_CWD=~
+
+# Codex binary. Options: codex, /absolute/path/to/codex.
 CODEX_COMMAND=codex
-CODEX_ARGS=--search --yolo
-CODEX_SUBMIT_KEY=Enter
-CODEX_SUBMIT_DELAY_MS=800
-TMUX_SESSION=codex-telegram-bridge
-CODEX_COLS=120
-CODEX_ROWS=40
-FLUSH_INTERVAL_MS=1200
-POLL_INTERVAL_MS=500
-CODEX_STARTUP_DELAY_MS=1500
+
+# Approval mode. Options: never, on-request, on-failure, untrusted.
+CODEX_APPROVAL_POLICY=never
+
+# Sandbox mode. Options: danger-full-access, workspace-write, read-only.
+CODEX_SANDBOX=danger-full-access
+
+# Stream edit throttle in ms. Options: 500-1500 typical.
 STREAM_EDIT_INTERVAL_MS=650
+
+# Min chars before stream edit. Options: 10-100 typical.
 STREAM_MIN_CHANGE_CHARS=24
+
+# Telegram typing interval in ms. Options: 3000-5000 typical.
 TYPING_INTERVAL_MS=4000
+
+# Max Telegram chunk size. Options: <=3900 recommended.
 MAX_TELEGRAM_CHARS=3500

package/README.md

@@ -2,20 +2,20 @@
 
 Control a local **Codex CLI** session from Telegram without opening any inbound ports to the internet.
 
-This package is useful when Codex runs on a home PC, workstation, homelab box, or private server and you want a simple mobile chat interface. The bridge starts Codex inside a detached `tmux` session, receives Telegram messages from an allowlisted user, sends them into Codex, and relays Codex output back to Telegram.
+This package is useful when Codex runs on a home PC, workstation, homelab box, or private server and you want a simple mobile chat interface. The bridge starts `codex app-server` over stdio, receives Telegram messages from an allowlisted user, sends them into Codex, and streams Codex output back to Telegram.
 
 ## Why Use This
 
 - No public SSH, HTTP, webhook, tunnel, or reverse proxy is required.
 - Telegram provides the outbound connection path from your machine.
-- Codex keeps running in `tmux`, so the session can survive terminal disconnects.
+- Codex uses the app-server JSON-RPC protocol instead of terminal screen scraping.
+- Stdio transport stays local-only and avoids exposing a network listener.
 - Access is restricted to the Telegram user IDs you allowlist.
 
 ## Requirements
 
 - Node.js 22 or newer
 - npm
-- `tmux`
 - Codex CLI available on `PATH`
 - A Telegram bot token from [@BotFather](https://t.me/BotFather)
 - Your numeric Telegram user ID, for example from [@userinfobot](https://t.me/userinfobot)
@@ -25,26 +25,9 @@ Check prerequisites:
 ```sh
 node --version
 npm --version
-tmux -V
 codex --version
 ```
 
-Install `tmux` if it is missing:
-
-```sh
-# macOS
-brew install tmux
-
-# Ubuntu / Debian
-sudo apt update && sudo apt install -y tmux
-
-# Fedora
-sudo dnf install -y tmux
-
-# Arch Linux
-sudo pacman -S tmux
-```
-
 ## Quick Start
 
 Install the package globally:
@@ -87,6 +70,10 @@ codex-telegram-bridge
 
 Open your Telegram bot chat and send `/status`. Any normal message after that is sent to Codex as a prompt.
 
+Codex output updates when app-server reports completed items. The bridge keeps a per-turn cache of completed messages, command summaries, and tool summaries, then edits/splits Telegram messages from that cache until the turn completes.
+
+You can also send screenshots, documents, PDFs, videos, audio, or voice notes. The bridge downloads each attachment to `/tmp/codex-telegram-bridge/` with a random filename, includes the local path in the Codex prompt, and attaches images as `localImage` inputs for Codex vision.
+
 ## Configuration File
 
 By default, the CLI reads:
@@ -111,15 +98,8 @@ CODEX_TELEGRAM_BRIDGE_ENV=/path/to/.env codex-telegram-bridge
 | `TELEGRAM_ALLOWED_USER_IDS` | required | Comma-separated numeric Telegram user IDs allowed to use the bot. |
 | `CODEX_CWD` | current directory | Working directory where Codex starts. `~` is supported. |
 | `CODEX_COMMAND` | `codex` | Codex command or binary path. |
-| `CODEX_ARGS` | `--search --yolo` | Extra Codex startup arguments. |
-| `CODEX_SUBMIT_KEY` | `Enter` | tmux key used to submit a prompt to Codex. |
-| `CODEX_SUBMIT_DELAY_MS` | `800` | Delay after pasting text before pressing submit. |
-| `CODEX_STARTUP_DELAY_MS` | `1500` | Delay before first prompt if Codex has not produced output yet. |
-| `TMUX_SESSION` | `codex-telegram-bridge` | Detached tmux session name. |
-| `CODEX_COLS` | `120` | tmux pane width. |
-| `CODEX_ROWS` | `40` | tmux pane height. |
-| `POLL_INTERVAL_MS` | `500` | How often the bridge polls tmux output. |
-| `FLUSH_INTERVAL_MS` | `1200` | Delay before flushing non-stream fallback output. |
+| `CODEX_APPROVAL_POLICY` | `never` | App-server thread approval policy: `never`, `on-request`, `on-failure`, or `untrusted`. |
+| `CODEX_SANDBOX` | `danger-full-access` | App-server thread sandbox: `danger-full-access`, `workspace-write`, or `read-only`. |
 | `STREAM_EDIT_INTERVAL_MS` | `650` | Minimum interval between Telegram message edits. |
 | `STREAM_MIN_CHANGE_CHARS` | `24` | Minimum text growth before editing mid-response. |
 | `TYPING_INTERVAL_MS` | `4000` | How often to send Telegram typing action. |
@@ -127,38 +107,32 @@ CODEX_TELEGRAM_BRIDGE_ENV=/path/to/.env codex-telegram-bridge
 
 ## Telegram Commands
 
-- `/status` — show bridge state, tmux session, working directory, and Codex command.
+- `/status` — show bridge state, stdio transport, working directory, and Codex command.
 - `/flush` — force-read and relay the latest Codex response.
-- `/interrupt` — send Ctrl-C to Codex.
-- `/restart` — restart the Codex tmux session.
-- `/stop` — stop the Codex tmux session.
+- `/interrupt` — interrupt the active Codex turn.
+- `/restart` — restart Codex app-server.
+- `/stop` — stop Codex app-server.
 - Any other text is sent directly to Codex as a prompt.
 
 ## Running as a Background Service
 
-For a long-running home server setup, run the bridge with your preferred process manager, for example `systemd`, `pm2`, `launchd`, or a persistent `tmux` session.
+For a long-running home server setup, run the bridge with your preferred process manager, for example `systemd`, `pm2`, or `launchd`.
 
-Example with `tmux`:
+Example with `pm2`:
 
 ```sh
-tmux new -s codex-telegram-bridge-runner 'codex-telegram-bridge'
-```
-
-Detach from tmux with:
-
-```text
-Ctrl-b, then d
+pm2 start codex-telegram-bridge --name codex-telegram-bridge
 ```
 
 ## Debugging Codex
 
-The bridge itself runs Codex inside another detached `tmux` session. Attach to it with:
+The bridge runs Codex as a child process with stdio JSON-RPC. To inspect protocol behavior directly, run:
 
 ```sh
-tmux attach -t codex-telegram-bridge
+codex app-server --stdio
 ```
 
-If `TMUX_SESSION` is changed in the config file, use that session name instead.
+The bridge always starts Codex with `app-server --stdio`; `CODEX_COMMAND` only changes the binary path.
 
 ## Install From Source
 
@@ -197,7 +171,7 @@ Recommended safeguards:
 - Do not share your Telegram bot token.
 - Run the bridge under a user account with appropriate file permissions.
 - Point `CODEX_CWD` at a workspace you are comfortable controlling remotely.
-- Understand that `CODEX_ARGS=--yolo` allows Codex to act with fewer confirmations.
+- Understand that `CODEX_APPROVAL_POLICY=never` and `CODEX_SANDBOX=danger-full-access` allow Codex to act with fewer confirmations and broader machine access.
 
 ## Repository
 

package/dist/codex-session.js

@@ -1,9 +1,17 @@
-import { capturePane, runTmux, shellCommand, tmuxSessionExists } from './tmux.js';
-export class CodexSession {
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { createInterface } from 'node:readline';
+export class CodexSession extends EventEmitter {
     config;
+    process = null;
     running = false;
     startPromise = null;
+    requestId = 1;
+    pendingRequests = new Map();
+    threadId = null;
+    activeTurnId = null;
     constructor(config) {
+        super();
         this.config = config;
     }
     get isRunning() {
@@ -13,64 +21,229 @@ export class CodexSession {
         if (this.startPromise) {
             return this.startPromise;
         }
-        this.startPromise = this.startSession().finally(() => {
+        this.startPromise = this.startServer().finally(() => {
             this.startPromise = null;
         });
         return this.startPromise;
     }
     async stop() {
-        if (await this.exists()) {
-            await runTmux(['kill-session', '-t', this.config.tmuxSession]).catch(() => undefined);
-        }
         this.running = false;
+        this.threadId = null;
+        this.activeTurnId = null;
+        for (const pending of this.pendingRequests.values()) {
+            pending.reject(new Error('Codex app-server stopped.'));
+        }
+        this.pendingRequests.clear();
+        if (this.process && !this.process.killed) {
+            this.process.kill('SIGTERM');
+        }
+        this.process = null;
     }
     async restart() {
         await this.stop();
         await this.start();
     }
-    async sendText(text) {
-        await runTmux(['set-buffer', '-b', 'codex-telegram-input', text]);
-        await runTmux(['paste-buffer', '-b', 'codex-telegram-input', '-t', this.config.tmuxSession]);
-        await sleep(this.config.codexSubmitDelayMs);
-        await runTmux(['send-keys', '-t', this.config.tmuxSession, this.config.codexSubmitKey]);
+    async sendText(text, attachments = []) {
+        await this.start();
+        if (!this.threadId) {
+            throw new Error('Codex thread is not ready.');
+        }
+        const input = [{
+                type: 'text',
+                text: textWithAttachmentContext(text, attachments),
+                text_elements: [],
+            }];
+        for (const attachment of attachments) {
+            if (attachment.kind === 'image') {
+                input.push({
+                    type: 'localImage',
+                    path: attachment.path,
+                });
+            }
+        }
+        const result = await this.request('turn/start', {
+            threadId: this.threadId,
+            input,
+        });
+        const turnId = getString(result?.turn?.id);
+        if (turnId) {
+            this.activeTurnId = turnId;
+        }
     }
     async interrupt() {
-        if (await this.exists()) {
-            await runTmux(['send-keys', '-t', this.config.tmuxSession, 'C-c']);
+        if (!this.threadId || !this.activeTurnId) {
+            return;
         }
+        await this.request('turn/interrupt', {
+            threadId: this.threadId,
+            turnId: this.activeTurnId,
+        }).catch(() => undefined);
     }
-    async waitUntilReady(hasOutput) {
-        if (this.config.startupDelayMs > 0 && !hasOutput) {
-            await sleep(this.config.startupDelayMs);
+    async startServer() {
+        if (this.running && this.process && !this.process.killed) {
+            return;
         }
+        this.process = spawn(this.config.codexCommand, ['app-server', '--stdio'], {
+            cwd: this.config.codexCwd,
+            env: process.env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.process.on('exit', (code, signal) => {
+            this.running = false;
+            this.threadId = null;
+            this.activeTurnId = null;
+            this.process = null;
+            for (const pending of this.pendingRequests.values()) {
+                pending.reject(new Error(`Codex app-server exited${code === null ? '' : ` with code ${code}`}.`));
+            }
+            this.pendingRequests.clear();
+            this.emit('exit', code, signal);
+        });
+        this.process.stderr.on('data', (chunk) => {
+            const message = chunk.toString('utf8').trim();
+            if (message) {
+                this.emit('error', message);
+            }
+        });
+        createInterface({ input: this.process.stdout }).on('line', (line) => this.handleLine(line));
+        await this.request('initialize', {
+            clientInfo: {
+                name: 'lapage-codex-telegram-bridge',
+                title: 'LaPage Codex Telegram Bridge',
+                version: '0.1.0',
+            },
+            capabilities: {
+                experimentalApi: false,
+                requestAttestation: false,
+            },
+        });
+        this.notify('initialized');
+        const threadStartResult = await this.request('thread/start', {
+            cwd: this.config.codexCwd,
+            approvalPolicy: this.config.codexApprovalPolicy,
+            sandbox: this.config.codexSandbox,
+            threadSource: 'telegram-bridge',
+            sessionStartSource: 'startup',
+            ephemeral: false,
+        });
+        const threadId = getString(threadStartResult?.thread
+            ?.id);
+        if (!threadId) {
+            throw new Error('Codex app-server did not return a thread id.');
+        }
+        this.threadId = threadId;
+        this.running = true;
     }
-    async exists() {
-        return tmuxSessionExists(this.config.tmuxSession);
+    request(method, params) {
+        if (!this.process?.stdin.writable) {
+            return Promise.reject(new Error('Codex app-server is not running.'));
+        }
+        const id = this.requestId++;
+        const payload = { method, id, params };
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(id, { resolve, reject });
+            this.process.stdin.write(`${JSON.stringify(payload)}\n`, (error) => {
+                if (error) {
+                    this.pendingRequests.delete(id);
+                    reject(error);
+                }
+            });
+        });
     }
-    async capturePane() {
-        return capturePane(this.config.tmuxSession, this.config.rows);
+    notify(method, params) {
+        if (!this.process?.stdin.writable) {
+            return;
+        }
+        const payload = params === undefined ? { method } : { method, params };
+        this.process.stdin.write(`${JSON.stringify(payload)}\n`);
     }
-    async startSession() {
-        if (this.running && await this.exists()) {
+    handleLine(line) {
+        if (!line.trim()) {
             return;
         }
-        await runTmux(['kill-session', '-t', this.config.tmuxSession]).catch(() => undefined);
-        await runTmux([
-            'new-session',
-            '-d',
-            '-s',
-            this.config.tmuxSession,
-            '-c',
-            this.config.codexCwd,
-            '-x',
-            String(this.config.cols),
-            '-y',
-            String(this.config.rows),
-            shellCommand([this.config.codexCommand, ...this.config.codexArgs]),
-        ]);
-        this.running = true;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            this.emit('error', line);
+            return;
+        }
+        if ('id' in message) {
+            this.handleResponse(message);
+            return;
+        }
+        this.handleNotification(message);
+    }
+    handleResponse(response) {
+        const pending = this.pendingRequests.get(response.id);
+        if (!pending) {
+            return;
+        }
+        this.pendingRequests.delete(response.id);
+        if (response.error) {
+            pending.reject(new Error(response.error.message));
+            return;
+        }
+        pending.resolve(response.result);
     }
+    handleNotification(notification) {
+        switch (notification.method) {
+            case 'turn/started': {
+                const turnId = getString(notification.params?.turn
+                    ?.id);
+                if (turnId) {
+                    this.activeTurnId = turnId;
+                }
+                this.emit('turnStarted');
+                return;
+            }
+            case 'item/completed': {
+                const item = notification.params
+                    ?.item;
+                if (isCompletedItem(item)) {
+                    this.emit('itemCompleted', item);
+                }
+                return;
+            }
+            case 'turn/completed': {
+                this.activeTurnId = null;
+                this.emit('turnCompleted');
+                return;
+            }
+            case 'error': {
+                const message = getString(notification.params?.message);
+                if (message) {
+                    this.emit('error', message);
+                }
+                return;
+            }
+            default:
+                return;
+        }
+    }
+}
+function isCompletedItem(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.type === 'string');
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function getString(value) {
+    return typeof value === 'string' ? value : null;
+}
+function textWithAttachmentContext(text, attachments) {
+    const trimmed = text.trim();
+    if (attachments.length === 0) {
+        return trimmed;
+    }
+    const attachmentLines = attachments.map((attachment, index) => {
+        const mime = attachment.mimeType ? `, ${attachment.mimeType}` : '';
+        return `${index + 1}. ${attachment.name} (${attachment.kind}${mime}): ${attachment.path}`;
+    });
+    return [
+        trimmed || 'Please inspect the attached file(s).',
+        '',
+        'Attached file(s) saved locally:',
+        ...attachmentLines,
+    ].join('\n');
 }

package/dist/config.js

@@ -11,25 +11,15 @@ export function readConfig() {
         token,
         allowedUserIds,
         codexCommand: process.env.CODEX_COMMAND || 'codex',
-        codexArgs: parseArgs(process.env.CODEX_ARGS || '--search --yolo'),
-        codexSubmitKey: process.env.CODEX_SUBMIT_KEY || 'Enter',
-        codexSubmitDelayMs: readNumber('CODEX_SUBMIT_DELAY_MS', 800),
         codexCwd: expandHome(process.env.CODEX_CWD || process.cwd()),
-        tmuxSession: process.env.TMUX_SESSION || 'codex-telegram-bridge',
-        cols: readNumber('CODEX_COLS', 120),
-        rows: readNumber('CODEX_ROWS', 40),
-        flushIntervalMs: readNumber('FLUSH_INTERVAL_MS', 1200),
-        pollIntervalMs: readNumber('POLL_INTERVAL_MS', 500),
-        startupDelayMs: readNumber('CODEX_STARTUP_DELAY_MS', 1500),
+        codexApprovalPolicy: process.env.CODEX_APPROVAL_POLICY || 'never',
+        codexSandbox: process.env.CODEX_SANDBOX || 'danger-full-access',
         streamEditIntervalMs: readNumber('STREAM_EDIT_INTERVAL_MS', 650),
         streamMinChangeChars: readNumber('STREAM_MIN_CHANGE_CHARS', 24),
         typingIntervalMs: readNumber('TYPING_INTERVAL_MS', 4000),
         maxTelegramChars: Math.min(readNumber('MAX_TELEGRAM_CHARS', 3500), 3900),
     };
 }
-function parseArgs(value) {
-    return value.split(' ').map((part) => part.trim()).filter(Boolean);
-}
 function readNumber(name, fallback) {
     const value = Number(process.env[name]);
     return Number.isFinite(value) && value > 0 ? value : fallback;

package/dist/env.js

@@ -46,15 +46,8 @@ function readEnvTemplate() {
         'TELEGRAM_ALLOWED_USER_IDS=123456789',
         'CODEX_CWD=~',
         'CODEX_COMMAND=codex',
-        'CODEX_ARGS=--search --yolo',
-        'CODEX_SUBMIT_KEY=Enter',
-        'CODEX_SUBMIT_DELAY_MS=800',
-        'TMUX_SESSION=codex-telegram-bridge',
-        'CODEX_COLS=120',
-        'CODEX_ROWS=40',
-        'FLUSH_INTERVAL_MS=1200',
-        'POLL_INTERVAL_MS=500',
-        'CODEX_STARTUP_DELAY_MS=1500',
+        'CODEX_APPROVAL_POLICY=never',
+        'CODEX_SANDBOX=danger-full-access',
         'STREAM_EDIT_INTERVAL_MS=650',
         'STREAM_MIN_CHANGE_CHARS=24',
         'TYPING_INTERVAL_MS=4000',