feat: add live codex healthcheck

Author: MackDing

AGENTS.md

@@ -22,6 +22,7 @@
 - `npm run check`: run the repository typecheck gate.
 - `npm run typecheck`: run `tsc --noEmit` directly.
 - `npm run healthcheck`: run the local runtime health check.
+- `npm run healthcheck:live`: run the live Codex + Telegram health probe when local credentials are configured.
 
 ## Lint And Format
 
@@ -52,5 +53,6 @@
 - Run `npm run format:check`.
 - Run `npm test`.
 - Run `npm run healthcheck`.
+- Run `npm run healthcheck:live` before production-facing releases when real credentials are available.
 - Review `git diff --stat` and `git status --short` for accidental edits.
 - If bot commands or behavior changed, update `README.md` and include a Telegram usage example in the PR or commit notes.

README.md

@@ -83,6 +83,7 @@ npm run lint
 npm run format:check
 npm test
 npm run healthcheck
+npm run healthcheck:live
 ```
 
 ## Development Commands
@@ -98,6 +99,7 @@ npm run healthcheck
 - `npm test` - run the full test suite
 - `npm run healthcheck` - static runtime readiness check
 - `npm run healthcheck:strict` - stricter production-oriented health check
+- `npm run healthcheck:live` - live Codex + Telegram probe against the configured backend and bot token
 - `npm run telegram:smoke` - live Telegram API smoke test when a real bot token is available
 
 ## Architecture
@@ -369,7 +371,7 @@ Recommended local release gate:
 
 ```bash
 npm run ci
-node scripts/healthcheck.js --strict --telegram-live
+node scripts/healthcheck.js --strict --telegram-live --codex-live
 ```
 
 Release references:

package.json

@@ -16,6 +16,7 @@
     "format:check": "prettier --check .",
     "healthcheck": "tsx scripts/healthcheck.js",
     "healthcheck:strict": "tsx scripts/healthcheck.js --strict",
+    "healthcheck:live": "tsx scripts/healthcheck.js --codex-live --telegram-live",
     "telegram:smoke": "tsx scripts/telegramSmoke.js",
     "ci": "npm run check && npm run lint && npm run format:check && npm test && npm run healthcheck"
   },

scripts/healthcheck.js

@@ -4,6 +4,7 @@ import { runHealthcheck } from "../src/ops/healthcheck.js";
 
 const strict = process.argv.includes("--strict");
 const telegramLiveCheck = process.argv.includes("--telegram-live");
+const codexLiveCheck = process.argv.includes("--codex-live");
 
 let config;
 try {
@@ -15,7 +16,8 @@ try {
 
 const result = await runHealthcheck(config, {
   strict,
-  telegramLiveCheck
+  telegramLiveCheck,
+  codexLiveCheck
 });
 
 for (const check of result.checks) {

src/ops/healthcheck.js

@@ -1,7 +1,9 @@
 import fs from "node:fs";
+import { spawn } from "node:child_process";
 import path from "node:path";
 import process from "node:process";
 import { repairNodePtySpawnHelperPermissions } from "../runner/ptyPreflight.js";
+import { extractCodexExecResponse } from "../bot/formatter.js";
 
 function makeCheck(name, status, detail) {
   return { name, status, detail };
@@ -68,6 +70,96 @@ function checkWritableDirectory(name, directoryPath) {
   }
 }
 
+function runCliCodexLiveCheck(config) {
+  return new Promise((resolve, reject) => {
+    const prompt = "Reply with exactly: HEALTHCHECK_OK";
+    const proc = spawn(
+      config.runner.command,
+      [...(config.runner.args || []), "exec", prompt],
+      {
+        cwd: config.runner.cwd,
+        env: process.env
+      }
+    );
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout?.on("data", (chunk) => {
+      stdout += String(chunk || "");
+    });
+    proc.stderr?.on("data", (chunk) => {
+      stderr += String(chunk || "");
+    });
+    proc.on("error", reject);
+    proc.on("close", (code, signal) => {
+      const output = extractCodexExecResponse(`${stdout}\n${stderr}`).trim();
+      if (code !== 0) {
+        reject(
+          new Error(
+            `CLI health check exited with code ${code}, signal ${signal || "none"}`
+          )
+        );
+        return;
+      }
+
+      if (output !== "HEALTHCHECK_OK") {
+        reject(
+          new Error(`Unexpected CLI response: ${output || "(empty output)"}`)
+        );
+        return;
+      }
+
+      resolve({
+        backend: "cli",
+        output
+      });
+    });
+  });
+}
+
+async function runSdkCodexLiveCheck(config) {
+  const { Codex } = await import("@openai/codex-sdk");
+  const codex = new Codex({
+    config: config.runner.sdkConfig
+  });
+  const thread = codex.startThread({
+    workingDirectory: config.runner.cwd,
+    skipGitRepoCheck: config.runner.sdkThreadOptions.skipGitRepoCheck,
+    approvalPolicy: config.runner.sdkThreadOptions.approvalPolicy,
+    sandboxMode: config.runner.sdkThreadOptions.sandboxMode,
+    modelReasoningEffort: config.runner.sdkThreadOptions.modelReasoningEffort,
+    networkAccessEnabled: config.runner.sdkThreadOptions.networkAccessEnabled,
+    webSearchMode: config.runner.sdkThreadOptions.webSearchMode,
+    additionalDirectories: config.runner.sdkThreadOptions.additionalDirectories
+  });
+  const turn = await thread.run("Reply with exactly: HEALTHCHECK_OK");
+
+  if (turn.finalResponse.trim() !== "HEALTHCHECK_OK") {
+    throw new Error(
+      `Unexpected SDK response: ${turn.finalResponse.trim() || "(empty output)"}`
+    );
+  }
+
+  return {
+    backend: "sdk",
+    threadId: thread.id,
+    output: turn.finalResponse.trim()
+  };
+}
+
+async function runCodexLiveCheck(config, options = {}) {
+  if (typeof options.codexLiveRunner === "function") {
+    return options.codexLiveRunner(config);
+  }
+
+  if (config.runner.backend === "sdk") {
+    return runSdkCodexLiveCheck(config);
+  }
+
+  return runCliCodexLiveCheck(config);
+}
+
 export async function runHealthcheck(config, options = {}) {
   const strict = Boolean(options.strict);
   const env = options.env || process.env;
@@ -144,6 +236,30 @@ export async function runHealthcheck(config, options = {}) {
     }
   }
 
+  const codexLiveCheck = Boolean(options.codexLiveCheck);
+  if (codexLiveCheck) {
+    try {
+      const result = await runCodexLiveCheck(config, options);
+      checks.push(
+        makeCheck(
+          "codex live",
+          "pass",
+          `${result.backend} backend responded with ${result.output}${
+            result.threadId ? ` (thread ${result.threadId})` : ""
+          }`
+        )
+      );
+    } catch (error) {
+      checks.push(
+        makeCheck(
+          "codex live",
+          "fail",
+          error instanceof Error ? error.message : String(error)
+        )
+      );
+    }
+  }
+
   const failed = checks.filter((check) => check.status === "fail");
   const warned = checks.filter((check) => check.status === "warn");
 

tests/healthcheck.test.js

@@ -17,8 +17,15 @@ function createConfig(root) {
       botToken: "dummy-token"
     },
     runner: {
+      backend: "sdk",
       command: "node",
-      cwd: root
+      args: [],
+      cwd: root,
+      sdkConfig: {},
+      sdkThreadOptions: {
+        skipGitRepoCheck: true,
+        additionalDirectories: []
+      }
     },
     github: {
       defaultWorkdir: root
@@ -80,3 +87,53 @@ test("runHealthcheck fails when the configured command is missing in strict mode
     true
   );
 });
+
+test("runHealthcheck reports a passing live Codex probe when the backend responds", async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "claws-health-"));
+  const config = createConfig(root);
+
+  const result = await runHealthcheck(config, {
+    env: process.env,
+    codexLiveCheck: true,
+    codexLiveRunner: async () => ({
+      backend: "sdk",
+      threadId: "thread-123",
+      output: "HEALTHCHECK_OK"
+    })
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(
+    result.checks.some(
+      (check) =>
+        check.name === "codex live" &&
+        check.status === "pass" &&
+        check.detail.includes("HEALTHCHECK_OK")
+    ),
+    true
+  );
+});
+
+test("runHealthcheck reports a failing live Codex probe when the backend check fails", async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "claws-health-"));
+  const config = createConfig(root);
+
+  const result = await runHealthcheck(config, {
+    env: process.env,
+    codexLiveCheck: true,
+    codexLiveRunner: async () => {
+      throw new Error("simulated codex failure");
+    }
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(
+    result.checks.some(
+      (check) =>
+        check.name === "codex live" &&
+        check.status === "fail" &&
+        check.detail.includes("simulated codex failure")
+    ),
+    true
+  );
+});