@edspencer/paddock 0.62.0 → 0.63.0

package/README.md

@@ -40,13 +40,17 @@ Paddock says at startup if it can find no credentials at all.
 ## What else Paddock does and does not take from your `~/.claude`
 
 Apart from that login: **nothing, by default.** Your `CLAUDE.md`, `agents/`,
-`commands/` and `plugins/` are not loaded, and the hooks your `settings.json` binds to
-tool use do not run. Both are one key in `<data-dir>/paddock.config.yaml`:
+`commands/` and `plugins/` are not loaded, the hooks your `settings.json` binds to tool
+use do not run, your transcripts are not touched, and your `~/.claude.json` MCP servers
+are not attached. Each is one key in `<data-dir>/paddock.config.yaml`:
 
 ```yaml
 claude:
+  transcripts: host    # own | host, default own — whose session transcripts
+  credentials: host    # own | host, default host — the one shared by default
   instructions: host   # own | host, default own — CLAUDE.md, agents, commands, plugins
   hooks: host          # own | host, default own — shell commands settings.json binds
+  mcpServers: host     # own | host, default own — the servers in your ~/.claude.json
 ```
 
 `instructions: own` is worth knowing about if you have curated a `~/.claude/CLAUDE.md`:
@@ -55,6 +59,22 @@ always applies. `hooks` is off by default because inheriting someone's shell com
 not a thing to discover after the fact; the rest of your `settings.json` — permissions,
 model, statusline — applies either way.
 
+To give this instance an MCP server your machine does not have — the case `host`
+cannot serve — declare it in a **sibling** `mcpServers:` block of the same file, using
+`env:VAR_NAME` anywhere a string goes so the token stays out of the git-tracked file
+(keep `driveMode` on its default `session` for a server holding a credential — `batch`
+passes the definition to `claude` as a command-line argument, where any local user can
+read it):
+
+```yaml
+mcpServers:
+  notion:
+    command: npx
+    args: ["-y", "@notionhq/notion-mcp-server"]
+    env:
+      NOTION_TOKEN: env:NOTION_TOKEN
+```
+
 ## Open your own project
 
 ```sh
@@ -118,10 +138,18 @@ A multi-arch Docker image is published alongside this package, and is the better
 fit for a server deployment:
 
 ```sh
-docker run -d -p 4000:4000 -v /srv/paddock-data:/data \
-  -e CLAUDE_CODE_OAUTH_TOKEN=… ghcr.io/edspencer/paddock:latest
+docker run -d -p 127.0.0.1:4000:4000 -v /srv/paddock-data:/data \
+  -e CLAUDE_CODE_OAUTH_TOKEN=… \
+  -e PADDOCK_DANGEROUSLY_ALLOW_OPEN=1 \
+  ghcr.io/edspencer/paddock:latest
 ```
 
+`PADDOCK_DANGEROUSLY_ALLOW_OPEN=1` is required: the image binds `0.0.0.0` and the
+default auth mode is `none`, and Paddock refuses to bind a routable interface
+unauthenticated unless told to. Publishing on `127.0.0.1:` is what makes that
+safe — Paddock runs code and spends Claude tokens, so put an auth mode or a
+reverse proxy in front of it before exposing the port to a network.
+
 ## Links
 
 - [Documentation](https://github.com/edspencer/paddock#readme)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",
@@ -37,7 +37,7 @@
     "@fastify/swagger-ui": "4.2.0",
     "@fastify/websocket": "10.0.1",
     "@herdctl/chat": "0.8.0",
-    "@herdctl/core": "5.31.0",
+    "@herdctl/core": "5.32.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "fastify": "4.28.1",
     "jose": "6.2.3",

package/packages/server/dist/app.js

@@ -21,6 +21,7 @@ import path from "node:path";
 import { loadPaddockConfig } from "./config.js";
 import { ensureClaudeHome, countLegacyTranscriptLinks, findPlantedChatsLinks, } from "./claude-home.js";
 import { loadHostMcpSource } from "./claude-mcp.js";
+import { loadHostPlugins } from "./claude-plugins.js";
 import { declaredMcpNotices } from "./mcp-servers.js";
 import { installHerdctlLogBridge } from "./agent-errors.js";
 import { ProjectStore, ROOT_KEY } from "./projects.js";
@@ -132,10 +133,22 @@ export async function buildApp(opts = {}) {
         servers: cfg.mcpServers,
         hostNames: Object.keys(hostMcp.source.user),
         browserMcp: cfg.browserMcp,
+        // …and where a declared credential ends up once the runtime has it: on the
+        // `claude` command line under `batch`, in-process under `session`. Paddock
+        // cannot close that from here, so it names it at boot instead.
+        driveMode: cfg.driveMode,
     })) {
         app.log[notice.level](notice.message);
     }
-    const herdctl = new HerdctlService(cfg, { ...hostMcp.source, declared: cfg.mcpServers });
+    // …and the host's Claude Code PLUGINS (#700), which no amount of reading
+    // `.claude.json` can find: a plugin declares its own MCP servers internally.
+    // Gated by `claude.instructions` (which is what bridges `plugins/`), with
+    // `claude.mcpServers` deciding only whether the plugins' servers come too —
+    // see `claude-plugins.ts` for why that is not the single lever #700 assumes.
+    const hostPlugins = await loadHostPlugins(cfg);
+    for (const notice of hostPlugins.notices)
+        app.log[notice.level](notice.message);
+    const herdctl = new HerdctlService(cfg, { ...hostMcp.source, declared: cfg.mcpServers }, hostPlugins.source);
     const git = new GitService(cfg.projectsRoot, cfg.gitAuthor);
     const githubAuth = new GithubAuth(path.join(cfg.dataDir, "github-auth.json"), cfg.githubClientId);
     const archive = new ArchiveStore(cfg.dataDir);

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

@@ -29,15 +29,20 @@ export declare function hostMcpConfigPath(legacyClaudeHome: string): string;
  * One MCP server, in the only shape herdctl's `McpServerSchema` can carry.
  *
  * Deliberately NOT `SDKMcpServerConfig`: that is what herdctl produces on the
- * far side of `transformMcpServer`, and pinning the narrower agent-config shape
- * here is what makes the lossiness above visible at the type level rather than
- * at runtime.
+ * far side of `transformMcpServer`, and pinning the agent-config shape here is
+ * what keeps any remaining lossiness visible at the type level rather than at
+ * runtime. As of herdctl 5.32.0 the two differ only in what the SDK has that
+ * herdctl still has no field for (`tools`).
  */
 export interface McpServerDef {
+    /** Explicit transport. Wins over the bare-`url` ⇒ `http` inference (5.32.0). */
+    type?: "stdio" | "sse" | "http";
     command?: string;
     args?: string[];
     env?: Record<string, string>;
     url?: string;
+    /** Carried verbatim since 5.32.0 — and part of the OAuth token's key. */
+    headers?: Record<string, string>;
 }
 /** A set of MCP servers, keyed by the name their tools are namespaced under. */
 export type McpServerDefs = Record<string, McpServerDef>;
@@ -45,7 +50,14 @@ export type McpServerDefs = Record<string, McpServerDef>;
 export interface HostMcpCaveat {
     /** The server's name in `.claude.json`. */
     name: string;
-    /** `dropped` = not passed at all; `degraded` = passed, but not faithfully. */
+    /**
+     * `dropped` = not passed at all; `degraded` = passed, but not faithfully.
+     *
+     * Nothing produces `degraded` since herdctl 5.32.0 carries `headers` and
+     * `type` verbatim (#700) — the variant and its notice branch are kept because
+     * the class of defect ("the engine has no field for this") is the one #699 was
+     * filed about and is one schema narrowing away from coming back.
+     */
     kind: "dropped" | "degraded";
     /** Human-readable, and specific enough to act on. */
     reason: string;

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

@@ -71,44 +71,73 @@
  * only when there are some, so an instance with no host servers stays
  * byte-identical to before.
  *
- * ## What cannot be carried, honestly
- *
- * herdctl's `McpServerSchema` is `{command?, args?, env?, url?}` and it is a
- * plain `z.object`, so anything else is silently STRIPPED at `addAgent`. Two
- * consequences that matter and that #691 does not mention:
- *
- * - **`headers` is dropped.** A remote MCP server authenticated with a bearer
- *   header therefore arrives unauthenticated.
- * - **`type` is dropped**, and `transformMcpServer` maps any `url` to
- *   `type: "http"`. An `sse` server is silently downgraded to HTTP.
- *
- * And those two strippings are worse than they look, because of where MCP OAuth
- * tokens turn out to live. #691 listed that as an open question; it is now
- * answered, from the bundled CLI binary rather than by inference:
- *
- * - 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** — they are not separable
- *   from the Anthropic login, in either direction.
- * - But the per-server key is `` `${serverName}|${sha256({type,url,headers}).slice(0,16)}` ``.
- *   A dropped `headers`, or an `sse` coerced to `http`, changes that hash and the
- *   stored token is simply not found. So the combination that works today is
- *   `credentials: host` + `mcpServers: host` for an OAuth server declared with no
- *   headers and no `type` disagreement; a header-authenticated or `sse` server
- *   arrives looking unauthenticated even though its token is right there.
- *
- * Neither is paddock's to fix here (both need a herdctl schema change). What
- * paddock CAN do is refuse to be silent about it: {@link parseHostMcpConfig}
- * records every key it had to drop and every `sse` it had to coerce, and the
- * boot notice names the server. The server is still passed — this is a
- * capability lever, not a security one, and a user who declared a server should
- * get it plus a warning rather than nothing plus a warning. The one case that IS
- * dropped is a server with neither `command` nor `url`, which cannot be started
- * at all.
+ * ## 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
  *
@@ -195,6 +224,22 @@ function narrowServer(name, raw, caveats) {
     }
     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,
@@ -203,29 +248,6 @@ function narrowServer(name, raw, caveats) {
         });
         return undefined;
     }
-    // The lossy bits. `type` and `headers` are real keys of Claude Code's own MCP
-    // config that herdctl's schema has no field for and therefore strips; saying so
-    // is the difference between "my Notion server does not work" and "my Notion
-    // server's bearer header was dropped, here is the issue to file".
-    if (isRecord(raw.headers) && Object.keys(raw.headers).length > 0) {
-        caveats.push({
-            name,
-            kind: "degraded",
-            reason: `its \`headers\` (${Object.keys(raw.headers).join(", ")}) cannot be carried — ` +
-                `herdctl's MCP schema has no field for them, so the server is passed WITHOUT them, ` +
-                `any auth they held is gone, and its stored OAuth token (keyed on a hash that ` +
-                `includes the headers) will not be found either`,
-        });
-    }
-    if (raw.type === "sse") {
-        caveats.push({
-            name,
-            kind: "degraded",
-            reason: 'it is an `sse` server, and herdctl maps every `url` to `type: "http"` — it will ' +
-                "be connected to as HTTP, and any OAuth token stored against the `sse` shape " +
-                "will not be found",
-        });
-    }
     return server;
 }
 function serversOf(raw, caveats) {

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 {};