codex-to-im 0.1.0

package/references/token-validation.md

@@ -0,0 +1,44 @@
+# Token Validation Commands
+
+After writing config.env, validate each enabled platform's credentials to catch typos and configuration errors early.
+
+## Telegram
+
+```bash
+curl -s "https://api.telegram.org/bot${TOKEN}/getMe"
+```
+Expected: response contains `"ok":true`. If not, the Bot Token is invalid — re-check with @BotFather.
+
+## Discord
+
+Verify token format matches: `[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+`
+
+A format mismatch means the token was copied incorrectly from the Discord Developer Portal.
+
+## Feishu / Lark
+
+```bash
+curl -s -X POST "${DOMAIN}/open-apis/auth/v3/tenant_access_token/internal" \
+  -H "Content-Type: application/json" \
+  -d '{"app_id":"...","app_secret":"..."}'
+```
+Expected: response contains `"code":0`. If not, check that App ID and App Secret match the Feishu Developer Console.
+
+## QQ
+
+Step 1 — Get access token:
+```bash
+curl -s -X POST "https://bots.qq.com/app/getAppAccessToken" \
+  -H "Content-Type: application/json" \
+  -d '{"appId":"...","clientSecret":"..."}'
+```
+Expected: response contains `access_token`.
+
+Step 2 — Verify gateway connectivity:
+```bash
+curl -s "https://api.sgroup.qq.com/gateway" \
+  -H "Authorization: QQBot <access_token>"
+```
+Expected: response contains a gateway URL.
+
+If either step fails, verify the App ID and App Secret from https://q.qq.com.

package/references/troubleshooting.md

@@ -0,0 +1,88 @@
+# Troubleshooting
+
+## Bridge won't start
+
+**Symptoms**: Starting the bridge from the local workbench fails, or the daemon exits immediately.
+
+**Steps**:
+
+1. Run the local doctor script or inspect the workbench logs to identify the issue
+2. Check that Node.js >= 20 is installed: `node --version`
+3. Check that Claude Code CLI is available: `claude --version`
+4. Verify config exists: `ls -la ~/.codex-to-im/config.env`
+5. Check logs for startup errors in `~/.codex-to-im/logs/`
+
+**Common causes**:
+- Missing or invalid config.env -- open the local workbench and save a valid configuration
+- Node.js not found or wrong version -- install Node.js >= 20
+- Port or resource conflict -- check if another bridge instance is already running
+
+## Messages not received
+
+**Symptoms**: Bot is online but doesn't respond to messages.
+
+**Steps**:
+
+1. Verify the bot token is valid with the local workbench test tools or doctor script
+2. Check allowed user IDs in config -- if set, only listed users can interact
+3. For Telegram: ensure you've sent `/start` to the bot first
+4. For Discord: verify the bot has been invited to the server with message read permissions
+5. For Feishu: confirm the app has been approved and event subscriptions are configured
+6. Check recent logs for incoming message events under `~/.codex-to-im/logs/`
+
+## Feishu streaming cards not working
+
+**Symptoms**: Feishu responds only with a final message, or the streaming card never appears even though `Enable Feishu streaming response cards` is checked.
+
+**Steps**:
+
+1. Check `~/.codex-to-im/logs/bridge.log` or `~/.claude-to-im/logs/bridge.log`
+2. Look for Feishu error `99991672`
+3. If the error mentions `cardkit:card:write`, add and publish the missing Feishu permissions:
+   - `cardkit:card:write`
+   - `cardkit:card:read`
+   - `im:message:update`
+4. Restart the bridge after the Feishu app version is approved
+
+**Important behavior note**:
+
+- If card creation is denied, the bridge falls back to a normal final-result message
+- Even after the Feishu permissions are fixed, the current `codex` runtime usually delivers assistant text when the turn completes, not token-by-token
+- That means Feishu streaming cards currently work best for `Thinking` / tool-progress updates, while the final response text may still appear all at once
+
+## Permission timeout
+
+**Symptoms**: Claude Code session starts but times out waiting for tool approval.
+
+**Steps**:
+
+1. The bridge runs Claude Code in non-interactive mode; ensure your Claude Code configuration allows the necessary tools
+2. Consider using `--allowedTools` in your configuration to pre-approve common tools
+3. Check network connectivity if the timeout occurs during API calls
+
+## High memory usage
+
+**Symptoms**: The daemon process consumes increasing memory over time.
+
+**Steps**:
+
+1. Check current bridge status from the local workbench
+2. Restart the daemon to reset memory:
+   ```
+   Stop the bridge, then start it again from the local workbench
+   ```
+3. If the issue persists, check how many concurrent sessions are active -- each Claude Code session consumes memory
+4. Review logs for error loops that may cause memory leaks
+
+## Stale PID file
+
+**Symptoms**: Status shows "running" but the process doesn't exist, or start refuses because it thinks a daemon is already running.
+
+The daemon management script (`daemon.sh`) handles stale PID files automatically. If you still encounter issues:
+
+1. Stop the bridge from the local workbench — this should clean up the stale PID file
+2. If stop also fails, manually remove the PID file:
+   ```bash
+   rm ~/.codex-to-im/runtime/bridge.pid
+   ```
+3. Start the bridge again from the local workbench

package/references/usage.md

@@ -0,0 +1,46 @@
+# Optional Codex Integration Usage
+
+This repository no longer uses a full bridge-management skill as its primary workflow.
+
+The main product is the local `codex-to-im` app and web workbench.
+
+`SKILL.md` is only an optional Codex integration entry with two actions:
+
+- `open`
+- `share-feishu`
+
+## open
+
+Open the local `codex-to-im` workbench.
+
+Preferred command:
+
+```bash
+codex-to-im open
+```
+
+Fallback:
+
+```bash
+node dist/cli.mjs open
+```
+
+## share-feishu
+
+Open the Feishu handoff flow for the current workflow.
+
+Preferred command:
+
+```bash
+codex-to-im share-feishu
+```
+
+Fallback:
+
+```bash
+node dist/cli.mjs share-feishu
+```
+
+## Non-goals
+
+If the user asks to configure credentials, start or stop the bridge, inspect logs, or diagnose problems, do not route them through the optional Codex integration. Open the local app instead.

package/scripts/build.js

@@ -0,0 +1,36 @@
+import * as esbuild from 'esbuild';
+
+const common = {
+  bundle: true,
+  platform: 'node',
+  format: 'esm',
+  target: 'node20',
+  external: [
+    // SDK must stay external — it spawns a CLI subprocess and resolves
+    // dist/cli.js relative to its own package location. Bundling it
+    // breaks that path resolution.
+    '@anthropic-ai/claude-agent-sdk',
+    '@openai/codex-sdk',
+    // discord.js optional native deps
+    'bufferutil', 'utf-8-validate', 'zlib-sync', 'erlpack',
+    // Node.js built-ins
+    'fs', 'path', 'os', 'crypto', 'http', 'https', 'net', 'tls',
+    'stream', 'events', 'url', 'util', 'child_process', 'worker_threads',
+    'node:*',
+  ],
+  banner: { js: "import { createRequire } from 'module'; const require = createRequire(import.meta.url);" },
+};
+
+async function build(entryPoint, outfile) {
+  await esbuild.build({
+    ...common,
+    entryPoints: [entryPoint],
+    outfile,
+  });
+}
+
+await build('src/main.ts', 'dist/daemon.mjs');
+await build('src/ui-server.ts', 'dist/ui-server.mjs');
+await build('src/cli.ts', 'dist/cli.mjs');
+
+console.log('Built dist/daemon.mjs, dist/ui-server.mjs, dist/cli.mjs');

package/scripts/daemon.ps1

@@ -0,0 +1,16 @@
+<#
+.SYNOPSIS
+  Windows entry point — delegates to supervisor-windows.ps1.
+.DESCRIPTION
+  Usage:  powershell -File scripts\daemon.ps1 start|stop|status|logs|install-service|uninstall-service
+#>
+param(
+    [Parameter(Position=0)]
+    [string]$Command = 'help',
+
+    [Parameter(Position=1)]
+    [int]$LogLines = 50
+)
+
+$supervisorScript = Join-Path (Split-Path -Parent $PSCommandPath) 'supervisor-windows.ps1'
+& $supervisorScript $Command $LogLines

package/scripts/daemon.sh

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+set -euo pipefail
+CTI_HOME="${CTI_HOME:-$HOME/.claude-to-im}"
+SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+PID_FILE="$CTI_HOME/runtime/bridge.pid"
+STATUS_FILE="$CTI_HOME/runtime/status.json"
+LOG_FILE="$CTI_HOME/logs/bridge.log"
+
+# ── Common helpers ──
+
+ensure_dirs() { mkdir -p "$CTI_HOME"/{data,logs,runtime,data/messages}; }
+
+ensure_built() {
+  local need_build=0
+  if [ ! -f "$SKILL_DIR/dist/daemon.mjs" ]; then
+    need_build=1
+  else
+    # Check if any source file is newer than the bundle
+    local newest_src
+    newest_src=$(find "$SKILL_DIR/src" -name '*.ts' -newer "$SKILL_DIR/dist/daemon.mjs" 2>/dev/null | head -1)
+    if [ -n "$newest_src" ]; then
+      need_build=1
+    fi
+    # Also check if node_modules/claude-to-im was updated (npm update)
+    # — its code is bundled into dist, so changes require a rebuild
+    if [ "$need_build" = "0" ] && [ -d "$SKILL_DIR/node_modules/claude-to-im/src" ]; then
+      local newest_dep
+      newest_dep=$(find "$SKILL_DIR/node_modules/claude-to-im/src" -name '*.ts' -newer "$SKILL_DIR/dist/daemon.mjs" 2>/dev/null | head -1)
+      if [ -n "$newest_dep" ]; then
+        need_build=1
+      fi
+    fi
+  fi
+  if [ "$need_build" = "1" ]; then
+    echo "Building daemon bundle..."
+    (cd "$SKILL_DIR" && npm run build)
+  fi
+}
+
+# Clean environment for subprocess isolation.
+clean_env() {
+  unset CLAUDECODE 2>/dev/null || true
+
+  local runtime
+  runtime=$(grep "^CTI_RUNTIME=" "$CTI_HOME/config.env" 2>/dev/null | head -1 | cut -d= -f2- | tr -d "'" | tr -d '"' || true)
+  runtime="${runtime:-claude}"
+
+  local mode="${CTI_ENV_ISOLATION:-inherit}"
+  if [ "$mode" = "strict" ]; then
+    case "$runtime" in
+      codex)
+        while IFS='=' read -r name _; do
+          case "$name" in ANTHROPIC_*) unset "$name" 2>/dev/null || true ;; esac
+        done < <(env)
+        ;;
+      claude)
+        # Keep ANTHROPIC_* (from config.env) — needed for third-party API providers.
+        # Strip OPENAI_* to avoid cross-runtime leakage.
+        while IFS='=' read -r name _; do
+          case "$name" in OPENAI_*) unset "$name" 2>/dev/null || true ;; esac
+        done < <(env)
+        ;;
+      auto)
+        # Keep both ANTHROPIC_* and OPENAI_* for auto mode
+        ;;
+    esac
+  fi
+}
+
+read_pid() {
+  [ -f "$PID_FILE" ] && cat "$PID_FILE" 2>/dev/null || echo ""
+}
+
+pid_alive() {
+  local pid="$1"
+  [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null
+}
+
+status_running() {
+  [ -f "$STATUS_FILE" ] && grep -q '"running"[[:space:]]*:[[:space:]]*true' "$STATUS_FILE" 2>/dev/null
+}
+
+show_last_exit_reason() {
+  if [ -f "$STATUS_FILE" ]; then
+    local reason
+    reason=$(grep -o '"lastExitReason"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATUS_FILE" 2>/dev/null | head -1 | sed 's/.*: *"//;s/"$//')
+    [ -n "$reason" ] && echo "Last exit reason: $reason"
+  fi
+}
+
+show_failure_help() {
+  echo ""
+  echo "Recent logs:"
+  tail -20 "$LOG_FILE" 2>/dev/null || echo "  (no log file)"
+  echo ""
+  echo "Next steps:"
+  echo "  1. Run diagnostics:  bash \"$SKILL_DIR/scripts/doctor.sh\""
+  echo "  2. Check full logs:  bash \"$SKILL_DIR/scripts/daemon.sh\" logs 100"
+  echo "  3. Rebuild bundle:   cd \"$SKILL_DIR\" && npm run build"
+}
+
+# ── Load platform-specific supervisor ──
+
+case "$(uname -s)" in
+  Darwin)
+    # shellcheck source=supervisor-macos.sh
+    source "$SKILL_DIR/scripts/supervisor-macos.sh"
+    ;;
+  MINGW*|MSYS*|CYGWIN*)
+    # Windows detected via Git Bash / MSYS2 / Cygwin — delegate to PowerShell
+    echo "Windows detected. Delegating to supervisor-windows.ps1..."
+    powershell.exe -ExecutionPolicy Bypass -File "$SKILL_DIR/scripts/supervisor-windows.ps1" "$@"
+    exit $?
+    ;;
+  *)
+    # shellcheck source=supervisor-linux.sh
+    source "$SKILL_DIR/scripts/supervisor-linux.sh"
+    ;;
+esac
+
+# ── Commands ──
+
+case "${1:-help}" in
+  start)
+    ensure_dirs
+    ensure_built
+
+    # Check if already running (supervisor-aware: launchctl on macOS, PID on Linux)
+    if supervisor_is_running; then
+      EXISTING_PID=$(read_pid)
+      echo "Bridge already running${EXISTING_PID:+ (PID: $EXISTING_PID)}"
+      cat "$STATUS_FILE" 2>/dev/null
+      exit 1
+    fi
+
+    # Source config.env BEFORE clean_env so that CTI_ANTHROPIC_PASSTHROUGH
+    # and other CTI_* flags are available when clean_env checks them.
+    [ -f "$CTI_HOME/config.env" ] && set -a && source "$CTI_HOME/config.env" && set +a
+
+    clean_env
+    echo "Starting bridge..."
+    supervisor_start
+
+    # Poll for up to 10 seconds waiting for status.json to report running
+    STARTED=false
+    for _ in $(seq 1 10); do
+      sleep 1
+      if status_running; then
+        STARTED=true
+        break
+      fi
+      # If supervisor process already died, stop waiting
+      if ! supervisor_is_running; then
+        break
+      fi
+    done
+
+    if [ "$STARTED" = "true" ]; then
+      NEW_PID=$(read_pid)
+      echo "Bridge started${NEW_PID:+ (PID: $NEW_PID)}"
+      cat "$STATUS_FILE" 2>/dev/null
+    else
+      echo "Failed to start bridge."
+      supervisor_is_running || echo "  Process not running."
+      status_running || echo "  status.json not reporting running=true."
+      show_last_exit_reason
+      show_failure_help
+      exit 1
+    fi
+    ;;
+
+  stop)
+    if supervisor_is_managed; then
+      echo "Stopping bridge..."
+      supervisor_stop
+      echo "Bridge stopped"
+    else
+      PID=$(read_pid)
+      if [ -z "$PID" ]; then echo "No bridge running"; exit 0; fi
+      if pid_alive "$PID"; then
+        kill "$PID"
+        for _ in $(seq 1 10); do
+          pid_alive "$PID" || break
+          sleep 1
+        done
+        pid_alive "$PID" && kill -9 "$PID"
+        echo "Bridge stopped"
+      else
+        echo "Bridge was not running (stale PID file)"
+      fi
+      rm -f "$PID_FILE"
+    fi
+    ;;
+
+  status)
+    # Platform-specific status info (prints launchd/service state)
+    supervisor_status_extra
+
+    # Process status: supervisor-aware (launchctl on macOS, PID on Linux)
+    if supervisor_is_running; then
+      PID=$(read_pid)
+      echo "Bridge process is running${PID:+ (PID: $PID)}"
+      # Business status from status.json
+      if status_running; then
+        echo "Bridge status: running"
+      else
+        echo "Bridge status: process alive but status.json not reporting running"
+      fi
+      cat "$STATUS_FILE" 2>/dev/null
+    else
+      echo "Bridge is not running"
+      [ -f "$PID_FILE" ] && rm -f "$PID_FILE"
+      show_last_exit_reason
+    fi
+    ;;
+
+  logs)
+    N="${2:-50}"
+    tail -n "$N" "$LOG_FILE" 2>/dev/null | sed -E 's/(token|secret|password)(["\\x27]?\s*[:=]\s*["\\x27]?)[^ "]+/\1\2*****/gi'
+    ;;
+
+  *)
+    echo "Usage: daemon.sh {start|stop|status|logs [N]}"
+    ;;
+esac

package/scripts/doctor.ps1

@@ -0,0 +1,27 @@
+<#
+.SYNOPSIS
+  Windows wrapper for the existing bash-based doctor script.
+.DESCRIPTION
+  Prefers Git Bash / bash.exe when available. Falls back to a clear message
+  when bash is missing, because the full diagnostics live in doctor.sh.
+#>
+
+$ErrorActionPreference = 'Stop'
+
+$doctorScript = Join-Path (Split-Path -Parent $PSCommandPath) 'doctor.sh'
+
+if (-not (Test-Path $doctorScript)) {
+    Write-Error "doctor.sh not found at $doctorScript"
+    exit 1
+}
+
+$bash = Get-Command bash -ErrorAction SilentlyContinue
+if (-not $bash) {
+    Write-Host "bash was not found in PATH."
+    Write-Host "Install Git Bash or another bash environment, then run:"
+    Write-Host "  bash `"$doctorScript`""
+    exit 1
+}
+
+& $bash.Source $doctorScript
+exit $LASTEXITCODE