@prohost/cli 0.2.1 → 0.2.3

package/dist/agent/codex.d.ts

@@ -0,0 +1,365 @@
+/**
+ * The one place that knows anything about Codex CLI specifically.
+ *
+ * The sibling of `claude.ts`, and it exists for the same reason: `exec.ts` is
+ * deliberately agent-agnostic — prompt on stdin, reply on stdout — and that
+ * lowest common denominator costs a Codex run the two things it can actually
+ * have. A run has no memory of the previous one, and it has no tools for
+ * looking anything up in the workspace it is answering about. Until this
+ * module existed, a `codex` brain ran bare while a `claude` brain got both, so
+ * the same mention answered by two hosts produced visibly different work.
+ *
+ * Everything here was verified against a real `codex-cli 0.144.1` rather than
+ * taken from documentation; the surprises are called out where they are relied
+ * on. Output and configuration used to prove the MCP boundary are deliberately
+ * load-bearing: if that proof is incomplete, the unsandboxed run must not
+ * start. Session continuity and reply parsing still fail independently.
+ */
+/**
+ * Environment variable the API key is handed to Codex in.
+ *
+ * Codex resolves MCP headers from the environment at request time
+ * (`env_http_headers`), which is why the key travels this way rather than in
+ * the config override. The override is part of the command line, and a command
+ * line is world-readable out of `ps`; a child's environment is not. This is the
+ * one place the Codex path is meaningfully *safer* than the Claude one, which
+ * has to keep the key in a `0600` file on disk.
+ */
+export declare const MCP_API_KEY_ENV_VAR = "PROHOST_MCP_API_KEY";
+/**
+ * Is this exec command Codex CLI in non-interactive mode?
+ *
+ * A **heuristic**, and deliberately as narrow as {@link isClaudeExec}: it
+ * matches when the first word of the command is `codex` (or a path ending in
+ * `/codex`) *and* the command uses the `exec` subcommand (or its `e` alias).
+ * Both halves matter. Interactive `codex` has no `--json` and no `resume`
+ * subcommand, so shaping it would break a command that works today.
+ *
+ * Three things are deliberately not shaped, each because appending to it would
+ * do harm rather than nothing:
+ *
+ *  * `codex exec resume …` and `codex exec review …`. The host already chose a
+ *    sub-subcommand; appending our own `resume` would produce two of them.
+ *  * Anything after a `--` sentinel, which is the host saying "stop parsing".
+ *  * A command carrying its own unquoted prompt, e.g. `codex exec hello`. Codex
+ *    takes exactly one prompt positional, so both the `-` this harness appends
+ *    and a `resume <id>` would be a second one — `error: unexpected argument
+ *    '-' found`, on a command that works today. Such a host keeps the plain
+ *    contract; the place to put standing instructions is now the agent's
+ *    ProhostAI profile, which arrives in the prompt itself.
+ *
+ * Shell syntax is different: recognisable Codex exec commands containing it
+ * stay classified as Codex so the harness can fail closed before spawn. Letting
+ * one fall through as a plain command would also drop the verified MCP boundary.
+ */
+export declare function isCodexExec(command: string, platform?: NodeJS.Platform): boolean;
+/**
+ * Shell syntax a shaped Codex command cannot safely preserve.
+ *
+ * Codex commands are eventually executed with `shell: true`, while the harness
+ * currently operates on whitespace-delimited words. Quotes, escapes,
+ * expansions, globs, comments and control/redirection operators all make those
+ * two views differ. Rather than guess at POSIX plus cmd.exe tokenization, only
+ * the deliberately boring argv-shaped subset is accepted. A matching command
+ * is still classified as Codex and then rejected before spawn.
+ */
+export declare function codexShellSyntax(command: string, platform?: NodeJS.Platform): string | undefined;
+/**
+ * The `-c` override that registers the ProhostAI MCP server.
+ *
+ * Codex takes a streamable-HTTP MCP server with **arbitrary** headers, which is
+ * what makes this possible at all: `codex mcp add --url` offers only
+ * `--bearer-token-env-var`, and a bearer token is the *wrong credential* for
+ * this endpoint — the server validates `Authorization: Bearer` as an OAuth
+ * access token, checks it first, and does not fall through to `X-API-Key` when
+ * it fails. A pairing hands out an `X-API-Key`. The `-c` path reaches the same
+ * config layer with none of that restriction.
+ *
+ * `env_http_headers` rather than `http_headers`: both work and both were
+ * verified against the running binary, but the former names an environment
+ * variable to read the value from instead of carrying the value itself, which
+ * keeps a live API key off a command line that anyone on the machine can read
+ * out of `ps`.
+ */
+export declare function prohostMcpEntry(mcpUrl: string): string;
+/**
+ * The whole `mcp_servers` override for a run, ProhostAI server included.
+ *
+ * It is one override, and it has to be: `-c` overrides are applied in order,
+ * and a later whole-table assignment **replaces** an earlier dotted one rather
+ * than merging with it. `-c mcp_servers.prohost={…} -c mcp_servers={…}` — the
+ * shape this had until it was measured — therefore drops the ProhostAI server
+ * outright, on every run that disables anything, while the harness went on
+ * logging "ProhostAI tools wired in" and the prompt went on telling the agent
+ * it had them. (Deep-merging is what happens between the CLI override and the
+ * *config file*, which is what made the wrong shape look right.)
+ */
+export declare function buildMcpOverride(mcpUrl: string): string;
+/** Entries destined for the one `mcp_servers` table override. */
+export interface ExtraEntries {
+    /** `"name"={…}` fragments, for {@link mcpServersOverride}. */
+    entries: string[];
+    /** Names that could not be encoded, for the operator to see. */
+    skipped: string[];
+    /** Literal extra-server credentials, kept off the process command line. */
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * Turn `extra-mcp.json` entries into `mcp_servers` table fragments.
+ *
+ * The name is quoted rather than written as a dotted path, which is what lets
+ * *any* name work. `-c` splits on the first `=` and reads everything before it
+ * as a dotted path, so `-c mcp_servers.fly.io.enabled=false` addresses
+ * `mcp_servers.fly.io` — three segments, not two — and Codex rejects the whole
+ * config with `invalid transport in mcp_servers.fly`. Quoting the segment does
+ * not help either: `mcp_servers."fly.io"` fails the same way, because the
+ * splitting happens before any TOML is parsed. Putting the name inside the
+ * *value* sidesteps the path parser entirely.
+ *
+ * Claude's JSON shape carries literal `headers` and stdio `env` values. Those
+ * must not be copied literally into Codex's `-c` argument: command lines are
+ * readable by other local processes. Translate them to Codex's indirection
+ * fields and put the values in the child environment instead. `type` is also a
+ * Claude-only discriminator; Codex infers the transport from `url`/`command`.
+ */
+export declare function extraMcpEntries(servers: Record<string, Record<string, unknown>>, platform?: NodeJS.Platform): ExtraEntries;
+/**
+ * Table fragments that switch off the servers the operator's Codex install has.
+ *
+ * This is the Codex answer to `--strict-mcp-config`, and it took a real binary
+ * to find. Two mechanisms that look like they should work do not: replacing the
+ * table wholesale does **not** replace it — Codex deep-merges config overrides,
+ * so the operator's servers survive alongside whatever the override adds — and
+ * `--ignore-user-config` does work but drops the operator's *entire* config
+ * with it, taking their model, profile and sandbox settings along for a
+ * security fix they did not ask to pay for that way.
+ *
+ * Setting `enabled=false` per server is the surgical one, verified end to end
+ * against `codex-cli 0.144.1`: the server is then reported `disabled` by
+ * `codex mcp list`, its own definition is left intact, other servers are
+ * untouched, and its tools are genuinely absent from the model's tool list
+ * mid-run.
+ *
+ * Names the extras file defines are left alone. Codex would deep-merge
+ * `enabled=false` into the operator's definition of the same name and produce a
+ * server the operator asked for twice and got zero times, which is a worse
+ * outcome than the collision itself.
+ */
+export declare function disableMcpEntries(configuredNames: string[], keep?: string[]): string[];
+/**
+ * Fold every entry into the single `-c mcp_servers={…}` override.
+ *
+ * One override rather than one per server, because they all reach the same
+ * table and Codex merges rather than replaces — so the combined form is
+ * equivalent, shorter on the command line, and (unlike the dotted-path form)
+ * imposes no constraint on what a server may be called.
+ */
+export declare function mcpServersOverride(entries: string[]): string | undefined;
+/** One MCP server as Codex reports it, and whether this config leaves it on. */
+export interface CodexMcpServer {
+    name: string;
+    enabled: boolean;
+}
+/** Runs one short command in the same directory as Codex itself. */
+export type CommandRunner = (command: string, cwd?: string) => {
+    status: number | null;
+    stdout: string;
+};
+/**
+ * Ask the binary what MCP servers it has, optionally under a `-c` override.
+ *
+ * Asking rather than parsing `~/.codex/config.toml` is deliberate twice over.
+ * `codex mcp list --json` already honours `CODEX_HOME` and the binary's normal
+ * config layering — and, measured on an ordinary install, it
+ * reports servers that appear **nowhere** in that file (plugins contribute
+ * their own). A config file we half-understand is exactly how an isolation
+ * guarantee ends up with a hole in it.
+ *
+ * Passing an override makes this a *verifier*: the listing then reflects the
+ * config the run would actually get, so "did the disable take" is a question
+ * with an answer rather than an assumption.
+ *
+ * The working directory is equally load-bearing. Codex discovers trusted
+ * project `.codex/config.toml` layers from cwd, so a probe in the harness's
+ * launch directory cannot certify a run executed in `$PROHOST_HOME/workspace`
+ * or an explicit `--workdir`. Every probe uses the eventual run cwd.
+ *
+ * Returns `null` — distinct from `[]` — when the question could not be
+ * answered, which for an override also means "that override does not load".
+ * The caller must treat the two differently: an empty list means there is
+ * nothing to disable, while `null` means we do not know, and a run that cannot
+ * enumerate must say so rather than claim an isolation it did not apply.
+ */
+export declare function listMcpServers(binary: string, runner: CommandRunner, override?: string, cwd?: string): CodexMcpServer[] | null;
+/** Disable entries proven to work, and the servers that could not be disabled. */
+export interface VerifiedDisable {
+    entries: string[];
+    /** Servers still reachable from the run. Empty is the outcome we want. */
+    failed: string[];
+}
+/**
+ * Disable entries, checked against the binary before they are used.
+ *
+ * Not paranoia — a measured failure. `{enabled=false}` merges onto a server's
+ * existing definition, and a server contributed by a **plugin** has no entry in
+ * `mcp_servers` to merge onto, so the override defines a table with no
+ * transport and Codex refuses the entire config: `invalid transport in
+ * mcp_servers.github`. Shipped unverified, that would not have leaked a
+ * server — it would have broken *every* run for anyone with a Codex plugin
+ * installed, which is a far worse outcome than the hole it was closing.
+ *
+ * So the entries are tried before they are trusted: one probe for the whole
+ * set, and only if that fails, one probe per server to find which ones can be
+ * disabled and which cannot. The happy path costs a single extra command per
+ * survey; the slow path is paid only by installs that need it.
+ *
+ * `failed` is the honest part. A server that cannot be disabled is still
+ * reachable from the run, and the caller has to say so out loud rather than
+ * report an isolation it only partly achieved.
+ */
+export declare function disableEntriesThatLoad(binary: string, runner: CommandRunner, targets: string[], cwd?: string): VerifiedDisable;
+/**
+ * The `codex` binary out of the host's `--exec` command.
+ *
+ * The host may have written a path (`/opt/homebrew/bin/codex`), and the
+ * enumeration above has to ask the *same* binary the run will use — a different
+ * one on `PATH` could be a different version reading a different `CODEX_HOME`.
+ */
+export declare function codexBinary(command: string): string;
+/**
+ * Is the host running Codex under a named profile?
+ *
+ * Worth asking because it is a hole in the isolation that cannot be closed from
+ * here. `codex exec -p work` additionally loads `$CODEX_HOME/work.config.toml`,
+ * and `codex mcp list` has no way to be asked about a profile: `-p` and
+ * `--profile` are rejected outright, and `-c profile="work"` is refused as a
+ * removed legacy form. So a server defined only inside a profile is invisible
+ * to the enumeration and stays reachable from the run.
+ *
+ * Nothing here can fix that — reading the profile file ourselves is the
+ * config-parsing this deliberately avoids, and it is exactly how an isolation
+ * guarantee ends up with a hole nobody knows about. What it can do is tell the
+ * operator, which is what the caller does with this.
+ */
+export declare function codexProfileName(command: string): string | undefined;
+/**
+ * A host flag that can make the actual run's MCP inventory differ from the
+ * plain `codex mcp list` probe.
+ *
+ * Replaying arbitrary config arguments into a separate shell command would
+ * require parsing the operator's shell syntax exactly. Guessing is not an
+ * isolation boundary, so reject the small set of flags that can alter cwd,
+ * config, or plugin loading. `-C`/`--cd` matters because Codex discovers
+ * project-local config from the directory it runs in. Dedicated model/sandbox
+ * flags remain supported.
+ */
+export declare function codexMcpInventoryFlag(command: string): string | undefined;
+export interface CodexFlags {
+    /** Session (Codex calls it a thread) to resume. Omitted for the first turn. */
+    sessionId?: string;
+    /**
+     * `mcp_servers` table entries for this run: the ProhostAI server, the
+     * operator's extras, and the `enabled=false` switches that keep their own
+     * config's servers out.
+     *
+     * Entries rather than complete overrides, and one list rather than several,
+     * because they must all land in a **single** `-c mcp_servers={…}` — see
+     * {@link buildMcpOverride} for what happens when they don't.
+     */
+    mcpEntries?: string[];
+    /**
+     * Run with approvals and the sandbox bypassed. Default ON — see
+     * {@link codexCommand}. Set false by `agent run --safe-tools`.
+     */
+    skipPermissions?: boolean;
+    /** Quoting target. Defaults to the running platform; tests set it. */
+    platform?: NodeJS.Platform;
+}
+/**
+ * Append the flags this harness needs to a Codex command.
+ *
+ * Four things get added, and each one is load-bearing:
+ *
+ * `--json` turns stdout into a JSONL event stream, which is the only way to
+ * read the thread id back out (and so the only way sessions can continue).
+ *
+ * `--skip-git-repo-check` is not optional. The harness runs the agent in
+ * `$PROHOST_HOME/workspace`, which is not a git repository, and Codex refuses
+ * to start there — `Not inside a trusted directory and --skip-git-repo-check
+ * was not specified.` Without this flag **every** Codex run fails before the
+ * model is ever reached.
+ *
+ * `--yolo` mirrors Claude Code's `--dangerously-skip-permissions`, for the same
+ * reason: in a non-interactive run nobody is there to approve a command, so a
+ * sandboxed brain silently declines the work it was hired for. It is a hidden
+ * alias of `--dangerously-bypass-approvals-and-sandbox`, and passing both spells
+ * is a hard clap error (`cannot be used multiple times`) — so a host who already
+ * wrote either one must not get ours on top, or every run of theirs fails.
+ *
+ * `resume` goes **after** the host's own flags, not before them. `codex exec
+ * resume` accepts a strict subset of `codex exec`'s flags (no `-s`, `-C`,
+ * `--add-dir`, `-p`), and a flag placed after `resume` is parsed by `resume`.
+ * `codex exec -s workspace-write resume <id>` parses; `codex exec resume <id>
+ * -s workspace-write` is rejected. Appending keeps the host's flags where Codex
+ * still understands them.
+ */
+export declare function codexCommand(base: string, flags?: CodexFlags): string;
+/** What the harness got back from one Codex invocation. */
+export type CodexOutput = {
+    ok: true;
+    text: string;
+    sessionId?: string;
+    denials: string[];
+} | {
+    ok: false;
+    error: string;
+    sessionId?: string;
+    denials: string[];
+};
+/**
+ * Read the reply and the thread id out of `--json` stdout.
+ *
+ * Codex emits **JSONL**, not one object: `thread.started` (carrying
+ * `thread_id`), `turn.started`, an `item.completed` per item the turn produced,
+ * then `turn.completed`. Only `agent_message` items are the answer — reasoning
+ * and command items share the stream — and the last one is what a person would
+ * have seen at the end of the run.
+ *
+ * Lines that are not JSON are skipped rather than treated as corruption,
+ * because they are *expected*: an unreachable MCP server puts `ERROR
+ * rmcp::transport::worker: …` straight into this stream, and the run around it
+ * succeeds normally. This was observed, not guessed at.
+ *
+ * As in `parseClaudeOutput`, output with no reply in it is a **failure** rather
+ * than a fallback to posting the raw text. We asked for JSON; anything else
+ * means something went wrong that we do not understand, and the one thing that
+ * must not happen is that reaching a customer's conversation.
+ *
+ * Refused tool calls come back too, as the Codex counterpart of Claude Code's
+ * `permission_denials`. Codex has no such field, but it does emit the fact: a
+ * refused call is an `item.completed` carrying a `mcp_tool_call` with
+ * `status: "failed"` and `error.message: "user cancelled MCP tool call"`, which
+ * is what a run with nobody at the terminal gets every time. Names are spelled
+ * `mcp__<server>__<tool>` so the harness's log line reads identically whichever
+ * brain produced it — and because that is genuinely how Codex names the tool to
+ * the model (verified against 0.144.1, same convention as Claude Code).
+ */
+export declare function parseCodexOutput(stdout: string): CodexOutput;
+/**
+ * Does this look like the resume having been rejected, rather than the agent
+ * having failed at its actual work?
+ *
+ * Two ways a Codex resume can fail where a fresh run would have worked: the
+ * thread is gone (rollout files get cleaned up and the ledger cannot know), or
+ * the host's own flags are ones `codex exec resume` does not accept, which clap
+ * reports as `unexpected argument`. Both must degrade to a fresh session
+ * instead of breaking that surface forever.
+ *
+ * The `thread.started` guard is what keeps this from firing on an ordinary bad
+ * turn. Codex echoes the thread id in that event on **success**, so the
+ * "output mentions the session id" heuristic — which is all `claude.ts` can
+ * do — would match a resumed run that started fine and then failed at its
+ * work, and retrying that runs the agent, and its tools, a second time for
+ * nothing.
+ */
+export declare function looksLikeCodexResumeFailure(output: string, sessionId: string): boolean;