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

# Sessions, Host und Umgebung

> Mit ServerRpc des Laravel Copilot SDK verwalten Sie Sessions, den Host, die Laufzeitumgebung, Cloud-Tasks und die Klassifizierung von Trajektorien.

## Sessions, Host und Umgebung

Geltungsbereich: ServerRpc (serverweite Operationen, die an den Client gebunden sind)

Eine Übersicht über RPC und die Liste aller RPC-Seiten finden Sie unter [RPC](https://kawax.biz/de/packages/laravel-copilot-sdk/rpc.md).

```php theme={null}
use Revolution\Copilot\Enums\EventsReadDirection;
use Revolution\Copilot\Types\Rpc\HooksDiscoverRequest;
use Revolution\Copilot\Types\Rpc\SessionsListRequest;
use Revolution\Copilot\Types\Rpc\SessionsPruneOldRequest;
use Revolution\Copilot\Types\Rpc\SessionsReadPersistedEventsRequest;
use Revolution\Copilot\Types\Rpc\SessionsOpenCreateRequest;
use Revolution\Copilot\Enums\SessionsOpenStatus;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SessionListFilter;

// Liste der integrierten Slash-Befehle, die in neuen Sessions verfügbar sind (experimental)
Copilot::client()->rpc()->commands()->list();

// Hook-Erkennung vor dem Sessionstart (experimental)
Copilot::client()->rpc()->hooks()->discover(new HooksDiscoverRequest(
    projectPaths: ['/path/to/project'],
));

// Sandbox-Unterstützung des Hosts (experimental)
$hostSupport = Copilot::client()->rpc()->sandbox()->getHostSupport();
// $hostSupport->supported, $hostSupport->reason, $hostSupport->capabilities

// sessions (experimental: Abfrage und Verwaltung persistierter Sessions)

// sessions.open wählt mit `kind` zwischen create, resume, resumeLast, attach, Remote-/Cloud-Verbindung oder Handoff.
$opened = $sessions->open(new SessionsOpenCreateRequest(
    options: new SessionConfig(sessionId: 'new-session', model: 'gpt-5'),
));
if ($opened->status === SessionsOpenStatus::Created) {
    echo $opened->sessionId;
}
// Auch ein Array kann übergeben werden. Beim Fortsetzen sessionId auf oberster Ebene der Variante angeben.
$resumed = $sessions->open(['kind' => 'resume', 'sessionId' => 'existing-session']);
// Gibt SessionsOpenResult zurück. Beim Status not_found ist keine sessionId vorhanden.
// sessionApi, onTaskCreated, onProgress und onConfirm sind nur prozessintern und nicht im Wire-Payload enthalten.

$listed = $sessions->list(new SessionsListRequest(
    source: 'local',
    metadataLimit: 50,
    filter: new SessionListFilter(cwd: '/path/to/project'),
));
// Über isRemote jedes SessionMetadata zwischen lokalen und Remote-Sessions unterscheiden
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']]);
// Prüft ohne Öffnen der Session, ob ein lokales Event-Log existiert (auch ein leeres Log zählt)
$hasEvents = Copilot::client()->rpc()->sessions()->hasEvents(['sessionId' => 'session-id']);
// $hasEvents->exists ist false, wenn die Session Metadaten, aber kein Log hat
$sizes = $sessions->getSizes(); // $sizes->sizes ist Session-ID => Anzahl Bytes
$inUse = $sessions->checkInUse(['sessionIds' => ['session-id']]);
$deleted = $sessions->bulkDelete(['sessionIds' => ['session-id']]);

// Aktive Session schließen (Verlauf wird nicht gelöscht)
$sessions->close(['sessionId' => 'session-id']);

// Ausstehende Events auf die Festplatte speichern
$sessions->save(['sessionId' => 'session-id']);

// Die von diesem Prozess gehaltene In-Use-Sperre der Session explizit freigeben
$sessions->releaseLock(['sessionId' => 'session-id']);

// reloadPluginHooks lädt User-/Plugin-Hooks neu.
// Vor der Folder-Trust-Bestätigung werden Repo-Hooks zurückgestellt und nach der Vertrauensbestätigung nachgeladen.
$sessions->reloadPluginHooks([
    'sessionId' => 'session-id',
    'deferRepoHooks' => true,
]);
$loadedHooks = $sessions->loadDeferredRepoHooks(['sessionId' => 'session-id']);
// $loadedHooks->startupPrompts und $loadedHooks->hookCount

// Manager-weite zusätzliche Plugin-Konfiguration ersetzen (leeres Array zum Löschen)
$sessions->setAdditionalPlugins(['plugins' => []]);

// summary / context der lokalen Session-Metadaten ergänzen
$enriched = $sessions->enrichMetadata([
    'sessions' => [[
        'sessionId' => 'session-id',
        'startTime' => '2026-10-17T09:00:00Z',
        'modifiedTime' => '2026-10-17T09:00:00Z',
        'isRemote' => false,
    ]],
]);

// close() führt Shutdown, Event-Speicherung und Freigabe der Sperre durch und verwirft die aktive Session,
// löscht aber nicht den persistierten Verlauf. $session->disconnect() gibt per session.detach die Verbindung
// zu diesem SDK und die In-Memory-Ressourcen auf PHP-Seite frei. Zum Löschen persistierter Daten verwenden Sie bulkDelete().

// Persistierte Events ohne Öffnen der Session mit einem Cursor seitenweise lesen
$cursor = null;
do {
    $page = $sessions->readPersistedEvents(new SessionsReadPersistedEventsRequest(
        sessionId: 'session-id',
        cursor: $cursor,
        max: 100,
        direction: EventsReadDirection::FORWARD,
    ));

    foreach ($page->events as $event) {
        // Event verarbeiten
    }

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

// dryRun löscht nichts, sondern gibt Kandidaten und Schätzungen zurück. Zum tatsächlichen Löschen dryRun: false angeben
$preview = $sessions->pruneOld(new SessionsPruneOldRequest(
    olderThanDays: 30,
    dryRun: true,
));

// sessions.fork
$sessions->fork(new SessionsForkRequest(
    sessionId: 'source-session-id',
    toEventId: 'evt-boundary', // Optional: Nur Events vor dieser ID einschließen
));

// environments (experimental: GitHub-Mission-Control-Umgebungen suchen, abrufen und löschen)
$result = Copilot::client()->rpc()->environments()->list(['kind' => 'user-local']);
// $result->environments ist ein Array von GitHubEnvironment
$env = Copilot::client()->rpc()->environments()->get(['environmentId' => 'env-id']);
Copilot::client()->rpc()->environments()->delete(['environmentId' => 'env-id']);
```

## Lebenszyklus von Runtime und Host (experimental)

`host.unpublishSession()` zieht eine Application-Publication von einem eigenen, laufenden Host zurück. Das Zurückziehen der Veröffentlichung löscht oder stoppt weder den ursprünglichen Session-Verlauf noch Worktrees oder laufende Arbeiten. Ist die Session bereits nicht veröffentlicht, ist `unpublished` gleich `false`; andere Publications als application führen zu einem Fehler.

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

`host.dispose()` beendet den Host-Listener mit der angegebenen `hostId`.

```php theme={null}
Copilot::client()->rpc()->host()->dispose(['hostId' => 'host-1']);
```

`host.setSessionCreationPolicy()` legt fest, ob ein laufender Host neue Remote-Sessions annimmt. Die Änderung trennt keine bestehenden Clients und gilt nur für spätere Zulassungen.

```php theme={null}
use Revolution\Copilot\Types\Rpc\HostSetSessionCreationPolicyRequest;

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

Bei einer vom SDK gestarteten stdio-Runtime ruft `Client::stop()` nach dem Trennen der Sessions und vor dem Schließen der JSON-RPC-Verbindung und des Prozesses `runtime.shutdown` auf. Das Trennen der Sessions (`session.detach`) teilt sich über alle Sessions hinweg eine gemeinsame Frist von 10 Sekunden. Ein Trennvorgang, der die Frist überschreitet, wird als Fehler in den Rückgabewert aufgenommen, und der Stoppvorgang wird fortgesetzt. Außerdem wird bis zu 10 Sekunden auf den Abschluss der Runtime-Bereinigung gewartet; bei einem Fehler wird dieser in den Rückgabewert aufgenommen und der restliche Stoppvorgang fortgesetzt. Bei Verbindungen zu externen Runtimes wie `cli_url` wird dieser RPC nicht aufgerufen, damit die gemeinsam genutzte Runtime nicht beendet wird.

Wenn die CLI die zugehörige Anfrage nicht ermitteln kann und einen JSON-RPC-Fehler mit `id: null` zurückgibt, schlagen alle laufenden Anfragen mit einer `JsonRpcException` fehl. Die Exception enthält eine Diagnosemeldung, aus der zitierte Werte entfernt wurden und deren Länge begrenzt ist. Die Verbindung bleibt geöffnet. Da die CLI die Anfrage möglicherweise bereits verarbeitet hat, wiederholen Sie sie nicht automatisch, ohne sicherzustellen, dass dies unbedenklich ist. Das SDK weist ausgehende Anfragen mit mehr als 127 Verschachtelungsebenen, die die CLI nicht lesen kann, bereits vor dem Senden zurück. Zu tief verschachtelte Handler-Antworten ersetzt es durch einen JSON-RPC-Fehler.

## cloudTasks (experimental: Cloud-Agent-Tasks)

`cloudTasks()` erstellt, löscht und ruft Tasks des Cloud-Coding-Agents ab, liest Session-Logs und Replays, ändert den Freigabestatus und ermittelt die Session, die zu einer Task-ID geöffnet werden soll. Jede Methode akzeptiert den passenden Params-Typ oder ein Array und gibt ein typisiertes DTO zurück. Ist `ok` im Erstellungsergebnis `false`, finden Sie in `reason` und `message` den Grund, aus dem der Dienst die Anfrage abgelehnt hat, und in `statusCode`, `errorMessage` und `errorPayloadJson` die Fehlerinformationen einer ausgeführten HTTP-Anfrage.

```php theme={null}
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 und $result->message beschreiben eine abgelehnte Anfrage.
    // $result->statusCode und $result->errorMessage beschreiben eine versuchte HTTP-Anfrage.
}
```

## taskAnalytics (experimental: aufgezeichnete Trajektorien klassifizieren)

`taskAnalytics()->classifyTrajectory()` klassifiziert aufgezeichnete Copilot-Events oder ATIF-Daten, ohne eine Session zu erstellen. Archivierte Tools werden nicht ausgeführt, und weder dem Gesprächsverlauf noch der Klassifizierungstelemetrie wird etwas hinzugefügt. Übergeben Sie `events` in ihrer ursprünglichen Reihenfolge. Sie können außerdem `classifiers`, `maxConcurrentRequests`, `judge` und `previousResult` angeben. Mit `validateOnly: true` überspringt die Runtime die Inferenz und gibt nur das Ergebnis der lokalen Validierung zurück.

Eine normale Klassifizierung sendet den Event-Inhalt an eine Modellverarbeitung, die Ihre GitHub-CAPI-Anmeldeinformationen verwendet. Es gibt keine automatische Schwärzung und keinen Schutz vor Prompt Injection. Genehmigen Sie den Upload, prüfen Sie die Herkunft des Archivs und entfernen Sie vorher sensible Daten. Klassifizierungsergebnisse sind keine gesicherten Fakten, verwenden Sie sie daher nicht für Autorisierungs- oder Sicherheitsentscheidungen.

```php theme={null}
$result = Copilot::client()->rpc()->taskAnalytics()->classifyTrajectory([
    'events' => $events,
    'validateOnly' => true,
]);
```

Um eine Authentifizierungs-URL im Browser zu öffnen, verwenden Sie `runtime()->openBrowser()`.

```php theme={null}
use Revolution\Copilot\Types\Rpc\RuntimeOpenBrowserRequest;

Copilot::client()->rpc()->runtime()->openBrowser(new RuntimeOpenBrowserRequest(
    url: 'https://example.com/authorize',
));
```

Um die Warnung zur Sandbox-Pfadfreigabe abzurufen, verwenden Sie `sandbox()->getPathGrantWarning()`.

```php theme={null}
use Revolution\Copilot\Types\Rpc\SandboxPathGrantWarningParams;

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

## sessions connect und Remote Control (TCP-Modus)

Um den CLI-Server mit einer bestehenden Remote-Session zu verbinden, verwenden Sie `sessions()->connect()`. Übergeben Sie die `sessionId` der Remote-Session. Das Ergebnis enthält die SDK-seitige `sessionId` und die Metadaten der Remote-Session.

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\Rpc\ConnectRemoteSessionParams;

$client = Copilot::useTcp(url: 'tcp://127.0.0.1:12345')->client();

$connected = $client->rpc()->sessions()->connect(
    new ConnectRemoteSessionParams(sessionId: 'remote-session-id'),
);

echo $connected->sessionId;
// $connected->metadata - ConnectedRemoteSessionMetadata-Objekt
```

Im TCP-Modus können Sie mit `sessions()` außerdem eine einzige Remote Control für die gesamte Runtime verwalten. Anders als mit dem sessionbezogenen `remote()->enable()` können Sie mit diesen Methoden Remote Control starten, stoppen, zwischen Sessions übertragen und den aktuellen Status lesen.

```php theme={null}
use Revolution\Copilot\Types\Rpc\RemoteControlConfig;
use Revolution\Copilot\Types\Rpc\SessionsStartRemoteControlRequest;

$result = $client->rpc()->sessions()->startRemoteControl(
    new SessionsStartRemoteControlRequest(
        sessionId: $sessionId,
        config: new RemoteControlConfig(
            remote: true,
            steerable: true,
            explicit: true,
            silent: false,
        ),
    ),
);

if ($result->status->frontendUrl !== null) {
    echo 'Remote URL: '.$result->status->frontendUrl.PHP_EOL;
}

$status = $client->rpc()->sessions()->getRemoteControlStatus();
// Der Zustand ist off / connecting / active / error. Bei active sind außerdem frontendUrl und isSteerable verfügbar

$client->rpc()->sessions()->setRemoteControlSteering(['enabled' => true]);
$client->rpc()->sessions()->transferRemoteControl([
    'toSessionId' => $nextSessionId,
    'expectedFromSessionId' => $sessionId,
]);
$client->rpc()->sessions()->stopRemoteControl([
    'expectedSessionId' => $nextSessionId,
]);
```

Details finden Sie unter [Remote Sessions](https://kawax.biz/de/packages/laravel-copilot-sdk/remote-sessions.md).


## Related topics

- [ServerRpc-Übersicht](https://kawax.biz/de/packages/laravel-copilot-sdk/rpc/server-overview.md)
- [RPC (Remote Procedure Call)](https://kawax.biz/de/packages/laravel-copilot-sdk/rpc.md)
- [AHP Host](https://kawax.biz/de/packages/laravel-copilot-sdk/ahp.md)
- [SessionConfig](https://kawax.biz/de/packages/laravel-copilot-sdk/session-config.md)
- [Session-Informationen und lokale Session-Verwaltung](https://kawax.biz/de/packages/laravel-copilot-sdk/rpc/session-info.md)


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