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 (server-level skill management)
// Discover skills
$result = Copilot::client()->rpc()->skills()->discover();
// $result->skills is an array of ServerSkill
// Optionally specify project paths
$result = Copilot::client()->rpc()->skills()->discover(new SkillsDiscoverRequest(
projectPaths: ['/path/to/project'],
skillDirectories: ['/custom/skills'],
));
// Configure skills to disable
Copilot::client()->rpc()->skills()->config()->setDisabledSkills(
new SkillsConfigSetDisabledSkillsRequest(disabledSkills: ['skill-name'])
);
// Enable or disable an individual skill
Copilot::client()->rpc()->skills()->config()->setSkillDisabled(
new SkillsConfigSetSkillDisabledRequest(name: 'skill-name', disabled: true)
);
// Install directly from an HTTPS URL or a local file (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',
));
// Persist the returned skillDirectories on the caller side
$skillDirectories = $installed->skillDirectories;
// Unregister a discovery directory. The directory contents aren't deleted
$removed = $skills->removeSource(new SkillsRemoveSourceRequest(
target: '/custom/skills',
cwd: '/workspace',
skillDirectories: $skillDirectories,
));
if ($removed->kind === SkillsRemoveSourceOutcomeKind::Removed) {
$skillDirectories = $removed->result->skillDirectories;
}
// If deleting files requires an inventory and you omit it, needs-inventory is returned and nothing changes
// Select a skill candidate with catalog.search → catalog.select (experimental)
$contract = new CatalogClientContract(1, ['catalog-selection', 'ai-skill-installation']);
$catalog = Copilot::client()->rpc()->catalog();
// Get official product recommendations from a product name and a complete task (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,
));
// Category filters require catalog-search-categories
$categoryContract = new CatalogClientContract(3, [
CatalogCapability::CatalogSearchCategories->value,
]);
$categorySearch = $catalog->search(new CatalogSearchRequest(
contract: $categoryContract,
query: 'design tools',
categories: ['design', 'test'],
));
// When you specify policySessionId, also require credential-required and session-bound in the contract;
// it binds only to an existing attached session. It never creates or resumes a session.
// Saved and generated catalog feeds (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],
));
// To bind to an existing attached session, also require the session-bound capability
$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 preserve feed order. Entries that don't match the trust tier keep their position as filtered,
// and entries that can't be displayed are returned as unavailable with a reason.
// If the feed doesn't exist, you get kind=unavailable, reason=feed-not-found. Auth, negotiation, and policy denials
// are also returned as their own typed results, and catalog feed RPCs never install or configure anything.
// Plan and apply a skill installation
$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() applies after confirmation via installations.confirm
$result = $skills->applyInstall(new SkillApplyInstallRequest(
contract: $contract,
planHandle: $planned->outcome->plan['planHandle'],
policySessionId: $sessionId,
));
}
}
// Installed skills and in-progress operations
$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,
));
// Uninstalling also applies after reviewing the 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: get directories where skills can be created (experimental)
// List of directories the runtime recognizes when you place skills in them
$result = Copilot::client()->rpc()->skills()->getDiscoveryPaths();
// $result->paths is an array of SkillDiscoveryPath
// $result->paths[0]->path - Directory path
// $result->paths[0]->scope - Scope (user, project, plugin)
// $result->paths[0]->preferredForCreation - Whether it's the recommended directory for new creation
// Optionally narrow by scope
$result = Copilot::client()->rpc()->skills()->getDiscoveryPaths(
new SkillsGetDiscoveryPathsRequest(scope: 'project')
);
// plugins (server-scoped plugin management)
$plugins = Copilot::client()->rpc()->plugins();
$result = $plugins->list(); // Returns a 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']));
// To distinguish direct installs with the same name, pass the directSourceId from list() in names
$plugins->enable(new PluginsEnableRequest(names: ['opaque-direct-source-id']));
$plugins->disable(new PluginsDisableRequest(names: ['opaque-direct-source-id']));
// Configure built-in plugin directories
$plugins->builtin()->set(new PluginsBuiltinSetRequest(paths: ['/opt/copilot/plugins']));
// If you specify directories used by all sessions in the client config,
// Client::start() registers them automatically before the first session is created
// config/copilot.php: 'builtin_plugin_directories' => ['/opt/copilot/plugins']
// Marketplace management
$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: custom agent management)
// Discover custom agents
$result = Copilot::client()->rpc()->agents()->discover();
// $result->agents is an array of AgentInfo
$result = Copilot::client()->rpc()->agents()->discover(new AgentsDiscoverRequest(
projectPaths: ['/path/to/project'],
excludeHostAgents: true,
));
// Get directories where agents can be created (experimental)
$result = Copilot::client()->rpc()->agents()->getDiscoveryPaths();
// $result->paths is an array of AgentDiscoveryPath
// $result->paths[0]->path - Directory path
// $result->paths[0]->scope - Scope (user, project, plugin)
// $result->paths[0]->preferredForCreation - Whether it's the recommended directory for new creation
$result = Copilot::client()->rpc()->agents()->getDiscoveryPaths(
new AgentsGetDiscoveryPathsRequest(scope: 'user')
);
// instructions (experimental: instruction management)
// Discover instructions
$result = Copilot::client()->rpc()->instructions()->discover();
// $result->sources is an array of InstructionSource
$result = Copilot::client()->rpc()->instructions()->discover(
new InstructionsDiscoverRequest(projectPaths: ['/path/to/project'])
);
// Get files/directories where instructions can be created (experimental)
$result = Copilot::client()->rpc()->instructions()->getDiscoveryPaths();
// $result->paths is an array of InstructionDiscoveryPath
// $result->paths[0]->path - File/directory path
// $result->paths[0]->location - Location (user, repository, working-directory, plugin)
// $result->paths[0]->kind - Kind (file, directory)
// $result->paths[0]->preferredForCreation - Whether it's recommended for new creation
$result = Copilot::client()->rpc()->instructions()->getDiscoveryPaths(
new InstructionsGetDiscoveryPathsRequest(location: 'repository')
);
// extensions (experimental: manage persisted extensions)
$result = Copilot::client()->rpc()->extensions()->discover();
Copilot::client()->rpc()->extensions()->enable(['ids' => ['user:demo']]);
Copilot::client()->rpc()->extensions()->disable(['ids' => ['plugin:demo']]);