@prohost/cli 0.2.2 → 0.2.3

package/dist/agent/codex.d.ts

@@ -11,9 +11,9 @@
  *
  * 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. As in `claude.ts`, nothing in this module is load-bearing for
- * correctness: if detection misses, if the session is unresumable, if the JSON
- * is not what we expect — the run still happens and still completes.
+ * 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.
@@ -35,22 +35,35 @@ export declare const MCP_API_KEY_ENV_VAR = "PROHOST_MCP_API_KEY";
  * Both halves matter. Interactive `codex` has no `--json` and no `resume`
  * subcommand, so shaping it would break a command that works today.
  *
- * Three things this refuses to touch, each because appending to it would do
- * harm rather than nothing:
+ * Three things are deliberately not shaped, each because appending to it would
+ * do harm rather than nothing:
  *
- *  * Commands with shell control operators. Flags are appended to the *end* of
- *    the string, so for `codex exec | jq .` they would land on `jq`.
  *  * `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 prompt, e.g. `codex exec 'Be terse'`. Codex
+ *  * 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 isCodexExec(command: string): boolean;
+export declare function codexShellSyntax(command: string, platform?: NodeJS.Platform): string | undefined;
 /**
  * The `-c` override that registers the ProhostAI MCP server.
  *
@@ -68,12 +81,192 @@ export declare function isCodexExec(command: string): boolean;
  * 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;
-    /** The paired MCP endpoint, when tools are being wired in. */
-    mcpUrl?: 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`.
@@ -116,10 +309,12 @@ 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.
@@ -139,6 +334,15 @@ export type CodexOutput = {
  * 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;
 /**