@tutar/graph-engineering 0.3.0

package/templates/pr-review/.github/graph-engineering/codex-compatible-executor.mjs

@@ -0,0 +1,130 @@
+import { readFile } from "node:fs/promises";
+
+import { SUPPORTED_ACTION_NAMES } from "./pr-review-contract.mjs";
+
+const DEFINITION = "github-pr-review/current";
+const PROFILE = "github-pr-review/codex/current";
+const ACTION_SOURCE = "tutar/codex-action";
+const ACTION_COMMIT = "f33581290086e62dc34d420a7f1862477fc2b503";
+const ACTION_SOURCE_REF = "fix/runner-login-no-proxy";
+const ACTION_UPSTREAM = {
+  source: "openai/codex-action",
+  commit: "86365089eb2b84e0a8fb0717b304f8bdcb13b20e",
+};
+const ACTION_PATCH = "read-proxy-server-info-only-with-openai-api-key";
+const CODEX_VERSION = "0.153.4";
+const RUNNER_LABELS = ["self-hosted", "Linux", "X64", "codex"];
+const ACTION_USES = `${ACTION_SOURCE}@${ACTION_COMMIT}`;
+
+export function resolveCompatibleExecution({ config, profile }) {
+  try {
+    validateProfile(profile);
+    validateConfiguration(config, profile);
+    return {
+      definition: config.definition,
+      profile: config.profile,
+      runnerLabels: [...RUNNER_LABELS],
+      events: structuredClone(config.events),
+      eventPrompt: config.eventPrompt.trim(),
+      action: {
+        uses: ACTION_USES,
+        codexVersion: CODEX_VERSION,
+        model: config.codex.model.trim(),
+        effort: config.codex.effort,
+        safetyStrategy: config.codex.safetyStrategy,
+      },
+      check: structuredClone(config.check),
+    };
+  } catch (error) {
+    throw new Error(`configuration-handoff: ${error.message}`);
+  }
+}
+
+export async function loadBundledCompatibility() {
+  const contracts = await readBundledContracts();
+  return resolveCompatibleExecution(contracts);
+}
+
+export async function readBundledContracts() {
+  const [config, profile] = await Promise.all([
+    readFile(new URL("./pr-review-config.json", import.meta.url), "utf8"),
+    readFile(new URL("./codex-compatibility-profile.json", import.meta.url), "utf8"),
+  ]);
+  return { config: JSON.parse(config), profile: JSON.parse(profile) };
+}
+
+function validateProfile(profile) {
+  assertExactKeys(profile, ["definition", "profile", "executor", "runner", "authentication", "action", "mapping", "outputs", "permissions", "consumerConfiguration", "validation"], "Profile");
+  if (profile.definition !== DEFINITION) throw new Error("Profile definition does not match the Executor version");
+  if (profile.profile !== PROFILE) throw new Error("Profile identity does not match the Executor version");
+  assertExactKeys(profile.executor, ["id", "version"], "Profile executor");
+  if (profile.executor?.id !== "codex-compatible-executor" || profile.executor?.version !== "current") throw new Error("Profile executor does not match the bundled Executor");
+  assertJsonEqual(profile.runner, { labels: RUNNER_LABELS }, "runner");
+  assertJsonEqual(profile.authentication, { mode: "runner-backed-codex", credentialSource: "default-codex-home", repositorySecret: false }, "authentication");
+  if (profile.action?.source !== ACTION_SOURCE || profile.action?.sourceRef !== ACTION_SOURCE_REF) throw new Error("Profile Action source or source ref does not match the bundled Executor");
+  assertExactKeys(profile.action, ["source", "sourceRef", "commit", "upstream", "patch", "codexVersion", "requiredInputs", "acceptedInputs"], "Profile Action");
+  if (profile.action.commit !== ACTION_COMMIT) throw new Error("Profile Action commit does not match the bundled Executor");
+  assertJsonEqual(profile.action.upstream, ACTION_UPSTREAM, "Action upstream base");
+  if (profile.action.patch !== ACTION_PATCH) throw new Error("Profile Action patch does not match the bundled Executor");
+  if (profile.action.codexVersion !== CODEX_VERSION) throw new Error("Profile Codex version does not match the bundled Executor");
+  assertJsonEqual(profile.action.requiredInputs, ["prompt-file", "output-schema-file", "working-directory", "codex-version", "safety-strategy"], "required inputs");
+  assertJsonEqual(profile.action.acceptedInputs, ["prompt-file", "output-schema-file", "working-directory", "codex-version", "model", "effort", "permission-profile", "safety-strategy"], "accepted inputs");
+  assertJsonEqual(profile.mapping, {
+    goalPrompt: "prompt-file",
+    reviewSchema: "output-schema-file",
+    codexVersion: "codex-version",
+    workingDirectory: "working-directory",
+    model: "model",
+    reasoningEffort: "effort",
+    safetyStrategy: "safety-strategy",
+    terminal: "step-outcome",
+    finalMessage: "final-message",
+  }, "mapping");
+  assertJsonEqual(profile.outputs, ["final-message"], "outputs");
+  assertJsonEqual(profile.permissions.reviewJob, { contents: "read", "pull-requests": "read", checks: "read" }, "review permissions");
+  assertJsonEqual(profile.permissions.publishJob, { contents: "read", "pull-requests": "read", checks: "write" }, "publish permissions");
+  assertJsonEqual(profile.consumerConfiguration, {
+    pullRequestActions: SUPPORTED_ACTION_NAMES,
+    manualDispatch: "boolean",
+    includeDrafts: [false],
+    modelPattern: "^[A-Za-z0-9._-]*$",
+    reasoningEfforts: ["", "low", "medium", "high", "xhigh"],
+    safetyStrategies: ["read-only"],
+    checkTextMaxLength: 100,
+  }, "consumer configuration");
+  assertJsonEqual(profile.validation, {
+    failClosed: true,
+    resultSchema: "review-result.schema.json",
+    terminals: ["completed", "handoff", "failed", "cancelled"],
+  }, "validation rules");
+}
+
+function validateConfiguration(config, profile) {
+  assertExactKeys(config, ["definition", "profile", "events", "eventPrompt", "codex", "check"], "configuration");
+  if (config.definition !== DEFINITION) throw new Error("configuration definition does not match this current task");
+  if (config.profile !== profile.profile) throw new Error("configuration profile does not match the bundled Profile");
+  assertExactKeys(config.events, ["pullRequestActions", "manualDispatch", "includeDrafts"], "events");
+  if (!Array.isArray(config.events.pullRequestActions) || !config.events.pullRequestActions.every((action) => profile.consumerConfiguration.pullRequestActions.includes(action)) || new Set(config.events.pullRequestActions).size !== config.events.pullRequestActions.length) throw new Error("events.pullRequestActions contains an unsupported or duplicate event");
+  if (typeof config.events.manualDispatch !== "boolean") throw new Error("events.manualDispatch must be boolean");
+  if (!profile.consumerConfiguration.includeDrafts.includes(config.events.includeDrafts)) throw new Error("events.includeDrafts must remain false for this current task");
+  if (typeof config.eventPrompt !== "string" || !config.eventPrompt.trim()) throw new Error("eventPrompt is required");
+  assertExactKeys(config.codex, ["model", "effort", "safetyStrategy"], "codex");
+  if (typeof config.codex.model !== "string" || !new RegExp(profile.consumerConfiguration.modelPattern).test(config.codex.model)) throw new Error("codex.model contains unsupported characters");
+  if (!profile.consumerConfiguration.reasoningEfforts.includes(config.codex.effort)) throw new Error("codex.effort is not allowed");
+  if (!profile.consumerConfiguration.safetyStrategies.includes(config.codex.safetyStrategy)) throw new Error("codex.safetyStrategy must remain read-only");
+  assertExactKeys(config.check, ["name", "title"], "check");
+  for (const key of ["name", "title"]) {
+    if (typeof config.check[key] !== "string" || !config.check[key].trim() || config.check[key].length > profile.consumerConfiguration.checkTextMaxLength) throw new Error(`check.${key} must be a non-empty string of at most ${profile.consumerConfiguration.checkTextMaxLength} characters`);
+  }
+}
+
+function assertExactKeys(value, expected, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) throw new Error(`${label} contains missing or forbidden fields`);
+}
+
+function assertJsonEqual(actual, expected, label) {
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) throw new Error(`Profile ${label} does not match the bundled Executor`);
+}

package/templates/pr-review/.github/graph-engineering/github-api.mjs

@@ -0,0 +1,20 @@
+export async function githubRequest(path, { method = "GET", body, token = required("GH_TOKEN") } = {}) {
+  const response = await fetch(`${process.env.GITHUB_API_URL ?? "https://api.github.com"}${path}`, {
+    method,
+    headers: {
+      Accept: "application/vnd.github+json",
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      "X-GitHub-Api-Version": "2022-11-28",
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!response.ok) throw new Error(`GitHub API ${path} returned ${response.status}`);
+  return response.status === 204 ? null : response.json();
+}
+
+function required(name) {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+}

package/templates/pr-review/.github/graph-engineering/pr-review-case.mjs

@@ -0,0 +1,125 @@
+import { CHECK_NAME } from "./check-publication.mjs";
+
+export function formGoalPrompt({ eventPrompt, pullRequest }) {
+  return `${eventPrompt.trim()}
+
+Use the Consumer Project's installed \`code-review\` Skill to review:
+- repository: ${pullRequest.repository}
+- PR #${pullRequest.number}
+- base SHA: ${pullRequest.baseSha}
+- head SHA: ${pullRequest.headSha}
+- requested change: read \`pr-review-context.md\`
+
+Report Standards and Spec as separate axes using the supplied candidate review output schema.
+
+Always include standards, spec, and handoff. For completed review, provide both axis objects and handoff=null. For handoff, set both axes to null and provide a nonempty handoff summary. Never mix review axes with a handoff.
+
+If the review cannot be completed from the available trusted facts, return the schema's handoff form with a concrete summary. Do not claim to publish, comment, label, push, or otherwise write to GitHub.
+
+Completion Condition: finish only after both axes have a verdict and findings, and the result identifies the exact repository, PR, base SHA, and head SHA above.`;
+}
+
+export function mapActionExecution({ actionOutcome, finalMessage }, target) {
+  if (actionOutcome === "cancelled") {
+    return { terminal: "cancelled", diagnostic: "agent-action: execution was cancelled" };
+  }
+  if (actionOutcome !== "success") {
+    return { terminal: "failed", diagnostic: `agent-action: execution ended with ${actionOutcome || "an unknown outcome"}` };
+  }
+
+  let candidate;
+  try {
+    if (!finalMessage?.trim()) throw new Error("empty final-message");
+    candidate = JSON.parse(finalMessage);
+  } catch (error) {
+    return { terminal: "failed", diagnostic: `candidate-output: ${error.message}` };
+  }
+
+  try {
+    assertExactKeys(candidate, ["repository", "pullRequestNumber", "baseSha", "headSha", "standards", "spec", "handoff"]);
+    assertTrustedTarget(candidate, target);
+    if (candidate.handoff !== null) {
+      if (candidate.standards !== null || candidate.spec !== null) throw new Error("handoff must not contain review axes");
+      assertExactKeys(candidate.handoff, ["summary"]);
+      if (typeof candidate.handoff.summary !== "string" || !candidate.handoff.summary.trim()) {
+        throw new Error("handoff summary is missing");
+      }
+      return { terminal: "handoff", diagnostic: `goal-handoff: ${candidate.handoff.summary.trim()}` };
+    }
+
+    const { handoff, ...reviewCandidate } = candidate;
+    assertCandidateReview(reviewCandidate, target);
+    return {
+      terminal: "completed",
+      review: {
+        ...reviewCandidate,
+        runtime: {
+          terminal: "completed",
+          summary: "tutar/codex-action completed and returned a validated final-message.",
+        },
+      },
+    };
+  } catch (error) {
+    return { terminal: "failed", diagnostic: `candidate-output: ${error.message}` };
+  }
+}
+
+export function assertReviewResult(review, target) {
+  assertExactKeys(review, ["repository", "pullRequestNumber", "baseSha", "headSha", "standards", "spec", "runtime"]);
+  assertTrustedTarget(review, target);
+  for (const axis of ["standards", "spec"]) {
+    if (!review[axis] || typeof review[axis] !== "object") {
+      throw new Error(`review output is missing the ${axis} axis`);
+    }
+    assertExactKeys(review[axis], ["verdict", "findings"]);
+    if (!["pass", "fail"].includes(review[axis].verdict)
+      || !Array.isArray(review[axis].findings)
+      || !review[axis].findings.every((finding) => typeof finding === "string" && finding.trim())) {
+      throw new Error(`review output is missing the ${axis} axis`);
+    }
+  }
+  if (!review.runtime || review.runtime.terminal !== "completed" || !review.runtime.summary) {
+    throw new Error("Candidate review output Runtime terminal is not completed");
+  }
+}
+
+function assertCandidateReview(candidate, target) {
+  assertExactKeys(candidate, ["repository", "pullRequestNumber", "baseSha", "headSha", "standards", "spec"]);
+  assertReviewResult({
+    ...candidate,
+    runtime: { terminal: "completed", summary: "validated" },
+  }, target);
+}
+
+function assertTrustedTarget(candidate, target) {
+  if (
+    candidate.repository !== target.repository
+    || candidate.pullRequestNumber !== target.number
+    || candidate.baseSha !== target.baseSha
+    || candidate.headSha !== target.headSha
+  ) throw new Error("target does not match trusted GitHub facts");
+}
+
+function assertExactKeys(value, expected) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected an object");
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+    throw new Error(`unexpected fields: expected ${wanted.join(", ")}`);
+  }
+}
+
+export function buildCheck(review, target, settings = { name: CHECK_NAME, title: "PR Review" }) {
+  assertReviewResult(review, target);
+  return {
+    name: settings.name,
+    title: settings.title,
+    repository: target.repository,
+    pullRequestNumber: target.number,
+    headSha: target.headSha,
+    conclusion: review.standards.verdict === "pass" && review.spec.verdict === "pass" ? "success" : "failure",
+    standards: review.standards,
+    spec: review.spec,
+    runtime: review.runtime,
+  };
+}

package/templates/pr-review/.github/graph-engineering/pr-review-config.json

@@ -0,0 +1,19 @@
+{
+  "definition": "github-pr-review/current",
+  "profile": "github-pr-review/codex/current",
+  "events": {
+    "pullRequestActions": ["opened", "reopened", "synchronize", "ready_for_review"],
+    "manualDispatch": true,
+    "includeDrafts": false
+  },
+  "eventPrompt": "Review this change against the repository rules and its requested behavior.",
+  "codex": {
+    "model": "",
+    "effort": "",
+    "safetyStrategy": "read-only"
+  },
+  "check": {
+    "name": "Graph Engineering / PR Review",
+    "title": "PR Review"
+  }
+}

package/templates/pr-review/.github/graph-engineering/pr-review-contract.mjs

@@ -0,0 +1,2 @@
+export const SUPPORTED_ACTION_NAMES = ["opened", "reopened", "synchronize", "ready_for_review"];
+export const SUPPORTED_ACTIONS = new Set(SUPPORTED_ACTION_NAMES);

package/templates/pr-review/.github/graph-engineering/prepare-review.mjs

@@ -0,0 +1,50 @@
+import { writeFile } from "node:fs/promises";
+
+import { githubRequest } from "./github-api.mjs";
+import { formGoalPrompt } from "./pr-review-case.mjs";
+
+const repository = required("GITHUB_REPOSITORY");
+const pullRequestNumber = Number.parseInt(required("PULL_REQUEST_NUMBER"), 10);
+if (!Number.isInteger(pullRequestNumber) || pullRequestNumber < 1) throw new Error("PULL_REQUEST_NUMBER must be positive");
+
+const pull = await githubRequest(`/repos/${repository}/pulls/${pullRequestNumber}`);
+if (pull.head?.repo?.full_name !== repository) throw new Error("Only same-repository pull requests are supported");
+const checks = await githubRequest(`/repos/${repository}/commits/${pull.head.sha}/check-runs`);
+const target = {
+  repository,
+  number: pullRequestNumber,
+  baseSha: pull.base.sha,
+  headSha: pull.head.sha,
+  baseRef: pull.base.ref,
+  headRef: pull.head.ref,
+};
+
+await writeFile("pr-review-target.json", `${JSON.stringify(target, null, 2)}\n`);
+await writeFile("pr-review-context.md", [
+  `# PR #${pullRequestNumber}: ${pull.title}`,
+  "",
+  pull.body || "No pull request description was provided.",
+  "",
+  `Base branch: ${target.baseRef}`,
+  `Head branch: ${target.headRef}`,
+  `Existing Checks on head: ${(checks.check_runs ?? []).map((check) => `${check.name}=${check.conclusion ?? check.status}`).join(", ") || "none"}`,
+  "",
+].join("\n"));
+await writeFile("pr-review-goal.md", `${formGoalPrompt({
+  eventPrompt: required("EVENT_PROMPT"),
+  pullRequest: target,
+})}\n`);
+if (process.env.GITHUB_OUTPUT) {
+  await writeFile(process.env.GITHUB_OUTPUT, [
+    `base_sha=${target.baseSha}`,
+    `head_sha=${target.headSha}`,
+    `target_json=${JSON.stringify(target)}`,
+    "",
+  ].join("\n"), { flag: "a" });
+}
+
+function required(name) {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+}

package/templates/pr-review/.github/graph-engineering/publish-review.mjs

@@ -0,0 +1,103 @@
+import { readFile, writeFile } from "node:fs/promises";
+
+import { githubRequest } from "./github-api.mjs";
+import { loadBundledCompatibility } from "./codex-compatible-executor.mjs";
+import { planCheckPublication } from "./check-publication.mjs";
+import { buildCheck } from "./pr-review-case.mjs";
+
+try {
+  await publish();
+} catch (error) {
+  await writeDiagnostic(error.message);
+  throw error;
+}
+
+async function publish() {
+  const compatible = await loadBundledCompatibility();
+  const upstreamResult = process.env.UPSTREAM_RESULT ?? "success";
+  if (upstreamResult !== "success") {
+    const execution = await readOptionalJson("pr-review-artifact/review-execution.json");
+    throw new Error(execution?.diagnostic ?? `upstream-review: review job ended with ${upstreamResult}`);
+  }
+
+  const target = JSON.parse(await readFile("pr-review-artifact/pr-review-target.json", "utf8"));
+  const review = JSON.parse(await readFile("pr-review-artifact/review-result.json", "utf8"));
+  const check = buildCheck(review, target, compatible.check);
+
+  const current = await githubRequest(`/repos/${target.repository}/pulls/${target.number}`);
+  if (current.head.sha !== target.headSha) throw new Error("stale-target: PR head changed before publication");
+  const checks = await readCheckHistory(target, check.name);
+  const publication = planCheckPublication({ target, existingChecks: checks, checkName: check.name });
+
+  // History queries can take multiple requests. Recheck freshness before writing.
+  const beforeWrite = await githubRequest(`/repos/${target.repository}/pulls/${target.number}`);
+  if (beforeWrite.head.sha !== target.headSha) throw new Error("stale-target: PR head changed before publication");
+
+  // Nonsecret audit signal: never print tokens, headers or Agent contents.
+  console.log(JSON.stringify({
+    publicationMethod: publication.method,
+    externalId: publication.externalId,
+    existingCheckId: publication.method === "PATCH" ? Number(publication.path.split("/").at(-1)) : null,
+    historyCount: checks.length,
+  }));
+
+  const summary = [
+  `Standards: ${review.standards.verdict}`,
+  ...review.standards.findings.map((finding) => `- ${finding}`),
+  `Spec: ${review.spec.verdict}`,
+  ...review.spec.findings.map((finding) => `- ${finding}`),
+  `Runtime: ${review.runtime.summary}`,
+  ].join("\n");
+  const body = {
+  name: check.name,
+  external_id: publication.externalId,
+  status: "completed",
+  conclusion: check.conclusion,
+  output: { title: check.title, summary },
+  };
+  if (publication.method === "POST") body.head_sha = check.headSha;
+
+  await githubRequest(publication.path, { method: publication.method, body });
+}
+
+async function readCheckHistory(target, name) {
+  const history = [];
+  const ids = new Set();
+  for (let page = 1; page <= 100; page += 1) {
+    const response = await githubRequest(
+      `/repos/${target.repository}/commits/${target.headSha}/check-runs?check_name=${encodeURIComponent(name)}&filter=all&per_page=100&page=${page}`,
+    );
+    if (!Array.isArray(response.check_runs) || response.check_runs.length > 100) {
+      throw new Error("check-history: malformed Check listing");
+    }
+    for (const check of response.check_runs) {
+      if (!Number.isSafeInteger(check?.id) || check.id <= 0 || ids.has(check.id)) {
+        throw new Error("check-history: invalid or repeated Check ID across pages");
+      }
+      if (typeof check.name !== "string" || !check.name
+        || check.head_sha !== target.headSha
+        || !(check.external_id === null || typeof check.external_id === "string")) {
+        throw new Error("check-history: incomplete or mismatched Check identity fields");
+      }
+      ids.add(check.id);
+      history.push(check);
+    }
+    if (response.check_runs.length < 100) return history;
+  }
+  // Never interpret incomplete history as absence or create a new Check.
+  throw new Error("check-history: pagination limit reached before complete listing");
+}
+
+async function readOptionalJson(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function writeDiagnostic(message) {
+  const text = `## PR Review diagnostic\n\n${message}\n\nNo Check Run was published.\n`;
+  await writeFile("review-diagnostic.md", text);
+  if (process.env.GITHUB_STEP_SUMMARY) await writeFile(process.env.GITHUB_STEP_SUMMARY, text, { flag: "a" });
+}

package/templates/pr-review/.github/graph-engineering/review-result.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "repository",
+    "pullRequestNumber",
+    "baseSha",
+    "headSha",
+    "standards",
+    "spec",
+    "handoff"
+  ],
+  "properties": {
+    "repository": {
+      "type": "string",
+      "minLength": 1
+    },
+    "pullRequestNumber": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "baseSha": {
+      "type": "string",
+      "minLength": 1
+    },
+    "headSha": {
+      "type": "string",
+      "minLength": 1
+    },
+    "standards": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/axis"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "spec": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/axis"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "handoff": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "additionalProperties": false,
+      "required": [
+        "summary"
+      ],
+      "properties": {
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  },
+  "$defs": {
+    "axis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "verdict",
+        "findings"
+      ],
+      "properties": {
+        "verdict": {
+          "enum": [
+            "pass",
+            "fail"
+          ]
+        },
+        "findings": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}

package/templates/pr-review/.github/graph-engineering/route-review.mjs

@@ -0,0 +1,117 @@
+import { randomUUID } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+
+import { readBundledContracts, resolveCompatibleExecution } from "./codex-compatible-executor.mjs";
+import { githubRequest } from "./github-api.mjs";
+import { SUPPORTED_ACTIONS } from "./pr-review-contract.mjs";
+
+export { SUPPORTED_ACTIONS } from "./pr-review-contract.mjs";
+
+// This deliberately repeats the Workflow trigger as a fail-closed runtime check.
+// The template contract test requires exact parity between both boundaries.
+export function routeReviewEvent({
+  eventName,
+  event,
+  eventConfiguration = { pullRequestActions: [...SUPPORTED_ACTIONS], manualDispatch: true, includeDrafts: false },
+}) {
+  if (eventName === "workflow_dispatch") {
+    if (!eventConfiguration.manualDispatch) return { shouldStart: false, pullRequestNumber: null, reason: "manual-dispatch-disabled" };
+    const pullRequestNumber = Number.parseInt(event.inputs?.pull_request_number, 10);
+    if (!Number.isInteger(pullRequestNumber) || pullRequestNumber < 1) {
+      return { shouldStart: false, pullRequestNumber: null, reason: "invalid-manual-input" };
+    }
+    return { shouldStart: true, pullRequestNumber, reason: "manual-dispatch" };
+  }
+
+  if (eventName !== "pull_request" || !SUPPORTED_ACTIONS.has(event.action) || !eventConfiguration.pullRequestActions.includes(event.action)) {
+    return { shouldStart: false, pullRequestNumber: null, reason: "unsupported-event" };
+  }
+  const pullRequestNumber = event.pull_request.number;
+  if (event.pull_request.draft && !eventConfiguration.includeDrafts) {
+    return { shouldStart: false, pullRequestNumber, reason: "draft-pull-request" };
+  }
+  return { shouldStart: true, pullRequestNumber, reason: "supported-pull-request-event" };
+}
+
+export function planReviewRun({ eventName, event, config, profile }) {
+  try {
+    const compatible = resolveCompatibleExecution({ config, profile });
+    return {
+      configurationStatus: "compatible",
+      ...routeReviewEvent({ eventName, event, eventConfiguration: compatible.events }),
+      compatible,
+    };
+  } catch (error) {
+    return {
+      configurationStatus: "handoff",
+      shouldStart: false,
+      pullRequestNumber: null,
+      reason: "configuration-handoff",
+      diagnostic: error.message,
+    };
+  }
+}
+
+export async function enforceManualPullRequestState(planned, { repository, request = githubRequest } = {}) {
+  if (!planned.shouldStart || planned.reason !== "manual-dispatch") return planned;
+  try {
+    const pullRequest = await request(`/repos/${repository}/pulls/${planned.pullRequestNumber}`);
+    if (pullRequest.state !== "open") return { ...planned, shouldStart: false, reason: "manual-pull-request-not-open" };
+    if (pullRequest.draft && !planned.compatible.events.includeDrafts) return { ...planned, shouldStart: false, reason: "draft-pull-request" };
+    return planned;
+  } catch (error) {
+    return { ...planned, shouldStart: false, reason: "manual-pull-request-unreadable", diagnostic: error.message };
+  }
+}
+
+async function main() {
+  const event = JSON.parse(await readFile(required("GITHUB_EVENT_PATH"), "utf8"));
+  let contracts;
+  try {
+    contracts = await readBundledContracts();
+  } catch (error) {
+    const diagnostic = `configuration-handoff: ${error.message}`;
+    await writeOutputs({ configurationStatus: "handoff", shouldStart: false, pullRequestNumber: null, reason: "configuration-handoff", diagnostic });
+    if (process.env.GITHUB_STEP_SUMMARY) await writeFile(process.env.GITHUB_STEP_SUMMARY, `## PR Review handoff\n\n${diagnostic}\n`, { flag: "a" });
+    return;
+  }
+  const eventName = required("GITHUB_EVENT_NAME");
+  let planned = planReviewRun({ eventName, event, ...contracts });
+  if (planned.configurationStatus === "handoff") {
+    await writeOutputs(planned);
+    if (process.env.GITHUB_STEP_SUMMARY) await writeFile(process.env.GITHUB_STEP_SUMMARY, `## PR Review handoff\n\n${planned.diagnostic}\n`, { flag: "a" });
+    return;
+  }
+  if (eventName === "workflow_dispatch") planned = await enforceManualPullRequestState(planned, { repository: required("GITHUB_REPOSITORY") });
+  const manualPrompt = eventName === "workflow_dispatch" ? event.inputs?.event_prompt?.trim() : "";
+  await writeOutputs({
+    shouldStart: planned.shouldStart,
+    pullRequestNumber: planned.pullRequestNumber,
+    reason: planned.reason,
+    eventPrompt: manualPrompt || planned.compatible.eventPrompt,
+    codexModel: planned.compatible.action.model,
+    codexEffort: planned.compatible.action.effort,
+    safetyStrategy: planned.compatible.action.safetyStrategy,
+  });
+}
+
+async function writeOutputs(values) {
+  if (process.env.GITHUB_OUTPUT) {
+    const lines = [];
+    for (const [key, value] of Object.entries(values)) {
+      const outputKey = key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+      const delimiter = `loop_${randomUUID()}`;
+      lines.push(`${outputKey}<<${delimiter}`, String(value ?? ""), delimiter);
+    }
+    await writeFile(process.env.GITHUB_OUTPUT, `${lines.join("\n")}\n`, { flag: "a" });
+  }
+}
+
+function required(name) {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main();