dsh-agy-cli 0.0.0-stage → 0.12.0

package/lib/doctor.js

@@ -0,0 +1,923 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+import { redactText } from './agy/redact.js';
+import { getAgentPreset, listAgentPresets, readAgentPresetTemplate, } from './agent-presets.js';
+import { diagnoseProvider, } from './diagnostics.js';
+import { Config } from './provider/config.js';
+const require = createRequire(import.meta.url);
+function loadPackageMetadata() {
+    try {
+        return require('../package.json');
+    }
+    catch {
+        return {};
+    }
+}
+const packageMetadata = loadPackageMetadata();
+const PROFILE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const AGENT_WRITE_TOOLS = new Set([
+    'multi_replace_file_content',
+    'replace_file_content',
+    'write_to_file',
+]);
+function isSafeProfileName(value) {
+    return PROFILE_NAME_PATTERN.test(value);
+}
+function resolveDshInvocation(value) {
+    if (process.platform !== 'win32' || !/\.cmd$/i.test(value)) {
+        if (/\.(?:c|m)?js$/i.test(value))
+            return { executable: process.execPath, prefixArgs: [value] };
+        return { executable: value, prefixArgs: [] };
+    }
+    if (/[\\/]/.test(value)) {
+        const entry = join(dirname(value), '..', '@deepseek-ai', 'dsh', 'lib', 'bin.js');
+        if (existsSync(entry))
+            return { executable: process.execPath, prefixArgs: [entry] };
+    }
+    // npm's Windows .cmd shims cannot be spawned directly with shell=false.
+    // Keep shell=false and invoke the shim through the Windows command
+    // interpreter; profile names and DSH_HOME are passed as regular argv/env.
+    return {
+        executable: process.env.ComSpec ?? process.env.COMSPEC ?? 'cmd.exe',
+        prefixArgs: ['/d', '/s', '/c', 'call', value],
+    };
+}
+function killProcessTree(child) {
+    if (child.pid === undefined)
+        return;
+    if (process.platform === 'win32') {
+        const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], {
+            shell: false,
+            windowsHide: true,
+            stdio: 'ignore',
+        });
+        killer.once('error', () => child.kill());
+        return;
+    }
+    try {
+        process.kill(-child.pid, 'SIGKILL');
+    }
+    catch {
+        child.kill('SIGKILL');
+    }
+}
+function defaultRunCommand(executable, args, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const maxOutputBytes = 1024 * 1024;
+    return new Promise(resolve => {
+        let stdout = '';
+        let stderr = '';
+        let totalBytes = 0;
+        let timedOut = false;
+        let settled = false;
+        const child = spawn(executable, args, {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            shell: false,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killProcessTree(child);
+        }, timeoutMs);
+        const finish = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ exitCode, stdout, stderr, timedOut });
+        };
+        child.stdout?.setEncoding('utf8');
+        child.stderr?.setEncoding('utf8');
+        let stderrBytes = 0;
+        child.stdout?.on('data', chunk => {
+            totalBytes += Buffer.byteLength(chunk, 'utf8');
+            if (totalBytes <= maxOutputBytes)
+                stdout += chunk;
+        });
+        child.stderr?.on('data', chunk => {
+            // Counted incrementally like stdout: re-measuring the whole accumulated
+            // string per chunk is quadratic on a chatty child.
+            stderrBytes += Buffer.byteLength(chunk, 'utf8');
+            if (stderrBytes <= maxOutputBytes)
+                stderr += chunk;
+        });
+        child.once('error', () => finish(null));
+        child.once('close', exitCode => finish(exitCode));
+    });
+}
+function resolveDshHome(customHome) {
+    const envHome = process.env.DSH_HOME?.trim();
+    if (customHome !== undefined && customHome.trim().length > 0)
+        return customHome.trim();
+    if (envHome !== undefined && envHome.length > 0)
+        return envHome;
+    return join(homedir(), '.dsh');
+}
+function stripDumpValue(value) {
+    const withoutComment = value.replace(/\s+#.*$/, '').trim();
+    if (withoutComment.length >= 2) {
+        const first = withoutComment[0];
+        const last = withoutComment.at(-1);
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return withoutComment.slice(1, -1);
+        }
+    }
+    return withoutComment;
+}
+/** Parse only the provider bundle section; this is intentionally not a general YAML parser. */
+function parseDumpConfig(stdout) {
+    const values = {};
+    let recognized = false;
+    let malformed = false;
+    let inBundleSection = false;
+    const stack = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        if (/^\s*#\s*==\s*dsh-agy-cli\b/i.test(line)
+            || /^\s*-\s*id:\s*dsh-agy-cli\b/i.test(line)
+            || /^\s*id:\s*dsh-agy-cli\b/i.test(line)) {
+            recognized = true;
+            inBundleSection = true;
+            stack.length = 0;
+            continue;
+        }
+        if (inBundleSection && /^\s*#\s*==\s+/.test(line)) {
+            inBundleSection = false;
+            stack.length = 0;
+            continue;
+        }
+        if (!inBundleSection || line.trim().length === 0 || line.trim().startsWith('#'))
+            continue;
+        const match = /^(\s*)([A-Za-z][A-Za-z0-9_-]*):(?:\s*(.*))?$/.exec(line);
+        if (/^\s*-\s+/.test(line))
+            continue;
+        if (match === null || match[1] === undefined || match[2] === undefined) {
+            malformed = true;
+            continue;
+        }
+        const indent = match[1].replace(/\t/g, '  ').length;
+        while (stack.length > 0 && (stack.at(-1)?.indent ?? -1) >= indent)
+            stack.pop();
+        const path = [...stack.map(entry => entry.key), match[2]].join('.');
+        const rawValue = match[3]?.trim() ?? '';
+        values[path] = stripDumpValue(rawValue);
+        if (rawValue.length === 0)
+            stack.push({ indent, key: match[2] });
+    }
+    return { recognized, malformed, values };
+}
+function normalizeConfigValues(values) {
+    const normalized = { ...values };
+    for (const [key, value] of Object.entries(values)) {
+        if (key.startsWith('config.')) {
+            const shortKey = key.slice('config.'.length);
+            if (normalized[shortKey] === undefined)
+                normalized[shortKey] = value;
+        }
+    }
+    return normalized;
+}
+function valueOf(values, key) {
+    const value = values[key];
+    return value === undefined || value.length === 0 ? null : value;
+}
+function booleanValue(value) {
+    if (value === null)
+        return null;
+    if (value.toLowerCase() === 'true')
+        return true;
+    if (value.toLowerCase() === 'false')
+        return false;
+    return null;
+}
+function numberValue(value) {
+    if (value === null || !/^\d+$/.test(value))
+        return null;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) ? parsed : null;
+}
+function listValue(value) {
+    if (value === null)
+        return [];
+    const normalized = value.trim().replace(/^\[/, '').replace(/\]$/, '').trim();
+    if (normalized.length === 0)
+        return [];
+    return normalized.split(',').map(item => stripDumpValue(item.trim())).filter(Boolean);
+}
+function workspaceStatus(value) {
+    if (value === null || value.trim().length === 0)
+        return value === null ? 'unknown' : 'missing';
+    try {
+        return statSync(value).isDirectory() ? 'configured' : 'not-directory';
+    }
+    catch {
+        return 'missing';
+    }
+}
+function routeFromDump(values, purpose) {
+    const prefix = `purposeRoutes.${purpose}.`;
+    const configured = Object.keys(values).some(key => key.startsWith(prefix));
+    if (!configured)
+        return null;
+    const model = valueOf(values, `${prefix}model`);
+    const agent = valueOf(values, `${prefix}agent`);
+    const reasoningEffort = valueOf(values, `${prefix}reasoningEffort`);
+    return {
+        configured: true,
+        complete: model !== null && agent !== null && reasoningEffort !== null,
+        model,
+        agent,
+        reasoningEffort,
+    };
+}
+function emptyEffective(dumpStatus) {
+    return {
+        dumpStatus,
+        provider: null,
+        model: null,
+        agent: null,
+        agentPreset: null,
+        sessionMode: null,
+        retryPolicy: null,
+        purposeRoutes: { compaction: null, sessionTitle: null },
+        workspaceRootStatus: 'unknown',
+        workspaceSource: 'unknown',
+        visibleModels: { raw: null, count: null, filtered: false },
+        modelEffortSplit: { baseModel: null, suffixDetected: false, normalized: false },
+        imageInput: null,
+        modelCapability: { inputModalities: ['text'], imageBridge: 'unknown' },
+        agentCapability: {
+            knownPreset: null,
+            frontmatterValid: null,
+            tools: [],
+            viewFile: null,
+            writeTools: null,
+            commandExecutionPolicy: null,
+            mcpServersEmpty: null,
+            subagent: null,
+        },
+        dshContext: {
+            source: 'profile-dump',
+            session: { state: 'not-probed', required: false },
+            workspace: { state: 'not-probed', configured: false },
+            permission: { state: 'not-probed', preset: null },
+            approval: { state: 'not-probed', policy: null },
+            services: {
+                sessions: 'not-probed',
+                workspaceRegistry: 'not-probed',
+                sandboxPolicy: 'not-probed',
+                permissionPresets: 'not-probed',
+                approval: 'not-probed',
+            },
+        },
+        bridgeCapability: {
+            owner: 'unknown',
+            enabled: null,
+            agent: null,
+            internalTools: 'unknown',
+            schemaCapability: 'unknown',
+            legacyConfig: { agyOwned: false, workspaceRootConfigured: false },
+        },
+    };
+}
+function bridgeCapabilityFromConfig(toolPolicy, bundleEnabled, configuredAgent, agentCapability, workspaceRootStatus) {
+    const workspaceRootConfigured = workspaceRootStatus === 'configured';
+    if (toolPolicy === 'dsh-owned') {
+        return {
+            owner: 'dsh',
+            enabled: bundleEnabled,
+            agent: 'dsh-agy-tool-free',
+            internalTools: 'empty',
+            schemaCapability: 'prompt-contract-v1',
+            legacyConfig: { agyOwned: false, workspaceRootConfigured },
+        };
+    }
+    if (toolPolicy === 'agy-owned') {
+        const internalTools = agentCapability.frontmatterValid === true
+            && agentCapability.commandExecutionPolicy === 'off'
+            && agentCapability.mcpServersEmpty === true
+            && agentCapability.subagent === false
+            ? 'empty'
+            : agentCapability.frontmatterValid === false ? 'present' : 'unknown';
+        return {
+            owner: 'agy',
+            enabled: bundleEnabled,
+            agent: configuredAgent,
+            internalTools,
+            schemaCapability: 'agy-owned',
+            legacyConfig: { agyOwned: true, workspaceRootConfigured },
+        };
+    }
+    if (toolPolicy === 'reject') {
+        return {
+            owner: 'none',
+            enabled: bundleEnabled,
+            agent: configuredAgent,
+            internalTools: 'unknown',
+            schemaCapability: 'unsupported',
+            legacyConfig: { agyOwned: false, workspaceRootConfigured },
+        };
+    }
+    return {
+        owner: 'unknown',
+        enabled: bundleEnabled,
+        agent: configuredAgent,
+        internalTools: 'unknown',
+        schemaCapability: 'unknown',
+        legacyConfig: { agyOwned: false, workspaceRootConfigured },
+    };
+}
+function effectiveFromDump(parsed, dumpStatus) {
+    const values = normalizeConfigValues(parsed.values);
+    const imageInput = valueOf(values, 'imageInput');
+    const retryMax = valueOf(values, 'retryPolicy.maxRetries');
+    const retryCodes = valueOf(values, 'retryPolicy.retryableCodes');
+    const toolPolicy = valueOf(values, 'toolPolicy');
+    const bundleEnabled = booleanValue(valueOf(values, 'enabled'));
+    const workspaceRootStatus = workspaceStatus(valueOf(values, 'workspaceRoot'));
+    const workspaceSource = toolPolicy === 'dsh-owned' ? 'dsh-session-cwd' : workspaceRootStatus === 'configured' ? 'config-legacy' : 'unknown';
+    const rawVisible = valueOf(values, 'visibleModels');
+    const visibleCount = rawVisible === null ? null : (() => { try {
+        const v = JSON.parse(rawVisible);
+        return Array.isArray(v) ? v.length : null;
+    }
+    catch {
+        return rawVisible.length > 0 ? 1 : 0;
+    } })();
+    const rawModel = valueOf(values, 'model');
+    const suffixDetected = rawModel !== null && /-(?:low|medium|high)$/i.test(rawModel);
+    const baseModel = rawModel !== null ? rawModel.replace(/-(?:low|medium|high)$/i, '') : null;
+    const configuredAgent = valueOf(values, 'agent');
+    return {
+        dumpStatus,
+        provider: valueOf(values, 'provider'),
+        model: valueOf(values, 'model'),
+        agent: valueOf(values, 'agent'),
+        agentPreset: valueOf(values, 'agentPreset'),
+        sessionMode: valueOf(values, 'sessionMode'),
+        retryPolicy: retryMax === null && retryCodes === null
+            ? null
+            : { maxRetries: numberValue(retryMax), retryableCodes: listValue(retryCodes) },
+        purposeRoutes: {
+            compaction: routeFromDump(values, 'compaction'),
+            sessionTitle: routeFromDump(values, 'sessionTitle'),
+        },
+        workspaceRootStatus,
+        workspaceSource,
+        visibleModels: { raw: rawVisible, count: visibleCount, filtered: visibleCount !== null && visibleCount > 0 },
+        modelEffortSplit: { baseModel, suffixDetected, normalized: suffixDetected ? baseModel !== rawModel : false },
+        imageInput,
+        modelCapability: {
+            inputModalities: imageInput === 'experimental' ? ['text', 'image'] : ['text'],
+            imageBridge: imageInput === 'off' ? 'off' : imageInput === 'experimental' ? 'experimental' : 'unknown',
+        },
+        agentCapability: emptyEffective(dumpStatus).agentCapability,
+        dshContext: {
+            source: 'profile-dump',
+            session: { state: 'not-probed', required: toolPolicy === 'dsh-owned' },
+            workspace: { state: 'not-probed', configured: workspaceRootStatus === 'configured' },
+            permission: { state: 'not-probed', preset: null },
+            approval: { state: 'not-probed', policy: null },
+            services: {
+                sessions: 'not-probed',
+                workspaceRegistry: 'not-probed',
+                sandboxPolicy: 'not-probed',
+                permissionPresets: 'not-probed',
+                approval: 'not-probed',
+            },
+        },
+        bridgeCapability: bridgeCapabilityFromConfig(toolPolicy, bundleEnabled, configuredAgent, emptyEffective(dumpStatus).agentCapability, workspaceRootStatus),
+    };
+}
+function parseAgentFrontmatter(source) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source);
+    if (match === null || match[1] === undefined) {
+        return { name: null, tools: null, commandExecutionPolicy: null, mcpServersEmpty: null, subagent: null };
+    }
+    let name = null;
+    let tools = null;
+    let commandExecutionPolicy = null;
+    let mcpServersEmpty = null;
+    let subagent = null;
+    let collectingTools = false;
+    for (const line of match[1].split(/\r?\n/)) {
+        const listItem = /^\s*-\s*(.+?)\s*$/.exec(line);
+        if (collectingTools && listItem?.[1] !== undefined) {
+            tools ??= [];
+            tools.push(stripDumpValue(listItem[1]));
+            continue;
+        }
+        const field = /^([A-Za-z][A-Za-z0-9_-]*):(?:\s*(.*))?$/.exec(line);
+        if (field === null || field[1] === undefined)
+            continue;
+        collectingTools = field[1] === 'tools' && (field[2] ?? '').trim().length === 0;
+        const rawValue = stripDumpValue(field[2]?.trim() ?? '');
+        if (field[1] === 'name')
+            name = rawValue || null;
+        if (field[1] === 'tools' && !collectingTools)
+            tools = [...listValue(rawValue)];
+        if (field[1] === 'commandExecutionPolicy')
+            commandExecutionPolicy = rawValue || null;
+        if (field[1] === 'mcpServers')
+            mcpServersEmpty = rawValue === '[]';
+        if (field[1] === 'subagent')
+            subagent = booleanValue(rawValue);
+    }
+    return { name, tools, commandExecutionPolicy, mcpServersEmpty, subagent };
+}
+function presetForAgent(agent, agentPreset) {
+    return getAgentPreset(agentPreset) ?? listAgentPresets().find(preset => preset.agentName === agent);
+}
+async function inspectAgent(agent, agentPreset) {
+    const preset = presetForAgent(agent, agentPreset);
+    if (preset === undefined) {
+        return {
+            capability: {
+                knownPreset: agent === null ? null : false,
+                frontmatterValid: agent === null ? null : null,
+                tools: [],
+                viewFile: agent === null ? null : false,
+                writeTools: agent === null ? null : false,
+                commandExecutionPolicy: null,
+                mcpServersEmpty: null,
+                subagent: null,
+            },
+            ...(agent === null ? {} : {
+                suggestion: `Install or inspect the selected Agent explicitly; bundled options: ${listAgentPresets().map(item => item.id).join(', ')}`,
+            }),
+        };
+    }
+    try {
+        const frontmatter = parseAgentFrontmatter(await readAgentPresetTemplate(preset));
+        const actualTools = frontmatter.tools ?? [];
+        const toolsMatch = actualTools.length === preset.tools.length
+            && actualTools.every((tool, index) => tool === preset.tools[index]);
+        const valid = frontmatter.name === preset.agentName
+            && toolsMatch
+            && frontmatter.commandExecutionPolicy === 'off'
+            && frontmatter.mcpServersEmpty === true
+            && frontmatter.subagent === false;
+        const capability = {
+            knownPreset: true,
+            frontmatterValid: valid,
+            tools: actualTools,
+            viewFile: actualTools.includes('view_file'),
+            writeTools: actualTools.some(tool => AGENT_WRITE_TOOLS.has(tool)),
+            commandExecutionPolicy: frontmatter.commandExecutionPolicy,
+            mcpServersEmpty: frontmatter.mcpServersEmpty,
+            subagent: frontmatter.subagent,
+        };
+        return valid
+            ? { capability }
+            : {
+                capability,
+                issue: {
+                    component: 'profile',
+                    code: 'PROFILE_AGENT_FRONTMATTER_INVALID',
+                    message: `Bundled Agent ${preset.agentName} does not match its declared tool and execution policy`,
+                },
+                suggestion: `Reinstall the bundled Agent with: npx dsh-agy-cli agents install ${preset.id} --apply`,
+            };
+    }
+    catch {
+        return {
+            capability: {
+                knownPreset: true,
+                frontmatterValid: false,
+                tools: [],
+                viewFile: preset.tools.includes('view_file'),
+                writeTools: preset.tools.some(tool => AGENT_WRITE_TOOLS.has(tool)),
+                commandExecutionPolicy: null,
+                mcpServersEmpty: null,
+                subagent: null,
+            },
+            issue: {
+                component: 'profile',
+                code: 'PROFILE_AGENT_FRONTMATTER_UNREADABLE',
+                message: `Could not read the bundled Agent template for ${preset.agentName}`,
+            },
+            suggestion: `Reinstall the bundled Agent with: npx dsh-agy-cli agents install ${preset.id} --apply`,
+        };
+    }
+}
+export async function diagnoseProfile(options) {
+    const profileName = options.profileName.trim();
+    const dshHome = resolveDshHome(options.dshHome);
+    const dshHomePresent = existsSync(dshHome);
+    const validProfileName = isSafeProfileName(profileName);
+    const profileDir = validProfileName ? join(dshHome, 'profiles', profileName) : '';
+    const profilePresent = dshHomePresent && existsSync(profileDir);
+    const issues = [];
+    if (!validProfileName) {
+        return {
+            profileSchemaVersion: 4,
+            name: '<invalid>',
+            dshHomePresent,
+            profilePresent: false,
+            packageInstalled: false,
+            bundleDeclared: false,
+            bundleEnabled: null,
+            toolPolicy: null,
+            effectiveProvider: null,
+            effectiveModel: null,
+            effective: emptyEffective('not-run'),
+            repairSuggestions: [],
+            issues: [{
+                    component: 'profile',
+                    code: 'PROFILE_NAME_INVALID',
+                    message: 'Profile name must contain 1-64 letters, numbers, dots, underscores, or hyphens and must not contain path separators',
+                }],
+        };
+    }
+    let packageInstalled = false;
+    let bundleDeclared = false;
+    let bundleEnabled = null;
+    let toolPolicy = null;
+    let effectiveProvider = null;
+    let effectiveModel = null;
+    let effective = emptyEffective('not-run');
+    const repairSuggestions = [];
+    const addSuggestion = (suggestion) => {
+        if (!repairSuggestions.includes(suggestion))
+            repairSuggestions.push(suggestion);
+    };
+    if (!dshHomePresent) {
+        issues.push({
+            component: 'profile',
+            code: 'DSH_HOME_NOT_FOUND',
+            message: `DSH home directory not found: run DSH once or set DSH_HOME`,
+        });
+    }
+    else if (!profilePresent) {
+        issues.push({
+            component: 'profile',
+            code: 'PROFILE_NOT_FOUND',
+            message: `Profile "${profileName}" not found. Create with: npx @deepseek-ai/dsh plugin --profile ${profileName} add dsh-agy-cli`,
+        });
+    }
+    else {
+        const profilePackageJsonPath = join(profileDir, 'package.json');
+        if (existsSync(profilePackageJsonPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(profilePackageJsonPath, 'utf8'));
+                const deps = pkg.dependencies ?? {};
+                const devDeps = pkg.devDependencies ?? {};
+                packageInstalled = Boolean(deps['dsh-agy-cli'] || devDeps['dsh-agy-cli']);
+                const bundles = pkg.dsh?.profile?.bundles;
+                bundleDeclared = Array.isArray(bundles) && bundles.includes('dsh-agy-cli');
+            }
+            catch {
+                issues.push({
+                    component: 'profile',
+                    code: 'PROFILE_PACKAGE_JSON_INVALID',
+                    message: `Could not parse package.json for profile "${profileName}"`,
+                });
+            }
+        }
+        if (!packageInstalled) {
+            issues.push({
+                component: 'profile',
+                code: 'PROFILE_PACKAGE_MISSING',
+                message: `Package dsh-agy-cli is not installed in profile "${profileName}". Run: npx @deepseek-ai/dsh plugin --profile ${profileName} add dsh-agy-cli`,
+            });
+        }
+        else if (!bundleDeclared) {
+            issues.push({
+                component: 'profile',
+                code: 'PROFILE_BUNDLE_MISSING',
+                message: `Bundle dsh-agy-cli is not declared in dsh.profile.bundles for profile "${profileName}". Re-run: npx @deepseek-ai/dsh plugin --profile ${profileName} add dsh-agy-cli`,
+            });
+        }
+        // Inspect effective dump-config. Failure is part of the diagnostic result;
+        // it must not silently turn into a false "unknown but healthy" profile.
+        const runCmd = options.runCommand ?? defaultRunCommand;
+        const customBin = options.dshBin?.trim() || process.env.DSH_BIN?.trim();
+        const dshCandidates = [
+            ...(customBin ? [customBin] : []),
+            join(profileDir, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js'),
+            join(dirname(profileDir), '..', 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js'),
+        ];
+        const pathDshCommand = process.platform === 'win32' ? 'dsh.cmd' : 'dsh';
+        const dshEntry = options.runCommand !== undefined
+            ? (customBin ?? pathDshCommand)
+            : dshCandidates.find(p => existsSync(p))
+                ?? pathDshCommand;
+        // dshEntry always resolves (the PATH fallback is unconditional), so there
+        // is no "missing" branch to guard: a dump is always attempted.
+        let dumpStatus = 'not-run';
+        {
+            try {
+                const invocation = resolveDshInvocation(dshEntry);
+                const args = [...invocation.prefixArgs, '--profile', profileName, '--dump-config'];
+                const dumpResult = await runCmd(invocation.executable, args, {
+                    timeoutMs: options.timeoutMs ?? 10_000,
+                    cwd: profileDir,
+                    env: { ...process.env, DSH_HOME: dshHome },
+                });
+                if (dumpResult.timedOut) {
+                    dumpStatus = 'timeout';
+                    issues.push({
+                        component: 'profile',
+                        code: 'PROFILE_DUMP_TIMEOUT',
+                        message: `DSH --dump-config timed out for profile "${profileName}"`,
+                    });
+                    addSuggestion(`Retry the read-only check: npx @deepseek-ai/dsh --profile ${profileName} --dump-config`);
+                }
+                else if (dumpResult.exitCode !== 0) {
+                    dumpStatus = 'nonzero';
+                    issues.push({
+                        component: 'profile',
+                        code: 'PROFILE_DUMP_NONZERO',
+                        message: `DSH --dump-config exited unsuccessfully for profile "${profileName}"`,
+                    });
+                    addSuggestion(`Run the read-only check directly: npx @deepseek-ai/dsh --profile ${profileName} --dump-config`);
+                }
+                else {
+                    const parsed = parseDumpConfig(dumpResult.stdout);
+                    if (!parsed.recognized || parsed.malformed) {
+                        dumpStatus = 'parse-error';
+                        issues.push({
+                            component: 'profile',
+                            code: 'PROFILE_DUMP_PARSE_FAILED',
+                            message: `DSH --dump-config did not contain a valid dsh-agy-cli section for profile "${profileName}"`,
+                        });
+                        addSuggestion(`Inspect the read-only dump format: npx @deepseek-ai/dsh --profile ${profileName} --dump-config`);
+                    }
+                    else {
+                        dumpStatus = 'ok';
+                        effective = effectiveFromDump(parsed, dumpStatus);
+                        const configValues = normalizeConfigValues(parsed.values);
+                        bundleEnabled = booleanValue(valueOf(configValues, 'enabled'));
+                        toolPolicy = valueOf(configValues, 'toolPolicy');
+                        effectiveProvider = effective.provider;
+                        effectiveModel = effective.model;
+                        const agentInspection = await inspectAgent(effective.agent, effective.agentPreset);
+                        effective = {
+                            ...effective,
+                            agentCapability: agentInspection.capability,
+                            bridgeCapability: bridgeCapabilityFromConfig(toolPolicy, bundleEnabled, effective.agent, agentInspection.capability, effective.workspaceRootStatus),
+                        };
+                        if (agentInspection.issue !== undefined)
+                            issues.push(agentInspection.issue);
+                        if (agentInspection.suggestion !== undefined)
+                            addSuggestion(agentInspection.suggestion);
+                        if (toolPolicy === 'agy-owned') {
+                            issues.push({
+                                component: 'profile',
+                                code: 'PROFILE_TOOL_POLICY_DEPRECATED',
+                                message: 'toolPolicy "agy-owned" is a legacy compatibility mode; DSH-owned execution is recommended and the profile was not changed',
+                            });
+                            addSuggestion('Set toolPolicy: dsh-owned after confirming the DSH permission and approval services are available');
+                        }
+                        if (toolPolicy === 'dsh-owned' && effective.bridgeCapability.internalTools === 'present') {
+                            issues.push({
+                                component: 'profile',
+                                code: 'DSH_BRIDGE_AGENT_INTERNAL_TOOLS',
+                                message: 'The DSH-owned bridge Agent exposes internal AGY tools; the bridge requires the bundled tool-free Agent',
+                            });
+                            addSuggestion('Use the bundled dsh-agy-tool-free Agent for toolPolicy: dsh-owned');
+                        }
+                        if (toolPolicy === 'reject' && bundleEnabled === true) {
+                            issues.push({
+                                component: 'profile',
+                                code: 'DSH_SCHEMA_UNSUPPORTED',
+                                message: 'The active profile rejects DSH tool schemas; tool bridge capability is unavailable until toolPolicy is explicitly selected',
+                            });
+                        }
+                        // 0.9.0: dsh-owned uses DSH session cwd, no workspaceRoot required; only warn for legacy agy-owned
+                        if (toolPolicy === 'dsh-owned' && effective.workspaceRootStatus === 'configured') {
+                            issues.push({
+                                component: 'profile',
+                                code: 'DEPRECATED_WORKSPACE_ROOT',
+                                message: 'workspaceRoot is deprecated for toolPolicy dsh-owned; DSH session workspace is used automatically',
+                            });
+                            addSuggestion('Remove workspaceRoot from profile; open the project folder in DSH and rely on session workspace');
+                        }
+                        if (effective.modelEffortSplit.suffixDetected) {
+                            issues.push({
+                                component: 'profile',
+                                code: 'DEPRECATED_MODEL_EFFORT_SUFFIX',
+                                message: `Model id "${effective.model}" contains -low/-medium/-high suffix; use base model "${effective.modelEffortSplit.baseModel}" and select reasoningEffort separately`,
+                            });
+                            addSuggestion('Set model to ' + effective.modelEffortSplit.baseModel + ' and choose reasoningEffort low/medium/high via DSH');
+                        }
+                        if (effective.agentCapability.writeTools === true
+                            && effective.workspaceRootStatus !== 'configured'
+                            && toolPolicy !== 'dsh-owned') {
+                            issues.push({
+                                component: 'profile',
+                                code: 'PROFILE_WORKSPACE_REQUIRED',
+                                message: 'The selected Agent can write files but no existing workspace directory is configured',
+                            });
+                            addSuggestion('Set workspaceRoot to an existing project directory before enabling workspace-write');
+                        }
+                        for (const purpose of ['compaction', 'sessionTitle']) {
+                            const route = effective.purposeRoutes[purpose];
+                            if (route?.complete === false) {
+                                issues.push({
+                                    component: 'profile',
+                                    code: 'PROFILE_PURPOSE_ROUTE_INCOMPLETE',
+                                    message: `Purpose route "${purpose}" is missing model, agent, or reasoningEffort`,
+                                });
+                                addSuggestion(`Complete or remove purposeRoutes.${purpose} in the profile configuration`);
+                            }
+                        }
+                        if (effective.retryPolicy !== null
+                            && (effective.retryPolicy.maxRetries === null || effective.retryPolicy.maxRetries > 5)) {
+                            issues.push({
+                                component: 'profile',
+                                code: 'PROFILE_RETRY_POLICY_INVALID',
+                                message: 'retryPolicy.maxRetries must be an integer from 0 through 5',
+                            });
+                            addSuggestion('Set retryPolicy.maxRetries to an integer from 0 through 5 in the profile configuration');
+                        }
+                    }
+                }
+            }
+            catch {
+                dumpStatus = 'unavailable';
+                issues.push({
+                    component: 'profile',
+                    code: 'PROFILE_DUMP_UNAVAILABLE',
+                    message: `Could not execute DSH --dump-config for profile "${profileName}"`,
+                });
+                addSuggestion(`Verify the DSH executable and retry: npx @deepseek-ai/dsh --profile ${profileName} --dump-config`);
+            }
+        }
+        if (dumpStatus !== 'ok')
+            effective = emptyEffective(dumpStatus);
+        // Check bundleEnabled and toolPolicy warnings
+        if (bundleEnabled === false) {
+            issues.push({
+                component: 'profile',
+                code: 'PROFILE_BUNDLE_DISABLED',
+                message: `Bundle dsh-agy-cli is disabled in profile "${profileName}". Enable in cordis.patch.yml or profile config`,
+            });
+        }
+        if (toolPolicy === 'reject' && profileName === 'web') {
+            issues.push({
+                component: 'profile',
+                code: 'PROFILE_TOOL_POLICY_REJECT',
+                message: `Profile "${profileName}" carries tool schemas by default, but toolPolicy is "reject". Set toolPolicy: dsh-owned to let DSH execute tools, or agy-owned for legacy AGY-owned execution`,
+            });
+        }
+    }
+    return {
+        profileSchemaVersion: 4,
+        name: profileName,
+        dshHomePresent,
+        profilePresent,
+        packageInstalled,
+        bundleDeclared,
+        bundleEnabled,
+        toolPolicy,
+        effectiveProvider,
+        effectiveModel,
+        effective,
+        repairSuggestions,
+        issues,
+    };
+}
+export async function runDoctor(options = {}) {
+    const providerResult = await diagnoseProvider(options);
+    let profileResult;
+    const profileName = options.profile?.trim();
+    if (profileName !== undefined && profileName.length > 0) {
+        profileResult = await diagnoseProfile({
+            profileName,
+            ...(options.dshHome === undefined ? {} : { dshHome: options.dshHome }),
+            ...(options.dshBin === undefined ? {} : { dshBin: options.dshBin }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            ...(options.runProfileCommand === undefined ? {} : { runCommand: options.runProfileCommand }),
+        });
+    }
+    const allErrors = [...providerResult.errors];
+    if (profileResult !== undefined) {
+        allErrors.push(...profileResult.issues);
+    }
+    return {
+        ...providerResult,
+        ok: allErrors.length === 0,
+        ...(profileResult === undefined ? {} : { profile: profileResult }),
+        errors: allErrors,
+    };
+}
+export function formatDoctorHuman(result) {
+    const lines = [];
+    lines.push(`dsh-agy-cli doctor (schema v${result.schemaVersion})`);
+    lines.push(`status: ${result.ok ? 'PASS' : 'FAIL'}; quotaUsed: ${result.quotaUsed}`);
+    lines.push(`plugin: ${result.plugin.name}@${result.plugin.version ?? 'unknown'}; enabled: ${result.plugin.enabled}`);
+    lines.push(`node: ${result.node.version} (${result.node.supported ? 'supported' : 'unsupported'})`);
+    lines.push(`dsh: cli=${result.dsh.cliVersion ?? 'unknown'}; llm=${result.dsh.llmContractVersion ?? 'unknown'}; bundle=${result.dsh.bundlePatchPresent ? 'present' : 'missing'}`);
+    if (result.profile !== undefined) {
+        const p = result.profile;
+        lines.push(`profile [${p.name}]: exists=${p.profilePresent}; packageInstalled=${p.packageInstalled}; bundleDeclared=${p.bundleDeclared}; enabled=${p.bundleEnabled ?? 'unknown'}; toolPolicy=${p.toolPolicy ?? 'unknown'}`);
+        lines.push(`effective: dump=${p.effective.dumpStatus}; provider=${p.effective.provider ?? 'unknown'}; model=${p.effective.model ?? 'unknown'}; agent=${p.effective.agent ?? 'unknown'}; sessionMode=${p.effective.sessionMode ?? 'unknown'}; imageInput=${p.effective.imageInput ?? 'unknown'}; inputModalities=${p.effective.modelCapability.inputModalities.join(',')}`);
+        lines.push(`agentCapability: preset=${p.effective.agentCapability.knownPreset ?? 'unknown'}; frontmatter=${p.effective.agentCapability.frontmatterValid ?? 'unknown'}; view_file=${p.effective.agentCapability.viewFile ?? 'unknown'}; writeTools=${p.effective.agentCapability.writeTools ?? 'unknown'}; workspace=${p.effective.workspaceRootStatus}`);
+        lines.push(`dshContext: session=${p.effective.dshContext.session.state}; workspace=${p.effective.dshContext.workspace.configured ? 'configured' : 'not-configured'}; permission=${p.effective.dshContext.permission.state}; approval=${p.effective.dshContext.approval.state}`);
+        lines.push(`bridge: owner=${p.effective.bridgeCapability.owner}; agent=${p.effective.bridgeCapability.agent ?? 'unknown'}; schema=${p.effective.bridgeCapability.schemaCapability}; internalTools=${p.effective.bridgeCapability.internalTools}`);
+        if (p.repairSuggestions.length > 0) {
+            lines.push('repair suggestions:');
+            for (const suggestion of p.repairSuggestions)
+                lines.push(`- ${suggestion}`);
+        }
+    }
+    lines.push(`provider: ${result.configuration.provider}; agent=${result.configuration.agent}; defaultModel=${result.configuration.defaultModel}; toolPolicy=${result.configuration.toolPolicy}; transport=${result.configuration.transport ?? 'one-shot'}`);
+    lines.push(`transport: persistentIdleTtlMs=${result.configuration.persistentIdleTtlMs ?? 30000}; readyTimeout=${result.configuration.persistentReadyTimeoutMs ?? 10000}; fallback=${result.configuration.persistentFallback ?? 'before-accept'}`);
+    lines.push(`models: ${result.models.map(m => `${m.id} (${m.name})`).join(', ') || 'none'}`);
+    lines.push(`modelCatalog: source=${result.modelCatalog.source}; stale=${result.modelCatalog.stale}; warningCode=${result.modelCatalog.warningCode ?? 'none'}`);
+    lines.push(`agy: version=${result.agy.version ?? 'unknown'}; agents=${result.agy.agents.join(', ') || 'none'}; executableSource=${result.agy.executableSource}`);
+    if (result.errors.length > 0) {
+        lines.push('issues:');
+        for (const issue of result.errors) {
+            lines.push(`- [${issue.component}/${issue.code}] ${issue.message}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function formatDoctorHelp() {
+    return `Usage: dsh-agy-cli [doctor] [options]
+
+Quota-free diagnostic CLI v3 for dsh-agy-cli and DSH profiles.
+
+Commands:
+  doctor                  Run diagnostic checks (default)
+
+Options:
+  --profile <name>        DSH profile to inspect (e.g. web, headless)
+  --dsh-home <path>       Custom DSH home directory path
+  --dsh-bin <path>        Custom DSH CLI executable / entry path
+  --json                  Output structured JSON
+  -v, --version           Print version and exit
+  -h, --help              Show help information
+
+Examples:
+  npx dsh-agy-cli doctor
+  npx dsh-agy-cli doctor --profile web
+  npx dsh-agy-cli doctor --profile web --json
+`;
+}
+export async function runDoctorCli(argv, stdout = text => process.stdout.write(text), stderr = text => process.stderr.write(text)) {
+    const args = [...argv];
+    if (args[0] === 'doctor')
+        args.shift();
+    if (args.includes('-h') || args.includes('--help')) {
+        stdout(`${formatDoctorHelp()}\n`);
+        return 0;
+    }
+    if (args.includes('-v') || args.includes('--version')) {
+        stdout(`${packageMetadata.version ?? 'unknown'}\n`);
+        return 0;
+    }
+    const jsonOutput = args.includes('--json');
+    let profile;
+    const profileIdx = args.indexOf('--profile');
+    if (profileIdx !== -1 && profileIdx + 1 < args.length) {
+        profile = args[profileIdx + 1];
+    }
+    let dshHome;
+    const dshHomeIdx = args.indexOf('--dsh-home');
+    if (dshHomeIdx !== -1 && dshHomeIdx + 1 < args.length) {
+        dshHome = args[dshHomeIdx + 1];
+    }
+    let dshBin;
+    const dshBinIdx = args.indexOf('--dsh-bin');
+    if (dshBinIdx !== -1 && dshBinIdx + 1 < args.length) {
+        dshBin = args[dshBinIdx + 1];
+    }
+    try {
+        const result = await runDoctor({
+            ...(profile === undefined ? {} : { profile }),
+            ...(dshHome === undefined ? {} : { dshHome }),
+            ...(dshBin === undefined ? {} : { dshBin }),
+            config: Config({}),
+        });
+        if (jsonOutput) {
+            stdout(`${JSON.stringify(result, null, 2)}\n`);
+        }
+        else {
+            stdout(`${formatDoctorHuman(result)}\n`);
+        }
+        return result.ok ? 0 : 1;
+    }
+    catch (error) {
+        const message = redactText(error instanceof Error ? error.message : String(error), 512);
+        if (jsonOutput) {
+            stdout(JSON.stringify({
+                schemaVersion: 1,
+                ok: false,
+                quotaUsed: false,
+                errors: [{ component: 'config', code: 'DOCTOR_EXECUTION_FAILED', message }],
+            }, null, 2) + '\n');
+        }
+        else {
+            stderr(`Error running doctor: ${message}\n`);
+        }
+        return 1;
+    }
+}
+//# sourceMappingURL=doctor.js.map