Session AI credit limits

Use sessionLimits to set a soft AI credit limit for the current accounting window of a Copilot session. You can set it both when creating and when resuming a session.

Set a limit

Pass the limit to maxAiCredits on SessionLimitsConfig. Usage is checked after each model call completes, so a single response can exceed the configured value. Once the limit is exceeded, the runtime blocks the next model call.

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ResumeSessionConfig;
use Revolution\Copilot\Types\Rpc\SessionLimitsConfig;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session) {
    $session->sendAndWait(prompt: 'Tell me something about Laravel.');
}, config: new SessionConfig(
    sessionLimits: new SessionLimitsConfig(maxAiCredits: 30.0),
));

Copilot::client()->resumeSession(
    'existing-session-id',
    new ResumeSessionConfig(
        sessionLimits: new SessionLimitsConfig(maxAiCredits: 30.0),
    ),
);

Both SessionConfig and ResumeSessionConfig accept sessionLimits as either a SessionLimitsConfig instance or an array.

Limit events

Listen to session events to react to limit changes and to prompt the user when the limit is reached.

Event	When it fires	Main data
`session.session_limits_changed` (`SessionEventType::SESSION_SESSION_LIMITS_CHANGED`)	The effective session limits change. If `sessionLimits` is `null`, no limit applies.	`sessionLimits.maxAiCredits` (optional)
`session.usage_checkpoint` (`SessionEventType::SESSION_USAGE_CHECKPOINT`)	The runtime records aggregate usage for resuming or accounting.	`totalNanoAiu`, `totalPremiumRequests` (optional)
`session_limits_exhausted.requested` (`SessionEventType::SESSION_LIMITS_EXHAUSTED_REQUESTED`)	The limit is reached and the user must decide before the session continues.	`requestId`, `maxAiCredits`, `usedAiCredits`
`session_limits_exhausted.completed` (`SessionEventType::SESSION_LIMITS_EXHAUSTED_COMPLETED`)	The exhausted-limit prompt is resolved.	`requestId`, `response.action`, `response.additionalAiCredits` (optional), `response.maxAiCredits` (optional)

For example, when you receive SESSION_LIMITS_EXHAUSTED_REQUESTED, use the event data to show a confirmation UI.

use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Types\SessionEvent;

$session->on(function (SessionEvent $event): void {
    if ($event->is(SessionEventType::SESSION_LIMITS_EXHAUSTED_REQUESTED)) {
        $requestId = $event->data['requestId'];
        $maxAiCredits = $event->data['maxAiCredits'];
        $usedAiCredits = $event->data['usedAiCredits'];

        // Show a confirmation UI using $requestId
    }
});

Respond to an exhausted limit

Send the user’s choice back to the runtime with handlePendingSessionLimitsExhausted(). Set action to a SessionLimitsExhaustedResponseAction case.

use Revolution\Copilot\Enums\SessionLimitsExhaustedResponseAction;
use Revolution\Copilot\Types\Rpc\UIHandlePendingSessionLimitsExhaustedRequest;
use Revolution\Copilot\Types\Rpc\UISessionLimitsExhaustedResponse;

$session->rpc()->ui()->handlePendingSessionLimitsExhausted(
    new UIHandlePendingSessionLimitsExhaustedRequest(
        requestId: $requestId,
        response: new UISessionLimitsExhaustedResponse(
            action: SessionLimitsExhaustedResponseAction::Add,
            additionalAiCredits: 10.0,
        ),
    ),
);

The available actions are:

Add: Adds the given AI credits to the current limit. Set additionalAiCredits.
Set: Changes the limit to a new absolute value. Set maxAiCredits.
Unset: Removes the session limit.
Cancel: Cancels the blocked model request without changing the limit.

The exhausted-limit prompt flow using session_limits_exhausted.requested and session_limits_exhausted.completed, and the related response API, are experimental. They may change or be removed in the future.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds and RSS

Middleware

Set a limit

Limit events

Respond to an exhausted limit

​Set a limit

​Limit events

​Respond to an exhausted limit

Set a limit

Limit events

Respond to an exhausted limit