Skip to content

code-yeongyu/oh-my-openagent / .agents/skills/codex-qa

codex-qa

Verified

QA the omo Codex Light edition (lazycodex / packages/omo-codex) itself, in strict isolation so ONLY our plugin is exercised, never the user's real ~/.codex. The first-party method drives the real `codex app-server` against an isolated CODEX_HOME plus a LOCAL mock model (no real API call), and proves a plugin hook fired by asserting hook/started + hook/completed notifications. Also: isolated install verification, per-component hook probes, a tmux TUI smoke, and runtime log observation (RUST_LOG / logs SQLite / /debug-config). Ships tested helper scripts each with a --self-test. Use whenever someone changes anything under packages/omo-codex or wants to QA, smoke-test, verify, or debug the Codex plugin, its hooks/components, the installer/config.toml, the app-server flow, or the Codex TUI. Triggers: codex qa, qa codex, codex-qa, test codex plugin, verify codex hook, codex app-server, lazycodex qa, isolated CODEX_HOME, prove codex hook fired, codex tui test.

FileKindSize
SKILL.mdskill md7.6 KB
references/app-server.mdmarkdown3.0 KB
references/components-hooks.mdmarkdown2.7 KB
references/docker-qa.mdmarkdown2.6 KB
references/install-verify.mdmarkdown2.6 KB
references/isolation.mdmarkdown2.5 KB
references/logging-debug.mdmarkdown2.6 KB
scripts/app-server-drive.shexecutablescript3.1 KB
scripts/hook-unit-probe.shexecutablescript3.0 KB
scripts/install-verify.shexecutablescript2.5 KB
scripts/lib/app-server-client.mjsscript6.3 KB
scripts/lib/app-server-client.test.jsscript1.9 KB
scripts/lib/common.shexecutablescript7.1 KB
scripts/lib/mock-model.mjsscript2.1 KB
scripts/lsp-e2e.shexecutablescript150.9 KB
scripts/tui-smoke.shexecutablescript2.9 KB

scripts/lib/app-server-client.mjs

View on GitHub
// app-server-client.mjs - drive a real `codex app-server` turn for QA.
//
// This is the FIRST-PARTY way to QA the omo Codex plugin: instead of scripting
// the TUI, we speak the app-server's own protocol (newline-delimited JSON over
// stdio - NO "jsonrpc" field) and watch the structured notification stream.
//
//   initialize -> initialized -> thread/start -> turn/start
//   ... collect hook/started + hook/completed (plugin proof)
//   ... collect item/completed agentMessage (assistant text)
//   stop on turn/completed (turn.status == "completed" | "failed")
//
// Env (CODEX_HOME is inherited and MUST already point at the isolated home):
//   MOCK_PORT     port of the mock model server (required; no real API call).
//   PROMPT        user message text (default "say hello").
//   QA_CWD        conversation working dir (default process.cwd()).
//   DEADLINE_MS   hard stop (default 60000).
//   EXPECT_HOOK   comma-separated hook eventNames that MUST complete for exit 0
//                 (e.g. "userPromptSubmit,sessionStart"). Empty = only require
//                 turn/completed.
//   CODEX_BIN     codex binary (default "codex"; PATH lookup, no shell function).
//
// Prints a JSON summary to stdout. Exit 0 iff the turn completed, every
// EXPECT_HOOK fired with status "completed", and no hook completed failed.
import { spawn } from "node:child_process"
import { pathToFileURL } from "node:url"

export function parseExpectedHooks(value) {
  return (value || "")
    .split(",")
    .map((s) => s.trim())
    .filter(Boolean)
}

export function summarizeRun({ turnStatus, assistantText, threadId, turnId, expectHook, hooks, stderr }) {
  const completed = new Set(
    hooks.filter((h) => h.method === "hook/completed" && h.status === "completed").map((h) => h.eventName),
  )
  const missingHooks = expectHook.filter((eventName) => !completed.has(eventName))
  const failedHooks = hooks.filter((h) => h.method === "hook/completed" && h.status !== "completed")
  const ok = turnStatus === "completed" && missingHooks.length === 0 && failedHooks.length === 0
  return {
    ok,
    turnStatus,
    assistantText,
    threadId,
    turnId,
    expectHook,
    missingHooks,
    failedHooks,
    hooks,
    stderrTail: stderr.split("\n").slice(-10).join("\n"),
  }
}

function main() {
  const CODEX_BIN = process.env.CODEX_BIN || "codex"
  const MOCK_PORT = process.env.MOCK_PORT
  const PROMPT = process.env.PROMPT || "say hello"
  const CWD = process.env.QA_CWD || process.cwd()
  const DEADLINE_MS = Number(process.env.DEADLINE_MS || 60000)
  const EXPECT = parseExpectedHooks(process.env.EXPECT_HOOK || "")

  if (!MOCK_PORT) {
    console.error("app-server-client: MOCK_PORT is required (start lib/mock-model.mjs first)")
    process.exit(2)
  }

  // Config overrides force codex onto the local mock provider, never the real one.
  const overrides = [
    `model="mock-model"`,
    `model_provider="mock_provider"`,
    `model_providers.mock_provider.name="codex-qa mock"`,
    `model_providers.mock_provider.base_url="http://127.0.0.1:${MOCK_PORT}/v1"`,
    `model_providers.mock_provider.wire_api="responses"`,
    `model_providers.mock_provider.request_max_retries=0`,
    `model_providers.mock_provider.stream_max_retries=0`,
    `approval_policy="never"`,
    `sandbox_mode="read-only"`,
  ]
  const args = overrides.flatMap((o) => ["-c", o]).concat("app-server")

  const child = spawn(CODEX_BIN, args, { stdio: ["pipe", "pipe", "pipe"], env: process.env })
  let stderr = ""
  child.stderr.on("data", (c) => (stderr += c))

  const hooks = []
  let assistantText = null
  let threadId = null
  let turnId = null
  let turnStatus = null
  let buf = ""
  let finished = false

  const send = (obj) => child.stdin.write(JSON.stringify(obj) + "\n")

  function finish() {
    if (finished) return
    finished = true
    try {
      child.kill("SIGTERM")
    } catch (error) {
      const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error)
      stderr += `\n[driver] failed to terminate app-server: ${message}\n`
    }
    const summary = summarizeRun({ turnStatus, assistantText, threadId, turnId, expectHook: EXPECT, hooks, stderr })
    console.log(JSON.stringify(summary, null, 2))
    process.exit(summary.ok ? 0 : 1)
  }

  function handle(msg) {
    if (msg.id === 1 && msg.result) {
      send({ method: "initialized" })
      send({ id: 2, method: "thread/start", params: { cwd: CWD } })
    } else if (msg.id === 2 && msg.result) {
      threadId = msg.result.thread?.id
      send({ id: 3, method: "turn/start", params: { threadId, input: [{ type: "text", text: PROMPT }] } })
    } else if (msg.id === 3 && msg.result) {
      turnId = msg.result.turn?.id
    } else if (msg.method === "hook/started" || msg.method === "hook/completed") {
      const run = msg.params?.run || {}
      hooks.push({
        method: msg.method,
        eventName: run.eventName,
        status: run.status,
        source: run.source ?? run.pluginId,
        pluginId: run.pluginId,
        hookName: run.hookName ?? run.name,
        runId: run.id,
      })
    } else if (msg.method === "item/completed") {
      const item = msg.params?.item
      if (item?.type === "agentMessage" && typeof item.text === "string") assistantText = item.text
    } else if (msg.method === "turn/completed") {
      turnStatus = msg.params?.turn?.status
      finish()
    }
  }

  child.stdout.on("data", (chunk) => {
    buf += chunk
    let nl
    while ((nl = buf.indexOf("\n")) >= 0) {
      const line = buf.slice(0, nl).trim()
      buf = buf.slice(nl + 1)
      if (!line) continue
      let msg
      try {
        msg = JSON.parse(line)
      } catch (error) {
        if (error instanceof SyntaxError) continue
        throw error
      }
      handle(msg)
    }
  })
  child.on("exit", (code) => {
    if (finished) return
    console.log(
      JSON.stringify(
        { ok: false, exitCode: code, turnStatus, hooks, stderrTail: stderr.split("\n").slice(-15).join("\n") },
        null,
        2,
      ),
    )
    process.exit(1)
  })

  send({
    id: 1,
    method: "initialize",
    params: {
      clientInfo: { name: "codex-qa", version: "0.1.0" },
      capabilities: { experimentalApi: true, requestAttestation: false },
    },
  })
  setTimeout(() => {
    stderr += "\n[driver] deadline reached\n"
    finish()
  }, DEADLINE_MS)
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  main()
}
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 321kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 321kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 321kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall