> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Session information and local session management

> Use SessionRpc in Laravel Copilot SDK to read session information and manage local sessions.

## Session information and local session management

Scope: SessionRpc (per-session operations tied to a Session)

For an overview of RPC and the list of all RPC pages, see [RPC](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc.md).

## metadata (experimental: session information)

```php theme={null}
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`.

```php theme={null}
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.

```php theme={null}
$management->close(new SessionManagementCloseRequest(
    targetSessionId: 'child-session-id',
));
```


## Related topics

- [RPC (Remote Procedure Call)](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc.md)
- [Session lifecycle events](https://kawax.biz/en/packages/laravel-copilot-sdk/session-lifecycle-event.md)
- [Session](https://kawax.biz/en/session.md)
- [ServerRpc overview](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc/server-overview.md)
- [Cloud Sessions](https://kawax.biz/en/packages/laravel-copilot-sdk/cloud-sessions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.