@agentworkforce/workload-router 0.19.0 → 2.1.0

package/dist/index.js

@@ -1,845 +1,6 @@
+import { deepFreeze, isObject, isTier, materializeSkills, materializeSkillsFor, parsePersonaSpec, PERSONA_INTENTS, PERSONA_TIERS, resolveSidecar, sidecarSelectionFields, buildInstallArtifacts, buildCleanupArtifacts } from '@agentworkforce/persona-kit';
 import { personaImprover, personaMaker } from './generated/personas.js';
 import defaultRoutingProfileJson from '../routing-profiles/default.json' with { type: 'json' };
-export const HARNESS_VALUES = ['opencode', 'codex', 'claude'];
-export const PERSONA_TIERS = ['best', 'best-value', 'minimum'];
-export const PERSONA_TAGS = [
-    'planning',
-    'implementation',
-    'review',
-    'testing',
-    'debugging',
-    'documentation',
-    'release',
-    'discovery',
-    'analytics'
-];
-export const PERSONA_INTENTS = [
-    'implement-frontend',
-    'review',
-    'architecture-plan',
-    'requirements-analysis',
-    'debugging',
-    'security-review',
-    'documentation',
-    'verification',
-    'test-strategy',
-    'tdd-enforcement',
-    'flake-investigation',
-    'opencode-workflow-correctness',
-    'npm-provenance',
-    'cloud-sandbox-infra',
-    'sage-slack-egress-migration',
-    'sage-proactive-rewire',
-    'cloud-slack-proxy-guard',
-    'sage-cloud-e2e-conduction',
-    'capability-discovery',
-    'npm-package-compat',
-    'posthog',
-    'persona-authoring',
-    'persona-improvement',
-    'agent-relay-workflow',
-    'slop-audit',
-    'api-contract-review',
-    'local-stack-orchestration',
-    'e2e-validation',
-    'write-integration-tests',
-    'relay-orchestrator'
-];
-export const BUILT_IN_PERSONA_INTENTS = ['persona-authoring', 'persona-improvement'];
-export const CODEX_SANDBOX_MODES = [
-    'read-only',
-    'workspace-write',
-    'danger-full-access'
-];
-export const CODEX_APPROVAL_POLICIES = [
-    'untrusted',
-    'on-failure',
-    'on-request',
-    'never'
-];
-/**
- * Sidecar markdown delivery mode. `overwrite` writes only the persona's
- * resolved markdown into the harness's mount file. `extend` reads the
- * caller's real-cwd file (if any) and prepends it to the persona content,
- * separated by `\n\n---\n\n`. With no real-cwd file `extend` degrades to
- * `overwrite` semantics — the persona content lands alone.
- */
-export const SIDECAR_MD_MODES = ['overwrite', 'extend'];
-export const PERMISSION_MODES = [
-    'default',
-    'acceptEdits',
-    'bypassPermissions',
-    'plan'
-];
-// ---------------------------------------------------------------------------
-// Skill materialization
-// ---------------------------------------------------------------------------
-//
-// Personas declare *what* skill they need via `skills: [{ id, source, ... }]`.
-// The SDK is the only layer that knows *how* to make that skill available to
-// a given harness — because each harness has its own on-disk convention and
-// its own prpm install flag. Keeping this mapping here means:
-//
-//   1. Workflow authors never hand-type `prpm install ... --as codex`.
-//   2. Changing install rules is a one-line SDK edit, not a repo-wide grep.
-//   3. Persona JSON stays harness-agnostic and forward-compatible.
-//
-// `materializeSkills` is a pure function: it returns the install plan but
-// never touches the filesystem or spawns processes. Callers (relay workflows,
-// the OpenClaw spawner, ad-hoc scripts) decide how to execute it.
-export const SKILL_SOURCE_KINDS = ['prpm', 'skill.sh'];
-export const HARNESS_SKILL_TARGETS = {
-    claude: { asFlag: 'claude', dir: '.claude/skills' },
-    codex: { asFlag: 'codex', dir: '.agents/skills' },
-    opencode: { asFlag: 'opencode', dir: '.skills' }
-};
-const PRPM_URL_RE = /^https?:\/\/prpm\.dev\/packages\/([^/\s?#]+)\/([^/\s?#]+)\/?(?:[?#].*)?$/i;
-const PRPM_BARE_REF_RE = /^([^/\s]+)\/([^/\s]+)$/;
-function lastSegment(ref) {
-    const slash = ref.lastIndexOf('/');
-    return slash >= 0 ? ref.slice(slash + 1) : ref;
-}
-const prpmProvider = {
-    kind: 'prpm',
-    parse(source) {
-        const urlMatch = source.match(PRPM_URL_RE);
-        if (urlMatch) {
-            const ref = `${urlMatch[1]}/${urlMatch[2]}`;
-            return { kind: 'prpm', packageRef: ref, installedName: lastSegment(ref) };
-        }
-        const bareMatch = source.match(PRPM_BARE_REF_RE);
-        if (bareMatch) {
-            return { kind: 'prpm', packageRef: source, installedName: lastSegment(source) };
-        }
-        return null;
-    },
-    buildInstallCommand(ref, harness) {
-        const target = HARNESS_SKILL_TARGETS[harness];
-        return Object.freeze([
-            'npx',
-            '-y',
-            'prpm',
-            'install',
-            ref.packageRef,
-            '--as',
-            target.asFlag
-        ]);
-    },
-    cleanupPaths(ref, harness) {
-        const target = HARNESS_SKILL_TARGETS[harness];
-        return Object.freeze([`${target.dir}/${ref.installedName}`]);
-    }
-};
-// skill.sh source forms:
-// - `<github-url>#<skill-name>`
-// - `<github-url>/tree/<ref>/<path-to-skill>`
-// Examples:
-// - `https://github.com/vercel-labs/skills#find-skills`
-// - `https://github.com/wsimmonds/claude-nextjs-skills/tree/main/nextjs-anti-patterns`
-const SKILL_SH_URL_RE = /^(https?:\/\/github\.com\/[^/\s?#]+\/[^/\s?#]+?)(?:\.git)?#([^\s?#]+)$/i;
-const SKILL_SH_TREE_URL_RE = /^(https?:\/\/github\.com\/[^/\s?#]+\/[^/\s?#]+?)(?:\.git)?\/tree\/([^/\s?#]+)\/([^?#]+?)(?:[?#].*)?$/i;
-const SKILL_NAME_RE = /^(?!\.{1,2}$)[A-Za-z0-9][A-Za-z0-9._-]*$/;
-function toSafeSkillName(raw) {
-    const name = raw.trim();
-    return SKILL_NAME_RE.test(name) ? name : null;
-}
-/**
- * Paths `npx skills add` writes per install. Mirrors the on-disk layout from
- * a live `npx -y skills add ... -y` run (universal dir + harness-side
- * symlinks). `skills-lock.json` is deliberately excluded so repeat runs can
- * re-resolve from the lock instead of refetching sources.
- */
-function skillShArtifactPaths(installedName) {
-    return Object.freeze([
-        `.agents/skills/${installedName}`,
-        `.claude/skills/${installedName}`,
-        `.factory/skills/${installedName}`,
-        `.kiro/skills/${installedName}`,
-        `skills/${installedName}`
-    ]);
-}
-const skillShProvider = {
-    kind: 'skill.sh',
-    parse(source) {
-        const match = source.match(SKILL_SH_URL_RE);
-        if (match) {
-            const [, repoUrl, rawSkillName] = match;
-            const skillName = toSafeSkillName(rawSkillName);
-            if (!skillName)
-                return null;
-            return {
-                kind: 'skill.sh',
-                // packageRef preserves the full `<repo>#<skill>` shape so the command builder
-                // can reconstruct both halves without re-parsing the original source.
-                packageRef: `${repoUrl}#${skillName}`,
-                installedName: skillName
-            };
-        }
-        const treeMatch = source.match(SKILL_SH_TREE_URL_RE);
-        if (!treeMatch)
-            return null;
-        const [, repoUrl, ref, skillPath] = treeMatch;
-        const skillName = toSafeSkillName(skillPath.split('/').filter(Boolean).at(-1) ?? '');
-        if (!skillName)
-            return null;
-        return {
-            kind: 'skill.sh',
-            packageRef: `${repoUrl}/tree/${ref}#${skillName}`,
-            installedName: skillName
-        };
-    },
-    buildInstallCommand(ref) {
-        const [repoUrl, skillName] = ref.packageRef.split('#');
-        return Object.freeze([
-            'npx',
-            '-y',
-            'skills',
-            'add',
-            repoUrl,
-            '--skill',
-            skillName,
-            '-y'
-        ]);
-    },
-    cleanupPaths(ref) {
-        // skill.sh installs the same universal dir + harness symlinks regardless
-        // of which agent is the "host" — clean all of them so nothing leaks into
-        // `.claude/`, `.agents/`, etc. after the persona run.
-        return skillShArtifactPaths(ref.installedName);
-    }
-};
-const SKILL_PROVIDERS = Object.freeze([prpmProvider, skillShProvider]);
-function resolveSkillSource(source) {
-    for (const provider of SKILL_PROVIDERS) {
-        const parsed = provider.parse(source);
-        if (parsed) {
-            return parsed;
-        }
-    }
-    throw new Error(`Unsupported skill source: ${source}. ` +
-        `Supported forms: prpm.dev package URL (https://prpm.dev/packages/<scope>/<name>), ` +
-        `bare "<scope>/<name>" prpm reference, ` +
-        `skill.sh github URL with skill fragment (https://github.com/<org>/<repo>#<skill>), ` +
-        `or GitHub tree URL to a skill directory (https://github.com/<org>/<repo>/tree/<ref>/<skill>).`);
-}
-function providerFor(kind) {
-    const provider = SKILL_PROVIDERS.find((p) => p.kind === kind);
-    if (!provider) {
-        throw new Error(`No skill provider registered for kind: ${kind}`);
-    }
-    return provider;
-}
-/**
- * Given a set of persona skills and the harness the persona will run under,
- * produce the concrete install plan: which install invocations to run, where
- * the skill will land on disk, and which artifact paths should be cleaned up
- * after the persona run to keep the workspace tidy.
- *
- * Pure function — does not execute commands or touch the filesystem.
- */
-export function materializeSkills(skills, harness, options = {}) {
-    const target = HARNESS_SKILL_TARGETS[harness];
-    if (!target) {
-        throw new Error(`No skill install target configured for harness: ${harness}`);
-    }
-    const { installRoot } = options;
-    if (installRoot !== undefined && harness !== 'claude') {
-        throw new Error(`installRoot is only supported for the claude harness (got: ${harness}). ` +
-            `codex and opencode still install into the harness's conventional repo-relative directory.`);
-    }
-    const installs = skills.map((skill) => {
-        const resolved = resolveSkillSource(skill.source);
-        const provider = providerFor(resolved.kind);
-        const baseCommand = provider.buildInstallCommand(resolved, harness);
-        // In session-install-root mode, the install runs `cd <installRoot> && <prpm>`
-        // so that prpm's harness-relative dirs (`.claude/skills/<name>`) land
-        // inside the stage dir instead of the user's repo. The per-install command
-        // stays self-contained so callers who run a single install.installCommand
-        // directly still get the correct placement.
-        const installCommand = installRoot !== undefined
-            ? Object.freeze([
-                'sh',
-                '-c',
-                `cd ${shellEscape(installRoot)} && ${commandToShellString(baseCommand)}`
-            ])
-            : baseCommand;
-        // For prompt-injection fallback we still want a single canonical manifest
-        // path. prpm installs into the harness target dir; skill.sh installs into
-        // its universal `.agents/skills` dir regardless of harness, so key off
-        // whichever cleanup path ends in the installed name.
-        const repoRelativeDir = resolved.kind === 'skill.sh'
-            ? `.agents/skills/${resolved.installedName}`
-            : `${target.dir}/${resolved.installedName}`;
-        const installedDir = installRoot !== undefined ? `${installRoot}/${repoRelativeDir}` : repoRelativeDir;
-        // When the plan stages into `installRoot`, cleanup targets the whole
-        // session dir (handled at plan level in buildCleanupArtifacts). Leave
-        // per-skill cleanupPaths empty so callers running individual
-        // install.cleanupPaths don't accidentally remove unrelated things.
-        const cleanupPaths = installRoot !== undefined
-            ? Object.freeze([])
-            : provider.cleanupPaths(resolved, harness);
-        return {
-            skillId: skill.id,
-            source: skill.source,
-            sourceKind: resolved.kind,
-            packageRef: resolved.packageRef,
-            harness,
-            installCommand,
-            installedDir,
-            installedManifest: `${installedDir}/SKILL.md`,
-            cleanupPaths
-        };
-    });
-    return {
-        harness,
-        installs,
-        ...(installRoot !== undefined ? { sessionInstallRoot: installRoot } : {})
-    };
-}
-/**
- * Convenience wrapper: derive the install plan directly from a resolved
- * persona selection, using its tier's harness automatically.
- */
-export function materializeSkillsFor(selection, options = {}) {
-    return materializeSkills(selection.skills, selection.runtime.harness, options);
-}
-function shellEscape(value) {
-    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
-        return value;
-    }
-    return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-function commandToShellString(command) {
-    return command.map(shellEscape).join(' ');
-}
-/**
- * Minimal Claude Code plugin manifest written to `<root>/.claude-plugin/plugin.json`
- * in session-install-root mode. Claude's plugin loader treats any directory
- * that contains this file (alongside a `skills/` tree) as a plugin; we pass
- * the root to `claude --plugin-dir <root>` so the session sees exactly the
- * skills we staged — and nothing the repo happens to carry.
- */
-const SESSION_PLUGIN_MANIFEST = JSON.stringify({
-    name: 'agent-workforce-session',
-    version: '0.0.0',
-    description: 'Ephemeral skills staged by agent-workforce for this session.'
-});
-function buildSessionScaffoldCommand(root) {
-    const q = shellEscape(root);
-    // mkdir -p creates both the plugin metadata dir and the prpm target.
-    // `ln -sfn .claude/skills skills` makes Claude's expected plugin layout
-    // (`<root>/skills/<name>/SKILL.md`) resolve to prpm's actual output
-    // (`<root>/.claude/skills/<name>/SKILL.md`) without moving any files.
-    // The -n guards against following into an existing `skills/` dir (e.g.
-    // when the session dir is reused), and -f replaces a prior symlink so
-    // the scaffold is idempotent.
-    return [
-        `mkdir -p ${q}/.claude-plugin ${q}/.claude/skills`,
-        `ln -sfn .claude/skills ${q}/skills`,
-        `printf '%s' ${shellEscape(SESSION_PLUGIN_MANIFEST)} > ${q}/.claude-plugin/plugin.json`
-    ].join(' && ');
-}
-function buildInstallArtifacts(plan) {
-    if (plan.sessionInstallRoot !== undefined) {
-        // Session mode always stages a plugin dir so the caller can pass
-        // `--plugin-dir <root>` to claude unconditionally. Even for personas
-        // with zero skills, we emit the scaffold (mkdir + manifest + symlink)
-        // so the `--plugin-dir` target exists.
-        const root = plan.sessionInstallRoot;
-        const scaffold = buildSessionScaffoldCommand(root);
-        if (plan.installs.length === 0) {
-            return {
-                installCommand: Object.freeze(['sh', '-c', scaffold]),
-                installCommandString: scaffold
-            };
-        }
-        // Chain the raw provider commands after a single `cd <root>` so we emit
-        // one shell invocation instead of repeating the cd per skill. Each
-        // install.installCommand is already self-contained (`sh -c 'cd <root> &&
-        // …'`) for callers who want to run one at a time, but here we flatten
-        // to the underlying prpm argv for a cleaner chain.
-        const perSkill = plan.installs
-            .map((install) => {
-            const resolved = resolveSkillSource(install.source);
-            const provider = providerFor(resolved.kind);
-            return commandToShellString(provider.buildInstallCommand(resolved, plan.harness));
-        })
-            .join(' && ');
-        const installCommandString = `${scaffold} && cd ${shellEscape(root)} && ${perSkill}`;
-        return {
-            installCommand: Object.freeze(['sh', '-c', installCommandString]),
-            installCommandString
-        };
-    }
-    if (plan.installs.length === 0) {
-        return {
-            installCommand: Object.freeze(['sh', '-c', ':']),
-            installCommandString: ':'
-        };
-    }
-    const installCommandString = plan.installs
-        .map((install) => commandToShellString(install.installCommand))
-        .join(' && ');
-    return {
-        installCommand: Object.freeze(['sh', '-c', installCommandString]),
-        installCommandString
-    };
-}
-/**
- * Post-run cleanup: one shell command that removes every ephemeral artifact
- * path declared across all installs in the plan. Runs AFTER the agent step so
- * the agent can still read skill manifests off disk during execution. The
- * provider lockfile is deliberately not in the path set, so repeat runs keep
- * cached resolution.
- *
- * Empty plans return `:` (shell no-op) to keep the post-step shape uniform.
- */
-function buildCleanupArtifacts(plan) {
-    // Session mode: cleanup is the whole stage dir. The scaffold always runs
-    // (even for zero-skill personas), so cleanup unconditionally drops the
-    // stage dir. The CLI is responsible for removing the enclosing session
-    // root; this command covers the install subtree.
-    if (plan.sessionInstallRoot !== undefined) {
-        const cleanupCommandString = `rm -rf ${shellEscape(plan.sessionInstallRoot)}`;
-        return {
-            cleanupCommand: Object.freeze(['sh', '-c', cleanupCommandString]),
-            cleanupCommandString
-        };
-    }
-    const allPaths = plan.installs.flatMap((install) => [...install.cleanupPaths]);
-    const cleanupCommandString = allPaths.length === 0 ? ':' : `rm -rf ${allPaths.map(shellEscape).join(' ')}`;
-    return {
-        cleanupCommand: Object.freeze(['sh', '-c', cleanupCommandString]),
-        cleanupCommandString
-    };
-}
-function deepFreeze(value) {
-    if (value === null || value === undefined || typeof value !== 'object') {
-        return value;
-    }
-    if (Array.isArray(value)) {
-        for (const entry of value) {
-            deepFreeze(entry);
-        }
-        return Object.freeze(value);
-    }
-    for (const nested of Object.values(value)) {
-        deepFreeze(nested);
-    }
-    return Object.freeze(value);
-}
-function isObject(value) {
-    return typeof value === 'object' && value !== null;
-}
-function isHarness(value) {
-    return typeof value === 'string' && HARNESS_VALUES.includes(value);
-}
-function isTier(value) {
-    return typeof value === 'string' && PERSONA_TIERS.includes(value);
-}
-function isIntent(value) {
-    return typeof value === 'string' && PERSONA_INTENTS.includes(value);
-}
-function isTag(value) {
-    return typeof value === 'string' && PERSONA_TAGS.includes(value);
-}
-function parseTags(value, context) {
-    if (!Array.isArray(value) || value.length === 0) {
-        throw new Error(`${context} must be a non-empty array of tags`);
-    }
-    const out = [];
-    for (const [idx, entry] of value.entries()) {
-        if (!isTag(entry)) {
-            throw new Error(`${context}[${idx}] must be one of: ${PERSONA_TAGS.join(', ')}`);
-        }
-        if (!out.includes(entry))
-            out.push(entry);
-    }
-    return out;
-}
-function isSidecarMode(value) {
-    return typeof value === 'string' && SIDECAR_MD_MODES.includes(value);
-}
-function assertSidecarPath(value, context) {
-    if (typeof value !== 'string' || !value.trim()) {
-        throw new Error(`${context} must be a non-empty string`);
-    }
-    if (value.startsWith('/')) {
-        throw new Error(`${context} must be a relative POSIX path; got absolute "${value}"`);
-    }
-    const segments = value.split(/[\\/]+/);
-    if (segments.some((s) => s === '..')) {
-        throw new Error(`${context} must not contain ".." segments`);
-    }
-    if (!value.toLowerCase().endsWith('.md')) {
-        throw new Error(`${context} must end with .md`);
-    }
-}
-function parseHarnessSettings(value, context) {
-    if (!isObject(value)) {
-        throw new Error(`${context} must be an object`);
-    }
-    const { reasoning, timeoutSeconds, sandboxMode, approvalPolicy, workspaceWriteNetworkAccess, webSearch } = value;
-    if (!['low', 'medium', 'high'].includes(String(reasoning))) {
-        throw new Error(`${context}.reasoning must be low|medium|high`);
-    }
-    if (typeof timeoutSeconds !== 'number' || !Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
-        throw new Error(`${context}.timeoutSeconds must be a positive number`);
-    }
-    const out = {
-        reasoning: reasoning,
-        timeoutSeconds
-    };
-    if (sandboxMode !== undefined) {
-        if (!CODEX_SANDBOX_MODES.includes(sandboxMode)) {
-            throw new Error(`${context}.sandboxMode must be one of: ${CODEX_SANDBOX_MODES.join(', ')}`);
-        }
-        out.sandboxMode = sandboxMode;
-    }
-    if (approvalPolicy !== undefined) {
-        if (!CODEX_APPROVAL_POLICIES.includes(approvalPolicy)) {
-            throw new Error(`${context}.approvalPolicy must be one of: ${CODEX_APPROVAL_POLICIES.join(', ')}`);
-        }
-        out.approvalPolicy = approvalPolicy;
-    }
-    if (workspaceWriteNetworkAccess !== undefined) {
-        if (typeof workspaceWriteNetworkAccess !== 'boolean') {
-            throw new Error(`${context}.workspaceWriteNetworkAccess must be a boolean`);
-        }
-        out.workspaceWriteNetworkAccess = workspaceWriteNetworkAccess;
-    }
-    if (webSearch !== undefined) {
-        if (typeof webSearch !== 'boolean') {
-            throw new Error(`${context}.webSearch must be a boolean`);
-        }
-        out.webSearch = webSearch;
-    }
-    return out;
-}
-function parseRuntime(value, context) {
-    if (!isObject(value)) {
-        throw new Error(`${context} must be an object`);
-    }
-    const { harness, model, systemPrompt, harnessSettings, claudeMd, claudeMdMode, agentsMd, agentsMdMode, claudeMdContent, agentsMdContent } = value;
-    if (!isHarness(harness)) {
-        throw new Error(`${context}.harness must be one of: ${HARNESS_VALUES.join(', ')}`);
-    }
-    if (typeof model !== 'string' || !model.trim()) {
-        throw new Error(`${context}.model must be a non-empty string`);
-    }
-    if (typeof systemPrompt !== 'string' || !systemPrompt.trim()) {
-        throw new Error(`${context}.systemPrompt must be a non-empty string`);
-    }
-    const parsedHarnessSettings = parseHarnessSettings(harnessSettings, `${context}.harnessSettings`);
-    if (claudeMd !== undefined)
-        assertSidecarPath(claudeMd, `${context}.claudeMd`);
-    if (agentsMd !== undefined)
-        assertSidecarPath(agentsMd, `${context}.agentsMd`);
-    if (claudeMdMode !== undefined && !isSidecarMode(claudeMdMode)) {
-        throw new Error(`${context}.claudeMdMode must be one of: ${SIDECAR_MD_MODES.join(', ')}`);
-    }
-    if (agentsMdMode !== undefined && !isSidecarMode(agentsMdMode)) {
-        throw new Error(`${context}.agentsMdMode must be one of: ${SIDECAR_MD_MODES.join(', ')}`);
-    }
-    // Mode is allowed without a same-level path: a tier may declare just
-    // `claudeMdMode` and inherit the path from the spec top-level (or vice
-    // versa). The cascade validates that a path/content actually exists at
-    // runtime — a stranded mode with no path anywhere becomes a no-op.
-    if (claudeMdContent !== undefined && (typeof claudeMdContent !== 'string' || !claudeMdContent.length)) {
-        throw new Error(`${context}.claudeMdContent must be a non-empty string`);
-    }
-    if (agentsMdContent !== undefined && (typeof agentsMdContent !== 'string' || !agentsMdContent.length)) {
-        throw new Error(`${context}.agentsMdContent must be a non-empty string`);
-    }
-    return {
-        harness,
-        model,
-        systemPrompt,
-        harnessSettings: parsedHarnessSettings,
-        ...(typeof claudeMd === 'string' ? { claudeMd } : {}),
-        ...(claudeMdMode ? { claudeMdMode: claudeMdMode } : {}),
-        ...(typeof agentsMd === 'string' ? { agentsMd } : {}),
-        ...(agentsMdMode ? { agentsMdMode: agentsMdMode } : {}),
-        ...(typeof claudeMdContent === 'string' ? { claudeMdContent } : {}),
-        ...(typeof agentsMdContent === 'string' ? { agentsMdContent } : {})
-    };
-}
-function parseSkills(value, context) {
-    if (value === undefined) {
-        return [];
-    }
-    if (!Array.isArray(value)) {
-        throw new Error(`${context} must be an array if provided`);
-    }
-    return value.map((entry, idx) => {
-        const entryContext = `${context}[${idx}]`;
-        if (!isObject(entry)) {
-            throw new Error(`${entryContext} must be an object`);
-        }
-        const { id, source, description } = entry;
-        if (typeof id !== 'string' || !id.trim()) {
-            throw new Error(`${entryContext}.id must be a non-empty string`);
-        }
-        if (typeof source !== 'string' || !source.trim()) {
-            throw new Error(`${entryContext}.source must be a non-empty string`);
-        }
-        if (typeof description !== 'string' || !description.trim()) {
-            throw new Error(`${entryContext}.description must be a non-empty string`);
-        }
-        return { id, source, description };
-    });
-}
-function parseStringList(value, context) {
-    if (value === undefined)
-        return undefined;
-    if (!Array.isArray(value)) {
-        throw new Error(`${context} must be an array if provided`);
-    }
-    const parsed = value.map((entry, idx) => {
-        if (typeof entry !== 'string' || !entry.trim()) {
-            throw new Error(`${context}[${idx}] must be a non-empty string`);
-        }
-        return entry;
-    });
-    return parsed.length > 0 ? parsed : undefined;
-}
-function parseMount(value, context) {
-    if (value === undefined)
-        return undefined;
-    if (!isObject(value)) {
-        throw new Error(`${context} must be an object if provided`);
-    }
-    const ignoredPatterns = parseStringList(value.ignoredPatterns, `${context}.ignoredPatterns`);
-    const readonlyPatterns = parseStringList(value.readonlyPatterns, `${context}.readonlyPatterns`);
-    return ignoredPatterns || readonlyPatterns
-        ? {
-            ...(ignoredPatterns ? { ignoredPatterns } : {}),
-            ...(readonlyPatterns ? { readonlyPatterns } : {})
-        }
-        : undefined;
-}
-const INPUT_NAME_RE = /^[A-Z_][A-Z0-9_]*$/;
-function assertInputName(name, context) {
-    if (!INPUT_NAME_RE.test(name)) {
-        throw new Error(`${context} must be an env-style name matching ${INPUT_NAME_RE.source}`);
-    }
-}
-function parseInputs(value, context) {
-    if (value === undefined)
-        return undefined;
-    if (!isObject(value)) {
-        throw new Error(`${context} must be an object if provided`);
-    }
-    const out = {};
-    for (const [name, raw] of Object.entries(value)) {
-        assertInputName(name, `${context}.${name}`);
-        if (typeof raw === 'string') {
-            if (!raw) {
-                throw new Error(`${context}.${name} default must be non-empty`);
-            }
-            out[name] = { default: raw };
-            continue;
-        }
-        if (!isObject(raw)) {
-            throw new Error(`${context}.${name} must be a string default or an object`);
-        }
-        const { description, env, default: defaultValue, optional } = raw;
-        const parsed = {};
-        if (description !== undefined) {
-            if (typeof description !== 'string' || !description.trim()) {
-                throw new Error(`${context}.${name}.description must be a non-empty string if provided`);
-            }
-            parsed.description = description;
-        }
-        if (env !== undefined) {
-            if (typeof env !== 'string' || !env.trim()) {
-                throw new Error(`${context}.${name}.env must be a non-empty string if provided`);
-            }
-            assertInputName(env, `${context}.${name}.env`);
-            parsed.env = env;
-        }
-        if (defaultValue !== undefined) {
-            if (typeof defaultValue !== 'string' || !defaultValue) {
-                throw new Error(`${context}.${name}.default must be a non-empty string if provided`);
-            }
-            parsed.default = defaultValue;
-        }
-        if (optional !== undefined) {
-            if (typeof optional !== 'boolean') {
-                throw new Error(`${context}.${name}.optional must be a boolean if provided`);
-            }
-            if (optional && parsed.default !== undefined) {
-                throw new Error(`${context}.${name} cannot set both 'optional: true' and 'default' — pick one (defaults already make an input always-resolved)`);
-            }
-            parsed.optional = optional;
-        }
-        out[name] = parsed;
-    }
-    return Object.keys(out).length > 0 ? out : undefined;
-}
-function parsePersonaSpec(value, expectedIntent) {
-    if (!isObject(value)) {
-        throw new Error(`persona[${expectedIntent}] must be an object`);
-    }
-    const { id, intent, tags, description, tiers, defaultTier, skills, inputs, env, mcpServers, permissions, mount, claudeMd, claudeMdMode, agentsMd, agentsMdMode, claudeMdContent, agentsMdContent } = value;
-    if (typeof id !== 'string' || !id.trim()) {
-        throw new Error(`persona[${expectedIntent}].id must be a non-empty string`);
-    }
-    if (!isIntent(intent)) {
-        throw new Error(`persona[${expectedIntent}].intent is invalid`);
-    }
-    if (intent !== expectedIntent) {
-        throw new Error(`persona[${expectedIntent}] intent mismatch: got ${intent}`);
-    }
-    const parsedTags = parseTags(tags, `persona[${expectedIntent}].tags`);
-    if (typeof description !== 'string' || !description.trim()) {
-        throw new Error(`persona[${expectedIntent}].description must be a non-empty string`);
-    }
-    if (!isObject(tiers)) {
-        throw new Error(`persona[${expectedIntent}].tiers must be an object`);
-    }
-    const parsedTiers = {};
-    for (const tier of PERSONA_TIERS) {
-        parsedTiers[tier] = parseRuntime(tiers[tier], `persona[${expectedIntent}].tiers.${tier}`);
-    }
-    let parsedDefaultTier;
-    if (defaultTier !== undefined) {
-        if (!isTier(defaultTier)) {
-            throw new Error(`persona[${expectedIntent}].defaultTier must be one of: ${PERSONA_TIERS.join(', ')}`);
-        }
-        parsedDefaultTier = defaultTier;
-    }
-    const parsedSkills = parseSkills(skills, `persona[${expectedIntent}].skills`);
-    const parsedInputs = parseInputs(inputs, `persona[${expectedIntent}].inputs`);
-    const parsedEnv = parseStringMap(env, `persona[${expectedIntent}].env`);
-    const parsedMcpServers = parseMcpServers(mcpServers, `persona[${expectedIntent}].mcpServers`);
-    const parsedPermissions = parsePermissions(permissions, `persona[${expectedIntent}].permissions`);
-    const parsedMount = parseMount(mount, `persona[${expectedIntent}].mount`);
-    if (claudeMd !== undefined)
-        assertSidecarPath(claudeMd, `persona[${expectedIntent}].claudeMd`);
-    if (agentsMd !== undefined)
-        assertSidecarPath(agentsMd, `persona[${expectedIntent}].agentsMd`);
-    if (claudeMdMode !== undefined && !isSidecarMode(claudeMdMode)) {
-        throw new Error(`persona[${expectedIntent}].claudeMdMode must be one of: ${SIDECAR_MD_MODES.join(', ')}`);
-    }
-    if (agentsMdMode !== undefined && !isSidecarMode(agentsMdMode)) {
-        throw new Error(`persona[${expectedIntent}].agentsMdMode must be one of: ${SIDECAR_MD_MODES.join(', ')}`);
-    }
-    // Spec-level mode without a spec-level path is allowed — a tier may
-    // supply the path while inheriting the mode here. See parseRuntime.
-    if (claudeMdContent !== undefined &&
-        (typeof claudeMdContent !== 'string' || !claudeMdContent.length)) {
-        throw new Error(`persona[${expectedIntent}].claudeMdContent must be a non-empty string`);
-    }
-    if (agentsMdContent !== undefined &&
-        (typeof agentsMdContent !== 'string' || !agentsMdContent.length)) {
-        throw new Error(`persona[${expectedIntent}].agentsMdContent must be a non-empty string`);
-    }
-    return {
-        id,
-        intent,
-        tags: parsedTags,
-        description,
-        skills: parsedSkills,
-        ...(parsedInputs ? { inputs: parsedInputs } : {}),
-        tiers: parsedTiers,
-        ...(parsedDefaultTier ? { defaultTier: parsedDefaultTier } : {}),
-        ...(parsedEnv ? { env: parsedEnv } : {}),
-        ...(parsedMcpServers ? { mcpServers: parsedMcpServers } : {}),
-        ...(parsedPermissions ? { permissions: parsedPermissions } : {}),
-        ...(parsedMount ? { mount: parsedMount } : {}),
-        ...(typeof claudeMd === 'string' ? { claudeMd } : {}),
-        ...(claudeMdMode ? { claudeMdMode: claudeMdMode } : {}),
-        ...(typeof agentsMd === 'string' ? { agentsMd } : {}),
-        ...(agentsMdMode ? { agentsMdMode: agentsMdMode } : {}),
-        ...(typeof claudeMdContent === 'string' ? { claudeMdContent } : {}),
-        ...(typeof agentsMdContent === 'string' ? { agentsMdContent } : {})
-    };
-}
-function parsePermissions(value, context) {
-    if (value === undefined)
-        return undefined;
-    if (!isObject(value)) {
-        throw new Error(`${context} must be an object if provided`);
-    }
-    const out = {};
-    const { allow, deny, mode } = value;
-    if (allow !== undefined) {
-        if (!Array.isArray(allow) || allow.some((s) => typeof s !== 'string' || !s.trim())) {
-            throw new Error(`${context}.allow must be an array of non-empty strings`);
-        }
-        out.allow = allow;
-    }
-    if (deny !== undefined) {
-        if (!Array.isArray(deny) || deny.some((s) => typeof s !== 'string' || !s.trim())) {
-            throw new Error(`${context}.deny must be an array of non-empty strings`);
-        }
-        out.deny = deny;
-    }
-    if (mode !== undefined) {
-        if (!PERMISSION_MODES.includes(mode)) {
-            throw new Error(`${context}.mode must be one of: ${PERMISSION_MODES.join(', ')}`);
-        }
-        out.mode = mode;
-    }
-    return Object.keys(out).length > 0 ? out : undefined;
-}
-function parseStringMap(value, context) {
-    if (value === undefined)
-        return undefined;
-    if (!isObject(value)) {
-        throw new Error(`${context} must be an object if provided`);
-    }
-    const out = {};
-    for (const [key, v] of Object.entries(value)) {
-        if (typeof v !== 'string') {
-            throw new Error(`${context}.${key} must be a string`);
-        }
-        out[key] = v;
-    }
-    return out;
-}
-function parseMcpServers(value, context) {
-    if (value === undefined)
-        return undefined;
-    if (!isObject(value)) {
-        throw new Error(`${context} must be an object if provided`);
-    }
-    const out = {};
-    for (const [name, raw] of Object.entries(value)) {
-        if (!isObject(raw)) {
-            throw new Error(`${context}.${name} must be an object`);
-        }
-        const type = raw.type;
-        if (type === 'http' || type === 'sse') {
-            if (typeof raw.url !== 'string' || !raw.url.trim()) {
-                throw new Error(`${context}.${name}.url must be a non-empty string for type=${type}`);
-            }
-            const headers = parseStringMap(raw.headers, `${context}.${name}.headers`);
-            out[name] = { type, url: raw.url, ...(headers ? { headers } : {}) };
-        }
-        else if (type === 'stdio') {
-            if (typeof raw.command !== 'string' || !raw.command.trim()) {
-                throw new Error(`${context}.${name}.command must be a non-empty string for type=stdio`);
-            }
-            const args = raw.args;
-            if (args !== undefined && (!Array.isArray(args) || args.some((a) => typeof a !== 'string'))) {
-                throw new Error(`${context}.${name}.args must be an array of strings`);
-            }
-            const env = parseStringMap(raw.env, `${context}.${name}.env`);
-            out[name] = {
-                type: 'stdio',
-                command: raw.command,
-                ...(args ? { args: args } : {}),
-                ...(env ? { env } : {})
-            };
-        }
-        else {
-            throw new Error(`${context}.${name}.type must be one of: http, sse, stdio`);
-        }
-    }
-    return out;
-}
 function parseRoutingProfile(value, context) {
     if (!isObject(value)) {
         throw new Error(`${context} must be an object`);
@@ -894,52 +55,6 @@ function requireBuiltInPersona(intent) {
 export const routingProfiles = {
     default: parseRoutingProfile(defaultRoutingProfileJson, 'routingProfiles.default')
 };
-/**
- * Resolve the effective sidecar config for a (spec, tier) pair.
- *
- * Path-or-content resolution: each sidecar (`claude*`, `agents*`) is a
- * single "channel" — its `*Md` and `*MdContent` fields are tied together
- * and travel as a unit through the cascade. If the tier-level runtime
- * declares EITHER `claudeMd` or `claudeMdContent`, the tier owns the
- * channel and the top-level path/content is ignored (otherwise a tier
- * path override would silently lose to inherited inlined content, since
- * downstream consumers prefer Content over a path).
- *
- * Mode resolution: independent — a tier can set just `claudeMdMode` and
- * inherit the top-level path. Defaults to `overwrite` if neither layer
- * sets a mode. Modes are only meaningful when a path/content is present.
- */
-export function resolveSidecar(spec, tier) {
-    const runtime = spec.tiers[tier];
-    const tierOwnsClaude = runtime.claudeMd !== undefined || runtime.claudeMdContent !== undefined;
-    const tierOwnsAgents = runtime.agentsMd !== undefined || runtime.agentsMdContent !== undefined;
-    const claudePath = tierOwnsClaude ? runtime.claudeMd : spec.claudeMd;
-    const claudeContent = tierOwnsClaude ? runtime.claudeMdContent : spec.claudeMdContent;
-    const agentsPath = tierOwnsAgents ? runtime.agentsMd : spec.agentsMd;
-    const agentsContent = tierOwnsAgents ? runtime.agentsMdContent : spec.agentsMdContent;
-    return {
-        ...(claudePath ? { claudeMd: claudePath } : {}),
-        ...(claudeContent ? { claudeMdContent: claudeContent } : {}),
-        claudeMdMode: runtime.claudeMdMode ?? spec.claudeMdMode ?? 'overwrite',
-        ...(agentsPath ? { agentsMd: agentsPath } : {}),
-        ...(agentsContent ? { agentsMdContent: agentsContent } : {}),
-        agentsMdMode: runtime.agentsMdMode ?? spec.agentsMdMode ?? 'overwrite'
-    };
-}
-function sidecarSelectionFields(sidecar) {
-    return {
-        ...(sidecar.claudeMd ? { claudeMd: sidecar.claudeMd } : {}),
-        ...(sidecar.claudeMdContent ? { claudeMdContent: sidecar.claudeMdContent } : {}),
-        ...(sidecar.claudeMd || sidecar.claudeMdContent
-            ? { claudeMdMode: sidecar.claudeMdMode }
-            : {}),
-        ...(sidecar.agentsMd ? { agentsMd: sidecar.agentsMd } : {}),
-        ...(sidecar.agentsMdContent ? { agentsMdContent: sidecar.agentsMdContent } : {}),
-        ...(sidecar.agentsMd || sidecar.agentsMdContent
-            ? { agentsMdMode: sidecar.agentsMdMode }
-            : {})
-    };
-}
 export function resolvePersona(intent, profile = 'default') {
     const profileSpec = typeof profile === 'string' ? routingProfiles[profile] : profile;
     const rule = profileSpec.intents[intent];