@prohost/cli 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,71 @@ Versions follow [semver](https://semver.org/). Publishing is automated: merging
 a version bump to `main` triggers `.github/workflows/npm-publish-cli.yml`, which
 builds via `prepack`, runs the suite, publishes, and tags `cli-v<version>`.
 
+## 0.2.1
+
+- Prompt: tell brains with a ToolSearch tool that part of their toolkit
+  (notably WebSearch/WebFetch) is deferred and must be loaded before use, so
+  a paired agent stops telling customers it cannot browse the web when it can.
+
+## 0.2.0
+
+The harness stopped being a one-shot prompt pipe. 0.1.x answered every mention
+from a single 500-character excerpt, in whatever directory you happened to be
+standing in, with no memory of the previous message and no way to look anything
+up — and told the agent about an MCP endpoint it had no client for, which
+produced replies confidently describing lookups that never happened.
+
+- **The agent gets the thread.** `agent.run_requested` now carries
+  `recent_messages` and `memories` when the server sends them, rendered as
+  delimited "Conversation so far" and "Things you remember" blocks ahead of the
+  triggering message. Both fields are optional in both directions: an older
+  server behaves exactly as before, and a newer one can add or move fields
+  without breaking a CLI that is already on someone's laptop.
+- **Claude Code runs keep their session.** When `--exec` is `claude` in print
+  mode, the harness runs it with `--output-format json`, reads the reply and
+  `session_id` out of the result, and `--resume`s that session for the next run
+  on the same conversation (ledger: `~/.prohost/sessions.json`). A session that
+  has expired is retried once without `--resume` rather than failing the surface
+  forever. Any other `--exec` command keeps the exact stdin/stdout behaviour it
+  had before.
+- **Claude Code runs can actually act.** Runs are invoked with
+  `--dangerously-skip-permissions`: in print mode nobody is at a terminal to
+  approve a tool call, so a gated brain silently declines the work it was hired
+  for. `--safe-tools` (alias `--no-skip-permissions`) opts back into gating. The
+  README now states the trust model plainly — the agent runs as you, unsandboxed,
+  on instructions written by workspace teammates — and the harness says so on
+  every start-up. Codex users should pass `codex --yolo` in their `--exec`.
+- **Reply bodies carry the server's extra fields.** `reply_instructions` may now
+  include `body_extra`, merged into the reply POST alongside the body field —
+  first use is `reply_to_message_id`, so a team-chat reply lands in the right
+  sub-thread. Merged without being interpreted, so the server can extend the
+  reply body without a CLI release; the body field always wins a key collision,
+  so nothing can displace the reply text.
+- **Claude Code runs get ProhostAI tools.** The paired MCP endpoint is written
+  to a `0600` `~/.prohost/mcp.json` and passed as `--mcp-config` with
+  `--strict-mcp-config` (so the run never picks up the operator's own MCP
+  servers) and `--allowedTools`, since nothing can be approved interactively in
+  print mode. Tools the run asked for and was refused are now printed.
+- **The prompt is honest about the run.** It states that this is a single
+  non-interactive turn, that tools needing approval are unavailable, and that
+  the agent should name what it could not do instead of narrating a lookup. The
+  ProhostAI tools are described only when they are actually wired in, and no
+  workspace domain is named — a paired credential's scopes don't reach every
+  tool (reservations and listings are excluded today), so the prompt says the
+  credential is narrow and that a permission error is a real limit.
+- **A dedicated workspace.** `agent run` gains `--workdir`, defaulting to
+  `$PROHOST_HOME/workspace` instead of the current directory. Agents read
+  `CLAUDE.md`, `.claude/settings.json` and `.mcp.json` from their working
+  directory; started from a code checkout they inherit that repo's instructions
+  and permission denials. `--cwd` still works as an alias.
+- **`prohost agent install-daemon` / `uninstall-daemon`.** Generates and loads a
+  `KeepAlive` launchd agent on macOS so the harness survives logout and reboot,
+  logging to `$PROHOST_HOME/agent.log`. The plist carries your `PATH` forward,
+  since launchd's default one contains no `claude`, and the daemon is scoped to
+  `$PROHOST_HOME` — installing twice from one home replaces the daemon instead
+  of adding a second one running the same credential. On Linux it prints a
+  systemd-user unit to install by hand.
+
 ## 0.1.2
 
 The release that carries 0.1.1's fix to users. 0.1.1 was tagged in the monorepo

package/README.md

@@ -27,6 +27,9 @@ npx @prohost/cli agent pair --code <pairing-code>
 
 # 2. Point it at whatever agent you already use.
 npx @prohost/cli agent run --exec 'claude -p'
+
+# 3. Optional, but you probably want it: keep it running across reboots.
+npx @prohost/cli agent install-daemon --exec 'claude -p'
 ```
 
 That's it — @-mention the agent in ProhostAI and it answers from your machine.
@@ -84,7 +87,7 @@ in a team thread, a 1:1 DM, a task comment, a trigger — you'll see:
 Other agents, same command:
 
 ```bash
-npx @prohost/cli agent run --exec 'codex exec -'
+npx @prohost/cli agent run --exec 'codex exec - --yolo'
 npx @prohost/cli agent run --exec 'goose run -i -'
 npx @prohost/cli agent run --exec './my-agent.sh'
 ```
@@ -106,13 +109,74 @@ nothing is posted and the run is left open.
 2. The CLI verifies the event's HMAC signature. An event that doesn't verify is
    **not executed** — the whole point of the signature is that a run event makes
    your machine execute a command.
-3. It builds a prompt (who your agent is, the conversation, the message that
-   mentioned it) and runs your `--exec` command with that prompt on **stdin**.
+3. It builds a prompt — who your agent is, what it's replying to, the recent
+   messages in the thread, anything the account remembers that bears on it, and
+   the message that mentioned it — and runs your `--exec` command with that
+   prompt on **stdin**.
 4. Your command's **stdout** is the reply. It's posted into the conversation
    verbatim, so print the message and nothing else — no preamble, no reasoning.
+   (Claude Code is the exception: see below.)
 5. The run is completed either way. A command that crashes, times out, or prints
    nothing reports `failed`; a run is never left hanging.
 
+### Where your agent runs
+
+By default the command runs in `~/.prohost/workspace`, which the CLI creates —
+**not** the directory you started `agent run` from. That matters more than it
+sounds like it does: coding agents read their working directory as
+configuration. Start one inside a code checkout and it picks up that repo's
+`CLAUDE.md`, its `.claude/settings.json` permission list, and its `.mcp.json`
+servers — so your agent answers a customer's question carrying instructions
+about a codebase, and quietly refuses tools that repo happens to deny.
+
+Point `--workdir` somewhere else if you want the agent to work in a particular
+directory. Just choose it deliberately.
+
+### If your agent is Claude Code
+
+When `--exec` starts with `claude` and asks for print mode (`-p` / `--print`),
+the CLI does three extra things. Every other command — Codex, goose, your own
+script — is left exactly alone.
+
+**It keeps the conversation.** Each run is a fresh process, so without this your
+agent meets every message as its first: someone answers its clarifying question
+and gets a reply that has forgotten asking. The CLI reads the `session_id` out
+of Claude Code's JSON output, records it per conversation in
+`~/.prohost/sessions.json`, and `--resume`s it next time. Sessions don't live
+forever; when one is gone the run is retried once from scratch rather than
+failing.
+
+**It lets the agent actually do things.** Runs are invoked with
+`--dangerously-skip-permissions`, so tool calls execute without stopping to ask.
+This is deliberate: in print mode there is nobody at a terminal to approve
+anything, so a permission-gated brain silently declines to do the work you hired
+it for. **Read the trust model below before you leave this running.** Pass
+`--safe-tools` (or `--no-skip-permissions`) to gate tools instead — expect the
+agent to answer rather than act.
+
+**It gives the agent your ProhostAI tools.** The MCP endpoint from your pairing
+is written to `~/.prohost/mcp.json` (`chmod 600` — it holds your API key) and
+passed with `--mcp-config`, so the agent can look things up instead of guessing.
+`--strict-mcp-config` is passed too: the run gets *only* this server, never the
+MCP servers you use for your own work.
+
+A pairing is deliberately narrow, so not every tool will work: today's default
+scopes cover conversations, tasks, cleanings and approvals, but **not**
+reservations or listings — those tools return a permission error. The prompt
+tells the agent to say what it couldn't reach rather than answer as if it had,
+and refused tools are printed in the run log.
+
+**It reads the reply out of JSON.** The run is invoked with
+`--output-format json`, and the `result` field is what gets posted. If that
+output isn't JSON — a login prompt, a crash banner — the run is reported failed
+rather than pasting it into a customer's conversation.
+
+Detection is deliberately narrow: it matches only when `claude` is the first
+word of the command *and* print mode is asked for. Anything else — `npx claude
+-p`, `env FOO=1 claude -p`, a wrapper script, or any command containing a pipe,
+redirect, or `&&` — keeps the plain stdin/stdout contract untouched. So
+`--exec 'sh -c "claude -p"'` is the way to opt out.
+
 Runs are handled one at a time, and each run executes **at most once on this
 machine** — even across restarts. Started runs are recorded in
 `~/.prohost/runs.json` before the command launches, so a webhook redelivery
@@ -121,12 +185,35 @@ your agent a second time. That matters because your agent holds a credential:
 a second execution could file the same task or send the same email again, which
 no amount of message deduplication would undo.
 
-**Treat mention text as untrusted input.** The prompt contains a message someone
-else wrote, and your agent runs on your machine with whatever credentials and
-tools you gave it. Give it the access the job needs and no more — the same
-judgement you'd apply to any agent reading input from the internet. (The message
-only ever reaches your command on stdin, never the shell, so it cannot inject a
-command.)
+### The trust model — read this once
+
+`agent run` is a standing instruction to execute a command on your machine when
+someone in your ProhostAI workspace asks. Be clear-eyed about what that means:
+
+- **The agent runs as you.** Same user, same filesystem, same SSH keys, same
+  logged-in CLIs. It is not sandboxed.
+- **By default its tools are not gated.** With `--dangerously-skip-permissions`
+  (the default for Claude Code) nothing pauses for confirmation. That is what
+  makes it useful and it is also the whole risk.
+- **The instructions come from other people.** The prompt carries a message a
+  teammate wrote, plus thread history. Treat all of it as untrusted input — the
+  same judgement you'd apply to any agent reading text from the internet. A
+  colleague's compromised account, or a guest message quoted into a thread, is
+  an instruction channel into your laptop.
+
+What the harness does to bound this: the message reaches your command on
+**stdin only**, never the shell, so it cannot inject a command; runs execute at
+most once each; every event's signature is verified before anything runs; the
+agent works in `~/.prohost/workspace` rather than your code; and
+`--strict-mcp-config` keeps your own MCP servers out of the run.
+
+What it does **not** do: sandbox the process. If that matters for your machine,
+run `agent run` inside a container or a dedicated user account, or use
+`--safe-tools` and accept that the agent will answer rather than act.
+
+Other agents: the CLI shapes no command but Claude Code's, so give yours its own
+equivalent flag — `codex --yolo` for Codex CLI, whatever your runner calls it —
+and apply the same judgement.
 
 ### `agent run` flags
 
@@ -135,10 +222,51 @@ command.)
 | `--exec` | *(required)* | Command to run for each requested run. Prompt arrives on stdin. |
 | `--timeout` | `300` | Seconds one run may take before the command is killed. |
 | `--dry-run` | off | Print the reply that would be posted; write nothing. |
-| `--cwd` | current dir | Working directory for the command. |
+| `--workdir` | `~/.prohost/workspace` | Working directory for the command. See "Where your agent runs". |
+| `--cwd` | — | Deprecated alias for `--workdir`. |
 | `--machine` | OS hostname | Name shown next to the connection in ProhostAI. |
 | `--url` | paired value | Websocket endpoint override. Pairing stores the URL the server reports, so you should not normally need this. |
 | `--allow-unverified` | off | Run events whose signature can't be verified. See below. |
+| `--safe-tools` | off | Gate the agent's tools behind permission prompts instead of bypassing them. Claude Code only. Alias: `--no-skip-permissions`. |
+
+### Keeping it running
+
+`agent run` in a terminal window stops being an agent the moment you close the
+window or the laptop reboots — and nothing tells you it stopped. Someone
+@-mentions it and the run times out server-side.
+
+```bash
+npx @prohost/cli agent install-daemon --exec 'claude -p'
+npx @prohost/cli agent uninstall-daemon
+```
+
+On macOS this writes a launchd agent to
+`~/Library/LaunchAgents/ai.prohost.agent.<id>.plist` and loads it, with
+`KeepAlive` on so it starts at login and restarts if it exits. Output goes to
+`$PROHOST_HOME/agent.log` — the first place to look when the agent is quiet.
+Re-running it with a different `--exec` replaces the old daemon.
+
+The daemon is scoped to `$PROHOST_HOME`, because that's where the one credential
+lives: installing twice from the same home replaces the daemon rather than
+adding a second one. To run two agents on one machine, give each its own
+`$PROHOST_HOME` — separate credentials, separate ledgers, separate daemons.
+
+**The daemon does not inherit your shell.** It gets `PATH` and `PROHOST_HOME`
+and nothing else, because a supervised process starts from a bare environment.
+If your `--exec` command needs anything more — an API key, a proxy setting —
+point it at a wrapper script that sets those itself. Copying them into the plist
+would put your secrets in a file on disk that nothing else protects.
+
+It also records the `PATH` you had when you ran `install-daemon`. launchd starts
+jobs with a bare `PATH` that contains no `claude`, so without this the daemon
+installs, reports success, and then quietly fails every run with
+`command not found`. If you later move your agent binary, re-run
+`install-daemon`.
+
+`install-daemon` takes the same flags as `agent run` and passes them through. On
+Linux it prints a systemd-user unit for you to install by hand, because making
+it survive logout needs `loginctl enable-linger`, which isn't this CLI's
+decision to make.
 
 ### `agent pair` flags
 
@@ -169,10 +297,20 @@ has real credentials.
 | `auth_error: stream_subscription_unavailable` | The connection has no event subscription to stream. Re-pair. |
 | `signature did not verify` | The event didn't come from ProhostAI, or your stored secret is stale. Re-pair. |
 | Replies contain your agent's reasoning | Your command is printing more than the message. Use a "print only the answer" flag (e.g. `claude -p`). |
+| `claude did not return JSON` | Claude Code printed something else — usually a login prompt. Run `claude -p hello` yourself and fix what it says. |
+| `tools the agent asked for and was refused` | The run wanted a tool nothing could approve (nobody is at a terminal). Expected for most built-ins; if it names a `mcp__prohost__…` tool, re-pair. |
+| The agent answers as if it were working on some repo | It's running in a code checkout and inherited that repo's `CLAUDE.md`. Drop `--workdir`, or point it somewhere neutral. |
+
+Everything the CLI stores lives under `~/.prohost` (`$PROHOST_HOME` moves it):
 
-Credentials live in `~/.prohost/agent.json` and the run ledger in
-`~/.prohost/runs.json`; set `$PROHOST_HOME` to move that directory. Delete the file to un-pair locally, and revoke the connection in
-ProhostAI to invalidate the key itself.
+| File | What it is |
+| --- | --- |
+| `agent.json` | Credentials. Delete to un-pair locally; revoke in ProhostAI to invalidate the key itself. |
+| `runs.json` | Runs already executed on this machine, so a redelivery can't run your agent twice. |
+| `sessions.json` | Conversation → Claude Code session, for continuity. Safe to delete; costs the agent its memory of open threads. |
+| `mcp.json` | Generated MCP config. Holds your API key — `chmod 600`. |
+| `workspace/` | Where your agent command runs by default. |
+| `agent.log` | Daemon output. |
 
 ### What the pairing can and can't do
 

package/dist/agent/api.d.ts

@@ -27,8 +27,13 @@ export interface ApiResult {
  * Keyed on ``run_id`` so the send is idempotent server-side. The harness dedupes
  * runs in memory, but that memory dies with the process: without this header a
  * redelivered run after a restart would post the reply a second time.
+ *
+ * ``extra`` carries the event's ``reply_instructions.body_extra`` verbatim —
+ * threading fields and whatever the server adds later. It is merged, not
+ * interpreted: the point is that the server can extend the reply body without
+ * a CLI release.
  */
-export declare function postReply(options: ApiOptions, path: string, bodyKey: string, message: string, runId: string): Promise<ApiResult>;
+export declare function postReply(options: ApiOptions, path: string, bodyKey: string, message: string, runId: string, extra?: Record<string, unknown>): Promise<ApiResult>;
 /**
  * Report a run's terminal state. Called for every run — including one whose
  * command crashed — so the server never waits on a run this harness abandoned.

package/dist/agent/api.js

@@ -57,9 +57,17 @@ async function post(options, path, body, idempotencyKey) {
  * Keyed on ``run_id`` so the send is idempotent server-side. The harness dedupes
  * runs in memory, but that memory dies with the process: without this header a
  * redelivered run after a restart would post the reply a second time.
+ *
+ * ``extra`` carries the event's ``reply_instructions.body_extra`` verbatim —
+ * threading fields and whatever the server adds later. It is merged, not
+ * interpreted: the point is that the server can extend the reply body without
+ * a CLI release.
  */
-export async function postReply(options, path, bodyKey, message, runId) {
-    return post(options, path, { [bodyKey]: message }, `prohost-cli-run-${runId}`);
+export async function postReply(options, path, bodyKey, message, runId, extra) {
+    // `extra` first, so the message can never be clobbered by a `body_extra` key
+    // that happens to collide with the body field. The reply text is the one
+    // thing in this request that must survive.
+    return post(options, path, { ...extra, [bodyKey]: message }, `prohost-cli-run-${runId}`);
 }
 /**
  * Report a run's terminal state. Called for every run — including one whose

package/dist/agent/claude.d.ts

@@ -0,0 +1,161 @@
+/**
+ * The one place that knows anything about Claude Code specifically.
+ *
+ * `exec.ts` is deliberately agent-agnostic — prompt on stdin, reply on stdout,
+ * the lowest common denominator every CLI agent already speaks — and it stays
+ * that way. But that contract costs two things Claude Code can actually
+ * provide: 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. Both are fixed
+ * with flags, and flags are not portable. So the knowledge lives here, behind a
+ * detection function, and every other exec command keeps the exact behaviour it
+ * had before this module existed.
+ *
+ * Nothing in here 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. These are enhancements that must fail soft.
+ */
+/**
+ * Name the ProhostAI MCP server is registered under, which is also what makes
+ * its tools appear as `mcp__prohost__<tool>`. Referenced in the prompt, in the
+ * `--allowedTools` pattern, and in the config file — keep them in sync from
+ * here rather than by hand.
+ */
+export declare const MCP_SERVER_NAME = "prohost";
+/**
+ * What goes to `--allowedTools` so the ProhostAI tools are callable.
+ *
+ * Two spellings, comma-joined. `mcp__<server>` is the documented way to approve
+ * a whole MCP server and is the one expected to do the work; `mcp__<server>__*`
+ * is a pattern people write by analogy with `Bash(git *)`. Sending both costs
+ * a few bytes and removes an entire class of silent failure: an unapproved tool
+ * in print mode is not an error the agent reports, it is a tool the agent
+ * quietly never calls — and the visible symptom is an answer that sounds like
+ * the model just didn't feel like looking anything up.
+ *
+ * Comma-joined into ONE argument rather than passed as two, because
+ * `--allowedTools` is variadic (`<tools...>`) and would otherwise keep eating
+ * whatever followed it on the command line.
+ */
+export declare const MCP_ALLOWED_TOOLS = "mcp__prohost,mcp__prohost__*";
+/** Filename of the generated MCP config, inside `$PROHOST_HOME`. */
+export declare const MCP_CONFIG_FILENAME = "mcp.json";
+/**
+ * Is this exec command Claude Code in print mode?
+ *
+ * A **heuristic**, and intentionally a narrow one: it matches when the first
+ * word of the command is `claude` (or a path ending in `/claude`) *and* the
+ * command asks for print mode. Both halves matter. The first because the whole
+ * point of `--exec` is that it takes an arbitrary command, and the second
+ * because `--output-format` is a print-mode flag — appending it to an
+ * interactive invocation would break a command that works today.
+ *
+ * Things this deliberately does **not** match: `env X=1 claude -p`,
+ * `npx claude -p`, a wrapper script that calls Claude Code internally,
+ * `sh -c 'claude -p'`. Each of those keeps the plain stdin/stdout behaviour —
+ * which is correct output, just without session continuity or MCP tools. The
+ * failure direction is what was chosen here: a missed detection costs features,
+ * while a false positive would append flags to somebody's shell script and
+ * break their agent outright.
+ *
+ * Nor does it match a command containing shell control operators, even one that
+ * starts with `claude`. Flags are appended to the *end* of the string, so for
+ * `claude -p | jq -r .result` they would land on `jq` — breaking a command that
+ * works today, which is precisely the outcome the narrowness is for.
+ */
+export declare function isClaudeExec(command: string): boolean;
+export interface ClaudeFlags {
+    /** Session to resume. Omitted for the first turn on a surface. */
+    sessionId?: string;
+    /** Path to the generated MCP config, when MCP wiring is active. */
+    mcpConfigPath?: string;
+    /**
+     * Run the agent with permission checks bypassed. Default ON — see
+     * {@link claudeCommand}. 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 Claude Code command.
+ *
+ * `--dangerously-skip-permissions` is on by default, by explicit product
+ * decision: a paired brain is hired to *do* things, and in print mode there is
+ * nobody to approve a tool call — so without it the agent silently declines to
+ * act and the feature is a chat box. The trust model this assumes is stated
+ * plainly in the README: the brain runs as the host user with that user's full
+ * local permissions, on prompts written by workspace teammates. `--safe-tools`
+ * opts out for hosts who want prompt-gated behaviour instead.
+ *
+ * `--strict-mcp-config` is not optional decoration, and matters *more* under
+ * skipped permissions rather than less. Without it Claude Code merges the
+ * servers in the operator's own configuration with ours, so a run answering a
+ * customer's question would hold whatever MCP servers they use for their day
+ * job — with permission checks off. Ours is the only one this run is entitled
+ * to.
+ */
+export declare function claudeCommand(base: string, flags?: ClaudeFlags): string;
+/** What the harness got back from one Claude Code invocation. */
+export type ClaudeOutput = {
+    ok: true;
+    text: string;
+    sessionId?: string;
+    denials: string[];
+} | {
+    ok: false;
+    error: string;
+    sessionId?: string;
+    denials: string[];
+};
+/**
+ * Read the reply and the session id out of `--output-format json` stdout.
+ *
+ * Unparseable output is a **failure**, not a fallback to posting the raw text.
+ * We asked for JSON; stdout that isn't JSON means something went wrong that we
+ * do not understand — a crash banner, a login prompt, an npm warning — and the
+ * one thing that must not happen is that being posted verbatim into a customer's
+ * conversation. Reporting the run failed is recoverable; sending a stack trace
+ * to a guest is not.
+ */
+export declare function parseClaudeOutput(stdout: string): ClaudeOutput;
+/**
+ * Does this look like the resume having been rejected, rather than the agent
+ * having failed at its actual work?
+ *
+ * Sessions do not live forever: the transcript is on disk and gets cleaned up,
+ * and the ledger has no way to know. A stale entry must not turn into a
+ * permanently broken surface, so the caller retries once without `--resume`.
+ *
+ * The observed failure is exit 1, empty stdout, and
+ * `No conversation found with session ID: <uuid>` on stderr. Matching is
+ * broader than that string because the wording is not ours to depend on, and it
+ * is gated by the caller on the run having actually failed — so a *successful*
+ * run whose reply text happens to quote a session id is never mistaken for one.
+ */
+export declare function looksLikeResumeFailure(output: string, sessionId: string): boolean;
+/** Absolute path of the generated MCP config. */
+export declare function mcpConfigPath(env?: NodeJS.ProcessEnv): string;
+export interface McpConfigOptions {
+    /** The MCP endpoint the pairing reported, e.g. `https://connect.prohost.ai/mcp`. */
+    mcpUrl: string;
+    /** The paired API key. Written to a `0600` file and nowhere else. */
+    apiKey: string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * The config object handed to `--mcp-config`.
+ *
+ * Split out from the write so a test can assert on the shape without going near
+ * the filesystem, and so the header scheme is stated in exactly one place.
+ */
+export declare function buildMcpConfig(options: McpConfigOptions): Record<string, unknown>;
+/**
+ * Write the MCP config and return its path.
+ *
+ * The file holds a live API key, so it gets the same treatment as
+ * `agent.json`: `0600` inside a `0700` directory, written with the mode set at
+ * create time rather than chmod'ed afterwards — and chmod'ed anyway, because
+ * `writeFileSync`'s mode is masked by the umask and is ignored outright when
+ * the file already exists.
+ */
+export declare function writeMcpConfig(options: McpConfigOptions): string;