CopilotSession class
A Copilot agent session.
Sessions are created via CopilotClient.createSession or CopilotClient.resumeSession.
final session = await client.createSession(
config: SessionConfig(onPermissionRequest: approveAllPermissions),
);
// Event-driven
session.on((event) {
switch (event) {
case AssistantMessageEvent(:final content):
stdout.write(content);
case SessionIdleEvent():
print('\n--- Done ---');
}
});
// Send a message
await session.send('Hello, Copilot!');
// Or wait for completion
final reply = await session.sendAndWait('What is 2+2?');
print(reply?.content);
Constructors
- CopilotSession({required String sessionId, required JsonRpcConnection connection, required SessionConfig config, String? workspacePath})
Properties
- config → SessionConfig
-
Session configuration.
final
- effectiveHooks → SessionHooks?
-
The effective hooks (dynamic override > config).
no setter
- effectivePermissionHandler → PermissionHandler
-
The effective permission handler (dynamic override > config).
no setter
- effectiveUserInputHandler → UserInputHandler?
-
The effective user input handler (dynamic override > config).
no setter
-
events
→ Stream<
SessionEvent> -
A broadcast stream of all session events.
no setter
- hashCode → int
-
The hash code for this object.
no setterinherited
- isDestroyed → bool
-
Whether the session has been destroyed.
no setter
- onDestroyed ↔ void Function()?
-
Called when the session is destroyed (used by CopilotClient).
getter/setter pair
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- sessionId → String
-
The unique session ID.
final
- workspacePath → String?
-
Workspace path returned from the CLI (if set).
final
Methods
-
abort(
) → Future< void> - Aborts the current operation in this session.
-
addTool(
Tool tool) → void - Adds a tool to this session.
-
compact(
) → Future< CompactionResult> - Compacts the session history.
-
createWorkspaceFile(
String path, String content) → Future< void> - Creates a file in the workspace.
-
deletePlan(
) → Future< void> - Deletes the plan.
-
deselectAgent(
) → Future< void> - Deselects the current agent.
-
destroy(
) → Future< void> - Destroys this session.
-
getCurrentAgent(
) → Future< AgentInfo?> - Gets the currently active agent.
-
getCurrentModel(
) → Future< String> - Gets the current model for this session.
-
getMessages(
) → Future< List< SessionEvent> > - Gets the current messages in this session.
-
getMode(
) → Future< AgentMode> - Gets the current agent mode.
-
getToolHandler(
String name) → ToolHandler? - Retrieves a registered tool handler by name.
-
handleConnectionClose(
) → void - Internal: handle connection close.
-
handleEvent(
SessionEvent event) → void - Internal: dispatch an event to all handlers.
-
handleToolCall(
String toolName, dynamic arguments, ToolInvocation invocation, {List< Tool> fallbackTools = const []}) → Future<ToolResult> - Internal: handle a tool call from the CLI.
-
listAgents(
) → Future< List< AgentInfo> > - Lists available agents for this session.
-
listWorkspaceFiles(
) → Future< List< String> > - Lists files in the workspace.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
on(
void handler(SessionEvent event)) → void Function() - Register a handler for all session events. Returns an unsubscribe fn.
-
once(
void handler(SessionEvent event)) → void Function() - Register a one-shot handler. Automatically removed after first call.
-
onType<
T extends SessionEvent> (void handler(T event)) → void Function() -
Register a typed handler. Only called for events of type
T. -
readPlan(
) → Future< PlanReadResult> - Reads the current plan.
-
readWorkspaceFile(
String path) → Future< String> - Reads a file from the workspace.
-
registerHooks(
SessionHooks hooks) → void - Dynamically registers hooks on this session.
-
registerPermissionHandler(
PermissionHandler handler) → void - Dynamically registers a permission handler on this session.
-
registerTools(
List< Tool> tools) → void - Registers multiple tools at once.
-
registerUserInputHandler(
UserInputHandler handler) → void - Dynamically registers a user input handler on this session.
-
removeTool(
String name) → void - Removes a tool by name.
-
selectAgent(
String name) → Future< AgentInfo> - Selects an agent by name.
-
send(
String prompt, {List< Attachment> attachments = const [], MessageDeliveryMode? mode}) → Future<String> - Sends a message to the session. Returns the message ID.
-
sendAndWait(
String prompt, {List< Attachment> attachments = const [], MessageDeliveryMode? mode, Duration timeout = const Duration(seconds: 60)}) → Future<AssistantMessageEvent?> - Sends a message and waits for the assistant's complete reply.
-
sendMessage(
MessageOptions options) → Future< String> - Sends a message using a MessageOptions object.
-
setMode(
AgentMode mode) → Future< void> - Sets the agent mode.
-
startFleet(
{String? prompt}) → Future< void> - Starts fleet mode (spawns sub-agents for parallel execution).
-
switchModel(
String modelId) → Future< void> - Switches the model for this session.
-
toString(
) → String -
A string representation of this object.
inherited
-
updatePlan(
String content) → Future< void> - Updates the plan.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited