@edspencer/paddock 0.61.1 → 0.63.0

package/packages/server/dist/claude-mcp.js

@@ -0,0 +1,389 @@
+/**
+ * The `claude.mcpServers` lever (#691): whose MCP servers this instance's agents
+ * get.
+ *
+ * The last of the five levers, and the only one that is not about a file inside
+ * `~/.claude`. Everything else in the `claude:` block is a bridge decision about
+ * an entry of the home directory; MCP servers are declared in **`~/.claude.json`**,
+ * which is a SIBLING of that directory rather than a member of it. Claude Code
+ * resolves it as `join(CLAUDE_CONFIG_DIR ?? homedir(), ".claude.json")` — read
+ * out of the SDK bundle, where the two paths sit one expression apart and do not
+ * agree:
+ *
+ * ```js
+ * let d = n?.CLAUDE_CONFIG_DIR ?? process.env.CLAUDE_CONFIG_DIR,
+ *     f = d ?? Dr(sO(), ".claude");     // .credentials.json lives under here
+ * … await eV(Dr(f, ".credentials.json"), "utf-8")
+ * … await KMe(Dr(d ?? sO(), ".claude.json"), …)   // ← homedir, NOT ~/.claude
+ * ```
+ *
+ * So the moment paddock owns its own home (#620/#691) the user's `.claude.json`
+ * stops being on the path, and NO symlink bridge inside the home structurally
+ * can reach it. That is why MCP inheritance broke silently, separately from
+ * everything else, and why this lever is a read rather than a link.
+ *
+ * ## Why not just symlink `.claude.json`
+ *
+ * Because Claude Code WRITES to it — per-project trust, `enabledMcpjsonServers`,
+ * onboarding/migration flags, cached tips. Bridging it means paddock's instance
+ * mutating the user's real config, which is the exact thing #691 exists to stop.
+ * Read it, take the two keys that declare servers, hand those to the runtime.
+ *
+ * ## The seam, which is not the one #691 names
+ *
+ * #691 says to pass the servers through herdctl's runner option
+ * (`SDKQueryOptions.mcpServers`, merged at `sdk-runtime.js`) and that **"paddock
+ * sets none today"**. Both halves are wrong in a way that makes the work
+ * smaller, not larger:
+ *
+ * 1. `SDKQueryOptions` is built BY herdctl (`toSDKOptions`), not by paddock.
+ *    Paddock never constructs one. The field is populated from
+ *    `transformMcpServers(agent.mcp_servers)` — i.e. from the AGENT CONFIG.
+ * 2. Paddock already sets `mcp_servers`: the headless-Chromium server from
+ *    `browserMcpServers` (#269) is an external stdio MCP server passed exactly
+ *    this way, on every keeper and every trigger, whenever `PADDOCK_BROWSER_MCP`
+ *    is on.
+ *
+ * `agent.mcp_servers` is also the seam that covers BOTH runtimes for free: the
+ * SDK runtime transforms it into `sdkOptions.mcpServers`, and the CLI runtime
+ * serialises the same record into `--mcp-config '{"mcpServers":…}'`
+ * (`cli-runtime.js`). Passing it as a per-run option would have covered one.
+ *
+ * `injectedMcpServers` is, as #691 says, the wrong hook — `InjectedMcpServerDef`
+ * is `{name, version, tools}` with in-process JS handlers (`send_file`), and both
+ * runtimes materialise it as an HTTP bridge. It cannot express a stdio command.
+ *
+ * ## The allowlist, without which this lever is a no-op
+ *
+ * Paddock's fleet defaults carry an explicit `allowed_tools` array, and **both
+ * runtimes auto-deny any tool not on it, with no prompt** (the lesson `Skill`
+ * taught, recorded in `ensureConfigFile`). Tools from an MCP server are named
+ * `mcp__<server>__<tool>`, so a host server that is passed but not allowlisted
+ * connects and then has every one of its tools denied — an instance that looks
+ * configured and does nothing.
+ *
+ * herdctl handles this for INJECTED servers only ("Auto-add injected MCP tool
+ * patterns to allowedTools… only needed when the agent has an explicit
+ * allowlist", `cli-runtime.js`); config `mcp_servers` get no such treatment,
+ * which is why `mcp__playwright__*` is hard-coded into the defaults today. So
+ * this module also produces {@link mcpToolPattern} for each host server, and
+ * `buildAgentConfig` widens the keeper's allowlist by exactly those entries —
+ * only when there are some, so an instance with no host servers stays
+ * byte-identical to before.
+ *
+ * ## What could not be carried, and now can (herdctl 5.32.0)
+ *
+ * Until `@herdctl/core@5.32.0`, `McpServerSchema` was `{command?, args?, env?,
+ * url?}`, so `headers` and `type` were silently STRIPPED at `addAgent` and
+ * `transformMcpServer` rewrote every `url` to `type: "http"`. A
+ * header-authenticated server arrived unauthenticated and an `sse` server was
+ * downgraded to HTTP, so #699 shipped a boot warning naming every server that
+ * lost a field.
+ *
+ * herdctl#446 (in 5.32.0) widened the schema to mirror the SDK's own
+ * `McpServerConfig` — `type`, `headers`, `timeout` and `alwaysLoad` — and an
+ * explicit `type` now wins over the bare-`url` inference. Verified against the
+ * installed 5.32.0 rather than assumed: `addAgent` → `getAgents()` →
+ * `toSDKOptions()` returns `{type: "sse", url, headers}` unchanged for a server
+ * declared that way, and still infers `type: "http"` for a bare `url`. So the
+ * two `degraded` caveats are gone and {@link McpServerDef} carries both fields.
+ *
+ * Why that mattered more than it looked, and why it is worth not regressing:
+ * MCP OAuth tokens are stored under a top-level **`mcpOAuth`** key in the SAME
+ * credential store as `claudeAiOauth` — `<securestorage-dir>/.credentials.json`
+ * on Linux, the one `Claude Code-credentials` keychain item on darwin. There is
+ * no MCP-specific service name and no `mcp-oauth/` directory. The store is
+ * resolved by `CLAUDE_SECURESTORAGE_CONFIG_DIR ?? CLAUDE_CONFIG_DIR ?? ~/.claude`,
+ * which is exactly the variable `claude.credentials` drives — **so
+ * `credentials: host` DOES carry MCP OAuth tokens**, in either direction. But
+ * the per-server key is `` `${serverName}|${sha256({type,url,headers}).slice(0,16)}` ``,
+ * so a dropped header or a coerced `type` changed the hash and the stored token
+ * was simply not found. Carrying both fields verbatim is what makes
+ * `credentials: host` + `mcpServers: host` work for an OAuth server at all.
+ *
+ * `z.object` still strips what it has no field for (`tools`, and anything Claude
+ * Code grows next), so this narrowing is still a narrowing — it is just no longer
+ * one that breaks authentication. The one case that is still DROPPED is a server
+ * with neither `command` nor `url`, which cannot be started at all.
+ *
+ * ## The cost of carrying `headers`, which is real and is upstream
+ *
+ * herdctl's **CLI runtime** serialises the whole `mcp_servers` record into a
+ * single `--mcp-config '{"mcpServers":…}'` argv element, so everything in it is
+ * readable from `/proc/<pid>/cmdline` by any process of the same user. That was
+ * already true of an `env` value; it is now true of an `Authorization` header as
+ * well, which is the more likely place a bearer token lives. The SDK runtime
+ * passes the record in-process and is unaffected.
+ *
+ * Paddock's chats default to the SDK runtime (`driveMode: session`), but the
+ * sweeper and triggers are always one-shot CLI runs and a `driveMode: batch`
+ * project's turns are too — and neither the sweeper nor a trigger is given these
+ * servers, so the exposure is `driveMode: batch` only. Not paddock's to fix (the
+ * argv shape is herdctl's) and not a reason to go back to dropping the header:
+ * a stripped header is an authentication failure for everyone, while this is a
+ * same-user disclosure on one non-default drive mode. Worth knowing before
+ * putting a long-lived token in a `headers` block on a shared box.
+ *
+ * #702 found and measured this for a DECLARED server's `env` (it reads the token
+ * back out of a real spawned process's argv), and `mcp-servers.ts`'s
+ * `argvExposure` is the boot warning — now widened to `headers` for the same
+ * reason. There is no equivalent warning for a HOST server, deliberately: this
+ * module does not look at a value it did not resolve, and a user who ran
+ * `claude mcp add` on the box is already in the argv-exposure position with their
+ * own terminal.
+ *
+ * ## Plugins are the other half of this lever
+ *
+ * A Claude Code **plugin** can provide MCP servers too, and they are invisible to
+ * everything above: they are declared inside the plugin, not in `.claude.json`
+ * (#700). `claude-plugins.ts` is that half — it enumerates the host's installed
+ * plugin directories for `agent.plugins`, the second thing 5.32.0 added.
+ *
+ * ## Scope: keepers only
+ *
+ * The sweeper is tool-less by design and the trigger agents declare their own
+ * narrow `allowed_tools` per trigger, so neither would be able to call a host
+ * server even if it were attached. Attaching one anyway would spawn a stdio
+ * process per fire for nothing. Keepers are what a user means by "my MCP servers
+ * in paddock".
+ *
+ * ## Step 6 landed here, as an addition
+ *
+ * #691 step 6 — an instance-level `mcpServers:` block in `paddock.config.yaml`
+ * for servers a user declares themselves — is `mcp-servers.ts`. It contributes
+ * {@link McpSources.declared} and nothing else: the shape, {@link mcpServersFor},
+ * and the allowlist widening in `buildAgentConfig` were already source-agnostic
+ * and did not change. What it does NOT share is validation posture — a host
+ * server paddock cannot carry faithfully is passed with a warning (the user
+ * declared it elsewhere, for something else), while a declared one is refused
+ * with an error (they typed it here, at us, and can fix it).
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/** Isolation is the default, as everywhere except `credentials`. */
+export const DEFAULT_MCP_SERVERS_MODE = "own";
+/** Type guard, so an unknown config value falls back instead of failing a boot. */
+export function isKnownMcpServersMode(value) {
+    return value === "own" || value === "host";
+}
+/**
+ * The file MCP servers are declared in — a SIBLING of the Claude home, not an
+ * entry inside it. See the module doc for the SDK expression that settles this.
+ */
+export const HOST_MCP_CONFIG_FILE = ".claude.json";
+/**
+ * Where the user's own `.claude.json` is.
+ *
+ * Derived from `cfg.legacyClaudeHome` (always `~/.claude`) rather than read from
+ * `os.homedir()` again, so it moves with the one value the rest of the bridge
+ * already treats as "the host's Claude Code" — and so a test can point the whole
+ * lever at a temp dir by setting that one field.
+ */
+export function hostMcpConfigPath(legacyClaudeHome) {
+    return path.join(path.dirname(legacyClaudeHome), HOST_MCP_CONFIG_FILE);
+}
+/** No servers from anywhere: `mcpServers: own` + an empty block, and where tests start. */
+export const EMPTY_MCP_SOURCES = Object.freeze({
+    user: {},
+    byDir: {},
+    declared: {},
+    caveats: [],
+});
+/** The allowlist entry that lets a server's tools actually be called. */
+export function mcpToolPattern(name) {
+    return `mcp__${name}__*`;
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Narrow one declared server to what herdctl can carry, recording what was lost.
+ *
+ * Returns `undefined` for a server that cannot be started at all — no `command`
+ * and no `url` — which is the only case where dropping beats degrading.
+ */
+function narrowServer(name, raw, caveats) {
+    if (!isRecord(raw)) {
+        caveats.push({ name, kind: "dropped", reason: "its declaration is not a JSON object" });
+        return undefined;
+    }
+    const server = {};
+    if (typeof raw.command === "string" && raw.command !== "")
+        server.command = raw.command;
+    if (Array.isArray(raw.args) && raw.args.every((a) => typeof a === "string")) {
+        if (raw.args.length > 0)
+            server.args = [...raw.args];
+    }
+    if (isRecord(raw.env)) {
+        const env = {};
+        for (const [k, v] of Object.entries(raw.env))
+            if (typeof v === "string")
+                env[k] = v;
+        if (Object.keys(env).length > 0)
+            server.env = env;
+    }
+    if (typeof raw.url === "string" && raw.url !== "")
+        server.url = raw.url;
+    // Both carried verbatim since herdctl 5.32.0 (#700). Before that they were
+    // stripped at `addAgent` and this function pushed a `degraded` caveat naming
+    // the server; the fields reaching `toSDKOptions()` intact is what retired that
+    // warning. A `type` we do not recognise is left off rather than passed on —
+    // herdctl's enum would strip it anyway, and the bare-`url` inference is the
+    // better fallback than nothing.
+    if (raw.type === "stdio" || raw.type === "sse" || raw.type === "http")
+        server.type = raw.type;
+    if (isRecord(raw.headers)) {
+        const headers = {};
+        for (const [k, v] of Object.entries(raw.headers))
+            if (typeof v === "string")
+                headers[k] = v;
+        if (Object.keys(headers).length > 0)
+            server.headers = headers;
+    }
+    if (server.command === undefined && server.url === undefined) {
+        caveats.push({
+            name,
+            kind: "dropped",
+            reason: "it declares neither a `command` nor a `url`, so there is nothing to start",
+        });
+        return undefined;
+    }
+    return server;
+}
+function serversOf(raw, caveats) {
+    if (!isRecord(raw))
+        return {};
+    const out = {};
+    for (const [name, decl] of Object.entries(raw)) {
+        const server = narrowServer(name, decl, caveats);
+        if (server)
+            out[name] = server;
+    }
+    return out;
+}
+/**
+ * Parse a `.claude.json` into the two server scopes. Pure, so the whole
+ * selection is testable from a string with no filesystem and no real home.
+ *
+ * Fails soft in both directions on purpose. Unparseable JSON, a non-object top
+ * level, a `projects` value that is not a map — none of them throw, because the
+ * user's `.claude.json` is a file paddock does not own, cannot validate and must
+ * never turn into a boot failure. What it does instead is return nothing and let
+ * the caller say so.
+ */
+export function parseHostMcpConfig(raw) {
+    const caveats = [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { user: {}, byDir: {}, declared: {}, caveats };
+    }
+    if (!isRecord(parsed))
+        return { user: {}, byDir: {}, declared: {}, caveats };
+    const user = serversOf(parsed.mcpServers, caveats);
+    const byDir = {};
+    if (isRecord(parsed.projects)) {
+        for (const [dir, entry] of Object.entries(parsed.projects)) {
+            if (!isRecord(entry))
+                continue;
+            const servers = serversOf(entry.mcpServers, caveats);
+            if (Object.keys(servers).length > 0)
+                byDir[dir] = servers;
+        }
+    }
+    return { user, byDir, declared: {}, caveats };
+}
+/**
+ * The servers that apply to one agent's working directory.
+ *
+ * Precedence, weakest first: host user scope, host directory scope, then this
+ * instance's own `mcpServers:` block.
+ *
+ * Host per-directory wins over host user scope because it is the more specific
+ * declaration, and it is the one `claude mcp add` writes by default, so a user
+ * who re-declared a server inside a project meant that one. {@link
+ * McpSources.declared} wins over both because it is a statement about THIS
+ * instance while `~/.claude.json` is ambient machine state — a user who wrote a
+ * server into paddock's own config was answering "what should paddock have?",
+ * which is a narrower question than "what does this machine have?".
+ *
+ * The host lookup is exact rather than a prefix walk. `.claude.json`'s `projects`
+ * keys are the literal cwd Claude Code was started in, and Claude Code does not
+ * inherit a parent directory's entry either — matching that keeps paddock's
+ * answer the same as the terminal's, which is the whole point of `host`.
+ */
+export function mcpServersFor(source, workingDir) {
+    return { ...source.user, ...(source.byDir[workingDir] ?? {}), ...source.declared };
+}
+/** Every directory-scoped key, for the boot notice. */
+export function hostMcpScopedDirs(source) {
+    return Object.keys(source.byDir);
+}
+/**
+ * Read the host's `.claude.json` — once, at boot — and say what came of it.
+ *
+ * Under `own` the file is not opened at all. That is not an optimisation: "own
+ * everywhere means nothing outside the data dir is read" is the guarantee #691
+ * exists to make sayable, and a lever that read the file and then discarded it
+ * would make the guarantee false in the only place anyone could check.
+ *
+ * Read once rather than per turn, for the same reason `claude.hooks` materialises
+ * its `settings.json` once: a `.claude.json` that grows a server mid-run is picked
+ * up at the next restart, and the boot notice is where a user looks to confirm
+ * what this instance actually has.
+ */
+export async function loadHostMcpSource(cfg) {
+    if (cfg.claude.mcpServers !== "host")
+        return { source: EMPTY_MCP_SOURCES, notices: [] };
+    const file = hostMcpConfigPath(cfg.legacyClaudeHome);
+    const notices = [];
+    let raw;
+    try {
+        raw = await fs.readFile(file, "utf8");
+    }
+    catch (err) {
+        notices.push({
+            level: "info",
+            message: `\`claude.mcpServers: host\` is set but ${file} could not be read (${String(err)}) — ` +
+                `no host MCP servers are attached. That file is where \`claude mcp add\` writes; ` +
+                `it does not exist until you have added one.`,
+        });
+        return { source: EMPTY_MCP_SOURCES, notices };
+    }
+    const source = parseHostMcpConfig(raw);
+    const userNames = Object.keys(source.user);
+    const scoped = hostMcpScopedDirs(source);
+    const total = userNames.length + scoped.reduce((n, d) => n + Object.keys(source.byDir[d]).length, 0);
+    if (total === 0) {
+        notices.push({
+            level: "info",
+            message: `\`claude.mcpServers: host\`: no MCP servers are declared in ${file} ` +
+                `(neither at the top level nor under any \`projects\` entry).`,
+        });
+    }
+    else {
+        notices.push({
+            level: "info",
+            message: `Claude MCP servers: host (\`claude.mcpServers: host\`) — ` +
+                (userNames.length > 0 ? `user scope: ${userNames.join(", ")}` : "no user-scope servers") +
+                (scoped.length > 0
+                    ? `; directory scope: ${scoped
+                        .map((d) => `${d} (${Object.keys(source.byDir[d]).join(", ")})`)
+                        .join(", ")}`
+                    : "") +
+                `. A project's keeper gets the user-scope servers plus any scoped to its own ` +
+                `working directory.`,
+        });
+    }
+    for (const caveat of source.caveats) {
+        notices.push({
+            level: "warn",
+            message: caveat.kind === "dropped"
+                ? `MCP server "${caveat.name}" in ${file} was NOT attached: ${caveat.reason}.`
+                : `MCP server "${caveat.name}" from ${file} is attached but degraded: ${caveat.reason}.`,
+        });
+    }
+    return { source, notices };
+}

package/packages/server/dist/claude-plugins.d.ts

@@ -0,0 +1,131 @@
+import type { McpServersMode } from "./claude-mcp.js";
+import type { InstructionsMode } from "./claude-instructions.js";
+/**
+ * One plugin to load, in herdctl's `PluginSchema` object form.
+ *
+ * The schema also accepts a bare path string and normalises it to this, but
+ * paddock always needs the object because {@link HostPlugin.skipMcpDiscovery} is
+ * how the two levers are kept apart.
+ */
+export interface HostPlugin {
+    type: "local";
+    path: string;
+    skipMcpDiscovery?: boolean;
+}
+/** Something about a host plugin worth telling the operator at boot. */
+export interface HostPluginCaveat {
+    /** The plugin's id (`<name>@<marketplace>`) or its directory name. */
+    name: string;
+    /** `dropped` = not passed at all; `degraded` = passed, but incompletely. */
+    kind: "dropped" | "degraded";
+    reason: string;
+}
+/** What {@link enumerateHostPlugins} found. */
+export interface HostPluginSource {
+    /** Ready for `agent.plugins`, in registry order. */
+    plugins: HostPlugin[];
+    /**
+     * `mcp__<server>__*` patterns for every plugin-provided server paddock could
+     * name statically. Empty whenever MCP discovery is off.
+     */
+    toolPatterns: string[];
+    caveats: HostPluginCaveat[];
+}
+/** Nothing inherited: `instructions: own`, and where tests start. */
+export declare const EMPTY_HOST_PLUGINS: HostPluginSource;
+/** The plugin root, `join(CLAUDE_CONFIG_DIR, "plugins")` in the CLI's terms. */
+export declare function hostPluginRoot(legacyClaudeHome: string): string;
+/** The CLI's own registry of what is installed, under {@link hostPluginRoot}. */
+export declare const INSTALLED_PLUGINS_FILE = "installed_plugins.json";
+/** A plugin's manifest, relative to its directory. */
+export declare const PLUGIN_MANIFEST: string;
+/** A plugin's out-of-manifest MCP declaration, relative to its directory. */
+export declare const PLUGIN_MCP_FILE = ".mcp.json";
+/**
+ * The allowlist pattern for one server of one plugin.
+ *
+ * Deliberately not `mcpToolPattern` from `claude-mcp.ts`: the name a plugin's
+ * server is registered under is not the name it is declared under, and that
+ * derivation is the whole content of this function.
+ */
+export declare function pluginMcpToolPattern(pluginName: string, serverName: string): string;
+/** One plugin's name and the MCP servers it declares, as far as they are static. */
+export interface PluginServerNames {
+    /** `manifest.name`, else the directory name — the CLI's own fallback order. */
+    pluginName: string;
+    /** Server names as declared, BEFORE the `plugin:<plugin>:` prefixing. */
+    servers: string[];
+    /**
+     * A `mcpServers` the manifest points at rather than spells out, and that could
+     * not be resolved to a file inside the plugin directory. Non-empty means the
+     * allowlist for this plugin is incomplete.
+     */
+    unresolved: string[];
+}
+/**
+ * Read one plugin directory's declared MCP server names.
+ *
+ * Mirrors the CLI's own discovery order — `<dir>/.mcp.json` first, then whatever
+ * `manifest.mcpServers` adds — with the one deliberate gap described in the
+ * module doc: a manifest that points at an MCPB source (or at any path outside
+ * its own directory) is recorded in {@link PluginServerNames.unresolved} rather
+ * than fetched. Paddock does not download anything to build an allowlist.
+ */
+export declare function readPluginServerNames(dir: string): Promise<PluginServerNames>;
+/** One installed plugin: its id, and where it landed on disk. */
+interface InstalledPlugin {
+    id: string;
+    installPath: string;
+}
+/**
+ * Parse `installed_plugins.json`, v1 or v2. Pure, so the whole selection is
+ * testable from a string.
+ *
+ * v2 keys each `<name>@<marketplace>` id to an ARRAY of installations (one per
+ * scope), each carrying an explicit `installPath`. v1 keyed it to a single record
+ * with no path, which the CLI derives as
+ * `<root>/cache/<marketplace>/<name>/<version>` with each segment sanitised
+ * `[^a-zA-Z0-9\-_] → -` (and the version segment additionally allowing `.`).
+ *
+ * Fails soft in every direction: this is a file paddock does not own and must
+ * never turn into a boot failure.
+ */
+export declare function parseInstalledPlugins(raw: string, root: string): InstalledPlugin[];
+/** A line for the boot log, at a level (mirrors `HostMcpNotice`). */
+export interface HostPluginNotice {
+    level: "info" | "warn";
+    message: string;
+}
+/** What {@link loadHostPlugins} found, ready for the agent config and the log. */
+export interface HostPluginReport {
+    source: HostPluginSource;
+    notices: HostPluginNotice[];
+}
+/**
+ * Enumerate the host's installed plugin directories. Pure apart from reading the
+ * plugin tree, and takes the two files' contents rather than paths so the whole
+ * selection is testable without a home directory.
+ */
+export declare function enumerateHostPlugins(opts: {
+    root: string;
+    installed: string | undefined;
+    settings: unknown;
+    /** Whether the plugins' own MCP servers come too. */
+    mcp: boolean;
+}): Promise<HostPluginSource>;
+/**
+ * Read the host's plugin registry — once, at boot — and say what came of it.
+ *
+ * Under `instructions: own` nothing is opened at all, for the same reason
+ * `loadHostMcpSource` does not open `.claude.json` under `mcpServers: own`: "own
+ * everywhere means nothing outside the data dir is read" is a guarantee that has
+ * to be true in the place someone would check it.
+ */
+export declare function loadHostPlugins(cfg: {
+    legacyClaudeHome: string;
+    claude: {
+        instructions: InstructionsMode;
+        mcpServers: McpServersMode;
+    };
+}): Promise<HostPluginReport>;
+export {};