@sweny-ai/core 0.1.141 → 0.1.143

package/dist/harness/codex.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Codex harness (#331): runs a node on OpenAI Codex through `codex exec --json`.
+ *
+ * Interfaces used, all read from openai/codex at rust-v0.159.2:
+ * - `codex-rs/exec/src/cli.rs`: `exec --json`, `--output-schema <file>`,
+ *   `--ignore-user-config`, `--ignore-rules`, `--ephemeral`,
+ *   `--skip-git-repo-check`, `--sandbox`, `--cd`, `--model`, `-c key=value`,
+ *   prompt on stdin with `-`.
+ * - `codex-rs/exec/src/exec_events.rs`: the JSONL events (`thread.started`,
+ *   `turn.started|completed|failed`, `item.started|updated|completed`,
+ *   `error`) and item kinds.
+ * - `sdk/typescript/src/exec.ts`: how the official SDK spawns the same CLI
+ *   (config overrides as TOML values, stdin prompt, exit handling).
+ * - `codex-rs/core/config.schema.json`: `features.*`, `web_search`,
+ *   `agents.enabled`, `sandbox_workspace_write.network_access`,
+ *   `mcp_servers.<id>.{command,args,env,env_vars,url,http_headers,...}`.
+ * - `codex-rs/rmcp-client/src/utils.rs`: an MCP stdio server gets only a
+ *   small default env plus the names listed in `env_vars`, so the tool
+ *   bridge token travels by name, never in argv.
+ *
+ * Every sweny opinion in the Codex column of the enforcement matrix is
+ * enforced natively here, kept by sweny (watchdog, fencing, env scoping,
+ * output validation), reported in `degraded`, or refused under strict policy
+ * by `policyGate`. Nothing is dropped silently.
+ */
+import type { Logger, McpServerConfig, ToolContext } from "../types.js";
+import { type SandboxMode } from "../agent-env.js";
+import type { AgentHarness, HarnessCapabilities, HarnessCompleteRequest, HarnessInfo, HarnessRunRequest, HarnessRunResult, ToolClass } from "./types.js";
+import { CODEX_CAPABILITIES } from "./capabilities.js";
+import { type HarnessPolicyMode } from "./policy.js";
+import { type SandboxWrapper } from "./sandbox-wrapper.js";
+export { CODEX_CAPABILITIES };
+/** Oldest Codex CLI whose flags this adapter uses (`--ignore-user-config`, `--ignore-rules`). */
+export declare const MIN_CODEX_VERSION = "0.159.0";
+/**
+ * Codex features sweny always turns off, so a node sees only the tools sweny
+ * gave it: ChatGPT apps and plugins (their own MCP servers), tool suggestions,
+ * browser and computer use, lifecycle hooks, and image generation. Keys from
+ * `codex-rs/features/src/lib.rs` at rust-v0.159.2.
+ */
+export declare const CODEX_ISOLATION_FEATURES_OFF: readonly ["apps", "plugins", "tool_suggest", "browser_use", "computer_use", "hooks", "image_generation"];
+/**
+ * Hosts Codex itself needs (its model API and ChatGPT sign-in), always allowed
+ * through the sandbox wrapper, plus the host of `OPENAI_BASE_URL` when set.
+ */
+export declare function codexBackendHosts(env?: Record<string, string | undefined>): string[];
+export interface CodexHarnessOptions {
+    /** Model override (`--model`). Free text; sweny has no model opinion. */
+    model?: string;
+    /** Tool-call budget the watchdog enforces when a node sets no `max_turns` (default: 20). */
+    maxTurns?: number;
+    /** Working directory (default: process.cwd()). */
+    cwd?: string;
+    logger?: Logger;
+    /** Default tool context for standalone usage (not via the executor). */
+    defaultContext?: ToolContext;
+    /** Catalog defaults, overridden by per-run skill servers and explicit mcpServers. */
+    defaultMcpServers?: Record<string, McpServerConfig>;
+    /** Explicit external MCP servers, overriding defaults and per-run skill servers. */
+    mcpServers?: Record<string, McpServerConfig>;
+    /** Extra env var names passed through (see agent-env.ts). Default: `SWENY_ENV_PASSTHROUGH`. */
+    envPassthrough?: string[];
+    /** Scope the Codex env to the allowlist. Default: `SWENY_ENV_SCOPE`, else on in CI. */
+    envScope?: boolean;
+    /**
+     * Codex sandbox for commands: `strict` = `workspace-write` or fail, `auto` =
+     * `workspace-write` when the host can sandbox, `off` = `danger-full-access`.
+     * Default: `SWENY_SANDBOX`, else `auto` in CI and `off` locally.
+     */
+    sandbox?: SandboxMode;
+    /** Sandbox preflight probe (test seam). Returns a reason when the host cannot sandbox. */
+    sandboxProbe?: () => string | undefined;
+    /**
+     * The host's process sandbox wrapper (#360 step 2). `undefined` = detect
+     * srt once per process; `null` = none (test seam).
+     */
+    sandboxWrapper?: SandboxWrapper | null;
+    /** `strict` refuses a node with unenforceable opinions. Default: {@link resolveHarnessPolicy}. */
+    policy?: HarnessPolicyMode;
+    /** The Codex CLI. Default: `SWENY_CODEX_PATH`, else `codex` on PATH. Test seam for the fake. */
+    codexCommand?: {
+        command: string;
+        args: string[];
+    };
+    /** Shim command override for the tool bridge (test seam). */
+    toolBridgeShim?: {
+        command: string;
+        args: string[];
+    };
+    /** Grace period between SIGTERM and SIGKILL when stopping Codex (default: 2000 ms). */
+    killGraceMs?: number;
+}
+/** A TOML value for `-c key=value`, as the official SDK writes it (sdk/typescript/src/exec.ts). */
+export declare function toTomlValue(value: unknown): string;
+/**
+ * Split `disallowed_tools` names into portable classes Codex can act on and
+ * the names it has no tool for.
+ */
+export declare function translateDenyNames(names?: readonly string[]): {
+    classes: ToolClass[];
+    unknown: string[];
+};
+/**
+ * Is this JSON schema accepted by OpenAI strict structured outputs? Codex
+ * sends `--output-schema` with `strict: true` (core/src/session/turn.rs), which
+ * requires `additionalProperties: false` and every property listed in
+ * `required` on every object. Not a full check; it catches the common misses.
+ */
+export declare function isStrictCompatibleSchema(schema: unknown): boolean;
+export declare class CodexHarness implements AgentHarness {
+    readonly id: "codex";
+    readonly capabilities: HarnessCapabilities;
+    /**
+     * Empty on purpose: judges use Codex's own default model. Leaving this
+     * undefined would fall back to the Claude judge model, which Codex cannot run.
+     */
+    readonly defaultJudgeModel = "";
+    readonly logger: Logger;
+    private model;
+    private maxTurns;
+    private cwd;
+    private defaultContext;
+    private mcpServers;
+    private defaultMcpServers;
+    private envPassthrough;
+    private envScope;
+    private sandboxMode;
+    private sandboxProbe;
+    private sandboxWarned;
+    private sandboxWrapper;
+    private loginWarned;
+    private policyMode;
+    private codexCommand;
+    private toolBridgeShim;
+    private killGraceMs;
+    private preflightResult;
+    private version;
+    constructor(opts?: CodexHarnessOptions);
+    info(): HarnessInfo;
+    /** `codex --version`, checked against {@link MIN_CODEX_VERSION}. Cached per instance. */
+    preflight(): Promise<{
+        ok: true;
+        version: string;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /** Env for the Codex process: scoped like Claude Code's, with Codex's auth vars instead of Anthropic's. */
+    private buildEnv;
+    /** The node policy after `disallowed_tools` names are translated into Codex classes. */
+    private compilePolicy;
+    /** Resolve the Codex `--sandbox` value for a normal (not read-only) run. */
+    private resolveSandbox;
+    /** argv shared by run() and complete(). */
+    private baseArgs;
+    /** `-c mcp_servers.<id>.*` for each server. Returns the args and anything Codex cannot load. */
+    private mcpArgs;
+    /** Spawn codex exec, feed the prompt on stdin, and read JSONL until it exits. */
+    private exec;
+    /**
+     * Run a node. The gate runs first: in strict mode a node whose opinions
+     * Codex cannot honor is refused before Codex starts. With a sandbox mode
+     * other than off, the whole Codex process runs inside the host's process
+     * sandbox wrapper (#360 step 2) when there is one, which also keeps the
+     * node's per-host egress allowlist that Codex cannot keep itself.
+     */
+    run(req: HarnessRunRequest): Promise<HarnessRunResult>;
+    /** Map one exec outcome onto a NodeResult with Claude Code's semantics. */
+    private toResult;
+    /**
+     * One completion: read-only sandbox, no shell, no web search, no subagents,
+     * no MCP. null when it failed (callers fail closed).
+     */
+    complete(req: HarnessCompleteRequest): Promise<string | null>;
+}