@prohost/cli 0.2.0 → 0.2.2

package/dist/agent/prompt.js

@@ -6,6 +6,19 @@
  * a shell script that greps it. The reply contract is stated explicitly so an
  * agent that would otherwise narrate its reasoning returns something sendable.
  */
+/**
+ * Describe one attachment.
+ *
+ * The URL is the point — it is the only part the agent can act on — so it goes
+ * last, where it is easy to copy out of, and it is never abbreviated.
+ */
+function renderAttachment(attachment) {
+    // `image/jpeg` and a bare `image` both count; anything else, including a
+    // missing type, is described as a file rather than guessed at.
+    const kind = attachment.type?.toLowerCase().startsWith('image') ? 'image' : 'file';
+    const name = attachment.name ? ` "${attachment.name}"` : '';
+    return `attached ${kind}${name}: ${attachment.url}`;
+}
 /**
  * Render one line of thread history.
  *
@@ -13,12 +26,18 @@
  * a row with a role and no author — which is what a system row like
  * `{role: "event", text: "Reservation confirmed"}` looks like — reads as
  * `event: …` rather than the nonsense `someone (event): …`.
+ *
+ * Attachments render inline, after the text. An image-only message has no text
+ * at all, so the parts are joined rather than concatenated — otherwise the line
+ * opens with a stray space where the message would have been.
  */
 function renderMessage(message) {
     const who = message.author ?? message.role ?? 'someone';
     const role = message.author && message.role ? ` (${message.role})` : '';
     const when = message.at ? `[${message.at}] ` : '';
-    return `${when}${who}${role}: ${message.text}`;
+    const attachments = (message.attachments ?? []).map((file) => `[${renderAttachment(file)}]`);
+    const body = [message.text, ...attachments].filter((part) => part.length > 0).join(' ');
+    return `${when}${who}${role}: ${body}`;
 }
 /** Render one remembered fact. */
 function renderMemory(memory) {
@@ -28,8 +47,9 @@ function renderMemory(memory) {
 export function buildPrompt(run, context) {
     const name = run.agent_name ?? context.agentName;
     const canReply = Boolean(run.reply_surface !== 'none' && run.reply_path && run.reply_body_key);
+    const title = run.agent_title ? ` (${run.agent_title})` : '';
     const lines = [
-        `You are "${name}", an AI teammate in a ProhostAI workspace.`,
+        `You are "${name}"${title}, an AI teammate in a ProhostAI workspace.`,
         canReply && run.reply_surface === 'conversation'
             ? 'You were mentioned in a conversation and someone is waiting on a reply.'
             : run.reply_surface === 'none'
@@ -39,6 +59,20 @@ export function buildPrompt(run, context) {
                     : `You have been given work on a ${run.reply_surface}. There is nowhere to post a reply.`,
         '',
     ];
+    // The operator's own configuration comes first, above everything the server
+    // generated. It is who this agent *is* — persona, house rules, escalation
+    // policy — and an agent that meets its standing instructions only after four
+    // blocks of run context reads them as an afterthought rather than as its
+    // brief.
+    //
+    // Rendered as instructions, not as quoted data: the text is written by the
+    // person who runs this machine, in their own agent profile, and reaches us
+    // over the same HMAC-verified channel as the rest of the run — the same trust
+    // as the `--exec` command they typed. It is fenced anyway, so the agent can
+    // always tell where its operator stops talking and the server starts.
+    if (run.system_prompt) {
+        lines.push('Your operator configured these standing instructions for you, in your', 'ProhostAI agent profile. Follow them — they define how you work here.', '--- begin operator instructions ---', run.system_prompt, '--- end operator instructions ---', 'Everything below this line is generated by ProhostAI for this one run. It', 'describes what is actually true about this turn and your access to it,', 'which the instructions above do not change.', '');
+    }
     const facts = [];
     if (run.kind)
         facts.push(`Why you woke up: ${run.kind}`);
@@ -72,14 +106,26 @@ export function buildPrompt(run, context) {
     if (run.recent_messages?.length) {
         lines.push('Conversation so far (oldest first):', ...run.recent_messages.map(renderMessage), '--- end of conversation history ---', '');
     }
+    const triggerAttachments = run.trigger_attachments ?? [];
     if (run.trigger_text) {
         // The server caps this excerpt, so say so rather than let an agent assume
         // it has the whole message.
         lines.push('Message that woke you (may be truncated by the server):', run.trigger_text, '');
     }
+    else if (triggerAttachments.length > 0) {
+        // Distinct from "the server didn't send the text": here the message really
+        // had none. An agent told the text was merely missing goes looking for it,
+        // or apologises for not having it, when the picture below IS the message.
+        lines.push('The message that woke you had no text — what follows is all of it.', '');
+    }
     else {
         lines.push('The message text was not included in the event.', '');
     }
+    if (triggerAttachments.length > 0) {
+        lines.push('Sent with that message:', ...triggerAttachments.map((file) => `- ${renderAttachment(file)}`), '');
+    }
+    const hasAttachments = triggerAttachments.length > 0 ||
+        Boolean(run.recent_messages?.some((message) => message.attachments?.length));
     // An agent that doesn't know it is headless narrates as if it were mid-
     // session — "let me connect to that", "I'll check once the tools load" —
     // and that text is what gets posted to a customer, describing a lookup that
@@ -92,7 +138,48 @@ export function buildPrompt(run, context) {
         : '  nothing will stop to ask you for permission: your tools run as soon\n' +
             '  as you call them. Do the work rather than proposing it — but that\n' +
             '  also means a mistaken action happens for real, so check before you\n' +
-            '  change or delete anything.', '- Nothing about your access changes after this turn. Do not say a tool is', '  "connecting", "loading", or about to become available, and do not', '  promise to follow up.', "- State limits plainly. If you cannot look something up, say what you don't", '  know and answer with what you do — a short honest answer beats a', '  confident invented one.', 
+            '  change or delete anything.', '- Nothing about your access changes after this turn. Do not say a tool is', '  "connecting", "loading", or about to become available, and do not', '  promise to follow up.', 
+    // Claude Code lazy-loads part of its catalog — WebSearch/WebFetch among
+    // them — so a run that inspects its loaded tools concludes it cannot
+    // browse and says so to a customer, when one ToolSearch call away it
+    // 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 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
+    // all sitting right there. Only true when tools are ungated — under
+    // --safe-tools the looking-around itself would sit waiting on an approval
+    // nobody is there to give, so the licence is withheld rather than dangled.
+    ...(context.toolsGated
+        ? []
+        : [
+            "- You are running on your operator's own machine, in their shell, with",
+            '  whatever they have installed — not in an empty sandbox. Before you',
+            '  tell anyone you have no access to some repository, codebase, log, or',
+            '  capability, take a QUICK look for it: the usual places a checkout',
+            '  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.',
+        ]), 
+    // 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
+    // prompt teaches an agent to mention attachments nobody sent.
+    ...(!hasAttachments
+        ? []
+        : context.toolsGated
+            ? [
+                '- Attachments above are given as URLs, not as pictures you can see.',
+                '  Fetching one needs a tool that may not run this turn, so if you',
+                '  could not view it, say so rather than guessing at what it shows.',
+            ]
+            : [
+                '- Attachments above are given as URLs, and a URL is not something you',
+                '  can see. To actually look at one, download it to a local file first',
+                '  (`curl -sL "<url>" -o /tmp/attachment.jpg`) and then open that file',
+                '  with your file-reading tool — your vision works on local files, not',
+                '  on links. Never describe an image you have not opened.',
+            ]), "- State limits plainly. If you cannot look something up, say what you don't", '  know and answer with what you do — a short honest answer beats a', '  confident invented one.', 
     // Deliberately does not list which domains are reachable. A paired
     // credential holds a narrow, server-chosen scope set — the current default
     // covers conversations, tasks, cleanings and approvals but NOT reservations
@@ -101,7 +188,13 @@ export function buildPrompt(run, context) {
     // domains the credential can't reach is the same failure as naming an MCP
     // endpoint it can't call: the agent reports a lookup it never made.
     context.mcpServerName
-        ? `- You have ProhostAI tools (mcp__${context.mcpServerName}__*). They are the sanctioned ` +
+        ? `- You have ProhostAI tools${
+        // Named by pattern only where the harness has verified how this brain
+        // spells them; otherwise by server, which the agent can match against
+        // its own tool list without being told a name that might be wrong.
+        context.mcpToolPattern
+            ? ` (${context.mcpToolPattern})`
+            : `, from the MCP server registered as "${context.mcpServerName}"`}. They are the sanctioned ` +
             'way to look up workspace data, so use them rather than guessing. Your credential is ' +
             'deliberately narrow and does not reach every part of the workspace: if a tool returns ' +
             'a permission error, that is a real limit rather than a glitch — say what you could not ' +

package/dist/agent/run.js

@@ -20,7 +20,9 @@
 import os from 'node:os';
 import WebSocket from 'ws';
 import { completeRun, postReply } from './api.js';
-import { MCP_SERVER_NAME, claudeCommand, isClaudeExec, looksLikeResumeFailure, parseClaudeOutput, writeMcpConfig, } from './claude.js';
+import { claudeCommand, isClaudeExec, looksLikeResumeFailure, parseClaudeOutput, writeMcpConfig, } from './claude.js';
+import { MCP_API_KEY_ENV_VAR, codexCommand, isCodexExec, looksLikeCodexResumeFailure, parseCodexOutput, } from './codex.js';
+import { MCP_SERVER_NAME, MCP_TOOL_PATTERN } from './mcp.js';
 import { EVENT_AGENT_RUN_REQUESTED, EVENT_MENTION_CREATED, EVENT_MESSAGE_TEAM_CHAT, eventData, parseRunRequest, } from './contract.js';
 import { ensureWorkspace, streamUrlFor, workspacePath } from './credentials.js';
 import { execAgent } from './exec.js';
@@ -125,13 +127,23 @@ function resolveWorkdir(options, log) {
 function buildRuntime(options, log) {
     const workdir = resolveWorkdir(options, log);
     const sessions = SessionStore.load(options.env, log);
-    const claude = isClaudeExec(options.exec);
+    const brain = isClaudeExec(options.exec)
+        ? 'claude'
+        : isCodexExec(options.exec)
+            ? 'codex'
+            : 'plain';
     const skipPermissions = options.safeTools !== true;
-    if (!claude)
-        return { workdir, sessions, claude, skipPermissions };
-    let mcpConfigPath;
+    if (brain === 'plain') {
+        return { workdir, sessions, brain, skipPermissions, mcpWired: false };
+    }
     const mcpUrl = options.credentials.mcp_url;
-    if (mcpUrl) {
+    let mcpConfigPath;
+    let codexMcpUrl;
+    let execEnv;
+    if (!mcpUrl) {
+        log(`${timestamp()} ! this pairing carries no MCP endpoint; the agent will run without ProhostAI tools`);
+    }
+    else if (brain === 'claude') {
         try {
             mcpConfigPath = writeMcpConfig({
                 mcpUrl,
@@ -149,21 +161,37 @@ function buildRuntime(options, log) {
         }
     }
     else {
-        log(`${timestamp()} ! this pairing carries no MCP endpoint; the agent will run without ProhostAI tools`);
+        // Codex needs no file: the server is a `-c` override on each invocation and
+        // the key is read from the child's environment. Nothing to fail, so nothing
+        // to fall back from.
+        codexMcpUrl = mcpUrl;
+        execEnv = { [MCP_API_KEY_ENV_VAR]: options.credentials.api_key };
+    }
+    const mcpWired = Boolean(mcpConfigPath ?? codexMcpUrl);
+    const tools = mcpWired ? `, ProhostAI tools wired in as ${MCP_SERVER_NAME}` : '';
+    const where = workdir ? ` (workspace: ${workdir})` : '';
+    log(brain === 'claude'
+        ? `${timestamp()} ⚙ Claude Code detected — resuming a session per conversation${tools}${where}`
+        : `${timestamp()} ⚙ Codex detected — resuming a thread per conversation${tools}${where}`);
+    if (brain === 'codex' && mcpWired) {
+        // The one asymmetry worth an operator knowing about, because it is a
+        // security property they may be assuming they have. Claude Code is told to
+        // load our config and nothing else; Codex has no equivalent switch, so its
+        // own `~/.codex/config.toml` servers come along.
+        log(`${timestamp()} ! Codex has no --strict-mcp-config equivalent: this run also holds ` +
+            'whatever MCP servers your ~/.codex/config.toml defines.');
     }
-    log(`${timestamp()} ⚙ Claude Code detected — resuming a session per conversation` +
-        (mcpConfigPath ? `, ProhostAI tools wired in as ${MCP_SERVER_NAME}` : '') +
-        `${workdir ? ` (workspace: ${workdir})` : ''}`);
     // Said out loud every start-up, not buried in --help. This is the line that
     // tells an operator their machine will run tool calls, unprompted, on text
     // written by someone else in their workspace.
+    const bypassFlag = brain === 'claude' ? '--dangerously-skip-permissions' : '--yolo';
     log(skipPermissions
         ? `${timestamp()} ⚠ tools run WITHOUT permission prompts ` +
-            '(--dangerously-skip-permissions). The agent acts as you, with your local ' +
+            `(${bypassFlag}). The agent acts as you, with your local ` +
             'access, on instructions from your workspace. Use --safe-tools to gate them.'
         : `${timestamp()} ⚙ --safe-tools: tools are permission-gated; anything needing ` +
             'approval will not run (nobody is at a terminal to approve it).');
-    return { workdir, sessions, claude, mcpConfigPath, skipPermissions };
+    return { workdir, sessions, brain, mcpConfigPath, codexMcpUrl, execEnv, mcpWired, skipPermissions };
 }
 /**
  * Run the agent command once and turn its output into a reply.
@@ -187,6 +215,7 @@ async function runTurn(run, prompt, options, runtime, log) {
         prompt,
         timeoutMs: remainingMs(),
         cwd: runtime.workdir,
+        env: runtime.execEnv,
         spawnImpl: options.spawnImpl,
     });
     // Wall clock for the whole turn, retry included — what the operator waited,
@@ -199,7 +228,7 @@ async function runTurn(run, prompt, options, runtime, log) {
         detail: result.stderr.trim().slice(-500),
         durationMs: elapsed(),
     });
-    if (!runtime.claude) {
+    if (runtime.brain === 'plain') {
         const result = await exec(options.exec);
         if (!result.ok)
             return failure(result);
@@ -209,29 +238,55 @@ async function runTurn(run, prompt, options, runtime, log) {
             : { ok: false, reason: 'agent produced no output', durationMs: elapsed() };
     }
     // No session bookkeeping on a dry run. `--dry-run` promises to make no
-    // writes, and a resumed turn is a write: Claude Code records it in the
+    // writes, and a resumed turn is a write: both brains record it in their
     // transcript whether or not we post the reply, so remembering the session
     // would leave the next *real* run continuing from an answer nobody saw.
     const key = options.dryRun ? undefined : sessionKeyFor(run);
     const sessionId = runtime.sessions.get(key);
-    const shape = { mcpConfigPath: runtime.mcpConfigPath, skipPermissions: runtime.skipPermissions };
-    let result = await exec(claudeCommand(options.exec, { ...shape, sessionId }));
+    const codex = runtime.brain === 'codex';
+    // Same three questions for both brains — resume this thread, wire these
+    // tools, gate or don't — asked with each one's own flags.
+    const build = (resume) => codex
+        ? codexCommand(options.exec, {
+            sessionId: resume,
+            mcpUrl: runtime.codexMcpUrl,
+            skipPermissions: runtime.skipPermissions,
+        })
+        : claudeCommand(options.exec, {
+            sessionId: resume,
+            mcpConfigPath: runtime.mcpConfigPath,
+            skipPermissions: runtime.skipPermissions,
+        });
+    let result = await exec(build(sessionId));
     // A remembered session may simply be gone — transcripts are cleaned up and
     // the ledger can't know. One retry without it, because the alternative is a
     // surface that fails every run forever over an optimisation.
+    const resumeFailed = codex ? looksLikeCodexResumeFailure : looksLikeResumeFailure;
     if (!result.ok &&
         sessionId &&
-        looksLikeResumeFailure(`${result.stderr}\n${result.stdout}`, sessionId) &&
+        resumeFailed(`${result.stderr}\n${result.stdout}`, sessionId) &&
         // Skipped rather than squeezed into a token budget: a retry with no time
         // left would be killed on the spot and reported as a timeout, which is a
         // worse error message than the resume failure it replaced.
         remainingMs() > 0) {
         log(`    … session ${sessionId.slice(0, 12)} could not be resumed; starting a fresh one`);
         runtime.sessions.forget(key);
-        result = await exec(claudeCommand(options.exec, shape));
+        result = await exec(build());
     }
     if (!result.ok)
         return failure(result);
+    if (codex) {
+        const output = parseCodexOutput(result.stdout);
+        if (!output.ok) {
+            return {
+                ok: false,
+                reason: 'the agent did not produce a usable reply',
+                detail: output.error,
+                durationMs: elapsed(),
+            };
+        }
+        return { ok: true, reply: output.text, durationMs: elapsed(), sessionId: output.sessionId };
+    }
     const parsed = parseClaudeOutput(result.stdout);
     // A denied tool is not an error the agent reports — the turn succeeds and the
     // reply just quietly lacks whatever the tool would have found. Printing it is
@@ -265,7 +320,10 @@ async function handleRun(run, options, runtime, api, log, sleep) {
         // Named only when the tools are actually reachable from this invocation.
         // Telling an agent about an endpoint it has no client for is what produced
         // replies describing lookups that never happened.
-        mcpServerName: runtime.mcpConfigPath ? MCP_SERVER_NAME : undefined,
+        mcpServerName: runtime.mcpWired ? MCP_SERVER_NAME : undefined,
+        // Only Claude Code's spelling has been verified against the binary, so only
+        // Claude Code gets told a pattern. See PromptContext.mcpToolPattern.
+        mcpToolPattern: runtime.brain === 'claude' && runtime.mcpWired ? MCP_TOOL_PATTERN : undefined,
         toolsGated: !runtime.skipPermissions,
     });
     const result = await runTurn(run, prompt, options, runtime, log);

package/dist/agent/shell.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Quoting for the `shell: true` command lines the brain harnesses build.
+ *
+ * Shared by `claude.ts` and `codex.ts` because both append values — a session
+ * id we stored, a path under `$PROHOST_HOME`, a TOML config override — to a
+ * string that a shell will parse.
+ */
+/**
+ * Quote a value for a `shell: true` command line on this platform.
+ *
+ * Every value that goes through here is ours or the operator's — never
+ * event-derived text. It is quoted anyway: a home directory with a space in it
+ * is ordinary, and "the inputs are trusted" is the assumption that stops being
+ * true the first time someone extends this.
+ *
+ * Windows needs its own branch. `shell: true` there runs `cmd.exe`, where a
+ * single quote is an ordinary character rather than a quoting one — POSIX
+ * quoting would hand the child a config path with literal apostrophes around
+ * it, and the tools would simply never load.
+ */
+export declare function shellQuote(value: string, platform: NodeJS.Platform): string;
+/** Pipes, lists, redirections, subshells — anything that makes "append to the end" wrong. */
+export declare const SHELL_CONTROL_OPERATORS: RegExp;

package/dist/agent/shell.js

@@ -0,0 +1,27 @@
+/**
+ * Quoting for the `shell: true` command lines the brain harnesses build.
+ *
+ * Shared by `claude.ts` and `codex.ts` because both append values — a session
+ * id we stored, a path under `$PROHOST_HOME`, a TOML config override — to a
+ * string that a shell will parse.
+ */
+/**
+ * Quote a value for a `shell: true` command line on this platform.
+ *
+ * Every value that goes through here is ours or the operator's — never
+ * event-derived text. It is quoted anyway: a home directory with a space in it
+ * is ordinary, and "the inputs are trusted" is the assumption that stops being
+ * true the first time someone extends this.
+ *
+ * Windows needs its own branch. `shell: true` there runs `cmd.exe`, where a
+ * single quote is an ordinary character rather than a quoting one — POSIX
+ * quoting would hand the child a config path with literal apostrophes around
+ * it, and the tools would simply never load.
+ */
+export function shellQuote(value, platform) {
+    if (platform === 'win32')
+        return `"${value.replace(/"/g, '""')}"`;
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Pipes, lists, redirections, subshells — anything that makes "append to the end" wrong. */
+export const SHELL_CONTROL_OPERATORS = /[|&;<>(){}`]|\$\(/;

package/dist/version.d.ts

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export declare const CLI_VERSION = "0.2.0";
+export declare const CLI_VERSION = "0.2.2";
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
-export declare const USER_AGENT = "prohost-cli/0.2.0";
+export declare const USER_AGENT = "prohost-cli/0.2.2";

package/dist/version.js

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export const CLI_VERSION = '0.2.0';
+export const CLI_VERSION = '0.2.2';
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
 export const USER_AGENT = `prohost-cli/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prohost/cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Run your own AI agent as a ProhostAI teammate, and stream your account's webhooks to your laptop.",
   "type": "module",
   "license": "MIT",