@blunking/codexlink 0.1.0

package/start-codex.cmd

@@ -0,0 +1,2 @@
+@echo off
+call "%~dp0blun-codex.cmd" %*

package/telegram-doctor.ps1

@@ -0,0 +1,125 @@
+param(
+  [string]$Profile = "default"
+)
+
+$ErrorActionPreference = "Stop"
+
+function Read-DotEnvFile {
+  param([string]$Path)
+  $values = @{}
+  if (-not (Test-Path $Path)) { return $values }
+  foreach ($line in (Get-Content -Path $Path)) {
+    if (-not $line) { continue }
+    if ($line.Trim().StartsWith("#")) { continue }
+    $parts = $line -split "=", 2
+    if ($parts.Count -ne 2) { continue }
+    $values[$parts[0].Trim()] = $parts[1]
+  }
+  return $values
+}
+
+function Add-Check {
+  param(
+    [System.Collections.Generic.List[object]]$List,
+    [string]$Name,
+    [string]$Status,
+    [string]$Detail
+  )
+  $List.Add([pscustomobject]@{
+    name = $Name
+    status = $Status
+    detail = $Detail
+  }) | Out-Null
+}
+
+$runtimeRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
+$profilePath = Join-Path $runtimeRoot ("profiles\" + $Profile.ToLower() + ".json")
+$checks = New-Object 'System.Collections.Generic.List[object]'
+
+if (Test-Path $profilePath) {
+  Add-Check -List $checks -Name "profile_file" -Status "ok" -Detail $profilePath
+} else {
+  Add-Check -List $checks -Name "profile_file" -Status "fail" -Detail ("Missing profile: " + $profilePath)
+}
+
+$statusRaw = & powershell -ExecutionPolicy Bypass -File (Join-Path $runtimeRoot "telegram-status.ps1") -Profile $Profile
+$status = $statusRaw | ConvertFrom-Json
+
+$nodeCommand = Get-Command node -ErrorAction SilentlyContinue
+$codexCommand = Get-Command codex -ErrorAction SilentlyContinue
+Add-Check -List $checks -Name "node" -Status $(if ($nodeCommand) { "ok" } else { "fail" }) -Detail $(if ($nodeCommand) { $nodeCommand.Source } else { "node not found in PATH" })
+Add-Check -List $checks -Name "codex" -Status $(if ($codexCommand) { "ok" } else { "fail" }) -Detail $(if ($codexCommand) { $codexCommand.Source } else { "codex not found in PATH" })
+
+if ($status.plugin_root) {
+  Add-Check -List $checks -Name "telegram_plugin_root" -Status "ok" -Detail $status.plugin_root
+} else {
+  Add-Check -List $checks -Name "telegram_plugin_root" -Status "fail" -Detail "Telegram plugin root could not be resolved."
+}
+
+if ($status.state_dir -and (Test-Path $status.state_dir)) {
+  Add-Check -List $checks -Name "state_dir" -Status "ok" -Detail $status.state_dir
+} else {
+  Add-Check -List $checks -Name "state_dir" -Status "fail" -Detail ("Missing state dir: " + $status.state_dir)
+}
+
+$activeEnv = Read-DotEnvFile -Path (Join-Path $status.state_dir ".env")
+$legacyEnv = Read-DotEnvFile -Path (Join-Path $env:USERPROFILE ".codex\channels\codexlink-telegram\.env")
+$tokenSource = if ($activeEnv["BLUN_TELEGRAM_BOT_TOKEN"]) {
+  "active_state_env"
+} elseif ($legacyEnv["BLUN_TELEGRAM_BOT_TOKEN"]) {
+  "legacy_env_fallback"
+} else {
+  ""
+}
+Add-Check -List $checks -Name "bot_token" -Status $(if ($tokenSource) { "ok" } else { "fail" }) -Detail $(if ($tokenSource) { $tokenSource } else { "No BLUN_TELEGRAM_BOT_TOKEN found in active or legacy env files." })
+
+Add-Check -List $checks -Name "app_server_ws" -Status $(if ($status.active_ws) { "ok" } else { "warn" }) -Detail $(if ($status.active_ws) { $status.active_ws } else { "No active websocket recorded." })
+Add-Check -List $checks -Name "bound_thread" -Status $(if ($status.active_thread_id) { "ok" } else { "warn" }) -Detail $(if ($status.active_thread_id) { $status.active_thread_id } else { "No active thread bound yet." })
+Add-Check -List $checks -Name "poller" -Status $(if ($status.poller_alive) { "ok" } else { "warn" }) -Detail ("pid=" + [string]$status.poller_pid + " alive=" + [string]$status.poller_alive)
+Add-Check -List $checks -Name "dispatcher" -Status $(if ($status.dispatcher_alive) { "ok" } else { "warn" }) -Detail ("pid=" + [string]$status.dispatcher_pid + " alive=" + [string]$status.dispatcher_alive)
+Add-Check -List $checks -Name "responder" -Status $(if ($status.responder_alive) { "ok" } else { "warn" }) -Detail ("pid=" + [string]$status.responder_pid + " alive=" + [string]$status.responder_alive)
+
+if ($status.last_inbound) {
+  $lastInboundSummary = [string]::Format(
+    "chat={0} message={1} type={2} thread={3}",
+    $status.last_inbound.chatId,
+    $status.last_inbound.messageId,
+    $status.last_inbound.chatType,
+    $(if ($status.last_inbound.telegramThreadId) { $status.last_inbound.telegramThreadId } else { "-" })
+  )
+  Add-Check -List $checks -Name "last_inbound" -Status "ok" -Detail $lastInboundSummary
+} else {
+  Add-Check -List $checks -Name "last_inbound" -Status "warn" -Detail "No inbound Telegram message recorded yet."
+}
+
+if ($status.last_outbound) {
+  $lastOutboundSummary = [string]::Format(
+    "chat={0} message={1} reply_to={2} thread={3}",
+    $status.last_outbound.chatId,
+    $status.last_outbound.messageId,
+    $(if ($status.last_outbound.replyToMessageId) { $status.last_outbound.replyToMessageId } else { "-" }),
+    $(if ($status.last_outbound.telegramThreadId) { $status.last_outbound.telegramThreadId } else { "-" })
+  )
+  Add-Check -List $checks -Name "last_outbound" -Status "ok" -Detail $lastOutboundSummary
+} else {
+  Add-Check -List $checks -Name "last_outbound" -Status "warn" -Detail "No outbound Telegram message recorded yet."
+}
+
+Add-Check -List $checks -Name "queue" -Status $(if (([int]$status.queue_depth -eq 0) -and ([int]$status.pending_reply_depth -eq 0)) { "ok" } else { "warn" }) -Detail ("queued=" + $status.queue_depth + " submitted=" + $status.submitted_depth + " pending_replies=" + $status.pending_reply_depth)
+
+$overall = "ok"
+if (@($checks | Where-Object { $_.status -eq "fail" }).Count -gt 0) {
+  $overall = "fail"
+} elseif (@($checks | Where-Object { $_.status -eq "warn" }).Count -gt 0) {
+  $overall = "warn"
+}
+
+[ordered]@{
+  profile = $status.profile
+  overall = $overall
+  runtime_root = $runtimeRoot
+  state_dir = $status.state_dir
+  plugin_root = $status.plugin_root
+  checks = $checks
+  status = $status
+} | ConvertTo-Json -Depth 8

package/telegram-plugin/.codex-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "codexlink-telegram",
+  "description": "BLUN Telegram bridge for one visible CLI session. Queues inbound messages, binds the live thread, and sends explicit replies without a shadow bot.",
+  "version": "0.1.0",
+  "keywords": ["blun", "telegram", "codexlink", "bridge", "mcp"]
+}

package/telegram-plugin/.env.example

@@ -0,0 +1,9 @@
+BLUN_TELEGRAM_AGENT_NAME=default
+BLUN_TELEGRAM_BOT_TOKEN=123456789:replace_me
+BLUN_TELEGRAM_ALLOWED_CHAT_ID=1605241602
+BLUN_TELEGRAM_CODEX_BIN=codex
+BLUN_TELEGRAM_STATE_DIR=
+BLUN_TELEGRAM_THREAD_ID=
+BLUN_TELEGRAM_RESUME_TIMEOUT_MS=15000
+BLUN_TELEGRAM_POLL_INTERVAL_MS=5000
+BLUN_TELEGRAM_INJECT_INTERVAL_MS=15000

package/telegram-plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "codexlink_telegram": {
+      "command": "node",
+      "args": ["./server.js"]
+    }
+  }
+}

package/telegram-plugin/README.md

@@ -0,0 +1,68 @@
+# CodexLink Telegram Plugin
+
+This is the bundled Telegram plugin for CodexLink.
+
+It is intentionally **not** an autonomous answer bot.
+
+## What it does
+
+- polls Telegram updates into a local queue
+- stores inbound and outbound history under a local state directory
+- keeps private chats and group threads separated
+- binds a live thread id
+- injects the next queued Telegram message into that exact live thread
+- sends explicit manual replies from the visible operator session
+
+## What it does not do
+
+- no hidden second session
+- no autonomous answer loop
+- no background reply worker pretending to be the operator
+
+## State
+
+Default state directory:
+
+`%USERPROFILE%\\.codex\\channels\\codexlink-telegram`
+
+Files created there:
+
+- `.env`
+- `state.json`
+- `inbox.jsonl`
+- `outbox.jsonl`
+- `activity.log`
+- `prompts/`
+- `responses/`
+- `poller.pid`
+- `dispatcher.pid`
+- `responder.pid`
+
+## Env
+
+Copy `.env.example` to `.env` in the state directory or export env vars:
+
+- `BLUN_TELEGRAM_AGENT_NAME`
+- `BLUN_TELEGRAM_BOT_TOKEN`
+- `BLUN_TELEGRAM_ALLOWED_CHAT_ID`
+- `BLUN_TELEGRAM_CODEX_BIN`
+- `BLUN_TELEGRAM_THREAD_ID`
+- `BLUN_TELEGRAM_RESUME_TIMEOUT_MS`
+
+## Tools
+
+- `bridge_status`
+- `bridge_bind_current_thread`
+- `bridge_poll_once`
+- `bridge_list_queue`
+- `bridge_inject_next`
+- `bridge_reply`
+- `bridge_relay_once`
+- `bridge_tail_activity`
+
+## Runtime split
+
+- `poller.js` only fetches Telegram updates into the queue
+- `dispatcher.js` only retries queue delivery into the bound live thread
+- `responder.js` only relays finished answers back out
+- none of them are allowed to invent an answer on their own

package/telegram-plugin/app-server-cli.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { listLoadedThreadsOverWs, readThreadOverWs, startTextTurnOverWs, startThreadOverWs } from "./lib/app-server-client.js";
+
+function writeLine(stream, text) {
+  return new Promise((resolve, reject) => {
+    stream.write(text, (error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+function parseArgs(argv) {
+  const [command = "", ...rest] = argv;
+  const args = { _: [], command };
+  for (let i = 0; i < rest.length; i += 1) {
+    const token = rest[i];
+    if (!token.startsWith("--")) {
+      args._.push(token);
+      continue;
+    }
+    const key = token.slice(2);
+    const next = rest[i + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+      continue;
+    }
+    args[key] = next;
+    i += 1;
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.command === "start-thread") {
+    const result = await startThreadOverWs({
+      wsUrl: args["ws-url"],
+      cwd: args.cwd,
+      model: args.model,
+      sandbox: args.sandbox,
+      approvalPolicy: args["approval-policy"],
+      personality: args.personality,
+      timeoutMs: args["timeout-ms"]
+    });
+    await writeLine(process.stdout, `${JSON.stringify(result)}\n`);
+    return 0;
+  }
+
+  if (args.command === "start-turn") {
+    const result = await startTextTurnOverWs({
+      wsUrl: args["ws-url"],
+      threadId: args["thread-id"],
+      text: args.text || "",
+      model: args.model,
+      effort: args.effort,
+      personality: args.personality,
+      timeoutMs: args["timeout-ms"]
+    });
+    await writeLine(process.stdout, `${JSON.stringify(result)}\n`);
+    return 0;
+  }
+
+  if (args.command === "read-thread") {
+    const result = await readThreadOverWs({
+      wsUrl: args["ws-url"],
+      threadId: args["thread-id"],
+      timeoutMs: args["timeout-ms"]
+    });
+    await writeLine(process.stdout, `${JSON.stringify(result)}\n`);
+    return 0;
+  }
+
+  if (args.command === "list-loaded") {
+    const result = await listLoadedThreadsOverWs({
+      wsUrl: args["ws-url"],
+      timeoutMs: args["timeout-ms"]
+    });
+    await writeLine(process.stdout, `${JSON.stringify(result)}\n`);
+    return 0;
+  }
+
+  await writeLine(process.stderr, "Usage: node app-server-cli.js <start-thread|start-turn|read-thread|list-loaded> [--key value]\n");
+  return 1;
+}
+
+try {
+  const code = await main();
+  process.exit(typeof code === "number" ? code : 0);
+} catch (error) {
+  const message = error?.stack || error?.message || String(error);
+  await writeLine(process.stderr, `${message}\n`);
+  process.exit(1);
+}

package/telegram-plugin/dispatcher.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { injectNext } from "./lib/bridge.js";
+
+const intervalMs = Number.parseInt(process.env.BLUN_TELEGRAM_INJECT_INTERVAL_MS || "1500", 10) || 1500;
+let stopping = false;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+process.on("SIGINT", () => {
+  stopping = true;
+});
+
+process.on("SIGTERM", () => {
+  stopping = true;
+});
+
+async function main() {
+  while (!stopping) {
+    try {
+      const result = await injectNext("");
+      if (result.status !== "empty") {
+        console.log(JSON.stringify({ ts: new Date().toISOString(), kind: "inject", result }));
+      }
+    } catch (error) {
+      console.error(JSON.stringify({
+        ts: new Date().toISOString(),
+        kind: "error",
+        error: `${error}`
+      }));
+    }
+    await sleep(intervalMs);
+  }
+}
+
+await main();

package/telegram-plugin/lib/app-server-client.js

@@ -0,0 +1,290 @@
+function normalizeWsUrl(rawUrl) {
+  const value = String(rawUrl || "").trim();
+  if (!value) {
+    throw new Error("App-server websocket URL is missing.");
+  }
+  return value;
+}
+
+function makeError(message, meta = {}) {
+  const error = new Error(message);
+  Object.assign(error, meta);
+  return error;
+}
+
+function parseJson(data) {
+  const text = typeof data === "string" ? data : Buffer.from(data).toString("utf8");
+  return JSON.parse(text);
+}
+
+function buildInitializeRequest(id) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    method: "initialize",
+    params: {
+      clientInfo: {
+        name: "codexlink-telegram",
+        version: "0.2.0"
+      },
+      capabilities: {
+        experimentalApi: true
+      }
+    }
+  };
+}
+
+function buildInitializedNotification() {
+  return {
+    jsonrpc: "2.0",
+    method: "initialized"
+  };
+}
+
+function extractThreadId(response) {
+  return response?.result?.thread?.id
+    || response?.result?.threadId
+    || response?.result?.id
+    || "";
+}
+
+function extractTurnId(response) {
+  return response?.result?.turn?.id
+    || response?.result?.turnId
+    || response?.result?.id
+    || "";
+}
+
+function extractThreadPath(response) {
+  return response?.result?.thread?.path
+    || response?.result?.path
+    || "";
+}
+
+export class AppServerClient {
+  constructor(wsUrl, options = {}) {
+    this.wsUrl = normalizeWsUrl(wsUrl);
+    this.timeoutMs = Number.parseInt(String(options.timeoutMs || "15000"), 10) || 15000;
+    this.socket = null;
+    this.pending = new Map();
+    this.nextId = 1;
+    this.connected = false;
+  }
+
+  async connect() {
+    if (this.connected && this.socket?.readyState === WebSocket.OPEN) {
+      return;
+    }
+
+    const socket = new WebSocket(this.wsUrl);
+    this.socket = socket;
+
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(makeError(`Timed out connecting to ${this.wsUrl}`));
+      }, this.timeoutMs);
+
+      socket.addEventListener("open", () => {
+        clearTimeout(timer);
+        resolve();
+      }, { once: true });
+
+      socket.addEventListener("error", (event) => {
+        clearTimeout(timer);
+        reject(makeError(`WebSocket connection failed for ${this.wsUrl}`, { cause: event?.error || event }));
+      }, { once: true });
+    });
+
+    socket.addEventListener("message", (event) => {
+      let message;
+      try {
+        message = parseJson(event.data);
+      } catch (error) {
+        return;
+      }
+
+      if (message && Object.prototype.hasOwnProperty.call(message, "id")) {
+        const key = String(message.id);
+        const pending = this.pending.get(key);
+        if (!pending) {
+          return;
+        }
+        this.pending.delete(key);
+        clearTimeout(pending.timer);
+        if (message.error) {
+          pending.reject(makeError(message.error.message || "App-server request failed.", {
+            code: message.error.code,
+            data: message.error.data
+          }));
+          return;
+        }
+        pending.resolve(message);
+      }
+    });
+
+    socket.addEventListener("close", () => {
+      this.connected = false;
+      for (const [key, pending] of this.pending.entries()) {
+        clearTimeout(pending.timer);
+        pending.reject(makeError("App-server websocket closed before request completed."));
+        this.pending.delete(key);
+      }
+    });
+
+    const initId = String(this.nextId++);
+    const initPromise = this._waitForResponse(initId);
+    await this._sendRaw(buildInitializeRequest(Number(initId)));
+    const initializeResponse = await initPromise;
+    if (!initializeResponse?.result) {
+      throw makeError("App-server initialize returned no result.");
+    }
+    await this._sendRaw(buildInitializedNotification());
+
+    this.connected = true;
+  }
+
+  async request(method, params, options = {}) {
+    await this.connect();
+    const id = String(this.nextId++);
+    const payload = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      params
+    };
+
+    const responsePromise = this._waitForResponse(id, options.timeoutMs);
+    await this._sendRaw(payload);
+    return responsePromise;
+  }
+
+  async close() {
+    if (!this.socket) {
+      return;
+    }
+    try {
+      this.socket.close();
+    } catch {
+      // Ignore shutdown errors.
+    }
+    this.connected = false;
+    this.socket = null;
+  }
+
+  async _sendRaw(payload) {
+    const text = JSON.stringify(payload);
+    this.socket.send(text);
+  }
+
+  _waitForResponse(id, timeoutOverride) {
+    const timeoutMs = Number.parseInt(String(timeoutOverride || this.timeoutMs), 10) || this.timeoutMs;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(makeError(`App-server request ${id} timed out.`));
+      }, timeoutMs);
+
+      this.pending.set(id, { resolve, reject, timer });
+    });
+  }
+}
+
+export async function startThreadOverWs(options) {
+  const client = new AppServerClient(options.wsUrl, { timeoutMs: options.timeoutMs || 20000 });
+  try {
+    const response = await client.request("thread/start", {
+      cwd: options.cwd || null,
+      model: options.model || null,
+      sandbox: options.sandbox || null,
+      approvalPolicy: options.approvalPolicy || null,
+      personality: options.personality || null,
+      threadSource: "user",
+      sessionStartSource: "startup"
+    }, { timeoutMs: options.timeoutMs || 20000 });
+
+    const threadId = extractThreadId(response);
+    if (!threadId) {
+      throw makeError("App-server thread/start returned no thread id.");
+    }
+
+    return {
+      ok: true,
+      threadId,
+      response
+    };
+  } finally {
+    await client.close();
+  }
+}
+
+export async function startTextTurnOverWs(options) {
+  const client = new AppServerClient(options.wsUrl, { timeoutMs: options.timeoutMs || 20000 });
+  try {
+    const response = await client.request("turn/start", {
+      threadId: options.threadId,
+      input: [
+        {
+          type: "text",
+          text: options.text
+        }
+      ],
+      model: options.model || null,
+      effort: options.effort || null,
+      personality: options.personality || null
+    }, { timeoutMs: options.timeoutMs || 20000 });
+
+    return {
+      ok: true,
+      busy: false,
+      turnId: extractTurnId(response),
+      response
+    };
+  } catch (error) {
+    const details = `${error?.message || error}`.toLowerCase();
+    const busy = details.includes("active turn")
+      || details.includes("cannot accept")
+      || details.includes("already running")
+      || details.includes("busy");
+
+    return {
+      ok: false,
+      busy,
+      error
+    };
+  } finally {
+    await client.close();
+  }
+}
+
+export async function readThreadOverWs(options) {
+  const client = new AppServerClient(options.wsUrl, { timeoutMs: options.timeoutMs || 10000 });
+  try {
+    const response = await client.request("thread/read", {
+      threadId: options.threadId
+    }, { timeoutMs: options.timeoutMs || 10000 });
+    const threadId = extractThreadId(response);
+    return {
+      ok: Boolean(threadId),
+      threadId,
+      threadPath: extractThreadPath(response),
+      response
+    };
+  } finally {
+    await client.close();
+  }
+}
+
+export async function listLoadedThreadsOverWs(options) {
+  const client = new AppServerClient(options.wsUrl, { timeoutMs: options.timeoutMs || 10000 });
+  try {
+    const response = await client.request("thread/loaded/list", {}, { timeoutMs: options.timeoutMs || 10000 });
+    const data = Array.isArray(response?.result?.data) ? response.result.data : [];
+    return {
+      ok: true,
+      data,
+      response
+    };
+  } finally {
+    await client.close();
+  }
+}