RPC (Remote Procedure Call)

In the official SDK, recent new features are supported through auto-generated code from api.schema.json. In the Laravel version, the same features are implemented by following generated SDKs for other languages.

ServerRpc

An RPC class bound to the Client.

Connection, models, tools, and accounts

Use ping() and connect() to check and start the connection, and registerExtensionLaunchProvider() to register an extension launch provider. You can get the model list, token price units, and built-in catalog from models(), and the list of available tools from tools(). account() handles quota, authentication status, the list of logged-in users, login, and logout, while accounts() acquires Microsoft Entra ID tokens.

MCP, connectors, and secrets

mcp() lets you list, add, update, and remove MCP configurations, enable them, discover servers, search the registry, and plan and apply installations. connectors() lets you check connector capabilities, accounts, and the catalog. Server-side connector operations mainly consist of listing and updating per account. The experimental secrets()->addFilterValues() registers dynamic secrets generated by your host with the CLI’s redaction filter. The CLI then masks those values in session logs and exports.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\Rpc\SecretsAddFilterValuesRequest;

$result = Copilot::client()->rpc()->secrets()->addFilterValues(
    new SecretsAddFilterValuesRequest(values: [$accessToken]),
);
// $result->ok

// You can also pass an array
Copilot::client()->rpc()->secrets()->addFilterValues([
    'values' => [$accessToken],
]);

This RPC doesn’t acquire OAuth tokens. The SDK doesn’t persist the values or write them to additional logs. Register values that your host has already obtained.

Skills, plugins, agents, instructions, and extensions

Each group lets you discover items, get available paths, change settings, and reload. commands() provides the list of built-in commands, and hooks() provides hook discovery before a session starts. Skills and plugins support enabling, disabling, and installation management, and agents can also return built-in agent information. Extensions discovers, enables, and disables persisted extensions.

Catalog and installation

Use catalog() to search for candidates, get official product recommendations, make selections, and get feeds. The Skills, Plugins, and MCP APIs let you review installation plans, apply them, query their status, and cancel them. Planning and applying are separate operations. See the later sections for actual installation examples.

Sessions, host, and runtime

sessions() handles searching persisted sessions, reading events, checking sizes, deleting and pruning, and forking. You can also create and load workspaces and use remote control. host() starts the host, publishes, lists, and unpublishes sessions, handles authentication, changes the session admission policy, and disposes of the host. These host RPCs back the SDK’s high-level AHP (Agent Host Protocol) host API. runtime() handles the runtime lifecycle.

Cloud agent tasks (experimental)

cloudTasks() creates, deletes, and gets cloud coding agent tasks, retrieves session logs and replays, changes sharing state, and resolves the session to open from a task ID. Each method accepts the matching Params type or an array and returns a typed DTO. When ok on a create result is false, check reason and message for why the service declined the request, and statusCode, errorMessage, and errorPayloadJson for a failed HTTP request.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\Rpc\CloudTasksCreateParams;

$result = Copilot::client()->rpc()->cloudTasks()->create(
    new CloudTasksCreateParams(
        authInfo: $authInfo,
        integrationId: 'my-app',
        repositoryOwner: 'octo',
        repositoryName: 'example',
    ),
);

if (! $result->ok) {
    // $result->reason and $result->message describe a declined request.
    // $result->statusCode and $result->errorMessage describe an attempted HTTP request.
}

Git, environments, sandbox, and policies

Get branch, working directory, and Git remote information from git(), and discover GitHub repositories and owners with gitHubRepository() and gitHubOwners(). environments() handles Mission Control environments, sandbox() and sandboxProxyCa() handle sandbox support and the Proxy CA, contentExclusion() validates exclusion policies, and managedSettings() and userSettings() handle settings. Use settings() to remove individual keys from a settings file and to redact values for display. gitHubRepository()->getById() resolves an owner and name from a GitHub repository ID, and lookupBranchPullRequest() searches the given repositories, in priority order, for a pull request from the given head owner and branch. Both take authInfo as is. The getById() result contains the owner and name in repository, or null when the repository isn’t found. The pull request lookup status is one of found, no-token, no-pr, or lookup-failed. Unknown values are kept as strings, so they don’t throw. pullRequest is an associative array when a pull request is found, otherwise null.

use Revolution\Copilot\Facades\Copilot;

$repository = Copilot::client()->rpc()->gitHubRepository();

$resolved = $repository->getById([
    'authInfo' => $authInfo,
    'repositoryId' => 12345,
]);

$lookup = $repository->lookupBranchPullRequest([
    'authInfo' => $authInfo,
    'headOwner' => 'octo',
    'baseRepositories' => [
        ['owner' => 'octo', 'name' => 'demo'],
        ['owner' => 'upstream', 'name' => 'demo'],
    ],
    'branch' => 'feature',
    'includeClosed' => false,
]);

gitHubFetch() provides authenticated GitHub API requests and named operations. gitHubRelease() provides release lookup, snapshots, asset downloads, and progress checks. In Fetch, sessionId selects a session’s authentication; when omitted, the process authentication is used. Set authOwnerId to use a host-managed authentication binding. In Release, authInfo selects runtime-managed credentials, and public releases can be looked up and downloaded anonymously. Delete the downloaded path yourself after use. Fetch’s allocateRequestId(), request(), and executeOperation(), and Release’s abandonRequest(), getSnapshot(), and downloadAsset() can’t be called from Extensions. The Laravel SDK doesn’t currently expose the cancel RPC of either group, so you can’t cancel an in-flight operation from the SDK. abandonRequest() discards an unused Release request ID; it doesn’t stop an in-flight operation.

Local models, HTTP inference, and file system

azureMl() provides the local model catalog, resolution, and download, as well as status checks, cancellation, and deletion. llmInference() is an experimental API that relays model-layer HTTP requests to the client side. sessionFs() registers a file system/SQLite callback provider for sessions.

Network callbacks (experimental)

network()->setProvider() tells the runtime about the proxy resolution and Kerberos authentication callbacks registered on the client. The network option on the Client registers them automatically, so you normally do not need to call this RPC directly. The callback fields of NetworkSetProviderRequest indicate that the matching handler is registered. The RPC returns no value. The runtime must support the network.setProvider RPC. If it does not, the client throws an exception at startup that asks you to update the runtime. See Authentication for details.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Enums\NetworkScope;
use Revolution\Copilot\Types\Rpc\NetworkSetProviderRequest;

Copilot::client()->rpc()->network()->setProvider(
    new NetworkSetProviderRequest(
        scope: NetworkScope::Runtime,
        resolveProxy: true,
        authenticateNegotiate: true,
    ),
);

scope defaults to connection. runtime also covers shared background traffic, but only one connection at a time can register with this scope.

Internal and experimental RPCs

The following RPCs are marked internal in the official SDK, but Laravel exposes them as @experimental. They may change or be removed in the future, and the runtime’s caller restrictions still apply. Use them to create, list, and remove agent registry entries, open an authentication URL in the browser, clean up expired large tool outputs, and get sandbox path grant warnings. List results don’t include connection credentials.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\Rpc\AgentRegistryEnsureDirRequest;
use Revolution\Copilot\Types\Rpc\AgentRegistryListEntriesRequest;
use Revolution\Copilot\Types\Rpc\AgentRegistryRemoveEntryRequest;
use Revolution\Copilot\Types\Rpc\RuntimeOpenBrowserRequest;
use Revolution\Copilot\Types\Rpc\SandboxPathGrantWarningParams;

$rpc = Copilot::client()->rpc();
$homeDir = '/home/user';

$registry = $rpc->agentRegistry();
$registry->ensureDir(new AgentRegistryEnsureDirRequest(homeDir: $homeDir));
$entries = $registry->listEntries(new AgentRegistryListEntriesRequest(homeDir: $homeDir));
$registry->removeEntry(new AgentRegistryRemoveEntryRequest(
    homeDir: $homeDir,
    pid: 1234,
));

$rpc->runtime()->openBrowser(new RuntimeOpenBrowserRequest(
    url: 'https://example.com/authorize',
));
$rpc->tools()->largeOutput()->cleanup();

$warning = $rpc->sandbox()->getPathGrantWarning(new SandboxPathGrantWarningParams(
    resolvedPath: '/workspace/project',
    readOnly: false,
));

Basic call example

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Enums\TokenPriceUnit;
use Revolution\Copilot\Types\Rpc\ModelsListTokenPriceUnitsRequest;
use Revolution\Copilot\Types\Rpc\ModelList;

// Get the model list
// Returns a ModelList
$result = Copilot::client()->rpc()->models()->list();
// models is an array of ModelInfo
$models = $result->models;

// Almost the same as the original listModels()
// Returns an array of ModelInfo
Copilot::client()->listModels();

Features that were already in the SDK have also been added again in the auto-generated version.

Usage examples by feature

The following are representative call examples for the features above.

use Illuminate\Http\Client\Response;
use Revolution\Copilot\Enums\CatalogCandidateKind;
use Revolution\Copilot\Enums\CatalogCapability;
use Revolution\Copilot\Enums\CatalogSelectionDecision;
use Revolution\Copilot\Enums\CatalogTrustTier;
use Revolution\Copilot\Enums\EventsReadDirection;
use Revolution\Copilot\Enums\McpInstallationSecretStorage;
use Revolution\Copilot\Enums\OptionsUpdateToolFilterPrecedence;
use Revolution\Copilot\Enums\SkillInstallationManagementOutcomeKind;
use Revolution\Copilot\Enums\SkillInstallationManagementResultKind;
use Revolution\Copilot\Enums\AzureMlRegistry;
use Revolution\Copilot\Types\Rpc\AzureMlAcquireFamilyRequest;
use Revolution\Copilot\Types\Rpc\AzureMlCancelRequest;
use Revolution\Copilot\Types\Rpc\AzureMlCatalogRequest;
use Revolution\Copilot\Types\Rpc\AzureMlDiscardRequest;
use Revolution\Copilot\Types\Rpc\AzureMlDownloadRequest;
use Revolution\Copilot\Types\Rpc\AzureMlLatestRequest;
use Revolution\Copilot\Types\Rpc\AzureMlReleaseFamilyRequest;
use Revolution\Copilot\Types\Rpc\AzureMlResolveRequest;
use Revolution\Copilot\Types\Rpc\AzureMlStatusRequest;
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\ExtensionLaunchProfile;
use Revolution\Copilot\Types\Rpc\ExtensionLaunchProviderResolveRequest;
use Revolution\Copilot\Types\Rpc\ExtensionLaunchProviderResolveResult;
use Revolution\Copilot\Types\Rpc\HooksDiscoverRequest;
use Revolution\Copilot\Types\Rpc\InstructionsDiscoverRequest;
use Revolution\Copilot\Types\Rpc\InstructionsGetDiscoveryPathsRequest;
use Revolution\Copilot\Types\Rpc\McpApplyInstallRequest;
use Revolution\Copilot\Types\Rpc\McpApplyUninstallRequest;
use Revolution\Copilot\Types\Rpc\McpInstallationOperationRequest;
use Revolution\Copilot\Types\Rpc\McpInstallationsRequest;
use Revolution\Copilot\Types\Rpc\McpPlanUninstallRequest;
use Revolution\Copilot\Types\Rpc\McpPrepareInstallRequest;
use Revolution\Copilot\Types\Rpc\McpRegistryCancelRequest;
use Revolution\Copilot\Types\Rpc\McpRegistrySearchRequest;
use Revolution\Copilot\Types\Rpc\McpServerCardReference;
use Revolution\Copilot\Types\Rpc\McpShouldExcludeGitHubToolsRequest;
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\SessionsListRequest;
use Revolution\Copilot\Types\Rpc\SessionsOpenCreateRequest;
use Revolution\Copilot\Enums\SessionsOpenStatus;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\Rpc\SessionsPruneOldRequest;
use Revolution\Copilot\Types\Rpc\SessionsReadPersistedEventsRequest;
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\SkillPlanInstallFromReferenceRequest;
use Revolution\Copilot\Types\Rpc\SkillPlanUninstallRequest;
use Revolution\Copilot\Types\Rpc\SkillSetEnabledRequest;
use Revolution\Copilot\Types\Rpc\SkillsGetDiscoveryPathsRequest;
use Revolution\Copilot\Types\Rpc\UIEphemeralQueryRequest;
use Revolution\Copilot\Types\SessionListFilter;
use Revolution\Copilot\Support\CopilotRequestContext;
use Revolution\Copilot\Support\CopilotRequestHandler;

Copilot::client()->rpc()->ping();

// models
Copilot::client()->rpc()->models()->list();
// Get with a per-session GitHub token
Copilot::client()->rpc()->models()->list(new ModelsListRequest(gitHubToken: $token));
// Get the token price units for models. Pass the same account selection info as models.list
$priceUnits = Copilot::client()->rpc()->models()->listTokenPriceUnits(
    new ModelsListTokenPriceUnitsRequest(gitHubToken: $token),
);
// $priceUnits->units has modelId and a unit of TokenPriceUnit|string
foreach ($priceUnits->units as $priceUnit) {
    if ($priceUnit->unit === TokenPriceUnit::NanoAiu) {
        // To convert nano-AIU to AI Credits, divide by 1,000,000,000
    }
}
// Built-in model catalog
Copilot::client()->rpc()->models()->getBuiltInCatalog();

// Azure ML local model management (experimental)
$azureMl = Copilot::client()->rpc()->azureMl();
$catalog = $azureMl->catalog(new AzureMlCatalogRequest(includeDev: false));
$latest = $azureMl->latest(new AzureMlLatestRequest(
    registry: AzureMlRegistry::AzureMl,
    name: 'phi',
));
$resolved = $azureMl->resolve(new AzureMlResolveRequest(
    registry: AzureMlRegistry::AzureMl,
    name: $latest->name,
    version: $latest->version,
));

// requestId and leaseId are bound to this SDK connection, so don't reuse them with another Client
$lease = $azureMl->acquireFamily(new AzureMlAcquireFamilyRequest(
    registry: AzureMlRegistry::AzureMl,
    name: $latest->name,
));

try {
    $download = $azureMl->download(new AzureMlDownloadRequest(
        requestId: 'download-1',
        registry: AzureMlRegistry::AzureMl,
        name: $latest->name,
        version: $latest->version,
        destination: 'models/phi/'.$latest->version,
        leaseId: $lease->leaseId,
    ));
} finally {
    $azureMl->releaseFamily(new AzureMlReleaseFamilyRequest(
        leaseId: $lease->leaseId,
        registry: AzureMlRegistry::AzureMl,
        name: $latest->name,
    ));
}

// download() waits until completion. To check progress or cancel while it runs,
// call from another Fiber or similar using the same connection's $azureMl
// $status = $azureMl->status(new AzureMlStatusRequest(requestId: 'download-1'));
// $cancelled = $azureMl->cancel(new AzureMlCancelRequest(requestId: 'download-1'));
// The bool from cancel() indicates the cancel request was accepted; confirm cleanup completion via download()

// Delete an inactive version
$azureMl->discard(new AzureMlDiscardRequest(destination: 'models/phi/previous-version'));

// The resolve() and download() types have no dedicated field for signed URLs
// download() has no timeout by default. To specify seconds, pass them as the second argument

// List of built-in slash commands available in new sessions (experimental)
Copilot::client()->rpc()->commands()->list();

// Hook discovery before a session starts (experimental)
Copilot::client()->rpc()->hooks()->discover(new HooksDiscoverRequest(
    projectPaths: ['/path/to/project'],
));

// Host sandbox support (experimental)
$hostSupport = Copilot::client()->rpc()->sandbox()->getHostSupport();
// $hostSupport->supported, $hostSupport->reason, $hostSupport->capabilities

// tools
Copilot::client()->rpc()->tools()->list();

// account
Copilot::client()->rpc()->account()->getQuota();
// Get with a per-session GitHub token
Copilot::client()->rpc()->account()->getQuota(new AccountGetQuotaRequest(gitHubToken: $token));

// Resolve an absolute URL from the configured GitHub host name (no authentication required)
$hostUrl = Copilot::client()->rpc()->account()->getHostUrl([
    'copilotGhHost' => 'github.example.com',
])->url;

// Enroll an authenticated identity, without credentials, in Copilot Free
$enrollment = Copilot::client()->rpc()->account()->subscribeCopilotFree([
    'identity' => [
        'type' => 'token',
        'host' => 'https://github.com',
        'login' => 'octocat',
    ],
]);
// $enrollment->kind / $enrollment->status / $enrollment->message

// mcp config (manage MCP server configuration)
Copilot::client()->rpc()->mcp()->list();
Copilot::client()->rpc()->mcp()->add(new McpConfigAddRequest(
    name: 'my-server',
    config: new McpServerValue(type: 'local', command: 'php', args: ['artisan', 'mcp']),
));
// args is optional
Copilot::client()->rpc()->mcp()->update(new McpConfigUpdateRequest(
    name: 'my-server',
    config: new McpServerValue(type: 'http', url: 'https://mcp.example.com'),
));
Copilot::client()->rpc()->mcp()->remove(new McpConfigRemoveRequest(name: 'my-server'));
// Enable/disable MCP servers (global settings)
Copilot::client()->rpc()->mcp()->enable(new McpConfigEnableRequest(names: ['my-server']));
Copilot::client()->rpc()->mcp()->disable(new McpConfigDisableRequest(names: ['my-server']));
// Clear the in-memory cache (reloaded from disk on next read)
Copilot::client()->rpc()->mcp()->reload();

// MCP registry search (experimental/internal)
// $authInfo is JSON authentication info prepared by the host. The SDK doesn't interpret its contents.

$registry = Copilot::client()->rpc()->mcp()->registry();
$requestId = $registry->allocateRequestId()->requestId;
$servers = $registry->search(new McpRegistrySearchRequest(
    requestId: $requestId,
    authInfo: $authInfo, // Auth info passed from the host. The SDK doesn't interpret its contents.
    query: 'database',
    limit: 20,
));
// $servers->servers holds the registry server data (kept as-is without interpreting its shape)
// You can release unused reserved IDs. To cancel an in-progress search, call cancel() from another process.
$unusedRequestId = $registry->allocateRequestId()->requestId;
$cancelResult = $registry->cancel(new McpRegistryCancelRequest(requestId: $unusedRequestId));
// When releasing an unused ID, canceled is false. It's true only when a running search was stopped.

// Install / uninstall via the MCP catalog (experimental)
// Results are associative arrays of a discriminated union with kind. Check kind before reading each field.

$mcp = Copilot::client()->rpc()->mcp();
$contract = new CatalogClientContract(
    protocolVersion: 1,
    requiredCapabilities: ['mcp-server-card', 'mcp-install-planning'],
);

// $candidateHandle, $searchId, and $cardReference come from catalog search results.
// $sessionId is a session ID already connected to this Client.
$planned = $mcp->planInstall([
    'contract' => $contract->toArray(),
    'source' => ['kind' => 'candidate', 'candidateHandle' => $candidateHandle, 'searchId' => $searchId],
]);

if (($planned['kind'] ?? null) === 'planned') {
    $plan = $planned['plan'];
    $prepared = $mcp->prepareInstall(new McpPrepareInstallRequest(
        contract: $contract,
        planHandle: $plan['planHandle'],
        choiceId: $plan['transportChoices'][0]['choiceId'],
        inputs: [],
        policySessionId: $sessionId,
        secrets: [],
        secretStorage: McpInstallationSecretStorage::Keychain,
        source: McpServerCardReference::fromArray($cardReference),
    ));

    // During applyInstall, the installation_confirmation_handler set when creating the client is called.
    if (($prepared['kind'] ?? null) === 'outcome'
        && ($prepared['outcome']['kind'] ?? null) === 'install-prepared') {
        $applied = $mcp->applyInstall(new McpApplyInstallRequest(
            contract: $contract,
            operationId: $prepared['outcome']['operation']['operationId'],
            policySessionId: $sessionId,
        ));
    }
}

// List owned installations and recover incomplete operations
$installations = $mcp->installations();
$installations->list(new McpInstallationsRequest(contract: $contract, policySessionId: $sessionId));
$installations->recover(new McpInstallationsRequest(contract: $contract, policySessionId: $sessionId));
$installations->status(new McpInstallationOperationRequest($contract, $operationId));
$installations->cancel(new McpInstallationOperationRequest($contract, $operationId));

// To uninstall, plan with an installationId you own, then apply the returned planHandle.
$uninstallPlan = $mcp->planUninstall(new McpPlanUninstallRequest(
    contract: $contract,
    installationId: $installationId,
    policySessionId: $sessionId,
));
if (($uninstallPlan['kind'] ?? null) === 'outcome'
    && ($uninstallPlan['outcome']['kind'] ?? null) === 'uninstall-planned') {
    $mcp->applyUninstall(new McpApplyUninstallRequest(
        contract: $contract,
        planHandle: $uninstallPlan['outcome']['plan']['planHandle'],
        policySessionId: $sessionId,
    ));
}

// Determine whether GitHub MCP tools can be excluded (experimental/internal)

$exclude = Copilot::client()->rpc()->mcp()->shouldExcludeGitHubTools(
    new McpShouldExcludeGitHubToolsRequest(
        availableTools: ['builtin:bash'],
        excludedTools: [],
        toolFilterPrecedence: OptionsUpdateToolFilterPrecedence::Available,
    ),
)->excludeGhReplaceableTools;

// user settings
// The current CLI has no user.settings.reload RPC. get() targets settings.json.
Copilot::client()->rpc()->userSettings()->set(['settings' => ['theme' => 'dark']]); // No return value

// mcp discover (auto-discover MCP servers)
Copilot::client()->rpc()->mcp()->discover(new McpDiscoverRequest(
    workingDirectory: '/path/to/project',
));
// Can be run without arguments
$result = Copilot::client()->rpc()->mcp()->discover();
// $result->servers is an array of DiscoveredMcpServer

// llmInference (experimental: hook HTTP requests to the model layer)
$client = Copilot::client([
    'request_handler' => new class extends CopilotRequestHandler
    {
        public function sendRequest(CopilotRequestContext $context, string $method, string $body): Response
        {
            $context->url = 'https://proxy.example.com/v1/chat/completions';
            $context->headers['X-Request-Source'] = ['laravel'];

            return parent::sendRequest($context, $method, $body);
        }
    },
]);

// llmInference.setProvider is sent at startup, and you receive httpRequestStart / httpRequestChunk.
// A handler that doesn't override sendRequest transparently forwards HTTP/SSE with the Laravel HTTP Client.
// When you pass a Closure, return a Response in the form fn (CopilotRequestContext $context, string $method, string $body): Response.
// request_handler is experimental. The WebSocket transport isn't supported and returns a 501-equivalent error response.

// sessionFs (register a session file system provider)
Copilot::client()->rpc()->sessionFs()->setProvider(new SessionFsSetProviderRequest(
    initialCwd: '/path/to/project',
    sessionStatePath: '.copilot/sessions',
    conventions: 'posix',
));

// Client option that resolves how to launch extensions (respond within 15 seconds)
$client = Copilot::client([
    'extensionLaunchProvider' => fn (ExtensionLaunchProviderResolveRequest $request) => new ExtensionLaunchProviderResolveResult(
        launch: new ExtensionLaunchProfile(
            executable: '/usr/bin/node',
            args: [$request->modulePath],
        ),
    ),
]);
// Return null if there's no matching launch method.
// fn (ExtensionLaunchProviderResolveRequest $request) => null

$sessions = Copilot::client()->rpc()->sessions();

// sessions (experimental: query and manage persisted sessions)

// sessions.open selects create, resume, resumeLast, attach, remote/cloud connection, or handoff with `kind`.
$opened = $sessions->open(new SessionsOpenCreateRequest(
    options: new SessionConfig(sessionId: 'new-session', model: 'gpt-5'),
));
if ($opened->status === SessionsOpenStatus::Created) {
    echo $opened->sessionId;
}
// You can also pass an array. When resuming, set sessionId at the top level of the variant.
$resumed = $sessions->open(['kind' => 'resume', 'sessionId' => 'existing-session']);
// Returns SessionsOpenResult. When the status is not_found, there is no sessionId.
// sessionApi, onTaskCreated, onProgress, and onConfirm are in-process only and aren't included in the wire payload.

$listed = $sessions->list(new SessionsListRequest(
    source: 'local',
    metadataLimit: 50,
    filter: new SessionListFilter(cwd: '/path/to/project'),
));
// Use isRemote on each SessionMetadata to tell local and remote sessions apart
foreach ($listed->sessions as $session) {
    echo $session->sessionId;
}

$sessions->findByTaskId(['taskId' => 'task-id']);
$sessions->findByPrefix(['prefix' => 'session-id-prefix']);
$sessions->getLastForContext(['context' => ['cwd' => '/path/to/project']]);
$sizes = $sessions->getSizes(); // $sizes->sizes maps session ID => byte count
$inUse = $sessions->checkInUse(['sessionIds' => ['session-id']]);
$deleted = $sessions->bulkDelete(['sessionIds' => ['session-id']]);

// Close an active session (history isn't deleted)
$sessions->close(['sessionId' => 'session-id']);

// Save pending events to disk
$sessions->save(['sessionId' => 'session-id']);

// Explicitly release the in-use lock on a session held by this process
$sessions->releaseLock(['sessionId' => 'session-id']);

// reloadPluginHooks reloads user/plugin hooks.
// Repo hooks are deferred until folder trust is confirmed, then loaded after trust is confirmed.
$sessions->reloadPluginHooks([
    'sessionId' => 'session-id',
    'deferRepoHooks' => true,
]);
$loadedHooks = $sessions->loadDeferredRepoHooks(['sessionId' => 'session-id']);
// $loadedHooks->startupPrompts and $loadedHooks->hookCount

// Replace manager-wide additional plugin settings (clear with an empty array)
$sessions->setAdditionalPlugins(['plugins' => []]);

// Fill in summary / context for local session metadata
$enriched = $sessions->enrichMetadata([
    'sessions' => [[
        'sessionId' => 'session-id',
        'startTime' => '2026-10-17T09:00:00Z',
        'modifiedTime' => '2026-10-17T09:00:00Z',
        'isRemote' => false,
    ]],
]);

// close() shuts down, saves events, and releases the lock, then disposes of the active session,
// but doesn't delete persisted history. $session->disconnect() uses session.detach to release
// the connection to this SDK and the in-memory resources on the PHP side. Use bulkDelete() to delete persisted data.

// Page through persisted events with a cursor without opening the session
$cursor = null;
do {
    $page = $sessions->readPersistedEvents(new SessionsReadPersistedEventsRequest(
        sessionId: 'session-id',
        cursor: $cursor,
        max: 100,
        direction: EventsReadDirection::FORWARD,
    ));

    foreach ($page->events as $event) {
        // Process the event
    }

    $cursor = $page->cursor;
} while ($page->hasMore);

// dryRun returns candidates and estimates without deleting. To actually delete, specify dryRun: false
$preview = $sessions->pruneOld(new SessionsPruneOldRequest(
    olderThanDays: 30,
    dryRun: true,
));

// sessions.fork
$sessions->fork(new SessionsForkRequest(
    sessionId: 'source-session-id',
    toEventId: 'evt-boundary', // Optional: include only events before this ID
));

// 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)
);

// 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,
        ));
    }
}

// Plan a skill installation from an Agent Finder materialisation reference
$referenceContract = new CatalogClientContract(3, [
    'skill-confirmed-installation',
    'skill-reference-installation',
]);
$referencePlan = $skills->planInstallFromReference(new SkillPlanInstallFromReferenceRequest(
    contract: $referenceContract,
    reference: new CatalogMaterializationReference(
        resourceId: '12345',
        revisionId: '67890',
        schemaVersion: '1.0.0',
        descriptorDigest: 'sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
        bundleDigest: 'sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
    ),
    policySessionId: $sessionId,
));
// On success, $referencePlan->kind === SkillInstallationManagementResultKind::Outcome and
// $referencePlan->outcome->kind === SkillInstallationManagementOutcomeKind::InstallPlanned.
// Planning itself has no side effects. It fetches the descriptor from the fixed Agent Finder authority
// and verifies the descriptor and bundle digests. Review the contents and complete the existing confirmation flow before calling applyInstall().
// invalid-reference, descriptor-not-found, descriptor-withdrawn, digest-mismatch, and
// unsupported-resource are returned as refusal reasons in the plan result.
// The GitHub refusal reasons source-rate-limited, no-credential, and credential-rejected are
// distinguished by SkillInstallationFailureReason, and retryAfterSeconds is returned only for source-rate-limited.
// The message for network-failure is a safe description that contains no URLs, search queries, handles, or secrets.

// 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']]);

// environments (experimental: search, get, and delete GitHub Mission Control environments)
$result = Copilot::client()->rpc()->environments()->list(['kind' => 'user-local']);
// $result->environments is an array of GitHubEnvironment
$env = Copilot::client()->rpc()->environments()->get(['environmentId' => 'env-id']);
Copilot::client()->rpc()->environments()->delete(['environmentId' => 'env-id']);

Agent Plugin catalog candidates

Require agent-plugin-discovery in catalog.search and specify plugin in the search kinds to get Agent Plugin candidates. To receive application/vnd.anthropic.claude-plugin+json and application/agent-plugin+json in addition to the standard format application/vnd.github.copilot-plugin, require agent-plugin-formats in addition to agent-plugin-discovery. agent-plugin-confirmed-installation is a capability that returns installability and a plan for review. Require it together with agent-plugin-discovery as well. When granted, candidates include installability, whose value is one of installable, install-data-unavailable, feature-disabled, or not-installable-kind. installPlan is included only when installability is installable. The plan is data for review, and this catalog RPC never performs the installation. The plan’s sources contains materialization, marketplace, and repository candidates in priority order. A marketplace records its name and repository, and a direct repository records the repository and an optional path. In a materialization-only plan, pluginName is omitted and components is empty. Check the name and what will actually be installed in the review returned by plugins.planInstall(). For a selected candidate, plugins.planInstall() creates a validated plan with no side effects. plugins.applyInstall() asks the user for explicit confirmation and applies the plan if allowed. The plugin is registered in a disabled state after it’s applied. The review’s mcpServers shows the server names, transport, and, for remote servers, the host declared by the validated files. This isn’t a safety guarantee, so have the user review the contents before giving explicit confirmation. An installed plugin’s description comes from the manifest. verifiedSource shows the GitHub repository and pinned commit, and exists only for direct installs pinned to a commit. iconUrl is external, untrusted content, so don’t send credentials or GitHub credentials when fetching it. Credentials themselves are never returned as refusal reasons. For a network-failure installation result, you can check the CatalogNetworkFailureReason, the HTTP statusCode, an optional retryAfterSeconds, and a message that’s safe to display.

use Revolution\Copilot\Enums\CatalogReferenceInstallationResultKind;
use Revolution\Copilot\Enums\PluginInstallationManagementOutcomeKind;
use Revolution\Copilot\Types\Rpc\CatalogClientContract;
use Revolution\Copilot\Types\Rpc\PluginApplyInstallRequest;
use Revolution\Copilot\Types\Rpc\PluginPlanInstallRequest;

$contract = new CatalogClientContract(3, [
    'agent-plugin-confirmed-installation',
]);
$plugins = Copilot::client()->rpc()->plugins();

$planned = $plugins->planInstall(new PluginPlanInstallRequest(
    candidateHandle: $candidateHandle,
    contract: $contract,
    policySessionId: $sessionId,
));

if ($planned->kind === CatalogReferenceInstallationResultKind::Outcome
    && $planned->outcome?->kind === PluginInstallationManagementOutcomeKind::InstallPlanned) {
    $applied = $plugins->applyInstall(new PluginApplyInstallRequest(
        contract: $contract,
        planHandle: $planned->outcome->plan->planHandle,
        policySessionId: $sessionId,
    ));
}

To plan from an Agent Finder materialisation reference, use catalog.planInstallFromReference(). The result’s outcome->kind is one of plugin-install-planned, skill-install-planned, or refused. Pass plugin plans to plugins.applyInstall() and skill plans to skills.applyInstall().

use Revolution\Copilot\Enums\CatalogCapability;
use Revolution\Copilot\Enums\CatalogReferenceInstallationOutcomeKind;
use Revolution\Copilot\Enums\CatalogReferenceInstallationResultKind;
use Revolution\Copilot\Types\Rpc\CatalogClientContract;
use Revolution\Copilot\Types\Rpc\CatalogPlanInstallFromReferenceRequest;
use Revolution\Copilot\Types\Rpc\PluginApplyInstallRequest;

$referenceContract = new CatalogClientContract(3, [
    CatalogCapability::CatalogReferenceInstallation->value,
    CatalogCapability::AgentPluginConfirmedInstallation->value,
]);
$planned = Copilot::client()->rpc()->catalog()->planInstallFromReference(
    new CatalogPlanInstallFromReferenceRequest(
        contract: $referenceContract,
        policySessionId: $sessionId,
        reference: $reference,
    ),
);

$plugins = Copilot::client()->rpc()->plugins();
if ($planned->kind === CatalogReferenceInstallationResultKind::Outcome
    && $planned->outcome?->kind === CatalogReferenceInstallationOutcomeKind::PluginInstallPlanned) {
    $plugins->applyInstall(new PluginApplyInstallRequest(
        contract: $referenceContract,
        planHandle: $planned->outcome->plan->planHandle,
        policySessionId: $sessionId,
    ));
}

contentExclusion

You can validate content exclusion policy JSON before creating a session.

use Revolution\Copilot\Types\Rpc\ContentExclusionValidatePoliciesRequest;

$result = Copilot::client()->rpc()->contentExclusion()->validatePolicies(
    new ContentExclusionValidatePoliciesRequest(policiesJson: $policiesJson),
);
// $result->policies holds the validated, normalized policies

policiesJson is passed to the CLI as an unparsed JSON string. If JSON parsing or schema validation fails, the CLI raises an RPC error (JsonRpcException). This is a server-scoped RPC that validates the policies themselves. To check paths in the session’s working directory against the actual exclusion policies, use the session-scoped contentExclusion()->checkPaths().

managedSettings (experimental: managed settings)

Read managed settings, resolve policies, get the schema, validate, preview composition, and clear the cache.

$managedSettings = $client->rpc()->managedSettings()->read();
$effective = $client->rpc()->managedSettings()->resolve([
    'selectionId' => 'selection-id',
    'workingDirectory' => '/path/to/project',
]);
$schema = $client->rpc()->managedSettings()->schema();
$validation = $client->rpc()->managedSettings()->validate(['content' => ['permissions' => []]]);
$preview = $client->rpc()->managedSettings()->compose(['layers' => [
    ['source' => 'device', 'settings' => ['permissions' => []]],
]]);
$client->rpc()->managedSettings()->clearCache();

settings (experimental: settings file operations)

Remove a specific key from a settings file and redact secret values for display. removeRawKey() removes keys as-is, including keys that aren’t canonical settings paths, such as keys that failed to load. If the file can’t be parsed, the CLI doesn’t overwrite it and status is invalid. redactValueForDisplay() replaces secret values with placeholders based on the position in the settings tree given by basePath, so you can safely show the value to users or write it to logs.

$result = $client->rpc()->settings()->removeRawKey([
    'filePath' => '/path/to/settings.json',
    'rawKey' => 'misspelledKey',
]);
// $result->status is 'ok' or 'invalid'

$redacted = $client->rpc()->settings()->redactValueForDisplay([
    'value' => ['apiKey' => 'secret-value', 'name' => 'visible'],
    'basePath' => ['providers', 'openai'],
]);
// Secret values in $redacted->value are replaced with placeholders

Runtime and host lifecycle (experimental)

host.unpublishSession() withdraws an application publication from a running host you own. Unpublishing doesn’t delete or stop the original session history, worktree, or running work. If the session is already unpublished, unpublished is false, and publications other than application raise an error.

$result = Copilot::client()->rpc()->host()->unpublishSession([
    'hostId' => 'host-1',
    'sessionId' => 'session-1',
]);
// $result->unpublished

host.dispose() disposes of a host listener by hostId.

Copilot::client()->rpc()->host()->dispose(['hostId' => 'host-1']);

host.setSessionCreationPolicy() toggles whether a running host accepts new remote sessions. The change doesn’t disconnect existing clients and applies only to later admissions.

use Revolution\Copilot\Types\Rpc\HostSetSessionCreationPolicyRequest;

Copilot::client()->rpc()->host()->setSessionCreationPolicy(
    new HostSetSessionCreationPolicyRequest(
        hostId: 'host-1',
        allowCreatingNewSessions: false,
    ),
);

For a stdio runtime started by the SDK, Client::stop() calls runtime.shutdown after disconnecting sessions and before closing the JSON-RPC connection and the process. Session detaches (session.detach) share a single 10-second deadline across all sessions; a detach that misses the deadline is included in the return value as an error, and shutdown continues. It also waits up to 10 seconds for runtime cleanup to finish; on failure, it includes the error in the return value and continues with the rest of the shutdown. For connections to an external runtime such as cli_url, this RPC isn’t called so the shared runtime isn’t terminated. If the CLI can’t identify the matching request and returns a JSON-RPC error with id: null, every in-flight request fails with a JsonRpcException. The exception includes a diagnostic message with quoted values removed and its length capped. The connection stays open. Because the CLI may already have processed the request, don’t retry automatically without confirming that it’s safe. The SDK rejects outgoing requests nested deeper than 127 levels, which the CLI can’t read, before sending them. It replaces handler responses that are nested too deeply with a JSON-RPC error.

SessionRpc

An RPC class bound to the Session. You can also use features that weren’t possible in earlier SDKs, such as plan mode.

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\Rpc\ModeSetRequest;
use Revolution\Copilot\Types\Rpc\PlanReadResult;

Copilot::start(function (CopilotSession $session) {
    $session->rpc()->mode()->set(new ModeSetRequest(mode: 'plan'));

    $response = $session->sendAndWait(prompt: 'Create a plan for XX');

    $result = $session->rpc()->plan()->read();
    dump($result->content);

    $session->rpc()->mode()->set(new ModeSetRequest(mode: 'autopilot'));

    $response = $session->sendAndWait(prompt: 'Implement according to the plan');
    dump($response->content());
});

Model, mode, name, and plan

Use model() to check or switch the current model and to set reasoning effort, the Auto tier, and allowed models. mode() handles the mode, name() the session name, and plan() reads and writes the plan body and SQLite todos.

Workspaces, instructions, and LSP

workspaces() lets you list, read, write, move, and delete files and work with directories. Use instructions() to get, reload, and discover instructions, and lsp() to initialize language server settings.

Autopilot objective

autopilotObjective()->getState() returns the session’s current Autopilot objective state as a typed object. If no objective exists, state is null. This API differs from workspaces()->autopilotObjectiveExists(), which checks whether an objective is saved in the workspace.

$state = $session->rpc()->autopilotObjective()->getState()->state;

if ($state !== null) {
    dump($state->objective, $state->status, $state->turnCount, $state->creditLimit);
}

setStayInAutopilot() suppresses requests to return to interactive mode when an objective completes or pauses. The setting is kept in client memory and defaults to true. Pass false as value to stop suppressing. Set it again after you reconnect.

$session->rpc()->autopilotObjective()->setStayInAutopilot(['value' => true]);

Agents, Fleet, and background tasks

Use agent() to list, select, and reload agents, and fleet() to start Fleet. tasks() handles registering background agents and client-owned tasks, getting and updating progress, promotion, sending messages, cancellation, and removal.

MCP, plugins, extensions, and workflow

mcp() handles listing, starting, stopping, and reloading servers, tools, prompts, resources, OAuth, sampling, and updating dynamic headers. plugins() and extensions() manage in-session state, and customizations() reloads customizations. Use workflow() to run and query workflows, and diagnostics() and connectors() to get diagnostics and connectors.

Tools, permissions, commands, and UI

tools() and permissions() handle responses to pending requests delivered via events, as well as settings. permissions()->clearResumeEscalation() clears, in memory, the permission escalation restored from history on resume, and returns a typed success result. commands() provides listing commands, running them, and responding to events, and ui() responds to requests such as user input, elicitation, and plan approval. completions() gets input completions.

$result = $session->rpc()->permissions()->clearResumeEscalation();
// $result->success

Accounts, authentication, and providers

accounts() handles enumerating accounts, providers, and logged-in accounts with enumerate(), get() and set(), and interactive login with begin(), advance(), and cancel(). gitHubAuth() handles the session’s authentication status and credentials, provider() and providers() handle model endpoints and provider adapters, and connectors() handles the session’s connector connections.

History, queue, logs, and usage

history() provides conversation compaction (including compaction settings), aborting, handoff summaries, and truncation, and queue() provides inserting, moving, editing, removing, and immediately sending pending items. Use log(), eventLog(), usage(), quota(), and limitPrediction() to work with logs, events, usage, and limit information. schedule() lets you view and stop scheduled prompts.

Lifecycle, remote, and host integration

sendMessages() runs multiple messages in a single turn, and suspend() and shutdown() stop the session. interruptMainTurn() controls the main turn, and cancelAllBackgroundAgents() controls background agents separately. remote() and visibility() handle remote publication and sharing state, sandbox() the session’s sandbox, managedSettings() session-scoped managed settings, contentExclusion() path checks, metadata() client-owned metadata, and canvas() Canvas integration.

debug (experimental)

Use debug()->collectLogs() to collect a session’s event logs, process logs, and shell logs into a .tgz archive or a directory. Logs are redacted for sensitive information by default. You can add files or directories with additionalEntries, and set redaction to plain-text, events-jsonl, or none. With none, nothing is redacted, so be careful about what you add.

use Revolution\Copilot\Enums\DebugCollectLogsEntryKind;
use Revolution\Copilot\Enums\DebugCollectLogsRedaction;
use Revolution\Copilot\Types\Rpc\DebugCollectLogsDestination;
use Revolution\Copilot\Types\Rpc\DebugCollectLogsEntry;
use Revolution\Copilot\Types\Rpc\DebugCollectLogsRequest;

$result = $session->rpc()->debug()->collectLogs(new DebugCollectLogsRequest(
    destination: DebugCollectLogsDestination::archive('/tmp/copilot-debug.tgz', noOverwrite: true),
    additionalEntries: [
        new DebugCollectLogsEntry(
            kind: DebugCollectLogsEntryKind::File,
            path: '/var/log/my-app.log',
            bundlePath: 'application/my-app.log',
            redaction: DebugCollectLogsRedaction::PlainText,
            required: true,
        ),
    ],
));

Specify DebugCollectLogsDestination::directory('/tmp/copilot-debug') to output to a staging directory. With include, you can individually specify which logs and reference paths to collect, and you can check what was collected from entries and skippedEntries in the result. Destination and additional entry paths are paths on the CLI server side. In the standard setup where the CLI is started over stdio, that’s the same host as your app, but if you connect over TCP to a CLI server on another host, specify paths on the server side, not on the calling machine.

contentExclusion (experimental)

You can check whether local absolute paths in the session’s working directory are subject to content exclusion policies. Call this before reading or attaching file contents.

use Revolution\Copilot\Types\Rpc\ContentExclusionCheckPathsRequest;

$result = $session->rpc()->contentExclusion()->checkPaths(
    new ContentExclusionCheckPathsRequest(paths: [
        '/workspace/private.txt',
        '/workspace/public.txt',
    ]),
);

if ($result->isExcluded('/workspace/private.txt')) {
    // Excluded, or can't be determined safely.
}

checkPaths() accepts only absolute paths, and the paths must be inside the session’s working directory. checks are returned in the same order as the input, and duplicate paths are kept as-is. If the path, file system, or policy evaluation isn’t supported or available, you get available: false and an empty checks. In that case, isExcluded() always returns true, so treat all paths as excluded. Even with available: true, paths missing from the result are conservatively treated as excluded.

MCP Apps (experimental)

You can call MCP Apps RPCs from $session->rpc()->mcp()->apps(). listTools() and callTool() require originServerName, the name of the calling MCP server. The result of callTool() is returned as a free-form MCP result.

use Revolution\Copilot\Types\Rpc\MCPAppsDiagnoseRequest;
use Revolution\Copilot\Types\Rpc\MCPAppsListToolsRequest;
use Revolution\Copilot\Types\Rpc\McpAppsCallToolRequest;
use Revolution\Copilot\Types\Rpc\McpAppsReadResourceRequest;
use Revolution\Copilot\Types\Rpc\McpAppsSetHostContextDetails;
use Revolution\Copilot\Types\Rpc\McpAppsSetHostContextRequest;

$apps = $session->rpc()->mcp()->apps();

$tools = $apps->listTools(new MCPAppsListToolsRequest(
    serverName: 'my-server',
    originServerName: 'my-server',
));
$result = $apps->callTool(new McpAppsCallToolRequest(
    serverName: 'my-server',
    toolName: 'lookup',
    originServerName: 'my-server',
    arguments: ['query' => 'hello'],
));
$resource = $apps->readResource(new McpAppsReadResourceRequest(
    serverName: 'my-server',
    uri: 'ui://my-app/index.html',
));
$context = $apps->getHostContext();
$apps->setHostContext(new McpAppsSetHostContextRequest(
    context: new McpAppsSetHostContextDetails(theme: 'dark', locale: 'ja-JP'),
));
$diagnostics = $apps->diagnose(new MCPAppsDiagnoseRequest(serverName: 'my-server'));

readResource() returns resource data such as HTML. The SDK doesn’t render in a browser or manipulate iframes, so rendering the retrieved content is the responsibility of the calling application.

Usage examples by feature

The following are representative call examples for the features above.

// model
$session->rpc()->model()->getCurrent();
// Get the reasoning summary display policy for the current model (experimental)
$policy = $session->rpc()->model()->getReasoningSummaries(new ModelGetReasoningSummariesRequest(
    persistedShowReasoning: true, // Omit if not set
    summariesVisible: true, // Whether it's currently shown in the host UI
));
// $policy->ready, $policy->sessionShowsSummaries, $policy->visibility, etc.
// Change only the reasoning effort without changing the selected model (experimental)
$effort = $session->rpc()->model()->setReasoningEffort(
    new ModelSetReasoningEffortRequest(reasoningEffort: ReasoningEffort::HIGH),
);
// $effort->reasoningEffort
$session->rpc()->model()->switchTo(new ModelSwitchToRequest(modelId: 'gpt-4'));
// To specify reasoningEffort (supported models only)
$session->rpc()->model()->switchTo(new ModelSwitchToRequest(modelId: 'claude-opus-4.7', reasoningEffort: ReasoningEffort::HIGH));
// To specify reasoningSummary
$session->rpc()->model()->switchTo(new ModelSwitchToRequest(modelId: 'claude-opus-4.7', reasoningSummary: 'concise'));
// To specify contextTier (supported models only)
$session->rpc()->model()->switchTo(new ModelSwitchToRequest(modelId: 'gpt-4o', contextTier: 'long_context'));
// To override modelCapabilities
$session->rpc()->model()->switchTo(new ModelSwitchToRequest(
    modelId: 'gpt-4',
    modelCapabilities: new ModelCapabilitiesOverride(
        supports: new ModelCapabilitiesOverrideSupports(vision: true),
    ),
));
// Get the list of models available in the session (experimental)
$models = $session->rpc()->model()->list();
$models->auto?->tiers; // Auto routing preferences available to the account
$session->rpc()->model()->list(new ModelListRequest(skipCache: true)); // Skip the cache

// Change the Auto routing preference (doesn't change the selected model, experimental)
$session->rpc()->model()->switchAutoTier(new ModelSwitchAutoTierRequest(autoTier: AutoTier::BALANCE));
$session->rpc()->model()->switchAutoTier(new ModelSwitchAutoTierRequest(autoTier: null)); // Revert to provider-default Auto routing

// Set or clear the session's model allowlist from the host side (experimental)
$session->rpc()->model()->setAllowedModels(new ModelSetAllowedModelsRequest(allowedModels: ['gpt-5']));
$session->rpc()->model()->setAllowedModels(new ModelSetAllowedModelsRequest(allowedModels: null)); // Remove the restriction

// The setModel() helper can also take reasoningEffort and modelCapabilities
$session->setModel('claude-opus-4.7', ReasoningEffort::HIGH);
$session->setModel('claude-opus-4.7', 'high'); // A string also works
$session->setModel('gpt-4', modelCapabilities: ['supports' => ['vision' => true]]); // An array also works
// To specify autoTier (only effective when modelId is 'auto')
$session->setModel('auto', autoTier: AutoTier::INTELLIGENCE);

// Use the setAutoTier() helper to change only the Auto routing preference without changing the model (experimental)
$session->setAutoTier(AutoTier::EFFICIENCY);

// mode
$session->rpc()->mode()->get();
$modeResult = $session->rpc()->mode()->set(new ModeSetRequest(mode: 'plan'));
// $modeResult->modeApplied, $modeResult->modelChanged, $modeResult->confirmation, etc.

// name
$session->rpc()->name()->get();
$session->rpc()->name()->set(new NameSetRequest(name: 'My Session'));
// Apply a summary as the session name if the user hasn't set a name (experimental)
$autoName = $session->rpc()->name()->setAuto(new NameSetAutoRequest(summary: 'Summary of the session'));
// $autoName->applied

// plan
$session->rpc()->plan()->read();
$session->rpc()->plan()->update(new PlanUpdateRequest(content: '...'));
$session->rpc()->plan()->delete();
// Read the SQLite todo list (plan mode)
$result = $session->rpc()->plan()->readSqlTodos();
// $result->rows - Array of PlanSqlTodosRow (id, title, description, status)

// Read the SQLite todo list with dependencies (experimental)
$result = $session->rpc()->plan()->readSqlTodosWithDependencies();
// $result->rows - Array of PlanSqlTodosRow
// $result->dependencies - Array of PlanSqlTodoDependency (todo_id, depends_on)

// workspaces
$session->rpc()->workspaces()->getWorkspace();
$session->rpc()->workspaces()->listFiles();
$session->rpc()->workspaces()->readFile(new WorkspacesReadFileRequest(path: 'file.txt'));
$session->rpc()->workspaces()->createFile(new WorkspacesCreateFileRequest(path: 'file.txt', content: '...'));
$session->rpc()->workspaces()->statFile(new WorkspacesStatFileRequest(path: 'file.txt'));
$session->rpc()->workspaces()->createDirectory(new WorkspacesCreateDirectoryRequest(path: 'new/dir', recursive: true));
$session->rpc()->workspaces()->removePath(new WorkspacesRemovePathRequest(path: 'old/dir', recursive: true, force: true));
$session->rpc()->workspaces()->renamePath(new WorkspacesRenamePathRequest(source: 'old.txt', destination: 'new.txt'));

// instructions (get the session's instruction sources)
$result = $session->rpc()->instructions()->getSources();
// $result->sources - Array of InstructionsSources
$session->rpc()->instructions()->reload();

// Explicitly reload LSP settings (experimental)
$session->rpc()->lsp()->initialize([
    'workingDirectory' => base_path(),
    'gitRoot' => base_path(),
    'force' => true,
]);

// instructions discover (detect instruction files)
use Revolution\Copilot\Types\Rpc\InstructionsDiscoverRequest;

$result = $session->rpc()->instructions()->discover();
// $result->sources - Array of InstructionSource
$result = $session->rpc()->instructions()->discover(new InstructionsDiscoverRequest(
    projectPaths: ['/path/to/project'],
    excludeHostInstructions: true, // Exclude host-level instructions
));

// fleet
$session->rpc()->fleet()->start(new FleetStartRequest(prompt: '...'));
// See fleet-mode.md for details

// agent
$session->rpc()->agent()->list();
$session->rpc()->agent()->getCurrent();
$session->rpc()->agent()->select(new AgentSelectRequest(agentId: '...'));
$session->rpc()->agent()->deselect();
$session->rpc()->agent()->reload();

// skills (experimental: skill management)
$session->rpc()->skills()->list();
$session->rpc()->skills()->enable(new SkillsEnableRequest(name: 'skill-name'));
$session->rpc()->skills()->disable(new SkillsDisableRequest(name: 'skill-name'));
$session->rpc()->skills()->reload();
$session->rpc()->skills()->ensureLoaded(); // Load skills that aren't loaded yet (doesn't reload)
$invoked = $session->rpc()->skills()->getInvoked();
// $invoked->skills - History of skills invoked during the session

// mcp (experimental: MCP server management)
$servers = $session->rpc()->mcp()->list();
// Configured URL for HTTP/SSE servers: $servers->servers[0]->url
$session->rpc()->mcp()->enable(new McpEnableRequest(serverName: 'server-name'));
$session->rpc()->mcp()->disable(new McpDisableRequest(serverName: 'server-name'));
$session->rpc()->mcp()->reload();
// Move in-progress MCP loading to the background (releases the waiting turn)
$session->rpc()->mcp()->moveLoadingToBackground();

// Start or restart an MCP server in the session (doesn't change persisted settings)
use Revolution\Copilot\Types\Rpc\McpRestartServerRequest;
use Revolution\Copilot\Types\Rpc\McpStartServerRequest;

$session->rpc()->mcp()->startServer(new McpStartServerRequest(
    serverName: 'server-name',
    config: ['type' => 'http', 'url' => 'https://mcp.example.com'],
));
$session->rpc()->mcp()->restartServer(new McpRestartServerRequest(
    serverName: 'server-name',
    expectedInstallationId: 'installation-id',
));

// Remove the automatically managed GitHub MCP server and set how environment variable values are resolved
$removed = $session->rpc()->mcp()->removeGitHub();
$mode = $session->rpc()->mcp()->setEnvValueMode(['mode' => 'indirect']);
// $removed->removed, $mode->mode

// Run and cancel MCP sampling
use Revolution\Copilot\Types\Rpc\McpCancelSamplingExecutionParams;
use Revolution\Copilot\Types\Rpc\McpExecuteSamplingParams;

$sampling = $session->rpc()->mcp()->executeSampling(new McpExecuteSamplingParams(
    requestId: 'sampling-1',
    serverName: 'server-name',
    mcpRequestId: 'mcp-request-1',
    request: ['messages' => [], 'maxTokens' => 256],
));
$cancelled = $session->rpc()->mcp()->cancelSamplingExecution(
    new McpCancelSamplingExecutionParams(requestId: 'sampling-1'),
);

// Check whether an MCP server is running
use Revolution\Copilot\Types\Rpc\McpIsServerRunningRequest;

$result = $session->rpc()->mcp()->isServerRunning(new McpIsServerRunningRequest(serverName: 'my-server'));
// $result->running - Whether the server is running

// Get an MCP server's tool list
use Revolution\Copilot\Types\Rpc\McpListToolsRequest;

$result = $session->rpc()->mcp()->listTools(new McpListToolsRequest(serverName: 'my-server'));
// $result->tools - Array of McpTools (name, description)

// List and get MCP prompts (experimental)
use Revolution\Copilot\Types\Rpc\McpPromptsGetRequest;
use Revolution\Copilot\Types\Rpc\McpPromptsListRequest;

$prompts = $session->rpc()->mcp()->listPrompts(new McpPromptsListRequest(serverName: 'my-server'));
$rendered = $session->rpc()->mcp()->getPrompt(new McpPromptsGetRequest(
    serverName: 'my-server',
    promptName: 'summarize',
    arguments: ['document' => 'README.md'],
));
// $prompts->prompts - MCP prompt definitions
// $rendered->messages - Rendered prompt (not sent to the model)

// Stop an MCP server
use Revolution\Copilot\Types\Rpc\McpStopServerRequest;

$session->rpc()->mcp()->stopServer(new McpStopServerRequest(serverName: 'my-server'));

// Get the list of MCP resources (experimental)
use Revolution\Copilot\Types\Rpc\McpResourcesListRequest;

$result = $session->rpc()->mcp()->resources()->list(new McpResourcesListRequest(serverName: 'my-server'));
// $result->resources - Array of McpResource (uri, name, title, mimeType, etc.)
// $result->nextCursor - Cursor for the next page (if any)

// Get an MCP resource (experimental)
use Revolution\Copilot\Types\Rpc\McpResourcesReadRequest;

$result = $session->rpc()->mcp()->resources()->read(new McpResourcesReadRequest(serverName: 'my-server', uri: 'ui://example'));
// $result->contents - Array of McpResourceContent

// Get the list of MCP resource templates (experimental)
use Revolution\Copilot\Types\Rpc\McpResourcesListTemplatesRequest;

$result = $session->rpc()->mcp()->resources()->listTemplates(new McpResourcesListTemplatesRequest(serverName: 'my-server'));
// MCP OAuth login (for MCP servers that require authentication)
use Revolution\Copilot\Types\Rpc\McpOauthCompleteRequest;
use Revolution\Copilot\Types\Rpc\McpOauthLoginRequest;
use Revolution\Copilot\Types\Rpc\McpOauthProbeRequest;
use Revolution\Copilot\Types\Rpc\SessionMcpOauthCancelLoginRequest;
use Revolution\Copilot\Types\Rpc\SessionMcpOauthPrepareLoginRequest;

$result = $session->rpc()->mcp()->login(new McpOauthLoginRequest(serverName: 'my-server'));
// $result->authorizationUrl - URL for the OAuth flow (when authentication is required)
// For a host-managed OAuth redirect flow, specify redirectUri and call complete() after the callback
$result = $session->rpc()->mcp()->login(new McpOauthLoginRequest(
    serverName: 'my-server',
    redirectUri: 'http://localhost:3000/oauth/callback',
));
$session->rpc()->mcp()->complete(new McpOauthCompleteRequest(
    authorizationId: $result->authorizationId,
    callbackUrl: $callbackUrl,
));

// Check the OAuth state, and prepare or cancel a login tied to an owned installation
$probe = $session->rpc()->mcp()->oauth()->probe(new McpOauthProbeRequest(serverName: 'my-server'));
$prepared = $session->rpc()->mcp()->oauth()->prepareLogin(new SessionMcpOauthPrepareLoginRequest(
    serverName: 'my-server',
    expectedInstallationId: 'installation-id',
));
$cancelled = $session->rpc()->mcp()->oauth()->cancelLogin(new SessionMcpOauthCancelLoginRequest(
    expectedInstallationId: 'installation-id',
    loginId: $prepared->loginId,
));

// plugins (experimental: plugin list)
$session->rpc()->plugins()->list();
// To target direct installs with the same name, pass the directSourceId from list() in names
$session->rpc()->plugins()->enable(['names' => ['opaque-direct-source-id']]);
$session->rpc()->plugins()->disable(['names' => ['opaque-direct-source-id']]);
// Reload plugins
$session->rpc()->plugins()->reload();
// Reload with options
use Revolution\Copilot\Types\Rpc\PluginsReloadRequest;

$session->rpc()->plugins()->reload(new PluginsReloadRequest(
    reloadMcp: true,      // Reload MCP server settings
    reloadHooks: true,    // Reload hooks
    reloadCustomAgents: false, // Don't reload custom agents
));

// extensions (experimental: extension management)
$policy = $session->rpc()->extensions()->getPolicy(); // ExtensionManagedPolicy
// $policy->standalone is allowed / plugin_only / pending
// The policy is a snapshot, not a launch-authorization token. Don't use it for actual launch decisions
$session->rpc()->extensions()->list();
$session->rpc()->extensions()->enable(new ExtensionsEnableRequest(id: 'project:my-ext'));
$session->rpc()->extensions()->disable(new ExtensionsDisableRequest(id: 'project:my-ext'));
$session->rpc()->extensions()->reconcile(); // host-only: resyncs effective membership and returns the settled list
$session->rpc()->extensions()->reload();

// managedSettings (experimental: session managed settings)
// Re-evaluate the Policy Helper and return the resulting effective settings
$settings = $session->rpc()->managedSettings()->recheckPolicyHelper(); // ManagedSettingsResolvedData

// compaction → renamed to history
$session->rpc()->history()->compact();
// Set the model, instructions, and reasoning effort used for compaction (experimental). Each call replaces all three; omitted fields revert to defaults
$session->rpc()->history()->setCompactionConfig(new HistorySetCompactionConfigRequest(
    model: 'gpt-5', // Optional. In BYOK/provider sessions, the session's model does the summarization
    prompt: 'Keep decisions only', // Optional. Replaces the built-in prompt
    reasoningEffort: ReasoningEffort::LOW, // Optional
));
// Abort manual compaction / cancel background compaction
$session->rpc()->history()->abortManualCompaction();
$session->rpc()->history()->cancelBackgroundCompaction();
// Get a summary for handing off to another session
$summary = $session->rpc()->history()->summarizeForHandoff()->summary;
// Truncate history from a specific event onward
$session->rpc()->history()->truncate(new HistoryTruncateRequest(
    eventId: 'evt-123', // This event and all later events are deleted
));

// tools (protocol v3+: respond to external_tool.requested events)
// Initialize and validate the runtime tool set before sending (experimental, used for subagent sessions and similar)
$session->rpc()->tools()->initializeAndValidate();
// Returns an empty ToolsInitializeAndValidateResult

// Run a tool currently exposed to the session through the native call pipeline (experimental)
use Revolution\Copilot\Types\Rpc\ToolsExecuteRequest;

$result = $session->rpc()->tools()->execute(new ToolsExecuteRequest(
    name: 'search',
    arguments: ['query' => 'Laravel'],
    toolCallId: 'call-123', // Optional. Used to correlate with the call
));

if (is_string($result)) {
    // Simple text result
    echo $result;
} else {
    // ToolResultExpanded: textResultForLlm, resultType, newMessages,
    // mcpMeta, structuredContent, taskCompletionDecision, etc.
    echo $result->textResultForLlm;
    // resultType holds a ToolResultType or a string for unknown values
}

// Arrays also work. toolCallId can be omitted, and sessionId is overwritten with this session's value
$session->rpc()->tools()->execute([
    'name' => 'search',
    'arguments' => ['query' => 'Copilot'],
]);
// arguments: [] is sent as the JSON object {}, and scalars/null/non-empty arrays keep their JSON values

// execute() goes through the normal native tool call pipeline, so it doesn't bypass permission checks.
// If the tool requires approval, the onPermissionRequest handler in SessionConfig handles it as usual.
$session->rpc()->tools()->handlePendingToolCall(new HandlePendingToolCallRequest(
    requestId: '...',
    result: 'Tool execution result',
));
// Get the session's current tool metadata (experimental)
$session->rpc()->tools()->getCurrentMetadata();
// Fully replace the external tools provided by this connection (experimental)
$session->rpc()->tools()->set(['tools' => [
    ['name' => 'search', 'description' => 'Search documents', 'parameters' => ['type' => 'object']],
]]);
// Get the subagent settings applied to the current session (experimental)
$settings = $session->rpc()->tools()->getSubagentSettings();
// $settings->subagents is SubagentSettings, or null when there is no settings block
// Update subagent settings (experimental)
use Revolution\Copilot\Enums\SubagentSettingsEntryContextTier;
use Revolution\Copilot\Types\Rpc\SubagentSettings;
use Revolution\Copilot\Types\Rpc\SubagentSettingsEntry;
use Revolution\Copilot\Types\Rpc\UpdateSubagentSettingsRequest;

$result = $session->rpc()->tools()->updateSubagentSettings(new UpdateSubagentSettingsRequest(
    subagents: new SubagentSettings(agents: [
        'my-agent' => new SubagentSettingsEntry(
            contextTier: SubagentSettingsEntryContextTier::Default,
            model: 'gpt-5',
        ),
    ]),
));
// Applying the settings returns an empty ToolsUpdateSubagentSettingsResult

// permissions (protocol v3+: respond to permission.requested events)
use Revolution\Copilot\Types\Rpc\FolderTrustAddParams;
use Revolution\Copilot\Types\Rpc\PermissionLocationAddToolApprovalParams;
use Revolution\Copilot\Types\Rpc\PermissionLocationApplyParams;
use Revolution\Copilot\Types\Rpc\PermissionLocationResolveParams;
use Revolution\Copilot\Types\Rpc\PermissionsLocationsAddToolApprovalDetailsCommands;

$session->rpc()->permissions()->handlePendingPermissionRequest(new PermissionDecisionRequest(
    requestId: '...',
    result: PermissionDecision::approveOnce(),
));
// Automatically approve all permission requests in the session
$session->rpc()->permissions()->setApproveAll(new PermissionsSetApproveAllRequest(enabled: true));
// Set the permission mode (manual / assisted / allow-all)
$session->rpc()->permissions()->setMode(new PermissionsSetModeRequest(mode: PermissionMode::AllowAll));
// Get the current permission mode
$mode = $session->rpc()->permissions()->getMode();
// When you set permissionMode on session create or resume, get the applied result from the session
$result = $session->permissionModeResult();
// $result->success - Whether it was applied successfully
// $result->mode - The permission mode after it was applied
// Get the approval modes available under the current policy (experimental)
$capabilities = $session->rpc()->permissions()->getCapabilities();
// $capabilities->assistedApproval - Whether LLM-assisted approval is enabled
// $capabilities->bypassPermissions - Whether managed policy allows unconditional approval
// Reset session-scoped permission approvals
$session->rpc()->permissions()->resetSessionApprovals();
// Get the list of currently pending permission requests
$pending = $session->rpc()->permissions()->pendingRequests();
// Enable/disable the event bridge for permission requests
$session->rpc()->permissions()->setRequired(new PermissionsSetRequiredRequest(required: true));
// Add/remove permission rules
$session->rpc()->permissions()->modifyRules(new PermissionsModifyRulesParams(
    scope: PermissionsModifyRulesScope::SESSION,
    add: [['tool' => 'bash', 'decision' => 'allow']],
));
// Notify that a permission prompt was shown
$session->rpc()->permissions()->notifyPromptShown(new PermissionPromptShownNotification(message: 'tool permission prompt'));
// Path permissions
$paths = $session->rpc()->permissions()->paths()->list();
$session->rpc()->permissions()->paths()->add(new PermissionPathsAddParams(path: '/path/to/allow'));
$session->rpc()->permissions()->paths()->updatePrimary(new PermissionPathsUpdatePrimaryParams(path: '/path/to/allow'));
$session->rpc()->permissions()->paths()->isPathWithinAllowedDirectories(new PermissionPathsAllowedCheckParams(path: '/path/to/allow/file.txt'));
$session->rpc()->permissions()->paths()->isPathWithinWorkspace(new PermissionPathsWorkspaceCheckParams(path: '/path/to/allow/file.txt'));
// URL permissions
$session->rpc()->permissions()->urls()->setUnrestrictedMode(
    new PermissionUrlsSetUnrestrictedModeParams(enabled: true)
);
// Resolve the permission location for the working directory and apply saved rules
$location = $session->rpc()->permissions()->locations()->resolve(
    new PermissionLocationResolveParams(workingDirectory: '/path/to/repo')
);
$session->rpc()->permissions()->locations()->apply(
    new PermissionLocationApplyParams(workingDirectory: '/path/to/repo')
);
// Persist a tool approval to the permission location
$session->rpc()->permissions()->locations()->addToolApproval(
    new PermissionLocationAddToolApprovalParams(
        approval: new PermissionsLocationsAddToolApprovalDetailsCommands(commandIdentifiers: ['bash']),
        locationKey: $location->locationKey,
    )
);
// Check and add folder trust
$trusted = $session->rpc()->permissions()->folderTrust()->isTrusted(['path' => '/path/to/repo']);
$session->rpc()->permissions()->folderTrust()->addTrusted(new FolderTrustAddParams(path: '/path/to/repo'));

// commands: get the list of slash commands available in the session
use Revolution\Copilot\Types\Rpc\CommandsListRequest;

$list = $session->rpc()->commands()->list();
// $list->commands - Array of SlashCommandInfo
// $list->commands[0]->name - Command name (without the slash)
// $list->commands[0]->description - Command description
// $list->commands[0]->kind - Command category (builtin, skill, client)
// $list->commands[0]->allowDuringAgentExecution - Whether it can be used while the agent is running

// Get the list with filters
$list = $session->rpc()->commands()->list(new CommandsListRequest(
    includeBuiltins: true,
    includeSkills: false,
));

// commands: invoke a slash command
use Revolution\Copilot\Types\Rpc\CommandsInvokeRequest;

$result = $session->rpc()->commands()->invoke(new CommandsInvokeRequest(
    name: 'help',
    input: 'optional input text',
));

// commands: respond to a command invocation event
$session->rpc()->commands()->handlePendingCommand(new CommandsHandlePendingCommandRequest(
    requestId: '...',
));

// commands: run a slash command synchronously
use Revolution\Copilot\Types\Rpc\ExecuteCommandParams;

$result = $session->rpc()->commands()->execute(new ExecuteCommandParams(
    commandName: 'review',
    args: 'src/',
), timeout: 120.0); // How long to wait for the CLI response (seconds). Defaults to 30 seconds
// $result->error - Error message if execution failed (null on success)

// commands: respond to a queued command
$session->rpc()->commands()->respondToQueuedCommand(new CommandsRespondToQueuedCommandRequest(
    requestId: '...',
    result: new QueuedCommandResult(handled: true),
));

// ui: respond to a UI elicitation request
$session->rpc()->ui()->elicitation(new UIElicitationRequest(
    message: 'Question for the user',
    requestedSchema: ['type' => 'object', 'properties' => [...]],
));

// ui: an ephemeral query that isn't added to the conversation history
$result = $session->rpc()->ui()->ephemeralQuery(new UIEphemeralQueryRequest(
    question: 'Summarize the key points of the conversation so far.',
));
// $result->answer

// ui: respond to a pending elicitation request (via the elicitation.requested event)
$session->rpc()->ui()->handlePendingElicitation(new UIHandlePendingElicitationRequest(
    requestId: '...',
    result: ['action' => 'accept', 'content' => ['name' => 'John']],
));

// ui: respond to pending requests via broadcast events
use Revolution\Copilot\Enums\UIAutoModeSwitchResponse;
use Revolution\Copilot\Types\Rpc\UIExitPlanModeResponse;
use Revolution\Copilot\Types\Rpc\UIHandlePendingAutoModeSwitchRequest;
use Revolution\Copilot\Types\Rpc\UIHandlePendingExitPlanModeRequest;
use Revolution\Copilot\Types\Rpc\UIHandlePendingSamplingRequest;
use Revolution\Copilot\Types\Rpc\UIHandlePendingUserInputRequest;
use Revolution\Copilot\Types\Rpc\UIUserInputResponse;

$result = $session->rpc()->ui()->handlePendingUserInput(new UIHandlePendingUserInputRequest(
    requestId: '...',
    response: new UIUserInputResponse(answer: 'blue', wasFreeform: false),
));

$result = $session->rpc()->ui()->handlePendingExitPlanMode(new UIHandlePendingExitPlanModeRequest(
    requestId: '...',
    response: new UIExitPlanModeResponse(approved: true, selectedAction: 'autopilot_fleet'),
));

$result = $session->rpc()->ui()->handlePendingAutoModeSwitch(new UIHandlePendingAutoModeSwitchRequest(
    requestId: '...',
    response: UIAutoModeSwitchResponse::Yes,
));

// Answer data.requestId from auto_mode_recovery_consent.requested with the same RPC.
// The runtime retries or rewinds during recovery, so don't resend the prompt from your app.

$result = $session->rpc()->ui()->handlePendingSampling(new UIHandlePendingSamplingRequest(
    requestId: '...',
    response: ['result' => '...'],
));
// Each method returns UIHandlePendingResult. Check $result->success to see whether the response was accepted.

// onExitPlanModeRequest / onAutoModeSwitchRequest in SessionConfig respond automatically via reverse-RPC.
// If you respond manually to the same request via events, don't use both paths at the same time.

// log: record messages to the session timeline
$session->rpc()->log()->log(new LogRequest(message: 'Processing started'));
$session->rpc()->log()->log(new LogRequest(message: 'Disk usage is high', level: LogLevel::WARNING));
$session->rpc()->log()->log(new LogRequest(message: 'An error occurred', level: LogLevel::ERROR));
$session->rpc()->log()->log(new LogRequest(message: 'Debug info', ephemeral: true));

// shell: run shell commands in the session
$result = $session->rpc()->shell()->exec(new ShellExecRequest(command: 'ls -la'));
// Use $result->processId to get the process ID for killing or tracking output

$session->rpc()->shell()->exec(new ShellExecRequest(
    command: 'npm test',
    cwd: '/path/to/project',
    timeout: 60000, // Milliseconds
));

// Stop a running shell process
$session->rpc()->shell()->kill(new ShellKillRequest(
    processId: $result->processId,
    signal: 'SIGTERM', // SIGTERM (default), SIGKILL, SIGINT
));

// Cancel a user-requested shell command
use Revolution\Copilot\Types\Rpc\ShellExecuteUserRequestedRequest;
use Revolution\Copilot\Types\Rpc\ShellCancelUserRequestedRequest;

$execution = $session->rpc()->shell()->executeUserRequested(new ShellExecuteUserRequestedRequest(
    requestId: 'req-123',
    command: 'pwd',
), timeout: 120.0); // How long to wait for the CLI response (seconds). Defaults to 30 seconds
// $execution->toolCallId / success / output / exitCode / error
// To cancel from another process while it runs, specify the same requestId

$cancelled = $session->rpc()->shell()->cancelUserRequested(
    new ShellCancelUserRequestedRequest(requestId: 'req-123')
);
// $cancelled->cancelled - Whether the cancellation succeeded

// telemetry (experimental: session telemetry)
use Revolution\Copilot\Types\Rpc\TelemetrySetFeatureOverridesRequest;

$telemetry = $session->rpc()->telemetry();
$engagement = $telemetry->getEngagementId();
// $engagement->engagementId - The engagement ID when available, otherwise null

$telemetry->setFeatureOverrides(new TelemetrySetFeatureOverridesRequest(
    features: ['feature-key' => 'override-value'],
));
// The overrides are attached to later telemetry events and replace any previous overrides.
// This is separate from SessionConfig::$enableSessionTelemetry (which enables internal telemetry).

// usage (experimental: session usage metrics)
$metrics = $session->rpc()->usage()->getMetrics();
// $metrics->totalPremiumRequestCost - Total cost of premium requests
// $metrics->totalUserRequests - Total number of user requests
// $metrics->codeChanges - Code change metrics (lines added, lines removed, files changed)
// $metrics->modelMetrics - Token usage and request count per model
// $metrics->currentModel - Current model identifier

// auth: get the session's authentication status
$status = $session->rpc()->auth()->getStatus();
// $status->isAuthenticated - Whether authenticated
// $status->authType - Auth type (AuthInfoType enum: gh-cli, token, env, etc.)
// $status->login - GitHub login name
// $status->host - GitHub host
// $status->copilotPlan - Copilot plan (individual, business, etc.)
// $status->statusMessage - Authentication status message

// provider: get endpoint info for the provider the session uses (experimental)
// Used when calling the LLM backend directly in a BYOK (Bring Your Own Key) setup
use Revolution\Copilot\Types\Rpc\ProviderGetEndpointRequest;

$endpoint = $session->rpc()->provider()->getEndpoint();
// $endpoint->baseUrl - Base URL to pass to the LLM client library
// $endpoint->type - Provider type (openai, anthropic, etc.)
// $endpoint->headers - HTTP headers to include in requests
// $endpoint->apiKey - Credentials (nullable)
// $endpoint->sessionToken - Short-lived session credentials (nullable)
// $endpoint->wireApi - Provider-specific wire API (nullable)

// Get the provider configuration status of the selected model (doesn't validate credentials or contact the provider) (experimental)
$status = $session->rpc()->provider()->getStatus();
// $status->hasCustomProvider - Whether a custom provider is used instead of GitHub authentication

// Get the endpoint for a specific model
$endpoint = $session->rpc()->provider()->getEndpoint(
    new ProviderGetEndpointRequest(model: 'gpt-5')
);

// provider: withdraw host-managed models from the BYOK registry (experimental)
$result = $session->rpc()->provider()->withdraw(['models' => ['provider/model']]);
// $result->withdrawn, $result->providersRemoved, $result->modelDeselected

// queue: view and manage queued user-facing items
$pending = $session->rpc()->queue()->pendingItems();
// $pending->items - Array of QueuePendingItems
// $pending->items[0]->kind - QueuePendingItemsKind (Command / Message)

$removed = $session->rpc()->queue()->removeMostRecent();
// $removed->removed - Whether the most recent item was removed

$session->rpc()->queue()->clear();

// Insert an item at a given position (position is 0-based)
use Revolution\Copilot\Types\Rpc\QueueInsertAtRequest;
use Revolution\Copilot\Types\Rpc\QueueInsertMessage;

$queue = $session->rpc()->queue();
$inserted = $queue->insertAt(new QueueInsertAtRequest(
    position: 0,
    message: new QueueInsertMessage(prompt: 'Review the changes'),
));
// $inserted->id - ID of the inserted item

$queue->moveItem(['id' => $inserted->id, 'toPosition' => 1]);
$duplicated = $queue->duplicateAt(['id' => $inserted->id]);
$queue->updateText(['id' => $duplicated->id, 'prompt' => 'Review and test the changes']);
$removedAt = $queue->removeAt(['id' => $duplicated->id]);
// $removedAt->removed - Whether the item was removed

$sent = $queue->sendNow(['id' => $inserted->id]);
// $sent->steered - Whether it was sent to the running turn

// Pause draining. The pause isn't lifted automatically, so always resume with false
$queue->setDrainPaused(['paused' => true]);
$queue->setDrainPaused(['paused' => false]);

// schedule (experimental: scheduled prompt management)
$schedule = $session->rpc()->schedule()->list();
// $schedule->entries - Array of ScheduleEntry

use Revolution\Copilot\Types\Rpc\ScheduleStopRequest;

$stopped = $session->rpc()->schedule()->stop(new ScheduleStopRequest(id: 1));
// $stopped->stopped - Whether stopping succeeded

// tasks (experimental: background task management)
// Start an agent task and get its ID
use Revolution\Copilot\Types\Rpc\TasksStartAgentRequest;

$result = $session->rpc()->tasks()->startAgent(new TasksStartAgentRequest(
    agentType: 'explore',
    prompt: 'Search for all TODO comments in the codebase',
    name: 'todo-search',
    description: 'Find TODO items', // Optional
    model: 'gpt-4o', // Optional
));
// $result->agentId - ID of the background task

// Get the current task list
$list = $session->rpc()->tasks()->list();
// $list->tasks - Array of TaskAgentInfo, TaskShellInfo, and TaskClientInfo

// Incrementally read output from a detached shell with a cursor
use Revolution\Copilot\Types\Rpc\TasksReadOutputRequest;

$cursor = null;
do {
    $output = $session->rpc()->tasks()->readOutput(new TasksReadOutputRequest(
        id: 'shell-1',
        cursor: $cursor,
        waitMs: 1000,
    ));
    echo $output->text;
    $cursor = $output->cursor;
} while ($output->exit === null);
// $output->exit->status - Task exit status
// $output->exit->exitCode - Process exit code (nullable)

// Each read is up to 64 KiB. waitMs defaults to 0, with a maximum of 30000ms.
// stdout and stderr are merged. If the cursor becomes invalid, read again without a cursor.

// Register an application-owned job as a task
use Revolution\Copilot\Types\Rpc\TasksRegisterRequest;

$registered = $session->rpc()->tasks()->register(new TasksRegisterRequest(
    clientTaskId: 'import-123',
    description: 'Import customer data',
    cancellable: true,
    displayName: 'Customer import', // Optional
));
// $registered->task->id - Task ID assigned by the CLI
// $registered->created / $registered->reclaimed - Whether it was newly created or an orphaned task was reclaimed

// Update the progress of a client-owned task
use Revolution\Copilot\Enums\TaskClientActiveStatus;
use Revolution\Copilot\Enums\TaskClientUpdateKind;
use Revolution\Copilot\Types\Rpc\TaskClientUpdate;
use Revolution\Copilot\Types\Rpc\TasksUpdateRequest;

$updated = $session->rpc()->tasks()->update(new TasksUpdateRequest(
    id: $registered->task->id,
    sequence: 1,
    update: new TaskClientUpdate(
        kind: TaskClientUpdateKind::Progress,
        status: TaskClientActiveStatus::Running,
        phase: 'importing',
        percentage: 25,
    ),
));
// Increment sequence with each update

// Report completion
$completed = $session->rpc()->tasks()->update(new TasksUpdateRequest(
    id: $registered->task->id,
    sequence: 2,
    update: new TaskClientUpdate(
        kind: TaskClientUpdateKind::Completed,
        result: ['imported' => 100],
    ),
));

// Get task progress (null if not tracked)
$progress = $session->rpc()->tasks()->getProgress(['id' => $registered->task->id])->progress;
// TaskAgentProgress, TaskClientProgress, TaskShellProgress, or null

// Refresh the state of detached shells and wait for background work to finish
$session->rpc()->tasks()->refresh();
$session->rpc()->tasks()->waitForPending();

// Get the task that can currently be moved to the background, or move it to the background immediately
$promotable = $session->rpc()->tasks()->getCurrentPromotable()->task;
$promotedCurrent = $session->rpc()->tasks()->promoteCurrentToBackground()->task;

// Move a task to background mode (releases the synchronous wait)
use Revolution\Copilot\Types\Rpc\TasksPromoteToBackgroundRequest;

$promoted = $session->rpc()->tasks()->promoteToBackground(
    new TasksPromoteToBackgroundRequest(id: $result->agentId)
);
// $promoted->promoted - Whether the move succeeded

// Cancel a task
use Revolution\Copilot\Types\Rpc\TasksCancelRequest;

$cancelled = $session->rpc()->tasks()->cancel(
    new TasksCancelRequest(id: $result->agentId)
);
// $cancelled->cancelled - Whether the cancellation succeeded

// Remove a completed or cancelled task
use Revolution\Copilot\Types\Rpc\TasksRemoveRequest;

$removed = $session->rpc()->tasks()->remove(
    new TasksRemoveRequest(id: $result->agentId)
);
// $removed->removed - Whether the removal succeeded

// Send a message to a running agent task (steering)
use Revolution\Copilot\Types\Rpc\TasksSendMessageRequest;

$sent = $session->rpc()->tasks()->sendMessage(
    new TasksSendMessageRequest(id: $result->agentId, message: 'Please search other directories too')
);
// $sent->sent - Whether the message was sent successfully
// $sent->error - Error message if sending failed (nullable)

// Interrupt only the main turn and keep queued prompts for the next turn
use Revolution\Copilot\Types\Rpc\InterruptMainTurnRequest;

$interrupted = $session->rpc()->interruptMainTurn(
    new InterruptMainTurnRequest(flushQueued: true)
);
// $interrupted->interrupted - Whether the running main turn was interrupted

// Cancel all running background agents without interrupting the main turn
$cancelledCount = $session->rpc()->cancelAllBackgroundAgents();
// Number of cancelled agents

remote (experimental: remote session support)

use Revolution\Copilot\Enums\RemoteSessionMode;
use Revolution\Copilot\Types\Rpc\RemoteEnableRequest;
use Revolution\Copilot\Types\Rpc\RemoteEnableResult;

// Enable a remote session
// When run in a GitHub repository's working directory,
// it returns a URL you can use to access the session from GitHub web or mobile
$result = $session->rpc()->remote()->enable();
// $result->remoteSteerable - Whether remote steering is enabled
// $result->url - GitHub frontend URL (may be null)

// Enable with a mode
// RemoteSessionMode::Off - Local only (default)
// RemoteSessionMode::Export - Export session events to GitHub (no remote steering)
// RemoteSessionMode::On - Enable both export and remote steering
$result = $session->rpc()->remote()->enable(new RemoteEnableRequest(
    mode: RemoteSessionMode::Export,
));

// Disable the remote session
$session->rpc()->remote()->disable();

For details, see Remote Sessions.

sandbox (experimental: sandbox control)

// Check the host's sandbox support before creating a session
$hostSupport = $client->rpc()->sandbox()->getHostSupport();
// $hostSupport->supported, $hostSupport->reason, $hostSupport->capabilities

// Check whether a Proxy CA is needed and whether installation is supported
$proxyCa = $client->rpc()->sandboxProxyCa();
$relevant = $proxyCa->checkRelevance(['enabled' => true]);
$installable = $proxyCa->checkInstallationSupport();

use Revolution\Copilot\Types\Rpc\SandboxDisableForSessionRequest;
use Revolution\Copilot\Types\Rpc\SandboxGrantPathForRequestRequest;

// Get the sandbox enforcement status
$status = $session->rpc()->sandbox()->getEnforcementStatus();

// Credentials that may be usable in new sandbox shells (values aren't returned)
$credentials = $session->rpc()->sandbox()->getCredentialSuggestions();
// $credentials->suggestions is an array of SandboxCredentialSuggestion
// Empty array when the sandbox is disabled or there are no suggestions. Settings and network permissions aren't changed.

// Approve a pending sandbox bypass permission request and disable the sandbox for the whole session
$result = $session->rpc()->sandbox()->disableForSession(new SandboxDisableForSessionRequest(requestId: $requestId));
// $result->success, $result->enabled

// Approve the path grant (sandboxPathGrant) offered by a pending sandbox escalation permission request,
// add that path to the session's sandbox policy, and have the blocked operation
// re-run inside the sandbox
$result = $session->rpc()->sandbox()->grantPathForRequest(new SandboxGrantPathForRequestRequest(requestId: $requestId));
// Array input also works: ->grantPathForRequest(['requestId' => $requestId])
// $result->success
// Fails if the request is no longer pending, didn't come with a sandboxPathGrant,
// or the grant is invalid under the current managed policy.
// This least-privilege approach allows only a specific path and is preferred over disableForSession(), which disables the whole session.
// The path isn't persisted (it applies only to this session and isn't carried over to later sessions).
// Hosts that save sandbox settings can save the path themselves if needed.

In your permission handler, when $request['sandboxPathGrant'] is present, call this with the requestId of the pending request. Because this RPC itself responds to the permission request, return PermissionDecision::noResult() on success so that no normal response is sent.

if (isset($request['sandboxPathGrant'])) {
    $result = $session->rpc()->sandbox()->grantPathForRequest([
        'requestId' => $requestId,
    ]);

    return $result->success
        ? PermissionDecision::noResult()
        : PermissionDecision::reject();
}

metadata (experimental: session information)

use Revolution\Copilot\Types\Rpc\MetadataUpdateClientMetadataRequest;

// Get the session's current activity state
$activity = $session->rpc()->metadata()->activity();
// $activity->abortable - Whether there is work that can be aborted
// $activity->hasActiveWork - Whether work such as a turn or background task is running

// Get client-owned metadata tied to this local session
$metadata = $session->rpc()->metadata()->getClientMetadata();

// Update metadata atomically (applied in the order clear → remove → set)
$metadata = $session->rpc()->metadata()->updateClientMetadata(new MetadataUpdateClientMetadataRequest(
    set: ['my-app/key' => 'value'],
));

Local session management (experimental)

Use $session->rpc()->management() to configure, list, create, message, and close local sessions that opted in to management in the same configuration directory. Register a host callback with setSessionCreationHandler() to receive the reverse RPC from create(). The callback must create the child session with newSessionId, keep its permission and model restrictions, and return a SessionManagementCreateResult. In the following example, $sessionCreationHandler is a closure that receives a SessionManagementCreateHostRequest, creates the child session on the host, and returns a SessionManagementCreateResult.

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Enums\SessionManagementScope;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\Rpc\SessionManagementCloseRequest;
use Revolution\Copilot\Types\Rpc\SessionManagementConfigureRequest;
use Revolution\Copilot\Types\Rpc\SessionManagementCreateRequest;
use Revolution\Copilot\Types\Rpc\SessionManagementListRequest;
use Revolution\Copilot\Types\Rpc\SessionManagementMessageRequest;
use Revolution\Copilot\Types\Rpc\SessionManagementToolOverrides;

Copilot::start(function (CopilotSession $session) use ($sessionCreationHandler): void {
    $session->setSessionCreationHandler($sessionCreationHandler);
    $management = $session->rpc()->management();

    $policy = $management->configure(new SessionManagementConfigureRequest(
        cwd: base_path(),
        enabled: true,
        scope: SessionManagementScope::All,
        tools: new SessionManagementToolOverrides(
            create: true,
            list: true,
            message: true,
            close: true,
        ),
    ));

    $peers = $management->list(new SessionManagementListRequest());
    $peer = $peers->sessions[0] ?? null;

    $child = $management->create(new SessionManagementCreateRequest(
        prompt: 'Review the current implementation.',
    ));

    if ($peer !== null) {
        $message = $management->message(new SessionManagementMessageRequest(
            targetSessionId: $peer->sessionId,
            message: 'Please report your progress.',
        ));
    }
});

accepted from message() means the message was accepted for delivery, not that the target replied or finished its task. After you confirm separately that a child session finished its work, use close() to close only the children you created. Saved history isn’t deleted.

$management->close(new SessionManagementCloseRequest(
    targetSessionId: 'child-session-id',
));

Session canvas

Call the Canvas RPCs from $session->rpc()->canvas(). list() returns the list in canvases of a CanvasList, and listOpen() returns it in openCanvases of a CanvasListOpenResult. open() returns an OpenCanvasInstance, and action invocations return a CanvasActionInvokeResult. close() has no return value.

$canvases = $session->rpc()->canvas();
$available = $canvases->list()->canvases;
$openInstances = $canvases->listOpen()->openCanvases;

$instance = $canvases->open([
    'canvasId' => 'editor',
    'instanceId' => 'editor-1',
    'input' => ['file' => 'README.md'],
]);

$result = $canvases->action()->invoke([
    'instanceId' => $instance->instanceId,
    'actionName' => 'format',
    'input' => ['style' => 'compact'],
]);

$canvases->close(['instanceId' => $instance->instanceId]);

Canvas provider reverse-RPCs (canvas.open / canvas.close / canvas.action.invoke) are handled by canvasHandler in SessionConfig / ResumeSessionConfig. Rendering the canvas is the responsibility of the host UI.

workflow

The experimental RPC APIs for workflows, connectors, diagnostics, and more added in the Copilot CLI 1.0.89 series are also available from SessionRpc. Pass these variable protocol payloads as JSON-compatible arrays; responses are also returned as arrays. The current sessionId is added to each call automatically.

// Run a workflow registered on the CLI side and check its status
$run = $session->rpc()->workflow()->run([
    'name' => 'weekly-summary',
    'args' => ['team' => 'platform'],
]);
$current = $session->rpc()->workflow()->getRun(['runId' => $run['runId']]);

// Diagnostics and connector list
$diagnostics = $session->rpc()->diagnostics()->read(['sources' => ['mcp']]);
$connectors = $session->rpc()->connectors()->list();
$account = $session->rpc()->connectors()->getAccount(); // ConnectorSessionAccount if an account is selected

// Plugin marketplaces
$marketplaces = $session->rpc()->plugins()->marketplaces()->list();

// End the active session and process the sessionEnd hook in the background
$session->rpc()->shutdown(['detachSessionEndHooks' => true]);

workflow() calls the low-level RPCs provided by the CLI. A high-level API for registering and running PHP closures as workflows, like the Node.js SDK has, wasn’t added in this sync. These new RPC groups depend on the CLI version and are experimental, so use them only with a compatible CLI.

SessionFS callback types

Callback types (Request/Result) are defined for session-scoped file system operations. These are the request/response types used when the Copilot CLI calls back to the client.

Type class	Purpose
`SessionFsReadFileRequest` / `SessionFsReadFileResult`	Read file
`SessionFsWriteFileRequest`	Write file
`SessionFsAppendFileRequest`	Append to file
`SessionFsExistsRequest` / `SessionFsExistsResult`	Check file exists
`SessionFsStatRequest` / `SessionFsStatResult`	Get file metadata
`SessionFsMkdirRequest`	Create directory
`SessionFsReaddirRequest` / `SessionFsReaddirResult`	List directory
`SessionFsReaddirWithTypesRequest` / `SessionFsReaddirWithTypesResult`	List directory with types
`SessionFsRmRequest`	Delete file/directory
`SessionFsRenameRequest`	Rename file/directory

SessionFsStatResult, SessionFsReaddirResult, and SessionFsReaddirWithTypesResult have an optional error (SessionFsError) used on failure.

SessionFs handlers

The Client routes sessionFs.readFile / readFileBytes / writeFile / writeFileBytes requests, as well as appendFile, exists, stat, mkdir, readdir, readdirWithTypes, rm, rename, sqliteQuery, sqliteTransaction, and sqliteExists, to the Session’s provider. File operation failures are returned as an error of ENOENT (ENOENT or errno 2) or UNKNOWN. exists returns false on exception, and stat returns zero values plus an error on failure. Operations the provider doesn’t support result in an UNKNOWN error (a JSON-RPC error for SQLite operations). Exceptions from sqliteQuery/sqliteExists become JSON-RPC errors, and sqliteTransaction failures are returned as an error in the result (with errorClass). The provider-side interfaces (SessionFsFilesystemProvider, SessionFsSqliteCapableProvider, SessionFsSqliteProvider, SessionFsSqliteTransactionProvider) were added as separate interfaces so they don’t break the existing SessionFsProvider (two methods).

SQLite callback types

Type class	Purpose
`SessionFsSetProviderCapabilities`	Declares provider capabilities (such as SQLite support)
`SessionFsSqliteExistsRequest` / `SessionFsSqliteExistsResult`	Check whether a SQLite database exists
`SessionFsSqliteQueryRequest` / `SessionFsSqliteQueryResult`	Run a SQLite query
`SessionFsSqliteTransactionRequest` / `SessionFsSqliteTransactionStatement` / `SessionFsSqliteTransactionResult`	SQLite transaction (runs multiple statements atomically)
`SessionFsSqliteTransactionError`	Classification of transaction failures (`errorClass`: `busyOrLocked` / `fatal` / `postCommitAmbiguous`; enum `SessionFSSqliteTransactionErrorClass`)

To enable SQLite support, pass SessionFsSetProviderCapabilities(sqlite: true) to capabilities of SessionFsSetProviderRequest.

use Revolution\Copilot\Types\Rpc\SessionFsSetProviderCapabilities;
use Revolution\Copilot\Types\Rpc\SessionFsSetProviderRequest;

$client->rpc()->sessionFs()->setProvider(new SessionFsSetProviderRequest(
    initialCwd: '/app',
    sessionStatePath: '.copilot/sessions',
    capabilities: new SessionFsSetProviderCapabilities(sqlite: true),
));

Normally you don’t call this RPC directly. If you specify the Client option sessionFs (or session_fs in config/copilot.php), Client::start() sends sessionFs.setProvider only once. Sessions need createSessionFsProvider (see SessionConfig). The SessionFsSqliteQueryType enum (src/Enums/) represents the query type:

Exec: DDL/multiple statements (no result)
Query: SELECT (returns rows)
Run: INSERT/UPDATE/DELETE (returns rowsAffected)

These type classes are in src/Types/Rpc/.

Using arrays for arguments

Dedicated classes are used for both arguments and return values, but you can also pass arguments as arrays.

$session->rpc()->mode()->set(['mode' => 'plan']);

Testing

Copilot::fake() mocks are not available, so mock with Copilot::expects('client') or Copilot::expects('start').

For the latest updates, see the GitHub repository.