@agents-ensemble/core 0.7.0 → 0.9.0

package/dist/conductor/conductor-pi-auth.js

@@ -0,0 +1,656 @@
+import { readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { ModelRegistry, ModelRuntime, } from '@earendil-works/pi-coding-agent';
+import { findEnvKeys, getEnvApiKey, getModels, getProviders, } from '@earendil-works/pi-ai/compat';
+import { loadPiResources, resolvePiResourceRoots, } from './pi-resource-loader.js';
+/** Create the Pi 1.x model runtime and registry for the resolved resource roots. */
+export async function createPiConductorAuthContext(options, resources) {
+    const roots = resolvePiResourceRoots(options);
+    const authPath = join(roots.agentDir, 'auth.json');
+    const modelsPath = join(roots.agentDir, 'models.json');
+    const resolvedResources = resources ?? (await loadPiResources(options));
+    const modelRuntime = await createPiModelRuntime(options, resolvedResources);
+    return {
+        agentDir: roots.agentDir,
+        authPath,
+        modelsPath,
+        modelRuntime,
+        modelRegistry: new ModelRegistry(modelRuntime),
+    };
+}
+/** Resolve the provider used by `ensemble auth` from an explicit/default model. */
+export async function resolvePiConductorProvider(options) {
+    const resources = await loadPiResources(options);
+    const context = await createPiConductorAuthContext(options, resources);
+    return resolvePiConductorProviderFromResources(options, resources, context);
+}
+/** Login to a Pi provider. API-key login persists only in the user auth file. */
+export async function loginPiConductor(options) {
+    const resources = await loadPiResources(options);
+    const context = await createPiConductorAuthContext(options, resources);
+    const provider = await resolveConductorProviderOrThrow(options, resources, context);
+    const oauthProvider = Boolean(context.modelRuntime.getProvider(provider)?.auth.oauth);
+    if (oauthProvider) {
+        if (!options.oauthCallbacks) {
+            throw new Error(`Pi provider "${provider}" uses OAuth. Run this command from a TTY so the OAuth login flow can interact with you.`);
+        }
+        await context.modelRuntime.login(provider, 'oauth', toPiAuthInteraction(options.oauthCallbacks));
+        return {
+            backend: 'pi',
+            provider,
+            method: 'oauth',
+            authPath: context.authPath,
+        };
+    }
+    const apiKey = options.apiKey?.trim();
+    if (!apiKey) {
+        throw new Error(`Pi provider "${provider}" requires an API key. Pass a secret API-key prompt value or set ${formatPiProviderEnvHint(provider)}.`);
+    }
+    await writePiApiKey(context.authPath, provider, apiKey);
+    await context.modelRuntime.setRuntimeApiKey(provider, apiKey);
+    return {
+        backend: 'pi',
+        provider,
+        method: 'api_key',
+        authPath: context.authPath,
+    };
+}
+/** Whether the selected Pi provider exposes Pi's native OAuth login flow. */
+export async function isPiConductorOAuthProvider(options) {
+    const resources = await loadPiResources(options);
+    const context = await createPiConductorAuthContext(options, resources);
+    const provider = await resolveConductorProviderOrThrow(options, resources, context);
+    return Boolean(context.modelRuntime.getProvider(provider)?.auth.oauth);
+}
+/** Remove a Pi provider's user-layer credential. */
+export async function logoutPiConductor(options) {
+    const resources = await loadPiResources(options);
+    const context = await createPiConductorAuthContext(options, resources);
+    const provider = await resolveConductorProviderOrThrow(options, resources, context);
+    await context.modelRuntime.logout(provider);
+    return {
+        backend: 'pi',
+        provider,
+        authPath: context.authPath,
+    };
+}
+/** Return non-secret Pi auth metadata for the selected/default provider. */
+export async function getPiConductorAuthStatus(options) {
+    const resources = await loadPiResources(options);
+    const context = await createPiConductorAuthContext(options, resources);
+    const providers = await resolveStatusProviders(options, resources, context);
+    return {
+        backend: 'pi',
+        authPath: context.authPath,
+        providers: providers.map((provider) => getPiProviderAuthStatus(provider, context, resources, options.env ?? process.env)),
+    };
+}
+/** List only Pi models whose provider has usable configured auth. */
+export async function listPiConductorModels(options = { cwd: process.cwd() }) {
+    const resources = await loadPiResources(options);
+    const context = await createPiConductorAuthContext(options, resources);
+    const requestedProvider = normalizeProvider(options.provider) ?? providerFromModelId(options.modelId);
+    const entries = new Map();
+    // Filter the complete Pi 1.x runtime catalog through the merged
+    // project-over-user auth view before listing models.
+    for (const model of context.modelRegistry.getAll()) {
+        if (requestedProvider && model.provider !== requestedProvider)
+            continue;
+        if (!hasPiProviderAuth(model.provider, context, resources, options.env ?? process.env)) {
+            continue;
+        }
+        addPiModelEntry(entries, model);
+    }
+    // The runtime is built from the merged models resource, so custom models are
+    // already included in the registry above.
+    const result = [...entries.values()].sort((left, right) => left.id.localeCompare(right.id));
+    if (result.length === 0) {
+        const providerHint = requestedProvider ? ` for provider "${requestedProvider}"` : '';
+        throw new Error(`No authenticated Pi models are available${providerHint}. ` +
+            `Run ensemble auth login --provider <provider>, set provider credentials in ${context.agentDir}, ` +
+            'or configure a provider environment variable.');
+    }
+    return result;
+}
+/** Resolve a key while retaining project-over-user auth precedence. */
+export async function resolvePiConductorApiKey(options) {
+    const env = options.env ?? process.env;
+    if (options.explicitApiKey !== undefined)
+        return options.explicitApiKey;
+    // A project auth file intentionally remains above the user auth layer. When
+    // both roots point at the same file, ModelRuntime is the canonical reader so
+    // OAuth refresh is not bypassed by the resource-layer compatibility parser.
+    if (options.resources.roots.agentDir !== options.resources.roots.projectDir) {
+        const projectEntry = options.resources.authLayers.at(-1)?.[options.provider];
+        if (isPiOAuthAuthEntry(projectEntry)) {
+            throw new Error(formatProjectOAuthAuthError(options.provider));
+        }
+        const projectKey = resolvePiAuthEntry(projectEntry, env);
+        if (projectKey !== undefined)
+            return projectKey;
+    }
+    // ModelRuntime owns the Pi 1.x credential store, OAuth refresh, and locking.
+    // Resolve it on every request instead of capturing the key at construction.
+    try {
+        const runtimeAuth = await options.modelRuntime.getAuth(options.provider);
+        if (runtimeAuth?.auth.apiKey !== undefined)
+            return runtimeAuth.auth.apiKey;
+    }
+    catch {
+        // A models.json command or environment reference can be unavailable in
+        // the injected environment. Continue through the ensemble fallback chain
+        // so its resolved map remains authoritative for this request.
+    }
+    const settingsKey = resolvePiSettingsApiKey(options.resources.settings, options.provider, env);
+    if (settingsKey !== undefined)
+        return settingsKey;
+    const modelsKey = resolvePiModelsApiKey(options.resources.models.providers[options.provider], env);
+    if (modelsKey !== undefined)
+        return modelsKey;
+    return getEnvApiKey(options.provider, toProviderEnv(env));
+}
+/** Return whether a provider has configured auth without exposing its value. */
+export function hasPiProviderAuth(provider, context, resources, env = process.env) {
+    const status = getPiProviderAuthStatus(provider, context, resources, env);
+    return status.configured;
+}
+/** Synchronous readiness check used by CLI/e2e guards before async loading. */
+export function hasPiConductorAuth(options) {
+    const env = options.env ?? process.env;
+    const roots = resolvePiResourceRoots(options);
+    const userAuth = readPiJsonSync(join(roots.agentDir, 'auth.json'));
+    const projectAuth = readPiJsonSync(join(roots.projectDir, 'auth.json'));
+    const settings = readPiSettingsSync(roots);
+    const models = readPiModelsSync(roots);
+    const selection = resolvePiConductorSelectionSync(options, settings, models, userAuth);
+    if (selection.provider) {
+        return hasPiProviderAuthSync({
+            provider: selection.provider,
+            roots,
+            userAuth,
+            projectAuth,
+            settings,
+            models,
+            env,
+        });
+    }
+    // A configured model that cannot be mapped to one provider is not a
+    // usable conductor selection, even if another provider happens to have
+    // credentials.
+    if (selection.modelId)
+        return false;
+    return hasAnyPiConductorAuthSync({
+        roots,
+        userAuth,
+        projectAuth,
+        settings,
+        models,
+        env,
+    });
+}
+/**
+ * Mirror PiConductorAgent's synchronous provider/model selection for guards.
+ * The async agent receives the same merged settings and model layers.
+ */
+function resolvePiConductorSelectionSync(options, settings, models, userAuth) {
+    const requestedModel = normalizeModelId(options.modelId);
+    const configuredModel = normalizeModelId(firstString(settings.defaultModel, settings.model, settings.modelId));
+    const selectedModel = requestedModel ?? configuredModel;
+    let provider = normalizeProvider(options.provider);
+    let modelId = selectedModel;
+    if (selectedModel?.includes('/')) {
+        const separator = selectedModel.indexOf('/');
+        if (!provider) {
+            provider = normalizeProvider(selectedModel.slice(0, separator));
+        }
+        modelId = normalizeModelId(selectedModel.slice(separator + 1));
+    }
+    if (!provider)
+        provider = normalizeProvider(settings.defaultProvider);
+    if (!provider && modelId) {
+        const matches = new Set();
+        for (const model of knownPiModelsSync(models, userAuth)) {
+            if (model.id === modelId)
+                matches.add(model.provider);
+        }
+        for (const [candidate, config] of Object.entries(models.providers)) {
+            if (config.models?.some((model) => model.id === modelId)) {
+                matches.add(candidate);
+            }
+        }
+        if (matches.size === 1)
+            provider = [...matches][0];
+    }
+    return {
+        ...(provider ? { provider } : {}),
+        ...(modelId ? { modelId } : {}),
+    };
+}
+function hasPiProviderAuthSync(options) {
+    const projectEntry = options.projectAuth?.[options.provider];
+    if (options.roots.agentDir !== options.roots.projectDir &&
+        isPiOAuthAuthEntry(projectEntry)) {
+        return false;
+    }
+    if (resolvePiAuthEntry(projectEntry, options.env) !== undefined)
+        return true;
+    if (resolvePiAuthEntry(options.userAuth?.[options.provider], options.env) !== undefined) {
+        return true;
+    }
+    if (resolvePiSettingsApiKey(options.settings, options.provider, options.env) !== undefined) {
+        return true;
+    }
+    if (resolvePiModelsApiKey(options.models.providers[options.provider], options.env) !== undefined) {
+        return true;
+    }
+    return getEnvApiKey(options.provider, toProviderEnv(options.env)) !== undefined;
+}
+function hasAnyPiConductorAuthSync(options) {
+    const providers = new Set([
+        ...Object.keys(options.userAuth ?? {}),
+        ...knownPiModelsSync(options.models, options.userAuth).map((model) => model.provider),
+        ...Object.keys(options.models.providers),
+        ...Object.keys(options.projectAuth ?? {}),
+        ...getProviders(),
+    ]);
+    for (const provider of providers) {
+        if (hasPiProviderAuthSync({ ...options, provider }))
+            return true;
+    }
+    if (typeof options.settings.apiKey === 'string' ||
+        (isRecord(options.settings.apiKeys) &&
+            Object.values(options.settings.apiKeys).some((entry) => typeof entry === 'string'))) {
+        return true;
+    }
+    return false;
+}
+function readPiSettingsSync(roots) {
+    return mergePiRecords(readPiJsonSync(join(roots.agentDir, 'settings.json')) ?? {}, readPiJsonSync(join(roots.projectDir, 'settings.json')) ?? {});
+}
+function readPiModelsSync(roots) {
+    const merged = mergePiRecords(readPiJsonSync(join(roots.agentDir, 'models.json')) ?? {}, readPiJsonSync(join(roots.projectDir, 'models.json')) ?? {});
+    return {
+        providers: isRecord(merged.providers)
+            ? merged.providers
+            : {},
+    };
+}
+async function resolveConductorProviderOrThrow(options, resources, context) {
+    const provider = resolvePiConductorProviderFromResources(options, resources, context);
+    if (provider)
+        return provider;
+    throw new Error(`Pi provider is not configured. Set defaultProvider in ${join(context.agentDir, 'settings.json')} or pass --provider <id>.`);
+}
+function resolvePiConductorProviderFromResources(options, resources, context) {
+    const explicit = normalizeProvider(options.provider);
+    if (explicit)
+        return explicit;
+    const requestedModel = normalizeModelId(options.modelId);
+    const configuredModel = normalizeModelId(firstString(resources.settings.defaultModel, resources.settings.model, resources.settings.modelId));
+    const selectedModel = requestedModel ?? configuredModel;
+    if (selectedModel?.includes('/')) {
+        return selectedModel.slice(0, selectedModel.indexOf('/'));
+    }
+    const configuredProvider = normalizeProvider(resources.settings.defaultProvider);
+    if (configuredProvider)
+        return configuredProvider;
+    if (selectedModel) {
+        const matches = new Set();
+        for (const model of context.modelRegistry.getAll()) {
+            if (model.id === selectedModel)
+                matches.add(model.provider);
+        }
+        for (const [provider, config] of Object.entries(resources.models.providers)) {
+            if (config.models?.some((model) => model.id === selectedModel)) {
+                matches.add(provider);
+            }
+        }
+        if (matches.size === 1)
+            return [...matches][0];
+    }
+    return '';
+}
+async function resolveStatusProviders(options, resources, context) {
+    const explicit = normalizeProvider(options.provider);
+    if (explicit)
+        return [explicit];
+    const configured = resolvePiConductorProviderFromResources(options, resources, context);
+    if (configured)
+        return [configured];
+    const providers = new Set([
+        ...(await context.modelRuntime.listCredentials()).map((entry) => entry.providerId),
+        ...context.modelRegistry.getAll().map((model) => model.provider),
+        ...Object.keys(resources.models.providers),
+    ]);
+    return [...providers].sort();
+}
+function getPiProviderAuthStatus(provider, context, resources, env) {
+    if (resources.roots.agentDir !== resources.roots.projectDir) {
+        const projectEntry = resources.authLayers.at(-1)?.[provider];
+        if (isPiOAuthAuthEntry(projectEntry)) {
+            return {
+                provider,
+                configured: false,
+                source: 'project_oauth_unsupported',
+            };
+        }
+        const projectKey = resolvePiAuthEntry(projectEntry, env);
+        if (projectKey !== undefined) {
+            return { provider, configured: true, source: 'project_stored' };
+        }
+    }
+    const registryStatus = context.modelRuntime.getProviderAuthStatus(provider);
+    if (registryStatus.configured || registryStatus.source === 'stored') {
+        return normalizePiAuthStatus(provider, registryStatus, true);
+    }
+    const settingsKey = resolvePiSettingsApiKey(resources.settings, provider, env);
+    if (settingsKey !== undefined) {
+        return { provider, configured: true, source: 'settings_json' };
+    }
+    const modelsKey = resolvePiModelsApiKey(resources.models.providers[provider], env);
+    if (modelsKey !== undefined) {
+        return { provider, configured: true, source: 'models_json_key' };
+    }
+    const envKey = getEnvApiKey(provider, toProviderEnv(env));
+    if (envKey !== undefined) {
+        return {
+            provider,
+            configured: true,
+            source: 'environment',
+            label: formatPiProviderEnvHint(provider),
+        };
+    }
+    return normalizePiAuthStatus(provider, registryStatus, false);
+}
+function normalizePiAuthStatus(provider, status, configured) {
+    return {
+        provider,
+        configured,
+        ...(status.source ? { source: status.source } : {}),
+        ...(status.label ? { label: status.label } : {}),
+    };
+}
+function addPiModelEntry(entries, model) {
+    const id = `${model.provider}/${model.id}`;
+    entries.set(id, {
+        id,
+        displayName: model.name || model.id,
+        provider: model.provider,
+    });
+}
+function addPiCustomModelEntry(entries, provider, model) {
+    const id = `${provider}/${model.id}`;
+    entries.set(id, {
+        id,
+        displayName: model.name ?? model.id,
+        provider,
+    });
+}
+function resolvePiAuthEntry(entry, env) {
+    if (typeof entry === 'string')
+        return expandEnvReference(entry, env);
+    if (!isRecord(entry))
+        return undefined;
+    if (isPiOAuthAuthEntry(entry))
+        return undefined;
+    for (const key of ['key', 'apiKey', 'token', 'accessToken', 'access']) {
+        const value = entry[key];
+        if (typeof value === 'string')
+            return expandEnvReference(value, env);
+    }
+    return undefined;
+}
+function isPiOAuthAuthEntry(entry) {
+    return isRecord(entry) && entry.type === 'oauth';
+}
+function formatProjectOAuthAuthError(provider) {
+    return (`Project Pi OAuth credentials for provider "${provider}" are not supported in ` +
+        'project .ensemble/pi/auth.json because that layer cannot refresh them safely. ' +
+        `Run ensemble auth login --provider ${provider} to store the credential in the user Pi runtime.`);
+}
+function resolvePiSettingsApiKey(settings, provider, env) {
+    if (typeof settings.apiKey === 'string') {
+        return expandEnvReference(settings.apiKey, env);
+    }
+    if (!isRecord(settings.apiKeys))
+        return undefined;
+    const value = settings.apiKeys[provider];
+    return typeof value === 'string' ? expandEnvReference(value, env) : undefined;
+}
+function resolvePiModelsApiKey(providerConfig, env) {
+    return providerConfig?.apiKey
+        ? expandEnvReference(providerConfig.apiKey, env)
+        : undefined;
+}
+function expandEnvReference(value, env) {
+    if (value.startsWith('!'))
+        return undefined;
+    const variable = /^\$\{([^}]+)\}$/.exec(value) ?? /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(value);
+    return variable ? env[variable[1]] : value;
+}
+function toProviderEnv(env) {
+    return Object.fromEntries(Object.entries(env).filter((entry) => typeof entry[1] === 'string'));
+}
+/** Build the Pi 1.x runtime from the already-resolved ensemble resource view. */
+async function createPiModelRuntime(options, resources) {
+    const roots = resolvePiResourceRoots(options);
+    const runtime = await ModelRuntime.create({
+        authPath: join(roots.agentDir, 'auth.json'),
+        // The ensemble resource loader has already merged user and project models.
+        // Avoid letting ModelRuntime read an unmerged second view of models.json.
+        modelsPath: null,
+        allowModelNetwork: false,
+        refreshOnCreate: false,
+    });
+    const env = options.env ?? process.env;
+    for (const [provider, config] of Object.entries(resources.models.providers)) {
+        runtime.registerProvider(provider, toPiRuntimeProviderConfig(config, env));
+    }
+    if (roots.agentDir !== roots.projectDir) {
+        for (const [provider, entry] of Object.entries(resources.authLayers.at(-1) ?? {})) {
+            if (isPiOAuthAuthEntry(entry))
+                continue;
+            const key = resolvePiAuthEntry(entry, env);
+            if (key !== undefined)
+                await runtime.setRuntimeApiKey(provider, key);
+        }
+    }
+    if (isRecord(resources.settings.apiKeys)) {
+        for (const [provider, value] of Object.entries(resources.settings.apiKeys)) {
+            if (typeof value !== 'string')
+                continue;
+            const key = expandEnvReference(value, env);
+            if (key !== undefined)
+                await runtime.setRuntimeApiKey(provider, key);
+        }
+    }
+    await runtime.refresh({ allowNetwork: false });
+    return runtime;
+}
+function toPiRuntimeProviderConfig(config, env) {
+    const models = config.models?.map((model) => ({
+        type: 'chat',
+        id: model.id,
+        name: model.name ?? model.id,
+        ...(model.api ?? config.api ? { api: model.api ?? config.api } : {}),
+        ...(model.baseUrl ?? config.baseUrl
+            ? { baseUrl: model.baseUrl ?? config.baseUrl }
+            : {}),
+        input: model.input ?? ['text'],
+        reasoning: model.reasoning ?? false,
+        ...(model.thinkingLevelMap ? { thinkingLevelMap: model.thinkingLevelMap } : {}),
+        cost: model.cost ?? emptyPiModelCost(),
+        contextWindow: model.contextWindow ?? 128000,
+        maxTokens: model.maxTokens ?? 16384,
+        ...(model.headers ? { headers: model.headers } : {}),
+        ...(model.compat ? { compat: model.compat } : {}),
+    }));
+    return {
+        ...(config.name ? { name: config.name } : {}),
+        ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
+        ...(config.apiKey
+            ? { apiKey: expandEnvReference(config.apiKey, env) ?? undefined }
+            : {}),
+        ...(config.api ? { api: config.api } : {}),
+        ...(config.headers ? { headers: config.headers } : {}),
+        ...(config.authHeader !== undefined ? { authHeader: config.authHeader } : {}),
+        ...(models ? { models } : {}),
+    };
+}
+async function writePiApiKey(authPath, provider, apiKey) {
+    await mkdir(dirname(authPath), { recursive: true });
+    let auth = {};
+    try {
+        const parsed = JSON.parse(await readFile(authPath, 'utf8'));
+        if (isRecord(parsed))
+            auth = parsed;
+    }
+    catch (error) {
+        if (!isRecord(error) || error.code !== 'ENOENT')
+            throw error;
+    }
+    auth[provider] = { type: 'api_key', key: apiKey };
+    await writeFile(authPath, `${JSON.stringify(auth, null, 2)}\n`, 'utf8');
+}
+function toPiAuthInteraction(callbacks) {
+    return {
+        signal: callbacks.signal,
+        prompt: async (prompt) => {
+            if (prompt.type === 'select') {
+                const selected = await callbacks.onSelect({
+                    message: prompt.message,
+                    options: prompt.options.map((option) => ({
+                        id: option.id,
+                        label: option.label,
+                    })),
+                });
+                if (selected === undefined)
+                    throw new Error('OAuth login was cancelled.');
+                return selected;
+            }
+            if (prompt.type === 'manual_code' && callbacks.onManualCodeInput) {
+                return callbacks.onManualCodeInput();
+            }
+            return callbacks.onPrompt({
+                message: prompt.message,
+                ...(prompt.placeholder ? { placeholder: prompt.placeholder } : {}),
+            });
+        },
+        notify: (event) => {
+            if (event.type === 'auth_url') {
+                callbacks.onAuth({ url: event.url, instructions: event.instructions });
+            }
+            else if (event.type === 'device_code') {
+                callbacks.onDeviceCode({
+                    userCode: event.userCode,
+                    verificationUri: event.verificationUri,
+                    ...(event.intervalSeconds !== undefined
+                        ? { intervalSeconds: event.intervalSeconds }
+                        : {}),
+                    ...(event.expiresInSeconds !== undefined
+                        ? { expiresInSeconds: event.expiresInSeconds }
+                        : {}),
+                });
+            }
+            else if (callbacks.onProgress) {
+                callbacks.onProgress(event.message);
+            }
+        },
+    };
+}
+function knownPiModelsSync(models, _userAuth) {
+    const result = [];
+    for (const provider of getProviders()) {
+        try {
+            for (const model of getModels(provider) ?? [])
+                result.push(model);
+        }
+        catch {
+            // A static provider catalog failure must not make the sync auth guard fail.
+        }
+    }
+    for (const [provider, config] of Object.entries(models.providers)) {
+        for (const model of config.models ?? []) {
+            result.push({ provider, id: model.id, name: model.name });
+        }
+    }
+    return result;
+}
+function emptyPiModelCost() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+}
+function normalizeProvider(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized && normalized !== 'default' && normalized !== 'auto'
+        ? normalized
+        : undefined;
+}
+function normalizeModelId(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized && normalized !== 'default' && normalized !== 'auto'
+        ? normalized
+        : undefined;
+}
+function providerFromModelId(value) {
+    const modelId = normalizeModelId(value);
+    if (!modelId?.includes('/'))
+        return undefined;
+    return normalizeProvider(modelId.slice(0, modelId.indexOf('/')));
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value !== 'string')
+            continue;
+        const normalized = value.trim();
+        if (normalized && normalized !== 'default' && normalized !== 'auto')
+            return normalized;
+    }
+    return undefined;
+}
+/** Return the concrete environment variables recognised by Pi for a provider. */
+export function formatPiProviderEnvHint(provider) {
+    // `findEnvKeys` normally reports only variables that are currently set. A
+    // truthy probe lets the SDK expose its existing provider mapping even for a
+    // missing credential, which is the case where this recovery hint is used.
+    const envKeys = findEnvKeys(provider, PI_ENV_HINT_PROBE);
+    if (envKeys)
+        return envKeys.join(' / ');
+    if (provider === 'google-vertex') {
+        return 'GOOGLE_APPLICATION_CREDENTIALS / GOOGLE_CLOUD_PROJECT / GOOGLE_CLOUD_LOCATION';
+    }
+    if (provider === 'amazon-bedrock') {
+        return ('AWS_PROFILE / AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY / ' +
+            'AWS_BEARER_TOKEN_BEDROCK');
+    }
+    return `${provider.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_API_KEY`;
+}
+const PI_ENV_HINT_PROBE = new Proxy({}, { get: (_target, property) => (typeof property === 'string' ? 'configured' : undefined) });
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function readPiJsonSync(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, 'utf8'));
+        return isRecord(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function mergePiRecords(base, override) {
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        const previous = merged[key];
+        merged[key] =
+            isRecord(previous) && isRecord(value)
+                ? mergePiRecords(previous, value)
+                : value;
+    }
+    return merged;
+}
+//# sourceMappingURL=conductor-pi-auth.js.map