@agentworkforce/workload-router 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,10 +1,21 @@
 import { spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { resolve as resolvePath } from 'node:path';
-import { frontendImplementer, codeReviewer, architecturePlanner, requirementsAnalyst, debuggerPersona, securityReviewer, technicalWriter, verifierPersona, testStrategist, tddGuard, flakeHunter, opencodeWorkflowSpecialist, npmProvenancePublisher, cloudSandboxInfra } from './generated/personas.js';
+import { frontendImplementer, codeReviewer, architecturePlanner, requirementsAnalyst, debuggerPersona, securityReviewer, technicalWriter, verifierPersona, testStrategist, tddGuard, flakeHunter, opencodeWorkflowSpecialist, npmProvenancePublisher, cloudSandboxInfra, sageSlackEgressMigrator, sageProactiveRewirer, cloudSlackProxyGuard, agentRelayE2eConductor, capabilityDiscoverer, posthogAgent } 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',
@@ -19,7 +30,19 @@ export const PERSONA_INTENTS = [
     'flake-investigation',
     'opencode-workflow-correctness',
     'npm-provenance',
-    'cloud-sandbox-infra'
+    'cloud-sandbox-infra',
+    'sage-slack-egress-migration',
+    'sage-proactive-rewire',
+    'cloud-slack-proxy-guard',
+    'sage-cloud-e2e-conduction',
+    'capability-discovery',
+    'posthog'
+];
+export const PERMISSION_MODES = [
+    'default',
+    'acceptEdits',
+    'bypassPermissions',
+    'plan'
 ];
 // ---------------------------------------------------------------------------
 // Skill materialization
@@ -37,7 +60,7 @@ export const PERSONA_INTENTS = [
 // `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'];
+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' },
@@ -63,66 +86,188 @@ class CapturedCommandError extends Error {
 }
 const PRPM_URL_RE = /^https?:\/\/prpm\.dev\/packages\/([^/\s?#]+)\/([^/\s?#]+)\/?(?:[?#].*)?$/i;
 const PRPM_BARE_REF_RE = /^([^/\s]+)\/([^/\s]+)$/;
-function resolveSkillSource(source) {
-    const urlMatch = source.match(PRPM_URL_RE);
-    if (urlMatch) {
-        return { kind: 'prpm', packageRef: `${urlMatch[1]}/${urlMatch[2]}` };
+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 form: `<github-url>#<skill-name>`
+// Example: `https://github.com/vercel-labs/skills#find-skills`
+const SKILL_SH_URL_RE = /^(https?:\/\/github\.com\/[^/\s?#]+\/[^/\s?#]+?)(?:\.git)?#([^\s?#]+)$/i;
+/**
+ * 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) {
+            return null;
+        }
+        const [, repoUrl, skillName] = match;
+        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
+        };
+    },
+    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 bareMatch = source.match(PRPM_BARE_REF_RE);
-    if (bareMatch) {
-        return { kind: 'prpm', packageRef: source };
+};
+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>) ` +
-        `or a bare "<scope>/<name>" reference.`);
+        `Supported forms: prpm.dev package URL (https://prpm.dev/packages/<scope>/<name>), ` +
+        `bare "<scope>/<name>" prpm reference, ` +
+        `or skill.sh github URL with skill fragment (https://github.com/<org>/<repo>#<skill>).`);
 }
-function deriveInstalledName(packageRef) {
-    const slash = packageRef.lastIndexOf('/');
-    return slash >= 0 ? packageRef.slice(slash + 1) : packageRef;
+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 `prpm install` invocations to run
- * and where the skill will land on disk once installed.
+ * 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) {
+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 { kind, packageRef } = resolveSkillSource(skill.source);
-        const installedName = deriveInstalledName(packageRef);
-        const installedDir = `${target.dir}/${installedName}`;
+        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 Mode B 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: kind,
-            packageRef,
+            sourceKind: resolved.kind,
+            packageRef: resolved.packageRef,
             harness,
-            installCommand: Object.freeze([
-                'npx',
-                '-y',
-                'prpm',
-                'install',
-                packageRef,
-                '--as',
-                target.asFlag
-            ]),
+            installCommand,
             installedDir,
-            installedManifest: `${installedDir}/SKILL.md`
+            installedManifest: `${installedDir}/SKILL.md`,
+            cleanupPaths
         };
     });
-    return { harness, installs };
+    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) {
-    return materializeSkills(selection.skills, selection.runtime.harness);
+export function materializeSkillsFor(selection, options = {}) {
+    return materializeSkills(selection.skills, selection.runtime.harness, options);
 }
 function shellEscape(value) {
     if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
@@ -133,15 +278,107 @@ function shellEscape(value) {
 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) {
-    const installCommandString = plan.installs.length === 0
-        ? ':'
-        : plan.installs.map((install) => commandToShellString(install.installCommand)).join(' && ');
+    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 buildExecutionTask(systemPrompt, task, inputs) {
     const sections = [`System Instructions:\n${systemPrompt.trim()}`, `Task:\n${task.trim()}`];
     if (inputs && Object.keys(inputs).length > 0) {
@@ -389,6 +626,23 @@ function isTier(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 parseRuntime(value, context) {
     if (!isObject(value)) {
         throw new Error(`${context} must be an object`);
@@ -452,7 +706,7 @@ function parsePersonaSpec(value, expectedIntent) {
     if (!isObject(value)) {
         throw new Error(`persona[${expectedIntent}] must be an object`);
     }
-    const { id, intent, description, tiers, skills } = value;
+    const { id, intent, tags, description, tiers, skills, env, mcpServers, permissions } = value;
     if (typeof id !== 'string' || !id.trim()) {
         throw new Error(`persona[${expectedIntent}].id must be a non-empty string`);
     }
@@ -462,6 +716,7 @@ function parsePersonaSpec(value, expectedIntent) {
     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`);
     }
@@ -473,14 +728,105 @@ function parsePersonaSpec(value, expectedIntent) {
         parsedTiers[tier] = parseRuntime(tiers[tier], `persona[${expectedIntent}].tiers.${tier}`);
     }
     const parsedSkills = parseSkills(skills, `persona[${expectedIntent}].skills`);
+    const parsedEnv = parseStringMap(env, `persona[${expectedIntent}].env`);
+    const parsedMcpServers = parseMcpServers(mcpServers, `persona[${expectedIntent}].mcpServers`);
+    const parsedPermissions = parsePermissions(permissions, `persona[${expectedIntent}].permissions`);
     return {
         id,
         intent,
+        tags: parsedTags,
         description,
         skills: parsedSkills,
-        tiers: parsedTiers
+        tiers: parsedTiers,
+        ...(parsedEnv ? { env: parsedEnv } : {}),
+        ...(parsedMcpServers ? { mcpServers: parsedMcpServers } : {}),
+        ...(parsedPermissions ? { permissions: parsedPermissions } : {})
     };
 }
+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`);
@@ -530,7 +876,13 @@ export const personaCatalog = {
     'flake-investigation': parsePersonaSpec(flakeHunter, 'flake-investigation'),
     'opencode-workflow-correctness': parsePersonaSpec(opencodeWorkflowSpecialist, 'opencode-workflow-correctness'),
     'npm-provenance': parsePersonaSpec(npmProvenancePublisher, 'npm-provenance'),
-    'cloud-sandbox-infra': parsePersonaSpec(cloudSandboxInfra, 'cloud-sandbox-infra')
+    'cloud-sandbox-infra': parsePersonaSpec(cloudSandboxInfra, 'cloud-sandbox-infra'),
+    'sage-slack-egress-migration': parsePersonaSpec(sageSlackEgressMigrator, 'sage-slack-egress-migration'),
+    'sage-proactive-rewire': parsePersonaSpec(sageProactiveRewirer, 'sage-proactive-rewire'),
+    'cloud-slack-proxy-guard': parsePersonaSpec(cloudSlackProxyGuard, 'cloud-slack-proxy-guard'),
+    'sage-cloud-e2e-conduction': parsePersonaSpec(agentRelayE2eConductor, 'sage-cloud-e2e-conduction'),
+    'capability-discovery': parsePersonaSpec(capabilityDiscoverer, 'capability-discovery'),
+    posthog: parsePersonaSpec(posthogAgent, 'posthog')
 };
 export const routingProfiles = {
     default: parseRoutingProfile(defaultRoutingProfileJson, 'routingProfiles.default')
@@ -544,7 +896,10 @@ export function resolvePersona(intent, profile = 'default') {
         tier: rule.tier,
         runtime: spec.tiers[rule.tier],
         skills: spec.skills,
-        rationale: `${profileSpec.id}: ${rule.rationale}`
+        rationale: `${profileSpec.id}: ${rule.rationale}`,
+        ...(spec.env ? { env: spec.env } : {}),
+        ...(spec.mcpServers ? { mcpServers: spec.mcpServers } : {}),
+        ...(spec.permissions ? { permissions: spec.permissions } : {})
     };
 }
 /**
@@ -558,7 +913,10 @@ export function resolvePersonaByTier(intent, tier = 'best-value') {
         tier,
         runtime: spec.tiers[tier],
         skills: spec.skills,
-        rationale: `legacy-tier-override: ${tier}`
+        rationale: `legacy-tier-override: ${tier}`,
+        ...(spec.env ? { env: spec.env } : {}),
+        ...(spec.mcpServers ? { mcpServers: spec.mcpServers } : {}),
+        ...(spec.permissions ? { permissions: spec.permissions } : {})
     };
 }
 /**
@@ -637,6 +995,18 @@ export function usePersona(intent, options = {}) {
     const baseSelection = options.tier
         ? resolvePersonaByTier(intent, options.tier)
         : resolvePersona(intent, options.profile ?? 'default');
+    return useSelection(baseSelection, {
+        harness: options.harness,
+        installRoot: options.installRoot
+    });
+}
+/**
+ * Same as {@link usePersona}, but takes a pre-resolved {@link PersonaSelection}
+ * instead of an intent. Use this when you have a selection produced outside
+ * the standard repo catalog — for example, a user-local persona override
+ * loaded from disk — and want the same install/sendMessage surface.
+ */
+export function useSelection(baseSelection, options = {}) {
     const effectiveHarness = options.harness ?? baseSelection.runtime.harness;
     const selection = effectiveHarness === baseSelection.runtime.harness
         ? baseSelection
@@ -647,16 +1017,20 @@ export function usePersona(intent, options = {}) {
                 harness: effectiveHarness
             }
         };
+    const materializationOptions = options.installRoot !== undefined ? { installRoot: options.installRoot } : {};
     const installPlan = effectiveHarness === baseSelection.runtime.harness
-        ? materializeSkillsFor(selection)
-        : materializeSkills(selection.skills, effectiveHarness);
+        ? materializeSkillsFor(selection, materializationOptions)
+        : materializeSkills(selection.skills, effectiveHarness, materializationOptions);
     const { installCommand, installCommandString } = buildInstallArtifacts(installPlan);
+    const { cleanupCommand, cleanupCommandString } = buildCleanupArtifacts(installPlan);
     const frozenSelection = deepFreeze(selection);
     const frozenInstallPlan = deepFreeze(installPlan);
     const frozenInstall = Object.freeze({
         plan: frozenInstallPlan,
         command: installCommand,
-        commandString: installCommandString
+        commandString: installCommandString,
+        cleanupCommand,
+        cleanupCommandString
     });
     const sendMessage = (task, sendMessageOptions = {}) => {
         const runId = createDeferred();
@@ -674,6 +1048,7 @@ export function usePersona(intent, options = {}) {
         const stepName = sanitizeExecutionName(sendMessageOptions.name ?? `${frozenSelection.personaId}-${hash8(task)}`);
         const workflowName = `use-persona-${stepName}`;
         const installStepName = `${stepName}-install-skills`;
+        const cleanupStepName = `${stepName}-cleanup-skills`;
         const workingDirectory = resolvePath(sendMessageOptions.workingDirectory ?? process.cwd());
         const timeoutMs = Math.max(1, Math.round((sendMessageOptions.timeoutSeconds ??
             frozenSelection.runtime.harnessSettings.timeoutSeconds) * 1000));
@@ -758,6 +1133,25 @@ export function usePersona(intent, options = {}) {
                     verification: { type: 'exit_code', value: '0' },
                     ...(shouldInstallSkills ? { dependsOn: [installStepName] } : {})
                 });
+                // Post-agent cleanup: removes the ephemeral skill artifact paths the
+                // provider scattered during the install step. Only runs when this
+                // sendMessage owns the install (Mode A) AND the agent step completed
+                // — if the agent step fails or is skipped, the dag runner will skip
+                // this step too, which is fine because (a) failure diagnostics stay
+                // on disk for the user to inspect, and (b) `rm -rf` is idempotent so
+                // a follow-up run can re-clean. The lockfile is deliberately not in
+                // cleanupPaths, so repeat runs still benefit from cached resolution.
+                if (shouldInstallSkills && frozenInstall.cleanupCommandString !== ':') {
+                    builder.step(cleanupStepName, {
+                        type: 'deterministic',
+                        command: frozenInstall.cleanupCommandString,
+                        cwd: workingDirectory,
+                        timeoutMs,
+                        captureOutput: true,
+                        failOnError: false,
+                        dependsOn: [stepName]
+                    });
+                }
                 if (abortController.signal.aborted) {
                     runner.abort();
                 }