use Revolution\Copilot\Enums\CatalogCandidateKind;
use Revolution\Copilot\Enums\CatalogCapability;
use Revolution\Copilot\Enums\CatalogSelectionDecision;
use Revolution\Copilot\Enums\CatalogTrustTier;
use Revolution\Copilot\Enums\SkillInstallationManagementOutcomeKind;
use Revolution\Copilot\Enums\SkillInstallationManagementResultKind;
use Revolution\Copilot\Enums\SkillsRemoveSourceOutcomeKind;
use Revolution\Copilot\Types\Rpc\AgentsDiscoverRequest;
use Revolution\Copilot\Types\Rpc\AgentsGetDiscoveryPathsRequest;
use Revolution\Copilot\Types\Rpc\CatalogClientContract;
use Revolution\Copilot\Types\Rpc\CatalogGetGeneratedFeedRequest;
use Revolution\Copilot\Types\Rpc\CatalogGetSavedFeedRequest;
use Revolution\Copilot\Types\Rpc\CatalogMaterializationReference;
use Revolution\Copilot\Types\Rpc\CatalogRecommendRequest;
use Revolution\Copilot\Types\Rpc\CatalogSearchRequest;
use Revolution\Copilot\Types\Rpc\CatalogSelectionRequest;
use Revolution\Copilot\Types\Rpc\InstructionsDiscoverRequest;
use Revolution\Copilot\Types\Rpc\InstructionsGetDiscoveryPathsRequest;
use Revolution\Copilot\Types\Rpc\PluginsBuiltinSetRequest;
use Revolution\Copilot\Types\Rpc\PluginsDisableRequest;
use Revolution\Copilot\Types\Rpc\PluginsEnableRequest;
use Revolution\Copilot\Types\Rpc\PluginsInstallRequest;
use Revolution\Copilot\Types\Rpc\PluginsMarketplacesAddRequest;
use Revolution\Copilot\Types\Rpc\PluginsMarketplacesBrowseRequest;
use Revolution\Copilot\Types\Rpc\PluginsMarketplacesRefreshRequest;
use Revolution\Copilot\Types\Rpc\PluginsMarketplacesRemoveRequest;
use Revolution\Copilot\Types\Rpc\PluginsUninstallRequest;
use Revolution\Copilot\Types\Rpc\PluginsUpdateRequest;
use Revolution\Copilot\Types\Rpc\SkillApplyInstallRequest;
use Revolution\Copilot\Types\Rpc\SkillApplyUninstallRequest;
use Revolution\Copilot\Types\Rpc\SkillInstallationOperationRequest;
use Revolution\Copilot\Types\Rpc\SkillInstallationsRequest;
use Revolution\Copilot\Types\Rpc\SkillPlanInstallRequest;
use Revolution\Copilot\Types\Rpc\SkillPlanUninstallRequest;
use Revolution\Copilot\Types\Rpc\SkillSetEnabledRequest;
use Revolution\Copilot\Types\Rpc\SkillsInstallSourceRequest;
use Revolution\Copilot\Types\Rpc\SkillsRemoveSourceRequest;
use Revolution\Copilot\Types\Rpc\SkillsGetDiscoveryPathsRequest;
// skills (gestión de skills a nivel de servidor)
// Explorar skills
$result = Copilot::client()->rpc()->skills()->discover();
// $result->skills es un array de ServerSkill
// Opcionalmente, indicar rutas de proyecto
$result = Copilot::client()->rpc()->skills()->discover(new SkillsDiscoverRequest(
projectPaths: ['/path/to/project'],
skillDirectories: ['/custom/skills'],
));
// Configurar las skills que se desactivan
Copilot::client()->rpc()->skills()->config()->setDisabledSkills(
new SkillsConfigSetDisabledSkillsRequest(disabledSkills: ['skill-name'])
);
// Activar o desactivar skills individuales
Copilot::client()->rpc()->skills()->config()->setSkillDisabled(
new SkillsConfigSetSkillDisabledRequest(name: 'skill-name', disabled: true)
);
// Instalar directamente desde una URL HTTPS o un archivo local (experimental)
$skills = Copilot::client()->rpc()->skills();
$installed = $skills->installSource(new SkillsInstallSourceRequest(
source: 'https://example.test/skills/review/SKILL.md',
cwd: '/workspace',
personalSkillsDir: '/home/user/.copilot/skills',
projectSkillsDir: '/workspace/.copilot/skills',
project: false,
skillDirectories: ['/custom/skills'],
userAgent: 'my-app/1.0',
));
// Persistir en el lado del llamador los skillDirectories devueltos
$skillDirectories = $installed->skillDirectories;
// Anular el registro de un directorio de descubrimiento. El contenido del directorio no se elimina
$removed = $skills->removeSource(new SkillsRemoveSourceRequest(
target: '/custom/skills',
cwd: '/workspace',
skillDirectories: $skillDirectories,
));
if ($removed->kind === SkillsRemoveSourceOutcomeKind::Removed) {
$skillDirectories = $removed->result->skillDirectories;
}
// Si eliminar archivos requiere un inventario y lo omites, se devuelve needs-inventory y no cambia nada
// Seleccionar un candidato de skill con catalog.search → catalog.select (experimental)
$contract = new CatalogClientContract(1, ['catalog-selection', 'ai-skill-installation']);
$catalog = Copilot::client()->rpc()->catalog();
// Obtener recomendaciones de productos oficiales a partir de un nombre de producto y una tarea completa (experimental)
$recommendations = $catalog->recommend(new CatalogRecommendRequest(
contract: new CatalogClientContract(1, [CatalogCapability::CatalogRecommend->value]),
query: 'Review this repository and identify security issues.',
product: 'GitHub Copilot',
));
$search = $catalog->search(new CatalogSearchRequest(
contract: $contract,
query: 'code review skill',
kinds: [CatalogCandidateKind::AiSkill],
));
$selection = $catalog->select(new CatalogSelectionRequest(
contract: $contract,
sessionId: $sessionId,
selectionRef: $search['candidates'][0]['selectionRef'],
outcome: CatalogSelectionDecision::Selected,
));
// El category filter requiere catalog-search-categories
$categoryContract = new CatalogClientContract(3, [
CatalogCapability::CatalogSearchCategories->value,
]);
$categorySearch = $catalog->search(new CatalogSearchRequest(
contract: $categoryContract,
query: 'design tools',
categories: ['design', 'test'],
));
// Si indicas policySessionId, el contract también debe requerir credential-required y session-bound,
// y solo se vincula a una attached session existente. Nunca crea ni reanuda una session.
// catalog feed guardado y generado (credential required)
$feedContract = new CatalogClientContract(3, [
CatalogCapability::CatalogFeeds->value,
CatalogCapability::CatalogSearchCredentialRequired->value,
]);
$savedFeed = $catalog->getSavedFeed(new CatalogGetSavedFeedRequest(
contract: $feedContract,
feedId: 'opaque-feed-id',
trustTiers: [CatalogTrustTier::T1],
));
// Para vincular a una attached session existente, requiere también la capability session-bound
$sessionFeedContract = new CatalogClientContract(3, [
CatalogCapability::CatalogFeeds->value,
CatalogCapability::CatalogSearchCredentialRequired->value,
CatalogCapability::CatalogSearchSessionBound->value,
]);
$generatedFeed = $catalog->getGeneratedFeed(new CatalogGetGeneratedFeedRequest(
contract: $sessionFeedContract,
strategy: 'telemetry',
key: 'popular',
policySessionId: $sessionId,
trustTiers: [CatalogTrustTier::T1, CatalogTrustTier::T2],
));
// entries conserva el orden del feed. Las que no coinciden con el trust tier mantienen su posición como filtered,
// y las entry que no se pueden mostrar se devuelven con unavailable y reason.
// Si no hay feed, kind=unavailable y reason=feed-not-found. Los rechazos por autenticación, negociación o política
// también se devuelven como resultados tipados, y las RPC de catalog feed no instalan ni configuran nada.
// Planificar y aplicar la instalación de skills
$skills = Copilot::client()->rpc()->skills();
if ($selection['kind'] === 'selected') {
$planned = $skills->planInstall(new SkillPlanInstallRequest(
contract: $contract,
candidateHandle: $selection['candidateHandle'],
policySessionId: $sessionId,
));
if ($planned->kind === SkillInstallationManagementResultKind::Outcome
&& $planned->outcome?->kind === SkillInstallationManagementOutcomeKind::InstallPlanned) {
// applyInstall() se aplica tras la confirmación mediante installations.confirm
$result = $skills->applyInstall(new SkillApplyInstallRequest(
contract: $contract,
planHandle: $planned->outcome->plan['planHandle'],
policySessionId: $sessionId,
));
}
}
// Skills instaladas y operaciones en curso
$installations = $skills->installations();
$owned = $installations->list(new SkillInstallationsRequest($contract, $sessionId));
$pending = $installations->recover(new SkillInstallationsRequest($contract, $sessionId));
$status = $installations->status(new SkillInstallationOperationRequest($contract, 'operation-id'));
$cancelled = $installations->cancel(new SkillInstallationOperationRequest($contract, 'operation-id'));
$enabled = $installations->setEnabled(new SkillSetEnabledRequest(
contract: $contract,
installationId: 'installation-id',
enabled: true,
policySessionId: $sessionId,
));
// La desinstalación también se aplica tras revisar el plan
$removalPlan = $skills->planUninstall(new SkillPlanUninstallRequest(
contract: $contract,
installationId: 'installation-id',
policySessionId: $sessionId,
));
$removed = $skills->applyUninstall(new SkillApplyUninstallRequest(
contract: $contract,
planHandle: $removalPlan['planHandle'],
policySessionId: $sessionId,
));
// skills: obtener los directorios donde se pueden crear skills (experimental)
// Lista de directorios que el runtime reconoce al colocar skills en ellos
$result = Copilot::client()->rpc()->skills()->getDiscoveryPaths();
// $result->paths es un array de SkillDiscoveryPath
// $result->paths[0]->path - ruta del directorio
// $result->paths[0]->scope - ámbito (user, project, plugin)
// $result->paths[0]->preferredForCreation - si es el directorio recomendado para crear nuevos
// Opcionalmente, filtrar por ámbito
$result = Copilot::client()->rpc()->skills()->getDiscoveryPaths(
new SkillsGetDiscoveryPathsRequest(scope: 'project')
);
// plugins (gestión de plugins con ámbito de servidor)
$plugins = Copilot::client()->rpc()->plugins();
$result = $plugins->list(); // Devuelve un PluginList
$installed = $plugins->install(new PluginsInstallRequest(source: 'eslint@official'));
$plugins->uninstall(new PluginsUninstallRequest(name: 'eslint@official'));
$plugins->update(new PluginsUpdateRequest(name: 'eslint@official'));
$plugins->updateAll();
$plugins->enable(new PluginsEnableRequest(names: ['eslint@official']));
$plugins->disable(new PluginsDisableRequest(names: ['eslint@official']));
// Para distinguir instalaciones directas con el mismo nombre, indica en names el directSourceId de list()
$plugins->enable(new PluginsEnableRequest(names: ['opaque-direct-source-id']));
$plugins->disable(new PluginsDisableRequest(names: ['opaque-direct-source-id']));
// Configuración de directorios de plugins integrados
$plugins->builtin()->set(new PluginsBuiltinSetRequest(paths: ['/opt/copilot/plugins']));
// Si indicas en la configuración del cliente los directorios que usan todas las sesiones,
// Client::start() los registra automáticamente antes de crear la primera sesión
// config/copilot.php: 'builtin_plugin_directories' => ['/opt/copilot/plugins']
// Gestión de marketplaces
$marketplaces = $plugins->marketplaces();
$marketplaces->list();
$marketplaces->add(new PluginsMarketplacesAddRequest(source: 'github/copilot-plugins'));
$marketplaces->remove(new PluginsMarketplacesRemoveRequest(name: 'official', force: true));
$marketplaces->browse(new PluginsMarketplacesBrowseRequest(name: 'official'));
$marketplaces->refresh(new PluginsMarketplacesRefreshRequest(name: 'official'));
// agents (experimental: gestión de agentes personalizados)
// Explorar agentes personalizados
$result = Copilot::client()->rpc()->agents()->discover();
// $result->agents es un array de AgentInfo
$result = Copilot::client()->rpc()->agents()->discover(new AgentsDiscoverRequest(
projectPaths: ['/path/to/project'],
excludeHostAgents: true,
));
// Obtener los directorios donde se pueden crear agentes (experimental)
$result = Copilot::client()->rpc()->agents()->getDiscoveryPaths();
// $result->paths es un array de AgentDiscoveryPath
// $result->paths[0]->path - ruta del directorio
// $result->paths[0]->scope - ámbito (user, project, plugin)
// $result->paths[0]->preferredForCreation - si es el directorio recomendado para crear nuevos
$result = Copilot::client()->rpc()->agents()->getDiscoveryPaths(
new AgentsGetDiscoveryPathsRequest(scope: 'user')
);
// instructions (experimental: gestión de instrucciones)
// Explorar instrucciones
$result = Copilot::client()->rpc()->instructions()->discover();
// $result->sources es un array de InstructionSource
$result = Copilot::client()->rpc()->instructions()->discover(
new InstructionsDiscoverRequest(projectPaths: ['/path/to/project'])
);
// Obtener los ficheros/directorios donde se pueden crear instrucciones (experimental)
$result = Copilot::client()->rpc()->instructions()->getDiscoveryPaths();
// $result->paths es un array de InstructionDiscoveryPath
// $result->paths[0]->path - ruta del fichero/directorio
// $result->paths[0]->location - ubicación (user, repository, working-directory, plugin)
// $result->paths[0]->kind - tipo (file, directory)
// $result->paths[0]->preferredForCreation - si es la recomendada para crear nuevas
$result = Copilot::client()->rpc()->instructions()->getDiscoveryPaths(
new InstructionsGetDiscoveryPathsRequest(location: 'repository')
);
// extensions (experimental: gestión de extensiones persistidas)
$result = Copilot::client()->rpc()->extensions()->discover();
Copilot::client()->rpc()->extensions()->enable(['ids' => ['user:demo']]);
Copilot::client()->rpc()->extensions()->disable(['ids' => ['plugin:demo']]);