@agents-ensemble/core 0.20.0 → 0.22.0

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

@@ -1,17 +1,23 @@
+import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { chmod, lstat, mkdir, open, readFile, rename, unlink, } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
 import { ModelRegistry, ModelRuntime, SettingsManager, } 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';
+import { withPiUserRootLock } from './pi-user-root-lock.js';
+import { canonicalPath, getProjectWriteBoundaryPaths, isPathWithin, isPathWithinAnyRoot, } from './conductor-path-safety.js';
+import { loadPiResources, readPiSettingsFile, resolvePiResourceRoots, } from './pi-resource-loader.js';
 import { getPiHeadlessSetting } from './pi-headless-settings.js';
 /** Create the Pi 1.x model runtime and registry for the resolved resource roots. */
 export async function createPiConductorAuthContext(options, resources) {
+    return createPiConductorAuthContextWithAuthPath(options, resources);
+}
+async function createPiConductorAuthContextWithAuthPath(options, resources, runtimeAuthPath) {
     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);
+    const modelRuntime = await createPiModelRuntime(options, resolvedResources, runtimeAuthPath ?? authPath);
     return {
         agentDir: roots.agentDir,
         authPath,
@@ -28,18 +34,58 @@ export async function resolvePiConductorProvider(options) {
 }
 /** Login to a Pi provider. API-key login persists only in the user auth file. */
 export async function loginPiConductor(options) {
+    const roots = resolvePiResourceRoots(options);
+    const authPath = join(roots.agentDir, 'auth.json');
+    const getProtectedProjectRoots = () => getProjectWriteBoundaryPaths(options.cwd, [roots.projectDir]);
+    const protectedProjectRoots = await getProtectedProjectRoots();
+    const runtimeAuthPath = await resolveSafePiUserAuthPath(authPath, protectedProjectRoots);
     const resources = await loadPiResources(options);
-    const context = await createPiConductorAuthContext(options, resources);
+    const context = await createPiConductorAuthContextWithAuthPath(options, resources, runtimeAuthPath);
     const provider = await resolveConductorProviderOrThrow(options, resources, context);
     const oauthProvider = Boolean(context.modelRuntime.getProvider(provider)?.auth.oauth);
-    if (oauthProvider) {
+    if (oauthProvider && options.apiKey === undefined) {
         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.`);
         }
-        const roots = resolvePiResourceRoots(options);
-        await context.modelRuntime.login(provider, 'oauth', toPiAuthInteraction(options.oauthCallbacks), {
-            getDeviceId: () => SettingsManager.create(options.cwd, roots.agentDir).getOrCreateDeviceId(),
-        });
+        // Pi 1.2.0's OpenAI ChatGPT OAuth is the only built-in flow that requests
+        // a device ID. Other providers must not depend on user settings being writable.
+        const requiresDeviceId = provider === 'openai';
+        const settingsPath = join(roots.agentDir, 'settings.json');
+        let loginOptions;
+        if (requiresDeviceId) {
+            const deviceId = await withPiUserRootLock(roots.agentDir, options.cwd, [roots.projectDir], async () => {
+                // The hardlink split is a settings write too; keep it in the same
+                // read/create/persist transaction as the device ID.
+                await ensurePiUserSettingsSafeForOAuth(settingsPath, await getProtectedProjectRoots());
+                const securedAuthPath = await ensurePrivatePiUserAuthFile(context.authPath, await getProtectedProjectRoots());
+                if (securedAuthPath !== runtimeAuthPath) {
+                    throw new Error('Pi user auth.json target changed while preparing OAuth login; no credentials were written. Retry login after checking the auth.json symlink.');
+                }
+                const settingsManager = SettingsManager.create(options.cwd, roots.agentDir);
+                const deviceId = settingsManager.getOrCreateDeviceId();
+                await settingsManager.flush();
+                const settingsErrors = settingsManager
+                    .drainErrors()
+                    .filter(({ scope }) => scope === 'global');
+                if (settingsErrors.length > 0) {
+                    const details = settingsErrors
+                        .map(({ error }) => error.message)
+                        .join('; ');
+                    throw new Error(`Failed to persist the Pi OAuth device ID to user settings.json; OAuth login was not started: ${details}`);
+                }
+                return deviceId;
+            });
+            loginOptions = {
+                getDeviceId: () => deviceId,
+            };
+        }
+        else {
+            const securedAuthPath = await ensurePrivatePiUserAuthFile(context.authPath, await getProtectedProjectRoots());
+            if (securedAuthPath !== runtimeAuthPath) {
+                throw new Error('Pi user auth.json target changed while preparing OAuth login; no credentials were written. Retry login after checking the auth.json symlink.');
+            }
+        }
+        await context.modelRuntime.login(provider, 'oauth', toPiAuthInteraction(options.oauthCallbacks), loginOptions);
         return {
             backend: 'pi',
             provider,
@@ -49,9 +95,9 @@ export async function loginPiConductor(options) {
     }
     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)}.`);
+        throw new Error(`Pi provider "${provider}" requires an API key. Use --api-key-prompt from a TTY or --api-key-stdin with piped input to store one, or set ${formatPiProviderEnvHint(provider)} for request-time authentication.`);
     }
-    await writePiApiKey(context.authPath, provider, apiKey);
+    await writePiApiKey(context.authPath, await getProtectedProjectRoots(), provider, apiKey);
     await context.modelRuntime.setRuntimeApiKey(provider, apiKey);
     return {
         backend: 'pi',
@@ -69,9 +115,19 @@ export async function isPiConductorOAuthProvider(options) {
 }
 /** Remove a Pi provider's user-layer credential. */
 export async function logoutPiConductor(options) {
+    const roots = resolvePiResourceRoots(options);
+    const authPath = join(roots.agentDir, 'auth.json');
+    const protectedProjectRoots = await getProjectWriteBoundaryPaths(options.cwd, [
+        roots.projectDir,
+    ]);
+    const runtimeAuthPath = await resolveSafePiUserAuthPath(authPath, protectedProjectRoots);
     const resources = await loadPiResources(options);
-    const context = await createPiConductorAuthContext(options, resources);
+    const context = await createPiConductorAuthContextWithAuthPath(options, resources, runtimeAuthPath);
     const provider = await resolveConductorProviderOrThrow(options, resources, context);
+    const securedAuthPath = await ensurePrivatePiUserAuthFile(context.authPath, await getProjectWriteBoundaryPaths(options.cwd, [roots.projectDir]));
+    if (securedAuthPath !== runtimeAuthPath) {
+        throw new Error('Pi user auth.json target changed while preparing logout; no credentials were written. Retry after checking the auth.json symlink.');
+    }
     await context.modelRuntime.logout(provider);
     return {
         backend: 'pi',
@@ -79,6 +135,82 @@ export async function logoutPiConductor(options) {
         authPath: context.authPath,
     };
 }
+/** Register a Pi `!command` in the selected settings.json apiKeys entry. */
+export async function setPiConductorCommandAuth(options) {
+    const provider = requireCommandAuthProvider(options.provider);
+    validatePiCommandCredential(options.command);
+    const target = requireCommandAuthTarget(options.target);
+    const roots = resolvePiResourceRoots(options);
+    const settingsPath = join(target === 'project' ? roots.projectDir : roots.agentDir, 'settings.json');
+    const userSettingsPath = join(roots.agentDir, 'settings.json');
+    const projectSettingsPath = join(roots.projectDir, 'settings.json');
+    const [userSettings, projectSettings] = await Promise.all([
+        readPiSettingsFile(userSettingsPath),
+        roots.agentDir === roots.projectDir
+            ? Promise.resolve(undefined)
+            : readPiSettingsFile(projectSettingsPath),
+    ]);
+    const effectiveScalarApiKey = projectSettings !== undefined &&
+        Object.prototype.hasOwnProperty.call(projectSettings, 'apiKey')
+        ? projectSettings.apiKey
+        : userSettings.apiKey;
+    if (typeof effectiveScalarApiKey === 'string') {
+        throw new Error('Pi settings apiKey takes precedence over apiKeys[provider]; remove or change the scalar setting before registering a provider command.');
+    }
+    if (target === 'user' &&
+        roots.agentDir !== roots.projectDir &&
+        isRecord(projectSettings?.apiKeys) &&
+        Object.prototype.hasOwnProperty.call(projectSettings.apiKeys, provider)) {
+        throw new Error('Project Pi settings already define apiKeys for this provider; use --target project to update that entry.');
+    }
+    if (target === 'user') {
+        const protectedProjectRoots = await getProjectWriteBoundaryPaths(options.cwd, [roots.projectDir]);
+        if (await isPathWithinAnyRoot(settingsPath, protectedProjectRoots)) {
+            throw new Error('Refusing to write user Pi settings.json inside a project-owned resource.');
+        }
+        await mkdir(roots.agentDir, { recursive: true, mode: 0o700 });
+        await withPiUserRootLock(roots.agentDir, options.cwd, [roots.projectDir], async () => {
+            const currentProjectRoots = await getProjectWriteBoundaryPaths(options.cwd, [roots.projectDir]);
+            const targetPath = await resolveSafePiUserSettingsPath(settingsPath, currentProjectRoots);
+            await writePiSettingsCommand(targetPath, provider, options.command);
+        });
+    }
+    else {
+        await mkdir(roots.projectDir, { recursive: true });
+        const targetPath = await resolveSafePiProjectSettingsPath(settingsPath, roots.projectDir);
+        await writePiSettingsCommand(targetPath, provider, options.command);
+    }
+    return { backend: 'pi', provider, target, settingsPath };
+}
+/** Remove only a command value from the selected settings.json apiKeys entry. */
+export async function clearPiConductorCommandAuth(options) {
+    const provider = requireCommandAuthProvider(options.provider);
+    const target = requireCommandAuthTarget(options.target);
+    const roots = resolvePiResourceRoots(options);
+    const targetRoot = target === 'project' ? roots.projectDir : roots.agentDir;
+    const settingsPath = join(targetRoot, 'settings.json');
+    if (target === 'user') {
+        const protectedProjectRoots = await getProjectWriteBoundaryPaths(options.cwd, [roots.projectDir]);
+        if (await isPathWithinAnyRoot(settingsPath, protectedProjectRoots)) {
+            throw new Error('Refusing to update user Pi settings.json inside a project-owned resource.');
+        }
+        if (!(await pathExists(roots.agentDir))) {
+            return { backend: 'pi', provider, target, settingsPath, cleared: false };
+        }
+        const cleared = await withPiUserRootLock(roots.agentDir, options.cwd, [roots.projectDir], async () => {
+            const currentProjectRoots = await getProjectWriteBoundaryPaths(options.cwd, [roots.projectDir]);
+            const targetPath = await resolveSafePiUserSettingsPath(settingsPath, currentProjectRoots);
+            return clearPiSettingsCommand(targetPath, provider);
+        });
+        return { backend: 'pi', provider, target, settingsPath, cleared };
+    }
+    if (!(await pathExists(roots.projectDir))) {
+        return { backend: 'pi', provider, target, settingsPath, cleared: false };
+    }
+    const targetPath = await resolveSafePiProjectSettingsPath(settingsPath, roots.projectDir);
+    const cleared = await clearPiSettingsCommand(targetPath, provider);
+    return { backend: 'pi', provider, target, settingsPath, cleared };
+}
 /** Return non-secret Pi auth metadata for the selected/default provider. */
 export async function getPiConductorAuthStatus(options) {
     const resources = await loadPiResources(options);
@@ -153,23 +285,27 @@ export async function resolvePiConductorApiKey(options) {
     if (settingsKey !== undefined && isPiCommandConfigValue(settingsKey)) {
         options.modelRuntime.registerProvider(options.provider, { apiKey: settingsKey });
     }
+    else if (modelsKey !== undefined && isPiCommandConfigValue(modelsKey)) {
+        // models.json command providers are deliberately not registered while a
+        // conductor session is being assembled: ModelRuntime.refresh() checks
+        // provider auth and can execute their command. Register the selected value
+        // only when the request path asks for its credential.
+        options.modelRuntime.registerProvider(options.provider, { apiKey: modelsKey });
+    }
     // ModelRuntime owns the Pi 1.x credential store, OAuth refresh, and locking.
     // Resolve it on every request instead of capturing the key at construction.
-    let runtimeError;
     try {
         const runtimeAuth = await options.modelRuntime.getAuth(options.provider);
         if (runtimeAuth?.auth.apiKey !== undefined)
             return runtimeAuth.auth.apiKey;
     }
-    catch (error) {
-        runtimeError = error;
+    catch {
         // Non-command references can still use the ensemble fallback chain. A
-        // command reference is reported below instead of returning the raw command
-        // as an API key.
+        // command reference is reported below without preserving the raw error.
     }
     const commandKey = [settingsKey, modelsKey].find((value) => value !== undefined && isPiCommandConfigValue(value));
     if (commandKey !== undefined) {
-        throw formatPiCommandResolutionError(options.provider, commandKey, runtimeError);
+        throw formatPiCommandResolutionError();
     }
     if (settingsKey !== undefined)
         return settingsKey;
@@ -177,6 +313,54 @@ export async function resolvePiConductorApiKey(options) {
         return modelsKey;
     return getEnvApiKey(options.provider, toProviderEnv(env));
 }
+/** Prepare configured Pi commands when a provider request asks ModelRuntime for auth. */
+export async function preparePiConductorCommandAuthForRequest(options) {
+    const env = options.env ?? process.env;
+    const projectEntry = options.resources.authLayers.at(-1)?.[options.provider];
+    const projectKey = options.resources.roots.agentDir !== options.resources.roots.projectDir
+        ? resolvePiAuthEntry(projectEntry, env)
+        : undefined;
+    if (options.resources.roots.agentDir !== options.resources.roots.projectDir) {
+        if (isPiOAuthAuthEntry(projectEntry)) {
+            throw new Error(formatProjectOAuthAuthError(options.provider));
+        }
+        if (projectKey !== undefined) {
+            if (isPiCommandConfigValue(projectKey)) {
+                await resolvePiProjectCommandApiKey(options.modelRuntime, options.provider, projectKey);
+            }
+            // Any project auth entry remains above user/settings/model credentials.
+            return;
+        }
+    }
+    const settingsKey = resolvePiSettingsApiKey(options.resources.settings, options.provider, env);
+    const modelsKey = resolvePiModelsApiKey(options.resources.models.providers[options.provider], env);
+    if (settingsKey !== undefined && isPiCommandConfigValue(settingsKey)) {
+        options.modelRuntime.registerProvider(options.provider, {
+            apiKey: settingsKey,
+        });
+    }
+    else if (modelsKey !== undefined && isPiCommandConfigValue(modelsKey)) {
+        options.modelRuntime.registerProvider(options.provider, {
+            apiKey: modelsKey,
+        });
+    }
+}
+/** Whether resolving this provider's configured Pi credential can run a command. */
+export function hasPiConductorCommandCredential(resources, provider, env = process.env) {
+    if (resources.roots.agentDir !== resources.roots.projectDir) {
+        const projectEntry = resources.authLayers.at(-1)?.[provider];
+        if (isPiOAuthAuthEntry(projectEntry))
+            return false;
+        const projectKey = resolvePiAuthEntry(projectEntry, env);
+        if (projectKey !== undefined)
+            return isPiCommandConfigValue(projectKey);
+    }
+    const settingsKey = resolvePiSettingsApiKey(resources.settings, provider, env);
+    if (settingsKey !== undefined)
+        return isPiCommandConfigValue(settingsKey);
+    const modelsKey = resolvePiModelsApiKey(resources.models.providers[provider], env);
+    return modelsKey !== undefined && isPiCommandConfigValue(modelsKey);
+}
 /** 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);
@@ -346,14 +530,21 @@ async function resolveStatusProviders(options, resources, context) {
     const configured = resolvePiConductorProviderFromResources(options, resources, context);
     if (configured)
         return [configured];
+    const settingsApiKeys = getPiHeadlessSetting(resources.settings, 'apiKeys', 'auth-fallback');
     const providers = new Set([
         ...(await context.modelRuntime.listCredentials()).map((entry) => entry.providerId),
         ...context.modelRegistry.getAll().map((model) => model.provider),
         ...Object.keys(resources.models.providers),
+        ...(isRecord(settingsApiKeys)
+            ? Object.entries(settingsApiKeys)
+                .filter(([, value]) => typeof value === 'string')
+                .map(([provider]) => provider)
+            : []),
     ]);
     return [...providers].sort();
 }
 function getPiProviderAuthStatus(provider, context, resources, env) {
+    const settingsCommand = getPiSettingsCommandSource(resources, provider, env);
     if (resources.roots.agentDir !== resources.roots.projectDir) {
         const projectEntry = resources.authLayers.at(-1)?.[provider];
         if (isPiOAuthAuthEntry(projectEntry)) {
@@ -361,24 +552,156 @@ function getPiProviderAuthStatus(provider, context, resources, env) {
                 provider,
                 configured: false,
                 source: 'project_oauth_unsupported',
+                ...(settingsCommand
+                    ? {
+                        commandConfiguration: {
+                            source: 'settings_json',
+                            scope: settingsCommand.scope,
+                            path: settingsCommand.path,
+                            effective: false,
+                        },
+                    }
+                    : {}),
             };
         }
         const projectKey = resolvePiAuthEntry(projectEntry, env);
         if (projectKey !== undefined) {
-            return { provider, configured: true, source: 'project_stored' };
+            return {
+                provider,
+                configured: true,
+                source: 'project_stored',
+                ...getKnownAuthMode(projectEntry),
+                scope: 'project',
+                configurationPath: join(resources.roots.projectDir, 'auth.json'),
+                ...(settingsCommand
+                    ? {
+                        commandConfiguration: {
+                            source: 'settings_json',
+                            scope: settingsCommand.scope,
+                            path: settingsCommand.path,
+                            effective: false,
+                        },
+                    }
+                    : {}),
+            };
         }
     }
     const registryStatus = context.modelRuntime.getProviderAuthStatus(provider);
-    if (registryStatus.configured || registryStatus.source === 'stored') {
-        return normalizePiAuthStatus(provider, registryStatus, true);
+    if (registryStatus.source === 'stored' || registryStatus.source === 'runtime') {
+        const stored = registryStatus.source === 'stored';
+        const runtimeSettings = stored
+            ? undefined
+            : getPiSettingsApiKeysSource(resources, provider, env);
+        return {
+            ...normalizePiAuthStatus(provider, registryStatus, true),
+            ...(stored
+                ? getKnownAuthMode(resources.authLayers[0]?.[provider])
+                : { mode: 'api_key' }),
+            ...(stored
+                ? { scope: 'user', configurationPath: context.authPath }
+                : runtimeSettings
+                    ? {
+                        scope: runtimeSettings.scope,
+                        configurationPath: runtimeSettings.path,
+                    }
+                    : {}),
+            ...(settingsCommand
+                ? {
+                    commandConfiguration: {
+                        source: 'settings_json',
+                        scope: settingsCommand.scope,
+                        path: settingsCommand.path,
+                        effective: false,
+                    },
+                }
+                : {}),
+        };
+    }
+    if (settingsCommand?.selected) {
+        return {
+            provider,
+            configured: true,
+            source: 'settings_json',
+            mode: 'command',
+            scope: settingsCommand.scope,
+            configurationPath: settingsCommand.path,
+        };
+    }
+    if (registryStatus.configured) {
+        const modelsCommand = registryStatus.source === 'models_json_command'
+            ? getPiModelsCommandSource(resources, provider, env)
+            : undefined;
+        return {
+            ...normalizePiAuthStatus(provider, registryStatus, true),
+            ...(modelsCommand
+                ? {
+                    mode: 'command',
+                    scope: modelsCommand.scope,
+                    configurationPath: modelsCommand.path,
+                }
+                : {}),
+            ...(settingsCommand
+                ? {
+                    commandConfiguration: {
+                        source: 'settings_json',
+                        scope: settingsCommand.scope,
+                        path: settingsCommand.path,
+                        effective: false,
+                    },
+                }
+                : {}),
+        };
     }
     const settingsKey = resolvePiSettingsApiKey(resources.settings, provider, env);
     if (settingsKey !== undefined) {
-        return { provider, configured: true, source: 'settings_json' };
+        const settingsSource = getPiSettingsApiKeySource(resources, provider, env);
+        return {
+            provider,
+            configured: true,
+            source: 'settings_json',
+            ...(settingsSource
+                ? {
+                    scope: settingsSource.scope,
+                    configurationPath: settingsSource.path,
+                }
+                : {}),
+            ...(settingsCommand
+                ? {
+                    commandConfiguration: {
+                        source: 'settings_json',
+                        scope: settingsCommand.scope,
+                        path: settingsCommand.path,
+                        effective: false,
+                    },
+                }
+                : {}),
+        };
     }
     const modelsKey = resolvePiModelsApiKey(resources.models.providers[provider], env);
     if (modelsKey !== undefined) {
-        return { provider, configured: true, source: 'models_json_key' };
+        const modelsSource = getPiModelsApiKeySource(resources, provider, env);
+        return {
+            provider,
+            configured: true,
+            source: 'models_json_key',
+            ...(modelsSource
+                ? {
+                    scope: modelsSource.scope,
+                    configurationPath: modelsSource.path,
+                    ...(isPiCommandConfigValue(modelsKey) ? { mode: 'command' } : {}),
+                }
+                : {}),
+            ...(settingsCommand
+                ? {
+                    commandConfiguration: {
+                        source: 'settings_json',
+                        scope: settingsCommand.scope,
+                        path: settingsCommand.path,
+                        effective: false,
+                    },
+                }
+                : {}),
+        };
     }
     const envKey = getEnvApiKey(provider, toProviderEnv(env));
     if (envKey !== undefined) {
@@ -387,9 +710,31 @@ function getPiProviderAuthStatus(provider, context, resources, env) {
             configured: true,
             source: 'environment',
             label: formatPiProviderEnvHint(provider),
+            ...(settingsCommand
+                ? {
+                    commandConfiguration: {
+                        source: 'settings_json',
+                        scope: settingsCommand.scope,
+                        path: settingsCommand.path,
+                        effective: false,
+                    },
+                }
+                : {}),
         };
     }
-    return normalizePiAuthStatus(provider, registryStatus, false);
+    return {
+        ...normalizePiAuthStatus(provider, registryStatus, false),
+        ...(settingsCommand
+            ? {
+                commandConfiguration: {
+                    source: 'settings_json',
+                    scope: settingsCommand.scope,
+                    path: settingsCommand.path,
+                    effective: false,
+                },
+            }
+            : {}),
+    };
 }
 function normalizePiAuthStatus(provider, status, configured) {
     return {
@@ -399,6 +744,117 @@ function normalizePiAuthStatus(provider, status, configured) {
         ...(status.label ? { label: status.label } : {}),
     };
 }
+function getPiSettingsApiKeySource(resources, provider, env) {
+    const scalarValue = getPiHeadlessSetting(resources.settings, 'apiKey', 'auth-fallback');
+    const usesScalar = typeof scalarValue === 'string';
+    const apiKeys = getPiHeadlessSetting(resources.settings, 'apiKeys', 'auth-fallback');
+    const providerValue = !usesScalar &&
+        isRecord(apiKeys) &&
+        Object.prototype.hasOwnProperty.call(apiKeys, provider)
+        ? apiKeys[provider]
+        : undefined;
+    const selected = usesScalar ? scalarValue : providerValue;
+    if (typeof selected !== 'string')
+        return undefined;
+    return getPiSettingsLayerSource(resources, provider, env, usesScalar ? 'apiKey' : 'apiKeys', expandEnvReference(selected, env));
+}
+function getPiSettingsApiKeysSource(resources, provider, env) {
+    const apiKeys = getPiHeadlessSetting(resources.settings, 'apiKeys', 'auth-fallback');
+    if (!isRecord(apiKeys) || !Object.prototype.hasOwnProperty.call(apiKeys, provider)) {
+        return undefined;
+    }
+    const selected = apiKeys[provider];
+    if (typeof selected !== 'string')
+        return undefined;
+    return getPiSettingsLayerSource(resources, provider, env, 'apiKeys', expandEnvReference(selected, env));
+}
+function getPiSettingsLayerSource(resources, provider, env, field, resolved) {
+    if (resolved === undefined)
+        return undefined;
+    for (let index = resources.settingsLayers.length - 1; index >= 0; index -= 1) {
+        const layer = resources.settingsLayers[index];
+        const layerApiKeys = getPiHeadlessSetting(layer, 'apiKeys', 'auth-fallback');
+        const layerValue = field === 'apiKey'
+            ? getPiHeadlessSetting(layer, 'apiKey', 'auth-fallback')
+            : isRecord(layerApiKeys) &&
+                Object.prototype.hasOwnProperty.call(layerApiKeys, provider)
+                ? layerApiKeys[provider]
+                : undefined;
+        if (typeof layerValue === 'string' &&
+            expandEnvReference(layerValue, env) === resolved) {
+            const isProject = index === resources.settingsLayers.length - 1 &&
+                resources.roots.agentDir !== resources.roots.projectDir;
+            return {
+                scope: isProject ? 'project' : 'user',
+                path: join(isProject ? resources.roots.projectDir : resources.roots.agentDir, 'settings.json'),
+            };
+        }
+    }
+    return undefined;
+}
+function getPiSettingsCommandSource(resources, provider, env) {
+    const scalarApiKey = getPiHeadlessSetting(resources.settings, 'apiKey', 'auth-fallback');
+    if (typeof scalarApiKey === 'string') {
+        const resolvedScalar = expandEnvReference(scalarApiKey, env);
+        if (resolvedScalar !== undefined && isPiCommandConfigValue(resolvedScalar)) {
+            const source = getPiSettingsLayerSource(resources, provider, env, 'apiKey', resolvedScalar);
+            return source ? { ...source, selected: true } : undefined;
+        }
+    }
+    const apiKeys = getPiHeadlessSetting(resources.settings, 'apiKeys', 'auth-fallback');
+    if (!isRecord(apiKeys) ||
+        !Object.prototype.hasOwnProperty.call(apiKeys, provider) ||
+        typeof apiKeys[provider] !== 'string') {
+        return undefined;
+    }
+    const resolvedProviderKey = expandEnvReference(apiKeys[provider], env);
+    if (resolvedProviderKey === undefined || !isPiCommandConfigValue(resolvedProviderKey)) {
+        return undefined;
+    }
+    const source = getPiSettingsLayerSource(resources, provider, env, 'apiKeys', resolvedProviderKey);
+    return source
+        ? {
+            ...source,
+            selected: typeof scalarApiKey !== 'string',
+        }
+        : undefined;
+}
+function getPiModelsApiKeySource(resources, provider, env) {
+    const selected = resolvePiModelsApiKey(resources.models.providers[provider], env);
+    if (selected === undefined)
+        return undefined;
+    for (let index = resources.modelsLayers.length - 1; index >= 0; index -= 1) {
+        const layerValue = resources.modelsLayers[index]?.providers[provider]?.apiKey;
+        if (typeof layerValue === 'string' &&
+            expandEnvReference(layerValue, env) === selected) {
+            const isProject = index === resources.modelsLayers.length - 1 &&
+                resources.roots.agentDir !== resources.roots.projectDir;
+            return {
+                scope: isProject ? 'project' : 'user',
+                path: join(isProject ? resources.roots.projectDir : resources.roots.agentDir, 'models.json'),
+            };
+        }
+    }
+    return undefined;
+}
+function getPiModelsCommandSource(resources, provider, env) {
+    const selected = resolvePiModelsApiKey(resources.models.providers[provider], env);
+    if (selected === undefined || !isPiCommandConfigValue(selected))
+        return undefined;
+    return getPiModelsApiKeySource(resources, provider, env);
+}
+function getKnownAuthMode(entry) {
+    if (!isRecord(entry))
+        return undefined;
+    if (entry.type === 'oauth')
+        return { mode: 'oauth' };
+    if (entry.type === 'api_key') {
+        const key = [entry.key, entry.apiKey, entry.token, entry.accessToken, entry.access]
+            .find((value) => typeof value === 'string');
+        return { mode: key?.startsWith('!') ? 'command' : 'api_key' };
+    }
+    return undefined;
+}
 function addPiModelEntry(entries, model) {
     const id = `${model.provider}/${model.id}`;
     entries.set(id, {
@@ -445,6 +901,8 @@ function resolvePiSettingsApiKey(settings, provider, env) {
     const apiKeys = getPiHeadlessSetting(settings, 'apiKeys', 'auth-fallback');
     if (!isRecord(apiKeys))
         return undefined;
+    if (!Object.prototype.hasOwnProperty.call(apiKeys, provider))
+        return undefined;
     const value = apiKeys[provider];
     return typeof value === 'string' ? expandEnvReference(value, env) : undefined;
 }
@@ -462,9 +920,8 @@ function expandEnvReference(value, env) {
 function isPiCommandConfigValue(value) {
     return value.startsWith('!');
 }
-function formatPiCommandResolutionError(provider, command, cause) {
-    const causeMessage = cause instanceof Error ? ` (${cause.message})` : '';
-    return new Error(`Failed to resolve API key for Pi provider "${provider}" from shell command: ${command.slice(1)}${causeMessage}`, cause instanceof Error ? { cause } : undefined);
+function formatPiCommandResolutionError() {
+    return new Error('API key auth failed for provider: failed to resolve API key for Pi provider from the configured command.');
 }
 async function resolvePiProjectCommandApiKey(modelRuntime, provider, command) {
     const isolatedProvider = `__agents_ensemble_project_auth__${provider}`;
@@ -478,19 +935,19 @@ async function resolvePiProjectCommandApiKey(modelRuntime, provider, command) {
             return runtimeAuth.auth.apiKey;
         }
     }
-    catch (error) {
-        throw formatPiCommandResolutionError(provider, command, error);
+    catch {
+        throw formatPiCommandResolutionError();
     }
-    throw formatPiCommandResolutionError(provider, command, undefined);
+    throw formatPiCommandResolutionError();
 }
 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) {
+async function createPiModelRuntime(options, resources, authPath) {
     const roots = resolvePiResourceRoots(options);
     const runtime = await ModelRuntime.create({
-        authPath: join(roots.agentDir, 'auth.json'),
+        authPath,
         // The ensemble resource loader has already merged user and project models.
         // Avoid letting ModelRuntime read an unmerged second view of models.json.
         modelsPath: null,
@@ -499,7 +956,17 @@ async function createPiModelRuntime(options, resources) {
     });
     const env = options.env ?? process.env;
     for (const [provider, config] of Object.entries(resources.models.providers)) {
-        runtime.registerProvider(provider, toPiRuntimeProviderConfig(config, env));
+        const runtimeConfig = toPiRuntimeProviderConfig(config, env);
+        const modelApiKey = resolvePiModelsApiKey(config, env);
+        if (modelApiKey !== undefined && isPiCommandConfigValue(modelApiKey)) {
+            // registerProvider() starts a ModelRuntime availability refresh. Keep a
+            // models.json command out of that startup refresh and register it later,
+            // when the selected provider request resolves its auth.
+            runtime.registerProvider(provider, { ...runtimeConfig, apiKey: undefined });
+        }
+        else {
+            runtime.registerProvider(provider, runtimeConfig);
+        }
     }
     if (roots.agentDir !== roots.projectDir) {
         for (const [provider, entry] of Object.entries(resources.authLayers.at(-1) ?? {})) {
@@ -555,20 +1022,224 @@ function toPiRuntimeProviderConfig(config, env) {
         ...(models ? { models } : {}),
     };
 }
-async function writePiApiKey(authPath, provider, apiKey) {
-    await mkdir(dirname(authPath), { recursive: true });
+async function writePiApiKey(authPath, protectedProjectRoots, provider, apiKey) {
+    await mkdir(dirname(authPath), { recursive: true, mode: 0o700 });
+    const targetPath = await resolveSafePiUserAuthPath(authPath, protectedProjectRoots);
     let auth = {};
     try {
-        const parsed = JSON.parse(await readFile(authPath, 'utf8'));
+        const parsed = JSON.parse(await readFile(targetPath, 'utf8'));
         if (isRecord(parsed))
             auth = parsed;
     }
     catch (error) {
-        if (!isRecord(error) || error.code !== 'ENOENT')
+        if (!isMissingFile(error))
             throw error;
     }
     auth[provider] = { type: 'api_key', key: apiKey };
-    await writeFile(authPath, `${JSON.stringify(auth, null, 2)}\n`, 'utf8');
+    await atomicWritePrivatePiUserFile(targetPath, `${JSON.stringify(auth, null, 2)}\n`);
+}
+async function resolveSafePiUserAuthPath(authPath, protectedProjectRoots) {
+    if (await isPathWithinAnyRoot(authPath, protectedProjectRoots)) {
+        throw new Error(`Refusing to use Pi user auth.json at ${authPath} because its configured path or a symlink target enters the project Pi resource root or project .ensemble layer, or resolves to a target linked from either project layer. Configure a user agentDir outside those project paths.`);
+    }
+    return canonicalPath(authPath);
+}
+async function resolveSafePiUserSettingsPath(settingsPath, protectedProjectRoots) {
+    if (await isPathWithinAnyRoot(settingsPath, protectedProjectRoots)) {
+        throw new Error(`Refusing to use Pi user settings.json at ${settingsPath} because its configured path or a symlink target enters the project Pi resource root or project .ensemble layer, or resolves to a target linked from either project layer. Configure a user agentDir outside those project paths.`);
+    }
+    return canonicalPath(settingsPath);
+}
+async function resolveSafePiProjectSettingsPath(settingsPath, projectDir) {
+    const projectRoot = await canonicalPath(projectDir);
+    const targetPath = await canonicalPath(settingsPath);
+    if (!(await isPathWithin(projectRoot, targetPath))) {
+        throw new Error('Refusing to write Pi project settings.json outside the configured project resource root.');
+    }
+    await assertRegularSettingsTarget(targetPath, settingsPath);
+    return targetPath;
+}
+async function assertRegularSettingsTarget(targetPath, displayPath) {
+    let details;
+    try {
+        details = await lstat(targetPath);
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return;
+        throw error;
+    }
+    if (!details.isFile()) {
+        throw new Error(`Refusing to update Pi settings at ${displayPath} because the destination is not a regular file.`);
+    }
+}
+async function writePiSettingsCommand(settingsPath, provider, command) {
+    await assertRegularSettingsTarget(settingsPath, settingsPath);
+    const settings = await readPiSettingsFile(settingsPath);
+    const existingApiKeys = settings.apiKeys;
+    if (existingApiKeys !== undefined && !isRecord(existingApiKeys)) {
+        throw new Error('Pi settings apiKeys must be an object; the file was left unchanged.');
+    }
+    const apiKeys = { ...existingApiKeys };
+    Object.defineProperty(apiKeys, provider, {
+        configurable: true,
+        enumerable: true,
+        value: command,
+        writable: true,
+    });
+    const updated = { ...settings, apiKeys };
+    await atomicWritePrivatePiUserFile(settingsPath, `${JSON.stringify(updated, null, 2)}\n`);
+}
+async function clearPiSettingsCommand(settingsPath, provider) {
+    await assertRegularSettingsTarget(settingsPath, settingsPath);
+    let settings;
+    try {
+        settings = await readPiSettingsFile(settingsPath);
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return false;
+        throw error;
+    }
+    if (settings.apiKeys !== undefined && !isRecord(settings.apiKeys)) {
+        throw new Error('Pi settings apiKeys must be an object; the file was left unchanged.');
+    }
+    const apiKeys = settings.apiKeys;
+    if (!apiKeys ||
+        !Object.prototype.hasOwnProperty.call(apiKeys, provider) ||
+        typeof apiKeys[provider] !== 'string' ||
+        !isPiCommandConfigValue(apiKeys[provider])) {
+        return false;
+    }
+    const updatedApiKeys = { ...apiKeys };
+    delete updatedApiKeys[provider];
+    const updated = { ...settings };
+    if (Object.keys(updatedApiKeys).length === 0) {
+        delete updated.apiKeys;
+    }
+    else {
+        updated.apiKeys = updatedApiKeys;
+    }
+    await atomicWritePrivatePiUserFile(settingsPath, `${JSON.stringify(updated, null, 2)}\n`);
+    return true;
+}
+function requireCommandAuthProvider(provider) {
+    const normalized = normalizeProvider(provider);
+    if (!normalized ||
+        normalized !== provider ||
+        /[\u0000-\u001f\u007f]/u.test(normalized)) {
+        throw new Error('A valid Pi provider ID is required for command credentials.');
+    }
+    return normalized;
+}
+function requireCommandAuthTarget(target) {
+    if (target === undefined || target === 'user')
+        return 'user';
+    if (target === 'project')
+        return 'project';
+    throw new Error('Pi command credentials can target only user or project settings.');
+}
+function validatePiCommandCredential(command) {
+    if (typeof command !== 'string' ||
+        !command.startsWith('!') ||
+        command.slice(1).trim() === '' ||
+        command.includes('\0')) {
+        throw new Error('A Pi command credential must start with ! and include a non-empty command.');
+    }
+}
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return false;
+        throw error;
+    }
+}
+async function ensurePiUserSettingsSafeForOAuth(settingsPath, protectedProjectRoots) {
+    const targetPath = await resolveSafePiUserSettingsPath(settingsPath, protectedProjectRoots);
+    let details;
+    try {
+        details = await lstat(targetPath);
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return;
+        throw error;
+    }
+    if (!details.isFile()) {
+        throw new Error(`Refusing to use Pi user settings.json at ${settingsPath} because it is not a regular file.`);
+    }
+    const needsPrivateModeReset = process.platform !== 'win32' && (details.mode & 0o777) !== 0o600;
+    if (details.nlink > 1) {
+        const contents = await readFile(targetPath, 'utf8');
+        const safeTargetPath = await resolveSafePiUserSettingsPath(settingsPath, protectedProjectRoots);
+        if (safeTargetPath !== targetPath) {
+            throw new Error('Pi user settings.json target changed while preparing OAuth login; no credentials were written. Retry login after checking the settings.json symlink.');
+        }
+        await atomicWritePrivatePiUserFile(targetPath, contents);
+    }
+    else if (needsPrivateModeReset) {
+        await chmod(targetPath, 0o600);
+    }
+}
+async function atomicWritePrivatePiUserFile(path, contents) {
+    const directory = dirname(path);
+    const temporaryPath = join(directory, `.${basename(path)}.${randomUUID()}.tmp`);
+    let file;
+    try {
+        file = await open(temporaryPath, 'wx', 0o600);
+        // Set the final private mode before any credential bytes reach the file.
+        await file.chmod(0o600);
+        await file.writeFile(contents, 'utf8');
+        await file.sync();
+        await file.close();
+        file = undefined;
+        await rename(temporaryPath, path);
+    }
+    catch (error) {
+        await file?.close().catch(() => undefined);
+        await unlink(temporaryPath).catch(() => undefined);
+        throw error;
+    }
+}
+async function ensurePrivatePiUserAuthFile(authPath, protectedProjectRoots) {
+    // The Pi auth store only applies its mode when creating a file. Replace any
+    // permissive or hard-linked user file before OAuth or logout can mutate it.
+    const targetPath = await resolveSafePiUserAuthPath(authPath, protectedProjectRoots);
+    await mkdir(dirname(targetPath), { recursive: true, mode: 0o700 });
+    const safeTargetPath = await resolveSafePiUserAuthPath(authPath, protectedProjectRoots);
+    let details;
+    try {
+        details = await lstat(safeTargetPath);
+    }
+    catch (error) {
+        if (!isMissingFile(error))
+            throw error;
+        await atomicWritePrivatePiUserFile(safeTargetPath, '{}\n');
+        return safeTargetPath;
+    }
+    if (!details.isFile()) {
+        throw new Error(`Refusing to use Pi user auth.json at ${authPath} because it is not a regular file.`);
+    }
+    // Windows mode bits cannot distinguish owner/group/others ACLs. Treating a
+    // writable Windows file as non-private by mode alone would replace it on
+    // every OAuth login or logout and discard any file-specific ACL. Hardlinks
+    // still require replacement on every platform before runtime mutation.
+    const needsPrivateModeReset = process.platform !== 'win32' && (details.mode & 0o777) !== 0o600;
+    if (details.nlink > 1 || needsPrivateModeReset) {
+        const contents = await readFile(safeTargetPath, 'utf8');
+        await atomicWritePrivatePiUserFile(safeTargetPath, contents);
+    }
+    return safeTargetPath;
+}
+function isMissingFile(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
 }
 function toPiAuthInteraction(callbacks) {
     return {
@@ -581,17 +1252,24 @@ function toPiAuthInteraction(callbacks) {
                         id: option.id,
                         label: option.label,
                     })),
+                    ...(prompt.signal ? { signal: prompt.signal } : {}),
                 });
                 if (selected === undefined)
                     throw new Error('OAuth login was cancelled.');
                 return selected;
             }
             if (prompt.type === 'manual_code' && callbacks.onManualCodeInput) {
-                return callbacks.onManualCodeInput();
+                return callbacks.onManualCodeInput({
+                    message: prompt.message,
+                    ...(prompt.placeholder ? { placeholder: prompt.placeholder } : {}),
+                    ...(prompt.signal ? { signal: prompt.signal } : {}),
+                });
             }
             return callbacks.onPrompt({
                 message: prompt.message,
+                type: prompt.type,
                 ...(prompt.placeholder ? { placeholder: prompt.placeholder } : {}),
+                ...(prompt.signal ? { signal: prompt.signal } : {}),
             });
         },
         notify: (event) => {