@edspencer/paddock 0.61.1 → 0.62.0

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

@@ -0,0 +1,305 @@
+/**
+ * The prefix that makes a string an environment reference rather than a literal.
+ * Same spelling as `managementApi.clients.<id>.auth.ref`, deliberately: an
+ * operator should have to learn it once.
+ */
+export const ENV_REF_PREFIX = "env:";
+/**
+ * Server names paddock materialises itself, which a declaration may not take.
+ *
+ * Kept as literals rather than imported from `send-file-mcp.ts`/`self-mcp.ts` so
+ * config resolution stays free of the runtime modules — `mcp-servers-reserved`
+ * in the unit tests asserts the two spellings still agree.
+ */
+export const RESERVED_MCP_SERVER_NAMES = ["paddock", "paddock_manage"];
+/**
+ * `mcp__<server>__<tool>` is the tool name both runtimes match against, and the
+ * allowlist pattern is built from it by string concatenation, so a name with a
+ * separator or whitespace in it produces a pattern that matches nothing. Claude
+ * Code uses the same character class for a server name.
+ */
+const NAME_RE = /^[A-Za-z0-9_-]+$/;
+/** Keys of a declaration this module understands. Anything else is a typo. */
+const KNOWN_KEYS = new Set(["command", "args", "env", "url", "type", "headers"]);
+/**
+ * Env keys whose INLINE value is probably a credential. Deliberately a name
+ * heuristic and never a value one: matching on the value would mean reading it
+ * closely enough to describe it, and this module's whole posture is that it
+ * never looks at a value it is not about to hand to a server process.
+ */
+const SECRET_ISH_KEY_RE = /(TOKEN|SECRET|KEY|PASSWORD|PASSWD|CREDENTIAL|AUTH|PAT|COOKIE)/i;
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * A URL with everything credential-shaped removed — no query string, no
+ * fragment, no `user:pass@`. Used for every log line that mentions a `url`,
+ * because a remote MCP endpoint's API key is conventionally a query parameter.
+ * An unparseable URL is reported as its scheme only rather than echoed.
+ */
+export function redactUrl(raw) {
+    try {
+        const u = new URL(raw);
+        const auth = u.username || u.password ? "<redacted>@" : "";
+        return `${u.protocol}//${auth}${u.host}${u.pathname}${u.search ? "?<redacted>" : ""}`;
+    }
+    catch {
+        return "<unparseable url>";
+    }
+}
+/**
+ * A server rendered for a human, carrying no secret. THE chokepoint: every
+ * notice, warning and error about a declared server goes through here, so
+ * auditing "can a token reach a log line?" is auditing one function.
+ *
+ * Args and env values are counted, never printed — an API key is as likely to be
+ * `--token=…` in `args` as it is to be an `env` value. The command is reduced to
+ * its basename for the same reason, which the leak test in
+ * `test/unit/mcp-servers.test.ts` is what forced: a full path is more useful in a
+ * log, but the rule "nothing from the block is echoed" is only worth having if it
+ * has no exceptions to remember. The server's own name is printed alongside and
+ * is what actually identifies it.
+ */
+export function describeServer(name, def) {
+    const parts = [];
+    if (def.command)
+        parts.push(`stdio: ${def.command.split(/[\\/]/).pop()}`);
+    if (def.url)
+        parts.push(`http: ${redactUrl(def.url)}`);
+    if (def.args?.length)
+        parts.push(`${def.args.length} args`);
+    const envCount = Object.keys(def.env ?? {}).length;
+    if (envCount > 0)
+        parts.push(`${envCount} env ${envCount === 1 ? "entry" : "entries"}`);
+    return `${name} (${parts.join(", ")})`;
+}
+/**
+ * Resolve a string leaf: `env:VAR_NAME` reads `VAR_NAME`, anything else is a
+ * literal.
+ *
+ * An unset or blank variable FAILS the leaf, which drops the whole server. That
+ * is the fail-closed direction here for the same reason it is in
+ * `management-config.ts`: a server started without the credential it was
+ * declared with either fails every call confusingly or — worse for something
+ * that talks to a third party — connects unauthenticated.
+ */
+function resolveLeaf(raw, env, where) {
+    if (!raw.startsWith(ENV_REF_PREFIX))
+        return { ok: true, value: raw };
+    const varName = raw.slice(ENV_REF_PREFIX.length).trim();
+    if (varName.length === 0)
+        return { ok: false, error: `${where}: \`env:\` names no variable` };
+    const value = env[varName];
+    if (value === undefined || value.trim().length === 0) {
+        return {
+            ok: false,
+            error: `${where}: environment variable ${varName} is unset or empty`,
+        };
+    }
+    return { ok: true, value };
+}
+/**
+ * Validate + resolve one declaration into the shape herdctl's `McpServerSchema`
+ * carries, or explain why it cannot be.
+ *
+ * The rejections are the interesting part, and each is a thing step 5 discovered
+ * the engine strips silently:
+ *
+ * - **`headers`** — there is no field for them, so a bearer-authenticated server
+ *   would arrive unauthenticated AND miss its stored OAuth token, which is keyed
+ *   on a hash that includes the headers. Step 5 passes such a host server with a
+ *   warning; a hand-written declaration gets an error instead, because the user
+ *   typed the header and can act on being told it does nothing.
+ * - **`type: sse`** — every `url` is mapped to `type: "http"` downstream, so an
+ *   sse server is silently downgraded, with the same OAuth-key consequence.
+ * - **an unknown key** — the only defence against `arg:`/`envs:`/`commands:`,
+ *   which would otherwise yield a server that starts with the wrong argv.
+ */
+function narrowDeclaration(name, raw, env) {
+    const where = `mcpServers.${name}`;
+    const errors = [];
+    const warnings = [];
+    const fail = (msg) => ({
+        errors: [...errors, `${msg} — not attached`],
+        warnings,
+    });
+    if (!NAME_RE.test(name)) {
+        return fail(`${where}: a server name may contain only letters, digits, \`_\` and \`-\` (its tools are ` +
+            `named mcp__${name}__<tool>, and the allowlist pattern is built from that)`);
+    }
+    if (RESERVED_MCP_SERVER_NAMES.includes(name)) {
+        return fail(`${where}: "${name}" is reserved for a server paddock injects itself, and two servers ` +
+            `cannot share the mcp__${name}__* namespace`);
+    }
+    if (!isRecord(raw))
+        return fail(`${where}: is not a mapping`);
+    const unknown = Object.keys(raw).filter((k) => !KNOWN_KEYS.has(k));
+    if (unknown.length > 0) {
+        return fail(`${where}: unrecognised key(s) ${unknown.join(", ")} (supported: command, args, env, url) ` +
+            `— a mistyped key would otherwise be dropped without a trace`);
+    }
+    if (raw.headers !== undefined) {
+        const keys = isRecord(raw.headers) ? Object.keys(raw.headers) : [];
+        return fail(`${where}: \`headers\`${keys.length > 0 ? ` (${keys.join(", ")})` : ""} cannot be ` +
+            `carried — the engine's MCP schema has no field for them, so the server would arrive ` +
+            `unauthenticated and its stored OAuth token (keyed on a hash that includes the headers) ` +
+            `would not be found either`);
+    }
+    const hasCommand = typeof raw.command === "string" && raw.command.trim().length > 0;
+    const hasUrl = typeof raw.url === "string" && raw.url.trim().length > 0;
+    if (hasCommand && hasUrl) {
+        return fail(`${where}: declares both a \`command\` and a \`url\`; a server is one or the other`);
+    }
+    if (!hasCommand && !hasUrl) {
+        return fail(`${where}: declares neither a \`command\` nor a \`url\`, so there is nothing to start`);
+    }
+    if (raw.type !== undefined) {
+        const type = String(raw.type).trim().toLowerCase();
+        if (type === "sse") {
+            return fail(`${where}: \`type: sse\` cannot be carried — every \`url\` server is connected to as ` +
+                `streamable HTTP downstream, so an sse server would be silently downgraded (and its ` +
+                `stored OAuth token, keyed on a hash that includes the type, not found). Declare it ` +
+                `as \`http\` if the server supports it`);
+        }
+        const expected = hasUrl ? "http" : "stdio";
+        if (type !== expected) {
+            return fail(`${where}: \`type: ${type}\` disagrees with the declaration (expected ${expected})`);
+        }
+    }
+    const server = {};
+    if (hasCommand) {
+        const res = resolveLeaf(raw.command.trim(), env, `${where}.command`);
+        if (!res.ok)
+            return { errors, warnings: [...warnings, `${res.error} — server not attached`] };
+        server.command = res.value;
+    }
+    if (hasUrl) {
+        const res = resolveLeaf(raw.url.trim(), env, `${where}.url`);
+        if (!res.ok)
+            return { errors, warnings: [...warnings, `${res.error} — server not attached`] };
+        server.url = res.value;
+        // A key in the query string is the usual way a remote MCP endpoint is
+        // authenticated now that `headers` cannot be carried, and this file is
+        // git-tracked. Say so once; never echo the query itself.
+        if (!raw.url.startsWith(ENV_REF_PREFIX)) {
+            let parsed;
+            try {
+                parsed = new URL(server.url);
+            }
+            catch {
+                /* an unparseable url is the engine's problem, not a secrets one */
+            }
+            if (parsed && (parsed.search || parsed.username || parsed.password)) {
+                warnings.push(`${where}.url: carries a query string or userinfo, which is where an API key usually ` +
+                    `rides. This file is git-tracked — prefer \`url: ${ENV_REF_PREFIX}VAR_NAME\` and ` +
+                    `keep the value in the environment`);
+            }
+        }
+    }
+    if (raw.args !== undefined) {
+        if (!Array.isArray(raw.args) || !raw.args.every((a) => typeof a === "string")) {
+            return fail(`${where}.args: must be a list of strings`);
+        }
+        const args = [];
+        for (const [i, arg] of raw.args.entries()) {
+            const res = resolveLeaf(arg, env, `${where}.args[${i}]`);
+            if (!res.ok)
+                return { errors, warnings: [...warnings, `${res.error} — server not attached`] };
+            args.push(res.value);
+        }
+        if (args.length > 0)
+            server.args = args;
+    }
+    if (raw.env !== undefined) {
+        if (!isRecord(raw.env))
+            return fail(`${where}.env: must be a mapping of NAME to value`);
+        const resolved = {};
+        for (const [key, value] of Object.entries(raw.env)) {
+            if (typeof value !== "string") {
+                return fail(`${where}.env.${key}: must be a string (values are passed to a process verbatim)`);
+            }
+            const res = resolveLeaf(value, env, `${where}.env.${key}`);
+            if (!res.ok)
+                return { errors, warnings: [...warnings, `${res.error} — server not attached`] };
+            resolved[key] = res.value;
+            if (!value.startsWith(ENV_REF_PREFIX) && SECRET_ISH_KEY_RE.test(key)) {
+                warnings.push(`${where}.env.${key}: looks like a credential and is written into the config file ` +
+                    `itself, which is git-tracked — prefer \`${key}: ${ENV_REF_PREFIX}VAR_NAME\` and set ` +
+                    `the value in the environment`);
+            }
+        }
+        if (Object.keys(resolved).length > 0)
+            server.env = resolved;
+    }
+    return { server, errors, warnings };
+}
+/**
+ * Resolve the whole `mcpServers:` block against `env`.
+ *
+ * Never throws. A declaration paddock cannot carry is reported and dropped so one
+ * typo cannot take an instance down — the same posture as
+ * `resolveManagementApiConfig`, and for the same reason: this is a capability,
+ * and losing a capability is better than losing the instance.
+ */
+export function resolveDeclaredMcpServers(file, env) {
+    const servers = {};
+    const errors = [];
+    const warnings = [];
+    if (file === undefined || file === null)
+        return { servers, errors, warnings };
+    if (!isRecord(file)) {
+        errors.push("mcpServers: must be a mapping of server name to declaration — ignored");
+        return { servers, errors, warnings };
+    }
+    for (const [rawName, decl] of Object.entries(file)) {
+        const name = rawName.trim();
+        if (name.length === 0) {
+            errors.push("mcpServers: a server name is empty — not attached");
+            continue;
+        }
+        const res = narrowDeclaration(name, decl, env);
+        errors.push(...res.errors);
+        warnings.push(...res.warnings);
+        if (res.server)
+            servers[name] = res.server;
+    }
+    return { servers, errors, warnings };
+}
+/**
+ * What to say at boot about the declared servers — the answer to "what does this
+ * instance actually have?", which should be readable off the log rather than
+ * inferred from a YAML file plus an environment.
+ *
+ * Takes the already-resolved servers, so it cannot see a raw declaration and
+ * therefore cannot leak one; every line it produces goes through
+ * {@link describeServer}.
+ */
+export function declaredMcpNotices(opts) {
+    const names = Object.keys(opts.servers);
+    if (names.length === 0)
+        return [];
+    const notices = [
+        {
+            level: "info",
+            message: `MCP servers declared by this instance (\`mcpServers:\`): ` +
+                `${names.map((n) => describeServer(n, opts.servers[n])).join("; ")}. ` +
+                `Every project's keeper gets all of them.`,
+        },
+    ];
+    const shadowed = names.filter((n) => opts.hostNames?.includes(n));
+    if (shadowed.length > 0) {
+        notices.push({
+            level: "info",
+            message: `${shadowed.join(", ")} ${shadowed.length === 1 ? "is" : "are"} also declared in your ` +
+                `~/.claude.json (\`claude.mcpServers: host\`); this instance's own declaration wins.`,
+        });
+    }
+    if (opts.browserMcp && names.includes("playwright")) {
+        notices.push({
+            level: "warn",
+            message: `mcpServers.playwright collides with paddock's own browser server, which WINS — your ` +
+                `declaration is not attached. Set \`browserMcp: false\` to use yours instead.`,
+        });
+    }
+    return notices;
+}

package/packages/server/dist/routes/chats.js

@@ -584,7 +584,7 @@ export function registerChatWorkspaceRoutes(app, ctx) {
         schema: {
             tags: ["Chats"],
             summary: "Delete a project chat",
-            description: "Deletes a project chat (session): removes its transcript JSONL and clears any archived/starred flag so a future session id can't inherit it. Responds 200 with `{ ok, removed }`.",
+            description: "Deletes a project chat (session) and clears any archived/starred flag so a future session id can't inherit it. Responds 200 with `{ ok, removed, retained }`. In a Claude home Paddock owns, the transcript JSONL is unlinked (`removed: true`). In a home it does NOT own the transcript is the user's own terminal `claude` history — Paddock plants no symlink there (#682), so there is no copy to delete — and the session is RELEASED instead: it leaves the chat list, the file stays on disk, and `retained` is true (#689).",
             params: {
                 type: "object",
                 properties: {
@@ -605,7 +605,7 @@ export function registerChatWorkspaceRoutes(app, ctx) {
         try {
             const agent = await agentForSlug(req.params.slug);
             await cleanupAttachments(agent, req.params.sessionId);
-            const removed = await herdctl.deleteSession(agent, req.params.sessionId);
+            const { removed, retained } = await herdctl.deleteSession(agent, req.params.sessionId);
             // Drop any archived/starred/unread/detached flag so a future session id
             // can't inherit it. (Read-state watermarks, other users' unread overrides,
             // provenance and any queued message are deliberately NOT swept here — that
@@ -619,7 +619,7 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             // has to be cleared on the same path — otherwise a recycled session id
             // silently starts life detached from a parent it never had.
             await parentDetach.setDetached(agent, req.params.sessionId, false).catch(() => undefined);
-            return reply.code(200).send({ ok: true, removed });
+            return reply.code(200).send({ ok: true, removed, retained });
         }
         catch (err) {
             return sendProjectError(reply, err);
@@ -1208,7 +1208,13 @@ export function registerChatWorkspaceRoutes(app, ctx) {
                 try {
                     await cleanupAttachments(agent, sessionId);
                     const gone = await herdctl.deleteSession(agent, sessionId);
-                    if (gone)
+                    // `retained` counts as success here, and the distinction matters for
+                    // the flag-clearing below. These two buckets are "no longer in the
+                    // chat list" vs "still in it": a RELEASED chat (#689) left the list
+                    // even though its transcript survives on disk, so its flags must be
+                    // cleared like any other departure. Only a genuine failure — nothing
+                    // on disk to act on — belongs in `failed`.
+                    if (gone.removed || gone.retained)
                         removed.push(sessionId);
                     else
                         failed.push(sessionId);

package/packages/server/dist/transcripts.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Whose transcripts this instance uses — the `claude.transcripts` config key.
+ *
+ * `own` = paddock's, inside the data dir / project. `host` = this machine's
+ * Claude Code, shared live. See the module doc for the mechanism.
+ */
+export type TranscriptsMode = "own" | "host";
+/** Isolation is the default: nothing outside the data dir is written (#691). */
+export declare const DEFAULT_TRANSCRIPTS_MODE: TranscriptsMode;
+/** Type guard, so an unknown config value falls back instead of failing a boot. */
+export declare function isKnownTranscriptsMode(value: string): value is TranscriptsMode;
 /**
  * Encode a working directory the way Claude Code names its transcript dir.
  * For paths under 200 chars this is just the non-alphanumeric→'-' replacement
@@ -8,7 +19,44 @@ export declare function encodeProjectDir(dir: string): string;
 /** Absolute path to the project's local transcript directory. */
 export declare function projectChatsDir(projectDir: string): string;
 /**
- * Ensure `<chatsHostDir>/.chats/` exists and that Claude Code's encoded
+ * The transcript folder a Claude home holds for `workingDir` —
+ * `<home>/projects/<encoded-cwd>`.
+ *
+ * The LITERAL path, before any symlink is followed, which is what makes it worth
+ * naming: it is the string Claude Code builds its session file AND its agent
+ * memory dir (`<here>/memory`) out of, and the agent harness refuses to write to
+ * any path with a `.claude` component in it (#690). Under paddock's own home it
+ * never has one, in either {@link TranscriptsMode}.
+ */
+export declare function encodedTranscriptDir(claudeHome: string, workingDir: string): string;
+/**
+ * Where a project's transcripts are planted, and where they point.
+ *
+ * `path` is the Claude home to plant the redirect symlink in, and it is REQUIRED
+ * — no default (#620). Callers must pass `cfg.claudeHome`: the engine is
+ * constructed with that same resolved value, and a symlink planted in a
+ * different home than the one the engine reads is exactly the "chats list but
+ * open empty" failure (#588). It used to default to the env-derived home for
+ * callers with no config, and `ensureSweeperHome` silently took that default —
+ * so the sweeper's symlink landed in a different home than every other agent's.
+ * Making the parameter required is what stops that class of bug at the type
+ * level.
+ *
+ * Since #691 paddock ALWAYS owns `path`, so the old `owned` flag is gone: the
+ * question it used to answer ("may we write here?") now has one answer, and the
+ * question that actually varies — whose transcripts these are — is
+ * {@link transcripts}.
+ */
+export interface ClaudeHomeTarget {
+    /** Absolute path to paddock's own Claude home (`cfg.claudeHome`). */
+    path: string;
+    /** Whose transcripts this instance uses (`cfg.claude.transcripts`). */
+    transcripts: TranscriptsMode;
+    /** The user's own `~/.claude` — the store under `transcripts: "host"`. */
+    userHome: string;
+}
+/**
+ * Ensure the project's transcript store exists and that Claude Code's encoded
  * transcript path for `workingDir` is a symlink pointing at it (migrating an
  * existing real transcript dir in the process). Safe to call on every agent
  * registration. Never throws — a failure here must not block agent registration
@@ -21,38 +69,21 @@ export declare function projectChatsDir(projectDir: string): string;
  * store stays in the project's metadata dir (the data repo) — so transcripts
  * never pollute the external repo's working tree — hence the two are split.
  *
- * `home.path` is the Claude home to plant the symlink in, and it is REQUIRED —
- * no default (#620). Callers must pass `cfg.claudeHome`: the engine is
- * constructed with that same resolved value, and a symlink planted in a
- * different home than the one the engine reads is exactly the "chats list but
- * open empty" failure (#588). It used to default to the env-derived home for
- * callers with no config, and `ensureSweeperHome` silently took that default —
- * so the sweeper's symlink landed in a different home than every other agent's.
- * Making the parameter required is what stops that class of bug at the type
- * level.
- *
- * `home.owned` gates EVERY write into the home (#620, #682). Two of them:
+ * The store is `<chatsHostDir>/.chats/` under `transcripts: "own"` and the user's
+ * own `~/.claude/projects/<encoded-cwd>/` under `transcripts: "host"`; everything
+ * below is the same code either way.
  *
- *  - Migrating an existing real transcript directory into `.chats/` copies the
- *    files and then REMOVES the originals. That is correct self-healing inside a
- *    home paddock owns, where such a directory can only be paddock's own doing.
- *    Inside the user's `~/.claude` it is somebody else's data — a `claude` CLI
- *    session run in a directory paddock happens to also manage — so we leave it
- *    strictly alone and let the SDK keep writing there.
- *  - Planting the redirect symlink at a path that does not exist yet. Not
- *    destructive on the day it happens, which is why it was missed, but it
- *    silently claims where the user's FUTURE sessions for that directory get
- *    written (#682). See the branch itself for the full argument.
+ * ## The one write into `~/.claude`, and why it is not the #682 mistake
  *
- * Either way those transcripts stay importable through adoption (#588), which is
- * the deliberate, user-driven version of the same move.
+ * Under `host` this creates `~/.claude/projects/<encoded-cwd>/` if it is missing,
+ * because a symlink to a non-existent directory is not something Claude Code can
+ * `mkdir -p` through. That is a directory Claude Code itself would create the
+ * first time the user ran `claude` there, made under a config key whose entire
+ * meaning is "share the host's transcripts". #682 was the opposite: planting a
+ * link that silently REDIRECTED the user's future sessions into paddock's store
+ * on an instance that had asked for no such thing. Under `own` — the default —
+ * nothing under `~/.claude` is created, read or written at all.
  */
-export interface ClaudeHomeTarget {
-    /** Absolute path to the Claude home to plant the redirect symlink in. */
-    path: string;
-    /** Whether paddock owns this home — see `PaddockConfig.ownsClaudeHome`. */
-    owned: boolean;
-}
 export declare function ensureProjectChats(workingDir: string, chatsHostDir: string, home: ClaudeHomeTarget): Promise<void>;
 /**
  * Read a session's FIRST user message text, untruncated, straight from its