stageflow 0.36.0 → 0.40.0

package/dist/config/mcpOAuth.js

@@ -0,0 +1,263 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, linkSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { assertServerName, readMcpSecrets } from "./mcpHostCatalog.js";
+import { assertSafeMcpUrl, collectSecretValues, McpUrlPolicyError, oauthDefinition, scrubText } from "./mcpRedaction.js";
+import { loadMcpCatalog, resolveStageMcpServers, StageMcpError, } from "./resolveStageMcpServers.js";
+/**
+ * OAuth sign-in for remote MCP servers, run through pi-mcp-adapter's own flow.
+ *
+ * Tokens live in the adapter's encrypted-file store under the Host's Pi agent dir
+ * (`$STAGEFLOW_HOME/agent/mcp-oauth-encrypted`) and are keyed by a Host-generated key, so it works
+ * in a container with no OS keyring. The adapter refuses a symlinked store, and stage attempts run
+ * with a sealed per-attempt agent dir, so signed-in servers are available to agents and Check, not
+ * to pipeline stages.
+ */
+export const OAUTH_FILE_KEY_ENV = "PI_MCP_ADAPTER_OAUTH_FILE_KEY";
+/** HTTP status for each OAuth error code; the routes use this one table. */
+export const MCP_OAUTH_HTTP_STATUS = {
+    not_found: 404,
+    not_http: 400,
+    flow_failed: 400,
+    invalid_input: 400,
+    blocked_url: 400,
+    store_unavailable: 500,
+    host_state_corrupt: 409,
+};
+export class McpOAuthError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "McpOAuthError";
+        this.code = code;
+    }
+}
+export function oauthKeyPath(home = globalStageflowHome()) {
+    return path.join(home, "secrets", "mcp-oauth.key");
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function readKeyWithRetry(file) {
+    for (let i = 0; i < 20; i += 1) {
+        const value = readFileSync(file, "utf8").trim();
+        if (value !== "")
+            return value;
+        sleepSync(25);
+    }
+    throw new Error(`OAuth key file "${file}" is empty; remove it so a new key can be generated`);
+}
+/**
+ * Make the Host's file key available to the adapter, creating it on first use. The key is written
+ * to a private tmp file and linked into place, so a concurrent reader never sees a half-written key.
+ */
+export function ensureOAuthFileKey(home = globalStageflowHome()) {
+    if ((process.env[OAUTH_FILE_KEY_ENV] ?? "").trim() !== "")
+        return;
+    const file = oauthKeyPath(home);
+    if (!existsSync(file)) {
+        mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        const tmp = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+        try {
+            writeFileSync(tmp, `${randomBytes(32).toString("base64")}\n`, { mode: 0o600, flag: "wx" });
+            linkSync(tmp, file);
+        }
+        catch (err) {
+            // Another process linked its key first; read theirs.
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        finally {
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    process.env[OAUTH_FILE_KEY_ENV] = readKeyWithRetry(file);
+}
+/** Everything the adapter needs before it can read or write OAuth tokens in this process. */
+export function prepareMcpOAuth() {
+    ensureOAuthFileKey(globalStageflowHome());
+}
+let cachedFlow;
+/**
+ * The adapter only exports token reads publicly; the interactive flow lives in an internal module.
+ * It is loaded by path behind this one function, and `tests/mcp.oauth.flow.test.ts` fails if the
+ * names we rely on go away.
+ */
+async function loadFlow() {
+    cachedFlow ??= (async () => {
+        const require = createRequire(import.meta.url);
+        const pkgDir = path.dirname(require.resolve("pi-mcp-adapter/oauth"));
+        const { createJiti } = await import("jiti/static");
+        const jiti = createJiti(import.meta.url, {
+            fsCache: path.join(globalStageflowHome(), "cache", "jiti"),
+        });
+        return (await jiti.import(path.join(pkgDir, "mcp-auth-flow.ts")));
+    })();
+    try {
+        return await cachedFlow;
+    }
+    catch (err) {
+        cachedFlow = undefined;
+        throw err;
+    }
+}
+export function resetMcpOAuthFlowCacheForTests() {
+    cachedFlow = undefined;
+}
+const STORAGE = { authStorageOptions: { credentialStore: "encrypted-file" } };
+function consoleSecretValues() {
+    try {
+        return Object.values(readMcpSecrets());
+    }
+    catch {
+        return [];
+    }
+}
+/** Confirm `name` is a known URL server; no secrets are resolved. */
+async function requireRemoteEntry(projectRoot, name) {
+    try {
+        assertServerName(name);
+    }
+    catch {
+        throw new McpOAuthError(`Server "${name}" not found`, "not_found");
+    }
+    let catalog;
+    try {
+        catalog = await loadMcpCatalog(projectRoot, { scope: { kind: "validate" } });
+    }
+    catch (err) {
+        if (err instanceof StageMcpError) {
+            if (err.code === "host_state_corrupt")
+                throw new McpOAuthError(err.message, "host_state_corrupt");
+            throw new McpOAuthError(`Server "${name}" not found`, "not_found");
+        }
+        throw err;
+    }
+    if (!Object.hasOwn(catalog.servers, name)) {
+        throw new McpOAuthError(`Server "${name}" not found`, "not_found");
+    }
+    const entry = catalog.servers[name];
+    if (typeof entry.url !== "string") {
+        throw new McpOAuthError(`Server "${name}" is a local command; OAuth applies to URL servers`, "not_http");
+    }
+    return entry;
+}
+/** Name must be a known URL server when a project root is given (the routes always give one). */
+async function checkKnown(name, projectRoot) {
+    if (projectRoot !== undefined)
+        await requireRemoteEntry(projectRoot, name);
+}
+async function remoteServer(projectRoot, name) {
+    await requireRemoteEntry(projectRoot, name);
+    let resolved;
+    try {
+        resolved = await resolveStageMcpServers({
+            projectRoot,
+            allowlist: [name],
+            env: {},
+            scope: { kind: "agent" },
+        });
+    }
+    catch (err) {
+        if (err instanceof StageMcpError && err.code === "host_state_corrupt") {
+            throw new McpOAuthError(err.message, "host_state_corrupt");
+        }
+        if (err instanceof StageMcpError && err.code === "invalid_config") {
+            throw new McpOAuthError(err.message, "blocked_url");
+        }
+        throw err;
+    }
+    const entry = resolved[name] ?? {};
+    const url = String(entry.url);
+    try {
+        assertSafeMcpUrl(url);
+    }
+    catch (err) {
+        if (err instanceof McpUrlPolicyError)
+            throw new McpOAuthError(err.message, "blocked_url");
+        throw err;
+    }
+    return { url, definition: { ...oauthDefinition(entry), auth: "oauth" }, secrets: collectSecretValues(entry) };
+}
+function wrapFlowError(err, extraSecrets = []) {
+    if (err instanceof McpOAuthError)
+        throw err;
+    const raw = err instanceof Error ? err.message : String(err);
+    const message = scrubText(raw, [...extraSecrets, ...consoleSecretValues()]);
+    if (/OAUTH_FILE_KEY|credential store/i.test(message)) {
+        throw new McpOAuthError(message, "store_unavailable");
+    }
+    throw new McpOAuthError(message, "flow_failed");
+}
+function prepare() {
+    try {
+        prepareMcpOAuth();
+    }
+    catch (err) {
+        throw new McpOAuthError(`Could not prepare the OAuth store: ${err instanceof Error ? err.message : String(err)}`, "store_unavailable");
+    }
+}
+/** Begin sign-in; returns the link to open in a browser. */
+export async function startMcpOAuth(projectRoot, name) {
+    prepare();
+    const { url, definition, secrets } = await remoteServer(projectRoot, name);
+    try {
+        const flow = await loadFlow();
+        return await flow.startAuth(name, url, definition, STORAGE);
+    }
+    catch (err) {
+        return wrapFlowError(err, secrets);
+    }
+}
+const MAX_OAUTH_INPUT = 4096;
+/** The pasted redirect address, or a bare authorization code of sane length. */
+export function assertOAuthInput(input) {
+    const value = input.trim();
+    const looksLikeUrl = /^https?:\/\/\S+$/i.test(value);
+    const looksLikeCode = /^[A-Za-z0-9._~+/=-]{4,512}$/.test(value);
+    if (value.length > MAX_OAUTH_INPUT || !(looksLikeUrl || looksLikeCode)) {
+        throw new McpOAuthError("Paste the full address from the browser (or the authorization code)", "invalid_input");
+    }
+}
+/** Finish sign-in from the redirect URL the browser landed on (or a bare code). */
+export async function completeMcpOAuth(name, input, projectRoot) {
+    await checkKnown(name, projectRoot);
+    assertOAuthInput(input);
+    prepare();
+    try {
+        const flow = await loadFlow();
+        return await flow.completeAuthFromInput(name, input, STORAGE);
+    }
+    catch (err) {
+        return wrapFlowError(err);
+    }
+}
+export async function mcpOAuthStatus(name, projectRoot) {
+    await checkKnown(name, projectRoot);
+    prepare();
+    try {
+        const flow = await loadFlow();
+        return await flow.getAuthStatus(name, STORAGE);
+    }
+    catch (err) {
+        return wrapFlowError(err);
+    }
+}
+export async function removeMcpOAuth(name, projectRoot) {
+    await checkKnown(name, projectRoot);
+    prepare();
+    try {
+        const flow = await loadFlow();
+        await flow.removeAuth(name, STORAGE);
+    }
+    catch (err) {
+        wrapFlowError(err);
+    }
+}

package/dist/config/mcpRedaction.d.ts

@@ -0,0 +1,42 @@
+/**
+ * One place that knows every secret-bearing location of an MCP server entry:
+ * env values, header values, URL userinfo and query params, and args like `--token=...`.
+ *
+ * Three views of the same entry:
+ * - stored:   `extractSecrets` moves literal tokens out into a secrets map and leaves `${NAME}`.
+ * - shown:    `maskEntry` is what the console reads back; literals become "••••".
+ * - scrubbed: `scrubText` removes secret values from error text.
+ *
+ * Also hosts the URL policy (`assertSafeMcpUrl`) so save, probe, OAuth and resolve share it.
+ */
+export declare const MASK = "\u2022\u2022\u2022\u2022";
+/** Keys that carry a literal secret in env/headers/query/args. */
+export declare const SECRET_KEY: RegExp;
+export declare function literalLooksSecret(key: string, value: string): boolean;
+export declare class McpUrlPolicyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Link-local and cloud-metadata destinations are never a real MCP server and are the classic SSRF
+ * target. Loopback and private LAN ranges stay allowed: local MCP servers are normal.
+ */
+export declare function isBlockedMcpHost(hostname: string): boolean;
+/** Throws McpUrlPolicyError for an unusable or forbidden URL. Placeholder URLs are skipped. */
+export declare function assertSafeMcpUrl(raw: string): void;
+export type SecretNamer = (key: string, value: string, taken: Record<string, string>) => string;
+/**
+ * Move literal secrets out of a (validated) entry. Returns a new entry holding `${NAME}`
+ * placeholders and the `{ NAME: value }` map to store.
+ */
+export declare function extractSecrets(entry: Record<string, unknown>, name: SecretNamer, taken?: Record<string, string>): {
+    entry: Record<string, unknown>;
+    secrets: Record<string, string>;
+};
+/** Read-back view: placeholders stay, literal secrets become "••••". Same JSON shape. */
+export declare function maskEntry(entry: Record<string, unknown>): Record<string, unknown>;
+/** Secret values carried by a RESOLVED entry (placeholders already filled). */
+export declare function collectSecretValues(entry: Record<string, unknown>): string[];
+/** Remove secret values from text. Values shorter than 6 chars are ignored on purpose. */
+export declare function scrubText(text: string, secrets: Iterable<string>): string;
+/** OAuth only needs the URL, transport and non-secret headers; drop the rest. */
+export declare function oauthDefinition(entry: Record<string, unknown>): Record<string, unknown>;

package/dist/config/mcpRedaction.js

@@ -0,0 +1,314 @@
+/**
+ * One place that knows every secret-bearing location of an MCP server entry:
+ * env values, header values, URL userinfo and query params, and args like `--token=...`.
+ *
+ * Three views of the same entry:
+ * - stored:   `extractSecrets` moves literal tokens out into a secrets map and leaves `${NAME}`.
+ * - shown:    `maskEntry` is what the console reads back; literals become "••••".
+ * - scrubbed: `scrubText` removes secret values from error text.
+ *
+ * Also hosts the URL policy (`assertSafeMcpUrl`) so save, probe, OAuth and resolve share it.
+ */
+export const MASK = "••••";
+const MIN_SCRUB_LENGTH = 6;
+/** Keys that carry a literal secret in env/headers/query/args. */
+export const SECRET_KEY = /token|secret|password|passwd|api[-_]?key|auth|credential|bearer|private[-_]?key/i;
+const TOKEN_PREFIX = /^(?:gh[pousr]_|github_pat_|sk-|xox[abprs]-|AKIA|AIza|glpat-|npm_|pk_live_|sk_live_|ya29\.)/;
+const AUTH_PREFIX = /^(?:Bearer|Basic|Token)\s+/i;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function literalLooksSecret(key, value) {
+    if (value.length === 0 || value.includes("${"))
+        return false;
+    const bare = value.replace(AUTH_PREFIX, "");
+    if (TOKEN_PREFIX.test(bare))
+        return true;
+    if (SECRET_KEY.test(key))
+        return true;
+    return (bare.length >= 32 &&
+        /^[A-Za-z0-9_\-+/=.]+$/.test(bare) &&
+        /\d/.test(bare) &&
+        /[A-Za-z]/.test(bare));
+}
+// ---------------------------------------------------------------- URL policy
+export class McpUrlPolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpUrlPolicyError";
+    }
+}
+function ipv4Octets(host) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    return m ? m.slice(1).map(Number) : undefined;
+}
+function mappedV4(host) {
+    // URL() normalises ::ffff:1.2.3.4 to ::ffff:102:304
+    const m = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(host);
+    if (!m)
+        return undefined;
+    const hi = Number.parseInt(m[1], 16);
+    const lo = Number.parseInt(m[2], 16);
+    return [hi >> 8, hi & 0xff, lo >> 8, lo & 0xff];
+}
+/**
+ * Link-local and cloud-metadata destinations are never a real MCP server and are the classic SSRF
+ * target. Loopback and private LAN ranges stay allowed: local MCP servers are normal.
+ */
+export function isBlockedMcpHost(hostname) {
+    let host = hostname.toLowerCase();
+    if (host.startsWith("[") && host.endsWith("]"))
+        host = host.slice(1, -1);
+    host = host.replace(/\.$/, "");
+    if (host === "metadata.google.internal" || host === "metadata")
+        return true;
+    const v4 = ipv4Octets(host) ?? mappedV4(host);
+    if (v4)
+        return v4[0] === 169 && v4[1] === 254;
+    if (host.includes(":")) {
+        if (/^fe[89ab][0-9a-f]?:/i.test(host))
+            return true; // fe80::/10
+        if (/^fd00:0*ec2:(?:0*:)*0*:?0*254$/i.test(host) || host === "fd00:ec2::254")
+            return true;
+        if (/^fd00:ec2:/i.test(host) && /254$/.test(host))
+            return true;
+    }
+    return false;
+}
+/** Throws McpUrlPolicyError for an unusable or forbidden URL. Placeholder URLs are skipped. */
+export function assertSafeMcpUrl(raw) {
+    if (raw.includes("${"))
+        return;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new McpUrlPolicyError("\"url\" is not a valid URL");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new McpUrlPolicyError("\"url\" must start with http:// or https://");
+    }
+    if (isBlockedMcpHost(parsed.hostname)) {
+        throw new McpUrlPolicyError("\"url\" points at a link-local or cloud-metadata address, which is not allowed");
+    }
+}
+function take(ex, key, value) {
+    const prefix = AUTH_PREFIX.exec(value)?.[0] ?? "";
+    const bare = value.slice(prefix.length);
+    const secretName = ex.name(key, bare, { ...ex.taken, ...ex.found });
+    ex.found[secretName] = bare;
+    return `${prefix}\${${secretName}}`;
+}
+function extractUrl(url, ex) {
+    if (url.includes("${") && !/[?@]/.test(url))
+        return url;
+    const hashAt = url.indexOf("#");
+    const beforeHash = hashAt === -1 ? url : url.slice(0, hashAt);
+    const hash = hashAt === -1 ? "" : url.slice(hashAt);
+    const qAt = beforeHash.indexOf("?");
+    let base = qAt === -1 ? beforeHash : beforeHash.slice(0, qAt);
+    const query = qAt === -1 ? undefined : beforeHash.slice(qAt + 1);
+    base = base.replace(/^(\w+:\/\/)([^/@]*)@/, (_m, scheme, info) => {
+        const colon = info.indexOf(":");
+        if (colon === -1) {
+            return literalLooksSecret("token", info) && !info.includes("${")
+                ? `${scheme}${take(ex, "token", info)}@`
+                : `${scheme}${info}@`;
+        }
+        const user = info.slice(0, colon);
+        const pass = info.slice(colon + 1);
+        if (pass.length === 0 || pass.includes("${"))
+            return `${scheme}${info}@`;
+        return `${scheme}${user}:${take(ex, "password", decodeSafe(pass))}@`;
+    });
+    let out = base;
+    if (query !== undefined) {
+        const pairs = query.split("&").map((pair) => {
+            const eq = pair.indexOf("=");
+            if (eq === -1)
+                return pair;
+            const key = decodeSafe(pair.slice(0, eq));
+            const value = decodeSafe(pair.slice(eq + 1));
+            if (!literalLooksSecret(key, value))
+                return pair;
+            return `${pair.slice(0, eq)}=${take(ex, key, value)}`;
+        });
+        out += `?${pairs.join("&")}`;
+    }
+    return out + hash;
+}
+function decodeSafe(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function extractArgs(args, ex) {
+    const out = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        const eq = /^(--?[A-Za-z0-9][A-Za-z0-9_.-]*)=([\s\S]*)$/.exec(arg);
+        if (eq) {
+            const [, flag, value] = eq;
+            if (literalLooksSecret(flag.replace(/^-+/, ""), value)) {
+                out.push(`${flag}=${take(ex, flag.replace(/^-+/, ""), value)}`);
+            }
+            else {
+                out.push(arg);
+            }
+            continue;
+        }
+        const flag = /^--?([A-Za-z0-9][A-Za-z0-9_.-]*)$/.exec(arg);
+        const next = args[i + 1];
+        if (flag && next !== undefined && !next.startsWith("-") && literalLooksSecret(flag[1], next)) {
+            out.push(arg, take(ex, flag[1], next));
+            i += 1;
+            continue;
+        }
+        if (TOKEN_PREFIX.test(arg.replace(AUTH_PREFIX, ""))) {
+            out.push(take(ex, "token", arg));
+            continue;
+        }
+        out.push(arg);
+    }
+    return out;
+}
+/**
+ * Move literal secrets out of a (validated) entry. Returns a new entry holding `${NAME}`
+ * placeholders and the `{ NAME: value }` map to store.
+ */
+export function extractSecrets(entry, name, taken = {}) {
+    const ex = { taken, found: {}, name };
+    const out = { ...entry };
+    for (const key of ["env", "headers"]) {
+        const bag = entry[key];
+        if (!isPlainObject(bag))
+            continue;
+        const copy = {};
+        for (const [field, value] of Object.entries(bag)) {
+            copy[field] =
+                typeof value === "string" && literalLooksSecret(field, value)
+                    ? take(ex, field, value)
+                    : value;
+        }
+        out[key] = copy;
+    }
+    if (typeof entry.url === "string")
+        out.url = extractUrl(entry.url, ex);
+    if (Array.isArray(entry.args))
+        out.args = extractArgs(entry.args, ex);
+    return { entry: out, secrets: ex.found };
+}
+// -------------------------------------------------------------- shown (mask)
+function maskUrl(url) {
+    const { entry } = extractSecrets({ url }, (key, value) => {
+        void value;
+        return `__MASK_${key}`;
+    });
+    return String(entry.url)
+        .replace(/\$\{__MASK_[^}]*\}/g, MASK);
+}
+function maskArgs(args) {
+    const { entry } = extractSecrets({ args }, (key) => `__MASK_${key}`);
+    return entry.args.map((a) => a.replace(/\$\{__MASK_[^}]*\}/g, MASK));
+}
+/** Read-back view: placeholders stay, literal secrets become "••••". Same JSON shape. */
+export function maskEntry(entry) {
+    const out = { ...entry };
+    for (const key of ["env", "headers"]) {
+        const bag = entry[key];
+        if (!isPlainObject(bag))
+            continue;
+        const copy = {};
+        for (const [field, value] of Object.entries(bag)) {
+            if (typeof value === "string" && literalLooksSecret(field, value)) {
+                copy[field] = `${AUTH_PREFIX.exec(value)?.[0] ?? ""}${MASK}`;
+            }
+            else {
+                copy[field] = value;
+            }
+        }
+        out[key] = copy;
+    }
+    if (typeof entry.url === "string")
+        out.url = maskUrl(entry.url);
+    if (Array.isArray(entry.args))
+        out.args = maskArgs(entry.args);
+    return out;
+}
+// ----------------------------------------------------------- scrubbed (text)
+/** Secret values carried by a RESOLVED entry (placeholders already filled). */
+export function collectSecretValues(entry) {
+    const values = new Set();
+    const add = (v) => {
+        if (v.length < MIN_SCRUB_LENGTH)
+            return;
+        values.add(v);
+        const enc = encodeURIComponent(v);
+        if (enc !== v)
+            values.add(enc);
+    };
+    for (const key of ["env", "headers"]) {
+        const bag = entry[key];
+        if (!isPlainObject(bag))
+            continue;
+        for (const v of Object.values(bag)) {
+            if (typeof v !== "string")
+                continue;
+            add(v);
+            const bare = v.replace(AUTH_PREFIX, "");
+            if (bare !== v)
+                add(bare);
+        }
+    }
+    if (typeof entry.url === "string") {
+        const { secrets } = extractSecrets({ url: entry.url }, (k) => `S_${k}`);
+        Object.values(secrets).forEach(add);
+        // userinfo password even when it does not look token-like
+        const info = /^\w+:\/\/([^/@]*)@/.exec(entry.url)?.[1];
+        const pass = info?.includes(":") ? info.slice(info.indexOf(":") + 1) : undefined;
+        if (pass)
+            add(decodeSafe(pass));
+        try {
+            for (const [k, v] of new URL(entry.url).searchParams)
+                if (SECRET_KEY.test(k))
+                    add(v);
+        }
+        catch {
+            /* not parseable: nothing more to collect */
+        }
+    }
+    if (Array.isArray(entry.args)) {
+        const { secrets } = extractSecrets({ args: entry.args }, (k) => `S_${k}`);
+        Object.values(secrets).forEach(add);
+    }
+    return [...values];
+}
+/** Remove secret values from text. Values shorter than 6 chars are ignored on purpose. */
+export function scrubText(text, secrets) {
+    let out = text;
+    const list = [...secrets].filter((s) => s.length >= MIN_SCRUB_LENGTH);
+    list.sort((a, b) => b.length - a.length);
+    for (const secret of list)
+        out = out.split(secret).join("[redacted]");
+    return out;
+}
+/** OAuth only needs the URL, transport and non-secret headers; drop the rest. */
+export function oauthDefinition(entry) {
+    const out = {};
+    for (const [key, value] of Object.entries(entry)) {
+        if (key === "env" || key === "command" || key === "args" || key === "cwd")
+            continue;
+        if (key === "headers" && isPlainObject(value)) {
+            const kept = Object.fromEntries(Object.entries(value).filter(([name, v]) => !SECRET_KEY.test(name) && !(typeof v === "string" && literalLooksSecret(name, v))));
+            if (Object.keys(kept).length > 0)
+                out.headers = kept;
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}

package/dist/config/mcpToolCache.d.ts

@@ -0,0 +1,20 @@
+export type McpToolInfo = {
+    /** The name to put in an agent's `tools.mcp.<server>` list. */
+    name: string;
+    description?: string;
+};
+export type McpToolList = {
+    tools: McpToolInfo[];
+    cachedAt: number;
+};
+/**
+ * The name an agent grants for one MCP tool. The adapter exposes `<server>_<tool>` to Pi (dots in the
+ * tool name become underscores) and the runtime strips `<server>_` again, so the grant is the
+ * sanitised tool name without that prefix.
+ */
+export declare function grantNameForMcpTool(server: string, tool: string): string;
+/**
+ * Tools the adapter saw the last time it connected to `server` (it writes them to the Pi agent dir's
+ * `mcp-cache.json`). Undefined when it has never connected.
+ */
+export declare function listCachedMcpTools(server: string, agentDir?: string): McpToolList | undefined;

package/dist/config/mcpToolCache.js

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+/**
+ * The name an agent grants for one MCP tool. The adapter exposes `<server>_<tool>` to Pi (dots in the
+ * tool name become underscores) and the runtime strips `<server>_` again, so the grant is the
+ * sanitised tool name without that prefix.
+ */
+export function grantNameForMcpTool(server, tool) {
+    const sanitized = tool.replace(/\./g, "_");
+    return sanitized.startsWith(`${server}_`) && sanitized.length > server.length + 1
+        ? sanitized.slice(server.length + 1)
+        : sanitized;
+}
+/**
+ * Tools the adapter saw the last time it connected to `server` (it writes them to the Pi agent dir's
+ * `mcp-cache.json`). Undefined when it has never connected.
+ */
+export function listCachedMcpTools(server, agentDir = getAgentDir()) {
+    const file = path.join(agentDir, "mcp-cache.json");
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        const entry = parsed.servers?.[server];
+        if (!entry || !Array.isArray(entry.tools))
+            return undefined;
+        const tools = [];
+        for (const tool of entry.tools) {
+            if (typeof tool.name !== "string")
+                continue;
+            tools.push({
+                name: grantNameForMcpTool(server, tool.name),
+                ...(typeof tool.description === "string" && tool.description ? { description: tool.description } : {}),
+            });
+        }
+        tools.sort((a, b) => a.name.localeCompare(b.name));
+        return { tools, cachedAt: typeof entry.cachedAt === "number" ? entry.cachedAt : 0 };
+    }
+    catch {
+        return undefined;
+    }
+}