brainctl 0.1.7 → 0.1.9

package/dist/mcp/server.js

@@ -1,3 +1,4 @@
+import { spawn } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { FastMCP } from 'fastmcp';
@@ -288,14 +289,20 @@ export function createMcpServer(options = {}) {
         name: 'brainctl_export_profile',
         description: 'Export a profile as a portable tarball. Packages the profile config and bundled MCP source code for sharing.',
         parameters: z.object({
-            name: z.string().describe('Profile name to export'),
+            name: z.string().optional().describe('Profile name to export'),
+            agent: z.enum(['claude', 'codex', 'gemini']).optional().describe('Pack a live agent config instead of a saved profile'),
             output_path: z.string().optional().describe('Output file path (defaults to <name>.tar.gz in cwd)'),
         }),
         execute: async (args) => {
+            if (!args.name && !args.agent) {
+                return JSON.stringify({ error: 'Provide name or agent.' }, null, 2);
+            }
             const exportService = createProfileExportService();
             const result = await exportService.execute({
                 cwd,
-                name: args.name,
+                source: args.agent
+                    ? { source: 'agent', agent: args.agent, cwd }
+                    : { source: 'profile', name: args.name },
                 outputPath: args.output_path,
             });
             return JSON.stringify(result, null, 2);
@@ -307,6 +314,7 @@ export function createMcpServer(options = {}) {
         parameters: z.object({
             archive_path: z.string().describe('Path to the profile tarball'),
             force: z.boolean().default(false).describe('Overwrite existing profile if it exists'),
+            credentials: z.record(z.string(), z.string()).optional().describe('Credential values keyed by placeholder name'),
         }),
         execute: async (args) => {
             const importService = createProfileImportService();
@@ -314,6 +322,7 @@ export function createMcpServer(options = {}) {
                 cwd,
                 archivePath: args.archive_path,
                 force: args.force,
+                credentials: args.credentials,
             });
             return JSON.stringify(result, null, 2);
         },
@@ -321,17 +330,33 @@ export function createMcpServer(options = {}) {
     let uiServerInstance = null;
     server.addTool({
         name: 'brainctl_open_ui',
-        description: 'Start the brainctl web dashboard. Returns the URL to open in a browser. If already running, returns the existing URL.',
+        description: 'Start the brainctl web dashboard and open it in the default browser. Returns the URL. If already running, reopens the existing URL in the browser.',
         parameters: z.object({
             port: z.number().default(3333).describe('Port number for the UI server'),
+            openBrowser: z
+                .boolean()
+                .default(true)
+                .describe('Whether to launch the default browser at the UI URL'),
         }),
         execute: async (args) => {
             if (uiServerInstance) {
-                return JSON.stringify({ url: uiServerInstance.url, status: 'already_running' });
+                if (args.openBrowser)
+                    openInBrowser(uiServerInstance.url);
+                return JSON.stringify({
+                    url: uiServerInstance.url,
+                    status: 'already_running',
+                    browserOpened: args.openBrowser,
+                });
             }
             try {
                 uiServerInstance = await startUiServer({ cwd, port: args.port });
-                return JSON.stringify({ url: uiServerInstance.url, status: 'started' });
+                if (args.openBrowser)
+                    openInBrowser(uiServerInstance.url);
+                return JSON.stringify({
+                    url: uiServerInstance.url,
+                    status: 'started',
+                    browserOpened: args.openBrowser,
+                });
             }
             catch (err) {
                 return JSON.stringify({ error: err.message, status: 'failed' });
@@ -400,3 +425,24 @@ export async function startMcpServer(options = {}) {
     const server = createMcpServer(options);
     await server.start({ transportType: 'stdio' });
 }
+function openInBrowser(url) {
+    const platform = process.platform;
+    const { command, args } = platform === 'darwin'
+        ? { command: 'open', args: [url] }
+        : platform === 'win32'
+            ? { command: 'cmd', args: ['/c', 'start', '""', url] }
+            : { command: 'xdg-open', args: [url] };
+    try {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.on('error', () => {
+            // Browser open is best-effort; swallow errors so the MCP call still succeeds.
+        });
+        child.unref();
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/services/agent-config-service.d.ts

@@ -1,8 +1,9 @@
 import type { AgentName } from '../types.js';
-import { type AgentLiveConfig, type AgentMcpEntry } from './sync/agent-reader.js';
+import { type AgentLiveConfig, type AgentMcpEntry, type PortableRemoteMcpMetadata } from './sync/agent-reader.js';
 import { type McpPreflightService } from './mcp-preflight-service.js';
 import { type SkillPreflightService } from './skill-preflight-service.js';
 export type { AgentLiveConfig, AgentMcpEntry, AgentSkillEntry } from './sync/agent-reader.js';
+export type { PortableRemoteMcpMetadata } from './sync/agent-reader.js';
 export interface AgentConfigService {
     readAll(options: {
         cwd: string;
@@ -11,7 +12,8 @@ export interface AgentConfigService {
         cwd: string;
         agent: AgentName;
         key: string;
-        entry: AgentMcpEntry;
+        entry?: AgentMcpEntry;
+        remoteEntry?: PortableRemoteMcpMetadata;
     }): Promise<void>;
     removeMcp(options: {
         cwd: string;

package/dist/services/agent-config-service.js

@@ -25,25 +25,32 @@ export function createAgentConfigService(dependencies = {}) {
             return results;
         },
         async addMcp(options) {
-            const { cwd, agent, key, entry } = options;
-            const preflight = await mcpPreflightService.execute({ cwd, agent, key, entry });
+            const { cwd, agent, key, entry, remoteEntry } = options;
+            const preflight = await mcpPreflightService.execute({ cwd, agent, key, entry, remoteEntry });
             const firstError = preflight.checks.find((check) => check.status === 'error');
             if (firstError) {
                 throw new ValidationError(`MCP "${key}" cannot be added to ${agent}: ${firstError.message}`);
             }
             if (agent === 'claude') {
                 await mutateClaudeConfig(cwd, (servers) => {
-                    servers[key] = toClaudeEntry(entry);
+                    servers[key] = remoteEntry ? toClaudeRemoteEntry(remoteEntry) : toClaudeEntry(entry);
                 });
             }
             else if (agent === 'codex') {
-                await mutateCodexConfig((servers) => {
-                    servers[key] = entry;
+                await mutateCodexConfig(cwd, (state) => {
+                    delete state.mcpServers[key];
+                    delete state.remoteMcpServers[key];
+                    if (remoteEntry) {
+                        state.remoteMcpServers[key] = remoteEntry;
+                    }
+                    else {
+                        state.mcpServers[key] = entry;
+                    }
                 });
             }
             else if (agent === 'gemini') {
                 await mutateGeminiConfig(cwd, (servers) => {
-                    servers[key] = toGeminiEntry(entry);
+                    servers[key] = remoteEntry ? toGeminiRemoteEntry(remoteEntry) : toGeminiEntry(entry);
                 });
             }
         },
@@ -55,8 +62,9 @@ export function createAgentConfigService(dependencies = {}) {
                 });
             }
             else if (agent === 'codex') {
-                await mutateCodexConfig((servers) => {
-                    delete servers[key];
+                await mutateCodexConfig(cwd, (state) => {
+                    delete state.mcpServers[key];
+                    delete state.remoteMcpServers[key];
                 });
             }
             else if (agent === 'gemini') {
@@ -100,6 +108,11 @@ async function mutateClaudeConfig(cwd, mutate) {
     catch {
         // fresh config
     }
+    // Apply mutation to user-scoped (top-level) MCPs
+    const userServers = (existing.mcpServers ?? {});
+    mutate(userServers);
+    existing.mcpServers = userServers;
+    // Apply mutation to project-scoped MCPs
     const projects = (existing.projects ?? {});
     const projectConfig = projects[cwd] ?? {};
     const servers = (projectConfig.mcpServers ?? {});
@@ -117,8 +130,15 @@ function toClaudeEntry(entry) {
         ...(entry.env ? { env: entry.env } : {}),
     };
 }
+function toClaudeRemoteEntry(entry) {
+    return {
+        type: entry.transport === 'sse' ? 'sse' : 'http',
+        url: entry.url,
+        ...(entry.headers ? { headers: entry.headers } : {}),
+    };
+}
 /* ---- Codex: TOML with [mcp_servers.*] ---- */
-async function mutateCodexConfig(mutate) {
+async function mutateCodexConfig(cwd, mutate) {
     const configPath = path.join(homedir(), '.codex', 'config.toml');
     let existingContent = '';
     try {
@@ -129,12 +149,15 @@ async function mutateCodexConfig(mutate) {
         // fresh config
     }
     // Read current servers via reader
-    const current = await readers.codex.read({ cwd: '' });
-    const servers = { ...current.mcpServers };
-    mutate(servers);
+    const current = await readers.codex.read({ cwd });
+    const state = {
+        mcpServers: { ...current.mcpServers },
+        remoteMcpServers: { ...current.remoteMcpServers },
+    };
+    mutate(state);
     // Rebuild: preserve non-mcp content + new mcp sections
     const nonMcp = stripCodexMcpSections(existingContent).trim();
-    const mcpToml = buildCodexMcpToml(servers);
+    const mcpToml = buildCodexMcpToml(state);
     const final = nonMcp.length > 0 ? `${nonMcp}\n\n${mcpToml}` : mcpToml;
     await mkdir(path.dirname(configPath), { recursive: true });
     await atomicWrite(configPath, final + '\n');
@@ -156,9 +179,9 @@ function stripCodexMcpSections(content) {
     }
     return result.join('\n');
 }
-function buildCodexMcpToml(servers) {
+function buildCodexMcpToml(state) {
     const lines = [];
-    for (const [name, entry] of Object.entries(servers)) {
+    for (const [name, entry] of Object.entries(state.mcpServers)) {
         lines.push(`[mcp_servers.${name}]`);
         lines.push(`command = ${tomlStr(entry.command)}`);
         if (entry.args && entry.args.length > 0) {
@@ -173,6 +196,11 @@ function buildCodexMcpToml(servers) {
         }
         lines.push('');
     }
+    for (const [name, entry] of Object.entries(state.remoteMcpServers)) {
+        lines.push(`[mcp_servers.${name}]`);
+        lines.push(`url = ${tomlStr(entry.url)}`);
+        lines.push('');
+    }
     return lines.join('\n').trim();
 }
 function tomlStr(value) {
@@ -202,6 +230,13 @@ function toGeminiEntry(entry) {
         ...(entry.env ? { env: entry.env } : {}),
     };
 }
+function toGeminiRemoteEntry(entry) {
+    return {
+        ...(entry.transport === 'http' ? { httpUrl: entry.url } : { url: entry.url }),
+        ...(entry.headers ? { headers: entry.headers } : {}),
+        ...(entry.env ? { env: entry.env } : {}),
+    };
+}
 /* ---- Shared helpers ---- */
 async function backupFile(filePath) {
     const backupPath = `${filePath}.bak.${formatTimestamp()}`;

package/dist/services/agent-converter-service.d.ts

@@ -0,0 +1,21 @@
+export interface ParsedClaudeAgent {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export interface ParsedCodexAgent {
+    name: string;
+    description: string;
+    developerInstructions: string;
+    sandboxMode?: string;
+    model?: string;
+    extra: Record<string, unknown>;
+}
+export declare function parseMarkdownWithFrontmatter(source: string): ParsedClaudeAgent;
+export declare function serializeMarkdownWithFrontmatter(frontmatter: Record<string, unknown>, body: string): string;
+export declare function claudeAgentMdToCodexToml(source: string): string;
+export declare function codexAgentTomlToClaudeMd(source: string): string;
+export declare function claudeCommandMdToCodexSkill(source: string): {
+    frontmatter: Record<string, unknown>;
+    skillMarkdown: string;
+};
+export declare function parseCodexAgentToml(source: string): ParsedCodexAgent;

package/dist/services/agent-converter-service.js

@@ -0,0 +1,182 @@
+import YAML from 'yaml';
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+export function parseMarkdownWithFrontmatter(source) {
+    const match = source.match(FRONTMATTER_RE);
+    if (!match) {
+        return { frontmatter: {}, body: source };
+    }
+    const parsed = YAML.parse(match[1]);
+    return {
+        frontmatter: parsed ?? {},
+        body: match[2],
+    };
+}
+export function serializeMarkdownWithFrontmatter(frontmatter, body) {
+    const keys = Object.keys(frontmatter);
+    if (keys.length === 0)
+        return body;
+    const yaml = YAML.stringify(frontmatter).trimEnd();
+    const normalizedBody = body.startsWith('\n') ? body : `\n${body}`;
+    return `---\n${yaml}\n---${normalizedBody}`;
+}
+export function claudeAgentMdToCodexToml(source) {
+    const { frontmatter, body } = parseMarkdownWithFrontmatter(source);
+    const name = String(frontmatter.name ?? '').trim();
+    const description = String(frontmatter.description ?? '').trim();
+    if (!name)
+        throw new Error('Claude agent is missing required "name" frontmatter field.');
+    if (!description)
+        throw new Error('Claude agent is missing required "description" frontmatter field.');
+    const sandboxMode = inferSandboxModeFromClaudeTools(frontmatter.tools);
+    const lines = [];
+    lines.push(`name = ${tomlString(name)}`);
+    lines.push(`description = ${tomlString(description)}`);
+    lines.push(`developer_instructions = ${tomlMultiline(body.trim())}`);
+    if (sandboxMode)
+        lines.push(`sandbox_mode = ${tomlString(sandboxMode)}`);
+    return lines.join('\n') + '\n';
+}
+export function codexAgentTomlToClaudeMd(source) {
+    const parsed = parseCodexAgentToml(source);
+    const frontmatter = {
+        name: parsed.name,
+        description: parsed.description,
+    };
+    if (parsed.sandboxMode) {
+        frontmatter.tools = claudeToolsFromSandboxMode(parsed.sandboxMode);
+    }
+    return serializeMarkdownWithFrontmatter(frontmatter, `\n${parsed.developerInstructions.trim()}\n`);
+}
+export function claudeCommandMdToCodexSkill(source) {
+    const { frontmatter, body } = parseMarkdownWithFrontmatter(source);
+    const description = String(frontmatter.description ?? '').trim();
+    if (!description) {
+        throw new Error('Claude command is missing required "description" frontmatter field.');
+    }
+    const skillFrontmatter = {
+        description,
+    };
+    if (frontmatter['argument-hint']) {
+        skillFrontmatter['argument-hint'] = frontmatter['argument-hint'];
+    }
+    return {
+        frontmatter: skillFrontmatter,
+        skillMarkdown: serializeMarkdownWithFrontmatter(skillFrontmatter, body.startsWith('\n') ? body : `\n${body}`),
+    };
+}
+function inferSandboxModeFromClaudeTools(rawTools) {
+    const tools = normalizeClaudeToolList(rawTools);
+    if (tools.length === 0)
+        return undefined;
+    const mutating = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+    return tools.some((tool) => mutating.has(tool)) ? 'workspace-write' : 'read-only';
+}
+function normalizeClaudeToolList(raw) {
+    if (Array.isArray(raw))
+        return raw.map((item) => String(item).trim()).filter(Boolean);
+    if (typeof raw === 'string') {
+        return raw.split(',').map((item) => item.trim()).filter(Boolean);
+    }
+    return [];
+}
+function claudeToolsFromSandboxMode(sandboxMode) {
+    const readOnlyTools = 'Glob, Grep, LS, Read, NotebookRead, WebFetch, WebSearch';
+    if (sandboxMode === 'read-only')
+        return readOnlyTools;
+    return `${readOnlyTools}, Edit, Write, Bash`;
+}
+export function parseCodexAgentToml(source) {
+    const lines = source.split('\n');
+    const simple = new Map();
+    const extra = {};
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            i++;
+            continue;
+        }
+        if (/^\[/.test(trimmed)) {
+            i++;
+            continue;
+        }
+        const kvMatch = trimmed.match(/^(\w+)\s*=\s*(.+)$/);
+        if (!kvMatch) {
+            i++;
+            continue;
+        }
+        const [, key, rawValue] = kvMatch;
+        if (rawValue.startsWith('"""')) {
+            const { value, nextIndex } = readTomlMultiline(lines, i, rawValue);
+            simple.set(key, value);
+            i = nextIndex;
+            continue;
+        }
+        simple.set(key, parseTomlScalar(rawValue));
+        i++;
+    }
+    const name = simple.get('name');
+    const description = simple.get('description');
+    const developerInstructions = simple.get('developer_instructions');
+    if (!name)
+        throw new Error('Codex agent is missing required "name" field.');
+    if (!description)
+        throw new Error('Codex agent is missing required "description" field.');
+    if (!developerInstructions) {
+        throw new Error('Codex agent is missing required "developer_instructions" field.');
+    }
+    return {
+        name,
+        description,
+        developerInstructions,
+        sandboxMode: simple.get('sandbox_mode'),
+        model: simple.get('model'),
+        extra,
+    };
+}
+function readTomlMultiline(lines, startIndex, firstLine) {
+    const afterOpen = firstLine.slice(3);
+    if (afterOpen.endsWith('"""') && afterOpen.length >= 3) {
+        return { value: unescapeTomlString(afterOpen.slice(0, -3)), nextIndex: startIndex + 1 };
+    }
+    const collected = [];
+    if (afterOpen.length > 0)
+        collected.push(afterOpen);
+    let i = startIndex + 1;
+    while (i < lines.length) {
+        const line = lines[i];
+        const closeIdx = line.indexOf('"""');
+        if (closeIdx === -1) {
+            collected.push(line);
+            i++;
+            continue;
+        }
+        if (closeIdx > 0)
+            collected.push(line.slice(0, closeIdx));
+        return { value: unescapeTomlString(collected.join('\n').replace(/^\n/, '')), nextIndex: i + 1 };
+    }
+    throw new Error('Unterminated TOML multiline string.');
+}
+function parseTomlScalar(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return unescapeTomlString(trimmed.slice(1, -1));
+    }
+    return trimmed;
+}
+function unescapeTomlString(value) {
+    return value
+        .replace(/\\\\/g, '\\')
+        .replace(/\\"/g, '"')
+        .replace(/\\n/g, '\n')
+        .replace(/\\r/g, '\r')
+        .replace(/\\t/g, '\t');
+}
+function tomlString(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function tomlMultiline(value) {
+    const escaped = value.replace(/"""/g, '\\"\\"\\"');
+    return `"""\n${escaped}\n"""`;
+}

package/dist/services/credential-redaction-service.d.ts

@@ -0,0 +1,13 @@
+import type { McpServerConfig, PortableCredentialSpec } from '../types.js';
+export interface CredentialRedactionResult<T extends McpServerConfig> {
+    redacted: T;
+    credentials: PortableCredentialSpec[];
+}
+export declare function redactPortableMcpCredentials<T extends McpServerConfig>(config: T): CredentialRedactionResult<T>;
+interface CredentialAccumulator {
+    key: string;
+    required: true;
+    descriptions: Set<string>;
+}
+export declare function finalizePortableCredentialSpecs(credentialsByKey: Map<string, CredentialAccumulator>): PortableCredentialSpec[];
+export {};

package/dist/services/credential-redaction-service.js

@@ -0,0 +1,89 @@
+export function redactPortableMcpCredentials(config) {
+    const credentialsByKey = new Map();
+    const redactedEnv = redactStringMap(config.env, 'env', credentialsByKey);
+    if (config.kind === 'remote') {
+        const redactedHeaders = redactStringMap(config.headers, 'header', credentialsByKey);
+        return {
+            redacted: {
+                ...config,
+                ...(redactedEnv ? { env: redactedEnv } : {}),
+                ...(redactedHeaders ? { headers: redactedHeaders } : {}),
+            },
+            credentials: finalizePortableCredentialSpecs(credentialsByKey),
+        };
+    }
+    return {
+        redacted: {
+            ...config,
+            ...(redactedEnv ? { env: redactedEnv } : {}),
+        },
+        credentials: finalizePortableCredentialSpecs(credentialsByKey),
+    };
+}
+function redactStringMap(values, source, credentialsByKey) {
+    if (!values) {
+        return undefined;
+    }
+    const redacted = {};
+    for (const [key, value] of Object.entries(values)) {
+        if (!shouldRedact(key)) {
+            redacted[key] = value;
+            continue;
+        }
+        const credentialKey = normalizeCredentialKey(key);
+        addCredentialSpec(credentialsByKey, credentialKey, source, key);
+        redacted[key] = isCredentialPlaceholder(value)
+            ? value
+            : `\${credentials.${credentialKey}}`;
+    }
+    return redacted;
+}
+function shouldRedact(key) {
+    const tokens = tokenizeCredentialKey(key);
+    if (tokens.length === 0) {
+        return false;
+    }
+    return (tokens[tokens.length - 1] === 'authorization' ||
+        tokens[tokens.length - 1] === 'password' ||
+        tokens[tokens.length - 1] === 'secret' ||
+        tokens[tokens.length - 1] === 'token' ||
+        (tokens[tokens.length - 1] === 'key' &&
+            (tokens.includes('api') || (tokens.includes('auth') && tokens.includes('key')))));
+}
+function normalizeCredentialKey(key) {
+    return tokenizeCredentialKey(key).join('_');
+}
+function tokenizeCredentialKey(key) {
+    return key
+        .trim()
+        .replace(/([A-Z]+)([A-Z][a-z0-9])/g, '$1 $2')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/g)
+        .filter(Boolean);
+}
+function isCredentialPlaceholder(value) {
+    return /^\$\{credentials\.[^}]+\}$/.test(value) || /^(Bearer|Token)\s+\$\{credentials\.[^}]+\}$/i.test(value);
+}
+function addCredentialSpec(credentialsByKey, credentialKey, source, originalKey) {
+    const description = source === 'env' ? `Environment variable ${originalKey}` : `Header ${originalKey}`;
+    const existing = credentialsByKey.get(credentialKey);
+    if (existing) {
+        existing.descriptions.add(description);
+        return;
+    }
+    credentialsByKey.set(credentialKey, {
+        key: credentialKey,
+        required: true,
+        descriptions: new Set([description]),
+    });
+}
+export function finalizePortableCredentialSpecs(credentialsByKey) {
+    return Array.from(credentialsByKey.values())
+        .sort((left, right) => left.key.localeCompare(right.key))
+        .map((entry) => ({
+        key: entry.key,
+        required: entry.required,
+        description: `${Array.from(entry.descriptions).sort().join('; ')} required for MCP access`,
+    }));
+}

package/dist/services/credential-resolution-service.d.ts

@@ -0,0 +1,11 @@
+import type { McpServerConfig, PortableCredentialPlaceholder, PortableCredentialSpec } from '../types.js';
+export interface CredentialResolutionResult<T extends McpServerConfig> {
+    resolved: T;
+    missing: PortableCredentialSpec[];
+}
+export declare function resolvePortableMcpCredentials<T extends McpServerConfig>(config: T, options?: {
+    credentials?: Record<string, string>;
+    credentialSpecs?: PortableCredentialSpec[];
+    environment?: Record<string, string | undefined>;
+}): CredentialResolutionResult<T>;
+export declare function toPortableCredentialPlaceholder(key: string): PortableCredentialPlaceholder;

package/dist/services/credential-resolution-service.js

@@ -0,0 +1,69 @@
+export function resolvePortableMcpCredentials(config, options = {}) {
+    const specs = new Map((options.credentialSpecs ?? []).map((spec) => [spec.key, spec]));
+    const missing = new Map();
+    const env = resolveStringMap(config.env, specs, missing, options.credentials, options.environment);
+    if (config.kind === 'remote') {
+        const headers = resolveStringMap(config.headers, specs, missing, options.credentials, options.environment);
+        return {
+            resolved: {
+                ...config,
+                ...(env ? { env } : {}),
+                ...(headers ? { headers } : {}),
+            },
+            missing: Array.from(missing.values()),
+        };
+    }
+    return {
+        resolved: {
+            ...config,
+            ...(env ? { env } : {}),
+        },
+        missing: Array.from(missing.values()),
+    };
+}
+function resolveStringMap(values, specs, missing, credentials, environment) {
+    if (!values) {
+        return undefined;
+    }
+    const resolved = {};
+    for (const [key, value] of Object.entries(values)) {
+        const placeholder = parseCredentialPlaceholder(value);
+        if (!placeholder) {
+            resolved[key] = value;
+            continue;
+        }
+        const resolvedValue = credentials?.[placeholder.key] ?? environment?.[placeholder.key];
+        if (typeof resolvedValue === 'string' && resolvedValue.length > 0) {
+            resolved[key] = placeholder.prefix ? `${placeholder.prefix} ${resolvedValue}` : resolvedValue;
+            continue;
+        }
+        const spec = specs.get(placeholder.key) ?? {
+            key: placeholder.key,
+            required: true,
+            description: `Credential ${placeholder.key} is required`,
+        };
+        if (spec.required) {
+            missing.set(spec.key, spec);
+        }
+        resolved[key] = value;
+    }
+    return resolved;
+}
+function parseCredentialPlaceholder(value) {
+    const bareMatch = value.match(/^\$\{credentials\.([^}]+)\}$/);
+    if (bareMatch) {
+        return { key: bareMatch[1] };
+    }
+    const prefixedMatch = value.match(/^(Bearer|Token)\s+\$\{credentials\.([^}]+)\}$/i);
+    if (prefixedMatch) {
+        const prefix = prefixedMatch[1].toLowerCase() === 'bearer' ? 'Bearer' : 'Token';
+        return {
+            key: prefixedMatch[2],
+            prefix,
+        };
+    }
+    return null;
+}
+export function toPortableCredentialPlaceholder(key) {
+    return `\${credentials.${key}}`;
+}

package/dist/services/mcp-preflight-service.d.ts

@@ -1,5 +1,5 @@
 import type { AgentName } from '../types.js';
-import type { AgentMcpEntry } from './agent-config-service.js';
+import type { AgentMcpEntry, PortableRemoteMcpMetadata } from './agent-config-service.js';
 export interface McpPreflightCheck {
     label: string;
     status: 'ok' | 'warn' | 'error';
@@ -14,7 +14,8 @@ export interface McpPreflightService {
         cwd: string;
         agent: AgentName;
         key: string;
-        entry: AgentMcpEntry;
+        entry?: AgentMcpEntry;
+        remoteEntry?: PortableRemoteMcpMetadata;
     }): Promise<McpPreflightResult>;
 }
 interface McpPreflightDependencies {