@dougharness/codex 1.0.0

package/dist/schema.d.ts

@@ -0,0 +1,174 @@
+export declare const SEVERITIES: readonly ["blocker", "major", "minor"];
+export type Severity = (typeof SEVERITIES)[number];
+export declare const VERDICTS: readonly ["pass", "fail", "inconclusive"];
+export type Verdict = (typeof VERDICTS)[number];
+export interface ReviewIssue {
+    severity: Severity;
+    file: string;
+    line?: number;
+    description: string;
+    /** What the reviewer ran or read that shows the problem. */
+    evidence?: string;
+}
+/** What the model is asked to return. Everything else in ReviewResult is measured by the adapter. */
+export interface ModelReview {
+    verdict: Verdict;
+    summary: string;
+    issues: ReviewIssue[];
+}
+/** What a worker (or reviewer) hands back when it stops partway through, at the harness's direction. */
+export interface Handoff {
+    completed: string[];
+    remaining: string[];
+    next: string;
+    verify: string;
+}
+export interface CommandRun {
+    command: string;
+    /** Exit status as reported by the Codex event stream. null if it never completed. */
+    exitCode: number | null;
+    ok: boolean;
+    outputTail?: string;
+}
+export interface ReviewResult {
+    /**
+     * Same as the model's verdict when the review ran; "inconclusive" for every failure mode. The adapter
+     * turns a `fail` into `pass` when every blocker was downgraded under R12 (see `downgraded`); a `fail`
+     * with nothing downgraded is left alone.
+     */
+    verdict: Verdict;
+    summary: string;
+    issues: ReviewIssue[];
+    /** Commands Codex actually executed, with the exit codes it observed. Never from the model's prose. */
+    commandsRun: CommandRun[];
+    /** Files in base...head as computed by git, so the reviewer's scope claims can be checked. */
+    changedFiles: string[];
+    base: string;
+    head: string;
+    dir: string;
+    reviewer: "codex";
+    model: string | null;
+    sandbox: Sandbox;
+    /** null when the review completed; otherwise why it did not. */
+    error: ReviewError | null;
+    codexExitCode: number | null;
+    durationMs: number;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    } | null;
+    /**
+     * The nesting guard: `name` is the environment variable the adapter sets on the worker it spawns
+     * (`DOUG_CODEX_REVIEW`); `passed` is true once the adapter attempted to spawn codex with the marker
+     * in its environment; `inherited` is true when the adapter's own process environment already had
+     * the variable set to a non-empty value (this review is running inside another codex-review).
+     */
+    marker: {
+        name: string;
+        passed: boolean;
+        inherited: boolean;
+    };
+    /** True when the worker stopped at a boundary rather than finishing (R13); absent or false otherwise. */
+    partial?: boolean;
+    /** Present when partial is true: what a fresh worker needs to pick the remaining work up (R13). */
+    handoff?: Handoff;
+    /**
+     * Present only when `enforceBlockerEvidence` (contract.ts) downgraded at least one blocker for lacking
+     * R12 evidence: `index` into `issues` (now `major`) and the reason it was downgraded.
+     */
+    downgraded?: {
+        index: number;
+        reason: string;
+    }[];
+}
+export type ReviewError = {
+    kind: "codex-not-found";
+    message: string;
+} | {
+    kind: "codex-failed";
+    message: string;
+    stderrTail: string;
+} | {
+    kind: "timeout";
+    message: string;
+} | {
+    kind: "no-final-message";
+    message: string;
+} | {
+    kind: "unparseable";
+    message: string;
+    raw: string;
+} | {
+    kind: "git";
+    message: string;
+}
+/** The reviewer changed the working tree it was reviewing; its verdict cannot be trusted. */
+ | {
+    kind: "worktree-modified";
+    message: string;
+    changes: string[];
+};
+export declare const SANDBOXES: readonly ["read-only", "workspace-write"];
+export type Sandbox = (typeof SANDBOXES)[number];
+/**
+ * Codex 0.155.1 accepts `-c model_reasoning_effort=<level>` on `codex exec` at argv-parse time but does not
+ * validate the value itself (an unknown level loads fine), so codex-review rejects one that is not one of
+ * these five documented levels. The binary's own model catalog lists no `minimal` and adds `max`/`ultra` for
+ * some models; neither is verified for use here, so this stays the documented set.
+ */
+export declare const REASONING_EFFORTS: readonly ["minimal", "low", "medium", "high", "xhigh"];
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+/**
+ * JSON Schema for the model's final message. Codex passes it to the API in strict mode, which requires
+ * every property to be listed in `required`; optional fields are therefore nullable rather than absent.
+ */
+export declare const MODEL_REVIEW_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["verdict", "summary", "issues"];
+    readonly properties: {
+        readonly verdict: {
+            readonly type: "string";
+            readonly enum: readonly ["pass", "fail", "inconclusive"];
+        };
+        readonly summary: {
+            readonly type: "string";
+        };
+        readonly issues: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["severity", "file", "line", "description", "evidence"];
+                readonly properties: {
+                    readonly severity: {
+                        readonly type: "string";
+                        readonly enum: readonly ["blocker", "major", "minor"];
+                    };
+                    readonly file: {
+                        readonly type: "string";
+                    };
+                    readonly line: {
+                        readonly type: readonly ["integer", "null"];
+                        readonly description: "1-based line in file, or null";
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                    readonly evidence: {
+                        readonly type: readonly ["string", "null"];
+                        readonly description: "the command or observation that demonstrates the issue, or null";
+                    };
+                };
+            };
+        };
+    };
+};
+/** Validates a parsed final message. Returns the normalized review or an error string. */
+export declare function validateModelReview(value: unknown): {
+    review: ModelReview;
+} | {
+    error: string;
+};
+/** Exit code for the CLI: 0 no blockers, 1 blockers or a fail verdict, 2 could not review. */
+export declare function exitCodeFor(result: ReviewResult): number;

package/dist/schema.js

@@ -0,0 +1,84 @@
+// The contract between Doug and any worker: spec in, diff plus evidence out.
+// This file defines the "out" side for the review role. The JSON Schema is handed to
+// `codex exec --output-schema` so the model's final message is constrained to it, and the
+// parser validates it again because a schema on the way out is not a guarantee on the way in.
+export const SEVERITIES = ["blocker", "major", "minor"];
+export const VERDICTS = ["pass", "fail", "inconclusive"];
+export const SANDBOXES = ["read-only", "workspace-write"];
+/**
+ * Codex 0.155.1 accepts `-c model_reasoning_effort=<level>` on `codex exec` at argv-parse time but does not
+ * validate the value itself (an unknown level loads fine), so codex-review rejects one that is not one of
+ * these five documented levels. The binary's own model catalog lists no `minimal` and adds `max`/`ultra` for
+ * some models; neither is verified for use here, so this stays the documented set.
+ */
+export const REASONING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh"];
+/**
+ * JSON Schema for the model's final message. Codex passes it to the API in strict mode, which requires
+ * every property to be listed in `required`; optional fields are therefore nullable rather than absent.
+ */
+export const MODEL_REVIEW_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["verdict", "summary", "issues"],
+    properties: {
+        verdict: { type: "string", enum: [...VERDICTS] },
+        summary: { type: "string" },
+        issues: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["severity", "file", "line", "description", "evidence"],
+                properties: {
+                    severity: { type: "string", enum: [...SEVERITIES] },
+                    file: { type: "string" },
+                    line: { type: ["integer", "null"], description: "1-based line in file, or null" },
+                    description: { type: "string" },
+                    evidence: { type: ["string", "null"], description: "the command or observation that demonstrates the issue, or null" },
+                },
+            },
+        },
+    },
+};
+/** Validates a parsed final message. Returns the normalized review or an error string. */
+export function validateModelReview(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return { error: "final message is not a JSON object" };
+    const v = value;
+    if (!VERDICTS.includes(v.verdict))
+        return { error: `verdict must be one of ${VERDICTS.join(", ")}` };
+    if (typeof v.summary !== "string")
+        return { error: "summary must be a string" };
+    if (!Array.isArray(v.issues))
+        return { error: "issues must be an array" };
+    const issues = [];
+    for (const [i, raw] of v.issues.entries()) {
+        if (!raw || typeof raw !== "object")
+            return { error: `issues[${i}] must be an object` };
+        const it = raw;
+        if (!SEVERITIES.includes(it.severity))
+            return { error: `issues[${i}].severity must be one of ${SEVERITIES.join(", ")}` };
+        if (typeof it.file !== "string")
+            return { error: `issues[${i}].file must be a string` };
+        if (typeof it.description !== "string" || !it.description.trim())
+            return { error: `issues[${i}].description must be a non-empty string` };
+        const issue = { severity: it.severity, file: it.file, description: it.description };
+        if (typeof it.line === "number" && Number.isInteger(it.line))
+            issue.line = it.line;
+        if (typeof it.evidence === "string" && it.evidence)
+            issue.evidence = it.evidence;
+        issues.push(issue);
+    }
+    return { review: { verdict: v.verdict, summary: v.summary, issues } };
+}
+/** Exit code for the CLI: 0 no blockers, 1 blockers or a fail verdict, 2 could not review. */
+export function exitCodeFor(result) {
+    if (result.error)
+        return 2;
+    if (result.verdict === "inconclusive")
+        return 2;
+    if (result.verdict === "fail" || result.issues.some((i) => i.severity === "blocker"))
+        return 1;
+    return 0;
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@dougharness/codex",
+  "version": "1.0.0",
+  "description": "codex-review: Codex CLI as an adversarial reviewer. Spec in, diff plus evidence out, structured JSON with real exit statuses.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eschwa3/dougharness.git",
+    "directory": "packages/doug-codex"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "codex-review": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.16"
+  }
+}