create-principles-disciple 1.82.0 → 1.83.0

package/console/dist/server/config/pd-config-store.js

@@ -0,0 +1,660 @@
+/**
+ * PD Config Store — PRI-309
+ *
+ * I/O boundary for reading and writing `.pd/config.yaml`.
+ * Uses core validation and effective config computation.
+ * Safe partial writes: validate before write, preserve unrelated sections,
+ * reject malformed existing file.
+ *
+ * ERR entries:
+ * - ERR-001/ERR-005: No `as` bypasses on untrusted parsed YAML
+ * - ERR-002: Graceful degradation includes reason
+ * - ERR-009/ERR-010: Required fields fail loud
+ * - ERR-013: Object.hasOwn() for untrusted keys
+ * - ERR-045: ANY-segment redaction for sensitive keys
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import yaml from 'js-yaml';
+import { validatePdConfig, computeEffectivePdConfig, redactPdConfig, checkAgentRuntimeReadiness, resolveAgentRuntimeBinding, INTERNAL_AGENT_NAMES, } from '@principles/core/runtime-v2';
+// ── Constants ────────────────────────────────────────────────────────────────
+const PD_CONFIG_DIR = '.pd';
+const PD_CONFIG_FILENAME = 'config.yaml';
+/** Allowed top-level keys in PATCH /agents/:name/binding payload */
+const ALLOWED_PAYLOAD_KEYS = new Set(['runtimeProfile', 'enabled']);
+/** Secret-like key segments for ANY-segment detection (ERR-045) */
+const SECRET_KEY_SEGMENTS = [
+    'apikey', 'api_key', 'key', 'token', 'secret', 'password', 'auth',
+    'credential', 'gatewaytoken', 'gateway_token', 'accesstoken', 'access_token',
+];
+// ── Private Helpers (defined before public functions) ────────────────────────
+function buildProfileLabel(_id, profile) {
+    if (profile.type === 'openclaw') {
+        const parts = ['openclaw'];
+        if (profile.provider)
+            parts.push(profile.provider);
+        if (profile.model)
+            parts.push(profile.model);
+        if (profile.source && !profile.provider && !profile.model)
+            parts.push(profile.source);
+        return parts.join(': ');
+    }
+    return `pi-ai: ${profile.provider}/${profile.model}`;
+}
+function writeConfigAtomic(configPath, config) {
+    // Ensure directory exists
+    const dir = path.dirname(configPath);
+    fs.mkdirSync(dir, { recursive: true });
+    // Serialize to YAML
+    const content = yaml.dump(config, {
+        lineWidth: 120,
+        noRefs: true,
+        sortKeys: false,
+    });
+    // Atomic write: tmp → rename
+    const tmpPath = configPath + '.tmp';
+    fs.writeFileSync(tmpPath, content, 'utf8');
+    fs.renameSync(tmpPath, configPath);
+}
+function isValidAgentName(name) {
+    return INTERNAL_AGENT_NAMES.includes(name);
+}
+/**
+ * Type guard: is `value` a plain Record<string, unknown>?
+ * Replaces `payload as Record<string, unknown>` (ERR-001/ERR-005).
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * ANY-segment secret key detection (ERR-045).
+ * Checks if any segment of a dotted key path matches a secret-like pattern.
+ * E.g. "provider.api_key" → detected; "runtimeProfile" → not detected.
+ */
+function containsSecretSegment(key) {
+    const lower = key.toLowerCase();
+    const segments = lower.split(/[._-]/);
+    return segments.some(seg => SECRET_KEY_SEGMENTS.includes(seg));
+}
+/**
+ * Recursively scan an object for secret-like keys at any depth (ERR-045).
+ */
+function hasSecretLikeKeyDeep(obj, prefix = '') {
+    for (const key of Object.keys(obj)) {
+        const fullPath = prefix ? `${prefix}.${key}` : key;
+        if (containsSecretSegment(key)) {
+            return fullPath;
+        }
+        const val = obj[key];
+        if (isRecord(val)) {
+            const nested = hasSecretLikeKeyDeep(val, fullPath);
+            if (nested)
+                return nested;
+        }
+    }
+    return null;
+}
+export function validateBindingPayload(payload) {
+    // Use isRecord() type guard instead of `as` (ERR-001/ERR-005)
+    if (!isRecord(payload)) {
+        return { ok: false, error: 'bad_request', message: 'Payload must be a JSON object with runtimeProfile and enabled fields' };
+    }
+    // Strict whitelist: reject unknown top-level keys
+    const payloadKeys = Object.keys(payload);
+    for (const key of payloadKeys) {
+        if (!ALLOWED_PAYLOAD_KEYS.has(key)) {
+            return { ok: false, error: 'bad_request', message: `Payload contains unknown field '${key}'. Only 'runtimeProfile' and 'enabled' are allowed.` };
+        }
+    }
+    // ANY-segment secret key detection on nested values (ERR-045)
+    for (const key of payloadKeys) {
+        const val = payload[key];
+        if (isRecord(val)) {
+            const secretPath = hasSecretLikeKeyDeep(val, key);
+            if (secretPath) {
+                return { ok: false, error: 'bad_request', message: `Payload contains secret-like field '${secretPath}'. Remove secret fields from the request.` };
+            }
+        }
+    }
+    const runtimeProfileRaw = Object.hasOwn(payload, 'runtimeProfile') ? payload.runtimeProfile : undefined;
+    if (runtimeProfileRaw === undefined) {
+        return { ok: false, error: 'bad_request', message: 'Missing required field: runtimeProfile' };
+    }
+    if (typeof runtimeProfileRaw !== 'string' || runtimeProfileRaw.length === 0) {
+        return { ok: false, error: 'bad_request', message: 'runtimeProfile must be a non-empty string' };
+    }
+    const enabledRaw = Object.hasOwn(payload, 'enabled') ? payload.enabled : undefined;
+    if (enabledRaw === undefined) {
+        return { ok: false, error: 'bad_request', message: 'Missing required field: enabled' };
+    }
+    if (typeof enabledRaw !== 'boolean') {
+        return { ok: false, error: 'bad_request', message: 'enabled must be a boolean' };
+    }
+    return { ok: true, value: { runtimeProfile: runtimeProfileRaw, enabled: enabledRaw } };
+}
+// ── Config Path ──────────────────────────────────────────────────────────────
+export function getPdConfigPath(workspaceDir) {
+    return path.join(workspaceDir, PD_CONFIG_DIR, PD_CONFIG_FILENAME);
+}
+// ── Load Config ──────────────────────────────────────────────────────────────
+export function loadPdConfig(workspaceDir) {
+    const configPath = getPdConfigPath(workspaceDir);
+    // Missing file → defaults
+    if (!fs.existsSync(configPath)) {
+        const effective = computeEffectivePdConfig(null);
+        return {
+            ok: true,
+            effective,
+            source: 'defaults',
+            configPath,
+            warnings: effective.warnings,
+        };
+    }
+    // Read
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const defaults = computeEffectivePdConfig(null);
+        return {
+            ok: false,
+            source: 'malformed',
+            configPath,
+            errors: [{ path: '', reason: `Failed to read .pd/config.yaml: ${message}`, nextAction: 'Check file permissions for .pd/config.yaml' }],
+            defaults,
+            warnings: [],
+        };
+    }
+    // Parse YAML — treat as unknown (ERR-001)
+    let parsed;
+    try {
+        parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const defaults = computeEffectivePdConfig(null);
+        return {
+            ok: false,
+            source: 'malformed',
+            configPath,
+            errors: [{ path: '', reason: `YAML parse error: ${message}`, nextAction: 'Fix YAML syntax in .pd/config.yaml' }],
+            defaults,
+            warnings: [],
+        };
+    }
+    // Validate via core (ERR-001, ERR-005)
+    const validationResult = validatePdConfig(parsed);
+    if (!validationResult.ok) {
+        const defaults = computeEffectivePdConfig(null);
+        return {
+            ok: false,
+            source: 'malformed',
+            configPath,
+            errors: validationResult.errors.map(e => ({
+                path: e.path,
+                reason: e.reason,
+                nextAction: e.nextAction,
+            })),
+            defaults,
+            warnings: [],
+        };
+    }
+    // Compute effective config
+    const effective = computeEffectivePdConfig(validationResult.value);
+    return {
+        ok: true,
+        effective,
+        source: 'user_config',
+        configPath,
+        warnings: effective.warnings,
+    };
+}
+// ── Get Redacted Summary ─────────────────────────────────────────────────────
+export function getConfigSummary(workspaceDir) {
+    const result = loadPdConfig(workspaceDir);
+    const effective = result.ok ? result.effective : result.defaults;
+    const summary = redactPdConfig(effective);
+    if (!result.ok) {
+        return { summary, errors: result.errors };
+    }
+    return { summary };
+}
+// ── Get Catalog ──────────────────────────────────────────────────────────────
+export function getConfigCatalog(workspaceDir) {
+    const result = loadPdConfig(workspaceDir);
+    if (!result.ok) {
+        // Surface malformed config errors instead of silently using defaults
+        return {
+            profiles: [],
+            errors: result.errors,
+        };
+    }
+    const summary = redactPdConfig(result.effective);
+    return { profiles: summary.runtimeProfiles };
+}
+// ── Update Agent Binding ─────────────────────────────────────────────────────
+export function updateAgentBinding(workspaceDir, agentName, payload) {
+    // 1. Validate agent name
+    if (!isValidAgentName(agentName)) {
+        return {
+            ok: false,
+            statusCode: 400,
+            error: 'bad_request',
+            message: `Unknown agent name '${agentName}'. Valid agents: ${INTERNAL_AGENT_NAMES.join(', ')}`,
+        };
+    }
+    // 2. Validate payload
+    const payloadResult = validateBindingPayload(payload);
+    if (!payloadResult.ok) {
+        return { ok: false, statusCode: 400, error: payloadResult.error, message: payloadResult.message };
+    }
+    const { runtimeProfile, enabled } = payloadResult.value;
+    // 3. Load existing config
+    const loadResult = loadPdConfig(workspaceDir);
+    // 4. If malformed, refuse to write (AC: malformed existing config 拒绝写入)
+    if (!loadResult.ok) {
+        return {
+            ok: false,
+            statusCode: 409,
+            error: 'conflict',
+            message: `Cannot update agent binding: existing .pd/config.yaml is malformed. Fix config errors first. Errors: ${loadResult.errors.map(e => e.reason).join('; ')}`,
+        };
+    }
+    const { effective } = loadResult;
+    // 5. Validate runtime profile reference exists
+    if (!Object.hasOwn(effective.config.runtimeProfiles, runtimeProfile)) {
+        return {
+            ok: false,
+            statusCode: 400,
+            error: 'bad_request',
+            message: `Runtime profile '${runtimeProfile}' does not exist. Available profiles: ${Object.keys(effective.config.runtimeProfiles).join(', ')}`,
+        };
+    }
+    // 6. Build updated config — read original file to preserve unknown root entries
+    const configPath = getPdConfigPath(workspaceDir);
+    let rawConfig;
+    if (fs.existsSync(configPath)) {
+        const rawContent = fs.readFileSync(configPath, 'utf8');
+        const rawParsed = yaml.load(rawContent, { schema: yaml.JSON_SCHEMA });
+        if (isRecord(rawParsed)) {
+            rawConfig = { ...rawParsed };
+        }
+        else {
+            rawConfig = {};
+        }
+    }
+    else {
+        rawConfig = {};
+    }
+    // Update only the agent binding section
+    const agentsMap = {};
+    for (const name of INTERNAL_AGENT_NAMES) {
+        const existing = effective.config.internalAgents.agents[name];
+        if (name === agentName) {
+            agentsMap[name] = { enabled, runtimeProfile };
+        }
+        else if (existing) {
+            agentsMap[name] = {
+                enabled: existing.enabled,
+                ...(existing.runtimeProfile ? { runtimeProfile: existing.runtimeProfile } : {}),
+            };
+        }
+    }
+    // Merge: start from raw config, overlay known sections, update internalAgents.agents
+    const updatedConfig = {
+        ...rawConfig,
+        version: effective.config.version,
+        features: { ...effective.config.features },
+        runtimeProfiles: { ...effective.config.runtimeProfiles },
+        internalAgents: {
+            defaultRuntime: effective.config.internalAgents.defaultRuntime,
+            agents: agentsMap,
+        },
+        ui: { ...effective.config.ui },
+    };
+    // 7. Validate the updated config before writing
+    const validation = validatePdConfig(updatedConfig);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            statusCode: 400,
+            error: 'bad_request',
+            message: `Updated config would be invalid: ${validation.errors.map(e => e.reason).join('; ')}`,
+        };
+    }
+    // 8. Write to disk (atomic: write to tmp, then rename)
+    writeConfigAtomic(configPath, updatedConfig);
+    return {
+        ok: true,
+        agent: agentName,
+        runtimeProfile,
+        enabled,
+    };
+}
+export function updateDefaultRuntime(workspaceDir, payload) {
+    // 1. Validate payload
+    if (!isRecord(payload)) {
+        return { ok: false, statusCode: 400, error: 'bad_request', message: 'Payload must be a JSON object with a defaultRuntime field' };
+    }
+    const defaultRuntimeRaw = Object.hasOwn(payload, 'defaultRuntime') ? payload.defaultRuntime : undefined;
+    if (defaultRuntimeRaw === undefined) {
+        return { ok: false, statusCode: 400, error: 'bad_request', message: 'Missing required field: defaultRuntime' };
+    }
+    if (typeof defaultRuntimeRaw !== 'string' || defaultRuntimeRaw.length === 0) {
+        return { ok: false, statusCode: 400, error: 'bad_request', message: 'defaultRuntime must be a non-empty string' };
+    }
+    // ANY-segment secret key detection (ERR-045)
+    const secretPath = hasSecretLikeKeyDeep(payload);
+    if (secretPath) {
+        return { ok: false, statusCode: 400, error: 'bad_request', message: `Payload contains secret-like field '${secretPath}'. Remove secret fields from the request.` };
+    }
+    // 2. Load existing config
+    const loadResult = loadPdConfig(workspaceDir);
+    // 3. If malformed, refuse to write
+    if (!loadResult.ok) {
+        return {
+            ok: false,
+            statusCode: 409,
+            error: 'conflict',
+            message: `Cannot update default runtime: existing .pd/config.yaml is malformed. Fix config errors first. Errors: ${loadResult.errors.map(e => e.reason).join('; ')}`,
+        };
+    }
+    const { effective } = loadResult;
+    // 4. Validate runtime profile reference exists
+    if (!Object.hasOwn(effective.config.runtimeProfiles, defaultRuntimeRaw)) {
+        return {
+            ok: false,
+            statusCode: 400,
+            error: 'bad_request',
+            message: `Runtime profile '${defaultRuntimeRaw}' does not exist. Available profiles: ${Object.keys(effective.config.runtimeProfiles).join(', ')}`,
+        };
+    }
+    // 5. Build updated config — read original file to preserve unknown root entries
+    //    and preserve agent inheritance (agents without explicit runtimeProfile
+    //    should NOT get one written back — they inherit defaultRuntime)
+    const configPath = getPdConfigPath(workspaceDir);
+    let rawConfig;
+    let rawAgentsMap;
+    if (fs.existsSync(configPath)) {
+        const rawContent = fs.readFileSync(configPath, 'utf8');
+        const rawParsed = yaml.load(rawContent, { schema: yaml.JSON_SCHEMA });
+        if (isRecord(rawParsed)) {
+            rawConfig = { ...rawParsed };
+            // Extract the raw agents map from the file to preserve inheritance
+            const rawInternalAgents = rawParsed.internalAgents;
+            if (isRecord(rawInternalAgents) && Object.hasOwn(rawInternalAgents, 'agents')) {
+                const rawAgents = rawInternalAgents.agents;
+                if (isRecord(rawAgents)) {
+                    rawAgentsMap = rawAgents;
+                }
+            }
+        }
+        else {
+            rawConfig = {};
+        }
+    }
+    else {
+        rawConfig = {};
+    }
+    // Build agents map preserving ONLY explicit overrides from the original file.
+    // Agents that omit runtimeProfile in the file should continue to inherit
+    // defaultRuntime — we must NOT write back the effective (resolved) value.
+    // Only write agents that already exist in the file — do not add new ones.
+    const agentsMap = {};
+    if (rawAgentsMap) {
+        for (const name of Object.keys(rawAgentsMap)) {
+            const rawEntry = rawAgentsMap[name];
+            if (!isRecord(rawEntry))
+                continue;
+            // Preserve enabled if present, default to true
+            const enabledRaw = Object.hasOwn(rawEntry, 'enabled') ? rawEntry.enabled : undefined;
+            const enabled = typeof enabledRaw === 'boolean' ? enabledRaw : true;
+            // Only include runtimeProfile if the original file had an explicit one
+            const hasExplicitProfile = Object.hasOwn(rawEntry, 'runtimeProfile')
+                && typeof rawEntry.runtimeProfile === 'string'
+                && (rawEntry.runtimeProfile).length > 0;
+            agentsMap[name] = {
+                enabled,
+                ...(hasExplicitProfile ? { runtimeProfile: rawEntry.runtimeProfile } : {}),
+            };
+        }
+    }
+    else {
+        // No agents in file — write nothing (all agents inherit default)
+    }
+    // Merge: update only defaultRuntime, preserve agent overrides
+    const updatedConfig = {
+        ...rawConfig,
+        version: effective.config.version,
+        features: { ...effective.config.features },
+        runtimeProfiles: { ...effective.config.runtimeProfiles },
+        internalAgents: {
+            defaultRuntime: defaultRuntimeRaw,
+            agents: agentsMap,
+        },
+        ui: { ...effective.config.ui },
+    };
+    // 6. Validate the updated config before writing
+    const validation = validatePdConfig(updatedConfig);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            statusCode: 400,
+            error: 'bad_request',
+            message: `Updated config would be invalid: ${validation.errors.map(e => e.reason).join('; ')}`,
+        };
+    }
+    // 7. Write to disk (atomic)
+    writeConfigAtomic(configPath, updatedConfig);
+    return {
+        ok: true,
+        defaultRuntime: defaultRuntimeRaw,
+    };
+}
+// ── Principles Output Language (PRI-332 P1-1) ─────────────────────────────
+/** Valid values for principles.outputLanguage in config.yaml */
+export const VALID_OUTPUT_LANGUAGES = ['zh-CN', 'en'];
+function isValidOutputLanguage(value) {
+    return typeof value === 'string' && VALID_OUTPUT_LANGUAGES.includes(value);
+}
+/** Default output language when not configured. */
+const DEFAULT_OUTPUT_LANGUAGE = 'zh-CN';
+/**
+ * Read principles.outputLanguage from config.yaml.
+ * Returns default ('zh-CN') when not set.
+ * Fail loud if set to an invalid value (ERR-009).
+ */
+export function getPrinciplesOutputLanguage(workspaceDir) {
+    const configPath = getPdConfigPath(workspaceDir);
+    if (!fs.existsSync(configPath)) {
+        return { ok: true, outputLanguage: DEFAULT_OUTPUT_LANGUAGE, source: 'default' };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: 'read_error', statusCode: 500, message: `Failed to read config: ${message}`, nextAction: 'Check file permissions for .pd/config.yaml' };
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: 'yaml_error', statusCode: 500, message: `YAML parse error: ${message}`, nextAction: 'Fix YAML syntax in .pd/config.yaml' };
+    }
+    if (!isRecord(parsed)) {
+        return { ok: true, outputLanguage: DEFAULT_OUTPUT_LANGUAGE, source: 'default' };
+    }
+    // Extract principles section — unknown-first, no `as` bypass (ERR-001)
+    const principlesRaw = Object.hasOwn(parsed, 'principles') ? parsed.principles : undefined;
+    if (principlesRaw === undefined) {
+        return { ok: true, outputLanguage: DEFAULT_OUTPUT_LANGUAGE, source: 'default' };
+    }
+    if (!isRecord(principlesRaw)) {
+        return {
+            ok: false,
+            error: 'invalid_config',
+            statusCode: 500,
+            message: 'principles section must be a mapping',
+            nextAction: 'Fix principles section in .pd/config.yaml to be a YAML mapping',
+        };
+    }
+    const outputLangRaw = Object.hasOwn(principlesRaw, 'outputLanguage') ? principlesRaw.outputLanguage : undefined;
+    if (outputLangRaw === undefined) {
+        return { ok: true, outputLanguage: DEFAULT_OUTPUT_LANGUAGE, source: 'default' };
+    }
+    if (!isValidOutputLanguage(outputLangRaw)) {
+        return {
+            ok: false,
+            error: 'invalid_output_language',
+            statusCode: 500,
+            message: `principles.outputLanguage must be one of: ${VALID_OUTPUT_LANGUAGES.join(', ')}. Got: ${String(outputLangRaw)}`,
+            nextAction: `Set principles.outputLanguage to one of: ${VALID_OUTPUT_LANGUAGES.join(', ')}`,
+        };
+    }
+    return { ok: true, outputLanguage: outputLangRaw, source: 'user_config' };
+}
+/**
+ * Update principles.outputLanguage in config.yaml.
+ * Safe partial write: preserves unknown sections, validates before write.
+ */
+export function updatePrinciplesOutputLanguage(workspaceDir, payload) {
+    // 1. Validate payload
+    if (!isRecord(payload)) {
+        return { ok: false, error: 'bad_request', statusCode: 400, message: 'Payload must be a JSON object with an outputLanguage field', nextAction: 'Send { outputLanguage: "zh-CN" } or { outputLanguage: "en" }' };
+    }
+    const outputLangRaw = Object.hasOwn(payload, 'outputLanguage') ? payload.outputLanguage : undefined;
+    if (outputLangRaw === undefined) {
+        return { ok: false, error: 'bad_request', statusCode: 400, message: 'Missing required field: outputLanguage', nextAction: `Send { outputLanguage: "${DEFAULT_OUTPUT_LANGUAGE}" }` };
+    }
+    if (!isValidOutputLanguage(outputLangRaw)) {
+        return {
+            ok: false,
+            error: 'bad_request',
+            statusCode: 400,
+            message: `outputLanguage must be one of: ${VALID_OUTPUT_LANGUAGES.join(', ')}. Got: ${String(outputLangRaw)}`,
+            nextAction: `Set outputLanguage to one of: ${VALID_OUTPUT_LANGUAGES.join(', ')}`,
+        };
+    }
+    // 2. Read raw config to preserve unknown sections
+    const configPath = getPdConfigPath(workspaceDir);
+    let rawConfig;
+    if (fs.existsSync(configPath)) {
+        let rawContent;
+        try {
+            rawContent = fs.readFileSync(configPath, 'utf8');
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { ok: false, error: 'read_error', statusCode: 500, message: `Failed to read config for update: ${message}`, nextAction: 'Check file permissions for .pd/config.yaml' };
+        }
+        let rawParsed;
+        try {
+            rawParsed = yaml.load(rawContent, { schema: yaml.JSON_SCHEMA });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { ok: false, error: 'yaml_error', statusCode: 500, message: `YAML parse error during update: ${message}`, nextAction: 'Fix YAML syntax in .pd/config.yaml' };
+        }
+        if (isRecord(rawParsed)) {
+            rawConfig = { ...rawParsed };
+        }
+        else {
+            rawConfig = {};
+        }
+    }
+    else {
+        rawConfig = {};
+    }
+    // 3. Update principles.outputLanguage
+    const existingPrinciples = isRecord(rawConfig.principles) ? { ...rawConfig.principles } : {};
+    existingPrinciples.outputLanguage = outputLangRaw;
+    rawConfig.principles = existingPrinciples;
+    // 4. Validate via core (principles is an unknown section — safe to pass through)
+    const validation = validatePdConfig(rawConfig);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            error: 'validation_error',
+            statusCode: 500,
+            message: `Updated config would be invalid: ${validation.errors.map(e => e.reason).join('; ')}`,
+            nextAction: 'Fix config validation errors before retrying',
+        };
+    }
+    // 5. Atomic write
+    try {
+        writeConfigAtomic(configPath, rawConfig);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: 'write_error', statusCode: 500, message: `Failed to write config: ${message}`, nextAction: 'Check disk space and file permissions for .pd/config.yaml' };
+    }
+    return { ok: true, outputLanguage: outputLangRaw, source: 'user_config' };
+}
+// ── Check Readiness ──────────────────────────────────────────────────────────
+export function checkReadiness(workspaceDir, agentName, getEnvVar = (name) => process.env[name]) {
+    // 1. Validate agent name
+    if (!isValidAgentName(agentName)) {
+        return {
+            ok: false,
+            statusCode: 404,
+            error: 'not_found',
+            message: `Unknown agent name '${agentName}'. Valid agents: ${INTERNAL_AGENT_NAMES.join(', ')}`,
+        };
+    }
+    // 2. Load config — if malformed, return unknown (not defaults pretending normal)
+    const loadResult = loadPdConfig(workspaceDir);
+    if (!loadResult.ok) {
+        return {
+            ok: true,
+            agent: agentName,
+            readiness: 'unknown',
+            profileId: '',
+            profileLabel: '',
+            reason: `Config file is malformed: ${loadResult.errors[0]?.reason ?? 'unknown error'}`,
+            nextAction: 'Fix .pd/config.yaml errors before checking readiness',
+        };
+    }
+    const { effective } = loadResult;
+    // 3. Resolve agent binding
+    const bindingResult = resolveAgentRuntimeBinding(effective, agentName);
+    if (!bindingResult.ok) {
+        // Agent is disabled or profile not found
+        // Use the agent's override profile id if present, otherwise default
+        const unresolvedProfileId = effective.config.internalAgents.agents[agentName]?.runtimeProfile
+            ?? effective.config.internalAgents.defaultRuntime;
+        const resolvedProfileId = bindingResult.readiness === 'disabled'
+            ? effective.config.internalAgents.defaultRuntime
+            : unresolvedProfileId;
+        const resolvedProfile = effective.config.runtimeProfiles[resolvedProfileId];
+        // If profile not found, label must clearly indicate the missing profile
+        const profileLabel = resolvedProfile
+            ? buildProfileLabel(resolvedProfileId, resolvedProfile)
+            : `unknown:${resolvedProfileId}`;
+        return {
+            ok: true,
+            agent: agentName,
+            readiness: bindingResult.readiness,
+            profileId: resolvedProfileId,
+            profileLabel,
+            reason: bindingResult.reason,
+            nextAction: bindingResult.nextAction,
+        };
+    }
+    // 4. Check runtime readiness
+    const readinessResult = checkAgentRuntimeReadiness(bindingResult.profile, getEnvVar);
+    return {
+        ok: true,
+        agent: agentName,
+        readiness: readinessResult.readiness,
+        profileId: bindingResult.profileId,
+        profileLabel: buildProfileLabel(bindingResult.profileId, bindingResult.profile),
+        reason: readinessResult.reason,
+        nextAction: readinessResult.nextAction,
+    };
+}