Skip to content

v0.3.0

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 24 Apr 16:06
v0.3.0
dd2dcbc
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

This release adds new capabilities — per-session authentication, scoped permissions, agent-level tool and skill control, MCP interop utilities, and more — alongside a broad naming cleanup across all four SDK languages. As we close in on a GA release, we've done a deep clean on our naming to bring it closer to the final state, reducing the amount of churn you should expect in subsequent releases. The result is a more consistent, more readable API surface across the board.

New features

Per-session GitHub authentication

Sessions can now carry their own GitHub identity. Different sessions on the same CLI server can have different GitHub users, Copilot plans, and quota limits.

const session = await client.createSession({
    onPermissionRequest: approveAll,
    gitHubToken: userAToken, // Session-level identity
});

This is independent of the client-level gitHubToken (which authenticates the CLI process itself, and is not required if all sessions bring their own auth). The session-level token determines the identity used for content exclusion, model routing, and quota checks.

Per-agent tool visibility

A new defaultAgent.excludedTools option lets you hide tools from the default agent while keeping them available to custom sub-agents, enabling the orchestrator pattern where the default agent delegates to specialized sub-agents. (#1098)

Per-agent skills

Custom agents can now declare skills: string[] to eagerly inject specific skills into their context at startup. Skills are opt-in — agents receive no skills by default, and sub-agents do not inherit skills from the parent. (#995)

Sub-agent streaming content

When streaming is enabled, assistant.message_delta and assistant.reasoning_delta events are now also delivered for sub-agents. Each event carries an agentId field identifying which sub-agent produced it (absent for the root agent). If your application renders all streaming deltas to the UI, you'll want to filter by agentId (or for pure back-compat, set includeSubAgentStreamingEvents: false on SessionConfig to get the old behavior of only streaming main-agent content updates). (#1108)

Session idle timeout

A new sessionIdleTimeoutSeconds client option configures automatic session cleanup after inactivity. When set, sessions without activity for the specified duration are cleaned up. Disabled by default (sessions live indefinitely). Previously, sessions would always time out after 30 minutes of idleness - this change fixes that. (#1093)

Custom HTTP headers for BYOK model providers

Provider headers and per-message requestHeaders can now be passed through createSession, resumeSession, and send, enabling custom header forwarding to bring-your-own-key model providers. (#1094)

MCP CallToolResult conversion

A new convertMcpCallToolResult() utility function converts MCP CallToolResult objects (with content arrays of text, image, and resource blocks) into the SDK's ToolResultObject format. This makes it easy to use MCP tool servers as backends for SDK tool handlers. (#1049)

ProviderConfig exported

ProviderConfig is now re-exported from the Node.js and Python SDK entry points, so consumers no longer need to duplicate the type locally when configuring Responses API providers. (#1048)

New RPC methods

Additional low-level RPC methods are now available via session.rpc:

  • session.rpc.skills.config.setDisabledSkills(), session.rpc.skills.discover()
  • session.rpc.mcp.config.enable(), session.rpc.mcp.config.disable(), session.rpc.mcp.discover(), session.rpc.mcp.oauthLogin()
  • session.rpc.permissions.setApproveAll(), session.rpc.permissions.resetSessionApprovals()
  • session.rpc.instructions.getSources()
  • session.rpc.usage.getMetrics()
  • session.rpc.name.get(), session.rpc.name.set()

Changes and improvements

Scoped permission approvals

Permission handlers can now return scoped approvals instead of just one-shot decisions. Two new kind values are available:

  • "approve-for-session" — Approves a permission for the remainder of the session, with a scoped rule specifying what's approved (commands, read, write, MCP, MCP sampling, memory, or custom tool).
  • "approve-for-location" — Persists an approval to the workspace location, so it applies across future sessions too.

The existing approval vocabulary has also been clarified to better describe each outcome:

Previous Now
"approved" "approve-once"
"denied-interactively-by-user" "reject"
"denied-no-approval-rule-and-could-not-request-from-user" "user-not-available"

The "denied-by-rules", "denied-by-content-exclusion-policy", and "denied-by-permission-request-hook" outcomes have been removed from the handler result type — these are now handled server-side and never reach the SDK permission handler.

The built-in approveAll handler has been updated and now returns { kind: "approve-once" }. The PermissionRequest.kind field now also covers "memory" and "hook" permission types in addition to the existing "shell", "write", "mcp", "read", "url", and "custom-tool".

Dedicated session event types

Session events now have individually named types instead of being a single large inline union. In Node.js, the SessionEvent type is still available as a union of all event types, but each event now has a corresponding *Event interface and *Data type that you can import and use directly. Python and .NET received the same treatment — Python now has per-event typed classes, and .NET has dedicated event types with rich typing (long, DateTimeOffset, Guid, TimeSpan, data annotations, etc.).

import type { AssistantMessageData } from "@github/copilot-sdk";

session.onEvent("assistant.message", (event) => {
    // event.data is AssistantMessageData — importable and reusable
});

The runtime JSON shape is unchanged — existing event-handling code continues to work.

MCP server config types clarified

MCP server configuration types have been renamed to match MCP protocol terminology (#1051):

Previous Now
MCPLocalServerConfig MCPStdioServerConfig
MCPRemoteServerConfig MCPHTTPServerConfig (covers both HTTP and SSE transports)

The type field value correspondingly changes from "local"/"remote" to "stdio"/"http".

Improved SessionFs provider API

The SessionFs API now uses an idiomatic SessionFsProvider interface where methods take plain arguments and signal errors by throwing, instead of the previous RPC-shaped interface with parameter objects and error-result returns. Supply your provider via the createSessionFsHandler callback on SessionConfig:

createSessionFsHandler: (session) => ({
    readFile: async (path) => {
        return await fs.readFile(path, "utf8"); // throw on error
    },
    stat: async (path) => {
        const s = await fs.stat(path);
        return { size: s.size, isDirectory: s.isDirectory(), ... };
    },
    // ... other methods with plain args, throw on error
})

githubToken/GithubToken casing corrected

The githubToken/GithubToken property on CopilotClientOptions has been corrected to gitHubToken/GitHubToken (capital H) for consistency with GitHub's branding across all SDKs.

Sub-agent streaming deltas now included by default

Streaming sessions now receive assistant.message_delta and assistant.reasoning_delta events from sub-agents as well as the root agent. If your code renders all deltas without checking the source, sub-agent content will be interleaved with the main agent's output. To handle this, either filter on event.agentId (absent for the root agent) or set includeSubAgentStreamingEvents: false on SessionConfig to suppress sub-agent deltas entirely. (#1108)

Additional improvements

  • [Node] Model capabilities are now normalized for models that omit supports or limits fields (e.g., embedding models), preventing runtime errors. (cf5694c)
  • [Node] CLI startup timeout is now cleared when stop is requested, avoiding unnecessary 10-second delay. (#1046)
  • [.NET] Richer typing: integer → long, format: date-time → DateTimeOffset, format: uuid → Guid, format: duration → TimeSpan; data annotations ([Range], [RegularExpression], [Url], etc.). (#1067)
  • [.NET] Deprecated APIs are now annotated with [Obsolete] with descriptive messages. (#1099)
  • [Python] Dedicated per-event typed session event classes. (#1063)
  • SDK status changed to public preview. (#1054)

⚠️ Type and naming changes

As we close in on a GA release, we've done a deep clean on type naming across all four SDK languages to bring names closer to their final state. The goal is to reduce churn in subsequent releases — these names are now cleaner, more consistent, and better reflect what each type represents.

The changes follow a few simple rules:

  1. *Params → *Request — parameter types now use the clearer Request suffix.
  2. Redundant Session prefix dropped — types like SessionAgentSelectParams become AgentSelectRequest. The session context is already clear from the session.rpc.* namespace.
  3. List results use domain names — e.g., SessionSkillsListResult → SkillList, ModelsListResult → ModelList. These read more naturally.
  4. Empty placeholder types removed — types that were empty {} (void params or results for methods that take/return nothing) have been eliminated.

These types appear in the session.rpc.* and client.rpc.* method signatures. If your code references them by name (via imports or TypeScript utility types like Parameters<> / ReturnType<>), you'll need to update. Code that accesses return values structurally without naming the types is unaffected.

Cross-language note: The same logical renames apply across all four SDKs with language-appropriate casing (e.g., McpConfigAddRequest in TypeScript/C#, MCPConfigAddRequest in Go/Python, FS vs Fs, UI vs Ui). The tables below use TypeScript names unless otherwise noted. Go, Python, and .NET had names for additional types that TypeScript left as structural (inline/anonymous) — those extra renames are called out where relevant.

RPC type renames

Params → Request renames (39 renames — all languages)
v0.2.2 v0.3.0
McpConfigAddParams McpConfigAddRequest
McpConfigRemoveParams McpConfigRemoveRequest
McpConfigUpdateParams McpConfigUpdateRequest
PingParams PingRequest
SessionAgentSelectParams AgentSelectRequest
SessionCommandsHandlePendingCommandParams CommandsHandlePendingCommandRequest
SessionExtensionsDisableParams ExtensionsDisableRequest
SessionExtensionsEnableParams ExtensionsEnableRequest
SessionFleetStartParams FleetStartRequest
SessionFsAppendFileParams SessionFsAppendFileRequest
SessionFsExistsParams SessionFsExistsRequest
SessionFsMkdirParams SessionFsMkdirRequest
SessionFsReadFileParams SessionFsReadFileRequest
SessionFsReaddirParams SessionFsReaddirRequest
SessionFsReaddirWithTypesParams SessionFsReaddirWithTypesRequest
SessionFsRenameParams SessionFsRenameRequest
SessionFsRmParams SessionFsRmRequest
SessionFsSetProviderParams SessionFsSetProviderRequest
SessionFsStatParams SessionFsStatRequest
SessionFsWriteFileParams SessionFsWriteFileRequest
SessionHistoryTruncateParams HistoryTruncateRequest
SessionLogParams LogRequest
SessionMcpDisableParams McpDisableRequest
SessionMcpEnableParams McpEnableRequest
SessionModeSetParams ModeSetRequest
SessionModelSwitchToParams ModelSwitchToRequest
SessionPermissionsHandlePendingPermissionRequestParams PermissionDecisionRequest
SessionPlanUpdateParams PlanUpdateRequest
SessionShellExecParams ShellExecRequest
SessionShellKillParams ShellKillRequest
SessionSkillsDisableParams SkillsDisableRequest
SessionSkillsEnableParams SkillsEnableRequest
SessionToolsHandlePendingToolCallParams ToolsHandlePendingToolCallRequest
SessionUiElicitationParams UIElicitationRequest
SessionUiHandlePendingElicitationParams UIHandlePendingElicitationRequest
SessionWorkspaceCreateFileParams WorkspacesCreateFileRequest
SessionWorkspaceReadFileParams WorkspacesReadFileRequest
SessionsForkParams SessionsForkRequest
ToolsListParams ToolsListRequest
Result / list-result renames (27 renames — all languages)
v0.2.2 v0.3.0
McpConfigListResult McpConfigList
ModelsListResult ModelList
SessionAgentGetCurrentResult AgentGetCurrentResult
SessionAgentListResult AgentList
SessionAgentReloadResult AgentReloadResult
SessionAgentSelectResult AgentSelectResult
SessionCommandsHandlePendingCommandResult CommandsHandlePendingCommandResult
SessionExtensionsListResult ExtensionList
SessionFleetStartResult FleetStartResult
SessionHistoryCompactResult HistoryCompactResult
SessionHistoryTruncateResult HistoryTruncateResult
SessionLogResult LogResult
SessionMcpListResult McpServerList
SessionModeGetResult SessionMode
SessionModelGetCurrentResult CurrentModel
SessionModelSwitchToResult ModelSwitchToResult
SessionPermissionsHandlePendingPermissionRequestResult PermissionRequestResult
SessionPlanReadResult PlanReadResult
SessionPluginsListResult PluginList
SessionShellExecResult ShellExecResult
SessionShellKillResult ShellKillResult
SessionSkillsListResult SkillList
SessionToolsHandlePendingToolCallResult HandleToolCallResult
SessionUiElicitationResult UIElicitationResult
SessionWorkspaceListFilesResult WorkspacesListFilesResult
SessionWorkspaceReadFileResult WorkspacesReadFileResult
ToolsListResult ToolList

Go, Python, and .NET had named types for additional void results that TypeScript omitted (structural typing). These were also renamed — e.g., SessionModeSetResult → ModeSetResult, SessionPlanUpdateResult → PlanUpdateResult, SessionMcpDisableResult → McpDisableResult, etc. — following the same pattern.

Enum and helper type renames (Go, Python, and .NET only)

TypeScript used inline/literal types for these, so they had no standalone names to rename. Go, Python, and .NET each had named types that have been renamed to be more descriptive and avoid collisions:

Go / Python:

v0.2.2 v0.3.0
Mode SessionMode
Kind PermissionDecisionKind
Level SessionLogLevel
Signal ShellKillSignal
EntryType SessionFSReaddirWithTypesEntryType
Action UIElicitationResponseAction
Conventions SessionFSSetProviderConventions
Model ModelElement
Billing ModelBilling
Policy ModelPolicy
Skill ServerSkill
Plugin PluginElement
Entry SessionFSReaddirWithTypesEntry
QuotaSnapshot AccountQuotaSnapshot
Source MCPServerSource
ServerElement MCPServer
ServerValue / MCPConfigAddParamsConfig MCPServerConfig
ServerType MCPServerConfigType
ServerStatus MCPServerStatus
Various UI elicitation sub-types Prefixed with UIElicitation*

C# (.NET) — most helper types lived in SessionEvents.cs; only 6 renames in Rpc.cs:

v0.2.2 v0.3.0
EntryType SessionFsReaddirWithTypesEntryType
SessionFsSetProviderRequestConventions SessionFsSetProviderConventions
SessionLogRequestLevel SessionLogLevel
SessionModeGetResultMode SessionMode
SessionShellKillRequestSignal ShellKillSignal
SessionUiElicitationResultAction UIElicitationResponseAction

Session event type renames (.NET and Go)

TypeScript didn't have named sub-types for session event data before v0.3.0 (they were inline), and Python's event types were completely restructured rather than renamed. .NET and Go both had deeply-nested named sub-types that have been cleaned up following three patterns:

  1. *Data* infix flattened — e.g., AssistantMessageDataToolRequestsItem → AssistantMessageToolRequest
  2. Session prefix dropped — e.g., SessionCompactionCompleteDataCompactionTokensUsed → CompactionCompleteCompactionTokensUsed
  3. *Item suffix singularized — e.g., PermissionRequestShellCommandsItem → PermissionRequestShellCommand
Full session event rename table (63 renames — C# names; Go follows the same pattern)
v0.2.2 v0.3.0
AssistantMessageDataToolRequestsItem AssistantMessageToolRequest
AssistantMessageDataToolRequestsItemType AssistantMessageToolRequestType
AssistantUsageDataCopilotUsage AssistantUsageCopilotUsage
AssistantUsageDataCopilotUsageTokenDetailsItem AssistantUsageCopilotUsageTokenDetail
CapabilitiesChangedDataUi CapabilitiesChangedUI
CommandsChangedDataCommandsItem CommandsChangedCommand
ElicitationCompletedDataAction ElicitationCompletedAction
ElicitationRequestedDataMode ElicitationRequestedMode
ElicitationRequestedDataRequestedSchema ElicitationRequestedSchema
HookEndDataError HookEndError
McpOauthRequiredDataStaticClientConfig McpOauthRequiredStaticClientConfig
PermissionCompletedDataResult PermissionCompletedResult
PermissionCompletedDataResultKind PermissionCompletedKind
PermissionRequestShellCommandsItem PermissionRequestShellCommand
PermissionRequestShellPossibleUrlsItem PermissionRequestShellPossibleUrl
SessionCompactionCompleteDataCompactionTokensUsed CompactionCompleteCompactionTokensUsed
SessionCustomAgentsUpdatedDataAgentsItem CustomAgentsUpdatedAgent
SessionExtensionsLoadedDataExtensionsItem ExtensionsLoadedExtension
SessionExtensionsLoadedDataExtensionsItemSource ExtensionsLoadedExtensionSource
SessionExtensionsLoadedDataExtensionsItemStatus ExtensionsLoadedExtensionStatus
SessionHandoffDataRepository HandoffRepository
SessionHandoffDataSourceType HandoffSourceType
SessionMcpServersLoadedDataServersItem McpServersLoadedServer
SessionMcpServersLoadedDataServersItemStatus McpServersLoadedServerStatus
SessionPlanChangedDataOperation PlanChangedOperation
SessionResumeDataContext WorkingDirectoryContext
SessionShutdownDataCodeChanges ShutdownCodeChanges
SessionShutdownDataShutdownType ShutdownType
SessionSkillsLoadedDataSkillsItem SkillsLoadedSkill
SessionStartDataContext WorkingDirectoryContext
SessionStartDataContextHostType WorkingDirectoryContextHostType
SessionWorkspaceFileChangedDataOperation WorkspaceFileChangedOperation
SystemMessageDataMetadata SystemMessageMetadata
SystemMessageDataRole SystemMessageRole
SystemNotificationDataKind SystemNotification
SystemNotificationDataKindAgentCompleted SystemNotificationAgentCompleted
SystemNotificationDataKindAgentCompletedStatus SystemNotificationAgentCompletedStatus
SystemNotificationDataKindAgentIdle SystemNotificationAgentIdle
SystemNotificationDataKindShellCompleted SystemNotificationShellCompleted
SystemNotificationDataKindShellDetachedCompleted SystemNotificationShellDetachedCompleted
ToolExecutionCompleteDataError ToolExecutionCompleteError
ToolExecutionCompleteDataResult ToolExecutionCompleteResult
ToolExecutionCompleteDataResultContentsItem ToolExecutionCompleteContent
ToolExecutionCompleteDataResultContentsItemAudio ToolExecutionCompleteContentAudio
ToolExecutionCompleteDataResultContentsItemImage ToolExecutionCompleteContentImage
ToolExecutionCompleteDataResultContentsItemResource ToolExecutionCompleteContentResource
ToolExecutionCompleteDataResultContentsItemResourceLink ToolExecutionCompleteContentResourceLink
ToolExecutionCompleteDataResultContentsItemResourceLinkIconsItem ToolExecutionCompleteContentResourceLinkIcon
ToolExecutionCompleteDataResultContentsItemResourceLinkIconsItemTheme ToolExecutionCompleteContentResourceLinkIconTheme
ToolExecutionCompleteDataResultContentsItemTerminal ToolExecutionCompleteContentTerminal
ToolExecutionCompleteDataResultContentsItemText ToolExecutionCompleteContentText
UserMessageDataAgentMode UserMessageAgentMode
UserMessageDataAttachmentsItem UserMessageAttachment
UserMessageDataAttachmentsItemBlob UserMessageAttachmentBlob
UserMessageDataAttachmentsItemDirectory UserMessageAttachmentDirectory
UserMessageDataAttachmentsItemFile UserMessageAttachmentFile
UserMessageDataAttachmentsItemFileLineRange UserMessageAttachmentFileLineRange
UserMessageDataAttachmentsItemGithubReference UserMessageAttachmentGithubReference
UserMessageDataAttachmentsItemGithubReferenceReferenceType UserMessageAttachmentGithubReferenceType
UserMessageDataAttachmentsItemSelection UserMessageAttachmentSelection
UserMessageDataAttachmentsItemSelectionSelection UserMessageAttachmentSelectionDetails
UserMessageDataAttachmentsItemSelectionSelectionEnd UserMessageAttachmentSelectionDetailsEnd
UserMessageDataAttachmentsItemSelectionSelectionStart UserMessageAttachmentSelectionDetailsStart

Go has ~57 equivalent renames following the same patterns, with minor casing differences to satisfy Go idioms (e.g., UI vs Ui, FS vs Fs).

Removed empty types

Removed empty types (32 types — Node.js)

These were empty {} types (void params or results for methods that take/return nothing) and are no longer generated:

SessionAgentDeselectParams, SessionAgentDeselectResult, SessionAgentGetCurrentParams, SessionAgentListParams, SessionAgentReloadParams, SessionExtensionsDisableResult, SessionExtensionsEnableResult, SessionExtensionsListParams, SessionExtensionsReloadParams, SessionExtensionsReloadResult, SessionHistoryCompactParams, SessionMcpDisableResult, SessionMcpEnableResult, SessionMcpListParams, SessionMcpReloadParams, SessionMcpReloadResult, SessionModeGetParams, SessionModeSetResult, SessionModelGetCurrentParams, SessionPlanDeleteParams, SessionPlanDeleteResult, SessionPlanReadParams, SessionPlanUpdateResult, SessionPluginsListParams, SessionSkillsDisableResult, SessionSkillsEnableResult, SessionSkillsListParams, SessionSkillsReloadParams, SessionSkillsReloadResult, SessionUiHandlePendingElicitationResult, SessionWorkspaceCreateFileResult, SessionWorkspaceListFilesParams

Go, Python, and .NET had additional named empty types that were also removed — including void result types like SessionModeSetResult, SessionPlanUpdateResult, SessionMcpDisableResult, SessionExtensionsDisableResult, etc. that TypeScript never had names for (it used structural void returns). The same removal pattern applies.

Assets 2
Loading