forgeos 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/forge/agent-fabric/canonical.ts

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { AgentFabricError } from "./errors.ts";
+import type { Digest, DigestFunction } from "./types.ts";
+
+/**
+ * P0a canonical JSON profile.
+ *
+ * This profile is intentionally explicit and deterministic for the current
+ * TypeScript/JavaScript reference implementation. Cross-language JCS
+ * conformance is a separate protocol profile and is not claimed here.
+ */
+export const P0A_CANONICALIZATION_PROFILE = "forge-canonical-json/v0.1" as const;
+
+function canonicalizationFailure(message: string): never {
+  throw new AgentFabricError("AF_CANONICALIZATION_FAILED", message);
+}
+
+function assertJsonObjectShape(value: object): void {
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    canonicalizationFailure("Canonical objects must have Object.prototype or null prototype");
+  }
+
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string") {
+      canonicalizationFailure("Canonical objects cannot contain symbol properties");
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor?.enumerable) {
+      canonicalizationFailure(`Canonical object property ${key} must be enumerable`);
+    }
+    if (!("value" in descriptor)) {
+      canonicalizationFailure(`Canonical object property ${key} cannot be an accessor`);
+    }
+  }
+}
+
+function assertJsonArrayShape(value: readonly unknown[]): void {
+  if (Object.getPrototypeOf(value) !== Array.prototype) {
+    canonicalizationFailure("Canonical arrays must have Array.prototype");
+  }
+
+  const ownKeys = Reflect.ownKeys(value);
+  const expectedIndexKeys = new Set(Array.from({ length: value.length }, (_, index) => String(index)));
+
+  for (const key of ownKeys) {
+    if (key === "length") continue;
+    if (typeof key !== "string" || !expectedIndexKeys.has(key)) {
+      canonicalizationFailure("Canonical arrays cannot contain extra or symbol properties");
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor?.enumerable || !("value" in descriptor)) {
+      canonicalizationFailure(`Canonical array index ${key} must be an enumerable data property`);
+    }
+  }
+
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.prototype.hasOwnProperty.call(value, index)) {
+      canonicalizationFailure("Canonical arrays cannot be sparse");
+    }
+  }
+}
+
+function normalize(value: unknown, seen: Set<object>): unknown {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      canonicalizationFailure("Canonical values cannot contain non-finite numbers");
+    }
+    return Object.is(value, -0) ? 0 : value;
+  }
+
+  if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol") {
+    canonicalizationFailure(`Unsupported canonical value type: ${typeof value}`);
+  }
+
+  if (typeof value === "bigint") {
+    canonicalizationFailure("BigInt values must be encoded as strings before canonicalization");
+  }
+
+  if (Array.isArray(value)) {
+    if (seen.has(value)) canonicalizationFailure("Canonical values cannot be cyclic");
+    assertJsonArrayShape(value);
+    seen.add(value);
+    const normalized: unknown[] = [];
+    for (let index = 0; index < value.length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (!descriptor || !("value" in descriptor)) {
+        seen.delete(value);
+        canonicalizationFailure(`Canonical array index ${index} must be an own data property`);
+      }
+      normalized[index] = normalize(descriptor.value, seen);
+    }
+    seen.delete(value);
+    return normalized;
+  }
+
+  if (typeof value === "object") {
+    if (seen.has(value)) canonicalizationFailure("Canonical values cannot be cyclic");
+    assertJsonObjectShape(value);
+    seen.add(value);
+    const record = value as Record<string, unknown>;
+    // A null-prototype accumulator is required so an own `__proto__` key is
+    // preserved as data rather than invoking Object.prototype's legacy setter.
+    const normalized = Object.create(null) as Record<string, unknown>;
+    for (const key of Object.keys(record).sort()) {
+      if (record[key] === undefined) {
+        canonicalizationFailure(`Canonical object property ${key} is undefined`);
+      }
+      normalized[key] = normalize(record[key], seen);
+    }
+    seen.delete(value);
+    return normalized;
+  }
+
+  canonicalizationFailure("Unsupported canonical value");
+}
+
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(normalize(value, new Set<object>()));
+}
+
+export function sha256Digest(canonicalValue: string): Digest {
+  return `sha256:${createHash("sha256").update(canonicalValue).digest("hex")}`;
+}
+
+export function digestCanonical(
+  value: unknown,
+  digest: DigestFunction,
+): Digest {
+  return digest(stableStringify(value));
+}

package/src/forge/agent-fabric/codex-adversarial-review.ts

@@ -0,0 +1,229 @@
+import { spawn, type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from "node:child_process";
+import { createHash } from "node:crypto";
+import { realpathSync, statSync } from "node:fs";
+import type { Digest } from "./types.ts";
+
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+const MAX_TIMEOUT_MS = 10 * 60_000;
+const MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+const MAX_PROMPT_BYTES = 64 * 1024;
+const MAX_FINDINGS = 100;
+
+export interface CodexAdversarialFinding {
+  severity: "blocker" | "high" | "medium" | "low";
+  path: string;
+  line?: number;
+  title: string;
+  explanation: string;
+}
+
+export interface CodexAdversarialReport {
+  requestDigest: Digest;
+  verdict: "pass" | "changes_requested" | "inconclusive";
+  summary: string;
+  findings: readonly CodexAdversarialFinding[];
+}
+
+export interface CodexReviewUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cachedInputTokens?: number;
+}
+
+export type CodexAdversarialReviewResult =
+  | { state: "reported"; report: CodexAdversarialReport; outputDigest: Digest; usage?: CodexReviewUsage }
+  | { state: "inconclusive"; error: string; report?: CodexAdversarialReport; outputDigest?: Digest; usage?: CodexReviewUsage };
+
+export interface CodexAdversarialReviewOptions {
+  /** A prepared, exact review checkout. The caller must verify its Git identity and diff before and after this call. */
+  workspaceRoot: string;
+  /** Canonical digest of the review request and exact diff, supplied by the caller. */
+  requestDigest: Digest;
+  prompt: string;
+  timeoutMs: number;
+  maxOutputBytes: number;
+  executable?: string;
+  signal?: AbortSignal;
+  /** Injection point for tests; production uses node:child_process.spawn. */
+  spawnProcess?: (command: string, args: string[], options: SpawnOptionsWithoutStdio) => ChildProcessWithoutNullStreams;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function exactKeys(value: Record<string, unknown>, required: readonly string[], optional: readonly string[] = []): boolean {
+  return required.every((key) => Object.hasOwn(value, key)) &&
+    Object.keys(value).every((key) => required.includes(key) || optional.includes(key));
+}
+
+function nonEmptyText(value: unknown, maxLength: number): value is string {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= maxLength && !value.includes("\u0000");
+}
+
+function validFinding(value: unknown): value is CodexAdversarialFinding {
+  if (!isRecord(value) || !exactKeys(value, ["severity", "path", "title", "explanation"], ["line"])) return false;
+  if (!["blocker", "high", "medium", "low"].includes(String(value.severity))) return false;
+  if (!nonEmptyText(value.path, 512) || value.path.includes("\\") || value.path.startsWith("/") ||
+      /^[a-z]:/iu.test(value.path) || value.path.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) return false;
+  if (!nonEmptyText(value.title, 500) || !nonEmptyText(value.explanation, 4_000)) return false;
+  return value.line === undefined || (Number.isSafeInteger(value.line) && Number(value.line) > 0);
+}
+
+function parseReport(text: string, requestDigest: Digest): CodexAdversarialReport | undefined {
+  let value: unknown;
+  try { value = JSON.parse(text); } catch { return undefined; }
+  if (!isRecord(value) || !exactKeys(value, ["requestDigest", "verdict", "summary", "findings"])) return undefined;
+  if (value.requestDigest !== requestDigest || !["pass", "changes_requested", "inconclusive"].includes(String(value.verdict)) ||
+      !nonEmptyText(value.summary, 4_000) || !Array.isArray(value.findings) ||
+      value.findings.length > MAX_FINDINGS || !value.findings.every(validFinding)) return undefined;
+  if ((value.verdict === "pass" && value.findings.length !== 0) ||
+      (value.verdict === "changes_requested" && value.findings.length === 0)) return undefined;
+  return value as unknown as CodexAdversarialReport;
+}
+
+function parseUsage(value: unknown): CodexReviewUsage | undefined {
+  if (!isRecord(value)) return undefined;
+  const input = value.input_tokens;
+  const output = value.output_tokens;
+  const cached = value.cached_input_tokens;
+  if (!Number.isSafeInteger(input) || Number(input) < 0 ||
+      !Number.isSafeInteger(output) || Number(output) < 0) return undefined;
+  return {
+    inputTokens: Number(input), outputTokens: Number(output),
+    ...(Number.isSafeInteger(cached) && Number(cached) >= 0 ? { cachedInputTokens: Number(cached) } : {}),
+  };
+}
+
+function parseCodexEvents(stdout: string, requestDigest: Digest):
+  { report?: CodexAdversarialReport; usage?: CodexReviewUsage; error?: string } {
+  let finalText: string | undefined;
+  let usage: CodexReviewUsage | undefined;
+  let completed = false;
+  let failure = false;
+  for (const line of stdout.split(/\r?\n/u)) {
+    if (!line) continue;
+    let event: unknown;
+    try { event = JSON.parse(line); } catch { return { error: "invalid_jsonl" }; }
+    if (!isRecord(event) || typeof event.type !== "string") return { error: "invalid_event" };
+    if (event.type === "item.completed" && isRecord(event.item) && event.item.type === "agent_message") {
+      if (typeof event.item.text !== "string") return { error: "invalid_agent_message" };
+      finalText = event.item.text;
+    }
+    if (event.type === "turn.completed") {
+      completed = true;
+      usage = parseUsage(event.usage);
+    }
+    if (event.type === "turn.failed" || event.type === "error") failure = true;
+  }
+  if (failure) return { error: "codex_turn_failed", usage };
+  if (!completed) return { error: "missing_completed_turn", usage };
+  if (finalText === undefined) return { error: "missing_agent_report", usage };
+  const report = parseReport(finalText, requestDigest);
+  if (!report) return { error: "invalid_agent_report", usage };
+  return { report, usage };
+}
+
+function digestOutput(stdout: Buffer, stderr: Buffer): Digest {
+  const hash = createHash("sha256");
+  hash.update(stdout);
+  hash.update(stderr);
+  return `sha256:${hash.digest("hex")}`;
+}
+
+/** Codex's read-only sandbox is defense in depth; the caller owns checkout isolation and exact-diff verification. */
+export async function runCodexAdversarialReview(options: CodexAdversarialReviewOptions): Promise<CodexAdversarialReviewResult> {
+  if (!DIGEST_PATTERN.test(options.requestDigest) || !nonEmptyText(options.prompt, MAX_PROMPT_BYTES) ||
+      Buffer.byteLength(options.prompt, "utf8") > MAX_PROMPT_BYTES ||
+      !Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < 1 || options.timeoutMs > MAX_TIMEOUT_MS ||
+      !Number.isSafeInteger(options.maxOutputBytes) || options.maxOutputBytes < 1 || options.maxOutputBytes > MAX_OUTPUT_BYTES) {
+    throw new TypeError("Invalid Codex review bounds or request");
+  }
+  const workspaceRoot = realpathSync(options.workspaceRoot);
+  if (!statSync(workspaceRoot).isDirectory()) throw new TypeError("Codex review workspace must be a directory");
+  if (options.signal?.aborted) return { state: "inconclusive", error: "cancelled" };
+
+  const args = ["--sandbox", "read-only", "--ask-for-approval", "never", "exec", "review",
+    "--uncommitted", "--json", "--ephemeral", "-"];
+  const prompt = `${options.prompt.trimEnd()}\n\nReturn ONLY a JSON object as the final answer with exactly these keys: ` +
+    `requestDigest, verdict, summary, findings. Set requestDigest to ${options.requestDigest}. ` +
+    `verdict is pass, changes_requested, or inconclusive. Each finding has severity ` +
+    `(blocker, high, medium, low), repository-relative path, optional positive line, title, and explanation. ` +
+    `Use an empty findings array only for pass or inconclusive. Do not use Markdown fences.\n`;
+
+  return await new Promise((resolve) => {
+    let child: ChildProcessWithoutNullStreams;
+    try {
+      child = (options.spawnProcess ?? spawn)(options.executable ?? "codex", args, {
+        cwd: workspaceRoot, shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch {
+      resolve({ state: "inconclusive", error: "spawn_failed" });
+      return;
+    }
+
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let captured = 0;
+    let reason: string | undefined;
+    let settled = false;
+    let hardTimer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (code: number | null) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (hardTimer) clearTimeout(hardTimer);
+      options.signal?.removeEventListener("abort", cancel);
+      const out = Buffer.concat(stdout);
+      const err = Buffer.concat(stderr);
+      const outputDigest = digestOutput(out, err);
+      if (reason) {
+        resolve({ state: "inconclusive", error: reason, outputDigest });
+        return;
+      }
+      if (code !== 0) {
+        resolve({ state: "inconclusive", error: "codex_nonzero_exit", outputDigest });
+        return;
+      }
+      const parsed = parseCodexEvents(out.toString("utf8"), options.requestDigest);
+      if (!parsed.report) {
+        resolve({ state: "inconclusive", error: parsed.error ?? "invalid_agent_report", outputDigest,
+          ...(parsed.usage ? { usage: parsed.usage } : {}) });
+        return;
+      }
+      if (parsed.report.verdict === "inconclusive") {
+        resolve({ state: "inconclusive", error: "reviewer_inconclusive", report: parsed.report, outputDigest,
+          ...(parsed.usage ? { usage: parsed.usage } : {}) });
+        return;
+      }
+      resolve({ state: "reported", report: parsed.report, outputDigest,
+        ...(parsed.usage ? { usage: parsed.usage } : {}) });
+    };
+    const stop = (why: string) => {
+      if (reason || settled) return;
+      reason = why;
+      child.kill();
+      hardTimer = setTimeout(() => finish(null), 2_000);
+    };
+    const capture = (chunk: Buffer, target: Buffer[]) => {
+      if (reason || settled) return;
+      const remaining = options.maxOutputBytes - captured;
+      if (remaining > 0) {
+        const part = chunk.subarray(0, remaining);
+        target.push(part);
+        captured += part.length;
+      }
+      if (chunk.length > remaining) stop("output_limit");
+    };
+    const cancel = () => stop("cancelled");
+    child.stdout.on("data", (chunk: Buffer) => capture(chunk, stdout));
+    child.stderr.on("data", (chunk: Buffer) => capture(chunk, stderr));
+    child.on("error", () => stop("spawn_failed"));
+    child.on("close", finish);
+    const timer = setTimeout(() => stop("timeout"), options.timeoutMs);
+    options.signal?.addEventListener("abort", cancel, { once: true });
+    if (options.signal?.aborted) cancel();
+    child.stdin.on("error", () => stop("stdin_failed"));
+    try { child.stdin.end(prompt); } catch { stop("stdin_failed"); }
+  });
+}

package/src/forge/agent-fabric/codex-sdk-worker.ts

@@ -0,0 +1,203 @@
+import { Codex, type CodexOptions, type ThreadOptions, type TurnOptions, type ThreadEvent } from "@openai/codex-sdk";
+import { realpath, stat, readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+export interface CodexWorkerUsage { input_tokens: number; cached_input_tokens: number; output_tokens: number }
+export interface CodexWorkerEvent { type: string; threadId?: string; summary?: string; usage?: CodexWorkerUsage }
+export interface CodexWorkerInput {
+  cwd: string; prompt: string; role: "implementer" | "reviewer" | "investigator" | "decision";
+  model?: string; threadId?: string; signal: AbortSignal;
+  onEvent: (event: CodexWorkerEvent) => Promise<void> | void;
+}
+export interface CodexWorkerOutput {
+  threadId: string;
+  report: { summary: string; verdict?: "approved" | "changes_requested"; findings?: { description: string }[]; selectedNodeIds?: string[]; replanProposal?: string };
+  usage?: CodexWorkerUsage; eventsObserved: number;
+}
+export interface CodexWorkerThread {
+  readonly id: string | null;
+  runStreamed(prompt: string, options: TurnOptions): Promise<{ events: AsyncIterable<ThreadEvent> }>;
+}
+export interface CodexWorkerClient {
+  startThread(options: ThreadOptions): CodexWorkerThread;
+  resumeThread(id: string, options: ThreadOptions): CodexWorkerThread;
+}
+export type CodexWorkerFactory = (options: CodexOptions) => CodexWorkerClient | Promise<CodexWorkerClient>;
+export class CodexWorkerError extends Error {
+  constructor(readonly code: string, message: string) { super(message); this.name = "CodexWorkerError"; }
+}
+function fail(code: string, message: string): never { throw new CodexWorkerError(code, message); }
+function text(value: unknown, maximum: number): value is string { return typeof value === "string" && value.trim().length > 0 && value.length <= maximum && !value.includes("\0"); }
+function checkAbort(signal: AbortSignal): void { if (signal.aborted) fail("AF_CODEX_ABORTED", "Codex worker was cancelled; its outcome requires reconciliation"); }
+
+/** Restrict inherited environment while preserving local ChatGPT authentication. */
+export function codexWorkerEnvironment(source: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const allowed = new Set(["path", "systemroot", "windir", "comspec", "pathext", "temp", "tmp", "tmpdir", "home", "userprofile", "homedrive", "homepath", "appdata", "localappdata", "codex_home", "lang", "lc_all"]);
+  return Object.fromEntries(Object.entries(source).filter(([key, value]) => allowed.has(key.toLowerCase()) && typeof value === "string")) as Record<string, string>;
+}
+
+/** Disable each effective inherited server and verify the resulting CLI configuration. */
+export async function codexWorkerMcpIsolation(list: (overrides: string[]) => Promise<unknown>): Promise<string[]> {
+  const servers = await list([]);
+  if (!Array.isArray(servers) || servers.length > 256) fail("AF_CODEX_ISOLATION", "Cannot inspect effective Codex MCP configuration");
+  const overrides = servers.flatMap((server) => {
+    if (!server || typeof server !== "object" || !text(server.name, 128) || !/^[A-Za-z0-9_-]+$/u.test(server.name)) fail("AF_CODEX_ISOLATION", "Invalid effective Codex MCP server name");
+    // Plugin-provided servers may have no root-table transport to merge with.
+    // Supply an inert valid transport and explicitly disable it.
+    return [`mcp_servers.${server.name}.enabled=false`, `mcp_servers.${server.name}.command=${JSON.stringify(process.execPath)}`, `mcp_servers.${server.name}.args=[]`];
+  });
+  const observed = await list(overrides);
+  if (!Array.isArray(observed) || observed.length > 256 || observed.some((server) => !server || typeof server !== "object" || server.enabled !== false)) fail("AF_CODEX_ISOLATION", "Inherited Codex MCP servers remain enabled");
+  return overrides;
+}
+async function bundledCodexBinary(): Promise<string> {
+  const tripleByPlatform: Record<string, string> = { "win32:x64": "x86_64-pc-windows-msvc", "win32:arm64": "aarch64-pc-windows-msvc", "linux:x64": "x86_64-unknown-linux-musl", "linux:arm64": "aarch64-unknown-linux-musl", "darwin:x64": "x86_64-apple-darwin", "darwin:arm64": "aarch64-apple-darwin" };
+  const packageByPlatform: Record<string, string> = { "win32:x64": "@openai/codex-win32-x64", "win32:arm64": "@openai/codex-win32-arm64", "linux:x64": "@openai/codex-linux-x64", "linux:arm64": "@openai/codex-linux-arm64", "darwin:x64": "@openai/codex-darwin-x64", "darwin:arm64": "@openai/codex-darwin-arm64" };
+  const platform = `${process.platform}:${process.arch}`, triple = tripleByPlatform[platform], packageName = packageByPlatform[platform];
+  if (!triple || !packageName) fail("AF_CODEX_ISOLATION", "Unsupported Codex platform");
+  const require = createRequire(import.meta.resolve("@openai/codex-sdk")), codexPackage = require.resolve("@openai/codex/package.json");
+  const platformPackage = createRequire(codexPackage).resolve(`${packageName}/package.json`);
+  const root = join(dirname(platformPackage), "vendor", triple), binary = process.platform === "win32" ? "codex.exe" : "codex";
+  for (const path of [join(root, "bin", binary), join(root, "codex", binary)]) if (await stat(path).then((item) => item.isFile(), () => false)) return path;
+  fail("AF_CODEX_ISOLATION", "Bundled Codex executable is unavailable");
+}
+/** Hash observed local SDK/CLI/config inputs; persist hashes, never configuration/auth contents. */
+export async function codexWorkerRuntimeIdentity(cwd: string): Promise<string> {
+  const digest = createHash("sha256"), binary = await bundledCodexBinary();
+  digest.update(binary); digest.update(await readFile(binary)); digest.update(await readFile(fileURLToPath(import.meta.resolve("@openai/codex-sdk"))));
+  const paths = [join(process.env.CODEX_HOME ?? join(homedir(), ".codex"), "config.toml"), join(cwd, ".codex/config.toml")];
+  for (const [index, path] of paths.entries()) { digest.update(index === 0 ? path : "project-config"); try { digest.update(await readFile(path)); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; digest.update("absent"); } }
+  return `sha256:${digest.digest("hex")}`;
+}
+const exec = promisify(execFile);
+export async function codexWorkerIsolationOverrides(cwd: string, signal: AbortSignal): Promise<string[]> {
+  const executable = await bundledCodexBinary();
+  const overrides = await codexWorkerMcpIsolation(async (overrides) => {
+    const args = ["--cd", cwd, ...overrides.flatMap((override) => ["--config", override]), "mcp", "list", "--json"];
+    const output = await exec(executable, args, { cwd, env: codexWorkerEnvironment(), signal, timeout: 10000, maxBuffer: 1024 * 1024, windowsHide: true, encoding: "utf8" });
+    return JSON.parse(output.stdout);
+  });
+  return overrides;
+}
+async function isolatedCodexClient(options: CodexOptions, cwd: string, signal: AbortSignal): Promise<CodexWorkerClient> {
+  return new Codex({ ...options, configOverrides: await codexWorkerIsolationOverrides(cwd, signal) });
+}
+const reportSchema = {
+  type: "object", additionalProperties: false,
+  required: ["summary", "verdict", "findings", "selectedNodeIds", "replanProposal"],
+  properties: {
+    summary: { type: "string", minLength: 1, maxLength: 4096 },
+    verdict: { anyOf: [{ type: "string", enum: ["approved", "changes_requested"] }, { type: "null" }] },
+    findings: { type: "array", maxItems: 128, items: { type: "object", additionalProperties: false, required: ["description"], properties: { description: { type: "string", minLength: 1, maxLength: 4096 } } } },
+    selectedNodeIds: { type: "array", maxItems: 128, items: { type: "string", minLength: 1, maxLength: 128 } },
+    replanProposal: { anyOf: [{ type: "string", minLength: 1, maxLength: 4096 }, { type: "null" }] },
+  },
+};
+function validateReport(raw: string, role: CodexWorkerInput["role"]): CodexWorkerOutput["report"] {
+  if (Buffer.byteLength(raw) > 64 * 1024) fail("AF_CODEX_REPORT", "Codex report exceeds its size limit");
+  let data: unknown;
+  try { data = JSON.parse(raw); } catch { fail("AF_CODEX_REPORT", "Codex did not return a JSON report"); }
+  if (!data || typeof data !== "object" || Array.isArray(data)) fail("AF_CODEX_REPORT", "Invalid Codex report object");
+  const report = data as Record<string, unknown>;
+  const keys = Object.keys(report);
+  if (keys.length !== 5 || keys.some((key) => !Object.keys(reportSchema.properties).includes(key)) || !text(report.summary, 4096)) fail("AF_CODEX_REPORT", "Invalid Codex report fields");
+  if (report.verdict !== null && report.verdict !== "approved" && report.verdict !== "changes_requested") fail("AF_CODEX_REPORT", "Invalid Codex review verdict");
+  if (!Array.isArray(report.findings) || report.findings.length > 128 || report.findings.some((finding) => !finding || typeof finding !== "object" || Array.isArray(finding) || Object.keys(finding).length !== 1 || !text(finding.description, 4096))) fail("AF_CODEX_REPORT", "Invalid Codex findings");
+  if (!Array.isArray(report.selectedNodeIds) || report.selectedNodeIds.length > 128 || report.selectedNodeIds.some((id) => !text(id, 128) || !/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/u.test(id)) || new Set(report.selectedNodeIds).size !== report.selectedNodeIds.length) fail("AF_CODEX_REPORT", "Invalid Codex branch selection");
+  if (report.replanProposal !== null && !text(report.replanProposal, 4096)) fail("AF_CODEX_REPORT", "Invalid Codex replan proposal");
+  if (role === "reviewer" && report.verdict === null) fail("AF_CODEX_REPORT", "Reviewer report requires an explicit verdict");
+  if (report.verdict === "approved" && report.findings.length > 0) fail("AF_CODEX_REPORT", "Approved review cannot contain unresolved findings");
+  return { summary: report.summary, ...(report.verdict !== null ? { verdict: report.verdict as "approved" | "changes_requested" } : {}), findings: report.findings as { description: string }[], selectedNodeIds: report.selectedNodeIds as string[], ...(report.replanProposal !== null ? { replanProposal: report.replanProposal as string } : {}) };
+}
+function usage(value: unknown): CodexWorkerUsage {
+  if (!value || typeof value !== "object") fail("AF_CODEX_EVENT", "Invalid Codex usage");
+  const report = value as Record<string, unknown>;
+  for (const key of ["input_tokens", "cached_input_tokens", "output_tokens"]) if (!Number.isSafeInteger(report[key]) || (report[key] as number) < 0) fail("AF_CODEX_EVENT", "Invalid Codex usage counters");
+  return { input_tokens: report.input_tokens as number, cached_input_tokens: report.cached_input_tokens as number, output_tokens: report.output_tokens as number };
+}
+
+/** Real SDK streaming with explicit completion; callbacks contain metadata only. */
+async function runCodexWorkerInternal(input: CodexWorkerInput, factory: CodexWorkerFactory): Promise<CodexWorkerOutput> {
+  if (!input || !["implementer", "reviewer", "investigator", "decision"].includes(input.role) || !text(input.prompt, 128 * 1024) || !text(input.cwd, 4096) || typeof input.onEvent !== "function" || !input.signal || typeof input.signal.aborted !== "boolean") fail("AF_CODEX_INPUT", "Invalid Codex worker input");
+  if (input.model !== undefined && !text(input.model, 128)) fail("AF_CODEX_INPUT", "Invalid Codex model");
+  if (input.threadId !== undefined && (!text(input.threadId, 128) || !/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/u.test(input.threadId))) fail("AF_CODEX_INPUT", "Invalid Codex thread ID");
+  checkAbort(input.signal);
+  const cwd = await realpath(input.cwd);
+  if (!(await stat(cwd)).isDirectory()) fail("AF_CODEX_INPUT", "Codex working directory must be a directory");
+  const client = await factory({ env: codexWorkerEnvironment(), config: { mcp_servers: {}, web_search: "disabled", approval_policy: "never", sandbox_workspace_write: { network_access: false }, shell_environment_policy: { inherit: "none", set: {} } } });
+  const options: ThreadOptions = { workingDirectory: cwd, sandboxMode: input.role === "implementer" ? "workspace-write" : "read-only", networkAccessEnabled: false, webSearchMode: "disabled", approvalPolicy: "never", ...(input.model ? { model: input.model } : {}) };
+  const thread = input.threadId ? client.resumeThread(input.threadId, options) : client.startThread(options);
+  let threadId = input.threadId ?? thread.id ?? "", finalMessage: string | undefined, completed = false, eventsObserved = 0, reportedUsage: CodexWorkerUsage | undefined;
+  const stream = await thread.runStreamed(`${input.prompt}\n\nReturn the structured report requested by the output schema. Role: ${input.role}. Never include credentials in reports. Use null for inapplicable verdict/replanProposal, and empty arrays for absent findings/branch selection.`, { outputSchema: reportSchema, signal: input.signal });
+  for await (const event of stream.events) {
+    checkAbort(input.signal);
+    if (++eventsObserved > 10000) fail("AF_CODEX_EVENT_LIMIT", "Codex worker event limit exceeded; reconcile its thread");
+    if (!["thread.started", "turn.started", "item.completed", "item.started", "item.updated", "turn.completed", "turn.failed", "error"].includes(event.type)) fail("AF_CODEX_EVENT", "Unknown Codex event type");
+    let notification: CodexWorkerEvent = { type: event.type };
+    if (event.type === "thread.started") {
+      if (!text(event.thread_id, 128) || !/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/u.test(event.thread_id) || (threadId && threadId !== event.thread_id)) fail("AF_CODEX_EVENT", "Codex thread identity changed");
+      threadId = event.thread_id; notification = { type: event.type, threadId };
+    } else if (event.type === "item.completed" || event.type === "item.started" || event.type === "item.updated") {
+      if (!["command_execution", "file_change", "mcp_tool_call", "agent_message", "reasoning", "web_search", "error", "todo_list"].includes(event.item.type)) fail("AF_CODEX_EVENT", "Unknown Codex item type");
+      notification.summary = `Codex ${event.item.type}`;
+      if (event.type === "item.completed" && event.item.type === "agent_message") {
+        if (completed || !text(event.item.text, 64 * 1024)) fail("AF_CODEX_REPORT", "Invalid Codex response ordering or size");
+        finalMessage = event.item.text;
+      }
+    } else if (event.type === "turn.completed") {
+      if (completed) fail("AF_CODEX_EVENT", "Duplicate Codex completion");
+      completed = true; reportedUsage = usage(event.usage); notification.usage = reportedUsage;
+    } else if (event.type === "turn.failed" || event.type === "error") {
+      await input.onEvent({ type: event.type, ...(threadId ? { threadId } : {}), summary: "Codex execution failed; reconcile before retrying" });
+      fail("AF_CODEX_TURN_FAILED", "Codex execution failed; reconcile before retrying");
+    }
+    await input.onEvent(notification);
+  }
+  checkAbort(input.signal);
+  if (!completed || !threadId || finalMessage === undefined) fail("AF_CODEX_INCOMPLETE", "Codex stream ended without a completed report; reconcile its thread");
+  return { threadId, report: validateReport(finalMessage, input.role), ...(reportedUsage ? { usage: reportedUsage } : {}), eventsObserved };
+}
+
+export async function runCodexWorker(input: CodexWorkerInput, factory?: CodexWorkerFactory): Promise<CodexWorkerOutput> {
+  if (process.env.FORGE_FABRIC_TEST_MODE === "1" && !factory) fail("AF_CODEX_TEST_MODE", "Real LLM calls forbidden; provide a simulated SDK factory");
+  try { return await runCodexWorkerInternal(input, factory ?? ((options) => isolatedCodexClient(options, input.cwd, input.signal))); }
+  catch (error) {
+    if (error instanceof CodexWorkerError) throw error;
+    if (input?.signal?.aborted) fail("AF_CODEX_ABORTED", "Codex worker was cancelled; its outcome requires reconciliation");
+    fail("AF_CODEX_EXECUTION", "Codex SDK or event persistence failed; reconcile its thread before retrying");
+  }
+}
+
+/** V2 keeps the operational envelope outside the activity's owner-registered schema. */
+async function runTypedCodexWorkerInternal(input: CodexWorkerInput & { outputSchema: unknown; validateOutput: (data: unknown) => void }, factory?: CodexWorkerFactory): Promise<{ threadId: string; data: unknown; usage?: CodexWorkerUsage }> {
+  if (!input || !text(input.prompt, 128 * 1024) || !text(input.cwd, 4096) || !["implementer", "reviewer", "investigator", "decision"].includes(input.role) || typeof input.validateOutput !== "function") fail("AF_CODEX_INPUT", "Invalid typed worker input");
+  checkAbort(input.signal); const cwd = await realpath(input.cwd);
+  const options: CodexOptions = { env: codexWorkerEnvironment(), config: { mcp_servers: {}, web_search: "disabled", approval_policy: "never", sandbox_workspace_write: { network_access: false }, shell_environment_policy: { inherit: "none", set: {} } } };
+  const client = await (factory ?? ((configuration) => isolatedCodexClient(configuration, cwd, input.signal)))(options);
+  const threadOptions: ThreadOptions = { workingDirectory: cwd, sandboxMode: input.role === "implementer" ? "workspace-write" : "read-only", networkAccessEnabled: false, webSearchMode: "disabled", approvalPolicy: "never", ...(input.model ? { model: input.model } : {}) };
+  const thread = input.threadId ? client.resumeThread(input.threadId, threadOptions) : client.startThread(threadOptions);
+  let threadId = input.threadId ?? thread.id ?? "", finalMessage: string | undefined, completed = false, count = 0, observedUsage: CodexWorkerUsage | undefined;
+  const stream = await thread.runStreamed(`${input.prompt}\nReturn only data matching the requested output schema. Never include credentials.`, { outputSchema: input.outputSchema, signal: input.signal });
+  for await (const event of stream.events) {
+    checkAbort(input.signal); if (++count > 10000) fail("AF_CODEX_EVENT_LIMIT", "Typed worker event budget exceeded");
+    if (!["thread.started", "turn.started", "item.completed", "item.started", "item.updated", "turn.completed", "turn.failed", "error"].includes(event.type)) fail("AF_CODEX_EVENT", "Unknown typed event");
+    if (event.type === "thread.started") { if (!text(event.thread_id, 128) || !/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/u.test(event.thread_id) || threadId && threadId !== event.thread_id) fail("AF_CODEX_EVENT", "Thread identity changed"); threadId = event.thread_id; await input.onEvent({ type: event.type, threadId }); }
+    else if (event.type === "item.completed" && event.item.type === "agent_message") { if (completed || !text(event.item.text, 4 * 1024 * 1024)) fail("AF_CODEX_REPORT", "Invalid typed message"); finalMessage = event.item.text; }
+    else if (event.type === "turn.completed") { if (completed) fail("AF_CODEX_EVENT", "Duplicate completion"); completed = true; observedUsage = usage(event.usage); await input.onEvent({ type: event.type, usage: observedUsage }); }
+    else if (event.type === "turn.failed" || event.type === "error") fail("AF_CODEX_TURN_FAILED", "Typed worker failed; reconcile before retry");
+  }
+  checkAbort(input.signal); if (!completed || !threadId || !finalMessage) fail("AF_CODEX_INCOMPLETE", "Typed worker completion not observed");
+  let data: unknown; try { data = JSON.parse(finalMessage); input.validateOutput(data); } catch { fail("AF_CODEX_REPORT", "Typed worker output schema invalid"); }
+  return { threadId, data, ...(observedUsage ? { usage: observedUsage } : {}) };
+}
+export async function runTypedCodexWorker(input: CodexWorkerInput & { outputSchema: unknown; validateOutput: (data: unknown) => void }, factory?: CodexWorkerFactory): Promise<{ threadId: string; data: unknown; usage?: CodexWorkerUsage }> {
+  if (process.env.FORGE_FABRIC_TEST_MODE === "1" && !factory) fail("AF_CODEX_TEST_MODE", "Real LLM calls forbidden; provide a simulated SDK factory");
+  try { return await runTypedCodexWorkerInternal(input, factory); }
+  catch (error) { if (error instanceof CodexWorkerError) throw error; fail("AF_CODEX_EXECUTION", "Typed SDK or persistence failed; reconcile before retry"); }
+}