SessionConfig

Configure Laravel Copilot SDK sessions with SessionConfig, including tools, MCP, hooks, agents, and lifecycle event handlers.

SessionConfig

You can configure many behaviors with the SessionConfig class.

Use it with Copilot::run(prompt: '...', config: $config) or Copilot::start(function (CopilotSession $session) { ... }, config: $config). If you only need simple options like a model ID, you can pass an array instead of using SessionConfig: Copilot::run(prompt: '...', config: ['model' => 'auto']).

use Revolution\Copilot\Enums\ReasoningEffort;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ElicitationContext;
use Revolution\Copilot\Types\InfiniteSessionConfig;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverride;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverrideLimits;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverrideSupports;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SessionEvent;
use Revolution\Copilot\Types\SystemMessageConfig;
use Revolution\Copilot\Types\UserInputRequest;

$config = new SessionConfig(
    // Model to use
    model: 'auto',

    // Fixed session ID when creating a new session
    sessionId: 'session-123',

    clientName: 'my-app',

    // Reasoning level (only for supported models)
    reasoningEffort: ReasoningEffort::HIGH,

    // Override model capabilities. Deep-merged with runtime defaults.
    // modelCapabilities: new ModelCapabilitiesOverride(
    //     supports: new ModelCapabilitiesOverrideSupports(vision: true, reasoningEffort: true),
    //     limits: new ModelCapabilitiesOverrideLimits(max_prompt_tokens: 200000),
    // ),
    // Array format is also supported
    // modelCapabilities: ['supports' => ['vision' => true]],

    // Override config directory
    configDirectory: '',

    // Enable auto-discovery of MCP settings and skill directories
    // Auto-detects .mcp.json and .vscode/mcp.json from the working directory,
    // then merges them with explicitly provided mcpServers and skillDirectories.
    // Explicit values win on name conflicts.
    enableConfigDiscovery: true,

    // Custom tools
    tools: [...],

    // System message
    systemMessage: new SystemMessageConfig(
        content: 'You are a helpful assistant for Laravel developers.',
    ),

    // Replace mode (fully replace the system prompt)
    // systemMessage: new SystemMessageConfig(
    //     mode: 'replace',
    //     content: 'Entire custom system prompt',
    // ),

    // Customize mode (override by section)
    // systemMessage: new SystemMessageConfig(
    //     mode: 'customize',
    //     sections: [
    //         'tone' => new SectionOverride(action: SectionOverrideAction::REPLACE, content: 'Always respond in Japanese.'),
    //         'safety' => new SectionOverride(action: SectionOverrideAction::REMOVE),
    //         'custom_instructions' => new SectionOverride(action: SectionOverrideAction::APPEND, content: 'Additional instructions here.'),
    //     ],
    //     content: 'Optional extra content like append mode',
    // ),

    // Custom provider
    provider: new ProviderConfig(),

    // Per-session GitHub token (multi-tenant support)
    // Specifies a token per session, separate from the client-level github_token
    gitHubToken: $user->github_token,

    onPermissionRequest: function (array $request) {
        // Handle permission requests
    },

    onUserInputRequest: function (UserInputRequest $request) {
        // Handle user input requests (ask_user)
    },

    // Elicitation request handler
    // Lets you receive form-based UI dialog requests from the agent
    onElicitationRequest: function (ElicitationContext $context) {
        // Handle elicitation request
        return ['action' => 'accept', 'content' => ['field' => 'value']];
    },

    // Session hooks
    hooks: [],

    // Working directory
    workingDirectory: '',

    // Enable streaming
    streaming: true,

    // Whether to include sub-agent streaming events in the main stream (default: true)
    includeSubAgentStreamingEvents: true,

    // Allowed built-in tools
    availableTools: ['read_file', 'write_file'],

    // Or excluded tools
    excludedTools: ['shell'],

    // MCP server configuration
    mcpServers: [
        'github' => [
            'type' => 'http',
            'url' => 'https://api.githubcopilot.com/mcp/',
        ],
    ],

    // Custom agents
    customAgents: [
        [
            'name' => 'reviewer',
            'displayName' => 'Code Reviewer',
            'description' => 'Reviews code for best practices',
            'prompt' => 'You are an expert code reviewer.',
        ],
    ],

    // Default agent configuration. Applied to the built-in agent when no custom agent is selected.
    // excludedTools: list of tools to exclude from the default agent.
    // Custom sub-agents can still use excluded tools.
    defaultAgent: ['excludedTools' => ['tool_name']],

    // Agent activated at session start. Must match customAgents.name.
    agent: 'reviewer',

    // Skill directories
    skillDirectories: [],

    // Disabled skills
    disabledSkills: [],

    // Infinite session configuration (enabled by default)
    infiniteSessions: new InfiniteSessionConfig(
        enabled: true,
        backgroundCompactionThreshold: 0.80, // Start compaction at 80% context usage
        bufferExhaustionThreshold: 0.95,     // Block at 95% until compaction finishes
    ),

    // Disable infinite sessions
    // infiniteSessions: new InfiniteSessionConfig(enabled: false),

    // Register event handlers before the session creation RPC.
    // Use this to avoid missing early events such as session.start.
    // Equivalent to calling $session->on($handler) later, but earlier in the lifecycle.
    onEvent: function (SessionEvent $event) {
        // Receive all session events
    },
);

$response = Copilot::run('...', config: $config);

When resuming a session, use ResumeSessionConfig. It is almost the same as SessionConfig, but has small differences. In ResumeSessionConfig, specify only the options you want to change. All other settings are inherited from the original session start.

For cloud execution, see Cloud Sessions; for plugin directories, see Plugin Directories.

For the latest updates, see the GitHub repository.