@geotechcli/core 0.4.11 → 0.4.13

package/dist/skills/index.js

@@ -0,0 +1,869 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { homedir, tmpdir } from 'node:os';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+import { loadConfig } from '../config/index.js';
+import { ensureWorkspace } from '../agents/sandbox.js';
+import { validateReadPath, validateWritePath, getWorkspaceDir } from '../agents/sandbox.js';
+import { addArtifact, addNote, saveNamedDataset } from '../storage/index.js';
+export { getStrongBetaSkillApproval, isStrongBetaSkillApproved, STRONG_BETA_SKILL_APPROVALS, } from './approval.js';
+export const AGENT_SKILL_TOOL_NAMES = ['list_skills', 'describe_skill', 'run_skill'];
+const MANIFEST_FILENAME = '.geotechcli-skill.json';
+const SUPPORTED_SKILL_FILE_EXTENSIONS = new Set([
+    '.py',
+    '.md',
+    '.json',
+    '.csv',
+    '.yaml',
+    '.yml',
+    '.txt',
+]);
+const SYSTEM_ENV_KEYS = [
+    'PATH',
+    'PATHEXT',
+    'SYSTEMROOT',
+    'COMSPEC',
+    'WINDIR',
+    'TMP',
+    'TEMP',
+    'HOME',
+    'USERPROFILE',
+    'LANG',
+    'LC_ALL',
+];
+const DEFAULT_SKILL_EXECUTION_PROFILE = {
+    contract: 'input-dir-output-dir',
+};
+const SKILL_EXECUTION_PROFILES = {
+    'epb-conditioning-clogging': {
+        contract: 'legacy-file-inputs',
+        inputBindings: [
+            { flag: '--ground-model', fileName: 'ground_model.json' },
+            { flag: '--machine-config', fileName: 'machine_config.json' },
+            { flag: '--alignment-zones', fileName: 'alignment_zones.csv' },
+        ],
+        candidateArtifactTypes: ['assumptions', 'results', 'issues-and-corrections'],
+    },
+    'epb-face-support-window': {
+        contract: 'legacy-file-inputs',
+        inputBindings: [
+            { flag: '--ground-model', fileName: 'ground_model.json' },
+            { flag: '--machine-config', fileName: 'machine_config.json' },
+            { flag: '--alignment-zones', fileName: 'alignment_zones.csv' },
+        ],
+        candidateArtifactTypes: ['results', 'review-checklist', 'acceptance-status'],
+    },
+    'epb-production-and-ring-cycle': {
+        contract: 'legacy-file-inputs',
+        inputBindings: [
+            { flag: '--monitoring', fileName: 'monitoring.csv' },
+            { flag: '--machine-config', fileName: 'machine_config.json' },
+        ],
+        candidateArtifactTypes: ['results', 'final-report', 'review-checklist'],
+    },
+    'epb-soft-ground-screening': {
+        contract: 'legacy-file-inputs',
+        inputBindings: [
+            { flag: '--ground-model', fileName: 'ground_model.json' },
+            { flag: '--machine-config', fileName: 'machine_config.json' },
+            { flag: '--alignment-zones', fileName: 'alignment_zones.csv' },
+        ],
+        candidateArtifactTypes: ['ground-model', 'analysis-plan', 'results'],
+    },
+    'mixed-face-transition-planning': {
+        contract: 'legacy-file-inputs',
+        inputBindings: [
+            { flag: '--ground-model', fileName: 'ground_model.json' },
+            { flag: '--machine-config', fileName: 'machine_config.json' },
+            { flag: '--alignment-zones', fileName: 'alignment_zones.csv' },
+        ],
+        candidateArtifactTypes: ['analysis-plan', 'results', 'review-checklist', 'issues-and-corrections'],
+    },
+    'soft-ground-settlement-observational-control': {
+        contract: 'legacy-file-inputs',
+        inputBindings: [
+            { flag: '--ground-model', fileName: 'ground_model.json' },
+            { flag: '--machine-config', fileName: 'machine_config.json' },
+            { flag: '--alignment-zones', fileName: 'alignment_zones.csv' },
+            { flag: '--monitoring', fileName: 'monitoring.csv' },
+        ],
+        candidateArtifactTypes: ['results', 'review-checklist', 'acceptance-status', 'issues-and-corrections'],
+    },
+};
+function getSkillsDirFallback() {
+    return join(process.env.GEOTECHCLI_CONFIG_DIR ?? join(homedir(), '.geotechcli'), 'skills');
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function isDirectory(path) {
+    return existsSync(path) && statSync(path).isDirectory();
+}
+function isFile(path) {
+    return existsSync(path) && statSync(path).isFile();
+}
+function titleCaseFromName(value) {
+    return value
+        .split(/[-_]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
+function readTextIfExists(path) {
+    return isFile(path) ? readFileSync(path, 'utf-8') : null;
+}
+function parseFrontmatter(skillMarkdown) {
+    const match = skillMarkdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    const block = match?.[1] ?? '';
+    const name = block.match(/^name:\s*(.+)$/m)?.[1]?.trim();
+    const description = block.match(/^description:\s*(.+)$/m)?.[1]?.trim();
+    return {
+        name,
+        description,
+    };
+}
+function parseOpenAIYamlDisplayName(openAIYaml) {
+    if (!openAIYaml)
+        return undefined;
+    return openAIYaml.match(/^\s*display_name:\s*"?(.+?)"?\s*$/m)?.[1]?.trim();
+}
+function discoverSkillRoots(rootDir) {
+    const discovered = new Set();
+    function walk(currentDir) {
+        if (isFile(join(currentDir, 'SKILL.md'))) {
+            discovered.add(currentDir);
+            return;
+        }
+        for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name === '.git' || entry.name === 'node_modules')
+                continue;
+            walk(join(currentDir, entry.name));
+        }
+    }
+    walk(rootDir);
+    return [...discovered].sort((left, right) => left.localeCompare(right));
+}
+function walkFiles(rootDir) {
+    const files = [];
+    function walk(currentDir) {
+        for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+            const fullPath = join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                walk(fullPath);
+                continue;
+            }
+            files.push(fullPath);
+        }
+    }
+    walk(rootDir);
+    return files.sort((left, right) => left.localeCompare(right));
+}
+function detectEntryScript(skillRoot, skillName, skillMarkdown) {
+    const scriptsDir = join(skillRoot, 'scripts');
+    if (!isDirectory(scriptsDir)) {
+        return undefined;
+    }
+    const explicitMatches = [...skillMarkdown.matchAll(/scripts\/([A-Za-z0-9._-]+\.py)/g)]
+        .map((match) => match[1])
+        .filter((entry) => isFile(join(scriptsDir, entry)));
+    if (explicitMatches.length > 0) {
+        return join('scripts', explicitMatches[0]);
+    }
+    const scripts = readdirSync(scriptsDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.py'))
+        .map((entry) => entry.name)
+        .sort((left, right) => left.localeCompare(right));
+    if (scripts.length === 1) {
+        return join('scripts', scripts[0]);
+    }
+    const normalizedName = skillName.replace(/-/g, '_');
+    const exactMatch = scripts.find((entry) => basename(entry, '.py') === normalizedName);
+    if (exactMatch) {
+        return join('scripts', exactMatch);
+    }
+    const nonHelperScripts = scripts.filter((entry) => !/^common[_-]/.test(entry) && !/^__/.test(entry));
+    if (nonHelperScripts.length === 1) {
+        return join('scripts', nonHelperScripts[0]);
+    }
+    return nonHelperScripts[0] ? join('scripts', nonHelperScripts[0]) : undefined;
+}
+function computeInstallHash(rootDir) {
+    const hash = createHash('sha256');
+    for (const filePath of walkFiles(rootDir)) {
+        hash.update(relative(rootDir, filePath).replace(/\\/g, '/'));
+        hash.update('\0');
+        hash.update(readFileSync(filePath));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+function toCandidate(skillRoot) {
+    const issues = [];
+    const skillFile = join(skillRoot, 'SKILL.md');
+    const skillMarkdown = readTextIfExists(skillFile);
+    if (!skillMarkdown) {
+        return {
+            rootDir: skillRoot,
+            issues: [{ severity: 'error', message: 'Missing SKILL.md.' }],
+        };
+    }
+    const frontmatter = parseFrontmatter(skillMarkdown);
+    if (!frontmatter.name) {
+        issues.push({ severity: 'error', message: 'SKILL.md frontmatter is missing "name".' });
+    }
+    if (!frontmatter.description) {
+        issues.push({ severity: 'error', message: 'SKILL.md frontmatter is missing "description".' });
+    }
+    const files = walkFiles(skillRoot);
+    for (const filePath of files) {
+        const relativePath = relative(skillRoot, filePath).replace(/\\/g, '/');
+        if (relativePath === MANIFEST_FILENAME)
+            continue;
+        const extension = extname(filePath).toLowerCase();
+        if (!SUPPORTED_SKILL_FILE_EXTENSIONS.has(extension)) {
+            issues.push({
+                severity: 'error',
+                message: `Unsupported file type in skill bundle: ${relativePath}`,
+            });
+        }
+    }
+    const openAIYaml = readTextIfExists(join(skillRoot, 'agents', 'openai.yaml'));
+    const displayName = parseOpenAIYamlDisplayName(openAIYaml) ?? (frontmatter.name ? titleCaseFromName(frontmatter.name) : undefined);
+    const runtime = isDirectory(join(skillRoot, 'scripts')) ? 'python-script' : 'prompt-only';
+    const entryScript = frontmatter.name ? detectEntryScript(skillRoot, frontmatter.name, skillMarkdown) : undefined;
+    if (runtime === 'python-script' && !entryScript) {
+        issues.push({
+            severity: 'error',
+            message: 'Python-script skill does not have a detectable entry script in scripts/.',
+        });
+    }
+    if (!openAIYaml) {
+        issues.push({
+            severity: 'warning',
+            message: 'agents/openai.yaml is missing; display metadata will fall back to the skill name.',
+        });
+    }
+    return {
+        name: frontmatter.name,
+        displayName,
+        description: frontmatter.description,
+        runtime,
+        rootDir: skillRoot,
+        entryScript,
+        contentHash: computeInstallHash(skillRoot),
+        issues,
+    };
+}
+function isPathWithin(targetPath, parentPath) {
+    const resolvedTarget = resolve(targetPath);
+    const resolvedParent = resolve(parentPath);
+    return resolvedTarget === resolvedParent || resolvedTarget.startsWith(`${resolvedParent}\\`) || resolvedTarget.startsWith(`${resolvedParent}/`);
+}
+function isTrustedSkillSourcePath(sourcePath) {
+    const resolvedSource = resolve(sourcePath);
+    const trustedRoots = [
+        process.cwd(),
+        getWorkspaceDir(),
+        process.env.GEOTECHCLI_CONFIG_DIR ?? join(homedir(), '.geotechcli'),
+    ].map((rootPath) => resolve(rootPath));
+    return trustedRoots.some((rootPath) => isPathWithin(resolvedSource, rootPath));
+}
+function buildInstalledSkill(candidate, sourceType, sourceLabel, trusted) {
+    const rootDir = resolve(candidate.rootDir);
+    const files = walkFiles(rootDir);
+    const discoveredCandidate = candidate;
+    return {
+        name: candidate.name,
+        displayName: candidate.displayName ?? titleCaseFromName(candidate.name),
+        description: candidate.description ?? '',
+        runtime: candidate.runtime ?? 'prompt-only',
+        installPath: rootDir,
+        skillFile: join(rootDir, 'SKILL.md'),
+        installedAt: nowIso(),
+        entryScript: candidate.entryScript ? join(rootDir, candidate.entryScript) : undefined,
+        sourceType,
+        sourceLabel,
+        installHash: discoveredCandidate.contentHash ?? computeInstallHash(rootDir),
+        scriptCount: files.filter((filePath) => relative(rootDir, filePath).replace(/\\/g, '/').startsWith('scripts/')).length,
+        referenceCount: files.filter((filePath) => relative(rootDir, filePath).replace(/\\/g, '/').startsWith('references/')).length,
+        assetCount: files.filter((filePath) => relative(rootDir, filePath).replace(/\\/g, '/').startsWith('assets/')).length,
+        hasOpenAIYaml: isFile(join(rootDir, 'agents', 'openai.yaml')),
+        trusted,
+    };
+}
+function manifestPathFor(dirPath) {
+    return join(dirPath, MANIFEST_FILENAME);
+}
+function writeManifest(skillDir, skill) {
+    const manifest = {
+        ...skill,
+        installPath: skillDir,
+        skillFile: join(skillDir, 'SKILL.md'),
+        entryScript: skill.entryScript
+            ? join(skillDir, relative(skill.installPath, skill.entryScript))
+            : undefined,
+    };
+    writeFileSync(manifestPathFor(skillDir), JSON.stringify(manifest, null, 2), 'utf-8');
+}
+function loadManifest(dirPath) {
+    const manifestPath = manifestPathFor(dirPath);
+    if (!isFile(manifestPath))
+        return null;
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    if (!parsed.name || !parsed.description || !parsed.installPath || !parsed.skillFile || !parsed.runtime) {
+        return null;
+    }
+    return {
+        name: parsed.name,
+        displayName: parsed.displayName ?? titleCaseFromName(parsed.name),
+        description: parsed.description,
+        runtime: parsed.runtime,
+        installPath: parsed.installPath,
+        skillFile: parsed.skillFile,
+        installedAt: parsed.installedAt ?? nowIso(),
+        entryScript: parsed.entryScript,
+        sourceType: parsed.sourceType ?? 'directory',
+        sourceLabel: parsed.sourceLabel ?? basename(dirPath),
+        installHash: parsed.installHash ?? computeInstallHash(dirPath),
+        scriptCount: parsed.scriptCount ?? 0,
+        referenceCount: parsed.referenceCount ?? 0,
+        assetCount: parsed.assetCount ?? 0,
+        hasOpenAIYaml: parsed.hasOpenAIYaml ?? false,
+        trusted: parsed.trusted ?? false,
+    };
+}
+function ensureDirectory(dirPath) {
+    if (!existsSync(dirPath)) {
+        mkdirSync(dirPath, { recursive: true });
+    }
+    return dirPath;
+}
+function createTempDir(prefix) {
+    const dirPath = join(tmpdir(), `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+    mkdirSync(dirPath, { recursive: true });
+    return dirPath;
+}
+function buildPythonEnv() {
+    const env = {
+        PYTHONIOENCODING: 'utf-8',
+        PYTHONUTF8: '1',
+    };
+    for (const key of SYSTEM_ENV_KEYS) {
+        if (process.env[key]) {
+            env[key] = process.env[key];
+        }
+    }
+    return env;
+}
+function runPythonScript(scriptContent, args, cwd) {
+    const pythonPath = getSkillsRuntimeConfig().pythonPath;
+    const helperPath = join(createTempDir('geotechcli-skill-helper'), 'helper.py');
+    writeFileSync(helperPath, scriptContent, 'utf-8');
+    const result = spawnSync(pythonPath, [helperPath, ...args], {
+        cwd,
+        encoding: 'utf-8',
+        timeout: 30_000,
+        env: buildPythonEnv(),
+    });
+    rmSync(dirname(helperPath), { recursive: true, force: true });
+    if (result.error) {
+        throw result.error;
+    }
+    return {
+        status: result.status,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+}
+function extractZipToTemp(sourcePath) {
+    const extractRoot = createTempDir('geotechcli-skill-import');
+    const helperScript = [
+        'import pathlib',
+        'import sys',
+        'import zipfile',
+        '',
+        'src = pathlib.Path(sys.argv[1])',
+        'dest = pathlib.Path(sys.argv[2])',
+        'with zipfile.ZipFile(src) as archive:',
+        '    for info in archive.infolist():',
+        "        parts = pathlib.PurePosixPath(info.filename).parts",
+        "        if not parts:",
+        '            continue',
+        "        if any(part in ('..', '') for part in parts):",
+        "            raise SystemExit(f'unsafe zip entry: {info.filename}')",
+        "        if pathlib.PurePosixPath(info.filename).is_absolute():",
+        "            raise SystemExit(f'unsafe zip entry: {info.filename}')",
+        '        target = dest.joinpath(*parts)',
+        "        if info.is_dir():",
+        '            target.mkdir(parents=True, exist_ok=True)',
+        '            continue',
+        '        target.parent.mkdir(parents=True, exist_ok=True)',
+        '        with archive.open(info) as source_handle, open(target, "wb") as target_handle:',
+        '            target_handle.write(source_handle.read())',
+    ].join('\n');
+    const extractResult = runPythonScript(helperScript, [sourcePath, extractRoot]);
+    if (extractResult.status !== 0) {
+        rmSync(extractRoot, { recursive: true, force: true });
+        throw new Error(extractResult.stderr.trim() || extractResult.stdout.trim() || 'Failed to extract skill archive.');
+    }
+    return extractRoot;
+}
+function withPreparedSource(sourcePath, callback) {
+    const resolvedPath = resolve(sourcePath);
+    if (isDirectory(resolvedPath)) {
+        return callback(resolvedPath, 'directory');
+    }
+    if (isFile(resolvedPath) && extname(resolvedPath).toLowerCase() === '.zip') {
+        const extractedRoot = extractZipToTemp(resolvedPath);
+        try {
+            return callback(extractedRoot, 'zip');
+        }
+        finally {
+            rmSync(extractedRoot, { recursive: true, force: true });
+        }
+    }
+    throw new Error(`Unsupported skill source: ${sourcePath}. Expected a directory or .zip file.`);
+}
+function discoverPreparedSkillCandidates(preparedRoot) {
+    const cleanupPaths = [];
+    const seenRoots = new Set();
+    const candidates = [];
+    const addSkillRootsFrom = (rootDir) => {
+        for (const skillRoot of discoverSkillRoots(rootDir)) {
+            const resolvedRoot = resolve(skillRoot);
+            if (seenRoots.has(resolvedRoot))
+                continue;
+            seenRoots.add(resolvedRoot);
+            candidates.push(toCandidate(skillRoot));
+        }
+    };
+    addSkillRootsFrom(preparedRoot);
+    const nestedZipPaths = walkFiles(preparedRoot)
+        .filter((filePath) => extname(filePath).toLowerCase() === '.zip')
+        .sort((left, right) => left.localeCompare(right));
+    for (const zipPath of nestedZipPaths) {
+        const nestedPreparedRoot = extractZipToTemp(zipPath);
+        cleanupPaths.push(nestedPreparedRoot);
+        addSkillRootsFrom(nestedPreparedRoot);
+    }
+    return {
+        candidates,
+        cleanupPaths,
+    };
+}
+function dedupeEquivalentCandidates(candidates) {
+    const deduped = new Map();
+    for (const candidate of candidates) {
+        const key = candidate.name && candidate.contentHash
+            ? `${candidate.name}::${candidate.contentHash}`
+            : resolve(candidate.rootDir);
+        if (!deduped.has(key)) {
+            deduped.set(key, {
+                ...candidate,
+                issues: [...candidate.issues],
+            });
+        }
+    }
+    return [...deduped.values()]
+        .sort((left, right) => {
+        const leftKey = left.name ?? left.rootDir;
+        const rightKey = right.name ?? right.rootDir;
+        return leftKey.localeCompare(rightKey);
+    })
+        .map(({ contentHash, ...candidate }) => candidate);
+}
+function buildValidationResult(sourcePath, candidates) {
+    const issues = [];
+    if (candidates.length === 0) {
+        issues.push({ severity: 'error', message: 'No SKILL.md files were found in the provided source.' });
+    }
+    const duplicateNames = new Map();
+    for (const candidate of candidates) {
+        if (!candidate.name)
+            continue;
+        duplicateNames.set(candidate.name, (duplicateNames.get(candidate.name) ?? 0) + 1);
+    }
+    for (const candidate of candidates) {
+        if (candidate.name && (duplicateNames.get(candidate.name) ?? 0) > 1) {
+            candidate.issues.push({
+                severity: 'error',
+                message: `Duplicate skill name "${candidate.name}" detected in the same source.`,
+            });
+        }
+        issues.push(...candidate.issues);
+    }
+    return {
+        sourcePath: resolve(sourcePath),
+        valid: issues.every((issue) => issue.severity !== 'error'),
+        candidates,
+        issues,
+    };
+}
+function withPreparedSkillCandidates(sourcePath, callback) {
+    return withPreparedSource(sourcePath, (preparedRoot, sourceType) => {
+        const { candidates, cleanupPaths } = discoverPreparedSkillCandidates(preparedRoot);
+        const dedupedCandidates = dedupeEquivalentCandidates(candidates);
+        try {
+            return callback({
+                resolvedSourcePath: resolve(sourcePath),
+                sourceType,
+                candidates: dedupedCandidates,
+            });
+        }
+        finally {
+            for (const cleanupPath of cleanupPaths) {
+                rmSync(cleanupPath, { recursive: true, force: true });
+            }
+        }
+    });
+}
+export function getSkillsRuntimeConfig() {
+    const config = loadConfig();
+    const configuredDirectory = config.skills.directory?.trim();
+    return {
+        enabled: process.env.GEOTECHCLI_ENABLE_SKILLS === '1' || config.skills.enabled,
+        directory: process.env.GEOTECHCLI_SKILLS_DIR?.trim() || configuredDirectory || getSkillsDirFallback(),
+        pythonPath: process.env.GEOTECHCLI_SKILLS_PYTHON?.trim() || config.skills.python_path || 'python',
+        trustedOnly: process.env.GEOTECHCLI_SKILLS_TRUSTED_ONLY === '0'
+            ? false
+            : config.skills.trusted_only,
+    };
+}
+export function areAgentSkillToolsEnabled() {
+    return getSkillsRuntimeConfig().enabled;
+}
+export function isAgentSkillToolName(toolName) {
+    return AGENT_SKILL_TOOL_NAMES.includes(toolName);
+}
+export function getSkillsDirectory() {
+    return ensureDirectory(resolve(getSkillsRuntimeConfig().directory));
+}
+export function listInstalledSkills() {
+    const skillsDir = getSkillsDirectory();
+    return readdirSync(skillsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => loadManifest(join(skillsDir, entry.name)))
+        .filter((skill) => skill !== null)
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+export function getInstalledSkill(name) {
+    const skill = listInstalledSkills().find((entry) => entry.name === name);
+    if (!skill) {
+        throw new Error(`Skill "${name}" is not installed.`);
+    }
+    return skill;
+}
+export function readInstalledSkillGuide(name) {
+    const skill = getInstalledSkill(name);
+    return readFileSync(skill.skillFile, 'utf-8');
+}
+export function validateSkillSource(sourcePath) {
+    return withPreparedSkillCandidates(sourcePath, ({ resolvedSourcePath, candidates }) => buildValidationResult(resolvedSourcePath, candidates));
+}
+export function validateInstalledSkill(name) {
+    const skill = getInstalledSkill(name);
+    const candidate = toCandidate(skill.installPath);
+    return {
+        sourcePath: skill.installPath,
+        valid: candidate.issues.every((issue) => issue.severity !== 'error'),
+        candidates: [candidate],
+        issues: [...candidate.issues],
+    };
+}
+export function importSkillsFromSource(sourcePath, options) {
+    return withPreparedSkillCandidates(sourcePath, ({ resolvedSourcePath, sourceType, candidates, }) => {
+        const validation = buildValidationResult(resolvedSourcePath, candidates);
+        if (!validation.valid) {
+            const errors = validation.issues.filter((issue) => issue.severity === 'error');
+            throw new Error(errors.map((issue) => issue.message).join(' '));
+        }
+        const trusted = isTrustedSkillSourcePath(sourcePath);
+        if (getSkillsRuntimeConfig().trustedOnly && !trusted) {
+            throw new Error(`Skill import blocked: "${resolvedSourcePath}" is outside trusted strong-beta skill locations.`);
+        }
+        const sourceLabel = basename(resolvedSourcePath);
+        const imported = [];
+        const replaced = [];
+        for (const candidate of candidates) {
+            if (!candidate.name)
+                continue;
+            const installDir = join(getSkillsDirectory(), candidate.name);
+            if (existsSync(installDir)) {
+                if (!options?.force) {
+                    throw new Error(`Skill "${candidate.name}" is already installed. Re-run with --force to replace it.`);
+                }
+                rmSync(installDir, { recursive: true, force: true });
+                replaced.push(candidate.name);
+            }
+            cpSync(candidate.rootDir, installDir, { recursive: true });
+            const installedSkill = buildInstalledSkill({
+                ...candidate,
+                rootDir: installDir,
+            }, sourceType, sourceLabel, trusted);
+            writeManifest(installDir, installedSkill);
+            imported.push(installedSkill);
+        }
+        return {
+            sourcePath: resolvedSourcePath,
+            imported,
+            replaced,
+        };
+    });
+}
+function parseJsonFile(path) {
+    if (!isFile(path))
+        return undefined;
+    return JSON.parse(readFileSync(path, 'utf-8'));
+}
+function getSkillExecutionProfile(name) {
+    return SKILL_EXECUTION_PROFILES[name] ?? DEFAULT_SKILL_EXECUTION_PROFILE;
+}
+function asNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((item) => typeof item === 'string' && item.trim().length > 0)
+        .map((item) => item.trim());
+}
+function asFiniteNumber(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (typeof value === 'string' && value.trim()) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function normalizeCriticalRisks(value) {
+    return asStringArray(value).filter((item) => {
+        const token = item.trim().toLowerCase();
+        return token !== 'none' && token !== 'no critical risks' && token !== 'no critical risk';
+    });
+}
+function getLegacyAssessmentScope(payload) {
+    if (Array.isArray(payload.zone_results)) {
+        return { count: payload.zone_results.length, noun: 'zone' };
+    }
+    const totalRings = asFiniteNumber(payload.total_rings);
+    if (totalRings != null) {
+        return { count: totalRings, noun: 'ring' };
+    }
+    return { count: 0, noun: 'item' };
+}
+function pluralize(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+function buildLegacyProjectSummary(skill, payload, overallRecommendation, assessmentCount, assessmentNoun, criticalRiskCount, missingInputCount) {
+    const targetRings = asFiniteNumber(payload.target_rings);
+    const avgCycle = asFiniteNumber(payload.avg_cycle_min);
+    const metRingTarget = payload.met_ring_target === true
+        ? 'met'
+        : payload.met_ring_target === false
+            ? 'missed'
+            : undefined;
+    const lead = overallRecommendation
+        ? `${skill.displayName} overall recommendation: ${overallRecommendation}.`
+        : assessmentNoun === 'ring'
+            ? `${skill.displayName} reviewed ${pluralize(assessmentCount, 'ring')}${targetRings != null ? ` against a target of ${targetRings}` : ''}${avgCycle != null ? ` with an average cycle of ${avgCycle.toFixed(1)} minutes` : ''}${metRingTarget ? ` and ${metRingTarget} the ring target` : ''}.`
+            : `${skill.displayName} evaluated ${pluralize(assessmentCount, assessmentNoun)}.`;
+    const risk = criticalRiskCount > 0
+        ? ` Flagged ${pluralize(criticalRiskCount, 'critical risk')}.`
+        : ' No critical risks were flagged.';
+    const missing = missingInputCount > 0
+        ? ` ${pluralize(missingInputCount, 'missing input')} still need confirmation.`
+        : '';
+    return `${lead}${risk}${missing}`.trim();
+}
+function buildLegacyRunSummary(overallRecommendation, criticalRiskCount, missingInputCount, assessmentCount, assessmentNoun) {
+    const parts = [];
+    if (overallRecommendation) {
+        parts.push(`overall recommendation ${overallRecommendation}`);
+    }
+    parts.push(`${pluralize(assessmentCount, assessmentNoun)} assessed`);
+    if (criticalRiskCount > 0) {
+        parts.push(`${pluralize(criticalRiskCount, 'critical risk')} flagged`);
+    }
+    if (missingInputCount > 0) {
+        parts.push(`${pluralize(missingInputCount, 'missing input')} remain`);
+    }
+    return parts.join('; ') + '.';
+}
+function normalizeLegacySkillHandoff(skill, payload) {
+    const criticalRisks = normalizeCriticalRisks(payload.critical_risks);
+    const missingInputs = asStringArray(payload.missing_inputs);
+    const assessmentScope = getLegacyAssessmentScope(payload);
+    const overallRecommendation = asNonEmptyString(payload.overall_recommendation) ?? asNonEmptyString(payload.recommendation);
+    const projectSummary = asNonEmptyString(payload.project_summary) ??
+        buildLegacyProjectSummary(skill, payload, overallRecommendation, assessmentScope.count, assessmentScope.noun, criticalRisks.length, missingInputs.length);
+    const summary = asNonEmptyString(payload.summary) ??
+        buildLegacyRunSummary(overallRecommendation, criticalRisks.length, missingInputs.length, assessmentScope.count, assessmentScope.noun);
+    return {
+        ...payload,
+        skill: payload.skill ?? skill.name,
+        project_summary: projectSummary,
+        summary,
+    };
+}
+function buildLegacyArtifactMap(skill, profile, swarmHandoff) {
+    const missingInputs = asStringArray(swarmHandoff.missing_inputs);
+    const recommendedNextTools = asStringArray(swarmHandoff.recommended_next_tools);
+    const criticalRisks = normalizeCriticalRisks(swarmHandoff.critical_risks);
+    return {
+        skill: skill.name,
+        execution_contract: profile.contract,
+        named_dataset_keys: [
+            `skill:${skill.name}:swarm_handoff`,
+            `skill:${skill.name}:artifact_map`,
+        ],
+        derived_parameters: [],
+        assumption_records: missingInputs.map((item) => ({
+            type: 'missing_input',
+            detail: item,
+        })),
+        candidate_case_file_artifact_types: profile.candidateArtifactTypes,
+        recommended_next_tools: recommendedNextTools,
+        critical_risks: criticalRisks,
+    };
+}
+function runLegacyFileInputSkill(skill, inputDir, outputDir, profile, swarmHandoffPath, engineeringReportPath, caseFileArtifactMapPath) {
+    const args = [skill.entryScript];
+    for (const binding of profile.inputBindings) {
+        const inputPath = join(inputDir, binding.fileName);
+        if (!isFile(inputPath)) {
+            throw new Error(`Skill "${skill.name}" requires ${binding.fileName} in the input directory for ${binding.flag}.`);
+        }
+        args.push(binding.flag, inputPath);
+    }
+    args.push('--output-json', swarmHandoffPath, '--output-markdown', engineeringReportPath);
+    const result = spawnSync(getSkillsRuntimeConfig().pythonPath, args, {
+        cwd: skill.installPath,
+        encoding: 'utf-8',
+        timeout: 90_000,
+        env: buildPythonEnv(),
+    });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status === 0) {
+        const rawHandoff = parseJsonFile(swarmHandoffPath);
+        if (rawHandoff) {
+            const normalized = normalizeLegacySkillHandoff(skill, rawHandoff);
+            writeFileSync(swarmHandoffPath, JSON.stringify(normalized, null, 2) + '\n');
+            writeFileSync(caseFileArtifactMapPath, JSON.stringify(buildLegacyArtifactMap(skill, profile, normalized), null, 2) + '\n');
+        }
+    }
+    return result;
+}
+function buildSkillRunSummary(skill, success, swarmHandoff) {
+    if (!success) {
+        return `${skill.name} failed to complete.`;
+    }
+    const summary = typeof swarmHandoff?.summary === 'string' ? swarmHandoff.summary : undefined;
+    return summary ? `${skill.displayName}: ${summary}` : `${skill.displayName} completed successfully.`;
+}
+function persistSkillRun(projectId, run) {
+    if (run.swarmHandoff) {
+        saveNamedDataset(projectId, {
+            name: `skill:${run.skill.name}:swarm_handoff`,
+            kind: 'skill-swarm-handoff',
+            data: run.swarmHandoff,
+            source: run.skill.name,
+        });
+    }
+    if (run.caseFileArtifactMap) {
+        saveNamedDataset(projectId, {
+            name: `skill:${run.skill.name}:artifact_map`,
+            kind: 'skill-artifact-map',
+            data: run.caseFileArtifactMap,
+            source: run.skill.name,
+        });
+    }
+    if (run.engineeringReportPath && run.engineeringReport) {
+        addArtifact(projectId, {
+            kind: 'skill-report',
+            title: `${run.skill.displayName} report`,
+            path: run.engineeringReportPath,
+            content: run.engineeringReport,
+            mimeType: 'text/markdown',
+            metadata: {
+                skill: run.skill.name,
+                runDir: run.runDir,
+                outputDir: run.outputDir,
+            },
+        });
+    }
+    addNote(projectId, `Ran skill "${run.skill.name}" (${run.success ? 'success' : 'failed'}).`);
+}
+export function runInstalledSkill(name, options) {
+    const skill = getInstalledSkill(name);
+    if (skill.runtime !== 'python-script' || !skill.entryScript) {
+        throw new Error(`Skill "${name}" is not an executable python-script skill.`);
+    }
+    if (getSkillsRuntimeConfig().trustedOnly && !skill.trusted) {
+        throw new Error(`Skill "${name}" is blocked because it is not trusted for strong-beta execution.`);
+    }
+    const inputDirCheck = validateReadPath(options.inputDir, [skill.installPath, getSkillsDirectory()]);
+    if (!inputDirCheck.safe) {
+        throw new Error(inputDirCheck.error ?? `Input directory not allowed: ${options.inputDir}`);
+    }
+    const inputDir = inputDirCheck.resolved;
+    if (!isDirectory(inputDir)) {
+        throw new Error(`Input directory not found: ${inputDir}`);
+    }
+    const runDir = ensureDirectory(join(ensureWorkspace(), 'skills', 'runs', `${Date.now()}-${randomUUID().slice(0, 8)}-${skill.name}`));
+    let outputDir = join(runDir, 'output');
+    if (options.outputDir) {
+        const outputDirCheck = validateWritePath(options.outputDir, [getWorkspaceDir()]);
+        if (!outputDirCheck.safe) {
+            throw new Error(outputDirCheck.error ?? `Output directory not allowed: ${options.outputDir}`);
+        }
+        outputDir = outputDirCheck.resolved;
+    }
+    outputDir = ensureDirectory(outputDir);
+    const executionProfile = getSkillExecutionProfile(skill.name);
+    const swarmHandoffPath = join(outputDir, 'swarm_handoff.json');
+    const engineeringReportPath = join(outputDir, 'engineering_report.md');
+    const caseFileArtifactMapPath = join(outputDir, 'case_file_artifact_map.json');
+    const result = executionProfile.contract === 'legacy-file-inputs'
+        ? runLegacyFileInputSkill(skill, inputDir, outputDir, executionProfile, swarmHandoffPath, engineeringReportPath, caseFileArtifactMapPath)
+        : spawnSync(getSkillsRuntimeConfig().pythonPath, [skill.entryScript, '--input-dir', inputDir, '--output-dir', outputDir], {
+            cwd: skill.installPath,
+            encoding: 'utf-8',
+            timeout: 90_000,
+            env: buildPythonEnv(),
+        });
+    if (result.error) {
+        throw result.error;
+    }
+    const run = {
+        skill,
+        success: result.status === 0,
+        exitCode: result.status,
+        runDir,
+        outputDir,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        swarmHandoffPath: isFile(swarmHandoffPath) ? swarmHandoffPath : undefined,
+        engineeringReportPath: isFile(engineeringReportPath) ? engineeringReportPath : undefined,
+        caseFileArtifactMapPath: isFile(caseFileArtifactMapPath) ? caseFileArtifactMapPath : undefined,
+        swarmHandoff: parseJsonFile(swarmHandoffPath),
+        engineeringReport: readTextIfExists(engineeringReportPath) ?? undefined,
+        caseFileArtifactMap: parseJsonFile(caseFileArtifactMapPath),
+        persistedToProject: false,
+        summary: '',
+    };
+    run.summary = buildSkillRunSummary(skill, run.success, run.swarmHandoff);
+    if (options.projectId) {
+        persistSkillRun(options.projectId, run);
+        run.persistedToProject = true;
+    }
+    return run;
+}
+//# sourceMappingURL=index.js.map