@prohost/cli 0.2.2 → 0.2.3

package/dist/agent/extras.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The operator's opt-in extra MCP servers (`$PROHOST_HOME/extra-mcp.json`).
+ *
+ * Both brains this harness shapes get exactly one MCP server by default — ours
+ * — and that isolation is a security boundary rather than an implementation
+ * detail. A paired run executes with permission prompts off, on prompt text
+ * written by anyone who can mention the agent in the workspace, so every server
+ * reachable from that run is a server a workspace teammate can drive. Claude
+ * Code is held to it by `--strict-mcp-config`; Codex is held to it by
+ * explicitly disabling the servers its own config defines.
+ *
+ * That leaves no way at all to give the agent a tool the operator *does* want
+ * it to have, which is why this file exists. It is **never created by the
+ * CLI** — its presence is the operator's deliberate act, taken after reading
+ * what it costs. Nothing here weakens the boundary; it moves the decision to a
+ * file whose only purpose is to record it.
+ *
+ * Everything in this module fails soft, in the sense `claude.ts` states: a
+ * malformed file is a warning and a run without extras, never a run that
+ * doesn't happen. The operator's agent going quiet is a worse outcome than
+ * their extra server being missing, and the missing server is the one they can
+ * actually see in the log.
+ */
+/** Filename of the operator-authored extras file, inside `$PROHOST_HOME`. */
+export declare const EXTRA_MCP_FILENAME = "extra-mcp.json";
+/** One server definition, passed through to the brain untouched. */
+export type ExtraServer = Record<string, unknown>;
+export interface ExtraMcpServers {
+    /** Accepted definitions, keyed by server name. Empty when there are none. */
+    servers: Record<string, ExtraServer>;
+    /**
+     * Lines for the operator to see when the current grant set is loaded.
+     *
+     * Both the good news and the bad travel this way: which extras loaded is as
+     * worth printing as which were rejected, because "I added a server and the
+     * agent still can't use it" is otherwise a silent, unfalsifiable complaint.
+     */
+    warnings: string[];
+}
+/** Absolute path of the extras file. */
+export declare function extraMcpPath(env?: NodeJS.ProcessEnv): string;
+export interface LoadExtraOptions {
+    env?: NodeJS.ProcessEnv;
+    /** Injectable read, so a test can exercise the parse without a filesystem. */
+    readImpl?: (file: string) => string;
+}
+/**
+ * Read and validate `extra-mcp.json`.
+ *
+ * The file's shape is deliberately the same object Claude Code's
+ * `--mcp-config` takes — `{"mcpServers": {"<name>": {...}}}` — so an operator
+ * can lift a block straight out of a `.mcp.json` they already have rather than
+ * learn a format that exists only here.
+ *
+ * Four rejections, each returning a warning rather than an exception:
+ *
+ *  * **No file.** Not a warning at all — the overwhelmingly common case, and
+ *    the CLI never creates one, so its absence is the default state rather
+ *    than something the operator did wrong.
+ *  * **Unparseable JSON.** A warning and zero extras. The alternative — refuse
+ *    to start — would take a working agent offline over a trailing comma in an
+ *    optional enhancement.
+ *  * **A server named `prohost`.** Rejected loudly and never merged. The name
+ *    is how the prompt, the `--allowedTools` pattern and both generated
+ *    configs refer to the ProhostAI server; letting a file on disk take it
+ *    over would silently redirect a run's workspace lookups — with the agent
+ *    still reporting, in good faith, that it looked them up.
+ *  * **A definition that is not an object.** Rejected per entry, because a
+ *    `"github": "https://…"` typo would otherwise reach the brain as a config
+ *    it cannot parse and take the whole config down with it — including our
+ *    server.
+ */
+export declare function loadExtraMcpServers(options?: LoadExtraOptions): ExtraMcpServers;

package/dist/agent/extras.js

@@ -0,0 +1,118 @@
+/**
+ * The operator's opt-in extra MCP servers (`$PROHOST_HOME/extra-mcp.json`).
+ *
+ * Both brains this harness shapes get exactly one MCP server by default — ours
+ * — and that isolation is a security boundary rather than an implementation
+ * detail. A paired run executes with permission prompts off, on prompt text
+ * written by anyone who can mention the agent in the workspace, so every server
+ * reachable from that run is a server a workspace teammate can drive. Claude
+ * Code is held to it by `--strict-mcp-config`; Codex is held to it by
+ * explicitly disabling the servers its own config defines.
+ *
+ * That leaves no way at all to give the agent a tool the operator *does* want
+ * it to have, which is why this file exists. It is **never created by the
+ * CLI** — its presence is the operator's deliberate act, taken after reading
+ * what it costs. Nothing here weakens the boundary; it moves the decision to a
+ * file whose only purpose is to record it.
+ *
+ * Everything in this module fails soft, in the sense `claude.ts` states: a
+ * malformed file is a warning and a run without extras, never a run that
+ * doesn't happen. The operator's agent going quiet is a worse outcome than
+ * their extra server being missing, and the missing server is the one they can
+ * actually see in the log.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { prohostHome } from './credentials.js';
+import { MCP_SERVER_NAME } from './mcp.js';
+/** Filename of the operator-authored extras file, inside `$PROHOST_HOME`. */
+export const EXTRA_MCP_FILENAME = 'extra-mcp.json';
+/** Absolute path of the extras file. */
+export function extraMcpPath(env = process.env) {
+    return path.join(prohostHome(env), EXTRA_MCP_FILENAME);
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Read and validate `extra-mcp.json`.
+ *
+ * The file's shape is deliberately the same object Claude Code's
+ * `--mcp-config` takes — `{"mcpServers": {"<name>": {...}}}` — so an operator
+ * can lift a block straight out of a `.mcp.json` they already have rather than
+ * learn a format that exists only here.
+ *
+ * Four rejections, each returning a warning rather than an exception:
+ *
+ *  * **No file.** Not a warning at all — the overwhelmingly common case, and
+ *    the CLI never creates one, so its absence is the default state rather
+ *    than something the operator did wrong.
+ *  * **Unparseable JSON.** A warning and zero extras. The alternative — refuse
+ *    to start — would take a working agent offline over a trailing comma in an
+ *    optional enhancement.
+ *  * **A server named `prohost`.** Rejected loudly and never merged. The name
+ *    is how the prompt, the `--allowedTools` pattern and both generated
+ *    configs refer to the ProhostAI server; letting a file on disk take it
+ *    over would silently redirect a run's workspace lookups — with the agent
+ *    still reporting, in good faith, that it looked them up.
+ *  * **A definition that is not an object.** Rejected per entry, because a
+ *    `"github": "https://…"` typo would otherwise reach the brain as a config
+ *    it cannot parse and take the whole config down with it — including our
+ *    server.
+ */
+export function loadExtraMcpServers(options = {}) {
+    const file = extraMcpPath(options.env ?? process.env);
+    const read = options.readImpl ?? ((target) => readFileSync(target, 'utf8'));
+    let raw;
+    try {
+        raw = read(file);
+    }
+    catch (err) {
+        // ENOENT is the normal state and must stay silent. Anything else — a
+        // permission problem, a directory where the file should be — the operator
+        // wants to hear about, because they put the file there on purpose.
+        const code = err.code;
+        if (code === 'ENOENT')
+            return { servers: {}, warnings: [] };
+        return {
+            servers: {},
+            warnings: [`could not read ${file} (${err instanceof Error ? err.message : String(err)}); no extra MCP servers`],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            servers: {},
+            warnings: [`${file} is not valid JSON (${err instanceof Error ? err.message : String(err)}); no extra MCP servers`],
+        };
+    }
+    if (!isPlainObject(parsed) || !isPlainObject(parsed.mcpServers)) {
+        return {
+            servers: {},
+            warnings: [`${file} has no "mcpServers" object; no extra MCP servers`],
+        };
+    }
+    const servers = {};
+    const warnings = [];
+    for (const [name, definition] of Object.entries(parsed.mcpServers)) {
+        if (name === MCP_SERVER_NAME) {
+            warnings.push(`${file} defines a server named "${MCP_SERVER_NAME}" — that name is reserved for the ` +
+                'ProhostAI server and the entry was ignored. Rename it to use it.');
+            continue;
+        }
+        if (!isPlainObject(definition)) {
+            warnings.push(`${file}: server "${name}" is not an object; the entry was ignored`);
+            continue;
+        }
+        servers[name] = definition;
+    }
+    const names = Object.keys(servers);
+    if (names.length > 0) {
+        warnings.push(`extra MCP servers loaded from ${EXTRA_MCP_FILENAME}: ${names.join(', ')} — ` +
+            'anyone who can trigger this agent can use them, with permission prompts off.');
+    }
+    return { servers, warnings };
+}

package/dist/agent/mcp.d.ts

@@ -12,12 +12,13 @@
  */
 export declare const MCP_SERVER_NAME = "prohost";
 /**
- * How Claude Code spells the wired-in tools.
+ * How both shaped brains spell the wired-in tools.
  *
- * Deliberately **not** used for Codex: that binary namespaces MCP tools its own
- * way, and this harness has not verified the spelling against it. Telling an
- * agent a tool is called something it isn't is the same class of failure as
- * naming an endpoint it cannot call — so the prompt names the server instead
- * and leaves the pattern out. See {@link ../prompt.ts}.
+ * Claude Code's spelling was known from its documentation. Codex's was an open
+ * question until 0.2.3 — the prompt named the server and left the pattern out
+ * rather than guess — and the answer, measured by registering a stub MCP server
+ * against a real `codex-cli 0.144.1` and asking the model what it had just
+ * called, is that Codex uses the same `mcp__<server>__<tool>` convention. So
+ * both brains now get the pattern. See {@link ../prompt.ts}.
  */
 export declare const MCP_TOOL_PATTERN = "mcp__prohost__*";

package/dist/agent/mcp.js

@@ -12,12 +12,13 @@
  */
 export const MCP_SERVER_NAME = 'prohost';
 /**
- * How Claude Code spells the wired-in tools.
+ * How both shaped brains spell the wired-in tools.
  *
- * Deliberately **not** used for Codex: that binary namespaces MCP tools its own
- * way, and this harness has not verified the spelling against it. Telling an
- * agent a tool is called something it isn't is the same class of failure as
- * naming an endpoint it cannot call — so the prompt names the server instead
- * and leaves the pattern out. See {@link ../prompt.ts}.
+ * Claude Code's spelling was known from its documentation. Codex's was an open
+ * question until 0.2.3 — the prompt named the server and left the pattern out
+ * rather than guess — and the answer, measured by registering a stub MCP server
+ * against a real `codex-cli 0.144.1` and asking the model what it had just
+ * called, is that Codex uses the same `mcp__<server>__<tool>` convention. So
+ * both brains now get the pattern. See {@link ../prompt.ts}.
  */
 export const MCP_TOOL_PATTERN = `mcp__${MCP_SERVER_NAME}__*`;

package/dist/agent/prompt.d.ts

@@ -22,11 +22,12 @@ export interface PromptContext {
      * How this particular brain spells the wired-in tools, e.g. `mcp__prohost__*`.
      *
      * Set only when the harness has actually verified the spelling for the brain
-     * it is driving — Claude Code, today. Left unset for Codex, whose MCP tool
-     * namespacing this harness has not confirmed: the prompt then names the
-     * server without claiming a prefix, because a wrong tool name is the same
-     * failure as a wrong endpoint. The agent can see its own tool list; it does
-     * not need us to guess at it.
+     * it is driving — Claude Code and, since 0.2.3, Codex, which turned out to
+     * use the same convention. Left unset for every other `--exec` command,
+     * whose namespacing we have no way to know: the prompt then names the server
+     * without claiming a prefix, because a wrong tool name is the same failure as
+     * a wrong endpoint. The agent can see its own tool list; it does not need us
+     * to guess at it.
      */
     mcpToolPattern?: string;
     /**

package/dist/agent/prompt.js

@@ -145,6 +145,16 @@ export function buildPrompt(run, context) {
     // could. Field-observed on the first 0.2.0 deployment; phrased
     // conditionally because other `--exec` brains have no ToolSearch.
     '- If you have a ToolSearch tool, part of your toolkit is deferred and', '  invisible until loaded — web browsing (WebSearch, WebFetch) usually', '  is. Search ToolSearch for a capability before telling anyone you', '  lack it.', 
+    // The correction to the bullet above, and it is here because the bullet
+    // above caused a real production failure. A paired brain searched
+    // ToolSearch for "bash", found nothing — ToolSearch indexes only the
+    // *deferred* tools, and Bash is a direct one — and concluded across a
+    // whole resumed session that it had no shell, while
+    // `--dangerously-skip-permissions` had been handing it the full toolset
+    // the entire time. "Search before you claim you lack it" quietly taught
+    // the opposite of what it meant: that a ToolSearch miss is evidence of
+    // absence. It is not evidence of anything.
+    '- A ToolSearch miss proves nothing. ToolSearch indexes only the deferred', '  tools; the tools listed directly to you are the authoritative set, and', '  a tool can be fully available while ToolSearch has never heard of it', '  (Bash is exactly this). Never reason from a ToolSearch miss to "I do', '  not have that tool".', 
     // The counterpart to the ToolSearch bullet, and the same failure one level
     // up: a brain that assumes it is boxed in reports "I have no access to the
     // codebase" from a machine with the checkout, the credentials and the CLI
@@ -161,6 +171,12 @@ export function buildPrompt(run, context) {
             '  lives, `gh auth status`, whether the command is on PATH. A quick',
             '  look, not an audit — this run has a hard time limit and somebody',
             '  waiting at the end of it.',
+            '- "Looking" means running the command, not inspecting your own tool',
+            '  list. Say you have no shell, no file access, or no checkout only',
+            '  after an attempt failed and you can quote what it said. Introspection',
+            '  is not evidence here: you were started with your tools unrestricted,',
+            '  so a capability you cannot find in a list is far more likely to be',
+            '  one you have not tried.',
         ]), 
     // Only when there is something to look at. Said unconditionally it is a
     // paragraph of advice about a situation that does not exist, which is how a

package/dist/agent/run.d.ts

@@ -59,6 +59,18 @@ export interface AgentRunOptions {
     maxConnections?: number;
     /** Injectable sleep so tests don't wait out the reconnect backoff. */
     sleepImpl?: (ms: number) => Promise<void>;
+    /**
+     * Injectable short-command runner, used before Codex runs to ask which MCP
+     * servers the operator's current config defines. Separate from
+     * {@link spawnImpl} because it is synchronous and captures stdout, and
+     * because a test wants to answer this question without answering the other.
+     * The second argument is the exact cwd the eventual Codex process receives;
+     * Codex discovers project-local config from it.
+     */
+    probeImpl?: (command: string, cwd?: string) => {
+        status: number | null;
+        stdout: string;
+    };
     /** Environment used to locate the run ledger (tests point this at a temp dir). */
     env?: NodeJS.ProcessEnv;
 }
@@ -81,6 +93,26 @@ export interface AgentRunMetrics {
      */
     fatal?: string;
 }
+interface PreparedMcp {
+    /** Claude Code: path of the strict generated MCP config. */
+    mcpConfigPath?: string;
+    /** Codex: entries in the single verified `mcp_servers` override. */
+    codexMcpEntries?: string[];
+    /** Credentials moved out of Codex's process argv. */
+    execEnv?: NodeJS.ProcessEnv;
+    /** ProhostAI tools are actually reachable from this invocation. */
+    mcpWired: boolean;
+    /** A fail-closed preparation error. When set, the agent is never spawned. */
+    error?: string;
+}
+/**
+ * Prepare a fresh Codex MCP override immediately before each invocation.
+ *
+ * No cache is safe here: Codex rereads its config per invocation and the
+ * extras file is the operator's live grant list. Fresh reads make both a new
+ * configured server and a revoked extra visible to the very next run.
+ */
+export declare function codexMcpEntryProvider(options: AgentRunOptions, log: (line: string) => void, workdir?: string): () => PreparedMcp;
 /**
  * Run the harness until the abort signal fires (or ``maxConnections`` is hit).
  *
@@ -88,3 +120,4 @@ export interface AgentRunMetrics {
  * is fatal, because retrying a rejected credential just hammers the server.
  */
 export declare function runAgentHarness(options: AgentRunOptions): Promise<AgentRunMetrics>;
+export {};