agent-conveyor 0.1.0

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "agent-conveyor",
+  "version": "0.1.0",
+  "description": "Local agent manager/worker conveyor control plane for Codex sessions.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "conveyor": "dist/cli/main.js",
+    "workerctl": "dist/cli/main.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/program-name.d.ts",
+      "default": "./dist/cli/program-name.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "scripts/capture-static-html-screenshot.mjs",
+    "skills/**/*",
+    "README.md",
+    "docs/typescript-migration/*.md"
+  ],
+  "scripts": {
+    "test": "node dashboard/scripts/run-tests.mjs",
+    "build": "npm run build:cli && npm run build:dashboard",
+    "build:cli": "tsc -p tsconfig.cli.json",
+    "build:dashboard": "tsc -p dashboard/tsconfig.json && vite build --config dashboard/vite.config.ts",
+    "lint": "eslint .",
+    "knip": "npm run build:cli && knip",
+    "migration:audit": "node scripts/ts-migration-audit.mjs",
+    "migration:audit:final": "node scripts/ts-migration-audit.mjs --require-zero-python",
+    "check": "npm run lint && npm run knip && npm test -- --runInBand && npm run build",
+    "dashboard": "tsx dashboard/server/index.ts",
+    "prepack": "rm -rf dist/cli && npm run build:cli",
+    "prepublishOnly": "node scripts/prepublish-guard.mjs"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "keywords": [
+    "agent",
+    "codex",
+    "conveyor",
+    "manager-worker",
+    "workflow-automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neonwatty/agent-conveyor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/neonwatty/agent-conveyor/issues"
+  },
+  "homepage": "https://github.com/neonwatty/agent-conveyor#readme",
+  "dependencies": {
+    "@homebridge/node-pty-prebuilt-multiarch": "^0.13.1",
+    "@playwright/test": "^1.60.0",
+    "@vitejs/plugin-react": "^5.1.0",
+    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/xterm": "^5.5.0",
+    "express": "^5.1.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vite": "^7.2.4",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/express": "^5.0.5",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.6",
+    "@types/react-dom": "^19.2.3",
+    "@types/ws": "^8.18.1",
+    "eslint": "^10.4.1",
+    "globals": "^17.6.0",
+    "knip": "^6.15.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.60.1"
+  }
+}

package/scripts/capture-static-html-screenshot.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+const ERROR_PREFIX = "browser-backed QA requires Playwright/Chromium or a configured browser capture helper";
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 2; index < argv.length; index += 2) {
+    const key = argv[index];
+    const value = argv[index + 1];
+    if (!key || !key.startsWith("--") || value === undefined) {
+      throw new Error("Usage: capture-static-html-screenshot.mjs --html HTML --output PNG --width WIDTH --height HEIGHT");
+    }
+    args[key.slice(2)] = value;
+  }
+  return args;
+}
+
+function parsePositiveInteger(value) {
+  if (!/^[1-9][0-9]*$/.test(value ?? "")) {
+    throw new Error("Usage: capture-static-html-screenshot.mjs --html HTML --output PNG --width WIDTH --height HEIGHT");
+  }
+  return Number(value);
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const htmlPath = args.html;
+  const outputPath = args.output;
+  const width = parsePositiveInteger(args.width);
+  const height = parsePositiveInteger(args.height);
+
+  if (!htmlPath || !outputPath) {
+    throw new Error("Usage: capture-static-html-screenshot.mjs --html HTML --output PNG --width WIDTH --height HEIGHT");
+  }
+
+  const { pathToFileURL } = await import("node:url");
+  const { chromium } = await import("@playwright/test");
+  const launchAttempts = [
+    { backend: "playwright-chromium", options: { headless: true } },
+    { backend: "playwright-chrome-channel", options: { channel: "chrome", headless: true } },
+    {
+      backend: "playwright-chrome-app",
+      options: {
+        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        headless: true,
+      },
+    },
+  ];
+  let browser;
+  let backend;
+  let lastError;
+  for (const attempt of launchAttempts) {
+    try {
+      browser = await chromium.launch(attempt.options);
+      backend = attempt.backend;
+      break;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  if (!browser || !backend) {
+    throw lastError ?? new Error("No browser launch attempt was made.");
+  }
+  try {
+    const page = await browser.newPage({
+      deviceScaleFactor: 1,
+      viewport: { width, height },
+    });
+    await page.goto(pathToFileURL(htmlPath).href, { waitUntil: "load" });
+    await page.screenshot({ path: outputPath, fullPage: false });
+    console.log(JSON.stringify({
+      backend,
+      html_path: htmlPath,
+      screenshot_path: outputPath,
+      viewport: `${width}x${height}`,
+    }));
+  } finally {
+    await browser.close();
+  }
+}
+
+try {
+  await main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`${ERROR_PREFIX}: ${message}`);
+  process.exitCode = 2;
+}

package/skills/codex-review/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: codex-review
+description: "Codex code review closeout: local dirty changes, PR branch vs main, parallel tests."
+---
+
+# Codex Review
+
+Run Codex's built-in code review as a closeout check. This is code review (`codex review`), not Guardian `auto_review` approval routing.
+
+Use when:
+- user asks for Codex review / autoreview / second-model review
+- after non-trivial code edits, before final/commit/ship
+- reviewing a local branch or PR branch after fixes
+
+## Contract
+
+- Treat review output as advisory. Never blindly apply it.
+- Verify every finding by reading the real code path and adjacent files.
+- Read dependency docs/source/types when the finding depends on external behavior.
+- Reject unrealistic edge cases, speculative risks, broad rewrites, and fixes that over-complicate the codebase.
+- Prefer small fixes at the right ownership boundary; no refactor unless it clearly improves the bug class.
+- Keep going until Codex review returns no accepted/actionable findings.
+- If a review-triggered fix changes code, rerun focused tests and rerun Codex review.
+- Never switch or override the review model. If the review hits model capacity, retry the same command a few times with the same model. If it hits sandbox/permission limits, use the helper's `--full-access` option instead of changing models.
+- Stop as soon as the review command/helper exits 0 with no accepted/actionable findings. Do not run an extra direct `codex review` just to get a nicer "clean" line, a second opinion, or clearer closeout wording.
+- Treat the helper's successful exit plus absence of actionable findings as the clean review result, even if the underlying Codex CLI output is terse.
+- If rejecting a finding as intentional/not worth fixing, add a brief inline code comment only when it explains a real invariant or ownership decision that future reviewers should know.
+- Do not push just to review. Push only when the user requested push/ship/PR update.
+
+## Pick Target
+
+Dirty local work:
+
+```bash
+codex review --uncommitted
+```
+
+Use this only when the patch is actually unstaged/staged/untracked in the
+current checkout. For committed, pushed, or PR work, review the branch against
+its base instead; do not force `--mode local` / `--uncommitted` just because the
+helper docs mention dirty work first. A clean `--uncommitted` review only proves
+there is no local patch.
+
+Branch/PR work:
+
+```bash
+git fetch origin
+codex review --base origin/main
+```
+
+Do not pass an inline prompt with `--base`; current CLI rejects `--base` + `[PROMPT]` even though help text is ambiguous. If custom instructions are needed, run the plain base review first, then do a local/manual follow-up pass.
+
+If an open PR exists, use its actual base:
+
+```bash
+base=$(gh pr view --json baseRefName --jq .baseRefName)
+codex review --base "origin/$base"
+```
+
+Committed single change:
+
+```bash
+codex review --commit HEAD
+```
+
+## Parallel Closeout
+
+Format first if formatting can change line locations. Then it is OK to run tests and review in parallel:
+
+```bash
+~/.codex/skills/codex-review/scripts/codex-review --parallel-tests "<focused test command>"
+```
+
+Tradeoff: tests may force code changes that stale the review. If tests or review lead to code edits, rerun the affected tests and rerun review until no accepted/actionable findings remain. Once that rerun exits cleanly, stop; do not spend another long review cycle on redundant confirmation.
+
+## Context Efficiency
+
+Codex review is usually noisy. Default to a subagent filter when subagents are available. Ask it to run the review and return only:
+- actionable findings it accepts
+- findings it rejects, with one-line reason
+- exact files/tests to rerun
+
+Run inline only for tiny changes or when subagents are unavailable.
+
+## Helper
+
+Bundled helper:
+
+```bash
+~/.codex/skills/codex-review/scripts/codex-review --help
+```
+
+The helper:
+- chooses dirty `--uncommitted` first
+- otherwise uses current PR base if `gh pr view` works
+- otherwise uses `origin/main` for non-main branches
+- should be left in `--mode auto` or forced to `--mode branch` for committed/PR work; do not force `--mode local` after committing
+- writes only to stdout unless `--output` or `CODEX_REVIEW_OUTPUT` is set
+- supports `--dry-run` and `--parallel-tests`
+- supports `--full-access` for nested review runs that need localhost bind/listen tests
+- prints `codex-review clean: no accepted/actionable findings reported` when the selected review command exits 0
+
+Recursion guard:
+- The helper exports `CODEX_REVIEW_HELPER_LEVEL=1` to the nested `codex review` process.
+- If a review session tries to invoke the helper again, the helper exits `78` with `nested codex-review invocation blocked`.
+- Use `CODEX_REVIEW_ALLOW_NESTED=1` only for intentional debugging dry runs; do not use it in normal closeout, GoalBuddy conveyor, or PR review flows.
+
+## Final Report
+
+Include:
+- review command used
+- tests/proof run
+- findings accepted/rejected, briefly why
+- the clean review result from the final helper/review run, or why a remaining finding was consciously rejected
+
+Do not run another Codex review solely to improve the final report wording. If the final helper run exited 0 and produced no accepted/actionable findings, report that exact run as clean.

package/skills/codex-review/scripts/codex-review

@@ -0,0 +1,344 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: codex-review [options]
+
+Options:
+  --mode auto|local|branch   Target selection. Default: auto.
+  --base REF                 Base ref for branch review. Default: PR base or origin/main.
+  --codex-bin PATH           Codex binary. Default: codex.
+  --full-access              Run nested Codex review without sandbox/approval prompts.
+  --output FILE              Also save output to file.
+  --parallel-tests CMD       Run review and test command concurrently.
+  --dry-run                  Print selected commands, do not run.
+  -h, --help                 Show help.
+
+Modes:
+  local   codex review --uncommitted
+  branch  codex review --base <base>
+  auto    dirty tree -> local, else PR/current branch -> branch
+EOF
+}
+
+require_option_value() {
+  local option=$1
+  local value=${2-}
+
+  if [[ -z "$value" || "$value" == --* || "$value" == "-h" ]]; then
+    echo "missing value for $option" >&2
+    usage >&2
+    exit 2
+  fi
+}
+
+mode=auto
+base_ref=
+codex_bin=${CODEX_BIN:-codex}
+codex_args=()
+output=${CODEX_REVIEW_OUTPUT:-}
+parallel_tests=
+dry_run=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode)
+      require_option_value "$1" "${2-}"
+      mode=$2
+      shift 2
+      ;;
+    --base)
+      require_option_value "$1" "${2-}"
+      base_ref=$2
+      shift 2
+      ;;
+    --codex-bin)
+      require_option_value "$1" "${2-}"
+      codex_bin=$2
+      shift 2
+      ;;
+    --full-access)
+      codex_args+=(--dangerously-bypass-approvals-and-sandbox)
+      shift
+      ;;
+    --output)
+      require_option_value "$1" "${2-}"
+      output=$2
+      shift 2
+      ;;
+    --parallel-tests)
+      require_option_value "$1" "${2-}"
+      parallel_tests=$2
+      shift 2
+      ;;
+    --dry-run)
+      dry_run=true
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+case "$mode" in
+  auto|local|branch) ;;
+  *)
+    echo "invalid --mode: $mode" >&2
+    exit 2
+    ;;
+esac
+
+nested_level=${CODEX_REVIEW_HELPER_LEVEL:-0}
+allow_nested=${CODEX_REVIEW_ALLOW_NESTED:-}
+if ! [[ "$nested_level" =~ ^[0-9]+$ ]]; then
+  echo "codex-review: invalid CODEX_REVIEW_HELPER_LEVEL=$nested_level" >&2
+  exit 2
+fi
+nested_level_is_nested=false
+if [[ "$nested_level" =~ [1-9] ]]; then
+  nested_level_is_nested=true
+fi
+if [[ "$nested_level_is_nested" == true && "$allow_nested" != "1" ]]; then
+  echo "codex-review refusal: nested codex-review invocation blocked; set CODEX_REVIEW_ALLOW_NESTED=1 only for intentional debugging" >&2
+  exit 78
+fi
+if [[ "$nested_level_is_nested" != true ]]; then
+  export CODEX_REVIEW_HELPER_LEVEL=1
+elif (( ${#nested_level} <= 15 )); then
+  export CODEX_REVIEW_HELPER_LEVEL=$((10#$nested_level + 1))
+else
+  export CODEX_REVIEW_HELPER_LEVEL=2
+fi
+export CODEX_REVIEW_HELPER_PARENT_PID=$$
+
+git rev-parse --show-toplevel >/dev/null
+
+current_branch=$(git branch --show-current 2>/dev/null || true)
+dirty=false
+if [[ -n "$(git status --porcelain)" ]]; then
+  dirty=true
+fi
+
+pr_url=
+if [[ -z "$base_ref" && "$mode" != local ]] && command -v gh >/dev/null 2>&1; then
+  if pr_lines=$(gh pr view --json baseRefName,url --jq '[.baseRefName, .url] | @tsv' 2>/dev/null); then
+    base_name=${pr_lines%%$'\t'*}
+    pr_url=${pr_lines#*$'\t'}
+    if [[ -n "$base_name" ]]; then
+      base_ref="origin/$base_name"
+    fi
+  fi
+fi
+
+if [[ -z "$base_ref" ]]; then
+  base_ref=origin/main
+fi
+
+review_kind=
+if [[ "$mode" == local || ( "$mode" == auto && "$dirty" == true ) ]]; then
+  review_kind=local
+elif [[ "$mode" == branch || ( "$mode" == auto && -n "$current_branch" && "$current_branch" != "main" ) ]]; then
+  review_kind=branch
+else
+  echo "no review target: clean main checkout and no forced mode" >&2
+  exit 1
+fi
+
+if [[ "$review_kind" == local ]]; then
+  review_cmd=("$codex_bin" ${codex_args[@]+"${codex_args[@]}"} review --uncommitted)
+else
+  review_cmd=("$codex_bin" ${codex_args[@]+"${codex_args[@]}"} review --base "$base_ref")
+fi
+
+printf 'codex-review target: %s\n' "$review_kind"
+printf 'branch: %s\n' "${current_branch:-detached}"
+if [[ -n "$pr_url" ]]; then
+  printf 'pr: %s\n' "$pr_url"
+fi
+printf 'review:'
+printf ' %q' "${review_cmd[@]}"
+printf '\n'
+if [[ -n "$parallel_tests" ]]; then
+  printf 'tests: %s\n' "$parallel_tests"
+fi
+if [[ "$review_kind" == branch ]]; then
+  printf 'fetch: git fetch origin --quiet\n'
+fi
+if [[ -n "$output" ]]; then
+  printf 'output: %s\n' "$output"
+fi
+
+if [[ "$dry_run" == true ]]; then
+  exit 0
+fi
+
+if [[ "$review_kind" == branch ]]; then
+  git fetch origin --quiet || {
+    echo "warning: git fetch origin failed; reviewing with existing refs" >&2
+  }
+fi
+
+review_output=$output
+review_output_is_temp=false
+if [[ -z "$review_output" ]]; then
+  review_output=$(mktemp)
+  review_output_is_temp=true
+fi
+
+cleanup() {
+  if [[ "${review_output_is_temp:-false}" == true && -n "${review_output:-}" ]]; then
+    rm -f "$review_output"
+  fi
+}
+trap cleanup EXIT
+
+run_review() {
+  mkdir -p "$(dirname "$review_output")"
+  "${review_cmd[@]}" 2>&1 | tee "$review_output"
+}
+
+elapsed_since() {
+  local started_at=$1
+  local finished_at
+  finished_at=$(date +%s)
+  printf '%s\n' "$((finished_at - started_at))"
+}
+
+format_elapsed() {
+  local seconds=$1
+  if (( seconds < 60 )); then
+    printf '%ss\n' "$seconds"
+  else
+    printf '%sm%ss\n' "$((seconds / 60))" "$((seconds % 60))"
+  fi
+}
+
+review_output_empty() {
+  [[ ! -s "$review_output" ]] || ! grep -q '[^[:space:]]' "$review_output"
+}
+
+review_output_has_findings() {
+  # Codex CLI transcripts include tool output before the final `codex` section.
+  # After the CLI header, prefer the first final-answer marker after the last
+  # Codex diagnostic line; if there are no diagnostics, use the last marker.
+  # Direct/fake review commands are scanned as a whole.
+  awk '
+    {
+      lines[NR] = $0
+      if ($0 ~ /^OpenAI Codex v/) {
+        has_codex_header = 1
+      }
+      if ($0 ~ /^[0-9]{4}-[0-9]{2}-[0-9]{2}T.* (WARN|ERROR) /) {
+        last_diagnostic = NR
+      }
+      if ($0 ~ /\[P[0-3]\]/) {
+        any_finding = 1
+      }
+    }
+    END {
+      if (has_codex_header) {
+        if (last_diagnostic) {
+          for (i = last_diagnostic + 1; i <= NR; i++) {
+            if (lines[i] == "codex") {
+              final_start = i + 1
+              break
+            }
+          }
+        } else {
+          for (i = 1; i <= NR; i++) {
+            if (lines[i] == "codex") {
+              final_start = i + 1
+            }
+          }
+        }
+        if (final_start) {
+          for (i = final_start; i <= NR; i++) {
+            if (lines[i] ~ /\[P[0-3]\]/) {
+              exit 0
+            }
+          }
+          exit 1
+        }
+      }
+      exit any_finding ? 0 : 1
+    }
+  ' "$review_output"
+}
+
+report_clean_review_or_fail() {
+  local elapsed_text
+  elapsed_text=$(format_elapsed "${review_elapsed_seconds:-0}")
+
+  if review_output_has_findings; then
+    printf 'codex-review complete after %s\n' "$elapsed_text"
+    printf 'codex-review findings: accepted/actionable findings reported\n'
+    return 1
+  fi
+  if review_output_empty; then
+    printf 'codex-review complete after %s; no output\n' "$elapsed_text"
+    return 1
+  fi
+  printf 'codex-review complete after %s\n' "$elapsed_text"
+  printf 'codex-review clean: no accepted/actionable findings reported\n'
+}
+
+if [[ -z "$parallel_tests" ]]; then
+  review_started_at=$(date +%s)
+  set +e
+  run_review
+  review_status=$?
+  review_elapsed_seconds=$(elapsed_since "$review_started_at")
+  set -e
+  if [[ "$review_status" == 0 ]]; then
+    report_clean_review_or_fail
+    exit $?
+  fi
+  exit "$review_status"
+fi
+
+review_status_file=$(mktemp)
+review_elapsed_file=$(mktemp)
+tests_status_file=$(mktemp)
+
+(
+  set +e
+  review_started_at=$(date +%s)
+  run_review
+  status=$?
+  elapsed=$(elapsed_since "$review_started_at")
+  printf '%s\n' "$status" > "$review_status_file"
+  printf '%s\n' "$elapsed" > "$review_elapsed_file"
+) &
+review_pid=$!
+
+(
+  set +e
+  bash -lc "$parallel_tests"
+  status=$?
+  printf '%s\n' "$status" > "$tests_status_file"
+) &
+tests_pid=$!
+
+wait "$review_pid" || true
+wait "$tests_pid" || true
+
+review_status=$(cat "$review_status_file")
+review_elapsed_seconds=$(cat "$review_elapsed_file")
+tests_status=$(cat "$tests_status_file")
+rm -f "$review_status_file" "$review_elapsed_file" "$tests_status_file"
+
+printf 'codex-review exit: %s\n' "$review_status"
+printf 'tests exit: %s\n' "$tests_status"
+
+if [[ "$review_status" != 0 || "$tests_status" != 0 ]]; then
+  exit 1
+fi
+
+report_clean_review_or_fail