RPC (Remote Procedure Call)

Invoca metodi di protocollo su modelli, strumenti, permessi ecc. usando ServerRpc e SessionRpc di Laravel Copilot SDK.

​

RPC (Remote Procedure Call)

Nell’SDK ufficiale le funzionalità più recenti sono supportate tramite generazione automatica di codice a partire da api.schema.json. Nella versione Laravel implementiamo le stesse cose facendo riferimento alle versioni generate degli altri linguaggi.

​

ServerRpc

Classe RPC associata al Client.

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

// Recupero dell'elenco dei modelli
// Il valore di ritorno è ModelList
$result = Copilot::client()->rpc()->models()->list();
// models è un array di ModelInfo
$models = $result->models;

// Quasi equivalente a listModels() presente fin dall'inizio
// Il valore di ritorno è un array di ModelInfo
Copilot::client()->listModels();

Le funzionalità già incluse originariamente nell’SDK sono state aggiunte nuovamente anche nella versione generata automaticamente.

​

Elenco dei metodi

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

// models
Copilot::client()->rpc()->models()->list();
// Recupero con token GitHub per singola sessione
Copilot::client()->rpc()->models()->list(new ModelsListRequest(gitHubToken: $token));

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

// account
Copilot::client()->rpc()->account()->getQuota();
// Recupero con token GitHub per singola sessione
Copilot::client()->rpc()->account()->getQuota(new AccountGetQuotaRequest(gitHubToken: $token));

// mcp config (gestione della configurazione dei server MCP)
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']),
));
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'));
// Abilita/disabilita un server MCP (configurazione globale)
Copilot::client()->rpc()->mcp()->enable(new McpConfigEnableRequest(names: ['my-server']));
Copilot::client()->rpc()->mcp()->disable(new McpConfigDisableRequest(names: ['my-server']));

// mcp discover (rilevamento automatico dei server MCP)
Copilot::client()->rpc()->mcp()->discover(new McpDiscoverRequest(
    workingDirectory: '/path/to/project',
));
// Può essere eseguito senza argomenti
$result = Copilot::client()->rpc()->mcp()->discover();
// $result->servers is an array of DiscoveredMcpServer

// sessionFs (registrazione di un provider di filesystem di sessione)
Copilot::client()->rpc()->sessionFs()->setProvider(new SessionFsSetProviderRequest(
    initialCwd: '/path/to/project',
    sessionStatePath: '.copilot/sessions',
    conventions: 'posix',
));

// sessions (experimental: fork di sessione)
Copilot::client()->rpc()->sessions()->fork(new SessionsForkRequest(
    sessionId: 'source-session-id',
    toEventId: 'evt-boundary', // opzionale: include solo eventi precedenti a questo ID
));

// skills (gestione skill a livello di server)
// Ricerca delle skill
$result = Copilot::client()->rpc()->skills()->discover();
// $result->skills è un array di ServerSkill
// Opzionalmente specifica il percorso del progetto
$result = Copilot::client()->rpc()->skills()->discover(new SkillsDiscoverRequest(
    projectPaths: ['/path/to/project'],
    skillDirectories: ['/custom/skills'],
));

// Impostazione delle skill da disabilitare
Copilot::client()->rpc()->skills()->config()->setDisabledSkills(
    new SkillsConfigSetDisabledSkillsRequest(disabledSkills: ['skill-name'])
);

​

SessionRpc

Classe RPC associata alla Session.

È possibile anche usare la plan mode, cosa che nell’SDK precedente non era possibile.

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: 'Crea un piano per XX');

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

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

    $response = $session->sendAndWait(prompt: 'Implementa secondo il piano');
    dump($response->content());
});

​

Elenco dei metodi

// model
$session->rpc()->model()->getCurrent();
$session->rpc()->model()->switchTo(new ModelSwitchToRequest(modelId: 'gpt-4'));
// Se vuoi specificare reasoningEffort (solo modelli supportati)
$session->rpc()->model()->switchTo(new ModelSwitchToRequest(modelId: 'claude-opus-4.7', reasoningEffort: ReasoningEffort::HIGH));
// Se vuoi sovrascrivere modelCapabilities
$session->rpc()->model()->switchTo(new ModelSwitchToRequest(
    modelId: 'gpt-4',
    modelCapabilities: new ModelCapabilitiesOverride(
        supports: new ModelCapabilitiesOverrideSupports(vision: true),
    ),
));

// L'helper setModel() consente allo stesso modo di specificare reasoningEffort e modelCapabilities
$session->setModel('claude-opus-4.7', ReasoningEffort::HIGH);
$session->setModel('claude-opus-4.7', 'high'); // String is also supported
$session->setModel('gpt-4', modelCapabilities: ['supports' => ['vision' => true]]); // può essere specificato anche come array

// mode
$session->rpc()->mode()->get();
$session->rpc()->mode()->set(new ModeSetRequest(mode: 'plan'));

// name
$session->rpc()->name()->get();
$session->rpc()->name()->set(new NameSetRequest(name: 'My Session'));

// plan
$session->rpc()->plan()->read();
$session->rpc()->plan()->update(new PlanUpdateRequest(content: '...'));
$session->rpc()->plan()->delete();

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

// instructions (recupero delle sorgenti di istruzione della sessione)
$result = $session->rpc()->instructions()->getSources();
// $result->sources - array di InstructionsSources

// fleet
$session->rpc()->fleet()->start(new FleetStartRequest(prompt: '...'));
// Per i dettagli consulta Fleet Mode

// 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: gestione delle skill)
$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();

// mcp (experimental: gestione dei server MCP)
$session->rpc()->mcp()->list();
$session->rpc()->mcp()->enable(new McpEnableRequest(serverName: 'server-name'));
$session->rpc()->mcp()->disable(new McpDisableRequest(serverName: 'server-name'));
$session->rpc()->mcp()->reload();
// Login OAuth MCP (per server MCP che richiedono autenticazione)
$result = $session->rpc()->mcp()->login(new McpOauthLoginRequest(serverName: 'my-server'));
// $result->authorizationUrl - URL del flusso OAuth (se richiede autenticazione)

// plugins (experimental: elenco dei plugin)
$session->rpc()->plugins()->list();

// extensions (experimental: gestione delle extension)
$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()->reload();

// compaction → rinominato in history
$session->rpc()->history()->compact();
// Tronca la history a partire da un evento specifico
$session->rpc()->history()->truncate(new HistoryTruncateRequest(
    eventId: 'evt-123', // vengono eliminati questo evento e tutti quelli successivi
));

// tools (protocollo v3+: risposta all'evento external_tool.requested)
$session->rpc()->tools()->handlePendingToolCall(new ToolsHandlePendingToolCallRequest(
    requestId: '...',
    result: 'Risultato di esecuzione dello strumento',
));

// permissions (protocollo v3+: risposta all'evento permission.requested)
$session->rpc()->permissions()->handlePendingPermissionRequest(new PermissionDecisionRequest(
    requestId: '...',
    result: PermissionRequestResultKind::approveOnce(),
));
// Approva automaticamente tutte le richieste di permesso in sessione
$session->rpc()->permissions()->setApproveAll(new PermissionsSetApproveAllRequest(enabled: true));
// Reimposta le approvazioni di permesso a livello di sessione
$session->rpc()->permissions()->resetSessionApprovals();

// commands: risposta a un evento di invocazione comando
$session->rpc()->commands()->handlePendingCommand(new CommandsHandlePendingCommandRequest(
    requestId: '...',
));

// ui: risposta a una richiesta di elicitation UI
$session->rpc()->ui()->elicitation(new UIElicitationRequest(
    message: 'Domanda per l\'utente',
    requestedSchema: ['type' => 'object', 'properties' => [...]],
));

// ui: risposta a una richiesta di elicitation in sospeso (tramite evento elicitation.requested)
$session->rpc()->ui()->handlePendingElicitation(new UIHandlePendingElicitationRequest(
    requestId: '...',
    result: ['action' => 'accept', 'content' => ['name' => 'John']],
));

// log: registra un messaggio nella timeline della sessione
$session->rpc()->log()->log(new LogRequest(message: 'Elaborazione avviata'));
$session->rpc()->log()->log(new LogRequest(message: 'Uso disco elevato', level: LogLevel::WARNING));
$session->rpc()->log()->log(new LogRequest(message: 'Si è verificato un errore', level: LogLevel::ERROR));
$session->rpc()->log()->log(new LogRequest(message: 'Informazioni di debug', ephemeral: true));

// shell: esegue comandi shell all'interno della sessione
$result = $session->rpc()->shell()->exec(new ShellExecRequest(command: 'ls -la'));
// Con $result->processId ottieni l'ID del processo per kill o tracciamento output

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

// Interrompe un processo shell in esecuzione
$session->rpc()->shell()->kill(new ShellKillRequest(
    processId: $result->processId,
    signal: 'SIGTERM', // SIGTERM (default), SIGKILL, SIGINT
));

// usage (experimental: metriche di uso della sessione)
$metrics = $session->rpc()->usage()->getMetrics();
// $metrics->totalPremiumRequestCost - costo totale delle richieste premium
// $metrics->totalUserRequests - numero totale di richieste utente
// $metrics->codeChanges - metriche di modifica codice (righe aggiunte, righe rimosse, numero di file modificati)
// $metrics->modelMetrics - uso token e numero di richieste per modello
// $metrics->currentModel - identificatore del modello corrente

// auth: recupera lo stato di autenticazione della sessione
$status = $session->rpc()->auth()->getStatus();
// $status->isAuthenticated - se è autenticato
// $status->authType - tipo di autenticazione (enum AuthInfoType: gh-cli, token, env, ecc.)
// $status->login - nome utente GitHub
// $status->host - host GitHub
// $status->copilotPlan - piano Copilot (individual, business, ecc.)
// $status->statusMessage - messaggio dello stato di autenticazione

​

Tipi di callback SessionFS

Sono definiti tipi di callback (Request/Result) per operazioni sul filesystem a livello di sessione. Si tratta dei tipi di richiesta/risposta usati quando Copilot CLI richiama il client.

Classe di tipo	Uso
SessionFsReadFileRequest / SessionFsReadFileResult	Lettura file
SessionFsWriteFileRequest	Scrittura file
SessionFsAppendFileRequest	Append file
SessionFsExistsRequest / SessionFsExistsResult	Verifica esistenza file
SessionFsStatRequest / SessionFsStatResult	Recupero metadata file
SessionFsMkdirRequest	Creazione directory
SessionFsReaddirRequest / SessionFsReaddirResult	Elenco directory
SessionFsReaddirWithTypesRequest / SessionFsReaddirWithTypesResult	Elenco directory tipizzato
SessionFsRmRequest	Rimozione file/directory
SessionFsRenameRequest	Rinomina file/directory

Queste classi di tipo sono in src/Types/Rpc/.

​

Specifica degli argomenti come array

Sia gli argomenti sia i valori di ritorno usano classi dedicate, ma gli argomenti possono essere specificati anche come array.

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

​

Testing

Poiché non puoi usare il mock via Copilot::fake(), effettua il mock con Copilot::expects('client') o Copilot::expects('start').

Per le informazioni più recenti fai riferimento al repository GitHub.