RPC(Remote Procedure Call)

Laravel Copilot SDK의 ServerRpc와 SessionRpc를 사용해 모델, 도구, 권한 등의 프로토콜 메서드를 호출합니다.

​

RPC(Remote Procedure Call)

공식 SDK에서는 최근의 신기능은 api.schema.json을 기반으로 한 자동 코드 생성으로 대응하고 있습니다. Laravel 버전에서는 생성 후의 타 언어 버전을 참고해 동일하게 구현하고 있습니다.

​

ServerRpc

Client에 연결된 RPC 클래스입니다.

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

// 모델 목록 가져오기
// 반환값은 ModelList
$result = Copilot::client()->rpc()->models()->list();
// models는 ModelInfo의 배열
$models = $result->models;

// 초기부터 있던 listModels()와 거의 동일
// 반환값은 ModelInfo의 배열
Copilot::client()->listModels();

원래부터 SDK에 포함되어 있던 기능도 자동 코드 생성 버전에서 다시 추가되었습니다.

​

메서드 목록

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

// models
Copilot::client()->rpc()->models()->list();
// 세션별 GitHub 토큰으로 가져오기
Copilot::client()->rpc()->models()->list(new ModelsListRequest(gitHubToken: $token));

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

// account
Copilot::client()->rpc()->account()->getQuota();
// 세션별 GitHub 토큰으로 가져오기
Copilot::client()->rpc()->account()->getQuota(new AccountGetQuotaRequest(gitHubToken: $token));

// mcp config (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'));
// MCP 서버를 활성화/비활성화(글로벌 설정)
Copilot::client()->rpc()->mcp()->enable(new McpConfigEnableRequest(names: ['my-server']));
Copilot::client()->rpc()->mcp()->disable(new McpConfigDisableRequest(names: ['my-server']));

// mcp discover (MCP 서버 자동 검출)
Copilot::client()->rpc()->mcp()->discover(new McpDiscoverRequest(
    workingDirectory: '/path/to/project',
));
// 인자 없이 실행 가능
$result = Copilot::client()->rpc()->mcp()->discover();
// $result->servers is an array of DiscoveredMcpServer

// sessionFs (세션 파일시스템 프로바이더 등록)
Copilot::client()->rpc()->sessionFs()->setProvider(new SessionFsSetProviderRequest(
    initialCwd: '/path/to/project',
    sessionStatePath: '.copilot/sessions',
    conventions: 'posix',
));

// sessions (experimental: 세션 포크)
Copilot::client()->rpc()->sessions()->fork(new SessionsForkRequest(
    sessionId: 'source-session-id',
    toEventId: 'evt-boundary', // 옵션: 이 ID 이전의 이벤트만 포함
));

// skills (서버 레벨의 스킬 관리)
// 스킬 탐색
$result = Copilot::client()->rpc()->skills()->discover();
// $result->skills는 ServerSkill의 배열
// 옵션으로 프로젝트 경로 지정
$result = Copilot::client()->rpc()->skills()->discover(new SkillsDiscoverRequest(
    projectPaths: ['/path/to/project'],
    skillDirectories: ['/custom/skills'],
));

// 비활성화할 스킬 설정
Copilot::client()->rpc()->skills()->config()->setDisabledSkills(
    new SkillsConfigSetDisabledSkillsRequest(disabledSkills: ['skill-name'])
);

​

SessionRpc

Session에 연결된 RPC 클래스입니다.

이전 SDK에서 할 수 없었던 플랜 모드 이용 등도 가능합니다.

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: '〇〇의 플랜을 작성');

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

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

    $response = $session->sendAndWait(prompt: '플랜에 따라 구현');
    dump($response->content());
});

​

메서드 목록

// model
$session->rpc()->model()->getCurrent();
$session->rpc()->model()->switchTo(new ModelSwitchToRequest(modelId: 'gpt-4'));
// reasoningEffort를 지정하는 경우(대응 모델만)
$session->rpc()->model()->switchTo(new ModelSwitchToRequest(modelId: 'claude-opus-4.7', reasoningEffort: ReasoningEffort::HIGH));
// modelCapabilities를 오버라이드하는 경우
$session->rpc()->model()->switchTo(new ModelSwitchToRequest(
    modelId: 'gpt-4',
    modelCapabilities: new ModelCapabilitiesOverride(
        supports: new ModelCapabilitiesOverrideSupports(vision: true),
    ),
));

// setModel() 헬퍼로도 마찬가지로 reasoningEffort나 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]]); // 배열로도 지정 가능

// 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 (세션의 인스트럭션 소스 취득)
$result = $session->rpc()->instructions()->getSources();
// $result->sources - InstructionsSources의 배열

// fleet
$session->rpc()->fleet()->start(new FleetStartRequest(prompt: '...'));
// 자세한 내용은 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: 스킬 관리)
$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: 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();
// MCP OAuth 로그인(인증이 필요한 MCP 서버용)
$result = $session->rpc()->mcp()->login(new McpOauthLoginRequest(serverName: 'my-server'));
// $result->authorizationUrl - OAuth 플로우의 URL(인증이 필요한 경우)

// plugins (experimental: 플러그인 목록)
$session->rpc()->plugins()->list();

// extensions (experimental: 익스텐션 관리)
$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 → history 로 이름 변경
$session->rpc()->history()->compact();
// 특정 이벤트 이후의 이력을 절단
$session->rpc()->history()->truncate(new HistoryTruncateRequest(
    eventId: 'evt-123', // 이 이벤트와 그 이후의 모든 이벤트가 삭제됨
));

// tools (프로토콜 v3+: external_tool.requested 이벤트에 응답)
$session->rpc()->tools()->handlePendingToolCall(new ToolsHandlePendingToolCallRequest(
    requestId: '...',
    result: '도구의 실행 결과',
));

// permissions (프로토콜 v3+: permission.requested 이벤트에 응답)
$session->rpc()->permissions()->handlePendingPermissionRequest(new PermissionDecisionRequest(
    requestId: '...',
    result: PermissionRequestResultKind::approveOnce(),
));
// 세션 내의 모든 권한 요청을 자동 승인
$session->rpc()->permissions()->setApproveAll(new PermissionsSetApproveAllRequest(enabled: true));
// 세션 스코프의 권한 승인을 리셋
$session->rpc()->permissions()->resetSessionApprovals();

// commands: 커맨드 호출 이벤트에 응답
$session->rpc()->commands()->handlePendingCommand(new CommandsHandlePendingCommandRequest(
    requestId: '...',
));

// ui: UI 엘리시테이션 요청에 응답
$session->rpc()->ui()->elicitation(new UIElicitationRequest(
    message: '사용자에게의 질문',
    requestedSchema: ['type' => 'object', 'properties' => [...]],
));

// ui: 보류 중인 엘리시테이션 요청에 응답(elicitation.requested 이벤트 경유)
$session->rpc()->ui()->handlePendingElicitation(new UIHandlePendingElicitationRequest(
    requestId: '...',
    result: ['action' => 'accept', 'content' => ['name' => 'John']],
));

// log: 세션 타임라인에 메시지 기록
$session->rpc()->log()->log(new LogRequest(message: '처리를 시작했습니다'));
$session->rpc()->log()->log(new LogRequest(message: '디스크 사용량이 많음', level: LogLevel::WARNING));
$session->rpc()->log()->log(new LogRequest(message: '에러가 발생했습니다', level: LogLevel::ERROR));
$session->rpc()->log()->log(new LogRequest(message: '디버그 정보', ephemeral: true));

// shell: 세션 내에서 셸 명령 실행
$result = $session->rpc()->shell()->exec(new ShellExecRequest(command: 'ls -la'));
// $result->processId로 프로세스 ID를 취득해 kill이나 출력 추적에 사용

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

// 실행 중인 셸 프로세스 정지
$session->rpc()->shell()->kill(new ShellKillRequest(
    processId: $result->processId,
    signal: 'SIGTERM', // SIGTERM(기본값), SIGKILL, SIGINT
));

// usage (experimental: 세션 사용량 메트릭스)
$metrics = $session->rpc()->usage()->getMetrics();
// $metrics->totalPremiumRequestCost - 프리미엄 요청의 총 비용
// $metrics->totalUserRequests - 사용자 요청 총 수
// $metrics->codeChanges - 코드 변경 메트릭스(추가 라인 수, 삭제 라인 수, 변경 파일 수)
// $metrics->modelMetrics - 모델별 토큰 사용량과 요청 수
// $metrics->currentModel - 현재 모델 식별자

// auth: 세션의 인증 상태 취득
$status = $session->rpc()->auth()->getStatus();
// $status->isAuthenticated - 인증되었는지 여부
// $status->authType - 인증 타입(AuthInfoType enum: gh-cli, token, env 등)
// $status->login - GitHub 로그인명
// $status->host - GitHub 호스트
// $status->copilotPlan - Copilot 플랜(individual, business 등)
// $status->statusMessage - 인증 상태 메시지

​

SessionFS 콜백 타입

세션 스코프의 파일시스템 조작을 위한 콜백 타입(Request/Result)이 정의되어 있습니다. 이들은 Copilot CLI가 클라이언트에 콜백할 때의 리퀘스트/레스폰스 타입입니다.

타입 클래스	용도
SessionFsReadFileRequest / SessionFsReadFileResult	파일 읽기
SessionFsWriteFileRequest	파일 쓰기
SessionFsAppendFileRequest	파일 추가
SessionFsExistsRequest / SessionFsExistsResult	파일 존재 확인
SessionFsStatRequest / SessionFsStatResult	파일 메타데이터 취득
SessionFsMkdirRequest	디렉터리 작성
SessionFsReaddirRequest / SessionFsReaddirResult	디렉터리 목록
SessionFsReaddirWithTypesRequest / SessionFsReaddirWithTypesResult	타입 부여된 디렉터리 목록
SessionFsRmRequest	파일/디렉터리 삭제
SessionFsRenameRequest	파일/디렉터리 이름 변경

이들 타입 클래스는 src/Types/Rpc/에 배치되어 있습니다.

​

배열로 인자 지정

인자도 반환값도 전용 클래스를 사용하지만, 인자는 배열로 지정할 수도 있습니다.

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

​

테스트

Copilot::fake()로의 목은 사용할 수 없으므로 Copilot::expects('client')나 Copilot::expects('start')로 목해 주세요.

최신 정보는 GitHub 저장소를 참고하세요.